249 lines
11 KiB
Markdown
249 lines
11 KiB
Markdown
# 班级操行分管理系统
|
||
|
||
基于 Python FastAPI 开发的班级操行分管理系统，支持学生端、管理端、家长端三端访问，实现操行分管理、作业提交跟踪、考勤记录等功能。
|
||
|
||
## 主要功能
|
||
|
||
### 学生端
|
||
- 查询个人当前操行总分
|
||
- 查看个人加减分历史明细（时间、分数变化、原因、操作人）
|
||
- 查看个人作业提交情况
|
||
- 查看个人考勤记录
|
||
- 修改个人登录密码（首次登录强制修改）
|
||
|
||
### 家长端
|
||
- 查询子女当前操行总分和班级排名
|
||
- 查看子女操行分历史记录（加分/减分明细）
|
||
- 查看子女考勤记录
|
||
|
||
### 管理端
|
||
|
||
**班主任权限：**
|
||
- 学生管理：新增/编辑/删除学生、批量导入学生（JSON）
|
||
- 操行分管理：对学生进行加减分、撤销任何扣分记录、查看全班历史记录、导出德育分记录
|
||
- 作业管理：发布作业、查看提交情况
|
||
- 考勤管理：查看全班考勤记录、自定义考勤扣分值
|
||
- 科目管理：动态增删学科
|
||
- 管理员管理：添加/编辑/删除/重置密码班长/科代表/考勤委员/劳动委员/志愿委员
|
||
- 数据导出：导出历史记录、导出德育分记录（含加分/减分历史）
|
||
|
||
**班长权限：**
|
||
- 操行分管理：对学生进行加减分（±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 # 日志模型
|
||
│ │ ├── student.py # 学生模型
|
||
│ │ ├── subject.py # 科目模型
|
||
│ │ └── user.py # 用户模型
|
||
│ │
|
||
│ ├── routes/ # API 路由
|
||
│ │ ├── __init__.py
|
||
│ │ ├── admin.py # 管理端接口
|
||
│ │ ├── auth.py # 认证接口
|
||
│ │ ├── debug.py # 调试入口
|
||
│ │ ├── parent.py # 家长端接口
|
||
│ │ ├── student.py # 学生端接口
|
||
│ │ └── subject.py # 科目管理接口
|
||
│ │
|
||
│ ├── schemas/ # Pydantic 模型
|
||
│ │ ├── __init__.py
|
||
│ │ ├── admin.py
|
||
│ │ ├── auth.py
|
||
│ │ ├── common.py
|
||
│ │ ├── conduct.py
|
||
│ │ ├── parent.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
|
||
│ │ ├── 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 # 修改密码
|
||
│ │ ├── 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 # 公共头部
|
||
│ │
|
||
│ ├── parent/ # 家长端
|
||
│ │ ├── attendance.php # 考勤记录
|
||
│ │ ├── dashboard.php # 家长端首页
|
||
│ │ └── history.php # 历史记录
|
||
│ │
|
||
│ └── student/ # 学生端
|
||
│ ├── attendance.php # 考勤记录
|
||
│ ├── conduct.php # 操行分详情
|
||
│ ├── dashboard.php # 学生端首页
|
||
│ ├── homework.php # 作业情况
|
||
│ └── password.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分 | 可撤销任何记录 | 全班所有记录 | - |
|
||
| 学习委员 | 全班 | 仅扣分（按规则） | 不可撤销 | 仅自己提交的 | 作业管理、科目管理 |
|
||
| 考勤委员 | 全班 | 仅扣分（按规则） | 不可撤销 | 仅自己提交的 | 考勤管理 |
|
||
| 劳动委员 | 全班 | 仅±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 | 更新家长端查看加减分记录功能 |
|
||
|
||
## 许可证
|
||
|
||
本项目使用 [MIT License](LICENSE) 许可证 |