推送与设备需求文档

本文档定义平台端基于 push_devices 与 express_notifications 的推送能力需求，覆盖设备 CID 的采集/管理、物流事件驱动的消息生成与送达、隐私与验收标准。

关联文档：

配送模块需求文档.md
接口规范.md
前端字段清单.md
状态映射表.md
mall_sql/migrations/20260224_add_push_devices_and_notifications.sql

一、目标

保存每个用户/商家设备的推送 CID（支持多设备、多平台、多 appid）。
在轨迹事件触发时，生成消息中心记录并向对应活跃设备下发推送（通知/透传）。
提供消息幂等、未读/已读管理与审计能力，且严格控制敏感字段透传。

二、范围

包含：设备注册/解绑、设备活跃检测、消息表写入、消息去重、对外推送触发接口与消息中心 API。
不包含：具体第三方推送厂商通道的离线能力（小米/华为等厂商通道配置为后续任务）。

三、术语

CID：Push 平台分配的 client id。
设备：一台移动设备或浏览器实例，用 cid + appid 唯一标识。
消息（Notification）：由轨迹事件驱动的逻辑消息，写入 express_notifications 并可同步到消息中心与 Push 通道。

四、数据表与字段（概要）

说明：详细 DDL 请参考迁移脚本：mall_sql/migrations/20260224_add_push_devices_and_notifications.sql。

push_devices
- id, user_id, merchant_id, cid, platform, appid, is_active, last_seen_at, registration_source, created_at, updated_at
- 约束：同一 appid 下 cid 唯一；按 user_id/merchant_id 建索引。
express_notifications
- id, aud, recipient_id, order_id, waybill_id, tracking_no, carrier, message_id, event_text_safe, status_code, event_time, payload, read_at, dedupe_key, created_at, updated_at
- 幂等：message_id 唯一（若存在）或 dedupe_key 在生成逻辑层保证不重复写入。

五、REST API 设计（建议）

注：API 端点为示例，具体实现放在平台后端网关下。

设备管理

POST /api/v1/push/register — 注册/更新设备请求体：{user_id?, merchant_id?, cid, platform, appid, registration_source} 返回：设备记录
POST /api/v1/push/unregister — 解绑设备请求体：{cid, appid, user_id?}
GET /api/v1/push/devices?user_id=... — 列出某用户活跃设备

消息与消息中心

POST /api/v1/notifications/express/create — 由后端服务写入消息并触发推送（通常由 EventProcessor 调用）请求体示例：

{
  "aud":"user",
  "recipient_id":"<user_uuid>",
  "order_id":"<order_uuid>",
  "waybill_id":"<waybill_uuid>",
  "tracking_no":"YT123...",
  "carrier":"YTO",
  "message_id":"msg_...",
  "event_text_safe":"包裹正在派送中，派送员预计今日到达",
  "status_code":"OUT_FOR_DELIVERY",
  "event_time":"2026-02-24T10:00:00+08:00",
  "payload": {"deeplink": {"path":"/pages/order/detail","query":{"order_no":"ORD_...","tab":"logistics"}}},
  "dedupe_key":"waybill|event_id_or_composite"
}

GET /api/v1/notifications?aud=user&recipient_id=... — 列表
POST /api/v1/notifications/read — 标记已读（按 message_id 或 recipient_id+order_id 批量）

运维/调试

GET /api/v1/push/stats — 推送成功率/失败率/未读数（用于监控）

六、消息生成与推送流程

当 platform_express_tracking_events 写入新事件且满足推送策略（见下），平台事件处理器调用 express_notifications.create 写入消息表（使用 dedupe_key 保证幂等）。
写入成功后，异步任务查询 push_devices（按 aud/recipient_id/appid/is_active）获取目标 cid 列表并调用推送通道（uni-push2 或后端统一推送服务）。
推送返回结果写入日志并根据结果更新统计；若设备失效则将 push_devices.is_active 置 false（或记录探测失败）。

推送策略建议（MVP）：只在状态级变化或关键状态产生消息：SHIPPED/OUT_FOR_DELIVERY/READY_FOR_PICKUP/DELIVERED/EXCEPTION/RETURNED。

七、隐私与安全

不通过 push 透传 raw_payload、完整手机号、签名、密钥等敏感信息。
event_text_safe 为由平台清洗/脱敏后的文案，任何发送给客户端的文案必须经过该字段。
设备绑定时不得将密钥写入前端；CID 由客户端 SDK 提供，后端仅关联 user_id/merchant_id。
审计：对 push_devices 的创建/更新/读取 raw_payload 访问均需记录审计日志（平台侧实现）。

八、非功能需求

可用性：消息写入及触发应具备重试机制，推送通道建议异步队列化处理。
可观测性：记录每条消息的 created_at, sent_status, sent_at, response_code（推送日志由推送通道记录）。
可扩展性：支持按 appid 区分不同应用/环境，便于多包管理。

九、验收标准

能成功注册设备并查询到对应 cid（按 user_id）。
插入一条关键轨迹事件后：在 express_notifications 中新增消息且按活跃设备下发推送（模拟推送通道验证）。
相同事件重复到达不会产生重复消息（由 dedupe_key 或 message_id 保证）。
推送 payload 不包含敏感信息（检查 payload 字段）。

十、迁移与回滚建议

在执行迁移脚本前，先在测试库运行并检查索引与触发器。
若生产已有其它命名冲突，请先手工评估 push_devices 与 express_notifications 字段与现有表的兼容性。

十一、参考

pages/mall/delivery/doc/需求文档/配送模块需求文档.md
pages/mall/delivery/doc/需求文档/接口规范.md
mall_sql/migrations/20260224_add_push_devices_and_notifications.sql

作者：自动生成（可手动微调）日期：2026-02-24

5.8 KiB Raw Blame History Unescape Escape