# 架构决策

> 重构完成后沉淀的关键架构决策（ADR），给自己看的备忘。

## 说明

- 本文档是**重构完成态**的沉淀：`90-重构路线.md` / `91-重构备忘.md` / `92-重构进度.md` 三份过程文档会在重构收尾时删除，关键决策、权衡、反悔条件压到这里留档。
- 当前仍在重构中，本文档先留骨架，内容待重构收尾时填入。
- 单条 ADR 格式按业界主流（Michael Nygard 版精简）：**背景 / 决策 / 后果 / 候选方案 / 反悔条件** 五段；不套公司标准模板的多余字段。

## 模板

> 新增一条决策时，复制以下模板到 §2 列表内。编号连续，不复用已弃用编号。

```markdown
### ADR-NN 决策标题

- **状态**：已采纳 / 被 ADR-MM 取代 / 已弃用
- **背景**：当时面对的问题、约束、触发决策的场景。
- **决策**：最终选了什么方案，一句话。
- **后果**：带来的好处、新增的代价、影响到的模块。
- **候选方案**：考察过但否决的方案，以及否决理由。
- **反悔条件**：什么条件下会重新评估或反悔。
```

## 决策清单

### ADR-01 DataX 入口不做日期展开，按天补数归 DolphinScheduler

- **状态**：草案（2026-04-23 讨论成型，待正式拍板转"已采纳"）
- **背景**：老 `spark-sql-starter` 的 `get_date_range` 支持 `20260401-20260410` 范围格式自动展开；DataX 入口从未用过。本项目调度用 DolphinScheduler，DS 原生支持**业务日期补数**（时间区间选定后，按调度周期逐日实例化 task）。用户老 DS 配置即 `-start-date=${dt} -stop-date=${cdt}` 单日传参。
- **决策**：DataX 入口只接受单日语义（`start_date` / `stop_date` 对应一个 dt 分区）；按天展开 / 批量补数 / 回溯全部交由 DS 工作流承担。
- **后果**：
  - 正面：DataX 层职责单一；补数、回溯、失败重跑在 DS 层统一可视化 / 可审计；DataX 不维护日期展开状态（哪天已做、哪天失败、重试）
  - 负面：不走 DS 的一次性手工补 N 天需要外部 bash 循环或 `workspace/` 下临时 dispatcher
- **候选方案**：DataX 入口层实现"日期范围自动展开 + 多 json 分发多 worker"——否决，理由是**重复 DS 职责** + 引入状态管理复杂度
- **反悔条件**：项目从 DS 迁走到无补数功能的调度系统；或出现"必须在 DataX 层展开"的硬场景

### ADR-02 分布式分发归 DolphinScheduler worker group，DataX 不重复随机

- **状态**：草案（2026-04-23 讨论成型，待正式拍板转"已采纳"）
- **背景**：DataX 老入口 `single-job-starter.sh` 内置 `-random` + `workers.ini` 权重加权随机选 worker + ssh 分发。DS 自身亦有 **worker group** 机制（group 绑定机器列表、task 落到 group 内一台 worker）。两层叠加：DS 选 node01 → node01 上 DataX 再 random 到 node03。【查证 kb/91 §4.4】：用户老 DS 配置不传 `-random`，说明 DS 层已完成分发，DataX 只在本机跑——两层分发在实际运营中就没被"同时启用"过
- **决策**：DataX 入口不做 worker 分发；分布式执行在 task 粒度靠 DS worker group 承担。DataX 入口的 `select_worker` 等同"返回 `current_host`"，ssh 分支可删，`workers.ini` 可移除
- **后果**：
  - 正面：消除两层独立随机叠加打乱 DS 负载均衡；DataX 链路大幅简化（`worker.py` / ssh 远端执行 / `workers.ini` 可裁）；维护成本下降
  - 负面：单 DS 任务节点内部的批量（多 ini + `-parallel`）场景无法在 DataX 层散到多 worker，要分布式必须在 DS 层拆成多 task
- **候选方案**：保留 DataX 两层分发——否决，"两层独立随机"破坏 DS worker group 语义
- **反悔条件**：DS 换成无 worker group 支持的调度器；或单 task 内批量规模大到 DS 拆分成本过高