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