Neo
14a12342b5
这些审计记录原本堆积在 docs/audit/changes/changes/ 嵌套误产物目录下（由开发机迁移
79d3c2e 前后的不明批量操作产生）。由于同期 .gitignore 屏蔽了 docs/audit/ 全目录，
它们从未入过 git 任何分支 history。删除即永久丢失。
按 docs/specs/audit-gap-recovery/tasks.md 阶段 1 执行，将全部 96 份 D 类孤本
（主目录无同名、git history 亦无记录）复制到 docs/audit/changes/ 主目录入仓。
涵盖主题: P1-P18 全栈集成 / 多模块累积变更 / ETL bug 修复 / 业务日切 /
召回与任务引擎改造 / 租户管理与审批 / 董事会财务 / 客户与助教详情 /
DDL 基线合并 / Kiro 到 Claude Code 迁移
阶段 2（B 类内容漂移 1 份）和阶段 4（嵌套目录删除）独立推进。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2.9 KiB
2.9 KiB
审计记录：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 即可恢复原始逻辑
验证
-- 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');