# 班级操行分管理系统

基于 Python FastAPI 开发的班级操行分管理系统，支持学生端、管理端、家长端三端访问，实现操行分管理、作业提交跟踪、考勤记录等功能。

## 主要功能

### 学生端
- 查询个人当前操行总分
- 查看个人加减分历史明细（时间、分数变化、原因、操作人）
- 查看个人作业提交情况
- 查看个人考勤记录
- 查看历史学期归档数据（操行分、考勤统计、作业统计）
- 修改个人登录密码（首次登录强制修改）

### 家长端
- 查询子女当前操行总分和班级排名
- 查看子女操行分历史记录（加分/减分明细）
- 查看子女考勤记录
- 默认仅显示当前学期数据

### 管理端

**班主任权限：**
- 学生管理：新增/编辑/删除学生、批量导入学生（JSON）
- 操行分管理：对学生进行加减分、撤销任何扣分记录、查看全班历史记录、导出德育分记录
- 作业管理：发布作业、查看提交情况
- 考勤管理：查看全班考勤记录、自定义考勤扣分值
- 科目管理：动态增删学科
- 管理员管理：添加/编辑/删除/重置密码班长/科代表/考勤委员/劳动委员/志愿委员
- 学期管理：创建/编辑/删除学期、激活学期、归档学期（含考勤/作业统计快照）、关联历史记录、归档后可选重置分数
- 排行榜百分比筛选：在排行榜上方输入百分比，筛选显示前N%的学生（抹零法）
- 数据导出：导出历史记录、导出德育分记录（含加分/减分历史）

**班长权限：**
- 操行分管理：对学生进行加减分（±5分以内）、撤销任何人的扣分记录、查看全班历史记录

**学习委员权限：**
- 作业管理：更新作业提交状态、关联扣分（仅扣分，按规则）
- 科目管理：动态增删学科
- 历史记录：仅查看自己提交的操作记录

**考勤委员权限：**
- 考勤管理：记录考勤状态、关联扣分（仅扣分，按规则）
- 历史记录：仅查看自己提交的操作记录

**劳动委员权限：**
- 操行分管理：以卫生值日为理由进行加减分（固定 ±1 分）
- 历史记录：仅查看自己提交的操作记录

**志愿委员权限：**
- 操行分管理：以服务时长为由进行加分（仅加分）
- 历史记录：仅查看自己提交的操作记录

## 技术栈

| 层级 | 技术 | 版本 |
|------|------|------|
| 后端框架 | FastAPI | 0.104+ |
| 数据库 | MySQL | 5.7 |
| 缓存 | Redis | 7.x |
| 前端 | PHP | 8.0 |
| Web服务器 | Nginx | 1.28+ |

## 文件结构

```
classmanager/
│
├── backend/                          # Python FastAPI 后端
│   ├── .env.example                  # 后端环境变量示例
│   ├── .gitignore                    # Git 忽略文件
│   ├── config.py                     # 配置管理
│   ├── main.py                       # FastAPI 主入口
│   ├── requirements.txt              # Python 依赖
│   │
│   ├── logs/                         # 日志目录
│   │   ├── access.log
│   │   ├── app.log
│   │   ├── error.log
│   │   └── operation.log
│   │
│   ├── middleware/                   # 中间件
│   │   ├── __init__.py
│   │   ├── auth_middleware.py        # JWT 认证中间件
│   │   ├── permission.py             # 权限验证中间件
│   │   └── sanitize.py               # 输入过滤中间件
│   │
│   ├── models/                       # 数据模型
│   │   ├── __init__.py
│   │   ├── admin_role.py             # 管理员角色模型
│   │   ├── attendance.py             # 考勤模型
│   │   ├── conduct.py                # 操行分模型
│   │   ├── homework.py               # 作业模型
│   │   ├── log.py                    # 日志模型
│   │   ├── semester.py               # 学期模型
│   │   ├── student.py                # 学生模型
│   │   ├── subject.py                # 科目模型
│   │   └── user.py                   # 用户模型
│   │
│   ├── routes/                       # API 路由
│   │   ├── __init__.py
│   │   ├── admin.py                  # 管理端接口
│   │   ├── auth.py                   # 认证接口
│   │   ├── debug.py                  # 调试入口
│   │   ├── parent.py                 # 家长端接口
│   │   ├── semester.py               # 学期管理接口
│   │   ├── student.py                # 学生端接口
│   │   └── subject.py                # 科目管理接口
│   │
│   ├── schemas/                      # Pydantic 模型
│   │   ├── __init__.py
│   │   ├── admin.py
│   │   ├── auth.py
│   │   ├── common.py
│   │   ├── conduct.py
│   │   ├── parent.py
│   │   ├── semester.py               # 学期请求模型
│   │   ├── student.py
│   │   └── subject.py
│   │
│   ├── services/                     # 业务逻辑层
│   │   ├── __init__.py
│   │   ├── admin_service.py
│   │   ├── attendance_service.py
│   │   ├── auth_service.py
│   │   ├── conduct_service.py
│   │   ├── homework_service.py
│   │   ├── log_service.py
│   │   ├── parent_service.py
│   │   ├── semester_service.py       # 学期服务
│   │   ├── student_service.py
│   │   └── subject_service.py
│   │
│   └── utils/                        # 工具类
│       ├── __init__.py
│       ├── database.py               # MySQL 连接池
│       ├── jwt_handler.py            # JWT 处理
│       ├── logger.py                 # 日志轮转
│       ├── redis_client.py           # Redis 客户端
│       ├── response.py               # 统一响应
│       └── security.py               # 密码加密
│
├── frontend/                         # PHP 前端
│   ├── .env.example                  # 前端环境变量示例
│   ├── .htaccess                     # Apache 配置（可选）
│   ├── config.php                    # 前端配置
│   ├── index.php                     # 登录入口
│   │
│   ├── admin/                        # 管理端
│   │   ├── admins.php                # 管理员管理
│   │   ├── attendance.php            # 考勤管理
│   │   ├── conduct.php               # 操行分管理
│   │   ├── dashboard.php             # 管理端首页
│   │   ├── history.php               # 历史记录
│   │   ├── homework.php              # 作业管理
│   │   ├── password.php              # 修改密码
│   │   ├── semesters.php             # 学期管理
│   │   ├── students.php              # 学生管理
│   │   └── subjects.php              # 科目管理
│   │
│   ├── api/                          # 内部 API
│   │   └── save_session.php          # Session 保存接口
│   │
│   ├── assets/                       # 静态资源
│   │   ├── css/
│   │   │   ├── admin.css             # 管理端样式
│   │   │   └── style.css             # 全局样式
│   │   ├── js/
│   │   │   ├── admin.js              # 管理端 JS
│   │   │   ├── common.js             # 公共 JS
│   │   │   ├── parent.js             # 家长端 JS
│   │   │   └── student.js            # 学生端 JS
│   │   └── uploads/
│   │       └── sample_import.json    # 学生导入示例
│   │
│   ├── includes/                     # 公共包含文件
│   │   ├── footer.php                # 公共底部
│   │   ├── header.php                # 公共头部
│   │   └── nav.php                   # 导航栏
│   │
│   ├── parent/                       # 家长端
│   │   ├── attendance.php            # 考勤记录
│   │   ├── dashboard.php             # 家长端首页
│   │   └── history.php               # 历史记录
│   │
│   └── student/                      # 学生端
│       ├── attendance.php            # 考勤记录
│       ├── conduct.php               # 操行分详情
│       ├── dashboard.php             # 学生端首页
│       ├── homework.php              # 作业情况
│       ├── password.php              # 修改密码
│       └── semester_history.php      # 学期记录
│
├── sql/                              # 数据库脚本
│   └── init.sql                      # 初始化表结构
│
├── docs/                             # 文档
│   ├── student.md                    # 学生端详细文档
│   ├── parent.md                     # 家长端详细文档
│   ├── teacher.md                    # 班主任详细文档
│   ├── cadre.md                      # 班干部详细文档
│   └── guide/                        # 快速使用说明
│       ├── student.md
│       ├── parent.md
│       ├── teacher.md
│       └── cadre.md
│
├── .gitignore
├── INSTALL.md                        # 安装部署文档
├── LICENSE                           # MIT 许可证
└── README.md                         # 项目说明

```

## 角色权限一览表

| 角色 | 操行分查看 | 操行分加减 | 撤销扣分 | 历史记录查看 | 其他权限 |
|------|-----------|-----------|---------|-------------|---------|
| 班主任 | 全班 | 无限制 | 可撤销任何记录 | 全班所有记录 | 学生/管理员/科目管理、数据导出 |
| 班长 | 全班 | ±5分 | 可撤销任何记录 | 全班所有记录 | - |
| 学习委员 | 全班 | ±5分以内（加减分） | 不可撤销 | 仅自己提交的 | 作业管理、科目管理 |
| 考勤委员 | 全班 | 仅扣分（按规则） | 不可撤销 | 仅自己提交的 | 考勤管理 |
| 劳动委员 | 全班 | 仅±1分（卫生值日） | 不可撤销 | 仅自己提交的 | - |
| 志愿委员 | 全班 | 仅加分 | 不可撤销 | 仅自己提交的 | - |
| 学生 | 自己 | 无 | 无 | 自己的历史 | 修改密码 |
| 家长 | 子女总分 | 无 | 无 | 不可见详情 | - |

## 密码要求

- 长度：6-20位
- 复杂度：必须包含大写字母、小写字母、数字、特殊符号中的至少3种
- 示例有效密码：`Hello1!`、`Abc123#`、`Test@99`

## 安装部署

详见 [INSTALL.md](INSTALL.md)

## 使用说明

详细文档：

- 学生端详见 [docs/student.md](docs/student.md)
- 家长端详见 [docs/parent.md](docs/parent.md)
- 班主任详见 [docs/teacher.md](docs/teacher.md)
- 班干部详见 [docs/cadre.md](docs/cadre.md)

快速使用指南：

- [学生端](docs/guide/student.md) / [家长端](docs/guide/parent.md) / [班主任](docs/guide/teacher.md) / [班干部](docs/guide/cadre.md)

## 版本

| 版本 | 发布日期 | 说明 |
|------|---------|------|
| v1.0 | 2026.4.19 | 初始版本发布，包含基础功能 |
| v1.1 | 2026.4.20 | 更新家长端查看加减分记录功能 |
| v1.2 | 2026.4.22 | 学期管理、env配置加减分上限、排行榜百分比筛选、撤销操作日志、调试入口开关 |

## 许可证

本项目使用 [MIT License](LICENSE) 许可证