Neo-ZQYY/docs/_overview/wave1-findings/F1-5-impl-decisions.md

F1-5 沙箱 batch-run 接入 runtime_context — 实施决策卡

日期:2026-05-05 触发:F1-5 前置调研完成,4 份子代理报告整合后剩 6 项实施决策待 Neo 拍板 调研依据:runtime_context.py:264 / admin_service.py:622-631 / W1-T7 PRD 批 1(batch1-runtime-context-and-ai.md:494-547)/ P20 SPEC §10/§14 用法:Neo 在每个决策卡下面用 斜体 写反馈/选择,Claude 据此实施

---

决策总览

#	决策项	Claude 推荐	Neo 决定
D1	batch executor 实现方式(Semaphore / 全并发 / 串行 / TaskQueue)	Semaphore(3) + asyncio.gather + return_exceptions	(待填)
D2	GUC C 方案处置(全做 / 移除 / 混合)	混合(纳入阶段 A)	(待填)
D3	测试覆盖是否纳入 F1-5(同 commit)	纳入(阶段 A)	(待填)
D4	走查 mock 数据(切 sandbox=2026-03-01)	授权我用 PATCH 端点切 + 完成后切回 live	(待填)
D5	commit 拆分(1 个 / 2 个 / 3 个)	1 个统一 commit	(待填)
D6	P20 SPEC §11/§15/§10 文档同步更新	纳入 F1-5 commit	(待填)

---

D1. batch executor 实现方式

关联页面/接口

• 后端:apps/backend/app/services/ai/admin_service.py:622-631(_run_batch 当前是空壳 stub)
• 后端:apps/backend/app/services/ai/admin_service.py:576-620(estimate_batch / confirm_batch)
• 后端:apps/backend/app/routers/admin_ai.py:269-293(POST /batch-run / POST /batch-run/confirm)
• 前端:apps/admin-web/src/api/adminAI.ts:285,290(createBatchRun / confirmBatchRun)
• 前端:apps/admin-web/src/pages/AIOperations.tsx(批量执行 Modal,两步操作)

业务背景

/admin/ai/batch-run(两阶段提交)是 admin-web 的批量 AI 调用入口。运维选 N 个 app_type × M 个 member,估算 token / 调用次数 → 看到预估同意 → confirm 后台异步真跑。两阶段防误操作打爆 token 预算(因为 1000 个会员一次跑可能几百元)。

当前代码事实:

• estimate 端点工作 ✓ 算 token / calls
• confirm 端点工作 ✓ 返 {status: started},创建 asyncio.create_task(self._run_batch(...))
• _run_batch 是占位假动作:只 logger.info,实际不跑 AI 调用(注释"实际执行逻辑在路由层通过 dispatcher.handle_trigger 驱动"是 stub 假话)
• 路由层并未注入 dispatcher 到 service 层

冲突逻辑

当前 batch-run 端点 = 假动作:

• admin 看到 estimate 估算 / confirm 返 success
• 后台 logger 只打一行 "_run_batch invoked",0 个 AI 实际调用
• ai_run_logs / ai_cache 没有 batch 相关记录
• 这违反 PRD §"业务语义":"投递到 dispatcher"——但实际没投递

业务联系

• F1-5(本任务):batch-run 接入 sandbox runtime_context — 但前提是 batch-run 真的能跑,所以必须先把 executor 补完
• W1-T7 PRD 批 1 评估问题已标 P0:"batch_id 生命周期未声明 / 状态查询缺失 / member_ids 无上限"——但没标"实际不执行"(文档评估只看 schema 没看深度代码)
• Wave 2 计划:加 GET /batch-run/{batch_id}/status 进度查询(本次不做)
• AIPrewarm.tsx(/ai/prewarm)分组展示 72 组合,目前仅"每行触发"用单点 run/{app_type} 路径,batch-run 路径补完后可统一

修改影响

选项	影响范围	复杂度
a 全并发(asyncio.gather 无 sem)	1000 个 member 一次性发 → DashScope 限流熔断 / token 预算瞬间打爆	极不安全 ❌
b 串行(顺序 await)	1000 调用 × 2-5 秒 = 30+ 分钟,admin 看不到任何进度,confirm 时刻没回应	慢但安全
c Semaphore 限并发(我推荐 N=3)	3 个并发,1000 调用约 10 分钟,与现有 dispatcher 熔断/限流配合	平衡 ✅
d TaskQueue 推送(走 worker 消费)	引入跨进程依赖,与 confirm 端点的 asyncio.create_task 模型不一致	改造大

c 方案细节:

async def _run_batch(self, params: dict, ctx_snapshot: RuntimeContext) -> None:
    sem = asyncio.Semaphore(3)
    tasks = []
    for app_type in params["app_types"]:
        for member_id in params["member_ids"]:
            async def _one(at=app_type, mid=member_id):
                async with sem:
                    await self._dispatcher.run_single_app(
                        app_type=at,
                        context={
                            "site_id": params["site_id"],
                            "member_id": mid,
                            "business_date": ctx_snapshot.business_date.isoformat(),
                        },
                        triggered_by=f"batch:{params['batch_id']}",
                    )
            tasks.append(asyncio.create_task(_one()))
    await asyncio.gather(*tasks, return_exceptions=True)  # 单失败不连坐

• Semaphore(3):限并发 3,与 dispatcher 现有 circuit_breaker / rate_limiter 配合,不打爆 DashScope 1000 RPM 限制
• triggered_by=f"batch:{batch_id}":打标 ai_run_logs,Wave 2 加进度查询 WHERE triggered_by LIKE 'batch:<id>%' 即可统计
• ctx_snapshot:estimate 阶段抓 RuntimeContext 快照,worker 用快照值,避免 Neo 在 estimate→confirm 间切 sandbox 模式造成污染
• return_exceptions=True:1 个 member 失败不阻断其他 member,失败信息已写 ai_run_logs

推荐选项

c 方案 — Semaphore(3) + asyncio.gather + return_exceptions=True + ctx_snapshot

建议与理由

• 与现有架构(asyncio.create_task / dispatcher 限流)一致,无新引入复杂度
• 限并发 3 是经验值(可调),既快(10 分钟)又安全(不爆限流)
• 快照设计避免最大数据漂移风险(Neo 切模式时 batch 已在跑)
• triggered_by 打标为 Wave 2 进度查询埋好钩子
• 单失败不连坐符合"批量任务"行业惯例

Neo 反馈:

同意 c 方案 改并发数 N=5 改进 ctx_snapshot 合适的时机你来定)

---

D2. GUC C 方案处置

关联页面/接口

• 后端:apps/backend/app/services/runtime_context.py:244-263(apply_runtime_session_vars 函数,当前 dead code)
• DB(ETL):db/etl_feiqiu/migrations/20260502__rls_views_business_date_upper_bound.sql(26 个 app.v_* 视图加业务日上界)
• DB(ETL):app.business_date_now() 函数(读 GUC app.current_business_date,fallback 真实 today)
• DB(zqyy_app):无 RLS 视图层,业务库 SQL 直查 biz.* 表
• SPEC:docs/prd/specs/P20-runtime-context-sandbox.md §6(C 方案 GUC 路线)

业务背景

P20 沙箱机制要求:Neo 切 sandbox=2026-03-01 后,后端跑 AI / 查询数据时,只能看到 2026-03-01 及之前数据(防"未来数据泄露")。

实现方案有两条路线:

• A 应用层方案:每个查询函数都加 business_date 参数,SQL 里 WHERE date <= %s 显式裁剪
• C GUC 数据库层方案:DB 连接级 SET LOCAL app.current_business_date='2026-03-01',所有视图自动按 app.business_date_now() 裁剪(代码不需要每个 SQL 都改)

冲突逻辑

当前现状是"做了一半的 C 方案 + 大部分 A 方案":

库	方案	现状
etl_feiqiu(ETL)	C 方案	✅ 26 个视图加上界
zqyy_app(业务)	A 方案	✅ 应用层多数已传(7 prompt + 4 fetcher + board_service + fdw_queries)
apply_runtime_session_vars	C 方案"开关"	❌ 全仓库 0 处调用

致命隐性 bug:apply_runtime_session_vars 是激活 ETL 库 26 个视图的开关,但开关从未被打开 → ETL 库视图调 app.business_date_now() 拿不到 GUC → fallback 真实 today → Neo 切 sandbox=2026-03-01 后,后端走 ETL 库 app.v_* 视图查询时,仍能看到 2026-05-05 的"未来"数据。

业务联系

• F1-5 主诉求"仅能看到沙箱设定日期及之前数据" — 当前没满足(因为 GUC 开关没开)
• W1-T1 看板沙箱接入(2026-05-04)— 走 A 方案在前端 isCurrentMonthFilter 处理,与本决策正交
• W1-T2 SCD2 视图统一(2026-05-04)— 走 C 方案,本决策对其有影响(SCD2 视图也读 GUC)
• Wave 2 P1-1 schema 迁移、P1-6 触发器合并 — 与 C 方案 zqyy_app 视图层延伸相关

修改影响

选项	改动	工作量	业务效果
a 全做(扩 zqyy_app)	dispatcher 入口调 + zqyy_app 加 RLS 视图层(C 方案落地)	大(2-3 天,涉及 RLS 双 schema 规则)	两库都靠 GUC 自动保护
b 移除	删 apply_runtime_session_vars + 文档移除 C 方案 + ETL 库 26 视图改回不带 GUC	中(回滚 C 方案,审计成本)	只靠应用层 A 方案
c 混合(我推荐)	dispatcher 入口调一次 apply_runtime_session_vars + zqyy_app 库继续 A 方案,不新增 RLS 视图层	极小(1-2 行代码 + 几个调用点)	ETL 库 C 方案激活(自动保护)+ zqyy_app 应用层 A 方案(显式保护)— 两库都安全

推荐选项

c 混合方案 — 纳入阶段 A(F1-5 内做)

建议与理由

• ETL 库 C 方案是 2026-05-02 的已完成资产,丢掉浪费(b 方案)
• zqyy_app 库 RLS 视图层从无到有是新建工作量,且应用层 A 方案已做 80%(只剩 admin_service 的 CURRENT_DATE,在阶段 B1 已纳入),没必要重复建第二套保护(a 方案过度)
• c 方案只需要 dispatcher / batch executor 拿 DB 连接后调一次 apply_runtime_session_vars(conn, ctx=ctx_snapshot) → ETL 库 26 个视图立即激活
• 业务结果:Neo 切 sandbox 后,ETL 库视图自动裁剪未来数据,业务库由应用层显式传保护,两库都安全
• 副作用:docs/prd/specs/P20-runtime-context-sandbox.md 需要把 §6 中"zqyy_app 加 RLS 视图层"的规划项移除或标"永不做"

Neo 反馈:

能不能完整且统一？符合规范化的项目架构设计，保持一致，后续也能形成规范延续下去。

---

D3. 测试覆盖是否纳入 F1-5

关联页面/接口

• apps/backend/tests/(tests/tests/unit/、tests/tests/integration/)
• apps/backend/tests/test_runtime_context*.py(当前不存在)
• apps/backend/tests/test_admin_ai_*.py(已存在但 0 处 sandbox 覆盖)

业务背景

P20 SPEC §8 验收标准 AC1-13 含"沙箱模式数据隔离 / namespace 前缀正确 / 业务日上界生效"等多项硬性要求。当前全仓库 0 测试覆盖 sandbox/runtime_context:

• apply_runtime_session_vars、namespace_ai_target_id、task_runtime_filter、business_date_upper_bound_sql 全无 unit
• _run_batch 即使补完 executor,无 integration 测试验证 ctx_snapshot 不污染
• dispatcher 落 runtime 列无回归保护

冲突逻辑

• F1-5 是 P0-7 沙箱主线必修(P20 验收前提)
• 但调研发现 0 测试 → 无回归保护 → 上线后任何后续改动都可能悄无声息破坏 sandbox 隔离
• 这是 W1 findings F1-1 反馈"长事务幂等"同类风险:有规则没测试 = 规则形同虚设

业务联系

• W1 findings F1-1 长事务幂等:Neo 反馈"我们之前因没测试导致 mock/prod 偏差"(类似教训)
• F2-2 tests/ 入仓(Wave 5)— 测试需要先入仓才能跑 CI,但本地测试不需要
• 测试规范:docs/_overview/03-test-spec.md L1-L5 五级测试
• .gitignore:71 排除 tests/ → 本地写测试不能 commit(F2-2 待解决)

修改影响

选项	改动	工作量
a 纳入 F1-5(我推荐)	写 3 套测试:test_runtime_context.py(unit 13 API)/ test_admin_ai_batch_runtime.py(integration estimate→切模式→confirm 用快照)/ test_dispatcher_runtime.py(_run_step 落 runtime 列)	1-2 小时(主要是 fixture 准备)
b 留 Wave 2	现在不做,Wave 2 测试专项做	0(此次)+ Wave 2 半天
c 简化版纳入	只写 1 套 integration 测试(estimate→切模式→confirm 用快照),unit 留 Wave 2	30 分钟

推荐选项

a 纳入 F1-5 阶段 A

建议与理由

• 沙箱机制是 P0 主线,无测试上线极高风险
• 1-2 小时 vs 上线后回归 bug 抓虫 = 投入产出比极高
• F2-2 tests/ 入仓未做不阻塞:测试本地写本地跑,Wave 5 入仓时一并迁移
• W1 findings 教训告诉我们:不写测试的"机制"不是真机制
• 备选:如果时间紧,接受 c 方案(只 integration)

Neo 反馈:

同意 a 纳入

---

D4. 走查 mock 数据(切 sandbox=2026-03-01)授权

关联页面/接口

• 后端:apps/backend/app/routers/admin_runtime_context.py:95(PATCH /api/admin/runtime-context)
• DB:test_zqyy_app.biz.site_runtime_context(测试库唯一 site 2790685415443269 当前 mode='live')
• W1-T8 §14 走查清单:docs/prd/specs/P20-runtime-context-sandbox.md:487-566

业务背景

W1-T8 §14 成果层走查需要在 test_zqyy_app 切 sandbox=2026-03-01(与 W1-T1/T2 测试日期同步),实地验证:

• admin-web 顶部 sandbox 提示条显示
• 触发 1 次 app2_finance 后 ai_run_logs.runtime_mode='sandbox' + prompt JSON current_time='2026-03-01 HH:MM' + ai_cache.target_id 含 sbx_*: 前缀
• ETL 库 app.v_* 视图业务日上界生效(查不到 03-01 之后数据)

完成走查后切回 live。

冲突逻辑

• CLAUDE.md 测试与验证环境规范要求:"使用测试库,禁止连正式库" — 切 sandbox 是测试库操作,合规
• CLAUDE.md 不破坏原则:"不在测试库以外执行 DDL / TRUNCATE / DELETE" — 切 sandbox 是 UPDATE 不是 DDL,合规
• 但 mode 切换是状态改动,需要 Neo 显式授权

业务联系

• F1-5 走查必须先切 sandbox 才能验证(否则 live 模式下所有 sandbox 代码路径都不会触发)
• 切完 sandbox 不切回会污染后续测试(下次有人跑测试拿到的是"虚拟时间")
• audit_log 会记录切换动作(switch_runtime_context 内部已经写 audit)

修改影响

选项	改动	风险
a 授权 PATCH 端点切(我推荐)	调 PATCH /api/admin/runtime-context 切 sandbox=2026-03-01 + 走查完切回 live	测试库改动,有 audit 记录
b 授权 SQL 直改	UPDATE biz.site_runtime_context ... WHERE site_id=2790685415443269	绕过 audit,不推荐
c 不授权,Neo 自切	等 Neo 手动切完 + 通知 Claude 跑走查	多一轮等待,但更稳
d 走查时再决定	F1-5 改完之后再问授权	推迟决策,减少认知负担

推荐选项

a 授权 PATCH 端点切 + 完成后切回 live

建议与理由

• PATCH 端点是正式入口,自带 audit,合规
• 走查后立即切回 live 避免污染
• Claude 实施 F1-5 期间不需要切(F1-5 单元测试可用 mock RuntimeContext);只在 W1-T8 走查阶段切一次
• 切换是 idempotent 操作,失败可回滚
• 如果不放心,可以选 c(走查时 Neo 手动切)— 这是最保守的

Neo 反馈:

授权 a

---

D5. commit 拆分

关联页面/接口

• 阶段 A(MVP):admin_service.py _run_batch + estimate snapshot / admin_ai.py 路由 / app2_finance_prompt.py 3 行 / retry_trigger_job SQL / AIOperations.tsx 提示条 / 新 migration <日期>__ai_run_logs_runtime_index.sql
• 阶段 B(漂移防御):admin_service.py 6 处 SQL CURRENT_DATE / fdw_queries.py:113,2552 兜底
• 测试:3 个新 test 文件(若 D3 选 a)
• SPEC 同步:P20-runtime-context-sandbox.md §10/§11/§15(若 D6 选纳入)

业务背景

F1-5 涉及 ~10 个文件改动,跨后端 / 前端 / DB / 测试 / 文档 5 类。如何拆 commit 影响:

• 回滚粒度(出问题能精准 revert)
• 主题清晰度(commit log 可读)
• review 难度(reviewer 一次看多少)

冲突逻辑

维度	1 个 commit	2 个 commit	3 个 commit
主题	F1-5 完整收口	A 沙箱接入 / B 漂移防御	DB / Backend / Frontend
回滚	全或无	中粒度	细粒度
可读性	包大	中	多

CLAUDE.md 提倡"逻辑独立的改动各自 commit",但本次所有改动都属于 F1-5 单一主题。

业务联系

• F3-2C 之前拆 2 commit(A 处置 + B 防御 hook)— 因为是 2 个独立主题
• F1-5 是单一主题:让沙箱 batch-run 真正生效
• Wave 1 Day 1-4 多数是 1 个 commit / 任务

修改影响

选项	适用
A 1 个 commit(我推荐)	单一主题,回滚一气呵成,改动文件 ~10 个可控
B 2 个 commit	A:核心接入 / B:漂移防御 — 主题略有差异
C 3 个 commit	DB/Backend/Frontend — 跨层拆分,但每个 commit 不能独立运行(后端依赖 DB 索引,前端依赖后端字段)

推荐选项

A 1 个 commit:fix(ai): F1-5 沙箱 batch-run 接入 runtime_context(含 P20 漂移防御 + GUC C 方案激活)

建议与理由

• F1-5 是单一主题,拆 commit 反而割裂上下文
• 改动文件 10 个可读,commit message 清楚说明
• 跨层依赖(DB 索引 → 后端代码 → 前端组件)不能各自独立运行,拆 commit 后中间状态不可用
• 历史经验:F3-2C 拆 2 commit 是因为有 2 个独立主题(内容拆分 vs 防御机制),F1-5 不一样

Neo 反馈:

同意 1 个 commit

---

D6. P20 SPEC §11/§15/§10 文档同步更新

关联页面/接口

• docs/prd/specs/P20-runtime-context-sandbox.md
• §6 GUC C 方案路线(若 D2 选 c 混合,需要标"zqyy_app RLS 视图层不做")
• §10 跨模块覆盖矩阵(app2/app2a 标记从 "?" 改 ✅)
• §11 已知遗漏(删除 batch-run 相关项)
• §15 变更记录(追加 2026-05-05 F1-5)
• 可能 §14 走查归档章节(走查后追加结果链接)

业务背景

P20 SPEC 是沙箱机制的权威设计文档。F1-5 是 P20 落地的"最后一公里",完成后 SPEC 必须同步:

• §10 矩阵反映现状(否则未来 reviewer 看 SPEC 仍会以为有缺失)
• §11 已知遗漏要把 batch-run 移除(已修复)
• §15 变更记录追加里程碑

不同步会导致 SPEC 和实际代码漂移,违反 W1 findings F2-1 教训(OpenAPI 28 天 stale 同类问题)。

冲突逻辑

• CLAUDE.md 数据库 Schema 变更规则:"必须同步 docs/database/" — 类似规则适用 SPEC
• W1 findings F2-1 教训:文档与代码漂移会让审计失效

业务联系

• F2-1B 防御机制 hook(已生效):router 改动会提醒抓 OpenAPI — 类似机制对 SPEC 缺失
• W1 findings F1-1 长事务幂等:文档没说 → 没人能验收
• 后续审计文档需要引用 P20 SPEC 当前状态

修改影响

选项	改动	工作量
a 纳入 F1-5 commit(我推荐)	F1-5 同 commit 改 §6/§10/§11/§15	10 分钟(纯文档)
b 单独 commit	F1-5 后另起 commit "docs(spec): P20 同步 F1-5 落地"	多一个 commit
c 留 Wave 5 文档收尾	30+ 天 SPEC 漂移,期间任何人看到 SPEC 都误判	高漂移风险

推荐选项

a 纳入 F1-5 commit

建议与理由

• SPEC owner 视角同步,不做的话 SPEC 永远和实际漂移
• 10 分钟工作量,不值得拆 commit
• 跟 D5(1 个 commit)相容
• 跟 F3-2C 的 ai-app-prompts.md A 处置同时改造 SPEC 一样的逻辑

Neo 反馈:

同意 a 纳入

---

总览决策表(Neo 自填)

#	决策项	Claude 推荐	Neo 决定	备注
D1	batch executor 方式	Semaphore(3) + asyncio.gather + return_exceptions + ctx_snapshot
D2	GUC C 方案处置	混合(纳入阶段 A)
D3	测试覆盖	纳入(阶段 A)
D4	走查 mock 授权	授权 PATCH 切 + 完成切回
D5	commit 拆分	1 个统一 commit
D6	SPEC 同步	纳入 F1-5 commit

---

已确认项(无需决策,记录在案)

项	决策	来源
Q1 阶段 A+B 一起做	✅ 同意	Neo 5/5 反馈
Q4 子 1 — 不新建 sandbox_batch_runs 表,复用 sandbox_instance_id	✅ 同意	Neo 5/5 反馈
Q4 子 3 — ai_run_logs 索引随 F1-5 一起补	✅ 同意	Neo 5/5 反馈
Q4 子 4 — BD_manual_biz_registry_tables.md 保持分离	✅ 同意	Neo 5/5 反馈

---

关联

• F1-5 业务故事卡:00-W1-findings-stories.md(F1-5 章节)
• F1-5 反馈响应:01-W1-findings-response.md
• P20 SPEC:docs/prd/specs/P20-runtime-context-sandbox.md
• W1-T7 PRD 批 1:docs/_overview/admin-api-prd/batch1-runtime-context-and-ai.md
• 调研子代理报告(本次会话内,未单独入仓)