wms_worker_station/docs/packaging-voice-flow.md
zm2000 56341ddc35 feat(packaging): 调整 speak() 语音降级链顺序
将打包页语音播报降级链由「HTTP → 原生 TTS → Web Speech」
调整为「原生 TTS → HTTP → Web Speech」,并同步更新流程文档。
2026-09-28 15:31:52 +08:00

13 KiB
Raw Permalink Blame History

打包业务语音播报流程说明

范围:仓库打包业务页 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)做一次语音播报。
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 空闲自动登出

六、注意事项与已知问题

  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 串行播报,连扫时只保留最新一条待播,避免音频互相打断。