From team-standards
Builds knowledge graphs for backend single services capturing table relationships, ER diagrams, SQL/DAO logic, state transitions, business judgments, atomic capabilities, and project pain points like concurrency, perf, and edge cases.
npx claudepluginhub exception-coder/team-standards --plugin team-standardsThis skill uses the workspace's default tool permissions.
本 skill 负责 **后端单服务业务图谱 + 项目级技术难点图谱** 双重职责：
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Guides code writing, review, and refactoring with Karpathy-inspired rules to avoid overcomplication, ensure simplicity, surgical changes, and verifiable success criteria.
Executes ctx7 CLI to fetch up-to-date library documentation, manage AI coding skills (install/search/generate/remove/suggest), and configure Context7 MCP. Useful for current API refs, skill handling, or agent setup.
Share bugs, ideas, or general feedback.
本 skill 负责 后端单服务业务图谱 + 项目级技术难点图谱 双重职责：
目标是让 AI 在后端接口开发前先理解：
长对话识别是项目级技术难点的最重要触发信号：用户在同一会话中对同一技术点反复疑问 / 多轮验证 / 出现回归性措辞，就是该技术点应当沉淀的强证据。AI 不必等用户显式说"记到知识图谱"，命中长对话模式即自动追加候选记录。
不处理前端 UI 或跨项目全局拓扑。跨项目链路仍交给 cross-project-locator。
下列任一场景命中即必须第一时间调起本 skill，先做候选沉淀路由判定，再继续答题或落盘。错过这些时机就是流程违反。
| 触发场景 | 命中信号 | 必做动作 |
|---|---|---|
Write/Edit 一份描述后端表关系 / ER / SQL / 状态扭转 / 业务流程 → 表 CRUD 的 .md（无论路径，包括 ai-docs/、work-log/、scenarios/ 而不仅 docs/） | 文档主体含表名 + 关联键 + SQL / DAO / Mapper + state/字段判定 + 数据流箭头 | 先按本 skill 决定归属命名空间和模板，再 Write |
| 用户问询表关系 / SQL 查询逻辑类问题 | "X 与 Y 是 1:1 还是 1:N"、"改这个动哪些表"、"字段从哪来"、"这个业务怎么查"、"这个 SQL 怎么写/完善"、"退款/账单/流水/分摊怎么算"、"是新建快照还是引用原表"、"哪个状态会变" | 答题同时把事实追加到候选沉淀池；涉及查询时同步记录 SQL 指纹候选 |
| AI 已完成后端代码调查并发现 ≥1 条可复用事实（含跨项目"以另一服务为调查对象"的场景） | 调查报告里出现具体表/SQL/DAO/Mapper/Service/枚举/状态值 | 调查结论给用户的同一回合，必须将事实候选追加到被调查项目命名空间下的候选池；有 SQL 时同步到查询索引候选 |
| 用户主动要求 | "建知识图谱"、"整理图谱"、"更新图谱"、"归档" | 先读候选池 + 现有正式图谱 + 代码证据，再写正式图谱 |
| 项目已有正式图谱 | 存在 docs/knowledge-graph/backend/ | 编码前必先回顾相关卡片，编码后必同步回写 |
| 后端代码变更 | 新增/修改 API、Service、DAO、SQL、表、枚举、状态机、事务边界、MQ、外部依赖 | 同步更新对应卡片或候选池 |
| 同一技术主题反复疑问 ≥3 轮（项目级技术难点） | 用户在同一会话中对同一技术点重复提问 / 验证 / 担忧 ≥3 次；或出现回归性措辞："为什么...还" / "怎么又..." / "上次说..." / "是不是...占用了" / "现在又卡了"；或修复后 ≥2 轮验证性追问 | 答题同一回合自动追加候选到 _candidates.md，分类标记 技术难点；超过 5 轮反复或用户显式提示"这是核心点"时主动起 scenarios/ 场景卡 |
| AI 完成涉及子进程 / 并发 / 性能 / 资源边界的代码改动 | 修复 transferTo 阻塞、Semaphore 限流、孤儿进程清理、缓存键策略、超时回收、磁盘/CPU 争夺等"非业务技术陷阱" | 编码后必候选记录；用户提示"这是难点要登记"时立刻整理为正式场景卡 |
常见误判反例（已发生过的踩坑）：
- ❌ "用户只是问云端逻辑，没让我建图谱，所以不用触发" → 错，问询场景必触发并候选沉淀
- ❌ "用户只是让我完善 SQL，所以只回答 SQL 就行" → 错，必须归档查询逻辑、涉及表、join/where/group by/order by、业务语义和复用原子能力
- ❌ "本地工程没有
docs/knowledge-graph/backend/，所以 skill 不适用" → 错，没有就先写候选池- ❌ "主目录是 A，调查的是 B 云端，应该交给 cross-project-locator" → 错，单服务图谱归属 = 被调查的那个服务，与 cwd 无关
- ❌ "我直接 Write 一份图谱文档就行了" → 错，写前必经本 skill 决定归属和模板
- ❌ "技术难点（子进程 / 并发 / 性能）不是表关系，所以不归本 skill" → 错，本 skill v1.21 起范围已扩到项目级技术难点；用户反复疑问的技术陷阱必须沉淀
- ❌ "用户没显式说'记到知识图谱'，所以不用沉淀" → 错，会话同主题反复疑问 ≥3 轮即自动触发，无需用户提醒；事后才记容易丢上下文
- ❌ "技术难点等下次会话再说" → 错，当场记录，错过即流程违反；会话结束后重新还原难点上下文成本极高
核心规则：图谱归属永远 = 被调查的后端单服务项目，与当前主工作目录无关。
| 主目录 | 调查对象 | 图谱归属命名空间 |
|---|---|---|
| 本服务自身 | 本服务自身 | 本服务 |
| 项目 A（前端 / 调用方） | 项目 B（云端单服务） | 项目 B |
| 项目 A（前端） | 同时跨 A+B | A 的归 A、B 的归 B；纯跨项目链路（A 调 B 的对照映射、调用链）走 cross-project-locator |
候选池默认路径（被调查项目命名空间下）：
{USER_DOCUMENTS}/ai-docs/{被调查项目}/knowledge-graph/_candidates.md
{USER_DOCUMENTS}/ai-docs/{被调查项目}/knowledge-graph/scenarios/{场景}.md
{USER_DOCUMENTS}/ai-docs/{被调查项目}/knowledge-graph/00_index.md
正式图谱路径（用户明确要求"上传终版到项目内"才走）：
{被调查项目根目录}/docs/knowledge-graph/backend/...
判定本 skill vs cross-project-locator 的边界：
cross-project-locatorcross-project-locator 登记服务间链路后端接口开发不是只写接口文档，还必须沉淀表逻辑知识。
凡是本次开发涉及 DAO/Mapper/SQL、表状态、订单/退款/支付等业务判定、事务、锁、幂等或跨表组合查询，AI 必须把这些关系纳入后端知识图谱闭环：
编码前：先回顾表逻辑图谱 + 原子能力索引
编码中：优先复用已有原子能力 / DAO 原子查询
编码后：把新增或变更的表读写、状态变化、判定逻辑同步回图谱
如果项目尚无正式图谱，也不能让事实散落在会话里。必须写入用户目录候选池，至少沉淀“表逻辑候选记录”，后续确认或代码验证后再整理进正式图谱。
SQL 是后端知识图谱的一等资产。 只要会话中提到了某个业务查询逻辑、SQL、DAO/Mapper 方法、join 关系、过滤条件、聚合条件或排序分页规则，就必须沉淀为可合并的 SQL 指纹：
业务问题 → 涉及表/ER → SQL 指纹 → 原子能力 → 代码坐标 → 复用建议
SQL 图谱不追求保存一堆一次性 SQL 字符串，而是归档“业务查询能力”：
核心理念：第一份图谱只要 1 份场景卡 + 1 份扁平索引就算建立。 不要求 8 文件齐全才叫图谱——通过多个细小场景小卡渐进汇总成全景，是这套图谱的设计目标。
新建图谱时只需要这两个文件即可投入使用：
{命名空间根}/knowledge-graph/
00_index.md # 扁平索引：每个场景一行 + 关键词反查表
scenarios/{业务场景}.md # 一图一表的场景小卡（一图一表是底线）
_candidates.md # 候选沉淀池（未代码验证的会话事实）
_sql_candidates.md # SQL / 查询逻辑候选池（未正式合并的查询指纹）
每张场景小卡至少包含：
markdown-writing-standards）00_index.md 至少包含：
| 场景 | 主表 | 一句话 | 关键词 | 文件 |
|---|---|---|---|---|
| 退款数据模型 | refund_bill / pos_transaction / order_item / order_item_payment_allocate | 1 bill + N tx + 新建 item 快照 + 按 tx 比例分摊 | 退款 / 账单 / 流水 / 分摊 / 部分退 | scenarios/退款数据模型.md |
当已有 ≥3 张场景小卡，且发现表 / 枚举 / 流程 / 原子能力被多个场景共享时，再单独建以下卡片：
{命名空间根}/knowledge-graph/
tables/{table-name}.md # 高频被多场景引用的表
enums/{enum-name}.md # 高频枚举字典
flows/{flow-name}.md # 跨多场景的业务流程
atomic-capabilities/{cap}.md # 被多接口复用的原子能力
07_table_logic_index.md # 表逻辑反查索引（场景多了再建）
08_atomic_capability_index.md # 原子能力索引（能力多了再建）
09_sql_query_index.md # 原子能力 ↔ SQL 查询逻辑索引（查询多了再建）
sql-queries/{business-scenario}.md # 按业务场景合并后的 SQL 查询卡
仅在图谱规模足够大、需要给 AI 做"先读图谱再读代码"门控时再补：
{命名空间根}/knowledge-graph/
00_backend_service_profile.md # 服务画像
01_domain_capability_map.md # 领域能力地图
02_data_model_map.md # 数据模型总览
03_enum_dictionary.md # 枚举总字典
04_api_entrypoints.md # API 入口总表
05_external_dependencies.md # 外部依赖
06_business_flow_index.md # 流程总索引
| 阶段 | 命名空间根 | 何时使用 |
|---|---|---|
| 候选 / 草稿 | {USER_DOCUMENTS}/ai-docs/{被调查项目}/knowledge-graph/ | 默认；AI 起草、未确认、未代码验证 |
| 正式 | {被调查项目根目录}/docs/knowledge-graph/backend/ | 用户明确要求"上传终版到项目内"才走，遵循 doc-index-required |
入门门槛兜底：项目尚未有任何图谱时，本 skill 第一次落盘只产出 Tier 1 的最小文件即可（00_index.md + 1 张 scenarios/{xxx}.md + _candidates.md；若本次涉及 SQL，再加 _sql_candidates.md），不要一次性铺满 Tier 3。
SQL 图谱同样按渐进方式建立：
| 阶段 | 文件 | 何时创建 |
|---|---|---|
| 候选 | _sql_candidates.md | 任意会话提到业务查询、SQL、DAO/Mapper 查询逻辑时立即追加 |
| 索引 | 09_sql_query_index.md | 同一项目累计 ≥3 条 SQL 候选，或用户要求“整理 SQL / 完善 SQL / 归档查询逻辑”时创建 |
| 场景卡 | sql-queries/{business-scenario}.md | 同一业务场景存在 ≥2 条查询，或一个 SQL 涉及 ≥3 张表 / 聚合 / 状态判定时创建 |
| 全景 ER | 02_data_model_map.md + tables/{table}.md | 累计 ≥5 张核心表，或用户要求“全景 ER 图”时创建 / 更新 |
SQL 候选不可长期散落。 当用户要求“整理 / 归档 / 完善 SQL”时，必须先读取 _sql_candidates.md、09_sql_query_index.md、命中的 sql-queries/ 与表卡，然后去重合并，更新正式索引和场景卡。
开始分析或实现后端接口前，只要本次涉及数据库读写、状态判定、订单/退款/支付等业务对象，必须先按顺序回顾：
07_table_logic_index.md：按业务对象/场景反查表关系和判定规则08_atomic_capability_index.md：按业务关键词反查可复用原子能力09_sql_query_index.md：按业务关键词 / 表名 / DAO 方法反查已有 SQL 查询逻辑table-logic/{scenario}.mdatomic-capabilities/{capability}.mdsql-queries/{business-scenario}.mdtables/{table-name}.md、flows/{flow-name}.md、enums/{enum-name}.md若上述文件不存在，应在设计/编码过程中创建用户目录候选记录，不得因为“还没建图谱”就跳过沉淀。
写后端 Service / Handler / UseCase 主流程时，必须主动判断：
| 问题 | 正确动作 |
|---|---|
| 已有表逻辑图谱说明了该判定 | 按图谱回到代码坐标复用，不重新发明规则 |
| 已有原子能力覆盖该计算/查询 | 注入/调用原子能力，禁止复制 SQL 或业务计算 |
| 只有 DAO 原子查询，没有业务原子能力 | 优先复用 DAO；若本次组合逻辑会被多接口复用，沉淀新原子能力 |
| 发现旧代码有重复判定 | 本次改动范围允许时抽出原子函数；否则登记“待抽取原子能力”候选 |
已有 09_sql_query_index.md 命中类似 SQL | 复用现有 DAO/Mapper/SQL 指纹，只补差异条件，不重新拼一份相似查询 |
典型原子能力包括但不限于：
当用户要求“完善 SQL”或 AI 需要新增 / 修改查询时，必须按以下顺序处理：
09_sql_query_index.md → sql-queries/ → tables/ / 02_data_model_map.md_sql_candidates.md 或正式 09_sql_query_index.md / sql-queries/SQL 完善输出时必须显式说明：
SQL 完善依据：
- 业务问题：
- 复用 / 参考的原子能力：
- 涉及表与 ER 关系：
- 新增或调整的 join / where / group by / order by：
- 状态 / 枚举 / 金额字段语义：
- 索引风险：
- 需回写图谱：
后端源码改动完成后，只要命中以下任一项，必须更新正式图谱或候选池：
回写最少包含：
- 本次接口 / 能力名称
- 涉及表与读写动作
- 表之间业务关系
- 状态字段变化或判定规则
- 可复用原子能力 / DAO 方法
- 代码坐标
- 对后续新增接口的支持判断
为避免会话中的业务事实遗漏，后端知识图谱采用“两段式沉淀”：
会话提及 / 代码分析发现
→ 自动记录到候选沉淀池
→ 用户确认或证据校验
→ 整理进入正式知识图谱
候选沉淀池默认写入用户目录被调查项目命名空间下，不写项目 docs/：
{USER_DOCUMENTS}/ai-docs/{被调查项目}/knowledge-graph/_candidates.md
{USER_DOCUMENTS}/ai-docs/{被调查项目}/knowledge-graph/_sql_candidates.md
说明：v1.18.7 起候选池路径精简为
_candidates.md（按被调查项目而非按日期/agent 分），便于跨日期跨会话累积同主题事实并最终归并到 scenarios 卡。旧版{agent}/{YYYY-MM-DD}/backend-kg-candidates.md路径仅作向后兼容，不再推荐新增。
自动追加规则（强制）：
AI 在会话中只要回答了任何关于后端表关系 / 业务判定 / 状态扭转 / 字段语义的问题，即便用户没要求"建图谱"，回答的同一回合内必须自动追加 1 条候选记录到 _candidates.md。这是本 skill 的最低收口动作——错过即流程违反。
AI 在会话中只要回答了任何关于 SQL / DAO / Mapper / 查询逻辑 / 过滤条件 / join / 聚合的问题，同一回合还必须自动追加 1 条 SQL 候选记录到 _sql_candidates.md。如果答案里出现了 SQL 代码块、伪 SQL、查询字段清单、表 join 说明或 DAO 方法名，就视为命中。
候选池用于防遗漏，正式图谱用于可信引用。二者职责必须分开。
每条候选记录最少格式：
## YYYY-MM-DD HH:MM | {场景关键词}
- 事实：{一句话业务事实}
- 涉及：{表/枚举/状态字段}
- 来源：{代码坐标 or 用户描述 or 设计文档 or 调查报告}
- 可信度：待确认 / 已确认 / 已代码验证
- 后续动作：{待用户确认 / 待代码核验 / 可整理入正式 scenarios 卡}
SQL 候选记录最少格式：
## YYYY-MM-DD HH:MM | {业务问题 / 查询能力}
- 业务问题：{这个 SQL 回答什么问题}
- SQL 指纹：{SELECT 主字段 FROM 主表 JOIN ... WHERE ... GROUP BY ... ORDER BY ...，可脱敏 / 参数化}
- 参数：{入参及业务含义}
- 返回字段：{字段及业务含义}
- 涉及表：{主表、关联表、关联键}
- 过滤 / 聚合 / 排序：{where/group by/having/order by 的业务语义}
- 状态 / 枚举：{字段值与枚举含义}
- 原子能力：{DAO/Mapper/Repository/Service 方法，未知则写待定位}
- 代码坐标：{文件:行 / 方法名，未知则写待定位}
- 索引建议：{可能需要的索引，未知则写待评估}
- 可信度：待确认 / 已确认 / 已代码验证
- 合并目标：`09_sql_query_index.md` / `sql-queries/{场景}.md` / `tables/{table}.md`
整理 SQL 图谱时，必须先按“SQL 指纹”去重，而不是按原始字符串去重：
| 合并维度 | 说明 |
|---|---|
| 业务问题 | 同样回答“订单可退金额 / 退款流水池 / 账单明细查询”等问题的 SQL 归为同一查询能力 |
| 主表 + 关联表 | 主表相同、join 链路相同，只是 where 条件不同，合并为同一 SQL 卡的变体 |
| 过滤语义 | deleted=0、租户/门店、状态枚举、时间范围、金额方向等按语义归并 |
| 聚合语义 | sum/count/max 等聚合按“业务指标”命名，避免只写表达式 |
| 原子能力 | 同一 DAO/Mapper/Service 方法产生的 SQL 必须归到同一原子能力下 |
合并后保留：
分析后端需求前，按图谱所在层级读取（命名空间 = 草稿 ai-docs/{项目}/knowledge-graph/ 或 正式 docs/knowledge-graph/backend/）：
Tier 1 起步阶段（仅有 00_index.md + scenarios/ + _candidates.md）：
00_index.md：按关键词反查命中的场景小卡scenarios/{业务场景}.md_candidates.md：扫一遍候选池，看本次主题是否已有未确认事实Tier 2/3 成熟阶段（已有细分卡片）按以下顺序：
00_index.md → 00_backend_service_profile.md（如有）01_domain_capability_map.md、06_business_flow_index.md（如有）07_table_logic_index.md、08_atomic_capability_index.md（如有）09_sql_query_index.md（如有）scenarios/{场景}.mdtable-logic/{scenario}.md、atomic-capabilities/{capability}.md、sql-queries/{business-scenario}.mdcapabilities/{capability}.md、flows/{flow}.mdtables/{table}.md、enums/{enum}.md、02_data_model_map.md04_api_entrypoints.md、05_external_dependencies.md（如有）_candidates.md、_sql_candidates.md不得在已有图谱可定位时直接全量扫描代码。即使图谱只有 Tier 1，也要先读 00_index.md 和命中的场景小卡。
后端能力必须区分三类：
| 类型 | 定义 | 示例 |
|---|---|---|
| 原子能力 | 可复用的最小业务能力 | 生成订单号、校验商品、计算价格、锁库存 |
| 领域能力 | 围绕一个业务对象完成一项完整动作 | 创建订单、取消订单、支付订单 |
| 编排能力 | 跨多个领域能力/外部依赖的流程编排 | 下单履约流程、支付后出单流程、退款流程 |
能力卡必须写清能力类型，禁止把所有 Service 方法都叫“原子能力”。
07_table_logic_index.md 至少包含：
- 按业务对象索引：订单 / 退款 / 支付 / 库存 / 会员等
- 按场景索引：部分退、全退、取消、支付成功、补偿重试等
- 每个场景涉及的主表、关联表、状态字段、核心判定、对应 table-logic 卡片
- 常用问题反查：改了什么表、哪些状态会变、是否支持新增接口、应该复用哪个原子能力
推荐表格：
| 业务对象 | 场景 | 主表 | 关联表 | 状态/金额字段 | 核心判定 | 图谱卡 | 可复用能力 |
|---|---|---|---|---|---|---|---|
| 订单 | 部分退判定 | order | refund_order / order_item | order_status / refund_status / refund_amount | 已退金额 < 可退金额且存在未退商品 | table-logic/order-refund.md | calculateRefundableAmount |
09_sql_query_index.md 是项目级“原子能力 ↔ SQL”反查入口，至少包含：
- 按业务问题索引：订单查询 / 退款池 / 账单明细 / 流水聚合等
- 按主表索引：从主表反查有哪些查询能力
- 按原子能力索引：DAO/Mapper/Service 方法对应哪些 SQL 指纹
- 按状态 / 枚举 / 金额字段索引：哪些查询依赖这些关键字段
- SQL 变体：同一查询能力在不同入口下的 where/order/page 差异
推荐表格：
| 业务问题 | 原子能力 | 主表 | 关联表 | SQL 指纹 | 参数 | 返回字段 | 过滤/聚合语义 | 代码坐标 | 场景卡 |
|---|---|---|---|---|---|---|---|---|---|
| 查询订单可退流水池 | queryRefundableTxPool | order_transaction | refund_transaction / refund_method | `SELECT ... FROM order_transaction tx LEFT JOIN ... WHERE tx.order_id=? AND tx.support_refund=1 ...` | orderId | txId / payAmount / refundedAmount / maxRefundAmount | support_refund=1、已退金额扣减、按云端优先级排序 | RefundEligibilityDao#queryRefundableTxPool | sql-queries/order-refund.md |
每行必须能够回答“新接口要查这个业务问题时，应该复用哪个 SQL / 原子能力”。
sql-queries/{business-scenario}.md 至少包含：
- 场景名称
- 回答的业务问题
- Mermaid ER 图或局部 ER 图（主表 + 关联表）
- 标准 SQL 指纹（参数化）
- SQL 变体（不同入口 / 状态 / 排序分页）
- 参数语义
- 返回字段语义
- join/on 业务含义
- where/group by/having/order by 业务含义
- 依赖枚举 / 状态字段
- 对应原子能力 / DAO / Mapper / Repository / Service
- 调用入口
- 索引建议与性能风险
- 与 `tables/`、`table-logic/`、`atomic-capabilities/` 的交叉引用
推荐结构（实际文件中可使用 Mermaid / SQL fenced code block；本处只展示骨架）：
# 订单退款查询 SQL
## 业务问题
- 查询某订单当前还可以退款的原支付流水池。
## ER
- order_transaction ||--o{ refund_transaction : original_transaction_id
## 标准 SQL 指纹
- SELECT ...
- FROM order_transaction tx
- LEFT JOIN refund_transaction rt ON rt.original_transaction_id = tx.id
- WHERE tx.order_id = :orderId AND tx.support_refund = 1
- GROUP BY tx.id
## 字段语义
| 字段 | 来源 | 业务含义 |
|---|---|---|
## 原子能力
| 方法 | 说明 | 代码坐标 |
|---|---|---|
08_atomic_capability_index.md 至少包含：
- 原子能力名称
- 业务关键词
- 入参 / 出参
- 读写表
- SQL 指纹 / 查询卡
- 状态/金额/枚举规则
- 代码坐标
- 被哪些 API / Service 复用
- 新接口复用建议
推荐表格：
| 能力 | 关键词 | 入参 | 出参 | 涉及表 | SQL / 查询卡 | 代码坐标 | 复用入口 |
|---|---|---|---|---|---|---|---|
| 计算订单可退金额 | 退款 / 可退 / 部分退 | orderId | amount | order / refund_order / order_item | sql-queries/order-refund.md | XxxService#calculateRefundableAmount | 退款申请 / 退款预览 |
table-logic/{business-object-or-scenario}.md 至少包含：
- 场景名称
- 业务问题：这张卡回答什么问题
- 涉及表关系：主表、关联表、join/关联字段
- 核心判定矩阵：条件 → 业务含义 → 结果
- 状态变化矩阵：表.字段 原值 → 新值 → 触发动作 → 代码坐标
- 金额/数量聚合规则：字段来源、加减方向、过滤条件
- 可复用原子能力：Service/DAO/Mapper 方法
- 新接口支持判断：现有表/能力是否支持，缺口是什么
- 代码坐标与证据：SQL、DAO、枚举、设计文档、测试
推荐结构：
标题：订单部分退表逻辑
回答的问题：
- 如何判断订单是未退、部分退、全退？
- 新增退款相关接口时应该复用哪些表和原子能力？
表关系：
| 表 | 角色 | 关联字段 | 说明 |
|---|---|---|---|
判定矩阵：
| 条件 | 业务含义 | 判定结果 | 代码坐标 |
|---|---|---|---|
状态变化矩阵：
| 动作 | 表 | 字段 | 变化 | 触发条件 | 代码坐标 |
|---|---|---|---|---|---|
原子能力：
| 能力 | 方法 | 说明 |
|---|---|---|
atomic-capabilities/{capability-name}.md 至少包含：
- 能力名称
- 业务语义
- 入参 / 出参
- 读取表 / 写入表
- 依赖枚举 / 状态字段
- 过滤条件
- 事务要求
- 复用入口
- 禁止重复实现的位置
- 代码坐标
capabilities/{capability-name}.md 至少包含：
- 能力名称
- 能力类型：原子能力 / 领域能力 / 编排能力
- 业务目标
- 入口 API / Service / UseCase
- 调用的原子能力
- 涉及表
- 涉及枚举
- 状态流转
- 事务边界
- 幂等规则
- 外部依赖
- 失败与补偿
- 代码坐标
flows/{flow-name}.md 至少包含：
- 流程目标
- 触发入口
- Mermaid 时序图
- 表读写顺序
- 能力调用链
- 枚举/状态变化
- 外部系统调用
- 异常分支
- 日志与观测关键字
tables/{table-name}.md 至少包含：
- 表职责
- 主键 / 唯一键 / 关键索引
- 核心字段业务含义
- 状态字段解释
- 金额 / 数量 / 业务状态字段的计算来源
- 读它的能力
- 写它的能力
- 与其它表关系
- 参与的业务场景与 table-logic 卡片
- Mermaid ER 图
- 数据一致性约束
enums/{enum-name}.md 至少包含：
- 枚举类路径
- 数据库存储值
- 中文业务含义
- 可进入条件
- 可流转目标
- 禁止流转
- 前端展示含义（如已知）
- 历史兼容值（如存在）
用户在会话中经常提到的内容必须自动记录到候选沉淀池，但不能无条件自动写入正式知识图谱。按以下规则处理：
| 场景 | 处理 |
|---|---|
| 用户明确说“记入知识图谱 / 更新知识图谱 / 归档到后端图谱” | 先检索候选池 + 现有正式图谱，再整理更新正式图谱 |
| 本次后端代码变更新增/修改 API、Service、DAO/Mapper/SQL、表、枚举、状态流转、MQ、外部依赖 | 必须更新相关图谱卡片或候选池 |
| 本次后端代码涉及订单/退款/支付等表逻辑判定 | 必须更新 07_table_logic_index.md / table-logic/ / 08_atomic_capability_index.md 中至少一处 |
| 会话中反复出现同一后端业务事实，但尚未代码验证 | 自动追加到候选沉淀池，默认写用户目录，不进正式图谱 |
| 同一会话同一技术主题用户反复疑问 ≥3 轮（含直接提问 / 验证性追问 / 担忧性表达 / 回归性措辞） | 自动追加候选记录，标记 分类: 技术难点；超过 5 轮反复或用户显式提示"这是核心点"时直接生成 scenarios/ 场景卡 |
| 用户出现回归性措辞（"为什么...还"、"怎么又..."、"上次说..."、"是不是...占用了"、"现在又卡了"） | 视为技术难点信号，自动追加候选 |
| 修复后用户提出 ≥2 轮验证性追问（"是不是真的解决了"、"会不会再出现"、"还有没有其它"、"重启后还会有么"） | 答题同回合追加候选，标注 "已修复 + 验证关注点"，便于下次回归测试覆盖 |
| 涉及子进程 / 并发 / 性能 / 资源边界 / 外部依赖编排的非业务代码变更 | 编码后必候选记录到 _candidates.md，分类 技术难点；本身就是项目重点资产 |
| 事实来自代码、DDL、枚举类、接口契约、已确认设计文档 | 可作为正式图谱依据；更新前仍需合并候选池同主题内容 |
| 只是猜测、临时讨论、未确认方案 | 可记录为“待确认假设”，禁止写入正式图谱 |
正式图谱条目必须能追溯到至少一个来源：代码坐标、表结构、枚举类、接口契约、设计文档或用户明确确认。
候选沉淀池每条记录至少包含：
- 记录时间
- 服务/模块
- 分类：业务事实 / 技术难点 / 性能 / 资源 / 进程 / 并发 / 运维 / 其它
- 会话事实
- 关联能力/流程/表/枚举/外部依赖
- 触发模式：用户主动要求 / 长对话同主题 ≥3 轮 / 修复后验证追问 / 代码改动后自动归档 / ...
- 可信度：待确认 / 已确认 / 已代码验证
- 来源：用户描述 / 代码坐标 / DDL / 枚举类 / API 契约 / 实战 bug
- 后续动作：待用户确认 / 待代码核验 / 可整理入正式图谱
当用户后续要求“整理知识图谱 / 更新正式图谱 / 归档”时，必须先读取：
_candidates.md、_sql_candidates.mddocs/knowledge-graph/backend/ 现有正式图谱09_sql_query_index.md、sql-queries/、02_data_model_map.md、表卡、原子能力卡然后去重、合并、补证据，再写正式图谱。
后端源码出现以下变化时，应同步检查知识图谱：
若项目没有正式 docs/knowledge-graph/backend/，先在用户目录生成“知识图谱更新建议”和表逻辑候选池；用户确认后再写正式图谱。
若项目已有正式 docs/knowledge-graph/backend/，且本次代码变更已验证事实，应直接更新命中的正式卡片；不确定内容写入候选池。
当用户询问或 AI 自己需要判断“新增接口是否支持”时，必须基于表逻辑图谱回答：
输出格式：
后端表逻辑支持性：
- 结论：支持 / 部分支持 / 不支持
- 依据表：
- 依据状态/枚举：
- 可复用原子能力：
- 缺口：
- 需更新图谱：
多项目知识图谱不做单服务内部能力的重复整理，主要记录服务间关系：
跨项目链路交给 cross-project-locator。本 skill 只在单服务图谱中保留“外部依赖”视角，不把多个项目的内部表、枚举、原子能力混到一起。
执行后端知识图谱分析或更新时，必须回显：
后端知识图谱：
- 项目：
- 命中能力：
- 读取图谱：
- 命中 ER / 表关系：
- 命中表逻辑：
- 命中 SQL 查询：
- 可复用原子能力：
- 需更新图谱：
- 更新依据：
- 输出路径：
| 错误想法 | 正确处理 |
|---|---|
| “用户提到了就写入正式图谱” | 先自动进候选沉淀池，确认或代码验证后再整理入正式图谱 |
| “不自动记录，等用户以后想起来再说” | 错。会话中的后端业务事实应自动候选记录，防止遗漏 |
| “一个 plugin 把所有端都做了” | 本 skill 只管后端单服务，不管前端 UI 或跨项目全局拓扑 |
| “先全量扫代码再说” | 有图谱先读图谱，再按代码坐标读文件 |
| “表字段照抄一遍就算图谱” | 必须写字段业务含义、读写能力和一致性约束 |
| “SQL 回答完就结束” | 必须同步沉淀 SQL 指纹、业务问题、涉及表、join/where/group by/order by 语义和原子能力 |
| “全景 ER 等最后再画” | 当用户要求全景 ER 或核心表累计到一定规模时，必须更新 02_data_model_map.md，并从 SQL / 表卡反推关系 |
| “同一个业务查询换个 where 就另建一份 SQL” | 按 SQL 指纹合并，作为同一查询能力的变体，不制造重复卡 |
| “订单部分退这类规则问过很多次但不用沉淀” | 错。反复出现的表逻辑、状态判定、金额聚合必须进入表逻辑候选池或正式图谱 |
| “写新接口时直接再查一遍 SQL” | 先查 07_table_logic_index.md、08_atomic_capability_index.md 和 09_sql_query_index.md，已有 SQL / 原子能力直接复用 |
| “Service 里临时复制一段表判定最快” | 应优先复用原子能力；确需临时兼容时登记待抽取原子能力 |
| “枚举值不用单独整理” | 后端需求分析必须显式读取相关枚举卡 |
| “跨项目链路也写这里” | 单服务只记录本服务视角；跨项目交给 cross-project-locator |
| “ffmpeg / 子进程 / 性能 / 资源争夺这些是技术坑，不是表关系，不归图谱” | 错。v1.21 起范围已扩到项目级技术难点；反复出现的非业务技术陷阱同样必须沉淀 |
| “用户没显式说'记到知识图谱'，那就先不记” | 错。同主题 ≥3 轮反复疑问、回归性措辞、修复后验证追问，都是自动触发条件，无需用户提醒 |
| “技术难点等下次会话再说” | 错。当场记录是硬规则，错过即流程违反；会话结束后还原难点上下文成本极高 |
| “修复了就完事了，不用记" | 错。修复后用户多轮验证追问 = 这是项目持续关注的难点，必须沉淀供下次回归参考 |