init: 项目初始提交 - NeoZQYY Monorepo 完整代码

2026-02-15 14:58:14 +08:00
commit ded6dfb9d8
769 changed files with 182616 additions and 0 deletions
--- a/.kiro/specs/bd-manual-docs-consolidation/.config.kiro
+++ b/.kiro/specs/bd-manual-docs-consolidation/.config.kiro
@@ -0,0 +1 @@
+{"generationMode": "requirements-first"}
--- a/.kiro/specs/bd-manual-docs-consolidation/design.md
+++ b/.kiro/specs/bd-manual-docs-consolidation/design.md
@@ -0,0 +1,311 @@
+# 设计文档：数据库文档整理与补全
+
+## 概述
+
+本特性对 `docs/bd_manual/` 目录进行系统性整理和补全，涵盖四个核心工作流：
+
+1. **目录结构规范化** — 统一各层目录布局，新增 `ETL_Admin/` 层和根目录 `README.md` 索引
+2. **DDL 对比同步** — 编写 Python 脚本对比四个 schema 的 DDL 文件与数据库实际状态，以数据库为准修正 DDL
+3. **ODS 表级文档补全** — 为 `billiards` schema 下所有 ODS 表生成 Markdown 表级文档
+4. **API→ODS 字段映射文档** — 建立 API JSON 响应到 ODS 表字段的映射关系文档
+
+本特性以文档和 DDL 维护为主，不涉及业务代码逻辑变更。DDL 修正属于 `database/` 高风险路径，完成后需触发 `/audit`。
+
+## 架构
+
+```mermaid
+graph TD
+    subgraph 信息来源
+        DB[(PostgreSQL 数据库)]
+        DDL[database/schema_*.sql]
+        API_REF[docs/api-reference/]
+        PARSERS[models/parsers.py]
+        COMMENTS[DDL COMMENT ON 注释]
+    end
+
+    subgraph 对比脚本
+        COMPARE[scripts/compare_ddl_db.py]
+    end
+
+    subgraph 文档产出
+        README[docs/bd_manual/README.md]
+        ODS_DOCS[docs/bd_manual/ODS/main/*.md]
+        ODS_MAP[docs/bd_manual/ODS/mappings/*.md]
+        ODS_DICT[docs/dictionary/ods_tables_dictionary.md]
+        ETL_DOCS[docs/bd_manual/ETL_Admin/main/*.md]
+        CHANGES[docs/bd_manual/*/changes/*.md]
+        DDL_FIX[database/schema_*.sql 修正]
+    end
+
+    DB -->|information_schema 查询| COMPARE
+    DDL -->|解析 CREATE TABLE| COMPARE
+    COMPARE -->|差异报告| CHANGES
+    COMPARE -->|修正| DDL_FIX
+
+    DB -->|表结构 + COMMENT| ODS_DOCS
+    COMMENTS -->|字段说明| ODS_DOCS
+    API_REF -->|端点信息| ODS_MAP
+    PARSERS -->|转换逻辑| ODS_MAP
+    DB -->|表概览| ODS_DICT
+    DB -->|表结构| ETL_DOCS
+```
+
+## 组件与接口
+
+### 1. DDL 对比脚本 (`scripts/compare_ddl_db.py`)
+
+一个独立的 Python 脚本，用于对比 DDL 文件与数据库实际状态。
+
+**输入**：
+- DDL 文件路径（`database/schema_*.sql`）
+- 数据库连接（通过 `PG_DSN` 环境变量或 `--pg-dsn` 参数）
+
+**输出**：
+- 控制台差异报告（表级、字段级、类型级）
+- 可选：`--fix` 模式直接修正 DDL 文件
+
+**对比逻辑**：
+- 从 `information_schema.columns` 查询数据库实际表结构
+- 解析 DDL 文件中的 `CREATE TABLE` 语句提取表名和字段定义
+- 逐表逐字段对比：表是否存在、字段是否存在、字段类型是否一致、约束是否一致
+- 差异分类：`MISSING_TABLE`（DDL 缺表）、`EXTRA_TABLE`（DDL 多表）、`MISSING_COLUMN`、`EXTRA_COLUMN`、`TYPE_MISMATCH`、`NULLABLE_MISMATCH`
+
+**接口**：
+```python
+def compare_schema(ddl_path: str, schema_name: str, pg_dsn: str) -> list[SchemaDiff]
+```
+
+### 2. ODS 表级文档生成器
+
+手动编写（非自动生成脚本），参考以下信息来源：
+- 数据库 `information_schema.columns` 获取字段名、类型、可空性
+- DDL 文件中的 `COMMENT ON` 注释获取字段说明、示例值、JSON 字段映射
+- 现有 DWD/DWS 表级文档格式作为模板
+
+### 3. API→ODS 映射文档
+
+手动编写，参考以下信息来源：
+- `docs/api-reference/endpoints/*.md` — API 端点路径、请求参数、响应字段
+- `docs/api-reference/samples/*.json` — JSON 响应样本
+- `models/parsers.py` — `TypeParser` 类中的类型转换方法
+- DDL 文件中的 `COMMENT ON` 注释中的 `【JSON字段】` 标注
+
+### 4. 目录结构与索引
+
+**新增目录**：
+- `docs/bd_manual/ETL_Admin/main/`
+- `docs/bd_manual/ETL_Admin/changes/`
+- `docs/bd_manual/ODS/mappings/`
+
+**新增文件**：
+- `docs/bd_manual/README.md` — 根索引，列出目录结构和各层文档清单
+
+## 数据模型
+
+本特性不引入新的数据模型。涉及的现有 schema 如下：
+
+| Schema | DDL 文件 | 用途 | 预估表数 |
+|--------|----------|------|----------|
+| `billiards_ods` | `database/schema_ODS_doc.sql` | 原始数据存储 | ~22 张 |
+| `billiards_dwd` | `database/schema_dwd_doc.sql` | 明细数据层 | ~22 张（含 Ex） |
+| `billiards_dws` | `database/schema_dws.sql` | 数据服务层 | ~30 张 |
+| `etl_admin` | `database/schema_etl_admin.sql` | ETL 管理元数据 | ~5 张 |
+
+### 文档模板格式
+
+**ODS 表级文档模板**（与 DWD/DWS 保持一致）：
+
+```markdown
+# {表名} {中文说明}
+
+> 生成时间：YYYY-MM-DD
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | billiards |
+| 表名 | {表名} |
+| 主键 | {主键字段} |
+| 数据来源 | {API 端点 / JSON 文件} |
+| 说明 | {表说明} |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 说明 |
+|------|--------|------|------|------|
+| 1 | ... | ... | ... | ... |
+
+## 使用说明
+
+{SQL 示例}
+
+## 可回溯性
+
+| 项目 | 说明 |
+|------|------|
+| 可回溯 | ✅ 完全可回溯（保留 payload 原始 JSON） |
+| 数据来源 | {API 端点路径} |
+```
+
+**API→ODS 映射文档模板**：
+
+```markdown
+# {API端点名} → {ODS表名} 字段映射
+
+> 生成时间：YYYY-MM-DD
+
+## 端点信息
+
+| 属性 | 值 |
+|------|-----|
+| 接口路径 | {路径} |
+| 请求方法 | POST |
+| ODS 对应表 | {表名} |
+| JSON 数据路径 | {如 data.tenantMemberInfos} |
+
+## 字段映射
+
+| JSON 字段 | ODS 列名 | 类型转换 | 说明 |
+|-----------|----------|----------|------|
+| id | id | int→BIGINT | 主键 |
+| ... | ... | ... | ... |
+
+## ETL 补充字段
+
+| ODS 列名 | 生成逻辑 |
+|-----------|----------|
+| content_hash | 对业务字段计算 SHA256 |
+| source_file | 固定值：{文件名}.json |
+| source_endpoint | API 端点路径 |
+| fetched_at | 入库时间戳 |
+| payload | 完整原始 JSON 记录 |
+
+## 类型转换规则
+
+- 时间戳：通过 `TypeParser.parse_timestamp()` 转换，支持字符串和 Unix 毫秒时间戳
+- 金额：通过 `TypeParser.parse_decimal(value, scale=2)` 转换，ROUND_HALF_UP
+- 整数：通过 `TypeParser.parse_int()` 转换
+```
+
+
+## 正确性属性
+
+*属性是系统在所有有效执行中都应保持为真的特征或行为——本质上是关于系统应该做什么的形式化陈述。属性是人类可读规格说明与机器可验证正确性保证之间的桥梁。*
+
+### Property 1: 数据层目录结构一致性
+
+*For any* 数据层目录（ODS、DWD、DWS、ETL_Admin），该目录下都应包含 `main/` 和 `changes/` 两个子目录。
+
+**Validates: Requirements 1.2**
+
+### Property 2: DDL 对比脚本差异检测完整性
+
+*For any* schema 和对应的 DDL 文件，当数据库中存在 DDL 文件未定义的表或字段时，对比脚本应将其报告为 `MISSING_TABLE` 或 `MISSING_COLUMN`；当 DDL 文件中存在数据库没有的表或字段时，应报告为 `EXTRA_TABLE` 或 `EXTRA_COLUMN`；当字段类型不一致时，应报告为 `TYPE_MISMATCH`。
+
+**Validates: Requirements 2.1, 2.2, 2.3, 2.4**
+
+### Property 3: DDL 修正后零差异（不动点）
+
+*For any* schema，在以数据库实际状态修正 DDL 文件后，再次运行对比脚本，差异列表应为空。
+
+**Validates: Requirements 2.5**
+
+### Property 4: ODS 表级文档覆盖率
+
+*For any* `billiards` schema 中的 ODS 表，在 `docs/bd_manual/ODS/main/` 目录下都应存在一份对应的 Markdown 文档。
+
+**Validates: Requirements 3.1**
+
+### Property 5: ODS 表级文档格式完整性
+
+*For any* ODS 表级文档，都应包含以下章节：表信息（含 Schema、表名、主键、数据来源、说明）、字段说明表格、使用说明（含 SQL 示例）、可回溯性信息，以及 ETL 元数据字段（content_hash、source_file、source_endpoint、fetched_at、payload）的说明。
+
+**Validates: Requirements 3.2, 3.4, 3.5**
+
+### Property 6: ODS 表级文档命名规范
+
+*For any* ODS 表级文档文件，其文件名应匹配 `BD_manual_{表名}.md` 格式。
+
+**Validates: Requirements 3.6**
+
+### Property 7: 映射文档覆盖率
+
+*For any* 有对应 ODS 表的 API 端点，在 `docs/bd_manual/ODS/mappings/` 目录下都应存在一份对应的映射文档。
+
+**Validates: Requirements 4.1**
+
+### Property 8: 映射文档内容完整性
+
+*For any* 映射文档，都应包含以下信息：API 端点路径、ODS 表名、JSON 数据路径、字段映射表格，以及 ETL 补充字段（content_hash、source_file、source_endpoint、fetched_at、payload）的生成逻辑。
+
+**Validates: Requirements 4.2, 4.4**
+
+### Property 9: 映射文档命名规范
+
+*For any* 映射文档文件，其文件名应匹配 `mapping_{API端点名}_{ODS表名}.md` 格式。
+
+**Validates: Requirements 4.6**
+
+### Property 10: ODS 数据字典覆盖率
+
+*For any* `billiards` schema 中的 ODS 表，ODS 数据字典中都应有对应的条目，包含表名、中文说明、主键、数据来源信息。
+
+**Validates: Requirements 5.2**
+
+## 错误处理
+
+### DDL 对比脚本
+
+| 场景 | 处理方式 |
+|------|----------|
+| 数据库连接失败 | 输出错误信息并退出，返回非零退出码 |
+| DDL 文件不存在 | 输出错误信息并跳过该 schema |
+| DDL 文件解析失败 | 输出解析错误位置和原因，尽可能继续解析其余部分 |
+| schema 在数据库中不存在 | 输出警告并跳过 |
+
+### 文档生成
+
+| 场景 | 处理方式 |
+|------|----------|
+| 表无 COMMENT 注释 | 字段说明列填写"（待补充）" |
+| API 端点文档缺失 | 映射文档中标注"端点文档待补充"，仅基于 DDL COMMENT 生成 |
+| 字段类型无法识别 | 保留数据库原始类型字符串 |
+
+## 测试策略
+
+### 单元测试
+
+针对 DDL 对比脚本的核心逻辑编写单元测试（`tests/unit/test_compare_ddl.py`）：
+
+- 测试 DDL 解析器能正确提取表名、字段名、字段类型、约束
+- 测试差异检测逻辑能识别各类差异（缺失表、多余表、字段差异、类型差异）
+- 测试边界情况：空 DDL 文件、无表的 schema、COMMENT 中含特殊字符
+
+### 属性测试
+
+使用 `hypothesis` 库（Python 属性测试框架）。
+
+- **Property 2 测试**：生成随机的"DDL 表定义"和"数据库表定义"，注入已知差异，验证对比函数能检测到所有差异
+  - **Feature: bd-manual-docs-consolidation, Property 2: DDL 对比脚本差异检测完整性**
+  - 最少 100 次迭代
+
+- **Property 3 测试**：生成随机的数据库表定义，用其生成 DDL，再运行对比，验证差异为零
+  - **Feature: bd-manual-docs-consolidation, Property 3: DDL 修正后零差异（不动点）**
+  - 最少 100 次迭代
+
+### 集成验证
+
+文档覆盖率和格式验证通过 Python 脚本实现（`scripts/validate_bd_manual.py`），可在 CI 中运行：
+
+- 验证 Property 1（目录结构）、Property 4-10（文档覆盖率、格式、命名）
+- 输入：文件系统 + 数据库 `information_schema` 查询
+- 输出：通过/失败报告，列出缺失或不合规的文档
+
+### 测试配置
+
+- 属性测试库：`hypothesis`（需添加到开发依赖）
+- 单元测试：`pytest tests/unit/test_compare_ddl.py`
+- 集成验证：`python scripts/validate_bd_manual.py --pg-dsn "$PG_DSN"`
+- 每个属性测试最少 100 次迭代
+- 每个测试需注释引用对应的设计属性编号
--- a/.kiro/specs/bd-manual-docs-consolidation/requirements.md
+++ b/.kiro/specs/bd-manual-docs-consolidation/requirements.md
@@ -0,0 +1,80 @@
+# 需求文档
+
+## 简介
+
+整理和补全飞球 ETL 系统的数据库文档体系（`docs/bd_manual/`），包括目录结构规范化、DDL 与数据库实际状态的对比同步、ODS 层表级文档补全、以及 API JSON → ODS 字段映射文档的建立。本特性不涉及代码逻辑变更，仅涉及文档和 DDL 文件的维护。
+
+## 术语表
+
+- **BD_Manual**: 数据库手册目录（`docs/bd_manual/`），存放各层表级文档、变更记录等
+- **ODS**: 操作数据存储层（Operational Data Store），`billiards` schema，保留 API 原始数据
+- **DWD**: 明细数据层（Data Warehouse Detail），`billiards_dwd` schema，清洗后的维度和事实表
+- **DWS**: 数据服务层（Data Warehouse Service），`billiards_dws` schema，汇总宽表和配置表
+- **DDL**: 数据定义语言文件（`database/schema_*.sql`），定义表结构
+- **表级文档**: 以 Markdown 格式编写的单表说明文件，包含表信息、字段说明、使用示例等
+- **字段映射文档**: 记录 API JSON 响应字段到 ODS 表字段的对应关系和转换逻辑
+- **SCD2**: 缓慢变化维度类型 2，用于 DWD 维度表的历史版本管理
+- **ETL_Admin**: ETL 管理 schema（`etl_admin`），存放调度、游标、运行记录等元数据
+
+## 需求
+
+### 需求 1：规范化 BD_Manual 目录结构
+
+**用户故事：** 作为数据开发人员，我希望 BD_Manual 目录结构统一规范，以便快速定位各层各类型的数据库文档。
+
+#### 验收标准
+
+1. THE BD_Manual SHALL 包含以下顶层子目录：`ODS/`、`DWD/`、`DWS/`、`ETL_Admin/`
+2. WHEN 某一数据层目录被访问时，THE BD_Manual SHALL 在该层目录下提供 `main/`（表级文档）和 `changes/`（变更记录）两个子目录
+3. THE DWD 目录 SHALL 额外保留 `Ex/` 子目录用于存放扩展表文档
+4. THE BD_Manual SHALL 在根目录提供一个 `README.md` 索引文件，列出目录结构说明和各层文档清单
+5. WHEN ETL_Admin schema 存在表时，THE BD_Manual SHALL 在 `ETL_Admin/main/` 下为每张表提供表级文档
+
+### 需求 2：DDL 文件与数据库实际状态对比同步
+
+**用户故事：** 作为数据开发人员，我希望 DDL 文件与数据库实际表结构保持一致，以便 DDL 文件可作为可信的 schema 参考。
+
+#### 验收标准
+
+1. WHEN 对比 ODS 层 DDL 文件（`database/schema_ODS_doc.sql`）与数据库 `billiards_ods` schema 实际表结构时，THE 对比脚本 SHALL 输出所有差异项（缺失表、多余表、字段差异、类型差异、约束差异）
+2. WHEN 对比 DWD 层 DDL 文件（`database/schema_dwd_doc.sql`）与数据库 `billiards_dwd` schema 实际表结构时，THE 对比脚本 SHALL 输出所有差异项
+3. WHEN 对比 DWS 层 DDL 文件（`database/schema_dws.sql`）与数据库 `billiards_dws` schema 实际表结构时，THE 对比脚本 SHALL 输出所有差异项
+4. WHEN 对比 ETL_Admin 层 DDL 文件（`database/schema_etl_admin.sql`）与数据库 `etl_admin` schema 实际表结构时，THE 对比脚本 SHALL 输出所有差异项
+5. WHEN 发现差异时，THE DDL 文件 SHALL 以数据库实际状态为准进行修正
+6. WHEN DDL 文件被修正后，THE 变更记录 SHALL 在对应层的 `changes/` 目录下生成一份差异说明文档
+
+### 需求 3：补全 ODS 层表级文档
+
+**用户故事：** 作为数据开发人员，我希望 ODS 层每张表都有完整的表级文档，以便理解原始数据结构和来源。
+
+#### 验收标准
+
+1. THE ODS 表级文档 SHALL 为 `billiards_ods` schema 中的每张 ODS 表生成一份 Markdown 文档，存放于 `docs/bd_manual/ODS/main/`
+2. THE ODS 表级文档 SHALL 遵循与 DWD/DWS 表级文档一致的格式，包含：表信息表格、字段说明表格、使用说明（含 SQL 示例）、可回溯性信息
+3. WHEN ODS 表的字段含有 COMMENT 注释时，THE 表级文档 SHALL 将 COMMENT 中的说明、示例、JSON 字段映射信息提取并填入字段说明
+4. THE ODS 表级文档的表信息 SHALL 包含 Schema、表名、主键、数据来源（API 端点或文件）、说明
+5. THE ODS 表级文档 SHALL 包含 ETL 元数据字段（`content_hash`、`source_file`、`source_endpoint`、`fetched_at`、`payload`）的统一说明
+6. THE ODS 表级文档的文件命名 SHALL 遵循 `BD_manual_{表名}.md` 格式
+
+### 需求 4：建立 API JSON → ODS 字段映射文档
+
+**用户故事：** 作为数据开发人员，我希望有一份清晰的 API 响应字段到 ODS 表字段的映射文档，以便理解数据从 API 到 ODS 的转换逻辑。
+
+#### 验收标准
+
+1. THE 映射文档 SHALL 为每个 API 端点与其对应的 ODS 表建立一份映射文件，存放于 `docs/bd_manual/ODS/mappings/`
+2. THE 映射文档 SHALL 包含以下信息：API 端点路径、对应 ODS 表名、JSON 响应路径（如 `data.tenantMemberInfos`）、每个字段的 JSON 路径到 ODS 列名的映射
+3. WHEN 字段存在类型转换或值处理逻辑时，THE 映射文档 SHALL 记录转换规则（如时间格式转换、枚举值映射、金额精度处理）
+4. THE 映射文档 SHALL 标注 ETL 补充字段（`content_hash`、`source_file`、`source_endpoint`、`fetched_at`、`payload`）的生成逻辑
+5. THE 映射文档 SHALL 参考 `models/parsers.py` 中的解析逻辑和 `docs/api-reference/` 中的端点文档作为信息来源
+6. THE 映射文档的文件命名 SHALL 遵循 `mapping_{API端点名}_{ODS表名}.md` 格式
+
+### 需求 5：建立 ODS 数据字典
+
+**用户故事：** 作为数据开发人员，我希望有一份 ODS 层的数据字典汇总文档，以便快速查阅所有 ODS 表的概览信息。
+
+#### 验收标准
+
+1. THE ODS 数据字典 SHALL 创建于 `docs/dictionary/ods_tables_dictionary.md`
+2. THE ODS 数据字典 SHALL 列出所有 ODS 表的概览信息，包含：表名、中文说明、主键、记录数、数据来源
+3. THE ODS 数据字典 SHALL 遵循与现有 DWD/DWS 数据字典一致的格式
--- a/.kiro/specs/bd-manual-docs-consolidation/tasks.md
+++ b/.kiro/specs/bd-manual-docs-consolidation/tasks.md
@@ -0,0 +1,111 @@
+# 实施计划：数据库文档整理与补全
+
+## 概述
+
+按照"目录结构 → DDL 对比脚本 → DDL 同步 → ODS 文档 → 映射文档 → 数据字典 → 索引"的顺序，逐步完成文档体系的整理和补全。DDL 对比脚本先编写并测试，再用它驱动实际的 DDL 同步工作。
+
+## 任务
+
+- [x] 1. 规范化 BD_Manual 目录结构
+  - 创建 `docs/bd_manual/ETL_Admin/main/` 和 `docs/bd_manual/ETL_Admin/changes/` 目录
+  - 创建 `docs/bd_manual/ODS/mappings/` 目录
+  - 确认 ODS/DWD/DWS 各层均有 `main/` 和 `changes/` 子目录
+  - _Requirements: 1.1, 1.2, 1.3_
+
+- [ ] 2. 编写 DDL 对比脚本
+  - [x] 2.1 实现 DDL 解析器和对比核心逻辑 (`scripts/compare_ddl_db.py`)
+    - 解析 `CREATE TABLE` 语句提取表名、字段名、字段类型、约束、主键
+    - 查询 `information_schema.columns` 获取数据库实际表结构
+    - 实现逐表逐字段对比，输出差异分类（MISSING_TABLE、EXTRA_TABLE、MISSING_COLUMN、EXTRA_COLUMN、TYPE_MISMATCH、NULLABLE_MISMATCH）
+    - 支持 `--pg-dsn`、`--schema`、`--ddl-path` 参数
+    - _Requirements: 2.1, 2.2, 2.3, 2.4_
+
+  - [x] 2.2 编写 DDL 解析器单元测试 (`tests/unit/test_compare_ddl.py`)
+    - 测试 DDL 解析器正确提取表名、字段、类型、约束
+    - 测试差异检测逻辑识别各类差异
+    - 测试边界情况：空文件、COMMENT 含特殊字符
+    - _Requirements: 2.1_
+
+  - [x] 2.3 编写 DDL 对比属性测试
+    - **Property 2: DDL 对比脚本差异检测完整性**
+    - **Validates: Requirements 2.1, 2.2, 2.3, 2.4**
+
+  - [x] 2.4 编写 DDL 修正不动点属性测试
+    - **Property 3: DDL 修正后零差异（不动点）**
+    - **Validates: Requirements 2.5**
+
+- [x] 3. 检查点 — 确认对比脚本可用
+  - 确保所有测试通过，如有问题请向用户确认。
+
+- [x] 4. 执行 DDL 对比并同步
+  - [x] 4.1 运行对比脚本对比四个 schema（ODS、DWD、DWS、ETL_Admin）
+    - 执行 `scripts/compare_ddl_db.py` 对比每个 schema
+    - 记录所有差异项
+    - _Requirements: 2.1, 2.2, 2.3, 2.4_
+
+  - [x] 4.2 修正 DDL 文件以匹配数据库实际状态
+    - 以数据库为准修正 `database/schema_ODS_doc.sql`、`database/schema_dwd_doc.sql`、`database/schema_dws.sql`、`database/schema_etl_admin.sql`
+    - _Requirements: 2.5_
+
+  - [x] 4.3 生成 DDL 变更记录
+    - 在对应层的 `changes/` 目录下生成差异说明文档（日期前缀命名）
+    - 包含变更说明、兼容性影响、回滚策略、验证 SQL（至少 3 条）
+    - _Requirements: 2.6_
+
+- [x] 5. 检查点 — 确认 DDL 同步完成
+  - 确保所有测试通过，如有问题请向用户确认。
+
+- [x] 6. 补全 ODS 层表级文档
+  - [x] 6.1 为每张 ODS 表编写表级文档 (`docs/bd_manual/ODS/main/BD_manual_{表名}.md`)
+    - 从数据库 `information_schema.columns` 获取字段信息
+    - 从 DDL `COMMENT ON` 注释提取字段说明、示例值、JSON 字段映射
+    - 遵循 DWD/DWS 文档格式：表信息、字段说明、使用说明（含 SQL）、可回溯性
+    - 包含 ETL 元数据字段统一说明
+    - _Requirements: 3.1, 3.2, 3.3, 3.4, 3.5, 3.6_
+
+- [x] 7. 建立 API→ODS 字段映射文档
+  - [x] 7.1 为每个 API 端点编写映射文档 (`docs/bd_manual/ODS/mappings/mapping_{端点名}_{表名}.md`)
+    - 参考 `docs/api-reference/endpoints/*.md` 获取端点信息和响应字段
+    - 参考 DDL `COMMENT ON` 中的 `【JSON字段】` 标注获取映射关系
+    - 参考 `models/parsers.py` 中 `TypeParser` 的转换方法记录类型转换规则
+    - 包含 ETL 补充字段生成逻辑说明
+    - _Requirements: 4.1, 4.2, 4.3, 4.4, 4.5, 4.6_
+
+- [x] 8. 建立 ODS 数据字典和 ETL_Admin 文档
+  - [x] 8.1 创建 ODS 数据字典 (`docs/dictionary/ods_tables_dictionary.md`)
+    - 列出所有 ODS 表概览：表名、中文说明、主键、记录数、数据来源
+    - 遵循现有 DWD/DWS 数据字典格式
+    - _Requirements: 5.1, 5.2, 5.3_
+
+  - [x] 8.2 为 ETL_Admin 表编写表级文档 (`docs/bd_manual/ETL_Admin/main/BD_manual_{表名}.md`)
+    - 从数据库获取 `etl_admin` schema 表结构
+    - 遵循统一文档格式
+    - _Requirements: 1.5_
+
+- [x] 9. 编写 BD_Manual 根目录 README.md 索引
+  - 创建 `docs/bd_manual/README.md`
+  - 列出目录结构说明、各层文档清单、文档命名规范
+  - _Requirements: 1.4_
+
+- [x] 10. 编写文档验证脚本
+  - [x] 10.1 实现文档覆盖率和格式验证脚本 (`scripts/validate_bd_manual.py`)
+    - 验证目录结构一致性（Property 1）
+    - 验证 ODS 文档覆盖率和命名规范（Property 4, 6）
+    - 验证 ODS 文档格式完整性（Property 5）
+    - 验证映射文档覆盖率和命名规范（Property 7, 9）
+    - 验证映射文档内容完整性（Property 8）
+    - 验证数据字典覆盖率（Property 10）
+    - 支持 `--pg-dsn` 参数连接数据库获取表清单
+    - _Requirements: 1.2, 3.1, 3.2, 3.6, 4.1, 4.2, 4.6, 5.2_
+
+- [x] 11. 最终检查点 — 确认所有文档完整
+  - 运行 `scripts/validate_bd_manual.py` 确认所有验证通过
+  - 确保所有测试通过，如有问题请向用户确认。
+
+## 备注
+
+- 标记 `*` 的子任务为可选，可跳过以加速 MVP
+- 每个任务引用了具体的需求编号以便追溯
+- DDL 修正涉及 `database/` 高风险路径，完成后需触发 `/audit`
+- 属性测试验证对比脚本的通用正确性，集成验证脚本验证文档体系的完整性
+- ODS 表级文档和映射文档为手动编写（非自动生成），需逐表参考数据库和 API 文档