41 lines
4.9 KiB
Markdown
41 lines
4.9 KiB
Markdown
# 后台呼叫语音提醒
|
||
|
||
## 设计与实施计划（2026-10-03）
|
||
|
||
目标：已登录的后台在任意工作台页面接收新呼叫，启用语音后使用浏览器本机中文 TTS 播报桌位及服务类型。
|
||
|
||
选择浏览器 SpeechSynthesis，前端无新依赖、无第三方密钥。云 TTS 需费用与联网，本地服务端 TTS 需额外模型服务；本期不接入。仅选择 localService=true 的中文语音，避免自动把业务内容交给远程语音服务。
|
||
|
||
- [x] 先编写新增任务识别、去重、排队、关闭和失败行为测试，观察失败后实施。
|
||
- [x] Pinia 统一后台任务数据与 WebSocket 推送监听；退出登录停止请求并清空语音。切换业务页面不中断监听。连接就绪与事件推送后补查任务，每 60 秒低频兜底同步。
|
||
- [x] 首次快照仅建立基线；后续出现的新 pending 任务按时间排序播报，已接单/完成的不播报。关闭语音期间持续建立已见基线，不在重新启用时重放。
|
||
- [x] 全局可见开启/关闭、试听、状态和错误提示；语音通过用户点击启用，刷新页面重新启用。播报不包含顾客备注。
|
||
- [x] 串行播放并限制队列；等待播报期间任务被接单或取消则移除。失败停止语音并提示重新开启，队列卡住有超时处理。
|
||
- [x] 执行自动化测试、类型检查、生产构建与浏览器检查，记录真实语音能力限制。
|
||
|
||
当前每个页面独立开启语音；同一店铺建议只在指定接单电脑开启，多个设备/标签都开启时各自播报。WebSocket 推送成功后立即查询并更新列表；断线按 1–30 秒退避重连，45 秒无心跳主动重连；浏览器后台冻结、设备睡眠或页面关闭时无法保证播报。恢复网络后的下一次成功同步播报仍待接单的新任务。首次进入的历史未接单任务继续在列表展示，不补播。
|
||
|
||
依据：[SpeechSynthesis](https://developer.mozilla.org/en-US/docs/Web/API/SpeechSynthesis)、[localService](https://developer.mozilla.org/en-US/docs/Web/API/SpeechSynthesisVoice/localService)、[语音错误事件](https://developer.mozilla.org/en-US/docs/Web/API/SpeechSynthesisUtterance/error_event)。
|
||
|
||
WebSocket 协议：`GET /api/ws`，首帧 `{type:"auth",token}`，就绪 `ready`、通知 `tasks.changed`、每 20 秒 `heartbeat`；登录失效关闭 4403。token 不放 URL，Origin 校验且按门店隔离。服务端事务提交后通知，幂等重放不再次通知。首期单实例 Hub，未来多实例需 Redis Pub/Sub 分发。
|
||
|
||
## 接入位置
|
||
|
||
- `perler-beads-server/internal/server/websocket.go`：鉴权、按门店分组的连接、心跳与失效通知；`requests.go` 在创建/变更事务提交后发通知。
|
||
- `perler-beads-webui/src/notifications/store.ts`：Pinia 工作台级任务状态与同步；`realtime.ts`：连接状态、认证与退避重连。
|
||
- `core.ts`：快照去重与语音队列；`speech.ts`：本机中文 TTS 适配；`components/CallNotifications.vue`：全局控制与状态。
|
||
- `vite.config.ts` 与两份 Nginx 配置：WebSocket Upgrade 转发；frp HTTPS 透传无需增加独立隧道。
|
||
|
||
测试音与任务使用同一队列；不会因为试听而清空已有任务。服务端通知只带事件类型，不带顾客备注、图纸或用户资料，前端仍通过鉴权 API 获取当前数据。网络断线不重置任务已见集合，页面刷新则重新建立基线。
|
||
|
||
## 本次验收
|
||
|
||
- 后台 `npm test`：14 项通过；`npm run build`（包含 vue-tsc）通过。测试覆盖初始基线、重复/已处理任务、静音、中文本机音色、队列取消/过载/错误、试听期间的新任务、重连退避、鉴权失效与心跳超时。
|
||
- 服务端真实 PostgreSQL + Redis 的 `go test ./... -count=1`、`go test -race ./... -count=1`、`go vet ./...`、构建通过，详情见 [WS 服务端报告](ws-server-report.md)。
|
||
- 浏览器真实联调：已有登录工作台建立 WS，显示「实时连接正常」；选择系统本机音色「婷婷」，试听触发 onstart/onend；顾客 T01 桌提交呼叫后列表即时更新，最近播报变为「T01 桌，呼叫员工」。切换到图纸管理页后，再次提交补豆，最近播报变为「T01 桌，需要补充豆料」。这些是浏览器语音事件与界面验证，实际扬声器音量仍取决于设备设置。
|
||
- 两个联调呼叫已取消，保留验证记录；后台保持实时连接和语音开启，便于继续体验。页面刷新需要重新开启语音。
|
||
- 独立审查发现并修复了试听期间漏播/清空队列，以及 Nginx `$host` 丢失非标准端口导致 WS 同源校验失败。WS 路由使用 `$http_host` 保留端口。
|
||
- 未在 Docker/Nginx 实例、门店公网 TLS/frp、其他浏览器或睡眠唤醒设备上验收，部署前仍需测试。
|
||
|
||
截图：[新呼叫播报](screenshots/ws-tts-call.jpg)、[跨页面播报](screenshots/ws-tts-cross-page.jpg)。
|