Neo-ZQYY/docs/audit/changes/2026-05-06__f1_6_sprint2_member_balance.md

2026-05-06 · F1-6 Sprint 2 #4 — 储值卡余额迁移到 sandbox_replay(SCD2 时光机)

F1-6 沙箱时光机阶段 B Sprint 2 #4(详见 docs/_overview/wave1-findings/F1-6-tasks.md §3)

工作量评估 S / 30-50min(实际 ~ 40min)

Sprint 2 进度:#1 ✅ → #2 ✅ → #3 推迟 Sprint 3 → #4 储值卡余额 ☚ → #5 累计 GMV

完整模块 spec:docs/_overview/sandbox-replay-engine-spec.md §5.5(thin wrapper 决策)

背景

#4 储值卡余额是 Sprint 2 第 4 个迁移指标。与 #1 #2 不同,数据源是 SCD2 维度表 dim_member_card_account,非 daily 累计快照表。SCD2 维度表原生支持时光机回溯,sandbox 改造关键在替换 scd2_is_current=1 过滤为 scd2_start_time + scd2_end_time 时间过滤。

改动清单

Step 3 实施

新增文件(1 个):

• apps/backend/app/services/sandbox_replay/balance_replay.py — 新建模块,实现 get_member_balance 函数

修改文件(2 个):

• apps/backend/app/services/sandbox_replay/init.py — re-export get_member_balance_replay
• apps/backend/app/services/fdw_queries.pyget_member_balance(行 ~185)改 thin wrapper,委托给 sandbox_replay 实现,保持 5 处现有调用兼容

测试文件(本地不入仓 .gitignore:71):

• apps/backend/tests/test_sandbox_replay_sprint2.py — 累计 14 case(本指标 5 case)

测试覆盖:

• 空 member_ids 返回空 dict
• 正常返回 {member_id: Decimal} 映射
• sandbox 模式 SQL 用 SCD2 时光机过滤(scd2_start_time + scd2_end_time),不再含 scd2_is_current,SUM(balance) 多卡聚合保留
• SUM(balance) 为 NULL 时返回 Decimal('0')(沿用原行为)
• thin wrapper 委托链路验证

合并 sprint 1 + sprint 2 #1/#2/#4 测试套件:24/24 PASS,无回归。

SCD2 时光机 SQL 关键差异

-- 原 fdw_queries(live only):
WHERE tenant_member_id = ANY(%s)
  AND scd2_is_current = 1
GROUP BY tenant_member_id

-- 新 sandbox_replay(时光机):
WHERE tenant_member_id = ANY(%s)
  AND scd2_start_time <  (%s::date + INTERVAL '1 day')
  AND (scd2_end_time IS NULL
       OR scd2_end_time >= (%s::date + INTERVAL '1 day'))
GROUP BY tenant_member_id

ref_date = ctx.business_date,ref_date+1day 边界 = ref_date 当天结束时仍 active 的版本。 live 模式 ref_date=today,效果等同 scd2_is_current=1(实测验证)。

Step 4 双口径 UI 走查证据

目标 member: 2799207363643141(葛先生,138****8071)

⚠️ 切换 member 原因:黄先生(2799207087163141)在测试库 SCD2 历史中 dim_member_card_account 自 2026-04-06 起无变更,sandbox=2026-04-20 与 live 都返回 ¥547.29(无差异),不能演示时光机效果。葛先生在 04-20 与 05-05 之间有大额余额变化,差异 1.1w+,演示效果最显著。

双截图对照:

卡条位置	4a live (today=2026-05-05)	4b sandbox=2026-04-20
#1 储值余额 ☚	¥6,602	¥18,080
#2 60天消费	¥73,614	--(测试库 dws 无 stat_date<=04-20 数据)
#3 理想间隔	1天	1天
#4 距今到店	11天	--(同上 dws 数据局限)

走查截图(双口径 #1 格 sandbox 时光机数值变化清晰可见):

• _DEL/walkthrough_f1_6/sprint2_4a_live_balance.png — 顶部 stat 卡条 ¥6,602 / ¥73,614 / 1天 / 11天
• _DEL/walkthrough_f1_6/sprint2_4b_sandbox_balance.png — 顶部 stat 卡条 ¥18,080 / -- / 1天 / --

关键证据:同一会员葛先生,SCD2 维度表里 2026-04-20 时余额 ¥18,079.55,2026-05-05(live)余额 ¥6,602.07,sandbox 切换准确还原历史余额。差异 1.1w+,SCD2 时光机过滤生效铁证。

Step 5 审计

本文件 + F1-6-tasks.md Sprint 2 进度推进 + audit dashboard 刷新。

影响范围

端	影响	验证
后端 sandbox_replay.balance_replay	新增 模块 + get_member_balance 函数	unit test 5/5 + 累计 24/24 PASS
后端 fdw_queries.get_member_balance	改 thin wrapper(行为完全一致)	UI 4a/4b 双口径 PASS
后端 5 处调用方(chat / coach / customer ×2 / task_manager)	无感(thin wrapper 透明委托,签名不变)	4a=¥6,602 / 4b=¥18,080
小程序 customer-detail	无感(API 字段名不变)	UI 双截图实地确认
admin-web / 租户后台 / ETL	无影响	—

测试

• 后端 unit test 24/24 PASS(本地 apps/backend/tests/test_sandbox_replay_sprint{1,2}.py,因 .gitignore:71 不入仓)
• MCP 端到端 4a/4b 双口径 PASS(含 navigate_to + snapshot + screenshot 完整 UI 验证)
• 直接 SQL 实测 SCD2 时光机过滤行为验证
• 时区敏感性验证(Asia/Shanghai 一致 + PG date+1d vs timestamptz 比较语义稳定)

风险与未覆盖

• 现有口径未拆分储值卡 vs 赠送卡:get_member_balance 直接 SUM 全部 balance,本 sprint 保持口径不变。如未来需展示"储值卡余额"+"赠送卡余额"分项(参考 dws_finance_recharge_summary.cash_card_balance / gift_card_balance 字段),登记到架构演进 backlog
• scd2_end_time 当前 ETL 默认值是 '9999-12-31' 而非 NULL:SQL 用 IS NULL OR >= ref_date+1 兼容两种约定,防御未来 ETL 改动
• 测试库 SCD2 历史数据局限:并非所有会员都有 sandbox 期内的余额变化历史,需选择有差异的样本验证(本次选葛先生)
• 多连接器架构演进:本 SCD2 时光机查询直接读 dwd 维度表(通过 app.v_dim_member_card_account 视图),长远应通过 Core 层统一接口(详见 架构演进 backlog 第 4 项)

回滚策略

git revert <commit_hash>

回滚后:

• 删除 sandbox_replay/balance_replay.py 新建文件
• sandbox_replay/__init__.py 移除 re-export
• fdw_queries.get_member_balance 恢复原 scd2_is_current=1 实现
• 5 处调用点无影响(thin wrapper 透明)
• 测试文件本地保留(.gitignore 范围内)

Co-Authored-By

Claude Opus 4.7 (1M context) noreply@anthropic.com