<!-- 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
- [ ] 相关测试已编写并通过
- [ ] 命名、风格与项目既有代码一致