132 lines
5.0 KiB
Markdown
132 lines
5.0 KiB
Markdown
# 教学反馈助手 API 使用指南
|
||
|
||
## 1. 启动服务
|
||
|
||
先在项目根目录启动中文转录服务：
|
||
|
||
```bash
|
||
docker compose -f compose.asr.yml up --build -d
|
||
```
|
||
|
||
在 `server/.env` 中配置 `DATABASE_URL`、`WECHAT_APP_ID` 和 `WECHAT_APP_SECRET` 后执行：
|
||
|
||
```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**。除登录和健康检查外，业务接口需要填写：
|
||
|
||
```text
|
||
Authorization: Bearer <access-token>
|
||
```
|
||
|
||
access token 由小程序 `wx.login` code 调用 `POST /api/v1/auth/wechat/login` 获得。code 一次性且有效时间短，AppSecret 不得放入 Scalar、小程序或命令行历史。
|
||
|
||
请求体接口也已提供可发送的默认 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 "Authorization: Bearer $ACCESS_TOKEN" \
|
||
-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 "Authorization: Bearer $ACCESS_TOKEN" \
|
||
-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 "Authorization: Bearer $ACCESS_TOKEN"
|
||
```
|
||
|
||
## 4. 身份和数据隔离
|
||
|
||
微信 `openid` 只用于后端映射内部教师 UUID，客户端不能直接提交 `openid` 或 `user_id`。随机 access token 只在登录响应中返回，数据库仅保存哈希。
|
||
|
||
Bearer 会话不存在、过期或已撤销时返回 `401`，小程序会重新调用 `wx.login` 并重试原请求一次。本地接口测试可显式设置 `ALLOW_DEVELOPMENT_USER_HEADER=true` 使用旧开发头；生产必须保持 `false`。
|
||
|
||
小程序默认连接 `https://feedback.shay7sev.site`，并在“我的”页面显示微信登录状态和内部教师 ID。本地 API 调试时使用 `http://127.0.0.1:8080`。微信公众平台需将生产域名同时配置为 `request` 和 `uploadFile` 合法域名。
|
||
|
||
## 5. 响应状态码
|
||
|
||
| 状态码 | 含义 |
|
||
| --- | --- |
|
||
| `200` | 查询或更新成功 |
|
||
| `201` | 创建成功 |
|
||
| `204` | 删除成功，无响应体 |
|
||
| `400` | 参数格式或业务校验失败 |
|
||
| `401` | 登录 code 或 Bearer 会话无效 |
|
||
| `502` | 微信登录上游暂时不可用 |
|
||
| `404` | 记录不存在或不属于当前用户 |
|
||
| `500` | 数据库查询或服务内部错误 |
|
||
| `503` | 未配置数据库连接 |
|
||
|
||
错误响应统一为：
|
||
|
||
```json
|
||
{
|
||
"error": "错误说明"
|
||
}
|
||
```
|
||
|
||
录音上传接口在音频入库后立即返回 `processing`。Rust 后台工作线程会调用 FunASR，并将片段更新为 `ready` 或 `failed`；小程序会自动刷新状态，短录音转写完成后仍会直接加入反馈正文。
|
||
|
||
## 6. OpenAPI 维护方式
|
||
|
||
`/openapi.json` 在服务运行时由 `utoipa` 根据 Rust 路由注解生成，Scalar 使用同一份规范。新增或修改接口时，需要同时更新处理函数上的 `#[utoipa::path]`、请求/响应 schema 注释和示例；规范完整性测试会检查操作数量、接口说明和 Bearer 身份参数。
|