From ec6f5be6eee76b66126c277f4c3c6052d7640e90 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Wed, 18 Mar 2026 09:49:49 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=87=AA=E5=AE=9A=E4=B9=89=E6=8E=A8?= =?UTF-8?q?=E9=80=81=E6=A8=A1=E5=9D=97=E5=89=8D=E7=AB=AF=E5=AF=B9=E6=8E=A5?= =?UTF-8?q?=E6=8C=87=E5=8D=97=EF=BC=882=E6=8E=A5=E5=8F=A3+=E9=A1=B5?= =?UTF-8?q?=E9=9D=A2=E5=B8=83=E5=B1=80+=E6=9E=9A=E4=B8=BE+=E8=B0=83?= =?UTF-8?q?=E7=94=A8=E7=A4=BA=E4=BE=8B=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../2026-03/2026-03-18_custom_push_api.md | 271 ++++++++++++++++++ 1 file changed, 271 insertions(+) create mode 100644 changelogs/2026-03/2026-03-18_custom_push_api.md diff --git a/changelogs/2026-03/2026-03-18_custom_push_api.md b/changelogs/2026-03/2026-03-18_custom_push_api.md new file mode 100644 index 0000000..d673df0 --- /dev/null +++ b/changelogs/2026-03/2026-03-18_custom_push_api.md @@ -0,0 +1,271 @@ +# 自定义推送模块 - 前端对接指南 + +> **日期**: 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 }, ...] +```