feat: 多班级版班级管理系统 v2.0

技术栈：Go (Gin + GORM) + PHP + MySQL 5.7 + Redis 主要功能： - 多班级完全隔离（class_id 贯穿全系统） - 后端 Go Gin（端口 56789），Nginx 反代 - 超级管理员独立登录（env 配置，默认账密 admin/Admin123） - bcrypt 密码加密（无 PASSWORD_SALT） - 科任老师/课代表新角色 - 课代表作业管理页面 - 排行榜分项排行（操行分/考勤/作业） - 角色加减分上下限由班主任配置 - 家长改密功能（可开关） - 班级角色按需开关 - 宿舍号格式：南0-000 - 周度/月度重置功能 - MySQL 5.7 兼容 - 43 轮代码审查 + 全部修复开发者: Canglan 版权归属: Sea Network Technology Studio 许可证: Apache License 2.0
2026-06-22 10:21:52 +08:00
commit c6db68a9f4
135 changed files with 19933 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,233 @@
+# 多班级版班级管理系统 v1.0
+
+基于 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）
+- 操行分管理：对学生进行加减分（无限制）、撤销任何扣分记录、查看全班历史记录
+- 作业管理：发布作业、查看提交情况
+- 考勤管理：按时段（早上/中午/晚修）记录考勤
+- 科目管理：动态增删学科
+- 管理员管理：添加/编辑/删除班干部、科任老师、课代表
+- 学期管理：创建/编辑/删除/激活/归档学期
+- 班级设置：修改扣分规则、功能开关、角色权限、加减分限制
+- 排行榜：查看分项排行（操行分、作业、考勤）
+- 数据导出：导出德育分记录、历史记录
+
+**科任老师权限（需配置科目）：**
+- 对所教科目学生进行加减分（±5分以内，可在班级设置中配置）
+- 查看所教科目的作业管理
+- 查看全班历史记录
+
+**班长权限：**
+- 对学生进行加减分（±5分以内，可在班级设置中配置）
+- 撤销任何操行分记录
+- 查看全班历史记录
+
+**学习委员权限：**
+- 对学生进行加减分（±5分以内，可在班级设置中配置）
+- 科目管理
+- 作业管理
+
+**考勤委员权限：**
+- 考勤管理
+- 考勤扣分（仅扣分，上限8分）
+- 可撤销自己创建的记录
+
+**劳动委员权限：**
+- 对学生进行加减分（±1分以内）
+
+**志愿委员权限：**
+- 仅可加分（上限5分）
+- 查看全班历史记录
+
+**课代表权限：**
+- 管理所代表科目的作业（管理端页面）
+- 由学习委员/班主任/科任老师设定
+
+### 学生端
+- 查询个人当前操行总分和班级排名
+- 查看个人加减分历史明细
+- 查看个人作业提交情况
+- 查看个人考勤记录
+- 查看历史学期归档数据
+- 修改个人登录密码
+
+### 家长端
+- 查询子女当前操行总分和班级排名
+- 查看子女操行分历史记录
+- 查看子女考勤记录
+- 修改密码（受班级功能开关控制）
+
+## 角色权限矩阵
+
+| 功能 | 班主任 | 科任老师 | 班长 | 学习委员 | 考勤委员 | 劳动委员 | 志愿委员 | 课代表 |
+|------|--------|---------|------|---------|---------|---------|---------|--------|
+| 操行分管理 | ✓ 无限制 | ±5分 | ±5分 | ±5分 | 仅扣分 | ±1分 | 仅加分 | - |
+| 历史记录 | 全部(可撤销) | 自己的 | 全部(可撤销) | 自己的 | 自己的 | 自己的 | 自己的 | - |
+| 作业管理 | ✓ | 所教科目 | - | ✓ | - | - | - | 所教科目 |
+| 考勤管理 | ✓ | - | - | - | ✓ | - | - | - |
+| 科目管理 | ✓ | - | - | ✓ | - | - | - | - |
+| 学生管理 | ✓ | - | - | - | - | - | - | - |
+| 管理员管理 | ✓ | - | - | - | - | - | - | - |
+| 学期管理 | ✓ | - | - | - | - | - | - | - |
+| 班级设置 | ✓ | - | - | - | - | - | - | - |
+| 排行榜 | ✓ | - | - | - | - | - | - | - |
+
+> 加减分上下限可在班级设置中由班主任自行配置。
+
+## 多班级隔离机制
+
+```
+系统管理员 (super_admin)
+├── JWT 中 class_id 可变（通过 /api/class/switch 切换）
+├── 可管理所有班级
+└── 权限检查自动放行
+
+班级管理员 (admin) — 班主任/班长/科任老师/课代表等
+├── admin_roles 绑定 class_id
+├── JWT 中 class_id 固定
+├── 所有查询自动过滤 class_id
+└── 严格隔离在本班内
+
+学生/家长
+├── 通过 student.class_id 确定所属班级
+└── 只能看到本班数据
+```
+
+## 班级设置
+
+每个班级可独立配置以下内容（班主任可在管理端修改）：
+
+### 扣分规则
+| 配置项 | 说明 | 默认值 |
+|--------|------|--------|
+| 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 |
+
+### 功能开关
+| 功能标识 | 说明 | 默认 |
+|----------|------|------|
+| homework | 作业管理 | 启用 |
+| attendance | 考勤管理 | 启用 |
+| ranking | 排行榜 | 启用 |
+| dormitory | 宿舍管理 | 启用 |
+| parent_password | 家长改密功能 | 启用 |
+
+### 角色开关
+班主任可在班级设置中启用或禁用各角色（班长、学习委员、考勤委员、劳动委员、志愿委员、科任老师、课代表），禁用后该角色不可被分配。
+
+### 加减分限制
+班主任可在班级设置中配置各角色的加减分上下限，灵活控制权限范围。
+
+## 排行榜分项排行
+
+管理端排行榜支持以下分项查看：
+- **操行分排行**：按当前操行分排名
+- **作业排行**：按作业完成情况排名
+- **考勤排行**：按出勤率排名
+
+排行榜支持百分比筛选（如显示前 10% 的学生）。
+
+## 超级管理员独立登录
+
+超级管理员通过独立路径登录，与普通用户登录入口分离：
+- 登录路径通过 `.env` 中的 `SUPER_ADMIN_LOGIN_PATH` 配置
+- 默认路径：`/super-admin/login`
+- 首次启动自动创建，默认账号：`admin` / `Admin123`
+
+## 家长登录账号
+
+学生导入时，`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)）
+
+## 许可证
+
+本项目采用 [Apache License 2.0](LICENSE) 许可证。
+
+Copyright 2025 Sea Network Technology Studio
+
+## 开发者
+
+Canglan — admin@sea-studio.top