199 lines
13 KiB
Markdown
199 lines
13 KiB
Markdown
# 项目变更日志（CHANGELOG）
|
||
|
||
> 基于 `docs/audit/changes/` 审计记录整理的项目级版本变更历史。
|
||
> 按日期倒序排列，每条记录包含日期、变更摘要和影响范围。
|
||
|
||
---
|
||
|
||
## 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)
|