ARTICLE · 1249791
离线数仓开发插件拆解第三篇 | 离线数开流水线如何进行需求分析及概要设计
目录
• 一句加字段的需求，为什么会做偏[2] • P1 为什么独立站在研发之前[3] • 来源明确与来源不明，对应两种设计模式[4] • SQL 五问把字段判断落到数字上[5] • 八条规则检查设计能不能进入终版[6] • 知识缺口、增量沉淀和人工确认[7] • 终版贴回工单，下一阶段才能开工[8] • P1 能拦住什么，不能替你决定什么[9]
一句加字段的需求，为什么会做偏
还是用前两篇里的需求。ads_user_act_di 要增加首单渠道字段，来源指向 dwd_user_di，原有分区保留，第二天进入看板。
看到这里，熟悉 SQL 的人已经可以动手了。找到用户编号，关联用户明细，把渠道字段带过来，写到目标表。代码可能半小时就能写完。需要先回答的问题在后面。dwd_user_di 里的渠道字段是不是这次业务说的首单渠道，历史用户的渠道为空时该填什么，活跃用户和首单用户能否一一对应，目标表处于 ADS 层，直接消费 DWD 明细是否符合分层约定。这些问题没有先回答，SQL 写得越快，返工可能越早。
P1 数据概要设计处理的就是这一段。它不生成最终的 ETL，也不替代架构设计。P1 把一张需求里最容易含混的东西收进一份结构化设计，包括目标表、来源、字段映射、每一条映射的判断、验证 SQL、证据数字、知识来源、知识缺口和增量知识处理结果。
流水线里，P1 是唯一单独站在研发主流程之外的阶段。用户先做概要设计，确认设计结论，再把终版贴回工单。start 之后才从 P2 开始。这个顺序把想清楚与动手做分开。设计没有确认，研发入口不会打开。
P1 为什么独立站在研发之前
数据开发最容易出现的一种返工，来自早期假设没有被写出来。开发者先用一张明细表设计字段映射，架构阶段顺着这张表画链路，研发阶段遇到字段缺失，又发现需要补一层中间表。此时 SQL、调度和测试计划都已经开始做，改动会一路传下去。
把 P1 独立出来，先固定三件事。目标表是什么，字段从哪里来，凭什么判断这个来源是对的。设计结论还要写清分层、难度建议、是否需要中间表、用了哪份知识源以及还有哪些问题没解决。
这一步不追求一次把方案写得漂亮。它要让后面的人能看懂判断依据。一个字段映射只有“来源 dwd_user_di.channel_name”还不够，还要给出它和目标字段是否一致，不一致时改用什么，无法判断时为什么不能继续。设计文件是机器读取的，不是只给人看的说明文。
来源明确与来源不明，对应两种设计模式
概要设计有两条入口，取决于工单有没有声明来源。
工单已经写了来源表，走 verify。模型要拿声明的来源去对知识库里的域口径、表说明和分层规则，逐条判断字段映射。每条映射最终只能是三种结论之一，准确、不准确或无法判断。判成不准确必须给出修正，判成无法判断不能进入终版，要转成知识缺口继续查人或补知识。
工单只说了业务目标，没有给出源表，走 generate。模型先从知识库里找候选，路径包括域索引、记忆、数据资产和同类工单。找到候选表以后，仍然要走同一套 SQL 五问。没有声明来源不代表可以凭空猜一张表，候选来源同样要有证据。
两种模式最后汇入同一份 sds_design.json。这份文件里的 mode 记录本次怎么找到来源，declared_source 保留工单原始声明。每条字段映射由 field_mappings 逐项保存，目标字段和来源字段必须成对出现。来源层、验证结论与证据也随这条映射一起记录，后面的架构、研发和测试都从这里读。
SQL 五问把字段判断落到数字上
只靠字段名字相近，不能证明映射正确。P1 要求每次验证都有可重复的 SQL 和机器数字，大致回答五个问题。
row_count > 0 | ||
验证查询放在 verification/q*.sql，汇总结果写在 verification/evidence.json。sds_design.json 里也会保存一份 sql_validation。规则会逐项比较两份数字，默认容差只有 1e-9。两份文件不一致时返回 HALTED，流程停下来要求人工核查。
这个设计看起来有点严。开发者手写一段“命中率 99.8%”，旁边再放一份 SQL，也能让文档看起来很完整。把查询文件、证据文件和设计文件三处数字绑在一起，至少能发现复制错、改完设计忘改证据、替换了 SQL 却沿用旧结果这些情况。
验证阈值也不是随便定的。主键关联要求更高，因为用户、订单这类实体键对不上，后面的汇总通常已经不可信。普通维度允许略低一些，但低过阈值必须有解释。解释不是放行口令，它会以 WARN 保留下来，让后面的人知道这次设计接受了什么风险。
八条规则检查设计能不能进入终版
P1 的八条硬规则，分别检查结构、结论、溯源、分层、证据、比对、知识缺口和知识回流。
knowledge_source_uri 也在这里被检查。默认只接受配置好的知识库前缀，通常形如 viking://resources/。设计来源必须回到知识库里的具体文档，聊天内容不能承担这个来源。
规则通过以后，还要生成一份四段式说明书。说明书把需求与结论、目标表与字段映射、SQL 验证证据、风险与知识缺口放在一起。用户看到的是可读的确认材料，机器读取的是同一份设计文件里的 JSON 块。
知识缺口、增量沉淀和人工确认
八条规则能发现缺口，接下来还要处理缺口。SDS 后面有三道门。
知识缺口复核门处理当前知识库回答不了的问题。系统会要求用户选择刷新该域的知识库，或者由开发补充知识。复核轮次最多两轮，连续查不明白时状态会进入 blocked，避免模型在同一处反复兜圈。缺口存在时还要保存至少三条检索轨迹，其中一条必须命中知识库根，证明这次确实查过并且知道从哪里查。
增量沉淀门处理设计阶段新发现的知识。比如原工单没有声明来源，模型从数据资产里找到了候选表；或者声明来源经过验证发现字段含义不对，产生了修正。这类新知识有资格回写知识库。用户可以选择沉淀，也可以明确拒绝。设计文件会记录 synced 或 declined，不能空着进入终版。
确认门留给用户。系统先渲染说明书，用户看过目标表、字段映射、证据和缺口，再把确认记录写进 _user_confirmation.md。只有确认记录存在，confirmed=true 才能落进状态。模型可以准备材料，不能替用户签确认。
公开回归记录里，未确认的 SDS 会被确认门拦住，补上确认后再贴终版并回读。这个结果只说明门控按设计工作，业务口径是否正确仍然要看具体数据和人工判断。
终版贴回工单，下一阶段才能开工
确认完成后，流水线把设计组装成一条工单评论，锚头是 【数据概要设计 vN】。评论里包含说明书、完整 JSON 机读块和确认行。贴单以后还要调用 verify-latest 回读最新版本，确认这条评论确实存在，JSON 块和确认标记都能被找到。
接着生成 requirement_spec.md。这份文件上半部保留工单原文，下半部桥接 SDS 的目标表、字段映射、难度建议、知识来源和研发约束。P2 到 P6 都以这份文件作为共同输入，设计变更能够被下游看见。
准入门会再次检查工单是否存在、终版锚点是否在工单上、贴单内容能否重跑八条规则、口径指纹有没有变化，以及上下文能否重建。设计贴过但后来被改动，指纹会对不上，流程会停下来要求重新确认。
这就把“设计讨论”变成了可交接的契约。换个人接手，不需要先翻几十条消息。打开工单终版和 requirement_spec.md，能看到目标表、每个字段的来源、验证结果、未解决风险和本次难度。后面的研发如果偏离设计，P2 的交付表清单和 P3 的交付检查还会继续拦。
P1 能拦住什么，不能替你决定什么
P1 能拦住来源没有落到字段、映射没有结论、验证和证据对不上、知识来源不可追溯、知识缺口未处理、未确认就开工这些情况。它还能让设计选择在后续阶段留下可读取的版本，不用完全依赖会话记忆。
它不能证明业务口径天然正确。验证 SQL 本身写错，知识库口径过时，样本数据刚好避开边界，都可能让判断看起来通过。P1 的强项是把假设和证据摆到桌面上，让人知道这次设计建立在什么基础上。
P1 也不适合被拿来拖时间。一个字段都没有变化的临时查询，本来就走 L0 出口，不需要完整 SDS。需求真的会进入生产、会被别人接手、会改动已有任务时，先把目标表、来源和字段关系写清楚，后面的架构、研发和测试才有一个共同起点。
下一篇进入 P2 和 P3，看架构文档怎样把交付表清单变成研发契约，以及 DDL、ETL、调度任务为什么必须按顺序交付机器可验证的执行证据。
项目地址 MrSuiChuan/data-development-pipeline[1]许可证 Apache-2.0
引用链接
[1] MrSuiChuan/data-development-pipeline: https://github.com/MrSuiChuan/data-development-pipeline离线数仓开发插件拆解第一篇 | 从一条字段需求说起，离线数开为什么需要流水线
