hmo/piano-plan
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

更新：models/routes/services/templates/docs

Browse Source
This commit is contained in:
hmo
2026-04-26 18:02:36 +08:00
parent f7a82ac48a
commit 6abdd49c04
31 changed files with 1480 additions and 676 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/API.md
+309 -17
View File
@@ -103,12 +103,14 @@ GET /api/users
{
"id": 1,
"username": "admin",
"name": "管理员",
"role": "admin",
"created_at": "2026-04-17 10:00"
},
{
"id": 2,
"username": "teacher1",
"name": "张老师",
"role": "user",
"created_at": "2026-04-18 10:00"
}
@@ -141,10 +143,13 @@ PUT /api/users/<id>
**请求体**:
```json
{
"name": "新姓名",
"role": "user"
}
```
> ⚠️ `username` 不可修改，密码通过单独接口修改
### 重置用户密码
```
@@ -182,8 +187,12 @@ GET /api/classes
{
"id": 1,
"name": "钢琴初级班",
"level": "入门",
"description": "入门学员",
"teacher_id": 2,
"teacher_name": "张老师",
"student_count": 5,
"active": true,
"created_at": "2026-04-17 10:00"
}
]
@@ -201,7 +210,9 @@ POST /api/classes
```json
{
"name": "钢琴中级班",
"description": "进阶学员"
"level": "入门",
"description": "进阶学员",
"teacher_id": 2
}
```
@@ -217,7 +228,10 @@ PUT /api/classes/<id>
```json
{
"name": "钢琴中级班（2026）",
"description": "进阶学员"
"level": "入门",
"description": "进阶学员",
"teacher_id": 2,
"active": true
}
```
@@ -436,22 +450,91 @@ POST /api/generate-plan
```json
{
"student_id": 1,
"use_ai": true
"use_ai": true,
"template_id": 1
}
```
**参数说明**:
- `student_id`: 学员ID
- `use_ai`: 是否使用AI生成个性化报告（默认true）
- `template_id`: AI提示词模板ID（可选，不传则使用排序第一的默认模板）
**AI提示词模板参数**:
| 参数 | 说明 |
|------|------|
| `{student_name}` | 学员姓名 |
| `{practice_time}` | 每日练习时间 |
| `{problems}` | 学员问题列表（含严重程度、级别、建议练习时间） |
| `{student_goals}` | 学员未达成的目标内容（Markdown格式） |
| `{schedule_table}` | ~~每日练习安排表~~（已废弃，AI报告已包含） |
**响应**: SSE 流，包含进度信息
**SSE 事件说明**:
| step | 说明 |
|------|------|
| collecting | 收集问题数据 |
| basic | 生成基础练习方案 |
| basic_done | 基础方案生成完成 |
| ai_config | AI配置信息 |
| ai_start | 开始调用AI |
| ai_problems | 发送给AI的问题摘要 |
| ai_request | 等待AI响应 |
| ai_prompt | AI提示词已生成（含字数） |
| ai_generating | AI报告生成中 |
| ai_response | AI响应已接收 |
| ai_done | AI报告生成完成 |
| saved | 方案已保存 |
| complete | 全部完成 |
**complete 事件包含**:
```json
{
"step": "complete",
"prompt_length": 1234,
"ai_report_length": 567,
"plan_id": 1
}
```
---
### 预览提示词
```
POST /api/generate-plan/preview
```
**功能**: 根据学员ID和模板生成提示词，但不保存方案。用于在生成前预览提示词内容。
**请求体**:
```json
{
"student_id": 1,
"template_id": 1
}
```
**响应示例**:
```json
{
"plan_id": 1,
"ai_report": "## 个性化练习方案报告\n\n..."
"prompt": "根据学员张三的每日练习时间30分钟和以下问题，为其生成个性化练习方案...\n\n问题列表：\n1. 手小（中等）\n...",
"prompt_length": 1234,
"student_goals_length": 200,
"problems_length": 150
}
```
**SSE 事件说明**:
| step | 说明 |
|------|------|
| collecting | 收集数据 |
| prompt_generated | 提示词已生成（含字数统计） |
| complete | 预览完成 |
---
### 获取方案详情
```
@@ -464,32 +547,80 @@ GET /api/plans/<plan_id>
"id": 1,
"student_id": 1,
"student_name": "张三",
"is_typical": false,
"created_at": "2026-04-17 10:30",
"content": {
"student_name": "张三",
"practice_time": "30分钟",
"total_daily_minutes": 30,
"problems": [...],
"daily_schedule": [...],
"problems": [
{"name": "手小", "level": "入门", "severity": "中等"}
],
"ai_report": "..."
}
}
```
### 获取学员的方案列表
---
### 获取学员方案列表
```
GET /api/students/<student_id>/plans
```
---
### 设为典型方案
```
POST /api/plans/<plan_id>/typical
```
**响应**:
```json
{
"success": true,
"is_typical": true
}
```
---
### 删除方案
```
DELETE /api/plans/<plan_id>
```
}
```
### 导出PDF
```
GET /api/plans/<plan_id>/pdf
```
**参数**:
| 参数 | 类型 | 说明 |
|------|------|------|
| template_id | int | 报告模板ID（可选，不传则使用排序第一的默认模板） |
**返回**: PDF文件下载
### 导出Markdown
```
GET /api/plans/<plan_id>/md
```
**参数**:
| 参数 | 类型 | 说明 |
|------|------|------|
| template_id | int | 报告模板ID（可选，不传则使用排序第一的默认模板） |
**返回**: Markdown文件下载
### 微信卡片展示
```
@@ -498,12 +629,6 @@ GET /plans/<plan_id>/wechat
**返回**: HTML页面，用于微信分享
### 删除方案
```
DELETE /api/plans/<plan_id>
```
---
## 问题配置（仅管理员）
@@ -598,7 +723,18 @@ POST /api/config/test
更新目标
### DELETE /api/goals/{id}
删除目标
删除目标（仅管理员）
**权限**: 仅管理员
**依赖检查**：如果存在以下依赖关系，禁止删除：
- 已被学员分配的目标
- 作为父目标或子目标被其他目标关联
**错误响应示例**:
```json
{"error": "无法删除：已被 3 名学员分配, 有 2 个子目标关联"}
```
### GET /api/goals/{id}/children
获取目标的子目标
@@ -632,6 +768,7 @@ POST /api/config/test
"student_id": 1,
"goal_id": 1,
"goal_name": "掌握基本音阶",
"goal_content": "目标详细描述内容（Markdown）...",
"goal_level": "入门",
"goal_category": "演奏能力",
"status": "进行中",
@@ -692,7 +829,161 @@ POST /api/config/test
| comment | String | 评语 |
### DELETE /api/students/{id}/goals/{goal_id}
移除学员的目标
移除学员的目标（仅管理员，会级联删除关联的评估记录）
**权限**: 仅管理员
---
## 学员目标评估 API
### GET /api/students/{id}/evaluations
获取学员的所有评估记录
**响应**：
```json
[
{
"id": 1,
"student_goal_id": 1,
"goal_name": "掌握基本音阶",
"evaluator_id": 1,
"evaluator_name": "管理员",
"assessment_date": "2026-04-15",
"mastery_level": 3,
"comment": "进步明显",
"is_final": false,
"created_at": "2026-04-15T10:00:00"
}
]
```
### POST /api/students/{id}/evaluations
创建评估记录
**请求体**：
```json
{
"student_goal_id": 1,
"assessment_date": "2026-04-15",
"mastery_level": 3,
"comment": "进步明显",
"is_final": false
}
```
| 字段 | 类型 | 说明 |
|------|------|------|
| student_goal_id | Integer | 学员目标ID |
| assessment_date | String | 评估日期（YYYY-MM-DD） |
| mastery_level | Integer | 掌握程度 1-5 |
| comment | String | 评语 |
| is_final | Boolean | 是否为最终评估 |
### PUT /api/evaluations/{id}
更新评估记录
**请求体**：
```json
{
"assessment_date": "2026-04-16",
"mastery_level": 4,
"comment": "已完全掌握",
"is_final": true
}
```
### DELETE /api/evaluations/{id}
删除评估记录
---
## 模板管理 API
### GET /templates/templates
获取所有模板（按sort_order排序）
**参数**:
| 参数 | 类型 | 说明 |
|------|------|------|
| type | string | 可选，按类型筛选（`ai_prompt`/`report`） |
**响应**：
```json
[
{
"id": 1,
"name": "AI提示词模板",
"type": "ai_prompt",
"description": "生成练习方案时发送给AI的提示词",
"content": "...",
"sort_order": 0,
"created_at": "2026-04-23T10:00:00"
},
{
"id": 2,
"name": "报告导出模板",
"type": "report",
"description": "导出方案时使用的Markdown模板",
"content": "...",
"sort_order": 0,
"created_at": "2026-04-23T10:00:00"
}
]
```
### GET /templates/templates/{id}
获取单个模板
### POST /templates/templates
创建模板
**请求体**：
```json
{
"name": "新模板名称",
"type": "ai_prompt",
"content": "模板内容...",
"description": "模板描述",
"sort_order": 1
}
```
| 字段 | 类型 | 说明 |
|------|------|------|
| name | String | 模板名称 |
| type | String | 类型：`ai_prompt`（AI提示词）或 `report`（报告导出） |
| content | String | 模板内容（Markdown格式） |
| description | String | 描述 |
| sort_order | Integer | 排序序号（越小越靠前） |
### PUT /templates/templates/{id}
更新模板
### DELETE /templates/templates/{id}
删除模板
### POST /templates/templates/{type}/render
渲染模板预览
**参数**: `type` 为 `ai_prompt` 或 `report`
**请求体**：用于替换模板中的变量
```json
{
"student_name": "张三",
"practice_time": "30分钟",
"problems": "...",
"student_goals": "..."
}
```
**响应**：
```json
{
"rendered": "渲染后的内容..."
}
```
---
@@ -705,7 +996,8 @@ POST /api/config/test
| 班级查询/分配学员 | ✅ | ✅ |
| 学员管理 | ✅ | ✅ |
| 问题记录 | ✅ | ✅ |
| 方案生成 | ✅ | ✅ |
| 方案生成/预览 | ✅ | ✅ |
| 模板管理 | ✅ | ❌ |
| 系统设置 | ✅ | ❌ |
| 修改自己密码 | ✅ | ✅ |
docs/DEPLOYMENT.md
+5 -5
View File
@@ -3,8 +3,8 @@
## 目标服务器
- **服务器**: 阿里云 ECS (CentOS 7)
- **IP**: 47.106.65.108
- **连接**: `ssh -i ~/.ssh/id_rsa root@47.106.65.108`
- **IP**: 47.115.32.206
- **连接**: `ssh -i ~/.ssh/id_rsa root@47.115.32.206`
---
@@ -59,10 +59,10 @@ tar -czvf piano-plan.tar.gz \
-f - .
# 上传到服务器
scp -i ~/.ssh/id_rsa piano-plan.tar.gz root@47.106.65.108:/opt/
scp -i ~/.ssh/id_rsa piano-plan.tar.gz root@47.115.32.206:/opt/
# SSH登录服务器
ssh -i ~/.ssh/id_rsa root@47.106.65.108
ssh -i ~/.ssh/id_rsa root@47.115.32.206
```
### 2. 服务器准备
@@ -247,4 +247,4 @@ ls -la /app/data/
## 联系
部署完成后访问: `http://47.106.65.108:5000`
部署完成后访问: `http://47.115.32.206:5000`
docs/DEPLOYMENT_SOP.md
+18 -8
View File
@@ -1,7 +1,7 @@
# 钢琴练习方案系统 - 部署 SOP
> 版本：v1.3
> 日期：2026-04-24
> 版本：v1.3.6
> 日期：2026-04-26
> 核心原则：**不删除，只备份后新增/替换**
---
@@ -135,7 +135,7 @@ docker save piano-plan:v1.3.0 -o releases/v1.3.0/toRelease/program/piano-plan.ta
### 4.1 SSH 到服务器
```bash
ssh -i ~/.ssh/id_rsa root@47.106.65.108
ssh -i ~/.ssh/id_rsa root@47.115.32.206
```
### 4.2 创建版本目录并备份上次生产环境
@@ -163,14 +163,14 @@ cp -r /opt/piano-plan/config /opt/piano-plan/releases/v1.3.0/bk/config.bak.$(dat
exit # 先退出服务器 SSH
# 上传发布包
scp -i ~/.ssh/id_rsa -r releases/v1.3.0/toRelease/* root@47.106.65.108:/opt/piano-plan/releases/v1.3.0/toRelease/
scp -i ~/.ssh/id_rsa -r releases/v1.3.0/toRelease/* root@47.115.32.206:/opt/piano-plan/releases/v1.3.0/toRelease/
```
### 4.4 服务器执行部署
```bash
# SSH 再次连接
ssh -i ~/.ssh/id_rsa root@47.106.65.108
ssh -i ~/.ssh/id_rsa root@47.115.32.206
cd /opt/piano-plan/releases/v1.3.0
@@ -294,7 +294,7 @@ docker start piano-plan
| 项目 | 值 |
|------|-----|
| 生产地址 | https://piano.yoin.fun |
| SSH | `ssh -i ~/.ssh/id_rsa root@47.106.65.108` |
| SSH | `ssh -i ~/.ssh/id_rsa root@47.115.32.206` |
| 容器名 | piano-plan |
| 端口 | 5001 |
| 数据库位置 | piano-plan-data volume |
@@ -348,6 +348,9 @@ A: 检查数据库是否成功执行了 schema 迁移，新增了 goals, goal_re
### Q: SSE 不完整？
A: nginx 需要为 SSE 配置特定的代理设置，参考之前文档
### Q: v1.3.2 部署后评估功能不工作？
A: 检查是否执行了 migrate_goals_v3.py 迁移脚本，该脚本创建 student_goal_evaluations 表
---
## 十、检查清单（部署完成后必填）
@@ -355,8 +358,9 @@ A: nginx 需要为 SSE 配置特定的代理设置，参考之前文档
```
[ ] 容器状态：running
[ ] 服务响应：HTTP 200/302
[ ] 数据库表完整：users, students, classes, student_problems, practice_plans, problems, goals, goal_relations, student_goals
[ ] 数据库表完整：users, students, classes, student_problems, practice_plans, problems, goals, goal_relations, student_goals, student_goal_evaluations
[ ] 目标管理功能正常：创建目标、分配目标、评估目标
[ ] 时间线正常显示阶段评估和最终评估
[ ] API 配置正确
[ ] 功能验证：能生成练习方案
```
@@ -367,6 +371,12 @@ A: nginx 需要为 SSE 配置特定的代理设置，参考之前文档
| 版本 | 日期 | 变更 |
|------|------|------|
| v1.3.6 | 2026-04-24 | 方案详情导航优化（学员名→学员详情、返回按钮修复）；典型方案开关移至方案详情；方案列表显示问题级别+严重程度；plan.content新增level字段；学员生成方案增加模板选择器；生成时禁用按钮；完成后显示提示词/报告字数；学员目标删除支持级联删除评估；目标模板删除增加依赖检查；API文档更新 |
| v1.3.5 | 2026-04-24 | 班级班主任字段；用户姓名name字段；班级/学员/方案增加"我的"筛选；用户管理：姓名字段+可编辑；方案管理：模板列表权限修复；时间线"我的"按钮样式优化 |
| v1.3.4 | 2026-04-24 | 方案编辑按钮；问题增量添加；teachers API公开；用户管理权限修复 |
| v1.3.3 | 2026-04-24 | 评估日期编辑；最终评估关联 StudentGoal 同步 |
| v1.3.2 | 2026-04-24 | StudentGoal 新增 status 字段；新增 StudentGoalEvaluation 表；阶段评估+最终评估功能；时间线增强（尚余天数/提前或延迟达成） |
| v1.3.1 | 2026-04-24 | DRY 规范；Fragment 复用方案；班级批量分配目标 |
| v1.3 | 2026-04-24 | 目标管理模块：Goal/GoalRelation/StudentGoal；问题分类重构；学习历程时间线 |
| v1.2 | 2026-04-23 | 问题迁移到数据库；移除个性化方案挂载 |
| v1.1 | 2026-04-20 | 模板管理；API配置界面 |
@@ -375,4 +385,4 @@ A: nginx 需要为 SSE 配置特定的代理设置，参考之前文档
---
> **最后更新**：2026-04-24
> **更新原因**：v1.3.1 代码更新；DRY 规范入撰；Fragment 复用方案；班级批量分配目标
> **更新原因**：v1.3.6 发布；方案详情导航优化；典型方案开关移至详情页；列表显示级别+严重程度；生成方案增加模板选择器；提示词字数确认
docs/DEVELOPMENT.md
+2 -1
View File
@@ -199,7 +199,8 @@ deploy: v1.2.0 生产环境部署
| V1.1 | 2026-04-17 | 添加用户登录认证系统 |
| V1.2 | 2026-04-18 | 添加用户管理、角色权限、班级管理 |
| V1.2.0 | 2026-04-23 | 问题迁移到数据库；URL导航改造；侧边栏统一 |
| V1.3 | 2026-04-25 | 目标管理模块上线；班级级别属性；{student_goals}参数；提示词预览 |
---
*最后更新：2026-04-23*
*最后更新：2026-04-25*
docs/MODELS.md
+2 -8
View File
@@ -89,6 +89,7 @@
|------|------|------|
| id | Integer | 主键，自增 |
| name | String(100) | 班级名称，必填 |
| level | String(20) | 班级级别：启蒙/入门/进阶/熟练/精通 |
| description | Text | 班级描述，可选 |
| created_at | DateTime | 创建时间 |
@@ -120,14 +121,6 @@
"focus": {"basic": 15, "tech": 10, "piece": 20}
}
],
"daily_schedule": [
{
"phase": "热身",
"duration": "3分钟",
"content": "手部放松操 + 呼吸调节",
"purpose": "放松肌肉，进入状态"
}
],
"ai_report": "## 个性化练习方案报告\n\n..."
}
```
@@ -332,6 +325,7 @@ SELECT * FROM users;
| id | Integer | 主键 |
| student_id | Integer | 学员ID，外键 |
| goal_id | Integer | 目标ID，外键 |
| goal_content | Text | 目标内容副本（冗余存储，避免目标被删除后丢失） |
| start_date | DateTime | 开始日期 |
| assessment_date | DateTime | 评估日期 |
| mastery_level | Integer | 掌握程度 1-5（评估时填写） |
docs/STRUCTURE.md
+5 -1
View File
@@ -141,10 +141,13 @@ def create_app():
| 路由 | 方法 | 说明 |
|------|------|------|
| `/api/generate-plan` | POST | 生成练习方案 |
| `/api/generate-plan/preview` | POST | 预览提示词 |
| `/api/plans/<id>` | GET | 获取方案详情 |
| `/api/plans/<id>/pdf` | GET | 导出PDF |
| `/api/plans/<id>/md` | GET | 导出Markdown |
| `/plans/<id>/wechat` | GET | 微信卡片 |
| `/api/plans/<id>` | DELETE | 删除方案 |
| `/api/plans/<id>/typical` | POST | 设为典型方案 |
### routes/settings.py
@@ -281,4 +284,5 @@ generate_pdf(plan_id, student_name, content, output_dir)
| V1.0 | 2026-04-17 | 初始版本：学员管理、问题记录、方案生成 |
| V1.1 | 2026-04-17 | 添加用户登录认证系统 |
| V1.2 | 2026-04-18 | 添加用户管理、角色权限、班级管理 |
| V1.2.0 | 2026-04-23 | 问题迁移到数据库；URL导航改造；侧边栏统一 |
| V1.2.0 | 2026-04-23 | 问题迁移到数据库；URL导航改造；侧边栏统一 |
| V1.3 | 2026-04-25 | 目标管理模块上线；班级级别属性；{student_goals}参数；提示词预览 |