Neo-ZQYY/docs/database/changes/2026-05-02__sandbox_no_future_data_plan.md

沙箱「不看未来」完整修复清单

日期：2026-05-02 关联：changes/2026-05-01__runtime_context_sandbox.md 关联代码：

• 后端：apps/backend/app/services/runtime_context.py、fdw_queries.py、board_service.py、task_*.py、recall_detector.py、chat_service.py、coach_service.py、customer_service.py、performance_service.py、ai/data_fetchers/*、ai/prompts/*
• 数据库：db/etl_feiqiu/schemas/app.sql（DWS/DWD/DIM RLS 视图）
• 小程序：apps/miniprogram/miniprogram/pages/performance*、task-list、board-finance 等 风险等级：高（核心业务读取层广泛假设「真实今天」） 状态：方案待用户确认；实施前不动业务代码

---

一、问题陈述

R1 RuntimeContext 业务日期沙箱 的初版只解决了 写入隔离：sandbox 行带 runtime_mode='sandbox' + sandbox_instance_id='sbx_*'，与 live 数据共存但不污染。

但读取层仍大量使用 真实系统时间，导致 sandbox 模式下：

• get_finance_board 区间按 business_date 算（OK），但 prompts 内部的辅助 ETL 查询用 _calc_date_range(time) 漏传 ref_date，退回 date.today()，会拉「真实今天」的数据。
• AI data_fetchers（member_data / assistant_data / page_context）SQL 写死 CURRENT_DATE - INTERVAL '60 days' 等。
• App3-7 prompt current_time 字段是 datetime.now()，与沙箱业务时钟不一致。
• fdw_queries.py 大量 CURRENT_DATE 与 ORDER BY stat_date DESC LIMIT N，无业务日上界。
• 小程序 performance / performance-records 用本地 Date 推算 year/month 直接传给后端，绕过 RuntimeContext。

后果：sandbox 演示「以 2026-03-15 视角重放」时，看板/任务/AI 输出实际混合了截至真实今天的最新数据，纯净度被破坏。

---

二、修复策略（A + B + C 三层）

A 层：文档与 UI 警告（最轻，先上）

不改业务代码，只让用户清楚当前沙箱边界。

文件	改动
apps/admin-web/src/pages/RuntimeContext.tsx	Alert 中追加「当前沙箱可能仍读取部分真实近期数据」的警告，并提示完整修复进度
docs/database/BD_Manual_runtime_context_sandbox.md	新增「读取层局限与逐步修复路线」章节
docs/database/changes/2026-05-02__sandbox_no_future_data_plan.md	本文件，作为修复路线图

B 层：后端 + 小程序代码层修复（核心）

按调用链分两组：

B1 · 后端服务层时间锚替换 + SQL 上界

把 date.today() / datetime.now() / CURRENT_DATE / NOW() 在「业务窗口」语义里换成 as_runtime_today_param / as_runtime_now_param / task_runtime_filter 或参数化业务日；查询 DWS/DWD/FDW 时补 stat_date <= business_date / pay_time <= business_now 等上界。

调度元数据、审计、token TTL、写库 updated_at = NOW() 这类非业务窗口保持原状。

文件	行号	现状	改法
apps/backend/app/services/board_service.py	37	today = ref_date or date.today()	调用方必须传 ref_date=runtime_ctx.business_date（如 prompts 漏传需补）
同上	500	SQL 写死 create_time >= CURRENT_DATE - INTERVAL '60 days'	改 create_time BETWEEN %s AND %s，参数为 business_date - 60d 与 business_now
apps/backend/app/services/task_generator.py	231/845/884	datetime.now(timezone.utc)	业务窗口处改 as_runtime_now_param(site_id)；run_started_at（运行记录）保留真实时间
同上	873	直连 dwd.dim_assistant（非 RLS 视图）	切换 app.v_dim_assistant 或加 sandbox 上界
apps/backend/app/services/task_expiry.py	63	注释 expires_at < NOW()；实际已用 as_runtime_now_param	仅更新注释，无代码改动
apps/backend/app/services/task_manager.py	680-682	datetime.now(timezone.utc).year/month 用作工资月	改 as_runtime_today_param(site_id).year/month
同上	819-820	datetime.now() 计算年月	同上
同上	1199-1202	today = date.today(); cutoff_60d = today - 60d	today = as_runtime_today_param(site_id)
apps/backend/app/services/coach_service.py	150/716	datetime.date.today()	as_runtime_today_param
同上	198-207/744-756	biz.coach_tasks 查询无 task_runtime_filter	套 task_runtime_filter(site_id)
同上	550-566	_build_task_groups 未带 site_id	补 site_id 过滤 + runtime filter
apps/backend/app/services/customer_service.py	516	CURRENT_DATE - INTERVAL '60 days'	参数化为 business_date - 60d
apps/backend/app/services/performance_service.py	508-518 / 532-534	_calc_date_range ref 来自 next_month_start，未对齐沙箱	参数链路改为 business_date 推导
apps/backend/app/services/chat_service.py	195	NOW() - 3 days 限制对话上下文	改 business_now - 3 days
同上	692/709	CURRENT_DATE - 30 days	改 business_date - 30 days
同上	602	写消息 NOW()	写消息保留真实时间（持久化时钟应跟真实）
apps/backend/app/services/fdw_queries.py	196-200 / 489 / 567-568 / 650-651 / 688-689 / 924 / 1012-1016 / 等	大量 CURRENT_DATE 与 ORDER BY stat_date DESC LIMIT 无上界	函数签名增加 business_date / business_now 参数；SQL 加 stat_date <= %s / create_time <= %s
apps/backend/app/services/ai/admin_service.py	86-87 / 137 / 304-305 / 546-551	AI 调用统计窗口 CURRENT_DATE	super-admin 后台是否也按门店沙箱口径——需产品确认。默认建议保留真实时间
apps/backend/app/services/recall_detector.py	157-164 / 174-195	app.v_dws_* 查询无 stat_date 上界	加 stat_date <= business_date
apps/backend/app/services/scheduler.py / trigger_scheduler.py	—	调度元数据（任务下次运行时间）	不动：调度本身按真实时钟工作
apps/backend/app/routers/xcx_auth.py	~334-348	_dt.now().year/month 给 get_salary_calc	as_runtime_today_param(user.site_id).year/month
apps/backend/app/routers/admin_runtime_context.py	111	sandbox_date > date.today() 校验	保留：sandbox_date 的「未来」语义就是相对真实日历

AI prompts / data_fetchers：

文件	行号	改法
apps/backend/app/ai/prompts/app2_finance_prompt.py	817-818 / 841-846	调 _calc_date_range(time, ref_date=runtime_ctx.business_date)
apps/backend/app/ai/prompts/app2a_finance_area_prompt.py	466-468	同上
apps/backend/app/ai/prompts/app3_clue_prompt.py	65-66	current_time = as_runtime_now_param(site_id)
apps/backend/app/ai/prompts/app4_analysis_prompt.py	82-83	同上
apps/backend/app/ai/prompts/app5_tactics_prompt.py	82-83	同上
apps/backend/app/ai/prompts/app6_note_prompt.py	79-80	同上
apps/backend/app/ai/prompts/app7_customer_prompt.py	79-80	同上
apps/backend/app/ai/dispatcher.py	259/330	去重键的 date.today() 改为 as_runtime_today_param(site_id)，确保沙箱 vs live 去重不互相污染
apps/backend/app/ai/data_fetchers/member_data.py	166/211/280/326/377-378	CURRENT_DATE → 参数；date.today() → business_date；ORDER BY ... DESC LIMIT N 加上界
apps/backend/app/ai/data_fetchers/assistant_data.py	92/105-106/212-213	同上
apps/backend/app/ai/data_fetchers/page_context.py	140/154/218/243/364/413/415-416/465/467-468/518-519/602-603	同上；ORDER BY DESC LIMIT N 全部加 <= business_now / business_date 上界
apps/backend/app/ai/cache_service.py	83/279	expires_at > now() 与 TTL → 保留真实时钟（缓存 TTL 是真实时间维度）
apps/backend/app/ai/run_log_service.py	115/143/165/195-196/211-212	run log finished_at 真实时钟；窗口聚合按真实时钟（运维口径）

B2 · 小程序绕过点修复

让小程序停止用本地 Date 算 year/month 直接传给后端；改为后端从 RuntimeContext 决定。

文件	行号	改法
apps/miniprogram/miniprogram/pages/performance/performance.ts	121-127 / 133-135	不再传 year/month，调用 fetchPerformanceOverview() 让后端按 business_date 决定；或先 fetchRuntimeContext() 拿业务年月
apps/miniprogram/miniprogram/pages/performance-records/performance-records.ts	62-63 / 87-91 / 143-147 / 258-262	初始化用后端 business_date.year/month；canGoNext 上界改用 business_date
apps/miniprogram/miniprogram/pages/task-list/task-list.ts	389-411	isCurrentMonth 通过后端返回字段或 runtimeContext.business_date 计算
apps/miniprogram/miniprogram/pages/board-finance/board-finance.ts	17	isCurrentMonthFilter 同上
apps/miniprogram/miniprogram/services/api.ts	(新增)	fetchRuntimeContext() 包装 /api/config/runtime-context，返回 { business_date, business_now, is_sandbox }；缓存到全局 store
utils/time.ts	全文	不改：相对时间/IM 时间/截止日全是显示文案，按真实本地时间合理
chat.ts 367/407、customer-detail.ts 216-219 等乐观 UI 时间戳	—	不改：仅 UI 兜底，最终以后端时间为准

B 层后端公共改造点

为减少散点改动，建议在 apps/backend/app/services/runtime_context.py 加两个工具：

def runtime_window_upper_bound(site_id, conn=None) -> tuple[date, datetime]:
    """返回 (business_date, business_now) 用作 SQL 上界。"""

def runtime_year_month(site_id, conn=None) -> tuple[int, int]:
    """返回沙箱业务年月，用于绩效报表。"""

fdw_queries.py 函数签名增加可选 business_date、business_now 参数；调用方按需传入。

C 层：ETL RLS 视图业务日上界（最彻底）

利用现有 app.current_site_id 模式，引入 app.current_business_date 会话变量，在 app.v_* 视图层加上界。后端 _fdw_context 增加 SET LOCAL app.current_business_date = %s，sandbox 模式下传 business_date，live 模式下不设置或设置 9999-12-31。

C 方案 SQL 模式

-- 时间事实表（含 stat_date / pay_time / create_time）
CREATE OR REPLACE VIEW app.v_dws_finance_daily_summary AS
SELECT ...
FROM dws.dws_finance_daily_summary
WHERE site_id = current_setting('app.current_site_id')::bigint
  AND stat_date <= COALESCE(
        NULLIF(current_setting('app.current_business_date', true), '')::date,
        '9999-12-31'::date
      );

-- 维度表（含 scd2_effective_from）
CREATE OR REPLACE VIEW app.v_dim_member AS
SELECT ...
FROM dwd.dim_member
WHERE register_site_id = current_setting('app.current_site_id')::bigint
  AND COALESCE(scd2_effective_from, '0001-01-01'::date) <= COALESCE(
        NULLIF(current_setting('app.current_business_date', true), '')::date,
        '9999-12-31'::date
      );

current_setting('app.current_business_date', true) 第二个参数 true 表示「未设置时返回空字符串而非报错」，配合 NULLIF + COALESCE 实现：

• live 模式下 app.current_business_date 未设置 → 上界为 9999-12-31 → 等同无限制
• sandbox 模式下后端 SET LOCAL app.current_business_date = '2026-03-15' → 视图自动截断

C 方案涉及范围

db/etl_feiqiu/schemas/app.sql 共 49 个 RLS 视图：

类型	视图模式	上界字段
维度表 SCD2	v_dim_*（10 个）	scd2_effective_from 或 created_at
DWD 事实表	v_dwd_*（6 个）	create_time 或 pay_time
DWS 日粒度	v_dws_*_daily*（约 10 个）	stat_date
DWS 月粒度	v_dws_*_monthly*（约 5 个）	stat_month
DWS 索引/聚合	v_dws_*_index 等	stat_date
配置表	v_cfg_*	一般取「最新有效」，沙箱可保留真实最新（配置不该回放）

需要按视图逐个判断时间上界字段。建议分批：

1. C-1：财务相关 v_dws_finance_*（5 视图）。
2. C-2：助教/任务相关 v_dws_assistant_*、v_dws_member_assistant_*（约 12 视图）。
3. C-3：DWD 事实表 v_dwd_*（6 视图）。
4. C-4：维度表 SCD2 v_dim_*（10 视图，需配合 SCD2 字段）。
5. C-5：配置表 v_cfg_*（一般保留真实最新，但确认是否需要按 effective_to）。

每批按 RLS 双 schema 规则同时改 dws.v_* 和 app.v_*。

C 方案后端改造

# apps/backend/app/database.py 或 fdw_queries.py 内
def get_etl_readonly_connection(site_id, business_date=None):
    conn = ...
    with conn.cursor() as cur:
        cur.execute("SET default_transaction_read_only = on")
        cur.execute("SET LOCAL app.current_site_id = %s", (str(site_id),))
        if business_date is not None:
            cur.execute("SET LOCAL app.current_business_date = %s", (str(business_date),))
    ...

_fdw_context 同样改造：默认从 get_runtime_context(site_id) 取 business_date，sandbox 模式自动 SET。

---

三、推荐实施顺序

步骤	工作量	价值	依赖
A1 admin-web Alert 警告升级	0.5h	立即让用户知道当前局限	无
A2 BD_Manual + 本修复路线图	0.5h	后续工作可见	无
B1-后端 prompts ref_date 漏传补齐	1h	立即修复 App2/App2a 漏洞	无
B1-后端 runtime helpers + service 层关键路径	4h	修 task/board/coach/customer/performance 主链路	无
B1-后端 fdw_queries 上界改造	6h	收口最大公约数	上一步
B1-后端 AI data_fetchers + prompts current_time	3h	AI 链路对齐沙箱	无
B2-小程序 performance/year-month 改后端权威	2h	小程序绕过点收口	B1 后端 runtime helpers
C-1 财务视图 RLS 上界	2h	双 schema 规则；DDL 同步	B 层验证通过
C-2 助教/任务视图 RLS 上界	3h	同上	同上
C-3 DWD RLS 上界	2h	同上	同上
C-4 维度 SCD2 上界	3h	历史维度回放精度	同上
C-5 配置表评估（多数不改）	0.5h	—	同上
同步主 DDL + 双 schema + DDL 副本	1h	保证仓库 ddl 与测试库一致	C 完成

总估时：约 28-30 小时，单人执行；强烈建议分 4-5 个 PR：A、B-后端、B-小程序、C 财务视图、C 其他视图。

---

四、风险与开发约束

1. live 行为不能变：所有 SQL 上界用 COALESCE(... , '9999-12-31') 形式，live 不设变量时等同无限制。
2. 双 schema 规则：db/etl_feiqiu/schemas/app.sql 与 dws.v_* 必须同时更改。
3. DDL 副本同步：每批 C 改完跑 python tools/db/gen_consolidated_ddl.py，把 docs/database/ddl/etl_feiqiu__app.sql 等同步进 git。
4. 真实时钟字段保留：updated_at = NOW()、finished_at = NOW(timezone.utc)、缓存 TTL expires_at、调度 next_run_at、AI run_logs 写入时间——这些保留真实时钟。
5. 去重键：dispatcher / cache 的「当日去重」key 需带 runtime_mode + business_date，避免 sandbox 与 live 互相污染。
6. 配置表沙箱语义：v_cfg_* 一般取「最新有效」；如需历史回放，需要单独评估 scd2_effective_to 上界。
7. 测试：每批改完都要在 test_zqyy_app + test_etl_feiqiu 上运行至少一次端到端 sandbox 切换 + 看板抽查 + AI 触发。

---

五、未覆盖项（需用户确认或单独立项）

• 生产数据库执行：本修复在 test 库通过后才能上生产；窗口需运维约定。
• 写入沙箱数据归零：长期使用沙箱后会积累 sandbox 行（任务、AI cache、run logs、recall events），应有按 runtime_mode='sandbox' AND sandbox_instance_id=... 的清理脚本。
• 小程序 utils/time.ts：当前不改；如需把「相对时间」也按沙箱算（如沙箱日下「3 天前」按沙箱日推算），属于另一议题。
• 跨多门店 sandbox：当前未限制同时多门店进入 sandbox；若并行需求，需要约定每个 site 独立 RuntimeContext + 各自上界（架构已支持）。
• Admin-Web AI 调用统计 / 监控页：是否按真实时间口径，需产品决定。

---

六、实施建议

1. 本文档已落地（docs/database/changes/2026-05-02__sandbox_no_future_data_plan.md），作为后续多 PR 的统一目录。
2. 不立即动业务代码；等用户确认范围后开始。
3. 优先级建议：A → B-后端关键路径（task_generator、board_service、prompts ref_date 漏传）→ B-AI prompts current_time → B-小程序 performance → B-fdw_queries → C-财务视图 → 其他 C。
4. 每个 PR 自带单测：sandbox 模式下 SQL 不返回 sandbox_date 之后的数据。