# 多班级版班级管理系统 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