canglan/SharedClassManager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 多班级版 v2.0 - Go后端重写 + 43轮代码审查

Browse Source 
- 后端从 Python FastAPI 重写为 Go Gin（端口 56789）
- 多班级完全隔离
- 超级管理员独立登录
- 课代表作业管理、排行榜分项排行
- 角色加减分上下限可配置
- 家长改密功能（可开关）
- 周度/月度重置功能
- MySQL 5.7 兼容
- 43轮代码审查+全部修复
- Apache 2.0 许可证
This commit is contained in:
canglan
2026-06-22 10:06:10 +08:00
parent 4084afc53c
commit d6dec878bd
214 changed files with 12622 additions and 9725 deletions
Download Patch File Download Diff File Expand all files Collapse all files

430
README.md
View File

@@ -1,285 +1,233 @@
# 班级操行分管理系统
# 多班级版班级管理系统 v1.0
基于 Python FastAPI 开发的班级操行分管理系统，支持学生端、管理端、家长端三端访问，实现操行分管理、作业提交跟踪、考勤记录等功能。
基于 Go (Gin + GORM) + PHP + MySQL 5.7 + Redis 开发的多班级操行分管理系统，支持多班级完全隔离，包含系统管理员、学生、管理端、家长端四端访问。
## 主要功能
## 技术栈
### 学生端
- 查询个人当前操行总分
- 查看个人加减分历史明细（时间、分数变化、原因、操作人）
- 查看个人作业提交情况
- 查看个人考勤记录
- 查看历史学期归档数据（操行分、考勤统计、作业统计）
- 修改个人登录密码（首次登录强制修改）
| 层级 | 技术 | 说明 |
|------|------|------|
| 后端 API | **Go (Gin + GORM)** | 高性能、编译型、并发友好，适合中小规模管理系统 |
| 数据库 | **MySQL 5.7+** | 成熟稳定、事务支持完善、utf8mb4 全字符集支持 |
| 缓存 | **Redis 6.0+** | Token 管理、登录限流、会话缓存 |
| 前端 | **PHP 8.0+ + JavaScript** | 零构建依赖、部署简单、与后端 API 解耦，适合校园网络环境 |
### 家长端
- 查询子女当前操行总分和班级排名
- 查看子女操行分历史记录（加分/减分明细）
- 查看子女考勤记录
- 默认仅显示当前学期数据
## 功能特性
### 管理端
### 系统管理员（super_admin）
- 独立登录入口（路径可配置）
- 班级管理：创建/编辑/删除/启用禁用班级
- 切换班级上下文：在不同班级间切换进行管理操作
- 跨班级查看：查看所有班级的管理员和学生列表
- 首次启动自动创建，无需手动初始化
### 管理端（班级内角色）
**班主任权限：**
- 学生管理：新增/编辑/删除学生、批量导入学生（JSON）
- 操行分管理：对学生进行加减分、撤销任何扣分记录、查看全班历史记录、导出德育分记录
- 操行分管理：对学生进行加减分（无限制）、撤销任何扣分记录、查看全班历史记录
- 作业管理：发布作业、查看提交情况
- 考勤管理：按时段（早上 7:15/中午 14:00/晚修 19:30）记录考勤、自定义考勤扣分值
- 考勤管理：按时段（早上/中午/晚修）记录考勤
- 科目管理：动态增删学科
- 管理员管理：添加/编辑/删除/重置密码班长/科代表/考勤委员/劳动委员/志愿委员
- 学期管理：创建/编辑/删除学期、激活学期、归档学期（含考勤/作业统计快照）、关联历史记录、归档后可选重置分数
- 排行榜百分比筛选：在排行榜上方输入百分比，筛选显示前N%的学生（抹零法）
- 数据导出：导出历史记录、导出德育分记录（含加分/减分历史）
- 管理员管理：添加/编辑/删除班干部、科任老师、课代表
- 学期管理：创建/编辑/删除/激活/归档学期
- 班级设置：修改扣分规则、功能开关、角色权限、加减分限制
- 排行榜：查看分项排行（操行分、作业、考勤）
- 数据导出：导出德育分记录、历史记录
**科任老师权限（需配置科目）：**
- 对所教科目学生进行加减分（±5分以内，可在班级设置中配置）
- 查看所教科目的作业管理
- 查看全班历史记录
**班长权限：**
- 操行分管理：对学生进行加减分（±5分以内）、撤销任何人的扣分记录、查看全班历史记录
- 对学生进行加减分（±5分以内，可在班级设置中配置）
- 撤销任何操行分记录
- 查看全班历史记录
**学习委员权限：**
- 作业管理：更新作业提交状态、关联扣分（仅扣分，按规则）
- 科目管理：动态增删学科
- 历史记录：仅查看自己提交的操作记录
- 对学生进行加减分（±5分以内，可在班级设置中配置）
- 科目管理
- 作业管理
**考勤委员权限：**
- 考勤管理：按时段（早上 7:15/中午 14:00/晚修 19:30）记录考勤状态、关联扣分（仅扣分，按规则）
- 历史记录：仅查看自己提交的操作记录
- 考勤管理
- 考勤扣分（仅扣分，上限8分）
- 可撤销自己创建的记录
**劳动委员权限：**
- 操行分管理：以卫生值日为理由进行加减分（固定 ±1 分）
- 历史记录：仅查看自己提交的操作记录
- 对学生进行加减分（±1分以内）
**志愿委员权限：**
- 操行分管理：以服务时长为由进行加分（仅加分）
- 历史记录：仅查看自己提交的操作记录
- 仅可加分（上限5分）
- 查看全班历史记录
## 技术栈
## 安全特性
**课代表权限：**
- 管理所代表科目的作业（管理端页面）
- 由学习委员/班主任/科任老师设定
- 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+ |
## 文件结构
## 角色权限矩阵
| 功能 | 班主任 | 科任老师 | 班长 | 学习委员 | 考勤委员 | 劳动委员 | 志愿委员 | 课代表 |
|------|--------|---------|------|---------|---------|---------|---------|--------|
| 操行分管理 | ✓ 无限制 | ±5分 | ±5分 | ±5分 | 仅扣分 | ±1分 | 仅加分 | - |
| 历史记录 | 全部(可撤销) | 自己的 | 全部(可撤销) | 自己的 | 自己的 | 自己的 | 自己的 | - |
| 作业管理 | ✓ | 所教科目 | - | ✓ | - | - | - | 所教科目 |
| 考勤管理 | ✓ | - | - | - | ✓ | - | - | - |
| 科目管理 | ✓ | - | - | ✓ | - | - | - | - |
| 学生管理 | ✓ | - | - | - | - | - | - | - |
| 管理员管理 | ✓ | - | - | - | - | - | - | - |
| 学期管理 | ✓ | - | - | - | - | - | - | - |
| 班级设置 | ✓ | - | - | - | - | - | - | - |
| 排行榜 | ✓ | - | - | - | - | - | - | - |
> 加减分上下限可在班级设置中由班主任自行配置。
## 多班级隔离机制
```
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 # 项目说明
系统管理员 (super_admin)
├── JWT 中 class_id 可变（通过 /api/class/switch 切换）
├── 可管理所有班级
└── 权限检查自动放行
班级管理员 (admin) — 班主任/班长/科任老师/课代表等
├── admin_roles 绑定 class_id
├── JWT 中 class_id 固定
├── 所有查询自动过滤 class_id
└── 严格隔离在本班内
学生/家长
├── 通过 student.class_id 确定所属班级
└── 只能看到本班数据
```
## 角色权限一览表
## 班级设置
| 角色 | 操行分查看 | 操行分加减 | 撤销扣分 | 历史记录查看 | 其他权限 |
|------|-----------|-----------|---------|-------------|---------|
| 班主任 | 全班 | 无限制 | 可撤销任何记录 | 全班所有记录 | 学生/管理员/科目管理、数据导出 |
| 班长 | 全班 | ±5分 | 可撤销任何记录 | 全班所有记录 | - |
| 学习委员 | 全班 | ±5分以内（加减分） | 不可撤销 | 仅自己提交的 | 作业管理、科目管理 |
| 考勤委员 | 全班 | 仅扣分，最多扣8分 | 不可撤销 | 仅自己提交的 | 考勤管理 |
| 劳动委员 | 全班 | ±1分以内 | 不可撤销 | 仅自己提交的 | - |
| 志愿委员 | 全班 | 仅加分，最多+5分 | 不可撤销 | 仅自己提交的 | - |
| 学生 | 自己 | 无 | 无 | 自己的历史 | 修改密码 |
| 家长 | 子女总分 | 无 | 无 | 不可见详情 | - |
每个班级可独立配置以下内容（班主任可在管理端修改）：
## 密码要求
### 扣分规则
| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| student_initial_points | 学生初始操行分 | 60 |
| deduction_homework_not_submit | 作业未提交扣分 | 2 |
| deduction_homework_late | 作业迟交扣分 | 1 |
| deduction_attendance_absent | 缺勤扣分 | 3 |
| deduction_attendance_late | 迟到扣分 | 1 |
| deduction_attendance_leave | 请假扣分 | 0 |
- 长度：6-20位
- 复杂度：必须包含大写字母、小写字母、数字、特殊符号中的至少3种
- 示例有效密码：`Hello1!`、`Abc123#`、`Test@99`
### 功能开关
| 功能标识 | 说明 | 默认 |
|----------|------|------|
| homework | 作业管理 | 启用 |
| attendance | 考勤管理 | 启用 |
| ranking | 排行榜 | 启用 |
| dormitory | 宿舍管理 | 启用 |
| parent_password | 家长改密功能 | 启用 |
## 安装部署
### 角色开关
班主任可在班级设置中启用或禁用各角色（班长、学习委员、考勤委员、劳动委员、志愿委员、科任老师、课代表），禁用后该角色不可被分配。
详见 [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)
排行榜支持百分比筛选（如显示前 10% 的学生）。
快速使用指南：
## 超级管理员独立登录
- [学生端](docs/guide/student.md) / [家长端](docs/guide/parent.md) / [班主任](docs/guide/teacher.md) / [班干部](docs/guide/cadre.md)
超级管理员通过独立路径登录，与普通用户登录入口分离：
- 登录路径通过 `.env` 中的 `SUPER_ADMIN_LOGIN_PATH` 配置
- 默认路径：`/super-admin/login`
- 首次启动自动创建，默认账号：`admin` / `Admin123`
## 版本
## 家长登录账号
| 版本 | 发布日期 | 说明 |
|------|---------|------|
| 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 | 2026.5.26 | CSS变量化统一配色方案、简化按钮系统、操作列按钮风格统一、清理内联颜色、修复科目管理面板无法展开、数据库索引优化、清理init.sql冗余迁移代码、安全审计通过 |
| v2.2 | 2026.5.27 | 安全修复：管理员操作越权漏洞修复、新增宿舍集体加分功能、学生导入支持宿舍号、导入预览显示宿舍号列 |
| v2.3 | 2026.5.28 | 升级系统全面重构：修复前后端通信错误处理、SQL DELIMITER解析修复、XSS防护、升级验证+自动重试+失败回滚机制、补全v1.0-v1.6增量升级脚本 |
| v2.5 | 2026.5.28 | 历史记录页优化（文字宽度/换行/合并按钮样式）、新增状态筛选项、合并记录批量撤销/反撤销、操作菜单底部遮挡修复、删除科目报错修复、学期自动关联+当前周数计算 |
| v2.5.1 | 2026.5.29 | 筛选学生时自动取消合并记录、合并记录选项样式修复（竖排显示）、历史记录筛选改为折叠式、科目管理调用修复、全局escapeHtml XSS转义修复 |
| v2.6 | 2026.5.29 | 历史记录筛选面板重构（学生筛选移入面板、合并按钮始终可见）、新增科目下拉筛选、新增原因关键词搜索、科目删除后默认仅显示启用科目、筛选面板展开修复 |
| v2.7 | 2026.5.29 | 操作菜单定位修复、历史记录显示修复、筛选面板修复、科目删除修复、学期周数列修复、escapeHtml 转义修复 |
学生导入时，`parent_account` 字段为家长登录账号，**推荐填写手机号**。系统会自动为该账号创建家长用户，初始密码与学生相同（默认 `123456`）。
示例导入 JSON 格式：
```json
{
"students": [
{
"student_no": "2025001",
"name": "张三",
"parent_account": "13800138001",
"dormitory_number": "A301",
"password": "123456"
}
]
}
```
## 快速开始
详细部署指南请参阅 [INSTALL.md](INSTALL.md)。
### 环境要求
- Go 1.21+
- MySQL 5.7+
- Redis 6.0+
- Nginx 1.18+
- PHP 8.0+
### 安装步骤
1. 克隆项目
```bash
git clone https://hz-gitea.sea-studio.top/canglan/SharedClassManager.git
cd SharedClassManager
```
2. 初始化数据库
```bash
mysql -u root -p < sql/init.sql
```
3. 配置并启动 Go 后端
```bash
cd backend-go
cp .env.example .env
vim .env # 修改配置
go mod tidy
go build -o sharedclassmanager ./cmd/server
./sharedclassmanager
```
4. 配置前端
```bash
cd frontend
cp .env.example .env
# 编辑 .env 文件，配置 API 地址
```
5. 配置 Nginx 反向代理（参考 [INSTALL.md](INSTALL.md)）
## 许可证
本项目使用 [MIT License](LICENSE) 许可证
本项目采用 [Apache License 2.0](LICENSE) 许可证。
Copyright 2025 Sea Network Technology Studio
## 开发者
Canglan — admin@sea-studio.top