用户前台语音提醒：前端接入文档

日期：2026-10-09。

状态：后端已验证，未部署；本地七场景接入、152 项定向测试及模块构建通过。App 实现与真实云端/真机联调由前端完成；示例不代表线上已返回该字段。

责任与范围

后端在原来同一条用户订单通知中只增加 eventScene，保留文字与既有字段，不增加第二条推送、声音 URL 或语音接口。App 接收/播放、语言、音频和真机由前端人员完成，本任务不修改 App 或云函数。

仅在 App 前台收到新通知时播报；后台/锁屏声音保持现状。点击通知、消息列表加载、恢复 App 不补播，不使用通话/VoIP/后台保活绕过系统限制。

读取与字段

uniPush：读取消息 payload，可能是 JSON 字符串或对象，按实际 SDK 解包。
FCM：完整业务 JSON 在 data.payload；APNs 在 userInfo.payload，通常为字符串。
消息中心：已有记录 body 保存同一 JSON，但读取历史 body 不触发声音。
新字段只在完整 JSON 内，不要求同名顶层扁平字段；JSON 错误、缺场景或未知场景只保留原文字，不按正文猜声音。

字段	类型	用途
ddId	原类型不变，通常 string	订单标识
state	原类型不变，通常 string	原状态，不是统一语音分类依据
type	number	保持原值；0 已有其他用途，不表示用户语音场景
pushType	number	1 外卖、2 充值、3 闪送，保留原契约
eventScene	string，可缺省	唯一新增字段，下表场景之一

不新增 eventId、voiceLanguage、recipientUserId、eventTime，也不以别的字段名替代。前端直接按 eventScene 决定语句，再按 App 自身语言设置选择音频。后端文字仍按用户 Locale，本期不能从 payload 得知其语种或保证声音/文字语言完全一致。

场景与短语音

eventScene	简中建议语音	既有通知范围
RIDER_ACCEPTED	骑手已接单	外卖/闪送骑手实际接单
ORDER_DELIVERING	您的订单已派送	外卖取餐、闪送全部取件、自配送开始
ORDER_DELIVERED	您的订单已送达	外卖/闪送送达、自配送完成
MERCHANT_ACCEPTED	商家已接单	现有商家自配送接单用户通知
MERCHANT_READY	商家已出餐	现有商家出餐用户通知
PAYMENT_SUCCEEDED	您的订单已支付	在用 LINE/OMG 用户支付成功通知
ORDER_CANCELLED	您的订单已取消	现有外卖取消链路实际通知用户的情况

不增加通知时机：闪送部分取件不发派送，当前闪送取消只通知骑手，本期不补用户取消；自配送直接送达不补造开始配送。平台旧入口的数字 state 含义不同，不能用 state=3 一律判断送达。

只有实际商家出餐动作携带 MERCHANT_READY。旧订单资料编辑仍保留其原文字通知，但不携带 eventScene；前端不得据此或根据旧正文补播“已出餐”。

示例（后端协议示例，未部署）

{
  "ddId": "DD-DEMO-001",
  "state": "0",
  "type": -1,
  "pushType": 1,
  "eventScene": "RIDER_ACCEPTED"
}

闪送全部取件使用 pushType=3、state="PICKED_UP"、eventScene="ORDER_DELIVERING"。支付通知即使保留 type=0，也按 PAYMENT_SUCCEEDED 选语音。无 eventScene 的旧通知不自动播报。

前端处理建议及限制

只在收到消息且 App 确在前台、已登录时处理场景；点击、冷启动恢复和历史查询只展示/导航。
使用一个统一入口决定展示/播放责任，避免 uniPush 和原生监听器各自播放。SDK 若提供原有消息 ID，可用于本地去重；本期不提供后端事件 ID，不能保证精准跨回调去重。
不只按 ddId 去重，否则同单各状态互相覆盖；也不永久按 ddId+eventScene 去重，因为同场景可能合法再次发生。简单短时间去抖是前端权衡，不是恰好一次投递保证。
按场景和 App 自身语言映射本地短音频，单播放器串行播放，不叠加铃声。不播订单号/联系人/地址，不接受任意远程音频路径。
转后台、锁屏、登出或账号切换时停止/清空队列，恢复不补播。没有接收用户字段，payload 本身不能判别换号后迟到的消息归属，须依赖现有会话/设备绑定机制。
没有事件时间/版本，仅凭 payload 无法完整识别迟到、乱序或历史；不能把所有收到的消息当作最新订单状态。详情仍以业务查询为准。
音频缺失、播放失败或系统限制时保留文字，不请求后端补推，不强制音量，不启动后台保活。

前台播放器闲置且系统允许发声时，目标为实际收到通知后 2 秒内开始播报；具体实现、声音设置及效果由前端核验，后端不保证投递时延或播报成功。

点击与验收

点击按 pushType 区分实际外卖/闪送详情页，不把闪送 ddId 当外卖查询；不因点击再播声音。消息入库不代表外部已投递，外部到达也不代表声音已播放；本期无播放回执、可靠补发或跨通道自动回退。

前端联调检查：

七个场景选句正确，App 语言与资源对应，缺资源降级保留文字。
统一前台接收入口，检查多回调叠音风险；不声称只有本字段即可精准去重。
Android/iOS 前台播放；后台/锁屏不新增语音，恢复/点击/历史不补播。
多单连续通知、时序异常、账号切换、音频中断、静音/权限等按现有信息测试并记录限制。
旧 App 收新 JSON、新 App 收旧 JSON 保持通知，无 JSON 崩溃。
测试环境完整 payload 保留 eventScene；实际云端版本未验证，丢字段先反馈，不擅改云函数。

当前验证记录

七场景已接入，JDK 21 统一定向测试 152/152 通过，修复后 mvn -pl ruoyi-admin -am -DskipTests package 为 BUILD SUCCESS；整体审查发现的旧编辑误分类已回归修复。扩展回归 admin 947 项仍有 1 项基线泰文 key 缺失失败，详见 tasks。App、插件、音频、云函数未修改，真实云端/部署和真机未验证。新字段仅在完整 payload/body 内，不应从顶层查找 eventScene。

frontend-integration.md 6.3 KB Geçmiş Ham