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

144 lines
6.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 语音广播(一期:原声广播)
仓库现场「管理工作台 → 所有工作台」的单向通知:管理工作台录一段原声(或输入文字),
其它工作台实时收到后**横幅显示 + 播放原声**。
> 一期不依赖任何语音识别(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` / 根三级)。