从零开始：项目环境与数据准备

本章目标：从一个空目录开始，把项目要用的目录、数据、实验室库和 Git 仓库准备好，并跑通第一条校验。 前置知识：会打开终端、执行 cd 和 python 命令。不需要先学完 Hive、Spark 或数仓理论。 预计用时：40–60 分钟，主要花在下载数据和排错上。

0. 本章结束时你要有什么

1. 一个项目目录，里面有 data/raw/olist/ 和 8 个 CSV。
2. 一个能打开的实验室库 project/warehouse_lab.duckdb。
3. 一次成功的 Git 提交，且 CSV 不会进入仓库。
4. 一条能跑通的原始数据校验查询。

完成标志：python scripts/check_data.py 输出 8 张表 / 550,759 行，并且你能用 DuckDB 直接查到 99,441 个订单。

1. 项目线和理论线是什么关系

这个站有两条线：

不要因为还没学 Hive/Spark 就停在项目门口。 项目主线只需要 Python、DuckDB 和 SQL；Hive/Spark 是后面的迁移视角，不影响你先把数仓建出来。

2. 准备工具

在项目根目录（能看到 data、scripts、project 的那一层）打开 Git Bash，逐条检查：

python --version          # 3.10 及以上
git --version
python -c "import duckdb; print(duckdb.__version__)"

• Python 没有：看环境搭建第 3.3 节。
• Git 没有：看环境搭建第 3.1 节。
• DuckDB 没有：python -m pip install duckdb，慢就加清华镜像。

如果 python 弹出应用商店，先在 Windows“应用执行别名”里关掉 python.exe 和 python3.exe。 VS Code 不是必需，但建议用它打开项目根目录，终端和文件树都在一个窗口里。

3. 建项目目录

先确认当前目录，不要在建错地方：

pwd
ls

应该能看到 data、scripts、project。如果看不到，先 cd 到项目根目录。

建立项目要用的目录：

mkdir -p data/raw/olist
mkdir -p project/ads
mkdir -p output

目录职责：

data/raw/olist/      8 个原始 CSV，只读，不提交 Git
data/metrics.json    数据体检生成的标准答案
project/             实验室库、参考库、分层 SQL
project/ads/         ADS 导出的 CSV
output/              临时分析结果，不提交

4. 下载并校验数据

数据集已经打包好，不需要 Kaggle 账号：

• 下载 Olist 8 表数据集（zip，27.1 MB）
• 下载清单与校验值：olist-brazilian-ecommerce.json

也可以命令行下载：

python scripts/fetch_olist.py

两种方式得到同一批文件。下载后解压，把 8 个 CSV 直接放到 data/raw/olist/，文件名不要改：

data/raw/olist/
├── olist_orders_dataset.csv
├── olist_order_items_dataset.csv
├── olist_order_payments_dataset.csv
├── olist_customers_dataset.csv
├── olist_products_dataset.csv
├── olist_sellers_dataset.csv
├── olist_order_reviews_dataset.csv
└── product_category_name_translation.csv

检查文件数和总大小：

ls data/raw/olist | wc -l        # 应为 8
du -sh data/raw/olist            # 约 61 MB

然后跑体检脚本：

python scripts/check_data.py

关键输出应包含：

orders                    99,441 行
order_items              112,650 行
reviews.review_id 重复       : 814
有效订单                     : 98,207
GMV（含运费）                : 15,740,216.93
客单价 AOV                   : 160.29

数字对不上时先别往下做：优先检查是不是少了解压、文件名被改、CSV 放多了一层目录，或者下载不完整。 data/metrics.json 是后续所有对账的基线，体检成功后不要随手改它。

5. 建实验室库，跑第一条查询

项目有两条通道，从第一天就分清楚：

先创建空实验室库：

python project/run_sql.py -c "SELECT 1 AS ok"

第一次运行会生成 project/warehouse_lab.duckdb。库是空的，这是正常的。

直接用 DuckDB 查原始 CSV，确认数据真的能读：

python - <<'PY'
import duckdb

con = duckdb.connect()
con.sql("""
    SELECT COUNT(*) AS order_cnt,
           COUNT(DISTINCT order_status) AS status_cnt
    FROM 'data/raw/olist/olist_orders_dataset.csv'
""").show()
PY

应输出 order_cnt = 99441、status_cnt = 8。

再看一下按状态分布，确认你知道哪些订单算有效：

python - <<'PY'
import duckdb

con = duckdb.connect()
con.sql("""
    SELECT order_status, COUNT(*) AS cnt
    FROM 'data/raw/olist/olist_orders_dataset.csv'
    GROUP BY 1
    ORDER BY 2 DESC
""").show()
PY

这一步只验证“数据能读、SQL 能跑”。还不建 ODS 表，也不碰四层。ODS 从第 02 章开始建。

6. 初始化 Git，别把数据提交进去

在项目根目录检查是否已经是 Git 仓库：

git status

如果提示 not a git repository，初始化并建忽略规则：

git init
printf "data/raw/\nproject/warehouse_lab.duckdb*\nproject/warehouse.duckdb*\nproject/ads/*.csv\noutput/\n.venv/\n__pycache__/\n" > .gitignore

验证 CSV 被忽略：

git check-ignore -v data/raw/olist/olist_orders_dataset.csv

能看到 .gitignore 的匹配行才算成功。然后完成第一次提交：

git add .gitignore
git add scripts project 教程 2>/dev/null || true
git commit -m "chore: 初始化数仓项目与数据校验"
git log --oneline

不要把 data/raw/ 提交到 Git。55 万行 CSV 会让仓库变得很大，而且数据可以用 fetch_olist.py 重建。 如果之前误提交过，先 git rm -r --cached data/raw，再提交一次。

7. 项目约定：每建一张表先校验

后面 02–05 章都按同一个循环推进：

写 SQL → 执行 → 查行数/金额 → 对上基线 → 再写下一张

三个必须记住的数字：

每建完一张表，至少跑一次：

python project/run_sql.py -c "SELECT COUNT(*) FROM 你的表名"

数字不对时先回看上一层的输入，不要直接把错误的表接到下一层。

8. 常见卡点

9. 本章验收

• python --version、git --version 和 DuckDB 导入都正常。
• data/raw/olist/ 下正好 8 个 CSV，文件名未改。
• python scripts/check_data.py 显示 8 张表 / 550,759 行。
• 已生成 project/warehouse_lab.duckdb，并能执行 SELECT 1。
• 用 DuckDB 查询原始 CSV，得到 99,441 个订单、8 种状态。
• Git 仓库已初始化，CSV 被 .gitignore 忽略，完成第一次提交。
• 能说出实验室库和参考库的区别，以及 98,207 / 112,101 / 98,199 各是什么。

下一章：01 项目设计与架构。