init

voice-confirmation-web/README.md

@@ -0,0 +1,60 @@
+# 手术室耗材 — 语音确认（部署平台）
+
+这里是**语音确认浏览器端**的唯一静态载体：**与监控 API 分宿**，复制本目录即可独立分发（`index.html` + `voice_app.js`，Tailwind 使用 CDN）。
+
+- 功能：播放 TTS、并行录音、`POST .../resolve` 上传 WAV；WebSocket 收 `voice_assignment` / `voice_pending` 等。协议见 [`docs/客户端手术通信接口说明.md`](../docs/客户端手术通信接口说明.md)。
+- 界面：默认 **术间模式** 仅突出状态与用人话表述的结果；接口地址、原始 JSON 与详细日志在 **「高级设置」** 内。首次打开带查询参数 `?debug=1` 时会自动展开高级区（并记住展开状态）。
+- **禁止使用 `file://` 打开**（麦克风与跨域异常）；必须通过下文 **HTTP(S)** 方式访问。
+
+## 推荐：在本目录直接用 `start_http` 起服务
+
+仅需目标机装有 **Python 3**：
+
+| 系统 | 操作 |
+|------|------|
+| **macOS / Linux** | 首次：`chmod +x start_http.sh`，然后 `./start_http.sh`（端口可传第一参数，默认 `8080`） |
+| **Windows** | 运行 `start_http.bat`，端口可传第一参数（默认 `8080`） |
+
+环境变量 **`VOCH_HTTP_BIND`**：默认 `0.0.0.0`，用于同一局域网内的语音终端访问；若只允许本机调试，可设为 `127.0.0.1`（请配合防火墙与访问控制）。
+
+浏览器打开控制台打印的局域网 URL，将 **Base URL** 指向监控 API（示例 `http://192.168.1.100:38080`）。如果语音页 URL 是 `http://192.168.1.100:8080/`，页面首次加载会默认推导 API 为 `http://192.168.1.100:38080`，并据此连接 `ws://192.168.1.100:38080/client/voice-terminals/ws?...`。
+
+## 仓库根目录的封装脚本（仅此仓库内）
+
+在仓库根目录为开发便利提供的入口，行为与上文一致：
+
+```bash
+./start_voice_confirmation_web.sh --plain [端口]   # → 等价执行本目录 start_http.sh
+./start_voice_confirmation_web.sh --single [端口]  # → 生成 dist/ 后等价执行 dist/start_http.sh
+./start_voice_confirmation_web.sh [端口]           # livereload（需 uv sync --group dev）
+```
+
+Windows：`start_voice_confirmation_web.bat`。一键联调 `./start_all.sh` 在 `PLAIN_STATIC=1` 时会后台调用本目录的 `start_http.sh`（监听 `VOICE_HOST:VOICE_PORT`，默认 `0.0.0.0:8080`）。
+
+热重载也可直接：
+
+```bash
+uv run --group dev python scripts/dev_static_livereload.py --root voice-confirmation-web --host 0.0.0.0 -p 8080
+```
+
+（`--root` 须为**本目录的路径或名称**（在仓库根执行时即用 `voice-confirmation-web`）。）
+
+## 单 HTML 分发（`dist/`）
+
+在**仓库根**执行：
+
+```bash
+python3 scripts/bundle_voice_confirmation_single_html.py
+```
+
+生成 `dist/index.html`（内联脚本），并拷贝 `start_http.*` 到 `dist/`。对外只发包 **`dist/`** 即可；该目录默认被 `.gitignore` 忽略，需在本地或 CI 中执行上述命令生成。
+
+## 生产 / 大规模
+
+- 将本目录整体或 **`dist/`** 交给 **Nginx / Caddy / 对象存储 + CDN**；非 `localhost` 时通常需要 **HTTPS** 才能稳定使用麦克风，API 使用 **https** 与 **wss**。
+- **API 发布**：监控 API 默认由仓库根目录的 `./deploy.sh` 在宿主机监听 `0.0.0.0:38080`，浏览器 Base URL 填 `http://<监控服务局域网IP>:38080`。
+- **CORS**：独立部署的语音页跨域访问 API 时，后端需设置 `DEMO_CORS_ENABLED=true`；正式部署建议在 `.env` 里将 `DEMO_CORS_ORIGINS` 收窄为具体来源，例如 `http://<语音页局域网IP>:8080`。
+
+## 与 `scripts/demo_client` 的关系
+
+Demo 页（默认 :38081）负责流程联调；**不含**语音确认 UI。语音闭环只在**本目录**或 **`dist/`** 页面完成。