# 盘古用户平台 - 需求规格说明书

---

| 文档信息     | 内容                                                    |
| -------- | ----------------------------------------------------- |
| **文档版本** | V1.0                                                  |
| **项目名称** | 盘古用户平台（Pangu User Platform）                           |
| **编写团队** | pangu                                                 |
| **创建日期** | 2026-01-31                                            |
| **审核状态** | 待审核                                                   |
| **原型链接** | https://modao.cc/proto/atlwMul8t9pi6yxQ42W7up/sharing |

---

## 修订记录

| 版本   | 日期         | 修订人   | 修订内容 |
| ---- | ---------- | ----- | ---- |
| 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 编写目的

本文档旨在详细描述盘古用户平台的功能需求和非功能需求，作为系统设计、开发、测试和验收的依据。本文档的主要读者包括：

- 项目管理人员
- 系统架构师
- 开发工程师
- 测试工程师
- 产品经理
- 业务方代表

### 1.2 背景

盘古用户平台是一个面向教育行业的统一用户管理系统，主要服务于湖北新华书店系统内的学校、教师、家长和学生。系统需要支持多角色、多层级的用户管理，并为其他业务系统提供统一的用户认证和授权服务。

### 1.3 参考资料

| 文档名称         | 版本   | 来源                                                    |
| ------------ | ---- | ----------------------------------------------------- |
| 墨刀原型-用户系统    | -    | https://modao.cc/proto/atlwMul8t9pi6yxQ42W7up/sharing |
| RuoYi-Vue文档  | 3.8  | http://doc.ruoyi.vip                                  |
| 湖北新华业务中台技术规范 | V1.0 | 内部文档                                                  |

### 1.4 术语定义

| 术语    | 定义                          |
| ----- | --------------------------- |
| 会员    | 通过小程序/H5端注册的前端用户，包括家长和教师    |
| 后台用户  | 通过管理后台登录的管理人员，包括超级管理员和分公司用户 |
| 学生    | 学生信息实体，归属于会员（家长/教师）名下       |
| 应用    | 接入盘古用户平台的第三方业务系统            |
| Token | 用于用户身份验证的令牌                 |

---

## 2. 项目概述

### 2.1 项目目标

1. **统一用户管理**：建立统一的用户中心，管理学校、教师、家长、学生等各类用户
2. **多角色权限控制**：支持超级管理员、分公司用户、学校用户三级角色管理
3. **开放授权服务**：为其他业务系统提供标准化的用户认证和数据接口
4. **支持多端登录**：支持管理后台、小程序、H5等多种客户端

### 2.2 系统边界

```
┌─────────────────────────────────────────────────────────────────┐
│                        盘古用户平台                               │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │   管理后台    │  │  小程序/H5   │  │  第三方应用   │          │
│  │ (Web端)      │  │  (移动端)    │  │  (API调用)   │          │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘          │
│         │                 │                 │                   │
│         ▼                 ▼                 ▼                   │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                    统一认证服务                          │   │
│  │  - 手机号+密码登录  - 手机号+验证码登录  - 微信登录       │   │
│  └─────────────────────────────────────────────────────────┘   │
│                              │                                  │
│         ┌────────────────────┼────────────────────┐            │
│         ▼                    ▼                    ▼            │
│  ┌─────────────┐      ┌─────────────┐      ┌─────────────┐    │
│  │  用户管理    │      │  学校管理    │      │  应用管理    │    │
│  │  - 会员     │      │  - 学校     │      │  - 接口授权  │    │
│  │  - 学生     │      │  - 年级/班级 │      │  - 密钥管理  │    │
│  └─────────────┘      └─────────────┘      └─────────────┘    │
└─────────────────────────────────────────────────────────────────┘
```

### 2.3 系统上下文

**输入系统：**

- 微信开放平台（获取用户openId）
- 短信服务（发送验证码）

**输出系统：**

- AI智慧平台（提供用户数据）
- 其他业务系统（通过API接入）

---

## 3. 系统角色定义

### 3.1 角色层级结构

```
┌─────────────────────────────────────────┐
│              超级管理员                  │
│  (系统最高权限，管理全部数据)             │
└─────────────────┬───────────────────────┘
                  │
    ┌─────────────┴─────────────┐
    ▼                           ▼
┌───────────────┐       ┌───────────────┐
│  分公司用户    │       │  分公司用户    │
│  (管理所属区域) │       │  (管理所属区域) │
└───────┬───────┘       └───────┬───────┘
        │                       │
    ┌───┴───┐               ┌───┴───┐
    ▼       ▼               ▼       ▼
┌───────┐ ┌───────┐   ┌───────┐ ┌───────┐
│学校用户│ │学校用户│   │学校用户│ │学校用户│
└───────┘ └───────┘   └───────┘ └───────┘
```

### 3.2 角色权限矩阵

| 功能模块       | 超级管理员 | 分公司用户 | 学校用户 |
| ---------- |:-----:|:-----:|:----:|
| **学校管理**   |       |       |      |
| - 查看所有学校   | ✓     | ✗     | ✗    |
| - 查看所属区域学校 | ✓     | ✓     | ✗    |
| - 新增/编辑学校  | ✓     | ✓     | ✗    |
| - 删除学校     | ✓     | ✓     | ✗    |
| - 管理年级/班级  | ✓     | ✓     | ✗    |
| **会员管理**   |       |       |      |
| - 查看所有会员   | ✓     | ✗     | ✗    |
| - 查看所属区域会员 | ✓     | ✓     | ✗    |
| - 新增/编辑会员  | ✓     | ✓     | ✗    |
| - 重置密码     | ✓     | ✓     | ✗    |
| - 删除会员     | ✓     | ✓     | ✗    |
| **学生管理**   |       |       |      |
| - 查看所有学生   | ✓     | ✗     | ✗    |
| - 查看所属区域学生 | ✓     | ✓     | ✗    |
| - 查看本校学生   | ✓     | ✓     | ✓    |
| - 新增/编辑学生  | ✓     | ✓     | ✓    |
| - 批量导入学生   | ✓     | ✓     | ✓    |
| - 删除学生     | ✓     | ✓     | ✓    |
| **教师管理**   |       |       |      |
| - 查看本校教师   | ✗     | ✗     | ✓    |
| - 管理本校教师   | ✗     | ✗     | ✓    |
| **应用管理**   |       |       |      |
| - 查看所有应用   | ✓     | ✗     | ✗    |
| - 新增/编辑应用  | ✓     | ✗     | ✗    |
| - 接口授权     | ✓     | ✗     | ✗    |
| - 重置密钥     | ✓     | ✗     | ✗    |
| **基础数据**   |       |       |      |
| - 年级管理     | ✓     | ✓     | ✗    |
| - 班级管理     | ✓     | ✓     | ✗    |
| - 学科管理     | ✓     | ✓     | ✗    |
| - 区域管理     | ✓     | ✗     | ✗    |
| **系统设置**   | ✓     | ✗     | ✗    |
| **系统监控**   | ✓     | ✗     | ✗    |

### 3.3 前端用户角色

| 角色  | 说明              | 权限               |
| --- | --------------- | ---------------- |
| 家长  | 通过小程序/H5注册的家长用户 | 可绑定多个学生（不限学校）    |
| 教师  | 通过小程序/H5注册的教师用户 | 需绑定所属学校，只能绑定本校学生 |

---

## 4. 功能需求

### 4.1 学校管理模块

#### 4.1.1 功能概述

管理学校、年级、班级的树形组织结构，支持按区域筛选和层级管理。

#### 4.1.2 功能清单

| 功能编号    | 功能名称    | 功能描述              | 优先级 |
| ------- | ------- | ----------------- |:---:|
| SCH-001 | 学校列表查询  | 按区域树形展示学校、年级、班级结构 | P0  |
| SCH-002 | 学校信息查询  | 按学校名称、状态筛选查询      | P0  |
| SCH-003 | 新增学校    | 创建新学校，自动生成学校编码    | P0  |
| SCH-004 | 编辑学校    | 修改学校名称、所属区域、状态    | P0  |
| SCH-005 | 删除学校    | 软删除学校（需检查关联数据）    | P0  |
| SCH-006 | 新增年级    | 为学校挂载年级（从年级库选择）   | P0  |
| SCH-007 | 新增班级    | 为年级挂载班级（从班级库选择）   | P0  |
| SCH-008 | 删除年级/班级 | 软删除年级/班级（需检查关联数据） | P1  |

#### 4.1.3 业务规则

| 规则编号    | 规则描述                      |
| ------- | ------------------------- |
| SCH-R01 | 学校编码由系统自动生成，格式待定，不可修改     |
| SCH-R02 | 所属地区、学校编码、学校名称为必填项        |
| SCH-R03 | 新增学校时，所属地区默认带入列表页选择的区域    |
| SCH-R04 | 删除学校前需检查是否有子级（年级/班级），有则提示 |
| SCH-R05 | 删除学校前需检查是否被学生信息引用，有则不允许删除 |
| SCH-R06 | 所有删除操作均为软删除，保留历史数据        |
| SCH-R07 | 学校下新增年级为选择挂载，非新建年级        |
| SCH-R08 | 年级下新增班级为选择挂载，非新建班级        |
| SCH-R09 | 年级/班级选择支持多选               |

#### 4.1.4 数据项说明

**学校信息**

| 字段名称 | 字段类型 | 必填  | 说明              |
| ---- | ---- |:---:| --------------- |
| 学校名称 | 文本   | ✓   | 最大长度100字符       |
| 学校编码 | 文本   | ✓   | 系统自动生成，唯一       |
| 类型   | 枚举   | ✓   | 学校类型（小学/中学/高中等） |
| 所属区域 | 树形选择 | ✓   | 省-市-区三级         |
| 状态   | 开关   | ✓   | 启用/禁用           |
| 创建时间 | 日期时间 | -   | 系统自动记录          |
| 创建人  | 文本   | -   | 系统自动记录          |

---

### 4.2 会员管理模块

#### 4.2.1 功能概述

管理通过小程序/H5端注册的前端用户（家长/教师），支持用户信息维护和学生关联。

#### 4.2.2 功能清单

| 功能编号    | 功能名称    | 功能描述                   | 优先级 |
| ------- | ------- | ---------------------- |:---:|
| MEM-001 | 会员列表查询  | 按手机号、昵称、状态、注册时间、身份类型筛选 | P0  |
| MEM-002 | 新增会员    | 后台手动创建会员账号             | P0  |
| MEM-003 | 编辑会员    | 修改会员基本信息和学生绑定关系        | P0  |
| MEM-004 | 删除会员    | 软删除会员（需检查学生绑定）         | P1  |
| MEM-005 | 重置密码    | 重置会员登录密码并显示新密码         | P0  |
| MEM-006 | 禁用/启用会员 | 控制会员登录权限               | P0  |
| MEM-007 | 绑定学生    | 为会员绑定学生信息              | P0  |
| MEM-008 | 解绑学生    | 移除会员与学生的绑定关系           | P0  |

#### 4.2.3 业务规则

| 规则编号    | 规则描述                         |
| ------- | ---------------------------- |
| MEM-R01 | 会员编号由系统自动生成，格式：JS + 时间戳      |
| MEM-R02 | 昵称未填写时，系统自动生成默认昵称            |
| MEM-R03 | 手机号为必填项，需验证格式有效性和唯一性         |
| MEM-R04 | 出生日期和性别为选填项                  |
| MEM-R05 | 身份类型为"教师"时，必须选择所属区域/学校/年级/班级 |
| MEM-R06 | 身份类型为"教师"时，只能绑定同校学生          |
| MEM-R07 | 身份类型为"家长"时，不显示区域信息，可绑定任意学生   |
| MEM-R08 | 删除会员前需检查是否绑定学生，有则不允许删除       |
| MEM-R09 | 重置密码后，需弹窗显示新密码并提供复制功能        |
| MEM-R10 | 禁用会员后，该用户无法登录任何端             |
| MEM-R11 | 使用RuoYi鉴权体系，区分后台用户和会员信息      |

#### 4.2.4 登录方式支持

| 登录方式      | 说明                |
| --------- | ----------------- |
| 手机号 + 验证码 | 发送短信验证码登录         |
| 手机号 + 密码  | 使用账号密码登录          |
| 微信登录      | 通过微信授权登录，获取openId |

#### 4.2.5 数据项说明

**会员信息**

| 字段名称   | 字段类型 | 必填   | 说明          |
| ------ | ---- |:----:| ----------- |
| 会员编号   | 文本   | ✓    | 系统自动生成，唯一   |
| 手机号    | 文本   | ✓    | 11位手机号，唯一   |
| 昵称     | 文本   | -    | 最大长度50字符    |
| 性别     | 枚举   | -    | 男/女/未知      |
| 出生日期   | 日期   | -    | -           |
| 身份类型   | 枚举   | ✓    | 家长/教师       |
| 所属区域   | 树形选择 | 条件必填 | 教师身份必填      |
| 所属学校   | 下拉选择 | 条件必填 | 教师身份必填      |
| 所属年级   | 下拉选择 | 条件必填 | 教师身份必填      |
| 所属班级   | 下拉选择 | 条件必填 | 教师身份必填      |
| openId | 文本   | -    | 微信用户标识      |
| 注册时间   | 日期时间 | -    | 系统自动记录      |
| 注册来源   | 枚举   | -    | 小程序/H5/后台新增 |
| 状态     | 开关   | ✓    | 启用/禁用       |

---

### 4.3 学生管理模块

#### 4.3.1 功能概述

管理学生基本信息，支持与会员的绑定关系维护和批量导入功能。

#### 4.3.2 功能清单

| 功能编号    | 功能名称   | 功能描述                | 优先级 |
| ------- | ------ | ------------------- |:---:|
| STU-001 | 学生列表查询 | 按姓名、学号、性别、手机号、学科等筛选 | P0  |
| STU-002 | 学校树筛选  | 通过左侧学校树快速定位学生       | P0  |
| STU-003 | 新增学生   | 手动创建学生信息            | P0  |
| STU-004 | 编辑学生   | 修改学生基本信息            | P0  |
| STU-005 | 删除学生   | 软删除学生信息             | P1  |
| STU-006 | 批量导入   | 通过Excel模板批量导入学生     | P0  |
| STU-007 | 下载导入模板 | 下载标准Excel导入模板       | P0  |

#### 4.3.3 业务规则

| 规则编号    | 规则描述                                  |
| ------- | ------------------------------------- |
| STU-R01 | 学号在系统内不允许重复，可为空                       |
| STU-R02 | 姓名为必填项                                |
| STU-R03 | 学校信息（区域/学校/年级/班级）为必填项                 |
| STU-R04 | 出生日期和性别为选填项                           |
| STU-R05 | 学生需归属于某个会员（家长/教师）                     |
| STU-R06 | 批量导入时需校验必填字段完整性                       |
| STU-R07 | 批量导入时需校验区域/学校/年级/班级数据一致性              |
| STU-R08 | 批量导入时，若用户手机号已存在，则挂载到已有用户              |
| STU-R09 | 批量导入时，若用户手机号不存在，自动创建家长用户（初始密码：123456） |

#### 4.3.4 批量导入模板

| 序号  | 字段名称  | 必填  | 说明             |
|:---:| ----- |:---:| -------------- |
| 1   | 姓名    | ✓   | 学生姓名           |
| 2   | 学号    | ✓   | 学生学号，系统内唯一     |
| 3   | 用户手机号 | ✓   | 归属用户的手机号       |
| 4   | 区域    | ✓   | 格式：湖北省-武汉市-武昌区 |
| 5   | 学校    | ✓   | 学校名称，需与系统数据匹配  |
| 6   | 年级    | ✓   | 年级名称，需与系统数据匹配  |
| 7   | 班级    | ✓   | 班级名称，需与系统数据匹配  |
| 8   | 性别    | -   | 男/女            |
| 9   | 出生年月  | -   | 格式：YYYY-MM     |

#### 4.3.5 数据项说明

**学生信息**

| 字段名称 | 字段类型 | 必填  | 说明          |
| ---- | ---- |:---:| ----------- |
| 姓名   | 文本   | ✓   | 最大长度50字符    |
| 学号   | 文本   | -   | 唯一，最大长度20字符 |
| 性别   | 枚举   | -   | 男/女/未知      |
| 出生年月 | 日期   | -   | -           |
| 所属区域 | 树形选择 | ✓   | 省-市-区三级     |
| 所属学校 | 下拉选择 | ✓   | 依赖区域        |
| 所属年级 | 下拉选择 | ✓   | 依赖学校        |
| 所属班级 | 下拉选择 | ✓   | 依赖年级        |
| 学科   | 下拉选择 | -   | 学科信息        |
| 归属用户 | 关联   | ✓   | 关联会员ID      |
| 创建时间 | 日期时间 | -   | 系统自动记录      |

---

### 4.4 应用管理模块

#### 4.4.1 功能概述

管理接入盘古用户平台的第三方应用，控制API接口访问权限。

#### 4.4.2 功能清单

| 功能编号    | 功能名称    | 功能描述              | 优先级 |
| ------- | ------- | ----------------- |:---:|
| APP-001 | 应用列表查询  | 按应用名称、编码、状态筛选     | P0  |
| APP-002 | 新增应用    | 创建新应用，自动生成应用编码和密钥 | P0  |
| APP-003 | 编辑应用    | 修改应用信息和接口授权       | P0  |
| APP-004 | 删除应用    | 删除应用及其授权信息        | P1  |
| APP-005 | 重置密钥    | 重新生成应用密钥          | P0  |
| APP-006 | 接口授权    | 配置应用可访问的API接口     | P0  |
| APP-007 | 禁用/启用应用 | 控制应用访问权限          | P0  |

#### 4.4.3 业务规则

| 规则编号    | 规则描述                            |
| ------- | ------------------------------- |
| APP-R01 | 应用编码由系统自动生成，格式：YY + 6位数字        |
| APP-R02 | 应用密钥（AppSecret）由系统自动生成，32位随机字符串 |
| APP-R03 | 重置密钥后，旧密钥立即失效                   |
| APP-R04 | 重置密钥后需弹窗显示新密钥并提供复制功能            |
| APP-R05 | 删除应用需popconfirm二次确认             |
| APP-R06 | 禁用应用后，该应用无法调用任何API接口            |
| APP-R07 | 接口授权采用勾选方式，可多选                  |

#### 4.4.4 数据项说明

**应用信息**

| 字段名称 | 字段类型 | 必填  | 说明          |
| ---- | ---- |:---:| ----------- |
| 应用名称 | 文本   | ✓   | 最大长度100字符   |
| 应用编码 | 文本   | ✓   | 系统自动生成，唯一   |
| 应用密钥 | 文本   | ✓   | 系统自动生成，32位  |
| 授权接口 | 多选   | -   | 可访问的API接口列表 |
| 状态   | 开关   | ✓   | 启用/禁用       |
| 创建时间 | 日期时间 | -   | 系统自动记录      |
| 创建人  | 文本   | -   | 系统自动记录      |

**API接口列表**

| 接口名称   | 接口地址                 | 说明     |
| ------ | -------------------- | ------ |
| 查询学生信息 | /api/student/getList | 获取学生列表 |
| 查询学校信息 | /api/school/getList  | 获取学校列表 |
| 查询年级信息 | /api/grade/getList   | 获取年级列表 |
| 查询班级信息 | /api/class/getList   | 获取班级列表 |
| 查询会员信息 | /api/member/getList  | 获取会员列表 |

---

### 4.5 基础数据管理模块

#### 4.5.1 年级管理

| 功能编号    | 功能名称   | 功能描述         | 优先级 |
| ------- | ------ | ------------ |:---:|
| GRD-001 | 年级列表查询 | 按名称、编码、状态筛选  | P0  |
| GRD-002 | 新增年级   | 创建年级，自动生成编码  | P0  |
| GRD-003 | 编辑年级   | 修改年级名称、状态    | P0  |
| GRD-004 | 删除年级   | 软删除年级（需检查引用） | P1  |

**年级数据项**

| 字段名称 | 字段类型 | 必填  | 说明        |
| ---- | ---- |:---:| --------- |
| 年级名称 | 文本   | ✓   | 如：一年级、七年级 |
| 年级编码 | 文本   | ✓   | 系统自动生成    |
| 状态   | 开关   | ✓   | 启用/禁用     |

#### 4.5.2 班级管理

| 功能编号    | 功能名称   | 功能描述         | 优先级 |
| ------- | ------ | ------------ |:---:|
| CLS-001 | 班级列表查询 | 按名称、编码、状态筛选  | P0  |
| CLS-002 | 新增班级   | 创建班级，自动生成编码  | P0  |
| CLS-003 | 编辑班级   | 修改班级名称、状态    | P0  |
| CLS-004 | 删除班级   | 软删除班级（需检查引用） | P1  |

**班级数据项**

| 字段名称 | 字段类型 | 必填  | 说明      |
| ---- | ---- |:---:| ------- |
| 班级名称 | 文本   | ✓   | 如：1班、2班 |
| 班级编码 | 文本   | ✓   | 系统自动生成  |
| 状态   | 开关   | ✓   | 启用/禁用   |

#### 4.5.3 学科管理

| 功能编号    | 功能名称   | 功能描述         | 优先级 |
| ------- | ------ | ------------ |:---:|
| SUB-001 | 学科列表查询 | 按名称、编码、状态筛选  | P0  |
| SUB-002 | 新增学科   | 创建学科信息       | P0  |
| SUB-003 | 编辑学科   | 修改学科名称、状态    | P0  |
| SUB-004 | 删除学科   | 软删除学科（需检查引用） | P1  |

**学科数据项**

| 字段名称 | 字段类型 | 必填  | 说明         |
| ---- | ---- |:---:| ---------- |
| 学科名称 | 文本   | ✓   | 如：语文、数学、英语 |
| 学科编码 | 文本   | ✓   | 系统自动生成     |
| 状态   | 开关   | ✓   | 启用/禁用      |

#### 4.5.4 区域管理

| 功能编号    | 功能名称  | 功能描述           | 优先级 |
| ------- | ----- | -------------- |:---:|
| REG-001 | 区域树查询 | 树形展示省-市-区结构    | P0  |
| REG-002 | 新增区域  | 在指定节点下新增区域     | P0  |
| REG-003 | 编辑区域  | 修改区域名称         | P0  |
| REG-004 | 删除区域  | 删除区域（需检查子级和引用） | P1  |

**区域数据项**

| 字段名称 | 字段类型 | 必填  | 说明          |
| ---- | ---- |:---:| ----------- |
| 区域名称 | 文本   | ✓   | 如：湖北省、武汉市   |
| 父级区域 | 关联   | -   | 顶级区域无父级     |
| 层级   | 数字   | ✓   | 1=省，2=市，3=区 |
| 排序   | 数字   | -   | 同级排序        |

**预置区域数据**

```
湖北
├── 武汉
│   ├── 武昌区
│   ├── 汉口区
│   ├── 汉阳区
│   ├── 江夏区
│   ├── 新洲区
│   └── 黄陂区
└── 黄冈
    ├── 黄州区
    ├── 红安县
    └── 麻城市
北京
香港
吉宁
```

---

### 4.6 系统设置模块

> 复用RuoYi框架的系统设置功能

| 功能编号    | 功能名称 | 功能描述          | 优先级 |
| ------- | ---- | ------------- |:---:|
| SYS-001 | 用户管理 | 管理后台用户账号      | P0  |
| SYS-002 | 角色管理 | 管理系统角色和权限     | P0  |
| SYS-003 | 菜单管理 | 管理系统菜单结构      | P0  |
| SYS-004 | 部门管理 | 管理组织架构（用于分公司） | P0  |
| SYS-005 | 字典管理 | 管理系统字典数据      | P1  |
| SYS-006 | 参数设置 | 管理系统参数配置      | P1  |

---

### 4.7 系统监控模块

> 参考RuoYi框架的系统监控功能

| 功能编号    | 功能名称 | 功能描述     | 优先级 |
| ------- | ---- | -------- |:---:|
| MON-001 | 在线用户 | 查看当前在线用户 | P1  |
| MON-002 | 登录日志 | 查看用户登录记录 | P1  |
| MON-003 | 操作日志 | 查看用户操作记录 | P1  |
| MON-004 | 服务监控 | 查看服务器状态  | P2  |
| MON-005 | 缓存监控 | 查看缓存使用情况 | P2  |

---

## 5. 非功能需求

### 5.1 性能需求

| 需求编号    | 需求描述    | 指标            |
| ------- | ------- | ------------- |
| NFR-P01 | 页面加载时间  | 首屏加载 ≤ 3秒     |
| NFR-P02 | API响应时间 | 95%请求 ≤ 500ms |
| NFR-P03 | 并发用户数   | 支持 500 并发用户   |
| NFR-P04 | 批量导入性能  | 1000条数据 ≤ 30秒 |
| NFR-P05 | 数据库查询   | 单表查询 ≤ 100ms  |

### 5.2 安全需求

| 需求编号    | 需求描述                        |
| ------- | --------------------------- |
| NFR-S01 | 用户密码需加密存储（BCrypt）           |
| NFR-S02 | 登录需输入图形验证码                  |
| NFR-S03 | 密码错误5次后锁定账号10分钟             |
| NFR-S04 | API接口需Token认证               |
| NFR-S05 | 第三方应用调用需AppId + AppSecret认证 |
| NFR-S06 | 敏感操作需记录审计日志                 |
| NFR-S07 | 禁止SQL注入、XSS攻击               |
| NFR-S08 | 手机号等敏感信息需脱敏显示               |

### 5.3 可用性需求

| 需求编号    | 需求描述          |
| ------- | ------------- |
| NFR-A01 | 系统可用性 ≥ 99.9% |
| NFR-A02 | 支持数据定期备份      |
| NFR-A03 | 支持服务平滑重启      |

### 5.4 兼容性需求

| 需求编号    | 需求描述                              |
| ------- | --------------------------------- |
| NFR-C01 | 管理后台支持 Chrome、Edge、Firefox 最新两个版本 |
| NFR-C02 | 管理后台支持 1920x1080 及以上分辨率           |
| NFR-C03 | 小程序支持微信基础库 2.0 及以上                |
| NFR-C04 | H5端支持主流移动浏览器                      |

### 5.5 可维护性需求

| 需求编号    | 需求描述              |
| ------- | ----------------- |
| NFR-M01 | 代码需遵循团队编码规范       |
| NFR-M02 | 核心业务逻辑需编写单元测试     |
| NFR-M03 | API接口需提供Swagger文档 |
| NFR-M04 | 系统需支持日志分级输出       |

---

## 6. 用例规约

### 6.1 UC-001 用户登录

| 项目       | 内容                                                                                                                   |
| -------- | -------------------------------------------------------------------------------------------------------------------- |
| **用例名称** | 用户登录                                                                                                                 |
| **用例编号** | UC-001                                                                                                               |
| **参与者**  | 会员（家长/教师）                                                                                                            |
| **前置条件** | 用户已注册账号                                                                                                              |
| **后置条件** | 用户成功登录，获取访问Token                                                                                                     |
| **基本流程** | 1. 用户打开登录页面<br>2. 用户选择登录方式（验证码/密码/微信）<br>3. 用户输入登录信息<br>4. 系统验证登录信息<br>5. 验证通过，生成Token并返回<br>6. 跳转到首页                |
| **异常流程** | 3a. 手机号格式错误，提示"请输入正确的手机号"<br>4a. 验证码错误，提示"验证码错误"<br>4b. 密码错误，提示"密码错误"<br>4c. 密码错误5次，锁定账号10分钟<br>4d. 账号被禁用，提示"账号已被禁用" |

### 6.2 UC-002 批量导入学生

| 项目       | 内容                                                                                                                                               |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **用例名称** | 批量导入学生                                                                                                                                           |
| **用例编号** | UC-002                                                                                                                                           |
| **参与者**  | 后台管理员                                                                                                                                            |
| **前置条件** | 用户已登录后台，拥有学生管理权限                                                                                                                                 |
| **后置条件** | 学生数据导入成功                                                                                                                                         |
| **基本流程** | 1. 用户点击"批量导入"按钮<br>2. 系统弹出导入对话框<br>3. 用户下载导入模板<br>4. 用户填写学生数据<br>5. 用户上传Excel文件<br>6. 系统解析并校验数据<br>7. 校验通过，显示预览数据<br>8. 用户确认导入<br>9. 系统保存数据并关联用户 |
| **异常流程** | 6a. 文件格式错误，提示"请上传正确格式的Excel文件"<br>6b. 必填字段为空，提示"第N行XXX字段不能为空"<br>6c. 学校/年级/班级不匹配，提示"第N行学校信息不存在"<br>6d. 学号重复，提示"第N行学号已存在"                         |

### 6.3 UC-003 应用接口授权

| 项目       | 内容                                                                                                   |
| -------- | ---------------------------------------------------------------------------------------------------- |
| **用例名称** | 应用接口授权                                                                                               |
| **用例编号** | UC-003                                                                                               |
| **参与者**  | 超级管理员                                                                                                |
| **前置条件** | 用户已登录后台，拥有应用管理权限                                                                                     |
| **后置条件** | 应用获得指定接口的访问权限                                                                                        |
| **基本流程** | 1. 用户进入应用管理页面<br>2. 用户点击编辑按钮<br>3. 系统显示应用编辑表单<br>4. 用户在"接口授权"区域勾选允许访问的接口<br>5. 用户点击保存<br>6. 系统保存授权配置 |
| **异常流程** | 5a. 未选择任何接口，提示"请至少选择一个接口"                                                                            |

---

## 7. 数据字典

### 7.1 性别

| 编码  | 名称  |
|:---:| --- |
| 0   | 未知  |
| 1   | 男   |
| 2   | 女   |

### 7.2 身份类型

| 编码  | 名称  |
|:---:| --- |
| 1   | 家长  |
| 2   | 教师  |

### 7.3 注册来源

| 编码  | 名称   |
|:---:| ---- |
| 1   | 小程序  |
| 2   | H5   |
| 3   | 后台新增 |
| 4   | 批量导入 |

### 7.4 状态

| 编码  | 名称  |
|:---:| --- |
| 0   | 禁用  |
| 1   | 启用  |

### 7.5 区域层级

| 编码  | 名称  |
|:---:| --- |
| 1   | 省   |
| 2   | 市   |
| 3   | 区/县 |

---

## 8. 界面原型说明

### 8.1 原型访问信息

| 项目   | 内容                                                    |
| ---- | ----------------------------------------------------- |
| 原型工具 | 墨刀（Modao）                                             |
| 原型链接 | https://modao.cc/proto/atlwMul8t9pi6yxQ42W7up/sharing |
| 访问方式 | 只读模式                                                  |

### 8.2 页面清单

| 序号  | 模块     | 页面名称                 | 页面数量   |
|:---:| ------ | -------------------- |:------:|
| 1   | 系统整体说明 | 说明页                  | 1      |
| 2   | 学校管理   | 列表、编辑-学校、新增-年级、新增-班级 | 4      |
| 3   | 会员管理   | 列表、编辑                | 2      |
| 4   | 学生管理   | 列表、编辑、批量导入           | 3      |
| 5   | 应用管理   | 列表、编辑                | 2      |
| 6   | 年级管理   | 列表、编辑                | 2      |
| 7   | 班级管理   | 列表、编辑                | 2      |
| 8   | 学科管理   | 列表、编辑                | 2      |
| 9   | 区域管理   | 列表、编辑                | 2      |
|     | **合计** |                      | **17** |

### 8.3 墨刀批注汇总

> 以下为墨刀原型中的批注信息，作为开发实现的补充说明

#### 8.3.1 全局注意事项

| 批注序号 | 批注内容 |
|:------:|--------|
| 1 | 系统可以创建3个角色：管理员，分公司用户，学校用户 |
| 2 | 利用RuoYi的部门管理，创建分公司，并创建分公司的角色，分配对应的功能权限，也可创建学校用户角色 |
| 3 | 会员管理需要使用token来方便前端用户登录小程序或者H5 |

#### 8.3.2 学校管理批注

| 批注序号 | 批注内容 |
|:------:|--------|
| 1 | 学校下面新增年级，此处不做年级新增，只选择年级挂载在学校下面，功能类似编辑 |
| 2 | 删除时提示是否有子级，如有子级或者被学生信息使用时，给出提示，并且都是软删除 |
| 3 | 基于选择的区域根据学校名称和状态搜索 |
| 4 | 基于选择的区域新增学校信息 |
| 5 | 年级下面新增班级，此处不做班级新增，只选择班级挂载在年级下面，功能类似编辑 |
| 6 | 学校编码自动生成；所属地区从列表页选择的区域层级树带入，也可以手动调整；所属地区/学校编码/学校名称必填 |
| 7 | 学校下新增年级，选择对应的年级，支持多选，必填 |
| 8 | 年级下新增班级，选择对应的班级，支持多选 |

**示例数据 - 区域树：**
```
湖北
├── 武汉
│   ├── 武昌区
│   ├── 汉口区
│   ├── 汉阳区
│   ├── 江夏区
│   ├── 新洲区
│   └── 黄陂区
└── 黄冈
    ├── 黄州区
    ├── 红安县
    └── 麻城市
北京
香港
吉宁
```

**示例数据 - 学校树：**
```
武汉市第一中学
├── 七年级
│   ├── 1班
│   ├── 2班
│   └── 3班
├── 八年级
└── 九年级
武汉市第三中学
武汉市水果湖小学
├── 一年级
├── 二年级
├── 三年级
├── 四年级
├── 五年级
└── 六年级
```

#### 8.3.3 会员管理批注

| 批注序号 | 批注内容 |
|:------:|--------|
| 1 | 重置密码后，显示密码，提供复制功能 |
| 2 | 删除时，需要popconfirm提醒，并且如果会员明显绑定了学生信息，不允许删除，需要先移除绑定的学生信息 |
| 3 | 编辑跳转到会员编辑页面 |
| 4 | 使用RuoYi的鉴权登录处理用户，区分后台用户和会员信息 |
| 5 | 当前用户支持手机号+验证码登录、手机号+密码登录和微信登录，登录时需要使用输入验证码 |
| 6 | 禁用用户后，无法登录 |
| 7 | 昵称未填写时，自动生成 |
| 8 | 会员编号自动生成 |
| 9 | 出生日期和性别选填 |
| 10 | 身份信息为老师时，需要选择对应的区域/学校/年级/班级，学生信息从学生管理的数据中选择绑定，只允许选择与老师所属学校一样的学生 |
| 11 | 身份信息为家长时，不显示区域/学校/年级/班级，学生允许随便选择 |

**示例数据：**
- 会员编号：JS123123123
- 归属用户显示：昵称（手机号：13207166213）

**表格列定义：**
| 字段 | 说明 |
|-----|------|
| 会员编号 | 系统自动生成 |
| 手机号 | 11位手机号 |
| 昵称 | 用户昵称 |
| 性别 | 男/女/未知 |
| 出生日期 | 日期格式 |
| 身份类型 | 家长/教师 |
| 注册时间 | 日期时间 |
| 注册来源 | 小程序/H5/后台新增 |
| openId | 微信用户标识 |
| 状态 | 启用/禁用 |
| 操作 | 编辑、重置密码、删除 |

#### 8.3.4 学生管理批注

| 批注序号 | 批注内容 |
|:------:|--------|
| 1 | 学号不允许重复，可空 |
| 2 | 出生日期和性别可空 |
| 3 | 学校信息必填 |

**批量导入要求：**
| 序号 | 要求内容 |
|:---:|--------|
| 1 | 下载模板，模板包含姓名-必填，学号-必填，用户手机号-必填，区域-必填，学校-必填，年级-必填，班级-必填，性别-选填，出生年月-选填 |
| 2 | 导入数据时，检查必填信息，并检查区域/学校/年级/班级对应的信息一致 |
| 3 | 导入时，同时需要检查用户手机号，如果系统中存在用户手机号，那么导入的学生就挂在当前用户下；如果系统中不存在对应的用户，自动创建当前手机号的用户，身份为家长，初始密码123456，并把学生信息挂在当前用户下 |

**表格列定义：**
| 字段 | 说明 |
|-----|------|
| 姓名 | 学生姓名 |
| 学号 | 学生学号 |
| 性别 | 男/女/未知 |
| 出生年月 | 日期格式 |
| 地区 | 如：湖北省-武汉市-武昌区 |
| 学校 | 学校名称 |
| 年级 | 年级名称 |
| 班级 | 班级名称 |
| 学科 | 学科名称 |
| 用户身份 | 家长/教师 |
| 用户昵称 | 归属会员昵称 |
| 用户手机号 | 归属会员手机号 |
| 操作 | 编辑、删除 |

#### 8.3.5 应用管理批注

| 批注序号 | 批注内容 |
|:------:|--------|
| 1 | 重置密钥，弹出显示，并可以复制 |
| 2 | 删除popconfirm确认提示 |

**示例数据：**
- 应用名称：AI智慧平台
- 应用编码：YY000001
- 授权接口：学校接口、年级接口、班级接口

**接口授权表格：**
| 接口名称 | 接口地址 | 允许访问 |
|---------|---------|:------:|
| 查询学生信息 | /api/student/getList | ☐ |
| 查询学校信息 | /api/school/getList | ☐ |
| 查询年级信息 | /api/grade/getList | ☐ |
| 查询班级信息 | /api/class/getList | ☐ |

#### 8.3.6 区域管理批注

| 批注序号 | 批注内容 |
|:------:|--------|
| 1 | 区域名称必填 |
| 2 | 如果是新增下级跳转过来时，默认所属父级为选择的；直接点新增，所选区域需要手动选择 |

**表格列定义：**
| 字段 | 说明 |
|-----|------|
| 区域名称 | 如：湖北省、武汉市 |
| 区域编码 | 系统自动生成 |
| 创建时间 | 日期时间 |
| 创建人 | 操作人 |
| 操作 | 新增下级、编辑、删除 |

#### 8.3.7 年级管理

**表格列定义：**
| 字段 | 说明 |
|-----|------|
| 年级名称 | 如：一年级、七年级 |
| 年级编码 | 系统自动生成 |
| 状态 | 启用/禁用 |
| 创建时间 | 日期时间 |
| 创建人 | 操作人 |
| 操作 | 编辑、删除 |

**新增/编辑表单：**
- 年级名称（必填）
- 年级编码（自动生成）
- 状态（开关）

---

## 9. 约束与假设

### 9.1 技术约束

| 约束编号   | 约束描述                                   |
| ------ | -------------------------------------- |
| CON-01 | 后端基于 RuoYi-Vue 框架开发（Spring Boot + Vue） |
| CON-02 | 数据库使用 MySQL 8.0                        |
| CON-03 | 缓存使用 Redis                             |
| CON-04 | 前端使用 Vue 3 + Element Plus              |
| CON-05 | 需兼容 RuoYi 原有的用户认证体系                    |

### 9.2 业务假设

| 假设编号   | 假设描述                 |
| ------ | -------------------- |
| ASM-01 | 一个会员可以绑定多个学生         |
| ASM-02 | 一个学生只能归属一个会员         |
| ASM-03 | 学校、年级、班级数据相对稳定，变更频率低 |
| ASM-04 | 区域数据以湖北省为主，其他省份按需扩展  |
| ASM-05 | 第三方应用数量有限（预计 ≤ 20个）  |

---

## 10. 验收标准

### 10.1 功能验收标准

| 验收项  | 验收标准                |
| ---- | ------------------- |
| 学校管理 | 所有功能点可正常使用，业务规则符合需求 |
| 会员管理 | 支持三种登录方式，身份类型逻辑正确   |
| 学生管理 | 批量导入功能正常，数据校验完整     |
| 应用管理 | 接口授权可控制API访问权限      |
| 基础数据 | 年级、班级、学科、区域CRUD正常   |
| 权限控制 | 三种角色权限划分符合需求        |

### 10.2 性能验收标准

| 验收项   | 验收标准          |
| ----- | ------------- |
| 页面加载  | 首屏加载 ≤ 3秒     |
| API响应 | 95%请求 ≤ 500ms |
| 批量导入  | 1000条数据 ≤ 30秒 |

### 10.3 安全验收标准

| 验收项  | 验收标准                    |
| ---- | ----------------------- |
| 密码存储 | 密码使用BCrypt加密            |
| 登录保护 | 错误5次锁定10分钟              |
| 接口认证 | 所有API需Token/AppSecret认证 |
| 日志审计 | 敏感操作有审计记录               |

---

## 审核签字

| 角色    | 姓名  | 日期  | 签字  |
| ----- | --- | --- | --- |
| 产品负责人 |     |     |     |
| 技术负责人 |     |     |     |
| 测试负责人 |     |     |     |
| 项目经理  |     |     |     |

---

*文档结束*
