Neo-ZQYY/docs/audit/changes/2026-03-20__rns13-board-apis-e2e-fix.md

# 变更审计记录：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 语法验证通过