Neo-ZQYY/docs/audit/changes/2026-05-04__cumulative_baseline_pending_verification.md

累积基线变更 + 待验证清单（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 优先级逐一展开主题验证 + 收口。