feat(backend): F1-6 sprint1 sandbox_replay 模块脚手架 + get_last_visit_days 迁移试点 (W1)

F1-5b 完成后启动 F1-6 沙箱时光机阶段 B,Sprint 1 范围: 1. 建立 sandbox_replay 模块脚手架 2. 实现 @runtime_aware decorator(自动注入 RuntimeContext) 3. 试点迁移 1 个指标:get_last_visit_days(P1-4 距上次到店天数) 4. MCP 端到端 4a/4b 双口径走查新增文件: - apps/backend/app/services/sandbox_replay/__init__.py(模块入口 + re-export) - apps/backend/app/services/sandbox_replay/_decorator.py(@runtime_aware 实现) - apps/backend/app/services/sandbox_replay/consumption_replay.py(get_last_visit_days 试点) - docs/_overview/wave1-findings/F1-6-tasks.md(F1-6 任务清单 4 个 sprint) - docs/audit/changes/2026-05-05__f1_6_sprint1_sandbox_replay_kickoff.md(Sprint 1 审计) 修改: - apps/backend/app/services/fdw_queries.py:218-238 get_last_visit_days 改 thin wrapper,委托 sandbox_replay.consumption_replay 保持 75+ 现有调用点无感兼容关键 bug 修复:@trace_service + @runtime_aware 嵌套 sig.bind 失败 - 现象:仅 FastAPI 请求 + 有活跃 TraceContext 时复现 (直接 Python 脚本 get_current_trace 返回 None,跳过 _build_params_dict) - 根因:functools.wraps 设置 __wrapped__ 让 inspect.signature 追溯原函数 → bind 时缺 keyword-only 必传 ctx → TypeError - 修复:_decorator.py 不用 functools.wraps,手动复制元信息但不设 __wrapped__,inspect.signature 看到 wrapper 自身 (*args, **kwargs) 测试: - unit test 10/10 PASS(本地 .gitignore:71 不入仓) - 直接 customer_service.get_customer_detail PASS(独立诊断脚本) - etl_conn 复用模式 PASS MCP 双口径(member=2799207087163141 黄先生): - 4a live (today=2026-05-05): daysSinceVisit=32(05-05 - 04-03) - 4b sandbox=2026-04-20: daysSinceVisit=31(04-20 - 03-20) 通过插 walkthrough 测试快照 stat_date=2026-04-15 演示 (测试库 dws_member_consumption_summary 仅 stat_date=2026-05-01 一行, sandbox=4-20 时被视图层 stat_date <= business_date_now() 过滤) - 测试快照已清理,sandbox 已切回 live Sprint 2-4 待启动(见 F1-6-tasks.md): - Sprint 2:5 个会员 P1 指标(余额/60d 消费/累计交易/GMV/累计服务客户数) - Sprint 3:5 个助教/门店 P1 + MP-2 完整(含 ETL 改造) - Sprint 4:5 个 P2 算法重算指标 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-05 23:53:19 +08:00
parent 5d4da0ae8c
commit 9f1e35d71a
6 changed files with 522 additions and 51 deletions
--- a/docs/_overview/wave1-findings/F1-6-tasks.md
+++ b/docs/_overview/wave1-findings/F1-6-tasks.md
@@ -0,0 +1,146 @@
+# F1-6 沙箱时光机阶段 B 任务清单
+
+> 创建日期:2026-05-05 (F1-5b 收尾后启动)
+> 完整模块 spec:[`docs/_overview/sandbox-replay-engine-spec.md`](../sandbox-replay-engine-spec.md)
+> 上游:F1-5b 全部完成(commit `5d4da0a`)
+>
+> **状态**:Sprint 1 已启动并完成,Sprint 2-4 待启动
+
+## 一、阶段 B 总览
+
+按 sandbox-replay-engine-spec 阶段 B 拆 4 个 sprint:
+
+| Sprint | 范围 | 工作量 | 状态 |
+|--------|------|------|------|
+| **Sprint 1** | 框架(sandbox_replay 模块 + runtime_aware decorator) + 1 个试点指标(距上次到店天数迁移) | M ~ 4-5h | ✅ 完成(2026-05-05) |
+| Sprint 2 | 5 个会员相关 P1 指标(余额 / 60d 消费 / 累计交易 / GMV / 累计服务客户数) | M ~ 4h | ⏳ 待启动 |
+| Sprint 3 | 5 个助教/门店相关 P1 + **MP-2 完整**(daily salary 含 ETL 改造) | L ~ 8-10h | ⏳ 待启动 |
+| Sprint 4 | 5 个 P2 指标(RS 重算 / 客户黏性 / 任务完成率 / Excel 修正 / 月度新增流失) | M-L ~ 6-8h | ⏳ 待启动 |
+
+## 二、Sprint 1 收口(2026-05-05)
+
+### 范围
+1. ✅ 建立 `apps/backend/app/services/sandbox_replay/` 模块脚手架
+2. ✅ 实现 `@runtime_aware(metric=...)` decorator(自动注入 RuntimeContext)
+3. ✅ 试点迁移:`get_last_visit_days`(距上次到店天数,P1-4)
+   - `consumption_replay.py` 新实现
+   - `fdw_queries.get_last_visit_days` 改 thin wrapper(兼容 75+ 现有调用)
+4. ✅ Unit test 10/10 PASS
+5. ✅ MCP 端到端 4a/4b 双口径 PASS
+
+### 关键 bug 发现 + 修复
+
+**bug**:`@trace_service` + `@runtime_aware` 嵌套时,trace_service 的 `_build_params_dict` 用 `inspect.signature(func).bind(*args, **kwargs)` 做参数 redact。`functools.wraps` 默认设置 `__wrapped__` 让 `inspect.signature` 追溯到原函数(含 keyword-only 必传 ctx 参数),导致 sig.bind 抛 `TypeError: missing a required argument: 'ctx'`。
+
+只在 FastAPI 请求 + 有活跃 TraceContext 时触发(直接 Python 调用 get_current_trace 返回 None,跳过 _build_params_dict,不复现)。
+
+**修复**:`runtime_aware` 的 wrapper 不用 `functools.wraps`,改用手动复制 `__name__/__qualname__/__module__/__doc__`,**不设 `__wrapped__`**,让 `inspect.signature` 看到 wrapper 自身 `(*args, **kwargs)` 签名,sig.bind 永远成功。
+
+### 双口径验证证据(关键样本)
+
+**目标 member**: 2799207087163141(黄先生)
+
+| 维度 | 4a live (today=2026-05-05) | 4b sandbox=2026-04-20 |
+|------|---------------------------|----------------------|
+| stat_date 数据 | 2026-05-01 | 2026-04-15(walkthrough 测试快照) |
+| last_consume_date | 2026-04-03 | 2026-03-20 |
+| daysSinceVisit 计算 | 32 = 05-05 - 04-03 | **31 = 04-20 - 03-20** |
+| API 返回 | 32 ✓ | 31 ✓ |
+
+测试快照已清理,sandbox 已切回 live。
+
+### 走查脚本
+
+`_DEL/walkthrough_f1_6/`:
+- `step_sprint1_probe_member.py` — 找有 last_consume 的会员
+- `step_sprint1_check_view.py` — 视图层 RLS 行为
+- `step_sprint1_direct_call.py` — 直接调 sandbox_replay 函数
+- `step_sprint1_repro_etl_conn.py` — etl_conn 复用模式
+- `step_sprint1_call_service.py` — 直接调 customer_service.get_customer_detail
+- `step_sprint1_4b_probe.py` — sandbox=4-20 视图行为
+- `step_sprint1_4b_find_member.py` — 找 sandbox 下有数据的 member
+- `step_sprint1_4b_stat_dist.py` — stat_date 分布
+- `step_sprint1_4b_seed_data.py` — 插测试快照
+- `step_sprint1_cleanup.py` — 清理 + 切回 live
+
+### Sprint 1 commit
+
+`feat(backend): F1-6 sprint1 sandbox_replay 模块脚手架 + get_last_visit_days 迁移试点`
+
+---
+
+## 三、Sprint 2 范围(待启动)
+
+### 5 个会员相关 P1 指标
+
+| # | 指标 | 当前实现位置 | 目标迁移到 | 复杂度 |
+|---|------|-------------|----------|------|
+| 1 | 会员储值卡余额 | `fdw_queries.get_member_balance` | `sandbox_replay/balance_replay.py` | S |
+| 2 | 60 天消费 | `fdw_queries.get_consumption_60d` | `sandbox_replay/consumption_replay.py`(扩展) | S |
+| 3 | 累计消费总额 | (待补,目前无独立查询) | `sandbox_replay/consumption_replay.py` | S |
+| 4 | 累计交易笔数 | (待补,后端无实现) | `sandbox_replay/consumption_replay.py` | S |
+| 5 | 累计 GMV | `board_service` 财务总额 | `sandbox_replay/finance_replay.py`(新建) | S |
+
+### Sprint 2 实施模式
+所有指标走 `@runtime_aware` decorator + `app.v_dws_*` 视图查询。每个指标:
+- 1 个新函数 to sandbox_replay/
+- 1 个 thin wrapper in fdw_queries.py(兼容)
+- 单元测试 + MCP 走查
+- 审计 + 单独 commit
+
+### 估算
+5 指标 × 30-50min = 3-4h
+
+---
+
+## 四、Sprint 3 范围(待启动)
+
+### 5 个助教/门店相关 P1 + MP-2 完整
+
+| # | 指标 | 备注 |
+|---|------|------|
+| 6 | 累计服务客户数(助教) | dws_assistant_customer_stats daily |
+| 7 | 助教等级 | dws_assistant_daily_detail.assistant_level_code |
+| 8 | 月度课时(助教) | dws_assistant_daily_detail.base_hours 聚合 |
+| 9 | 月度计费金额(助教) | dws_assistant_daily_detail.total_ledger_amount 聚合 |
+| 10 | 月度新增/流失会员 | dws_member_*_summary daily |
+| **MP-2 完整 daily salary** | board-coach 月度面板 | **需 ETL 团队配合**:新建 dws_assistant_daily_salary 表 + ETL Excel 上传 UI 改造 |
+
+### Sprint 3 估算
+5 指标 ~ 3-4h + MP-2 完整 5-6h(含 ETL 改造) = **L ~ 8-10h**
+
+---
+
+## 五、Sprint 4 范围(待启动)
+
+### 5 个 P2 算法重算指标
+
+| # | 指标 | 难点 |
+|---|------|------|
+| 11 | RS 关系指数 | 算法窗口期 + 衰减函数,daily 重算需重做累计 |
+| 12 | 客户黏性指数 | 类似 RS,有时间衰减 |
+| 13 | 任务完成率(coach_tasks) | 需补 dws daily 聚合视图 |
+| 14 | Excel 修正(扣款/奖励/支出/收入) | 依赖 effective_date(F1-5b prep 已就位),后端 SQL 加截断 |
+| 15 | 月度新增/流失会员(算法版) | dws_member_lifecycle 重算 |
+
+### Sprint 4 估算
+M-L ~ 6-8h
+
+---
+
+## 六、阶段 C(F1-7+ 远期)
+
+详见 sandbox-replay-engine-spec.md §11.5:
+- 3 个 P3 指标(门店等级 / 助教星级 / 累计 KPI)
+- `biz.sandbox_audit_log` 用户行为审计表
+- AI app8_consolidate prompt audit
+
+---
+
+## 七、关联
+
+- 完整模块 spec:`docs/_overview/sandbox-replay-engine-spec.md`
+- F1-5b 任务清单:`docs/_overview/wave1-findings/F1-5b-tasks.md`
+- F1-5b MP-2 prep 审计:`docs/audit/changes/2026-05-05__wave1_f1_5b_mp2_prep.md`
+- P20 SPEC §11.4 + §11.5(F1-6 待办登记):`docs/prd/specs/P20-runtime-context-sandbox.md`
+- Sprint 1 审计:`docs/audit/changes/2026-05-05__f1_6_sprint1_sandbox_replay_kickoff.md`
--- a/docs/audit/changes/2026-05-05__f1_6_sprint1_sandbox_replay_kickoff.md
+++ b/docs/audit/changes/2026-05-05__f1_6_sprint1_sandbox_replay_kickoff.md
@@ -0,0 +1,119 @@
+# 2026-05-05 · F1-6 Sprint 1 沙箱时光机引擎启动 + get_last_visit_days 试点迁移
+
+> F1-6 沙箱时光机阶段 B Sprint 1(详见 `docs/_overview/wave1-findings/F1-6-tasks.md`)
+>
+> 工作量评估 M / 4-5h(实际 ~ 5h,含 trace_service + runtime_aware 嵌套 bug 排查 1.5h)
+>
+> 完整模块 spec:`docs/_overview/sandbox-replay-engine-spec.md`
+
+## 背景
+
+F1-5b 收尾后启动 F1-6 沙箱时光机阶段 B,Sprint 1 范围:
+1. 建立 `sandbox_replay/` 模块脚手架
+2. 实现 `@runtime_aware` decorator(自动注入 RuntimeContext)
+3. 试点迁移 1 个指标:`get_last_visit_days`(距上次到店天数,P1-4)
+4. MCP 端到端走查 4a/4b 双口径
+
+## 改动清单
+
+### Step 3 实施
+
+**新增文件**(3 个):
+- [apps/backend/app/services/sandbox_replay/__init__.py](apps/backend/app/services/sandbox_replay/__init__.py) — 模块入口 + re-export
+- [apps/backend/app/services/sandbox_replay/_decorator.py](apps/backend/app/services/sandbox_replay/_decorator.py) — `runtime_aware` decorator 实现
+- [apps/backend/app/services/sandbox_replay/consumption_replay.py](apps/backend/app/services/sandbox_replay/consumption_replay.py) — 消费/到店相关 sandbox 重算实现(`get_last_visit_days` 试点)
+
+**修改文件**:
+- [apps/backend/app/services/fdw_queries.py](apps/backend/app/services/fdw_queries.py)(L218-238)`get_last_visit_days` 改为 thin wrapper,委托给 sandbox_replay 实现,保持 75+ 现有调用兼容
+
+**测试文件**(本地不入仓):
+- [apps/backend/tests/test_sandbox_replay_sprint1.py](apps/backend/tests/test_sandbox_replay_sprint1.py)
+- 10 case 全 PASS:decorator 契约 5 case + consumption_replay 行为 3 case + thin wrapper 链路 1 case + (含 1 个 negative case)
+
+### Step 4 双口径验证 — 关键 bug 发现 + 修复
+
+**首次走查发现** API `daysSinceVisit` 返回 null,但直接 Python 调用返回正确值 32 → 后端 reload 看似生效但 sandbox_replay 链路未被触发。
+
+经多轮诊断:
+1. 排除 reload 卡死(后端 /health 200,Neo 完整重启)
+2. 排除 junction 穿透(本机无 D 盘)
+3. 排除 schema/字段映射(CamelModel 输出正确)
+4. 在 customer_service.py:138 加临时 diag 写文件,捕获异常:
+
+```
+[before] cust=2799207087163141 site=2790685415443269 etl_conn_type=connection
+[exception] TypeError: missing a required argument: 'ctx'
+```
+
+**根因**:`@trace_service` + `@runtime_aware` 嵌套时:
+- `runtime_aware` wrapper 用 `functools.wraps(func)` 复制元数据 → 设置 `__wrapped__` 属性
+- 外层 `trace_service` 在有活跃 TraceContext 时调 `_build_params_dict(func, args, kwargs)`,内部用 `inspect.signature(func).bind(*args, **kwargs)` 做参数 redact
+- `inspect.signature` 默认追溯 `__wrapped__` 链,看到原函数签名(含 keyword-only 必传 `ctx` 参数)
+- 调用时 args/kwargs 不含 ctx(因为 wrapper 应该自动注入)→ sig.bind 抛 TypeError
+- trace_service 让该 TypeError 冒泡 → customer_service except 捕获 → days_since_visit=None
+
+**关键诊断点**:仅在 FastAPI 请求 + 有活跃 trace 时复现(直接 Python 脚本 get_current_trace 返回 None,跳过 _build_params_dict)。
+
+**修复**:`runtime_aware` wrapper 不用 `functools.wraps`,改手动复制 `__name__/__qualname__/__module__/__doc__`,**不设 `__wrapped__`**,让 `inspect.signature` 看到 wrapper 自身 `(*args, **kwargs)` 签名,sig.bind 永远成功。
+
+修复后 unit test 10/10 仍 PASS(decorator 契约不变)。
+
+### Step 4 双口径走查证据(关键样本)
+
+**目标 member**: 2799207087163141(黄先生)
+
+| 维度 | 4a live (today=2026-05-05) | 4b sandbox=2026-04-20 |
+|------|---------------------------|----------------------|
+| stat_date 数据 | 2026-05-01(真实) | 2026-04-15(walkthrough 测试快照) |
+| last_consume_date | 2026-04-03 | 2026-03-20 |
+| daysSinceVisit 计算 | **32** = 05-05 - 04-03 | **31** = 04-20 - 03-20 |
+| API `/api/xcx/customers/2799207087163141` 返回 | 32 ✓ | 31 ✓ |
+
+**关键证据**:sandbox 切换时,sandbox_replay 框架按 `RuntimeContext.business_date` 实时计算,完全符合"沙箱时光机"语义。
+
+测试快照已清理:`DELETE FROM dws.dws_member_consumption_summary WHERE member_id=2799207087163141 AND stat_date='2026-04-15'`(1 行)。
+sandbox 已切回 live。
+
+### Step 5 审计
+
+本文件 + F1-6-tasks.md 任务清单。
+
+## 影响范围
+
+| 端 | 影响 | 验证 |
+|----|------|------|
+| 后端 sandbox_replay 模块 | **新增** 3 个文件 | unit test 10/10 PASS |
+| 后端 fdw_queries.get_last_visit_days | 改 thin wrapper(行为完全一致) | MCP 4a/4b 双口径 PASS |
+| 75+ 现有 fdw_queries.get_last_visit_days 调用点 | **无感**(thin wrapper 透明委托) | customer-detail.daysSinceVisit live=32 / sandbox=31 |
+| 其他 backend service | 无影响 | — |
+| admin-web / 小程序 / ETL | 无影响 | — |
+
+## 测试
+
+- 后端 unit test 10/10 PASS(本地 `apps/backend/tests/test_sandbox_replay_sprint1.py`,因 .gitignore:71 不入仓)
+- MCP 端到端 4a/4b 双口径 PASS
+- 直接 Python 调用 customer_service.get_customer_detail PASS
+- 直接 sandbox_replay.consumption_replay.get_last_visit_days PASS
+- etl_conn 复用模式 PASS
+
+## 风险与未覆盖
+
+- **本 sprint 仅迁移 1 个指标**:试点验证框架可用,Sprint 2-4 批量迁移其他 18 个指标
+- **decorator 元信息不完整**:不用 functools.wraps 后,`inspect.signature(wrapper)` 看到 (*args, **kwargs),无法看到原函数参数。如果未来其他 decorator 也依赖原函数签名(如 OpenAPI 生成),可能需要更复杂方案。当前 trace_service 是唯一已知会用 inspect.signature 的外层装饰器
+- **测试库 dws_member_consumption_summary 数据局限**:仅 stat_date=2026-05-01 一个快照(205 行),sandbox=4-20 时所有快照都被视图层过滤。本次 4b 走查通过插测试快照(stat_date=2026-04-15)演示框架行为,实际生产数据应有连续 daily 快照不会有此问题
+
+## 回滚策略
+
+```bash
+git revert <commit_hash>
+```
+
+回滚后:
+- 删除 sandbox_replay/ 目录
+- fdw_queries.get_last_visit_days 恢复原直接 SQL 实现
+- 75+ 调用点无影响(thin wrapper 透明)
+- 测试文件本地保留(.gitignore 范围内)
+
+## Co-Authored-By
+
+Claude Opus 4.7 (1M context) <noreply@anthropic.com>