# 学生管理系统 — 业务设计文档

## 1. 业务背景

本系统服务于教育培训机构的日常教务运营，解决以下核心业务问题：
- **学生信息管理**：统一管理学员档案，支持按班级、顾问老师查询
- **教学过程跟踪**：记录各阶段考核成绩，分析学习效果
- **就业数据沉淀**：追踪毕业生去向，统计就业率和薪资水平
- **班级师资配置**：管理班主任、授课老师、助教老师的协作关系

---

## 2. 用户角色

| 角色 | 说明 | 主要操作 |
|------|------|----------|
| 教务管理员 | 系统最高权限，负责全局数据维护 | 全部 CRUD、统计查看 |
| 班主任 | 负责班级管理 | 查看/编辑本班学生、班级信息 |
| 授课老师 | 负责成绩录入 | 录入/修改学生成绩 |
| 顾问老师 | 负责学生职业规划 | 查看所带学生信息、就业状态 |
| 就业专员 | 负责就业数据维护 | 录入/更新就业记录 |

> 当前阶段为内部工具，暂未实现角色权限控制；V2.0 规划接入 OAuth2 + RBAC。

---

## 3. 业务流程

### 3.1 学生入班流程

```
[创建教师] → [创建班级并分配师资] → [录入学生信息并绑定班级]
     │                  │                          │
     └──── 教师编号唯一 ──┘                          └── 学号唯一，班级必填
```

**规则**：
- 新建学生时，`class_id` 必须指向已存在的未删除班级
- `advisor_id`（顾问老师）可选，必须指向有效教师
- 学生编号（`num`）全局唯一

### 3.2 成绩录入流程

```
[选择学生] → [填写考核序次（num）] → [录入分数]
                │
                └── 同一学生同一考核序次不可重复录入（业务约束）
```

**规则**：
- 成绩 `score` 保留两位小数（DECIMAL(10,2)）
- 考核序次（如"第一次考核"、"期中"）由业务方定义，系统不做枚举约束
- 支持按学生 ID 或考核序次模糊查询

### 3.3 就业登记流程

```
[开放就业通道] → [登记就业公司信息] → [下发 Offer] → [记录薪资]
     │                   │                    │
  employment_open    employment_company   offer_received
    _time            _time                time
```

**规则**：
- 一个学生只能有一条有效就业记录（`sid` 唯一约束）
- `employment_open_time` 和 `offer_recived_time` 可为空（流程进行中）
- 平均签约周期 = `offer_recived_time - employment_open_time`（天数）

### 3.4 统计查询流程

```
[请求统计数据] → [按班级/考核序次过滤] → [聚合计算] → [返回统计结果]
```

| 统计类型 | 维度 | 指标 |
|----------|------|------|
| 班级人数统计 | 按班级 | 总人数、男生数、女生数 |
| 成绩统计 | 按考核序次+班级 | 平均分、最高分、最低分、参考人数 |
| 就业统计 | 按班级 | 已就业人数、就业率、平均薪资、平均签约周期 |

---

## 4. 核心业务实体关系

```
┌──────────┐     1:N     ┌──────────┐     1:N     ┌──────────┐
│  Teacher │◄───────────►│  Class   │◄───────────►│ Student  │
│  教师     │ 班主任/授课  │  班级     │  所属班级    │  学生     │
│          │  助教老师    │          │             │          │
└────┬─────┘              └────┬─────┘             └────┬─────┘
     │                         │                       │
     │ 1:N                     │ 1:1                   │ 1:N
     ▼                         ▼                       ▼
┌──────────┐              ┌──────────┐           ┌──────────┐
│  Score   │              │Employment│◄──────────►│ Student  │
│  成绩     │              │  就业     │   一对一    │          │
└──────────┘              └──────────┘           └──────────┘
```

### 关联说明
- **Teacher ↔ Class**：一对多（一个老师可担任多个班级的班主任/授课老师/助教）
- **Class ↔ Student**：一对多（一个班级有多个学生）
- **Student ↔ Score**：一对多（一个学生有多次考核成绩）
- **Student ↔ Employment**：一对一（一个学生只有一条有效就业记录）
- **Teacher ↔ Student**：多对一（一个顾问老师带多个学生）

---

## 5. 业务规则与约束

### 5.1 唯一性约束
| 字段 | 表 | 规则 |
|------|-----|------|
| `num` | teachers | 教师编号全局唯一 |
| `num` | classes | 班级编号全局唯一 |
| `num` | students | 学生编号全局唯一 |
| (sid, num) | scores | 同一学生同一考核序次只允许一条记录 |
| `sid` | employment | 一名学生只允许一条就业记录 |

### 5.2 外键约束（业务层校验）
| 字段 | 引用表 | 级联策略 |
|------|--------|----------|
| `students.class_id` | `classes.id` | 删除班级时限制（restrict），更新级联 |
| `students.advisor_id` | `teachers.id` | 删除教师时置空，更新级联 |
| `classes.head_teacher_id` | `teachers.id` | 同左 |
| `scores.sid` | `students.id` | 删除学生时级联删除成绩 |
| `employment.sid` | `students.id` | 删除学生时级联删除就业记录 |

### 5.3 软删除规则
- 所有表均支持软删除（`is_deleted = true` + `delete_time` 记录时间）
- 所有查询默认过滤 `is_deleted = false`
- 软删除不影响关联数据（成绩/就业随学生级联删除）

---

## 6. 统计业务逻辑详细说明

### 6.1 班级人数统计（`GET /api/stats/classes`）
```
SELECT class_id, class_name, COUNT(*) as total,
       SUM(CASE WHEN sex=1 THEN 1 ELSE 0 END) as male_count,
       SUM(CASE WHEN sex=2 THEN 1 ELSE 0 END) as female_count
FROM students s JOIN classes c ON s.class_id = c.id
WHERE s.is_deleted=0 AND c.is_deleted=0
GROUP BY s.class_id, c.name
```

### 6.2 成绩统计（`GET /api/stats/scores?class_id=&score_num=`）
```
SELECT score_num, class_id, AVG(score), MAX(score), MIN(score), COUNT(*)
FROM scores sc JOIN students s ON sc.sid = s.id
WHERE s.is_deleted=0 AND sc.is_deleted=0
GROUP BY score_num, class_id
[可选过滤 class_id / score_num]
```

### 6.3 就业统计（`GET /api/stats/employment?class_id=`）
```
SELECT e.class_id, c.name,
       COUNT(e.id) as employed_count,
       COUNT(s.id) as total_count,
       AVG(e.employment_salary) as avg_salary
FROM employment e
JOIN classes c ON e.class_id = c.id
JOIN students s ON e.sid = s.id
WHERE e.is_deleted=0 AND s.is_deleted=0 AND c.is_deleted=0
GROUP BY e.class_id, c.name
[可选过滤 class_id]

-- 额外计算：平均签约周期（天数）
AVG(JULIANDAY(offer_recived_time) - JULIANDAY(employment_open_time))
WHERE employment_open_time IS NOT NULL AND offer_recived_time IS NOT NULL
```

---

## 7. 数据字典（待 V2.0 实现）

以下字段当前以字符串或整数存储，建议 V2.0 升级为字典表管理：

| 字段 | 当前存储 | 建议字典类型 | 候选值 |
|------|----------|-------------|--------|
| `sex` | TINYINT (0/1/2) | dict_type=sex | 0:未知, 1:男, 2:女 |
| `education` | VARCHAR | dict_type=education | bachelor:本科, master:硕士, phd:博士 |
| `coach_area` | VARCHAR | dict_type=coach_area | app:应用, project:项目, algorithm:算法 |
| `college` | VARCHAR | dict_type=college | 院校代码 → 名称映射 |
| `specialty` | VARCHAR | dict_type=specialty | 专业代码 → 名称映射 |

---

## 8. 分期业务规划

| 阶段 | 业务目标 | 功能范围 |
|------|----------|----------|
| V1.0（当前）| 基础数据管理 | 五模块 CRUD + 三类统计 |
| V2.0 | 数据治理与权限 | 字典表、用户认证、部门/顾问模块、数据源配置 |
| V3.0 | 智能分析 | AI 知识库接入、自然语言查询、预测分析 |
| V4.0 | 多租户 SaaS | 租户隔离、多机构支持、API 开放平台 |