feat: add local voice transcription pipeline

API_GUIDE.md

@@ -2,6 +2,12 @@
 
 ## 1. 启动服务
 
+先在项目根目录启动中文转录服务：
+
+```bash
+docker compose -f compose.asr.yml up --build -d
+```
+
 在 `server/.env` 中配置 `DATABASE_URL` 后执行：
 
 ```bash
@@ -28,12 +34,12 @@ X-User-Id: 5a4da7f0-d70c-465f-bcab-124c504aa9f0
 
 请求体接口也已提供可发送的默认 JSON。建议按以下顺序测试：
 
-1. 执行 `GET /health`，确认 `database_configured` 为 `true`。
+1. 执行 `GET /health`，确认 `database_configured` 和 `speech_available` 均为 `true`。首次模型下载期间后者为 `false`。
 2. 执行 `GET /api/v1/profile-defaults`，即使用户未保存过预设也会返回系统默认值。
 3. 执行 `PUT /api/v1/profile-defaults`，可直接发送预填的美术课预设。
 4. 执行 `POST /api/v1/profiles`，可直接发送预填档案；保存响应中的 `id`。
 5. 将真实档案 `id` 填入 `{profile_id}`，测试单条查询、更新或删除。
-6. 执行 `POST /api/v1/feedback-records`。默认 `profile_id` 为 `null`，无需档案即可直接创建。
+6. 执行 `POST /api/v1/feedback-records`。默认 `profile_id` 和 `feedback_session_id` 为 `null`，无需档案或录音即可直接创建。
 7. 如需关联档案，将第 4 步得到的 `id` 写入 `profile_id`。创建后保存反馈响应中的 `id`。
 8. 将真实反馈 `id` 填入 `{record_id}`，测试删除接口。
 
@@ -74,7 +80,8 @@ curl -X POST http://127.0.0.1:8080/api/v1/feedback-records \
   -d '{
     "profile_id": null,
     "feedback_date": "2026-07-15",
-    "content": "今天完成了色彩搭配练习，构图有明显进步。"
+    "content": "今天完成了色彩搭配练习，构图有明显进步。",
+    "feedback_session_id": null
   }'
 ```
 
@@ -114,6 +121,8 @@ curl 'http://127.0.0.1:8080/api/v1/feedback-records?profile_id=<真实档案ID>'
 }
 ```
 
+录音上传接口在音频入库后立即返回 `processing`。Rust 后台工作线程会调用 FunASR，并将片段更新为 `ready` 或 `failed`；小程序会自动刷新状态，短录音转写完成后仍会直接加入反馈正文。
+
 ## 6. OpenAPI 维护方式
 
 `/openapi.json` 在服务运行时由 `utoipa` 根据 Rust 路由注解生成，Scalar 使用同一份规范。新增或修改接口时，需要同时更新处理函数上的 `#[utoipa::path]`、请求/响应 schema 注释和示例；规范完整性测试会检查操作数量、接口说明和默认身份参数。