Week05｜作业｜提交 Week5 指标包 v1：形成可负责的口径资产

把 Week05 收口成一套能被团队复核和继续消费的指标资产包

这份作业不是提交一堆 SQL 文件。

你要交付的是一套能说明“指标从哪来、怎么算、谁能查、如何审计、哪里会受影响”的 Week05 指标资产包。

回看实验页 返回 Week05 总览

这次作业真正要交付什么

Week05 到这里，课程已经把这些判断讲清楚了：

• 指标是工程接口，不是孤立 SQL；
• dbt 分层是为了消费边界稳定；
• tests / docs / lineage 是口径证据链；
• 语义层先从本地 registry 起步；
• Agent 查询必须走受控工具，而不是裸写 SQL。

这次作业要求你把实验结果整理成正式交付包：口径资产包，不是 SQL 文件堆。

作业心智模型

你不是在证明自己写了很多 SQL；你是在证明一个指标从 source 到 tool 的路径可解释、可复跑、可复核、可复盘。老师或助教应该能根据你的工件回答：

• 这个指标从哪里来；
• 一行代表什么 grain；
• 经过哪些 transform、tests、docs 和 lineage evidence；
• 哪些指标、维度、过滤器和角色允许被 Agent 查询；
• 如果口径变了，会影响哪些模型、工具和报告。

Important作业交付的是口径资产包，不是 SQL 文件堆

如果你的提交只能证明“我写过 SQL”，还不够。合格交付必须证明：这套口径可以被团队继续维护，也可以被 Week06、Week08 和 Week10 继续消费。

建议投入时间

建议按半天作业安排：先整理实验输出，再补齐 ADR、执行蓝图、evidence、tool examples 和 delivery summary。

最终必交工件

类型	必交文件	作用	合格标准
ADR	docs/blueprints/week05/adr-week5-analytics-path.md	说明为什么采用本地 dbt Core + registry + tool contract	能解释不选 dbt Cloud / NL2SQL 的原因。1
执行蓝图	docs/blueprints/week05/week05-execution-blueprint.md	串起 sources、marts、tests、docs、registry 和 tool	有清晰数据流和边界
dbt 工程	analytics/	交付 sources / staging / intermediate / marts	dbt build --select tag:week05 通过
KPI mart	analytics/models/marts/support_kpi_mart.sql	形成可消费 KPI 层	grain、维度、指标行可解释
Safe view	analytics/models/marts/agent_tool_input_view.sql	工具层唯一查询入口	不含 PII、正文和任意 SQL 能力
Metric registry	analytics/metric_registry_v1.yml	锁定指标、维度、过滤器、角色和窗口	validator 通过
Tool contract	contracts/tools/tools/query_support_kpis_v1.json	定义受控指标查询工具 v1	输入输出 schema、拒绝码和审计字段完整
Evidence	reports/week05/dbt_build_evidence.md	记录 build、tests、docs、tool、pytest 证据	有命令、状态和关键结果
Examples	reports/week05/query_tool_examples.md	记录正例、负例和结果	至少 1 个正例、3 个负例
Audit notes	reports/week05/query_tool_audit_notes.md	说明审计字段如何解释	能回答谁查了什么、查哪版数据。2
Summary	reports/week05/week05_delivery_summary.md	收口最终判断和遗留风险	能让别人复核和接手

Tip模板入口

附录已提供 Metric Interface Card、Registry Entry、Lineage Impact Notes、Tool Contract Review Checklist 和 Delivery Summary 模板。先按模板补齐最小信息，再补截图或额外说明。

工件	它证明什么	常见不合格表现
ADR	你为什么选本地 dbt Core + registry + tool contract	只说“因为课程要求”，没有权衡
execution blueprint	source 到 mart、registry、tool 的路径可解释	只有目录截图，没有数据流
dbt models	transform 分层和 grain 可复跑	SQL 能跑但 grain 不清
metric_registry_v1.yml	指标、维度、过滤器、角色和窗口被白名单化	把 mart 中所有字段都开放
query_support_kpis_v1.json	Agent 输入输出有结构和拒绝路径	只有正例，没有拒绝码
dbt build evidence	build、tests、docs、tool、pytest 真跑过	只贴截图，不写命令和状态
lineage-impact-notes	口径变更影响面可复盘	只写“已更新 SQL”
query_tool_examples	正例和负例可复核	只有 allowed=true，没有 bad cases
query_tool_audit_notes	谁查了什么、基于哪版口径可追踪	audit 字段缺 actor、registry 或 release
delivery summary	让别人接手和继续 Week06/08/10	只做流水账，没有风险和边界

Week05 在项目里的位置

Week05 的正式交付会被后续三类系统继续消费：

• Week06：把 dbt / metric / tool evidence 纳入 asset orchestration；
• Week08：把 retrieval consistency 和业务指标口径关联起来；
• Week10+：把更多 Agent tools 纳入权限、HITL 和审计治理。

评分 Rubric

维度	权重	优秀	合格	不合格
口径定义	20%	grain、source、owner、filters、roles、audit 全部完整	主要字段完整	只有 SQL
dbt models	20%	分层清晰，tests/docs 完整，safe view 边界明确	marts 可跑，基础测试存在	无法 build 或 grain 不清
tests / docs / lineage / artifacts	20%	manifest / catalog / run_results / lineage notes / build evidence 完整	有 build 和测试证据	只有截图或口头说明
metric registry	15%	指标、维度、过滤器、角色、窗口和 owner 清晰	validator 通过，核心白名单存在	任意开放字段或无 validator 证据
query tool 正负例和审计	15%	权限、窗口、拒绝码、audit 齐全	有基本 schema 和部分拒绝例	Agent 裸 SQL 或无拒绝路径
delivery summary 与复盘能力	10%	能解释一次指标变更影响哪些模型、指标、工具和报告	有简单总结	无法说明改动影响

优秀 / 合格 / 不合格样例

类型	表现
优秀	p1_ticket_count 写清 source、grain、time dimension、维度白名单、owner、tests、registry、tool 正负例和 audit；dbt_build_evidence.md 能证明命令跑过
合格	support_kpi_mart 能 build，registry validator 通过，工具至少有正例和 bad_metric / bad_role 两个负例
不合格	只提交 select count(*)，没有 tests、docs、registry、tool contract；或让 Agent 直接查询 raw table

最小合格和优秀的差异不在“文件更多”，而在“别人能不能接手”：

层级	关键差异
最小合格	能 build，基础 tests 有，registry validator 过，工具有正例和至少两个负例
优秀	能解释一次口径变更影响面，负例覆盖完整，delivery summary 能让别人复跑、复核和继续维护

不接受的作业类型

Important不要把 Week05 做成平台秀

这次作业不接受：

• 只展示 dbt Cloud / Semantic Layer 截图：截图不能替代本地可复跑交付。³
• 只提交 dashboard SQL：SQL 不能证明 owner、grain、tests、docs、roles 和 audit。
• 让 Agent 生成或执行任意 SQL：这绕过了本周最核心的工具契约。
• 未经验证地开放 customer_email、comment body、raw SQL filter：这破坏 safe view 和权限边界。
• 把 analytics/target/、logs、临时数据当成主要交付：target 可以作为证据来源，但不是正式资产包。
• 把 Week06 / Week08 / Week10 的能力提前塞成本周必做：本周评分只看 analytics、registry 和安全指标查询工具 v1。

Warning不要提交无法复跑的截图式作业

截图可以辅助说明，但不能替代命令、evidence、registry、tool examples 和 delivery summary。负例测试和审计字段比“页面看起来跑过”更重要。⁴

建议交付结构

docs/blueprints/week05/
  adr-week5-analytics-path.md
  week05-execution-blueprint.md
  metric-contract-notes.md
  lineage-impact-notes.md

analytics/
  README.md
  dbt_project.yml
  profiles.yml.example
  models/
    sources.yml
    staging/
    intermediate/
    marts/
  metric_registry_v1.yml

contracts/tools/tools/
  query_support_kpis_v1.json

reports/week05/
  dbt_build_evidence.md
  query_tool_examples.md
  query_tool_audit_notes.md
  week05_lab_execution_summary.md
  week05_delivery_summary.md

week05_delivery_summary.md 最少回答什么

• 这次指标包覆盖哪些业务问题；
• 关键 KPI 的口径是什么；
• 哪些 source / staging / intermediate / marts 支撑它；
• 哪些 tests / docs / lineage artifacts 证明它可信；
• 哪些指标允许被 Agent 工具查询；
• 哪些维度、过滤器或时间窗口被禁止；
• 正例和负例验证结果是什么；
• audit 字段如何解释；
• 哪些能力留给 Week06 / Week08 / Week10。

交付前自查清单

• dbt debug 通过。
• dbt build --select tag:week05 通过。
• dbt docs generate 生成 artifacts。
• analytics/scripts/validate_metric_registry.py --json 返回 valid=true。
• query_support_kpis_v1 正例返回 allowed=true。
• 未知 metric 返回 METRIC_DENIED。
• 未授权 role 返回 ROLE_DENIED。
• agent_tool_input_view 不暴露 PII / comment body / raw SQL。
• dbt_build_evidence.md 写清命令和结果。
• week05_delivery_summary.md 写清限制和下一步。

提交前 15 分钟自查流程

1. 随机挑 2 个 metric，能否说清 grain、source、time field 和 owner？
2. dbt_build_evidence.md 是否包含 build、tests、docs、registry、tool、pytest 状态？
3. query_tool_examples.md 是否至少有 1 个正例和 3 个负例？
4. query_tool_audit_notes.md 是否解释 actor、registry、release、row_count？
5. metric_registry_v1.yml 是否没有开放 PII、正文或 raw SQL filter？
6. lineage-impact-notes.md 是否说明一次口径变化会影响哪些 marts、registry、tools、reports？
7. week05_delivery_summary.md 是否写清 Week06 / Week08 / Week10 的边界？
8. 是否没有把 analytics/target/、logs、临时数据作为主要交付提交？

加分项

• 为 support_case_mart 和 support_kpi_mart 补清晰 lineage 截图或 manifest 摘要。
• 给 metric registry 增加 owner / sensitivity / freshness 字段。
• 把工具审计字段映射到当前项目已有 audit log 结构。
• 为未来 MetricFlow / Semantic Models 迁移写 compatibility notes。
• 写一份 lineage-impact-notes.md，演示首响口径变化如何影响 mart、registry、tool 和 dashboard。

最后的收尾判断

如果只记住一句话，就记这句：

Week05 交付的不是“我会写 dbt”，而是一套能让 BI、Agent 和团队复盘共享同一业务口径的工程资产。

延伸阅读

主题	推荐资料	为什么读
dbt documentation	dbt Docs: Documentation	理解 docs 为什么是交付证据的一部分
dbt data tests	dbt Docs: Data tests	理解基础质量门禁
dbt unit tests	dbt Docs: Unit tests	理解复杂逻辑的样本验证
dbt artifacts	dbt Docs: Artifacts	理解 manifest / catalog / run_results 如何支撑 evidence
dbt Semantic Layer	dbt Docs: Semantic Layer	理解未来语义层迁移方向
OpenAI Function Calling	OpenAI Docs: Function Calling	理解工具调用为什么需要契约
OpenAI Structured Outputs	OpenAI Docs: Structured Outputs	理解结构化输出与工具审计

Footnotes

Footnotes

1. ADR 的价值不是写作文，而是让后来者知道你为什么选择本地 dbt Core、registry 和 tool contract，以及放弃了哪些替代方案。

2. 工具审计字段不是加分项。没有 actor、registry、release、metrics、filters 和 denial code，就无法追责和复盘 Agent 答案。

3. dbt Cloud 或托管 Semantic Layer 可以是未来路线，但本周作业要求本地可复跑、可验证的 Student Core 交付，不能用截图替代。

4. 负例测试能证明系统会拒绝不该发生的请求，比单个成功截图更能说明工具边界可信。