wms_worker_station/docs/notice-voice-broadcast.md
zm2000 d75e4e8a74 feat(广播): 新增工作台语音广播一期(原声录制,storage mock 先行)
背景:仓库现场需要"管理工作台 → 所有工作台"的实时通知。管理员在任意工作台
录一段原声(或输入文字),其它工作台实时收到后横幅显示 + 播放原声。
后端接口尚未确定,一期用本地 storage 模拟,先跑通完整交互。

新增文件:
- notice.js            广播开关(NOTICE_MOCK)/长轮询/录音时长/存储键配置
- notice.ts               真实接口封装 send/poll/ack/uploadAudio(待后端就绪)
- notice-mock.js         storage 模拟"消息表 + 长轮询"
- notice.js              消息中心单例:轮询/去重/游标补发/过期丢弃/横幅通知/播报调度
- recorder.js            录音封装(App: getRecorderManager aac 16k 单声道;H5: MediaRecorder)
- notice-banner.vue        顶部广播横幅(通知/紧急、重播、关闭、自动收起)
- notice-send-dialog.vue   广播发送弹窗(语音/文字、录音计时、试听、优先级)
- notice-voice-broadcast.md          接口契约 + 验证步骤 + 已知限制

修改文件:
- voice.js               播报队列项改为 {kind:'tts'|'audio'},新增 playAudio/playUrgent/
                                  playAudioUrgent/clear,加 token 打断计数避免旧回调推进新队列;
                                  对外 play(text) 行为不变
- top-nav.vue      右上角新增"广播"入口(uni.$emit('notice:open-send'),预留
                                  canBroadcast 权限 prop);退出登录前 reset 消息中心;右侧容器改 flex
- index.vue       布局壳挂广播横幅 + 发送弹窗,onShow 启动接收,onUnload 清理,
                                  用户信息加载后同步发送人名称
- index.vue   打包模式页顶栏新增广播按钮 + 横幅(compact 12.5px 边距) + 弹窗,
                                  onShow 启动接收,退出登录 reset
- manifest.json               新增 android.permission.RECORD_AUDIO
- AndroidManifest.xml
                                  同步声明 RECORD_AUDIO(离线打包不读 manifest.json 的 permissions,
                                  不补会导至真机录音权限申请被拒)

说明:
- NOTICE_MOCK=true 时不发任何网络请求,消息只落本地 storage;同一浏览器多标签页可模拟多台工作台
  (游标只放内存、启动跳过历史,互不抢占);NOTICE_MOCK_SELF_PLAY=true 便于单机验证播报
- 两条登录路径都挂载横幅:账号登录走 pages/index 布局壳,工作台绑定登录走 pages/packaging
- 播报优先原声,未上传音频时回落现有 HTTP TTS;priority=1 插队并打断当前播报
- 老 WebView 兼容:组件内一律用 margin 代替 flex gap、控件 height+line-height 成对、
  广播按钮用 view(避开 APP-PLUS uni-button 内置样式),弹窗 z-index 990(低于内置 toast 999)
- 验证:npm run build:h5 / npm run build:app 均编译通过
2026-10-28 18:08:55 +08:00

6.8 KiB
Raw Blame History

语音广播(一期:原声广播)

仓库现场「管理工作台 → 所有工作台」的单向通知:管理工作台录一段原声(或输入文字), 其它工作台实时收到后横幅显示 + 播放原声。

一期不依赖任何语音识别(ASR)与后端接口:消息走本地 storage 模拟,先把交互跑通。 后端就绪后把 src/config/notice.js 的 NOTICE_MOCK 改为 false 即可切换真实接口。


1. 文件清单

文件 说明
src/config/notice.js 开关(NOTICE_MOCK)、长轮询时长、录音时长上限、弹窗/横幅时长、存储键
src/api/notice.ts 真实接口封装:sendNotice / pollNotice / ackNotice / uploadNoticeAudio
src/core/notice-mock.js 本地 storage 模拟的「消息表 + 长轮询」
src/core/notice.js 消息中心单例:长轮询、去重、游标补发、横幅通知、播报调度
src/core/recorder.js 录音封装(App 走 getRecorderManager,H5/Electron 走 MediaRecorder)
src/components/notice-banner.vue 顶部广播横幅(发送人 + 内容 + 重播 + 关闭)
src/components/notice-send-dialog.vue 广播发送弹窗(语音 / 文字、优先级)
src/core/voice.js 队列升级:支持 playAudio() 原声播放、playUrgent() 紧急插队、clear()

接入位置:

  • src/components/top-nav.vue:右上角「广播」按钮(uni.$emit('notice:open-send'))
  • src/pages/index/index.vue:账号登录后的布局壳 → 横幅 + 发送弹窗
  • src/pages/packaging/index.vue:工作台绑定登录后的打包模式页 → 顶栏「广播」按钮 + 横幅 + 弹窗
  • src/manifest.json:新增 android.permission.RECORD_AUDIO

两条登录路径都要挂横幅,否则绑定登录的工作台收不到广播。


2. 一期怎么验证(mock)

  1. npm run dev 启动 H5,账号登录进入工作台。
  2. 点右上角「广播」→「语音通知」→ 开始录音 → 停止 → 试听 → 发送广播。
  3. 本机立刻出现横幅并播放刚录的原声(mock 下 NOTICE_MOCK_SELF_PLAY = true)。
  4. 模拟其它工作台:同一浏览器再开一个标签页登录同一账号, 在 A 页发送,B 页也会收到横幅并播放(两个标签页各自维护内存游标,互不抢)。
  5. 「文字通知」走现有 HTTP TTS 接口播报(http://tbdata.gztbyc.com/voice/)。

真机(APP-PLUS):

  • 首次点「开始录音」会申请 RECORD_AUDIO 权限;
  • mock 只有本机 storage,跨设备不通,需要后端接口才能多机互发;
  • 真机录音格式为 aac(Android MediaRecorder 不支持 mp3 输出),播放走 innerAudioContext。

3. 真实后端接口契约

统一走现有 BASE_URL/system?method=xxx&v=1.0(POST JSON),音频上传单独走 multipart。

3.1 notice.uploadAudio(multipart/form-data)

file        : 音频文件(aac/m4a,16kHz 单声道)
duration    : 秒
workbench_id: 发起工作台 id
→ { url: "http://.../uploads/notice/xxx.aac", duration: 8.2 }

3.2 notice.send

{
  content: "B区波次已到货,抓紧复核",   // 可空(纯语音通知时为空)
  audio_url: "/uploads/notice/xxx.aac", // 可空(纯文字通知时为空)
  duration: 8.2,
  priority: 0,                          // 0 普通 / 1 紧急(接收端插队打断当前播报)
  target_type: "all",                   // all 全场(后续可扩展 group / workbench)
  target_ids: [],
  sender_name: "张三",
  sender_workbench_id: 8
}
→ { id: 1024, seq: 1024 }

3.3 notice.poll(长轮询)

{ since_id: 1023, workbench_id: 8, timeout: 25 }
→ 有新消息立即返回:{ list: [ {id, content, audio_url, duration, priority, sender_name,
                              sender_workbench_id, created_at, expire_at} ], last_id: 1024 }
→ 25 秒内无消息:{ list: [], last_id: 1023 }

要点:

  • 服务端 hold 25s;前端请求超时设成 30s(NOTICE_POLL_TIMEOUT + 5000);
  • since_id 由客户端持久化,断线/熄屏/重启后补发,保证不丢;
  • 返回字段按 id 升序。

3.4 notice.ack(可选)

{ ids: [1024, 1025], workbench_id: 8 }

用于「必达」统计(哪台工作台没收到/没播)。前端失败静默,不影响播报。


4. 已内置的行为

  • 去重:同一 id 只处理一次(内存 seenIds 滚动 200 条)
  • 离线补发:真实接口下 since_id 落 storage,重连后自动补拉
  • 过期丢弃:expire_at 已过期的消息只入游标、不播报(避免开机念旧通知)
  • 自己发的不播:sender_workbench_id === 本机 时只显示横幅(mock 下可用 NOTICE_MOCK_SELF_PLAY 打开,方便单机验证)
  • 原声优先:有 audio_url 播原声;没有则用 content 走 HTTP TTS
  • 紧急插播:priority=1 时插到播报队首并打断当前播报,横幅不自动消失
  • 录音前静音:开始录音先 getVoice().clear(),避免把播报声录进麦克风
  • 退避重连:拉取失败按 3s/6s/9s…(上限 15s)重试

5. 注意事项 / 已知限制

  1. mock 不跨设备:storage 是设备本地的,多机互发必须接后端。
  2. H5/Electron 录音:走 MediaRecorder(webm/opus),mock 下用 blob URL 播放; 接入真实上传时 H5 需后端支持 FormData 文件(uni.uploadFile 的 filePath 用 blob 受限)。
  3. H5 需要安全上下文:非 localhost 的 http:// 页面调不到麦克风(浏览器限制)。
  4. 老 WebView 兼容:组件内一律 margin 代替 flex gap;控件都写了 height + line-height; APP-PLUS 的 <button> 会被渲染成 <uni-button>(自带高特异性样式),广播按钮统一用 view。
  5. 层级:发送弹窗 z-index: 990(低于内置 toast 的 999);横幅在正常文档流中, 不遮挡页面的称重/包材等弹窗。
  6. 未做权限控制:目前所有登录用户都能发广播。若需限制为管理人员, 前端按 user.info 的角色/menus 传 canBroadcast 给 top-nav(已预留 prop), 服务端 notice.send 必须二次校验。
  7. 未做历史列表/未读:一期只有当前横幅,二期可加 notice.history + 未读数角标。
  8. 二期语音识别:管理员说话 → ASR 文本。只需把识别文本填入 content, 音频仍可一并上传(原声播放 + 文字留痕),接收端逻辑无需改动。

6. 切换到真实接口

  1. src/config/notice.js:NOTICE_MOCK = false;
  2. 后端按第 3 节补 4 个方法;
  3. 若接口名不同,改 NOTICE_METHOD 即可(send/poll/ack/upload);
  4. 若返回包裹层不同,调整 notice.js 的 fetchList / send 解包逻辑 (当前兼容 data / result / 根三级)。