122 lines
4.7 KiB
Markdown
122 lines
4.7 KiB
Markdown
# 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 行 | 业务逻辑泄漏到接口层 |
|