273 lines
7.4 KiB
Plaintext
273 lines
7.4 KiB
Plaintext
---
|
||
description: 盘古用户平台项目规范
|
||
globs:
|
||
alwaysApply: true
|
||
---
|
||
|
||
# 盘古用户平台（Pangu User Platform）项目规范
|
||
|
||
> **项目路径**：`/Users/felix/pgWorkSpace/pangu-user-platform`
|
||
>
|
||
> **重要声明**：本规范仅适用于 pangu-user-platform 项目，不受外部工程目录（如 `/Users/felix/pgWorkSpace/.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）
|
||
|
||
## 技术栈
|
||
|
||
### 前端（frontend）
|
||
- 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/ | 年级/班级/学科/区域 |
|