diff --git a/README.md b/README.md index c5f267d..2399d16 100644 --- a/README.md +++ b/README.md @@ -23,18 +23,20 @@ ## 功能特点 - ✅ 学员管理(增删改查) +- ✅ 班级管理(班主任负责) - ✅ 问题记录(15种常见问题 + 严重程度 + 练习时间 + 级别,数据存储在数据库) -- ✅ **AI生成个性化练习方案报告**(支持 MiniMax、火山方舟、DeepSeek) +- ✅ **AI生成个性化练习方案报告**(支持 MiniMax,火山方舟、DeepSeek) - ✅ **模板管理**(AI提示词模板、报告导出模板,支持排序) - ✅ **典型方案采纳**(推荐方案列表,可一键采纳) - ✅ 三种输出方式: - 网页展示 - - **PDF下载(支持中文)** + - **PDF下载(支持中文 + 可配置水印)** - 微信卡片分享 - ✅ **可视化编辑**(AI报告用 Markdown编辑器,每日练习用表格编辑器) - ✅ **API配置界面**(多提供商支持,切换时自动填充) - ✅ **方案审计字段**(created_by/updated_by/updated_at) - ✅ **目标管理**(目标设定、阶段评估、最终评估) +- ✅ **数据统计**(问题分布、级别分布、班级统计、可视化图表) ## 技术栈 @@ -162,8 +164,8 @@ piano-plan/ --- -> **版本**:v1.4.0 +> **版本**:v1.5.0 > **创建时间**:2026-04-17 > **最后更新**:2026-04-27 > -> **重要更新**:v1.4.0 - 问题数据已迁移到数据库;典型方案采纳功能;审计字段完善 +> **重要更新**:v1.5.0 - 数据统计页面(问题/级别分布可视化);PDF水印配置;编辑页按钮吸底;侧边栏调整 diff --git a/docs/API.md b/docs/API.md index 405ca5a..1e3114c 100644 --- a/docs/API.md +++ b/docs/API.md @@ -1066,6 +1066,47 @@ POST /api/config/test --- +--- + +## 数据统计 API + +### GET /api/statistics/students + +获取学员统计数据。 + +**权限**: 登录用户 + +**筛选参数**: +| 参数 | 类型 | 说明 | +|------|------|------| +| mine | bool | 是否只看当前用户负责的班级(true/false) | +| class_id | int | 筛选特定班级 | + +**响应示例**: +```json +{ + "total_students": 15, + "total_problems": 42, + "level_distribution": {"启蒙": 3, "入门": 8, "进阶": 4, "熟练": 0, "精通": 0}, + "severity_distribution": {"轻微": 12, "中等": 25, "严重": 5}, + "class_student_count": [ + {"class_id": 1, "class_name": "钢琴初级班", "level": "入门", "student_count": 8} + ], + "class_problem_count": [ + {"class_id": 1, "class_name": "钢琴初级班", "problem_count": 20} + ], + "problem_level_matrix": { + "轻微": {"启蒙": 2, "入门": 6, "进阶": 3, "熟练": 1, "精通": 0}, + "中等": {"启蒙": 1, "入门": 2, "进阶": 1, "熟练": 0, "精通": 0}, + "严重": {"启蒙": 0, "入门": 0, "进阶": 0, "熟练": 0, "精通": 0} + }, + "problem_name_distribution": {"手小": 5, "识谱慢": 8}, + "classes": [{"id": 1, "name": "钢琴初级班"}] +} +``` + +--- + ## 权限说明 | 接口 | 管理员 | 普通用户 | diff --git a/docs/DEPLOYMENT_SOP.md b/docs/DEPLOYMENT_SOP.md index f4eb65e..84683d6 100644 --- a/docs/DEPLOYMENT_SOP.md +++ b/docs/DEPLOYMENT_SOP.md @@ -1,12 +1,12 @@ # 钢琴练习方案系统 - 部署 SOP -> 版本:v1.4.0 +> 版本:v1.5.0 > 日期:2026-04-27 > 核心原则:**不删除,只备份后新增/替换** --- -## 重要更新(v1.4.0) +## 重要更新(v1.5.0) ### ⚠️ 问题文件已迁移到数据库 @@ -30,6 +30,17 @@ $env:HTTPS_PROXY="http://127.0.0.1:15000" docker build -t piano-plan:latest . ``` +### ⚠️ PDF 水印配置 + +PDF 水印文本在 API 设置页面(`/api-settings`)中配置,存储在 `api_config.json` 的 `watermark_text` 字段。 + +- 留空 = 不显示水印 +- 填写文字 = 每页中央斜向显示该文字(56pt,25%透明度) + +### ⚠️ 中文字体 + +Docker 镜像已内置 `fonts-wqy-microhei`,无需额外挂载。 + --- ## 一、部署原则(铁律) @@ -384,7 +395,19 @@ A: 检查是否执行了 migrate_goals_v3.py 迁移脚本,该脚本创建 stud --- ## 十、检查清单(部署完成后必填) - +``` +[ ] 容器状态:running +[ ] 服务响应:HTTP 200/302 +[ ] 数据库表完整:users, students, classes, student_problems, practice_plans, templates, problems, goals, goal_relations, student_goals, student_goal_evaluations +[ ] practice_plans 表有新字段:created_by, updated_by, updated_at, template_id, is_typical +[ ] 目标管理功能正常:创建目标、分配目标、评估目标 +[ ] 时间线正常显示阶段评估和最终评估 +[ ] API 配置正确 +[ ] 功能验证:能生成练习方案 +[ ] 方案列表支持删除 +[ ] 学员列表"暂无方案/问题"样式正常 +[ ] PDF 水印功能正常(配置后导出可见) +[ ] 数据统计页面正常显示 ``` [ ] 容器状态:running [ ] 服务响应:HTTP 200/302 @@ -404,6 +427,7 @@ A: 检查是否执行了 migrate_goals_v3.py 迁移脚本,该脚本创建 stud | 版本 | 日期 | 变更 | |------|------|------| +| v1.5.0 | 2026-04-27 | 数据统计页面(问题/级别分布可视化);PDF水印配置(可自定义文本);编辑页按钮吸底;侧边栏顺序调整;MySQL字体问题修复(Linux) | | v1.4.0 | 2026-04-27 | 典型方案采纳;推荐方案列表;方案编辑/详情页导航优化(bfcache处理);审计字段完善(created_by/updated_by/updated_at);方案列表支持删除;学员列表"暂无方案/问题"样式统一 | | v1.3.6 | 2026-04-24 | 方案详情导航优化;典型方案开关移至方案详情;方案列表显示问题级别+严重程度 | | v1.3.5 | 2026-04-24 | 班级班主任字段;用户姓名name字段;班级/学员/方案增加"我的"筛选 | @@ -419,4 +443,4 @@ A: 检查是否执行了 migrate_goals_v3.py 迁移脚本,该脚本创建 stud --- > **最后更新**:2026-04-27 -> **更新原因**:v1.4.0 发布;问题文件已废弃(迁移到数据库);添加代理配置说明;审计字段;方案列表删除功能 +> **更新原因**:v1.5.0 发布;数据统计页面;PDF水印;编辑页吸底按钮;Linux中文字体路径 diff --git a/docs/MODELS.md b/docs/MODELS.md index 3e27f2b..c706999 100644 --- a/docs/MODELS.md +++ b/docs/MODELS.md @@ -91,10 +91,13 @@ | name | String(100) | 班级名称,必填 | | level | String(20) | 班级级别:启蒙/入门/进阶/熟练/精通 | | description | Text | 班级描述,可选 | +| teacher_id | Integer | 外键,关联 User(班主任) | +| active | Boolean | 是否进行中,默认 true | | created_at | DateTime | 创建时间 | **关系**: - `students`: 与 Student 一对多 +- `teacher`: 与 User 多对一(班主任) ---