# 项目导览

> `poyee-data-warehouse` 数据仓库工程的模块划分、执行时序与配置管理；面向团队新人 / 外部协作者的入口文档。

**项目状态**：重构中，目前采用**原地渐进式重构**模式。

## 1. 目录结构（更新中）

```
poyee-data-warehouse/              # 项目根目录（仓库名 = 部署名）
├── bin/                           # 启动脚本层：Shell + Python 入口
│   ├── common/                    #   公共 Shell 函数与初始化
│   ├── spark-sql-starter.py
│   ├── datax-single-job-starter.sh
│   ├── datax-single-job-starter.py
│   ├── datax-multiple-job-starter.sh
│   ├── datax-multiple-job-starter.py
│   ├── datax-multiple-hive-job-starter.sh
│   ├── datax-multiple-hive-job-starter.py
│   ├── datax-job-config-generator.py
│   └── datax-gc-generator.py
├── jobs/                          # 业务代码层，定时调度执行
│   ├── raw/                       #   原始数据采集（DataX ini 或 CSV 导入任务定义）
│   ├── ods/                       #   贴源层计算 SQL
│   ├── dim/                       #   维度层计算 SQL
│   ├── dwd/                       #   明细层计算 SQL
│   ├── dws/                       #   汇总层计算 SQL
│   ├── tdm/                       #   主题域模型层计算 SQL
│   ├── ads/                       #   应用层计算 SQL + 导出 ini
│   └── archive/                   #   已弃用脚本归档
├── manual/                        # 一次性脚本（禁止接入定时调度）
│   ├── ddl/                       #   所有 DDL（初始 CREATE + 后续 ALTER）
│   ├── backfill/                  #   历史数据回刷
│   ├── fix/                       #   线上脏数据订正（必须带工单号）
│   ├── adhoc/                     #   临时取数 / 排查
│   ├── imports/{yyyymmdd}/        #   一次性入仓，按执行日期归档
│   └── exports/{yyyymmdd}/        #   一次性出仓，按执行日期归档
├── dw_base/                       # 通用库层
│   ├── __init__.py                #   全局初始化（环境检测、用户/权限判断、颜色常量）
│   ├── common/                    #   常量、容器
│   ├── spark/                     #   SparkSQL 相关
│   ├── datax/                     #   DataX 相关
│   ├── udf/                       #   UDF 库
│   │   ├── common/                #     通用 UDF
│   │   └── business/              #     业务专用 UDF
│   ├── utils/                     #   通用工具（参数解析、日期、文件、日志、SQL 解析等）
│   ├── io/                        #   （占位）I/O 边界：跨进程读写
│   │   ├── db/
│   │   ├── file/
│   │   └── hdfs/
│   ├── ops/                       #   （占位）仓内数据运维（小文件合并、分区清理）
│   ├── dq/                        #   （占位）数据质量检查
│   ├── pm/                        #   （占位）项目管理工具集成（TAPD / Jira API）
│   └── wiki/                      #   （占位）外部文档同步（Docmost → kb/inbox）
├── kb/                            # 知识库：项目文档
├── conf/                          # 配置层（非敏感配置，入库）
│   ├── env.sh                     #   环境变量 / 路径（bash + Python 单源）
│   ├── spark-defaults.conf
│   ├── spark-tuning.conf
│   ├── templates/                 #   开发样板（见 30-开发规范.md §7）
│   │   ├── datax/
│   │   │   ├── datasource/
│   │   │   └── sync/
│   │   └── spark/
│   │       ├── ddl/
│   │       └── sql/
│   └── bak/                       #   老配置归档（gitignore）
│       ├── datax/
│       │   ├── config/
│       │   └── datasource/
│       └── flume/
│           └── config/
├── tests/                         # 测试
│   ├── unit/                      #   纯函数单测
│   │   └── udf/
│   ├── integration/               #   Spark / DataX 集成测试
│   └── README.md
├── publish.sh                     # 集群部署脚本
├── requirements.txt               # Python 依赖
└── README.md
```

**项目同级目录（运维维护，不入仓库）：**

```
/home/bigdata/release/
├── poyee-data-warehouse/          # 本项目部署目录
└── datasource/                    # 数据源连接配置（含账密，由运维管理，不入仓库）
    ├── postgresql/                #   文件名约定 {env}-{实例简称}.ini
    │   ├── prod-hobby.ini         #     生产 PG hobby 业务库
    │   ├── prod-hobby-ro.ini      #     同环境多实例加二次后缀（ro = 只读从库）
    │   ├── test-hobby.ini
    │   └── dev-hobby.ini
    ├── mysql/
    │   └── prod-order.ini
    ├── mongo/
    ├── hdfs/
    │   ├── prod-ha.ini            #     HA 集群
    │   └── test-single.ini        #     单 NN 集群
    ├── clickhouse/
    ├── elasticsearch/
    ├── kafka/
    ├── redis/
    └── hbase/
```

## 2. 配置管理体系

### 2.1 配置分类

| 配置类型 | 存放位置 | 是否入仓库 | 维护角色 |
|----------|---------|-----------|------|
| 数据源连接（含账密） | `../datasource/{db_type}/{env}-{实例简称}.ini` | 否 | 运维   |
| DataX 同步任务定义 | `jobs/raw/` (采集) 和 `jobs/ads/` (导出) | 是 | 开发   |
| Spark 默认参数 | `conf/spark-defaults.conf`（行为/开关）+ `conf/spark-tuning.conf`（资源/调优） | 是 | 开发   |
| Spark 单作业覆盖 | 对应 `jobs/*.sql` 文件内 `SET spark.x.y=z` | 是 | 开发   |
| 环境变量 / 路径 | `conf/env.sh`（`bin/common/init.sh` + `dw_base/utils/env_loader.py` 消费） | 是 | 开发   |
| 告警 Webhook | `dw_base/common/alerter_constants.py` | 是（待改 `conf/alerter.ini`，入库） | 开发   |

## 3. DataX 入口使用说明（待重构后完善）

## 4. Spark 入口使用说明

### 4.1 常用参数

待补充

### 4.2 Spark 参数优先级（三级覆盖已实现）

```
命令行 -sc key=value / SparkSQL(...) 显式传参   (L3，最高优先级，临时 override)
        ↓ 覆盖
SQL 文件内 SET spark.x.y=z                      (L2，单作业级别，开发写)
        ↓ 覆盖
conf/spark-defaults.conf + conf/spark-tuning.conf   (L1，全局默认，大数据负责人维护)
```

## 5. 执行链路

待补充

## 6. 基础模块

待补充

## 7. 部署架构

```
集群节点：m3(master), d1, d2, d3, d4(data nodes)
部署目录：/home/bigdata/release/poyee-data-warehouse/
部署用户：bigdata
部署方式：git pull + rsync (publish.sh → re-all 分发)
```