# 项目结构说明

## 目录概览

```
练习方案系统/
├── 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/             # 前端模板
│       ├── 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 | 分配学员 | 登录用户 |

### 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导航改造；侧边栏统一 |