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

apps/etl/pipelines/feiqiu/docs/audit/changes/2026-02-13__api-ods-comparison-v2.md

@@ -0,0 +1,38 @@
+# 审计记录：API vs ODS 对比 v2
+
+- 日期：2026-02-13（Asia/Shanghai）
+- Prompt-ID：P20260213-223000
+- 原始原因：用户要求用 API 参考文档比对数据库 ODS 实际表结构（不依赖 DDL），生成对比报告和 ALTER SQL。上一次运行结果不准确，要求重做。
+- 直接原因：前次比对脚本存在 bug（stock_goods_category_tree 嵌套结构未正确解析），需重写脚本并重新生成报告。
+
+## 改动方案
+
+1. 重写 `scripts/compare_api_ods_v2.py`：
+   - 从 `docs/api-reference/*.md` 的 JSON 样例提取字段
+   - 查询 PostgreSQL `billiards_ods` 实际列
+   - 处理三种特殊结构：标准 `data.list`、嵌套 `siteProfile+settleList`、数组包装 `goodsCategoryList`
+   - 输出 JSON + Markdown 报告
+2. 运行脚本，生成 `docs/reports/api_ods_comparison_v2.json` 和 `.md`
+
+## 结论
+
+- 22 张 ODS 表全部与 API JSON 字段对齐（API 字段 ⊆ ODS 列）
+- 0 张漂移，无需 ALTER SQL
+- 3 张跳过（settlement_ticket_details 标记 skip，role_area_association / tenant_member_balance_overview 无 ODS 表）
+- ODS 独有列共 97 个（非元列），均为 ETL 派生列或历史新增字段，API 样例中不存在但不影响数据完整性
+
+## Changed
+
+| 文件 | 操作 |
+|------|------|
+| `scripts/compare_api_ods_v2.py` | 重写（完整脚本） |
+| `docs/reports/api_ods_comparison_v2.json` | 新建（JSON 报告） |
+| `docs/reports/api_ods_comparison_v2.md` | 新建（Markdown 报告） |
+
+## Risk / Verify
+
+- 风险：纯分析脚本 + 报告文档，无运行时影响，不修改数据库
+- 验证：
+  1. `python scripts/compare_api_ods_v2.py` 输出 "对齐 22 / 漂移 0"
+  2. 检查 `docs/reports/api_ods_comparison_v2.md` 汇总表中无 ⚠️ 漂移行
+  3. JSON 报告中所有 `api_only` 数组为空