# 审计记录：board-finance-integration 阶段 2（后端 API 修复）

- 日期：2026-03-27
- Prompt：执行 board-finance-integration SPEC 阶段 2（T2.1–T2.4）
- 直接原因：财务看板 4 个数据层 bug 修复

## 改动方案

### T2.1 修复预收资产卡余额聚合
- 文件：`apps/backend/app/services/fdw_queries.py` → `get_finance_recharge()`
- 问题：卡余额（快照值）用 SUM 聚合，多天求和无意义
- 方案：拆为 3 个查询——流量值 SUM / 快照值取最后一天 / consumed 从 finance_daily_summary SUM(card_consume_total)

### T2.2 修复现金流入板块
- 文件：`apps/backend/app/services/fdw_queries.py` → `get_finance_cashflow()`
- 问题：consume_items 包含"储值卡消费"（非现金流入）
- 方案：移除储值卡消费，新增"纸币现金"(cash_paper_amount) 和"扫码收款"(scan_pay_amount)
- ⚠️ 依赖 T1.1 新增字段，视图更新前这两个字段返回 0

### T2.3 修复助教分析
- 文件：`apps/backend/app/services/fdw_queries.py` → `get_finance_coach_analysis()`
- 问题：(1) 小时均价用 effective_hours 作分母；(2) 缺少"客户支付"和"球房分成"
- 方案：SQL 新增 base_hours/bonus_hours 及加权计算；pay=对客收费(hours×course_price)，share=球房分成(hours×deduction)，hourly=对客单价

### T2.4 区域筛选枚举重建
- 文件：`apps/backend/app/schemas/xcx_board.py` → `AreaFilterEnum`
- 方案：从 7 项改为 9 项（新增 vip/snooker/ktv，移除 teamBuilding）

## 文件清单

| 文件 | 改动类型 |
|------|---------|
| `apps/backend/app/services/fdw_queries.py` | T2.1/T2.2/T2.3 逻辑修改 |
| `apps/backend/app/schemas/xcx_board.py` | T2.4 枚举重建 |

## 风险评估
- T2.2 依赖 T1.1（DWS 新增 cash_paper_amount/scan_pay_amount），视图未更新前返回 COALESCE 默认值 0
- T2.3 视图 v_dws_assistant_salary_calc 已确认暴露所有需要字段（base_hours/bonus_hours/base_course_price/bonus_course_price/base_deduction/bonus_deduction_ratio）
- T2.4 前端 areaOptions 需同步更新（阶段 3 T3.3）

## 回滚
- git revert 本次 commit 即可恢复原始逻辑

## 验证
```sql
-- T2.1: 确认快照值取最后一天而非 SUM
SELECT stat_date, cash_card_balance, total_card_balance
FROM app.v_dws_finance_recharge_summary
WHERE stat_date >= '2026-03-01' AND stat_date <= '2026-03-27'
ORDER BY stat_date DESC LIMIT 1;

-- T2.3: 确认视图字段可用
SELECT assistant_level_name, SUM(base_hours), SUM(bonus_hours),
       SUM(base_hours * base_course_price) AS base_customer_pay
FROM app.v_dws_assistant_salary_calc
WHERE salary_month >= '2026-03-01'
GROUP BY assistant_level_name;

-- T2.2: 确认新字段存在（T1.1 完成后）
SELECT column_name FROM information_schema.columns
WHERE table_schema = 'dws' AND table_name = 'dws_finance_daily_summary'
  AND column_name IN ('cash_paper_amount', 'scan_pay_amount');
```