P2 Foundry

数据质量：规则与闭环

数据质量不是"出问题再救火"，而是用规则把质量门槛前置：管道每次运行自动检查，坏数据当场生成问题、告警隔离，再走"确认 → 修复 → 验证"闭环。看完这 3 个故事，你就能自己建规则、看问题、闭环处理。

数据工程师业务分析师质量规则问题闭环告警隔离共 3 个故事

能 / 不能速览

✅ 这个主题能做

四类质量规则：null（空值）、format（格式正则）、unique（唯一性）、referential（引用完整性）
规则挂管道（pipeline）或对象（object），随管道运行自动检查结果表
违规自动生成问题（affected_rows 带 count + sample），error 级违规让 run 标 failed 并阻断目标对象同步（write_mode 管道不落盘坏数据，问题隔离）
问题状态闭环 open → acknowledged → fixed，规则报警驱动修复
规则可启用 / 停用，历史问题保留可复盘

⛔ 这个主题做不了

运行时只检查管道（pipeline）范围的规则，object 范围规则当前不随 run 自动检查
没有独立"手动跑检查"按钮，检查随管道运行触发
规则检查的是"结果表"对应列，列必须存在于结果表
修复动作不自动联动：重跑管道无违规后，旧问题仍需人工确认 / 修复

适用角色

本主题面向三个角色：

数据工程师：建规则、把规则挂到管道、修 SQL / 源数据、重跑验证——是核心使用者。
业务分析师 / 运营人员：查看问题列表、确认影响、推动修复，是"报警驱动"的响应方。
平台管理员：把握规则启停与问题处理节奏，在审计里看谁在何时确认 / 修复了什么问题。

能力速览（能做什么）

四类质量规则

null 空值计数、format 格式正则、unique 唯一性、referential 引用完整性（外键缺失），规则配置 JSON 化。

随管道检查

规则挂在管道上，每次运行自动对结果表执行检查，返回 {Total, Passed, Failed, Sample}，无需人肉核对。

问题隔离

违规即生成问题（count + sample 样本）；error 级违规把 run 标 failed，并阻断目标对象同步（write_mode 管道不把坏数据落盘到对象表，问题隔离、可查可修）。

状态闭环

问题生命周期 open → acknowledged → fixed，确认与修复都留痕，规则报警驱动持续修复。

规则治理

规则可启用 / 停用（不删定义），删除规则保留历史问题，便于复盘与灰度试点。

调整指南（怎么调整）

建规则：规则名 + scope_type（pipeline / object）+ scope_id + rule_type + rule_config（column 必填，format 加正则，referential 加 ref_table / ref_column）+ severity。
定严重级别：warning 只记问题不影响 run；error 违规会让 run 标 failed（数据已写入），适合关键字段。
灰度试点：新规则先 warning 跑几天，验证误报率再升 error 或全量启用。
临时关停：规则可停用（enabled=false）不删定义，历史问题保留，复盘时再开。
修复顺序：先修管道 SQL / 源数据，再重跑管道，确认检查通过后把问题 fix 闭环。

做得好的场景

质量规则把"事后发现"变成"运行时自动卡"，特别适合以下场景：

脏值前置拦截：状态字段混入未知枚举、金额列出现非数值，管道运行时当场报警。
孤儿数据防漏：订单引用了不存在的客户，referential 规则一次抓全。
问题驱动修复：规则报警 → 确认影响 → 修源 / 修 SQL → 重跑验证 → 闭环，全程留痕。
质量复盘：历史问题保留，季度复盘"哪类脏数据最多"，源头治理有依据。

限制与不足

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

运行时只查 pipeline 规则：管道运行时自动检查的规则范围是 pipeline，object 范围规则当前不随 run 检查（需要手动触发能力时注意）。
检查随管道触发：没有独立的"手动跑检查"按钮，规则检查发生在管道运行时对结果表执行。
检查的是结果表：规则的 column 必须存在于管道结果表，否则检查报错被跳过。
状态流转靠人：重跑管道无违规后，旧问题不会自动变 fixed，需人工确认 / 修复。
问题隔离与 write_mode：error 级违规会阻断目标对象同步（sync skipped），但管道中间结果表（SQL 步骤产物）可能仍在，恢复靠修复源/SQL 后重跑；无目标对象的管道行为不变。
demo 数据重建：演示数据每次启动重建，想复现违规需在管道 SQL 里人为制造脏行。

场景故事

故事 1 建列格式规则校验订单状态枚举，随管道运行自动把关

场景：格式规则角色：数据工程师耗时：约 6 分钟

背景: 上周报表里混进一行 status='unknown' 的订单，源头是某次上游同步。张工要防住这一类问题：在"数据质量"页建一条列格式规则，挂在订单清洗管道 orders_active_sync 上，让管道每次运行自动检查结果表的 status 列。

传统做法对比: 以前坏数据要等报表上线、用户反馈才被发现，一次问题排查加返工大半天；质量校验规则散在脚本里，改一次管道就忘一次。现在规则随管道运行自动执行，脏值当场报警，从源头卡住。

角色: 数据工程师（建规则 + 挂管道 + 运行验证）。

操作步骤

打开侧边栏"数据质量"→"规则管理"→"+ 新建规则"
规则名称=orders_status_enum、scope_type=pipeline、scope_id=orders_active_sync 对应的管道 id、rule_type=format、severity=error
rule_config 填 column=status、format_regex=^(shipped|pending|cancelled)$，勾选"创建后即启用"
保存后到"管道构建"运行 orders_active_sync

系统响应: 创建返回 {"code":0,"data":{"id":N}}；管道运行后质量检查自动执行，返回 {total: 4, passed: 4, failed: 0}（4 行全过），无问题生成，run 仍为 success。

结果洞察: 质量门槛从"事后发现"前移到"管道运行时自动卡"：规则挂在管道上，只要 status 列出现枚举外的值，这次运行就会生成质量问题并隔离。当前演示数据是干净的，检查全通过——这正是该有的样子；哪天真混进脏数据，规则会第一时间报警，不再等用户反馈。

调整建议: severity 选 error 会让违规管道 run 标 failed（但数据仍已写入，告警 + 隔离）；新规则先 warning 灰度跑几天再升 error；格式正则先在少数行验证，避免误报；规则可随时停用，历史问题保留。

动手试一试: 登录：admin / admin1。页面路径：数据质量 → 规则管理。输入内容：orders_status_enum、scope_type=pipeline、scope_id=orders_active_sync 的 id、rule_type=format、column=status、regex=^(shipped|pending|cancelled)$、severity=error。预期结果：运行管道后无 issue（数据干净全通过），规则列表出现该规则。

限制提示: 规则检查的是"管道结果表"对应列，column 必须在结果表存在；检查随管道运行触发（无独立手动检查按钮）；想复现违规需在管道 SQL 里人为制造脏行（demo 数据每次启动重建）。

故事 2 引用完整性规则：孤儿订单 customer_id=99 当场被抓

场景：引用完整性角色：数据工程师耗时：约 8 分钟

背景: 张工接到反馈：清洗后的 orders_active 里混进了一行 customer_id=99 的孤儿订单，客户主表根本没有 99。他在"数据质量"页建引用完整性规则——orders_active.customer_id 必须存在于 customers.customer_id，挂到管道上随运行检查。

传统做法对比: 以前孤儿数据要么靠手工 SQL 反查（SELECT ... WHERE NOT IN 自己写），要么等业务用着用着才发现，一次外键漂移能漏好几周。现在 referential 规则把外键关系声明成检查，脏数据一进管道就被拦下并记录样本。

角色: 数据工程师（建规则 + 造脏数据验证 + 观察问题生成）。

操作步骤

"数据质量"→"规则管理"→"+ 新建规则"：名称=orders_customer_exists、scope_type=pipeline、scope_id=orders_active_sync 的 id、rule_type=referential、severity=error
rule_config 填 column=customer_id、ref_table=customers、ref_column=customer_id
保存后，在管道 SQL 的 create_table_as 里 UNION ALL 一行 customer_id=99（模拟上游脏数据）
运行管道，观察结果与问题生成

系统响应: 检查返回 {total: 5, passed: 4, failed: 1, sample: [99]}；问题列表新增一条 open issue，affected_rows={count:1, sample:[99]}；因 severity=error，run 标 failed，error 提示"1 quality rule(s) with severity=error violated (target object sync skipped, issues isolated)"。

结果洞察: 引用完整性规则把"外键关系"变成可执行检查：孤儿订单 1 行当场被抓，连样本值 99 都记下来了。关键在"问题隔离"：配置了目标对象（write_mode）的管道，error 级违规会阻断目标对象同步，坏数据不落盘到对象表；同时生成 issue、run 标 failed——既不让坏数据进下游，又不让流程静默。随后走确认 → 修复闭环，坏数据不再无声扩散。

调整建议: 先修管道 SQL 去掉 UNION ALL 脏行再重跑；或先 acknowledge 问题、等上游修复后重跑，规则全通过时把 issue fix；ref_table / ref_column 大小写与真实表名一致，否则检查 SQL 会报错。

动手试一试: 登录：admin / admin1。页面路径：数据质量 → 规则管理 → 管道构建。输入内容：referential 规则 customer_id → customers.customer_id；管道 SQL UNION ALL 一行 customer_id=99 后运行。预期结果：检查 failed=1、sample=[99]，生成 open issue，run 因 error 级违规标 failed。

限制提示: referential 规则基于"值不在引用表则违规"的 SQL 判定，引用表 / 列要真实存在；演示库每次启动重建，脏行需重造；问题生成依赖管道运行，先跑管道才有 issue。

故事 3 问题列表 → 确认 → 修复闭环：规则报警驱动处理

场景：问题闭环角色：业务分析师 + 数据工程师耗时：约 8 分钟

背景: 昨晚管道运行生成了 2 条质量问题（1 条 status 脏值、1 条孤儿客户）。王姐今天打开"数据质量"处理：先看问题列表确认影响，再推动张工修复，最后闭环。她要体验一遍 open → acknowledged → fixed 的完整生命周期。

传统做法对比: 以前坏数据要么没人管、要么靠邮件群里喊"谁处理一下"，处理到哪一步全靠自觉，复盘的记录基本没有。现在问题有状态机、有样本、有确认与修复动作，谁在何时确认、何时闭环都留痕。

角色: 业务分析师（查看 / 确认问题）+ 数据工程师（修 SQL / 源数据 + 重跑验证）。

操作步骤

"数据质量"→"质量问题" tab，状态筛选 open，看问题列表
逐条展开 affected_rows 的 count / sample，判断影响面
对可确认的问题点"确认"（acknowledge），open → acknowledged
张工修正管道 SQL / 上游数据后重跑管道，检查全通过
回到问题列表，对处理完的问题点"修复"（fix），acknowledged → fixed

系统响应: 确认返回 {"id":N,"status":"acknowledged"}；修复返回 {"id":N,"status":"fixed"}；问题列表状态徽标从 open → acknowledged → fixed 依次变化。

结果洞察: 质量问题的生命周期被完整管理：open（待处理）→ acknowledged（已确认）→ fixed（已修复）。规则报警驱动修复，确认与修复动作都可追溯——谁在何时确认了影响、谁在何时闭环，全程留痕。这一套下来，质量不再是"出问题才救火"，而是"规则 → 报警 → 确认 → 修复 → 验证"的持续闭环。

调整建议: 修复动作严格走"改 SQL / 改源数据 → 重跑管道 → 检查全通过 → fix"；already fixed 的问题不能再重复 fix（接口校验）；规则停用后历史问题仍保留，季度复盘直接用。

动手试一试: 登录：admin / admin1。页面路径：数据质量 → 质量问题。输入内容：造 1~2 条问题（管道 SQL 含脏行）后运行管道，然后逐条确认 → 修复。预期结果：状态依次 open → acknowledged → fixed，界面徽标与返回一致。

限制提示: 重跑管道无违规后，旧 issue 不会自动变 fixed——状态流转由人驱动（需人工确认 / 修复）；error 级违规 run 标 failed 并阻断目标对象同步（无目标对象的管道其 SQL 步骤结果保留），恢复需修复源/SQL 后重跑正确管道；已 fix 的问题不能再 acknowledge。

常见问题

质量检查什么时候触发？

随管道运行触发：管道执行完 SQL 步骤后，会自动取该管道（scope=pipeline）下启用的规则，对结果表逐条执行检查（null / format / unique / referential）。目前没有独立的"手动跑检查"按钮。

error 和 warning 规则有什么区别？

warning 违规只记录问题，不影响 run 结果；error 违规除了记录问题，还会把这次 run 标为 failed，并阻断目标对象同步（error 信息提示"target object sync skipped, issues isolated"）——配置了目标对象的管道不会把坏数据落盘。关键字段建议用 error。

为什么我建的 object 范围规则不检查？

当前管道运行时自动检查的规则范围是 pipeline；object 范围的规则定义会被保存，但不随 run 自动执行。想让它"跑起来"，把规则挂到具体管道（scope_type=pipeline）上。

问题修好了会自己关闭吗？

不会。问题状态由人驱动：open → acknowledged → fixed。即使重跑管道后不再有违规，旧问题也需要人工确认 / 修复来闭环，这样处理动作有留痕，复盘有依据。

演示数据怎么复现质量问题？

演示库每次启动重建，数据是干净的。想复现违规，可在管道 SQL 里人为制造脏行（如 UNION ALL 一行非法 status 或不存在的 customer_id），让规则在运行时把它抓出来生成问题。

主题小结

一句话：数据质量的核心是"规则随管道运行自动把关 + 问题走确认修复闭环"——四类规则（null / format / unique / referential）挂在管道上，违规生成带样本的问题，open → acknowledged → fixed 全程留痕。记住几个边界：运行时只查 pipeline 规则、检查随管道触发、状态流转靠人驱动。