# 钢琴练习方案生成系统

> 教师端学员练习方案管理工具

## 运维技能

本系统的开发，维护、部署等运维工作已标准化为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.4.0
> **创建时间**：2026-04-17
> **最后更新**：2026-04-27
>
> **重要更新**：v1.4.0 - 问题数据已迁移到数据库；典型方案采纳功能；审计字段完善