feat: establish Rust teaching feedback API
Add the Axum and PostgreSQL service for profiles, defaults, and feedback records, including migrations, OpenAPI documentation, and development identity handling for version 0.1.0.
This commit is contained in:
88
API.md
Normal file
88
API.md
Normal file
@@ -0,0 +1,88 @@
|
||||
# 教学反馈助手 API
|
||||
|
||||
## 交互文档
|
||||
|
||||
服务启动后提供以下文档入口:
|
||||
|
||||
- Scalar:`GET /scalar`
|
||||
- OpenAPI JSON:`GET /openapi.json`
|
||||
- 完整调用流程:[API_GUIDE.md](./API_GUIDE.md)
|
||||
|
||||
Scalar 中的业务接口已预填开发用户 ID 和请求体示例。创建、列表、预设和健康检查可以直接发起请求;按 ID 操作时,应使用创建或列表接口返回的真实 ID。
|
||||
|
||||
## 启动和数据库策略
|
||||
|
||||
本服务不会创建或启动本地 PostgreSQL。
|
||||
|
||||
- 未设置 `DATABASE_URL` 时,`cargo run` 只启动 HTTP 服务;`GET /health` 返回成功,数据接口返回 `503`。
|
||||
- 获得远程 PostgreSQL 地址后,将其写入本地未提交的 `server/.env`,执行 `cargo run --bin migrate`,再执行 `cargo run`。
|
||||
- 迁移不会使用 PostgreSQL 扩展,UUID 由 Rust 服务生成。
|
||||
|
||||
```bash
|
||||
cd server
|
||||
cp .env.example .env
|
||||
# 在 .env 中填写 DATABASE_URL
|
||||
cargo run --bin migrate
|
||||
cargo run
|
||||
```
|
||||
|
||||
## 临时身份边界
|
||||
|
||||
目前所有业务接口都要求 `X-User-Id` 请求头,值为 UUID。例如:
|
||||
|
||||
```text
|
||||
X-User-Id: 5a4da7f0-d70c-465f-bcab-124c504aa9f0
|
||||
```
|
||||
|
||||
这是微信登录接入完成前的开发身份边界,用于确保每位教师只能访问自己的记录。接入微信登录后,后端会从登录凭据解析用户身份,客户端不再直接提供此请求头。
|
||||
|
||||
## 接口
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `GET` | `/health` | 服务状态及数据库是否已配置。 |
|
||||
| `GET` | `/api/v1/profiles` | 列出学生档案;可选 `query`、`grade`、`subject` 参数。 |
|
||||
| `POST` | `/api/v1/profiles` | 创建学生档案。 |
|
||||
| `GET` | `/api/v1/profiles/{profile_id}` | 读取单个学生档案。 |
|
||||
| `PUT` | `/api/v1/profiles/{profile_id}` | 更新学生档案。 |
|
||||
| `DELETE` | `/api/v1/profiles/{profile_id}` | 删除学生档案。 |
|
||||
| `GET` | `/api/v1/profile-defaults` | 读取学生档案预设;未配置时返回美术课默认值。 |
|
||||
| `PUT` | `/api/v1/profile-defaults` | 写入年级、学科和上课时长预设。 |
|
||||
| `GET` | `/api/v1/feedback-records` | 列出反馈记录;可选 `profile_id` 参数。 |
|
||||
| `POST` | `/api/v1/feedback-records` | 创建反馈记录。 |
|
||||
| `DELETE` | `/api/v1/feedback-records/{record_id}` | 删除反馈记录。 |
|
||||
|
||||
### 创建学生档案
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "小谢",
|
||||
"grade": "艺术类",
|
||||
"subject": "美术",
|
||||
"academic_year": 2026,
|
||||
"term": "暑",
|
||||
"guardian_title": "小谢妈妈",
|
||||
"start_time": "18:00",
|
||||
"end_time": "19:00"
|
||||
}
|
||||
```
|
||||
|
||||
### 保存默认预设
|
||||
|
||||
```json
|
||||
{
|
||||
"grade": "艺术类",
|
||||
"subject": "美术",
|
||||
"lesson_duration_minutes": 60
|
||||
}
|
||||
```
|
||||
|
||||
### 创建反馈记录
|
||||
|
||||
```json
|
||||
{
|
||||
"profile_id": "5fa5af2c-cfc9-4bb8-b0b3-8715f080b167",
|
||||
"feedback_date": "2026-07-14",
|
||||
"content": "今天完成了色彩搭配练习,构图有明显进步。"
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user