root/Neo-ZQYY
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
b44096600dd6668738057b809f05e42f63f83513
Neo-ZQYY/docs/audit/changes/2026-03-28__board-finance-5fixes.md
Neo 14a12342b5 chore(audit): 补追 96 份未入仓审计孤本 — 覆盖 2026-02-26 ~ 2026-04-08 
这些审计记录原本堆积在 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>
2026-04-20 06:35:42 +08:00

4.9 KiB
Raw Blame History

变更审计记录：财务看板 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 + 联调文档已更新
Reference in New Issue View Git Blame Copy Permalink