12 KiB
12 KiB
班级操行分管理系统
基于 Python FastAPI 开发的班级操行分管理系统，支持学生端、管理端、家长端三端访问，实现操行分管理、作业提交跟踪、考勤记录等功能。
主要功能
学生端
- 查询个人当前操行总分
- 查看个人加减分历史明细（时间、分数变化、原因、操作人）
- 查看个人作业提交情况
- 查看个人考勤记录
- 查看历史学期归档数据（操行分、考勤统计、作业统计）
- 修改个人登录密码（首次登录强制修改）
家长端
- 查询子女当前操行总分和班级排名
- 查看子女操行分历史记录（加分/减分明细）
- 查看子女考勤记录
- 默认仅显示当前学期数据
管理端
班主任权限：
- 学生管理：新增/编辑/删除学生、批量导入学生（JSON）
- 操行分管理：对学生进行加减分、撤销任何扣分记录、查看全班历史记录、导出德育分记录
- 作业管理：发布作业、查看提交情况
- 考勤管理：按时段（早上 7:15/中午 14:00/晚修 19:30）记录考勤、自定义考勤扣分值
- 科目管理：动态增删学科
- 管理员管理：添加/编辑/删除/重置密码班长/科代表/考勤委员/劳动委员/志愿委员
- 学期管理：创建/编辑/删除学期、激活学期、归档学期（含考勤/作业统计快照）、关联历史记录、归档后可选重置分数
- 排行榜百分比筛选：在排行榜上方输入百分比，筛选显示前N%的学生（抹零法）
- 数据导出：导出历史记录、导出德育分记录（含加分/减分历史）
班长权限：
- 操行分管理：对学生进行加减分（±5分以内）、撤销任何人的扣分记录、查看全班历史记录
学习委员权限：
- 作业管理：更新作业提交状态、关联扣分（仅扣分，按规则）
- 科目管理：动态增删学科
- 历史记录：仅查看自己提交的操作记录
考勤委员权限：
- 考勤管理：按时段（早上 7:15/中午 14:00/晚修 19:30）记录考勤状态、关联扣分（仅扣分，按规则）
- 历史记录：仅查看自己提交的操作记录
劳动委员权限：
- 操行分管理：以卫生值日为理由进行加减分（固定 ±1 分）
- 历史记录：仅查看自己提交的操作记录
志愿委员权限：
- 操行分管理：以服务时长为由进行加分（仅加分）
- 历史记录：仅查看自己提交的操作记录
技术栈
安全特性
- JWT Token + PHP Session 双轨制认证
- Redis 管理登录态，支持空闲超时自动失效
- 全链路输入校验：Pydantic Schema 层（正则/长度/范围约束）+ Service 层（业务逻辑校验）
- 输入过滤中间件（XSS/SQL 注入防护）
- 密码 bcrypt 加密存储
- 操作日志记录
技术栈
| 层级 | 技术 | 版本 |
|---|---|---|
| 后端框架 | 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
使用说明
详细文档：
- 学生端详见 docs/student.md
- 家长端详见 docs/parent.md
- 班主任详见 docs/teacher.md
- 班干部详见 docs/cadre.md
快速使用指南：
版本
| 版本 | 发布日期 | 说明 |
|---|---|---|
| v1.0 | 2026.4.19 | 初始版本发布，包含基础功能 |
| v1.1 | 2026.4.20 | 更新家长端查看加减分记录功能 |
| v1.2 | 2026.4.22 | 学期管理、env配置加减分上限、排行榜百分比筛选、撤销操作日志、调试入口开关 |
| v1.3 | 2026.4.27 | 考勤时段系统（早上/中午/晚修三时段）、历史记录扣分类型筛选、管理员/科目信息编辑、全链路输入安全校验 |
| v1.4 | 2026.4.28 | 全量代码审查修复：双重密码哈希bug、学生端XSS漏洞、性能优化、Pydantic schema统一、权限检查补全、考勤委员撤销权限 |
| v1.5 | 2026.4.29 | 用户反馈修复：登录封禁5分钟+手动解锁、加减分回显修复、学习委员5分限制修复、按钮样式补全 |
许可证
本项目使用 MIT License 许可证