# 重构进度

> 本文档追踪 `poyee-data-warehouse` 重构任务的执行状态。每次完成一项，在对应 checkbox 打勾并写入完成日期。
> 与 `90-重构路线.md` 配套使用：90 说"为什么改、怎么改"，92 说"改到哪一步了"。

## 总览

| 阶段 | 状态 | 开始日期 | 完成日期 |
|------|------|---------|---------|
| 阶段 0：知识库梳理 | ✅ 已完成 | —  | 2026-04-14 |
| 阶段 1：P0 骨架重命名 | ⬜ 未开始 | — | — |
| 阶段 2：P1 硬编码外置 | ⬜ 未开始 | — | — |
| 阶段 3：业务 SQL 从零开发 | ⬜ 未开始 | — | — |
| 阶段 4：测试体系 + 废弃代码清理 | ⬜ 未开始 | — | — |
| 阶段 5：老项目残留删除 | ⬜ 未开始 | — | — |

当前所处阶段：**阶段 0 完成，阶段 1 待启动**。

---

## 阶段 0：知识库梳理 ✅

- [x] 项目架构文档 `00-项目架构.md`
- [x] 运行环境 `01-运行环境.md`
- [x] 权限与账号 `02-权限与账号.md`
- [x] 业务流程 `10-业务流程.md`
- [x] 数据资产 `11-数据资产.md`
- [x] 数仓分层与建模 `20-数仓分层与建模.md`
- [x] 命名规范 `21-命名规范.md`
- [x] 指标体系 `22-指标体系.md`
- [x] 标签体系 `23-标签体系.md`
- [x] 开发规范 `30-开发规范.md`
- [x] 重构路线 `90-重构路线.md`
- [x] 项目根 `CLAUDE.md` 指向 kb

## 阶段 1：P0 骨架重命名

**目标**：让新项目结构立起来，老项目代码可以正常运行不受影响。

- [x] `tendata/` 目录改名为 `dw_base/`（2026-04-15）
- [x] 全局替换 `from tendata` / `import tendata` → `from dw_base` / `import dw_base`（2026-04-15，102 个文件）
- [x] 全局替换 SQL 中的 `ADD FILE tendata/...` → `ADD FILE dw_base/...`（2026-04-15）
- [x] 全局替换 `zip -qr tendata.zip tendata` → `zip -qr dw_base.zip dw_base`（2026-04-15，spark_sql.py f-string 形式已手工修正）
- [x] 全局替换 `addPyFile('tendata.zip')` → `addPyFile('dw_base.zip')`（2026-04-15，publish.sh 同步更新）
- [ ] 全局替换路径正则 `re.sub(r"tendata-warehouse.*", ...)` → 使用新项目名（绑定仓库改名，~40 处待处理：dw_base/scheduler/*、dw_base/utils/*、bin/doris-*-starter.py、bin/hive-exec.sh）
- [x] 排查 `tendata_corp` 等数据库名/表名引用，**确认不要误替换**（2026-04-15，已确认保留：`tendata_corp`、`tendata_bigdata256!`、`ent_tendata_interface`、`api.tendata.cn`）
- [x] 新建 `jobs/` 目录 + `jobs/{raw,ods,dim,dwd,dws,tdm,ads}/` 子目录（2026-04-15，已放 `.gitkeep`，`dim/` 为顶层独立分层）
- [x] 新建 `manual/` 目录 + 5 个子目录（`ddl/`、`backfill/`、`fix/`、`adhoc/`、`archive/`）（2026-04-15，已放 `.gitkeep`；`manual/ddl/` 是所有 DDL 的唯一来源）
- [ ] 项目仓库改名 `tendata-warehouse-release` → `poyee-data-warehouse`（**同步改名** `.idea/tendata-warehouse-release.iml` → `.idea/poyee-data-warehouse.iml` 并更新 `.idea/modules.xml` 引用）
- [ ] 更新 `publish.sh` 中的部署路径与项目名
- [ ] 实现 `bin/csv-to-hdfs-starter.py`：本地 CSV → gzip（可选，大文件才压缩）→ `hdfs dfs -put` 到暂存区 → 调用 `SparkSQL` 执行 `jobs/raw/{域}/{表}.sql`（含 `USING csv` 临时视图 + `INSERT OVERWRITE`）→ 清理暂存。任务定义采用 SQL 格式（参见 `00-项目架构.md` §9.3 模板）
- [ ] 验证：在测试集群跑一次 `bin/spark-sql-starter.py` 样例，import 和 Spark 环境初始化能过
- [ ] 验证：在测试集群跑一次 `bin/datax-single-job-starter.sh` 样例，ini→json 生成能过
- [ ] 验证：`bin/csv-to-hdfs-starter.py` 用一个样例 CSV 跑通 raw 层入仓

**完成判定**：老项目 launch-pad 下的某个样例作业，在改名后的 `dw_base/` 基础上能跑通（import 和运行不报错）。

## 阶段 2：P1 硬编码外置

**目标**：消除对老环境（`alvis` 用户、`/home/alvis/release` 路径、硬编码的 worker 列表）的代码耦合。

- [ ] 新建项目根 `.gitignore`（清单与注意事项见 `90-重构路线.md` §2.4）**— 必须先于 `conf/alerter.conf` 落地，避免敏感文件误入第一次提交**
- [ ] 建立 `conf/env.sh`（Shell 环境变量）
- [ ] 建立 `conf/env.py` 或 Python 读 `env.sh` 的桥接
- [ ] 建立 `conf/workers.conf`（DataX Worker 列表 + 权重）
- [ ] 建立 `conf/alerter.conf`（钉钉/企微 Webhook，gitignore）
- [ ] `dw_base/__init__.py` 瘦身（拆分初始化逻辑，见 `90-重构路线.md` §3）**— 必须先做，下面 spark-defaults 依赖瘦身后的 `PROJECT_ROOT_PATH`**
- [ ] 建立 `conf/spark-defaults.yaml`（Spark 全局默认参数，见 `90-重构路线.md` §2.3）
- [ ] 改造 `dw_base/spark/spark_sql.py`：构造函数 fall back 到 yaml；实现 L1(yaml) < L2(SQL 内 SET，仅 `spark.sql.*` 系生效) < L3(命令行 -sc / 构造函数传参) 三级覆盖
- [ ] 验证：同一条 SQL 在无 SET、有 SET、命令行 -sc 三种场景下 `spark.conf.get(...)` 返回值符合优先级预期
- [ ] 验证：`SET spark.executor.memory=Xg` 不会影响已启动 executor（文档里说清楚这条限制）
- [ ] `RELEASE_USER="alvis"` → `RELEASE_USER="bigdata"` 并迁入 `conf/env.sh`
- [ ] `RELEASE_ROOT_DIR="/home/alvis/release"` → `/home/bigdata/release` 并迁入 `conf/env.sh`
- [ ] `DATAX_WORKERS=(m3 d1 d2 d3 d4)` 迁入 `conf/workers.conf`
- [ ] `LOG_ROOT_DIR="/opt/data/log"` 迁入 `conf/env.sh`
- [ ] **删除"按 whoami 分流日志路径"的分支逻辑**（见 `90-重构路线.md` §7.2.1）
- [ ] 钉钉 access_token 从代码移入 `conf/alerter.conf`
- [ ] 企微 Webhook Key 从代码移入 `conf/alerter.conf`

## 阶段 3：业务 SQL 从零开发

**目标**：按新分层架构填充 `jobs/` 下的真实业务 SQL，与老 `launch-pad/` 零关联。

- [ ] 梳理首批待入仓业务表（按 `11-数据资产.md`）
- [ ] `jobs/raw/` 首批 DataX ini（按业务域分目录）
- [ ] `jobs/ods/` 首批贴源 SQL
- [ ] `jobs/dwd/` 首批明细 SQL
- [ ] `jobs/dws/` 首批汇总 SQL
- [ ] `jobs/tdm/` 首批主题模型 SQL
- [ ] `jobs/ads/` 首批应用层 SQL + 导出 ini
- [ ] 在 DolphinScheduler 中配置工作流，贯通新链路

## 阶段 4：测试体系 + 废弃代码清理

- [ ] 建立 `tests/` 目录骨架（见 `90-重构路线.md` §6）
- [ ] UDF 单测首批
- [ ] DataX 配置生成单测
- [ ] `__contains__` → `in` 全局替换
- [ ] 删除废弃空模块和注释代码
- [x] 精简 `requirements.txt`（2026-04-15 提前完成：48 行 → 10 个强依赖，老清单备份到 `requirements.txt.bak` 并逐行打标）

## 阶段 5：老项目残留删除

**前置条件**：阶段 3 的业务 SQL 在生产稳定运行至少一个完整周期，且 DS 工作流已完全切换到 `jobs/`。

- [ ] 确认 DS 工作流已无对 `launch-pad/` 的引用
- [ ] 删除 `launch-pad/` 整个目录
- [ ] 删除其他已确认废弃的老文件

---

## 变更记录

| 日期 | 变更 | 操作人 |
|------|------|--------|
| 2026-04-14 | 初始化进度文档，阶段 0 知识库梳理完成 | — |
| 2026-04-15 | `90-重构建议.md` 更名 `90-重构路线.md`；新增 `his` 快照 + `dim` 顶层分层；`manual/ddl/` 作为 DDL 唯一来源（migration 模式）；精简 `requirements.txt`（提前完成阶段 4 一项）；新增 Spark 配置三级覆盖路线（L1 `conf/spark-defaults.yaml` / L2 SQL `SET` / L3 命令行 `-sc`，阶段 2 任务） | — |
| 2026-04-15 | 阶段 1 模块重命名：`tendata/` → `dw_base/`（目录 + 102 个文件的 import / SQL `ADD FILE` / `zip` 打包 / `addPyFile` / `publish.sh`）；跳过项：`tendata-warehouse` 正则（待仓库改名）、`tendata_corp` 等业务库名、`ent_tendata_interface` topic、`api.tendata.cn` URL | — |
| 2026-04-15 | 阶段 1 目录骨架：新建 `jobs/{raw,ods,dim,dwd,dws,tdm,ads}/` 与 `manual/{ddl,backfill,fix,adhoc,archive}/`，均放 `.gitkeep` 占位 | — |
| 2026-04-15 | `sql_style.xml` 从项目根移入 `kb/`，`30-开发规范.md` §4.2 补 IDE 格式化导入说明、关键风格表与"不对齐 AS"理由 | — |
| 2026-04-15 | 新增 `.gitignore` 计划（`90-重构路线.md` §2.4 + 阶段 2 checklist），含 `.idea/` / `.claude/` 部分 ignore 策略、`dw_base.zip` 构建产物、`conf/alerter.conf` 敏感项；阶段 1 仓库改名 checklist 追记 `.iml` 同步改名 | — |
| 2026-04-18 | `sql_style.xml` 从 `kb/` 移入 `conf/`（IDE 配置不算文档）；同步更新 `kb/README.md` 索引、`kb/30-开发规范.md` §4.2.1 路径引用、移除 `kb/90-重构路线.md` §5.1 对应待办行 | — |
| 2026-04-18 | kb 文档整理：`zhu_tianyu` → `tianyu.chu`（`00-项目架构.md` 2 处负责人注释）；`kb/inbox/` 4 份草稿整合完毕 —— `标签服务演进路线.md` 与 `23-标签体系.md §6` 100% 重复直接删除；`dwd明细粒度设计原则.md` 并入 `20-数仓分层与建模.md` §5.5；`hive数据类型映射.md` 并入 `20-数仓分层与建模.md` §8.4（ES→Hive 占位待补）；`业务库同步方案.md` 独立成文为 `kb/12-同步方案.md` 并入 README 索引 | — |
| 2026-04-18 | `02-权限与账号.md §1` 补齐 PySpark 鉴权路线（链路 B）：Unix 账号身份 + Ranger UserSync 同时同步 LDAP / Unix group；HS2 doAs 仅链路 A 生效；补漏编号 1 并新增"身份（Who）"条目 | — |
| 2026-04-18 | 架构框图重排：`01-运行环境.md §1` 大数据平台全景、`20-数仓分层与建模.md §2` 分层 × 维度侧柱、`00-项目架构.md §5` 分层架构图 —— 统一"单层单行 + 右侧 DIM 侧柱"样式，按"中文字符宽 2 / ASCII 宽 1"严格对齐；同步修复三文档数据流 ASCII 尾巴的 orphan `│` 和空行 | — |