piano-plan/docs/API.md

API 接口文档

基础信息

• Base URL: http://127.0.0.1:5000
• Content-Type: application/json

---

认证接口

检查登录状态

GET /api/check-login

响应示例:

{
  "logged_in": true,
  "username": "admin",
  "role": "admin"
}

登录

POST /api/login

请求体:

{
  "username": "admin",
  "password": "Admin@123"
}

响应示例:

{
  "message": "登录成功"
}

登出

POST /api/logout

初始设置（首次）

GET /setup

初始设置提交

POST /api/setup

请求体:

{
  "username": "admin",
  "password": "Admin@123",
  "confirm_password": "Admin@123"
}

修改当前用户密码

POST /api/users/change-password

请求体:

{
  "old_password": "Old@123",
  "new_password": "New@123",
  "confirm_password": "New@123"
}

---

用户管理（仅管理员）

获取用户列表

GET /api/users

响应示例:

[
  {
    "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

请求体:

{
  "username": "newuser",
  "password": "User@123",
  "role": "user"
}

角色选项: admin, user

编辑用户

PUT /api/users/<id>

请求体:

{
  "role": "user"
}

重置用户密码

POST /api/users/<id>/reset-password

请求体:

{
  "new_password": "Reset@123"
}

删除用户

DELETE /api/users/<id>

---

班级管理

获取班级列表

GET /api/classes

权限: 登录用户

响应示例:

[
  {
    "id": 1,
    "name": "钢琴初级班",
    "description": "入门学员",
    "student_count": 5,
    "created_at": "2026-04-17 10:00"
  }
]

新增班级

POST /api/classes

权限: 管理员

请求体:

{
  "name": "钢琴中级班",
  "description": "进阶学员"
}

编辑班级

PUT /api/classes/<id>

权限: 管理员

请求体:

{
  "name": "钢琴中级班（2026）",
  "description": "进阶学员"
}

删除班级

DELETE /api/classes/<id>

权限: 管理员

获取班级学员列表

GET /api/classes/<id>/students

权限: 登录用户

响应示例:

[
  {
    "id": 1,
    "name": "张三",
    "phone": "13800138000",
    "practice_time": "30分钟"
  }
]

分配学员到班级

POST /api/classes/<id>/assign

权限: 登录用户

请求体:

{
  "student_ids": [1, 2, 3]
}

---

学员管理

获取学员列表

GET /api/students

权限: 登录用户

响应示例:

[
  {
    "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

权限: 登录用户

请求体:

{
  "name": "学员姓名",
  "phone": "手机号",
  "wechat_nickname": "微信昵称",
  "practice_time": "30分钟",
  "class_id": 1,
  "notes": "备注信息"
}

获取学员详情

GET /api/students/<id>

更新学员

PUT /api/students/<id>

权限: 登录用户

请求体:

{
  "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

请求体:

{
  "problem_id": "01_手小",
  "problem_name": "手小",
  "severity": "中等",
  "level": "入门"
}

严重程度选项: 轻微, 中等, 严重

级别选项: 启蒙, 入门, 进阶, 熟练, 精通

删除问题

DELETE /api/students/<student_id>/problems/<problem_id>

---

方案生成

生成练习方案

POST /api/generate-plan

请求体:

{
  "student_id": 1,
  "use_ai": true
}

参数说明:

• student_id: 学员ID
• use_ai: 是否使用AI生成个性化报告（默认true）

响应示例:

{
  "plan_id": 1,
  "ai_report": "## 个性化练习方案报告\n\n..."
}

获取方案详情

GET /api/plans/<plan_id>

响应示例:

{
  "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

---

权限说明

接口	管理员	普通用户
用户管理	✅	❌
班级增删改	✅	❌
班级查询/分配学员	✅	✅
学员管理	✅	✅
问题记录	✅	✅
方案生成	✅	✅
系统设置	✅	❌
修改自己密码	✅	✅

---

错误响应

所有接口的错误响应格式：

{
  "error": "错误信息描述"
}

状态码：

• 400 - 请求参数错误
• 401 - 未登录或认证失败
• 403 - 权限不足
• 404 - 资源不存在
• 500 - 服务器内部错误