Neo-ZQYY/apps/etl/connectors/feiqiu/docs/CHANGELOG.md

项目变更日志（CHANGELOG）

基于 docs/audit/changes/ 审计记录整理的项目级版本变更历史。 按日期倒序排列，每条记录包含日期、变更摘要和影响范围。

---

2026-02-26

文档审计 — 任务统计、业务口径、SCD2 规则全面校正

• 摘要：对 docs/ 下 9 个文档进行系统性审计与修正，以 task_registry.py 为唯一事实来源，修复任务数量、域分组、表名、工具链引用等 15 处不一致
• 修正清单：
  • docs/README.md：移除不存在的 audit/、reports/ 目录引用
  • docs/etl_tasks/README.md：ODS 22→23、DWS 13→17、补充 ODS_STAFF_INFO/DWS_ASSISTANT_ORDER_CONTRIBUTION/库存汇总域/SPI
  • docs/etl_tasks/ods_tasks.md：任务总数 22→23
  • docs/etl_tasks/dws_tasks.md：任务总数 14→17、域分组四组→五组、补充库存汇总域概述表格
  • docs/etl_tasks/base_task_mechanism.md：DWS 13→17、INDEX 4→5
  • docs/operations/environment_setup.md：移除重复段落
  • docs/operations/troubleshooting.md：pip install -r requirements.txt → uv sync
  • docs/business-rules/dws_metrics.md：完全重写，移除不存在的表、修正表名、补充库存汇总域和指数算法章节
  • docs/business-rules/scd2_rules.md：完全重写，填充 9 个维度表的实际跟踪字段、补充 dim_staff 维度、文档化变更检测机制
• 影响范围：文档（docs/ 全目录，无代码变更）
• 风险：极低（纯文档修正）

---

2026-02-19

文档全面刷新 — Schema 名称、技术栈、任务统计同步至项目现状

• 摘要：批量更新 docs/ 下 144 个文档文件，将旧 schema 名称（billiards_ods/billiards_dwd/billiards_dws/etl_admin）统一替换为当前六层架构名称（ods/dwd/dws/meta）；更新 system_overview.md 移除已废弃的 PySide6 GUI 和 Flask 引用，替换为 FastAPI + admin-web；修正 ODS 任务数量（16→23）和 DWD 任务数量（5→2）；更新 environment_setup.md 安装方式（pip→uv sync）、DDL 路径、运行入口；补充 scheduling.md 缺失的 CLI 参数（--force-full、--window-split-unit、--window-split-days、--window-compensation-hours）；data_flow.md 新增 INDEX 层数据流图
• 影响范围：文档（docs/ 全目录，含 architecture/、etl_tasks/、operations/、database/、business-rules/ 等）
• 风险：极低（纯文档变更，无代码修改）

---

2026-02-15

审计目录整合与 API 文档字段归类修正

• 摘要：将 docs/ai_audit/ 旧目录内容统一归入 docs/audit/；修正 5 个 API 参考文档（summary/）的字段归类错误；为 3 个已有逻辑变更文件补全 AI_CHANGELOG 注释
• 影响范围：文档（docs/api-reference/summary/、docs/audit/）、代码注释（tasks/base_task.py、quality/）
• 风险：极低（纯文档重组与注释补录）
• 详情：审计记录

docs/bd_manual + docs/dictionary → docs/database 合并

• 摘要：将分散的 docs/bd_manual/ 和 docs/dictionary/ 合并为统一路径 docs/database/，按数据层（ODS/DWD/DWS/ETL_Admin/overview）分目录；更新所有路径引用（脚本、steering、hooks）
• 影响范围：文档路径（docs/database/）、脚本（scripts/validate_bd_manual.py）、配置（.kiro/steering/、.kiro/hooks/、.kiro/skills/）
• 风险：极低（纯路径重组，无运行时代码变更）
• 详情：审计记录

docs/index + docs/开发笔记 清理与路径整合

• 摘要：将 docs/index/index_algorithm_cn.md 移至 docs/database/DWS/；从 docs/开发笔记/ 分拣 6 个有价值文件至 docs/requirements/，删除过期内容；更新引用和测试
• 影响范围：文档路径（docs/database/DWS/、docs/requirements/）、脚本（scripts/audit/doc_alignment_analyzer.py）、测试（tests/unit/test_audit_doc_alignment.py）
• 风险：低（纯文档重组 + 脚本路径更新）
• 详情：审计记录

---

2026-02-14

API 文档归档至 summary/ + 字段分组修正

• 摘要：25 个 API 参考文档从根目录移至 docs/api-reference/summary/；修正 7 个文档的"响应字段详解"章节字段归类错误（非时间字段混入"时间"组等）
• 影响范围：文档（docs/api-reference/summary/、docs/api-reference/README.md）
• 风险：极低（纯文档分组调整）
• 详情：审计记录

API vs ODS 比对 v3-fixed

• 摘要：重写比对脚本，改用 API 参考文档（.md）的"响应字段详解"章节作为主要字段来源（替代 JSON 样本），解决 v3 中条件性字段误报问题；22 张 ODS 表全部比对，API 独有字段 0 个
• 影响范围：脚本（scripts/run_compare_v3_fixed.py）、报告（docs/reports/）
• 风险：极低（纯分析脚本和报告）
• 详情：审计记录

API vs ODS 逐表比对 v3

• 摘要：从 JSON 样本直接提取字段并与数据库实际列精确比对，逐表重做（替代 v2 不准确的结果）
• 影响范围：脚本（scripts/run_compare_v3.py、scripts/compare_api_ods_v3.py）、报告（docs/reports/）
• 风险：极低（纯分析脚本和报告）
• 详情：审计记录

API 参数校对 + ODS 设计方案输出

• 摘要：验证 25 个 API 的 .md 文档请求体参数与 API.txt 一致性（全部通过）；输出 tenant_member_balance_overview 的主表+子表 ODS 设计方案（待用户确认后执行）
• 影响范围：文档（docs/ai_audit/）
• 风险：极低（纯审计日志 + 对话输出）
• 详情：审计记录

删除 DWD 层 settle_list 冗余列

• 摘要：删除 dwd_settlement_head_ex.settle_list JSONB 列（与 ODS payload 中的 settleList 重复）；同步移除 DWD 加载映射
• 影响范围：数据库（billiards_dwd.dwd_settlement_head_ex）、ETL（tasks/dwd/dwd_load_task.py）、迁移脚本
• 风险：中（DB schema 变更，需确认下游无引用）
• 详情：审计记录

删除 ODS 层 settlelist 冗余列

• 摘要：删除 settlement_records 和 recharge_settlements 的 settlelist jsonb 列（与 payload 列数据重复）；DWD 加载改为从 payload->'settleList' 提取
• 影响范围：数据库（billiards_ods）、ETL（tasks/dwd/dwd_load_task.py）、脚本、报告
• 风险：中（DB schema 变更，历史 payload IS NULL 的行将永久丢失 settleList）
• 详情：审计记录

DWS 基类 bugfix — 绩效档位兜底 + safe_decimal 异常捕获

• 摘要：修复 get_performance_tier() 在封顶场景下返回 None 的 bug；修复 safe_decimal() 未捕获 decimal.InvalidOperation 的问题；修复 3 处测试 bug
• 影响范围：业务代码（tasks/dws/base_dws_task.py）、测试（tests/unit/test_dws_tasks.py）
• 风险：低（防御性修复，不改变正常路径行为）
• 详情：审计记录

全量 JSON 刷新 + MD 文档补全 + 数据路径修正

• 摘要：全部 24 个 JSON 样本刷新为 100 条数据；10 个 MD 文档补全共 39 个缺失字段；修正 api_registry.json 中 17 个端点的 data_path
• 影响范围：文档（docs/api-reference/）、脚本（scripts/refresh_json_and_audit.py）、报告
• 风险：极低（纯文档和脚本变更）
• 详情：审计记录

JSON 样本 vs MD 文档全面排查

• 摘要：编写比对脚本验证 24 个表的 .md 文档与 JSON 样本字段一致性，全部通过（4 个表有条件性字段差异属正常）
• 影响范围：脚本（scripts/check_json_vs_md.py）、报告（docs/reports/）
• 风险：极低（纯分析脚本和报告）
• 详情：审计记录

废弃独立 ODS/DWD 任务代码清理 + 文档同步

• 摘要：清理 14 个废弃独立 ODS 任务和 3 个废弃 DWD 任务的残留引用（注册表重复循环、测试工具废弃定义、过时文档）；重写 docs/etl_tasks/ 文档
• 影响范围：调度（orchestration/task_registry.py）、测试工具（tests/unit/task_test_utils.py）、文档（docs/etl_tasks/）、配置（.kiro/steering/tech.md）
• 风险：中（task_registry.py 是核心入口，需确认 52 个任务全部正确注册）
• 详情：审计记录

MD 占位符修正 + 临时文件清理

• 摘要：修正 5 个 API 文档中 v2 脚本自动插入的占位符描述为正式中文说明；合并/去重字段；清理 25 个临时 JSON 文件和 3 个临时脚本
• 影响范围：文档（docs/api-reference/）、报告
• 风险：极低（纯文档修正）
• 详情：审计记录

ODS 清理与文档标注

• 摘要：删除 ODS 层 2 个全 NULL 冗余列（option_name、able_site_transfer）；4 个 API 独有字段标记"暂不入 ODS"；补充 8 个 tableProfile 展开字段文档
• 影响范围：数据库（billiards_ods）、DDL（database/schema_ODS_doc.sql）、文档、脚本、报告
• 风险：低（删除的列全 NULL，无数据丢失）
• 详情：审计记录

ODS vs Summary 字段比对

• 摘要：编写脚本直接查询 PostgreSQL billiards_ods schema 与 25 个 summary MD 文档逐表比对；多轮修复比对脚本 bug（skip_words 误过滤、siteProfile 误跳过等），最终完全匹配 17 张表
• 影响范围：脚本（scripts/compare_ods_vs_summary_v2.py）、报告
• 风险：极低（纯分析脚本）
• 详情：审计记录

api/recording_client.py 默认时区修正

• 摘要：将 build_recording_client 默认时区从 Asia/Taipei 改为 Asia/Shanghai，语义更准确（实际偏移量无差异）
• 影响范围：API 客户端（api/recording_client.py）
• 风险：极低（两个时区当前 UTC 偏移相同）
• 详情：审计记录

替换 role_area_association 为 member_consumption_statistics

• 摘要：用会员消费统计 API（QueryMemberConsumptionStatistics）替换权限配置查询 API（role_area_association）；新建 JSON 样本和参考文档；输出 2 个新表的 ODS 设计方案
• 影响范围：文档（docs/api-reference/）
• 风险：极低（纯文档变更）
• 详情：审计记录

skip_words 误过滤 remark 业务字段修复

• 摘要：修复比对脚本中 skip_words 误过滤 remark/note/type 等真实业务字段的问题；最终用 Markdown 表格分隔行检测替代 skip_words 方案；修复 siteProfile 子节跳过逻辑和 goodsCategoryList 包装器忽略
• 影响范围：脚本（scripts/compare_ods_vs_summary_v2.py）、报告
• 风险：极低（纯分析脚本）
• 详情：审计记录

---

2026-02-13

API vs ODS 对比 v2

• 摘要：重写比对脚本（v1 存在嵌套结构解析 bug），从 API 参考文档提取字段与 PostgreSQL billiards_ods 实际列比对；22 张 ODS 表全部对齐，0 张漂移
• 影响范围：脚本（scripts/compare_api_ods_v2.py）、报告（docs/reports/）
• 风险：极低（纯分析脚本 + 报告文档）
• 详情：审计记录

API JSON 字段 vs ODS 表列对比

• 摘要：编写 Python 脚本查询 billiards_ods 的 information_schema.columns，与 API 参考文档做 camelCase→snake_case 归一化匹配；22 张 ODS 表全部对齐，无需 ALTER
• 影响范围：脚本（scripts/compare_api_ods.py）、报告（docs/reports/）、迁移脚本（空操作）
• 风险：低（纯分析工具，不修改数据库）
• 详情：审计记录

API 参考文档批量生成（第二批 6 个）

• 摘要：按标杆文档格式生成 6 个高质量 API 参考文档（member_profiles、member_stored_value_cards、member_balance_changes、platform_coupon_redemption_records、group_buy_packages、group_buy_redemption_records）
• 影响范围：文档（docs/api-reference/）
• 风险：极低（纯文档变更）
• 详情：审计记录

API 参考文档全面重构

• 摘要：对 23+ API 文档进行全面重构，创建结构化的 docs/api-reference/ 目录体系（endpoints/、samples/）；生成 25 个端点文档、24 个响应样本、标准化 API 注册表；废弃旧 test-json-doc 目录
• 影响范围：文档（docs/api-reference/）、配置（.kiro/steering/structure.md）
• 风险：极低（纯文档生成和目录结构调整）
• 详情：审计记录

BD_Manual 文档整理与 DDL 同步

• 摘要：修复 DDL 对比脚本 bug；同步 ODS/DWD/DWS 三层共 13 项 DDL 差异；生成 ODS 23 张表的表级文档、映射文档和数据字典；创建 BD_Manual 根索引和文档验证脚本
• 影响范围：DDL（database/schema_ODS_doc.sql、database/schema_dws.sql）、脚本（scripts/compare_ddl_db.py、scripts/validate_bd_manual.py）、文档（docs/bd_manual/、docs/dictionary/）、测试
• 风险：中（DDL 文件修正，虽未变更数据库结构但被其他脚本引用）
• 详情：审计记录

API 字段漂移报告修正更新

• 摘要：用正确的 limit 参数重新调用 3 个端点（settlement_records、recharge_settlements、payment_transactions），更新字段漂移报告；发现 5 个新增字段（电费、商户券/平台券相关）
• 影响范围：报告（docs/reports/）
• 风险：极低（纯文档更新）
• 详情：审计记录

移除旧版指数（RECALL/INTIMACY）+ ML last-touch 清理

• 摘要：彻底删除已被 WBI+NCI 替代的 RecallIndexTask 和已被 RelationIndexTask 替代的 IntimacyIndexTask；修复 WBI STOP_HIGH_BALANCE 评分 bug；移除 ML last-touch 备用路径；清理 GUI、调度注册、数据库对象和文档中的所有引用
• 影响范围：业务代码（tasks/dws/index/）、调度（orchestration/task_registry.py）、GUI（gui/）、数据库（DDL + seed + 迁移脚本）、文档、测试
• 风险：中（不可逆的 DROP TABLE，但用户确认不需要向后兼容）
• 详情：审计记录