# 项目变更日志（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/`）
- **风险**：极低（纯文档重组与注释补录）
- **详情**：[审计记录](audit/changes/2026-02-15__audit-consolidation-doc-reorg.md)

### 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/`）
- **风险**：极低（纯路径重组，无运行时代码变更）
- **详情**：[审计记录](audit/changes/2026-02-15__docs-database-merge.md)

### 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`）
- **风险**：低（纯文档重组 + 脚本路径更新）
- **详情**：[审计记录](audit/changes/2026-02-15__docs-devnotes-index-cleanup.md)

---

## 2026-02-14

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

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

### API vs ODS 比对 v3-fixed

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

### API vs ODS 逐表比对 v3

- **摘要**：从 JSON 样本直接提取字段并与数据库实际列精确比对，逐表重做（替代 v2 不准确的结果）
- **影响范围**：脚本（`scripts/run_compare_v3.py`、`scripts/compare_api_ods_v3.py`）、报告（`docs/reports/`）
- **风险**：极低（纯分析脚本和报告）
- **详情**：[审计记录](audit/changes/2026-02-14__api-ods-comparison-v3.md)

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

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

### 删除 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 变更，需确认下游无引用）
- **详情**：[审计记录](audit/changes/2026-02-14__drop-dwd-settle-list.md)

### 删除 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）
- **详情**：[审计记录](audit/changes/2026-02-14__drop-ods-settlelist.md)

### 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`）
- **风险**：低（防御性修复，不改变正常路径行为）
- **详情**：[审计记录](audit/changes/2026-02-14__dws-bugfix-tier-safedecimal.md)

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

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

### JSON 样本 vs MD 文档全面排查

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

### 废弃独立 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 个任务全部正确注册）
- **详情**：[审计记录](audit/changes/2026-02-14__legacy-ods-dwd-cleanup.md)

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

- **摘要**：修正 5 个 API 文档中 v2 脚本自动插入的占位符描述为正式中文说明；合并/去重字段；清理 25 个临时 JSON 文件和 3 个临时脚本
- **影响范围**：文档（`docs/api-reference/`）、报告
- **风险**：极低（纯文档修正）
- **详情**：[审计记录](audit/changes/2026-02-14__md-placeholder-fix-cleanup.md)

### ODS 清理与文档标注

- **摘要**：删除 ODS 层 2 个全 NULL 冗余列（`option_name`、`able_site_transfer`）；4 个 API 独有字段标记"暂不入 ODS"；补充 8 个 tableProfile 展开字段文档
- **影响范围**：数据库（`billiards_ods`）、DDL（`database/schema_ODS_doc.sql`）、文档、脚本、报告
- **风险**：低（删除的列全 NULL，无数据丢失）
- **详情**：[审计记录](audit/changes/2026-02-14__ods-cleanup-doc-update.md)

### ODS vs Summary 字段比对

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

### api/recording_client.py 默认时区修正

- **摘要**：将 `build_recording_client` 默认时区从 `Asia/Taipei` 改为 `Asia/Shanghai`，语义更准确（实际偏移量无差异）
- **影响范围**：API 客户端（`api/recording_client.py`）
- **风险**：极低（两个时区当前 UTC 偏移相同）
- **详情**：[审计记录](audit/changes/2026-02-14__recording-client-timezone-fix.md)

### 替换 role_area_association 为 member_consumption_statistics

- **摘要**：用会员消费统计 API（QueryMemberConsumptionStatistics）替换权限配置查询 API（role_area_association）；新建 JSON 样本和参考文档；输出 2 个新表的 ODS 设计方案
- **影响范围**：文档（`docs/api-reference/`）
- **风险**：极低（纯文档变更）
- **详情**：[审计记录](audit/changes/2026-02-14__replace-role-area-new-api-doc.md)

### skip_words 误过滤 remark 业务字段修复

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

---

## 2026-02-13

### API vs ODS 对比 v2

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

### API JSON 字段 vs ODS 表列对比

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

### 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/`）
- **风险**：极低（纯文档变更）
- **详情**：[审计记录](audit/changes/2026-02-13__api-reference-batch2.md)

### API 参考文档全面重构

- **摘要**：对 23+ API 文档进行全面重构，创建结构化的 `docs/api-reference/` 目录体系（endpoints/、samples/）；生成 25 个端点文档、24 个响应样本、标准化 API 注册表；废弃旧 `test-json-doc` 目录
- **影响范围**：文档（`docs/api-reference/`）、配置（`.kiro/steering/structure.md`）
- **风险**：极低（纯文档生成和目录结构调整）
- **详情**：[审计记录](audit/changes/2026-02-13__api-reference-overhaul.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 文件修正，虽未变更数据库结构但被其他脚本引用）
- **详情**：[审计记录](audit/changes/2026-02-13__bd-manual-docs-consolidation-ddl-sync.md)

### API 字段漂移报告修正更新

- **摘要**：用正确的 `limit` 参数重新调用 3 个端点（settlement_records、recharge_settlements、payment_transactions），更新字段漂移报告；发现 5 个新增字段（电费、商户券/平台券相关）
- **影响范围**：报告（`docs/reports/`）
- **风险**：极低（纯文档更新）
- **详情**：[审计记录](audit/changes/2026-02-13__field-drift-report-update.md)

### 移除旧版指数（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，但用户确认不需要向后兼容）
- **详情**：[审计记录](audit/changes/2026-02-13__remove-legacy-index-cleanup.md)