# 变更审计记录：财务看板 Phase 2 对齐 Demo（T1-T6）

| 字段 | 值 |
|------|-----|
| 日期 | 2026-03-27 23:41:47 |
| Prompt-ID | P20260327-233226 |
| Session-ID | fd0c357e |
| Session 路径 | docs/audit/session_logs/2026-03/27/19_2ce2a118_230836 |

## 操作摘要
统筹完成 board-finance-phase2.md 中的 6 个任务（T1-T6），对齐 Demo 原型：收入结构按物理区域分类、优惠减扣 4 项重组、优惠总计行展示、现金流入/流出项名对齐、费用分组空值填充、助教分析从订单级实际金额计算。

## 涉及文件

| 文件 | 变更类型 | 关联任务 |
|------|----------|----------|
| `apps/backend/app/services/fdw_queries.py` | 修改 | T1/T2/T4/T5/T6 |
| `apps/miniprogram/miniprogram/pages/board-finance/board-finance.wxml` | 修改 | T3 |
| `apps/miniprogram/miniprogram/pages/board-finance/board-finance.ts` | 修改 | T3/T4 |
| `apps/miniprogram/miniprogram/utils/format.wxs` | 修改 | T3 |
| `apps/miniprogram/miniprogram/pages/board-finance/board-finance.wxss` | 修改 | T3 |
| `docs/guides/FRONTEND-BACKEND-INTEGRATION.md` | 修改 | T6 |
| `.kiro/steering/frontend-backend-integration.md` | 修改 | T6 |
| `docs/prd/specs/board-finance-phase2.md` | 修改 | 状态更新 |

## 本次对话文件变更

### 新增文件
- `docs/audit/prompt_logs/prompt_log_20260327_233226.md`
- `docs/audit/session_logs/2026-03/27/15_39869986_175210/main_01_ec3464b5.md`
- `docs/audit/session_logs/2026-03/27/19_2ce2a118_230836/main_01_fd0c357e.md`
- `docs/audit/session_logs/2026-03/27/19_2ce2a118_230836/sub_01_ec3464b5.md`

### 删除文件
- `docs/audit/session_logs/2026-03/27/15_39869986_175210/main_01_58aad65c.md`

## 改动注解

### `apps/backend/app/services/fdw_queries.py`
- 变更类型：修改
- 原始原因：财务看板 Phase 2 要求对齐 Demo 原型的数据结构和展示口径，涉及收入结构、优惠减扣、现金流、费用、助教分析 5 个查询函数的重写
- 思路分析：
  - T1+T2 `get_finance_revenue()`：收入结构改为从 `dwd_settlement_head` 按物理区域聚合（CASE WHEN 映射 7 个区域），优惠减扣改为从 `v_dws_finance_daily_summary` 的 `discount_*` 字段聚合为 Demo 的 4 项（会员折扣、优惠券、团购优惠、其他优惠），渠道分布 label 对齐 Demo，新增 `discount_total` 返回字段
  - T4 `get_finance_cashflow()`：label 改名（扫码收款→线上收款，团购平台回款→团购平台），所有项添加 `desc` 字段用于前端 tooltip
  - T5 `get_finance_expense()`：4 个分组为空时填充固定项名对齐 Demo，避免空数据时前端展示不一致
  - T6 `get_finance_coach_analysis()`：客户支付改为 DWD `ledger_amount`（实际结算金额），球房分成 = 客户支付 - 助教到手（DWS `base_income`/`bonus_income`），遵循助教财务三列口径规范
- 修改结果：5 个查询函数返回结构与 Demo 原型完全对齐，数据口径从估算改为实际结算金额

### `apps/miniprogram/miniprogram/pages/board-finance/board-finance.wxml`
- 变更类型：修改
- 原始原因：T3 要求在发生额行下方添加优惠总计行，展示红色负数金额
- 思路分析：在经营一览卡片的发生额/正价行下方新增优惠总计行，使用 `fmt.negativeMoney()` WXS 函数格式化为负数红色显示，右侧对齐。同时将所有金额字段从 TS 预格式化改为 WXS 实时格式化（`fmt.money()`/`fmt.safe()`），修复双重格式化 NaN 问题。移除旧的加载态 toast（改用其他方案），看板 tab 改为动态渲染
- 修改结果：优惠总计行正确展示，金额格式化统一由 WXS 处理，避免 TS 与 WXS 格式化互斥问题

### `apps/miniprogram/miniprogram/pages/board-finance/board-finance.ts`
- 变更类型：修改
- 原始原因：T3 需要映射后端新增的 `discountTotal` 字段，T4 需要映射 `desc` 字段
- 思路分析：在 `setData` 中新增 `discountTotal` 字段映射（`?? 0` 防空），现金流各项新增 `desc` 字段传递。金额字段传原始数字，格式化交给 WXS
- 修改结果：前端正确接收并展示后端新增字段

### `apps/miniprogram/miniprogram/utils/format.wxs`
- 变更类型：修改
- 原始原因：T3 优惠总计需要以负数红色格式展示
- 思路分析：新增 `negativeMoney` 函数，接收数值参数，先 `parseFloat` 转数字（防止字符串类型），输出带负号和千分位的金额字符串（如 `-¥1,234`）
- 修改结果：WXS 层新增负数金额格式化能力，供 WXML 直接调用

### `apps/miniprogram/miniprogram/pages/board-finance/board-finance.wxss`
- 变更类型：修改
- 原始原因：T3 优惠总计行需要红色样式
- 思路分析：添加优惠总计行的 CSS 类，红色字体，右侧对齐，与发生额行视觉层级区分
- 修改结果：优惠总计行样式与 Demo 原型一致

### `docs/guides/FRONTEND-BACKEND-INTEGRATION.md`
- 变更类型：修改
- 原始原因：T6 改变了助教财务三列口径，文档需同步
- 思路分析：更新助教财务三列口径说明：对客收费从 `hours × course_price` 改为 DWD `ledger_amount`（API 实际结算），明确 DWS `base_income`/`bonus_income` 是助教到手而非对客收费
- 修改结果：文档与代码口径一致，避免后续开发误用旧口径

### `.kiro/steering/frontend-backend-integration.md`
- 变更类型：修改
- 原始原因：steering 规则需与主文档同步
- 思路分析：同步更新助教口径速查条目
- 修改结果：AI steering 规则与实际口径一致

### `docs/prd/specs/board-finance-phase2.md`
- 变更类型：修改
- 原始原因：标记 SPEC 执行进度
- 思路分析：状态从"待执行"改为"执行中"
- 修改结果：SPEC 状态反映实际进度

## 合规检查

| 检查项 | 状态 |
|--------|------|
| 文档同步 | ✅ 无缺失（code_without_docs 为空） |
| 迁移 SQL | ✅ 无新增迁移 |
| DDL 基线 | ⚠️ has_ddl_baseline=false（无新迁移，不影响） |
| API 变更 | ✅ 无接口变更 |
| OpenAPI Spec | ✅ 无需同步 |