# SPEC: 财务看板前后端联调（board-finance-integration）

> 创建日期：2026-03-27
> 状态：进行中
> 优先级：P0

## 背景

财务看板页面（`pages/board-finance/board-finance`）当前数据全为空——前端只绑定了赠送卡矩阵，其余 5 个板块的 API 返回数据未做 `setData`。同时走查发现多个数据层问题需要修复。

## 目标

1. 前端完整绑定 API 返回的 6 个板块数据
2. 筛选变更（时间/区域/环比）触发重新加载
3. 修复已确认的数据层问题
4. 优化加载效率

## 任务清单

### 阶段 1：DWS 层改造（ETL）

#### T1.1 DWS 财务日报新增支付方式拆分字段
- 目标表：`dws.dws_finance_daily_summary`
- 新增字段：`cash_paper_amount`（纸币现金）、`scan_pay_amount`（扫码收款）
- 数据来源：`dwd_payment` 表按 `payment_method` 拆分（2=现金，4=离线/扫码）
- 恒等式：`cash_paper_amount + scan_pay_amount = cash_pay_amount`
- 涉及文件：
  - `db/etl_feiqiu/migrations/2026-03-27__add_payment_split_to_finance_daily.sql`（DDL）
  - `apps/etl/connectors/feiqiu/tasks/dws/finance_base_task.py`（新增 extract 方法）
  - `apps/etl/connectors/feiqiu/tasks/dws/finance_daily_task.py`（transform 使用新字段）
  - `docs/database/ddl/etl_feiqiu__dws.sql`（DDL 基线更新）

#### T1.2 RLS 视图更新
- 更新 `app.v_dws_finance_daily_summary` 暴露新字段
- 涉及文件：`db/etl_feiqiu/migrations/2026-03-27__update_finance_daily_view.sql`

### 阶段 2：后端 API 修复

#### T2.1 修复预收资产卡余额聚合（快照值 SUM → 取最后一天）
- 文件：`apps/backend/app/services/fdw_queries.py` → `get_finance_recharge()`
- 改动：卡余额字段（cash_card_balance/gift_card_balance/total_card_balance 及 gift 细分）改为取时间范围内最后一天的值
- 同时填充 `consumed` 字段（从 `dws_finance_daily_summary.card_consume_total` SUM 聚合）

#### T2.2 修复现金流入板块
- 文件：`apps/backend/app/services/fdw_queries.py` → `get_finance_cashflow()`
- 改动：
  - 移除"储值卡消费"项
  - 新增"纸币现金"和"扫码收款"两项（从新字段读取）
  - 保留"团购平台回款"和"会员充值到账"

#### T2.3 修复助教分析小时均价 + 补充三列数据
- 文件：`apps/backend/app/services/fdw_queries.py` → `get_finance_coach_analysis()`
- 改动：
  - 基础课用 `base_hours`，激励课用 `bonus_hours`
  - 新增 `total_pay`（对客收费 = hours × course_price）
  - 新增 `total_share`（球房分成 = hours × deduction）
  - SQL 新增 `SUM(base_hours)`、`SUM(bonus_hours)`、`SUM(base_course_price)`、`SUM(bonus_course_price)`、`SUM(base_deduction)`、`SUM(bonus_deduction_ratio)` 的加权计算

#### T2.4 区域筛选枚举重建
- 文件：`apps/backend/app/schemas/xcx_board.py` → `AreaFilterEnum`
- 改动：从 7 项改为 9 项（all/hall/hallA/hallB/hallC/vip/snooker/mahjong/ktv）
- 后端 service 层传递 area 参数到 FDW 查询（本次不实现 SQL 过滤，仅传参预留）

#### T2.5 Pydantic Schema 同步
- 文件：`apps/backend/app/schemas/xcx_board.py`
- 确保 FinanceBoardResponse 及子 Panel 的字段与 service 返回一致

### 阶段 3：前端联调

#### T3.1 重写数据加载函数
- 文件：`apps/miniprogram/miniprogram/pages/board-finance/board-finance.ts`
- 改动：
  - `_loadGiftRows()` → `_loadData()`，绑定全部 6 个板块
  - 金额用 `formatMoney()`，百分比用 `toFixed(1) + '%'`
  - 后端返回原始数字，前端按位置格式化

#### T3.2 筛选联动
- `onTimeChange`/`onAreaChange`/`toggleCompare` 变更后调用 `_loadData()`
- 添加 loading 态管理

#### T3.3 区域筛选选项更新
- 前端 `areaOptions` 从 7 项改为 9 项
- 非"全部"时隐藏：预收资产、现金流出、助教分析

#### T3.4 微信开发者工具验证
- 截图对比各板块数据
- 验证筛选切换、环比开关

## 区域筛选对照表

| code | 前端显示 | 包含的物理区域 |
|------|---------|-------------|
| all | 全部区域 | 所有 |
| hall | 大厅 | A区+B区+C区+TV台+美洲豹赛台 |
| hallA | A区 | A区 |
| hallB | B区 | B区 |
| hallC | C区 | C区+TV台+美洲豹赛台 |
| vip | 台球包厢 | VIP包厢 |
| snooker | 斯诺克 | 斯诺克区 |
| mahjong | 麻将房 | 麻将房+M7+M8+666+发财 |
| ktv | 团建房 | K包+k包活动区+幸会158 |

## 区域筛选影响板块

| 板块 | 非"全部"时 |
|------|-----------|
| 经营一览 | 按区域过滤 |
| 预收资产 | 隐藏 |
| 应计收入确认 | 按区域过滤 |
| 现金流入 | 按区域过滤 |
| 现金流出 | 隐藏 |
| 助教分析 | 隐藏 |

## 不做

- 区域级 SQL 过滤（DWS 视图改造，后续迭代）
- 助教分析按区域统计（已记入 BACKLOG）
- 各区域各收费项目对比（已记入 BACKLOG）
- 支出数据 Excel 导入功能