pangu-user-platform/README.md

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

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

---

## 📁 项目目录结构

```
pangu-user-platform/           # 项目根目录
├── pom.xml                    # ⭐ Maven父项目配置 (必须在根目录)
├── README.md                  # 项目说明文档
├── backend/                   # 后端代码
│   ├── README.md             # 后端构建说明 (重要!)
│   ├── pangu-admin/          # 启动模块 (Spring Boot)
│   │   └── pom.xml           # 子模块配置
│   ├── pangu-common/         # 公共模块 (工具类、常量)
│   │   └── pom.xml
│   ├── pangu-framework/      # 框架模块 (配置、拦截器)
│   │   └── pom.xml
│   ├── pangu-system/         # 业务模块 (学校、会员、学生、应用)
│   │   └── pom.xml
│   ├── sql/                  # 数据库脚本
│   └── scripts/              # 运维脚本
├── frontend/                  # 前端代码
│   └── frontend/             # Vue3 + Element Plus + Vite
│       ├── package.json      # 前端依赖配置
│       └── README.md         # 前端使用说明
└── docs/                      # 项目文档
    ├── 01-需求文档/
    ├── 02-系统设计/
    ├── 03-数据库设计/
    ├── 04-接口文档/
    ├── 05-前端UI规范/
    ├── 05-技术方案/
    ├── 05-模块技术方案/
    ├── 06-测试文档/
    └── 07-运维文档/
```

### 📌 重要说明

**根目录的 `pom.xml` 为什么不在 backend 目录？**

这是 Maven 多模块项目的标准结构：
- 根 `pom.xml` 是**父项目配置**，管理所有子模块
- Maven 构建**必须从根目录**执行: `mvn clean package`
- 不要移动到 backend 目录，否则构建会失败

详细说明请查看: [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/frontend

# 安装依赖
npm install

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

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

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

---

## 📦 技术栈

### 后端技术

| 技术 | 说明 | 版本 |
|------|------|------|
| Spring Boot | 基础框架 | 2.7.18 |
| Spring Security | 安全框架 | 5.7.x |
| MyBatis-Plus | ORM框架 | 3.5.x |
| MySQL | 数据库 | 8.0.x |
| Redis | 缓存 | 6.0.x |
| JWT | 认证 | 0.9.1 |
| Druid | 连接池 | 1.2.x |

### 前端技术

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

---

## 🎯 核心功能

### 业务功能模块

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

### 系统功能

- 用户认证 (手机号+密码/验证码/微信)
- 权限管理 (超级管理员/分公司用户/学校用户)
- 数据权限 (按区域/学校隔离)
- 系统监控 (在线用户、日志、缓存)

---

## 📚 文档说明

| 文档类型 | 路径 |
|---------|------|
| 需求文档 | `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/frontend
npm run build
# 将 dist/ 目录部署到 Nginx
```

---

## 📝 更新日志

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

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

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

---

## 👥 团队

**开发团队**: pangu

---

## 📄 许可证

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

---

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