文档与血缘：让别人读懂你的数据
目标：为客户汇总写明粒度、单位和口径，并生成可浏览的模型文档。
同事看到 revenue 列，会问：这是订单金额、实收金额，还是扣除退款后的净额？字段类型 decimal(12,2) 回答不了这些问题。模型文档应解释业务含义，特别是粒度、单位、筛选范围和边界情况。只写“这是收入”几乎没有增加信息。
dbt 将项目描述、模型依赖、测试和数据库对象信息组织成文档。血缘图中的箭头来自 ref/source 的依赖，不意味着所有业务关系都会自动被理解。第 5 课刻意分开的 seed 与 source，也不会因为物理对象相同就在图上自动连成一条线。
给现有属性文件补上含义
将 models/marts/schema.yml 完整替换为：
version: 2
models:
- name: customer_summary
description: >
一位客户一行，保留没有成交订单的客户。
只将当前状态为 completed 的订单计入消费；returned 和 placed 不计入。
金额是本练习的订单口径，不代表会计确认收入或实际现金流水。
columns:
- name: customer_id
description: 客户唯一编号，对应 stg_customers.customer_id。
data_tests: [not_null, unique]
- name: customer_name
description: 已去除首尾空格的客户名称。
- name: completed_order_count
description: completed 订单笔数；没有成交时为 0。
- name: revenue_cents
description: completed 订单金额之和，单位为分；没有成交时为 0。
- name: revenue
description: revenue_cents 除以 100，单位为元，保留两位小数。
description 是说明文字，> 让多行文本合并成一段。测试声明仍在同一个模型下面，不能为了补说明而丢掉它。文件名 schema.yml 只是习惯，dbt 通过内容而不是这个固定文件名识别属性。
先预测文档中谁会出现在 customer_summary 的上游，再运行：
uv run dbt docs generate --profiles-dir .
uv run dbt docs serve --profiles-dir . --port 8080 --no-browser
第一条命令生成文档产物；第二条启动预览服务，会占用终端。在浏览器地址栏输入 http://localhost:8080。在本课 v1 基线中，target/ 会出现 index.html、manifest.json、catalog.json。manifest 描述项目资源和依赖，catalog 补充数据库对象信息。
在文档里完成一次交接
- 打开 customer_summary，确认“保留没有成交订单的客户”出现在说明里。
- 查看 revenue_cents 与 revenue，确认一个写分、一个写元。
- 打开血缘图，沿 customer_summary 回到 stg_orders，再回到 shop.orders；另一支应通向 stg_customers 和 shop.customers。
- 查看 customer_id 的测试，确认非空和唯一检查仍在。
- 完成后回到终端，按 Ctrl+C 停止服务，再继续其他 dbt 命令。
停止服务时，这个版本可能打印 KeyboardInterrupt 或 Aborted，表示你手动中断了预览；这不代表之前的模型构建或测试失败。
这些观察分别核对业务说明、单位、依赖和检查，不能只以“网页能打开”作为文档完成标准。generate 不会代替 build 刷新报表；数据库还未构建时，文档中的数据库信息也可能不完整。
独立练习：在 models/staging/schema.yml 的 - name: stg_orders 下添加一句描述：“一行一笔订单，保留全部状态；金额以分存储，并提供元的展示列。”保留原有 columns 和所有测试。重新 generate，刷新网页核对。
参考变换与判断方法
把该模型开头两行改成下面三行，其余内容沿用第 7 课完整文件：
- name: stg_orders
description: 一行一笔订单，保留全部状态；金额以分存储，并提供元的展示列。
columns:
description 和 columns 缩进相同。重新生成后，stg_orders 页面应显示新说明，模型的 order_id 非空与唯一测试仍能看到。本练习的描述可以保留，不影响后续数据结果。
若端口被占用，先停止已有预览再启动；若文字没更新，确认改的是源 YAML，重新 generate 后刷新浏览器。若提示模型属性重复，不要在另一个文件再次声明同一个模型，合并到已有条目中。
本课保留带说明的 marts 属性文件，可保留 staging 描述。target 中的文档属于生成产物，来源仍是项目 SQL 和 YAML；下次代码更新后需要重新生成。