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

> 目标库：`test_zqyy_app`（通过 `TEST_APP_DB_DSN` 连接）；生产库 `zqyy_app` 待上线
> 迁移脚本：[db/zqyy_app/migrations/20260501__runtime_context_sandbox.sql](../../db/zqyy_app/migrations/20260501__runtime_context_sandbox.sql)
> 关联变更说明：[changes/2026-05-01__runtime_context_sandbox.md](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](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 之后数据」的最小验证。