消息通知中心 3 接口(mock 阶段) + 五厂商推送(补华为/通用发送/测试三件套)

- GET /api/v1/notifications(分页,时间倒序不分组)/unread-count /read(ids|all), 对外 camelCase(PRD 前端契约);数据为内存 mock(13 类型全覆盖,重启复位), 接真实数据只换 repositories/notification_mock.py - vendor_push 补华为 Push Kit(OAuth+messages:send),抽通用 send_notification (任意文案+extras+mock 模式),send_accessibility_disabled 改薄封装行为不变 - 新增 /api/v1/push/{vendors,templates,test}:凭据状态/13 类 PRD 文案模板/测试发送 (默认 mock,mock=false 真发,可联动插站内 mock 消息闭环验证已读) - .env.example 补 HUAWEI_* 键;docs/api 新增 notifications.md + push-vendor-test.md - alembic merge 1a924c274fce 收拢 direct_vendor_push_fields/feedback_type_reply 双 head,恢复 upgrade head 可用 - tests: test_notifications + test_push_center 共 35 例 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-14 18:57:04 +08:00
parent 2236a8b3ee
commit a8ac5dc0c7
16 changed files with 2146 additions and 48 deletions
@@ -1,9 +1,9 @@
 # 傻瓜比价 App 后端 — API 接口文档（索引）

 > Base URL:生产 `https://app-api.shaguabijia.com`;本地联调 `http://<开发机>:8770`
-> 协议:HTTP / JSON,请求与响应体均 `application/json`,字段统一 **snake_case**
+> 协议:HTTP / JSON,请求与响应体均 `application/json`,字段统一 **snake_case**(⚠️ 例外:消息通知中心 `notifications` 族与厂商推送 `push` 族按 PRD 前端契约用 **camelCase**,见各自文档)
 > 鉴权:需鉴权的接口在请求头带 `Authorization: Bearer <access_token>`
-> 最后更新:2026-06-23（补全此前缺整族的端点:device 无障碍存活监控、internal 内部回写、CPS 短链落地、report/invite/wxpay,及 platform/coupon/feedback/user 的零散读端点;device/internal/cps-redirect 三族新建单文件文档。上一次 2026-06-18 补录比价透传端点与 `meituan/top-sales`）
+> 最后更新:2026-07-14（新增 **消息通知中心** 3 端点(M1-M3,虚拟数据阶段)与 **厂商推送测试** 3 端点(P1-P3,荣耀/华为/小米/OPPO/vivo);上一次 2026-06-23 补全 device/internal/CPS 短链等整族端点）
 > 架构:`app/api/v1/` 只放很轻的接口层;穿山甲/微信支付/极光/短信/美团等 SDK 集成的重逻辑在 `app/integrations/`,实现细节见 [docs/integrations/](../integrations/README.md)。

 ---
@@ -99,6 +99,14 @@
 | 38 | `POST /api/v1/feedback` | Bearer | [详情](./feedback.md) |
 | 38a | `GET /api/v1/feedback/config` | Bearer | 反馈页「加群二维码」卡配置（开关 + 二维码图 + 三行文案）(无单独文档) |
 | 38b | `GET /api/v1/feedback/records` | Bearer | 我的反馈历史（pending/adopted/rejected）(无单独文档) |
+| **消息通知中心**（前缀 `/api/v1/notifications`;⚠️ 本族对外 **camelCase**;虚拟数据阶段:内存 mock,重启复位） |||
+| M1 | `GET /api/v1/notifications` | Bearer | [详情](./notifications.md)（消息列表,分页;13 类型卡片字段 + sentAt/isRead;服务端已按时间倒序排好,不分组） |
+| M2 | `GET /api/v1/notifications/unread-count` | Bearer | [详情](./notifications.md)（未读总数,首页铃铛角标;>99 → "99+",0 → null 隐藏） |
+| M3 | `POST /api/v1/notifications/read` | Bearer | [详情](./notifications.md)（标记已读:`{ids:[...]}` 单条/多条 或 `{all:true}` 进通知中心全量清零;幂等） |
+| **厂商推送测试**（前缀 `/api/v1/push`;荣耀/华为/小米/OPPO/vivo 五通道联调三件套,同为 camelCase） |||
+| P1 | `GET /api/v1/push/vendors` | Bearer | [详情](./push-vendor-test.md)（5 厂商服务端凭据配置状态,缺哪些 .env 键一目了然） |
+| P2 | `GET /api/v1/push/templates` | Bearer | [详情](./push-vendor-test.md)（13 类通知的 push 标题/正文模板 + PRD 示例渲染效果） |
+| P3 | `POST /api/v1/push/test` | Bearer | [详情](./push-vendor-test.md)（测试发送:默认 mock 不真发;mock=false 真发;可联动插一条站内 mock 通知闭环验证已读） |
 | **首页门面数据 / 客户端配置**（前缀 `/api/v1/platform`；全平台展示数字 + 运营开关,**全部不鉴权**,登录前可读） |||
 | 39 | `GET /api/v1/platform/stats` | 无 | [详情](./platform-stats.md) |
 | 40 | `GET /api/v1/platform/savings-feed` | 无 | [详情](./platform-savings-feed.md) |
@@ -0,0 +1,121 @@
+# 消息通知中心(notifications 族)
+
+> 所属:notifications 组(前缀 `/api/v1/notifications`,源 `app/api/v1/notifications.py`) | 鉴权:**全部 Bearer**(消息按用户隔离) | [← 返回 API 索引](./README.md)
+>
+> 对应 PRD《消息通知中心》(通知类型清单 / 点击跳转 / 字段元素 / 未读红点 / Push 文案)。
+> Push 侧(厂商直推 + 测试)见 [push-vendor-test.md](./push-vendor-test.md)。
+>
+> ⚠️ **虚拟数据阶段**:数据来自内存 mock(`app/repositories/notification_mock.py`),每个用户首次访问生成一套固定样例(13 种类型全覆盖 + 今天/昨天/当年/跨年四种时间 + 已读未读混合,共 16 条,id 从 90001 起);已读状态在服务端内存维护,**重启服务复位**。后续接真实数据只换 repository 实现,接口契约不变。
+>
+> ⚠️ **字段命名**:本组接口(含 push 测试组)对外为 **camelCase**(`sentAt` / `isRead` / `pageSize`…),与库内其他 snake_case 接口不同——按 PRD 前端契约对接,勿混用。
+
+## 通知类型速查(13 种)
+
+列表**服务端已排好序:全列表按时间倒序**(最新在前,**不做分类分组**——PRD §1 的"按分类分组"为笔误,2026-07-14 需求方确认取消),前端按返回顺序渲染即可。category 仅用于卡片头部的分类标签展示。
+
+| category | 分类标签 | type | 类型 | cardStyle 版式 | actionText 操作行 | extra 里带什么 |
+|---|---|---|---|---|---|---|
+| withdraw_assistant | 提现助手 | `reward_expiring` | 金币现金奖励即将失效 | dual_amount 双金额卡 | 立即激活您的收益 | `batchId` |
+| withdraw_assistant | 提现助手 | `reward_expired` | 金币现金奖励已失效 | dual_amount 双金额卡 | 立即赚取新收益 | — |
+| withdraw_assistant | 提现助手 | `withdraw_success` | 提现成功 | withdraw 提现卡 | **null(无操作行,点击仅消红点)** | — |
+| withdraw_assistant | 提现助手 | `withdraw_failed` | 提现失败,款项已退回 | withdraw 提现卡 | 重新提现 | `withdrawId` |
+| system | 系统通知 | `perm_accessibility` | 比价功能异常(无障碍) | plain_text 纯文本卡 | 去开启 | `permission:"accessibility"` |
+| system | 系统通知 | `perm_battery` | 比价续航保护异常(省电策略) | plain_text 纯文本卡 | 去开启 | `permission:"battery"` |
+| system | 系统通知 | `perm_autostart` | 比价启动保护异常(自启动) | plain_text 纯文本卡 | 去开启 | `permission:"autostart"` |
+| system | 系统通知 | `perm_overlay` | 比价按钮异常(悬浮窗) | plain_text 纯文本卡 | 去开启 | `permission:"overlay"` |
+| feedback | 我的反馈 | `feedback_reply` | 官方回复 | plain_text 纯文本卡 | 查看详情 | `feedbackId` |
+| feedback | 我的反馈 | `feedback_reward` | 反馈奖励(必带官方留言行) | coin_reward 金币奖励卡 | 查看反馈详情 | `feedbackId` |
+| report | 我的爆料 | `report_approved` | 爆料审核通过 | coin_reward 金币奖励卡 | 查看爆料详情 | `reportId` |
+| invite | 好友邀请 | `invite_order_reward` | 好友下单奖励到账 | friend_cash 好友现金卡 | 邀请更多好友赚现金 | `inviteeNickname` |
+| invite | 好友邀请 | `invite_remind` | 好友催单提醒 | plain_text 纯文本卡 | 去提醒 TA | `inviteeNickname`, `scrollTo:"remind"` |
+
+点击跳转逻辑按 PRD §2 由客户端按 `type` 分发;点击目标 = 整张卡片(不区分主体和操作行),任何点击都先调 `POST /read` 消该条红点。
+
+## GET /api/v1/notifications — 消息列表(分页)
+
+**入参(query)**
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `page` | int | ❌ | 页码,1 起,默认 1 |
+| `pageSize` | int | ❌ | 每页条数,默认 20,最大 100 |
+
+**出参**
+
+```jsonc
+{
+  "items": [
+    {
+      "id": 90001,
+      "category": "withdraw_assistant",   // 分类 key(5 种,见上表)
+      "categoryLabel": "提现助手",         // 卡片头部左上角分类标签
+      "type": "reward_expiring",          // 类型 key(13 种,决定点击行为)
+      "cardStyle": "dual_amount",         // 版式:dual_amount/withdraw/plain_text/coin_reward/friend_cash
+      "title": "金币现金奖励即将失效",      // 卡片标题
+      "coins": 86,                        // 金币数,整数;无金币的版式为 null
+      "cashCents": 1280,                  // 现金金额(分);无现金的版式为 null
+      "cashYuan": "12.80",                // 现金展示串(元,两位小数),与 cashCents 同源
+      "infoRows": [                       // 信息行,已按 PRD 拼好文案,逐行 label: value 渲染
+        { "label": "过期说明", "value": "您有86金币和12.80元现金即将失效，完成一次一键领券或一键比价即可激活收益" },
+        { "label": "过期时间", "value": "3天后失效" }
+      ],
+      "actionText": "立即激活您的收益",    // 操作行;null = 无操作行(提现成功卡)
+      "extra": { "batchId": "batch_20260714" },  // 跳转/联动参数,按 type 取用(见上表)
+      "sentAt": "2026-07-14T14:59:58+08:00",     // ISO8601 带时区
+      "isRead": false                     // false → 分类标签右侧显示 6px 红点(#E53935)
+    }
+  ],
+  "page": 1,
+  "pageSize": 20,
+  "total": 16,
+  "hasMore": false,
+  "unreadCount": 12    // 与 /unread-count 同口径,进页面可顺手刷角标
+}
+```
+
+**时间显示规则(前端处理 `sentAt`)**:今天 →「今天」;昨天 →「昨天」;当年 →「M月D日」(不补零);跨年 →「YYYY年M月D日」。mock 样例特意覆盖了这四种情况。
+
+**数值约束(PRD §3)**:金币整数不带小数;现金/提现金额两位小数(直接用 `cashYuan`)。
+
+## GET /api/v1/notifications/unread-count — 未读总数(首页铃铛角标)
+
+无入参。**出参**:
+
+```jsonc
+{ "count": 12, "badgeText": "12" }   // count>99 时 badgeText="99+";count=0 时 badgeText=null → 整个角标隐藏
+```
+
+刷新时机(PRD §4):进入首页时、从通知中心/其他页面返回首页时(原型监听 `pageshow`)。
+
+## POST /api/v1/notifications/read — 标记已读
+
+**入参(JSON),两种模式二选一(同时传时 `all` 优先)**
+
+| 模式 | body | 使用场景 |
+|---|---|---|
+| 单条/多条 | `{ "ids": [90001, 90003] }` | ① 点击某张消息卡片(点击后无论跳转/弹窗/无动作都算已读);② 用户点击 push 直达落地页后,客户端拿 push extras 里的 `notificationId` 同步置读 |
+| 全量清零 | `{ "all": true }` | 进入通知中心自动清零(只浏览列表就消红点,无需逐条点击;退出通知中心时也可再调一次兜底) |
+
+**出参**
+
+```jsonc
+{ "ok": true, "markedCount": 2, "unreadCount": 10 }   // unreadCount = 处理后剩余未读,可直接刷新角标
+```
+
+幂等:不存在/已读的 id 忽略,重复调用 `markedCount=0` 不报错。
+
+**错误**:`400` ids 与 all 都没传(或 ids 为空数组);`401` 未鉴权。
+
+## 联调小抄
+
+```bash
+# 1. 登录拿 token(SMS mock:任意手机号 + 任意 6 位验证码)
+curl -X POST :8770/api/v1/auth/sms/send  -d '{"phone":"13800001234"}'
+curl -X POST :8770/api/v1/auth/sms/login -d '{"phone":"13800001234","code":"123456"}'
+# 2. 列表 / 角标 / 置读
+curl ":8770/api/v1/notifications?page=1&pageSize=20" -H "Authorization: Bearer $TOKEN"
+curl ":8770/api/v1/notifications/unread-count"        -H "Authorization: Bearer $TOKEN"
+curl -X POST ":8770/api/v1/notifications/read" -d '{"all":true}' -H "Authorization: Bearer $TOKEN"
+```
+
+要重置 mock 数据(重新生成整套样例):重启服务即可。想造「push → 站内联动」数据,用 [POST /api/v1/push/test](./push-vendor-test.md) 的 `createNotification:true`。
@@ -0,0 +1,102 @@
+# 厂商推送测试三件套(push 族)
+
+> 所属:push 组(前缀 `/api/v1/push`,源 `app/api/v1/push.py`) | 鉴权:**全部 Bearer** | [← 返回 API 索引](./README.md)
+>
+> 发送实现:`app/integrations/vendor_push.py`(荣耀 / **华为** / 小米 / OPPO / vivo 五通道,
+> `send_notification()` 通用入口)。站内消息中心见 [notifications.md](./notifications.md)。
+> 与 `POST /api/v1/device/push-test`(无障碍召回通道延迟自测)互补:本组面向消息中心 13 类 push 的文案/参数/通道联调。
+>
+> 字段命名同 notifications 族:**camelCase**。
+
+## 链路总览
+
+```
+真实业务事件(奖励过期/提现回执/审核通过/…)
+      └→ vendor_push.send_notification(vendor, token, title, body, extras)
+              extras = { type, notificationId, ...业务参数 }        ← 客户端深链 + 已读联动的钥匙
+客户端点击 push → 按 extras.type 直达落地页(与站内点击一致)
+              → 调 POST /notifications/read {ids:[extras.notificationId]} 同步消红点(PRD §4)
+```
+
+推送目标来源:客户端集成各厂商 push SDK 拿到 regId/token 后,通过 `POST /api/v1/device/register` 上报 `push_vendor` + `push_token`,服务端存 `device_liveness` 表。
+
+## GET /api/v1/push/vendors — 厂商配置状态
+
+检查 5 家厂商服务端凭据是否配齐(只读 .env,不打厂商接口)。`missingKeys` 即还要补的配置键;mock 测试不依赖任何凭据。
+
+```jsonc
+{ "vendors": [
+    { "vendor": "honor",  "label": "荣耀", "configured": false, "missingKeys": ["HONOR_PUSH_APP_ID", "HONOR_PUSH_CLIENT_ID", "HONOR_PUSH_CLIENT_SECRET"] },
+    { "vendor": "huawei", "label": "华为", "configured": false, "missingKeys": ["HUAWEI_PUSH_APP_ID", "HUAWEI_PUSH_APP_SECRET"] },
+    { "vendor": "xiaomi", "label": "小米", "configured": true,  "missingKeys": [] },
+    { "vendor": "oppo",   "label": "OPPO", "configured": false, "missingKeys": ["OPPO_PUSH_APP_KEY", "OPPO_PUSH_MASTER_SECRET"] },
+    { "vendor": "vivo",   "label": "vivo", "configured": false, "missingKeys": ["VIVO_PUSH_APP_ID", "VIVO_PUSH_APP_KEY", "VIVO_PUSH_APP_SECRET"] }
+] }
+```
+
+## GET /api/v1/push/templates — 13 类通知的 push 模板预览
+
+PRD §5 的 13 条 push 文案(标题固定 ≤11 字不带变量;正文 `{var}` 为变量,示例值即 PRD 示例)。对文案、看变量名用。
+
+```jsonc
+{ "templates": [
+    {
+      "type": "withdraw_success",
+      "category": "withdraw_assistant", "categoryLabel": "提现助手", "cardStyle": "withdraw",
+      "pushTitle": "提现到账提醒",
+      "pushBodySample": "¥0.50已存入您的微信钱包，点击查看到账详情",   // 用示例值渲染后的效果
+      "pushBodyTemplate": "¥{amount}已存入您的微信钱包，点击查看到账详情",
+      "variables": ["amount"],
+      "sampleVars": { "amount": "0.50" }
+    }
+    // ... 共 13 条,顺序即 PRD 编号
+] }
+```
+
+## POST /api/v1/push/test — 测试发送(默认 mock)
+
+**入参(JSON)**
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `vendor` | string | ❌* | `honor/huawei/xiaomi/oppo/vivo`,中文「华为」「小米」等别名也识别;留空时用 `deviceId` 设备上报的 vendor |
+| `pushToken` | string | ❌* | 厂商 push token/regId;留空则按 `deviceId` 反查已注册设备(*mock 模式两者都缺时用占位 token,只看渲染结果*) |
+| `deviceId` | string | ❌ | 客户端 `DeviceId.get()` 的设备 id,用于反查 vendor+token |
+| `type` | string | ❌ | 13 种类型 key 之一 → 按 PRD 模板渲染;不传且没直给文案 → 发通用测试文案 |
+| `vars` | object | ❌ | 覆盖模板变量,如 `{"coins":"520","cash":"6.66"}`;缺省用 PRD 示例值 |
+| `title` / `content` | string | ❌ | 直接指定标题/正文(优先于 type 模板) |
+| `createNotification` | bool | ❌ | true = 同时往该用户消息中心插一条同类型未读 mock 通知,extras 带其 `notificationId` → 可闭环验证「点 push → 调 /notifications/read 消红点」(仅 type 合法时生效) |
+| `mock` | bool | ❌ | **默认 true = 不真调厂商 API**,回显渲染结果;false = 真发到手机(要求该厂商凭据已配) |
+
+**出参**
+
+```jsonc
+{
+  "ok": true, "mock": true, "vendor": "huawei",
+  "title": "反馈奖励已到账",
+  "body": "谢谢您帮傻瓜比价变得更好，300金币已到账，还有一条给您的留言～",
+  "extras": { "type": "feedback_reward", "feedbackId": "3002", "notificationId": "90017" },
+  "notificationId": 90017,          // createNotification=true 时的站内 mock 通知 id
+  "missingKeys": ["HUAWEI_PUSH_APP_ID", "HUAWEI_PUSH_APP_SECRET"],  // 真发前还缺的配置(真发成功时必为空)
+  "vendorResponse": null            // 真发时为厂商 API 原始响应
+}
+```
+
+**错误**:`400` vendor/type 非法、真发但凭据未配(detail 列缺失键);`409` 真发但拿不到 pushToken;`502` 厂商 API 返回失败(detail 带厂商原始错误)。
+
+**真发注意**:
+- 目标手机必须先装 App 且客户端已集成对应厂商 SDK、`/device/register` 上报过 token;
+- vivo 未上架前走测试推送(`VIVO_PUSH_MODE=1`),目标手机需在 vivo 开放平台加入测试设备;
+- 小米新设备需在开放平台把签名/包名配好,token 才有效。
+
+## 厂商凭据怎么拿(.env 键名)
+
+| 厂商 | 后台 | 需要的键 |
+|---|---|---|
+| 华为 | AGC 控制台 → 项目设置 → 常规 → 应用 | `HUAWEI_PUSH_APP_ID`、`HUAWEI_PUSH_APP_SECRET`(OAuth client_id 即 AppId) |
+| 荣耀 | 荣耀开发者服务平台 → 推送服务 | `HONOR_PUSH_APP_ID`、`HONOR_PUSH_CLIENT_ID`、`HONOR_PUSH_CLIENT_SECRET` |
+| 小米 | 开放平台 → 消息推送 → 应用秘钥 | `XIAOMI_PUSH_APP_SECRET`(服务端只要这个;AppID/AppKey 是客户端 SDK 用) |
+| OPPO | 开放平台 → 推送服务 | `OPPO_PUSH_APP_KEY`、`OPPO_PUSH_MASTER_SECRET`(注意是**服务端 MasterSecret**) |
+| vivo | 开放平台 → 推送 | `VIVO_PUSH_APP_ID`、`VIVO_PUSH_APP_KEY`、`VIVO_PUSH_APP_SECRET` |
+
+各家发送协议差异(鉴权方式/成功码/payload 结构)封装在 `integrations/vendor_push.py`,业务侧只面对 `send_notification()`。