# 手术室耗材 — 语音确认（部署平台）

这里是**语音确认浏览器端**的唯一静态载体：**与监控 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/`** 页面完成。