279 lines
13 KiB
Markdown
279 lines
13 KiB
Markdown
# 班级操行分管理系统
|
||
|
||
基于 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 加密存储
|
||
- 操作日志记录
|
||
|
||
## 技术栈
|
||
|
||
| 层级 | 技术 | 版本 |
|
||
|------|------|------|
|
||
| 后端 | Python | 3.13.x |
|
||
| 后端框架 | 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分以内（加减分） | 不可撤销 | 仅自己提交的 | 作业管理、科目管理 |
|
||
| 考勤委员 | 全班 | 仅扣分，最多扣8分 | 不可撤销 | 仅自己提交的 | 考勤管理 |
|
||
| 劳动委员 | 全班 | ±1分以内 | 不可撤销 | 仅自己提交的 | - |
|
||
| 志愿委员 | 全班 | 仅加分，最多+5分 | 不可撤销 | 仅自己提交的 | - |
|
||
| 学生 | 自己 | 无 | 无 | 自己的历史 | 修改密码 |
|
||
| 家长 | 子女总分 | 无 | 无 | 不可见详情 | - |
|
||
|
||
## 密码要求
|
||
|
||
- 长度：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配置加减分上限、排行榜百分比筛选、撤销操作日志、调试入口开关 |
|
||
| v1.3 | 2026.4.27 | 考勤时段系统（早上/中午/晚修三时段）、历史记录扣分类型筛选、管理员/科目信息编辑、全链路输入安全校验 |
|
||
| v1.4 | 2026.4.28 | 全量代码审查修复：双重密码哈希bug、学生端XSS漏洞、性能优化、Pydantic schema统一、权限检查补全、考勤委员撤销权限 |
|
||
| v1.5 | 2026.4.29 | 登录错误封禁5分钟+手动解锁、加减分回显修复、权限限制修复、按钮样式补全 |
|
||
| v1.6 | 2026.4.29 | 权限修复：考勤委员提示遗漏、历史记录权限泄露、时间筛选失效、作业页分数限制与后端同步 |
|
||
| v1.7 | 2026.5.21 | 全量一致性审计：前后端配置统一（.env.example/config.py/config.php）、清理废弃全局变量、角色权限表精确化 |
|
||
| v1.8 | 2026.5.22 | 科目管理融入作业管理页、科目删除数据依赖检查、加减分记录类型区分（manual/homework/attendance）、学生端作业详情优化 |
|
||
| v2.0.1 | 2026.5.23 | 操作列折叠优化、扣分类型大类区分、科目选择修复、改名作业扣分、记录人优化、家长端优化、学期管理优化 |
|
||
| v2.1 | 2025.7.14 | CSS变量化统一配色方案、简化按钮系统、操作列按钮风格统一、清理内联颜色、修复科目管理面板无法展开、数据库索引优化、清理init.sql冗余迁移代码、安全审计通过 |
|
||
|
||
## 许可证
|
||
|
||
本项目使用 [MIT License](LICENSE) 许可证 |