docs(kb): 00 §1 同步 dw_base 子目录真实状态；§2 表砍、§3 Mermaid 清空占位

kb/00-项目架构.md

@@ -13,6 +13,7 @@ poyee-data-warehouse/              # 项目根目录（仓库名 = 部署名）
 │   ├── datax-single-job-starter.sh#   DataX 单任务启动
 │   ├── datax-multiple-job-starter.sh # DataX 批量任务启动
 │   ├── datax-job-config-generator.py # ini→json 配置生成
+│   ├── publish.sh                 #   集群部署脚本（DS 调度入口，和 bin 同类）
 │   └── ...
 ├── jobs/                          # 业务代码层（新建，替代老项目 launch-pad/），每日调度执行
 │   ├── raw/                       #   原始数据采集（DataX ini 或 CSV 导入任务定义）
@@ -31,19 +32,21 @@ poyee-data-warehouse/              # 项目根目录（仓库名 = 部署名）
 │   ├── imports/{yyyymmdd}/        #   一次性入仓（硬盘、历史 dump、外部 CSV），按执行日期归档
 │   └── exports/{yyyymmdd}/        #   一次性出仓任务，按执行日期归档
 ├── dw_base/                       # 通用库层
-│   ├── __init__.py                #   全局初始化
-│   ├── common/                    #   常量、容器
-│   ├── spark/                     #   SparkSQL 核心
-│   ├── udf/                       #   Spark UDF 库（common + business）
-│   ├── datax/                     #   DataX 配置生成引擎
-│   ├── database/                  #   MongoDB/MySQL 工具
-│   ├── scheduler/                 #   调度辅助脚本
-│   ├── hive/                      #   Hive DDL 生成
-│   ├── utils/                     #   通用工具函数
-│   └── ...
+│   ├── __init__.py                #   全局初始化（环境检测、findspark、用户/权限判断、颜色常量）
+│   ├── common/                    #   常量、容器（alerter / config / template 常量）
+│   ├── spark/                     #   SparkSQL 引擎（Session 管理、UDF 注册、SQL 执行、数据导出）
+│   ├── udf/                       #   UDF 库（common 通用 + business 业务专用）
+│   ├── datax/                     #   DataX 配置生成引擎（ini→json），含 datasources/ + plugins/
+│   ├── database/                  #   MongoDB / MySQL 原生客户端封装
+│   ├── utils/                     #   通用工具（参数解析、日期、文件、日志、SQL 解析、字符串等）
+│   ├── io/                        #   （占位）I/O 边界：db / file / hdfs 跨进程读写
+│   ├── ops/                       #   （占位）湖内数据运维（小文件合并、分区清理、vacuum）
+│   ├── dq/                        #   （占位）数据质量检查（schema drift、值域、关联、规模）
+│   ├── pm/                        #   （占位）项目管理工具集成（TAPD / Jira API）
+│   └── sync/                      #   （占位）外部文档同步（Docmost → kb/inbox）
 ├── kb/                            # 知识库：项目文档
-├── conf/                          # 配置层（当前为样例，后续存放非敏感配置）
-├── publish.sh                     # 集群部署脚本
+├── conf/                          # 配置层（非敏感配置入库：alerter.ini / workers.ini / datax-speed.ini / spark-defaults.conf 等）
+├── tests/                         # 测试：unit/ 纯函数单测 + integration/ Spark local[*] 集成测试
 ├── requirements.txt               # Python 依赖
 └── README.md
 ```
@@ -67,112 +70,11 @@ poyee-data-warehouse/              # 项目根目录（仓库名 = 部署名）
 
 ## 2. 核心模块职责
 
-| 模块 | 路径（新） | 职责 |
-|------|-----------|------|
-| 全局初始化 | `dw_base/__init__.py` | 环境检测、颜色常量、findspark 初始化、用户/权限判断 |
-| SparkSQL 引擎 | `dw_base/spark/spark_sql.py` | SparkSession 管理、UDF 注册、SQL 执行、数据导出 |
-| UDF 库 | `dw_base/udf/` | `common/` 通用 UDF（入口自动注册）+ `business/` 业务专用 UDF（按需 `ADD FILE`） |
-| DataX 引擎 | `dw_base/datax/` | ini 配置解析 → json 作业文件生成 |
-| DataX 数据源 | `dw_base/datax/datasources/` | 各类数据源的连接参数抽象 |
-| DataX 插件 | `dw_base/datax/plugins/` | Reader/Writer 工厂 + 各数据源实现 |
-| 数据库工具 | `dw_base/database/` | MongoDB、MySQL 原生客户端封装 |
-| 调度辅助 | `dw_base/scheduler/` | 轮询调度、分区清理等（告警模块已删，待重写） |
-| Hive 工具 | `dw_base/hive/` | DDL 生成、库表命名规则 |
-| 通用工具 | `dw_base/utils/` | 参数解析、日期、文件、日志、SQL 解析、字符串等 |
+模块职责已并入 §1 目录结构的行尾注释，不再单独列表（避免目录变动时多处同步）。
 
 ## 3. 模块关系图
 
-```mermaid
-graph TB
-    subgraph 外部系统
-        DS[DolphinScheduler<br/>调度系统]
-        YARN[Spark on YARN]
-        HIVE[Hive MetaStore]
-        HDFS[HDFS]
-        MONGO[(MongoDB)]
-        MYSQL[(MySQL)]
-        CK[(ClickHouse)]
-        ES[(Elasticsearch)]
-        KAFKA[Kafka]
-        DORIS[(Doris)]
-        REDIS[(Redis)]
-        DINGTALK[钉钉/企微<br/>告警]
-    end
-
-    subgraph bin [bin/ 启动脚本]
-        SPARK_STARTER[spark-sql-starter.py]
-        DATAX_MULTI[datax-multiple-job-starter.sh]
-        DATAX_SINGLE[datax-single-job-starter.sh]
-        DATAX_GEN[datax-job-config-generator.py]
-        DORIS_STARTER[doris-*-starter.py]
-        INIT_SH[common/init.sh]
-    end
-
-    subgraph dw_base [dw_base/ 通用库]
-        INIT_PY[__init__.py<br/>全局初始化]
-        SPARK_SQL[spark/spark_sql.py<br/>SparkSQL 引擎]
-        UDF[udf/<br/>UDF 库]
-        DATAX_ENGINE[datax/<br/>配置生成引擎]
-        DATASOURCES_CODE[datax/datasources/<br/>数据源抽象]
-        PLUGINS[datax/plugins/<br/>Reader/Writer]
-        SCHEDULER[scheduler/<br/>调度辅助]
-        DB_UTILS[database/<br/>DB 工具]
-        UTILS[utils/<br/>通用工具]
-    end
-
-    subgraph jobs [jobs/ 按数仓分层组织]
-        RAW[raw/<br/>原始数据采集 ini]
-        ODS_JOBS[ods/<br/>贴源层 SQL]
-        DWD_JOBS[dwd/<br/>明细层 SQL]
-        DWS_JOBS[dws/<br/>汇总层 SQL]
-        TDM_JOBS[tdm/<br/>主题域模型 SQL]
-        ADS_JOBS[ads/<br/>应用层 SQL + 导出 ini]
-    end
-
-    subgraph external_conf [项目同级 datasource/]
-        DS_INI[数据源 .ini<br/>含账密]
-    end
-
-    DS -->|触发| DATAX_MULTI
-    DS -->|触发| SPARK_STARTER
-    DS -->|触发| DORIS_STARTER
-
-    DATAX_MULTI --> DATAX_SINGLE
-    DATAX_SINGLE --> DATAX_GEN
-    DATAX_GEN --> DATAX_ENGINE
-    DATAX_ENGINE --> PLUGINS
-    PLUGINS --> DATASOURCES_CODE
-    DATASOURCES_CODE -->|读取| DS_INI
-
-    SPARK_STARTER --> INIT_PY
-    SPARK_STARTER --> SPARK_SQL
-    SPARK_SQL --> UDF
-    SPARK_SQL -->|spark.sql| YARN
-    YARN --> HIVE
-    YARN --> HDFS
-
-    DATAX_SINGLE -->|python datax.py| HDFS
-    DATAX_SINGLE -->|python datax.py| MONGO
-    DATAX_SINGLE -->|python datax.py| MYSQL
-    DATAX_SINGLE -->|python datax.py| CK
-    DATAX_SINGLE -->|python datax.py| ES
-    DATAX_SINGLE -->|python datax.py| KAFKA
-
-    DORIS_STARTER --> DORIS
-
-    SCHEDULER --> DINGTALK
-    SCHEDULER --> DB_UTILS
-    DB_UTILS --> MONGO
-    DB_UTILS --> MYSQL
-
-    DATAX_GEN -->|读取| RAW
-    SPARK_STARTER -->|读取| ODS_JOBS
-    SPARK_STARTER -->|读取| DWD_JOBS
-    SPARK_STARTER -->|读取| DWS_JOBS
-    SPARK_STARTER -->|读取| TDM_JOBS
-    SPARK_STARTER -->|读取| ADS_JOBS
-    DATAX_GEN -->|读取| ADS_JOBS
-```
+> 待 `dw_base/` 基础模块（`io/` / `ops/` / `dq/` / `pm/` / `sync/` 等占位）实装后重绘。当前过渡期保留此小节标题占位。
 
 ## 4. 执行链详解
 

kb/92-重构进度.md

@@ -168,5 +168,6 @@
 | 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 | **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 | **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 状态改"推进中 / 部分提前完成" | — |