AI/teaching-feedback-assistant
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add WeChat session authentication

Browse Source
This commit is contained in:
shay7sev
2026-07-20 14:47:16 +08:00
parent 2ada52f35a
commit 67d29d3ca0
26 changed files with 1289 additions and 130 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
server/API_GUIDE.md
View File

@@ -8,7 +8,7 @@
docker compose -f compose.asr.yml up --build -d
```
在 `server/.env` 中配置 `DATABASE_URL` 后执行：
在 `server/.env` 中配置 `DATABASE_URL`、`WECHAT_APP_ID` 和 `WECHAT_APP_SECRET` 后执行：
```bash
cd server
@@ -26,12 +26,14 @@ cargo run
## 2. 在 Scalar 中直接测试
打开 `/scalar`，选择接口后点击 **Test Request**。业务接口已经预填以下开发用户 ID：
打开 `/scalar`，选择接口后点击 **Test Request**。除登录和健康检查外，业务接口需要填写：
```text
X-User-Id: 5a4da7f0-d70c-465f-bcab-124c504aa9f0
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`。
@@ -58,7 +60,7 @@ 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' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-d '{
"name": "小谢",
"grade": "艺术类",
@@ -76,7 +78,7 @@ curl -X POST http://127.0.0.1:8080/api/v1/profiles \
```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' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-d '{
"profile_id": null,
"feedback_date": "2026-07-15",
@@ -89,16 +91,16 @@ curl -X POST http://127.0.0.1:8080/api/v1/feedback-records \
```bash
curl 'http://127.0.0.1:8080/api/v1/feedback-records?profile_id=<真实档案ID>' \
-H 'X-User-Id: 5a4da7f0-d70c-465f-bcab-124c504aa9f0'
-H "Authorization: Bearer $ACCESS_TOKEN"
```
## 4. 身份和数据隔离
当前尚未接入微信登录，所有业务接口临时使用 `X-User-Id` 标识用户。相同 UUID 可以访问自己创建的数据，不同 UUID 之间的数据互相不可见。
微信 `openid` 只用于后端映射内部教师 UUID，客户端不能直接提交 `openid` 或 `user_id`。随机 access token 只在登录响应中返回，数据库仅保存哈希。
`X-User-Id` 缺失时返回 `401`，格式不是 UUID 时返回 `400`。接入微信登录后，应由后端根据登录凭据确定用户身份，客户端不再直接提交该请求头。
Bearer 会话不存在、过期或已撤销时返回 `401`，小程序会重新调用 `wx.login` 并重试原请求一次。本地接口测试可显式设置 `ALLOW_DEVELOPMENT_USER_HEADER=true` 使用旧开发头；生产必须保持 `false`。
小程序开发客户端当前使用同一个测试 UUID，并默认连接 `https://feedback.shay7sev.site`。可在小程序“我的”页面修改 API 地址并执行健康检查；本地 API 调试时使用 `http://127.0.0.1:8080`。微信公众平台需将生产域名同时配置为 `request` 和 `uploadFile` 合法域名。
小程序默认连接 `https://feedback.shay7sev.site`，并在“我的”页面显示微信登录状态和内部教师 ID。本地 API 调试时使用 `http://127.0.0.1:8080`。微信公众平台需将生产域名同时配置为 `request` 和 `uploadFile` 合法域名。
## 5. 响应状态码
@@ -108,7 +110,8 @@ curl 'http://127.0.0.1:8080/api/v1/feedback-records?profile_id=<真实档案ID>'
| `201` | 创建成功 |
| `204` | 删除成功，无响应体 |
| `400` | 参数格式或业务校验失败 |
| `401` | 缺少 `X-User-Id` |
| `401` | 登录 code 或 Bearer 会话无效 |
| `502` | 微信登录上游暂时不可用 |
| `404` | 记录不存在或不属于当前用户 |
| `500` | 数据库查询或服务内部错误 |
| `503` | 未配置数据库连接 |
@@ -125,4 +128,4 @@ curl 'http://127.0.0.1:8080/api/v1/feedback-records?profile_id=<真实档案ID>'
## 6. OpenAPI 维护方式
`/openapi.json` 在服务运行时由 `utoipa` 根据 Rust 路由注解生成，Scalar 使用同一份规范。新增或修改接口时，需要同时更新处理函数上的 `#[utoipa::path]`、请求/响应 schema 注释和示例；规范完整性测试会检查操作数量、接口说明和默认身份参数。
`/openapi.json` 在服务运行时由 `utoipa` 根据 Rust 路由注解生成，Scalar 使用同一份规范。新增或修改接口时，需要同时更新处理函数上的 `#[utoipa::path]`、请求/响应 schema 注释和示例；规范完整性测试会检查操作数量、接口说明和 Bearer 身份参数。