打包业务语音播报流程说明
范围:仓库打包业务页 src/pages/packaging/index.vue(工作台打包模式)。
说明:行号为当前版本(1.0.28)源码位置,随代码变更可能漂移,以方法名为准。
一、播报架构总览
打包业务存在 两条互相独立的语音播报链路,叠加生效:
- 页面主动播报链路
speak():打包页在关键业务节点主动调用 this.speak(文案),自带原生 TTS / HTTP 语音接口 / Web Speech 三级降级,并有串行队列(voicePlaying/voicePendingText)避免连扫时音频互相打断。
- 全局 toast 拦截播报链路:
src/main.js 在应用启动时接管了全局 uni.showToast,任何 toast 都会同步调用 getVoice().play(title)(src/core/voice.js)做一次语音播报。
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 降级链(平台分支)
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 |
空闲自动登出 |
六、注意事项与已知问题
- 双重播报(已修复,2026-09-23):业务节点原本
speak(x) + showToast(x) 成对出现,而 showToast 被 main.js 全局接管会再次播报 → 同一文案播两遍。
- 修复方案:
main.js 拦截器新增 silentVoice 跳过标志;打包页 19 处成对 toast 均加 silentVoice: true,语音统一由 speak() 三级降级链路播报。
- 保留的独立 toast(无
silentVoice)仍走全局 getVoice().play() 播报。
- 平板缺中文语音包:原生 TTS
setLanguage(Locale.CHINA) 返回 -2,ttsReady=false,必须依赖 HTTP 语音接口 tbdata.gztbyc.com 才能发声(实测结论,见仓库记忆)。
- URL 编码不一致:打包页
speakViaHttp 对文案做 encodeURIComponent,而 core/voice.js 的 play() 未编码,含中文/特殊字符文案在两链路下的请求 URL 不同,后端需同时兼容。
- 长文本截断:
speak() 对 >12 字文案截断为「前 12 字 + 等」;当前所有文案均 ≤12 字,未触发。
- HTTP 接口超时:请求 timeout 3000ms + 播放 5s 兜底;接口不可达时自动降级 Web Speech,不影响业务流程。
- 资源释放:页面卸载时
shutdownNativeTts() + destroyVoiceAudio(),避免音频实例泄漏。
- APP-PLUS 与 H5 差异:原生 TTS 仅在 APP-PLUS 可用;Electron/H5 端无原生 TTS,实际生效链为「HTTP → Web Speech」。
- 串行队列:
speak() 内部用 voicePlaying/voicePendingText 串行播报,连扫时只保留最新一条待播,避免音频互相打断。