spec.md 13 KB
Feature Specification: 可切换的原生业务推送通道
Feature Branch: 033-native-push-routing
Created: 2026-09-29
Status: 服务端路由与随包 classpath 凭据已实现；默认 uni，原生通道未启用且真机投递未验证
Input: 为现有普通业务通知增加 Android FCM 与 iOS APNs 原生发送能力，以服务端配置切换，重启后生效；交付时继续默认使用 uniPush，不启用原生通道。仅涉及服务端；音视频通话推送不在范围内。
背景与边界
当前业务推送通过 PayPush 调用用户、商家、骑手三套 uniCloud 云函数，部分路径通过 PushEvent 写入 push_message。info_user 已有 cid、cidType、deviceToken：cid 是 uniPush 标识，deviceToken 承载 Android FCM token 或 iOS APNs device token，两者不可互用。用户已确认同一账号只允许一台手机登录，新手机登录后旧手机登录状态失效，因此本功能沿用现有单设备字段，不新增推送设备表。
本功能覆盖当前仍在使用的普通业务通知，包括订单、闪送、支付结果及平台/商家通知等现有发送路径；只替换发送通道，不增加新的业务触发时机或文案。不修改已废弃的支付/订单入口、临时测试推送接口，也不改动音视频通话推送。App 端 token 获取、上报及通知展示不在本功能实现范围；服务端以已有上报字段为输入。
User Scenarios & Testing (mandatory)
User Story 1 - 默认继续使用 uniPush (Priority: P1)
运维部署新版本后，不做任何切换，普通业务通知仍按现有路径发送，不因原生凭据尚未部署而影响服务启动。
Why this priority: 先交付原生能力但暂不启用，必须保证当前线上推送行为不变。
Independent Test: 不设置通道配置，触发用户、商家、骑手各一条现有业务通知，验证只调用对应 uniCloud 通道。
Acceptance Scenarios:
- Given 未配置推送通道或配置为
uni，When 任一普通业务通知触发，Then 仅走现有 uniPush 通道，不调用 FCM/APNs。 - Given 未部署原生通道凭据，When 服务以默认配置启动，Then 启动成功且现有 uniPush 可用。
- Given 已部署原生发送代码，When 音视频通话推送触发，Then 继续按原有独立流程处理，不受普通业务通知开关影响。
User Story 2 - 配置切换后 Android 走 FCM (Priority: P1)
运维将普通业务推送配置切换为原生并重启服务后，Android 接收方通过对应 App 的 FCM 项目收到现有通知。
Why this priority: 这是 Android 原生通知的核心能力，同时必须避免误把 uniPush CID 当作 FCM token。
Independent Test: 在原生配置下，分别向用户、商家、骑手 Android 账号触发通知，验证使用各自 Firebase 项目和 deviceToken，且未调用 uniCloud。
Acceptance Scenarios:
- Given 通道为
native、接收方系统为 Android 且有有效deviceToken，When 普通业务通知触发，Then 通过该接收端对应的 Firebase 项目向deviceToken发送一次；不得把cid传给 FCM。 - Given 用户、商家、骑手分别使用不同 Firebase 项目，When 三端各有通知触发，Then 每条通知使用对应项目凭据，不串用项目。
- Given 普通商家、夜市商家或商家子账号是接收方，When 原生通知触发，Then 均按商家端凭据路由。
- Given 门店存在符合当前通道发送条件的已登录分管账号，When 订单通知触发，Then 只通知这些分管账号，不同时通知主账号；如果没有符合条件的分管账号，才回退通知可用的主账号。切换原生通道不得改变这一收件人优先级。
User Story 3 - 配置切换后 iOS 走 APNs (Priority: P1)
同一原生配置下，iOS 接收方通过对应 App 的 APNs 普通通知证书收到现有通知。
Why this priority: 只有 Android FCM 不满足“三端全切原生”的目标。
Independent Test: 在原生配置下，分别向用户、商家、骑手 iOS 账号触发通知，验证使用各自普通推送证书、正确环境与 deviceToken，且未调用 uniCloud。
Acceptance Scenarios:
- Given 通道为
native、接收方系统为 iOS 且有有效deviceToken，When 普通业务通知触发，Then 通过该接收端对应的 APNs 普通通知证书向deviceToken发送一次；不得使用voIPToken。 - Given 运行环境为开发或生产，When 发送 iOS 通知，Then 选择相应 APNs 网关并使用该接收端对应的同一份普通推送证书，不混用三端凭据。
- Given 原有通知带有订单标识、业务类型或点击跳转所需 payload，When 改走 APNs，Then 这些业务字段仍可供接收端识别。
User Story 4 - 安全切换、失败隔离与回退 (Priority: P1)
运维能通过修改服务端配置并重启，在 uniPush 与原生通道间切换。单次通知只选择一个通道；发送失败不影响订单等业务操作。
Why this priority: 切换期间必须避免重复通知、业务流程被第三方推送故障阻断，以及随包凭据被写入日志或向非授权方分发。
Independent Test: 用缺失 token、原生服务异常、缺失凭据及配置回退场景验证发送结果、业务结果与消息中心记录。
Acceptance Scenarios:
- Given 通道为
native且原生 token 缺失或发送失败，When 普通业务通知触发，Then 记录可定位的失败信息，不自动补发 uniPush，也不改变原业务操作结果。 - Given 原路径会通过
PushEvent写入消息中心，When 任一通道发送成功、失败或 token 缺失，Then 保持原有入库语义，每次业务通知最多写入一条记录，不因切换重复入库。 - Given 通道从
native改回uni并重启，When 后续通知触发，Then 重新使用cid和 uniPush，不再调用 FCM/APNs。 - Given 原生模式所需的三端 FCM 或 APNs 凭据配置缺失、无法读取，When 服务启动，Then 明确报错并拒绝以不完整的原生配置启动；默认 uni 模式不受影响。
Edge Cases
cidType为空或不是android/ios：原生模式下不猜测平台，不尝试使用错误通道；记录失败，保持业务和原有消息中心行为。deviceToken为空、失效或来自另一 App/项目：不把cid当作替代 token；记录失败结果，失效 token 的后续处理应避免误删新手机刚更新的 token。- 同一账号换手机或 token 刷新：后端始终以当前账号最新上报的
cidType与deviceToken为发送目标；本功能不改变现有登录互斥机制。 - 批量发送含不同接收端或系统：按接收端、系统及相应项目/证书分组，不把不同项目 token 混发，也不因部分失败重复发送成功项。
- 业务代码直接调用底层 uniPush 方法：在范围内的普通业务通知必须纳入统一路由；已废弃代码、临时测试推送接口及音视频通话流程除外。
- 在用路径存在“CID 为空则不选择收件人/不触发推送”的前置判断：默认 uni 模式维持原判断效果；原生模式应以当前账号的
deviceToken判断可发送性，不得因 CID 为空漏掉有原生 token 的收件人。
Requirements (mandatory)
Functional Requirements
- FR-001: 服务端 MUST 提供普通业务推送的全局通道配置，取值为
uni/native，未配置时默认为uni；修改后重启生效，不新增管理后台实时开关。 - FR-002: 默认
uni模式 MUST 保持现有用户、商家、骑手 uniCloud 发送行为与消息中心入库行为；不得要求原生凭据存在。 - FR-003:
native模式 MUST 根据接收端类型和cidType路由：Android 使用对应 App 的 FCM，iOS 使用对应 App 的 APNs；普通商家、夜市商家及商家子账号均属于商家端。 - FR-003a: 门店订单通知 MUST 保持现有“符合条件的分管账号优先、没有时主账号兜底”规则，不得因切换通道而同时推送两类账号；分管账号的发送地址资格按当前通道判断。
- FR-004: 原生发送 MUST 只使用
deviceToken，uniPush MUST 只使用cid；不得相互复制或替代，voIPToken不得用于普通通知。 - FR-005: 用户、商家、骑手三套 Firebase 项目及 APNs 普通通知证书 MUST 独立配置并正确选择；iOS MUST 区分开发与生产环境。
- FR-006: 三端 FCM 服务账号、普通 APNs 证书及其
packetName/pwd配置 MUST 分别以user、merchant、rider明确命名并放在ruoyi-admin/src/main/resources/business-push/，由 classpath 读取。用户已明确要求这些真实凭据提交 Git 并随 JAR 打包；不得把私钥或密码写入日志、规格正文或推送响应。仓库和构建产物必须按含密钥材料管理。 - FR-006a: 每端
ios.p12与iosdev.p12经核对文件完全相同，资源中每端只保留一份 APNs 普通推送.p12。development/production只切换 APNs 网关，不切换证书文件；三端证书、Firebase 项目和 topic 不得混用。 - FR-007: 原生模式的必要凭据不完整时 MUST 在启动阶段明确失败；默认 uni 模式 MUST 可在无原生凭据时正常启动。
- FR-008: 所有当前在用的普通业务推送路径 MUST 使用一致的通道选择规则，包括适用的单发、批量及直接调用现有底层方法的路径；不改变业务触发时机、文案和 payload 语义。临时测试推送接口不在范围内。
- FR-009: 单次业务通知 MUST 只使用一个外部发送通道；原生发送失败或缺少 token 时 MUST NOT 自动回退到 uniPush，且 MUST NOT 使原业务操作失败。
- FR-010: 对现有会入库的推送，通道切换 MUST NOT 增加或漏掉
push_message记录；消息中心记录与外部发送结果保持解耦。 - FR-011: 实现范围 MUST 排除音视频通话推送、已废弃订单/支付入口及 App 端代码；不新增推送业务场景或改变登录互斥规则。
- FR-012: 本功能 MUST 沿用现有
info_user单设备字段，不新增数据库字段或设备表。 - FR-013: 外卖和闪送新单向多名骑手开放时，仅在
native模式对 Android 骑手按相同标题、正文及 payload 分组，使用骑手端 FCM multicast 发送；iOS 骑手保留逐设备 APNs 请求，uni模式保留原有逐骑手发送方式，不接入旧批量方法。各骑手的语言、消息中心记录和发送失败处理 MUST 保持独立，原生失败不得回退 uniPush。
Key Entities (include if feature involves data)
- 接收账号：已有账号记录，包含接收端类型、
cid、cidType、deviceToken；同一账号仅保留当前手机的一组推送标识。 - 普通业务通知：已有业务事件生成的标题、正文、payload 与接收方；发送渠道是可替换属性，不改变业务含义。
- 消息中心记录：现有
push_message，继续按原路径写入，不作为外部发送成功的证明。 - 通道配置与凭据：服务端全局
uni/native配置，以及已提交资源目录的三端 FCM/APNs 凭据；不属于业务数据库数据。
Success Criteria (mandatory)
Measurable Outcomes
- SC-001: 未配置开关的部署中，受测在用普通业务通知 100% 仍选择原 uniPush 通道，且无原生凭据时服务可启动。
- SC-002: 原生配置下，用户、商家、骑手 × Android、iOS 六种路由组合均选中正确凭据与
deviceToken，未把cid或voIPToken发送到原生通道。 - SC-003: 受测通知在正常发送、token 缺失和发送异常场景下，单次均不出现双通道外发；现有会入库的路径每次最多生成一条消息记录。
- SC-004: 模拟 FCM/APNs 不可用或 token 无效时，原业务操作结果与不发送推送时一致；失败可通过日志定位到接收端、平台与错误类别，日志不包含完整 token 或凭据。
- SC-005: 测试配置切回
uni并重启后，后续受测通知恢复原 uniPush 发送路径；音视频通话路径保持原行为。
Assumptions
- 用户已确认同一账号只允许一台手机登录，且新手机登录后旧手机登录状态失效；本功能依赖现有机制，不重新实现登录互斥。
- App 端会上报真实 FCM/APNs
deviceToken与正确的cidType；App 端变更和真机展示不包含在此次服务端交付范围。 - 原生能力交付后仍保持
uni为默认值；凭据虽随包提供，只有运维确认 App 端 token、将服务端配置切为native并重启，才会启用原生通道。 - 音视频通话使用其他推送流程，不受本次普通业务通知通道开关控制；
voIPToken及 VoIP 证书不用于本功能。 - 证书与 Firebase 服务账号由用户提供并提交到本仓库；仓库访问、构建产物分发和凭据轮换由部署方按含密钥材料管理。默认
uni下不加载这些凭据。