wms_worker_station/docs/packaging-voice-flow.md
zm2000 c057cbdad2 feat(packaging): 打包页语音播报去重与串行队列
- 全局 showToast 拦截器支持 silentVoice 标志,跳过重复播报
- 打包页新增语音串行队列,连扫时不打断、只保留最新待播
- speak() 重构,非 HTTP 通道按语速估时取下一条
- 工牌码支持重复扫码切换上线/下线
- 绑定成功播报带上操作员姓名,核实类 toast 统一为「数据一致」
- 新增 docs/packaging-voice-flow.md 播报流程说明
2026-09-23 17:11:34 +08:00

12 KiB
Raw Blame History

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

范围:仓库打包业务页 src/pages/packaging/index.vue(工作台打包模式)。 说明:行号为当前版本(1.0.28)源码位置,随代码变更可能漂移,以方法名为准。


一、播报架构总览

打包业务存在 两条互相独立的语音播报链路,叠加生效:

  1. 页面主动播报链路 speak():打包页在关键业务节点主动调用 this.speak(文案),自带 HTTP 语音接口 / 原生 TTS / Web Speech 三级降级。
  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/>HTTP → 原生TTS → 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)
  ├─ 空文本 → 直接 return
  └─ str.length > 12 → 截断为「前 12 字 + 等」
  • 截断规则:str.slice(0, 12) + '等',防止长文案播报啰嗦。
  • 当前所有业务文案均在 12 字以内(最长「绑定失败,请点击绑定重试」「已结束打包并下线全部成员」正好 12 字),暂不触发截断。

2.2 平台分支

flowchart TD
    S[speak text] --> P{编译平台}
    P -- APP-PLUS 安卓App --> H[speakViaHttp HTTP 语音接口]
    P -- H5 / Electron --> W[speakViaTtsOrWebSpeech]
    H -- 成功 --> END[播放完成]
    H -- 失败 --> W
    W --> T{ttsEngine 且 ttsReady}
    T -- 是 --> N[speakNativeTts 原生 TTS]
    T -- 否 --> WS[speakViaWebSpeech Web Speech]

2.3 各子方法职责

方法 职责 关键实现
speak(text) 播报总入口 文本清洗 + 12 字截断 + 平台分流
speakViaHttp(msg) HTTP 语音接口(APP 首选) GET VOICE_API_URL + encodeURIComponent(msg),返回 {audio} 后用 playVoiceAudio 播放
playVoiceAudio(src, onEnd) 音频播放 uni.createInnerAudioContext,销毁旧实例再播,onEnded/onError 回调
speakViaTtsOrWebSpeech(text) TTS 兜底 有引擎且就绪→原生 TTS;引擎未就绪→暂存到 ttsPendingText;无引擎→Web Speech
speakNativeTts(text) Android 原生 TTS TextToSpeech.QUEUE_FLUSH=0 清队列后播报
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 HTTP 语音接口(解决平板缺中文语音包)

  • 常量(约 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。
  • 兜底:5 秒超时定时器,播放未结束也视为完成,避免一直等待。
  • 失败判定:请求 fail / 未返回 audio 字段 / 音频播放 error → finish(false) → 触发 TTS 降级。

2.5 Android 原生 TTS(HTTP 失败后的兜底)

  • 初始化:initNativeTts() 在 mounted 调用;TextToSpeech(activity, OnInitListener)。
  • 就绪条件:onInit 回调 status===0 且 setLanguage(Locale.CHINA) 返回值 >= 0 才置 ttsReady=true。
  • 关键坑:平板缺中文语音包时 setLanguage 返回 -2(不支持)→ ttsReady=false,只能依赖 HTTP 接口发声;引擎未就绪期间只保留最后一条文案到 ttsPendingText,就绪后补播。
  • 释放:beforeUnmount 调 shutdownNativeTts()。

2.6 Web Speech(最终兜底)

  • 仅 typeof window !== 'undefined' && window.speechSynthesis 可用。
  • Android App WebView 内 window.speechSynthesis 通常不可用 → 真机主要依赖 HTTP 接口 / 原生 TTS。

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) 未编码
降级链 HTTP → 原生 TTS → 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 兜底;接口不可达时自动降级 TTS/Web Speech,不影响业务流程。
  6. 资源释放:页面卸载时 shutdownNativeTts() + destroyVoiceAudio(),避免音频实例泄漏。
  7. APP-PLUS 与 H5 差异:Electron/H5 端跳过 HTTP 接口直接走 TTS/Web Speech(#ifdef APP-PLUS 条件编译)。