feat(backend): F1-6 sprint2 #4 储值卡余额迁移 sandbox_replay (SCD2 时光机)

新建 sandbox_replay/balance_replay.py 模块,迁移 fdw_queries.get_member_balance,
fdw_queries 改 thin wrapper 保持 5 处现有调用(chat/coach/customer x2/task_manager)
透明兼容。

数据源 dim_member_card_account 是 SCD2 维度表(原生支持时光机),sandbox 改造
关键是替换 scd2_is_current=1 过滤为 scd2_start_time + scd2_end_time 时间过滤
(ref_date+1day 边界 = 当天结束时仍 active 的版本,timestamptz 比较稳定)。

双口径 UI 走查 PASS(member=2799207363643141 葛先生,SCD2 历史余额变化样本):
- 4a live(today=2026-05-05): 储值余额 ¥6,602
- 4b sandbox=2026-04-20: 储值余额 ¥18,080(差异 1.1w+,时光机效果显著)

unit test sprint1+sprint2 累计 24/24 PASS,无回归。

附带本次 sprint 2 触发的架构级登记:
- 新建 docs/_overview/architecture-evolution-backlog.md(DWD 孤立 + Core 中间件 +
  库重组,长远架构演进 backlog)
- F1-6-tasks.md 登记 #3 累计交易笔数推迟 Sprint 3(ETL 配合新增
  total_open_table_count,因现有 total_visit_count 实算 COUNT(settle_type IN (1,3))
  含商城订单,不符 Neo "开台次数"业务语义)
- sandbox-replay-engine-spec §5.5 thin wrapper 决策原则(已在 #2 commit)

详见 docs/audit/changes/2026-05-06__f1_6_sprint2_member_balance.md

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs/_overview/architecture-evolution-backlog.md

@@ -0,0 +1,49 @@
+# 架构演进 Backlog(长远)
+
+> 创建日期:2026-05-06
+> 状态:**backlog,等优先级排期**(不在当前 F1-6 范围)
+> 记录人:Neo + Claude(F1-6 Sprint 2 #3 调研触发)
+
+## 一、核心方向
+
+**DWD 层孤立 + Core 做连接器中间件,Core 之上的全部上游(DWS / 指数 / RLS 视图等)在所有连接器之间统一规范。**
+
+## 二、目标
+
+1. 后期可能接入多个连接器(与 `feiqiu` 平行的其他平台,不同字段/不同设计)
+2. **DWD 层归属于各连接器自身**(字段/口径可异),保留为各连接器原始数据落地层
+3. **Core 层作为中间件**:
+   - 下游对接各连接器的 DWD 层(吸收差异)
+   - 上游输出**统一规范**的字段/语义
+4. **Core 之上的所有层**(DWS、指数计算、RLS 视图、ETL 任务输出表等)结构、字段、设计、设置在所有连接器之间**完全一致**
+5. 后端 / 小程序 / admin-web / tenant-admin 仅依赖 Core 之上的统一层,不感知具体连接器
+
+## 三、牵连(待逐一决断)
+
+记录所有触发的牵连项,推进时逐一对齐:
+
+| # | 牵连项 | 说明 | 当前状态 |
+|---|------|------|---------|
+| 1 | 库结构重组(连接器粒度) | 当前每店铺一个 ETL 库(`etl_feiqiu` / `test_etl_feiqiu`),Neo 指示**至少每连接器一个库**,Core 后的全部上游应统一到一个共享库集中管理 | 待设计 |
+| 2 | DWS 字段名 vs 实算口径不一致 | F1-6 Sprint 2 #3 调研发现 `dws_member_consumption_summary.total_visit_count` 字段名"累计到店次数",实算是 `COUNT(settle_type IN (1,3))` 即结算单数(含商城订单);BD manual / dws_tasks.md 描述误导 | 待修订(随 #3 推到 Sprint 3) |
+| 3 | F1-6 #3 累计交易笔数 | 按 Neo 业务语义"开台次数"(不含 settle_type=3 商城订单),需 ETL 在 DWS 新增 `total_open_table_count = COUNT(settle_type=1)` 字段 | 推迟 Sprint 3(ETL 配合) |
+| 4 | DWD 不可被后端 / 应用层直读 | F1-6 Sprint 2 #3 调研发现 `app7_customer` AI prompt 当前直接读 `app.v_dwd_settlement_head` COUNT(*),违反"DWD 孤立"原则 | 待重构(随大架构演进) |
+| 5 | 后端 fdw_queries.py 中所有 `app.v_dwd_*` 直读点 | 需要梳理全部,逐一改走 Core / DWS 统一接口 | 待清单化 |
+| 6 | F1-7+ thin wrapper 收尾 sprint | F1-6 全部迁完后清理 fdw_queries 的 thin wrapper(详见 sandbox-replay-engine-spec.md §5.5) | 与本演进同步 |
+
+## 四、不属于本 backlog
+
+- **F1-6 沙箱时光机阶段 B**(Sprint 1-4)— 仍按现有 ETL 库结构推进,不等本演进。Sprint 推进过程中遇到本 backlog 第 2-5 项的具体问题,各自登记到对应 Sprint 任务清单。
+- **架构设计细节**(Core 层 schema 定义、库迁移策略、连接器适配 SDK 等)— 本文件仅做需求登记,详细设计待优先级到位时另起 spec。
+
+## 五、关联
+
+- F1-6 Sprint 3 任务清单:[`docs/_overview/wave1-findings/F1-6-tasks.md`](wave1-findings/F1-6-tasks.md) §4
+- 沙箱时光机模块 spec:[`docs/_overview/sandbox-replay-engine-spec.md`](sandbox-replay-engine-spec.md) §5.5(thin wrapper)+ §11(远期目标)
+- DWD 强制规则:[`apps/etl/connectors/feiqiu/CLAUDE.md`](../../apps/etl/connectors/feiqiu/CLAUDE.md) §DWD 强制规则(12 条)
+
+## 六、决策与变更记录
+
+| 日期 | 决策 / 变更 | 触发 |
+|------|------------|------|
+| 2026-05-06 | 创建本 backlog | F1-6 Sprint 2 #3 累计交易笔数调研发现 DWS 字段名与实算口径矛盾 + app7 直读 DWD 违规,Neo 决定将 DWD 孤立 + Core 中间件目标提上任务表 |

docs/_overview/wave1-findings/F1-6-tasks.md

@@ -14,7 +14,7 @@
 |--------|------|------|------|
 | **Sprint 1** | 框架(sandbox_replay 模块 + runtime_aware decorator) + 1 个试点指标(距上次到店天数迁移) | M ~ 4-5h | ✅ 完成(2026-05-05) |
 | **Sprint 2** | 5 个会员相关 P1 指标(60d 消费 / 累计消费总额 / 累计交易笔数 / 储值卡余额 / 累计 GMV) | M ~ 4h | 🔄 进行中(#1 60d 消费 ✅ 2026-05-06) |
-| Sprint 3 | 5 个助教/门店相关 P1 + **MP-2 完整**(daily salary 含 ETL 改造) | L ~ 8-10h | ⏳ 待启动 |
+| Sprint 3 | 5 个助教/门店 P1 + **MP-2 完整**(daily salary 含 ETL 改造)+ Sprint 2 推迟的 #3(ETL 新增 `total_open_table_count`)| L ~ 9-11h | ⏳ 待启动 |
 | Sprint 4 | 5 个 P2 指标(RS 重算 / 客户黏性 / 任务完成率 / Excel 修正 / 月度新增流失) | M-L ~ 6-8h | ⏳ 待启动 |
 
 ## 二、Sprint 1 收口(2026-05-05)
@@ -79,8 +79,8 @@
 |---|------|-------------|----------|------|------|
 | 1 | 60 天消费 | `fdw_queries.get_consumption_60d` | `sandbox_replay/consumption_replay.py`(扩展) | S | ✅ 2026-05-06(thin wrapper)|
 | 2 | 累计消费总额 | (无,新增) | `sandbox_replay/consumption_replay.py`(扩展) | S | ✅ 2026-05-06(无 wrapper,0 调用方)|
-| 3 | 累计交易笔数 | (字段未定,需 Neo 决断 dws_order_summary vs total_visit_count) | `sandbox_replay/consumption_replay.py`(扩展) | S | ⏸️ **暂停**(spec §4 字段未明确)|
-| 4 | 会员储值卡余额 | `fdw_queries.get_member_balance` | `sandbox_replay/balance_replay.py`(新建) | S | ⏳ 待启动 |
+| 3 | 累计交易笔数 | DWS 现有 `total_visit_count` 实算 `COUNT(settle_type IN (1,3))` 不符开台次数语义,需 ETL 新增 `total_open_table_count` | `sandbox_replay/consumption_replay.py`(扩展) | S | ⏸️ **推迟 Sprint 3**(ETL 配合,详见 [架构演进 backlog](../architecture-evolution-backlog.md))|
+| 4 | 会员储值卡余额 | `fdw_queries.get_member_balance` | `sandbox_replay/balance_replay.py`(新建) | S | ✅ 2026-05-06(thin wrapper,SCD2 时光机)|
 | 5 | 累计 GMV | `dws_finance_daily_summary.gross_amount`(门店级,与现有"区间 GMV"语义不同) | `sandbox_replay/finance_replay.py`(新建) | S | ⏳ 待启动 |
 
 ### Sprint 2 实施模式
@@ -92,8 +92,9 @@
 
 ### Sprint 2 commit
 - #1 60d 消费 — commit `d418621`(2026-05-06)
-- #2 累计消费总额 — `feat(backend): F1-6 sprint2 #2 累计消费总额加入 sandbox_replay`(待提交)
-- #3 累计交易笔数 — **暂停**(spec §4 字段未明确,需 Neo 决断 `dws_order_summary` vs `dws_member_consumption_summary.total_visit_count`)
+- #2 累计消费总额 — commit `32716bc`(2026-05-06)
+- #3 累计交易笔数 — **推迟 Sprint 3**(ETL 配合新增 `total_open_table_count`,详见 [架构演进 backlog](../architecture-evolution-backlog.md) 第 3 项)
+- #4 储值卡余额 — `feat(backend): F1-6 sprint2 #4 储值卡余额迁移 sandbox_replay (SCD2 时光机)`(待提交)
 
 ### 估算
 5 指标 × 30-50min = 3-4h(#1 实际 ~ 40min)