docs(kb): DS 残留清 kb 前瞻；workers 锁 ini；spark-defaults 走 Spark 原生 .conf

kb/00-项目架构.md

@@ -39,7 +39,6 @@ poyee-data-warehouse/              # 项目根目录（仓库名 = 部署名）
 │   ├── database/                  #   MongoDB/MySQL 工具
 │   ├── scheduler/                 #   调度辅助脚本
 │   ├── hive/                      #   Hive DDL 生成
-│   ├── ds/                        #   DolphinScheduler API
 │   ├── utils/                     #   通用工具函数
 │   └── ...
 ├── kb/                            # 知识库：项目文档
@@ -119,7 +118,6 @@ graph TB
         SCHEDULER[scheduler/<br/>调度辅助]
         DB_UTILS[database/<br/>DB 工具]
         UTILS[utils/<br/>通用工具]
-        DS_API[ds/<br/>DS API]
     end
 
     subgraph jobs [jobs/ 按数仓分层组织]
@@ -166,7 +164,6 @@ graph TB
     SCHEDULER --> DB_UTILS
     DB_UTILS --> MONGO
     DB_UTILS --> MYSQL
-    DS_API --> DS
 
     DATAX_GEN -->|读取| RAW
     SPARK_STARTER -->|读取| ODS_JOBS
@@ -533,7 +530,7 @@ jobs/
 |----------|---------|-----------|------|
 | 数据源连接（含账密） | `../datasource/{db_type}/{env}/{instance}.ini` | 否 | 运维   |
 | DataX 同步任务定义 | `jobs/raw/` (采集) 和 `jobs/ads/` (导出) | 是 | 开发   |
-| Spark 默认参数 | `conf/spark-defaults.yaml`（目标态） / `spark_sql.py` 构造函数（现状） | 是 | 开发   |
+| Spark 默认参数 | `conf/spark-defaults.conf`（目标态，Spark 原生格式） / `spark_sql.py` 构造函数（现状） | 是 | 开发   |
 | Spark 单作业覆盖 | 对应 `jobs/*.sql` 文件内 `SET spark.x.y=z` | 是 | 开发   |
 | 环境变量 / 路径 | `dw_base/__init__.py`、`bin/common/init.sh` | 是（待改为conf） | 开发   |
 | 告警 Webhook | `dw_base/common/alerter_constants.py` | 否（待改 `conf/alerter.ini`，入库） | 开发   |
@@ -545,10 +542,10 @@ jobs/
         ↓ 覆盖
 SQL 文件内 SET spark.x.y=z                      (L2，单作业级别，开发写)
         ↓ 覆盖
-conf/spark-defaults.yaml                        (L1，全局默认，大数据负责人维护)
+conf/spark-defaults.conf                        (L1，全局默认，大数据负责人维护)
 ```
 
-**目标态由 `dw_base/spark/spark_sql.py` 启动时加载 L1，再让 Spark 本身处理 L2/L3 的覆盖**。详细改造计划见 `90-重构路线.md` §2.3。
+**目标态由 `dw_base/spark/spark_sql.py` 启动时按 Spark 原生 `key value` 格式加载 L1，再让 Spark 本身处理 L2/L3 的覆盖**。详细改造计划见 `90-重构路线.md` §2.3。
 
 ### 6.3 DataX ini 配置格式
 

kb/90-重构路线.md

@@ -42,11 +42,11 @@
 | `RELEASE_USER="alvis"` | `bin/common/init.sh` | 改为 `RELEASE_USER="bigdata"` 并移入 `conf/env.sh` |
 | `RELEASE_ROOT_DIR="/home/alvis/release"` | `init.sh`、`__init__.py` | 改为 `/home/bigdata/release` 并移入 `conf/env.sh` |
 | 项目部署目录 `poyee-data-warehouse/` | `publish.sh` | 新项目发布目录为 `/home/bigdata/release/poyee-data-warehouse/` |
-| `DATAX_WORKERS=(m3 d1 d2 d3 d4)` + `DATAX_WORKERS_WEIGHTS` 权重 map | `init.sh:18-31`（含展开 `DATAX_WORKERS_QUEUE` 的循环） | workers 列表 + 权重 map **整体**移入 `conf/workers.conf`（ini 或 yaml 格式），`init.sh` 仅保留读取 + 展开逻辑 |
+| `DATAX_WORKERS=(m3 d1 d2 d3 d4)` + `DATAX_WORKERS_WEIGHTS` 权重 map | `init.sh:18-31`（含展开 `DATAX_WORKERS_QUEUE` 的循环） | workers 列表 + 权重 map **整体**移入 `conf/workers.ini`（ini 格式），`init.sh` 仅保留读取 + 展开逻辑 |
 | `HADOOP_CONF_DIR='/etc/hadoop/conf'` | `__init__.py` | 使用系统环境变量 |
 | `LOG_ROOT_DIR="/opt/data/log"` + whoami 分流 | `init.sh`、`__init__.py` | 删除 whoami 分支，单值改为 `${HOME}/log` 并迁入 `conf/env.sh`，见 §7.2.1 |
 | 告警 Webhook（钉钉 / 企微 Key） | `dw_base/common/alerter_constants.py`（老告警模块已于 2026-04-20 删除，含 `dingtalk_notifier.py` / `ent_interface_dingtalk*` / `bin/dingtalk-work-alert.sh`） | 新告警模块重写时 Webhook Key 外移到 `conf/alerter.ini`（**入库**——部署靠 git pull，gitignore 会拉不到；webhook key 不算高敏感，最多被拿去发垃圾消息），Python 侧改 ConfigParser 加载；`alerter_constants.py` 整个删除；新项目不再使用钉钉 |
-| Spark 默认参数（executor/driver/shuffle/sql.*） | `dw_base/spark/spark_sql.py` 构造函数 + `.config(...)` 链 | 移入 `conf/spark-defaults.yaml`，SQL 文件可用 `SET` 覆盖，见 §2.3 |
+| Spark 默认参数（executor/driver/shuffle/sql.*） | `dw_base/spark/spark_sql.py` 构造函数 + `.config(...)` 链 | 移入 `conf/spark-defaults.conf`，SQL 文件可用 `SET` 覆盖，见 §2.3 |
 | DataX ini 路径前缀剥离 `conf/datax/config/` | `bin/datax-single-job-starter.sh`（TEMP 处理）、`bin/datax-job-config-generator.py`（`replace('conf/datax/config/', '')`）、`bin/datax-multiple-job-starter.sh`（日志路径派生） | 原目录已整体挪到 `conf/bak/` 并 gitignore，脚本里 replace 现在是 no-op 死逻辑。去除前缀假设，改为靠 ini 文件名（= 任务唯一标识，见 `21-命名规范.md` §3.9）识别用途 |
 | DataX 生成 JSON 输出目录名 `conf/datax/generated` | `bin/datax-job-config-generator.py` 末尾 `default_output_dir`、`bin/datax-single-job-starter.sh` 第 89/118 行、`bin/datax-multiple-job-starter.sh` 第 187 行、`.gitignore` | 目录改名 `conf/datax-json/`；子路径扁平化为 `conf/datax-json/{env}/{ini_basename}.json`（仅按 env 分一级，去掉 src_dst / project_layer_env 等派生层级）；`.gitignore` 同步改 |
 | JOB_NAME / JSON 文件名的 `ini→json` 转换逻辑重复实现 | Python 侧 `bin/datax-job-config-generator.py:126`（`os.path.basename(gcf).replace('.ini', '.json')`）+ Bash 侧 `bin/datax-single-job-starter.sh:88`（`basename .ini`） | 合一到 `dw_base.datax.path_utils.job_name_from_ini()`（或类似工具）；Bash 侧通过 `python3 -c` 调用或在 `bin/common/init.sh` 定义等价 shell 函数，单一来源 |
@@ -64,12 +64,9 @@
 conf/
 ├── env.sh                    # Shell 环境变量（路径、用户、日志目录等）
 ├── env.py                    # Python 环境变量（或直接读 env.sh）
-├── workers.conf              # DataX Worker 列表与权重
+├── workers.ini               # DataX Worker 列表与权重
 ├── alerter.ini               # 告警 Webhook 配置（入库；见 §2.1）
-├── spark-defaults.yaml       # Spark 默认参数
-└── ds/
-    ├── base_config.yaml      # DolphinScheduler 配置
-    └── process_code.yaml     # 工作流编码映射
+└── spark-defaults.conf       # Spark 默认参数（Spark 原生格式）
 ```
 
 ### 2.3 Spark 配置三级覆盖策略
@@ -84,53 +81,55 @@ conf/
 **目标态：三级覆盖**
 
 ```
-conf/spark-defaults.yaml         (L1) 全局默认，运维可改，发版同步到集群
+conf/spark-defaults.conf         (L1) 全局默认，运维可改，发版同步到集群
         ↓ 被覆盖
 SQL 文件内 SET spark.xxx=yyy     (L2) 单作业级别的覆盖，业务开发写
         ↓ 被覆盖
 命令行 -sc key=value / Python 构造函数传参  (L3) 临时/调试 override
 ```
 
-**`conf/spark-defaults.yaml` 草案**：
+**`conf/spark-defaults.conf` 草案**：
 
-```yaml
+沿用 Spark 官方 `$SPARK_HOME/conf/spark-defaults.conf` 的格式：**flat `spark.x.y  value`**，空白分隔，`#` 注释，无 section。好处：运维熟悉、与 `spark-submit --properties-file` 原生兼容、代码侧零映射转换。
+
+```conf
 # 全局 Spark 默认参数，dw_base/spark/spark_sql.py 启动时加载
 # 单作业需要覆盖时，在对应 jobs/*.sql 文件开头写 SET；不要改本文件
 
-executor:
-  instances: 4
-  cores: 4
-  memory: 8g
-  memoryOverhead: 2g
-
-driver:
-  cores: 2
-  memory: 4g
-  maxResultSize: 2g
-
-sql:
-  shuffle.partitions: 200
-  adaptive.enabled: true
-  broadcastTimeout: -1
-  codegen.wholeStage: false
-  execution.arrow.enabled: true
-  execution.arrow.fallback.enabled: true
-  files.ignoreCorruptFiles: true
-  statistics.fallBackToHdfs: true
-
-default:
-  parallelism: 400
+# Executor
+spark.executor.instances                    4
+spark.executor.cores                        4
+spark.executor.memory                       8g
+spark.executor.memoryOverhead               2g
+
+# Driver
+spark.driver.cores                          2
+spark.driver.memory                         4g
+spark.driver.maxResultSize                  2g
+
+# SQL
+spark.sql.shuffle.partitions                200
+spark.sql.adaptive.enabled                  true
+spark.sql.broadcastTimeout                  -1
+spark.sql.codegen.wholeStage                false
+spark.sql.execution.arrow.enabled           true
+spark.sql.execution.arrow.fallback.enabled  true
+spark.sql.files.ignoreCorruptFiles          true
+spark.sql.statistics.fallBackToHdfs         true
+
+# Default parallelism
+spark.default.parallelism                   400
 ```
 
 **代码改动要点**：
 
 1. `dw_base/spark/spark_sql.py`
-   - 新增 `_load_default_config() -> dict`：读 `conf/spark-defaults.yaml`，扁平化为 `{"spark.executor.instances": 4, ...}` 形式（dot-notation 按 yaml 嵌套路径拼）
-   - 构造函数接收的显式参数（`spark_executor_cores` 等）改为 `None` 默认，若未传则 fall back 到 yaml
+   - 新增 `_load_default_config() -> dict`：逐行读 `conf/spark-defaults.conf`，跳过空行与 `#` 注释，首段空白切成 `(key, value)`；key 已是全限定 `spark.x.y`，直接作为 dict key 返回，不做任何变换
+   - 构造函数接收的显式参数（`spark_executor_cores` 等）改为 `None` 默认，若未传则 fall back 到 conf
    - `SparkSession.builder` 的 `.config(...)` 链改成 `for k, v in resolved_config.items(): builder.config(k, v)`
 2. SQL 文件内的 `SET spark.xxx=yyy` 本来就由 `spark.sql(...)` 原生支持，无需改动
 3. 命令行 `-sc` 参数保持现有语义，覆盖 L1
-4. **Python 单测要能跑**：yaml 读取要容错（测试环境下找不到 conf 文件时回退到一套最小内置默认，不阻塞 `tests/unit/`）
+4. **Python 单测要能跑**：conf 读取要容错（测试环境下找不到 conf 文件时回退到一套最小内置默认，不阻塞 `tests/unit/`）
 
 **兼容性**：老代码里已在写 `SparkSQL(spark_executor_cores=8, ...)` 的调用站点不破坏，因为显式传参仍是最高级（L3）。
 
@@ -140,12 +139,12 @@ default:
    - `spark.sql.*`、`spark.default.parallelism` 等运行时参数 —— `spark.conf.set(...)` 或 SQL 内 `SET` 可动态改写
    - `spark.executor.*`、`spark.driver.*`、`spark.executor.memoryOverhead` 等资源类参数 —— **session 启动时锁定**，SQL 里写 `SET spark.executor.memory=16g` 不会真的扩容已启动的 executor
 
-   因此开发写 SQL 内 `SET` 时只能调 `spark.sql.*` 和并行度；需要改资源的场景只能走 L3（命令行 `-sc` 或调用方在构造 `SparkSQL(...)` 时显式传参）。文档里和 `spark-defaults.yaml` 注释里都要讲清楚这条，避免开发以为 `SET spark.executor.memory` 有效。
+   因此开发写 SQL 内 `SET` 时只能调 `spark.sql.*` 和并行度；需要改资源的场景只能走 L3（命令行 `-sc` 或调用方在构造 `SparkSQL(...)` 时显式传参）。文档里和 `spark-defaults.conf` 注释里都要讲清楚这条，避免开发以为 `SET spark.executor.memory` 有效。
 
-2. **`conf/spark-defaults.yaml` 的路径解析依赖 `PROJECT_ROOT_PATH`**，这和 §三 `__init__.py` 瘦身存在先后依赖：
+2. **`conf/spark-defaults.conf` 的路径解析依赖 `PROJECT_ROOT_PATH`**，这和 §三 `__init__.py` 瘦身存在先后依赖：
    - 现状 `PROJECT_ROOT_PATH` 在 `dw_base/__init__.py` 顶部定义，`import dw_base` 就会拿到
-   - 瘦身后 `__init__.py` 只保留最基本路径定义，`PROJECT_ROOT_PATH` 仍可用，但拆分过程中要保证 `spark_sql.py` 加载 yaml 的那行代码拿到的根路径与瘦身前一致
-   - **执行顺序建议**：先做 §三 `__init__.py` 瘦身，把 `PROJECT_ROOT_PATH` 的定义稳定下来；再做 §2.3 的 `spark-defaults.yaml` 接入。反过来做会踩到"瘦身后路径变了"的返工
+   - 瘦身后 `__init__.py` 只保留最基本路径定义，`PROJECT_ROOT_PATH` 仍可用，但拆分过程中要保证 `spark_sql.py` 加载 conf 的那行代码拿到的根路径与瘦身前一致
+   - **执行顺序建议**：先做 §三 `__init__.py` 瘦身，把 `PROJECT_ROOT_PATH` 的定义稳定下来；再做 §2.3 的 `spark-defaults.conf` 接入。反过来做会踩到"瘦身后路径变了"的返工
 
 **与仓库改名的联动**：
 

kb/92-重构进度.md

@@ -62,16 +62,16 @@
 - [ ] 新建项目根 `.gitignore`（清单与注意事项见 `90-重构路线.md` §2.4）
 - [ ] 建立 `conf/env.sh`（Shell 环境变量）
 - [ ] 建立 `conf/env.py` 或 Python 读 `env.sh` 的桥接
-- [ ] 建立 `conf/workers.conf`（DataX Worker 列表 + 权重 map，整体迁出 `bin/common/init.sh:18-31`）
+- [ ] 建立 `conf/workers.ini`（DataX Worker 列表 + 权重 map，整体迁出 `bin/common/init.sh:18-31`）
 - [ ] 建立 `conf/alerter.ini`（企微 Webhook，**入库**；格式见 `90-重构路线.md` §2.1）
 - [ ] `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 / 构造函数传参) 三级覆盖
+- [ ] 建立 `conf/spark-defaults.conf`（Spark 全局默认参数，Spark 原生格式，见 `90-重构路线.md` §2.3）
+- [ ] 改造 `dw_base/spark/spark_sql.py`：构造函数 fall back 到 conf；实现 L1(conf) < 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)` + 权重 map 迁入 `conf/workers.conf`
+- [ ] `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 各一份，单一来源）
@@ -164,3 +164,4 @@
 | 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 前瞻文档，属于此前"默默做完"漏记，本次补 | — |