chore: merge Rust backend into monorepo

git-subtree-dir: server git-subtree-mainline: fb6a84d75f git-subtree-split: 8a88706ff9
2026-07-20 10:50:48 +08:00
parent fb6a84d75f 8a88706ff9
commit afdfa8bcf7
18 changed files with 6191 additions and 0 deletions
--- a/server/API_GUIDE.md
+++ b/server/API_GUIDE.md
@@ -0,0 +1,128 @@
+# 教学反馈助手 API 使用指南
+
+## 1. 启动服务
+
+先在项目根目录启动中文转录服务：
+
+```bash
+docker compose -f compose.asr.yml up --build -d
+```
+
+在 `server/.env` 中配置 `DATABASE_URL` 后执行：
+
+```bash
+cd server
+cargo run --bin migrate
+cargo run
+```
+
+默认地址取决于 `.env` 中的 `HOST` 和 `PORT`。使用示例配置时，可访问：
+
+- Scalar 交互文档：<http://127.0.0.1:8080/scalar>
+- OpenAPI JSON：<http://127.0.0.1:8080/openapi.json>
+- 健康检查：<http://127.0.0.1:8080/health>
+
+如果未配置 `DATABASE_URL`，服务仍可启动并访问健康检查和 API 文档，但业务接口返回 `503`。
+
+## 2. 在 Scalar 中直接测试
+
+打开 `/scalar`，选择接口后点击 **Test Request**。业务接口已经预填以下开发用户 ID：
+
+```text
+X-User-Id: 5a4da7f0-d70c-465f-bcab-124c504aa9f0
+```
+
+请求体接口也已提供可发送的默认 JSON。建议按以下顺序测试：
+
+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` 和 `feedback_session_id` 为 `null`，无需档案或录音即可直接创建。
+7. 如需关联档案，将第 4 步得到的 `id` 写入 `profile_id`。创建后保存反馈响应中的 `id`。
+8. 将真实反馈 `id` 填入 `{record_id}`，测试删除接口。
+
+OpenAPI 中的 `11111111-...` 和 `22222222-...` 仅用于展示路径参数格式，并不是数据库预置记录。调用按 ID 查询、更新或删除的接口时，必须换成创建或列表接口返回的真实 ID。
+
+## 3. 常用请求示例
+
+### 健康检查
+
+```bash
+curl http://127.0.0.1:8080/health
+```
+
+### 创建学生档案
+
+```bash
+curl -X POST http://127.0.0.1:8080/api/v1/profiles \
+  -H 'Content-Type: application/json' \
+  -H 'X-User-Id: 5a4da7f0-d70c-465f-bcab-124c504aa9f0' \
+  -d '{
+    "name": "小谢",
+    "grade": "艺术类",
+    "subject": "美术",
+    "academic_year": 2026,
+    "term": "暑",
+    "guardian_title": "小谢妈妈",
+    "start_time": "18:00",
+    "end_time": "19:00"
+  }'
+```
+
+### 创建不关联档案的反馈
+
+```bash
+curl -X POST http://127.0.0.1:8080/api/v1/feedback-records \
+  -H 'Content-Type: application/json' \
+  -H 'X-User-Id: 5a4da7f0-d70c-465f-bcab-124c504aa9f0' \
+  -d '{
+    "profile_id": null,
+    "feedback_date": "2026-07-15",
+    "content": "今天完成了色彩搭配练习，构图有明显进步。",
+    "feedback_session_id": null
+  }'
+```
+
+### 筛选反馈记录
+
+```bash
+curl 'http://127.0.0.1:8080/api/v1/feedback-records?profile_id=<真实档案ID>' \
+  -H 'X-User-Id: 5a4da7f0-d70c-465f-bcab-124c504aa9f0'
+```
+
+## 4. 身份和数据隔离
+
+当前尚未接入微信登录，所有业务接口临时使用 `X-User-Id` 标识用户。相同 UUID 可以访问自己创建的数据，不同 UUID 之间的数据互相不可见。
+
+`X-User-Id` 缺失时返回 `401`，格式不是 UUID 时返回 `400`。接入微信登录后，应由后端根据登录凭据确定用户身份，客户端不再直接提交该请求头。
+
+小程序开发客户端当前使用同一个测试 UUID，并默认连接 `http://127.0.0.1:8080`。可在小程序“我的”页面修改 API 地址并执行健康检查。真机或正式环境应使用已配置为微信 request 合法域名的 HTTPS 地址。
+
+## 5. 响应状态码
+
+| 状态码 | 含义 |
+| --- | --- |
+| `200` | 查询或更新成功 |
+| `201` | 创建成功 |
+| `204` | 删除成功，无响应体 |
+| `400` | 参数格式或业务校验失败 |
+| `401` | 缺少 `X-User-Id` |
+| `404` | 记录不存在或不属于当前用户 |
+| `500` | 数据库查询或服务内部错误 |
+| `503` | 未配置数据库连接 |
+
+错误响应统一为：
+
+```json
+{
+  "error": "错误说明"
+}
+```
+
+录音上传接口在音频入库后立即返回 `processing`。Rust 后台工作线程会调用 FunASR，并将片段更新为 `ready` 或 `failed`；小程序会自动刷新状态，短录音转写完成后仍会直接加入反馈正文。
+
+## 6. OpenAPI 维护方式
+
+`/openapi.json` 在服务运行时由 `utoipa` 根据 Rust 路由注解生成，Scalar 使用同一份规范。新增或修改接口时，需要同时更新处理函数上的 `#[utoipa::path]`、请求/响应 schema 注释和示例；规范完整性测试会检查操作数量、接口说明和默认身份参数。