Week04｜作业｜Week04 Lakehouse 最小交付包与 baseline report

把 Week04 收口成一套可交接、可复核、可继续扩展的最小交付包

这份作业不是把实验页再机械重跑一遍，而是要求你把 Week04 真正交付成一套：

可解释、可回看、可演进、可验收 的 Lakehouse 基线包。

回看实验页 返回 Week04 总览

这次作业真正要交付什么

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

  • 为什么需要有记忆的表；
  • Iceberg 的状态模型是什么；
  • 最小 4 表应该怎样落；
  • 本地最小闭环怎样跑；
  • baseline 应该怎样看。

这次作业不是再演示一遍命令，而是要把这些内容整理成团队可交接交付物。

建议投入时间

建议按半天作业安排：先整理实验输出，再补齐设计说明、runbook 和评分自查。

最终必交工件

工件 文件/截图/报告 合格标准 常见不合格原因
ADR / Foundation docs/blueprints/week04/lakehouse_foundation_v1.md 目标、边界、为什么需要表状态记忆讲清楚 写成 Iceberg 百科，没有项目判断
source-to-Iceberg mapping docs/blueprints/week04/source_to_iceberg_mapping_v1.md source、target、transform、required、note 齐全 自己发明字段，和 repo schema 不一致
4 表物化记录 reports/week04/materialization_report.json 4 表范围、row count、write mode、snapshot 证据可复核 只有 create table，没有真实写入
time travel 记录 reports/week04/time_travel_demo_report.md 有 snapshot_id、old/current 对比和结论 只说“能 time travel”，没有证据
schema evolution 记录 reports/week04/schema_evolution_demo_report.md 只做 add-column，说明兼容性边界 扩展到 rename/drop 但无治理说明
baseline report reports/week04/iceberg_baseline_report.md 指标、异常、建议完整 只有截图或命令，无判断
runbook runbooks/week04/README.md 别人能按步骤复现并排错 只贴命令，不写前置与失败处理
课程同步包 docs/blueprints/week04/course_site_sync_packet_v1.md 课程页命令与项目 runbook 一致 页面、runbook、实际模块三者漂移
测试证据 Week04 contract / integration tests 输出 能证明 schema、catalog、dry-run、time travel、baseline 都可检查 只跑页面，不跑项目验证

Week04 在项目里的位置

Week04 作业页项目位置图：Week02 contract / manifest / gate 进入 Week03 batch + incremental baseline，再进入 Week04 lakehouse / snapshots / evolution，并分别支撑 Week05 semantic layer / transform、Week06 asset factory / backfill、Week08 retrieval consistency / serving。

与真实项目实现对齐

本次作业以 dataPro-lgtm/omnisupport-copilot 的 Week04 主线为准，不再使用占位命令。你提交时要能说明：

对齐点 项目路径 / 命令 作业里要体现什么
主执行路径 runbooks/week04/README.md 按 devbox CLI 跑，不把 Dagster 当主写入路径
环境契约 python -m pipelines.lakehouse.settings --check catalog、warehouse、MinIO endpoint 配置可解释
Catalog smoke python -m pipelines.lakehouse.catalog --smoke bucket、namespace、4 表可 ensure
物化 python -m pipelines.lakehouse.materialize --all-core --report-json reports/week04/materialization_report.json 4 表 row count、write mode、snapshot_id 可复核
Inspection python -m pipelines.lakehouse.inspect_metadata --table silver.ticket_fact --view snapshots snapshots / history / files 至少覆盖一张核心 Silver 表
Time travel python -m pipelines.lakehouse.demo_time_travel --table silver.ticket_fact --out reports/week04/time_travel_demo_report.md 有旧状态与当前状态对比
Schema evolution python -m pipelines.lakehouse.demo_schema_evolution --table bronze.raw_doc_asset --add-column source_checksum_algo --out reports/week04/schema_evolution_demo_report.md 只做 add-column，并说明兼容性边界
Baseline python -m pipelines.lakehouse.perf_baseline --all-core --out reports/week04/iceberg_baseline_report.md 形成可交接 baseline report

这次作业最重要的边界

Important不要把 Week04 做成 Week05+

这次作业不要求：

  • dbt / semantic layer 主实现；
  • Gold mart 全量设计；
  • RAG 主链路；
  • 重型基础设施引入；
  • compaction / cleanup 的完整生产 pipeline。

它只要求你交付 Week04 自己的最小闭环和正式交付包。

七项任务

任务 1：写清 Lakehouse foundation

lakehouse_foundation_v1.md 至少回答：

  • Week04 解决什么问题；
  • 为什么 Week03 ingest baseline 还不够；
  • 为什么要建立 table state reproducibility；
  • 本周做什么、不做什么；
  • 后续 Week05 / Week06 / Week08 如何消费这个结果。

任务 2：完成 source-to-Iceberg mapping

source_to_iceberg_mapping_v1.md 至少包含：

source source field target table target column type rule semantic note
ticket 待补 bronze.raw_ticket_event 待补 待补 待补

不要随意发明字段。真实字段以项目仓库的 source schema、pipelines/lakehouse/iceberg_schemas.py 和 Week02 contract 为准。

任务 3：完成最小 4 表设计

bronze_silver_table_design_v1.md 至少说明：

  • bronze.raw_ticket_event 的角色；
  • bronze.raw_doc_asset 的角色；
  • silver.ticket_fact 的角色；
  • silver.knowledge_doc 的角色；
  • Bronze 保真与 Silver 统一如何分工；
  • hidden partitioning 的初始判断；
  • 为什么不提前做 Gold / evidence anchor。

任务 4：完成 catalog runtime plan

catalog_runtime_plan_v1.md 至少说明：

  • 为什么选 PyIceberg；
  • 为什么用 PostgreSQL-backed SQL Catalog；
  • 为什么用 MinIO warehouse；
  • catalog / warehouse / table location 如何拆开；
  • CLI 与 Dagster thin wrapper 的边界；
  • 为什么当前学生主路径是 devbox CLI，而不是 Dagster 直接写 Iceberg。

任务 5：提交 baseline report

iceberg_baseline_report.md 至少包含：

  • 表名；
  • 当前数据规模；
  • snapshot 状态；
  • 文件状态；
  • 分区状态；
  • latest snapshot time；
  • time travel demo 结果；
  • schema evolution demo 结果；
  • 异常点；
  • 下一步建议。

任务 6：整理 runbook

runbooks/week04/README.md 至少覆盖：

  • 环境准备；
  • catalog 检查；
  • warehouse 检查；
  • ensure table；
  • materialization；
  • inspection；
  • time travel；
  • schema evolution；
  • baseline report；
  • 常见失败与排查。

任务 7：补齐验证证据

至少跑通或解释下面两类验证：

docker compose --profile tools --env-file infra/env/.env.local -f infra/docker-compose.yml run --rm devbox \
  pytest tests/contract/test_week4_iceberg_schema_contract.py -v
docker compose --profile tools --env-file infra/env/.env.local -f infra/docker-compose.yml run --rm devbox \
  pytest tests/integration/test_week4_catalog_smoke.py \
    tests/integration/test_week4_lakehouse_smoke.py \
    tests/integration/test_week4_time_travel.py \
    tests/integration/test_week4_perf_baseline.py -v

如果因为本地资源或 Docker 状态导致无法完整运行，你需要在提交说明里写清楚失败点、错误信息和下一步修复路径。

评分 Rubric

维度 优秀 合格 不合格
边界意识 能解释 Week4 做什么、不做什么，以及为什么不抢跑 基本列出 Week4 边界 把 dbt / RAG / Gold / governance 当主交付
可复现性 命令、输入、输出、失败排查都能让同学复现 有主要命令和报告 只有截图或口头成功
表设计说明 4 表角色、业务键、技术键、分区边界都清楚 4 表角色基本清楚 表边界混乱或字段自造
time travel 证据 有 snapshot_id、对比结果和结论 有旧状态回看记录 没有可复核证据
baseline 质量 指标、异常、建议、后续衔接完整 记录主要指标 只有数字，没有解释
runbook 可执行性 另一个同学可按 runbook 接手 基本可运行 命令散落、缺少前置与排错
与项目主线一致性 明确对齐 Week02/03/04/05 边界和 omnisupport-copilot 真实 runbook 基本对齐 另起一套命名或路径
验证证据 contract / integration tests 或等价输出齐全 有主要 smoke 输出 没有测试或失败原因说明

优秀 / 合格 / 不合格边界

等级 表现
优秀 有设计、有证据、有 baseline、有失败排查，能清楚解释为什么不抢跑
合格 交付物齐全，能覆盖 4 表、snapshot、time travel、schema evolution、baseline
不合格 只有截图不解释；只有命令无结果；没有 baseline；跳去做 RAG / dbt 但 Week04 闭环没跑通

不接受的作业类型

  • 只截图不解释；
  • 只贴命令无结果；
  • 没有 baseline report；
  • 抢跑 RAG / dbt，但 Week4 闭环没跑通；
  • 自己发明一套与 repo 不一致的字段和路径；
  • 复制旧课程页命令，但没有对齐当前项目 runbook。

提交格式

建议按目录提交 Markdown 报告、命令日志和 baseline report。截图可以作为辅助证据，但不接受“只贴截图不解释”的作业。

提交说明至少包含：

  • 本次使用的 repo commit；
  • 使用的 data batch / manifest；
  • catalog 与 warehouse 配置来源；
  • 真实命令来自哪个 runbook；
  • 哪些命令按 runbook 跑通，哪些因为环境原因没有跑通；
  • 失败点、绕过方式与后续风险。

优秀样例应该具备什么

优秀作业通常有这些特征：

  • 能解释为什么选当前 catalog / warehouse；
  • 能说明最小 4 表的边界；
  • 能给出 snapshot_id 和对比结果；
  • baseline report 有结论，而不是只有指标；
  • runbook 真的能让另一个同学复现；
  • 明确说明哪些内容留给 Week05、Week08 或 Week14。

推荐目录结构

docs/blueprints/week04/
  lakehouse_foundation_v1.md
  source_to_iceberg_mapping_v1.md
  bronze_silver_table_design_v1.md
  catalog_runtime_plan_v1.md

runbooks/week04/
  README.md

reports/week04/
  materialization_report.json
  time_travel_demo_report.md
  schema_evolution_demo_report.md
  iceberg_baseline_report.md

docs/blueprints/week04/
  course_site_sync_packet_v1.md

完成标准

这次作业真正的通过标准是：

  1. 你能交付一套和当前项目结构一致的 Week04 基线包。
  2. 你能清楚解释为什么只做最小 4 表和 baseline，不抢跑 Week05+。
  3. 你能说清当前 Dagster / CLI / runtime 的边界，而不是模糊带过。
  4. 你能提供可以被别人复核的 baseline report。

与 Week05 的衔接

Week05 会基于本周 Silver 表继续 transform 和语义层设计。

它不会回头替你补：

  • source-to-Iceberg mapping；
  • Bronze / Silver 表状态；
  • snapshot / time travel 记录；
  • baseline report；
  • Week04 runbook。

最后的收尾判断

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

Week04 交付的不是“会用 Iceberg”，而是一套以后能支撑 release-aware 数据系统的最小状态记忆层。