Neo-ZQYY/docs/audit/changes/2026-03-27__board-finance-phase2-t1-t6.md

变更审计记录：财务看板 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	✅ 无需同步