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>
64 lines
2.9 KiB
Markdown
64 lines
2.9 KiB
Markdown
# 审计记录：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');
|
||
```
|