# SPEC: 财务看板第二阶段 — Demo 对齐与数据修正（board-finance-phase2）

> 创建日期：2026-03-27
> 前置 SPEC：`board-finance-integration`（已完成，实现了基础数据绑定和筛选联动）
> 状态：执行中
> 优先级：P0

---

## 一、背景与前提

### 1.1 已完成的工作（Phase 1）

Phase 1（`board-finance-integration` SPEC）已完成：
- 前端 `_loadData()` 绑定全部 6 个板块数据
- 筛选联动（时间/区域/环比切换触发重新加载）
- 区域筛选枚举重建（9 项）
- DWS 新增 `cash_paper_amount`/`scan_pay_amount` 字段（支付方式拆分）
- 预收资产卡余额从 SUM 改为取最后一天快照
- consumed 字段从硬编码 0 改为从 `card_consume_total` 取值
- 助教排序改为初→中→高→星
- 百分比字段 ×100 修复

### 1.2 当前状态

- 后端 API 200 正常返回，6 个板块有数据
- DWS 已重跑（含 `DWS_SALARY_ALLOW_OUT_OF_CYCLE=true`），激励课有数据
- 前端数据绑定正常，WXS 格式化正常
- 微信开发者工具 Power 已连接（`ws://127.0.0.1:9420`）

### 1.3 遗留问题清单（本 SPEC 要解决的）

| # | 问题 | 板块 | 严重程度 |
|---|------|------|---------|
| P1 | 收入结构分类不对，需按区域筛选体系分类 | 应计收入确认 | 高 |
| P2 | 优惠减扣分项名称/结构与 Demo 不一致 | 应计收入确认 | 高 |
| P3 | 优惠减扣总计未在发生额右侧齐平展示 | 应计收入确认 | 中 |
| P4 | 现金流入各项名称/描述与 Demo 不一致 | 现金流入 | 中 |
| P5 | 现金流出各项名称为空（需固定项名对齐 Demo） | 现金流出 | 中 |
| P6 | 助教分析数据不准，需从订单级绩效方案重算 | 助教分析 | 高 |

---

## 二、开发环境

### 2.1 技术栈
- 后端：Python 3.10+ / FastAPI / psycopg2（原生 SQL）
- 前端：微信小程序 TypeScript / WXML / WXSS / WXS
- 数据库：PostgreSQL（ETL 测试库 `test_etl_feiqiu`、业务测试库 `test_zqyy_app`）
- ETL：uv workspace，`apps/etl/connectors/feiqiu/`

### 2.2 可用工具
- **微信开发者工具 Power**：`ws://127.0.0.1:9420`，支持页面导航、截图、JS 执行、元素快照、网络监控
- **PostgreSQL Power**：`pg-etl-test`（ETL 库）和 `pg-app-test`（业务库），支持 SQL 执行、表结构查看
- **OpenAPI Power**：后端 API 测试

### 2.3 关键文件路径

| 文件 | 说明 |
|------|------|
| `apps/backend/app/services/fdw_queries.py` | FDW 查询层（6 个财务看板查询函数） |
| `apps/backend/app/services/board_service.py` | Service 编排层（6 个 _build_* 函数 + 环比计算） |
| `apps/backend/app/schemas/xcx_board.py` | Pydantic Schema（FinanceBoardResponse） |
| `apps/miniprogram/miniprogram/pages/board-finance/board-finance.ts` | 前端页面逻辑 |
| `apps/miniprogram/miniprogram/pages/board-finance/board-finance.wxml` | 前端模板 |
| `apps/miniprogram/miniprogram/pages/board-finance/board-finance.wxss` | 前端样式 |
| `apps/miniprogram/miniprogram/utils/format.wxs` | WXS 格式化函数 |
| `apps/demo-miniprogram/miniprogram/pages/board-finance/` | Demo 原型（对齐目标） |

### 2.4 数据库关键表/视图

| 表/视图 | 说明 |
|--------|------|
| `app.v_dws_finance_daily_summary` | 财务日报（RLS 视图） |
| `app.v_dws_finance_income_structure` | 收入结构（RLS 视图） |
| `app.v_dws_finance_discount_detail` | 优惠明细（RLS 视图） |
| `app.v_dws_finance_expense_summary` | 支出汇总（RLS 视图，Excel 导入） |
| `app.v_dws_platform_settlement` | 平台结算（RLS 视图，Excel 导入） |
| `app.v_dws_assistant_salary_calc` | 助教工资计算（RLS 视图） |
| `dwd.dwd_settlement_head` / `_ex` | 结算单头表/扩展表 |
| `dwd.dwd_assistant_service_log` / `_ex` | 助教服务流水 |
| `dwd.dwd_payment` | 支付流水（payment_method: 2=现金, 4=扫码） |
| `dwd.dwd_groupbuy_redemption` | 团购核销 |
| `ods.site_tables_master` | 桌台主数据（areaname 字段） |

---

## 三、Demo 原型数据结构（对齐目标）

### 3.1 应计收入确认

**收入结构表（structureRows）**：
```
开台与包厢    ¥358,600  -¥45,200  ¥313,400
  A区         ¥118,200  -¥11,600  ¥106,600  (isSub)
  B区          ¥95,800  -¥11,200   ¥84,600  (isSub)
  C区          ¥72,600  -¥11,100   ¥61,500  (isSub)
  团建区       ¥48,200   -¥6,800   ¥41,400  (isSub)
  麻将区       ¥23,800   -¥4,500   ¥19,300  (isSub)
助教 基础课   ¥232,500      -     ¥232,500
助教 激励课   ¥112,800      -     ¥112,800
食品酒水      ¥119,556  -¥68,136   ¥51,420
```

**发生额构成（priceItems）**：
```
开台消费  ¥358,600
酒水商品  ¥186,420
包厢费用  ¥165,636
助教服务  ¥112,800
```

**优惠减扣（discountItems）**：
```
团购优惠                    -¥56,200
手动调整 + 大客户优惠        -¥34,800
赠送卡抵扣 (台桌卡+酒水卡+抵用券) -¥22,336
其他优惠 (免单+抹零)         -¥0
```

**收款渠道（channelItems）**：
```
储值卡结算冲销    ¥238,200
现金/线上支付     ¥345,800
团购核销确认收入 (团购成交价) ¥126,120
```

### 3.2 现金流入

```
纸币现金 (柜台现金收款)                    ¥85,600
线上收款 (微信/支付宝/刷卡 已扣除平台服务费) ¥260,200
团购平台 (美团/抖音回款 已扣除平台服务费)    ¥126,120
会员充值到账 (首充/续费实收)               ¥352,800
合计                                      ¥824,720
```

### 3.3 现金流出

```
进货与运营：食品饮料 ¥108,200 / 耗材 ¥21,850 / 报销 ¥10,920
固定支出：房租 ¥125,000 / 水电 ¥24,200 / 物业 ¥11,500 / 人员工资 ¥112,000
助教薪资：基础课分成 ¥116,250 / 激励课分成 ¥23,840 / 充值提成 ¥12,640 / 额外奖金 ¥11,500
平台服务费：汇来米 ¥10,680 / 美团 ¥11,240 / 抖音 ¥10,580
合计 ¥600,400
```

### 3.4 助教分析

```
基础课：
  totalPay(客户支付) / totalShare(球房抽成) / avgHourly(小时平均)
  初级: pay ¥68,600 / share ¥34,300 / hourly ¥20/h
  中级: pay ¥82,400 / share ¥41,200 / hourly ¥25/h
  高级: pay ¥57,800 / share ¥28,900 / hourly ¥30/h
  星级: pay ¥23,700 / share ¥11,850 / hourly ¥35/h

激励课：同结构
```

---

## 四、任务清单

### T1：应计收入确认 — 收入结构按区域分类

**问题**：当前 `get_finance_revenue()` 从 `v_dws_finance_income_structure` 读取，按 INCOME_TYPE/AREA 分类。需要改为按物理区域分类。

**方案**：不依赖 `dws_finance_income_structure`，直接从 `dwd_settlement_head` + 桌台维度表聚合。

**数据来源**：
- `dwd_settlement_head.table_id` → `ods.site_tables_master.areaname` 获取物理区域
- 按区域聚合 `table_charge_money`（台费）为"开台与包厢"主行
- 按区域拆分子行（A区/B区/C区/团建区/麻将区等）
- 助教行：`assistant_pd_money`（基础课）+ `assistant_cx_money`（激励课）
- 食品酒水行：`goods_money`

**区域映射**（与财务看板区域筛选对照表一致）：
```
A区 → A区
B区 → B区
C区 + TV台 + 美洲豹赛台 → C区
VIP包厢 → 台球包厢
斯诺克区 → 斯诺克
麻将房 + M7 + M8 + 666 + 发财 → 麻将区
K包 + k包活动区 + 幸会158 → 团建区
虚拟台 + 补时长 → 排除
```

**涉及文件**：
- `apps/backend/app/services/fdw_queries.py` → `get_finance_revenue()` 重写
- 可能需要在 ETL 库中创建区域映射视图或在后端 SQL 中内联 CASE WHEN

**注意**：
- 营业日转换：使用 `biz_date_sql_expr` 或后端等效逻辑
- `settle_type IN (1, 3)` 过滤
- 优惠按区域拆分可能不可行（优惠是订单级的，不是区域级的），需确认

### T2：应计收入确认 — 优惠减扣对齐 Demo

**问题**：当前 discountItems 从 `v_dws_finance_discount_detail` 读取，分项名称与 Demo 不一致。

**Demo 目标 4 项**：
1. 团购优惠 → `discount_groupbuy`
2. 手动调整 + 大客户优惠 → `discount_manual + discount_other`（adjust_amount 的两个子集）
3. 赠送卡抵扣（台桌卡+酒水卡+抵用券）→ `discount_gift_card`
4. 其他优惠（免单+抹零）→ `discount_rounding`

**方案**：不从 `v_dws_finance_discount_detail` 读取，直接从 `v_dws_finance_daily_summary` 的 6 个 discount_* 字段聚合，按 Demo 的 4 项重新组合。

**涉及文件**：
- `apps/backend/app/services/fdw_queries.py` → `get_finance_revenue()` 中 discount 部分重写

### T3：应计收入确认 — 优惠总计展示位置

**问题**：优惠减扣总计需在发生额右侧齐平展示。

**方案**：WXML 布局调整，在 `totalOccurrence` 行下方添加优惠总计行，右侧对齐。

**涉及文件**：
- `apps/miniprogram/miniprogram/pages/board-finance/board-finance.wxml`
- 可能需要 WXSS 调整

### T4：现金流入对齐 Demo

**问题**：当前项名和描述与 Demo 不一致。

**Demo 目标**：
1. 纸币现金（desc: 柜台现金收款）→ `cash_paper_amount`
2. 线上收款（desc: 微信/支付宝/刷卡 已扣除平台服务费）→ `scan_pay_amount`
3. 团购平台（desc: 美团/抖音回款 已扣除平台服务费）→ `groupbuy_pay_amount`
4. 会员充值到账（desc: 首充/续费实收）→ `recharge_cash_inflow`

**方案**：修改 `get_finance_cashflow()` 返回的 label 和 desc 字段。

**注意**：
- "线上收款"的 desc 说"已扣除平台服务费"，但当前 `scan_pay_amount` 是扫码支付原始金额，未扣除平台服务费。需确认是否需要扣除 `platform_fee_amount`
- "团购平台"同理，`groupbuy_pay_amount` 是团购实付金额，是否已扣除平台服务费取决于 `platform_settlement_amount` 是否有值

**涉及文件**：
- `apps/backend/app/services/fdw_queries.py` → `get_finance_cashflow()`
- `apps/miniprogram/miniprogram/pages/board-finance/board-finance.ts` → `_loadData()` 中 cashflow 映射

### T5：现金流出对齐 Demo

**问题**：当前支出数据来自 Excel 导入（`dws_finance_expense_summary` + `dws_platform_settlement`），数据全为 0。但项名和分组结构需要与 Demo 对齐。

**Demo 目标 4 组**：
1. 进货与运营：食品饮料 / 耗材 / 报销
2. 固定支出：房租 / 水电 / 物业 / 人员工资
3. 助教薪资：基础课分成 / 激励课分成 / 充值提成 / 额外奖金
4. 平台服务费：按平台名分项（汇来米 / 美团 / 抖音）

**方案**：
- 进货运营 + 固定支出：来自 `dws_finance_expense_summary`（Excel 导入），按 `expense_category` 分组
- 助教薪资：可从 `dws_assistant_salary_calc` 聚合（基础课分成 = SUM(base_income 对应的球房抽成)，激励课分成 = SUM(bonus 对应的球房抽成)，充值提成 = SUM(recharge_commission)，额外奖金 = SUM(sprint_bonus + top_rank_bonus + other_bonus)）
- 平台服务费：来自 `dws_platform_settlement`（Excel 导入），按 `platform_name` 分组

**涉及文件**：
- `apps/backend/app/services/fdw_queries.py` → `get_finance_expense()` 重写
- 前端 `_loadData()` 中 expense 映射

### T6：助教分析 — 从订单级绩效方案重算

**问题**：当前从 `dws_assistant_salary_calc` 聚合，该表是月度粒度的工资计算结果，使用的是配置表中的标准费率。用户要求从每笔订单的实际绩效方案计算。

**用户要求**：
- 客户支付：每笔订单中客户实际支付的助教费用
- 球房抽成：每笔订单中球房实际抽取的金额
- 助教到手 = 客户支付 - 球房抽成
- 小时平均 = 球房抽成 / 总小时数

**数据来源**：
- `dwd_assistant_service_log`：每笔助教服务记录（assistant_id, skill_id, 时长）
- `dwd_settlement_head`：每笔结算单（assistant_pd_money=基础课客户支付, assistant_cx_money=激励课客户支付）
- 球房抽成需要从配置表（`cfg_assistant_level_price` + `cfg_performance_tier`）按每笔订单的助教等级和档位计算

**方案选择**：
- 方案 A：直接从 `dwd_assistant_service_log` + `dwd_settlement_head` 关联计算（绕过 DWS）
- 方案 B：继续用 `dws_assistant_salary_calc`，但验证其数据与订单级计算一致

**建议**：先用方案 B 验证数据一致性。如果一致，保持现有逻辑；如果不一致，再改为方案 A。

**验证方法**：
- 从 `dwd_settlement_head` 聚合 `SUM(assistant_pd_money)` 和 `SUM(assistant_cx_money)`
- 与 `dws_assistant_salary_calc` 的 `SUM(base_hours * base_course_price)` 和 `SUM(bonus_hours * bonus_course_price)` 对比
- 如果一致，说明 DWS 数据可靠

**涉及文件**：
- `apps/backend/app/services/fdw_queries.py` → `get_finance_coach_analysis()`
- 可能需要新增 FDW 查询函数

**参考文件**：
- `tmp/助理教练流水_朗朗桌球_20260301_20260327.xlsx`（飞球系统导出的助教流水，用于交叉验证）

---

## 五、依赖关系

```
T1（收入结构按区域）→ 独立，可先做
T2（优惠减扣对齐）→ 独立，可先做
T3（优惠总计展示）→ 依赖 T2 完成
T4（现金流入对齐）→ 独立，可先做
T5（现金流出对齐）→ 独立，可先做
T6（助教分析重算）→ 独立，可先做
```

建议执行顺序：T6 → T1 → T2 → T3 → T4 → T5（先解决数据准确性，再对齐展示）

---

## 六、权威文档引用

| 文档 | 路径 | 用途 |
|------|------|------|
| DWD-DOC 权威规则 | `.kiro/steering/dwd-doc-authority.md` | consume_money 禁用、支付恒等式、会员字段断档等 |
| DWS 权威规范 | `.kiro/steering/dws-doc-authority.md` | 幂等策略、课程定价、绩效档位等 |
| 前后端联调规范 | `docs/guides/FRONTEND-BACKEND-INTEGRATION.md` | 数据契约、WXS 格式化、快照值 vs 流量值等 |
| 财务看板 Phase 1 SPEC | `docs/prd/specs/board-finance-integration.md` | 已完成的工作和区域对照表 |
| Demo 原型 | `apps/demo-miniprogram/miniprogram/pages/board-finance/` | 对齐目标 |
| 支付方式 BD 手册 | `apps/etl/connectors/feiqiu/docs/database/DWD/main/BD_manual_dwd_payment.md` | payment_method 枚举 |

---

## 七、DWD-DOC 强制规则速查

1. `consume_money` 禁止直接用于计算 → 用 `items_sum` 拆分字段
2. 助教费用必须拆分：`assistant_pd_money`（陪打/基础课）+ `assistant_cx_money`（超休/激励课）
3. 支付恒等式：`balance_amount = recharge_card_amount + gift_card_amount`
4. `settle_type IN (1, 3)` 过滤正向交易
5. 支付方式拆分从 `dwd_payment`（payment_method: 2=现金, 4=扫码），不从 `settlement_head_ex`
6. 快照值（卡余额）禁止 SUM，取最后一天
7. TS 层传原始数字，WXS 负责格式化（禁止双重格式化）

---

## 八、区域筛选对照表

| code | 前端显示 | 包含的物理区域（areaname） |
|------|---------|--------------------------|
| 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 |

排除：虚拟台、补时长

---

## 九、区域筛选影响板块

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

---

## 十、验证方法

每个任务完成后：
1. 用 PostgreSQL Power 直接查询 DWS/DWD 数据验证计算正确性
2. 用微信开发者工具 Power 的 `evaluate_script` 检查前端 `setData` 后的值
3. 用 `get_page_snapshot` 检查 DOM 渲染结果
4. 用 `screenshot` 截图对比 Demo 原型

---

## 十一、收尾

- 所有改动添加 CHANGE 注释（日期 + Prompt + 直接原因）
- 更新 `docs/prd/specs/board-finance-integration.md` 的状态
- 如涉及 DDL 变更，同步更新 `docs/database/ddl/` 基线和 BD 手册
- 如涉及新的踩坑模式，沉淀到 `.kiro/steering/` 和 `docs/guides/FRONTEND-BACKEND-INTEGRATION.md`