Neo-ZQYY/docs/database/BD_Manual_runtime_context_sandbox.md

BD_Manual：业务运行上下文（biz.site_runtime_context）+ 沙箱隔离列

目标库：test_zqyy_app（通过 TEST_APP_DB_DSN 连接）；生产库 zqyy_app 待上线 迁移脚本：db/zqyy_app/migrations/20260501__runtime_context_sandbox.sql 关联变更说明：changes/2026-05-01__runtime_context_sandbox.md 关联设计：球房停业后，希望按门店把后台 / 小程序切到“假设当前是历史日期”的状态做开发与演示，而真实预算与系统时间不受影响。

---

1. 设计目标

• 多门店隔离：每个 site_id 独立选择 live 或 sandbox，互不影响。
• 业务时钟统一：后端任务、看板、AI 调用都通过 RuntimeContext.business_date 取“今天”，不再直接调用 date.today() / NOW()。
• 写入隔离：sandbox 模式下任务、AI cache、run logs 写入时携带 runtime_mode='sandbox' + sandbox_instance_id=sbx_*，与 live 数据共存但不污染。
• 安全降级：表缺失或异常时退回 live，确保迁移前线上行为不变。

---

2. 表结构

2.1 biz.site_runtime_context（9 字段）

字段	类型	约束	说明
site_id	bigint	PK，FK → biz.sites(site_id)	门店 ID
mode	varchar(20)	NOT NULL DEFAULT 'live'，CHECK IN ('live','sandbox')	运行模式
sandbox_date	date	可空	sandbox 模式下系统假设的业务日期
sandbox_instance_id	varchar(64)	可空	sandbox 模式写入隔离实例 ID（格式 sbx_<24hex>）
ai_mode	varchar(20)	NOT NULL DEFAULT 'live'，CHECK IN ('live')	AI 调用模式；当前仅 live，沙箱也真实调用 DashScope
status	varchar(20)	NOT NULL DEFAULT 'active'	上下文状态
reason	text	可空	切换原因（运维/演示备注）
updated_by	bigint	可空	最近一次切换的 admin user_id
created_at	timestamptz	NOT NULL DEFAULT now()	创建时间
updated_at	timestamptz	NOT NULL DEFAULT now()	更新时间（API 切换时手动写入 NOW()）

约束：

约束名	类型	说明
site_runtime_context_pkey	PK	(site_id)
site_runtime_context_site_id_fkey	FK	site_id → biz.sites(site_id)
site_runtime_context_mode_check	CHECK	mode IN ('live','sandbox')
site_runtime_context_ai_mode_check	CHECK	ai_mode IN ('live')
site_runtime_context_sandbox_check	CHECK	live 模式 sandbox_* 必为 NULL；sandbox 模式 sandbox_* 必非 NULL

2.2 7 张表新增 runtime 维度列

每张表新增两列，默认值 'live' / 'live'，NOT NULL：

Schema.Table	主要用途
biz.coach_tasks	助教任务（召回/回访/关系建设）
biz.coach_task_transfer_log	任务转移日志
biz.coach_task_history	任务历史归档
biz.recall_events	消费引发的召回事件
biz.ai_cache	AI 应用缓存
biz.ai_run_logs	AI 调用明细
biz.ai_trigger_jobs	AI 调度记录

列	类型	默认值	说明
runtime_mode	varchar(20)	'live'	写入时所处模式
sandbox_instance_id	varchar(64)	'live'	sandbox 实例 ID；live 模式占位 'live'

2.3 索引

替换的旧索引：

Schema.Index	状态
biz.idx_coach_tasks_site_assistant_member_type	DROP
biz.idx_recall_events_site_assistant_member_day	DROP

新建索引：

Schema.Index	类型	列	说明
idx_coach_tasks_runtime_unique_active	UNIQUE，部分 WHERE status='active'	(site_id, assistant_id, member_id, task_type, runtime_mode, sandbox_instance_id)	同一 (site/assistant/member/task) 在 live 与 sandbox 之间互不冲突，可同时存在活跃任务
idx_recall_events_runtime_site_assistant_member_day	UNIQUE	(site_id, assistant_id, member_id, runtime_mode, sandbox_instance_id, date_trunc('day', pay_time AT TIME ZONE 'Asia/Shanghai'))	召回事件按当日去重，加入 runtime 维度
idx_coach_tasks_runtime_assistant_status	INDEX	(site_id, runtime_mode, sandbox_instance_id, assistant_id, status)	任务列表查询
idx_ai_cache_runtime_lookup	INDEX	(cache_type, site_id, runtime_mode, sandbox_instance_id, target_id, created_at DESC)	AI cache 查询
idx_ai_trigger_jobs_runtime_site	INDEX	(site_id, runtime_mode, sandbox_instance_id, event_type, status)	AI 调度记录查询

---

3. 写入与查询约定

3.1 写入

写入新行时统一使用 app.services.runtime_context.runtime_insert_columns(site_id) 取出列、占位符与值；live 行得到 ('live','live')，sandbox 行得到 ('sandbox', sbx_<id>)。

biz.ai_cache.target_id 在 sandbox 模式下会被 namespace_ai_target_id 加上前缀，例如 sbx_xxx:this_month__all。

3.2 查询

业务查询统一使用 task_runtime_filter(site_id, alias=...)：

• live 模式 AND COALESCE(t.runtime_mode,'live')='live' AND COALESCE(t.sandbox_instance_id,'live')='live'
• sandbox 模式 AND t.runtime_mode='sandbox' AND t.sandbox_instance_id=%s

3.3 切换 API

接口	权限	说明
GET /api/config/runtime-context	任意登录用户	返回当前用户门店的 RuntimeContext
GET /api/admin/runtime-context?site_id=...	super_admin	按 site_id 查询
GET /api/admin/runtime-context/sites	super_admin	列出门店与运行上下文
PATCH /api/admin/runtime-context	super_admin	切换 live/sandbox

切换 sandbox 时按 site_id 暂停 biz.trigger_jobs 中 status='enabled' 的记录为 paused_by_sandbox；切回 live 时恢复同一 site 的 paused_by_sandbox 为 enabled。

---

4. 真实数据 vs 沙箱数据

主体	live 行	sandbox 行
业务时钟	真实日期	sandbox_date
任务表	写入 ('live','live')	写入 ('sandbox', sbx_*)
AI cache	runtime_mode='live'，target_id 不变	runtime_mode='sandbox'，target_id 加 sbx_*: 前缀
AI run logs / trigger jobs	live	sandbox + sbx_*
真实预算 / DashScope tokens 计费	计入真实统计	同样真实计入（不为节流）
biz.trigger_jobs	sandbox 模式下当前 site 下 enabled 行被改为 paused_by_sandbox；其它 site 不动

---

5. 验证清单

• 列 / 索引 / 约束按 changes/2026-05-01__runtime_context_sandbox.md 第 4 节 5 项 SQL 验证。
• 切换流程：在 admin-web /settings/runtime-context 选择门店 → 切到 sandbox（指定 sandbox_date）→ 验证 biz.trigger_jobs 仅当前 site 被暂停，其它 site 不受影响 → 切回 live 恢复。

---

6. 注意事项

• 不要直接清空 sandbox 数据：coach_tasks、ai_cache 等如有清理需求，须按 runtime_mode='sandbox' AND sandbox_instance_id=... 限定。
• 生产库上线：执行迁移前先确认无门店启用 sandbox；上线后再开放 admin-web 入口。
• 降级路径：当 biz.site_runtime_context 表暂未上线（如逐步发布），后端 get_runtime_context 自动降级为 live，避免业务中断。

7. 读取层「不看未来」改造路线

R1 初版只解决了写入隔离。读取层的看板 / 任务 / AI / 小程序仍存在「sandbox 模式下读到 sandbox_date 之后真实数据」的风险。完整改造方案与逐项文件清单见 changes/2026-05-02__sandbox_no_future_data_plan.md。

层	进度
A 文档 / UI 警告	进行中（admin-web Alert + 本章节）
B-1 后端 service / prompts / data_fetchers / fdw_queries 时间锚替换与 SQL 上界	计划中
B-2 小程序去除本地年月	计划中
C ETL RLS 视图层 app.current_business_date 业务日上界	计划中

完成顺序按 plan 文档执行；每个 PR 自带 sandbox 模式下「不返回 sandbox_date 之后数据」的最小验证。