piano-plan/docs/STRUCTURE.md

项目结构说明

目录概览

练习方案系统/
├── 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
│   │   ├── goals.py          # 目标管理 API
│   │   └── student_goals.py  # 学员目标 API
│   │
│   ├── services/              # 业务逻辑
│   │   ├── plan_generator.py  # 方案生成器
│   │   └── pdf_generator.py   # PDF生成器
│   │
│   └── templates/             # 前端模板
│       ├── fragments/          # 可复用模态窗体片段（{% include %})
│       │   └── assign_goal_modal.html  # 分配目标模态窗体
│       ├── base.html          # 基础模板（所有页面继承，统一侧边栏）
│       ├── index.html         # 学员管理页面（继承base）
│       ├── home.html          # 默认首页（显示统计信息）
│       ├── student.html       # 学员详情页（URL导航）
│       ├── plan_detail.html   # 方案详情页（URL导航）
│       ├── plan_edit.html     # 方案编辑页（URL导航）
│       ├── plans.html         # 方案管理列表页
│       ├── settings.html      # 问题配置页面（继承base）
│       ├── login.html         # 登录页面（独立）
│       ├── setup.html         # 初始设置页面（独立）
│       ├── users.html         # 用户管理页面（继承base）
│       ├── classes.html       # 班级管理页面（继承base）
│       ├── goals.html        # 目标管理页面
│       ├── templates.html     # 模板管理页面（继承base）
│       ├── api_settings.html  # API设置页面（继承base）
│       └── wechat_card.html   # 微信卡片模板（独立）
│
├── data/                      # 数据目录（运行时创建）
│   └── piano_plans.db         # SQLite数据库
│
├── output/                    # PDF输出目录（运行时创建）
│
├── config/                    # 配置目录（运行时创建）
│   └── api_config.json        # API配置文件
│
├── run.py                     # 应用入口
├── run.bat                    # 启动脚本
├── requirements.txt           # Python依赖
└── README.md                  # 项目说明

---

核心模块

app/__init__.py

应用工厂，负责：

• 创建Flask应用实例
• 加载配置
• 初始化数据库
• 注册蓝图
• 创建必要目录

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 - 问题记录（关联 Problem 表）
• Problem - 问题定义（15种预定义问题，已从文件迁移到数据库）
• 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	生成练习方案（SSE）
/api/generate-plan/preview	POST	预览提示词
/api/plans/<id>	GET	获取方案详情
/api/plans/<id>/content	PUT	更新方案内容
/api/plans/<id>/pdf	GET	导出PDF
/api/plans/<id>/md	GET	导出Markdown
/plans/<id>/wechat	GET	微信卡片
/api/plans/<id>	DELETE	删除方案
/api/plans/<id>/typical	POST	设为典型方案
/api/plans/<id>/adopt	POST	采纳典型方案
/api/students/<id>/plans	GET	获取学员方案列表
/api/students/<id>/recommended-plans	GET	获取推荐方案列表

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	分配学员	登录用户
/api/classes/<id>/goals	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

核心业务逻辑：

# 生成基础练习方案
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：

generate_pdf(plan_id, student_name, content, output_dir)

---

权限系统

角色

角色	说明
admin	管理员，拥有所有权限
user	普通用户，受限权限

权限矩阵

模块	管理员	普通用户
用户管理	增删改查	❌
班级管理	增删改	查询+分配
学员管理	增删改查	增删改查
问题记录	增删改查	增删改查
方案生成	✅	✅
系统设置	✅	❌
修改密码	✅	✅

权限装饰器

# 后端权限装饰器
@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	添加用户管理、角色权限、班级管理
V1.2.0	2026-04-23	问题迁移到数据库；URL导航改造；侧边栏统一
V1.3	2026-04-25	目标管理模块上线；班级级别属性；{student_goals}参数；提示词预览
V1.4	2026-04-27	典型方案采纳；推荐方案列表；方案编辑/详情页导航优化；审计字段完善