docs: 合并 kb/README 进根 README

README.md

@@ -2,6 +2,13 @@
 
 基于 PySpark + DataX 的数据仓库项目，负责多源数据采集、清洗、分层加工和分发。
 
+> 本 README 兼作**开发手册**，也是 **vibe coding 和 Review 的参考依据**。
+
+## 项目现状速读（冷启动必读）
+
+- **`launch-pad/` 不做业务迁移**：里面是上个项目（与当前业务无关）的历史业务代码，仅作**样板 SQL / DataX ini 写法的参考**，新项目业务 SQL 全部从零开发，完成后 `launch-pad/` 整体删除
+- **重构进度**：进度追踪见 `kb/92-重构进度.md`
+
 ## 技术栈
 
 - **计算引擎**：PySpark 2.4 on YARN (CDH 6.3.2)
@@ -54,6 +61,61 @@ PG/ES ──DataX(raw)──> RAW ──> ODS ──> DWD ──> DWS ──> TD
 - Python 3.6.8，依赖见 `requirements.txt`
 - 部署：`publish.sh` 通过 git pull + rsync 分发到集群各节点
 
-## 文档
+## 文档索引
+
+文件按编号前缀分组，序号越小越基础、越靠前阅读。
+
+### 0x 项目与环境
+
+| 文档 | 内容                                               |
+|----|--------------------------------------------------|
+| [00-项目架构](kb/00-项目架构.md) | 模块关系图、Spark SQL / DataX 执行时序、DataX 脚本详细使用说明、配置管理 |
+| [01-运行环境](kb/01-运行环境.md) | CDH 技术栈版本、平台架构图、开发侧约束                            |
+| [02-权限与账号](kb/02-权限与账号.md) | 鉴权链路、job账号 vs 个人账号
+
+### 1x 业务上下文
+
+| 文档 | 内容 |
+|----|----|
+| [10-业务流程](kb/10-业务流程.md) | Hobby Stocks 用户侧 + 商家侧 + 售后全链路流程图 |
+| [11-数据资产](kb/11-数据资产.md) | 业务库、埋点数据、爬虫数据、采购数据清单 |
+| [12-同步方案](kb/12-同步方案.md) | PG → Hive 存量/增量/历史归档/CDC 同步策略与阶段演进 |
+
+### 2x 数仓建模
+
+| 文档 | 内容 |
+|----|----|
+| [20-数仓分层与建模](kb/20-数仓分层与建模.md) | 分层定义、主题域、总线矩阵、维度建模五步法、同步策略 |
+| [21-命名规范](kb/21-命名规范.md) ★ | 五段式表名、字段规则、词根字典、建表自检 Checklist |
+| [22-指标体系](kb/22-指标体系.md) | 指标分类、逻辑结构、指标/维度/度量字典 |
+| [23-标签体系](kb/23-标签体系.md) | TDM 层用户/商品/商家画像设计 |
+
+### 3x 开发流程
+
+| 文档 | 内容 |
+|----|----|
+| [30-开发规范](kb/30-开发规范.md) | TPAD 任务规范、数仓数据开发流程、代码 / SQL 规范、Git 协作规范 |
+| [31-UDF手册](kb/31-UDF手册.md) | UDF 自查表 |
+
+### 9x 过渡资料
+
+| 文档 | 内容 |
+|----|----|
+| [90-重构路线](kb/90-重构路线.md) | 基于老项目代码分析的重构路线（P0-P3） |
+| [92-重构进度](kb/92-重构进度.md) | 重构任务 checklist 与当前进度 |
+
+## 阅读建议
+
+**新成员上手路径：**
+1. [00-项目架构](kb/00-项目架构.md) — 了解模块全貌
+2. [01-运行环境](kb/01-运行环境.md) — 了解基础设施
+3. [20-数仓分层与建模](kb/20-数仓分层与建模.md) — 了解建模方法论
+4. [21-命名规范](kb/21-命名规范.md) — 熟悉命名规则（★ 最高频参考）
+5. [30-开发规范](kb/30-开发规范.md) — 熟悉开发流程
+
+**样板（待补充）：**
 
-详细文档见 `kb/` 目录
+- 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`

kb/90-重构路线.md

@@ -130,7 +130,7 @@ D 基础设施 ─────┘
 | 导出类 ini 扇出撞名风险 | `jobs/ads/{域}/` 下 ini 若都以源 Hive 表名命名，同一张 ads 表扇出到多个目标库时会重名覆盖 | 命名规则改为 `{源 Hive 表名}__{目标 db_type}_{目标 instance}.ini`（双下划线分隔源/目标），见 `21-命名规范.md` §3.9 |
 | `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}` 双扩展名。与上条废弃的运行时模板完全不同：这里的模板不被任何代码读取，只供开发者对照写新文件；`kb/README.md` 已加入口 |
+| 缺少集中的开发者参考模板目录 | —（新增） | 已建 `conf/templates/{datasource,datax/{raw,ads,manual},sql,ddl}/`，模板用 `*.template.{ini,sql}` 双扩展名。与上条废弃的运行时模板完全不同：这里的模板不被任何代码读取，只供开发者对照写新文件；项目根 `README.md` 已加入口 |
 
 ### 2.2 建议的配置结构
 
@@ -619,6 +619,7 @@ if name in self.REGISTERED_UDF:
 | `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 |
+| `kb/README.md` | 整文件删，内容合入项目根 `README.md`（项目现状速读 / 文档索引 / 阅读建议三节），CLAUDE.md 引用同步更新 | 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` |
 
@@ -728,10 +729,6 @@ else:
 
 **后续处理**：若 HMS 未挂 Ranger Hive，调研补挂成本 + 评估现有 HDFS 兜底是否足够（大部分数仓读写场景下足够，因为 PySpark 任务绝大多数以受控 Unix 账号提交、权限粒度粗即可；若要满足敏感列屏蔽类需求则必须补挂）。
 
-### 7.6 项目 README 整合（低优先级）
-
-根 `README.md` 与 `kb/README.md` 内容冗余。后续把根 README 收缩为一行指向 `kb/README.md`，技术栈 / 目录结构 / 执行入口等细节统一由 `kb/` 承载。
-
 ## 八、聚簇推进视图
 
 替换原 P0-P3 线性优先级表。按聚簇 A-F 组织（定义见 §〇），同一聚簇内部不强排序，跨聚簇只标强依赖。

kb/README.md

@@ -1,71 +0,0 @@
-# poyee-data-warehouse 知识库
-
-> `kb/` 是 `poyee-data-warehouse` 数据仓库项目的知识库。
-> 是**开发手册**，也是 **vibe coding 和 Review 的参考依据**。
-
-## 项目现状速读（冷启动必读）
-
-- **`launch-pad/` 不做业务迁移**：里面是上个项目（与当前业务无关）的历史业务代码，仅作**样板 SQL / DataX ini 写法的参考**，新项目业务 SQL 全部从零开发，完成后 `launch-pad/` 整体删除
-- **重构进度**：进度追踪见 `92-重构进度.md`
-
-## 文档分组
-
-文件按编号前缀分组，序号越小越基础、越靠前阅读。
-
-## 文档索引
-
-### 0x 项目与环境
-
-| 文档 | 内容                                               |
-|----|--------------------------------------------------|
-| [00-项目架构](00-项目架构.md) | 模块关系图、Spark SQL / DataX 执行时序、DataX 脚本详细使用说明、配置管理 |
-| [01-运行环境](01-运行环境.md) | CDH 技术栈版本、平台架构图、开发侧约束                            |
-| [02-权限与账号](02-权限与账号.md) | 鉴权链路、job账号 vs 个人账号
-
-### 1x 业务上下文
-
-| 文档 | 内容 |
-|----|----|
-| [10-业务流程](10-业务流程.md) | Hobby Stocks 用户侧 + 商家侧 + 售后全链路流程图 |
-| [11-数据资产](11-数据资产.md) | 业务库、埋点数据、爬虫数据、采购数据清单 |
-| [12-同步方案](12-同步方案.md) | PG → Hive 存量/增量/历史归档/CDC 同步策略与阶段演进 |
-
-### 2x 数仓建模
-
-| 文档 | 内容 |
-|----|----|
-| [20-数仓分层与建模](20-数仓分层与建模.md) | 分层定义、主题域、总线矩阵、维度建模五步法、同步策略 |
-| [21-命名规范](21-命名规范.md) ★ | 五段式表名、字段规则、词根字典、建表自检 Checklist |
-| [22-指标体系](22-指标体系.md) | 指标分类、逻辑结构、指标/维度/度量字典 |
-| [23-标签体系](23-标签体系.md) | TDM 层用户/商品/商家画像设计 |
-
-### 3x 开发流程
-
-| 文档 | 内容 |
-|----|----|
-| [30-开发规范](30-开发规范.md) | TPAD 任务规范、数仓数据开发流程、代码 / SQL 规范、Git 协作规范 |
-| [31-UDF手册](31-UDF手册.md) | UDF 自查表 |
-
-### 9x 过渡资料
-
-| 文档 | 内容 |
-|----|----|
-| [90-重构路线](90-重构路线.md) | 基于老项目代码分析的重构路线（P0-P3） |
-| [92-重构进度](92-重构进度.md) | 重构任务 checklist 与当前进度 |
-
-## 阅读建议
-
-**新成员上手路径：**
-1. [00-项目架构](00-项目架构.md) — 了解模块全貌
-2. [01-运行环境](01-运行环境.md) — 了解基础设施
-3. [20-数仓分层与建模](20-数仓分层与建模.md) — 了解建模方法论
-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`
-- 数据源连接样板 → `conf/templates/datasource/*.template.ini`
-