pangu-user-platform/README.md

# 盘古用户平台 (Pangu User Platform)

> 统一用户管理系统 - 面向教育行业的用户管理平台
> 
> **作者**: pangu

---

## 📁 项目目录结构

```
pangu-user-platform/           # 项目根目录
├── README.md                  # 项目说明文档
├── backend/                   # 后端代码 (RuoYi-Vue-Plus 5.5.x)
│   ├── README.md             # 后端构建说明 (重要!)
│   ├── pom.xml               # 后端父 POM
│   ├── pangu-admin/          # 启动与认证入口 (Spring Boot)
│   ├── pangu-common/         # 公共模块 (core/redis/security/satoken 等)
│   ├── pangu-modules/        # 业务与系统模块
│   │   ├── pangu-system/     # 系统 (用户/角色/菜单/部门/字典/监控)
│   │   ├── pangu-business/   # 业务 (学校/会员/学生/应用/基础数据/H5/开放API)
│   │   ├── pangu-generator/ # 代码生成
│   │   └── pangu-job/        # 定时任务
│   ├── pangu-extend/         # 扩展 (Monitor Admin、SnailJob Server 等)
│   ├── script/               # 数据库脚本等
│   └── 各模块 pom.xml
├── frontend/                  # 管理后台前端 (Vue3 + Element Plus + Vite)
│   ├── package.json
│   └── src/
└── docs/                      # 项目文档
    ├── 01-需求文档/
    ├── 02-系统设计/
    ├── 03-数据库设计/
    ├── 04-接口文档/
    ├── 05-前端UI规范/、05-技术方案/、05-模块技术方案/
    ├── 06-测试文档/
    └── 07-运维文档/
```

### 📌 重要说明

- **后端构建**：在 `backend` 目录执行 `mvn clean package -DskipTests -pl pangu-admin -am`，生成 `pangu-admin/target/pangu-admin.jar`。
- **前端构建**：在 `frontend` 目录执行 `npm run build:prod`，产出 `dist/`。
- 详细说明请查看: [backend/README.md](backend/README.md)

---

## 🚀 快速开始

### 1. 环境要求

| 组件 | 版本要求 |
|------|---------|
| JDK | 17+ |
| Maven | 3.6+ |
| Node.js | 16+ |
| MySQL | 8.0+ |
| Redis | 6.0+ |

### 2. 后端启动

```bash
# 进入后端目录
cd backend/pangu-admin

# 启动后端服务
mvn spring-boot:run
```

**访问地址**: `http://localhost:8080`

### 3. 前端启动

```bash
# 进入前端目录
cd frontend

# 安装依赖
npm install

# 启动开发服务器
npm run dev
```

**访问地址**: 以 vite 配置为准（如 `http://localhost:80`）

**默认账号**: admin / admin123

---

## 📦 技术栈

### 后端技术

| 技术 | 说明 | 版本 |
|------|------|------|
| Spring Boot | 基础框架 | 3.5.x |
| Sa-Token | 认证与权限 | 1.44.x |
| MyBatis-Plus | ORM框架 | 3.5.x |
| MySQL | 数据库 | 8.0+ |
| Redis / Redisson | 缓存 | 6.0+ |
| RuoYi-Vue-Plus | 基础框架 | 5.5.x |

### 前端技术

| 技术 | 说明 | 版本 |
|------|------|------|
| Vue | 前端框架 | 3.x |
| Element Plus | UI组件库 | 最新 |
| Vite | 构建工具 | 最新 |
| Axios | HTTP客户端 | 最新 |
| Vue Router | 路由管理 | 4.x |
| Pinia | 状态管理 | 最新 |

---

## 🎯 核心功能

### 业务功能模块

| 模块 | 功能 | 状态 |
|------|------|:----:|
| **学校管理** | 学校、年级、班级管理 | ✅ |
| **会员管理** | 家长/教师用户管理 | ✅ |
| **学生管理** | 学生信息、批量导入 | ✅ |
| **应用管理** | 第三方应用接入授权 | ✅ |
| **基础数据** | 年级、班级、学科、区域 | ✅ |

### 系统功能

- 用户认证 (手机号+密码/验证码/微信)
- 权限管理 (超级管理员/分公司用户/学校用户)
- 数据权限 (按区域/学校隔离)
- 系统监控 (在线用户、登录/操作日志、**服务监控**（CPU/内存/JVM/磁盘）、缓存监控)

---

## 📚 文档说明

| 文档类型 | 路径 |
|---------|------|
| 需求文档 | `docs/01-需求文档/` |
| 系统设计 | `docs/02-系统设计/` |
| 数据库设计 | `docs/03-数据库设计/` |
| 接口文档 | `docs/04-接口文档/` |
| 前端UI规范 | `docs/05-前端UI规范/` |
| 技术方案 | `docs/05-技术方案/` |
| 测试文档 | `docs/06-测试文档/` |
| 运维文档 | `docs/07-运维文档/` |

---

## 🔧 开发规范

### 代码规范

- 遵循 `/.cursorrules` 中定义的团队规范
- 注释使用中文，变量名使用英文
- 所有代码作者统一标注: **pangu**

### Git提交规范

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

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

---

## 📊 数据库

### 初始化

```bash
# 1. 创建数据库
CREATE DATABASE pangu_user_platform DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

# 2. 执行SQL脚本 (按顺序)
cd backend/sql
mysql -u root -p pangu_user_platform < ry_20250522.sql
mysql -u root -p pangu_user_platform < pangu_menu.sql
mysql -u root -p pangu_user_platform < pangu_base_data.sql
mysql -u root -p pangu_user_platform < pangu_school.sql
mysql -u root -p pangu_user_platform < pangu_member.sql
mysql -u root -p pangu_user_platform < pangu_student.sql
mysql -u root -p pangu_user_platform < pangu_application.sql
```

### 测试数据

```bash
# 导入测试数据
mysql -u root -p pangu_user_platform < backend/sql/test_data_101.sql
```

---

## 🧪 测试

### 功能测试

参考 `docs/06-测试文档/软件测试计划_v1.0.md`

### 测试报告

- `docs/06-测试文档/功能测试报告_2026-02-02.md` - 最新功能测试报告
- `docs/06-测试文档/最终交付测试报告_v2.0.md` - 交付测试报告

---

## 🌐 部署

### 后端部署

```bash
cd backend/pangu-admin
mvn clean package -DskipTests
java -jar target/pangu-admin.jar
```

### 前端部署

```bash
cd frontend
npm run build:prod
# 将 dist/ 目录部署到 Nginx
```

---

## 📝 更新日志

### v1.0.0 (2026-02-02)

✅ **完成功能**:
- 学校管理模块 (列表、新增、编辑、年级/班级管理)
- 会员管理模块 (列表、新增、编辑、重置密码)
- 学生管理模块 (列表、新增、编辑、批量导入)
- 应用管理模块 (列表、新增、编辑、接口授权、密钥管理)
- 基础数据模块 (年级、班级、学科、区域管理)

✅ **测试状态**:
- 核心功能测试 100% 通过
- 数据查询功能正常
- 搜索筛选功能正常

---

## 👥 团队

**开发团队**: pangu

---

## 📄 许可证

本项目为内部项目，未开源。

---

*最后更新: 2026-02-05*