test-backend/CLAUDE.md

ghb-base — AI 开发总纲

所有 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 感知 · mojibake 还原）

接口契约

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

环境要求

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

# 后端启动
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（同级目录）

---

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

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

# 后端代码检查
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`
手写 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 行	业务逻辑泄漏到接口层