pangu-user-platform/README.md

# 盘古用户平台（Pangu User Platform）

> 面向教育行业的统一用户管理系统

---

## 项目简介

盘古用户平台是一个基于 RuoYi-Vue 框架开发的教育行业用户管理系统，主要用于管理学校、教师、家长和学生信息，并为其他业务系统提供统一的用户认证和授权服务。

### 核心功能

- **学校管理**：管理学校、年级、班级的树形组织结构
- **会员管理**：管理前端用户（家长/教师），支持多种登录方式
- **学生管理**：管理学生信息，支持批量导入
- **应用管理**：管理第三方应用接入，控制API访问权限
- **基础数据**：年级、班级、学科、区域等基础数据维护
- **系统设置**：用户、角色、菜单、部门等系统管理（复用RuoYi）

### 角色权限

| 角色    | 权限范围            |
| ----- | --------------- |
| 超级管理员 | 全部功能，管理所有数据     |
| 分公司用户 | 管理所属区域的学校、会员、学生 |
| 学校用户  | 管理本校的教师、学生      |

---

## 技术栈版本

### 前端技术栈

| 框架/库             | 当前版本    | 官方最新版本           | 说明         |
| ---------------- | ------- | ---------------- | ---------- |
| **Vue**          | 3.5.26  | 3.5.26           | ✅ 最新稳定版    |
| **Vite**         | 7.3.1   | 7.3.1            | ✅ 最新稳定版    |
| **Element Plus** | 2.13.2  | 2.13.1           | ✅ 已是最新     |
| **Pinia**        | 3.0.4   | 3.0.4            | ✅ 最新稳定版    |
| **Vue Router**   | 4.6.4   | 4.6.4 (5.0.0刚发布) | ✅ 稳定版      |
| **Axios**        | 1.13.4  | 1.13.4           | ✅ 最新稳定版    |
| **MockJS**       | 1.1.0   | 1.1.0            | ✅ 用于Mock数据 |
| **Node.js**      | ≥18.0.0 | -                | 运行环境要求     |

### 后端技术栈

| 框架/库                | 推荐版本  | 官方最新版本 | 说明         |
| ------------------- | ----- | ------ | ---------- |
| **Spring Boot**     | 3.3.x | 4.0.2  | 建议使用LTS版本  |
| **Spring Security** | 6.x   | 6.4.x  | JWT认证      |
| **MyBatis Plus**    | 3.5.x | 3.5.9  | ORM框架      |
| **MySQL**           | 8.0+  | 8.0.40 | 数据库        |
| **Redis**           | 7.x   | 7.4.x  | 缓存/Session |
| **JDK**             | 17+   | 21 LTS | 运行环境       |

### 基础框架

| 框架            | 版本    | 说明     |
| ------------- | ----- | ------ |
| **RuoYi-Vue** | 3.8.8 | 后台管理框架 |

---

## 项目结构

```
pangu-user-platform/
├── docs/                           # 项目文档
│   ├── 01-需求文档/                 # 需求规格说明书
│   ├── 02-系统设计/                 # 系统设计文档
│   ├── 03-数据库设计/               # 数据库设计文档
│   ├── 04-接口文档/                 # 接口设计文档
│   └── 多Agent协同开发指南.md        # 前端多Agent开发文档
├── pangu-admin/                    # 后端启动模块
├── pangu-common/                   # 后端公共模块
├── pangu-framework/                # 后端框架模块
├── pangu-system/                   # 后端业务模块
├── ruoyi-ui/                       # 前端工程 (Vue 3 + Element Plus)
│   ├── src/
│   │   ├── api/                    # API接口定义
│   │   ├── mock/                   # Mock数据
│   │   ├── views/                  # 页面视图
│   │   └── ...
│   └── vite.config.js
├── sql/                            # 数据库脚本
│   ├── pangu_base_data.sql         # 基础数据表
│   └── pangu_menu.sql              # 菜单配置
├── pom.xml                         # Maven父工程
└── README.md
```

---

## 快速开始

### 环境要求

| 环境      | 版本要求    |
| ------- | ------- |
| Node.js | ≥18.0.0 |
| npm     | ≥9.0.0  |
| JDK     | ≥17     |
| Maven   | ≥3.8    |
| MySQL   | ≥8.0    |
| Redis   | ≥7.0    |

### 前端启动（Mock模式）

```bash
# 1. 进入前端目录
cd ruoyi-ui

# 2. 安装依赖
npm install

# 3. 启动开发服务器（Mock模式，无需后端）
npm run dev

# 4. 访问 http://localhost:80
```

> Mock 模式下无需启动后端，数据由 Mock.js 模拟返回。

### 后端启动

```bash
# 数据库：pguser-db（8.148.25.55:3306）
# 配置已写入 pangu-admin/src/main/resources/application.yml

# 1. 导入数据库脚本（首次执行）
mysql -h 8.148.25.55 -u root -p pguser-db < sql/pangu_base_data.sql
mysql -h 8.148.25.55 -u root -p pguser-db < sql/pangu_menu.sql

# 2. 编译并启动
mvn clean install -DskipTests
cd pangu-admin
mvn spring-boot:run

# 3. 后端启动成功后访问 http://localhost:8080
```

### 前后端联调

```bash
# 1. 修改前端配置 ruoyi-ui/.env.development
# 将 VITE_APP_MOCK = 'true' 改为 'false'

# 2. 重启前端
npm run dev

# 3. 前端请求将通过代理转发到后端 http://localhost:8080
```

---

## 功能模块

| 模块   | 路由            | 状态   | 说明         |
| ---- | ------------- | ---- | ---------- |
| 登录   | /login        | ✅ 完成 | 用户名密码+验证码  |
| 首页   | /dashboard    | ✅ 完成 | 统计卡片       |
| 学校管理 | /school       | ✅ 完成 | 左侧区域树+右侧列表 |
| 会员管理 | /member       | ✅ 完成 | 家长/教师管理    |
| 学生管理 | /student      | ✅ 完成 | 左侧学校树+右侧列表 |
| 应用管理 | /application  | ✅ 完成 | 第三方应用接入    |
| 年级管理 | /base/grade   | ✅ 完成 | 基础数据       |
| 班级管理 | /base/class   | ✅ 完成 | 基础数据       |
| 学科管理 | /base/subject | ✅ 完成 | 基础数据       |
| 区域管理 | /base/region  | ✅ 完成 | 树形表格       |

---

## 文档说明

| 文档         | 路径                   | 说明                      |
| ---------- | -------------------- | ----------------------- |
| 需求规格说明书    | docs/01-需求文档/        | 详细功能需求，用于评审             |
| 系统设计文档     | docs/02-系统设计/        | 架构设计、模块设计               |
| 数据库设计文档    | docs/03-数据库设计/       | 表结构、ER图、初始数据            |
| 接口设计文档     | docs/04-接口文档/        | API接口规范                 |
| 学生管理技术方案   | docs/05-模块技术方案/学生管理/ | 学生管理模块前后端技术方案、开发任务、测试用例 |
| 多Agent开发指南 | docs/多Agent协同开发指南.md | 前端协同开发说明                |

---

## 原型设计

- **墨刀原型**：https://modao.cc/proto/atlwMul8t9pi6yxQ42W7up/sharing
- **页面数量**：17个
- **访问方式**：只读模式

### 原型批注要点

> 详细批注信息见 `docs/01-需求文档/需求规格说明书_v1.0.md` 第8章

| 模块       | 关键批注                                         |
| -------- | -------------------------------------------- |
| **全局**   | 系统支持3个角色：管理员、分公司用户、学校用户；会员需使用token支持小程序/H5登录 |
| **学校管理** | 学校下新增年级/班级为挂载模式（非新建）；删除需检查子级和引用；所有删除为软删除     |
| **会员管理** | 支持3种登录方式；教师必须绑定学校信息且只能绑定本校学生；家长可绑定任意学生       |
| **学生管理** | 批量导入时自动创建不存在的家长用户（初始密码：123456）               |
| **应用管理** | 重置密钥需弹窗显示并支持复制；接口授权采用勾选方式                    |
| **区域管理** | 新增下级时自动带入父级区域                                |

### 示例数据

**区域示例：**

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

**学校示例：**

- 武汉市第一中学（七年级1-3班、八年级、九年级）
- 武汉市第三中学
- 武汉市水果湖小学（一至六年级）

**应用示例：**

- AI智慧平台（YY000001）- 授权接口：学校接口、年级接口、班级接口

---

## 开发规范

### 作者规范

> **重要**：本项目所有文档、代码注释的作者统一使用 **湖北新华业务中台研发团队**

- 文档的作者/编写团队：`湖北新华业务中台研发团队`
- 代码注释中的 @author：`湖北新华业务中台研发团队`
- 不使用个人姓名或其他名称

### 代码规范

- 遵循《湖北新华业务中台代码规范》
- 类/方法使用Javadoc注释
- 使用统一的返回格式和异常处理

### 分支管理

| 分支        | 用途         |
| --------- | ---------- |
| master    | 主分支，生产环境代码 |
| develop   | 开发分支       |
| feature/* | 功能分支       |
| hotfix/*  | 紧急修复分支     |

### 提交规范

```
<type>: <简要描述>

类型说明：
- feat: 新功能
- fix: 修复Bug
- docs: 文档修改
- style: 代码格式调整
- refactor: 代码重构
- test: 测试相关
- chore: 构建/工具变动
```

---

## 版本更新日志

### v1.0.1 (2026-01-31)

**文档完善：**

- 需求规格说明书：补充墨刀原型批注汇总（第8.3章）
- 数据库设计文档：补充学校/会员/学生/应用示例数据
- 接口设计文档：补充业务规则说明（第10章）
- README.md：补充原型批注要点和示例数据

### v1.0.0 (2026-01-31)

**前端技术栈升级：**

- Vue 3.5.24 → 3.5.26
- Vite 7.2.4 → 7.3.1

**功能完成：**

- 完成登录、首页、学校管理等10个功能模块
- 完成所有Mock数据和API接口定义
- 完成多Agent协同开发指南

---

## 仓库地址

- **Gitea**: http://47.99.144.51:3000/fangxh2013/pangu-user-platform

---

## 联系方式

- **团队**：pangu
- **创建时间**：2026-01-31

---

*最后更新：2026-01-31*