docs(kb): 新建 kb/31 UDF 手册骨架

kb/31-UDF手册.md

@@ -0,0 +1,16 @@
+# UDF 手册
+
+`dw_base/udf/common/` 下通用 UDF 的自查表：每次增删 / 重命名 / 改签名时同步更新本表。
+业务专用 UDF 放 `dw_base/udf/business/`，不走本表，由各 business 子目录自己的 README 维护。
+
+## 1. 准入规则
+
+待通用 UDF 注释统一化首版落地、本表登记全量函数后写入。
+
+## 2. 自查表
+
+| 函数名 | 分类 | 入参 | 返回 | 摘要 | 代码位置 | 补注释状态 |
+|--------|------|------|------|------|----------|------------|
+| — | — | — | — | — | — | — |
+
+> 分类由 `dw_base/udf/common/spark_common_udf.py` 中的实际划分为准；本表行数应等于 `spark_common_udf.py` 中导出的 UDF 函数数（启动日志里 `注册 Python UDF` 的条数即真值）。

kb/90-重构路线.md

@@ -552,9 +552,9 @@ record_per_channel = 100000
 
 1. **注释完整化**：40 函数全部补齐 docstring，统一 5 段模板 —— 一句话摘要 / 入参（名 · 类型 · 约束 / 可空 / 单位） / 返回（类型 · 语义 · 空值场景） / 异常与边界 / SQL 调用示例。按分类分批推进：JSON 段 → Array 段 → String 段 → Numeric-Date-Hash 段 → Cross-type 段，5 批独立 commit。
 
-2. **UDF 自查表**：新建 `kb/31-UDF 手册.md`（与 `30-开发规范.md` 同级独立文档；40 函数规模独立成文更稳，新增 UDF 需要稳定引用锚点）。表头 `函数名 | 分类 | 入参 | 返回 | 摘要 | 代码位置 | 补注释状态`。初版把现有 40 函数全量登记，后续新增通用 UDF（进 `common/`）必须同步登记此表；只进 `business/` 的 UDF 不走此表，在 `business/` 子目录 README 维护。
+2. **UDF 自查表**：新建 `kb/31-UDF手册.md`（与 `30-开发规范.md` 同级独立文档；40 函数规模独立成文更稳，新增 UDF 需要稳定引用锚点）。表头 `函数名 | 分类 | 入参 | 返回 | 摘要 | 代码位置 | 补注释状态`。初版把现有 40 函数全量登记，后续新增通用 UDF（进 `common/`）必须同步登记此表；只进 `business/` 的 UDF 不走此表，在 `business/` 子目录 README 维护。
 
-3. **注册准入规则**：`kb/30-开发规范.md` 新增一节或 `CLAUDE.md` 一行硬约束 —— 向 `common/` 增删 UDF 前，先读 `kb/31` 自查表；新增必须同步更新表（函数名 / 分类 / 示例），否则 commit 不过。与 `tests/unit/udf/test_spark_common_udf.py`（阶段 4 首批单测目标，见 §2.11 占位 registry）是配套的：自查表为开发者服务，单测为回归服务。
+3. **注册准入规则**：在 `kb/30-开发规范.md` 新增一节或 `kb/31-UDF手册.md` 内嵌一节写硬约束 —— 向 `common/` 增删 UDF 前，先读 `kb/31` 自查表；新增必须同步更新表（函数名 / 分类 / 示例），否则 commit 不过。与 `tests/unit/udf/test_spark_common_udf.py`（阶段 4 首批单测目标，见 §2.11 占位 registry）是配套的：自查表为开发者服务，单测为回归服务。
 
 **回归检验**：
 - 任意 SQL 文件直接 `SELECT my_udf(col)` 能跑通（common auto-load 链路未变，保留现状）

kb/92-重构进度.md

@@ -183,3 +183,4 @@
 | 2026-04-21 | **kb/30 §4.6 整合 Git 协作规范**：`kb/inbox/git规范.md` 草稿 6 章整合进 kb/30 §4.6（§4.5 与 §5 之间），节号重排为 §4.6.1~§4.6.6 对齐现有多级风格；草稿 §六 "命名规范" 改名为 "分支 / Tag 命名" 避开与 `kb/21-命名规范.md` 主文档重名；补分支/hotfix/tag 命名示例到各 3 个（个人分支 3 个与 §4.6.1.2 ASCII 图的李四/王五/张三对齐） | — |
 | 2026-04-21 | **kb/30 大梳理：删 §1 通用开发流程 / §4.5 占位模块规范，Commit 信息归入 Git 协作节，整体节号重排**：(a) 删 §1 通用开发流程（与项目无针对性）；(b) 删 §4.5 占位模块规范（该规范仅用于架构规划专用、非普通开发内容，迁至项目根 `CLAUDE.md`）；(c) 原 §4.4 Commit 信息（Conventional Commits）并入 Git 协作规范作为 §3.4.7；(d) 节号重排 §2→§1 TPAD / §3→§2 数仓流程 / §4→§3 代码开发（§4.1-§4.3→§3.1-§3.3、§4.6→§3.4，其 §4.6.1-6 → §3.4.1-6）/ §5→§4 / §6→§5 / §7→§6；(e) 联动 `kb/README.md` §30 条目描述 + `kb/90-重构路线.md §2.11` 占位模块标准引用从 `kb/30 §4.5` 改指 `CLAUDE.md` | — |
 | 2026-04-21 | **datasource 目录结构收敛到 kb/00 §1 一处**：老 kb 内 datasource 目录树在 kb/00 §1（扁平老结构）、kb/00 §6.4（带 env 层目标态）、kb/02 §4（带 env 层）三处平行画，一改就易漏。kb/00 §1 子树补齐 env 层 + 实例举例（`postgresql/{prod,test,dev}/hobby.ini`）作为唯一真源；kb/00 §6.4 删内嵌目录示例块 + 删"当前状态：尚未落地"段（按"不标现状/目标态，以目标态为准"约定）；kb/02 §4 删重复目录树，改跨文档引 `kb/00 §1` | — |
+| 2026-04-21 | **kb/31-UDF手册.md 骨架建立**（聚簇 B / §2.12(b) 启动）：新建独立文档作为 `dw_base/udf/common/` 通用 UDF 自查表的稳定锚点；仅骨架（概述 + 准入规则占位 + 空表头），分类不预划由 Codex 按 `spark_common_udf.py` 实际划分登记；`kb/README.md` §3x 加入口。配套修正 `kb/90 §2.12`：(a) 文件名 `kb/31-UDF 手册.md` → `kb/31-UDF手册.md`（无空格）；(b) 准入规则落点候选从 `kb/30 或 CLAUDE.md` 改为 `kb/30 或 kb/31 内部`（规范类条款不进 CLAUDE.md）。首版全量登记 + 硬约束正文待 Codex UDF 注释统一化落地后另起 changelog | — |

kb/README.md

@@ -45,6 +45,7 @@
 | 文档 | 内容 |
 |----|----|
 | [30-开发规范](30-开发规范.md) | TPAD 任务规范、数仓数据开发流程、代码 / SQL 规范、Git 协作规范（IDE 格式化 scheme 见 `conf/sql_style.xml`） |
+| [31-UDF手册](31-UDF手册.md) | `dw_base/udf/common/` 下通用 UDF 自查表与准入规则 |
 
 ### 9x 过渡资料