refactor(conf/templates): 样板目录按引擎顶层分 + README 样板段迁入 kb/30 §6

conf/templates/{datasource,datax/{raw,ads,manual},sql,ddl}/
→ conf/templates/{datax/{datasource,sync},spark/{sql,ddl}}/；
已备 3 份 datasource ini 随迁；README 样板段替换为链接，kb/30 新增 §6 开发样板
（原 §6 相关文档 → §7）。

README.md

@@ -108,9 +108,4 @@ PG/ES ──DataX(raw)──> RAW ──> ODS ──> DWD ──> DWS ──> TD
 4. [21-命名规范](kb/21-命名规范.md) — 熟悉命名规则（★ 最高频参考）
 5. [30-开发规范](kb/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`
-- 数据源连接样板 → `conf/templates/datasource/*.template.ini`（已备：postgresql / hdfs / hdfs-ha）
+**开发样板**：`conf/templates/` 下按引擎分 datax / spark 两类，详见 [30-开发规范 §6](kb/30-开发规范.md#6-开发样板)。

kb/30-开发规范.md

@@ -327,7 +327,23 @@ flowchart LR
    - 临时取数给业务方 → `manual/adhoc/`
    - 脏数据订正 → `manual/fix/`，必须附 TPAD 工单号
 
-## 6. 相关文档
+## 6. 开发样板
+
+`conf/templates/` 下按**引擎**分顶层，模板供开发者照抄写新文件，不被任何代码读取。
+
+| 类别 | 目录 | 说明 |
+|------|------|------|
+| DataX 数据源连接 | `conf/templates/datax/datasource/` | 源 ini 样板（已备 postgresql / hdfs / hdfs-ha），对应项目根 `datasource/{db_type}/{env}-{实例简称}.ini` |
+| DataX 同步作业 | `conf/templates/datax/sync/` | sync ini 样板，对应 `jobs/raw/` / `jobs/ads/` / `manual/` 下的 DataX 作业 |
+| Spark SQL 作业 | `conf/templates/spark/sql/` | 各层 `INSERT OVERWRITE` 样板 |
+| Spark 建表 DDL | `conf/templates/spark/ddl/` | 各层 `CREATE EXTERNAL TABLE ... STORED AS ORC` 样板 |
+
+**约定**：
+
+- 文件名用双扩展名 `*.template.{ini,sql}`，避免被 DataX / Spark SQL 引擎误拾
+- 新增样板归到对应子目录；新增引擎类时顶层并列目录
+
+## 7. 相关文档
 
 - [命名规范](21-命名规范.md)
 - [数仓分层与建模](20-数仓分层与建模.md)

kb/90-重构路线.md

@@ -119,7 +119,7 @@ D 基础设施 ─────┘
 | 导出类 ini 扇出撞名风险 | `jobs/ads/{域}/` 下 ini 若都以源 Hive 表名命名，同一张 ads 表扇出到多个目标库时会重名覆盖 | 命名规则改为 `{源 Hive 表名}__{目标 db_type}_{目标 instance}.ini`（双下划线分隔源/目标） |
 | `dw_base/common/template_constants.py` 大量死代码 | 定义了 20+ 个 SQL 模板路径常量，实际只有 2 个（`MYSQL_HIVE_CREATE_TABLE_TEMPLATE` / `MYSQL_HIVE_HBASE_CREATE_TABLE_TEMPLATE`）被引用，其余 18 个零 import | 整个文件删除；连带废弃下一条 |
 | `MySQLReader.generate_hive_ddl()` / `generate_hive_over_hbase_ddl()` 自动建表 DDL 路径 | `dw_base/datax/plugins/reader/mysql_reader.py:195/222`，被 `bin/datax-gc-generator.py:616/728` 调用；且 `conf/template/` 目录在新项目根本不存在，真调用会 FileNotFoundError | 整段路径废弃——与 CLAUDE.md 约定的 `manual/ddl/` 是 DDL 唯一来源相冲突。`datax-gc-generator.py` 仅生成 ini 配置，不再输出 CREATE TABLE DDL；DDL 由开发者按 `21-命名规范.md` 手写到 `manual/ddl/` |
-| 缺少集中的开发者参考模板目录 | —（新增） | 已建 `conf/templates/{datasource,datax/{raw,ads,manual},sql,ddl}/`，模板用 `*.template.{ini,sql}` 双扩展名。与上条废弃的运行时模板完全不同：这里的模板不被任何代码读取，只供开发者对照写新文件；项目根 `README.md` 已加入口 |
+| 缺少集中的开发者参考模板目录 | —（新增） | 已建 `conf/templates/{datax/{datasource,sync},spark/{sql,ddl}}/`，模板用 `*.template.{ini,sql}` 双扩展名。与上条废弃的运行时模板完全不同：这里的模板不被任何代码读取，只供开发者对照写新文件；入口见 `kb/30-开发规范.md §6` |
 
 ### 2.2 建议的配置结构
 

kb/92-重构进度.md

@@ -182,4 +182,5 @@
 | 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` | — |