docs(kb): 清理陈旧内容并同步模块变动

kb/00-项目架构.md

@@ -3,7 +3,7 @@
 > `poyee-data-warehouse` 数据仓库工程的模块划分、执行时序与配置管理。
 
 **项目状态**：重构中，目前采用**原地渐进式重构**模式。
-## 1. 目录结构（目标态）
+## 1. 目录结构（更新中）
 
 ```
 poyee-data-warehouse/              # 项目根目录（仓库名 = 部署名）
@@ -37,16 +37,15 @@ poyee-data-warehouse/              # 项目根目录（仓库名 = 部署名）
 │   ├── 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）
+│   ├── ops/                       #   （占位）仓内数据运维（小文件合并、分区清理）
 │   ├── dq/                        #   （占位）数据质量检查（schema drift、值域、关联、规模）
 │   ├── pm/                        #   （占位）项目管理工具集成（TAPD / Jira API）
-│   └── sync/                      #   （占位）外部文档同步（Docmost → kb/inbox）
+│   └── wiki/                      #   （占位）外部文档同步（Docmost → kb/inbox）
 ├── kb/                            # 知识库：项目文档
 ├── conf/                          # 配置层（非敏感配置入库：alerter.ini / workers.ini / datax-speed.ini / spark-defaults.conf 等）
-├── tests/                         # 测试：unit/ 纯函数单测 + integration/ Spark local[*] 集成测试
+├── tests/                         # 测试：unit/ 纯函数单测 + integration/ Spark datax 集成测试
 ├── requirements.txt               # Python 依赖
 └── README.md
 ```
@@ -75,72 +74,17 @@ poyee-data-warehouse/              # 项目根目录（仓库名 = 部署名）
     └── hbase/
 ```
 
-## 2. 核心模块职责
 
-模块职责已并入 §1 目录结构的行尾注释，不再单独列表（避免目录变动时多处同步）。
 
 ## 3. 模块关系图
 
-> 待 `dw_base/` 基础模块（`io/` / `ops/` / `dq/` / `pm/` / `sync/` 等占位）实装后重绘。当前过渡期保留此小节标题占位。
+待补充
 
 ## 4. 执行链详解
 
-### 4.1 Spark SQL 执行链
-
-```mermaid
-sequenceDiagram
-    participant DS as DolphinScheduler
-    participant BIN as spark-sql-starter.py
-    participant INIT as dw_base/__init__.py
-    participant CFG as utils/config_utils.py
-    participant SQL_ENGINE as spark/spark_sql.py
-    participant HIVE as Hive/YARN
-
-    DS->>BIN: 调用 -f sql文件 -dt 20250101
-    BIN->>INIT: import（环境检测 + findspark）
-    BIN->>CFG: parse_args() 解析参数
-    BIN->>SQL_ENGINE: SparkSQL(session_name, udf_files, ...)
-    SQL_ENGINE->>SQL_ENGINE: 读取 SQL 文件，解析 SET/ADD FILE
-    SQL_ENGINE->>SQL_ENGINE: zip -qr dw_base.zip dw_base
-    SQL_ENGINE->>HIVE: SparkSession.builder.enableHiveSupport()
-    SQL_ENGINE->>SQL_ENGINE: 注册 UDF（反射扫描函数）
-    loop 按日期循环
-        SQL_ENGINE->>SQL_ENGINE: 替换 ${dt} 等参数
-        SQL_ENGINE->>HIVE: spark.sql(sql_statement)
-        HIVE-->>SQL_ENGINE: DataFrame
-        SQL_ENGINE->>SQL_ENGINE: show / 记录日志
-    end
-```
-
-### 4.2 DataX 数据同步执行链
-
-```mermaid
-sequenceDiagram
-    participant DS as DolphinScheduler
-    participant MULTI as datax-multiple-job-starter.sh
-    participant SINGLE as datax-single-job-starter.sh
-    participant GEN as datax-job-config-generator.py
-    participant ENGINE as datax/job_config_generator.py
-    participant PLUGIN as plugins/plugin_factory.py
-    participant DS_FILE as datasource/*.ini
-    participant DATAX as DataX (python datax.py)
-
-    DS->>MULTI: -gc ini文件 -start-date -stop-date
-    MULTI->>SINGLE: 逐个/并行调用
-    SINGLE->>SINGLE: select_worker() 选择执行节点
-    SINGLE->>GEN: 调用生成器
-    GEN->>ENGINE: JobConfigGenerator(ini, start, stop, output)
-    ENGINE->>ENGINE: ConfigParser 读取 .ini
-    ENGINE->>PLUGIN: PluginFactory.get_plugin(reader/writer)
-    PLUGIN->>DS_FILE: 读取数据源 ini（账密等）
-    PLUGIN-->>ENGINE: reader/writer JSON 片段
-    ENGINE->>ENGINE: 组装完整 JSON + 限速配置
-    ENGINE->>ENGINE: 写入 conf/datax/generated/*.json
-    SINGLE->>DATAX: python datax.py generated.json
-    DATAX->>DATAX: 执行数据同步
-```
-
-### 4.3 DataX 脚本详细使用说明
+待补充
+
+### 4.3 DataX 脚本详细使用说明 （即将重构）
 
 DataX 脚本分为**执行脚本**和**辅助工具**两类，调用链如下：
 

kb/30-开发规范.md

@@ -328,7 +328,7 @@ flowchart LR
 **反例**（会被 reject）：
 
 - `update` / `修改` / `提交` —— 没有 type，描述空洞
-- `feat: xxx\nfix: yyy\ndocs: zzz` —— 一条 commit 混多个 type
+- `feat: xxx fix: yyy docs: zzz` —— 一条 commit 混多个 type
 - `feat: 新增了一大堆表` —— scope 和具体目标不明
 
 ## 4. 测试规范

kb/90-重构路线.md

@@ -14,7 +14,7 @@
 | **A** | 配置外移 / 硬编码清理 | `conf/env.sh` / `workers.ini` / `alerter.ini` / `spark-defaults.conf` / `datax-speed.ini` / datasource 多环境 / DataX 路径解耦 | 阶段 2 主体 |
 | **B** | `dw_base/` 重组 | B1 `__init__.py` 瘦身 · B2 `common/utils/io/ops` 四模块边界定稿 · B3 代码风格修正（`__contains__` / SQL 注入 / Shell-Python 重复） · B4 新占位模块 registry | 阶段 2 / 4 混合 |
 | **C** | `bin/` 入口收口 | `datax-import` / `datax-export` 两命令收口 · `datax-gc-generator` 从零重写 · `csv-to-hdfs-starter` 实现 · `publish.sh` 已入 `bin/` | 阶段 1 尾 + 阶段 2 |
-| **D** | 基础设施 | `tests/` 测试体系 · 告警模块重写 · 日志模块统一 · `dq/` 数据质量 · `sync/` Docmost · `pm/` 项目管理集成 | 阶段 2 / 4 |
+| **D** | 基础设施 | `tests/` 测试体系 · 告警模块重写 · 日志模块统一 · `dq/` 数据质量 · `wiki/` Docmost · `pm/` 项目管理集成 | 阶段 2 / 4 |
 | **E** | 业务 SQL 从零开发 | `jobs/{raw,ods,dwd,dws,tdm,ads}/` · DS 工作流 | 阶段 3 |
 | **F** | 老代码删除 | `launch-pad/` 整删 · 其他已确认废弃 | 阶段 5 |
 
@@ -520,19 +520,17 @@ record_per_channel = 100000
 
 ### 2.11 新占位模块 registry（B4） [聚簇 B（B4）]
 
-2026-04-20 本批建立的占位模块（空骨架 + README，实现待后续阶段），登记在此便于跨会话追踪：
+2026-04-20 本批建立的占位模块（空骨架，实现待后续阶段），登记在此便于跨会话追踪：
 
 | 模块 | 路径 | 状态 | 何时实现 | 对应阶段 |
 |------|------|------|----------|---------|
-| `io/` | `dw_base/io/{db,file,hdfs}/` | 骨架 | B2 四模块边界定稿后，搬入 `mysql_utils` + 文件读写 | 阶段 2 |
+| `io/` | `dw_base/io/{db,file,hdfs}/` | 骨架 | B2 四模块边界定稿后，搬入 db/file/hdfs 读写封装 | 阶段 2 |
 | `ops/` | `dw_base/ops/` | 骨架 | 阶段 4 随"重新实现小文件合并 / 分区保留工具"落地 | 阶段 4 |
 | `pm/` | `dw_base/pm/` | 骨架 | 待确认 TAPD vs Jira 后实现（commit → 任务 ID 联动） | 阶段 4 之后 |
 | `dq/` | `dw_base/dq/` | 骨架 | 待确认告警落点 + 首批规则后实现 | 阶段 4 |
-| `sync/` | `dw_base/sync/` | 骨架 | 待确认 Docmost API 鉴权 / webhook 支持后实现 | 阶段 4 之后 |
+| `wiki/` | `dw_base/wiki/` | 骨架 | 待确认 Docmost API 鉴权 / webhook 支持后实现 | 阶段 4 之后 |
 | `tests/` | `tests/{unit,integration}/` | 骨架 | 阶段 4 首批 UDF 单测启动时同步补 `conftest.py` + fixtures | 阶段 4 |
 
-**标准**：每个占位模块必须带 README，4 节（职责 / 接口 / 依赖 / 状态）—— 规则见项目根 `CLAUDE.md`（架构规划专用约定，普通开发不涉及）。空 `__init__.py` + 无 README 直接删除，不保留"暂留"。
-
 ### 2.12 通用 UDF 注释完整化 + 自查表（B 延伸） [聚簇 B]
 
 **现状**：`dw_base/udf/common/spark_common_udf.py` 500 行 40 函数由 6 份老文件合并而来（见 `kb/92` 2026-04-20 UDF 重组条目），函数签名齐全但注释粗细不一：部分函数只有函数名，部分 docstring 写了逻辑但没写入参约束 / 返回类型 / 异常路径 / SQL 调用示例。`common/` 目录 UDF 由 `bin/spark-sql-starter.py` 自动 `ADD FILE` 注册（启动日志 40 条 `注册 Python UDF xxx` 可证），理论上任意 SQL 都能用，但"能用"不等于"知道怎么用"。
@@ -603,15 +601,6 @@ if name in self.REGISTERED_UDF:
 
 **建议：** 统一由 Python 入口处理，Shell 脚本仅做最小化的环境设置后调用 Python。或提取为一份共享的配置文件。
 
-### 4.3 SQL 注入风险
-
-`mysql_utils.py` 中使用 f-string 拼接 SQL：
-```python
-sql = "... WHERE TABLE_SCHEMA='%s' ..." % (database, table_name)
-```
-
-**建议：** 改用参数化查询。
-
 ## 五、清理废弃代码（中优先级） [聚簇 F]
 
 截至 2026-04-20 本节已无待清理项。后续若发现新的废弃代码，在下方表格追加登记；已完成项保留在"历史档案"表中留档。
@@ -628,6 +617,8 @@ sql = "... WHERE TABLE_SCHEMA='%s' ..." % (database, table_name)
 |----------|---------|----------------|
 | `dw_base/{validation,ml,flink,elasticsearch}/` 四空壳模块 | 整目录删（仅 56 字节空 `__init__.py`，零引用） | 2026-04-20，见 `92-进度.md` |
 | `dw_base/database/mongodb_utils.py` | 整文件删（184 行 = 19 行 MongoClient 薄包装 + 165 行注释，零外部引用，需要时 `MongoClient(uri)` 一行重写） | 2026-04-20，见 `92-进度.md` |
+| `dw_base/database/` 整目录 | 整目录删（`__init__.py` + 仅剩的 `mysql_utils.py`，zero 外部引用；mysql 读写后续在 `dw_base/io/db/` 下重建） | 2026-04-21 |
+| 5 个占位模块 README（`dq/` `io/` `ops/` `pm/` `sync/`） | 批量删，占位模块 docstring 即文档，不再要求单独 README | 2026-04-21 |
 | `conf/datax/` 下老项目遗留 ini / datasource 样例 | 整批挪入 `conf/bak/datax/{config,datasource}/`，由 `.gitignore:6 conf/bak` 拦截不入库 | 项目初始化 `8d2ade5`（2026-04-17） |
 | `bin/flume-control.sh` | 整文件删（194 行）。职责：管理单个 Flume-Kafka-HDFS 作业生命周期（log/monitor/start/status/stop/restart/start-all/stop-all/restart-all 一组子命令）。实际状态：顶部 shebang 损坏（`ho#!/bin/bash`）、依赖已删除的 `bin/wechat-work-alert.sh`、L64 与 L162 `conf/flume/*.properties` vs `conf/flume/config/*.properties` 路径自相矛盾，整体已不可跑。按需重建时参考：`conf/flume/config/*.properties` 为作业配置约定、`flume-ng agent --conf-file` 为启动命令、启动前需 `mkdir -p ${LOG_ROOT_DIR}/flume-agent/${TODAY}`、监控循环 `head -n 1000 log | grep -E "gz failed\|java.io.IOException\|org.apache.flume.ChannelException\|java.lang.IllegalStateException"` 命中则发企微告警。Kafka→HDFS 接入通道重建时按新 `conf/alerter.ini` 告警外配重写，不沿用老 SKB_LITTLE_CUTE / 手机号硬编码 | 2026-04-21，见 `92-进度.md` |
 
@@ -766,8 +757,8 @@ else:
 | **B2** `common/utils/io/ops` 四模块边界定稿 | 待启动 | — | §2.10 |
 | **B3** `__contains__` → `in` 全局替换 | 待启动 | — | §4.1 |
 | **B3** Shell/Python 环境检测去重（`bin/common/init.sh` ↔ `dw_base/__init__.py`） | 待启动 | B1 | §4.2 |
-| **B3** `mysql_utils.py` SQL 注入修复 | 待启动 | —（该文件在 §2.7 `datax-gc-generator` 重写时一并重造，可能被废） | §4.3 |
-| **B4** 新占位模块 `io/` / `ops/` / `pm/` / `dq/` / `sync/` 骨架 + README | ✅ 2026-04-20 已建 | B2 边界规则先立 §2.10 | §2.11 |
+| **B3** `mysql_utils.py` SQL 注入修复 | ✅ 2026-04-21 随 `dw_base/database/` 整目录删自动完成；mysql 读写后续在 `dw_base/io/db/` 下重造 | — | 见 §5.2 |
+| **B4** 新占位模块 `io/` / `ops/` / `pm/` / `dq/` / `wiki/` 骨架 | ✅ 2026-04-20 已建（2026-04-21 去掉各模块 README，docstring 即文档） | B2 边界规则先立 §2.10 | §2.11 |
 
 ### C `bin/` 入口收口
 
@@ -792,7 +783,7 @@ else:
 | 分区保留工具重新实现（元表驱动 + 参数化） | 待启动 | **B2** → `ops/` | 阶段 4 |
 | `dq/` 数据质量规则首批 + runner | 待启动 | `conf/alerter.ini` 就绪 | §2.11 |
 | `pm/` TAPD / Jira 集成（commit → 任务 ID） | 待启动 | 确认平台选型 | §2.11 |
-| `sync/` Docmost → `kb/inbox/` | 待启动 | Docmost API 鉴权确认 | §2.11 |
+| `wiki/` Docmost → `kb/inbox/` | 待启动 | Docmost API 鉴权确认 | §2.11 |
 | Ranger Hive 策略验证（集群侧） | 待启动 | — | §7.5 |
 
 ### E 业务 SQL 从零开发（阶段 3）

kb/README.md

@@ -6,8 +6,7 @@
 ## 项目现状速读（冷启动必读）
 
 - **`launch-pad/` 不做业务迁移**：里面是上个项目（与当前业务无关）的历史业务代码，仅作**样板 SQL / DataX ini 写法的参考**，新项目业务 SQL 全部从零开发，完成后 `launch-pad/` 整体删除
-- **`tendata/` → `dw_base/`**：这是重构核心映射，需要修改模块名 + 所有 `from tendata ...` import、`ADD FILE tendata/...`、`tendata.zip` 打包命令等引用（详见 `90-重构路线.md` §1.1）
-- **重构进度**：刚起步，kb 文档梳理完成，代码层面尚未动工。进度追踪见 `92-重构进度.md`
+- **重构进度**：进度追踪见 `92-重构进度.md`
 
 ## 文档分组
 
@@ -44,8 +43,8 @@
 
 | 文档 | 内容 |
 |----|----|
-| [30-开发规范](30-开发规范.md) | TPAD 任务规范、数仓数据开发流程、代码 / SQL 规范、Git 协作规范（IDE 格式化 scheme 见 `conf/sql_style.xml`） |
-| [31-UDF手册](31-UDF手册.md) | `dw_base/udf/common/` 下通用 UDF 自查表与准入规则 |
+| [30-开发规范](30-开发规范.md) | TPAD 任务规范、数仓数据开发流程、代码 / SQL 规范、Git 协作规范 |
+| [31-UDF手册](31-UDF手册.md) | UDF 自查表 |
 
 ### 9x 过渡资料
 
@@ -63,8 +62,8 @@
 4. [21-命名规范](21-命名规范.md) — 熟悉命名规则（★ 最高频参考）
 5. [30-开发规范](30-开发规范.md) — 熟悉开发流程
 
+**样板（待补充）：**
 
-**查样板：**
 - DataX ini 样板 → `conf/templates/datax/{raw,ads,manual}/*.template.ini`
 - Spark SQL 样板 → `conf/templates/sql/*.template.sql`
 - 建表 DDL 样板 → `conf/templates/ddl/*.template.sql`