topfans/CLAUDE.md

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 语句，末尾必须同步重置序列：

   -- 错误示例（会导致序列不同步）
   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 末尾包含序列重置语句：

   fmt.Printf(`SELECT setval('%s_id_seq', (SELECT MAX(id) FROM %s));\n`, tableName, tableName)
   

3. 新表创建时：预留足够的序列起始值给测试数据：

   CREATE SEQUENCE assets_id_seq START WITH 10000;
   

4. 定期检查：环境部署后执行以下 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 导致用户铸造/创建失败，需紧急修复序列。