feat: 初始提交 v1.2.0 - 钢琴练习方案生成系统

2026-04-21 20:00:33 +08:00
commit fd593bddf4
44 changed files with 10936 additions and 0 deletions
@@ -0,0 +1,556 @@
+# 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]
+}
+```
+
+---
+
+## 学员管理
+
+### 获取学员列表
+
+```
+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
+```
+
+---
+
+## 权限说明
+
+| 接口 | 管理员 | 普通用户 |
+|------|--------|----------|
+| 用户管理 | ✅ | ❌ |
+| 班级增删改 | ✅ | ❌ |
+| 班级查询/分配学员 | ✅ | ✅ |
+| 学员管理 | ✅ | ✅ |
+| 问题记录 | ✅ | ✅ |
+| 方案生成 | ✅ | ✅ |
+| 系统设置 | ✅ | ❌ |
+| 修改自己密码 | ✅ | ✅ |
+
+---
+
+## 错误响应
+
+所有接口的错误响应格式：
+
+```json
+{
+  "error": "错误信息描述"
+}
+```
+
+状态码：
+- `400` - 请求参数错误
+- `401` - 未登录或认证失败
+- `403` - 权限不足
+- `404` - 资源不存在
+- `500` - 服务器内部错误