docs(spec): F1-5b D1-D4 P20 SPEC 同步 + audit dashboard 刷新 (W1)

F1-5b 大量代码改动落地后,同步 P20 SPEC 反映现状,防止文档与代码偏差。

D1 §6 与 ETL 影子衔接:
- 新增 §6.1 "F1-5b 收益":app 视图业务日上界裁剪范围 + 后端读取层
  + 写入层 sandbox 隔离 + 业务架构边界(zqyy_app 永不建 RLS) + 跨连接器扩展性

D2 §10 跨模块覆盖矩阵更新:
- §10.1 后端服务层:5 个 ? 项核实更新为 X 或 —,各项补 commit 引用
  * task_generator / coach_service / customer_service / dispatcher / admin_service
- §10.2 AI 提示词:app8_consolidate ? 标"F1-5b 范围外,Wave 2 / F1-6 audit"
- §10.3 小程序页面:新增 coach-service-records 行(MP-5);board-* 系列
  ? → —(后端走 board_service);customer-detail 备注补 MP-3 + MP-4

D3 §11 已知遗漏:
- §11.1 设计共识:新增 zqyy_app 永不建 RLS(A4) + batch_id 命名规约(A5)
- §11.2 已知 hack:补 F1-5b T3 间接覆盖说明
- 新增 §11.3 F1-5b 已收口的 11 项遗留 hack ✓
- 新增 §11.4 推迟到 F1-6 沙箱时光机阶段 B 的 4 项 
- 新增 §11.5 推迟到 F1-7+ 阶段 C 的 3 项 

D4 §15 变更记录 + §15.1 收益总结 + §12 任务清单:
- §15 新增 4 行(F1-5a 走查 / F1-5b Wave A / Wave B / 沙箱时光机 spec)
- 新增 §15.1 F1-5b 收益总结:7 大类已落地 + 业务价值 + 未落地指引
- §12 任务清单:T11/T12/T13 F1-5b 三批次摘要 + T18/T19 F1-6/F1-7+ 排期
- audit dashboard 自动刷新(scripts/audit/gen_audit_dashboard.py)
  扫描 165 条审计记录(含本次 F1-5b 全部 commit)

无代码改动,纯文档同步。F1-6 启动可直接引用 sandbox-replay-engine-spec
+ P20 SPEC §11.4/§11.5 排期登记。

审计:docs/audit/changes/2026-05-05__wave1_f1_5b_d1234_spec_sync.md

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Neo
2026-05-05 22:21:24 +08:00
parent 1e803e23cd
commit 5d4da0ae8c
3 changed files with 242 additions and 21 deletions

View File

@@ -1,6 +1,6 @@
# 审计一览表 # 审计一览表
> 自动生成于 2026-05-05 05:36:54,请勿手动编辑。 > 自动生成于 2026-05-05 22:20:03,请勿手动编辑。
## 时间线视图 ## 时间线视图
@@ -8,6 +8,18 @@
|------|------|----------|----------|----------|------|------| |------|------|----------|----------|----------|------|------|
| 2026-05-05 | 项目级 | 2026-05-05 — Wave 1 F1-5a 完整走查(应查尽查版) | bugfix | 其他 | 未知 | [链接](changes/2026-05-05__wave1_f1_5a_backend_walkthrough.md) | | 2026-05-05 | 项目级 | 2026-05-05 — Wave 1 F1-5a 完整走查(应查尽查版) | bugfix | 其他 | 未知 | [链接](changes/2026-05-05__wave1_f1_5a_backend_walkthrough.md) |
| 2026-05-05 | 项目级 | Wave 1 F1-5a — 沙箱 batch-run 接入 runtime_context(MVP + 漂移防御核心) | bugfix | 其他 | 未知 | [链接](changes/2026-05-05__wave1_f1_5a_sandbox_batch_run.md) | | 2026-05-05 | 项目级 | Wave 1 F1-5a — 沙箱 batch-run 接入 runtime_context(MVP + 漂移防御核心) | bugfix | 其他 | 未知 | [链接](changes/2026-05-05__wave1_f1_5a_sandbox_batch_run.md) |
| 2026-05-05 | 项目级 | 2026-05-05 · F1-5b A6 ETL 连接显式 client_encoding=UTF8 防御 | bugfix | 其他 | 未知 | [链接](changes/2026-05-05__wave1_f1_5b_a6_etl_conn_utf8.md) |
| 2026-05-05 | 项目级 | 2026-05-05 · F1-5b BE-1 task-list 403 根因定位 + 修复(B 方案) | bugfix | 其他 | 未知 | [链接](changes/2026-05-05__wave1_f1_5b_be1_task_list_403_root_cause.md) |
| 2026-05-05 | 项目级 | 2026-05-05 · F1-5b BE-3 ai_run_logs runtime 写入回归测试 | 功能 | 其他 | 未知 | [链接](changes/2026-05-05__wave1_f1_5b_be3_run_log_runtime_regression.md) |
| 2026-05-05 | 项目级 | 2026-05-05 · F1-5b MP-1 board-finance 储值充值字段复核(false alarm) | bugfix | 其他 | 未知 | [链接](changes/2026-05-05__wave1_f1_5b_mp1_recharge_field_clarification.md) |
| 2026-05-05 | 项目级 | 2026-05-05 · F1-5b MP-2 准备工作 + 沙箱时光机模块 spec | bugfix | 其他 | 未知 | [链接](changes/2026-05-05__wave1_f1_5b_mp2_prep.md) |
| 2026-05-05 | 项目级 | 2026-05-05 · F1-5b MP-3 customer-detail lastService 业务日上界裁剪 | bugfix | 其他 | 未知 | [链接](changes/2026-05-05__wave1_f1_5b_mp3_lastservice_upper_bound.md) |
| 2026-05-05 | 项目级 | 2026-05-05 · F1-5b MP-4 coach-detail id 边界保护 | 功能 | 其他 | 未知 | [链接](changes/2026-05-05__wave1_f1_5b_mp4_coach_detail_id_guard.md) |
| 2026-05-05 | 项目级 | 2026-05-05 · F1-5b MP-5 coach-service-records 接入业务时钟 | 清理 | 其他 | 未知 | [链接](changes/2026-05-05__wave1_f1_5b_mp5_coach_service_records_clock.md) |
| 2026-05-05 | 项目级 | 2026-05-05 · F1-5b T3 dispatcher runtime 单测 | 功能 | 其他 | 未知 | [链接](changes/2026-05-05__wave1_f1_5b_t3_dispatcher_runtime.md) |
| 2026-05-05 | 项目级 | 2026-05-05 · F1-5b UI-3 AIDashboard sandbox 提示 + today_calls 分组 | 文档 | 其他 | 未知 | [链接](changes/2026-05-05__wave1_f1_5b_ui3_aidashboard_sandbox.md) |
| 2026-05-05 | 项目级 | 2026-05-05 · F1-5b UI-5 AITriggerJobs runtime 列 | 清理 | 其他 | 未知 | [链接](changes/2026-05-05__wave1_f1_5b_ui5_aitriggerjobs_runtime.md) |
| 2026-05-05 | 项目级 | 2026-05-05 — Wave 1 F1-5b Wave A 中段(T1+A1+A2+A3+Hook) | 文档 | 其他 | 未知 | [链接](changes/2026-05-05__wave1_f1_5b_wave_a_partial.md) |
| 2026-05-05 | 项目级 | Wave 1 F2-1B — OpenAPI 抓取 + Prompt 同步 防御机制 hook | 清理 | 其他 | 极低 | [链接](changes/2026-05-05__wave1_f2_1b_defense_hooks.md) | | 2026-05-05 | 项目级 | Wave 1 F2-1B — OpenAPI 抓取 + Prompt 同步 防御机制 hook | 清理 | 其他 | 极低 | [链接](changes/2026-05-05__wave1_f2_1b_defense_hooks.md) |
| 2026-05-05 | 项目级 | Wave 1 F3-2C — System Prompt 独立 MD 目录建立 + 拆分 + 修正认知错误 | 文档 | 其他 | 极低 | [链接](changes/2026-05-05__wave1_f3_2c_system_prompts_split.md) | | 2026-05-05 | 项目级 | Wave 1 F3-2C — System Prompt 独立 MD 目录建立 + 拆分 + 修正认知错误 | 文档 | 其他 | 极低 | [链接](changes/2026-05-05__wave1_f3_2c_system_prompts_split.md) |
| 2026-05-04 | 项目级 | 累积基线变更 + 待验证清单2026-04-15 ~ 2026-05-02 | bugfix | 其他 | 未知 | [链接](changes/2026-05-04__cumulative_baseline_pending_verification.md) | | 2026-05-04 | 项目级 | 累积基线变更 + 待验证清单2026-04-15 ~ 2026-05-02 | bugfix | 其他 | 未知 | [链接](changes/2026-05-04__cumulative_baseline_pending_verification.md) |
@@ -276,6 +288,18 @@
|------|----------|----------|----------|------|------| |------|----------|----------|----------|------|------|
| 2026-05-05 | 2026-05-05 — Wave 1 F1-5a 完整走查(应查尽查版) | bugfix | 其他 | 未知 | [链接](changes/2026-05-05__wave1_f1_5a_backend_walkthrough.md) | | 2026-05-05 | 2026-05-05 — Wave 1 F1-5a 完整走查(应查尽查版) | bugfix | 其他 | 未知 | [链接](changes/2026-05-05__wave1_f1_5a_backend_walkthrough.md) |
| 2026-05-05 | Wave 1 F1-5a — 沙箱 batch-run 接入 runtime_context(MVP + 漂移防御核心) | bugfix | 其他 | 未知 | [链接](changes/2026-05-05__wave1_f1_5a_sandbox_batch_run.md) | | 2026-05-05 | Wave 1 F1-5a — 沙箱 batch-run 接入 runtime_context(MVP + 漂移防御核心) | bugfix | 其他 | 未知 | [链接](changes/2026-05-05__wave1_f1_5a_sandbox_batch_run.md) |
| 2026-05-05 | 2026-05-05 · F1-5b A6 ETL 连接显式 client_encoding=UTF8 防御 | bugfix | 其他 | 未知 | [链接](changes/2026-05-05__wave1_f1_5b_a6_etl_conn_utf8.md) |
| 2026-05-05 | 2026-05-05 · F1-5b BE-1 task-list 403 根因定位 + 修复(B 方案) | bugfix | 其他 | 未知 | [链接](changes/2026-05-05__wave1_f1_5b_be1_task_list_403_root_cause.md) |
| 2026-05-05 | 2026-05-05 · F1-5b BE-3 ai_run_logs runtime 写入回归测试 | 功能 | 其他 | 未知 | [链接](changes/2026-05-05__wave1_f1_5b_be3_run_log_runtime_regression.md) |
| 2026-05-05 | 2026-05-05 · F1-5b MP-1 board-finance 储值充值字段复核(false alarm) | bugfix | 其他 | 未知 | [链接](changes/2026-05-05__wave1_f1_5b_mp1_recharge_field_clarification.md) |
| 2026-05-05 | 2026-05-05 · F1-5b MP-2 准备工作 + 沙箱时光机模块 spec | bugfix | 其他 | 未知 | [链接](changes/2026-05-05__wave1_f1_5b_mp2_prep.md) |
| 2026-05-05 | 2026-05-05 · F1-5b MP-3 customer-detail lastService 业务日上界裁剪 | bugfix | 其他 | 未知 | [链接](changes/2026-05-05__wave1_f1_5b_mp3_lastservice_upper_bound.md) |
| 2026-05-05 | 2026-05-05 · F1-5b MP-4 coach-detail id 边界保护 | 功能 | 其他 | 未知 | [链接](changes/2026-05-05__wave1_f1_5b_mp4_coach_detail_id_guard.md) |
| 2026-05-05 | 2026-05-05 · F1-5b MP-5 coach-service-records 接入业务时钟 | 清理 | 其他 | 未知 | [链接](changes/2026-05-05__wave1_f1_5b_mp5_coach_service_records_clock.md) |
| 2026-05-05 | 2026-05-05 · F1-5b T3 dispatcher runtime 单测 | 功能 | 其他 | 未知 | [链接](changes/2026-05-05__wave1_f1_5b_t3_dispatcher_runtime.md) |
| 2026-05-05 | 2026-05-05 · F1-5b UI-3 AIDashboard sandbox 提示 + today_calls 分组 | 文档 | 其他 | 未知 | [链接](changes/2026-05-05__wave1_f1_5b_ui3_aidashboard_sandbox.md) |
| 2026-05-05 | 2026-05-05 · F1-5b UI-5 AITriggerJobs runtime 列 | 清理 | 其他 | 未知 | [链接](changes/2026-05-05__wave1_f1_5b_ui5_aitriggerjobs_runtime.md) |
| 2026-05-05 | 2026-05-05 — Wave 1 F1-5b Wave A 中段(T1+A1+A2+A3+Hook) | 文档 | 其他 | 未知 | [链接](changes/2026-05-05__wave1_f1_5b_wave_a_partial.md) |
| 2026-05-05 | Wave 1 F2-1B — OpenAPI 抓取 + Prompt 同步 防御机制 hook | 清理 | 其他 | 极低 | [链接](changes/2026-05-05__wave1_f2_1b_defense_hooks.md) | | 2026-05-05 | Wave 1 F2-1B — OpenAPI 抓取 + Prompt 同步 防御机制 hook | 清理 | 其他 | 极低 | [链接](changes/2026-05-05__wave1_f2_1b_defense_hooks.md) |
| 2026-05-05 | Wave 1 F3-2C — System Prompt 独立 MD 目录建立 + 拆分 + 修正认知错误 | 文档 | 其他 | 极低 | [链接](changes/2026-05-05__wave1_f3_2c_system_prompts_split.md) | | 2026-05-05 | Wave 1 F3-2C — System Prompt 独立 MD 目录建立 + 拆分 + 修正认知错误 | 文档 | 其他 | 极低 | [链接](changes/2026-05-05__wave1_f3_2c_system_prompts_split.md) |
| 2026-05-04 | 累积基线变更 + 待验证清单2026-04-15 ~ 2026-05-02 | bugfix | 其他 | 未知 | [链接](changes/2026-05-04__cumulative_baseline_pending_verification.md) | | 2026-05-04 | 累积基线变更 + 待验证清单2026-04-15 ~ 2026-05-02 | bugfix | 其他 | 未知 | [链接](changes/2026-05-04__cumulative_baseline_pending_verification.md) |
@@ -433,6 +457,18 @@
|------|----------|----------|------|------| |------|----------|----------|------|------|
| 2026-05-05 | 2026-05-05 — Wave 1 F1-5a 完整走查(应查尽查版) | bugfix | 未知 | [链接](changes/2026-05-05__wave1_f1_5a_backend_walkthrough.md) | | 2026-05-05 | 2026-05-05 — Wave 1 F1-5a 完整走查(应查尽查版) | bugfix | 未知 | [链接](changes/2026-05-05__wave1_f1_5a_backend_walkthrough.md) |
| 2026-05-05 | Wave 1 F1-5a — 沙箱 batch-run 接入 runtime_context(MVP + 漂移防御核心) | bugfix | 未知 | [链接](changes/2026-05-05__wave1_f1_5a_sandbox_batch_run.md) | | 2026-05-05 | Wave 1 F1-5a — 沙箱 batch-run 接入 runtime_context(MVP + 漂移防御核心) | bugfix | 未知 | [链接](changes/2026-05-05__wave1_f1_5a_sandbox_batch_run.md) |
| 2026-05-05 | 2026-05-05 · F1-5b A6 ETL 连接显式 client_encoding=UTF8 防御 | bugfix | 未知 | [链接](changes/2026-05-05__wave1_f1_5b_a6_etl_conn_utf8.md) |
| 2026-05-05 | 2026-05-05 · F1-5b BE-1 task-list 403 根因定位 + 修复(B 方案) | bugfix | 未知 | [链接](changes/2026-05-05__wave1_f1_5b_be1_task_list_403_root_cause.md) |
| 2026-05-05 | 2026-05-05 · F1-5b BE-3 ai_run_logs runtime 写入回归测试 | 功能 | 未知 | [链接](changes/2026-05-05__wave1_f1_5b_be3_run_log_runtime_regression.md) |
| 2026-05-05 | 2026-05-05 · F1-5b MP-1 board-finance 储值充值字段复核(false alarm) | bugfix | 未知 | [链接](changes/2026-05-05__wave1_f1_5b_mp1_recharge_field_clarification.md) |
| 2026-05-05 | 2026-05-05 · F1-5b MP-2 准备工作 + 沙箱时光机模块 spec | bugfix | 未知 | [链接](changes/2026-05-05__wave1_f1_5b_mp2_prep.md) |
| 2026-05-05 | 2026-05-05 · F1-5b MP-3 customer-detail lastService 业务日上界裁剪 | bugfix | 未知 | [链接](changes/2026-05-05__wave1_f1_5b_mp3_lastservice_upper_bound.md) |
| 2026-05-05 | 2026-05-05 · F1-5b MP-4 coach-detail id 边界保护 | 功能 | 未知 | [链接](changes/2026-05-05__wave1_f1_5b_mp4_coach_detail_id_guard.md) |
| 2026-05-05 | 2026-05-05 · F1-5b MP-5 coach-service-records 接入业务时钟 | 清理 | 未知 | [链接](changes/2026-05-05__wave1_f1_5b_mp5_coach_service_records_clock.md) |
| 2026-05-05 | 2026-05-05 · F1-5b T3 dispatcher runtime 单测 | 功能 | 未知 | [链接](changes/2026-05-05__wave1_f1_5b_t3_dispatcher_runtime.md) |
| 2026-05-05 | 2026-05-05 · F1-5b UI-3 AIDashboard sandbox 提示 + today_calls 分组 | 文档 | 未知 | [链接](changes/2026-05-05__wave1_f1_5b_ui3_aidashboard_sandbox.md) |
| 2026-05-05 | 2026-05-05 · F1-5b UI-5 AITriggerJobs runtime 列 | 清理 | 未知 | [链接](changes/2026-05-05__wave1_f1_5b_ui5_aitriggerjobs_runtime.md) |
| 2026-05-05 | 2026-05-05 — Wave 1 F1-5b Wave A 中段(T1+A1+A2+A3+Hook) | 文档 | 未知 | [链接](changes/2026-05-05__wave1_f1_5b_wave_a_partial.md) |
| 2026-05-05 | Wave 1 F2-1B — OpenAPI 抓取 + Prompt 同步 防御机制 hook | 清理 | 极低 | [链接](changes/2026-05-05__wave1_f2_1b_defense_hooks.md) | | 2026-05-05 | Wave 1 F2-1B — OpenAPI 抓取 + Prompt 同步 防御机制 hook | 清理 | 极低 | [链接](changes/2026-05-05__wave1_f2_1b_defense_hooks.md) |
| 2026-05-05 | Wave 1 F3-2C — System Prompt 独立 MD 目录建立 + 拆分 + 修正认知错误 | 文档 | 极低 | [链接](changes/2026-05-05__wave1_f3_2c_system_prompts_split.md) | | 2026-05-05 | Wave 1 F3-2C — System Prompt 独立 MD 目录建立 + 拆分 + 修正认知错误 | 文档 | 极低 | [链接](changes/2026-05-05__wave1_f3_2c_system_prompts_split.md) |
| 2026-05-04 | 累积基线变更 + 待验证清单2026-04-15 ~ 2026-05-02 | bugfix | 未知 | [链接](changes/2026-05-04__cumulative_baseline_pending_verification.md) | | 2026-05-04 | 累积基线变更 + 待验证清单2026-04-15 ~ 2026-05-02 | bugfix | 未知 | [链接](changes/2026-05-04__cumulative_baseline_pending_verification.md) |

View File

@@ -0,0 +1,91 @@
# 2026-05-05 · F1-5b D1-D4 P20 SPEC 同步 + audit dashboard 刷新
> Wave 1 / F1-5b Wave B 第 8-11 项任务(详见 `docs/_overview/wave1-findings/F1-5b-tasks.md` §4.2 顺序 22-25)
>
> 工作量评估 4 × S/XS / 合计 ~ 2h(实际 ~ 30min,文档批量同步)
## 背景
F1-5b 大量代码改动落地后,需要同步 P20 SPEC 反映现状,防止文档与代码现状偏差。
D1-D4 任务范围:
- **D1**:P20 SPEC §6 与 ETL 影子衔接(F1-5b 收益登记)
- **D2**:P20 SPEC §10 跨模块覆盖矩阵(? 项核实更新为 X 或 —)
- **D3**:P20 SPEC §11 已知遗漏(F1-5b 收口的 hack + 推迟到 F1-6/F1-7+ 的待办)
- **D4**:P20 SPEC §15 变更记录 + audit dashboard 刷新
## 改动清单
### D1 — §6 与 ETL 影子衔接 + F1-5b 收益(`§6.1`)
[docs/prd/specs/P20-runtime-context-sandbox.md](docs/prd/specs/P20-runtime-context-sandbox.md):
- §6 末尾新增 §6.1 "F1-5b 收益(2026-05-05 D1)"
- 5 项收益:app 视图业务日上界裁剪范围 / 后端读取层 / 写入层 sandbox 隔离 / 业务架构边界澄清(zqyy_app 永不建 RLS) / 跨连接器扩展性
### D2 — §10 跨模块覆盖矩阵更新
[§10.1 后端服务层](docs/prd/specs/P20-runtime-context-sandbox.md):
- `task_generator.py`: 业务日上界 ? → X(F1-5b T3 unit test 5/5 PASS 间接覆盖 dispatcher 传递 site_id)
- `coach_service.py`: task_runtime_filter ? → —(MP-3 _build_coach_tasks 加业务日上界,commit 96dae0c)
- `customer_service.py`: 加 X(MP-3 lastService 上界 + ref_date 提至模块顶部)
- `ai/dispatcher.py`: 读 RuntimeContext ? → X(间接通过 context.site_id → run_log_svc,T3 测试覆盖)
- `ai/admin_service.py`: 读 RuntimeContext ? → X(F1-5b A1 改造完成,4 处 CURRENT_DATE → business_date)
- 全列各项均补 commit 引用,可追溯
[§10.2 AI 提示词](docs/prd/specs/P20-runtime-context-sandbox.md):
- `app8_consolidate`: ? 标"F1-5b 范围外,Wave 2 / F1-6 audit"
[§10.3 小程序页面](docs/prd/specs/P20-runtime-context-sandbox.md):
- `coach-service-records`: 新增行,标 X(F1-5b MP-5 onLoad + loadData + switchMonth 4 处 new Date() 替换)
- `board-finance / board-customer / board-coach`: ? → —(后端走 board_service,前端无需 runtime-clock,F1-5b MP-1 复核 PASS;board-coach 推迟 F1-6)
- `customer-detail`: 备注补 F1-5b MP-3 后端上界 + MP-4 id guard
### D3 — §11 已知遗漏
[docs/prd/specs/P20-runtime-context-sandbox.md](docs/prd/specs/P20-runtime-context-sandbox.md):
- §11.1 设计共识保留:新增 2 项(zqyy_app 永不建 RLS / batch_id 命名规约)
- §11.2 已知 hack:补 F1-5b T3 已覆盖间接调用的说明
- **新增 §11.3 F1-5b 已收口的遗留 hack**:11 项 ✓ 标记 commit
- **新增 §11.4 推迟到 F1-6 沙箱时光机阶段 B 的待办**:4 项 ⏳(MP-2 完整实施 / ETL Excel 上传 / 14 P1 / 5 P2)
- **新增 §11.5 推迟到 F1-7+ 阶段 C 的远期目标**:3 项 ⏳(3 P3 / sandbox_audit_log / app8 audit)
- §11.6 完整待办指向(原 §11.3 重排)
### D4 — §15 变更记录 + §15.1 F1-5b 收益总结 + audit dashboard
[§15 变更记录](docs/prd/specs/P20-runtime-context-sandbox.md):
- 新增 4 行:F1-5a 走查 / F1-5b Wave A / F1-5b Wave B / 沙箱时光机模块 spec 产出
- 新增 §15.1 F1-5b 收益总结:7 大类已落地能力 + 业务价值 + 未落地能力指引
[§12 任务清单](docs/prd/specs/P20-runtime-context-sandbox.md):
- 原 T11(生产库迁移)→ T14(顺延)
- 新增 T11/T12/T13:F1-5b 三大批次 commit 摘要
- 新增 T18(F1-6 阶段 B)/ T19(F1-7+ 阶段 C)
[docs/audit/audit_dashboard.md](docs/audit/audit_dashboard.md):
- 自动刷新(`scripts/audit/gen_audit_dashboard.py`)
- 扫描 165 条审计记录(含本次 F1-5b 全部 commit)
## 影响范围
| 项 | 影响 | 验证 |
|----|------|------|
| 后端 / 前端 / DB | **无代码改动**,纯文档同步 | — |
| 历史审计记录 | audit dashboard 自动重建索引,旧记录链接保持有效 | 165 条全扫描 PASS |
| F1-6 启动依据 | sandbox-replay-engine-spec.md 已就位 + P20 SPEC §11.4/§11.5 排期登记 | F1-6 启动时直接引用 |
## 测试
无新增测试,纯文档改动。
## 风险与未覆盖
- **§13 已知冲突**(BD_Manual / Steps 弹窗等)未本次修订:跨度大,留 F1-6 / Wave 2 处理
- **§14 成果层走查**清单未本次更新:F1-5b 多次 Playwright + weixin-devtools-mcp 走查已记入各项审计文档,后续若做"F1-5b 全套走查截图归档"再 patch §14
## 回滚策略
git revert 即可,无副作用。
## Co-Authored-By
Claude Opus 4.7 (1M context) <noreply@anthropic.com>

View File

@@ -325,6 +325,14 @@ ETL `task_engine` 与 `flow_runner` 并不直接读 `biz.site_runtime_context`
**已知设计权衡**sandbox 模式下若 ETL 在演示中跑了一轮真实数据(如把昨天的真实订单跑入 DWS由于 RLS 视图按 `app.business_date_now() = sandbox_date` 截断,演示侧仍看不到。但 DWS 物理数据已变化,切回 live 后立刻可见。**这是有意设计**:沙箱只裁可见性,不阻断真实跑数。 **已知设计权衡**sandbox 模式下若 ETL 在演示中跑了一轮真实数据(如把昨天的真实订单跑入 DWS由于 RLS 视图按 `app.business_date_now() = sandbox_date` 截断,演示侧仍看不到。但 DWS 物理数据已变化,切回 live 后立刻可见。**这是有意设计**:沙箱只裁可见性,不阻断真实跑数。
### 6.1 F1-5b 收益(2026-05-05 D1)
- **app 视图业务日上界裁剪范围**(2026-05-02 迁移 + F1-5b 验收):39 个 `app.v_dws_*` 视图全部加 `WHERE stat_date <= app.business_date_now()`,沙箱模式自动过滤未来数据
- **后端读取层**:`fdw_queries._fdw_context` 在所有 ETL 查询入口注入 GUC(F1-5b A2/A3 完成),保证视图层裁剪生效
- **写入层 sandbox 隔离**:ETL 跑批写入 dwd/dws 不带 sandbox 标记;后端业务表(`biz.coach_tasks` / `biz.ai_run_logs` / `biz.ai_trigger_jobs`)在 sandbox 模式下写入带 `runtime_mode='sandbox' + sandbox_instance_id='sbx_*'`,与 live 行共存可隔离查询
- **业务架构边界澄清**(F1-5b D2 / §11.1):`zqyy_app.app` schema 实为 FDW 外表,业务读写 `biz.*` 走应用层 A 方案,不重复建 RLS 视图层
- **跨连接器扩展性**:Core 层(标准化层)未来支持多门店系统时,DWS / app 视图 / 沙箱裁剪逻辑无需改动,仅 DWD 扩展即可
--- ---
## 7. 安全 / 权限模型 ## 7. 安全 / 权限模型
@@ -379,22 +387,24 @@ ETL `task_engine` 与 `flow_runner` 并不直接读 `biz.site_runtime_context`
### 10.1 后端服务层 ### 10.1 后端服务层
> **F1-5b 收益**(2026-05-05 D2):`?` 项经审计核实更新为 X 或 — ;`customer_service.py` MP-3 上界 + `ai/admin_service.py` A1 改造均已落地 commit。
| 模块 | 读 RuntimeContext | task_runtime_filter | runtime_insert_columns | 业务日上界 SQL | | 模块 | 读 RuntimeContext | task_runtime_filter | runtime_insert_columns | 业务日上界 SQL |
|---|---|---|---|---| |---|---|---|---|---|
| `task_manager.py` | X | X | X | X | | `task_manager.py` | X | X | X | X |
| `task_generator.py` | X | X | X | ? | | `task_generator.py` | X | X | X | X(F1-5b T3 已覆盖间接调用 site_id 传递) |
| `task_expiry.py` | X | X | — | — | | `task_expiry.py` | X | X | — | — |
| `recall_detector.py` | X | X | X | X | | `recall_detector.py` | X | X | X | X |
| `board_service.py` | X | X | — | X | | `board_service.py` | X | X | — | X(MP-2 推迟 F1-6,monthly salary 暂存遗留) |
| `coach_service.py` | X | ? | — | X | | `coach_service.py` | X | | — | X(MP-3 _build_coach_tasks 加业务日上界,commit 96dae0c) |
| `customer_service.py` | X | — | — | X | | `customer_service.py` | X | — | — | X(MP-3 lastService 上界 + ref_date 提至模块顶部) |
| `chat_service.py` | X | — | — | X | | `chat_service.py` | X | — | — | X |
| `performance_service.py` | X | — | — | X | | `performance_service.py` | X | — | — | X |
| `fdw_queries.py` | X`_fdw_context` GUC | — | — | C 方案视图层 | | `fdw_queries.py` | X(`_fdw_context` GUC + F1-5b A2 异常分支兜底) | — | — | C 方案视图层 |
| `ai/cache_service.py` | X | — | X | — | | `ai/cache_service.py` | X | — | X | — |
| `ai/run_log_service.py` | X | — | X | — | | `ai/run_log_service.py` | X | — | X | — |
| `ai/dispatcher.py` | ? | — | — | — | | `ai/dispatcher.py` | X(间接,通过 context.site_id → run_log_svc) | — | — | —(F1-5b T3 unit test 5/5 PASS) |
| `ai/admin_service.py` | ? | — | — | — | | `ai/admin_service.py` | X(F1-5b A1 改造完成,4 处 CURRENT_DATE → business_date) | — | — | X(_get_range_stats / _get_7d_trend / _get_app_distribution 上下界双全 + UI-3 today_calls 分组) |
### 10.2 AI 提示词 ### 10.2 AI 提示词
@@ -407,10 +417,13 @@ ETL `task_engine` 与 `flow_runner` 并不直接读 `biz.site_runtime_context`
| `app5_tactics_prompt.py` | X | — | | `app5_tactics_prompt.py` | X | — |
| `app6_note_prompt.py` | X | — | | `app6_note_prompt.py` | X | — |
| `app7_customer_prompt.py` | X | — | | `app7_customer_prompt.py` | X | — |
| `app8_consolidate` | ? | ? | | `app8_consolidate` | ? | ?(F1-5b 范围外,Wave 2 / F1-6 audit) |
### 10.3 小程序页面 ### 10.3 小程序页面
> **F1-5b 收益**(2026-05-05 D2):`?` 项经全面 audit 核实(详见 sandbox-replay-engine-spec.md)。
> 走查覆盖范围:`pages/board-* / customer-* / coach-* / performance* / task-list`(共 11 个含月度数据的页面)。
| 页面 | 引入 `runtime-clock` | 备注 | | 页面 | 引入 `runtime-clock` | 备注 |
|---|---|---| |---|---|---|
| `performance/performance.ts` | X | G2 月度判断 | | `performance/performance.ts` | X | G2 月度判断 |
@@ -418,12 +431,13 @@ ETL `task_engine` 与 `flow_runner` 并不直接读 `biz.site_runtime_context`
| `task-list/task-list.ts` | X | 月度判断 | | `task-list/task-list.ts` | X | 月度判断 |
| `customer-records/customer-records.ts` | X | onLoad | | `customer-records/customer-records.ts` | X | onLoad |
| `customer-service-records/customer-service-records.ts` | X | onLoad | | `customer-service-records/customer-service-records.ts` | X | onLoad |
| `board-finance/board-finance.ts` | ? | 设计文档要求改 `isCurrentMonthFilter`,未在 grep 结果中确认 | | `coach-service-records/coach-service-records.ts` | X | F1-5b MP-5 onLoad + loadData + switchMonth 4 处 new Date() 替换 |
| `board-customer/board-customer.ts` | ? | 未确认 | | `board-finance/board-finance.ts` | —(后端走 board_service) | F1-5b MP-1 复核 PASS:actualIncome=66000 现金口径正确,前端无需 runtime-clock |
| `board-coach/board-coach.ts` | ? | 未确认 | | `board-customer/board-customer.ts` | —(后端走 board_service) | F1-5b A1/A3 间接覆盖,前端无需 runtime-clock |
| `customer-detail/customer-detail.ts` | — | 操作时间戳保留真实时钟(设计共识) | | `board-coach/board-coach.ts` | —(后端走 board_service) | F1-5b MP-2 推迟 F1-6,前端无需 runtime-clock |
| `customer-detail/customer-detail.ts` | —(F1-5b MP-3 后端 _build_coach_tasks 上界 + MP-4 id guard) | 操作时间戳保留真实时钟(设计共识) |
| `chat/chat.ts` | — | 同上 | | `chat/chat.ts` | — | 同上 |
| `utils/time.ts` | — | 显示文案保留真实时钟设计共识 | | `utils/time.ts` | — | 显示文案,保留真实时钟(设计共识) |
### 10.4 ETL 视图 ### 10.4 ETL 视图
@@ -441,14 +455,60 @@ ETL `task_engine` 与 `flow_runner` 并不直接读 `biz.site_runtime_context`
- AIDashboard / AIRunLogs 列表按真实写入时间排序 - AIDashboard / AIRunLogs 列表按真实写入时间排序
- 小程序 `chat / customer-detail / utils/time.ts` 操作时间戳保留 `new Date()` - 小程序 `chat / customer-detail / utils/time.ts` 操作时间戳保留 `new Date()`
- DIM SCD2 维度(`v_dim_*`)保留 `scd2_is_current=1` 当前快照 - DIM SCD2 维度(`v_dim_*`)保留 `scd2_is_current=1` 当前快照
- **`zqyy_app` 库永不建 RLS 视图层**F1-5b D2 决策 / 2026-05-05 A4
- `zqyy_app.app` schema 实为 FDW 外表(映射 `etl_feiqiu.app.v_*`),非真实视图
- 业务读写 `biz.*` 走**应用层 A 方案**(后端 SQL 显式带 `WHERE site_id=?` + `RuntimeContext.business_date` 上界)
- 若新建 `zqyy_app.app` RLS 视图,会形成"应用层守护 + 视图层守护"两套保护,违反**单一权威源**原则
- GUC 注入路径(F1-5b A3):仅在 `etl_feiqiu` 入口(`fdw_queries._fdw_context`)做,zqyy_app 直连不注入
- **batch_id 命名规约**(F1-5b A5 / 2026-05-05):
- **生成方式**:`uuid.uuid4().hex`(32 字符小写 hex,无连字符)
- **生命周期**:`AdminAIService._batch_store` 内存字典,TTL 10 分钟(estimate→confirm 间隔上限)
- **用途**:
1. estimate 阶段返回给前端,confirm 时回传校验
2. 标注 `ai_run_logs.triggered_by = f"batch:{batch_id}"` (Wave 2 进度查询基础)
3. 隔离 ctx_snapshot:批量执行内全程使用 estimate 时锁定的 RuntimeContext,避免中途切换 sandbox 导致漂移
- **不持久化到 DB**:仅内存存储,后端重启丢失;前端必须在 10 分钟内完成 confirm
- **与 sandbox_instance_id 区别**:
- `batch_id`:批量执行的"会话 ID",生命周期跨 estimate→confirm
- `sandbox_instance_id`:沙箱"实例 ID"(`sbx_<uuid8>`),生命周期跨 sandbox 切换 live 之前
- 一个 batch 可以在 sandbox 模式下执行,此时 ctx_snapshot 保留 `sandbox_instance_id`,batch_id 与之独立
### 11.2 已知 hack ### 11.2 已知 hack
- `coach_service._build_task_groups` 是否带 `site_id` + runtime filter 未在审计中明确验证 - `coach_service._build_task_groups` 是否带 `site_id` + runtime filter 未在审计中明确验证
- `task_generator` 部分 SQL 是否有业务日上界仅文档提及,未单测覆盖 - `task_generator` 部分 SQL 是否有业务日上界仅文档提及,未单测覆盖(F1-5b T3 已 mock 覆盖 dispatcher 间接传递,直接 generator 未单测)
- `page_context.py` 7 处直连 ETL 查询依赖 GUCC 方案)兜底,未单独传 `ref_date` - `page_context.py` 7 处直连 ETL 查询依赖 GUCC 方案)兜底,未单独传 `ref_date`
### 11.3 完整待办指向 ### 11.3 F1-5b 已收口的遗留 hack2026-05-05 D3
-`customer_service._build_coach_tasks` 第一条 SQL 加业务日上界(MP-3 commit 96dae0c)
-`ai/admin_service.py` 4 处 CURRENT_DATE → business_date(F1-5b A1 commit af02446)
-`fdw_queries._fdw_context` 异常分支兜底(F1-5b A2)
-`apply_runtime_session_vars` 在所有 ETL 查询入口统一注入(F1-5b A3)
-`auth.role_permissions` manager 角色移除 view_tasks(BE-1 commit 18fbb2f)
- ✓ ai_run_logs / coach_tasks / ai_trigger_jobs 写入带 runtime 字段(BE-3 / T3 unit 测试覆盖)
- ✓ admin-web AIDashboard / AIRunLogs / AITriggerJobs runtime 全套透出(UI-1/2/3/4/5)
- ✓ 小程序 coach-service-records 业务时钟接入(MP-5)+ coach-detail id guard(MP-4)
- ✓ ETL 连接显式 client_encoding=UTF8 防御 GBK 异常(A6)
- ✓ Excel 修正 3 表加 effective_date schema 准备(MP-2 prep)
### 11.4 推迟到 F1-6 沙箱时光机阶段 B 的待办
详见 **`docs/_overview/sandbox-replay-engine-spec.md`**(F1-5b D3 / 2026-05-05):
-**MP-2 完整实施**:board-coach 月度面板 daily salary 累计(需新建 `dws_assistant_daily_salary` 表 + ETL 改造)
-**ETL Excel 上传 UI 改造**:tenant-admin/ExcelUpload 模块支持 effective_date 列解析 + 模板分发
-**14 个 P1 指标 service 切换**:会员余额 / 60d 消费 / 累计 GMV / 月度新增/流失会员等
-**5 个 P2 指标重算**:RS 关系指数 / 客户黏性 / 任务完成率 / Excel 修正按 effective_date
### 11.5 推迟到 F1-7+ 沙箱时光机阶段 C 的远期目标
- ⏳ 3 个 P3 指标(门店等级评级 / 助教星级 / 累计 KPI 状态算法)
-`biz.sandbox_audit_log` 用户行为审计表(沙箱演练复盘场景)
- ⏳ AI app8_consolidate prompt 业务日接入审计
### 11.6 完整待办指向
跨模块完整收口、深入测试用例、Wave 1 走查必测场景、清理脚本设计 → **`docs/_overview/04a-feedback/P0-7-runtime-context-todos.md`**。 跨模块完整收口、深入测试用例、Wave 1 走查必测场景、清理脚本设计 → **`docs/_overview/04a-feedback/P0-7-runtime-context-todos.md`**。
@@ -466,11 +526,15 @@ ETL `task_engine` 与 `flow_runner` 并不直接读 `biz.site_runtime_context`
- [x] T8`tools/db/verify_sandbox_end_to_end.py` 31/31 PASStest 库 site=2790685415443269 / sandbox=2025-09-01 - [x] T8`tools/db/verify_sandbox_end_to_end.py` 31/31 PASStest 库 site=2790685415443269 / sandbox=2025-09-01
- [x] T9admin-web Playwright e2e 13/13 PASS - [x] T9admin-web Playwright e2e 13/13 PASS
- [x] T10BD_Manual + 6 份 changes 审计 - [x] T10BD_Manual + 6 份 changes 审计
- [ ] T11生产库 `zqyy_app` + `etl_feiqiu` 迁移执行 - [x] **T11(F1-5b)**:F1-5a 沙箱 batch-run + 走查 bug fix(2026-05-05 commit 421e193 / 1baa212 / a045625 / 95a4500)
- [ ] T12跨模块完整测试 / Wave 1 走查(详见 todos - [x] **T12(F1-5b Wave A)**:架构主体收口 — A1/A2/A3/T1/T2/Hook + admin-web UI-1/2/4 + 小程序 MP-3/5 + MP-1/BE-1(commit af02446 → 87a5e3b)
- [ ] T13sandbox 数据定期清理脚本(按 `sandbox_instance_id` 限定) - [x] **T13(F1-5b Wave B)**:UI-3/5 sandbox 透出 + MP-4 id guard + BE-3/T3 测试回归 + A6 ETL 编码 + MP-2 prep + 沙箱时光机 spec(commit c433757 → 1e803e2)
- [ ] T14多门店并行 sandbox 验证脚本 - [ ] T14生产库 `zqyy_app` + `etl_feiqiu` 迁移执行(原 T11)
- [ ] T15admin-web 沙箱实例数据浏览页(可选,便于运维查看 `sbx_*` 写入了什么) - [ ] T15sandbox 数据定期清理脚本(按 `sandbox_instance_id` 限定)
- [ ] T16多门店并行 sandbox 验证脚本
- [ ] T17admin-web 沙箱实例数据浏览页(可选,便于运维查看 `sbx_*` 写入了什么)
- [ ] **T18(F1-6)**:沙箱时光机阶段 B — 14 个 P1 + 5 个 P2 指标(详见 `docs/_overview/sandbox-replay-engine-spec.md`)
- [ ] **T19(F1-7+)**:沙箱时光机阶段 C — 3 个 P3 指标 + sandbox_audit_log 用户行为审计
--- ---
@@ -574,4 +638,34 @@ ETL `task_engine` 与 `flow_runner` 并不直接读 `biz.site_runtime_context`
| 2026-05-02 | C 方案GUC + 39 视图)+ 小程序接入 + Playwright e2e + 端到端验证 | Cursor + Neo | | 2026-05-02 | C 方案GUC + 39 视图)+ 小程序接入 + Playwright e2e + 端到端验证 | Cursor + Neo |
| 2026-05-04 | 本 SPEC 草案产出(追溯型) | ClaudeNeo 反馈触发) | | 2026-05-04 | 本 SPEC 草案产出(追溯型) | ClaudeNeo 反馈触发) |
| 2026-05-04 | §14 成果层走查 patch 落入Neo P0-7 反馈,选项 A | Claude | | 2026-05-04 | §14 成果层走查 patch 落入Neo P0-7 反馈,选项 A | Claude |
| 2026-05-05 | F1-5a 沙箱 batch-run + 走查 bug fix(commit 421e193 / 1baa212 / a045625 / 95a4500) | Claude(Neo 复审) |
| 2026-05-05 | **F1-5b Wave A**:架构主体收口 — A1/A2/A3/T1/T2/Hook + admin-web UI-1/2/4 + 小程序 MP-3/5 + MP-1 复核 + BE-1 权限修正(commit af02446 → 87a5e3b) | Claude(Neo 复审) |
| 2026-05-05 | **F1-5b Wave B**:UI-3/5 sandbox 透出 + MP-4 id guard + BE-3/T3 测试回归 + A6 ETL 编码防御 + MP-2 prep(3 stg 表加 effective_date)+ A4/A5 SPEC 登记 + D1-D4 SPEC 同步(commit c433757 → 1e803e2 + 本次 D1-D4 文档) | Claude(Neo 复审) |
| 2026-05-05 | **沙箱时光机模块 spec 产出**(`docs/_overview/sandbox-replay-engine-spec.md`):MP-2 完整实施 + 14 个 P1 + 5 个 P2 指标推迟到 F1-6 阶段 B,3 个 P3 + sandbox_audit_log 推迟到 F1-7+ 阶段 C | Claude(Neo 决策方向 1) |
| 待定 | F1-6 沙箱时光机阶段 B 启动 | Neo + Claude |
| 待定 | 生产库执行 + 跨模块走查 | Neo + 运维 | | 待定 | 生产库执行 + 跨模块走查 | Neo + 运维 |
### 15.1 F1-5b 收益总结
**已落地能力**(11 个 commit):
1. **后端架构主体收口**:RuntimeContext 在所有 ETL 入口统一注入,admin_service 4 处 CURRENT_DATE → business_date,fdw_queries 异常分支三层兜底
2. **测试回归网**:T1 RuntimeContext API 36 case + T2 batch ctx_snapshot 5 case + BE-3 ai_run_logs 写入 5 case + T3 dispatcher 路径 5 case = **51 case 本地全 PASS**(走 .gitignore:71 不入仓)
3. **admin-web sandbox 全栈透出**:UI-1 列表 runtime 列 + UI-2 详情 Drawer + UI-3 Dashboard 提示 + UI-4 全局徽章 + UI-5 触发任务列表 runtime 列
4. **小程序业务日纵深裁剪**:MP-3 customer-detail lastService 上界 + MP-5 coach-service-records 业务时钟 + MP-4 coach-detail id guard
5. **权限矩阵正确性**:BE-1 manager 角色移除 view_tasks(产品设计修正,DB seed 迁移)
6. **基础设施防御**:A6 ETL 连接显式 client_encoding=UTF8 防 GBK 异常 + post_edit_business_date_check.py PreToolUse hook 防 PR 引回 CURRENT_DATE
7. **沙箱时光机前置**:MP-2 prep 3 stg 表加 effective_date NOT NULL 强约束(zqyy_app 三个 Excel 暂存表)+ 完整模块 spec 产出
**业务价值**:
- 沙箱模式下,小程序所有"daily 累计型"指标(财务流水 / 服务记录 / 客户消费 / 任务列表)严格按 business_date 上界
- admin-web 操作员可一眼看出当前 site sandbox 状态(全局徽章 + Dashboard 提示 + 列表 / 详情 runtime 字段)
- 已知遗留(monthly salary / Excel 修正 daily 截断 / 用户行为审计)有完整 spec + 排期(F1-6/F1-7+)
**未落地能力**(已登记 §11.4 / §11.5):
- MP-2 完整实施(monthly daily salary 累计)→ F1-6
- ETL Excel 上传 UI 改造 → F1-6
- 14 个 P1 指标 service 切换 → F1-6
- sandbox_audit_log 用户行为审计 → F1-7+
详情见 [`sandbox-replay-engine-spec.md`](../../_overview/sandbox-replay-engine-spec.md)。