# 老师学员匹配系统需求文档

## 1. 项目概述
本系统旨在实现老师和学员的自动匹配功能，根据双方的可用时间进行智能匹配，并生成匹配结果。

## 2. 功能需求

### 2.1 基础功能
- **老师管理**：支持通过Excel导入老师信息，包含老师类型标记
- **时间数据导入**：通过Excel文件导入老师和学生的可用时间
- **智能匹配**：根据时间兼容性自动匹配老师和学生
- **匹配结果导出**：生成Excel格式的匹配结果
- **历史匹配记录**：记录学生与老师的历史匹配情况，避免重复匹配

### 2.2 核心匹配规则（按优先级）
1. **首次上课限制**：学生第一次上课只能匹配旧老师
2. **交替匹配规则**：后续上课按"新老师→旧老师→新老师→..."交替进行
3. **历史匹配规避**：学生不能匹配之前上过课的老师
4. **每日唯一性**：每位老师每天只能接待一位学生
5. **均衡分配**：优先匹配次数少的老师，让更多老师参与

### 2.3 核心流程
1. 导入老师信息（包含老师类型）和可用时间
2. 导入学生信息（包含历史匹配）和可用时间
3. 系统自动匹配老师和学生
4. 生成匹配结果并导出
5. 记录匹配历史

## 3. 数据结构

### 3.1 老师数据结构
| 字段名 | 数据类型 | 说明 |
|-------|---------|------|
| 老师ID | 字符串 | 唯一标识 |
| 姓名 | 字符串 | 老师姓名 |
| 老师类型 | 字符串 | 新老师/旧老师 |
| 可用时间 | 时间列表 | 每个日期的可用时间段 |
| 其他信息 | 字符串 | 可选的额外信息 |

### 3.2 学生数据结构
| 字段名 | 数据类型 | 说明 |
|-------|---------|------|
| 学生ID | 字符串 | 唯一标识 |
| 姓名 | 字符串 | 学生姓名 |
| 可用时间 | 时间列表 | 每个日期的可用时间段 |
| 历史匹配老师 | 老师ID列表 | 曾经匹配过的老师 |
| 其他信息 | 字符串 | 可选的额外信息 |

### 3.3 匹配结果数据结构
| 字段名 | 数据类型 | 说明 |
|-------|---------|------|
| 匹配ID | 字符串 | 唯一标识 |
| 学生ID | 字符串 | 学生标识 |
| 老师ID | 字符串 | 老师标识 |
| 匹配日期 | 日期 | 匹配的具体日期 |
| 匹配时段 | 时间段 | 具体上课时间段 |
| 状态 | 字符串 | 匹配状态（成功/未匹配） |

## 4. Excel格式设计

### 4.1 老师信息Excel格式
| 列名 | 说明 |
|-----|------|
| 老师姓名 | 唯一标识 |
| 老师类型 | 新老师/旧老师 |
| 备注 | 可选的额外信息 |
| 1月1日 | 可用时间段（如：9:00-11:00;14:00-16:00） |
| 1月2日 | 可用时间段 |
| ... | ... |

### 4.2 学生信息Excel格式
| 列名 | 说明 |
|-----|------|
| 学生姓名 | 唯一标识 |
| 历史匹配老师 | 曾经匹配过的老师姓名，用逗号分隔 |
| 备注 | 可选的额外信息 |
| 1月1日 | 可用时间段 |
| 1月2日 | 可用时间段 |
| ... | ... |

### 4.3 匹配结果Excel格式
| 列名 | 说明 |
|-----|------|
| 学生 | 学生姓名 |
| 老师 | 匹配的老师姓名 |
| 日期 | 匹配日期 |
| 时段 | 匹配的时间段 |
| 状态 | 匹配状态 |

## 5. 技术要求

### 5.1 开发环境
- 操作系统：Windows
- 开发语言：Python（打包为EXE）
- 依赖库：
  - pandas（处理Excel文件）
  - openpyxl（Excel文件读写）
  - Flet（GUI界面）
  - pyinstaller（打包为EXE）

### 5.2 性能要求
- 支持至少100名学生和20名老师的匹配
- 匹配过程响应时间不超过10秒

## 6. 界面设计

### 6.1 主界面
- 老师管理区域：显示老师列表（包含类型标识）
- 数据导入区域：提供Excel文件选择和导入按钮
- 匹配控制区域：开始匹配按钮
- 结果显示区域：显示匹配结果
- 导出区域：导出匹配结果按钮

### 6.2 操作流程
1. 用户打开软件
2. 导入老师Excel文件（包含类型信息）
3. 导入学生Excel文件（包含历史匹配）
4. 点击开始匹配按钮
5. 查看匹配结果
6. 导出匹配结果到Excel文件

## 7. 其他需要讨论的点

1. **匹配算法**：具体的匹配规则和优先级如何确定？
2. **时间冲突处理**：如果多个学生同时匹配到同一个老师的同一天，如何处理？
3. **数据验证**：如何验证导入的Excel数据格式是否正确？
4. **错误处理**：当匹配失败或数据异常时，如何提示用户？
5. **历史数据存储**：历史匹配记录如何存储和管理？
6. **用户权限**：是否需要不同级别的用户权限？
7. **界面语言**：是否需要支持多语言？
8. **系统兼容性**：支持的Windows版本范围？
9. **安装部署**：是否需要安装程序或绿色版？
10. **更新机制**：如何进行系统更新？

## 8. 项目计划

1. **需求分析与设计**：1天
2. **数据结构实现**：1天
3. **Excel文件处理**：1天
4. **匹配算法实现**：2天
5. **GUI界面开发**：2天
6. **测试与调试**：2天
7. **打包与部署**：1天

## 9. 验收标准

1. 系统能够正确导入老师和学生的Excel文件
2. 系统能够根据时间兼容性自动匹配老师和学生
3. 系统能够避免重复匹配历史上已经匹配过的老师和学生
4. 系统能够确保每位老师每天只接待一位学生
5. 系统能够按规则分配新/旧老师（首次→旧老师，后续交替）
6. 系统能够优先分配匹配次数少的老师
7. 系统能够生成正确的匹配结果Excel文件
8. 系统界面友好，操作简单
9. 系统运行稳定，无明显错误