feat: 初始提交 v1.2.0 - 钢琴练习方案生成系统

2026-04-21 20:00:33 +08:00
commit fd593bddf4
44 changed files with 10936 additions and 0 deletions
@@ -0,0 +1,164 @@
+# 钢琴练习方案生成系统
+
+> 教师端学员练习方案管理工具
+
+## 运维技能
+
+本系统的开发，维护、部署等运维工作已标准化为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配置界面**（多提供商支持，切换时自动填充）
+
+## 技术栈
+
+- 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.2.0
+> **创建时间**：2026-04-17
+> **最后更新**：2026-04-21