02 规划与设计

学员课程 02 规划与设计 的讲师配套材料。

时间安排

约 90 分钟，其中几乎没有任何无人值守的部分。这是唯一一个围绕个人或结对练习册工作展开的 模块，而不是靠后台跑脚本。第 1 步（性能画像脚本）是唯一自动化的环节，几分钟就能跑完； 其余全部，第 2 步的五份练习册和第 3 步的 migration-plan.md，才是这 90 分钟真正花掉的 地方。不要把休息安排在这个模块中间；如果教室需要休息，就放在模块 03 的交界处，而不是 练习册进行到一半的时候。

讲解要点

• 先说清楚这个模块不是什么：它不是模块 03 那场"真正的"迁移之前的拖延。ClickHouse 迁移性能不达预期，最常见的原因是架构问题，而不是调优问题，团队总是先搬数据，后做设计。
• 把这一点直接讲出来，因为它是为这 90 分钟辩护的最强论据：这是搭档最容易想跳过的模块， 因为模块 03 的 setup.sh 在 migration-plan.md 缺失或不完整时只会给出警告， 它从不阻塞。
• 讲一遍如果一位搭档还是跳过了会发生什么：他们在模块 03 里机械层面上照样能成功， fact_trips 照样以 ReplacingMergeTree 建起来，数据照样搬过去，但他们不会知道 为什么选这个引擎而不是普通的 MergeTree，不会知道 ORDER BY 键是如何从查询负载中推导出来的，不会认出 dbt 配置里的 delete_insert 和 FINAL， 也没有能力向客户解释或复现模块 05 的基准测试提速结果。
• 只在搭档已经尝试写过自己的方案之后，才指向"参考范例"（Worked Example）页面， 它是用来对照检查的，不是在思考之前拿来照抄的模板。

常见故障

• 第 1 步的性能画像脚本运行时 ACCOUNT_USAGE 不可用。 它要么需要 Snowflake 账号创建后 1-3 小时的数据传播延迟，要么需要 ACCOUNTADMIN 角色。脚本会自动回退到 INFORMATION_SCHEMA，并注明哪些指标没能测到，这是优雅降级，不是崩溃，但搭档可能不会 注意到发生了回退。如果自动生成的画像看起来内容太单薄，就指向 scripts/02_query_history.sql，它可以在 Snowflake UI 里手工运行。
• 一位搭档把 migration-plan.md 里的完成检查清单当成可选项。 它不是， 模块 03 的 setup.sh 会读取它，而一个未勾选的复选框就是本模块在实质上被跳过的信号， 即便那个文件本身存在。
• TODO：与模块 01 和 03 不同，本模块自己的 README 里没有排障小节。在练习册部分与真实 教室跑过一遍之后，用演练所得把这里补上。

重置步骤

• profile_report.md（第 1 步的输出）已被 gitignore，并且每次运行都会从搭档自己的实时 Snowflake 账号重新生成，如果它看起来陈旧或有误，直接重跑 ./scripts/01_profile_snowflake.sh。没有任何东西需要销毁。
• 五份练习册在站点上填写，答案会立即判分并保存在参与者的浏览器里（localStorage），而不是 保存在仓库中。migration-plan.md 仍然是在仓库里原地编辑，本模块不在任何一个云上开通 资源，所以既没有 teardown.sh，也没有可用的 setup 参数。
• 如果某位参与者把一份练习册弄到了糟糕的状态，就指向那份练习册自带的"Clear answers" 控件，而不是 git checkout，他们的答案从未进入 git，所以 checkout 帮不上忙。