# 学生管理模块 - 技术方案 --- | 文档信息 | 内容 | |---------|------| | **文档版本** | V1.0 | | **项目名称** | 盘古用户平台（Pangu User Platform） | | **模块名称** | 学生管理模块 | | **编写团队** | pangu | | **创建日期** | 2026-01-31 | | **审核状态** | 待审核 | --- ## 修订记录 | 版本 | 日期 | 修订人 | 修订内容 | |------|------|--------|----------| | V1.0 | 2026-01-31 | pangu | 初稿 | --- ## 目录 1. [模块概述](#1-模块概述) 2. [功能清单](#2-功能清单) 3. [业务流程](#3-业务流程) 4. [业务规则](#4-业务规则) 5. [数据模型](#5-数据模型) 6. [接口设计概览](#6-接口设计概览) 7. [技术架构](#7-技术架构) 8. [开发计划](#8-开发计划) 9. [风险分析](#9-风险分析) 10. [验收标准](#10-验收标准) --- ## 1. 模块概述 ### 1.1 模块定位 学生管理模块是盘古用户平台的核心业务模块之一，负责管理学生基本信息、学生与会员的绑定关系、以及支持批量导入功能。该模块为其他业务系统（如AI智慧平台）提供学生数据查询服务。 ### 1.2 模块边界 ``` ┌────────────────────────────────────────────────────────────────┐ │ 学生管理模块 │ ├────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌────────────────┐ │ │ │ 学生列表查询 │ │ 学生信息维护 │ │ 批量导入 │ │ │ │ - 多条件筛选 │ │ - 新增学生 │ │ - 模板下载 │ │ │ │ - 学校树筛选 │ │ - 编辑学生 │ │ - Excel导入 │ │ │ │ - 分页查询 │ │ - 删除学生 │ │ - 数据校验 │ │ │ └─────────────────┘ └─────────────────┘ └────────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ 数据关联 │ │ │ │ - 学生 → 会员（归属关系） │ │ │ │ - 学生 → 学校/年级/班级（组织关系） │ │ │ │ - 学生 → 学科（教学关系） │ │ │ └──────────────────────────────────────────────────────────┘ │ └────────────────────────────────────────────────────────────────┘ │ ┌─────────────────┼─────────────────┐ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ 会员模块 │ │ 学校模块 │ │ 开放API │ └──────────┘ └──────────┘ └──────────┘ ``` ### 1.3 用户角色 | 角色 | 权限范围 | |------|----------| | **超级管理员** | 查看/管理所有学生数据 | | **分公司用户** | 查看/管理所属区域的学生数据 | | **学校用户** | 查看/管理本校学生数据 | ### 1.4 相关文档 | 文档 | 路径 | 说明 | |------|------|------| | 需求规格说明书 | docs/01-需求文档/需求规格说明书_v1.0.md | 第4.3章 学生管理 | | 系统设计文档 | docs/02-系统设计/系统设计文档_v1.0.md | 整体架构设计 | | 数据库设计文档 | docs/03-数据库设计/数据库设计文档_v1.0.md | pg_student表 | | 接口设计文档 | docs/04-接口文档/接口设计文档_v1.0.md | 第5章 学生管理接口 | | 墨刀原型 | https://modao.cc/proto/atlwMul8t9pi6yxQ42W7up/sharing | 学生管理页面 | --- ## 2. 功能清单 ### 2.1 功能列表 | 功能编号 | 功能名称 | 功能描述 | 优先级 | 复杂度 | |---------|---------|----------|:------:|:------:| | STU-001 | 学生列表查询 | 按姓名、学号、性别、手机号、学科等筛选 | P0 | 中 | | STU-002 | 学校树筛选 | 通过左侧学校树快速定位学生 | P0 | 中 | | STU-003 | 新增学生 | 手动创建学生信息 | P0 | 低 | | STU-004 | 编辑学生 | 修改学生基本信息 | P0 | 低 | | STU-005 | 删除学生 | 软删除学生信息 | P1 | 低 | | STU-006 | 批量导入 | 通过Excel模板批量导入学生 | P0 | 高 | | STU-007 | 下载导入模板 | 下载标准Excel导入模板 | P0 | 低 | ### 2.2 功能依赖 ``` ┌─────────────────────────────────────────────────────────┐ │ 功能依赖关系 │ ├─────────────────────────────────────────────────────────┤ │ │ │ STU-001 学生列表查询 │ │ ├── 依赖：区域树数据（区域模块） │ │ ├── 依赖：学校树数据（学校模块） │ │ └── 依赖：学科列表（学科模块） │ │ │ │ STU-002 学校树筛选 │ │ └── 依赖：学校-年级-班级树形结构（学校模块） │ │ │ │ STU-003/004 新增/编辑学生 │ │ ├── 依赖：区域级联选择器 │ │ ├── 依赖：学校-年级-班级级联选择器 │ │ ├── 依赖：学科下拉列表 │ │ └── 依赖：会员选择器（会员模块） │ │ │ │ STU-006 批量导入 │ │ ├── 依赖：区域数据校验 │ │ ├── 依赖：学校数据校验 │ │ └── 依赖：会员自动创建（会员模块） │ │ │ └─────────────────────────────────────────────────────────┘ ``` --- ## 3. 业务流程 ### 3.1 学生信息维护流程 ``` ┌─────────────────────────────────────────────────────────────────┐ │ 学生信息维护流程 │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ 用户 ──► 选择学校树节点 ──► 查看学生列表 │ │ │ │ │ ┌───────────────────────┼───────────────────────┐ │ │ ▼ ▼ ▼ │ │ 新增学生 编辑学生 删除学生 │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ 填写学生信息 修改学生信息 确认删除 │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ 选择归属会员 保存修改 软删除处理 │ │ │ │ │ │ │ ▼ │ │ │ │ 保存学生信息 │ │ │ │ │ │ │ │ │ └───────────────────────┴───────────────────────┘ │ │ │ │ │ ▼ │ │ 刷新列表数据 │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ### 3.2 批量导入流程 ``` ┌─────────────────────────────────────────────────────────────────┐ │ 批量导入流程 │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────┐ ┌──────────────┐ ┌─────────────────────┐ │ │ │ 下载模板 │───▶│ 填写学生数据 │───▶│ 上传Excel文件 │ │ │ └──────────┘ └──────────────┘ └──────────┬──────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────┐ │ │ │ 解析Excel文件 │ │ │ └──────────┬──────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────┐ │ │ │ 数据格式校验 │ │ │ │ - 必填字段检查 │ │ │ │ - 数据格式检查 │ │ │ └──────────┬──────────┘ │ │ │ │ │ ┌──────────────┴──────────┐ │ │ ▼ ▼ │ │ ┌─────────────┐ ┌──────────┐│ │ │ 格式错误 │ │ 格式正确 ││ │ │ 返回错误信息│ │ 继续处理 ││ │ └─────────────┘ └────┬─────┘│ │ │ │ │ ▼ │ │ ┌─────────────────┐│ │ │ 业务数据校验 ││ │ │ - 区域/学校匹配 ││ │ │ - 学号唯一性 ││ │ └───────┬─────────┘│ │ │ │ │ ▼ │ │ ┌─────────────────┐│ │ │ 处理会员关联 ││ │ │ - 手机号已存在: ││ │ │ 挂载到已有会员 ││ │ │ - 手机号不存在: ││ │ │ 创建新会员 ││ │ └───────┬─────────┘│ │ │ │ │ ▼ │ │ ┌─────────────────┐│ │ │ 批量保存学生 ││ │ └───────┬─────────┘│ │ │ │ │ ▼ │ │ ┌─────────────────┐│ │ │ 返回导入结果 ││ │ │ - 成功数量 ││ │ │ - 失败数量及原因 ││ │ └─────────────────┘│ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ### 3.3 数据权限控制流程 ``` ┌─────────────────────────────────────────────────────────────────┐ │ 数据权限控制流程 │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ 请求进入 ──► 获取当前用户角色 │ │ │ │ │ ┌───────────┼───────────┬───────────┐ │ │ ▼ ▼ ▼ ▼ │ │ 超级管理员 分公司用户 学校用户 其他用户 │ │ │ │ │ │ │ │ ▼ ▼ ▼ ▼ │ │ 无限制 按区域过滤 按学校过滤 拒绝访问 │ │ 查询所有 查询所属区域 查询本校 返回403 │ │ 学生数据 学生数据 学生数据 │ │ │ │ │ │ │ └───────────┴───────────┘ │ │ │ │ │ ▼ │ │ 返回过滤后的数据 │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` --- ## 4. 业务规则 ### 4.1 基础规则 | 规则编号 | 规则描述 | 验证时机 | |:--------:|----------|----------| | STU-R01 | 学号在系统内不允许重复，可为空 | 新增/编辑/导入时校验 | | STU-R02 | 姓名为必填项，最大长度50字符 | 新增/编辑/导入时校验 | | STU-R03 | 学校信息（区域/学校/年级/班级）为必填项 | 新增/编辑/导入时校验 | | STU-R04 | 出生日期和性别为选填项 | - | | STU-R05 | 学生需归属于某个会员（家长/教师） | 新增/编辑/导入时校验 | | STU-R06 | 所有删除操作均为软删除，保留历史数据 | 删除时执行 | ### 4.2 批量导入规则 | 规则编号 | 规则描述 | 验证时机 | |:--------:|----------|----------| | IMP-R01 | 批量导入时需校验必填字段完整性 | 解析Excel后校验 | | IMP-R02 | 批量导入时需校验区域/学校/年级/班级数据一致性 | 解析Excel后校验 | | IMP-R03 | 批量导入时，若用户手机号已存在，则挂载到已有用户 | 保存数据时处理 | | IMP-R04 | 批量导入时，若用户手机号不存在，自动创建家长用户（初始密码：123456） | 保存数据时处理 | | IMP-R05 | 单次导入数据量限制：≤1000条 | 上传文件时校验 | | IMP-R06 | Excel文件大小限制：≤5MB | 上传文件时校验 | ### 4.3 导入模板规范 | 序号 | 字段名称 | 必填 | 格式说明 | 示例 | |:----:|----------|:----:|----------|------| | 1 | 姓名 | ✓ | 最大50字符 | 张小明 | | 2 | 学号 | ✓ | 最大32字符，系统内唯一 | STU20260001 | | 3 | 用户手机号 | ✓ | 11位手机号 | 13812345678 | | 4 | 区域 | ✓ | 格式：省-市-区 | 湖北省-武汉市-武昌区 | | 5 | 学校 | ✓ | 学校名称，需与系统数据匹配 | 武汉市第一中学 | | 6 | 年级 | ✓ | 年级名称，需与系统数据匹配 | 七年级 | | 7 | 班级 | ✓ | 班级名称，需与系统数据匹配 | 1班 | | 8 | 性别 | - | 男/女/空 | 男 | | 9 | 出生年月 | - | 格式：YYYY-MM | 2015-03 | ### 4.4 数据权限规则 | 规则编号 | 角色 | 查询范围 | 操作权限 | |:--------:|------|----------|----------| | AUTH-R01 | 超级管理员 | 所有学生数据 | 增删改查 | | AUTH-R02 | 分公司用户 | 所属区域学生数据 | 增删改查 | | AUTH-R03 | 学校用户 | 本校学生数据 | 增删改查 | --- ## 5. 数据模型 ### 5.1 核心实体关系 ``` ┌─────────────────────────────────────────────────────────────────┐ │ 学生数据模型 │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ │ │ pg_region │ 1 n │ pg_school │ 1 n │pg_school_ │ │ │ │ 区域 │────▶│ 学校 │────▶│ grade │ │ │ └───────────┘ └───────────┘ │ 学校年级 │ │ │ └─────┬─────┘ │ │ │ 1 │ │ │ │ │ ▼ n │ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ │ │ pg_member │ 1 n │pg_student │ n 1 │pg_school_ │ │ │ │ 会员 │────▶│ 学生 │◀────│ class │ │ │ └───────────┘ └─────┬─────┘ │ 学校班级 │ │ │ │ └───────────┘ │ │ │ n │ │ │ │ │ ▼ 1 │ │ ┌───────────┐ │ │ │pg_subject │ │ │ │ 学科 │ │ │ └───────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ### 5.2 学生表结构（pg_student） | 字段名 | 类型 | 必填 | 说明 | |--------|------|:----:|------| | student_id | bigint | ✓ | 学生ID，主键自增 | | student_name | varchar(50) | ✓ | 学生姓名 | | student_no | varchar(32) | - | 学号，唯一索引 | | gender | char(1) | - | 性别（0未知 1男 2女） | | birthday | date | - | 出生年月 | | region_id | bigint | ✓ | 所属区域ID | | region_path | varchar(200) | - | 区域路径（冗余存储） | | school_id | bigint | ✓ | 所属学校ID | | school_grade_id | bigint | ✓ | 所属学校年级ID | | school_class_id | bigint | ✓ | 所属学校班级ID | | subject_id | bigint | - | 学科ID | | member_id | bigint | ✓ | 归属会员ID | | status | char(1) | ✓ | 状态（0正常 1停用） | | create_by | varchar(64) | - | 创建者 | | create_time | datetime | - | 创建时间 | | update_by | varchar(64) | - | 更新者 | | update_time | datetime | - | 更新时间 | | del_flag | char(1) | ✓ | 删除标志（0存在 1删除） | | remark | varchar(500) | - | 备注 | ### 5.3 索引设计 | 索引名 | 索引字段 | 索引类型 | 说明 | |--------|----------|----------|------| | PRIMARY | student_id | 主键 | 主键索引 | | uk_student_no | student_no | 唯一 | 学号唯一性保证 | | idx_member_id | member_id | 普通 | 按会员查询学生 | | idx_school_id | school_id | 普通 | 按学校查询学生 | | idx_school_class_id | school_class_id | 普通 | 按班级查询学生 | | idx_student_name | student_name | 普通 | 按姓名模糊查询 | --- ## 6. 接口设计概览 ### 6.1 接口清单 | 接口编号 | 请求方式 | 接口路径 | 功能描述 | |---------|---------|----------|----------| | API-001 | GET | /api/student/list | 查询学生列表（分页） | | API-002 | GET | /api/student/{studentId} | 获取学生详情 | | API-003 | POST | /api/student | 新增学生 | | API-004 | PUT | /api/student | 修改学生 | | API-005 | DELETE | /api/student/{studentId} | 删除学生 | | API-006 | POST | /api/student/import | 批量导入学生 | | API-007 | GET | /api/student/template | 下载导入模板 | ### 6.2 接口与功能映射 | 功能编号 | 功能名称 | 前端操作 | 调用接口 | |---------|---------|----------|----------| | STU-001 | 学生列表查询 | 查询表单+分页 | API-001 | | STU-002 | 学校树筛选 | 点击树节点 | API-001 | | STU-003 | 新增学生 | 弹窗表单提交 | API-003 | | STU-004 | 编辑学生 | 弹窗表单提交 | API-002, API-004 | | STU-005 | 删除学生 | 确认弹窗删除 | API-005 | | STU-006 | 批量导入 | 上传Excel | API-006 | | STU-007 | 下载导入模板 | 点击下载 | API-007 | --- ## 7. 技术架构 ### 7.1 前端技术栈 | 技术 | 版本 | 用途 | |------|------|------| | Vue | 3.5.x | 前端框架 | | Element Plus | 2.x | UI组件库 | | Axios | 1.x | HTTP请求 | | Pinia | 3.x | 状态管理 | | Vue Router | 4.x | 路由管理 | | XLSX | 0.18.x | Excel解析 | ### 7.2 后端技术栈 | 技术 | 版本 | 用途 | |------|------|------| | Spring Boot | 3.3.x | 应用框架 | | Spring Security | 6.x | 安全框架 | | MyBatis Plus | 3.5.x | ORM框架 | | EasyExcel | 4.x | Excel处理 | | Hutool | 5.x | 工具库 | | JDK | 17+ | 运行环境 | ### 7.3 组件划分 **前端组件：** ``` src/views/student/ ├── index.vue # 学生管理主页面 ├── components/ │ ├── StudentDialog.vue # 新增/编辑学生弹窗 │ ├── ImportDialog.vue # 批量导入弹窗 │ └── SchoolTree.vue # 学校树组件（可复用） src/api/ └── student.js # 学生管理API src/mock/ └── student.js # Mock数据 ``` **后端组件：** ``` pangu-admin/ └── controller/ └── StudentController.java # 学生管理控制器 pangu-system/ ├── domain/ │ ├── Student.java # 学生实体 │ ├── dto/ │ │ ├── StudentDTO.java # 学生DTO │ │ └── StudentImportDTO.java # 导入DTO │ └── vo/ │ └── StudentVO.java # 学生VO ├── mapper/ │ └── StudentMapper.java # 学生Mapper ├── service/ │ ├── IStudentService.java # 学生服务接口 │ └── impl/ │ └── StudentServiceImpl.java# 学生服务实现 └── listener/ └── StudentImportListener.java # Excel导入监听器 ``` --- ## 8. 开发计划 ### 8.1 里程碑 | 阶段 | 任务 | 交付物 | |------|------|--------| | 第一阶段 | 基础功能开发 | 列表查询、新增、编辑、删除 | | 第二阶段 | 批量导入开发 | 模板下载、Excel导入、数据校验 | | 第三阶段 | 联调测试 | 前后端联调、功能测试 | | 第四阶段 | 验收交付 | 文档完善、验收评审 | ### 8.2 任务分解 **第一阶段：基础功能开发** | 序号 | 任务 | 负责端 | 依赖 | |:----:|------|:------:|------| | 1.1 | 创建学生表、初始化数据 | 后端 | 无 | | 1.2 | 学生服务层开发（CRUD） | 后端 | 1.1 | | 1.3 | 学生Controller开发 | 后端 | 1.2 | | 1.4 | 学生列表页面开发 | 前端 | Mock数据 | | 1.5 | 学校树组件开发 | 前端 | Mock数据 | | 1.6 | 新增/编辑弹窗开发 | 前端 | Mock数据 | **第二阶段：批量导入开发** | 序号 | 任务 | 负责端 | 依赖 | |:----:|------|:------:|------| | 2.1 | 导入模板生成 | 后端 | 无 | | 2.2 | Excel解析与校验 | 后端 | 2.1 | | 2.3 | 会员自动创建逻辑 | 后端 | 2.2 | | 2.4 | 批量保存与事务处理 | 后端 | 2.3 | | 2.5 | 导入弹窗开发 | 前端 | Mock数据 | | 2.6 | 导入结果展示 | 前端 | 2.5 | **第三阶段：联调测试** | 序号 | 任务 | 负责人 | 依赖 | |:----:|------|:------:|------| | 3.1 | 前后端接口联调 | 前端+后端 | 1.x, 2.x | | 3.2 | 功能测试 | 测试 | 3.1 | | 3.3 | Bug修复 | 前端+后端 | 3.2 | | 3.4 | 回归测试 | 测试 | 3.3 | --- ## 9. 风险分析 ### 9.1 技术风险 | 风险项 | 风险等级 | 影响 | 应对措施 | |--------|:--------:|------|----------| | Excel大文件导入性能 | 中 | 导入超时 | 使用EasyExcel流式读取，分批处理 | | 批量导入数据校验复杂 | 中 | 校验不完整 | 设计完善的校验规则，编写单元测试 | | 学校树数据量大 | 低 | 页面加载慢 | 使用懒加载，按需加载子节点 | | 并发导入冲突 | 低 | 数据重复 | 使用乐观锁，学号唯一索引 | ### 9.2 业务风险 | 风险项 | 风险等级 | 影响 | 应对措施 | |--------|:--------:|------|----------| | 导入模板格式变更 | 中 | 用户导入失败 | 模板版本控制，兼容处理 | | 会员自动创建失败 | 中 | 学生无法关联 | 事务回滚，返回详细错误 | | 数据权限配置错误 | 高 | 数据泄露 | 完善权限测试用例 | --- ## 10. 验收标准 ### 10.1 功能验收 | 验收项 | 验收标准 | |--------|----------| | 学生列表查询 | 支持多条件筛选，分页正确，学校树筛选有效 | | 新增学生 | 必填校验正确，学号唯一性校验，关联数据正确 | | 编辑学生 | 数据回显正确，修改保存成功 | | 删除学生 | 确认提示，软删除，列表刷新 | | 批量导入 | 模板下载正确，Excel解析正确，校验完整，会员自动创建 | | 数据权限 | 三种角色权限控制正确 | ### 10.2 性能验收 | 验收项 | 验收标准 | |--------|----------| | 列表查询 | 响应时间 ≤ 500ms | | 学校树加载 | 首次加载 ≤ 1s | | 批量导入 | 1000条数据 ≤ 30s | | 单条保存 | 响应时间 ≤ 200ms | ### 10.3 质量验收 | 验收项 | 验收标准 | |--------|----------| | 代码规范 | 符合团队编码规范 | | 单元测试 | 核心业务覆盖率 ≥ 80% | | 接口文档 | Swagger文档完整 | | 日志记录 | 关键操作有审计日志 | --- ## 审核签字 | 角色 | 姓名 | 日期 | 签字 | |------|------|------|------| | 技术负责人 | | | | | 产品负责人 | | | | | 测试负责人 | | | | | 项目经理 | | | | --- *文档结束*