feat: 2026-04-15~05-02 累积变更基线 — AI 重构 + Runtime Context + DWS 修复

涵盖（每条对应已存的审计记录）： - AI 模块拆分：apps/backend/app/ai/apps -> prompts/（8 个 APP + app2a 派生） audit: 2026-04-20__ai-module-complete.md - admin-web AI 管理套件：AIDashboard / AIOperations / AIRunLogs / AITriggers / TriggerManager audit: 2026-04-21__admin-web-ai-management-suite.md - App2 财务洞察 prompt v3 -> v5.1 + 小程序 AI 接入（chat / board-finance） audit: 2026-04-22__app2_prompt_v5_1_and_miniprogram_ai_insight.md - App2 prewarm 全过滤器 + AI 触发器 cron reschedule audit: 2026-04-21__app2-finance-prewarm-all-filters.md migration: 20260420_ai_trigger_jobs_and_app2_prewarm.sql / 20260421_app2_prewarm_cron_reschedule.sql - AppType 联合类型对齐 + adminAiAppTypes.test.ts audit: 2026-04-30__admin_web_ai_app_type_alignment.md - DashScope tokens_used 提取修复 audit: 2026-04-30__backend_dashscope_tokens_used_extraction.md - App3 线索完整详情 prompt audit: 2026-05-01__backend_app3_full_detail_prompt.md - Runtime Context 沙箱（5-1~5-2 主线）： - 后端 schema/service + admin_runtime_context / xcx_runtime_clock 两个 router - admin-web RuntimeContext.tsx + miniprogram runtime-clock.ts - migration: 20260501__runtime_context_sandbox.sql - tools/db/verify_admin_web_sandbox.py + verify_sandbox_end_to_end.py - database/changes: 7 份 sandbox_* 验证报告 - 飞球 DWS 修复：finance_area_daily 区域汇总 + task_engine 调整 + RLS 视图业务日上界（migration 20260502 + scripts/ops/gen_rls_business_date_migration.py）合规： - .gitignore 启用 tmp/ 排除 - 不入仓：apps/etl/connectors/feiqiu/.env（API_TOKEN secret，本地修改保留）待验证清单： - docs/audit/changes/2026-05-04__cumulative_baseline_pending_verification.md 每个主题的功能完整性 / 上线验证几乎都未收口，按优先级 P0~P3 逐一处理
2026-05-04 02:30:19 +08:00
parent 2010034840
commit caf179a5da
130 changed files with 14543 additions and 2717 deletions
--- a/docs/audit/changes/2026-05-04__cumulative_baseline_pending_verification.md
+++ b/docs/audit/changes/2026-05-04__cumulative_baseline_pending_verification.md
@@ -0,0 +1,183 @@
+# 累积基线变更 + 待验证清单（2026-04-15 ~ 2026-05-02）
+
+| 字段 | 值 |
+|------|-----|
+| 日期 | 2026-05-04 |
+| 类型 | 累积基线提交（多主题合流） |
+| 覆盖时间 | 2026-04-15 ~ 2026-05-02 |
+| 文件总数 | 129（不含 `apps/etl/connectors/feiqiu/.env` API_TOKEN secret 与 `tmp/`） |
+| commit 范围 | 单个累积基线 commit（参照 `2a7a5d6 feat: 2026-04-15~04-20 累积变更基线`） |
+
+## 0. 背景
+
+经历 Cursor 时代的多次会话累积，4 月 15 日之后未做完整 push 收尾。本次反向迁回 Claude Code 后做单轨化 + 推送收尾时发现 124 个未提交业务变更，但**已存在 8 个审计记录 + 7 个数据库变更文档**（散落在 `docs/audit/changes/` 和 `docs/database/changes/` 中 untracked）。审计步骤已在前序会话完成，本次仅做**累积基线 commit + 推送**。
+
+**关键原则**：每个主题的"功能完整性 + 上线验证"**几乎都没有收口**，本文档列出待逐一处理的验证清单，作为后续工作起点。
+
+## 1. 已存在的审计记录索引
+
+| 审计记录 | 主题 |
+|---|---|
+| `docs/audit/changes/2026-04-20__ai-module-complete.md` | AI 模块完成（8 个千问 APP） |
+| `docs/audit/changes/2026-04-21__admin-web-ai-management-suite.md` | admin-web AI 管理套件 |
+| `docs/audit/changes/2026-04-21__app2-finance-prewarm-all-filters.md` | App2 财务预热全过滤器 |
+| `docs/audit/changes/2026-04-21__board-finance-ai-insights-verify.png` | board-finance AI 洞察验证截图 |
+| `docs/audit/changes/2026-04-22__app2_prompt_v5_1_and_miniprogram_ai_insight.md` | App2 prompt v5.1 + 小程序 AI 接入 |
+| `docs/audit/changes/2026-04-30__admin_web_ai_app_type_alignment.md` | admin-web AI AppType 联合类型对齐 |
+| `docs/audit/changes/2026-04-30__backend_dashscope_tokens_used_extraction.md` | DashScope tokens_used 提取修复 |
+| `docs/audit/changes/2026-05-01__backend_app3_full_detail_prompt.md` | App3 线索完整详情 prompt |
+
+## 2. 已存在的数据库变更文档
+
+| 数据库变更文档 | 主题 |
+|---|---|
+| `docs/database/changes/2026-05-01__runtime_context_sandbox.md` | Runtime Context 沙箱设计 |
+| `docs/database/changes/2026-05-02__sandbox_admin_web_manual_checklist.md` | 沙箱 admin-web 手工验证清单 |
+| `docs/database/changes/2026-05-02__sandbox_admin_web_playwright_report.md` | 沙箱 admin-web Playwright 报告 |
+| `docs/database/changes/2026-05-02__sandbox_admin_web_verify_report.md` | 沙箱 admin-web 验证报告 |
+| `docs/database/changes/2026-05-02__sandbox_complete_refactor.md` | 沙箱完整重构 |
+| `docs/database/changes/2026-05-02__sandbox_e2e_verify_report.md` | 沙箱 e2e 验证报告 |
+| `docs/database/changes/2026-05-02__sandbox_no_future_data_plan.md` | 沙箱避免未来数据策略 |
+
+## 3. 各主题待验证清单（核心）
+
+> **每个主题都标注实际未完成 / 待验证项。以下为后续逐一处理的工作起点。**
+
+### 3.1 AI 模块重构（8 个千问 APP 拆分）
+
+**变更**：删除旧 `apps/backend/app/ai/apps/app[1-8]_*.py`（9 个），改为 `apps/backend/app/ai/prompts/app[1-8]_*_prompt.py` 模块化。`dispatcher.py` 重构调用链路。
+
+**待验证**：
+
+- [ ] 8 个 APP 在生产环境的实际调用链路完整性（`chat / finance / clue / analysis / tactics / note / customer / consolidate`）
+- [ ] `app2a_finance_area_prompt.py` 区域财务派生 APP 是否独立稳定
+- [ ] `dispatcher.py` 重构后的熔断 / 限流 / 预算追踪行为是否与重构前一致
+- [ ] `cache_service.py` AI 对话缓存是否仍按 `cache_type` 正确分桶
+- [ ] `references.py` 新增的引用聚合层是否被所有 prompt builder 正确使用
+- [ ] `event_bus.py` 新增事件总线在生产中的实际订阅者数量
+- [ ] `ws/ai_events.py` WebSocket 事件推送的浏览器侧消费稳定性
+
+### 3.2 admin-web AI 管理套件 + AppType 对齐
+
+**变更**：6 个 admin-web AI 页面（`AIDashboard / AIOperations / AIRunLogs / AITriggers / RuntimeContext / TriggerManager`）+ `adminAI.ts` API 封装 + `adminAiAppTypes.test.ts` 单元测试。
+
+**待验证**：
+
+- [ ] AITriggers 页面在 admin-web 主菜单的入口路由是否注册
+- [ ] AppType 联合类型（`adminAiAppTypes.test.ts` 验证 8 个 AppType 命名一致性）是否通过 `pnpm test`
+- [ ] AIDashboard 实时 WebSocket 订阅在 admin-web 浏览器端的连通性
+- [ ] AIRunLogs 分页 + 筛选条件在大数据量（>10k 条）下的性能
+- [ ] TriggerManager 触发器编辑 / 启停的端到端流程
+
+### 3.3 App2 财务洞察 prompt v3 → v5.1 演进
+
+**变更**：`app2_finance_prompt.py` 升级到 v5.1；存档 8 份 prompt 版本（`docs/ai/app2_finance_system_prompt_*`）+ A/B 测试脚本（`scripts/ab_test_app2_prompt.py` 等 5 个）。
+
+**待验证**：
+
+- [ ] v5.1 vs v5 vs v4 在真实门店数据上的店长视角评分（参考 `analyze_store_manager_quality.py`）
+- [ ] 12 条产出齐整率 + 三色灯分布稳定性（`ab_test_app2_prompt.py`）
+- [ ] 客单价环比是否从原字段引用、不做推测（`analyze_ab_content_quality.py` 板块 A）
+- [ ] 储值卡余额变化是否引用权威字段（板块 C）
+- [ ] 旺淡倍率 + 同周/期均基线是否在 seq 9-10 中体现（板块 E）
+
+### 3.4 App3 线索完整详情 prompt
+
+**变更**：`app3_clue_prompt.py` 新增完整详情构造逻辑。
+
+**待验证**：
+
+- [ ] 与 App3 dispatcher 调用链路联调
+- [ ] 线索数据 fetcher 字段完整性（`data_fetchers/` 多个文件改动）
+
+### 3.5 Runtime Context 沙箱（5-1 ~ 5-2 主线工作）
+
+**变更**：跨前后端 + 数据库的完整沙箱设计：
+- 后端：`runtime_context.py` schema/service + `admin_runtime_context.py` `xcx_runtime_clock.py` 两个新 router
+- admin-web：`RuntimeContext.tsx` 页面 + `runtimeContext.ts` API
+- 小程序：`runtime-clock.ts` 工具
+- 数据库：`db/zqyy_app/migrations/20260501__runtime_context_sandbox.sql`
+- 验证工具：`tools/db/verify_admin_web_sandbox.py`
+
+**待验证**：
+
+- [ ] 7 份 `docs/database/changes/2026-05-0[12]__sandbox_*.md` 中描述的验证步骤是否全部执行
+- [ ] sandbox 时间漂移在小程序端的实际表现（`runtime-clock.ts` 在多端时区切换下的稳定性）
+- [ ] admin-web RuntimeContext 页面的"未来数据"防护策略（参考 `sandbox_no_future_data_plan.md`）
+- [ ] e2e 测试报告中 Playwright 截图与手工 checklist 的一致性
+- [ ] `xcx_runtime_clock.py` 小程序时间同步 API 在生产灰度环境的实际行为
+
+### 3.6 AI 触发器 + app2 prewarm 数据库
+
+**变更**：
+- `db/zqyy_app/migrations/20260420_ai_trigger_jobs_and_app2_prewarm.sql`
+- `db/zqyy_app/migrations/20260421_app2_prewarm_cron_reschedule.sql`
+- `docs/database/BD_manual_ai_trigger_jobs_register.md`
+- `apps/backend/app/services/trigger_scheduler.py` 调整
+
+**待验证**：
+
+- [ ] cron 重调度后的 prewarm 命中率（`apps/backend/app/services/trigger_scheduler.py`）
+- [ ] AI 触发器 jobs 表的实际数据量
+- [ ] 21 日 cron reschedule 是否影响其他既有触发器
+
+### 3.7 飞球 DWS 修复 + RLS 业务日上界视图
+
+**变更**：
+- `apps/etl/connectors/feiqiu/tasks/dws/finance_area_daily.py` 区域财务汇总
+- `apps/etl/connectors/feiqiu/tasks/dws/task_engine.py` 任务引擎
+- `db/etl_feiqiu/migrations/20260502__rls_views_business_date_upper_bound.sql` RLS 视图加业务日上界
+- `scripts/ops/gen_rls_business_date_migration.py` 视图迁移生成器
+
+**待验证**：
+
+- [ ] RLS 业务日上界视图覆盖的 N 个视图是否全部通过 `pg_get_viewdef` 重建
+- [ ] `finance_area_daily` 在 area 维度的会员分桶是否与 DWS 权威规范一致
+- [ ] task_engine 改动后的幂等性（按 `apps/etl/connectors/feiqiu/CLAUDE.md` DWS 幂等规则）
+
+### 3.8 admin-web 沙箱验证产物
+
+**变更**：3 份 `2026-05-02__sandbox_admin_web_*.md` 报告 + 验证工具 `tools/db/verify_admin_web_sandbox.py`。
+
+**待验证**：
+
+- [ ] verify_admin_web_sandbox.py 在最新数据下重跑结果
+- [ ] manual checklist 的所有项是否在生产环境复现
+
+### 3.9 部署文档
+
+**变更**：
+- `docs/deployment/LAUNCH-CHECKLIST.md` 修改
+- `docs/deployment/SERVER-ACCESS.md` 新增
+
+**待验证**：
+
+- [ ] 实际部署链路与 SERVER-ACCESS 中描述的服务器是否一致（注意：`SERVER-ACCESS.md` 可能含敏感连接信息，入仓前应复扫）
+
+## 4. 后续处理优先级建议
+
+| 优先级 | 主题 | 原因 |
+|---|---|---|
+| P0 | 3.1 AI 模块重构验证 | 8 APP 是核心业务，重构面广 |
+| P0 | 3.5 Runtime Context 沙箱 | 跨前后端 + DB，5-1~5-2 主线工作未收口 |
+| P1 | 3.7 飞球 DWS + RLS 业务日上界 | 数据正确性，影响所有下游 |
+| P1 | 3.6 AI 触发器 prewarm | cron 改动需观察是否漏触发 |
+| P2 | 3.3 App2 prompt v5.1 | A/B 测试脚本已就绪，需要跑评分 |
+| P2 | 3.2 admin-web AI 管理套件 | 工具页面，问题影响面有限 |
+| P3 | 3.4 / 3.8 / 3.9 | 较为独立的小主题 |
+
+## 5. 不入仓项
+
+- `apps/etl/connectors/feiqiu/.env`：飞球上游 SaaS API_TOKEN（modified 但保留为本地修改）
+- `tmp/`：临时分析产物（已加入 `.gitignore`）
+
+## 6. 操作记录
+
+```
+git add -A
+git restore --staged apps/etl/connectors/feiqiu/.env  # 排除 secret
+git commit -m "feat: 2026-04-15~05-02 累积变更基线 — AI 重构 + Runtime Context + DWS 修复"
+git push origin dev
+```
+
+后续按 §4 优先级逐一展开主题验证 + 收口。