feat: add local voice transcription pipeline

API.md

@@ -26,6 +26,39 @@ cargo run --bin migrate
 cargo run
 ```
 
+## 语音转录和反馈汇总
+
+长短录音统一通过小程序原生录音器上传到本服务。服务先将音频保存在 `AUDIO_STORAGE_DIR` 并立即响应，再由持久化后台队列调用本地 FunASR；模型暂时不可用或 API 重启都不会丢失已上传音频。
+
+```text
+AUDIO_STORAGE_DIR=./data/audio
+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
+```
+
+在项目根目录执行 `docker compose -f compose.asr.yml up --build -d` 启动中文模型。`GET /health` 中 `speech_available=true` 表示模型已下载并可以接收任务。
+
+腾讯云仅作为可选提供方保留。需要切换时配置：
+
+```text
+ASR_PROVIDER=tencent
+TENCENT_CLOUD_ASR_APP_ID=1234567890
+TENCENT_CLOUD_ASR_SECRET_ID=your-secret-id
+TENCENT_CLOUD_ASR_SECRET_KEY=your-secret-key
+TENCENT_CLOUD_ASR_ENGINE_TYPE=16k_zh
+```
+
+反馈汇总支持可选的 OpenAI 兼容 Chat Completions 接口。未配置时使用本地抽取式汇总，录音转录和保存流程仍可工作：
+
+```text
+FEEDBACK_SUMMARY_API_URL=https://api.example.com/v1/chat/completions
+FEEDBACK_SUMMARY_API_KEY=your-api-key
+FEEDBACK_SUMMARY_MODEL=your-model
+```
+
 ## 临时身份边界
 
 目前所有业务接口都要求 `X-User-Id` 请求头，值为 UUID。例如：
@@ -40,7 +73,7 @@ X-User-Id: 5a4da7f0-d70c-465f-bcab-124c504aa9f0
 
 | 方法 | 路径 | 说明 |
 | --- | --- | --- |
-| `GET` | `/health` | 服务状态及数据库是否已配置。 |
+| `GET` | `/health` | 服务、数据库、语音提供方及模型可用状态。 |
 | `GET` | `/api/v1/profiles` | 列出学生档案；可选 `query`、`grade`、`subject` 参数。 |
 | `POST` | `/api/v1/profiles` | 创建学生档案。 |
 | `GET` | `/api/v1/profiles/{profile_id}` | 读取单个学生档案。 |
@@ -51,6 +84,15 @@ X-User-Id: 5a4da7f0-d70c-465f-bcab-124c504aa9f0
 | `GET` | `/api/v1/feedback-records` | 列出反馈记录；可选 `profile_id` 参数。 |
 | `POST` | `/api/v1/feedback-records` | 创建反馈记录。 |
 | `DELETE` | `/api/v1/feedback-records/{record_id}` | 删除反馈记录。 |
+| `GET` | `/api/v1/feedback-sessions/active` | 读取指定学生进行中的语音反馈批次。 |
+| `POST` | `/api/v1/feedback-sessions` | 创建或恢复语音反馈批次。 |
+| `PUT` | `/api/v1/feedback-sessions/{session_id}` | 自动保存反馈正文和日期。 |
+| `POST` | `/api/v1/feedback-sessions/{session_id}/lessons` | 开始下一节课堂录音。 |
+| `POST` | `/api/v1/feedback-lessons/{lesson_id}/segments` | 上传一个自动切分的片段并加入后台转录队列。 |
+| `POST` | `/api/v1/feedback-lessons/{lesson_id}/finish` | 结束课节并汇总片段状态。 |
+| `POST` | `/api/v1/feedback-lessons/{lesson_id}/mark-applied` | 标记短录音文字已直接加入反馈。 |
+| `POST` | `/api/v1/audio-segments/{segment_id}/retry` | 重试失败片段的转录。 |
+| `POST` | `/api/v1/feedback-sessions/{session_id}/generate` | 汇总多节转录并生成反馈正文。 |
 
 ### 创建学生档案
 
@@ -83,6 +125,7 @@ X-User-Id: 5a4da7f0-d70c-465f-bcab-124c504aa9f0
 {
   "profile_id": "5fa5af2c-cfc9-4bb8-b0b3-8715f080b167",
   "feedback_date": "2026-07-14",
-  "content": "今天完成了色彩搭配练习，构图有明显进步。"
+  "content": "今天完成了色彩搭配练习，构图有明显进步。",
+  "feedback_session_id": null
 }
 ```