hmo/piano-plan
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ad621d9426efdc8ed61cb563a151321887e9bc91
piano-plan/docs/API.md
T

9.8 KiB
Raw Blame History

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]
}

批量分配目标给班级学员

POST /api/classes/<id>/goals

权限: 登录用户

请求体:

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

响应示例:

{
  "message": "成功分配 5 个学员",
  "assigned": 5,
  "skipped": ["李四", "王五"],
  "skipped_count": 2
}

学员管理

获取学员列表

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

目标管理 API

GET /api/goals

获取所有目标

响应：

[
  {
    "id": 1,
    "name": "掌握基本音阶",
    "content": "...",
    "created_at": "2026-04-23T10:00:00",
    "updated_at": "2026-04-23T10:00:00"
  }
]

POST /api/goals

创建新目标

请求体：

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

添加子目标关联（含循环检测）

请求体：

{
  "child_goal_id": 2
}

DELETE /api/goals/{id}/children/{child_id}

移除子目标关联

学员目标 API

GET /api/students/{id}/goals

获取学员的所有目标

响应：

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

为学员分配目标

请求体：

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

更新学员目标

请求体：

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

移除学员的目标

权限说明

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

错误响应

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

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

状态码：

  • 400 - 请求参数错误
  • 401 - 未登录或认证失败
  • 403 - 权限不足
  • 404 - 资源不存在
  • 500 - 服务器内部错误
Reference in New Issue View Git Blame Copy Permalink