92-重构进度.md 67 KB
重构进度
本文档追踪
poyee-data-warehouse重构任务的执行状态。每次完成一项，在对应 checkbox 打勾并写入完成日期。 与90-重构路线.md配套使用：90 说"为什么改、怎么改"，92 说"改到哪一步了"。
总览
推进组织方式：2026-04-20 起 kb/90-重构路线.md 改为聚簇 + DAG 视图（A 配置外移 / B dw_base 重组 / C bin 收口 / D 基础设施 / E 业务 SQL / F 老代码删除），阶段号保留作为历史分期，实际推进按聚簇；见 kb/90 §〇 + §八。本 checklist 下方的阶段分节仍保留，便于按阶段对账。
| 阶段 | 状态 | 开始日期 | 完成日期 |
|---|---|---|---|
| 阶段 0：知识库梳理 | ✅ 已完成 | — | 2026-04-14 |
| 阶段 1：P0 骨架重命名 | 🟡 推进中 | 2026-04-15 | — |
| 阶段 2：P1 硬编码外置 | 🟡 部分提前完成（B4 骨架 / bin/publish.sh / excel_to_hive 删） | 2026-04-20 | — |
| 阶段 4：测试体系 + 废弃代码清理 | 🟡 tests 骨架已建 / requirements 精简已完成 | 2026-04-15 | — |
| 阶段 5：老项目残留删除 | ⬜ 未开始 | — | — |
原"阶段 3：业务 SQL 从零开发"不属于重构 scope（2026-04-21 移除，详见变更记录），已从本 checklist 删除。业务 SQL 开发走独立路径，不在本进度追踪内；阶段 5 的前置条件相应调整为"新业务 SQL 生产稳定运行"。
当前所处阶段：主线阶段 1（P0 骨架）推进中；阶段 2 / 4 部分先导项随聚簇 B4 提前完成。
阶段 0：知识库梳理 ✅
- 项目导览文档
00-项目导览.md - 运行环境
01-运行环境.md - 权限与账号
02-权限与账号.md - 业务流程
10-业务流程.md - 数据资产
11-数据资产.md - 数仓分层与建模
20-数仓分层与建模.md - 命名规范
21-命名规范.md - 指标体系
22-指标体系.md - 标签体系
23-标签体系.md - 开发规范
30-开发规范.md - 重构路线
90-重构路线.md - 项目根
CLAUDE.md指向 kb
阶段 1：P0 骨架重命名
目标：让新项目结构立起来，老项目代码可以正常运行不受影响。
-
tendata/目录改名为dw_base/（2026-04-15） - 全局替换
from tendata/import tendata→from dw_base/import dw_base（2026-04-15，102 个文件） - 全局替换 SQL 中的
ADD FILE tendata/...→ADD FILE dw_base/...（2026-04-15） - 全局替换
zip -qr tendata.zip tendata→zip -qr dw_base.zip dw_base（2026-04-15，spark_sql.py f-string 形式已手工修正） - 全局替换
addPyFile('tendata.zip')→addPyFile('dw_base.zip')（2026-04-15，publish.sh 同步更新） - 全局替换路径正则
re.sub(r"tendata-warehouse.*", ...)→poyee-data-warehouse（2026-04-22，dw_base/utils/file_utils.py:9+dw_base/utils/hdfs_merge_small_file.py:7两处字面量） - 排查
tendata_corp等数据库名/表名引用，确认不要误替换（2026-04-15，已确认保留：tendata_corp、tendata_bigdata256!、ent_tendata_interface、api.tendata.cn） - 新建
jobs/目录 +jobs/{raw,ods,dim,dwd,dws,tdm,ads}/子目录（2026-04-15，已放.gitkeep，dim/为顶层独立分层） - 新建
manual/目录 + 5 个子目录（ddl/、backfill/、fix/、adhoc/、archive/）（2026-04-15，已放.gitkeep；manual/ddl/是所有 DDL 的唯一来源） - 项目仓库改名
tendata-warehouse-release→poyee-data-warehouse（2026-04-22，根目录已由用户手动改名；.idea/*.iml与modules.xml不入库，残留不影响运行，不处理） - 更新
publish.sh中的部署路径与项目名 - 实现
bin/csv-to-hdfs-starter.py：本地 CSV → gzip（可选，大文件才压缩）→hdfs dfs -put到暂存区 → 调用SparkSQL执行jobs/raw/{域}/{表}.sql（含USING csv临时视图 +INSERT OVERWRITE）→ 清理暂存。任务定义采用 SQL 格式（参见30-开发规范.md§4.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/env.sh（Shell + Python 环境变量单源，5 vars：RELEASE_USER / RELEASE_ROOT_DIR / PYTHON3_PATH / DATAX_HOME / LOG_ROOT_DIR） - Python 侧由
dw_base/utils/env_loader.py通过 bash 子进程解析注入os.environ（单源，不做双份配置） - 建立
conf/workers.ini（DataX Worker 列表 + 权重 map，整体迁出bin/common/init.sh:13-28；2026-04-23 落地，新集群 hostname 适配 cdhmaster02 / cdhnode01-03） - 建立
conf/alerter.ini（企微 Webhook，入库；格式见90-重构路线.md§2.1） -
dw_base/__init__.py瘦身（2026-04-21，修剪式，不拆core/；见90-重构路线.md§三 已完成态） - 建立
conf/spark-defaults.conf（底层行为/开关类 11 条，少改）+conf/spark-tuning.conf（资源/并行度 10 条，业务常改）（2026-04-21，Spark 原生格式；两文件拆分，见90-重构路线.md§2.3） - 改造
dw_base/spark/spark_sql.py：构造函数 10 个 tuning 默认值 →Nonesentinel；新增_load_spark_conf_file()；__init_spark_session按 L1(两 conf 叠加) < L2(SQL SET) < L3(构造参数非 None +extra_spark_config) 三级覆盖（2026-04-21） - 验证：同一条 SQL 在无 SET、有 SET、命令行 -sc 三种场景下
spark.conf.get(...)返回值符合优先级预期 -
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)+ 权重 map 迁入conf/workers.ini - 删除
whoami == RELEASE_USER分流，LOG_ROOT_DIR单值${HOME}/log放入conf/env.sh（见90-重构路线.md§7.2.1） - 日志路径统一模板
${LOG_ROOT_DIR}/{module}/{dt}/{file}.log（3 层） - 实现
log_path(module, dt, file)工具函数（Python / Shell 各一份，单一来源） - 企微 Webhook Key 从
alerter_constants.py移入conf/alerter.ini（钉钉已于 2026-04-20 全部删除，不再迁移） - DataX 入口收口为两条命令（暂称
datax-import/datax-export，命名待确认；见90-重构路线.md§2.6） - 导入命令实现分区管理（
-skip-exist/-force-overwrite/-skip-partitions） - 导出命令实现源 HDFS 路径探测（
-src-check/-skip-missing） -
bin/datax-gc-generator.py从零重写：定位为参考模板生成器（from=pg to=hdfs，输出到开发者本地workspace/{yyyymmdd}/{name}.ini，该目录被.gitignore排除、不入仓；开发者裁剪后把成品提交到jobs/raw/{domain}/），不再生成 DDL（见90-重构路线.md§2.7） -
.gitignore增加workspace/行（见90-重构路线.md§2.4 清单） - 废弃并删除
mysql_utils/MySQLDataSource/MySQLReader.generate_hive_ddl*/convert_mysql_column_types（见 §2.7 拆除清单） - HDFS HA 自检（前置决策）：2026-04-18 新 CDH 环境实测：
HADOOP_CONF_DIR未设 +/opt/datax无预置 hdfs-site.xml；手动export HADOOP_CONF_DIR=/etc/hadoop/conf后跑 DataX 仍UnknownHostException: nameservice1。结论：HADOOP_CONF_DIR对 DataX 无效（datax.py不把 conf 目录入 classpath），锁定走 Path B - 改造
HDFSDataSource：覆写get_datasource_dict()把[hadoop_config]整节作为 dict 塞进ds_dict['hadoopConfig']（2026-04-18） - 清理
dw_base/__init__.py:16死代码os.environ['HADOOP_CONF_DIR']（2026-04-18，实测对 DataX JVM 无影响） - HDFS 数据源 ini 新建：按新 schema 运维补齐
datasource/hdfs/{env}-{实例简称}.ini（HA 集群带[hadoop_config]；单 NN 只写[base] defaultFS） - HA 回归测试：真实 HA 集群 + 单 NN 集群 + 主备切换三场景
- DataX 速率配置外移：
conf/datax-speed.ini定义分时速率档；dw_base/datax/job_config_generator.py:60-67硬编码替换为读 conf（见90-重构路线.md§2.9） - 新建
manual/imports/+manual/exports/目录（按日期{yyyymmdd}/组织一次性任务）
阶段 4：测试体系 + 废弃代码清理
- 建立
tests/目录骨架（见90-重构路线.md§6） - UDF 单测首批
- DataX 配置生成单测
-
__contains__→in全局替换 - 删除废弃空模块和注释代码
- 重新实现 Hive HDFS 小文件合并工具：原
dw_base/utils/hive_file_merge.py（2026-04-20 随老业务批清理一并删除）提供alter table ... partition (...) concatenate压实能力，但硬编码了老 HiveServer 连接 /cts_*_ex/_im表名规则 /mirror_country过滤。新版需通用化：HiveServer 连接从conf/读取、表过滤参数化，剥离业务命名假设 - 重写告警模块：老钉钉告警文件（
dingtalk_*/ent_interface_dingtalk*/country_count_dingtalk/spark_parse_json_to_hive里的dingtalk()/bin/dingtalk-work-alert.sh）已于 2026-04-20 全部删除；新项目不再使用钉钉，Webhook Key 走conf/alerter.ini（见90-重构路线.md §2.1） - 重新实现分区保留工具：老
dw_base/scheduler/drop_partitions.py+drop_daily_full_snapshot_tbls.py（2026-04-20 删除）提供"按表清理超期分区，保留最近 N 天 + 例外 dt"能力。前者硬编码海关cts_{mgdb}_{catalog}表名 +mg_count_monitor元表，后者元表驱动（daily_full_snapshot_tbls存db/tbl/days）模式更通用。新版采用元表驱动 + 保留天数参数化 + 例外 dt 白名单，不绑业务表名；新目录可能不叫 scheduler（按 N 天清分区不是调度职责，更像ops/或maintenance/） - Spark / HMS 侧 Ranger Hive 策略验证（低优先级，见
90-重构路线.md§7.5） - 精简
requirements.txt（2026-04-15 提前完成：48 行 → 10 个强依赖，老清单备份到requirements.txt.bak并逐行打标）
阶段 5：老项目残留删除
前置条件：新业务 SQL（不属于本重构 scope）在生产稳定运行至少一个完整周期，且 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 │ 和空行 |
— |
| 2026-04-18 | 02-权限与账号.md §2 Mermaid 时序图补齐链路 B（PySpark → HMS + Ranger Hive Plugin → NameNode + Ranger HDFS Plugin → HDFS，身份=Unix 账号，无 doAs） |
— |
| 2026-04-18 | 反转两条决策：(a) manual/ddl/ 目录组织从"扁平存放"→ 按 {layer}/{domain}/ 分子目录；(b) jobs/{layer}/{domain}/ 下 SQL 从"一张目标表一个 .sql"→ 简单表仍单文件，多步表用 {表名}/{表名}-{NN}-{描述}.sql 子目录（99 为最终 insert），区分"可复用中间结果应升层"和"单目标加速 tmp 表"两种语义；同步更新 00-项目架构.md §9.1/§9.2/§9.5 文件命名速查表 |
— |
| 2026-04-18 | 90-重构路线.md 新增 §2.6 DataX 入口收口为 datax-import + datax-export、§2.7 datax-gc-generator 从零重写（仅 PG→HDFS，不再生成 DDL）、§2.8 HDFS defaultFS 统一 nameservice；§2.1 workers 行追记"权重 map 一起迁"；§7.2.1 反转"删除 whoami 分流"→"保留分流 + 目的地改为 {module}/{dt}/{file}.log" |
— |
| 2026-04-18 | manual/ 新增两个子目录语义：manual/imports/{yyyymmdd}/（一次性入仓）+ manual/exports/{yyyymmdd}/（一次性出仓），同步更新 00-项目架构.md §1 目录树 / §9 manual/ 用途表 / §9.5 文件命名速查 |
— |
| 2026-04-18 | 修正 90-重构路线.md §2.8 关于 HDFS nameservice 的表述：代码侧零特殊处理（dw_base/datax/datasources/hdfs_data_source.py:8,21 只把 defaultFS 当不透明字符串透传），nameservice 解析完全靠 DataX worker 节点的 Hadoop 客户端 + hdfs-site.xml；仓库内无 HADOOP_CONF_DIR export |
— |
| 2026-04-18 | 90-重构路线.md §2.7 改写 datax-gc-generator 定位为参考模板生成器（不是"一键出可用 ini"），产物落 manual/imports/{yyyymmdd}/ 供开发者按需裁剪字段 / 加 WHERE / 调分区；§2.6 datax-import / datax-export 名称标注"命名待确认" |
— |
| 2026-04-18 | 30-开发规范.md 新增 §4.4 Git 提交信息（Conventional Commits）：type 白名单（feat/fix/docs/refactor/perf/test/chore/style/build/ci/revert）、scope 约定（{层}/{域} 或模块名）、标题 ≤ 50 字符、破坏性变更 ! + BREAKING CHANGE: 正文约定 |
— |
| 2026-04-18 | 新增 workspace/ 概念：开发者本地草稿区（datax-gc-generator 输出的参考模板 / 临时 SQL 调试），被 .gitignore 排除、永不入仓。同步更新 90-重构路线.md §2.4 .gitignore 清单增加 workspace/ 行、§2.7 datax-gc-generator 输出目的地从 manual/imports/ 改为 workspace/{yyyymmdd}/{name}.ini；并明确 workspace/ vs manual/imports/ 分工 |
— |
| 2026-04-18 | 修正 §2.8：原"把 defaultFS 换 nameservice 就算支持 HA"是错的；DataX HA 必须在 json 里同时提供 defaultFS + hadoopConfig 块（否则无法把 nameservice 解析为具体 NameNode）。ini schema 升级：新增 ha_enabled + [hadoop_config] 节，key 照搬 hdfs-site.xml；HDFSDataSource 需覆写 get_datasource_dict()；reader/writer 两侧代码不用改（靠 load_data_source() 自动注入） |
— |
| 2026-04-18 | 新增 §2.9：DataX 速率控制从 job_config_generator.py:60-67 的分时硬编码（0750-1900 走 10ch×10MB、其它走 6ch×256MB）外移到 conf/datax-speed.conf，按时间段分档；默认值保持向后兼容；在 conf 头注释里补"白天避开业务高峰"的动机 |
— |
| 2026-04-18 | 排查"运维写死 nameservice"实现：全仓 grep HADOOP_OPTS / -Dfs. / 自定义 hdfs-site.xml 写入等全部零命中；现存 conf/bak/.../hdfs-*.ini 只有 defaultFS 一行。仓库零实现。 |
— |
| 2026-04-18 | 修正早先文档误述：dw_base/__init__.py:16 实际上有 os.environ['HADOOP_CONF_DIR'] = '/etc/hadoop/conf'（原 2026-04-18 changelog 早条说"仓库内无 HADOOP_CONF_DIR export"不准确） |
— |
| 2026-04-18 | §2.8 改造降级为"条件触发"（第三轮修正）：用户提供老项目真实生产 json 样例显示只写 defaultFS（无 hadoopConfig）也能跑 HA —— 说明老 worker 节点 hdfs-site.xml 配置完整，hadoopConfig 是可选覆盖而非 HA 必要条件。前两轮论断（"必须加 hadoopConfig"、"运维把 xml 写死单 NN"）都被推翻。§2.8 加"新环境 HDFS HA 自检清单"（echo $HADOOP_CONF_DIR / grep xml HA keys / hadoop fs -ls hdfs://nameservice1/），三项全过则整节改造不做；仅任何一项失败才启动 ini schema 升级 + HDFSDataSource 改造。92 阶段 2 checklist 相应改为"自检前置 + 条件触发"4 条子项 |
— |
| 2026-04-18 | §2.8 锁定 Path B（第四轮，实测决定）：新 CDH 环境三连实测（json 含/不含 hadoopConfig × HADOOP_CONF_DIR 设/不设），结论：对 DataX JVM，仅 json 的 hadoopConfig 块有效，HADOOP_CONF_DIR 无效（datax.py 不把 conf 目录入 classpath，与 hadoop 命令行不同）。老项目能纯 defaultFS 跑通最可能是老运维把 hdfs-site.xml 塞进了 DataX classpath 目录，新环境 /opt/datax 没这类预置文件。改造要点：(a) HDFSDataSource.get_datasource_dict() 吃 [hadoop_config] 整节注入 hadoopConfig；(b) 删除 dw_base/__init__.py:16 os.environ['HADOOP_CONF_DIR'] 死代码。简化 §2.8 文本：去掉 ha_enabled 开关（用 [hadoop_config] 节存在性代替）、去掉自检决策树（已决定）、去掉"运维手工改 IP"误记 |
— |
| 2026-04-20 | §7.2.1 再次反转：删除 whoami == RELEASE_USER 分流，LOG_ROOT_DIR 改为单值默认 ${HOME}/log 并保留在 conf/env.sh（外配后期可改）。理由：$HOME 天然按用户隔离（bigdata/个人用户家目录不同），代码判断是多余一层；bigdata 本身就是专属调度账号，其 $HOME 即是生产日志合法归宿，不需要系统级 /opt/data/log 那条路。同步更新 90-重构路线.md §7.2.1（核心段）+ §2.1 硬编码表行 + §2.4 env.sh 草稿 + 00-项目架构.md §6 部署段 + 92 阶段 2 checklist |
— |
| 2026-04-20 | 老业务耦合代码第二批清理（重构计划外）：在 UDF/模块独立化讨论中顺带盘点 dw_base/ 子模块，决定 16 文件批量删除：整目录删 3 个——oss/（oss2_util.py + init，新业务不需要对象存储）、scheduler/（polling_scheduler / drop_partitions / drop_daily_full_snapshot_tbls 三业务文件，前者绑死老 Mongo 轮询、后两者按 N 天清分区的能力已在阶段 4 记录重写任务）、hive/（hive_utils + hive_constants；hive_utils 中 get_hive_create_table_ddl* 零引用 + 依赖 COLUMN_NAME_COMMENT_DICT 老业务字段字典、DDL 生成器整体不重建；get_hive_database_name / get_hive_table_prefix 两个命名约定函数语义已在 kb/21-命名规范.md 有规则，不重建代码，后续 bin/datax-gc-generator.py 从零重写时按新约定实现）；utils/ 删 7 文件——data_distinct / diff_utils / excel_to_hive_utils / hive_diff_database / hive_to_excel_utils / pdt_check_table / pdt_check_table_multis，全部零外部引用 + 强业务耦合（硬编码 tendata 路径 / 老集群 IP 192.168.30.3 / 中文表名拼音转换 / 海关 cts_* 表名模式）。连带效应：bin/datax-gc-generator.py:26 import hive_utils 成破损 import，由 90-路线 §2.7 "从零重写" 任务覆盖，不单独修复。阶段 4 新增任务：重新实现分区保留工具（元表驱动 + 参数化天数，目录可能不叫 scheduler）。CLAUDE.md 规则追加："空模块直接删"原则首次执行延后（elasticsearch/flink/ml/validation/common/ 暂留，后续更细粒度规整） |
— |
| 2026-04-20 | 老业务耦合代码批量清理（重构计划外）：排查 tendata 残留时发现一批与 tendata_corp / ent_tendata_interface / DolphinScheduler / 钉钉告警强耦合的存量文件，逐项核对后批量删除 40 个文件 + 精简 1 个：老业务模块 34（dw_base/scheduler/ 下 get_oldmongo_* ×5、dingtalk_* / ent_interface_dingtalk* / country_count_dingtalk / mg_company_alias_init ×8、mg2es/ 整目录 13 文件；dw_base/ds/ 整目录 4 文件；dw_base/spark/udf/spark_read_hive_columns_cnt.py；dw_base/utils/tid_utils.py；dw_base/spark/td_spark_init.py（老同事 xunxu 所写未被调用）；bin/hive-exec.sh），级联清理 6（dw_base/spark/udf/spark_id_generate_udf.py + dw_base/spark/udf/enterprise/unique/spark_tid_match_udf.py 依赖已删 tid_utils；dw_base/utils/hive_file_merge.py + dw_base/utils/spark_parse_json_to_hive.py 依赖已删 mg2es/钉钉告警；bin/hive-exec-job-starter.py 调用已删 hive-exec.sh；bin/dingtalk-work-alert.sh），精简 1：dw_base/spark/udf/spark_mmq_udf.py 从 530 行裁到 4 个数据类型转换函数（phone/domain/website/statname 等场景相关 UDF 与 Mongo 相关逻辑全删）。同步更新：00-项目架构.md（移除 td_spark_init / DS 相关条目）、90-重构路线.md（钉钉 + 企微 Webhook 合并表述、删除 DS API 行、§5.2 依赖清理清单标记提前完成）、92-进度.md 阶段 1 第 6 行 re.sub checklist 更新残留范围（~15 处）。阶段 4 新增两项任务：(1) 重新实现 Hive HDFS 小文件合并工具（通用化连接 / 剥离 cts_*_ex/_im 表名假设）；(2) 重写告警模块（弃钉钉走 conf/alerter.ini Webhook） |
— |
| 2026-04-20 | pyspark 入 requirements.txt（反转 2026-04-15 "不写进" 决策）：实际开发流程是 PyCharm SSH 到服务器用 bigdata 用户的 Python 解释器，该解释器 site-packages 只有 findspark==2.0.1，真正的 pyspark 在 CDH $SPARK_HOME/python/ 下不被索引 → PyCharm 静态索引红线 + 本地 pytest 失败。解法：pyspark==2.4.0 入 requirements.txt（版本对齐 CDH 6.3.2 parcel 自带 Spark 2.4.0，见 requirements.txt.bak:45 + kb/01-运行环境.md:64）；运行时仍靠 findspark.init() 指向集群 $SPARK_HOME/python/，同版本双轨不冲突。同步 kb/90-重构路线.md §7.1 KEEP 行放回 pyspark + 末句机制改写 |
— |
| 2026-04-20 | UDF 提升为顶层模块（重构计划外）：dw_base/spark/udf/ → dw_base/udf/。动机：UDF 是独立能力域（后续会高频扩展、需本地单测），不应锁死在 spark/ 子树里。联动：dw_base/__init__.py:27 常量、bin/spark-sql-starter.py + bin/excel_to_hive.py 文件头 SQL 样例注释、dw_base/udf/common/spark_common_udf.py 模块 docstring、kb/00-项目架构.md（目录树新增 udf/ 行 + 模块职责表 + Mermaid 节点）、kb/23-标签体系.md §5 bitmap UDF 注册路径。bin/spark-sql-starter.py:172-173 用的是常量自动生效 |
— |
| 2026-04-20 | 修正 §7.1 pyspark 误记：前期文档把 pyspark 列进强依赖 KEEP 行 + "pyspark 2.4.0 固定" 一句，均与真实的 requirements.txt 不符。真实机制：findspark==2.0.1 运行时定位 CDH 集群已装 PySpark，版本随集群走，客户端不固定也不入 requirements.txt。kb/90 §7.1 表格 KEEP 列去 pyspark + "后续事项"末行改为 findspark 机制说明 |
— |
| 2026-04-20 | UDF 模块重组（重构计划外）：独立 dw_base/spark/udf/ 目录结构为 common/（通用 UDF，SparkSQL 入口自动 ADD FILE 注册）+ business/（业务专用 UDF，SQL 中按需 ADD FILE 加载）两类。(a) 6 份源文件（根 spark_common_udf.py 24 函数 + spark_json_array_udf.py 23 函数 + spark_mmq_udf.py 3 函数 + customs/cts_common.py + product/escape_udf.py + enterprise/spark_eng_ent_json_array_append_udf.py）通读 + 去重 + 业务耦合剥离后，合并为单文件 common/spark_common_udf.py（500 行 40 函数，分 JSON / Array / String / Numeric-Date-Hash / Cross-type-converters 5 段）。单文件方案而非按类型拆分，理由：跨类型转换函数（json2str / arr2json / str2map 等约 9 个，占 20%+）没有明确归属，强行分只会制造边界争议。(b) 清理 dw_base/spark/udf/ 下所有老业务 UDF 子目录与根级业务文件共 60 个：整目录删 contacts/ / customs/ / enterprise/ / product/ / productApplication/ / test/；根目录删 spark_eng_ent_name_clean.py / spark_india_format_phone_udf.py / solr_similar_match_udf.py / main_test.py 以及 3 份源 UDF 文件。(c) dw_base/__init__.py:27 COMMON_SPARK_UDF_FILE 常量路径由 dw_base/spark/udf/spark_common_udf.py 改为 dw_base/spark/udf/common/spark_common_udf.py（bin/spark-sql-starter.py:172-173 两处 usage 靠常量传递自动生效）。(d) 删除老 dingtalk_* / mg2es 级联清理中没赶上的 UDF 业务耦合文件在此批统一清零。business/ 目录暂为骨架，后续真正出现新业务 UDF 时按需补 |
— |
| 2026-04-20 | 删除空壳模块 ml/ / elasticsearch/ / flink/ / validation/（反转 2026-04-20 早先"暂留"记录）：4 个目录下均只有 56 字节空 __init__.py，零 import / 零内容，保留无意义；2026-04-20 UDF 模块重组 changelog 末尾"暂留"一句是误记。git rm -r 一批清零。同步 kb/90-重构路线.md §5.1 从废弃代码表中移除这 4 行并加指向本条 changelog 的尾注。dw_base/common/ 因 alerter_constants.py / config_constants.py / container.py / template_constants.py 非空保留，不在本批 |
— |
| 2026-04-20 | 删除 dw_base/database/mongodb_utils.py + kb/90 §5.1 档案化改造：(a) mongodb_utils.py 184 行真实内容仅 MongoDBHandler 薄类 19 行（吃 url/port/user/pwd 拼 URI 实例化 MongoClient），其余 165 行全是公司名→Mongo/ES 查询 + TF-IDF 关键词抽取 + 三段老集群 dds-m5e* 连接串注释。grep 零外部引用。新项目若需连 Mongo 一行 MongoClient(uri) 即可，薄包装无保留价值。(b) §5.1 原表两行实际状态：mongodb_utils.py = 本次删除；conf/datax/ 下老项目遗留 ini/datasource = 项目初始化 8d2ade5 时已整体挪入 conf/bak/datax/{config,datasource}/ 并由 .gitignore:6 conf/bak 拦截，早已完成但没画勾。(c) §5.1 改造为"待清理表（当前为空）+ 历史档案表（完成项留档）"双表结构，空壳模块 4 行 + 本次 mongodb_utils + conf/datax 挪 bak 三项入档案。尾注说明：代码里残留的 conf/datax/config/ replace 死逻辑 + conf/datax/generated 默认值属于 §2.x 路径硬编码清理（改名 conf/datax-json/），不在本节范围 |
— |
| 2026-04-20 | alerter + datax-speed 扩展名统一为 .ini + alerter 口径统一为"入库"：(a) conf/alerter.conf → conf/alerter.ini + 从 gitignore 改为入库；反转 2026-04-15 changelog（line 139）当时记的 .conf + gitignore 口径。理由：项目 conf/ 全部 ini + 代码侧 configparser 使用 10+ 次 + PyYAML 在 requirements 但零 import yaml（躺尸依赖）→ ini 是事实标准；webhook key 低敏（最多被拿去发垃圾消息，非账密级）+ 部署靠 git pull，gitignore 会让 bigdata / DolphinScheduler 拉不到配置。结构：[common] url_prefix + [channels] ba/dcp/etl/skb/realtime = <key>。(b) conf/datax-speed.conf → conf/datax-speed.ini，同一口径收敛，消除 .conf/.ini 混用。同步点：kb/00 §6 sparkconfig 表告警 Webhook 行（gitignore 列 是 → 否）、kb/90 §2.1 硬编码表 alerter 行 / §2.4 目录树 / §2.9 整节 4 处、kb/92 阶段 2 checklist 4 处（line 62 去掉"敏感文件"措辞、line 66 改为入库、line 78 钉钉条删除合并入 line 79、line 91 扩展名改）、记忆 project_templates_and_config 去掉"kb/92 一致性提醒"段（已消除）。未改动：2026-04-15 changelog line 139（历史快照保留）、2026-04-18 changelog line 153（历史快照保留）、workers.conf 扩展名 + kb/90 §2.1 里"ini 或 yaml 格式"未定的表述（不在本批范围，用户后续拍板） |
— |
| 2026-04-20 | DS 残留清理 + workers / spark-defaults 扩展名收敛：(a) DS 残留：dw_base/ds/ 目录在 f20d9c3 就随老业务批被删，但前瞻 kb 未同步 —— 本次清 kb/00-项目架构.md:42 目录树 ds/ 行 + :122 Mermaid 节点 DS_API + :169 Mermaid 边 DS_API --> DS + kb/90-重构路线.md:70-72 目标态目录树 ds/ 子树 3 行。(b) conf/workers.conf → conf/workers.ini（kb/90 §2.1 硬编码表 + §2.4 目录树 + kb/92 checklist 2 处），并把 §2.1 里"ini 或 yaml 格式"的未决表述锁死为"ini 格式"—— 与本项目 Python 读配置统一走 configparser 的约定一致（见上一条 alerter 口径）。(c) conf/spark-defaults.yaml → conf/spark-defaults.conf（Spark 原生 flat spark.x.y value 格式，非 ini）：反转中途一度采纳的"全部配置 .ini 统一"结论，理由是该文件是 $SPARK_HOME/conf/spark-defaults.conf 的克隆（运维熟悉、与 spark-submit --properties-file 原生兼容、代码侧零映射转换、无 section 前缀/key 拼接 tax）。§2.3 草案块从 [executor]/[driver]/[sql]/[default] section + configparser + spark.{section}.{key} 拼接的写法，整段改写为 flat key-value；_load_default_config() 从 configparser 改为 10 行手写解析器。同步点：kb/90 §2.1 硬编码表 + §2.3 整节（草案 + 代码要点 + 两个落地坑 4 处引用）+ §2.4 目录树、kb/00 §6 配置分类表 + §6.2 三级覆盖图 + §6.2 说明段（启动加载方式从 "configparser" 改为 "Spark 原生 key value"）、kb/92 checklist 2 处、记忆 project_templates_and_config 扩展名约定段追加 spark-defaults.conf 例外说明。未改动：2026-04-15 changelog line 134（conf/spark-defaults.yaml 历史快照保留）。路线外变更同步入册原则：DS 目录删除在 f20d9c3 未同步 kb 前瞻文档，属于此前"默默做完"漏记，本次补 |
— |
| 2026-04-20 | DATAX_HOME 条件赋值 + 默认值对齐新环境（§2.1 最小铺垫）：bin/common/init.sh:17 从 DATAX_HOME="/opt/module/datax" 改为 DATAX_HOME="${DATAX_HOME:-/opt/datax}"。触发：dim_calendar 测试同步在服务器上报 /opt/module/datax/bin/datax.py 不存在，实际新 CDH 环境 DataX 装在 /opt/datax。两步改动：(a) 默认值从 tendata 时代的 /opt/module/datax 更正为新项目真实路径 /opt/datax，(b) 改为 ${VAR:-default} 条件赋值，允许 shell 环境 override（未来多机器部署路径不一致时零代码改动）。未做：§2.1 完整外配到 conf/env.sh 仍待推进。同步更新 kb/90-重构路线.md §2.1 表格对应行的当前值与备注 |
— |
| 2026-04-20 | 恢复 dw_base/__init__.py 的 HIVE_CONF_DIR export（反转 2026-04-18 第四轮决策的另一部分；应随 HADOOP_CONF_DIR 恢复时一起做而遗漏，本次补）：spark-sql-starter.py 启动通过 HADOOP_CONF_DIR 校验后，查 test.dim_calendar_dw2 报 Table or view not found，同一张表在 Hive CLI describe 正常。根因：.enableHiveSupport() 没找到 hive-site.xml 会静默回落 in-memory metastore，看不到 HMS 真实库表。和 HADOOP_CONF_DIR 是同一批 2026-04-18 被误删的 env export，属同类 bug。整改：(a) 取消 dw_base/__init__.py:19 HIVE_CONF_DIR 的注释；(b) kb/90 §2.8 "老 env 设置"段重写合并 HADOOP_CONF_DIR / HIVE_CONF_DIR 两条说明 + 代码改造清单附表行合并；(c) 教训同步入记忆 feedback_act_not_flatter.md 的触发面扩到"修同类问题时邻域扫一遍" |
— |
| 2026-04-20 | 删除 geo_hash UDF + pygeohash 依赖（重构计划外）：spark-sql-starter.py 在新 CDH 环境启动时报 ModuleNotFoundError: No module named 'pygeohash'（dw_base/udf/common/spark_common_udf.py:19 import pygeohash）。根因：2026-04-20 UDF 重组（kb/92:165）把 geo_hash(lat, lng, precision) 保留进 common/（auto-load），但 pygeohash 在 kb/90 §7.1 还标 LAZY 且注释"只被即将清理的老业务代码引用"—— UDF 进 common 后该分类失效。当前阶段业务 SQL 尚未开始，geo_hash 零现成消费者；真需要 geo 分析再从老项目 copy + 放 business/。整改：(a) 删 spark_common_udf.py:19 import pygeohash + :375-376 def geo_hash(...)；(b) kb/90 §7.1 LAZY 行的 pygeohash 移除（仓库零引用，不需要 LAZY 档） |
— |
| 2026-04-20 | kb/00 目录树同步真实状态 + §2/§3 收敛：dw_base/ 实际子目录已变（2026-04-20 删 scheduler/ / hive/，新建占位 io/ / ops/ / dq/ / pm/ / sync/），kb/00 §1 目录树仍停留在旧态；§2 核心模块职责表 + §3 Mermaid 均与 §1 同一信息三视图重复。整改：(a) §1 目录树同步真实子目录，职责并入每行行尾注释；顺带补漏 publish.sh 已挪入 bin/（6936460）+ 新增 tests/ 条目 + conf/ 注释更新为"非敏感入库"口径；(b) §2 表删除，替换为一行"职责已并入 §1"指引；(c) §3 Mermaid 删除，保留标题 + 一行"待基础模块实装后重绘"说明。保留 §2/§3 heading 保证节号稳定，外部引用（kb/90 §4.3/§5/§6.4/§9、kb/30 §8/§9.6）零更新 |
— |
| 2026-04-20 | 恢复 dw_base/__init__.py:16 的 HADOOP_CONF_DIR export（反转 2026-04-18 第四轮决策的一小部分）：spark-sql-starter.py -f workspace/20260420/select_dim_calendar_dw2.sql 在新 CDH 环境报 When running with master 'yarn' either HADOOP_CONF_DIR or YARN_CONF_DIR must be set —— Spark on YARN 启动时 SparkSubmitArguments.validateSubmitArguments 强校验该 env；bigdata 账号 shell 里未 export。2026-04-18 第四轮决策（kb/92:158）把这行当"死代码"删，判断只基于 DataX JVM（DataX 确实不靠它，HA 走 ini [hadoop_config] 注入），忽略了同一 dw_base/__init__.py 也是 Spark 入口的 bootstrap。本次恢复：os.environ['HADOOP_CONF_DIR'] = '/etc/hadoop/conf' 加回，注释更新为"Spark 需要；DataX 不读 classpath"。同步更新 kb/90 §2.8 末尾"死代码"段（重写为"仅对 Spark 生效"）+ §2.8 代码改造清单附表对应行（从"删除"改为"保留"，给出双路径理由）。DataX 侧结论（ini [hadoop_config] 注入 HA、HADOOP_CONF_DIR 对 DataX JVM 无效）不受影响 |
— |
| 2026-04-20 | 补 SPARK_CONF_DIR env 兜底 + 回退 HIVE_CONF_DIR 伪修复 + 删 HDP 残留注释：昨日恢复 HIVE_CONF_DIR 后冒烟测试仍报 Table or view not found，说明 HIVE_CONF_DIR 不是真正触发点。对比老项目 tendata-warehouse-release/tendata/__init__.py 发现老代码同样把 HIVE_CONF_DIR 注释掉（反证此前上一条 changelog 的"伪修复"），且同样没有 SPARK_CONF_DIR。真正差异在环境：新 CDH 用 pip 安装的 pyspark 其 SPARK_CONF_DIR 默认指向自身空 conf/，不会加载集群 /etc/spark/conf/hive-site.xml，.enableHiveSupport() 静默回落 in-memory metastore。整改：(a) dw_base/__init__.py os.environ.setdefault('SPARK_CONF_DIR', '/etc/spark/conf')（用 setdefault 允许 shell 侧 export 覆盖），同时把 HIVE_CONF_DIR 重新注释掉，并删除历史遗留行 # os.environ['SPARK_HOME'] = '/usr/hdp/3.1.5.0-152/spark2'（过期 HDP 路径 + 本就是注释，无保留价值）；多行 comment 合并为单行；(b) kb/01-运行环境.md 新增 §4 Spark 运行时环境变量（HADOOP_CONF_DIR / SPARK_CONF_DIR 表）；(c) kb/90-重构路线.md §2.8 代码改造清单附表行回退 —— 从"保留 HADOOP_CONF_DIR + HIVE_CONF_DIR"改为"保留 HADOOP_CONF_DIR + 新增 SPARK_CONF_DIR.setdefault"，附详情指向 01 §4；(d) kb/90 §7.1 findspark 加 TODO：CDH + pip pyspark 环境下其功能可由 SPARK_CONF_DIR + setdefault 覆盖，evaluate 移除。教训：上一条 changelog（HIVE_CONF_DIR 恢复）是在没对比老项目的情况下拍板的，属于典型的"邻域扫但没找对根因"；act-not-flatter memory 同步更新边界判定（同根因 yes/no） |
— |
| 2026-04-20 | raw 层外部表规范 + "每日调度" 措辞收敛：(a) kb/20-数仓分层与建模.md §8.1 新增 bullet：raw 层建表一律 CREATE EXTERNAL TABLE，DROP TABLE 只删元数据、HDFS 数据保留，raw 作为链路兜底层误删可恢复；(b) kb/00-项目架构.md 三处"每日调度"收敛为"调度执行"：§9 目录说明 jobs/ 用途行（L617）、§9 目录说明 jobs SQL 路径行（L623）、§9.2 标题（L703）—— 因为调度周期不一定是日（小时/周/月/ad-hoc 均可），"每日"措辞在通用性描述里不准确；同文档 L909 ads_trd_gmv_d.sql 注释 + kb/23-标签体系.md 两处 tdm_*_ful_d 场景描述保留"每日计算"（_d 后缀表明具体表就是日粒度）。遗留冲突待拍：kb/00-项目架构.md §9.2 L829 的 raw 层 CTAS 样例（CREATE TABLE raw.raw_trd_legacy_order_his_o ... AS SELECT）是 managed table，与 §8.1 新规范的"raw 一律 EXTERNAL"冲突——CREATE EXTERNAL TABLE ... AS SELECT 在 Spark / Hive 语法上不支持。候选：① 样例拆两步（先 CREATE EXTERNAL TABLE + LOCATION 再 INSERT OVERWRITE）② §8.1 加 "CTAS 例外" 条款 ③ 删掉 §9.2 CTAS 路径只留 INSERT OVERWRITE 路径。待用户拍板 |
— |
| 2026-04-20 | 里程碑：DataX + Spark SQL 双入口在新 CDH 环境首次端到端冒烟跑通（tag milestone/datax+spark-smoke-2026-04-20）：链路 DataX 导入 PG dim_calendar → Hive test.dim_calendar_dw2（workspace/20260420/dim_calendar.ini），Spark SQL 从 Hive 查回（workspace/20260420/select_dim_calendar_dw2.sql），端到端返回 10 行。新 CDH 环境适配前后共三处连锁修复：(a) cf87744 恢复 HADOOP_CONF_DIR（Spark on YARN 启动强校验）；(b) 5b2569a 删除 geo_hash UDF + pygeohash 依赖（common auto-load 链路无 fallback）；(c) 本次 SPARK_CONF_DIR=/etc/spark/conf setdefault（pip pyspark 默认指向自身空 conf/，缺此项 enableHiveSupport 静默回落 in-memory metastore，看不到 HMS 真实库表）。注：该 tag 打在 feature 分支 commit 上，违反后续 kb/30 §3.4.6.3 "Tag 打在 release → master 合并提交" 规则，已于 2026-04-21 删除（本地 + 远程） |
— |
| 2026-04-20 | 存储格式约定反转：orc.compress 不显式写 NONE，走 ORC 默认（ZLIB）：workspace/20260420/dim_pub_calendar_ful_o.sql 建表时写了 TBLPROPERTIES ('orc.compress' = 'NONE')，核查 ORC 默认压缩为 ZLIB，NONE 是显式关闭压缩（非 no-op）。前期 kb 三处口径"咱不压缩放弃磁盘换 CPU"属于过早决策，小表省 CPU 微乎其微、业务表规模上来后 ZLIB 更优，维护一套"显式写 NONE"的约束成本大于收益。改为走默认、建表不加 TBLPROPERTIES。文档同步三处：kb/20-数仓分层与建模.md §7 压缩行（orc.compress=NONE → 走 ORC 默认）、kb/00-项目架构.md §9.1 末尾存储格式约定行（删 + orc.compress=NONE）、kb/00-项目架构.md raw 层 CTAS 样例（删 OPTIONS ('orc.compress'='NONE') 一行）。未在文档里加"为什么不显式写 NONE"的解释性注释（见用户反馈） |
— |
| 2026-04-20 | kb/20 分区/raw STRING 口径收敛：§7 分区字段补 dt 类型 STRING + 格式 YYYYMMDD（如 20260101）；§8.1 "全字段 STRING" bullet 去掉 "（不含 dt 分区）"（dt 本身也是 STRING，括号让人误以为 dt 是另一种类型） |
— |
| 2026-04-20 | raw EXTERNAL 规范硬化：kb/00 §9.2 CTAS 样例改 INSERT OVERWRITE：关闭上一批 changelog 的"CTAS + EXTERNAL 冲突待拍"。(a) kb/00 §9.2 CSV 一次性导入样例从 CTAS 改为预建 EXTERNAL TABLE + INSERT OVERWRITE 两步；"CTAS vs INSERT OVERWRITE" 对照表替换为"raw 层写入模式对照"（3 个场景全部 EXTERNAL + INSERT OVERWRITE）；"为什么 CSV 一次性导入推荐 CTAS" 论证段删除（论点作废）；raw 层不再有"省 manual/ddl/"的例外。(b) kb/20 §8.1 "全字段 STRING" bullet 改为 "raw 层所有表字段（含 dt 分区）一律 STRING 类型"（与 §7 dt STRING 规范对齐，消除"业务字段 vs 分区字段"的措辞分裂） |
— |
| 2026-04-20 | kb/90 新增 §2.12 通用 UDF 注释完整化 + 自查表（聚簇 B 延伸）：dw_base/udf/common/spark_common_udf.py 40 函数注释粗细不一，且当前 common/ auto-load 链路没有任何"新增 UDF 需要登记哪里"的准入规则。三档改造：(a) 40 函数 docstring 统一 5 段模板（摘要 / 入参 / 返回 / 异常与边界 / SQL 示例），按 JSON → Array → String → Numeric-Date-Hash → Cross-type 5 批分 commit；(b) 新建 kb/31-UDF 手册.md（与 30-开发规范.md 同级独立文档，方案 A 而非并入 30），表头 函数名 / 分类 / 入参 / 返回 / 摘要 / 代码位置 / 补注释状态，初版登记 40 函数全量，新增通用 UDF 进 common/ 时必须同步登记；business/ UDF 在自己的子目录 README 维护，不走此表；(c) 注册准入规则（于 2026-04-21 评估取消，详见当日 changelog）。本条是 2026-04-20 UDF 模块重组（本 changelog 之前记录的 UDF 6 文件合一 + business/common 分离）的延伸，不动 auto-load 机制，只补文档与规则 |
— |
| 2026-04-20 | dw_base 占位模块骨架 + tests 骨架 + bin 收口（B4 提前 + C 起步）：(a) 新建 5 个占位模块 dw_base/io/{db,file,hdfs}/ + dw_base/ops/ + dw_base/pm/ + dw_base/dq/ + dw_base/sync/，每个带 __init__.py + README.md（4 节：职责/接口/依赖/状态）；实现留待后续阶段。(b) tests/{unit,integration}/ 骨架 + tests/README.md + .gitkeep；首批单测目标 tests/unit/udf/test_spark_common_udf.py（40 函数）。(c) bin/excel_to_hive.py 删除（一次性工具，有需求重做）；publish.sh 从项目根 git mv 到 bin/publish.sh（publish 是 DS 调度入口 = 和 bin 同类）。代码侧单次 commit 6936460。(d) 文档侧同步：kb/30-开发规范.md §4.5 占位模块规范（4 节标准 + "空 init.py 无 README → 删"铁律）；kb/90-重构路线.md 按聚簇 + DAG 重组（新增 §〇 全景与 DAG、§2.10 common/utils/io/ops 四模块律、§2.11 新占位 registry、§六.1 tests 骨架标注、§八 从 P0-P3 线性表替换为聚簇 A-F 推进视图；所有主章节加 [聚簇 X] 标签；§2.1 publish.sh 行改为 bin/publish.sh）；本文档总览引入聚簇视图说明 + 阶段 1/2/4 状态改"推进中 / 部分提前完成" |
— |
| 2026-04-21 | kb/30 §4.6 整合 Git 协作规范：kb/inbox/git规范.md 草稿 6 章整合进 kb/30 §4.6（§4.5 与 §5 之间），节号重排为 §4.6.1~§4.6.6 对齐现有多级风格；草稿 §六 "命名规范" 改名为 "分支 / Tag 命名" 避开与 kb/21-命名规范.md 主文档重名；补分支/hotfix/tag 命名示例到各 3 个（个人分支 3 个与 §4.6.1.2 ASCII 图的李四/王五/张三对齐） |
— |
| 2026-04-21 | kb/30 大梳理：删 §1 通用开发流程 / §4.5 占位模块规范，Commit 信息归入 Git 协作节，整体节号重排：(a) 删 §1 通用开发流程（与项目无针对性）；(b) 删 §4.5 占位模块规范（该规范仅用于架构规划专用、非普通开发内容，迁至项目根 CLAUDE.md）；(c) 原 §4.4 Commit 信息（Conventional Commits）并入 Git 协作规范作为 §3.4.7；(d) 节号重排 §2→§1 TPAD / §3→§2 数仓流程 / §4→§3 代码开发（§4.1-§4.3→§3.1-§3.3、§4.6→§3.4，其 §4.6.1-6 → §3.4.1-6）/ §5→§4 / §6→§5 / §7→§6；(e) 联动 kb/README.md §30 条目描述 + kb/90-重构路线.md §2.11 占位模块标准引用从 kb/30 §4.5 改指 CLAUDE.md |
— |
| 2026-04-21 | datasource 目录结构收敛到 kb/00 §1 一处：老 kb 内 datasource 目录树在 kb/00 §1（扁平老结构）、kb/00 §6.4（带 env 层目标态）、kb/02 §4（带 env 层）三处平行画，一改就易漏。kb/00 §1 子树补齐 env 层 + 实例举例（postgresql/{prod,test,dev}/hobby.ini）作为唯一真源；kb/00 §6.4 删内嵌目录示例块 + 删"当前状态：尚未落地"段（按"不标现状/目标态，以目标态为准"约定）；kb/02 §4 删重复目录树，改跨文档引 kb/00 §1 |
— |
| 2026-04-21 | kb/31-UDF手册.md 骨架建立（聚簇 B / §2.12(b) 启动）：新建独立文档作为 dw_base/udf/common/ 通用 UDF 自查表的稳定锚点；仅骨架（概述 + 准入规则占位 + 空表头），分类不预划由 Codex 按 spark_common_udf.py 实际划分登记；kb/README.md §3x 加入口。配套修正 kb/90 §2.12：(a) 文件名 kb/31-UDF 手册.md → kb/31-UDF手册.md（无空格）；(b) 准入规则落点候选从 kb/30 或 CLAUDE.md 改为 kb/30 或 kb/31 内部（规范类条款不进 CLAUDE.md）。首版全量登记 + 硬约束正文待 Codex UDF 注释统一化落地后另起 changelog |
— |
| 2026-04-21 | kb/31 表头定稿 + 合并 common/business + 取消 UDF 准入规则：(a) kb/31 表头改为 函数编号 \| 函数名 \| 分类 \| 入参 \| 返回 \| 描述 \| 示例 \| 补注释状态，函数编号由 Codex 在 spark_common_udf.py 以顺序注释注入（不依赖行号，避免改动污染其他函数）；(b) business UDF 纳入 kb/31 第二段（原"business 在子目录 README 维护，不走此表"规划取消）；(c) UDF 准入规则取消（无执行主体，规则无意义）。联动 kb/90 §2.12：删"业务 UDF 进 common 准入标准缺失"问题项、同步新表头、删"business 不走此表"表述、删"注册准入规则"整点、关系节去"准入规则"字样；kb/92 L181 历史条目 (c) 改软标注指向本条。另 kb/30 §5 删"jobs/ 里没有 CREATE TABLE 可改"冗余句与"归档策略"防御性条款 |
— |
| 2026-04-21 | 聚簇 A.1 环境变量外配到 conf/env.sh（bash + Python 单源）：新建 conf/env.sh 统一 5 vars —— RELEASE_USER="bigdata"（替换 "alvis"）/ RELEASE_ROOT_DIR="/home/bigdata/release" / PYTHON3_PATH / DATAX_HOME（保持原有 ${DATAX_HOME:-/opt/datax} 条件赋值）/ LOG_ROOT_DIR="${HOME}/log"。Python 侧新建 dw_base/utils/env_loader.bootstrap_env() 通过 subprocess.run(['bash', '-c', '. env.sh && env -0']) 让 bash 自己解析 env.sh，再 os.environ.setdefault(...) 注入（避免重写一套解析器导致 bash/py 双解析漂移；setdefault 允许 shell 侧已 export 的值优先）。dw_base/__init__.py 顶部加 bootstrap_env() 调用 + 读 os.environ['RELEASE_USER' / 'RELEASE_ROOT_DIR' / 'LOG_ROOT_DIR']，删 /opt/data/log vs ${HOME}/data/log 的 whoami 分流（对齐 kb/90 §7.2.1 的单值决策）。bin/common/init.sh 顶部加 . conf/env.sh + 删对应硬编码变量 + 删 whoami 分流 + 删 export LOG_ROOT_DIR / PYTHON3_PATH / RELEASE_ROOT_DIR / DATAX_HOME（env.sh 已 export）；bin/publish.sh 加 . conf/env.sh + 删 L15 RELEASE_ROOT_DIR="/home/alvis/release" 硬编码。联动 kb/90 §2.1 删 5 行已完成硬编码（DATAX_HOME / PYTHON3_PATH / RELEASE_USER / RELEASE_ROOT_DIR / LOG_ROOT_DIR）+ §2.2 config 结构删 env.py（单源不做双份）+ §7.2.1 大幅瘦身（去掉现状/为什么/代码改动三段，仅保留日志路径 {module}/{dt}/{file}.log 约定）+ 本文阶段 2 checklist 4 处 [x] |
— |
| 2026-04-21 | dw_base/common/__init__.py 撤销删除（反转先前空壳判断）：早先 ls 只看到 __init__.py 0 字节就判定"空壳"、按 CLAUDE.md "空 init.py + 无 README 下次清理直接删"规则挂入 A.1 执行清单第 9 项。grep 查证发现 dw_base/common/ 下 config_constants.py / container.py / template_constants.py 分别被 bin/spark-sql-starter.py / bin/datax-job-config-generator.py / dw_base/utils/log_utils.py / dw_base/datax/plugins/reader/mysql_reader.py import，__init__.py 0 字节是 Python 正常的 package 标识（dw_base/__init__.py 含 bootstrap 逻辑，保持 regular package 一致性优于切 namespace package）。结论：不删。教训：空壳判断必须 ls 整个目录 + grep 所有子模块引用，不能只看 __init__.py 字节数 |
— |
| 2026-04-21 | 删除 bin/flume-control.sh（194 行；事实不可用）：脚本顶部 shebang 损坏（ho#!/bin/bash）+ 依赖已在 2026-04-20 删除的 bin/wechat-work-alert.sh + L64 conf/flume/*.properties 与 L162 conf/flume/config/*.properties 路径自相矛盾，实际已跑不起来。决定：整文件删 + Kafka→HDFS 接入通道的设计理念归档到 kb/90 §5.2 历史档案，按需重建时以该档为参考（不沿用老 SKB_LITTLE_CUTE / 手机号硬编码告警，重建时按 conf/alerter.ini 外配走） |
— |
| 2026-04-21 | SQL 风格基线尝试后撤回：本轮前半段把 sql_style.xml 从 conf/ 挪到项目根，并在 kb/30 §3.2.1 / §3.2.2 立了强基线（关键字/类型 UPPER、SELECT/FROM/ORDER/GROUP 一项一行、JOIN/ON 缩进、CASE/CTE/UNION/OVER/INSERT OVERWRITE/分号九条换行与缩进样例）。实测 IDEA formatter 支持面不足（KEYWORD_CASE 仅作用于新输入不改存量、SELECT 前置逗号长期不支持、ORDER/GROUP 一项一行的 option 名 JetBrains 非公开、UNION 前后空行 formatter 不管、CASE THEN/END 独立行无选项控制），强约束无法靠 formatter 落地。本轮后半段全部回退：删 sql_style.xml、kb/30 §3.2.1 / §3.2.2 整节删除、原 §3.2.3 不对齐 AS 重编号为 §3.2.1。团队 SQL 格式化改由各自 IDEA 默认 + 项目 SQL 方言统一设为 Spark 承担，冲突走 review |
— |
| 2026-04-21 | 下线"阶段 3：业务 SQL 从零开发" + 取消 UDF 注释补齐 + kb/31 首批登记 13 个通用 UDF：(a) 业务 SQL 从零开发属于新开发、不属于重构 scope：kb/92 总览表删阶段 3 行、阶段 3 整节删除、阶段 5 前置条件从"阶段 3 稳定"改为"新业务 SQL 稳定"；kb/90 §〇 聚簇表删 E 行、DAG 图删 E 节点、关键依赖边 "A+B+C→E" 与 "E→F" 合并为 "新业务 SQL 生产稳定→F"、§八 聚簇 E 整节删除、当前推进建议"等待前置"里 E 行改为 F 行。(b) 通用 UDF 注释已由开发者手动补完（spark_common_udf.py 13 个 @udf 函数均带 UDF-XX 顺序编号 + 分节注释），kb/90 §2.12 删"5 段模板 + 5 批 commit"规划、"40 函数"更正为"13 个注册 UDF"、标题从"注释完整化 + 自查表"改为"自查表"。(c) kb/31-UDF手册.md §1 通用 UDF 表从空壳填入 13 行（UDF-01/02/21/22/23/31/32/33/41/42/51/52/53），分类按代码中分节注释（JSON / ARRAY / STRING / NUMERIC-DATE-HASH / CROSS-TYPE），函数编号按代码中 UDF-XX 注释；§2 业务 UDF 保持占位；非 @udf 普通 def（18 个辅助 / 工具函数）不登记 |
— |
| 2026-04-21 | 聚簇 B.1 __init__.py 瘦身（修剪式，不拆 core/）：dw_base/__init__.py 从 127 行 → 83 行。三处删除：(a) import findspark + findspark.init() —— 查证 3 条事实后安全删：findspark 全仓仅此 2 处引用；入口全走 python3 xxx.py（非 spark-submit），SPARK_HOME 从未被代码注入，findspark 在 CDH 节点上 which spark-submit → readlink -f 反推出 parcel $SPARK_HOME 把 $SPARK_HOME/python 前插进 sys.path，但 pip pyspark 2.4.0 和 parcel pyspark 2.4.0 同版本，业务表现零差异（见里程碑 datax+spark-smoke-2026-04-20 冒烟链路，HMS 真正入口是 SPARK_CONF_DIR=/etc/spark/conf/hive-site.xml，与 findspark 无关）；(b) 删 21 个外部零引用的颜色常量 —— CHG_BOLD / NORM_BLU / NORM_WHT / 7×BOLD_* / 7×BGRD_*（if/else 两分支同步删），保留实际被引用的 6 个（DO_RESET / NORM_RED / NORM_GRN / NORM_YEL / NORM_MGT / NORM_CYN）；(c) 删 IS_RUN_BY_NORMAL_USER 状态变量（两处赋值外部无引用，仅内部 elif 分支走到时为 True，无消费者）。不拆 core/* 的理由：findspark 去掉后"懒加载"诉求大半消失，拆分需改 11 处调用点 import，ROI 低；py/sh 颜色双份是运行时分家的必然（跨 runtime 单源化要加 subprocess 解析，得不偿失），真冗余只是 py 侧定义超过实际被用的部分。联动：requirements.txt:3 删 findspark==2.0.1；tests/README.md:26 findspark 段改写为 HMS 入口说明；kb/00 §1 __init__.py 行注释去 findspark；kb/90 §三 改写为"已完成 · 修剪式"并附未拆 core/ 的理由；kb/90 §7.1 KEEP 行去 findspark + 末尾 TODO 行改写为"已删除" |
— |
| 2026-04-22 | 勘误：移除 "SQL SET 资源类参数不生效" 的错误表述：A.4 落地时误把 "SparkSession.conf.set() 对已启动 session 不改变资源" 这条 Spark 固有行为类推到"SQL 里的 SET"。实际 spark_sql.py:query() L433-440 对 SQL 内 SET spark.* 做预扫描，在 session 启动前塞进 _final_spark_config，__init_spark_session 通过 builder.config() 写入后才 getOrCreate()——资源类 SET 同样生效。清理 4 处错误：dw_base/spark/spark_sql.py:155 注释、conf/spark-tuning.conf L6-7 注意段、kb/90 §2.3 "落地坑"段 + L2 行括号、本文 L74 基于错误前提的验证项 |
— |
| 2026-04-22 | 仓库改名 tendata-warehouse-release → poyee-data-warehouse 收尾：项目根目录由用户手动改名完成；代码侧 dw_base/utils/file_utils.py:9 + dw_base/utils/hdfs_merge_small_file.py:7 两处 re.sub(r"tendata-warehouse.*", ...) 字面量同步更新。.idea/*.iml / modules.xml / workspace.xml 因 .idea + *.iml 在 .gitignore，属本地 IDE 状态，不入库亦不影响运行（老 tendata-warehouse-release.iml + modules.xml / workspace.xml 里的 module name 残留不处理）。联动 kb/90 §1.1 L88 表格行打勾 + §2.3 末尾"与仓库改名的联动"段压缩为一行记录 |
— |
| 2026-04-21 | 聚簇 A.4 Spark 参数外配 + spark_sql.py 三级覆盖：按业务调整频率拆两文件入库 —— conf/spark-defaults.conf（12 条底层行为/开关类，初始化后少改：spark.sql.adaptive/broadcastTimeout/codegen/arrow*/files/statistics.* + spark.dynamicAllocation.enabled + spark.files.ignoreCorruptFiles + spark.debug.maxToStringFields + spark.port.maxRetries + hive.exec.orc.default.block.size）+ conf/spark-tuning.conf（10 条资源/并行度/队列，业务早期常改：spark.{driver,executor}.{memory,cores} + spark.executor.instances + spark.executor.memoryOverhead + spark.driver.maxResultSize + spark.default.parallelism + spark.sql.shuffle.partitions + spark.yarn.queue）。dw_base/spark/spark_sql.py 改造：(a) 模块级新增 _load_spark_conf_file(path)，读 Spark 原生 key value 格式，支持 # 注释与空行，文件缺失返回 {} 容错单测；(b) __init__ 10 个 tuning 相关构造参数默认值 '2g' / 200 / ... → Optional[...] = None sentinel，不破坏既有调用点显式传参；(c) __init_spark_session 原 22 条硬编码 .config(...) 链替换为三段：L1 先 spark-defaults.conf 后 spark-tuning.conf（相同 key tuning 覆盖 defaults）→ L2 self._final_spark_config（SQL 内 SET）→ L3 构造参数非 None 项 + extra_spark_config（L3 内 extra 覆盖 named），保持原"extra > SQL SET > named" 的向后兼容；日志分层打 L1/L2/L3 前缀便于排查。联动：kb/90 §2.2 conf 结构加 spark-tuning.conf + §2.3 改写为两文件模型（去单文件草案）+ 删"坑 2"（B1 → A2 依赖边）+ 聚簇 L59 依赖边删 |
— |
| 2026-04-22 | datasource 扁平化 + db_type 按父目录段判定（方向反转）：反转 2026-04-15 起立项的"一套代码跑多环境"设计（kb/90 原 §2.5：-env 参数 + datasource/{db_type}/{env}/{instance}.ini 分层 + env 注入）。实际前期跨环境同步是常态（test 业务库 → prod HDFS），"全局 env"概念不成立。新方案：(a) source ini 落位 datasource/{db_type}/{env}-{实例简称}.ini，env 写进文件名（env ∈ dev/test/prod），扁平组织；(b) sync ini 内 dataSource = {db_type}/{env}-{实例简称}（强制带 db_type 前缀；旧裸名 hdfs-ha 不再支持）；(c) 代码侧 dw_base/datax/plugins/plugin.py:37 + plugin_factory.py:34 的 db_type 提取从"文件名按 - 切首词"改为"按 / 切首段"（父目录名）—— 旧算法在新文件名出现 - 时会把 env 误判为 db_type，必须改。联动：kb/00 §1 目录树重绘（去 env 子目录，加样例 prod-hobby.ini / test-hobby.ini / prod-ha.ini 等 + sync ini 引用形式说明段）+ §6.1 配置分类表落位描述、kb/02 §4 同步、kb/21 §3.9 过时 3 行修正（废 -env 注入表述；引用形式 {db_type}/{env}-{实例简称}；JSON 输出路径去 {env}/ 层）、kb/90 §2.1 硬编码表合并 3 行为 1 行 + §2.5 大幅压缩（三阶段设计整段删，保留路径解耦部分）+ §2.8 末尾表行更新 + §八 状态表合并、kb/92 L90 checklist 落位改扁平。conf/templates/datasource/*.template.ini × 3 头注释补"落位"+"dataSource 引用"两行。bin/datax-job-config-generator.py L5/L114/L115 的路径注释讲的是另一个 conf/datax/config/ 作业分组层级，与本次 datasource 扁平化无关，不动；dw_base/datax/plugins/reader/mysql_reader.py:178 {group}/mysql-{database} 生成逻辑是非活跃代码（批量采集未启动），留到 §2.7 重构时对齐 |
— |
| 2026-04-22 | conf/templates 按引擎顶层重组 + README 样板段迁入 kb/30 §6：conf/templates/{datasource,datax/{raw,ads,manual},sql,ddl}/ → conf/templates/{datax/{datasource,sync},spark/{sql,ddl}}/。datasource 挪进 datax/ 匹配其仅服务于 DataX 的事实（Spark 入口只读 Hive，不读 ini）；datax/{raw,ads,manual} 三空目录合并为 datax/sync/（kb/21 §3.9 删后三分类在样板层级无意义）；sql/ddl 归 spark/ 按执行引擎归属。已备 3 份 datasource ini 随 git mv 挪入 datax/datasource/，头注释不含 conf/templates 字面量不需改。README 原 L111-116 "样板（待补充）"整段删除，替换为一句指向 kb/30 §6 链接；kb/30 新增 §6 开发样板（原 §6 相关文档 → §7）；kb/90 §2.1 模板目录行同步更新目录字面量 + 入口从 README 改指 kb/30 §6 |
— |
| 2026-04-22 | kb/21 §3.9 DataX ini 命名移出：kb/21 主题收敛到 Hive 表/字段/词根命名，§3.9 "DataX ini 文件命名"（命名模板表 + 导出类双下划线规则 + 通用约定 + 样板指引 + 老命名反思）整节删除，§8 速查表同删 3 行 DataX ini；DataX ini 命名示例已在 kb/00 §1 目录树 + §9.5 文件命名速查中体现，不再单独成节。连带清理 7 处跨文档 §3.9 引用：kb/00（L143 示例标题 + L582 §9.5 jobs/ads 行）、kb/30（§3.4.7 docs commit 示例改指 §3.4）、kb/90（§2.1 硬编码表 3 行 + §2.5 目标态段）。kb/21 §5.1 顺手清理一条残留垃圾字符 buyc1 |
— |
| 2026-04-22 | kb/00 §9 样板 job 结构迁入 kb/30 §4：kb/00 主题收敛到架构（模块/数据流/配置），§9 "DDL/jobs 组织 + migration 模式 + 命名速查" 属数仓开发方法论，整节（§9.1–§9.6）迁入 kb/30 新增的 §4 数仓开发文件组织；kb/30 原 §4/§5/§6/§7 顺序后移为 §5/§6/§7/§8，§6 manual/ 临时 SQL 规范里 "详见 00-项目架构.md §9.6" 改指本文 §4.6（就近内引）。外部引用更新：kb/90 §八 csv-to-hdfs 行"参见"列改指 kb/30 §4.3；kb/92 阶段 1 csv-to-hdfs checklist 里 "§9.3 模板" 改指 kb/30 §4.3。历史 changelog 里带 "§9.x" 的条目保留不改（历史 snapshot） |
— |
| 2026-04-22 | README 文档索引加入 SSOT 职责边界：索引段起首加一行 SSOT 原则（每篇文档是其主题的唯一权威，跨文档用 § 锚点互引不复述）；5 张分组表 "内容" 列改为 "职责"，每行重写为加粗前缀（架构 / 基础设施 / 鉴权链路 / 建模方法论 / 命名规则 / 开发方法论 等）+ 边界简述。顺带修两处：02-权限与账号行原来缺尾 ` |
表格闭合；末尾开发样板链接§6改§7`（对齐上一条 kb/30 §4 插入后的重编号） |
| 2026-04-22 | kb/00 结构收尾：用户侧删除 §4.3 DataX 脚本说明 / §6.3 DataX ini 格式 / §6.4 env 注入 / §8 manual/ 执行规范四大块，保留 §1 目录树 + §3/§4 待补充骨架 + §6 配置分类 + Spark 参数优先级。AI 侧：(a) §1 目录树补 conf/ 与 tests/ 实际文件（env.sh / spark-defaults.conf / spark-tuning.conf / templates/ / bak/；unit/ / integration/）；(b) §7 DataX 入口 + §8 Spark 入口半成品标题格式修复（7 。 → ## 7.、8 . / 8.1 补 heading level）；(c) 编号去跳号重排：1/3/4/6/7/8 + 重复的 7 → 1/2/3/4/5/6/7 连续，§7 部署架构规避冲突后落在新 §7；(d) §7 部署架构说明改写，分清已实现（whoami 分流删除 + LOG_ROOT_DIR 外配，2026-04-21 A.1）与目标态（{module}/{dt}/{file}.log 日志统一，待日志模块重写 kb/90 §7.2 / §7.2.1）。联动：kb/30 §6 删 "详见 kb/00 §8"（§8 已删）；kb/30 §4.3 raw 层下补 DataX ini dataSource = {db_type}/{env}-{实例简称} 运行时契约（代码由 plugin.py:37 父目录判 db_type）—— kb/00 删掉的接口约定移到 kb/30 归属；kb/90 §1.2 L97 陈旧引用 kb/00 §5 的样板 改指 kb/00 §1 + kb/30 §4.2；README 0x 表 00-项目架构 行职责描述同步为"目录结构、模块关系、执行链、配置管理、DataX / Spark 入口、部署架构" |
— |
| 2026-04-22 | kb/00 §1 目录树补齐子目录并去冗余注释；章节号去跳号：(a) §1 补子目录 bin/common/、conf/templates/{datax/{datasource,sync},spark/{ddl,sql}}/、conf/bak/{datax/{config,datasource},flume/config}/、dw_base/datax/{datasources,plugins/{reader,writer}}/、dw_base/io/{db,file,hdfs}/、dw_base/udf/{common,business}/、tests/unit/udf/；conf 下"行为/开关类少改 vs 资源/调优类常改"等冗余注释去掉；bin/ 脚本逐行列出；(b) 用户调整大标题顺序后号码与位置不匹配，重排为连续 §1/§2/§3 执行链详解/§4 配置管理体系/§5 DataX 入口/§6 Spark 入口/§7 部署架构 |
— |
| 2026-04-23 | kb/00 章节顺序再调：执行链详解后移到入口说明之后（理由：先有入口才有调用链），最终顺序 §1 目录结构 / §2 模块关系图 / §3 配置管理体系（§3.1 配置分类）/ §4 DataX 入口 / §5 Spark 入口（§5.1 常用参数 / §5.2 Spark 参数优先级）/ §6 执行链详解 / §7 部署架构。kb/90 + kb/30 外部引用仅指向 §1 目录树，不受影响 | — |
| 2026-04-23 | kb/00 §2 模块关系图并入 §5 执行链路 + 新增 §6 基础模块骨架：模块关系图（静态依赖拓扑）与 执行链详解（动态调用）在本项目线性链式结构下几乎 1:1，合并为 §5 执行链路（业界更通用表述）；新增 §6 基础模块 骨架，后续介绍 dw_base/ 除 spark/ / datax/ / udf/ 外的其他模块。子节编号随父节上移：§3.1 配置分类 → §2.1；§5.1 常用参数 → §4.1；§5.2 Spark 参数优先级 → §4.2。最终 §1 目录结构 / §2 配置管理体系 / §3 DataX 入口 / §4 Spark 入口 / §5 执行链路 / §6 基础模块 / §7 部署架构 |
— |
| 2026-04-23 | 新增 kb/93-架构决策.md 骨架（永久文档）：作为重构收尾后 90-重构路线.md / 91-重构备忘.md / 92-重构进度.md 三份过程文档压缩留档的 ADR 沉淀点；当前仅留"说明 + 决策清单（待补充）"骨架；README §9x 过渡资料表加行 |
— |
| 2026-04-23 | kb/00 改名项目导览 + kb/93 补 ADR 模板 + kb/91 入库：(a) kb/00-项目架构.md → kb/00-项目导览.md（git mv），文档定位收敛为"新人 / 外部协作者入口"；级联改 README（索引行 + 阅读建议 #1）、CLAUDE.md 冷启动必读、kb/02 §4 + kb/30 §6 + kb/90 §1.2 跨文档引用、kb/92 阶段 0 checklist；历史 changelog 里的 00-项目架构.md 字面量保留为 snapshot 不改；(b) kb/93 按业界主流（Michael Nygard）补 5 段 ADR 模板（Context / Decision / Consequences / Alternatives / Reversal Trigger）；(c) kb/91-重构备忘.md 从 untracked 入库（保留现有 DataX 脚本使用说明内容，作为重构期间的独立备忘文件） |
— |
| 2026-04-23 | kb/90 §2.6 两入口收口按老入口平迁收敛 + 新增 §九 待讨论议题：(a) §2.6 命名锁定 datax-hive-import-starter.sh / datax-hdfs-export-starter.sh（对齐 -starter 风格）；参数表删 6 项新设计（-dt / -skip-exist / -force-overwrite / -skip-partitions / -src-check / -env），改为老参数平迁集，其中 -env 本轮不做且未来不规划（datasource 已扁平化）；-c / -cd / -jc / -jcd + --override + 5 个 xxx_array=() 不平迁（后两者在老脚本从未激活使用，2026-04-23 查证）；实现建议改为 6 个新模块落 dw_base/datax/ 包内（放宽 B2 前置）、老脚本冒烟 2 通过后整体删不留转发封装；后延 ADR 锚点 1 项（日期范围展开）；(b) 新增 §九 待讨论议题锚点，先登记"分布式任务分发"（DS worker × 新入口内部实现）一项 |
— |
| 2026-04-23 | 聚簇 A.2 conf/workers.ini 外配 + 新集群 hostname 适配：bin/common/init.sh 原硬编码 RELEASE_HOST="m3" + DATAX_WORKERS=(m3 d1 d2 d3 d4) + DATAX_WORKERS_WEIGHTS map + 队列展开 for 循环（L13-28），整体外移到 conf/workers.ini（[release] host + [weights] 两 section，ini 格式入库）；init.sh 改为纯 bash 读 ini（case + BASH_REMATCH 正则，不调 Python，避免 bash/py 双源漂移）。新集群 hostname 从老短名 m3/d1-d4 换到真实短名 cdhmaster02 / cdhnode01-03（用户 2026-04-23 提供），权重从 1/2/2/3/3 改为 1/3/3/3（master 1、3 个 worker 均权 3）。联动 kb/90 §2.1 行标 ✅ + §八 A 聚簇状态表行标 ✅ |
— |