dsh-data-domain-knowledge 0.1.0-alpha.1

package/src/diagnosis/seed.ts

@@ -0,0 +1,291 @@
+import type { AttributionGraphData } from './types.js'
+
+/**
+ * 案例 = **一篇 wiki 定义 + 一条有序排查路径**。
+ *
+ * 两段各有明确消费者，不能合并：
+ * - `sections` 是给人读、给向量召回的散文（可 diff、可评审、可追溯）；
+ * - `path` 是给图和剪枝用的结构（有序、可判真假、带被否定的分支）。
+ *
+ * 序和枚举一旦写进散文，归并算法就再也读不到它们了 —— 所以路径单独成段。
+ */
+export interface CaseSection {
+  heading: string
+  body: string
+}
+
+export interface CasePathStep {
+  nodeId: string
+  label: string
+  note: string
+  /** 这一步的结论是「否定」：它把某个假设置于死地，而不是坐实。 */
+  refuted?: boolean
+}
+
+export interface AttributionCase {
+  id: string
+  title: string
+  symptomId: string
+  sections: CaseSection[]
+  path: CasePathStep[]
+  durationMinutes: number
+  /** 误导段：最贵的那条知识。没有它，下次还会有人在同一个假设上烧掉四十分钟。 */
+  misleading?: { nodeId: string; label: string; wastedMinutes: number; why: string }
+  rootCause: string
+}
+
+/**
+ * Seed 图谱：与 0021 §11 的三个案例同源，用来说明「同一现象有多个根因、否定边有用、
+ * 误导边昂贵」。
+ *
+ * 它现在有两重身份：
+ * 1. **首次启动的起点** —— `DiagnosisStore.ensure()` 在 `05_diagnosis/` 为空时把它写成
+ *    真实的 jsonl，之后用户可以手改，不会被覆盖回去；
+ * 2. **回归样本** —— 上面那三条结论需要一个稳定的夹具，所以它不会被删除。
+ */
+export const SEED_GRAPH: AttributionGraphData = {
+  nodes: [
+    // ── 类型层：问题侧（每个现象带问题大类 / 子类，见 0021 §4.5） ───────────
+    // 三个**具体**现象，而不是一个「指标报表 T-1 异常」—— 大类是切面，不是节点；
+    // 把「T-1 指标异常」这种泛指做成节点，等于让三个不同的故障在图上长得一模一样。
+    {
+      id: 'S1', kind: 'symptom', layer: 'type', title: '日报 GMV 为 0',
+      problemClass: 'missing', problemSubclass: 'missing-zero',
+      summary: '观测量：日报 GMV + 单日窗口；精确为 0 而不是偏低。',
+    },
+    {
+      id: 'S2', kind: 'symptom', layer: 'type', title: '订单数只剩昨日 12%',
+      problemClass: 'deviation', problemSubclass: 'deviation-drop-sharp',
+      summary: '观测量：日报订单数 + 单日窗口；下降 88%，按渠道切开后缺口集中在新增渠道。',
+    },
+    {
+      id: 'S3', kind: 'symptom', layer: 'type', title: 'DAU 突增 3.1 倍',
+      problemClass: 'deviation', problemSubclass: 'deviation-rise-sharp',
+      summary: '观测量：DAU + 单日窗口；放大 3.1 倍且只有 T-1 单日，相邻日期正常。',
+    },
+
+    { id: 'H1', kind: 'hypothesis', layer: 'type', title: '上游分区未产出', failureMode: 'upstream-missing', reuseCount: 12,
+      summary: '当日 dwd / ods 分区不存在 → 指标必然为 0。反例：分区在但行数为 0 时不是它。',
+      discriminator: '当日 dwd / ods 分区不存在 → 指标必然为 0',
+      notWhen: '分区存在但行数为 0（那是 H4）；分区正常而指标仍为 0（那是口径或消费侧）' },
+    { id: 'H2', kind: 'hypothesis', layer: 'type', title: '口径 / 版本变更', failureMode: 'spec-change', reuseCount: 5,
+      summary: '口径版本切换未同步 → 同名词指标在不同版本下口径不同。',
+      discriminator: '口径版本切换后，同名词指标在两版定义下口径不一致',
+      notWhen: '口径未变更时本假设不成立 —— 不要用「名字一样」当作口径一致的证据' },
+    { id: 'H3', kind: 'hypothesis', layer: 'type', title: '维表映射丢失', failureMode: 'data-processing', reuseCount: 4,
+      summary: '新渠道未补录维表 → join 落 unknown 后被 where 过滤。',
+      discriminator: '维表 join 后 unknown 占比显著升高，且缺口集中在新增维度成员上',
+      notWhen: 'unknown 占比正常时本假设不成立；缺口若均匀分布在各维度上，应转 H4 或 H5' },
+    { id: 'H4', kind: 'hypothesis', layer: 'type', title: '重复 / 回刷', failureMode: 'data-processing', reuseCount: 6,
+      summary: '上游重跑写入重复行 → 计数类指标放大。',
+      discriminator: '主键不唯一，或分区行数同比放大',
+      notWhen: '主键唯一性检查通过（T4.1）时本假设不成立 —— 这是最常被误判的一条' },
+    { id: 'H5', kind: 'hypothesis', layer: 'type', title: '时间窗口 / 时区', failureMode: 'data-processing', reuseCount: 2,
+      summary: '跨天事件被补写进 T-1 分区 → 单日指标异常放大。',
+      discriminator: '分区内事件时间跨天，且只有 T-1 单日异常',
+      notWhen: '相邻日期同时异常时应转 H2；事件时间落在单日内则应转 H4' },
+    { id: 'H6', kind: 'hypothesis', layer: 'type', title: '权限 / 过滤条件', failureMode: 'permission', reuseCount: 1,
+      summary: '行级权限或 where 条件变更 → 结果集被静默收窄。',
+      discriminator: '结果集被行级权限或 where 条件静默收窄',
+      notWhen: '权限与过滤条件在本周期未变更时本假设不成立' },
+    { id: 'H7', kind: 'hypothesis', layer: 'type', title: '下游 BI 缓存 / 增量', failureMode: 'consumption', reuseCount: 3,
+      summary: '缓存或增量刷新未触发 → 展示侧滞后，明细不受影响。',
+      discriminator: 'BI 展示侧滞后，但直连明细的数字正常',
+      notWhen: '明细对账一致（T7.2）时本假设不成立；注意 T7.1「缓存时间正常」不足以否定它' },
+
+    // `code` 是这张卡片的稳定标识：假设卡片里写的是编码（`failure_mode: data-processing`），
+    // 边要连到节点 —— 少了它，「编码 → 节点」就只能靠 F1..F5 的位置去猜。
+    { id: 'F1', kind: 'failure-mode', layer: 'type', title: '上游未产出', code: 'upstream-missing' },
+    { id: 'F2', kind: 'failure-mode', layer: 'type', title: '口径变更', code: 'spec-change' },
+    { id: 'F3', kind: 'failure-mode', layer: 'type', title: '数据处理', code: 'data-processing' },
+    { id: 'F4', kind: 'failure-mode', layer: 'type', title: '消费与展示', code: 'consumption' },
+    { id: 'F5', kind: 'failure-mode', layer: 'type', title: '权限与过滤', code: 'permission' },
+
+    { id: 'T1.1', kind: 'check', layer: 'type', title: '查分区存在性', costMinutes: 1, automation: 'auto', owner: '@duty',
+      summary: '分区 dwd_ord_di/dt 是否存在。不存在 → 支持 H1。',
+      verdictTrue: '分区不存在', verdictFalse: '分区存在' },
+    { id: 'T1.2', kind: 'check', layer: 'type', title: '查任务实例状态', costMinutes: 1, automation: 'auto', owner: '@duty',
+      summary: '上游任务实例是否 failed。failed → 支持 H1。',
+      verdictTrue: '实例状态 failed', verdictFalse: '实例状态 success / running' },
+    { id: 'T2.1', kind: 'check', layer: 'type', title: '口径版本对比', costMinutes: 15, automation: 'manual', owner: '@metric-owner',
+      summary: '对比近两次口径版本定义。口径变化 → 支持 H2。',
+      verdictTrue: '近两次口径定义不一致', verdictFalse: '口径定义逐字一致' },
+    { id: 'T3.1', kind: 'check', layer: 'type', title: 'unknown 占比', costMinutes: 2, automation: 'auto', owner: '@duty',
+      summary: '维表 join 后 unknown 占比。显著升高 → 支持 H3。',
+      verdictTrue: 'unknown 占比 > 5%', verdictFalse: 'unknown 占比 ≤ 5%' },
+    { id: 'T4.1', kind: 'check', layer: 'type', title: '主键唯一性', costMinutes: 3, automation: 'auto', owner: '@duty',
+      summary: '主键唯一性检查。通过 → 否定 H4。这是最常被误判的一条。',
+      verdictTrue: '存在重复主键', verdictFalse: '主键唯一 → 否定 H4' },
+    { id: 'T5.1', kind: 'check', layer: 'type', title: '事件时间分布', costMinutes: 8, automation: 'auto', owner: '@duty',
+      summary: '分区内事件时间分布。跨天 → 支持 H5。',
+      verdictTrue: '分区内事件时间跨出 T-1 单日窗口', verdictFalse: '事件时间全部落在 T-1 内' },
+    { id: 'T7.1', kind: 'check', layer: 'type', title: '查缓存时间戳', costMinutes: 2, automation: 'auto', owner: '@duty',
+      summary: '缓存时间正常并不能否定 H7 —— 便宜检查给不出结论。',
+      verdictTrue: '缓存时间戳过期', verdictFalse: '缓存时间正常 —— 注意：这一条**不足以**否定 H7' },
+    { id: 'T7.2', kind: 'check', layer: 'type', title: '直连明细对账', costMinutes: 35, automation: 'manual', owner: '@analyst',
+      summary: '明细对账一致 → 否定 H7。要否定它必须做这次贵检查。',
+      verdictTrue: '明细与报表数字不一致', verdictFalse: '明细与报表一致 → 否定 H7' },
+
+    // ── 引用层 ────────────────────────────────────────────────────────────
+    { id: 'dwd_ord_di', kind: 'asset', layer: 'reference', title: 'dwd_ord_di' },
+    { id: 'ods_order_sync', kind: 'asset', layer: 'reference', title: 'ods_order_sync' },
+    { id: 'dim_channel_df', kind: 'asset', layer: 'reference', title: 'dim_channel_df' },
+
+    // ── 实例层（默认折叠，展开后用于演示「证据与复用」） ────────────────────
+    // 案例节点是**图上的桩**：标题必须与 `SEED_CASES[].title` 是同一个字符串，否则同一份
+    // 知识会有两份标题（而且还真的不一致过：「只剩」vs「只有」）。画布要在标签前显示案例 id，
+    // 那是渲染层的事（见 `nodeStyleFor` 的 labelText）。
+    { id: 'CASE-001', kind: 'case', layer: 'instance', title: '日报 GMV 为 0' },
+    { id: 'CASE-002', kind: 'case', layer: 'instance', title: '订单数只有昨日 12%' },
+    { id: 'CASE-003', kind: 'case', layer: 'instance', title: 'DAU 突增 3.1 倍' },
+    { id: 'C1', kind: 'cause', layer: 'instance', title: 'C1 ODS 任务失败' },
+    { id: 'C2', kind: 'cause', layer: 'instance', title: 'C2 渠道维表未补录' },
+    { id: 'C3', kind: 'cause', layer: 'instance', title: 'C3 跨天事件补写' },
+    { id: 'E1', kind: 'evidence', layer: 'instance', title: 'E1 分区不存在' },
+    { id: 'E7', kind: 'evidence', layer: 'instance', title: 'E7 明细对账一致' },
+  ],
+  edges: [
+    // 层内：现象 → 假设（含一条僵尸边，用来演示「权重过期」）
+    //
+    // **三个现象共享同一批假设，这是这张图最重要的性质。** 每条现象只连它真正可能的原因，
+    // 于是「同一个假设被几个现象指向」就成了它的复用读数；而「为 0」与「突增」两个看起来
+    // 相反的故障，会在 H4（重复 / 回刷）上相遇 —— 这正是案例各长一棵树时永远看不见的东西。
+    { id: 'e-s1-h1', source: 'S1', target: 'H1', kind: 'may_be_caused_by' },
+    { id: 'e-s1-h2', source: 'S1', target: 'H2', kind: 'may_be_caused_by', staleDays: 94 },
+    { id: 'e-s1-h3', source: 'S1', target: 'H3', kind: 'may_be_caused_by' },
+    { id: 'e-s1-h4', source: 'S1', target: 'H4', kind: 'may_be_caused_by' },
+    { id: 'e-s1-h5', source: 'S1', target: 'H5', kind: 'may_be_caused_by' },
+    { id: 'e-s1-h6', source: 'S1', target: 'H6', kind: 'may_be_caused_by' },
+    { id: 'e-s1-h7', source: 'S1', target: 'H7', kind: 'may_be_caused_by' },
+
+    // 突降：产出缺失、重复回刷、维表过滤、缓存滞后都能造成下降；口径与权限这次不在列。
+    { id: 'e-s2-h1', source: 'S2', target: 'H1', kind: 'may_be_caused_by' },
+    { id: 'e-s2-h3', source: 'S2', target: 'H3', kind: 'may_be_caused_by' },
+    { id: 'e-s2-h4', source: 'S2', target: 'H4', kind: 'may_be_caused_by' },
+    { id: 'e-s2-h7', source: 'S2', target: 'H7', kind: 'may_be_caused_by' },
+
+    // 突增：放大只可能来自重复计数、跨天补写、缓存重复展示 —— 缺口类的原因在这里不成立。
+    { id: 'e-s3-h4', source: 'S3', target: 'H4', kind: 'may_be_caused_by' },
+    { id: 'e-s3-h5', source: 'S3', target: 'H5', kind: 'may_be_caused_by' },
+    { id: 'e-s3-h7', source: 'S3', target: 'H7', kind: 'may_be_caused_by' },
+
+    // 层内：假设 → 检查（H6 故意没有，它就是图上的空区）
+    { id: 'e-h1-t11', source: 'H1', target: 'T1.1', kind: 'verified_by' },
+    { id: 'e-h1-t12', source: 'H1', target: 'T1.2', kind: 'verified_by' },
+    { id: 'e-h2-t21', source: 'H2', target: 'T2.1', kind: 'verified_by' },
+    { id: 'e-h3-t31', source: 'H3', target: 'T3.1', kind: 'verified_by' },
+    { id: 'e-h4-t41', source: 'H4', target: 'T4.1', kind: 'verified_by' },
+    { id: 'e-h5-t51', source: 'H5', target: 'T5.1', kind: 'verified_by' },
+    { id: 'e-h7-t71', source: 'H7', target: 'T7.1', kind: 'verified_by' },
+    { id: 'e-h7-t72', source: 'H7', target: 'T7.2', kind: 'verified_by' },
+
+    // 层内：假设 → 失败模式（切面）
+    { id: 'e-h1-f1', source: 'H1', target: 'F1', kind: 'categorized_as' },
+    { id: 'e-h2-f2', source: 'H2', target: 'F2', kind: 'categorized_as' },
+    { id: 'e-h3-f3', source: 'H3', target: 'F3', kind: 'categorized_as' },
+    { id: 'e-h4-f3', source: 'H4', target: 'F3', kind: 'categorized_as' },
+    { id: 'e-h5-f3', source: 'H5', target: 'F3', kind: 'categorized_as' },
+    { id: 'e-h6-f5', source: 'H6', target: 'F5', kind: 'categorized_as' },
+    { id: 'e-h7-f4', source: 'H7', target: 'F4', kind: 'categorized_as' },
+
+    // 跨层：资产反向索引
+    { id: 'e-a-dwd-h1', source: 'dwd_ord_di', target: 'H1', kind: 'indexed_from' },
+    { id: 'e-a-ods-h1', source: 'ods_order_sync', target: 'H1', kind: 'indexed_from' },
+    { id: 'e-a-dim-h3', source: 'dim_channel_df', target: 'H3', kind: 'indexed_from' },
+
+    // 跨层：检查产出证据、证据支持或否定假设
+    { id: 'e-t11-e1', source: 'T1.1', target: 'E1', kind: 'produces' },
+    { id: 'e-e1-h1', source: 'E1', target: 'H1', kind: 'supports' },
+    { id: 'e-t72-e7', source: 'T7.2', target: 'E7', kind: 'produces' },
+    { id: 'e-e7-h7', source: 'E7', target: 'H7', kind: 'refutes' },
+
+    // 跨层：假设确认成根因
+    { id: 'e-h1-c1', source: 'H1', target: 'C1', kind: 'confirmed_as' },
+    { id: 'e-h3-c2', source: 'H3', target: 'C2', kind: 'confirmed_as' },
+    { id: 'e-h5-c3', source: 'H5', target: 'C3', kind: 'confirmed_as' },
+
+    // 跨层：案例实例化（三个案例各归各的现象，但收敛到**同一批假设**）
+    { id: 'e-case1-s1', source: 'CASE-001', target: 'S1', kind: 'instance_of', count: 1 },
+    { id: 'e-case2-s2', source: 'CASE-002', target: 'S2', kind: 'instance_of', count: 1 },
+    { id: 'e-case3-s3', source: 'CASE-003', target: 'S3', kind: 'instance_of', count: 1 },
+  ],
+}
+
+/** 三个 seed 案例，与上面图谱里的节点 id 对齐（0021 §11）。 */
+export const SEED_CASES: AttributionCase[] = [
+  {
+    id: 'CASE-001',
+    title: '日报 GMV 为 0',
+    symptomId: 'S1',
+    durationMinutes: 65,
+    rootCause: 'ODS 任务 ods_order_sync 02:40 失败且未启用重试，dwd_ord_di/dt 分区未产出。',
+    sections: [
+      { heading: '现象', body: '2026-08-11 日报 GMV = 0，前一日 128.4 万。指标值精确为 0 而不是偏低。' },
+      { heading: '影响面', body: '全量受影响，不随维度细分变化 —— 这个特征把「口径类」原因基本排除了。' },
+      { heading: '排查过程', body: '先确认分区是否存在（1 分钟），再确认上游任务实例状态；随后被下游缓存方向带走约 40 分钟，最终用明细对账否定它。' },
+      { heading: '根因', body: '上游 ODS 任务在 02:40 失败，重试未启用。分区缺失导致下游 dwd 无输入，指标落 0。' },
+      { heading: '修复与防复发', body: '补 dwd_ord_di 分区；给 ods_order_sync 加失败告警与自动重试；分区存在性检查加入日报前置校验。' },
+    ],
+    path: [
+      { nodeId: 'S1', label: 'S1', note: '进入：日报 GMV = 0' },
+      { nodeId: 'H1', label: 'H1', note: '按优先分 29 排第一' },
+      { nodeId: 'T1.1', label: 'T1.1', note: '查分区存在性 → 分区不存在' },
+      { nodeId: 'E1', label: 'E1', note: '产出证据，支持 H1' },
+      { nodeId: 'C1', label: 'C1', note: '确认根因' },
+    ],
+    misleading: {
+      nodeId: 'H7',
+      label: 'H7 下游 BI 缓存',
+      wastedMinutes: 40,
+      why: 'T7.1 查缓存时间戳只要 2 分钟且返回「正常」，但**这个便宜检查给不出结论**；要否定 H7 必须做 35 分钟的人工明细对账。浪费不发生在笨检查上，而发生在这种「便宜检查无结论、贵检查没人愿意先做」的夹缝里。',
+    },
+  },
+  {
+    id: 'CASE-002',
+    title: '订单数只有昨日 12%',
+    symptomId: 'S2',
+    durationMinutes: 22,
+    rootCause: '新增渠道未补录维表，dim_channel_df join 落 unknown 后被 where channel is not null 过滤。',
+    sections: [
+      { heading: '现象', body: '订单数 8,412，前一日 70,110，下降 88%。' },
+      { heading: '影响面', body: '按渠道维度切开后，缺口集中在新增的两个渠道 —— 这个线索直接指向维表而不是上游。' },
+      { heading: '排查过程', body: '按优先分先做最便宜的分区存在性检查（1 分钟），分区在，H1 被否定；接着做 H4 的主键唯一性检查，通过，H4 也被否定；转查 H3 的 unknown 占比，88%，一击确认。两次否定各花不到 3 分钟。' },
+      { heading: '根因', body: '新渠道未补录维表，join 落 unknown，被下游过滤条件静默丢弃。' },
+      { heading: '修复与防复发', body: '补录渠道维表；把 unknown 占比纳入日常巡检；下游过滤改为「先报警再过滤」。' },
+    ],
+    path: [
+      { nodeId: 'S2', label: 'S2', note: '进入：订单数下降 88%' },
+      { nodeId: 'H1', label: 'H1', note: '优先分第一（1 分钟的分区检查）' },
+      { nodeId: 'T1.1', label: 'T1.1✗', note: '分区存在 → 否定 H1', refuted: true },
+      { nodeId: 'H4', label: 'H4', note: '剩余先验最高' },
+      { nodeId: 'T4.1', label: 'T4.1✗', note: '主键唯一性通过 → 否定 H4', refuted: true },
+      { nodeId: 'H3', label: 'H3', note: '转向维表映射' },
+      { nodeId: 'T3.1', label: 'T3.1', note: 'unknown 占比 88%' },
+      { nodeId: 'C2', label: 'C2', note: '确认根因' },
+    ],
+  },
+  {
+    id: 'CASE-003',
+    title: 'DAU 突增 3.1 倍',
+    symptomId: 'S3',
+    durationMinutes: 35,
+    rootCause: '上游重跑把跨天事件补写进 T-1 分区，事件时间与处理时间边界被跨越。',
+    sections: [
+      { heading: '现象', body: 'DAU 112 万 → 347 万，无对应投放或活动。' },
+      { heading: '影响面', body: '只有 T-1 单日放大，相邻日期正常 —— 这排除了口径变更（口径类会同时影响多天）。' },
+      { heading: '排查过程', body: '主键唯一性通过，H4 被否定；再查缓存时间戳，返回「正常」但**这一条给不出结论**（与 CASE-001 是同一个坑）；最后查事件时间分布，发现跨天事件，命中 H5。' },
+      { heading: '根因', body: '上游重跑把跨天事件补写进 T-1 分区。' },
+      { heading: '修复与防复发', body: '重跑加事件时间边界校验；分区写入前检查事件时间下界。' },
+    ],
+    path: [
+      { nodeId: 'S3', label: 'S3', note: '进入：DAU 突增 3.1×' },
+      { nodeId: 'H4', label: 'H4', note: '优先分第一（重复数据会放大计数）' },
+      { nodeId: 'T4.1', label: 'T4.1✗', note: '主键唯一性通过 → 否定 H4', refuted: true },
+      { nodeId: 'H7', label: 'H7', note: '转向展示侧' },
+      { nodeId: 'T7.1', label: 'T7.1~', note: '缓存时间正常 —— 但这一条给不出结论' },
+      { nodeId: 'H5', label: 'H5', note: '转向时间窗口' },
+      { nodeId: 'T5.1', label: 'T5.1', note: '事件时间跨天' },
+      { nodeId: 'C3', label: 'C3', note: '确认根因' },
+    ],
+  },
+]