nj/CLAUDE.md

@wiki/index.md 整个项目对话都使用中文进行，包括文档、代码注释、事件名称等。

HMS 健康管理平台 — 协作与实现规则

Health Management System (HMS) — 面向体检中心/医疗机构的综合健康管理平台。从 ERP 底座分叉独立，继承身份权限/工作流/消息/配置等基础能力，erp-health 原生模块承载医疗业务。

当前阶段: erp-health 模块开发。 设计规格已确认，开始实施。

1. 项目定位

1.1 这是什么

一个 健康管理 + ERP 基础设施 架构的医疗 SaaS 平台：

• 医疗核心 — 患者管理、健康数据、预约排班、随访管理、咨询管理（原生 Rust 模块 erp-health）
• 基础底座 — 身份权限、工作流引擎、消息中心、系统配置（继承自 ERP）
• 多租户 + 私有化 — 默认 SaaS 共享数据库隔离，支持独立 schema 私有部署
• Web 优先 — 浏览器 SPA 是 PC 管理后台主力，小程序（患者端/医护端）独立开发

1.2 决策原则

任何改动都要问：这对健康管理平台的医疗业务和可扩展性有帮助吗？

• ✅ 完善模块接口和 trait 定义 → 最高优先
• ✅ 确保多租户隔离的正确性 → 最高优先
• ✅ 按计划推进 Phase 交付物 → 高优先
• ✅ 清晰的模块边界和事件契约 → 高优先
• ❌ 跳过 Phase 顺序提前实现远期功能 → 禁止
• ❌ 在模块间创建直接耦合 → 永远不做
• ❌ 硬编码租户 ID 或绕过多租户中间件 → 永远不做
• ❌ 过度设计未来才需要的能力 → 永远不做

1.3 架构铁律

约束	原因
模块间只通过事件总线和 trait 通信	保证模块可独立拆分为微服务
所有数据表必须含 tenant_id	多租户是核心能力，不可事后补
使用 UUID v7 作为主键	时间排序 + 唯一性，分布式友好
软删除，不硬删除	ERP 数据不可丢失，审计追溯需要
所有 API 使用 /api/v1/ 前缀	版本化是 SaaS 产品的基本要求

---

2. 工作风格

2.1 按计划推进

• 严格按 Phase 顺序执行 — Phase 2 依赖 Phase 1 的基础设施
• 每个 Task 完成后立即提交 — 不积压，保持可追溯
• 先测试后实现 — TDD 流程：写失败测试 → 实现 → 通过 → 提交

2.2 分步编写文档（强制）

编写计划、设计文档、实施报告等长文档时，必须分步编写，禁止一次性输出全文：

1. 先写大纲 — 确认文档结构和章节划分
2. 逐章编写 — 每次只写 1-2 个章节，写完确认后继续下一章
3. 最终整合 — 所有章节完成后合并为完整文档

原因： 上下文过长会导致输出截断或卡死。分步编写保证每步都能完整输出，且用户可以中途调整方向。

适用范围： 超过 200 行的文档、实施计划、设计规格、技术报告等。简短的 bugfix 说明、单页 wiki 更新不受此限制。

2.3 讨论记录

每次发散式讨论（brainstorming、方案探索、需求梳理、技术选型等）必须建立独立文档：

• 存放位置： docs/discussions/YYYY-MM-DD-{主题简称}.md
• 文档格式：

  # {讨论主题}
  > 日期: YYYY-MM-DD | 参与者: ...
  
  ## 背景
  为什么会有这次讨论
  
  ## 讨论要点
  - 要点 1
  - 要点 2
  
  ## 结论 / 待定
  达成的共识或遗留问题
  

• 时机： 讨论结束后立即创建，不要积压。如果讨论横跨多个主题，拆分为多份文档。
• 用途： 作为后续实施的输入和决策追溯的依据，避免"之前讨论过但忘了结论"。

2.4 模块化思维

开发任何功能时先问：

1. 它属于哪个模块？ — 不确定就放到 erp-core 共享层
2. 它的接口是什么？ — 先定义 trait，再实现
3. 它需要发什么事件？ — 跨模块通知必须走事件总线
4. 其他模块怎么发现它？ — 通过 ErpModule trait 注册

2.5 闭环工作法（强制）

每次改动必须按顺序完成以下步骤，不允许跳过：

0. 阅读 Wiki（强制起点） — 收到任何任务后，先读 wiki 再动手：
   • 读取 wiki/index.md 了解项目全貌和当前进度
   • 根据任务涉及的范围，读取相关 wiki 页面（wiki/infrastructure.md、wiki/testing.md、wiki/wasm-plugin.md 等）
   • wiki 中包含实际的环境配置（数据库连接、端口、登录凭据、启动方式），不看 wiki 就无法正确验证
   • 违反此步骤 = 盲目工作，浪费时间去猜环境配置，产出不可信
1. 现状确认（强制） — 动手之前，先检查代码里已经有什么：
   • 用 Grep/Glob/Read 工具搜索相关文件，确认哪些能力已存在
   • 明确列出"已有"和"缺失"，不允许凭印象断言缺失
   • 如果不确定现有实现状态，停下来问用户，不要编造
   • 违反此步骤 = 所有后续工作可能脱离实际，白费力气
2. 理解需求 — 确认改动的目标模块和影响范围
3. 最小实现 — 只改必要的代码，保持模块边界
4. 验证通过 — 必须全部通过才可继续：
   • cargo check — 编译无错误
   • cargo test --workspace — 所有测试通过（有相关测试时）
   • 功能验证 — 启动后端 + 前端服务，在浏览器中实际操作验证改动生效（涉及 API 或 UI 时）
   • pnpm build — 前端生产构建通过（涉及前端时）
5. 提交 + 文档 + 推送（三合一，强制） — 验证通过后按顺序执行：
   • a. 按 §5 规范提交代码
   • b. 检查本次变更是否触发 wiki 更新（见下方 wiki 更新触发条件），触发则更新后单独 docs(wiki) 提交
   • c. git push 立即推送，不允许"等一下再推"
   • 禁止连续 5 个非 docs 提交而不更新 wiki 关键数字

wiki 更新触发条件（步骤 5b 的判定标准）

以下任一条件满足时，必须更新 wiki 后才能继续下一任务：

• fix 提交 → wiki/index.md 症状导航新增条目或标记"已修复"
• feat 提交（新功能） → wiki/index.md 关键数字更新 + 对应模块 wiki 页更新（实体数/路由数/端点数等）
• 数据库迁移变化 → 关键数字中的迁移数/表数更新
• API 路由变化 → 路由数更新
• 测试数量变化 → 测试数/断言数更新
• 连续 5 个代码提交 → 强制做一次 wiki/index.md 关键数字全文校正（对比代码实际数量）

铁律：

• 步骤 0 阅读 Wiki 是绝对起点 — 不读 wiki 就开干 = 连环境配置都不知道，所有验证步骤都是空谈。
• 步骤 1 现状确认是强制起点 — 不检查就开干 = 脱离实际，所有产出不可信。
• 步骤 4 功能验证必须实际操作 — 只看编译通过不算验证，必须启动服务、在浏览器中确认功能正常。
• 步骤 5 三合一是强制流程 — 提交后必须检查 wiki、必须推送，缺一不可。
• 每次新会话开始时，先检查是否有未推送的提交并立即推送。

2.6 Feature DoD — 功能完成定义（强制）

历史数据显示 24% 的提交是 fix，根因是缺少统一的完成标准。 每个功能标记"完成"前，必须逐项检查以下清单，不允许跳过。

后端

• Entity 包含所有标准字段（id/tenant_id/created_at/updated_at/created_by/updated_by/deleted_at/version）
• Handler 添加 require_permission 权限守卫
• 权限码已写入 seed 迁移（每个实体 .list + .manage，权限码前缀与实体名一致）
• utoipa 注解已添加（#[derive(utoipa::OpenApi)] + path/response schema）
• Service 层核心路径有单元/集成测试
• 多租户隔离正确（所有查询含 tenant_id 过滤，无手写 SQL 拼接）
• 输入验证完整（必填字段 + 格式校验 + 长度限制）
• 错误处理统一（AppError，不 panic，不 unwrap 生产代码）
• 关键操作有 tracing 日志（info/warn/error 级别合理）

前端（Web）

• API 路径与后端 OpenAPI spec 一致（不手写路径，从 api/health/ 模块调用）
• 路由声明权限码（permissions: [...]），与后端 handler 一致
• 菜单配置已更新（parent_id 正确 + permission 字段 + menu_roles 关联）
• 错误状态有用户友好提示（不显示原始 error message）
• 不使用 any 类型（用 unknown + 类型守卫）

前端（小程序）

• Service 层接口契约与后端 DTO 一致（字段名/类型/结构体）
• 登录态处理正确（useDidShow 恢复认证、退出清理 Storage）
• 页面间数据通过 API 获取，不用 Storage 传递
• 长者模式适配完成（字号 ≥ 22px）
• 图片使用合法 URL（HTTPS 或相对路径，不用 HTTP）

安全

• 新增端点有权限声明（默认拒绝，不是默认放行）
• 敏感数据有脱敏/加密处理（PII 字段走 AES-256-GCM）
• 用户输入已验证和消毒（防 SQL 注入、XSS、命令注入、路径穿越）
• 无 CORS 通配符、无硬编码密钥、无 fallback 默认密钥
• 日志中无敏感数据输出（密码、token、身份证号、手机号等）
• 文件上传有 MIME 类型验证 + 大小限制 + 路径穿越防护
• API 响应不暴露内部实现细节（数据库错误、堆栈跟踪、文件路径）
• 速率限制已配置（认证端点更严格）
• 密钥通过环境变量注入，.env.example 已同步更新

文档一致性

• wiki/index.md 关键数字与代码实际状态一致（迁移数、路由数、实体数、测试数等）
• 新增/修复的 bug 已记录在症状导航中（含根因+解决方案）
• 新增功能已记录在对应模块 wiki 页面中（实体、端点、事件等）
• wiki 页面的"最后更新"日期已刷新为当天

端到端验证

• cargo check 全 workspace 通过
• cargo test 全部通过
• 浏览器中手动验证功能正常（列表/创建/编辑/删除/权限拦截）
• 小程序中验证（涉及小程序页面时）
• 相关路由权限按角色测试通过（至少 admin + 只读角色）
• 本地提交已推送到远程仓库

---

3. 实现规则

3.1 错误处理

• 跨 crate 边界：使用 thiserror 定义类型化错误，转换为 AppError
• crate 内部：可以使用 anyhow，但永远不跨越 crate 边界
• 数据库错误：通过 From<sea_orm::DbErr> 自动转换为 AppError
• 验证错误：包含字段级详情，方便 UI 渲染

3.2 数据库操作

• 所有 SeaORM Entity 必须包含：id, tenant_id, created_at, updated_at, created_by, updated_by, deleted_at, version
• 查询时始终带 tenant_id 过滤（中间件自动注入）
• 更新时检查 version 字段实现乐观锁
• 删除使用软删除（设置 deleted_at）

3.3 API 设计

• 所有端点使用 /api/v1/ 前缀
• 响应统一使用 ApiResponse<T> 包装
• 分页使用 Pagination + PaginatedResponse<T>
• utoipa 自动生成 OpenAPI 文档
• 租户 ID 从 JWT 中间件注入，不在 API 路径中传递（管理员接口除外）

新增 API 端点安全检查（强制）

默认拒绝是安全基线 — 绝大多数安全修复源于默认放行模式。 新增端点时必须逐项确认：

• 端点已添加 require_permission 权限守卫（非公开端点）
• 公开端点已显式标记为 public（不继承认证中间件）
• 路由使用 .nest() 注册带中间件的子路由（禁止 .merge() 防止中间件泄漏）
• 敏感操作有速率限制
• 无 format! 拼接 SQL — 所有查询使用 SeaORM 参数化
• FHIR/第三方端点有 tenant_id 和 allowed_patient_ids 范围过滤
• 无硬编码密钥或 fallback 默认值

前后端接口同步检查（强制）

前后端接口不一致是高频 bug 来源 — 任何 DTO 变更必须双向同步。 后端 DTO 变更时必须同步检查前端：

• DTO 字段名变更 → 前端 TypeScript 接口同步更新
• DTO 新增必填字段 → 前端表单和请求体同步更新
• API 路径变更 → 前端 api/ 模块路径同步更新
• 返回数据结构变更（数组/对象/嵌套）→ 前端解析逻辑同步更新
• 枚举值变更 → 前端类型定义和 UI 映射同步更新
• 后端新增端点 → 前端 API 模块同步添加调用函数，不允许留空

DTO 输入校验检查（强制）

DTO 输入校验是安全防线 — 缺失校验等于暴露攻击面，Update 和 Create 必须对称。 新增/修改 DTO 时必须逐项确认：

• 所有请求结构体已 derive(Validate)（包括 Update*Req、查询参数）
• Update*Req 与 Create*Req 校验对称（不允许 Update 降级）
• 字符串字段有 #[validate(length(min, max))]
• 枚举/类型字段有 #[validate(custom)] 限制合法值
• 集合字段有 #[validate(length(min = 1))] 非空检查
• 数值范围字段有 #[validate(range(min, max))]
• URL 字段有 SSRF 防护（禁止 localhost/内网地址，仅 http/https）
• 密码字段有 max = 128 防止 DoS
• handler 层已调用 req.validate().map_err(|e| AppError::Validation(e.to_string()))?

3.4 事件总线

• 模块间通信只能通过 EventBus
• 事件必须持久化到 domain_events 表（outbox 模式）
• 事件处理失败记录到 dead-letter 存储
• 事件类型命名：{模块}.{动作} 如 user.created, workflow.task.completed
• 铁律：每个事件必须有至少一个消费者，否则功能不算完成。 新增事件发布时必须同步实现消费者和对应测试。详见 docs/discussions/2026-04-28-architecture-retrospective.md §4。

3.5 Rust 代码规范

// 命名：snake_case (函数/变量), PascalCase (类型/trait), SCREAMING_SNAKE (常量)
// 模块公开接口通过 lib.rs 统一导出
// 每个 public 函数和 trait 必须有文档注释
// 异步函数返回 Result 时使用 AppResult<T> 类型别名
// 数据库操作使用 SeaORM 的 Entity + Model + Relation 模式

3.6 TypeScript / React 代码规范

// 避免 any，优先 unknown + 类型守卫
// 函数组件 + hooks
// 复杂状态收敛到 Zustand store
// API 调用封装到独立的 service 层，不在组件中直接 fetch
// 使用 Ant Design 组件，不自行实现已有组件
// 国际化文案使用 i18n key，不硬编码中文

3.7 安全规范

密钥与凭据管理

• 所有密钥、token、密码必须通过环境变量或密钥管理服务注入，禁止硬编码在源码中
• 开发环境密钥必须与生产环境严格隔离（cfg(debug_assertions) 编译期防护）
• 生产密钥禁止有 fallback 默认值，缺失时启动 panic
• 新增密钥时必须同步更新 .env.example 和 wiki/infrastructure.md

依赖安全

• 新增依赖前必须检查已知漏洞（cargo audit / npm audit）
• 禁止引入有未修补高危漏洞的依赖版本
• 定期更新依赖到最新安全补丁版本

数据安全

• PII 数据（姓名、身份证号、手机号、地址等）必须加密存储（AES-256-GCM）
• 日志中禁止输出 PII 数据和认证凭据（密码、token、session key）
• 敏感操作（登录、权限变更、数据导出、批量删除）必须记录审计日志（操作者、时间、目标、结果）
• 文件上传必须验证 MIME 类型 + 限制文件大小 + 防止路径穿越（文件名 sanitize）

传输安全

• 生产环境必须强制 HTTPS，禁止降级到 HTTP
• HTTP 响应必须包含安全头（HSTS、CSP、X-Frame-Options、X-Content-Type-Options、Permissions-Policy）
• SSE/WebSocket 长连接认证 token 不通过 URL query 参数传递（使用 header 或 cookie）
• API 响应禁止暴露内部实现细节（堆栈跟踪、数据库错误、文件路径、SQL 语句）

认证与授权

• 密码必须使用单向哈希（bcrypt/argon2），禁止明文或可逆加密存储
• JWT 必须设置合理过期时间，支持 token 吊销机制
• 敏感操作（删除数据、权限变更）需要二次确认
• 权限检查在 handler 层执行，禁止仅依赖前端隐藏控制访问
• tenant_id 必须从 JWT 中间件注入，禁止信任客户端传递的值

速率限制

• 所有 API 端点必须配置速率限制
• 认证相关端点（登录、注册、密码重置）限制更严格
• 批量操作和数据导出需要独立的速率限制策略
• 速率限制超出时返回 429 状态码，响应包含 Retry-After header

---

4. 测试与验证

4.1 测试要求

测试类型	覆盖目标	工具
单元测试	每个 service 函数	#[cfg(test)] + tokio::test
集成测试	API 端点 → 数据库	Testcontainers + 真实 PostgreSQL
多租户测试	数据隔离验证	独立测试 crate
E2E 测试	前端关键流程	Playwright
插件测试	动态表 CRUD + 租户隔离	Testcontainers

4.2 验证命令

# Rust 编译检查
cargo check

# Rust 全量测试
cargo test --workspace

# 后端服务启动
cd crates/erp-server && cargo run

# Docker 环境
cd docker && docker compose up -d

# 桌面端开发
cd apps/desktop && pnpm tauri dev

# 数据库迁移检查
docker exec erp-postgres psql -U erp -c "\dt"

4.3 Phase 完成标准

每个 Phase 完成时必须满足：

• cargo check 全 workspace 通过
• cargo test 全部通过
• PostgreSQL 服务正常运行，迁移自动执行
• 所有迁移可正/反向执行
• API 端点可通过 Swagger UI 测试
• 桌面端可正常启动并展示对应 UI
• 所有代码已提交

---

5. 提交规范

<type>(<scope>): <description>

类型:

• feat — 新功能
• fix — 修复问题
• refactor — 重构
• docs — 文档更新
• test — 测试相关
• chore — 杂项（构建、配置等）
• perf — 性能优化

Scope 对应 crate 或模块名:

scope	范围
core	erp-core
auth	erp-auth
workflow	erp-workflow
message	erp-message
config	erp-config
server	erp-server
health	erp-health
ai	erp-ai
dialysis	erp-dialysis
plugin	erp-plugin / erp-plugin-prototype / erp-plugin-test-sample
assessment	erp-plugin-assessment
crm	erp-plugin-crm
inventory	erp-plugin-inventory
web	Web 前端
ui	React 组件
db	数据库迁移
docker	Docker 配置

示例:

feat(auth): 添加用户管理 CRUD
feat(core): 实现事件总线和模块注册
fix(server): 修复数据库连接池配置
refactor(auth): 拆分 RBAC 和 ABAC 权限模型
chore(docker): 添加 PostgreSQL 健康检查

---

6. 反模式警告

• ❌ 不要不看 wiki 就开干 — wiki 包含环境配置、数据库连接、启动方式、已知问题，不看就做等于盲猜，浪费时间且产出不可信
• ❌ 不要在业务 crate 之间创建直接依赖 — 只通过事件和 trait 通信
• ❌ 不要跳过多租户中间件 — 所有数据操作必须带 tenant_id 过滤
• ❌ 不要硬编码配置值 — 使用 config.toml + 环境变量
• ❌ 不要跳过迁移直接建表 — 所有 schema 变更通过 SeaORM Migration
• ❌ 不要在前端组件中直接调用 HTTP — 封装到 service 层
• ❌ 不要使用 anyhow 跨越 crate 边界 — 内部可用，对外必须转 AppError
• ❌ 不要假设只有单租户 — 从第一天就按多租户设计
• ❌ 不要提前实现远期功能 — 严格按 Phase 计划推进
• ❌ 不要忽略 version 字段 — 所有更新操作必须检查乐观锁
• ❌ 不要在动态表 SQL 中拼接用户输入 — 使用 sanitize_identifier 防注入
• ❌ 不要在插件 crate 中直接依赖 erp-auth — 权限注册用 raw SQL，保持模块边界
• ❌ 不要在 plugin.toml 中使用与实体名不一致的权限码 — permissions[].code 前缀必须与 schema.entities[].name 完全一致（如实体 customer_tag → 权限码 customer_tag.list/customer_tag.manage，不能写成 tag.manage），否则页面 403
• ❌ 不要漏掉实体的 .list 权限 — 每个实体必须同时声明 .list 和 .manage，缺少 .list 导致列表页 403
• ❌ 不要跳过验证直接提交 — 编译/测试/功能验证必须全部通过
• ❌ 不要提交后忘记推送 — 不推送等于没完成，远程仓库必须同步。每次新会话开始先检查未推送提交
• ❌ 不要忘记更新文档 — 涉及架构、接口、模块变化时必须同步更新相关文档
• ❌ 不要连续 5 个代码提交不更新 wiki — wiki 是团队唯一真相源，过期数据比没有数据更有害
• ❌ 不要修复 bug 后跳过症状导航更新 — 每个修复都应该帮助未来遇到同类问题的人快速定位根因
• ❌ 不要新增功能后不更新 wiki 关键数字 — 迁移数/路由数/实体数/测试数必须与代码同步，否则 wiki 指标表就是废数据
• ❌ 不要一次性输出长文档 — 超过 200 行的文档必须分步编写（先大纲 → 逐章 → 整合），否则会因上下文过长卡死
• ❌ 不要忽略讨论记录 — 每次发散式讨论结束后必须建立文档到 docs/discussions/，不要口头确认后就忘
• ❌ 不要跳过 Feature DoD — 每个功能标记"完成"前必须通过 §2.6 检查清单，不全面验证就提交将导致后续反复修复
• ❌ 不要新增端点时默认放行 — 所有端点默认拒绝访问，必须显式声明权限
• ❌ 不要后端 DTO 变更不同步前端 — 字段名/路径/类型变更时必须同步更新前端 TypeScript 接口
• ❌ 不要写 Update DTO 时省略校验 — UpdateReq 必须与 CreateReq 校验对称（Validate derive / 枚举 custom / Vec min=1 / 密码 max=128）
• ❌ 不要URL 字段不做 SSRF 防护 — 禁止 localhost/127.0.0.1/内网地址，仅允许 http/https 协议
• ❌ 不要handler 层跳过 .validate() — 所有 Json<T> handler 函数体第一行必须调 req.validate().map_err(\|e\| AppError::Validation(e.to_string()))?
• ❌ 不要在日志中输出敏感数据 — 密码、token、身份证号、手机号等 PII 信息禁止写入日志
• ❌ 不要信任客户端传递的 tenant_id — 必须从 JWT 中间件注入，客户端可伪造
• ❌ 不要在生产代码中使用 unwrap() — 必须处理所有错误，使用 ? 或 map_err
• ❌ 不要将内部错误信息返回给客户端 — 数据库错误、堆栈跟踪、文件路径等必须转换为用户友好的错误消息
• ❌ 不要使用 HTTP 传输敏感数据 — 生产环境必须 HTTPS
• ❌ 不要跳过依赖安全检查 — 新增依赖前运行 cargo audit / npm audit，禁止引入有高危漏洞的版本
• ❌ 不要文件上传不做安全处理 — 必须验证 MIME 类型 + 限制大小 + sanitize 文件名防路径穿越

场景化指令

• 当遇到新增模块 → 实现 ErpModule trait，在 erp-server 注册
• 当遇到跨模块通信 → 定义事件类型，通过 EventBus 发布/订阅
• 当遇到数据查询 → 确保包含 tenant_id 过滤，检查软删除条件
• 当遇到新增 API → 添加 utoipa 注解，确保 OpenAPI 文档同步
• 当遇到新增表 → 创建 SeaORM migration + Entity，包含所有标准字段
• 当遇到新增页面 → 使用 Ant Design 组件，i18n key 引用文案
• 当遇到新增业务模块插件 → 参考 wiki/wasm-plugin.md 的插件制作完整流程和 .claude/skills/plugin-development/SKILL.md，创建 cdylib crate + 实现 Guest trait + 编译为 WASM Component。权限码必须与实体名一致（每个实体声明 .list + .manage）
• 当遇到新增/修改 DTO → 参考 wiki/architecture.md §4 DTO 输入校验规范：derive(Validate) + 字段级校验 + handler 层 validate() 调用 + 单元测试

---

7. 详细参考（wiki）

以下内容已从本文件迁移到 wiki，需要时查阅：

主题	wiki 页面
目录结构、crate 依赖、技术栈	wiki/architecture.md §2
模块开发规范、ErpModule trait、迁移规范	wiki/architecture.md §3
安全注意事项（认证/多租户/通用）	wiki/architecture.md §4
UI 布局规范	wiki/frontend.md §2
常用命令（Rust/前端/数据库/WASM）	wiki/infrastructure.md §3
设计文档索引	wiki/index.md
开发进度、模块状态	wiki/index.md 关键数字
环境配置、连接信息、登录凭据	wiki/infrastructure.md §2

graphify — 代码知识图谱

项目知识图谱位于 graphify-out/，当前规模：18,517 节点 / 22,666 边 / 1,841 社区（纯 AST 解析，无 API 成本）。 工具：python -m graphify（已安装 graphifyy 0.8.18）。

开发流程中的使用场景

时机	命令	目的
接手新任务，理解代码关系	graphify query "概念名"	搜索相关节点，比 Grep 更精准（按调用/引用/包含关系）
排查 bug，追踪调用链	graphify path "A" "B"	查找两个模块/函数间的最短路径
理解某个模块的职责	graphify explain "模块名"	自然语言解释节点及其邻居
代码改动后	graphify update .	增量更新图谱（AST-only，秒级完成）
宏观架构审查	读 graphify-out/GRAPH_REPORT.md	全局社区结构、跨文件关系概览

使用优先级（融入 §2.5 闭环工作法）

在 §2.5 步骤 1「现状确认」中，优先使用 graphify 替代盲目 Grep：

1. 先 graphify query — 精确定位相关节点和社区（比 Grep 返回更结构化的结果）
2. 再 graphify path — 确认模块间依赖路径（避免遗漏间接依赖）
3. 最后 Grep/Glob/Read — 确认 graphify 发现的具体文件内容

注意事项

• graphify update . 纯本地 AST 解析，不消耗 LLM token，每次代码改动后都可以运行
• 查询结果比 GRAPH_REPORT.md 更精准，优先使用 query/path/explain，仅在需要全局视图时读报告
• 首次生成需几分钟（1712 文件），后续增量更新秒级完成