在准备环境前提交次全部更改。

scripts/ops/gen_dataflow_doc.py

@@ -0,0 +1,339 @@
+# -*- coding: utf-8 -*-
+"""
+从源代码和 DDL 中提取 API → ODS → DWD 数据流映射，生成 Markdown 文档。
+用法: python scripts/ops/gen_dataflow_doc.py
+输出: docs/reports/dataflow_api_ods_dwd.md
+"""
+import re
+import ast
+import sys
+import os
+from pathlib import Path
+from collections import OrderedDict
+
+ROOT = Path(__file__).resolve().parents[2]
+ETL = ROOT / "apps" / "etl" / "pipelines" / "feiqiu"
+DB = ROOT / "db" / "etl_feiqiu" / "schemas"
+OUT = ROOT / "docs" / "reports" / "dataflow_api_ods_dwd.md"
+
+
+# ── 1. 从 DDL 解析表结构 ──────────────────────────────────────────
+def parse_ddl_tables(sql_path: Path, schema: str) -> dict[str, list[dict]]:
+    """解析 CREATE TABLE 语句，返回 {schema.table: [{col, type}, ...]}"""
+    text = sql_path.read_text(encoding="utf-8")
+    tables: dict[str, list[dict]] = {}
+    # 匹配 CREATE TABLE IF NOT EXISTS table_name (...)
+    pattern = re.compile(
+        r"CREATE\s+TABLE\s+IF\s+NOT\s+EXISTS\s+"
+        r"(?:(\w+)\.)?(\w+)\s*\((.*?)\)\s*;",
+        re.DOTALL | re.IGNORECASE,
+    )
+    for m in pattern.finditer(text):
+        s = m.group(1) or schema
+        tname = m.group(2)
+        body = m.group(3)
+        cols = []
+        for line in body.split("\n"):
+            line = line.strip().rstrip(",")
+            if not line or line.upper().startswith("PRIMARY") or line.startswith("--"):
+                continue
+            # 跳过约束行
+            if re.match(r"^(CONSTRAINT|UNIQUE|CHECK|FOREIGN|EXCLUDE)\b", line, re.I):
+                continue
+            parts = line.split()
+            if len(parts) >= 2:
+                col_name = parts[0].strip('"')
+                col_type = parts[1]
+                # 合并类型修饰符
+                if len(parts) > 2 and parts[2].startswith("("):
+                    col_type += parts[2]
+                cols.append({"col": col_name, "type": col_type})
+        full = f"{s}.{tname}"
+        tables[full] = cols
+    return tables
+
+
+# ── 2. 从 Python 源码解析 TABLE_MAP ──────────────────────────────
+def parse_table_map(py_path: Path) -> dict[str, str]:
+    """解析 TABLE_MAP: dict[str, str] = {...}"""
+    text = py_path.read_text(encoding="utf-8")
+    # 找到 TABLE_MAP 字典
+    match = re.search(
+        r"TABLE_MAP\s*(?::\s*dict\[.*?\])?\s*=\s*\{(.*?)\}",
+        text,
+        re.DOTALL,
+    )
+    if not match:
+        return {}
+    body = match.group(1)
+    result = {}
+    for m in re.finditer(r'"([^"]+)"\s*:\s*"([^"]+)"', body):
+        result[m.group(1)] = m.group(2)
+    return result
+
+
+# ── 3. 从 Python 源码解析 FACT_MAPPINGS ──────────────────────────
+def parse_fact_mappings(py_path: Path) -> dict[str, list[tuple]]:
+    """解析 FACT_MAPPINGS 字典，返回 {dwd_table: [(dwd_col, ods_expr, cast), ...]}"""
+    text = py_path.read_text(encoding="utf-8")
+    # 找到 FACT_MAPPINGS 块
+    start = text.find("FACT_MAPPINGS")
+    if start < 0:
+        return {}
+    # 找到第一个 { 后的内容
+    brace_start = text.find("{", start)
+    if brace_start < 0:
+        return {}
+
+    # 手动匹配大括号
+    depth = 0
+    end = brace_start
+    for i in range(brace_start, len(text)):
+        if text[i] == "{":
+            depth += 1
+        elif text[i] == "}":
+            depth -= 1
+            if depth == 0:
+                end = i + 1
+                break
+
+    block = text[brace_start:end]
+    result = {}
+    # 匹配每个表的映射列表
+    table_pattern = re.compile(r'"([^"]+)"\s*:\s*\[', re.DOTALL)
+    for tm in table_pattern.finditer(block):
+        table_name = tm.group(1)
+        list_start = tm.end()
+        # 找到对应的 ]
+        bracket_depth = 1
+        list_end = list_start
+        for i in range(list_start, len(block)):
+            if block[i] == "[":
+                bracket_depth += 1
+            elif block[i] == "]":
+                bracket_depth -= 1
+                if bracket_depth == 0:
+                    list_end = i
+                    break
+        list_body = block[list_start:list_end]
+        # 匹配 (dwd_col, ods_expr, cast|None)
+        tuples = []
+        tuple_pattern = re.compile(
+            r'\(\s*"([^"]+)"\s*,\s*"([^"]+)"\s*,\s*(?:"([^"]+)"|None)\s*\)'
+        )
+        for tp in tuple_pattern.finditer(list_body):
+            tuples.append((tp.group(1), tp.group(2), tp.group(3)))
+        result[table_name] = tuples
+    return result
+
+
+# ── 4. 从 Python 源码解析 ODS_TASK_SPECS ─────────────────────────
+def parse_ods_specs(py_path: Path) -> list[dict]:
+    """解析 ODS_TASK_SPECS，提取 code, table_name, endpoint, list_key, description"""
+    text = py_path.read_text(encoding="utf-8")
+    specs = []
+    # 匹配每个 OdsTaskSpec(...)
+    pattern = re.compile(r"OdsTaskSpec\s*\((.*?)\)\s*,", re.DOTALL)
+    for m in pattern.finditer(text):
+        body = m.group(1)
+        spec = {}
+        for key in ("code", "table_name", "endpoint", "list_key", "description"):
+            km = re.search(rf'{key}\s*=\s*"([^"]*)"', body)
+            if km:
+                spec[key] = km.group(1)
+        if "code" in spec:
+            specs.append(spec)
+    return specs
+
+
+# ── 5. 生成文档 ──────────────────────────────────────────────────
+def generate_doc():
+    ods_ddl = parse_ddl_tables(DB / "ods.sql", "ods")
+    dwd_ddl = parse_ddl_tables(DB / "dwd.sql", "dwd")
+
+    dwd_task_py = ETL / "tasks" / "dwd" / "dwd_load_task.py"
+    table_map = parse_table_map(dwd_task_py)
+    fact_mappings = parse_fact_mappings(dwd_task_py)
+
+    ods_specs = parse_ods_specs(ETL / "tasks" / "ods" / "ods_tasks.py")
+    # ODS 表 → API 端点映射
+    ods_to_api: dict[str, dict] = {}
+    for spec in ods_specs:
+        tn = spec.get("table_name", "")
+        ods_to_api[tn] = spec
+
+    lines = []
+    lines.append("# API → ODS → DWD 数据流对比文档")
+    lines.append("")
+    lines.append("> 自动生成于 `scripts/ops/gen_dataflow_doc.py`，基于 DDL 和 ETL 源码解析。")
+    lines.append("")
+    lines.append("## 概览")
+    lines.append("")
+    lines.append(f"- ODS 表数量: {len(ods_ddl)}")
+    lines.append(f"- DWD 表数量: {len(dwd_ddl)}")
+    lines.append(f"- TABLE_MAP 映射条目: {len(table_map)}")
+    lines.append(f"- ODS 任务数量: {len(ods_specs)}")
+    lines.append("")
+
+    # ── 按 ODS 表分组 ──
+    # 先建立 ODS 表 → DWD 表列表的反向映射
+    ods_to_dwd: dict[str, list[str]] = {}
+    for dwd_t, ods_t in table_map.items():
+        ods_to_dwd.setdefault(ods_t, []).append(dwd_t)
+
+    # 收集所有涉及的 ODS 表（去重、排序）
+    all_ods = sorted(set(list(ods_to_dwd.keys()) + [s.get("table_name", "") for s in ods_specs]))
+
+    lines.append("## 目录")
+    lines.append("")
+    for i, ods_t in enumerate(all_ods, 1):
+        anchor = ods_t.replace(".", "").replace("_", "-")
+        short = ods_t.split(".")[-1] if "." in ods_t else ods_t
+        lines.append(f"{i}. [{short}](#{anchor})")
+    lines.append("")
+    lines.append("---")
+    lines.append("")
+
+    # ── 逐表详情 ──
+    for ods_t in all_ods:
+        short = ods_t.split(".")[-1] if "." in ods_t else ods_t
+        lines.append(f"## {short}")
+        lines.append("")
+
+        # API 信息
+        api_info = ods_to_api.get(ods_t, {})
+        if api_info:
+            lines.append("### API 端点")
+            lines.append("")
+            lines.append(f"- 任务编码: `{api_info.get('code', 'N/A')}`")
+            lines.append(f"- 端点: `{api_info.get('endpoint', 'N/A')}`")
+            lk = api_info.get("list_key")
+            if lk:
+                lines.append(f"- 数据路径: `data.{lk}`")
+            desc = api_info.get("description", "")
+            if desc:
+                lines.append(f"- 说明: {desc}")
+            lines.append("")
+
+        # ODS 表字段
+        ods_cols = ods_ddl.get(ods_t, [])
+        if ods_cols:
+            lines.append(f"### ODS 表: `{ods_t}` ({len(ods_cols)} 列)")
+            lines.append("")
+            lines.append("| # | 列名 | 类型 |")
+            lines.append("|---|------|------|")
+            for idx, c in enumerate(ods_cols, 1):
+                lines.append(f"| {idx} | `{c['col']}` | {c['type']} |")
+            lines.append("")
+
+        # DWD 表
+        dwd_tables = ods_to_dwd.get(ods_t, [])
+        if dwd_tables:
+            for dwd_t in sorted(dwd_tables):
+                dwd_cols = dwd_ddl.get(dwd_t, [])
+                is_dim = "dim_" in dwd_t
+                is_ex = dwd_t.endswith("_ex")
+                table_type = "维度" if is_dim else "事实"
+                if is_ex:
+                    table_type += "（扩展）"
+
+                mappings = fact_mappings.get(dwd_t, [])
+
+                lines.append(f"### DWD 表: `{dwd_t}` — {table_type} ({len(dwd_cols)} 列)")
+                lines.append("")
+
+                # 字段对比表
+                lines.append("| # | DWD 列名 | DWD 类型 | ODS 来源表达式 | 转换 | 备注 |")
+                lines.append("|---|----------|----------|----------------|------|------|")
+
+                # 建立映射查找
+                mapping_dict = {m[0]: (m[1], m[2]) for m in mappings}
+
+                for idx, c in enumerate(dwd_cols, 1):
+                    col_name = c["col"]
+                    col_type = c["type"]
+
+                    # SCD2 列
+                    scd2_cols = {"scd2_start_time", "scd2_end_time", "scd2_is_current", "scd2_version"}
+                    if col_name.lower().replace("scd2_", "scd2_") in scd2_cols or col_name.lower() in scd2_cols:
+                        lines.append(f"| {idx} | `{col_name}` | {col_type} | — | — | DWD 慢变元数据 |")
+                        continue
+
+                    if col_name in mapping_dict:
+                        ods_expr, cast = mapping_dict[col_name]
+                        cast_str = f"CAST → {cast}" if cast else "直接映射"
+                        # 判断是否为 JSONB 提取
+                        note = ""
+                        if "->>" in ods_expr:
+                            note = "JSONB 提取"
+                        elif "CASE" in ods_expr.upper():
+                            note = "派生计算"
+                        elif ods_expr != col_name:
+                            note = "字段重命名"
+                        lines.append(f"| {idx} | `{col_name}` | {col_type} | `{ods_expr}` | {cast_str} | {note} |")
+                    else:
+                        # 同名直传
+                        ods_col_names = {oc["col"].lower() for oc in ods_cols}
+                        if col_name.lower() in ods_col_names:
+                            lines.append(f"| {idx} | `{col_name}` | {col_type} | `{col_name}` | 直接映射 | 同名直传 |")
+                        else:
+                            lines.append(f"| {idx} | `{col_name}` | {col_type} | — | — | 未在 FACT_MAPPINGS 中显式映射 |")
+
+                lines.append("")
+        else:
+            lines.append(f"*该 ODS 表暂无 DWD 映射（仅用于 DWS 或其他下游）*")
+            lines.append("")
+
+        lines.append("---")
+        lines.append("")
+
+    # ── 附录：ETL 元数据列说明 ──
+    lines.append("## 附录：ETL 元数据列")
+    lines.append("")
+    lines.append("所有 ODS 表均包含以下 ETL 元数据列，不映射到 DWD：")
+    lines.append("")
+    lines.append("| 列名 | 类型 | 说明 |")
+    lines.append("|------|------|------|")
+    lines.append("| `content_hash` | TEXT | 记录内容哈希，用于去重和变更检测 |")
+    lines.append("| `source_file` | TEXT | 原始导出文件名，用于数据追溯 |")
+    lines.append("| `source_endpoint` | TEXT | 采集来源接口/文件路径 |")
+    lines.append("| `fetched_at` | TIMESTAMPTZ | 采集/入库时间戳 |")
+    lines.append("| `payload` | JSONB | 完整原始 JSON 记录快照 |")
+    lines.append("")
+
+    lines.append("## 附录：DWD 维度表 SCD2 列")
+    lines.append("")
+    lines.append("所有 DWD 维度表（`dim_*`）均包含以下 SCD2 慢变维度列：")
+    lines.append("")
+    lines.append("| 列名 | 类型 | 说明 |")
+    lines.append("|------|------|------|")
+    lines.append("| `scd2_start_time` | TIMESTAMPTZ | 版本生效起点 |")
+    lines.append("| `scd2_end_time` | TIMESTAMPTZ | 版本失效时间（9999-12-31 = 当前） |")
+    lines.append("| `scd2_is_current` | INT | 当前版本标记（1=当前，0=历史） |")
+    lines.append("| `scd2_version` | INT | 版本号（自增） |")
+    lines.append("")
+
+    lines.append("## 附录：DWD 事实表增量策略")
+    lines.append("")
+    lines.append("事实表按时间窗口增量写入，优先使用以下业务时间列进行过滤（按优先级排序）：")
+    lines.append("")
+    lines.append("1. `pay_time` — 支付时间")
+    lines.append("2. `create_time` — 创建时间")
+    lines.append("3. `update_time` — 更新时间")
+    lines.append("4. `occur_time` — 发生时间")
+    lines.append("5. `settle_time` — 结算时间")
+    lines.append("6. `start_use_time` — 开始使用时间")
+    lines.append("7. `fetched_at` — 入库时间（兜底）")
+    lines.append("")
+
+    # 写入文件
+    OUT.parent.mkdir(parents=True, exist_ok=True)
+    OUT.write_text("\n".join(lines), encoding="utf-8")
+    print(f"文档已生成: {OUT}")
+    print(f"  ODS 表: {len(ods_ddl)}, DWD 表: {len(dwd_ddl)}")
+    print(f"  TABLE_MAP: {len(table_map)} 条, FACT_MAPPINGS: {len(fact_mappings)} 条")
+    print(f"  ODS 任务: {len(ods_specs)} 个")
+
+
+if __name__ == "__main__":
+    generate_doc()