# ghb-base — AI 开发总纲

> coverage: 聚合版，可直接粘贴到 Kimi / DeepSeek / GPT 等无自动加载的 AI 对话中。自动加载工具（Claude Code / Cursor / Codex / Copilot / Windsurf）会从对应入口文件读取。
>
> 所有 AI 编码助手首先读本文件。读完本文件后，必须继续读取 `.claude/` 目录下的全部规则文件，再开始编写代码。

## 项目信息

- **名称**：ghb-base（基于 JeecgBoot 3.9.2 精简）
- **技术栈**：Spring Boot 3.5.5 / Java 17 / MyBatis-Plus / Shiro+JWT / MySQL / Redis
- **包名**：`com.ghb.base` | 数据库：`ghb_base` | 上下文路径：`/ghb`
- **前端**：Vue 3 + Vite + Ant Design Vue + TypeScript

## 模块

```
ghb-base-parent/
├── ghb-base-core/          # 核心框架（不改）
├── ghb-module-system/      # 租户/用户/角色/菜单/字典/日志（不改）
├── ghb-module-business/    # 业务代码 ← 写这里
└── ghb-server-cloud/       # 微服务（网关/Nacos/监控）
```

## 必读规则（全部读完再写代码）

1. `.claude/contract.md` — 返回格式 · 分页 · 状态值 · 契约生命周期 · 同步铁律
2. `.claude/backend.md` — 分层 · 命名 · 注释 · CRUD 模板 · 禁止清单 · 检查表
3. `.claude/frontend.md` — 样式 · 命名 · 注释 · 组件铁律 · 页面模板 · 检查表
4. `.claude/database.md` — 表设计 · 字段类型 · 索引 · 必有字段 · 检查表
5. `.claude/git.md` — 分支命名 · commit 格式 · AI 提交标注 · 禁止操作
6. `.claude/security.md` — 认证 · 数据权限 · 敏感信息 · 文件上传 · 日志
7. `.claude/testing.md` — 测试要求 · 错误码 · 全局异常处理 · 检查表
8. `.claude/encoding.md` — 字符编码（UTF-8 无 BOM · 禁 GBK · 批量改写须 UTF-8 感知）

## 接口契约

契约文件在 `contract/` 目录（独立 git 仓库，前后端 submodule 引用）。修改接口前必须先更新契约。

## 环境要求

- JDK 17+
- Maven 3.8+
- MySQL 8.0+
- Redis 6.0+
- Node.js 18+ / pnpm

```bash
# 后端启动
cd test-module-system/test-system-start
mvn spring-boot:run -Pdev

# 前端启动
cd ghb-frontend
pnpm install
pnpm dev
```

## 多工具兼容

| 工具 | 入口文件 | 操作 |
|------|----------|------|
| Claude Code | `CLAUDE.md` | 自动加载，无需操作 |
| Cursor | `.cursorrules` | 自动加载，无需操作 |
| Codex / OpenCode | `AGENTS.md` | 自动加载，无需操作 |
| GitHub Copilot | `.github/copilot-instructions.md` | 自动加载，无需操作 |
| Windsurf | `.windsurfrules` | 自动加载（把 CLAUDE.md 复制一份改名为 .windsurfrules） |
| **Kimi / DeepSeek / GPT** | 无自动 | **手动粘贴**：把本文件 + `.claude/` 全部内容一次性贴到对话开头 |
| **人工开发** | 无自动 | 阅读 `开发规范-人工版.md`（同级目录） |

---

## 审查机制 — 怎么检查代码是否合规

### 自动化检查（提交前自动跑）

```bash
# 后端代码检查
mvn checkstyle:check          # Java 代码风格
mvn test                       # 单元测试

# 前端代码检查
pnpm lint                      # ESLint
pnpm stylelint                 # 样式检查

# 数据库 SQL 检查
# 人工 review：金额字段是不是 DECIMAL、有没有 COMMENT、有没有 create_time
```

### AI 产出专项检查

| 检查项 | 怎么查 | 不合格的表现 |
|--------|--------|-------------|
| 返回值是否包装 | `grep -r "return [^R]" --include="*.java" | grep -v Result` | 出现裸 `return data;` |
| 手写 SQL 是否带租户 | `grep -r "@Select" --include="*.java"` | SQL 里没有 `tenant_id` |
| Controller 是否写了业务逻辑 | 人工 review Controller 方法体 | 超过 20 行或有 `if/else` 嵌套 |
| Commit 是否标注 AI | `git log --oneline -20` | 没有 `[AI: xxx]` 标记 |
| 是否包含测试 | `git diff --stat` 看是否有测试文件 | 新功能没测试类 |

### PR Review 必查清单

```
□ 接口变更 → contract/ 目录有对应更新
□ 返回格式 → 全部用 Result 包装
□ 手写 SQL → 有 tenant_id 条件
□ 新增表 → 有 create_time / update_time / COMMENT
□ 金额字段 → 类型是 DECIMAL
□ 硬编码 → 无魔法数字、无裸色值、无裸字号
□ Commit → 格式正确，AI 代码有标注
□ 测试 → 新功能有测试代码
```

### 常见违规信号

| 信号 | 可能的问题 |
|------|-----------|
| `return data;`（裸返回） | 没读规则 |
| `@Select("SELECT * FROM xxx WHERE ...")` 缺 tenant_id | 数据泄露风险 |
| 类名超过 35 字符 | 没缩写 |
| `color: #` 硬编码 | 没读前端规则 |
| `git commit -m "update"` | 没读 Git 规则 |
| Controller 超过 100 行 | 业务逻辑泄漏到接口层 |