# 演进路线

> 框架重构已收尾，本文档承接其后续——只登记"还要做什么"。
> 重构期的决策、权衡、反悔条件已沉淀到 `93-架构决策.md`（ADR）；过程文档（原重构路线 / 进度 / 对比）已删。

## 一、目标结构约束：`dw_base/` 四模块边界

非业务代码（非 `spark/` / `udf/` / `datax/` 等明确功能域）按**边界属性**归入四个顶层模块：

| 模块 | 边界属性 | 典型内容 | 反例（不该放在此处） |
|------|---------|---------|---------------------|
| **`common/`** | 常量 / 全局上下文 / 无行为的元数据 | 颜色常量、枚举、模板路径常量、项目级单例 context | 任何"动词"型函数 —— 那是 `utils/` |
| **`utils/`** | 纯函数，无外部副作用，可纯 Python 单测 | 日期格式、字符串切分、配置解析、数据结构转换 | 读/写 DB / 文件 / HDFS —— 那是 `io/` |
| **`io/`** | 与外部系统通信的**边界** | DB connector 薄封装、CSV/JSON/Excel 读写、HDFS 文件读写 | 数据湖维护动作（合并小文件、清理分区）—— 那是 `ops/` |
| **`ops/`** | 数据湖维护动作，会改变湖里的物理状态 | 小文件合并、分区清理、统计信息刷新、存储压缩 | 一次性的业务查询脚本 —— 那走 `jobs/` 或 `manual/` |

**落地规则**：

1. **写新代码前先对号入座**：一个函数既读文件又做纯计算，按**最强副作用**归类（读文件 → `io/`，即便函数里 90% 是计算）
2. **`io/` 只做薄封装**：不把业务 schema 嵌入 `io/`，业务 schema 留在调用方
3. **`ops/` 里的函数预期被多处复用**：只被一张表调用一次的"清分区"走 `manual/adhoc/`，不进 `ops/`
4. **跨模块依赖方向**：`ops/` 可依赖 `io/` + `utils/` + `common/`；`io/` 可依赖 `utils/` + `common/`；`utils/` 只依赖 `common/`；`common/` 不依赖任何项目内模块。**禁止反向依赖**

> `io/` / `ops/` 当前仍是空骨架，按本边界规则把下方待办 2、3 的内容填实，即为四模块边界定稿。

## 二、待办清单

| # | 待办 | 落点 | 参见 |
|---|------|------|------|
| 1 | `publish.sh` 部署路径与项目名更新（发布目录 `/home/bigdata/release/poyee-data-warehouse/`） | `bin/publish.sh`（如重建） | — |
| 2 | Hive 小文件合并工具重新实现（`alter table ... concatenate` 压实，连接 / 表过滤参数化，剥业务命名） | `dw_base/ops/` | §一 |
| 3 | 分区保留工具重新实现（元表驱动 + 保留天数参数化 + 例外 dt 白名单） | `dw_base/ops/` | §一 |
| 4 | 数据质量首批 + runner（schema drift 探查 + PG/Hive 行数比对） | `dw_base/dq/` + `bin/dq-runner.py` | `93` ADR-07（表数 ≥ 5 张启动） |
| 5 | TAPD API 集成 + Claude Code hook 同步操作（hook 主动同步，非 commit→任务 ID 联动；细节待展开） | `dw_base/pm/` + hook | — |
| 6 | DWS 回算窗对齐 DWD 滚动 N=30（`jobs/dws` SQL 现为 N=2，改滚动 30 以与 DWD 口径一致） | `jobs/dws/` | `25-dws建模` §1.4 · ADR-09 |