foodie-server/specs/033-native-push-routing/quickstart.md

普通业务推送：原生通道部署与回退

状态（2026-09-29）：服务端具备 FCM/APNs 路由能力，默认 uni，尚未启用原生推送。本功能不处理音视频通话，也不包含 App 端 token 获取、上报和展示改造；未完成真机验证前不要切换生产环境。

配置与凭据

三端真实凭据已按用户明确要求提交在 ruoyi-admin/src/main/resources/business-push/，并随 JAR 打包；每端只保留一份普通 APNs .p12，开发/正式只切换网关。任何能读取 Git 历史、JAR 或包含资源的镜像的人都能取得服务账号私钥与证书密码。须限制仓库及构建产物访问，不把密钥内容写入日志或公开分发；如发生泄露，应轮换 Firebase 服务账号与 APNs 证书，并重新构建发布。

接收端	FCM 服务账号	APNs 普通证书	APNs topic/密码配置
用户	user-fcm-service-account.json	user-apns.p12	user-apns-config.json
商家（含夜市及分管账号）	merchant-fcm-service-account.json	merchant-apns.p12	merchant-apns-config.json
骑手	rider-fcm-service-account.json	rider-apns.p12	rider-apns-config.json

APNs 配置 JSON 使用原文件的 packetName 作为 topic、pwd 解锁同端 .p12；三端 Firebase 项目分别对应各自 App，不能共享 server.json。不使用 VoIP 证书。application.yml 默认指向上述 classpath 文件，仍保留显式文件路径及 APNs 密码/topic 覆盖能力，以兼容原部署方式。

设置	环境变量	默认/要求
通道	BUSINESS_PUSH_MODE	uni；可选 native，重启后生效
APNs 环境	BUSINESS_PUSH_APNS_ENVIRONMENT	production；测试包用 development
三端 FCM 路径覆盖	`BUSINESSPUSH{USER	MERCHANT
三端 APNs 证书路径覆盖	`BUSINESSPUSH{USER	MERCHANT
三端 APNs 配置路径覆盖	`BUSINESSPUSH{USER	MERCHANT

如需覆盖 APNs 配置 JSON，也可分别设置原有的 BUSINESS_PUSH_{USER|MERCHANT|RIDER}_APNS_CERTIFICATE_PASSWORD 与 BUSINESS_PUSH_{USER|MERCHANT|RIDER}_APNS_TOPIC；两项都显式提供时不读取配置 JSON。默认 uni 模式不读取原生凭据；native 模式启动时校验三端配置并加载文件，缺失、不可读或证书无私钥/已过期时启动失败。

BUSINESS_PUSH_APNS_ENVIRONMENT=development 使用 APNs sandbox 网关，production 使用正式网关；两种环境读取同端同一份证书。已核对三端 packetName 与证书主题相符，但证书能否在两个网关实际投递仍需真机验证。三端证书到期日为 2027-07-30；更新任一资源后必须重新构建并部署 JAR，再做各端测试。

启用前条件

1. App 端分别上报真实的 Android FCM token 或 iOS APNs device token 至 info_user.deviceToken，并把 cidType 设置为 android 或 ios；cid 只用于 uniPush，不能复制到 deviceToken。本次交付不实现 App 端上报。
2. 确认新手机登录后旧手机会话失效，数据库中账号只保留当前设备 token；原生发送时服务端重新读取该账号的当前 cidType/deviceToken。
3. 在非生产环境确认私有 JAR 包含九个按端命名的资源，设置对应 APNs 环境与 BUSINESS_PUSH_MODE=native 并重启。先检查服务启动，再用三端 Android/iOS 各一台真机触发订单、闪送和支付通知；核对通知栏、点击 payload、消息中心、语言与接收人。iOS 骑手使用 pushsound.caf；Android 骑手 FCM 带 qsRing 通知渠道标识，须由 App 创建并配置该渠道才能保证自定义铃声，本次不修改 App。门店订单有可用分管账号时只通知分管账号，没有时才回退主账号。
4. 重点覆盖 CID 为空而原生 token 有效、token 缺失/失效、账号换机、预约闪送进入可抢单窗口，以及发送失败但业务操作成功。某条原生通知失败时不会自动回退 uniPush；原路径已有的消息中心记录应保持一次。

切换与回退

生产切换须先完成 App 端配套和真机验收。使用包含上述资源的受控构建，将 BUSINESS_PUSH_MODE 设为 native，按实例逐一重启并检查启动及推送错误日志；一条通知只会选择当前实例的一个通道，滚动重启期间不同实例可能短暂处于不同模式。若原生投递异常，改回 BUSINESS_PUSH_MODE=uni 并逐一重启；之后的新通知重新使用 cid，已失败的通知不会由服务端自动补发。回退时确认 App 仍维护有效的 uniPush CID。

自动化测试验证三端 classpath 凭据可加载、路由、请求构造和错误隔离；真实设备 token、FCM/APNs 外部投递、通知展示与回退操作仍需部署环境验证。

外卖和闪送新单通知附近最多 20 名骑手时，native 模式会按骑手当前设备类型分流：Android 骑手按相同语言文案和订单 payload 使用骑手端 FCM multicast，逐 token 处理返回结果；iOS 骑手继续逐设备走 APNs。每位骑手的消息中心事件保持独立，批量失败不回退 uniPush。默认 uni 模式及其逐骑手新单通知完全不变，旧的 uni 批量方法未接入此流程。