将打包页语音播报降级链由「HTTP → 原生 TTS → Web Speech」 调整为「原生 TTS → HTTP → Web Speech」,并同步更新流程文档。
219 lines
13 KiB
Markdown
219 lines
13 KiB
Markdown
# 打包业务语音播报流程说明
|
||
|
||
> 范围:仓库打包业务页 `src/pages/packaging/index.vue`(工作台打包模式)。
|
||
> 说明:行号为当前版本(1.0.28)源码位置,随代码变更可能漂移,以方法名为准。
|
||
|
||
---
|
||
|
||
## 一、播报架构总览
|
||
|
||
打包业务存在 **两条互相独立的语音播报链路**,叠加生效:
|
||
|
||
1. **页面主动播报链路** `speak()`:打包页在关键业务节点主动调用 `this.speak(文案)`,自带原生 TTS / HTTP 语音接口 / Web Speech 三级降级,并有串行队列(`voicePlaying`/`voicePendingText`)避免连扫时音频互相打断。
|
||
2. **全局 toast 拦截播报链路**:`src/main.js` 在应用启动时接管了全局 `uni.showToast`,任何 toast 都会同步调用 `getVoice().play(title)`(`src/core/voice.js`)做一次语音播报。
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A[打包业务节点] --> B[this.speak 文案]
|
||
A --> C[uni.showToast 文案<br/>silentVoice: true]
|
||
B --> D[speak 链路<br/>原生TTS → HTTP → WebSpeech]
|
||
C --> E[main.js 全局拦截器]
|
||
E -- silentVoice 跳过 --> X[不再重复播报]
|
||
```
|
||
|
||
> **双重播报已去重**:打包页所有「`speak(x)` + `showToast(x)`」成对节点,toast 均带 `silentVoice: true`,全局拦截器检测到该标志后跳过播报,同一文案只由 `speak()` 播一遍。
|
||
|
||
---
|
||
|
||
## 二、主动播报链路 `speak()`
|
||
|
||
定义于 `packaging/index.vue` 的 `methods.speak`(约 1185 行)。
|
||
|
||
### 2.1 入口:文本清洗 + 串行队列
|
||
|
||
```
|
||
speak(text)
|
||
├─ normalizeSpeakText:trim + 超 12 字截断为「前 12 字 + 等」
|
||
├─ voicePlaying 为 true → 覆盖 voicePendingText(只保留最新一条待播)后直接 return
|
||
└─ 否则置 voicePlaying=true → playSpeakText(str)
|
||
```
|
||
|
||
- 截断规则:`str.slice(0, 12) + '等'`,防止长文案播报啰嗦。
|
||
- 当前所有业务文案均在 12 字以内(最长「绑定失败,请点击绑定重试」「已结束打包并下线全部成员」正好 12 字),暂不触发截断。
|
||
- 串行队列:快速连扫时若正在播报,不打断当前音频,只保留最新一条待播文本(`voicePendingText`);当前一条播完由 `scheduleNextSpeak()` 取下一条,全部播完才把 `voicePlaying` 置回 false。
|
||
|
||
### 2.2 降级链(平台分支)
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
S[playSpeakText str] --> T{APP-PLUS<br/>ttsEngine 且 ttsReady}
|
||
T -- 是 --> N[speakNativeTts<br/>原生 TTS]
|
||
T -- 否 --> H[speakViaHttp<br/>HTTP 语音接口]
|
||
N --> E1[按语速估时 → scheduleNextSpeak]
|
||
H -- 成功 --> E2[scheduleNextSpeak]
|
||
H -- 失败 --> W[speakViaWebSpeech<br/>Web Speech]
|
||
W --> E3[按语速估时 → scheduleNextSpeak]
|
||
```
|
||
|
||
### 2.3 各子方法职责
|
||
|
||
| 方法 | 职责 | 关键实现 |
|
||
| --- | --- | --- |
|
||
| `speak(text)` | 播报总入口 | 文本清洗 + 12 字截断 + 串行队列调度 |
|
||
| `normalizeSpeakText(text)` | 文本清洗 | trim + >12 字截断为「前 12 字 + 等」 |
|
||
| `playSpeakText(str)` | 队列执行单元 | 降级链:原生 TTS → HTTP → Web Speech |
|
||
| `scheduleNextSpeak()` | 队列推进 | 取 `voicePendingText` 继续播,否则置 `voicePlaying=false` |
|
||
| `estimateSpeakMs(str)` | 估时 | 每字约 300ms,500–4000ms 区间 |
|
||
| `speakNativeTts(text)` | 原生 TTS(APP 首选) | `TextToSpeech.QUEUE_FLUSH=0` 清队列后播报 |
|
||
| `speakViaHttp(msg)` | HTTP 语音接口(TTS 不可用时) | GET `VOICE_API_URL + encodeURIComponent(msg)`,返回 `{audio}` 后下载本地播放 |
|
||
| `downloadVoiceAudio(src)` | 音频下载 | `uni.downloadFile` 下载到本地临时文件,失败回退远程地址 |
|
||
| `playVoiceAudio(src, onEnd)` | 音频播放 | `uni.createInnerAudioContext`,销毁旧实例再播,`onEnded`/`onError` 回调 |
|
||
| `speakViaWebSpeech(text)` | Web Speech(最终兜底) | `window.speechSynthesis`,`lang='zh-CN'` |
|
||
| `initNativeTts()` | 初始化原生 TTS | `plus.android.importClass('android.speech.tts.TextToSpeech')` + `OnInitListener` |
|
||
| `shutdownNativeTts()` | 释放 TTS | `stop()` + `shutdown()` + 清空字段 |
|
||
| `destroyVoiceAudio()` | 释放音频实例 | `stop()` + `destroy()` |
|
||
|
||
### 2.4 原生 TTS(APP 首选)
|
||
|
||
- 初始化:`initNativeTts()` 在 `mounted` 调用;`TextToSpeech(activity, OnInitListener)`。
|
||
- 就绪条件:`onInit` 回调 `status===0` 且 `setLanguage(Locale.CHINA)` 返回值 `>= 0` 才置 `ttsReady=true`。
|
||
- 播报:`speakNativeTts` 用 `TextToSpeech.QUEUE_FLUSH=0` 清队列后播报;无结束回调,播完后按 `estimateSpeakMs` 估时再推进队列。
|
||
- 关键坑:**平板缺中文语音包时 `setLanguage` 返回 -2(不支持)→ `ttsReady=false`**,此时跳过原生 TTS,降级到 HTTP 接口发声。
|
||
- 释放:`beforeUnmount` 调 `shutdownNativeTts()`。
|
||
|
||
### 2.5 HTTP 语音接口(原生 TTS 不可用时的兜底)
|
||
|
||
- 常量(约 358 行):
|
||
- `VOICE_API_URL = 'http://tbdata.gztbyc.com/voice/'`
|
||
- `VOICE_API_PATH = 'http://tbdata.gztbyc.com'`
|
||
- 请求:`uni.request`,GET `VOICE_API_URL + encodeURIComponent(msg + '。。')`,`timeout: 3000`,header `content-type: text/xml; charset=utf-8`。
|
||
- 响应:`res.data.audio` 为音频相对路径,拼 `VOICE_API_PATH + audio` 得完整 src。
|
||
- 下载:先 `downloadVoiceAudio` 下载到本地临时文件再播(避免内网/流式播放缓冲不足截断尾帧),失败回退直接播远程地址。
|
||
- 兜底:5 秒超时定时器,播放未结束也视为完成,避免一直等待。
|
||
- 失败判定:请求 fail / 未返回 `audio` 字段 / 音频播放 error → `finish(false)` → 触发 Web Speech 降级。
|
||
|
||
### 2.6 Web Speech(最终兜底)
|
||
|
||
- 仅 `typeof window !== 'undefined' && window.speechSynthesis` 可用。
|
||
- Android App WebView 内 `window.speechSynthesis` 通常不可用 → 真机主要依赖原生 TTS / HTTP 接口。
|
||
|
||
### 2.7 生命周期
|
||
|
||
| 时机 | 动作 |
|
||
| --- | --- |
|
||
| `mounted` | `initNativeTts()` 初始化 TTS |
|
||
| `beforeUnmount` | `shutdownNativeTts()` + `destroyVoiceAudio()` 释放 |
|
||
|
||
---
|
||
|
||
## 三、全局 toast 播报链路
|
||
|
||
### 3.1 机制(`src/main.js` + `src/core/voice.js`)
|
||
|
||
- `main.js` 在应用启动时覆盖 `uni.showToast`:每次 toast 取 `title`,调用 `getVoice().play(title)`。
|
||
- `core/voice.js` 的 `Voice` 类(单例):
|
||
- 请求 `GET http://tbdata.gztbyc.com/voice/{msg}`(注意:**msg 未 encodeURIComponent**,与打包页 `speakViaHttp` 的 `encodeURIComponent(msg)` 不同)。
|
||
- 返回 `{audio}` → `VOICE_BASE + audio` → `uni.createInnerAudioContext().play()`。
|
||
- 注释明确其用途:「仅播放语音,不弹 toast,避免与全局 showToast 拦截器互相递归」。
|
||
|
||
### 3.2 与 `speak()` 的关系
|
||
|
||
| 对比项 | 打包页 `speak()` | 全局拦截器 `getVoice().play()` |
|
||
| --- | --- | --- |
|
||
| 触发方式 | 业务节点显式调用 | 任何 `uni.showToast` 自动触发 |
|
||
| 文案编码 | `encodeURIComponent(msg)` | 未编码 |
|
||
| 降级链 | 原生 TTS → HTTP → Web Speech | 仅 HTTP,失败静默 |
|
||
| 适用范围 | 仅打包页 | 全应用所有页面 |
|
||
|
||
---
|
||
|
||
## 四、业务触发点全景
|
||
|
||
> 每个节点均为「语音文案 + 伴随 toast 文案」。`speakText` 表示来自 `checkOrderBlocked()` 返回的动态文案。
|
||
|
||
### 4.1 操作员绑定 / 下线
|
||
|
||
| # | 触发方法(行) | 触发条件 | 语音文案 | 伴随 toast |
|
||
| --- | --- | --- | --- | --- |
|
||
| 1 | `handlePackSearch`(683) | 扫码且无在线成员、非工牌码,拦截 | 需要先登录 | 需要先登录 |
|
||
| 2 | `queryPackOrderByCode`(706) | 未绑定操作员时禁止查询订单 | 未绑定操作员 | 请先绑定操作员 |
|
||
| 3 | `handleBadgeScan`(2482) | 工牌查询失败(failure/404 未找到用户) | 未绑定操作员 | 未找到该用户 |
|
||
| 4 | `doBindOperator`(2552) | 绑定接口 flag=failure | 绑定失败,请点击绑定重试 | 后端失败文案/绑定失败 |
|
||
| 5 | `doBindOperator`(2574) | 绑定成功 | 操作员姓名+绑定成功 | 绑定成功 |
|
||
| 6 | `doRemoveOperator`(2652) | 下线接口 flag=failure | 下线失败 | 后端失败文案/下线失败 |
|
||
| 7 | `doRemoveOperator`(2676) | 下线成功 | 操作员姓名+下线成功 | 操作员已下线 |
|
||
| 8 | `doRemoveOperator`(2684) | 下线返回 removed=0(未找到成员) | 下线失败 | 未找到该成员 |
|
||
| 9 | `doRemoveOperator`(2690) | 下线接口异常 | 下线失败 | 网络异常,请稍后重试 |
|
||
|
||
### 4.2 运单查询与预检
|
||
|
||
| # | 触发方法(行) | 触发条件 | 语音文案 | 伴随 toast |
|
||
| --- | --- | --- | --- | --- |
|
||
| 10 | `applyQueryResult`(817) | 工作台已解绑(401/403) | 无记录 | — |
|
||
| 11 | `applyQueryResult`(821) | 查询 flag=failure(未找到订单) | 无记录 | 未找到对应订单(>24 字则截断) |
|
||
| 12 | `applyQueryResult`(935) | 预检未通过 | `precheck.speakText`(见下) | `precheck.reason` |
|
||
| 13 | `applyQueryResult`(942) | 重复查询正在打包的同一单 | 正在打包 | 正在打包 |
|
||
|
||
**预检文案来源 `checkOrderBlocked()`**:
|
||
|
||
| 场景 | `speakText`(语音) | `reason`(toast) |
|
||
| --- | --- | --- |
|
||
| 团单/散单 未复核 | 订单未复核,禁止打包 | 订单未复核,禁止打包 |
|
||
| 团单/散单 已打包(非重复查询) | 已打包 | 订单已打包,禁止打包 |
|
||
| 散单 已拦截 | 订单已拦截,禁止打包 | 订单已拦截,禁止打包 |
|
||
|
||
### 4.3 团单商品核实
|
||
|
||
| # | 触发方法(行) | 触发条件 | 语音文案 | 伴随 toast |
|
||
| --- | --- | --- | --- | --- |
|
||
| 14 | `matchProductBarcode`(965) | 条码匹配但该商品已核实(重复扫) | 数据一致 | `xxx 已核实` |
|
||
| 15 | `matchProductBarcode`(973) | 条码匹配、标记已核实 | 数据一致 | `xxx 已核实` |
|
||
| 16 | `matchProductBarcode`(978) | 条码与待核实商品不匹配 | 无记录 | 条码与待核实商品不匹配 |
|
||
| 17 | `handleLongPressProduct`(1003) | 长按免验通过 | 免验通过 | `「xxx」免验通过` |
|
||
| 18 | `confirmCancelVerify`(1029) | 取消核实 | 已取消核实 | 已取消核实 |
|
||
|
||
### 4.4 开始打包与自动登出
|
||
|
||
| # | 触发方法(行) | 触发条件 | 语音文案 | 伴随 toast |
|
||
| --- | --- | --- | --- | --- |
|
||
| 19 | `startPack`(1136) | 上报开始打包成功(`reportPackOrder(1)` 成功) | 开始打包 | 开始打包 |
|
||
| 20 | `autoLogoutForIdle`(2946) | 30 分钟无新任务自动登出全部成员 | 已结束打包并下线全部成员 | 长时间无新打包任务,已自动下线 |
|
||
|
||
---
|
||
|
||
## 五、播报文案汇总(去重后)
|
||
|
||
| 文案 | 出现节点 | 语义 |
|
||
| --- | --- | --- |
|
||
| 需要先登录 | 1 | 未绑定且扫码非工牌 |
|
||
| 未绑定操作员 | 2、3 | 未绑定即查单 / 工牌未找到用户 |
|
||
| 操作员姓名+绑定成功 | 5 | 操作员绑定成功 |
|
||
| 绑定失败,请点击绑定重试 | 4 | 绑定失败 |
|
||
| 操作员姓名+下线成功 | 7 | 操作员下线成功 |
|
||
| 下线失败 | 6、8、9 | 下线失败 |
|
||
| 无记录 | 10、11、16 | 查无订单 / 条码不匹配 |
|
||
| 订单未复核,禁止打包 | 12 | 预检:未复核 |
|
||
| 已打包 | 12 | 预检:已打包 |
|
||
| 订单已拦截,禁止打包 | 12 | 预检:散单已拦截 |
|
||
| 正在打包 | 13 | 重复查询同一单 |
|
||
| 数据一致 | 14、15 | 商品核实一致 |
|
||
| 免验通过 | 17 | 长按免验 |
|
||
| 已取消核实 | 18 | 取消团单核实 |
|
||
| 开始打包 | 19 | 开始打包上报成功 |
|
||
| 已结束打包并下线全部成员 | 20 | 空闲自动登出 |
|
||
|
||
---
|
||
|
||
## 六、注意事项与已知问题
|
||
|
||
1. **双重播报(已修复,2026-09-23)**:业务节点原本 `speak(x)` + `showToast(x)` 成对出现,而 `showToast` 被 `main.js` 全局接管会再次播报 → 同一文案播两遍。
|
||
- 修复方案:`main.js` 拦截器新增 `silentVoice` 跳过标志;打包页 19 处成对 toast 均加 `silentVoice: true`,语音统一由 `speak()` 三级降级链路播报。
|
||
- 保留的独立 toast(无 `silentVoice`)仍走全局 `getVoice().play()` 播报。
|
||
2. **平板缺中文语音包**:原生 TTS `setLanguage(Locale.CHINA)` 返回 -2,`ttsReady=false`,必须依赖 HTTP 语音接口 `tbdata.gztbyc.com` 才能发声(实测结论,见仓库记忆)。
|
||
3. **URL 编码不一致**:打包页 `speakViaHttp` 对文案做 `encodeURIComponent`,而 `core/voice.js` 的 `play()` 未编码,含中文/特殊字符文案在两链路下的请求 URL 不同,后端需同时兼容。
|
||
4. **长文本截断**:`speak()` 对 >12 字文案截断为「前 12 字 + 等」;当前所有文案均 ≤12 字,未触发。
|
||
5. **HTTP 接口超时**:请求 timeout 3000ms + 播放 5s 兜底;接口不可达时自动降级 Web Speech,不影响业务流程。
|
||
6. **资源释放**:页面卸载时 `shutdownNativeTts()` + `destroyVoiceAudio()`,避免音频实例泄漏。
|
||
7. **APP-PLUS 与 H5 差异**:原生 TTS 仅在 APP-PLUS 可用;Electron/H5 端无原生 TTS,实际生效链为「HTTP → Web Speech」。
|
||
8. **串行队列**:`speak()` 内部用 `voicePlaying`/`voicePendingText` 串行播报,连扫时只保留最新一条待播,避免音频互相打断。
|