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

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

Browse Source
This commit is contained in:
hmo
2026-04-21 20:00:33 +08:00
commit fd593bddf4
44 changed files with 10936 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/STRUCTURE.md
+279
View File
@@ -0,0 +1,279 @@
# 项目结构说明
## 目录概览
```
练习方案系统/
├── docs/ # 项目文档
│ ├── API.md # API接口文档
│ ├── MODELS.md # 数据模型说明
│ └── STRUCTURE.md # 本文件 - 项目结构
│
├── app/ # Flask应用主目录
│ ├── __init__.py # 应用工厂
│ ├── config.py # 配置管理
│ ├── models.py # 数据库模型
│ │
│ ├── routes/ # 路由模块
│ │ ├── __init__.py # 蓝图注册
│ │ ├── auth.py # 登录认证
│ │ ├── students.py # 学员管理API
│ │ ├── problems.py # 问题记录API
│ │ ├── plans.py # 方案生成API
│ │ ├── settings.py # 系统设置API
│ │ └── classes.py # 班级管理API（新增）
│ │
│ ├── services/ # 业务逻辑
│ │ ├── plan_generator.py # 方案生成器
│ │ └── pdf_generator.py # PDF生成器
│ │
│ └── templates/ # 前端模板
│ ├── base.html # 基础模板（所有页面继承）
│ ├── index.html # 学员管理页面（继承base）
│ ├── settings.html # 问题配置页面（继承base）
│ ├── login.html # 登录页面（独立）
│ ├── setup.html # 初始设置页面（独立）
│ ├── users.html # 用户管理页面（继承base）
│ ├── classes.html # 班级管理页面（继承base）
│ ├── templates.html # 模板管理页面（继承base）
│ ├── api_settings.html # API设置页面（继承base）
│ └── wechat_card.html # 微信卡片模板（独立）
│
├── data/ # 数据目录（运行时创建）
│ └── piano_plans.db # SQLite数据库
│
├── output/ # PDF输出目录（运行时创建）
│
├── config/ # 配置目录（运行时创建）
│ └── api_config.json # API配置文件
│
├── 个性化方案/ # 练习方案内容
│ └── 针对性练习（拆分为单独文件）/
│ ├── 01_手小.md
│ ├── 02_识谱慢.md
│ └── ...
│
├── run.py # 应用入口
├── run.bat # 启动脚本
├── requirements.txt # Python依赖
└── README.md # 项目说明
```
---
## 核心模块
### app/__init__.py
应用工厂，负责：
- 创建Flask应用实例
- 加载配置
- 初始化数据库
- 注册蓝图
- 创建必要目录
```python
def create_app():
app = Flask(__name__)
# 加载配置...
db.init_app(app)
app.register_blueprint(main_bp)
# 创建目录...
return app
```
### app/config.py
配置文件，包含：
- 数据库路径
- 问题文件目录
- PDF输出目录
- API配置加载/保存函数
- 权限配置
### app/models.py
数据库模型定义：
- `User` - 用户（登录认证、权限管理）
- `Student` - 学员
- `StudentProblem` - 问题记录
- `Class` - 班级（新增）
- `PracticePlan` - 练习方案
---
## 路由详解
### routes/auth.py
| 路由 | 方法 | 说明 |
|------|------|------|
| `/login` | GET | 登录页面 |
| `/api/login` | POST | 登录API |
| `/api/logout` | POST | 登出API |
| `/api/check-login` | GET | 检查登录状态 |
| `/setup` | GET | 初始设置页面 |
| `/api/setup` | POST | 初始设置API |
### routes/students.py
| 路由 | 方法 | 说明 |
|------|------|------|
| `/api/students` | GET | 获取学员列表 |
| `/api/students` | POST | 创建学员 |
| `/api/students/<id>` | GET | 获取学员详情 |
| `/api/students/<id>` | PUT | 更新学员 |
| `/api/students/<id>` | DELETE | 删除学员 |
### routes/problems.py
| 路由 | 方法 | 说明 |
|------|------|------|
| `/api/students/<id>/problems` | GET | 获取学员问题 |
| `/api/students/<id>/problems` | POST | 添加问题 |
| `/api/students/<id>/problems/<pid>` | DELETE | 删除问题 |
### routes/plans.py
| 路由 | 方法 | 说明 |
|------|------|------|
| `/api/generate-plan` | POST | 生成练习方案 |
| `/api/plans/<id>` | GET | 获取方案详情 |
| `/api/plans/<id>/pdf` | GET | 导出PDF |
| `/plans/<id>/wechat` | GET | 微信卡片 |
| `/api/plans/<id>` | DELETE | 删除方案 |
### routes/settings.py
| 路由 | 方法 | 说明 | 权限 |
|------|------|------|------|
| `/settings` | GET | 设置页面 | 管理员 |
| `/api/problems` | GET | 获取问题列表 | 管理员 |
| `/api/problems` | POST | 创建问题 | 管理员 |
| `/api/problems/<id>` | GET | 问题详情 | 管理员 |
| `/api/problems/<id>` | PUT | 更新问题 | 管理员 |
| `/api/problems/<id>` | DELETE | 删除问题 | 管理员 |
| `/api/config` | GET | 获取API配置 | 管理员 |
| `/api/config` | POST | 更新API配置 | 管理员 |
| `/api/config/test` | POST | 测试API连接 | 管理员 |
### routes/classes.py（新增）
| 路由 | 方法 | 说明 | 权限 |
|------|------|------|------|
| `/api/classes` | GET | 班级列表 | 登录用户 |
| `/api/classes` | POST | 新增班级 | 管理员 |
| `/api/classes/<id>` | PUT | 编辑班级 | 管理员 |
| `/api/classes/<id>` | DELETE | 删除班级 | 管理员 |
| `/api/classes/<id>/students` | GET | 班级学员 | 登录用户 |
| `/api/classes/<id>/assign` | POST | 分配学员 | 登录用户 |
### routes/users.py（新增）
| 路由 | 方法 | 说明 | 权限 |
|------|------|------|------|
| `/users` | GET | 用户管理页面 | 管理员 |
| `/api/users` | GET | 用户列表 | 管理员 |
| `/api/users` | POST | 新增用户 | 管理员 |
| `/api/users/<id>` | PUT | 编辑用户 | 管理员 |
| `/api/users/<id>` | DELETE | 删除用户 | 管理员 |
| `/api/users/<id>/reset-password` | POST | 重置密码 | 管理员 |
| `/api/users/change-password` | POST | 修改自己密码 | 登录用户 |
---
## 服务层
### services/plan_generator.py
核心业务逻辑：
```python
# 生成基础练习方案
generate_practice_plan(student_name, problems, problems_dir)
# 生成AI报告（调用LLM）
generate_ai_report(student_name, problems, practice_time, time_config)
```
### services/pdf_generator.py
使用 reportlab 生成中文PDF：
```python
generate_pdf(plan_id, student_name, content, output_dir)
```
---
## 权限系统
### 角色
| 角色 | 说明 |
|------|------|
| admin | 管理员，拥有所有权限 |
| user | 普通用户，受限权限 |
### 权限矩阵
| 模块 | 管理员 | 普通用户 |
|------|--------|----------|
| 用户管理 | 增删改查 | ❌ |
| 班级管理 | 增删改 | 查询+分配 |
| 学员管理 | 增删改查 | 增删改查 |
| 问题记录 | 增删改查 | 增删改查 |
| 方案生成 | ✅ | ✅ |
| 系统设置 | ✅ | ❌ |
| 修改密码 | ✅ | ✅ |
### 权限装饰器
```python
# 后端权限装饰器
@admin_required # 仅管理员
@login_required # 需登录
# 前端根据 role 动态显示菜单和按钮
```
---
## 启动流程
1. 双击 `run.bat`
2. 脚本自动：
- 删除旧venv（如有）
- 创建新venv
- 安装依赖
- 启动Flask服务
3. 首次访问 `/setup` 创建管理员
4. 登录后使用系统
---
## 扩展开发
### 新增功能步骤
1. **数据模型**：在 `app/models.py` 添加新模型
2. **路由**：在 `app/routes/` 添加新路由文件
3. **业务逻辑**：在 `app/services/` 添加服务
4. **前端**：在 `app/templates/` 添加模板
5. **文档**：更新 `docs/` 目录
### 添加新依赖
1. 修改 `requirements.txt`
2. 运行 `pip install -r requirements.txt`
3. 更新 `run.bat` 中的安装命令
---
## 版本历史
| 版本 | 日期 | 说明 |
|------|------|------|
| V1.0 | 2026-04-17 | 初始版本：学员管理、问题记录、方案生成 |
| V1.1 | 2026-04-17 | 添加用户登录认证系统 |
| V1.2 | 2026-04-18 | 添加用户管理、角色权限、班级管理 |