172 lines
6.0 KiB
Markdown
172 lines
6.0 KiB
Markdown
# 钢琴练习方案生成系统
|
||
|
||
> 教师端学员练习方案管理工具
|
||
|
||
## 运维技能
|
||
|
||
本系统的开发，维护、部署等运维工作已标准化为AI技能：
|
||
|
||
- **技能名称**: `piano-practice-sys`
|
||
- **技能路径**: `D:\F\NewI\opencode\daily-workspace\.opencode\skills\piano-practice-sys\SKILL.md`
|
||
|
||
**当需要进行以下操作时，使用此技能：**
|
||
- 查看/修改学员、班级、问题配置
|
||
- 数据备份与恢复
|
||
- 系统部署上线
|
||
- 查看操作日志
|
||
- 任何运维相关工作
|
||
|
||
调用方式：加载 `piano-practice-sys` 技能后，按照技能指引操作。
|
||
|
||
---
|
||
|
||
## 功能特点
|
||
|
||
- ✅ 学员管理（增删改查）
|
||
- ✅ 班级管理（班主任负责）
|
||
- ✅ 问题记录（15种常见问题 + 严重程度 + 练习时间 + 级别，数据存储在数据库）
|
||
- ✅ **AI生成个性化练习方案报告**（支持 MiniMax，火山方舟、DeepSeek）
|
||
- ✅ **模板管理**（AI提示词模板、报告导出模板，支持排序）
|
||
- ✅ **典型方案采纳**（推荐方案列表，可一键采纳）
|
||
- ✅ 三种输出方式：
|
||
- 网页展示
|
||
- **PDF下载（支持中文 + 可配置水印）**
|
||
- 微信卡片分享
|
||
- ✅ **可视化编辑**（AI报告用 Markdown编辑器，每日练习用表格编辑器）
|
||
- ✅ **API配置界面**（多提供商支持，切换时自动填充）
|
||
- ✅ **方案审计字段**（created_by/updated_by/updated_at）
|
||
- ✅ **目标管理**（目标设定、阶段评估、最终评估）
|
||
- ✅ **数据统计**（问题分布、级别分布、班级统计、可视化图表）
|
||
|
||
## 技术栈
|
||
|
||
- Flask + SQLite
|
||
- reportlab（PDF中文支持）
|
||
- 支持 LLM：MiniMax-M2.7-highspeed、火山方舟 doubao-seed、DeepSeek
|
||
- Bootstrap5 前端 + EasyMDE + Tabulator
|
||
|
||
## 快速启动（Windows）
|
||
|
||
```bash
|
||
# 双击运行
|
||
run.bat
|
||
```
|
||
|
||
首次运行会自动创建虚拟环境并安装依赖。
|
||
|
||
**访问地址**：http://127.0.0.1:5001
|
||
|
||
## 使用流程
|
||
|
||
1. **添加学员** → 输入姓名、电话、微信昵称
|
||
2. **记录问题** → 选择问题 + 严重程度 + 级别 + 每日练习时间
|
||
3. **生成方案** → 一键生成个性化练习计划（含AI报告，可选提示词模板）
|
||
4. **导出分发** → PDF下载 / 微信卡片分享 / 预览报告
|
||
5. **配置API** → 设置页面可修改LLM配置（支持多提供商）
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
piano-plan/
|
||
├── app/ # Flask应用核心代码
|
||
│ ├── __init__.py # 应用工厂
|
||
│ ├── config.py # 配置管理
|
||
│ ├── models.py # 数据库模型
|
||
│ ├── routes/ # 路由模块
|
||
│ │ ├── students.py # 学员管理
|
||
│ │ ├── problems.py # 问题记录
|
||
│ │ ├── plans.py # 方案生成
|
||
│ │ ├── settings.py # 系统设置
|
||
│ │ ├── templates.py # 模板管理
|
||
│ │ └── auth.py # 认证
|
||
│ ├── services/ # 业务逻辑
|
||
│ │ ├── plan_generator.py # 方案生成器
|
||
│ │ └── pdf_generator.py # PDF生成器
|
||
│ └── templates/ # 前端模板（base.html + 页面模板）
|
||
│
|
||
├── config/ # 配置文件
|
||
├── data/ # SQLite数据库（不提交git）
|
||
├── docs/ # 项目文档
|
||
│ ├── API.md # API接口文档
|
||
│ ├── MODELS.md # 数据模型说明
|
||
│ ├── STRUCTURE.md # 项目结构说明
|
||
│ ├── DEPLOYMENT_SOP.md # 部署SOP
|
||
│ ├── FRONTEND_ARCH.md # 前端架构规范
|
||
│ └── DEVELOPMENT.md # 开发规范 ⭐
|
||
├── releases/ # 部署包（版本化，如 v1.2.0/）
|
||
├── scripts/ # 临时调试脚本（开发用，完成后删除）
|
||
├── output/ # PDF输出目录（不提交git）
|
||
│
|
||
├── run.py # 应用入口
|
||
├── run.bat # Windows启动脚本
|
||
├── deploy.sh # 部署脚本
|
||
├── docker-compose.yml
|
||
├── Dockerfile
|
||
├── requirements.txt
|
||
└── README.md
|
||
```
|
||
|
||
## 15种常见问题
|
||
|
||
| 编号 | 问题 | 分类 |
|
||
|------|------|------|
|
||
| 01 | 手小 | 技术类 |
|
||
| 02 | 识谱慢 | 认知类 |
|
||
| 03 | 节奏感差 | 节奏类 |
|
||
| 04 | 压手腕 | 习惯类 |
|
||
| 05 | 掌关节支撑差 | 技术类 |
|
||
| 06 | 第一关节支撑差 | 技术类 |
|
||
| 07 | 对键盘不熟悉 | 认知类 |
|
||
| 08 | 手指僵硬、紧张 | 习惯类 |
|
||
| 09 | 手指不会跑动 | 技术类 |
|
||
| 10 | 力度不会把握 | 技术类 |
|
||
| 11 | 左右手不协调 | 综合类 |
|
||
| 12 | 不会用节拍器 | 节奏类 |
|
||
| 13 | 不会编配指法 | 技术类 |
|
||
| 14 | 基本功练习 | 综合类 |
|
||
| 15 | 练习缺乏监督 | 习惯类 |
|
||
|
||
## 支持的 LLM 提供商
|
||
|
||
| 提供商 | Endpoint | 模型 |
|
||
|--------|----------|------|
|
||
| MiniMax | https://api.minimaxi.com/anthropic/v1 | MiniMax-M2.7-highspeed |
|
||
| 火山方舟 | https://ark.cn-beijing.volces.com/api/coding/v3 | doubao-seed-2.0-pro |
|
||
| DeepSeek | https://api.deepseek.com | deepseek-chat |
|
||
|
||
## 文档
|
||
|
||
详细开发文档见 `docs/` 目录：
|
||
|
||
- [API接口文档](docs/API.md)
|
||
- [数据模型说明](docs/MODELS.md)
|
||
- [项目结构说明](docs/STRUCTURE.md)
|
||
- [部署SOP](docs/DEPLOYMENT_SOP.md)
|
||
- [前端架构规范](docs/FRONTEND_ARCH.md)
|
||
- [开发规范](docs/DEVELOPMENT.md) ⭐ 版本/发布/脚本规范
|
||
|
||
## 配置
|
||
|
||
### API配置
|
||
|
||
访问设置页面（`/api-settings`）可配置：
|
||
- LLM提供商（MiniMax/火山方舟/DeepSeek）
|
||
- API Key（每个提供商单独保存）
|
||
- 模型选择
|
||
- Temperature参数
|
||
|
||
### 模板管理
|
||
|
||
访问模板管理页面（`/templates`）可配置：
|
||
- AI提示词模板（生成方案时使用）
|
||
- 报告导出模板（下载报告时使用）
|
||
- 支持排序（排在前面的优先使用）
|
||
|
||
---
|
||
|
||
> **版本**：v1.5.0
|
||
> **创建时间**：2026-04-17
|
||
> **最后更新**：2026-04-27
|
||
>
|
||
> **重要更新**：v1.5.0 - 数据统计页面（问题/级别分布可视化）；PDF水印配置；编辑页按钮吸底；侧边栏调整
|