272 行
9.2 KiB
Markdown
272 行
9.2 KiB
Markdown
# 自定义推送模块 - 前端对接指南
|
||
|
||
> **日期**: 2026-03-18
|
||
> **后端状态**: ✅ 已完成，可直接对接
|
||
> **页面路由**: `/notification/push`（通知中心 → 自定义推送）
|
||
|
||
---
|
||
|
||
## 页面功能说明
|
||
|
||
管理员可以通过该页面，向C端用户发送自定义通知消息。
|
||
|
||
**核心流程**：
|
||
1. 填写推送标题和内容
|
||
2. 选择推送通道（站内信 / 短信 / 企业微信）
|
||
3. 选择推送目标（全部用户 / 指定用户）
|
||
4. 如选择"指定用户"，通过搜索框搜索并勾选用户
|
||
5. 点击发送，展示推送结果（成功/失败数）
|
||
|
||
---
|
||
|
||
## 接口清单
|
||
|
||
| # | 接口 | 方法 | 路径 | 说明 |
|
||
|---|------|------|------|------|
|
||
| 1 | 搜索推送目标用户 | GET | `/admin/notification/custom-push/users` | 选择"指定用户"时，搜索用户列表 |
|
||
| 2 | 发送自定义推送 | POST | `/admin/notification/custom-push` | 执行推送，返回成功/失败数 |
|
||
| 3 | 查询推送日志 | GET | `/admin/notification/logs` | 已有接口，用于查看推送记录 |
|
||
|
||
---
|
||
|
||
## 接口 1：搜索推送目标用户
|
||
|
||
**使用场景**：推送目标选择"指定用户"时，输入关键词搜索C端用户，展示为可勾选列表。
|
||
|
||
```
|
||
GET /admin/notification/custom-push/users?keyword=张三
|
||
```
|
||
|
||
### 请求参数
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| keyword | String | 否 | 搜索关键词，支持按**真实姓名**或**手机号**模糊搜索。不传则返回最近注册的20个用户 |
|
||
|
||
### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"data": [
|
||
{
|
||
"id": "2025607151170445314",
|
||
"realName": "张三",
|
||
"phone": "138****1234",
|
||
"avatarUrl": "https://oss.example.com/avatar/xxx.jpg"
|
||
},
|
||
{
|
||
"id": "2025607151170445315",
|
||
"realName": "张丽",
|
||
"phone": "139****5678",
|
||
"avatarUrl": null
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 响应字段
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | String | 用户ID（雪花ID，注意用String接收） |
|
||
| realName | String | 真实姓名，可能为null（用户未完善资料） |
|
||
| phone | String | 手机号（脱敏显示），可能为null |
|
||
| avatarUrl | String | 头像URL，可能为null |
|
||
|
||
### 前端实现建议
|
||
- 用 `el-select` 远程搜索模式（`remote` + `filterable`），绑定搜索方法
|
||
- 搜索结果展示为：头像 + 姓名 + 手机号
|
||
- 支持多选（`multiple`），选中后存入 `userIds` 数组
|
||
- 防抖 300ms，避免频繁请求
|
||
- 无头像时显示默认头像或姓名首字占位
|
||
|
||
---
|
||
|
||
## 接口 2：发送自定义推送
|
||
|
||
**使用场景**：填写完推送内容后，点击"发送"按钮调用此接口。
|
||
|
||
```
|
||
POST /admin/notification/custom-push
|
||
Content-Type: application/json
|
||
```
|
||
|
||
### 请求参数
|
||
|
||
```json
|
||
{
|
||
"title": "暑期特惠活动通知",
|
||
"content": "亲爱的用户，暑期呼伦贝尔亲子营限时9折优惠，详情请查看小程序首页！",
|
||
"channel": "INAPP",
|
||
"targetType": "ALL_USERS",
|
||
"userIds": null,
|
||
"categoryCode": "PROMO",
|
||
"link": "/pages/product/list"
|
||
}
|
||
```
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| title | String | **是** | 推送标题 |
|
||
| content | String | **是** | 推送内容（纯文本） |
|
||
| channel | String | **是** | 推送通道，见下方通道枚举 |
|
||
| targetType | String | **是** | 目标类型，见下方枚举 |
|
||
| userIds | Long[] | 条件必填 | 目标用户ID列表，`targetType=SPECIFIC_USERS` 时必填 |
|
||
| categoryCode | String | 否 | 消息分类编码，默认 `SYSTEM`，见下方分类枚举 |
|
||
| link | String | 否 | 跳转链接（站内信时使用），如小程序页面路径 |
|
||
|
||
### 通道枚举（channel）
|
||
|
||
| 值 | 中文 | 说明 | 推送对象 |
|
||
|----|------|------|----------|
|
||
| `INAPP` | 站内信 | 写入用户消息表，小程序"消息"页展示 | C端用户（小程序） |
|
||
| `SMS` | 短信 | 发送短信到用户手机号 | C端用户（手机号） |
|
||
| `WECHAT_WORK` | 企业微信 | 通过企微应用消息推送 | **仅员工**（企微内部成员） |
|
||
|
||
> ⚠️ **注意**：企业微信通道（`WECHAT_WORK`）只能推送给企微内部员工，不能推给C端普通用户。前端应在选择该通道时给予提示。
|
||
|
||
### 目标类型枚举（targetType）
|
||
|
||
| 值 | 中文 | 说明 |
|
||
|----|------|------|
|
||
| `ALL_USERS` | 全部用户 | 推送给所有活跃用户（最多1000人） |
|
||
| `SPECIFIC_USERS` | 指定用户 | 推送给 `userIds` 中指定的用户 |
|
||
|
||
### 消息分类枚举（categoryCode）
|
||
|
||
| 值 | 中文 | 使用场景 |
|
||
|----|------|----------|
|
||
| `SYSTEM` | 系统消息 | 系统公告、维护通知等（默认值） |
|
||
| `ORDER` | 订单消息 | 订单相关通知 |
|
||
| `TRIP` | 行程消息 | 行程提醒 |
|
||
| `PROMO` | 优惠促销 | 活动优惠、营销推送 |
|
||
|
||
### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"data": {
|
||
"totalCount": 15,
|
||
"successCount": 14,
|
||
"failCount": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
### 响应字段
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| totalCount | Integer | 推送总人数 |
|
||
| successCount | Integer | 成功数 |
|
||
| failCount | Integer | 失败数（如用户无手机号、通道异常等） |
|
||
|
||
### 前端实现建议
|
||
- 发送前弹 `el-dialog` 确认框，显示"即将向 X 人推送，确认发送？"
|
||
- 发送按钮加 loading 状态（推送可能需要几秒）
|
||
- 发送成功后用 `el-result` 或 `el-message-box` 展示推送结果：
|
||
- 全部成功：成功图标 + "推送完成，共成功 14 人"
|
||
- 部分失败：警告图标 + "推送完成，成功 14 人，失败 1 人，详情请查看通知日志"
|
||
- 提供"查看推送日志"跳转按钮，跳到 `/notification/log` 页面
|
||
- 企业微信通道选中时，显示提示文字："企业微信仅支持推送给内部员工"
|
||
|
||
---
|
||
|
||
## 接口 3：查询推送日志（已有接口，复用）
|
||
|
||
**使用场景**：推送完成后查看推送记录详情，或在通知日志页面筛选自定义推送记录。
|
||
|
||
```
|
||
GET /admin/notification/logs?eventCode=CUSTOM_PUSH&page=1&pageSize=20
|
||
```
|
||
|
||
> 已有接口，筛选条件加 `eventCode=CUSTOM_PUSH` 即可查看自定义推送的发送记录。
|
||
|
||
---
|
||
|
||
## 页面布局建议
|
||
|
||
```
|
||
┌──────────────────────────────────────────────┐
|
||
│ 自定义推送 │
|
||
├──────────────────────────────────────────────┤
|
||
│ │
|
||
│ 推送标题： [________________________] │
|
||
│ │
|
||
│ 推送内容： [________________________] │
|
||
│ [________________________] │
|
||
│ [________________________] │
|
||
│ │
|
||
│ 推送通道： ○ 站内信 ○ 短信 ○ 企业微信 │
|
||
│ ⚠️ 企微仅支持推送给内部员工 │
|
||
│ │
|
||
│ 消息分类： [系统消息 ▼] │
|
||
│ │
|
||
│ 跳转链接： [________________________] │
|
||
│ (站内信时生效，如小程序页面路径) │
|
||
│ │
|
||
│ 推送目标： ○ 全部用户 ○ 指定用户 │
|
||
│ │
|
||
│ 选择用户： [搜索姓名或手机号... ▼] │
|
||
│ ┌──────────────────────┐ │
|
||
│ │ 👤 张三 138****1234 │ │
|
||
│ │ 👤 张丽 139****5678 │ │
|
||
│ └──────────────────────┘ │
|
||
│ (targetType=SPECIFIC_USERS时显示) │
|
||
│ │
|
||
│ [ 发送推送 ] │
|
||
│ │
|
||
└──────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 表单校验规则
|
||
- 标题：必填，最长50字
|
||
- 内容：必填，最长500字
|
||
- 通道：必选
|
||
- 目标类型：必选
|
||
- 用户列表：目标类型为"指定用户"时必选至少1人
|
||
|
||
---
|
||
|
||
## 完整调用示例
|
||
|
||
### 示例1：向全部用户推送站内信
|
||
|
||
```javascript
|
||
await request.post('/admin/notification/custom-push', {
|
||
title: '暑期特惠活动',
|
||
content: '呼伦贝尔亲子营限时9折优惠！',
|
||
channel: 'INAPP',
|
||
targetType: 'ALL_USERS',
|
||
categoryCode: 'PROMO',
|
||
link: '/pages/product/list'
|
||
})
|
||
```
|
||
|
||
### 示例2：向指定用户发送短信
|
||
|
||
```javascript
|
||
await request.post('/admin/notification/custom-push', {
|
||
title: '出行提醒',
|
||
content: '您的呼伦贝尔之旅将于3天后出发，请做好准备！',
|
||
channel: 'SMS',
|
||
targetType: 'SPECIFIC_USERS',
|
||
userIds: ['2025607151170445314', '2025607151170445315'],
|
||
categoryCode: 'TRIP'
|
||
})
|
||
```
|
||
|
||
### 示例3：搜索用户
|
||
|
||
```javascript
|
||
// 输入关键词搜索
|
||
const { data } = await request.get('/admin/notification/custom-push/users', {
|
||
params: { keyword: '张' }
|
||
})
|
||
// data = [{ id, realName, phone, avatarUrl }, ...]
|
||
```
|