# 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/ ``` **请求体**: ```json { "role": "user" } ``` ### 重置用户密码 ``` POST /api/users//reset-password ``` **请求体**: ```json { "new_password": "Reset@123" } ``` ### 删除用户 ``` DELETE /api/users/ ``` --- ## 班级管理 ### 获取班级列表 ``` 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/ ``` **权限**: 管理员 **请求体**: ```json { "name": "钢琴中级班（2026）", "description": "进阶学员" } ``` ### 删除班级 ``` DELETE /api/classes/ ``` **权限**: 管理员 ### 获取班级学员列表 ``` GET /api/classes//students ``` **权限**: 登录用户 **响应示例**: ```json [ { "id": 1, "name": "张三", "phone": "13800138000", "practice_time": "30分钟" } ] ``` ### 分配学员到班级 ``` POST /api/classes//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/ ``` ### 更新学员 ``` PUT /api/students/ ``` **权限**: 登录用户 **请求体**: ```json { "name": "新姓名", "phone": "新手机号", "wechat_nickname": "新昵称", "practice_time": "45分钟", "class_id": 2, "notes": "新备注" } ``` ### 删除学员 ``` DELETE /api/students/ ``` --- ## 问题记录 ### 获取学员的问题列表 ``` GET /api/students//problems ``` ### 添加问题 ``` POST /api/students//problems ``` **请求体**: ```json { "problem_id": "01_手小", "problem_name": "手小", "severity": "中等", "level": "入门" } ``` **严重程度选项**: `轻微`, `中等`, `严重` **级别选项**: `启蒙`, `入门`, `进阶`, `熟练`, `精通` ### 删除问题 ``` DELETE /api/students//problems/ ``` --- ## 方案生成 ### 生成练习方案 ``` 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/ ``` **响应示例**: ```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//plans ``` ### 导出PDF ``` GET /api/plans//pdf ``` **返回**: PDF文件下载 ### 微信卡片展示 ``` GET /plans//wechat ``` **返回**: HTML页面，用于微信分享 ### 删除方案 ``` DELETE /api/plans/ ``` --- ## 问题配置（仅管理员） ### 获取问题列表 ``` GET /api/problems ``` ### 获取问题详情 ``` GET /api/problems/ ``` ### 创建问题 ``` POST /api/problems ``` ### 更新问题 ``` PUT /api/problems/ ``` ### 删除问题 ``` DELETE /api/problems/ ``` --- ## API设置（仅管理员） ### 获取API配置 ``` GET /api/config ``` ### 更新API配置 ``` POST /api/config ``` ### 测试API连接 ``` POST /api/config/test ``` --- ## 权限说明 | 接口 | 管理员 | 普通用户 | |------|--------|----------| | 用户管理 | ✅ | ❌ | | 班级增删改 | ✅ | ❌ | | 班级查询/分配学员 | ✅ | ✅ | | 学员管理 | ✅ | ✅ | | 问题记录 | ✅ | ✅ | | 方案生成 | ✅ | ✅ | | 系统设置 | ✅ | ❌ | | 修改自己密码 | ✅ | ✅ | --- ## 错误响应 所有接口的错误响应格式： ```json { "error": "错误信息描述" } ``` 状态码： - `400` - 请求参数错误 - `401` - 未登录或认证失败 - `403` - 权限不足 - `404` - 资源不存在 - `500` - 服务器内部错误