chore(audit): 补追 96 份未入仓审计孤本 — 覆盖 2026-02-26 ~ 2026-04-08
这些审计记录原本堆积在 docs/audit/changes/changes/ 嵌套误产物目录下（由开发机迁移
79d3c2e 前后的不明批量操作产生）。由于同期 .gitignore 屏蔽了 docs/audit/ 全目录，
它们从未入过 git 任何分支 history。删除即永久丢失。
按 docs/specs/audit-gap-recovery/tasks.md 阶段 1 执行，将全部 96 份 D 类孤本
（主目录无同名、git history 亦无记录）复制到 docs/audit/changes/ 主目录入仓。
涵盖主题: P1-P18 全栈集成 / 多模块累积变更 / ETL bug 修复 / 业务日切 /
召回与任务引擎改造 / 租户管理与审批 / 董事会财务 / 客户与助教详情 /
DDL 基线合并 / Kiro 到 Claude Code 迁移
阶段 2（B 类内容漂移 1 份）和阶段 4（嵌套目录删除）独立推进。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
171
docs/audit/changes/2026-03-20__rns13-board-apis-e2e-fix.md
Normal file
171
docs/audit/changes/2026-03-20__rns13-board-apis-e2e-fix.md
Normal file
@@ -0,0 +1,171 @@
|
||||
# 变更审计记录：RNS1.3 三看板 FDW 查询层数据口径修复
|
||||
|
||||
| 字段 | 值 |
|
||||
|------|-----|
|
||||
| 日期 | 2026-03-19 16:23:59 |
|
||||
| Prompt-ID | P20260319-160132 |
|
||||
| Session-ID | 088656c4 |
|
||||
| Session 路径 | docs/audit/session_logs/2026-03/19/41_54e4189f_160131 |
|
||||
|
||||
## 操作摘要
|
||||
|
||||
根据 feiqiu-data-rules 审计 rns1-board-apis SPEC 实现，修复 `fdw_queries.py` 中 6 个函数的数据口径和功能缺陷。审计发现 9 个问题（3 P0 + 3 P1 + 3 P2），本次修复可修复的 6 个（P0 全部 + P1-4/5 + P2-7）。同时完成 E2E 测试修正、board_service 环比逻辑修正、文档同步更新。
|
||||
|
||||
---
|
||||
|
||||
## 1. 变更原因
|
||||
|
||||
### 原始原因（Prompt）
|
||||
CONTEXT TRANSFER：继续 rns1-board-apis spec Tasks 17-20（全量验证、E2E 测试、文档更新、审计）。用户要求"先查库，然后对比 dws-doc-authority.md，若吻合，则修改代码"。
|
||||
|
||||
### 直接原因
|
||||
feiqiu-data-rules 审计发现 fdw_queries.py 中 6 个函数存在数据口径错误或功能缺失：
|
||||
- P0-1: 储值金额数据源错误
|
||||
- P0-2: 消费潜力指数未实际查询
|
||||
- P0-3: 财务收入层级映射错误
|
||||
- P1-4: 助教技能筛选未实现
|
||||
- P1-5: 项目筛选未实现
|
||||
- P2-7: ideal_days 硬编码为 0
|
||||
|
||||
---
|
||||
|
||||
## 2. 改动方案
|
||||
|
||||
### 2.1 fdw_queries.py — 6 个函数修复
|
||||
|
||||
| 编号 | 函数 | 修复内容 |
|
||||
|------|------|---------|
|
||||
| P0-1 | `get_coach_sv_data()` | 数据源从 `v_dws_assistant_monthly_summary` 改为 `v_dws_assistant_recharge_commission`，修正储值金额口径 |
|
||||
| P0-2 | `get_customer_board_potential()` | 从空列表降级改为实际查询 `v_dws_member_spending_power_index`，支持消费潜力指数排行 |
|
||||
| P0-3 | `get_finance_revenue()` | 修复 `structure_type` 层级映射（AREA→is_sub=True），填充 `price_items` 和 `channel_items` |
|
||||
| P1-4 | `get_all_assistants()` | 通过 LEFT JOIN `v_dws_assistant_project_tag` 实现 `skill_filter` 筛选 |
|
||||
| P1-5 | `_project_filter_clause()` | 通过 `v_dws_member_project_tag` 子查询实现项目筛选 |
|
||||
| P2-7 | `get_customer_board_recent()` | `ideal_days` 从 `v_dws_member_winback_index.ideal_interval_days` 获取，不再硬编码为 0 |
|
||||
|
||||
新增辅助函数 `_derive_potential_tags()`。
|
||||
|
||||
### 2.2 FDW 列名修正（17 处）
|
||||
|
||||
| 视图 | 修正数量 | 关键映射 |
|
||||
|------|---------|---------|
|
||||
| `v_dws_finance_daily_summary` | 6 | occurrence→gross_amount, discount→discount_total, confirmed_revenue→confirmed_income, cash_in→cash_inflow_total, cash_out→cash_outflow_total, cash_balance→cash_balance_change |
|
||||
| `v_dws_finance_recharge_summary` | 4 | actual_income→recharge_cash, first_charge→first_recharge_cash, renew_charge→renewal_cash, card_balance→cash_card_balance |
|
||||
| `v_dws_member_winback_index` | 2 | ideal_days→ideal_interval_days, wbi_score→display_score |
|
||||
| `v_dws_member_consumption_summary` | 1 | items_sum_60d→consume_amount_60d |
|
||||
| `v_dim_member_card_account` | 1 | balance_amount→balance |
|
||||
| `v_dws_finance_expense_summary` + `v_dws_platform_settlement` | 3 | expense_group→expense_category, stat_date→expense_month/settlement_date |
|
||||
|
||||
### 2.3 board_service.py 修正
|
||||
- `_build_recharge` 环比比较逻辑修正（compare 参数正确传递）
|
||||
- `_empty_revenue` 新增完整空默认值工厂（含 price_items, channel_items 等必需字段）
|
||||
- skills 字段暂返回空列表
|
||||
|
||||
### 2.4 gift_rows GiftCell 修正
|
||||
赠送卡 3×4 矩阵每个 cell 从裸 float 改为 `{"value": float}` dict，匹配 Pydantic GiftCell schema。
|
||||
|
||||
### 2.5 E2E 测试（test_e2e_board.py）
|
||||
22 个集成测试覆盖：四端点基本请求、环比开关、参数互斥、分页、区域约束、权限校验、camelCase 序列化。
|
||||
|
||||
### 2.6 文档更新
|
||||
- `docs/contracts/openapi/backend-api.json`：新增 4 端点 + 5 schema
|
||||
- `docs/database/BD_Manual_biz_tables.md`：补充 coach_tasks 看板场景引用说明
|
||||
|
||||
---
|
||||
|
||||
## 3. 未修复项（已知限制）
|
||||
|
||||
| 编号 | 问题 | 原因 |
|
||||
|------|------|------|
|
||||
| P1-6 | 礼品卡矩阵无细分数据 | ETL 层无 liquor/table_fee/voucher 细分列，需 ETL 侧先补数据 |
|
||||
| P2-8 | expense 日期粒度差异 | 低风险，显示层可接受 |
|
||||
| P2-9 | level 映射硬编码 | 显示层低风险，后续可迁移至配置表 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 本次对话文件变更
|
||||
|
||||
### 新增文件
|
||||
- `docs/audit/changes/2026-03-20__rns13-board-apis-e2e-fix.md`（本文件）
|
||||
- `docs/audit/prompt_logs/prompt_log_20260319_160132.md`
|
||||
- `docs/audit/session_logs/2026-03/19/38_d68afacc_154946/main_01_a7041a46.md`
|
||||
- `docs/audit/session_logs/2026-03/19/40_fd008ef9_155123/main_01_c4a82443.md`
|
||||
- `docs/audit/session_logs/2026-03/19/40_fd008ef9_155123/sub_01_c4a82443.md`
|
||||
- `docs/audit/session_logs/2026-03/19/40_fd008ef9_155123/sub_02_c4a82443.md`
|
||||
|
||||
### 删除文件
|
||||
- `docs/audit/session_logs/2026-03/19/38_d68afacc_154946/main_01_d94c682a.md`（被 main_01_a7041a46.md 替代）
|
||||
|
||||
---
|
||||
|
||||
## 5. 文件清单
|
||||
|
||||
| 文件 | 变更类型 | 说明 |
|
||||
|------|---------|------|
|
||||
| `apps/backend/app/services/fdw_queries.py` | 修改 | 6 函数修复 + 17 处列名修正 + gift_rows GiftCell + 新增 `_derive_potential_tags()` |
|
||||
| `apps/backend/app/services/board_service.py` | 修改 | _build_recharge 环比 + _empty_revenue + skills 空列表 |
|
||||
| `apps/backend/tests/integration/test_e2e_board.py` | 修改 | 22 个 E2E 集成测试修正 |
|
||||
| `docs/contracts/openapi/backend-api.json` | 修改 | 4 端点 + 5 schema |
|
||||
| `docs/database/BD_Manual_biz_tables.md` | 修改 | RNS1.3 看板引用说明 |
|
||||
| `.kiro/specs/rns1-board-apis/tasks.md` | 修改 | Tasks 17-20 标记完成 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 数据库变更
|
||||
|
||||
**无 DDL 变更。** 本次实现全部基于已有的 `app.v_*` RLS 视图执行 SELECT 查询。`IMPORT FOREIGN SCHEMA app` 在 `setup_fdw.sql` 中已自动导入所有视图，无需新增 FDW 映射。
|
||||
|
||||
⚠️ DDL 基线待合并（`compliance.has_ddl_baseline` = false）
|
||||
|
||||
---
|
||||
|
||||
## 7. 改动注解
|
||||
|
||||
### `apps/backend/app/services/fdw_queries.py`
|
||||
- 变更类型：修改
|
||||
- 原始原因：feiqiu-data-rules 审计发现 6 个函数的数据口径与 DWS 权威规范不一致，部分功能未实现（空列表降级、硬编码 0）
|
||||
- 思路分析：逐函数对照 dws-doc-authority.md 和实际视图结构修正。P0-1 改用正确的储值佣金视图；P0-2 从降级空列表改为实际查询消费潜力指数视图；P0-3 修正 AREA 层级映射并填充 price_items/channel_items；P1-4/5 通过 LEFT JOIN 和子查询实现筛选功能；P2-7 从视图获取 ideal_interval_days 替代硬编码。新增 `_derive_potential_tags()` 辅助函数用于消费潜力标签推导
|
||||
- 修改结果：6 个函数数据口径与 DWS 规范对齐，skill_filter 和 project_filter 功能可用。影响 board_service.py 的三看板数据展示。17 处 FDW 列名映射同步修正
|
||||
|
||||
### `apps/backend/app/services/board_service.py`
|
||||
- 变更类型：修改
|
||||
- 原始原因：fdw_queries.py 修复后，board_service 的环比逻辑和空默认值需要同步适配
|
||||
- 思路分析：`_build_recharge` 的 compare 参数传递链路修正；`_empty_revenue` 补全 price_items、channel_items 等必需字段避免前端渲染报错；skills 字段暂返回空列表（待 ETL 补数据后启用）
|
||||
- 修改结果：三看板接口在数据为空时不再抛异常，返回结构完整的空响应
|
||||
|
||||
### `apps/backend/tests/integration/test_e2e_board.py`
|
||||
- 变更类型：修改
|
||||
- 原始原因：fdw_queries.py 列名修正后，E2E 测试中的 mock 数据和断言需同步更新
|
||||
- 思路分析：更新 22 个测试用例中涉及的列名引用，确保 mock 数据结构与修正后的查询一致
|
||||
- 修改结果：22 个 E2E 集成测试全部通过
|
||||
|
||||
### `docs/database/BD_Manual_biz_tables.md`
|
||||
- 变更类型：修改（简要）
|
||||
- 补充 coach_tasks 在 RNS1.3 看板场景中的引用说明
|
||||
|
||||
### `docs/contracts/openapi/backend-api.json`
|
||||
- 变更类型：修改（简要）
|
||||
- 新增 BOARD-1/2/3 + CONFIG-1 共 4 个端点定义和 5 个 schema
|
||||
|
||||
### `.kiro/specs/rns1-board-apis/tasks.md`
|
||||
- 变更类型：修改（简要）
|
||||
- Tasks 17-20 子任务标记为已完成
|
||||
|
||||
---
|
||||
|
||||
## 8. 风险与回滚
|
||||
|
||||
### 风险
|
||||
- 列名映射依赖当前 ETL 视图定义，ETL 视图变更时需同步更新 fdw_queries.py
|
||||
- 降级处理（空列表/返回 0）在 ETL 数据补全后需移除
|
||||
- P1-6（礼品卡矩阵细分）依赖 ETL 侧补数据，当前返回 0
|
||||
|
||||
### 回滚
|
||||
代码层面 revert fdw_queries.py + board_service.py 即可，无数据库回滚需求。
|
||||
|
||||
---
|
||||
|
||||
## 9. 验证
|
||||
|
||||
- 17 个属性测试全部通过（`pytest tests/test_board_properties.py -v`）
|
||||
- 22 个 E2E 集成测试全部通过（`pytest apps/backend/tests/integration/test_e2e_board.py -v`）
|
||||
- OpenAPI JSON 语法验证通过
|
||||
Reference in New Issue
Block a user