284 lines
8.7 KiB
Markdown
284 lines
8.7 KiB
Markdown
# 项目结构说明
|
||
|
||
## 目录概览
|
||
|
||
```
|
||
练习方案系统/
|
||
├── 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_edit.html # 方案编辑页（URL导航）
|
||
│ ├── 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应用实例
|
||
- 加载配置
|
||
- 初始化数据库
|
||
- 注册蓝图
|
||
- 创建必要目录
|
||
|
||
```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` - 问题记录（关联 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 | 生成练习方案 |
|
||
| `/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 | 分配学员 | 登录用户 |
|
||
| `/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
|
||
|
||
核心业务逻辑：
|
||
|
||
```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 | 添加用户管理、角色权限、班级管理 |
|
||
| V1.2.0 | 2026-04-23 | 问题迁移到数据库；URL导航改造；侧边栏统一 | |