# ghb-base 开发规范（人工版）

> 给不用 AI 编码的开发者阅读。用 AI 写代码的看 `.claude/` 目录。


## 一、返回格式（不变式）

**所有接口必须用 `Result<T>` 包装：**

```java
// ✅ 正确
return Result.OK(data);
return Result.OK("操作成功", data);
return Result.error("参数错误");

// ❌ 禁止
return data;
return "success";
return Map.of(...);
```

**分页格式：** `{ code, message, data: { records, total, size, current } }`

**日期格式：** 统一 `yyyy-MM-dd HH:mm:ss`

**状态值：** 枚举中文值必须从 `contract/common/status-map.md` 取，不许硬编码前端文案同义替换（"已拒绝"="拒绝"之类）。


## 二、分层规则

```
controller/     — 参数校验 + 调用 service + 返回 Result，不许写业务逻辑
service/        — 业务逻辑，事务管理
mapper/         — SQL（MyBatis XML 或 @Select），不许写业务逻辑
entity/         — 表映射，纯数据对象
```

**禁止：Controller 超过 20 行、Controller 里有 if/else 嵌套、Service 里直接操作 HttpServletRequest**


## 三、命名规则

| 元素 | 规则 | 示例 |
|------|------|------|
| 类名 | 大驼峰，名词 | `TaskController`，❌ `taskController` |
| 方法名 | 小驼峰，动词开头 | `getById()`，❌ `getbyid()` |
| 变量 | 小驼峰，有意义 | `taskList`，❌ `list` `data` |
| 包名 | 全小写 | `com.ghb.base.modules.business` |
| 表名 | 小写，下划线，单数 | `task_apply`，❌ `TaskApply` |
| 字段名 | 小写，下划线 | `create_time`，❌ `createdAt` |
| 主键 | 统一 `id` | ❌ `task_id` |
| 外键 | `关联表_id` | `user_id`，❌ `uid` |
| 布尔 | `del_flag` 或明确业务含义的 `is_` 前缀 | `del_flag`，❌ `deleted` |

**长度控制：** 类名/表名超过 3 个单词或 30 字符必须缩写。缩写必须一眼能认出含义：

| 完整 | 缩写 |
|------|------|
| department | dept |
| permission | perm |
| message | msg |
| enterprise | ent |


## 四、字段类型

| 场景 | 类型 |
|------|------|
| 金额 | `DECIMAL(15,2)`，❌ `FLOAT` `DOUBLE` |
| 时间 | `DATETIME`，❌ `VARCHAR` `TIMESTAMP` |
| 状态 | `VARCHAR(20)`，存英文枚举值 |
| 文本 | `VARCHAR(N)`（长度写死，不用 TEXT） |

**必有字段：** 每张表必须包含 `id` `create_by` `create_time` `update_by` `update_time`。每个字段必须有 `COMMENT`。


## 五、索引规则

| 场景 | 索引 |
|------|------|
| 外键 | 必须建索引 |
| WHERE 高频字段 | 必须建索引 |
| 唯一约束 | `uk_表名_字段` |
| 普通索引 | `idx_表名_字段` |


## 六、Git 规则

**分支：** `dev`（开发）/ `master`（生产）。新功能从 `dev` 拉，合回 `dev`。

**Commit 格式：**
```
<type>: <简短描述>

[AI: 模型名]
```

**Type：** feat / fix / refactor / docs / style / test / chore

**禁止：** `git push --force`、commit 只写 "update"、提交含硬编码密钥


## 七、安全规则

- 所有接口（除登录）必须验证 JWT Token
- 涉及租户数据的 SQL 必须带 `tenant_id` 条件
- 密码/密钥/Token 禁止硬编码、禁止 log 输出、禁止提交到 Git
- 文件上传限制大小（≤10MB）和类型（白名单）
- 用户输入必须做 XSS 过滤
- 日志不输出敏感信息（手机号脱敏 176****2303）


## 八、编码规则

- 所有源文件：UTF-8 无 BOM
- 禁止 GBK/GB2312
- `ghb-backend/.editorconfig` 和 `ghb-frontend/.editorconfig` 各一个，不要覆盖
- **Windows 终端重定向（`>` `>>`）会按 GBK 写入，不要用**


## 九、测试规则

**必须写测试：**
- 新增 Service 方法 → 单元测试
- 新增 Controller 接口 → 集成测试
- 涉及金额计算 → 单元测试（多组边界值）
- 涉及状态流转 → 单元测试（覆盖所有路径）

**错误码：** 200 成功 / 400 参数错误 / 401 未登录 / 403 无权限 / 500 服务器异常


## 十、前端规则

**样式铁律：**
- 颜色禁硬编码（`color: #333` ❌），走主题变量
- 字号/间距禁硬编码，走全局类或 Less 变量
- 所有文案必须走 i18n，不能写死中文

**命名规则：**

| 元素 | 规则 | 示例 |
|------|------|------|
| 组件文件 | kebab-case | `task-card.vue`，❌ `TaskCard.vue` |
| 组件 name | PascalCase | `TaskCard` |
| CSS 类名 | kebab-case | `.task-card`，❌ `.taskCard` |
| JS 变量 | 小驼峰 | `taskList`，❌ `task_list` |

**代码修改痕迹：** 所有新增或修改的代码块必须用 `// update-begin` / `// update-end` 包裹，注明 author/date/原因。


## 十一、提交前检查表

```
□ 接口变更 → contract/ 同步更新
□ 返回格式 → 全部用 Result 包装
□ 手写 SQL → 有 tenant_id 条件
□ 新增表 → create_time / update_time / COMMENT 完整
□ 金额字段 → DECIMAL 类型
□ 无硬编码魔法数字/裸色值
□ Commit 格式正确
□ 测试通过
```