729 lines
9.8 KiB
Markdown
729 lines
9.8 KiB
Markdown
# API 接口文档
|
||
|
||
## 基础信息
|
||
|
||
- **Base URL**: `http://127.0.0.1:5000`
|
||
- **Content-Type**: `application/json`
|
||
|
||
---
|
||
|
||
## 认证接口
|
||
|
||
### 检查登录状态
|
||
|
||
```
|
||
GET /api/check-login
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"logged_in": true,
|
||
"username": "admin",
|
||
"role": "admin"
|
||
}
|
||
```
|
||
|
||
### 登录
|
||
|
||
```
|
||
POST /api/login
|
||
```
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"username": "admin",
|
||
"password": "Admin@123"
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"message": "登录成功"
|
||
}
|
||
```
|
||
|
||
### 登出
|
||
|
||
```
|
||
POST /api/logout
|
||
```
|
||
|
||
### 初始设置（首次）
|
||
|
||
```
|
||
GET /setup
|
||
```
|
||
|
||
### 初始设置提交
|
||
|
||
```
|
||
POST /api/setup
|
||
```
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"username": "admin",
|
||
"password": "Admin@123",
|
||
"confirm_password": "Admin@123"
|
||
}
|
||
```
|
||
|
||
### 修改当前用户密码
|
||
|
||
```
|
||
POST /api/users/change-password
|
||
```
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"old_password": "Old@123",
|
||
"new_password": "New@123",
|
||
"confirm_password": "New@123"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 用户管理（仅管理员）
|
||
|
||
### 获取用户列表
|
||
|
||
```
|
||
GET /api/users
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
[
|
||
{
|
||
"id": 1,
|
||
"username": "admin",
|
||
"role": "admin",
|
||
"created_at": "2026-04-17 10:00"
|
||
},
|
||
{
|
||
"id": 2,
|
||
"username": "teacher1",
|
||
"role": "user",
|
||
"created_at": "2026-04-18 10:00"
|
||
}
|
||
]
|
||
```
|
||
|
||
### 新增用户
|
||
|
||
```
|
||
POST /api/users
|
||
```
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"username": "newuser",
|
||
"password": "User@123",
|
||
"role": "user"
|
||
}
|
||
```
|
||
|
||
**角色选项**: `admin`, `user`
|
||
|
||
### 编辑用户
|
||
|
||
```
|
||
PUT /api/users/<id>
|
||
```
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"role": "user"
|
||
}
|
||
```
|
||
|
||
### 重置用户密码
|
||
|
||
```
|
||
POST /api/users/<id>/reset-password
|
||
```
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"new_password": "Reset@123"
|
||
}
|
||
```
|
||
|
||
### 删除用户
|
||
|
||
```
|
||
DELETE /api/users/<id>
|
||
```
|
||
|
||
---
|
||
|
||
## 班级管理
|
||
|
||
### 获取班级列表
|
||
|
||
```
|
||
GET /api/classes
|
||
```
|
||
|
||
**权限**: 登录用户
|
||
|
||
**响应示例**:
|
||
```json
|
||
[
|
||
{
|
||
"id": 1,
|
||
"name": "钢琴初级班",
|
||
"description": "入门学员",
|
||
"student_count": 5,
|
||
"created_at": "2026-04-17 10:00"
|
||
}
|
||
]
|
||
```
|
||
|
||
### 新增班级
|
||
|
||
```
|
||
POST /api/classes
|
||
```
|
||
|
||
**权限**: 管理员
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"name": "钢琴中级班",
|
||
"description": "进阶学员"
|
||
}
|
||
```
|
||
|
||
### 编辑班级
|
||
|
||
```
|
||
PUT /api/classes/<id>
|
||
```
|
||
|
||
**权限**: 管理员
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"name": "钢琴中级班（2026）",
|
||
"description": "进阶学员"
|
||
}
|
||
```
|
||
|
||
### 删除班级
|
||
|
||
```
|
||
DELETE /api/classes/<id>
|
||
```
|
||
|
||
**权限**: 管理员
|
||
|
||
### 获取班级学员列表
|
||
|
||
```
|
||
GET /api/classes/<id>/students
|
||
```
|
||
|
||
**权限**: 登录用户
|
||
|
||
**响应示例**:
|
||
```json
|
||
[
|
||
{
|
||
"id": 1,
|
||
"name": "张三",
|
||
"phone": "13800138000",
|
||
"practice_time": "30分钟"
|
||
}
|
||
]
|
||
```
|
||
|
||
### 分配学员到班级
|
||
|
||
```
|
||
POST /api/classes/<id>/assign
|
||
```
|
||
|
||
**权限**: 登录用户
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"student_ids": [1, 2, 3]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 批量分配目标给班级学员
|
||
|
||
```
|
||
POST /api/classes/<id>/goals
|
||
```
|
||
|
||
**权限**: 登录用户
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"goal_id": 1,
|
||
"assessment_days": "30",
|
||
"assessment_date": null,
|
||
"start_date": null,
|
||
"start_now": true
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| goal_id | int | 是 | 目标ID |
|
||
| assessment_days | string | 否 | 评估天数（15/30/60/90/180） |
|
||
| assessment_date | string | 否 | 评估日期（YYYY-MM-DD），与 assessment_days 二选一 |
|
||
| start_date | string | 否 | 开始日期（YYYY-MM-DD） |
|
||
| start_now | bool | 否 | 是否立即开始（默认true） |
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"message": "成功分配 5 个学员",
|
||
"assigned": 5,
|
||
"skipped": ["李四", "王五"],
|
||
"skipped_count": 2
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 学员管理
|
||
|
||
### 获取学员列表
|
||
|
||
```
|
||
GET /api/students
|
||
```
|
||
|
||
**权限**: 登录用户
|
||
|
||
**响应示例**:
|
||
```json
|
||
[
|
||
{
|
||
"id": 1,
|
||
"name": "张三",
|
||
"phone": "13800138000",
|
||
"wechat_nickname": "小张",
|
||
"practice_time": "30分钟",
|
||
"class_id": 1,
|
||
"class_name": "钢琴初级班",
|
||
"notes": "",
|
||
"problem_count": 2,
|
||
"plan_count": 1,
|
||
"created_at": "2026-04-17 10:00"
|
||
}
|
||
]
|
||
```
|
||
|
||
### 创建学员
|
||
|
||
```
|
||
POST /api/students
|
||
```
|
||
|
||
**权限**: 登录用户
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"name": "学员姓名",
|
||
"phone": "手机号",
|
||
"wechat_nickname": "微信昵称",
|
||
"practice_time": "30分钟",
|
||
"class_id": 1,
|
||
"notes": "备注信息"
|
||
}
|
||
```
|
||
|
||
### 获取学员详情
|
||
|
||
```
|
||
GET /api/students/<id>
|
||
```
|
||
|
||
### 更新学员
|
||
|
||
```
|
||
PUT /api/students/<id>
|
||
```
|
||
|
||
**权限**: 登录用户
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"name": "新姓名",
|
||
"phone": "新手机号",
|
||
"wechat_nickname": "新昵称",
|
||
"practice_time": "45分钟",
|
||
"class_id": 2,
|
||
"notes": "新备注"
|
||
}
|
||
```
|
||
|
||
### 删除学员
|
||
|
||
```
|
||
DELETE /api/students/<id>
|
||
```
|
||
|
||
---
|
||
|
||
## 问题记录
|
||
|
||
### 获取学员的问题列表
|
||
|
||
```
|
||
GET /api/students/<student_id>/problems
|
||
```
|
||
|
||
### 添加问题
|
||
|
||
```
|
||
POST /api/students/<student_id>/problems
|
||
```
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"problem_id": "01_手小",
|
||
"problem_name": "手小",
|
||
"severity": "中等",
|
||
"level": "入门"
|
||
}
|
||
```
|
||
|
||
**严重程度选项**: `轻微`, `中等`, `严重`
|
||
|
||
**级别选项**: `启蒙`, `入门`, `进阶`, `熟练`, `精通`
|
||
|
||
### 删除问题
|
||
|
||
```
|
||
DELETE /api/students/<student_id>/problems/<problem_id>
|
||
```
|
||
|
||
---
|
||
|
||
## 方案生成
|
||
|
||
### 生成练习方案
|
||
|
||
```
|
||
POST /api/generate-plan
|
||
```
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"student_id": 1,
|
||
"use_ai": true
|
||
}
|
||
```
|
||
|
||
**参数说明**:
|
||
- `student_id`: 学员ID
|
||
- `use_ai`: 是否使用AI生成个性化报告（默认true）
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"plan_id": 1,
|
||
"ai_report": "## 个性化练习方案报告\n\n..."
|
||
}
|
||
```
|
||
|
||
### 获取方案详情
|
||
|
||
```
|
||
GET /api/plans/<plan_id>
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"student_id": 1,
|
||
"student_name": "张三",
|
||
"created_at": "2026-04-17 10:30",
|
||
"content": {
|
||
"student_name": "张三",
|
||
"practice_time": "30分钟",
|
||
"total_daily_minutes": 30,
|
||
"problems": [...],
|
||
"daily_schedule": [...],
|
||
"ai_report": "..."
|
||
}
|
||
}
|
||
```
|
||
|
||
### 获取学员的方案列表
|
||
|
||
```
|
||
GET /api/students/<student_id>/plans
|
||
```
|
||
|
||
### 导出PDF
|
||
|
||
```
|
||
GET /api/plans/<plan_id>/pdf
|
||
```
|
||
|
||
**返回**: PDF文件下载
|
||
|
||
### 微信卡片展示
|
||
|
||
```
|
||
GET /plans/<plan_id>/wechat
|
||
```
|
||
|
||
**返回**: HTML页面，用于微信分享
|
||
|
||
### 删除方案
|
||
|
||
```
|
||
DELETE /api/plans/<plan_id>
|
||
```
|
||
|
||
---
|
||
|
||
## 问题配置（仅管理员）
|
||
|
||
### 获取问题列表
|
||
|
||
```
|
||
GET /api/problems
|
||
```
|
||
|
||
### 获取问题详情
|
||
|
||
```
|
||
GET /api/problems/<problem_id>
|
||
```
|
||
|
||
### 创建问题
|
||
|
||
```
|
||
POST /api/problems
|
||
```
|
||
|
||
### 更新问题
|
||
|
||
```
|
||
PUT /api/problems/<problem_id>
|
||
```
|
||
|
||
### 删除问题
|
||
|
||
```
|
||
DELETE /api/problems/<problem_id>
|
||
```
|
||
|
||
---
|
||
|
||
## API设置（仅管理员）
|
||
|
||
### 获取API配置
|
||
|
||
```
|
||
GET /api/config
|
||
```
|
||
|
||
### 更新API配置
|
||
|
||
```
|
||
POST /api/config
|
||
```
|
||
|
||
### 测试API连接
|
||
|
||
```
|
||
POST /api/config/test
|
||
```
|
||
|
||
---
|
||
|
||
## 目标管理 API
|
||
|
||
### GET /api/goals
|
||
获取所有目标
|
||
|
||
**响应**：
|
||
```json
|
||
[
|
||
{
|
||
"id": 1,
|
||
"name": "掌握基本音阶",
|
||
"content": "...",
|
||
"created_at": "2026-04-23T10:00:00",
|
||
"updated_at": "2026-04-23T10:00:00"
|
||
}
|
||
]
|
||
```
|
||
|
||
### POST /api/goals
|
||
创建新目标
|
||
|
||
**请求体**：
|
||
```json
|
||
{
|
||
"name": "目标名称",
|
||
"content": "目标内容（Markdown）"
|
||
}
|
||
```
|
||
|
||
### GET /api/goals/{id}
|
||
获取单个目标
|
||
|
||
### PUT /api/goals/{id}
|
||
更新目标
|
||
|
||
### DELETE /api/goals/{id}
|
||
删除目标
|
||
|
||
### GET /api/goals/{id}/children
|
||
获取目标的子目标
|
||
|
||
### GET /api/goals/{id}/parents
|
||
获取目标的父目标
|
||
|
||
### POST /api/goals/{id}/children
|
||
添加子目标关联（含循环检测）
|
||
|
||
**请求体**：
|
||
```json
|
||
{
|
||
"child_goal_id": 2
|
||
}
|
||
```
|
||
|
||
### DELETE /api/goals/{id}/children/{child_id}
|
||
移除子目标关联
|
||
|
||
## 学员目标 API
|
||
|
||
### GET /api/students/{id}/goals
|
||
获取学员的所有目标
|
||
|
||
**响应**：
|
||
```json
|
||
[
|
||
{
|
||
"id": 1,
|
||
"student_id": 1,
|
||
"goal_id": 1,
|
||
"goal_name": "掌握基本音阶",
|
||
"goal_level": "入门",
|
||
"goal_category": "演奏能力",
|
||
"status": "进行中",
|
||
"start_date": "2026-04-01T00:00:00",
|
||
"assessment_date": "2026-05-01T00:00:00",
|
||
"mastery_level": 3,
|
||
"achievement_date": null,
|
||
"comment": null,
|
||
"created_at": "2026-04-01T10:00:00"
|
||
}
|
||
]
|
||
```
|
||
|
||
**排序**：按状态（进行中→未开始→已结束），再按评估日期倒序
|
||
|
||
### POST /api/students/{id}/goals
|
||
为学员分配目标
|
||
|
||
**请求体**：
|
||
```json
|
||
{
|
||
"goal_id": 1,
|
||
"assessment_days": 30,
|
||
"assessment_date": "2026-05-01",
|
||
"start_date": "2026-04-01",
|
||
"start_now": true
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| goal_id | Integer | 目标ID，必填 |
|
||
| assessment_days | Integer | 评估天数（15/30/60/90/180），与 assessment_date 二选一 |
|
||
| assessment_date | String | 具体评估日期（ISO格式），与 assessment_days 二选一 |
|
||
| start_date | String | 开始日期（ISO格式），可选 |
|
||
| start_now | Boolean | 设为 true 表示立即开始（默认当前时间） |
|
||
|
||
### PUT /api/students/{id}/goals/{goal_id}
|
||
更新学员目标
|
||
|
||
**请求体**：
|
||
```json
|
||
{
|
||
"start_date": "2026-04-01",
|
||
"assessment_date": "2026-05-01",
|
||
"mastery_level": 4,
|
||
"achievement_date": "2026-05-01",
|
||
"comment": "表现优秀，已掌握"
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| start_date | String | 开始日期（ISO格式） |
|
||
| assessment_date | String | 评估日期（ISO格式） |
|
||
| mastery_level | Integer | 掌握程度 1-5 |
|
||
| achievement_date | String | 达成日期（ISO格式） |
|
||
| comment | String | 评语 |
|
||
|
||
### DELETE /api/students/{id}/goals/{goal_id}
|
||
移除学员的目标
|
||
|
||
---
|
||
|
||
## 权限说明
|
||
|
||
| 接口 | 管理员 | 普通用户 |
|
||
|------|--------|----------|
|
||
| 用户管理 | ✅ | ❌ |
|
||
| 班级增删改 | ✅ | ❌ |
|
||
| 班级查询/分配学员 | ✅ | ✅ |
|
||
| 学员管理 | ✅ | ✅ |
|
||
| 问题记录 | ✅ | ✅ |
|
||
| 方案生成 | ✅ | ✅ |
|
||
| 系统设置 | ✅ | ❌ |
|
||
| 修改自己密码 | ✅ | ✅ |
|
||
|
||
---
|
||
|
||
## 错误响应
|
||
|
||
所有接口的错误响应格式：
|
||
|
||
```json
|
||
{
|
||
"error": "错误信息描述"
|
||
}
|
||
```
|
||
|
||
状态码：
|
||
- `400` - 请求参数错误
|
||
- `401` - 未登录或认证失败
|
||
- `403` - 权限不足
|
||
- `404` - 资源不存在
|
||
- `500` - 服务器内部错误 |