# 教学反馈助手 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": "今天完成了色彩搭配练习，构图有明显进步。"
}
```