254 lines
11 KiB
Markdown
254 lines
11 KiB
Markdown
<!-- code-review-graph MCP tools -->
|
||
## MCP Tools: code-review-graph
|
||
|
||
**IMPORTANT: This project has a knowledge graph. ALWAYS use the
|
||
code-review-graph MCP tools BEFORE using Grep/Glob/Read to explore
|
||
the codebase.** The graph is faster, cheaper (fewer tokens), and gives
|
||
you structural context (callers, dependents, test coverage) that file
|
||
scanning cannot.
|
||
|
||
### When to use graph tools FIRST
|
||
|
||
- **Exploring code**: `semantic_search_nodes` or `query_graph` instead of Grep
|
||
- **Understanding impact**: `get_impact_radius` instead of manually tracing imports
|
||
- **Code review**: `detect_changes` + `get_review_context` instead of reading entire files
|
||
- **Finding relationships**: `query_graph` with callers_of/callees_of/imports_of/tests_for
|
||
- **Architecture questions**: `get_architecture_overview` + `list_communities`
|
||
|
||
Fall back to Grep/Glob/Read **only** when the graph doesn't cover what you need.
|
||
|
||
### Key Tools
|
||
|
||
| Tool | Use when |
|
||
| ------ | ---------- |
|
||
| `detect_changes` | Reviewing code changes — gives risk-scored analysis |
|
||
| `get_review_context` | Need source snippets for review — token-efficient |
|
||
| `get_impact_radius` | Understanding blast radius of a change |
|
||
| `get_affected_flows` | Finding which execution paths are impacted |
|
||
| `query_graph` | Tracing callers, callees, imports, tests, dependencies |
|
||
| `semantic_search_nodes` | Finding functions/classes by name or keyword |
|
||
| `get_architecture_overview` | Understanding high-level codebase structure |
|
||
| `refactor_tool` | Planning renames, finding dead code |
|
||
|
||
### Workflow
|
||
|
||
1. The graph auto-updates on file changes (via hooks).
|
||
2. Use `detect_changes` for code review.
|
||
3. Use `get_affected_flows` to understand impact.
|
||
4. Use `query_graph` pattern="tests_for" to check coverage.
|
||
|
||
---
|
||
|
||
## 数据库操作规范
|
||
|
||
### PostgreSQL 序列同步规则（强制）
|
||
|
||
**问题背景**：项目使用 `BIGSERIAL` / `autoIncrement` 自增主键。当通过 SQL 手动 `INSERT` 指定 `id` 值时，PostgreSQL 序列不会自动跟进，导致后续 GORM 插入报 `duplicate key value violates unique constraint`。
|
||
|
||
**触发场景**：
|
||
- 测试数据脚本（如 `create_gallery_test_users.go`）硬编码 ID
|
||
- 数据迁移脚本手动插入记录
|
||
- DBeaver / psql 手动补数据
|
||
|
||
**规范要求**：
|
||
|
||
1. **任何手动指定 ID 的 INSERT 语句，末尾必须同步重置序列**：
|
||
```sql
|
||
-- 错误示例（会导致序列不同步）
|
||
INSERT INTO assets (id, name, ...) VALUES (1000, 'xxx', ...);
|
||
|
||
-- 正确示例
|
||
INSERT INTO assets (id, name, ...) VALUES (1000, 'xxx', ...);
|
||
SELECT setval('assets_id_seq', (SELECT MAX(id) FROM assets));
|
||
```
|
||
|
||
2. **脚本文件规范**：所有输出 SQL 的 Go 脚本（如 `backend/scripts/*.go`），必须在生成的 SQL 末尾包含序列重置语句：
|
||
```go
|
||
fmt.Printf(`SELECT setval('%s_id_seq', (SELECT MAX(id) FROM %s));\n`, tableName, tableName)
|
||
```
|
||
|
||
3. **新表创建时**：预留足够的序列起始值给测试数据：
|
||
```sql
|
||
CREATE SEQUENCE assets_id_seq START WITH 10000;
|
||
```
|
||
|
||
4. **定期检查**：环境部署后执行以下 SQL 确认序列健康：
|
||
```sql
|
||
SELECT
|
||
schemaname, sequencename, last_value,
|
||
(SELECT MAX(id) FROM assets) AS table_max_id,
|
||
last_value >= (SELECT MAX(id) FROM assets) AS is_healthy
|
||
FROM pg_sequences
|
||
WHERE sequencename = 'assets_id_seq';
|
||
```
|
||
|
||
**受影响表**（使用 autoIncrement 主键）：
|
||
- `assets`
|
||
- `asset_registry`
|
||
- `users`
|
||
- `stars`
|
||
- `activity_assets`
|
||
- `collection_assets`
|
||
- `materials`
|
||
- `exhibitions`
|
||
- `galleries`
|
||
- 以及其他所有 `id BIGSERIAL PRIMARY KEY` 的表
|
||
|
||
**违规后果**：生产环境报 `duplicate key` 导致用户铸造/创建失败，需紧急修复序列。
|
||
|
||
---
|
||
|
||
## Git 提交规范
|
||
|
||
### 核心规则：AI 不得主动 commit
|
||
|
||
**未经用户明确指示，AI 严禁执行 `git commit`。** 只有用户在消息中明确说出"帮我 commit"、"提交吧"、"commit 一下"等类似指令时，AI 才可以执行 commit 操作。除此之外，任何情况下都不允许 AI 自行提交。
|
||
|
||
**默认允许的 git 操作（只读 / 暂存）**：
|
||
- ✅ `git status`、`git diff`、`git log`、`git show` 等只读命令
|
||
- ✅ `git add <file>` 暂存指定文件（仅在用户明确要求时）
|
||
- ❌ `git commit` —— 必须由用户明确触发
|
||
- ❌ `git push` —— 必须由用户明确触发
|
||
- ❌ `git reset --hard`、`git push --force`、`git checkout .` 等破坏性操作 —— 一律禁止
|
||
|
||
### 附加规范
|
||
|
||
1. **commit 前确认**：执行 commit 前，先 `git status` 和 `git diff --staged` 确认暂存区内容与用户预期一致。
|
||
2. **commit 粒度**：一个 commit 只做一件事，不要把无关修改混在一起。
|
||
3. **默认分支保护**：当前在 `main` / `master` 时，不要直接修改，先提示用户创建 feature 分支。
|
||
4. **commit message**：使用 `Co-Authored-By: Claude <noreply@anthropic.com>` 结尾（仅在 AI 协助生成 commit 时）。
|
||
5. **不要自作主张**：即使代码写完、测试通过、用户长时间未回复，也**不要**主动 commit 等待用户确认。
|
||
|
||
**违规后果**：污染提交历史、丢失用户未保存的修改、误推到远端等难以撤销的问题。
|
||
|
||
---
|
||
|
||
## 自审与回归检查规范
|
||
|
||
### 核心规则：修复后必须做整体回归检查
|
||
|
||
**每次自审发现 bug 并完成修复后，必须对改动范围及周边逻辑做一次整体回归检查**，防止"修复 A 引入 B"的情况。
|
||
|
||
### 检查流程
|
||
|
||
1. **第一遍：定位并修复问题**
|
||
- 找到自审发现的问题点
|
||
- 实施修复
|
||
|
||
2. **第二遍：修复后整体回归（强制）**
|
||
- **改动文件本身**：确认修复没有破坏原有功能
|
||
- **直接调用方 / 被调用方**：通过 `query_graph pattern="callers_of"` / `callees_of"` 确认上下游不受影响
|
||
- **相邻模块**：同 package、同目录的相关文件需要扫一遍
|
||
- **测试用例**：如果项目有测试，跑一遍相关测试
|
||
- **依赖配置**：如果修改了 model/migration/route 等配置，确认下游消费方同步更新
|
||
|
||
3. **第三遍：交叉影响检查**
|
||
- 多个 bug 一起修时，要检查**修复之间**是否有冲突
|
||
- 公共函数 / 共享状态被多个修复点改动时，特别注意副作用
|
||
|
||
### 检查清单（自审模板）
|
||
|
||
修复完一个 bug 后，逐项过一遍：
|
||
|
||
- [ ] 修复是否解决了**原始问题**（不是新引入的问题）
|
||
- [ ] 修改的函数/方法的**所有调用方**是否仍能正常工作
|
||
- [ ] 相关单元测试是否通过 / 是否需要补充新用例
|
||
- [ ] 是否有**条件分支**（if/else、switch）只改了其中一支
|
||
- [ ] 错误处理 / 边界条件（空值、nil、超长、并发）是否被新逻辑覆盖
|
||
- [ ] 数据库 / API 字段变更是否同步更新了所有使用方
|
||
- [ ] 日志、错误信息、文档是否需要同步更新
|
||
|
||
### 违规后果
|
||
|
||
- 一次修复引入新 bug，调试时间翻倍
|
||
- 用户对代码质量失去信任
|
||
- 提交历史变成"反复横跳"的打补丁记录
|
||
|
||
---
|
||
|
||
## 接口开发规范
|
||
|
||
### 核心规则：添加/修改接口必须使用工程化方式完成
|
||
|
||
**每次新增或修改 API 接口时，必须以工程化、标准化方式完成**，禁止"能跑就行"的临时拼凑。完成后必须能直接通过代码审查，不需要大改。
|
||
|
||
### 工程化要求清单
|
||
|
||
1. **分层架构**（强制）：
|
||
- `handler`（控制器）：接收请求、参数绑定与校验、调用 service、组装响应
|
||
- `service`（业务层）：业务逻辑编排、事务控制、调用 repository
|
||
- `repository` / `dao`（数据层）：纯数据库操作，不含业务逻辑
|
||
- handler 中**禁止**直接调用 repository / 直接写 SQL
|
||
- service 中**禁止**直接操作 HTTP 请求/响应对象
|
||
|
||
2. **请求/响应 DTO**：
|
||
- 入参和出参使用独立的结构体（`XxxRequest` / `XxxResponse`）
|
||
- **禁止**直接用 DB model 当作入参或返回值
|
||
- 字段命名遵循项目既有规范（snake_case / camelCase）
|
||
- 敏感字段（密码、手机号、token）在响应中**必须脱敏或排除**
|
||
|
||
3. **参数校验**：
|
||
- 使用 `binding` / `validate` tag 在 handler 层做必填、长度、格式、枚举校验
|
||
- 业务规则校验放在 service 层
|
||
- 校验失败的错误信息要明确指出哪个字段、什么问题
|
||
|
||
4. **错误处理**：
|
||
- 使用项目统一的错误码/错误类型（如 `ErrCodeXxx`）
|
||
- **禁止**把原始 error 直接返回给前端
|
||
- **禁止**用 `_` 吞掉错误
|
||
- 关键业务错误必须打 ERROR 级别日志（含 trace_id / request_id）
|
||
|
||
5. **日志规范**：
|
||
- 接口入口：记录 method、path、request_id、用户身份（脱敏）
|
||
- 业务关键节点：状态流转、跨服务调用、缓存命中/未命中
|
||
- 异常退出：必须记录 stack trace 或 error cause
|
||
|
||
6. **API 文档**：
|
||
- 同步更新 Swagger / OpenAPI 注释
|
||
- 包含：接口描述、请求参数、响应示例、错误码列表、权限要求
|
||
- 字段类型、是否必填、示例值都要写清楚
|
||
|
||
7. **数据库变更**：
|
||
- 表结构变更必须写 migration
|
||
- 索引、外键、唯一约束、默认值要显式声明
|
||
- 影响现有数据的变更要考虑兼容方案（默认值、backfill）
|
||
|
||
8. **缓存策略**：
|
||
- 是否需要缓存、用什么 key、过期时间、缓存更新/失效策略要明确
|
||
- **禁止**缓存与 DB 数据不一致的方案（如只 set 不 delete）
|
||
|
||
9. **测试**：
|
||
- service 层核心业务逻辑必须覆盖单元测试
|
||
- handler 层至少一个 happy path + 一个 error case
|
||
- 数据库相关测试考虑使用事务回滚或测试容器
|
||
|
||
10. **遵循项目既有约定**：
|
||
- 命名风格、目录结构、文件命名、错误码定义与项目保持一致
|
||
- 复用项目已有的工具函数、中间件、错误处理逻辑
|
||
- **禁止**引入与项目风格冲突的新写法（例如项目用 snake_case 却写 camelCase）
|
||
|
||
### 禁止的反模式
|
||
|
||
- ❌ 在 handler 里直接写 SQL / ORM 调用
|
||
- ❌ 把 DB model 直接作为 API 入参或返回值
|
||
- ❌ 复制粘贴老接口代码不做适配（路径、参数、错误处理不一致）
|
||
- ❌ 用 `if err != nil { return err }` 一把梭，没有业务错误码
|
||
- ❌ 缺少或忘记更新 API 文档
|
||
- ❌ 改了表结构但没写 migration
|
||
- ❌ 没有写测试或测试只覆盖了 happy path
|
||
- ❌ 临时引入新的库/框架（未和项目既有技术栈对齐）
|
||
|
||
### 完成自检
|
||
|
||
接口写完后，逐项确认：
|
||
|
||
- [ ] 分层结构正确（handler / service / repository 各司其职）
|
||
- [ ] 入参/出参是独立 DTO
|
||
- [ ] 参数校验完整（必填、长度、格式、边界）
|
||
- [ ] 错误处理统一（错误码 + 友好提示 + 日志）
|
||
- [ ] 关键路径有日志
|
||
- [ ] Swagger 文档已更新
|
||
- [ ] DB 变更已写 migration
|
||
- [ ] 相关测试已编写并通过
|
||
- [ ] 命名、风格与项目既有代码一致
|