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

apps/etl/pipelines/feiqiu/docs/audit/changes/2026-02-14__api-ods-comparison-v3-fixed.md

@@ -0,0 +1,71 @@
+# 审计记录：API vs ODS 比对 v3-fixed
+
+## 基本信息
+
+- 日期：2026-02-14（Asia/Shanghai）
+- Prompt-ID：P20260214-003000
+- 原始原因：用户 Prompt — "还是不准，比如assistant_accounts_master（助教账号主数据）的last_update_name，命名Json里就有，再仔细比对下"
+- 直接原因：v3 比对仅从 JSON 样本提取字段，JSON 样本是单条记录快照，可能缺少条件性返回的字段（如 `last_update_name`），导致误报为"ODS独有"。需改用 API 参考文档（.md）的"响应字段详解"章节作为主要字段来源。
+
+## 修改方案
+
+完全重写 `scripts/run_compare_v3_fixed.py`：
+1. 从 .md 文档"四、响应字段详解"章节精确提取字段（排除请求参数、跨表关联等章节）
+2. JSON 样本作为补充来源（union）
+3. 对 settlement_records / recharge_settlements 的 siteProfile 子字段不提取（ODS 中存为 siteprofile jsonb 单列）
+4. 对 table_fee_discount_records 的 tableProfile/siteProfile 展开字段正确分类
+5. 对 stock_goods_category_tree 的 categoryBoxes 正确识别为 ODS jsonb 列
+6. 对所有 ODS 独有字段进行详细分类说明
+
+## Changed
+
+| 文件 | 变更类型 | 说明 |
+|------|----------|------|
+| `scripts/run_compare_v3_fixed.py` | 重写 | 完全重写字段提取和比对逻辑 |
+| `docs/reports/api_ods_comparison_v3_fixed.json` | 新建 | JSON 格式比对结果 |
+| `docs/reports/api_ods_comparison_v3_fixed.md` | 新建 | Markdown 格式比对报告 |
+| `docs/ai_audit/prompt_log.md` | 追加 | 新增 P20260214-003000 条目 |
+
+## 比对结论
+
+- 22 张 ODS 表全部比对
+- API 独有字段：0（所有 API 文档中的响应字段在 ODS 中都有对应列）
+- ODS 独有字段：51 列，分类如下：
+  - API 后续版本新增字段：38 列（文档快照未覆盖，但 ODS 已通过 ETL 动态发现并入库）
+  - tableProfile/siteProfile 嵌套对象展开字段：8 列（table_fee_discount_records）
+  - ODS 额外添加的 tenant_id：2 列（assistant_cancellation_records、payment_transactions）
+  - ODS jsonb 列（settlelist）：2 列（settlement_records、recharge_settlements）
+  - ODS 后续版本新增字段：1 列（site_tables_master.order_id）
+- 完全对齐表：7 张（assistant_accounts_master、refund_transactions、platform_coupon_redemption_records、stock_goods_category_tree、goods_stock_movements、goods_stock_summary、site_tables_master 除 order_id 外）
+- 无需 ALTER TABLE
+
+## Risk / Verify
+
+- 风险：纯分析脚本和报告，无运行时影响，不修改数据库或 ETL 逻辑
+- 验证：
+  1. 确认 `assistant_accounts_master` 的 `last_update_name` 被正确识别为匹配字段（62:62 完全对齐）
+  2. 确认 API 独有字段总数为 0
+  3. 确认 ODS 独有字段全部有分类说明
+
+## Change Impact Review
+
+- 判定：**无逻辑改动**
+- 本次变更为纯分析脚本（一次性工具）和报告文档，不涉及 ETL 管线、业务规则、数据处理逻辑、API 行为或数据库 schema
+- 文档同步评估：
+  - `product.md` — 无需更新（产品功能未变）
+  - `tech.md` — 无需更新（技术栈未变）
+  - `structure.md` — 无需更新（目录结构未变，临时分析脚本不列入）
+  - `README.md` — 无需更新（运行方式未变）
+  - `docs/bd_manual/` — 无需更新（无表结构变更）
+  - `gui/README.md` / `scripts/` / `tasks/` / `database/` / `tests/` — 均无需更新
+- 回归范围：无（纯分析产出，不影响任何运行时代码路径）
+- 建议验证：`python scripts/run_compare_v3_fixed.py` 确认输出 API独有=0
+
+<!--
+AI_CHANGELOG:
+- 日期: 2026-02-14
+- Prompt: P20260214-003000 — v3 比对不准确，重写为 v3-fixed
+- 直接原因: 创建审计记录
+- 变更摘要: 新建审计记录文件，记录 v3-fixed 比对的完整变更信息
+- 风险与验证: 纯文档，无运行时影响
+-->