# 用户 App 推送语音：前端接入说明

**日期**: 2026-10-09
**一句话**: 用户订单推送的 payload 里新增了 `eventScene` 字段，App 在前台收到通知时按这个字段播一句短语音。

---

## 1. 从哪里读

| 通道 | 读哪里 |
|------|--------|
| uniPush（当前在用） | 消息的 `payload`，可能是 JSON 字符串或对象 |
| FCM | `data.payload`（JSON 字符串） |
| APNs | `userInfo.payload`（JSON 字符串） |

payload 长这样：

```json
{
  "ddId": "DD1700000001",
  "state": "1",
  "type": -1,
  "pushType": 1,
  "eventScene": "RIDER_ACCEPTED"
}
```

| 字段 | 用途 |
|------|------|
| `ddId` | 订单号 |
| `pushType` | 点击跳转用：1 外卖、2 充值、3 闪送 |
| `eventScene` | **本次新增**，播语音只看它；没有这个字段就不播 |

不要用 `state`、`type` 判断场景（历史含义不统一）。

## 2. eventScene 对应表

按 **App 自己的语言设置**选音频（payload 里没有语言字段）。音频自己录制，打进 App 包，每个场景一句短话。

| eventScene | 含义 | 简体中文 | 繁體中文 | English | ไทย |
|------------|------|---------|---------|---------|-----|
| `RIDER_ACCEPTED` | 骑手接单 | 骑手已接单 | 騎手已接單 | Rider accepted your order | ไรเดอร์รับออเดอร์แล้ว |
| `ORDER_DELIVERING` | 开始配送 | 您的订单已派送 | 您的訂單已派送 | Your order is on the way | ออเดอร์ของคุณกำลังจัดส่ง |
| `ORDER_DELIVERED` | 已送达 | 您的订单已送达 | 您的訂單已送達 | Your order has been delivered | จัดส่งออเดอร์ของคุณแล้ว |
| `MERCHANT_ACCEPTED` | 商家接单 | 商家已接单 | 商家已接單 | The merchant accepted your order | ร้านค้ารับออเดอร์แล้ว |
| `MERCHANT_READY` | 商家出餐 | 商家已出餐 | 商家已出餐 | Your order is ready | ร้านค้าเตรียมอาหารเสร็จแล้ว |
| `PAYMENT_SUCCEEDED` | 支付成功 | 您的订单已支付 | 您的訂單已支付 | Payment successful | ชำระเงินสำเร็จ |
| `ORDER_CANCELLED` | 订单取消 | 您的订单已取消 | 您的訂單已取消 | Your order has been cancelled | ยกเลิกออเดอร์ของคุณแล้ว |

## 3. 播放逻辑（示例）

```js
// 收到通知回调里（uniPush 2.0 示例）
uni.onPushMessage((res) => {
  if (res.type !== 'receive') return;   // 点击通知不播
  let p = res.data && res.data.payload;
  if (typeof p === 'string') {
    try { p = JSON.parse(p); } catch (e) { return; }
  }
  playVoice(p && p.eventScene);
});

function playVoice(scene) {
  if (!scene || !isForeground() || !isLogin()) return;  // 只在前台且已登录时播
  const audio = uni.createInnerAudioContext();
  audio.src = `/static/voice/${scene}_${uni.getLocale()}.mp3`;  // 如 rider_accepted_zh-CN.mp3
  audio.play();
}
```

多笔订单连续通知时用一个播放器排队串行播，不要叠音。

## 4. 规则（就这几条）

1. **只在前台播**；后台/锁屏走系统通知原样，不播语音。
2. **没有 `eventScene` 不播**（旧通知都这样），JSON 解析失败也不播、不崩溃。
3. **只播一次**：点击通知、打开消息列表、恢复 App 都不补播。
4. 音频只用 App 内本地文件，不播订单号等额外信息；播放失败就只留文字。

## 5. 点击跳转

| pushType | 跳转 |
|----------|------|
| 1 | 外卖订单详情 |
| 2 | 充值/钱包页 |
| 3 | 闪送订单详情（闪送单号别调外卖查询接口） |

---

**联调备注**: 后端字段已实现但未部署；uniPush 通道如果真机上收不到 `eventScene`，反馈后端排查，不要自行改云函数。详细规则见 `specs/035-user-notification-voice/frontend-integration.md`。