P2 Foundry

数据血缘：来路与去向

数据从哪来、被谁加工、被哪个指标消费、被谁改写过？血缘把"源 → 管道 → 对象 → 指标"前四跳链路画成图（报表最后一跳当前断链，P1），改表先评估影响，写回留下写边。看完这 3 个故事，你就能自己查来路、估影响、追责改动。

数据工程师业务分析师影响分析写边追踪审计共 3 个故事

能 / 不能速览

✅ 这个主题能做

GET /lineage 从任意节点沿 upstream / downstream BFS 展开血缘图（nodes + edges）
四级链路：源表 → 管道 → 对象 → 指标前四跳自动打点（节点用稳定标识），Action 写回打"对象 → 动作"写边
Action 写回自动打"对象 → 动作"写边，配合审计可追"谁在何时改了什么"
边带字段映射 field_map（表级为主，字段级 P2 渐进），边幂等不重复插入
结合 POST /ontology/objects/:id/impact 做对象被引用位置的影响分析

⛔ 这个主题做不了

血缘边"按需打点"：对象创建本身不记"源表 → 对象"边，必须跑过以该对象为目标的管道
报表血缘断链（P1）：仪表盘模块没有血缘引用，"指标 → 报表"最后一跳无生产打点，血缘图里查不到 report 节点
写边只到"对象 → 动作"层，单条记录变更明细在编辑态 / 审计里，不在血缘图里
外部系统（血缘图外）的数据消费不在感知范围

适用角色

本主题面向三个角色：

数据工程师：查血缘评估改表影响、排数据链路、定位数据来源——是核心使用者。
业务分析师 / 运营人员：理解"这个数是怎么来的"，向领导解释口径来源。
平台管理员 / 审计：通过 Action 写边 + 审计日志追溯"谁在何时改了什么"。

能力速览（能做什么）

方向追溯

从任意节点沿 upstream（上游：数据从哪来）或 downstream（下游：数据被谁用）逐层 BFS 展开，自动防环。

四级链路

源 → 管道 → 对象 → 指标前四跳自动打点，节点用稳定标识引用（表名 / 管道名 / 对象名 / 指标名），跨环境安全；报表最后一跳当前断链（P1）。

Action 写边

每次 Action 写回成功自动打点"对象 → 动作"边，改动在血缘图里可见，配合审计定位责任人。

字段映射

血缘边可带 field_map（如源列 → 目标列），当前以表级 / 对象级为主，字段级 P2 渐进。

影响分析

对对象做 POST /ontology/objects/:id/impact，返回被链接 / 管道 / 血缘 / 指标 / 编辑引用的位置清单。

调整指南（怎么调整）

看单层 vs 全链路：depth=1 只看直接上下游，depth 设大（如 10）看全链路，BFS 自动防环。
换方向：要查"谁用我"选 downstream，要查"我从哪来"选 upstream，同一节点换方向即切换视角。
补链路：想让"源 → 对象"边出现，跑一条以该对象为目标对象的管道；想接指标，给对象建指标。
追写回：改动对不上账时，从对象下溯找 action 节点，再到审计 / 编辑态看 prior state。
做变更评估：改表前先查下游，再用影响分析接口拿被引用清单，附在变更单上。

做得好的场景

血缘把"数据来路"从人脑变成图，特别适合以下场景：

解释指标来源：被问"这个数哪来的"，血缘图一拉，从源表到指标一条链交代清楚。
改表影响评估：customers 表要改结构，下游谁在读、谁在同步，先查血缘再动手。
变更追责：订单状态被改了，Action 写边 + 审计定位"谁、何时、改前值"，有据可查。
链路健康巡检：查关键对象的下游，确认管道 / 指标消费关系没断。

限制与不足

以下是明确的边界，使用前先知道：

按需打点：血缘只记录"真实发生过"的关系。仅创建对象、从未跑管道，customers 的下游可能为空。
报表血缘断链（P1）：四级链路的前四跳（源 → 管道 → 对象 → 指标）可用，但"指标 → 报表"最后一跳断链——dashboard 模块没有任何 Lineage 引用，RecordMetricToReport 无生产调用方，血缘图里查不到 report 节点。
写边粒度：写边只到"对象 → 动作"层，单条记录的变更明细在编辑态 / 审计里查。
字段级渐进：field_map 目前以表级 / 对象级为主，字段级映射属 P2 渐进能力。
外部盲区：平台血缘图之外的外部系统消费，不在感知范围内。

场景故事

故事 1 王姐写周报被问"总销售额哪来的"，血缘一查讲清楚

场景：来源追溯角色：业务分析师 + 数据工程师耗时：约 6 分钟

背景: 周五周报评审，领导问王姐："这个总销售额（total_gmv）到底是从哪来的？"王姐只会在指标查询里点按钮，说不清数据链路。她拉上张工，在"数据血缘"页把 total_gmv 的上游一层层查出来。

传统做法对比: 以前要翻建数文档、问当年写报表的人，链路往往断在某个离职同事的聊天记录里；"这个数怎么来的"可能永远说不清。现在血缘一查，节点、边、方向都在图上，几分钟讲清楚来龙去脉。

角色: 业务分析师（查血缘理解来源）+ 数据工程师（解释链路与打点规则）。

操作步骤

登录平台，打开侧边栏"数据血缘"
节点类型选 metric，节点 ID 填 total_gmv，方向选 upstream（上游），depth 填 10，点查询
看到 total_gmv 的直接上游：order 对象（对象 → 指标边在指标创建时自动打点）
继续查 order 对象的上游，看到 orders 源表（若之前跑过以 order 为目标对象的管道）
把节点 / 边截图附进周报，向领导交代链路

系统响应

返回示例：

{
  "nodes": [
    { "type": "metric", "id": "total_gmv" },
    { "type": "object", "id": "order" },
    { "type": "source", "id": "orders" }
  ],
  "edges": [
    { "from": { "type": "object", "id": "order" },
      "to": { "type": "metric", "id": "total_gmv" } }
  ]
}

页面上节点表格与边表格（from → to）并排展示。

结果洞察: 指标不是凭空算出来的：total_gmv 的直接上游是 order 对象（指标创建那一刻自动打点），order 再由 orders 源表经管道加工而来。王姐在周报里一句话交代清楚："订单表 → 订单对象 → 总销售额指标"，领导当场点头。对象 → 指标这种边全自动打点，不需要人工维护。

调整建议: 想看到"源 → 对象"段，需要跑过以该对象为目标对象的管道（源 → 管道 → 对象）；重跑管道不会产生重复边（幂等）；边详情里的 field_map 可展开看字段映射，字段级细化在 P2 渐进。

动手试一试: 登录：admin / admin1。页面路径：数据血缘。输入内容：type=metric、id=total_gmv、direction=upstream、depth=10。预期结果：至少出现 order → total_gmv 一条边；若跑过相关管道，还能看到 orders 源表节点。

限制提示: 血缘边"按需打点"：对象创建本身不记录"源表 → 对象"边，必须先跑过以该对象为目标对象的管道；报表血缘断链（P1）——仪表盘模块没有血缘引用，"指标 → 报表"最后一跳无生产打点，血缘图里查不到 report 节点。

故事 2 DBA 要改 customers 表结构，张工先用血缘评估下游影响

场景：影响评估角色：数据工程师耗时：约 8 分钟

背景: 周一 DBA 通知：customers 表下周要改结构（region 字段改枚举并新增一列）。张工得先搞清楚"谁在用 customers、改表会波及哪些下游"，再决定迁移顺序。他打开血缘页查 customers 的下游，并跑影响分析拿引用清单。

传统做法对比: 以前改表靠"问一圈 + 猜"：问各团队"你们有用 customers 吗"，答不上来的就漏了；改挂一次线上报表，救火一整天。现在血缘下游一查 + 影响分析一出，受影响面一次列全，照着排迁移顺序。

角色: 数据工程师（评估影响、排迁移计划）；DBA 提供变更时间窗。

操作步骤

打开"数据血缘"，节点类型选 source，节点 ID 填 customers，方向选 downstream，depth 填 10，点查询
看下游节点列表：哪些管道读了 customers、哪些对象由它同步而来
对关键对象调 POST /ontology/objects/:id/impact 做影响分析，拿被引用位置清单（链接 / 管道 / 血缘 / 指标 / 编辑）
按影响面排序迁移计划：先改对象映射，再改管道，最后改源表
把血缘截图与影响清单附在变更单上，提前通知下游负责人

系统响应: 血缘返回 customers 的下游边（若被同步管道消费则出现 source → pipeline）；影响分析返回对象被引用位置，如"被 2 个链接、1 个管道、3 处血缘引用"，逐项列出引用详情。

结果洞察: 改表最怕"不知道谁在用"。血缘把消费者一次性列出来：谁读了 customers、谁把它同步成对象、有没有指标直接依赖。张工据此把迁移顺序定为"先改对象映射 → 再改管道 → 最后改源表"，并提前通知下游。影响评估从"靠记忆 + 开会问"变成"查图即得"，变更单也更好写了。

调整建议: depth=1 只看直接下游，要全链路设大 depth；删改字段时重点核对对象属性映射，属性被指标引用时指标创建校验会拦截，先清理依赖；字段级影响（具体哪些列被用）P2 渐进，目前先看表级 / 对象级。

动手试一试: 登录：admin / admin1。页面路径：数据血缘。输入内容：type=source、id=customers、direction=downstream、depth=10。预期结果：若跑过消费 customers 的管道可见对应下游节点；再到对象详情 / 接口做影响分析，拿被引用清单。

限制提示: 血缘只记录"真实跑过"的关系——仅创建对象、从未跑管道，customers 的下游可能为空；影响分析基于平台内引用（链接 / 管道 / 血缘 / 指标 / 编辑），血缘图之外的外部系统消费不在感知范围。

故事 3 订单状态被改了？Action 写边 + 审计追出"谁、何时、改前值"

场景：写边追踪角色：运营人员 + 数据工程师耗时：约 7 分钟

背景: 周三运营小陈用 update_order_status 把 order_id=2 从 pending 改成 shipped。周四数据对不上账，张工要追查"谁在何时改了这单"。血缘页里 order 对象的下游应该有一条 Action 写边，配合审计就能定位责任人。

传统做法对比: 以前改状态要么找 DBA 手写 UPDATE（无审计、无回滚，出事了查不到谁改的），要么线下 OA + 人工同步，一次变更动辄半天。现在 Action 是唯一写路径，执行成功自动打写边，配合审计日志，"谁、何时、改前值"一查即中。

角色: 运营人员（执行 Action 写回）+ 数据工程师（查血缘 / 审计定位改动）。

操作步骤

确认之前 Action 执行成功：在"Action 测试"选 update_order_status，填 order_id=2、status=shipped，先 VALIDATE 再 VALIDATE_AND_EXECUTE
打开"数据血缘"，节点类型选 object，节点 ID 填 order，方向选 downstream，depth 填 10，点查询
在下游节点里找到 update_order_status 动作节点（对象 → 动作写边）
到审计日志按对象 / 时间过滤，看操作人、时间与编辑态 prior state（改前值）

系统响应: 血缘返回 order 的下游边，其中一条为 { "from": { "type": "object", "id": "order" }, "to": { "type": "action", "id": "update_order_status" } }；审计 / 编辑态中可查到该次执行的操作人、时间与 prior state（status: pending）。

结果洞察: 写回不是"改了就没影"：每次 Action 成功执行都会在血缘里留下 order → update_order_status 的写边，配合审计日志（操作人、时间、编辑态 prior state），"谁在何时改了什么"一查即中。小陈的修改有据可查，业务方核对数据时也能自证清白——这正是受控变更该有的样子。

调整建议: 执行 Action 时务必带上 expected_updated_at 乐观锁期望值，减少 409 冲突；要查某次具体执行的前后值，去编辑态 / 审计看 prior state；给关键对象配审批策略（最少批准人数、指定评审人），从源头压缩无痕改动。

动手试一试: 登录：admin / admin1。页面路径：对象查询 → Action 测试（把 order_id=2 改为 shipped）→ 数据血缘。输入内容：type=object、id=order、direction=downstream。预期结果：下游出现 update_order_status 动作节点；审计里能看到该次写回的操作人与时间。

限制提示: 写边仅在 Action 成功执行时打点（VALIDATE 预校验不落盘、不打点）；demo 数据每次启动重建，写回源表的改动会还原，但编辑态与审计记录保留在平台库；写边只到"对象 → 动作"层，单条记录的变更明细在编辑态 / 审计里查。

常见问题

血缘里为什么会没有我想看的边？

血缘边是"按需打点"：只在真实动作发生时记录——管道运行成功（源表 → 管道、管道 → 对象）、指标创建（对象 → 指标）、Action 执行成功（对象 → 动作）。对象创建本身不记"源表 → 对象"边，所以仅创建对象、从未跑管道时，下游可能为空。另外报表边当前断链（P1）：仪表盘模块没有血缘引用，血缘图里查不到 report 节点。

upstream 和 downstream 怎么区分？

从某个节点出发：upstream 是"数据从哪来"（一级级往上找源），downstream 是"数据被谁用"（一级级往下找消费者）。同一个节点换方向就是换视角，depth 控制展开几层。

节点 ID 填什么？

填稳定标识：对象填对象名（api_name，如 order）、管道填管道名、源填表名（如 orders）、指标填指标名（如 total_gmv）。血缘页里 type=object 时会提供对象名下拉候选。

血缘和审计日志什么关系？

血缘回答"数据链路"：谁在链路里、流向哪里；审计 / 编辑态回答"操作细节"：谁、何时、改前值（prior state）。Action 写回会在血缘里留"对象 → 动作"写边，而具体某次改动的明细要到审计 / 编辑态里查。

字段级血缘有吗？

血缘边支持 field_map 字段映射字段，但当前以表级 / 对象级打点为主，字段级映射属 P2 渐进能力。想按字段细化影响评估，目前要靠"对象属性 + 指标校验"这类间接手段。

主题小结

一句话：血缘把"数据来路"从人脑变成图——源 → 管道 → 对象 → 指标前四跳链路，加上 Action 写边。记住几个边界：边是"按需打点"（跑过管道才有源对象边）、报表血缘断链（P1，dashboard 无 Lineage 引用）、写边只到对象 → 动作层、字段级映射 P2 渐进。