feat: add voice transcription feedback workflow

DEBUG_GUIDE.md

@@ -0,0 +1,310 @@
+# 本地调试指南
+
+本文用于在本机启动 PostgreSQL 连接、中文 FunASR、Rust API 和微信小程序，并验证短录音、长录音及多课节汇总。
+
+## 1. 服务关系
+
+```text
+微信小程序
+  -> Rust API（127.0.0.1:8080）
+     -> PostgreSQL
+     -> FunASR（127.0.0.1:10095）
+```
+
+本地录音转写的核心是 FunASR，当前组合为：
+
+- Paraformer：中文语音识别。
+- FSMN-VAD：检测并切分有效语音。
+- CT-Transformer：恢复中文标点。
+- PyTorch：CPU 推理运行时。
+
+Rust API 负责音频保存、持久化任务队列、重试、课节状态和反馈汇总。小程序每 8 分钟自动切片，并每 3 秒无感刷新转写状态。
+
+## 2. 当前主机资源实测
+
+测试主机为 Apple Silicon、10 核 CPU、16 GB 统一内存，配置为 CPU 单并发：
+
+| 项目 | 实测值 |
+| --- | --- |
+| FunASR 模型缓存 | 约 2.1 GB |
+| Python 虚拟环境 | 约 871 MB |
+| 模型加载后的物理内存 | 约 2.8 GB |
+| 进程历史内存峰值 | 约 4.9 GB |
+| 8 分钟、16 kHz、单声道、48 kbps MP3 | 约 44.8 秒完成 |
+| 推理期间 CPU | 约 90% 至 132%，即约 1 至 1.3 个 CPU 核 |
+
+8 分钟数据使用重复的清晰中文样本测得，真实课堂中的噪声、停顿和说话人数会影响耗时和识别质量。
+
+容量建议：
+
+- 当前单教师或低并发调试：不需要 GPU，当前 16 GB 主机足够。
+- CPU 部署最低建议：4 vCPU、8 GB 内存；8 GB 可能发生交换，16 GB 更稳妥。
+- 多教师并发：先保持单并发观察队列；若片段持续积压，再考虑增加 CPU 实例或 NVIDIA GPU。
+- GPU 是可选优化，不是运行前提。CUDA 部署需要单独的 CUDA/PyTorch 镜像，当前 CPU 镜像不能只修改 `ASR_DEVICE=cuda`。
+- GPU 部署建议从 8 GB 显存起步并用真实课堂录音压测。当前 Apple Silicon 配置没有使用 Apple GPU。
+- `ASR_WORKER_CONCURRENCY` 和 `ASR_MAX_CONCURRENCY` 应保持一致；每提高一个并发都要重新观察内存和吞吐。
+
+## 3. 首次准备
+
+在项目根目录执行：
+
+```bash
+cd /Users/zhangheng/project/ai/miniprogram/teaching-feedback-assistant
+```
+
+确认 `server/.env` 存在，并填写可访问的 `DATABASE_URL`。不存在时再复制示例，避免覆盖现有配置：
+
+```bash
+test -f server/.env || cp server/.env.example server/.env
+```
+
+本地 FunASR 默认配置如下，无需腾讯云密钥：
+
+```env
+ASR_PROVIDER=local
+LOCAL_ASR_URL=http://127.0.0.1:10095
+ASR_REQUEST_TIMEOUT_SECONDS=1800
+ASR_WORKER_CONCURRENCY=1
+ASR_JOB_LEASE_SECONDS=3600
+```
+
+首次准备 Python 环境：
+
+```bash
+cd asr-service
+python3 -m venv .venv
+.venv/bin/python -m pip install --upgrade pip
+.venv/bin/python -m pip install -r requirements.txt
+cd ..
+```
+
+模型首次启动会下载约 2.1 GB 到 `asr-service/.models`。`.venv` 和 `.models` 均已被 Git 和微信小程序打包忽略。
+
+## 4. 启动全部服务
+
+### 4.1 执行数据库迁移
+
+每次拉取到新迁移后执行一次：
+
+```bash
+cd server
+cargo run --bin migrate
+cd ..
+```
+
+看到 `PostgreSQL migrations completed` 表示成功。
+
+### 4.2 启动 FunASR
+
+终端一：
+
+```bash
+cd asr-service
+MODELSCOPE_CACHE=.models .venv/bin/uvicorn app:app \
+  --host 127.0.0.1 \
+  --port 10095 \
+  --no-access-log
+```
+
+另一个终端检查：
+
+```bash
+curl http://127.0.0.1:10095/health
+```
+
+预期结果：
+
+```json
+{"status":"ok","model":"paraformer-zh","device":"cpu"}
+```
+
+首次下载或缓存加载期间端口可能暂不可用，应等待模型完全加载。
+
+Docker 方式可替代本机 Python：
+
+```bash
+docker compose -f compose.asr.yml up --build -d
+docker compose -f compose.asr.yml logs -f funasr
+```
+
+### 4.3 启动 Rust API
+
+终端二：
+
+```bash
+cd server
+cargo run
+```
+
+检查完整链路：
+
+```bash
+curl http://127.0.0.1:8080/health | jq .
+```
+
+正常状态应包含：
+
+```json
+{
+  "status": "ok",
+  "database_configured": true,
+  "speech_configured": true,
+  "speech_available": true,
+  "speech_provider": "local-funasr"
+}
+```
+
+接口文档：<http://127.0.0.1:8080/scalar>
+
+### 4.4 启动微信开发者工具
+
+终端三，在项目根目录执行：
+
+```bash
+cli open \
+  --project /Users/zhangheng/project/ai/miniprogram/teaching-feedback-assistant \
+  --port 63097 \
+  --lang zh
+```
+
+自动预览编译检查：
+
+```bash
+cli auto-preview \
+  --project /Users/zhangheng/project/ai/miniprogram/teaching-feedback-assistant \
+  --port 63097 \
+  --lang zh \
+  --info-output /tmp/teaching-feedback-preview.json
+```
+
+开发者工具模拟器默认访问 `http://127.0.0.1:8080`。进入小程序“我的”页面，应看到“服务、数据库和语音转录正常”。
+
+## 5. 录音测试流程
+
+### 短录音
+
+1. 打开“反馈生成”。
+2. 点击“语音录入”，录制 10 至 30 秒中文。
+3. 点击“结束录音”。
+4. 页面短暂显示“正在处理”。
+5. 转写完成后文字应自动加入反馈内容。
+
+短录音条件为不超过 60 秒，且转写文本未超过后端短文本限制。
+
+### 长录音
+
+1. 录制超过 60 秒的中文。
+2. 结束后等待状态变成“已就绪”。
+3. 主按钮变为“生成反馈”。
+4. 点击一次后，转写内容会汇总进反馈草稿。
+
+### 多课节汇总
+
+1. 录制并结束第一节课。
+2. 再次点击“语音录入”录制下一节。
+3. 重复完成多节录音。
+4. 所有课节就绪后点击一次“生成反馈”。
+
+单节录音超过 8 分钟时，小程序会自动结束当前片段并立即开始下一片段，用户无需操作。
+
+## 6. 故障恢复测试
+
+### FunASR 未启动
+
+停止 FunASR 后录音，Rust API 仍会保存音频，页面保持“正在处理”。重新启动 FunASR 后，后台队列会自动继续。
+
+### Rust 在推理中退出
+
+任务使用租约避免多个工作线程重复处理。默认租约为 3600 秒。调试崩溃恢复时，可在 `server/.env` 临时设置：
+
+```env
+ASR_JOB_LEASE_SECONDS=60
+```
+
+重新启动 Rust API 后，超出租约的任务会再次被领取。生产环境应使用足够覆盖最长片段推理时间的租约。
+
+### 转写失败
+
+点击页面中的语音状态，可查看课节状态并重试失败片段。音频保存在 `server/data/audio`，转写失败不会立即删除原文件。
+
+## 7. 常见问题
+
+### `speech_configured=true` 但 `speech_available=false`
+
+- FunASR 尚未启动或模型仍在加载。
+- `10095` 端口被占用。
+- `LOCAL_ASR_URL` 配置错误。
+
+检查：
+
+```bash
+lsof -nP -iTCP:10095 -sTCP:LISTEN
+curl http://127.0.0.1:10095/health
+```
+
+### `database_configured=false` 或数据接口返回 503
+
+检查 `server/.env` 中的 `DATABASE_URL`，然后重新执行迁移并启动 API。
+
+### 微信模拟器无法连接 API
+
+```bash
+lsof -nP -iTCP:8080 -sTCP:LISTEN
+curl http://127.0.0.1:8080/health
+```
+
+再到小程序“我的”页面确认 API 地址为 `http://127.0.0.1:8080`。
+
+### 真机无法访问 `127.0.0.1`
+
+真机中的 `127.0.0.1` 指手机自身。局域网调试时：
+
+1. 将 `server/.env` 的 `HOST` 改为 `0.0.0.0`。
+2. 确认手机和电脑连接同一网络。
+3. 在“我的”页面将 API 地址改为 `http://<电脑局域网IP>:8080`。
+4. 检查系统防火墙和微信开发者工具的域名校验设置。
+
+正式环境必须使用微信允许的 HTTPS 合法域名。
+
+## 8. 代码检查
+
+小程序：
+
+```bash
+npm run typecheck
+```
+
+Rust：
+
+```bash
+cd server
+cargo fmt --check
+cargo test
+cargo clippy --all-targets -- -D warnings
+```
+
+FunASR 服务：
+
+```bash
+python3 -m py_compile asr-service/app.py
+asr-service/.venv/bin/python -m pip check
+```
+
+## 9. 停止服务
+
+前台运行时，在 FunASR 和 Rust API 各自终端按 `Ctrl+C`。
+
+Docker 方式：
+
+```bash
+docker compose -f compose.asr.yml down
+```
+
+确认端口已经释放：
+
+```bash
+lsof -nP -iTCP:8080 -sTCP:LISTEN
+lsof -nP -iTCP:10095 -sTCP:LISTEN
+```
+
+正常停止服务不会删除 `asr-service/.models` 模型缓存。除非希望重新下载模型，否则不要删除该目录。