pangu-user-platform/.cursor/rules/pangu-project.mdc

---
description: 盘古用户平台项目规范
globs: 
alwaysApply: true
---

# 盘古用户平台（Pangu User Platform）项目规范

> **项目路径**：`/Users/felix/hbxhWorkSpace/pangu-user-platform`
>
> **重要声明**：本规范仅适用于 pangu-user-platform 项目，不受外部工程目录（如 `/Users/felix/hbxhWorkSpace/.cursorrules`）中其他规范的影响。当本规范与外部规范冲突时，以本规范为准。

## 作者规范（必须遵守）

> ⚠️ **强制要求**：本项目所有代码、文档、脚本的作者**必须**使用 **pangu**
> 
> **不要使用**：pangu、个人姓名、英文名或其他任何名称

| 位置 | 作者写法 |
|------|----------|
| Java @author | `@author pangu` |
| SQL 注释 | `-- 作者：pangu` |
| 文档署名 | `pangu` |
| Shell 脚本 | `# 作者：pangu` |

示例：
```java
/**
 * 学校管理服务
 * @author pangu
 */
public class SchoolService { }
```

```javascript
/**
 * 学校管理API
 * @author pangu
 */
```

```sql
-- 作者：pangu
```

## 项目信息

- **项目名称**：盘古用户平台（Pangu User Platform）
- **远程仓库**：http://47.99.144.51:3000/fangxh2013/pangu-user-platform
- **数据库**：pguser-db（courier_test 服务器：8.148.25.55）

## 技术栈

### 前端（pangu-ui）
- Vue 3.5.x + Element Plus 2.13.x + Vite 6.x
- 基于 RuoYi-Vue3 框架

### 后端（待开发）
- Spring Boot 3.3.x + JDK 17+
- 基于 RuoYi-Vue 框架

## API 接口规范（盘古做法）

本项目采用盘古(RuoYi)框架推荐的 API 前缀规范：

### 规则说明

| 位置 | 配置 | 说明 |
|------|------|------|
| 前端 baseURL | `/dev-api` | 开发环境 API 前缀 |
| 代理重写 | `/dev-api` → `''` | 去掉前缀后转发 |
| 后端接口 | 无前缀 | `/login`, `/system/user` |

### 请求流程

```
前端请求: /dev-api/system/user/list
   ↓ (vite 代理去掉 /dev-api)
后端接收: /system/user/list
```

### 代码示例

```javascript
// vite.config.js
proxy: {
  '/dev-api': {
    target: 'http://localhost:8080',
    rewrite: (p) => p.replace(/^\/dev-api/, '')  // 去掉前缀
  }
}
```

```java
// 后端 Controller - 不带 /api 前缀
@RestController
@RequestMapping("/system/user")
public class SysUserController { }

@RestController  // LoginController 无类级别前缀
public class LoginController {
    @GetMapping("/captchaImage")  // 直接 /captchaImage
    public AjaxResult getCaptchaImage() { }
}
```

### 注意事项

- **新建 Controller 不要添加 `/api` 前缀**
- 前端 API 调用路径如 `/system/user/list`，会被自动加上 `/dev-api` 前缀
- 生产环境通过 nginx 配置同样的代理规则

## 前后端数据命名规范

本项目前后端数据交互时，必须遵循以下命名规范：

### 命名风格对照

| 位置 | 命名风格 | 示例 |
|------|----------|------|
| 数据库字段 | snake_case（下划线） | `user_id`, `dept_name`, `create_time` |
| 后端返回 JSON | camelCase（小驼峰） | `userId`, `deptName`, `createTime` |
| 前端变量 | camelCase（小驼峰） | `userId`, `deptName`, `createTime` |

### 后端 Controller 返回规范

**重要**：后端使用 JdbcTemplate 直接查询时，必须将 snake_case 字段名转换为 camelCase 后再返回。

```java
// ❌ 错误：直接返回数据库字段名
List<Map<String, Object>> rows = jdbcTemplate.queryForList(sql);
return AjaxResult.success(rows);  // 前端收到 user_id, dept_name

// ✅ 正确：转换为驼峰格式
List<Map<String, Object>> rows = jdbcTemplate.queryForList(sql);
List<Map<String, Object>> result = new ArrayList<>();
for (Map<String, Object> row : rows) {
    Map<String, Object> item = new HashMap<>();
    item.put("userId", row.get("user_id"));
    item.put("deptName", row.get("dept_name"));
    item.put("createTime", row.get("create_time"));
    result.add(item);
}
return AjaxResult.success(result);  // 前端收到 userId, deptName
```

### 嵌套对象规范

当前端期望嵌套对象时（如 `user.dept.deptName`），后端需要构造嵌套结构：

```java
// 前端期望格式: { userId: 1, dept: { deptId: 100, deptName: "技术部" } }
Map<String, Object> item = new HashMap<>();
item.put("userId", row.get("user_id"));

Map<String, Object> dept = new HashMap<>();
dept.put("deptId", row.get("dept_id"));
dept.put("deptName", row.get("dept_name"));
item.put("dept", dept);
```

### 常见字段转换对照表

| 数据库字段 | 后端返回 JSON | 说明 |
|------------|---------------|------|
| `user_id` | `userId` | 用户ID |
| `user_name` | `userName` | 用户名 |
| `nick_name` | `nickName` | 昵称 |
| `dept_id` | `deptId` | 部门ID |
| `dept_name` | `deptName` | 部门名称 |
| `role_id` | `roleId` | 角色ID |
| `role_name` | `roleName` | 角色名称 |
| `menu_id` | `menuId` | 菜单ID |
| `menu_name` | `menuName` | 菜单名称 |
| `post_id` | `postId` | 岗位ID |
| `post_name` | `postName` | 岗位名称 |
| `dict_id` | `dictId` | 字典ID |
| `dict_name` | `dictName` | 字典名称 |
| `dict_type` | `dictType` | 字典类型 |
| `dict_label` | `dictLabel` | 字典标签 |
| `dict_value` | `dictValue` | 字典值 |
| `parent_id` | `parentId` | 父级ID |
| `order_num` | `orderNum` | 排序号 |
| `create_time` | `createTime` | 创建时间 |
| `update_time` | `updateTime` | 更新时间 |
| `create_by` | `createBy` | 创建人 |
| `update_by` | `updateBy` | 更新人 |

### 分页接口返回格式

分页列表接口统一使用 `TableDataInfo` 格式：

```java
TableDataInfo dataInfo = new TableDataInfo();
dataInfo.setCode(200);
dataInfo.setMsg("查询成功");
dataInfo.setRows(result);  // 转换后的驼峰格式数据
dataInfo.setTotal(total);
return dataInfo;
```

前端接收格式：
```json
{
  "code": 200,
  "msg": "查询成功",
  "rows": [{ "userId": 1, "userName": "admin" }],
  "total": 100
}
```

### 非分页接口返回格式

使用 `AjaxResult.success(data)` 格式：

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": [{ "menuId": 1, "menuName": "系统管理" }]
}
```

## 构建工具（build.sh）

后端项目提供了快速编译打包脚本，位于 `backend/build.sh`，支持多种编译模式。

### 常用命令

| 命令 | 说明 | 耗时 |
|------|------|------|
| `./build.sh -q` | 快速编译，仅检查语法错误 | ~4秒 |
| `./build.sh -p` | 增量打包（默认） | ~4秒 |
| `./build.sh -f` | 全量编译（clean + package） | ~30秒 |
| `./build.sh -m pangu-business` | 仅编译业务模块 | 更快 |
| `./build.sh -r` | 增量打包并重启后端 | ~27秒 |
| `./build.sh -m pangu-business -r` | 编译业务模块并重启 | ~27秒 |
| `./build.sh -c` | 仅清理 target 目录 | - |
| `./build.sh -h` | 显示帮助信息 | - |

### 开发建议

1. **日常开发**：修改代码后用 `-q` 快速检查语法错误
2. **本地测试**：用 `-r` 编译并重启服务
3. **仅改某模块**：用 `-m` 指定模块，加快编译速度
4. **部署前**：用 `-f` 全量编译确保干净

### 示例

```bash
# 进入后端目录
cd backend

# 快速检查语法
./build.sh -q

# 修改 pangu-business 模块后编译并重启
./build.sh -m pangu-business -r

# 全量编译
./build.sh -f
```

## 业务模块

| 模块 | 路径 | 说明 |
|------|------|------|
| 学校管理 | views/school/ | 管理学校、年级、班级 |
| 会员管理 | views/member/ | 管理家长/教师 |
| 学生管理 | views/student/ | 管理学生信息 |
| 应用管理 | views/application/ | 第三方应用接入 |
| 基础数据 | views/base/ | 年级/班级/学科/区域 |