# 变更审计记录：财务看板 5 项修复（ODS 行膨胀 / 优惠分摊 / 环比字段 / 区域过滤 / 规范沉淀）

| 字段 | 值 |
|------|-----|
| 日期 | 2026-03-28 02:40:14 |
| Prompt-ID | P20260328-020451 |

## 操作摘要

用户反馈应计收入数值扩大好多倍、优惠为 0、经营一览区域不变、环比不全。根因分析后修复 5 个问题：ODS 快照表 JOIN 行膨胀、优惠未分摊、Schema 缺环比字段、overview 无区域过滤、团购金额双口径规范沉淀。

## 变更文件清单

| 文件 | 变更类型 |
|------|----------|
| `apps/backend/app/services/fdw_queries.py` | 修改 |
| `apps/backend/app/schemas/xcx_board.py` | 修改 |
| `apps/backend/app/services/board_service.py` | 修改 |
| `.kiro/steering/frontend-backend-integration.md` | 修改 |
| `docs/guides/FRONTEND-BACKEND-INTEGRATION.md` | 修改 |

## 改动注解

### `apps/backend/app/services/fdw_queries.py`
- 变更类型：修改
- 原始原因：`get_finance_revenue()` 中 JOIN `ods.site_tables_master` 导致行膨胀（ODS 快照表同一 id 有 100+ 重复行），应计收入数值扩大数十倍；区域子行的 discount 硬编码为 0，导致优惠全部为 0
- 思路分析：
  1. **ODS 行膨胀修复**：将 `ods.site_tables_master` 替换为 `app.v_dim_table`（DWD 维度表，`scd2_is_current=1` 保证唯一），字段从 `areaname` 改为 `site_table_area_name`。收入结构改为从 `v_dwd_settlement_head` 按物理区域聚合，用 CASE WHEN 将 `site_table_area_name` 映射为 7 个标准区域标签
  2. **优惠分摊修复**：区域子行的 discount 从硬编码 0 改为按 `table_charge_money` 占比分摊 DWS `discount_total`（团购优惠 + 手动调整 + 赠送卡抵扣 + 抹零免单）
  3. **区域过滤**：新增 `_AREA_LABEL_MAP` 字典，area 参数非 "all" 时在 SQL WHERE 中追加 `area_label = ANY(%s)` 过滤
  4. **助教分析改回纯 DWS**：`get_finance_coach_analysis()` 三列（pay/share/hourly）全部从 `dws_assistant_salary_calc` 计算，禁止 DWD `ledger_amount` JOIN DWS 等级（同一助教同月可有多等级记录导致行膨胀）
  5. **返回 `discount_total` 字段**：供前端展示优惠总计和 overview 区域覆盖
- 修改结果：应计收入恢复正常数量级；优惠按区域占比正确分摊；区域筛选生效；助教分析无行膨胀

### `apps/backend/app/schemas/xcx_board.py`
- 变更类型：修改
- 原始原因：前端需要展示环比数据但 Schema 缺少对应字段，Pydantic 静默丢弃 service 层返回的环比字段
- 思路分析：RevenuePanel 添加 9 个环比字段（`total_occurrence_compare/down/flat`、`discount_total` + `compare/down/flat`、`confirmed_total_compare/down/flat`）；CashflowPanel 添加 3 个环比字段（`total_compare/down/flat`）；RevenueItem/ChannelItem/CashflowItem 添加可选 `desc` 字段；AreaFilterEnum 从 7 项重建为 9 项（新增 vip/snooker/ktv，移除 teamBuilding）
- 修改结果：环比数据正确透传到前端；区域枚举与后端映射表一致

### `apps/backend/app/services/board_service.py`
- 变更类型：修改
- 原始原因：area≠all 时经营一览（overview）的发生额/优惠/确认收入仍显示全店数据，未按区域过滤
- 思路分析：在 `get_finance_board()` 中，当 `area != "all"` 时，用 revenue 返回的 `total_occurrence`/`discount_total`/`confirmed_total` 覆盖 overview 对应字段，并重算 `discount_rate`。同时为 `_build_revenue()` 和 `_build_cashflow()` 增加环比计算逻辑（调用 `_attach_compare` 和 `calc_compare`）
- 修改结果：区域筛选时 overview 数据与收入结构一致；revenue 和 cashflow 面板支持环比展示

### `.kiro/steering/frontend-backend-integration.md`
- 变更类型：修改（已提交，diff 为空）
- 原始原因：团购金额双口径（DWS 交易金额 vs 估算回款）容易混淆，需沉淀为规范
- 思路分析：在"数据查询"段落新增"团购金额双口径"踩坑记录和"助教财务三列口径"规范
- 修改结果：后续开发者可直接查阅规范，避免重复踩坑

### `docs/guides/FRONTEND-BACKEND-INTEGRATION.md`
- 变更类型：修改（已提交，diff 为空）
- 原始原因：同上，完整文档同步更新
- 思路分析：与 steering 文件保持一致
- 修改结果：完整联调文档包含最新规范

## 风险评估

| 风险项 | 评估 |
|--------|------|
| 数据正确性 | ✅ ODS→DWD 维度表消除行膨胀，优惠按占比分摊符合业务逻辑 |
| 向后兼容 | ✅ 新增字段均有默认值，前端不读取不影响 |
| 性能 | ⚠️ `get_finance_revenue` 改为从 `v_dwd_settlement_head` 聚合，数据量大时需关注查询耗时 |
| 区域映射 | ⚠️ CASE WHEN 硬编码了区域名称映射，新增区域需同步更新 |

## 合规检查

- 迁移 SQL：无
- DDL 基线：不涉及
- OpenAPI spec：不涉及（接口签名未变，仅返回值字段增加）
- 文档同步：steering + 联调文档已更新