Files

shay7sev afdfa8bcf7 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

4.7 KiB

Raw Blame History

教学反馈助手 API 使用指南

1. 启动服务

先在项目根目录启动中文转录服务：

docker compose -f compose.asr.yml up --build -d

在 server/.env 中配置 DATABASE_URL 后执行：

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：

X-User-Id: 5a4da7f0-d70c-465f-bcab-124c504aa9f0

请求体接口也已提供可发送的默认 JSON。建议按以下顺序测试：

执行 GET /health，确认 database_configured 和 speech_available 均为 true。首次模型下载期间后者为 false。
执行 GET /api/v1/profile-defaults，即使用户未保存过预设也会返回系统默认值。
执行 PUT /api/v1/profile-defaults，可直接发送预填的美术课预设。
执行 POST /api/v1/profiles，可直接发送预填档案；保存响应中的 id。
将真实档案 id 填入 {profile_id}，测试单条查询、更新或删除。
执行 POST /api/v1/feedback-records。默认 profile_id 和 feedback_session_id 为 null，无需档案或录音即可直接创建。
如需关联档案，将第 4 步得到的 id 写入 profile_id。创建后保存反馈响应中的 id。
将真实反馈 id 填入 {record_id}，测试删除接口。

OpenAPI 中的 11111111-... 和 22222222-... 仅用于展示路径参数格式，并不是数据库预置记录。调用按 ID 查询、更新或删除的接口时，必须换成创建或列表接口返回的真实 ID。

3. 常用请求示例

健康检查

curl http://127.0.0.1:8080/health

创建学生档案

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"
  }'

创建不关联档案的反馈

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
  }'

筛选反馈记录

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`	未配置数据库连接

错误响应统一为：

{
  "error": "错误说明"
}

录音上传接口在音频入库后立即返回 processing。Rust 后台工作线程会调用 FunASR，并将片段更新为 ready 或 failed；小程序会自动刷新状态，短录音转写完成后仍会直接加入反馈正文。

6. OpenAPI 维护方式

/openapi.json 在服务运行时由 utoipa 根据 Rust 路由注解生成，Scalar 使用同一份规范。新增或修改接口时，需要同时更新处理函数上的 #[utoipa::path]、请求/响应 schema 注释和示例；规范完整性测试会检查操作数量、接口说明和默认身份参数。

4.7 KiB Raw Blame History Unescape Escape