pangu-user-platform/backend/README.md

# 盘古用户平台 - 后端项目

> **重要提示**: Maven 构建必须在项目根目录执行！
> 
> 根目录的 `pom.xml` 是父项目配置，管理所有后端子模块。

---

## 🏗️ 项目结构

```
backend/
├── pangu-admin/          # 启动模块 (Spring Boot 主应用)
├── pangu-common/         # 公共模块 (工具类、常量)
├── pangu-framework/      # 框架模块 (配置、拦截器)
├── pangu-system/         # 业务模块 (学校、会员、学生、应用)
├── sql/                  # 数据库脚本
└── scripts/              # 运维脚本
```

---

## 🚀 构建与启动

### Maven 构建

**必须在项目根目录执行：**

```bash
# 切换到项目根目录
cd /Users/felix/hbxhWorkSpace/pangu-user-platform

# 清理并打包
mvn clean package

# 跳过测试打包
mvn clean package -DskipTests
```

❌ **错误示例** (不要在 backend 目录执行):
```bash
cd backend
mvn clean package  # ❌ 这样会失败！
```

### 启动后端服务

**方式1: 在根目录通过模块指定启动**
```bash
cd /Users/felix/hbxhWorkSpace/pangu-user-platform
mvn -pl backend/pangu-admin spring-boot:run
```

**方式2: 进入子模块目录启动**
```bash
cd backend/pangu-admin
mvn spring-boot:run
```

**方式3: 运行打包后的 JAR**
```bash
java -jar backend/pangu-admin/target/pangu-admin.jar
```

---

## 📦 模块说明

### pangu-admin (启动模块)
- **作用**: Spring Boot 主应用，包含启动类
- **端口**: 8080
- **依赖**: pangu-framework, pangu-system

### pangu-common (公共模块)
- **作用**: 公共工具类、常量、异常定义
- **内容**:
  - 工具类 (DateUtils, StringUtils, ServletUtils)
  - 基础实体 (BaseEntity, AjaxResult)
  - 注解 (DataScope)

### pangu-framework (框架模块)
- **作用**: 框架配置、拦截器、切面
- **内容**:
  - Spring Security 配置
  - MyBatis-Plus 配置
  - Redis 配置
  - 全局异常处理

### pangu-system (业务模块)
- **作用**: 所有业务功能实现
- **包含**:
  - 学校管理 (school)
  - 会员管理 (member)
  - 学生管理 (student)
  - 应用管理 (application)
  - 基础数据 (base)

---

## 🗄️ 数据库

### 初始化脚本

```bash
cd 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 < sql/test_data_101.sql
```

---

## 🔧 配置文件

**配置文件位置**: `backend/pangu-admin/src/main/resources/application.yml`

**主要配置项**:
```yaml
server:
  port: 8080

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/pangu_user_platform
    username: root
    password: your_password
  
  redis:
    host: localhost
    port: 6379
```

---

## 📝 开发规范

### 包结构

```
com.pangu.xxx.controller   # 控制器
com.pangu.xxx.service      # 服务接口
com.pangu.xxx.service.impl # 服务实现
com.pangu.xxx.mapper       # Mapper 接口
com.pangu.xxx.domain       # 实体类
```

### 代码规范

- 所有作者标注: **湖北新华业务中台研发团队**
- 注释使用中文
- 遵循阿里巴巴 Java 开发规范

---

## 🐛 常见问题

### 1. 构建失败: "无法找到父项目"

**原因**: 在 backend 目录执行了 `mvn` 命令

**解决**: 切换到项目根目录执行

### 2. 启动失败: "数据库连接失败"

**检查**:
- MySQL 是否启动
- 数据库是否已创建
- application.yml 中的连接配置

### 3. 端口被占用

**解决**:
```bash
# 查找占用8080端口的进程
lsof -i :8080

# 杀掉进程
kill -9 <PID>
```

---

*开发团队: 湖北新华业务中台研发团队*
*最后更新: 2026-02-02*