# dw-project

基于 PySpark + DataX 的数据仓库项目，负责多源数据采集、清洗、分层加工和分发。

> 本 README 兼作**开发手册**，也是 **vibe coding 和 Review 的参考依据**。

## 技术栈

- **计算引擎**：PySpark 2.4 on YARN (CDH 6.3.2)
- **数据集成**：DataX_v202309
- **元数据管理**：Hive MetaStore（MySQL 后端）
- **存储**：HDFS (ORC)、RDS PostgreSQL --> Polar PostgreSQL、Elasticsearch
- **调度**：DolphinScheduler
- **告警**：企业微信机器人

## 目录结构

```
dw-project/
├── bin/           # 启动脚本（Shell + Python 入口）
├── jobs/          # 业务代码，按数仓分层组织
│   ├── raw/       #   原始数据采集（DataX ini）
│   ├── ods/       #   贴源层（SQL）
│   ├── dwd/       #   明细层（SQL）
│   ├── dws/       #   汇总层（SQL）
│   ├── tdm/       #   主题域模型层（SQL）
│   └── ads/       #   应用层（SQL + 导出 ini）
├── dw_base/       # 通用库（Spark 引擎、DataX 引擎、工具函数、UDF）
├── kb/            # 知识库（项目文档）
├── conf/          # 配置（非敏感项，样例 + 环境配置）
├── publish.sh     # 集群部署脚本
└── requirements.txt
```

数据源连接配置（含账密）存放在项目同级目录 `datasource/` 下，由运维维护，不纳入版本控制。

## 主要执行入口(datax部分待重构)

| 脚本 | 用途 | 示例 |
|------|------|------|
| `bin/spark-sql-starter.py` | 执行 Spark SQL | `-f jobs/customs/001india/02incr/01india_im/02dwd.sql -dt 20250101` |
| `bin/datax-multiple-hive-job-starter.sh` | Hive 批量采集（主力） | `-gcd conf/datax/config/mysql-hdfs/prod -start-date 20250101 -parallel` |
| `bin/datax-multiple-job-starter.sh` | 通用批量 DataX 同步 | `-gcd jobs/customs/001india/02incr/01india_im/ -start-date 20250101` |
| `bin/datax-single-job-starter.sh` | 单个 DataX 同步 | `-gc jobs/xxx/from_mongo.ini -start-date 20250101` |


## 数仓分层

```
PG/ES ──DataX(raw)──> RAW ──> ODS ──> DWD ──> DWS ──> TDM ──> ADS
```

## 开发环境

- 使用 PyCharm 远程 SSH 连接服务器开发调试
- Python 3.6.8，依赖见 `requirements.txt`
- 部署：`publish.sh` 通过 git pull + rsync 分发到集群各节点（暂时不使用）

## 文档索引

文件按编号前缀分组，序号越小越基础、越靠前阅读。每篇文档是其主题的**唯一权威**（SSOT），跨文档用 `§` 锚点互引、不复述。

### 0x 平台基建

| 文档 | 职责 |
|----|----|
| [00-项目导览](kb/00-项目导览.md) | **项目导览**：目录结构、配置管理、DataX / Spark 入口、执行链路、基础模块、部署架构 |
| [01-运行环境](kb/01-运行环境.md) | **基础设施**：CDH 版本矩阵、集群拓扑、开发侧约束 |
| [02-权限与账号](kb/02-权限与账号.md) | **鉴权链路**：HS2 doAs / PySpark / Ranger / LDAP；job 账号 vs 个人账号 |

### 1x 业务与接入

| 文档 | 职责 |
|----|----|
| [10-业务流程](kb/10-业务流程.md) | **业务全景**：用户 + 商家 + 售后全链路流程 |
| [11-数据资产](kb/11-数据资产.md) | **数据源清单**：业务库 / 埋点 / 爬虫 / 采购 |
| [12-同步方案](kb/12-同步方案.md) | **同步策略**：PG→Hive 存量 / 增量 / 历史归档 / CDC 阶段演进 |
| [13-埋点同步-设计](kb/13-埋点同步-设计.md) | **埋点同步设计**：合规约束、整体方案、脱敏策略、协作流程（受众：产品 / CTO） |
| [14-埋点同步-开发](kb/14-埋点同步-开发.md) | **埋点同步实现**：raw DDL、脱敏配置、历史 / 增量入仓脚本、落地 checklist |
| [15-raw接入流程](kb/15-raw接入流程.md) | **新表入仓标准 8 步**：sync 生成器 + mask 配置 + DDL 生成器 + raw/ods 建模文档协同 |

### 2x 数仓建模

| 文档 | 职责 |
|----|----|
| [20-数仓分层与建模](kb/20-数仓分层与建模.md) | **建模方法论**：分层定义、主题域、总线矩阵、维度五步法、分区与建模原则 |
| [21-时间语义](kb/21-时间语义.md) | **时间变量约定**：T 任务日锚点 + DS 变量底层 + cdt/dt/tdt/pdt 项目参数 + 各层 dt 语义 + 重跑幂等条件 |
| [22-业务库 raw / ods 建模](kb/22-业务库raw建模.md) | **raw/ods 层约定 + raw 源表字段目录**：raw 全 STRING landing、ods 类型化/脏数据边界、各源表三态裁剪决策 |
| [23-dwd建模](kb/23-dwd建模.md) | **DWD 字段建模**：业务过程拆分 + 维度退化策略 + 滚动 N=30 回算 + 各业务过程字段表 |
| [24-dim建模](kb/24-dim建模.md) | **DIM 字段建模**：ful_d 优先选型 + ful→zip 触发条件 + 跑批策略 + 脏数据清洗位置 + 各实体字段表 |
| [25-dws建模](kb/25-dws建模.md) | **DWS 字段建模**：日聚合主题宽表单一职责 + 维度退化触发条件 + 滚动 30 回算（与 DWD 对齐）+ 字段表 |
| [26-tdm建模](kb/26-tdm建模.md) | **TDM 字段建模**：EAV 7 字段不扩 + _d 日更 / _o 凝固分表 + tag_code 命名 + 16 品类 × 4 窗口消费明细 + 跨年扩张 |

### 3x 指标与标签

| 文档 | 职责 |
|----|----|
| [30-指标体系](kb/30-指标体系.md) | **指标字典**：指标 / 维度 / 度量定义与口径 |
| [31-标签体系](kb/31-标签体系.md) | **TDM 画像**：用户 / 商品 / 商家标签体系架构 |
| [32-标签字典](kb/32-标签字典.md) | **标签字典权威源**：103 标签全量（编码 / 口径 / 业务价值 / 示例）+ 编码规则 + 跨年滚动 + INTERSECT 圈选 SQL 示例（读者：运营 / 数据分析师）|

### 4x 规范与工具

| 文档 | 职责 |
|----|----|
| [40-命名规范](kb/40-命名规范.md) | **命名规则**：Hive 表 / 字段 / 词根字典 + 建表 Checklist |
| [41-开发规范](kb/41-开发规范.md) | **开发方法论**：TPAD、数据开发流程、代码/SQL/Git 规范、DDL/jobs 文件组织、manual/ 临时 SQL、样板 |
| [42-UDF手册](kb/42-UDF手册.md) | **UDF 登记表**：通用 + 业务 UDF 清单 |

### 9x 演进与决策

| 文档 | 职责 |
|----|----|
| [90-演进路线](kb/90-演进路线.md) | **后续演进**：四模块边界 + ops/dq/publish/TAPD 待办 |
| [93-架构决策](kb/93-架构决策.md) | **ADR 沉淀**：重构与建模的关键决策、权衡、反悔条件 |

## 阅读建议

**新成员上手路径：**
1. [00-项目导览](kb/00-项目导览.md) — 了解模块全貌
2. [01-运行环境](kb/01-运行环境.md) — 了解基础设施
3. [20-数仓分层与建模](kb/20-数仓分层与建模.md) — 了解建模方法论
4. [40-命名规范](kb/40-命名规范.md) — 熟悉命名规则
5. [41-开发规范](kb/41-开发规范.md) — 熟悉开发流程