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>
74 lines
4.9 KiB
Markdown
74 lines
4.9 KiB
Markdown
# 变更审计记录：财务看板 5 项修复（ODS 行膨胀 / 优惠分摊 / 环比字段 / 区域过滤 / 规范沉淀）
|
||
|
||
| 字段 | 值 |
|
||
|------|-----|
|
||
| 日期 | 2026-03-28 02:40:14 |
|
||
| Prompt-ID | P20260328-020451 |
|
||
|
||
## 操作摘要
|
||
|
||
用户反馈应计收入数值扩大好多倍、优惠为 0、经营一览区域不变、环比不全。根因分析后修复 5 个问题：ODS 快照表 JOIN 行膨胀、优惠未分摊、Schema 缺环比字段、overview 无区域过滤、团购金额双口径规范沉淀。
|
||
|
||
## 变更文件清单
|
||
|
||
| 文件 | 变更类型 |
|
||
|------|----------|
|
||
| `apps/backend/app/services/fdw_queries.py` | 修改 |
|
||
| `apps/backend/app/schemas/xcx_board.py` | 修改 |
|
||
| `apps/backend/app/services/board_service.py` | 修改 |
|
||
| `.kiro/steering/frontend-backend-integration.md` | 修改 |
|
||
| `docs/guides/FRONTEND-BACKEND-INTEGRATION.md` | 修改 |
|
||
|
||
## 改动注解
|
||
|
||
### `apps/backend/app/services/fdw_queries.py`
|
||
- 变更类型：修改
|
||
- 原始原因：`get_finance_revenue()` 中 JOIN `ods.site_tables_master` 导致行膨胀（ODS 快照表同一 id 有 100+ 重复行），应计收入数值扩大数十倍；区域子行的 discount 硬编码为 0，导致优惠全部为 0
|
||
- 思路分析：
|
||
1. **ODS 行膨胀修复**：将 `ods.site_tables_master` 替换为 `app.v_dim_table`（DWD 维度表，`scd2_is_current=1` 保证唯一），字段从 `areaname` 改为 `site_table_area_name`。收入结构改为从 `v_dwd_settlement_head` 按物理区域聚合，用 CASE WHEN 将 `site_table_area_name` 映射为 7 个标准区域标签
|
||
2. **优惠分摊修复**：区域子行的 discount 从硬编码 0 改为按 `table_charge_money` 占比分摊 DWS `discount_total`（团购优惠 + 手动调整 + 赠送卡抵扣 + 抹零免单）
|
||
3. **区域过滤**：新增 `_AREA_LABEL_MAP` 字典，area 参数非 "all" 时在 SQL WHERE 中追加 `area_label = ANY(%s)` 过滤
|
||
4. **助教分析改回纯 DWS**：`get_finance_coach_analysis()` 三列（pay/share/hourly）全部从 `dws_assistant_salary_calc` 计算，禁止 DWD `ledger_amount` JOIN DWS 等级（同一助教同月可有多等级记录导致行膨胀）
|
||
5. **返回 `discount_total` 字段**：供前端展示优惠总计和 overview 区域覆盖
|
||
- 修改结果：应计收入恢复正常数量级；优惠按区域占比正确分摊；区域筛选生效；助教分析无行膨胀
|
||
|
||
### `apps/backend/app/schemas/xcx_board.py`
|
||
- 变更类型：修改
|
||
- 原始原因：前端需要展示环比数据但 Schema 缺少对应字段，Pydantic 静默丢弃 service 层返回的环比字段
|
||
- 思路分析：RevenuePanel 添加 9 个环比字段（`total_occurrence_compare/down/flat`、`discount_total` + `compare/down/flat`、`confirmed_total_compare/down/flat`）；CashflowPanel 添加 3 个环比字段（`total_compare/down/flat`）；RevenueItem/ChannelItem/CashflowItem 添加可选 `desc` 字段；AreaFilterEnum 从 7 项重建为 9 项（新增 vip/snooker/ktv，移除 teamBuilding）
|
||
- 修改结果：环比数据正确透传到前端；区域枚举与后端映射表一致
|
||
|
||
### `apps/backend/app/services/board_service.py`
|
||
- 变更类型：修改
|
||
- 原始原因：area≠all 时经营一览（overview）的发生额/优惠/确认收入仍显示全店数据，未按区域过滤
|
||
- 思路分析：在 `get_finance_board()` 中，当 `area != "all"` 时，用 revenue 返回的 `total_occurrence`/`discount_total`/`confirmed_total` 覆盖 overview 对应字段，并重算 `discount_rate`。同时为 `_build_revenue()` 和 `_build_cashflow()` 增加环比计算逻辑（调用 `_attach_compare` 和 `calc_compare`）
|
||
- 修改结果：区域筛选时 overview 数据与收入结构一致；revenue 和 cashflow 面板支持环比展示
|
||
|
||
### `.kiro/steering/frontend-backend-integration.md`
|
||
- 变更类型：修改（已提交，diff 为空）
|
||
- 原始原因：团购金额双口径（DWS 交易金额 vs 估算回款）容易混淆，需沉淀为规范
|
||
- 思路分析：在"数据查询"段落新增"团购金额双口径"踩坑记录和"助教财务三列口径"规范
|
||
- 修改结果：后续开发者可直接查阅规范，避免重复踩坑
|
||
|
||
### `docs/guides/FRONTEND-BACKEND-INTEGRATION.md`
|
||
- 变更类型：修改（已提交，diff 为空）
|
||
- 原始原因：同上，完整文档同步更新
|
||
- 思路分析：与 steering 文件保持一致
|
||
- 修改结果：完整联调文档包含最新规范
|
||
|
||
## 风险评估
|
||
|
||
| 风险项 | 评估 |
|
||
|--------|------|
|
||
| 数据正确性 | ✅ ODS→DWD 维度表消除行膨胀，优惠按占比分摊符合业务逻辑 |
|
||
| 向后兼容 | ✅ 新增字段均有默认值，前端不读取不影响 |
|
||
| 性能 | ⚠️ `get_finance_revenue` 改为从 `v_dwd_settlement_head` 聚合，数据量大时需关注查询耗时 |
|
||
| 区域映射 | ⚠️ CASE WHEN 硬编码了区域名称映射，新增区域需同步更新 |
|
||
|
||
## 合规检查
|
||
|
||
- 迁移 SQL：无
|
||
- DDL 基线：不涉及
|
||
- OpenAPI spec：不涉及（接口签名未变，仅返回值字段增加）
|
||
- 文档同步：steering + 联调文档已更新
|