# 打包业务语音播报流程说明 > 范围:仓库打包业务页 `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 文案
silentVoice: true] B --> D[speak 链路
原生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
ttsEngine 且 ttsReady} T -- 是 --> N[speakNativeTts
原生 TTS] T -- 否 --> H[speakViaHttp
HTTP 语音接口] N --> E1[按语速估时 → scheduleNextSpeak] H -- 成功 --> E2[scheduleNextSpeak] H -- 失败 --> W[speakViaWebSpeech
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` 串行播报,连扫时只保留最新一条待播,避免音频互相打断。