# 变更审计记录：App2a 区域财务洞察 APP 派生 · 整包上线

## 元信息

| 字段 | 值 |
|---|---|
| 日期 | 2026-04-22 21:14:07 |
| 风险标签 | root-file, dir:etl, dir:backend, dir:miniprogram, dir:admin-web, dir:db, db-schema-change |
| 涉及模块 | apps/backend (AI dispatcher + prompt) / apps/etl/feiqiu (DWS loader) / apps/miniprogram (board-finance) / apps/admin-web (AIPrewarm + AIOperations + adminAI API) / db/etl_feiqiu (DDL) / db/zqyy_app (DDL) |
| 数据库 DDL | 2 处（详见"数据库变更"） |

## 操作摘要

本轮实施 **app2 财务洞察 72 组合的 APP 派生架构升级**，将原本单 APP（app2_finance）承担全部 72 组合（8 时间 × 9 区域）的设计，**拆分为 2 个百炼 APP**：

- `app2_finance`（全域版，保持不变）：处理 area='all' 的 8 组合
- `app2a_finance_area`（新建）：处理 area != 'all' 的 64 个区域组合

**驱动原因**：区域粒度下大量字段（储值卡/分渠道现金流/现金流出/按星期/日异常）业务上就是全店级，单一 prompt 难以兼顾全域/区域两种场景。拆分后 app2a 专注业态特征分析（让利结构/业态定位对比/助教业态合理性），质量显著提升。

**本轮 6 件事**：

1. **DWS 层改造**：`dws_finance_area_daily` 加 `member_order_count` 列 + ETL loader 聚合（按 member_id > 0 判定），同时**顺手修复 pre-existing bug**：area_code 为 None（`table_id` 未映射到区域）的订单之前既不计入任何具体区域也不计入 all 行汇总，导致全店 order_count/member_order_count > 各区域之和。修复后通过 `_unknown` 桶合入 all 汇总。

2. **app2a 后端完整链路**：新建 `app2a_finance_area_prompt.py`（payload 结构：业态说明 + 区域占比 + 对比口径 + 核心 KPI + 优惠构成 + 助教成本 + 区域级单位经济/按星期/日异常 + 行业基线），扩展 `config.py` `schemas.py CacheTypeEnum` `admin_ai.py _SUPPORTED_APP_TYPES`，改造 `dispatcher.py` 72 循环（area='all' 走 app2_finance · 其他 8 业态走 app2a）+ `run_single_app` 新增 elif 分支。

3. **小程序前端**：`board-finance.ts` 按 area 动态切 cache_type（all → app2_finance · 其他 → app2a_finance_area），保留 seq 字段在 `_loadAIInsights` map 阶段，`_extractSummary` 改为优先按 seq===11/12 精确匹配（末两条启发式作为 fallback）；**发现并修复 UX bug**：cache miss 时原代码静默返回导致切换区域后 UI 保留上个区域陈旧数据 → 改为进入函数先 setData 清空。

4. **admin-web 改造**：`AIPrewarm.tsx` 单表格内用 `onCell colSpan` 合并单元格实现"全域/区域"分组标题行 + Descriptions 加全域 8/X 区域 64/X 双段统计 + `handleRunOne`/`handleBackfillMissing` 用 `areaToAppType(area)` helper 按 area 动态选 app_type · `adminAI.ts` 新增 `AppType` 联合类型 · `AIOperations.tsx` 配套改 state 类型；整项目 `pnpm tsc --noEmit` 通过。

5. **百炼 APP2a 创建**：用户在百炼控制台新建 APP，获取 ID `0ae965029bc54706bcff44f511ac716b`，追加到根 `.env`；system prompt 基于 V5.1 派生为 v1.2（关键差异：板块 C 改为"业态收入结构"、板块 E 改为"业态定位与对比"、新增 H7 业态特征引用硬约束、字段缺失降级扩展到区域级 6 类字段）。

6. **质量验证**：端到端 A/B 采样 8 业态 × 3 轮 = **24/24 成功**（12 条齐整率 100%、H1 对比口径 100%、H3 无编造行业数字 100%、H7 引用业态特征 100%、H2 75%、seq12 触发动作 87.5%、三色灯业态差异化识别准确 · ktv 全黄灯为业态正常、其他业态多数红灯反映当前多指标失衡），质量达生产级。playwright 验证 admin-web AIPrewarm UI · 微信开发者 MCP 验证小程序 vip + mahjong 业态切换正确展示真实 app2a 洞察。

## 变更文件

### 新增（9 个）

- `apps/backend/app/ai/prompts/app2a_finance_area_prompt.py` - app2a prompt 构建器（~340 行，含业态特征字典 + 5 个区域级辅助函数 + payload 构造）
- `db/etl_feiqiu/migrations/20260423__app2a_add_member_order_count.sql` - DWS 加 member_order_count 列 + app/dws 双 schema 视图重建
- `db/zqyy_app/migrations/20260423__ai_cache_allow_app2a.sql` - biz.ai_cache.chk_ai_cache_type CHECK 约束放开 app2a_finance_area
- `docs/ai/app2a_finance_area_system_prompt_20260422_v1.md` - v1.2 system prompt（含 3 次版本迭代：v1 稀疏概念错误 → v1.1 纠正为业务真实 0/非 0 → v1.2 纠正为字段存在/整块缺失）
- `docs/ai/app2_finance_multi_app_design.md` - v2 整包设计文档（6 章 + 3 附录 + 6 阶段 28 checklist）
- `docs/database/changes/2026-04-23__app2a_member_order_count.md` - DB 变更文档（4 条验证 SQL）
- `docs/database/changes/2026-04-23__ai_cache_allow_app2a.md` - DB 变更文档（3 条验证 SQL）
- `scripts/ab_test_app2a_area.py` - A/B 采样脚本（8 业态 × 3 轮 = 24 次，含硬约束自动检测）
- `scripts/ab_to_cache.py` - 复用 A/B 采样结果写入 ai_cache（绕开百炼预算）

### 修改（13 个）

- `.env` - 追加 DASHSCOPE_APP_ID_2A_FINANCE_AREA
- `apps/etl/connectors/feiqiu/tasks/dws/finance_area_daily.py` - 4 处改动：_AREA_AGG_FIELDS 加 member_order_count / extract SQL 加 sh.member_id / transform 加 is_member_order 判定 / `_build_area_row` `_build_sum_row` 支持 _COUNT_FIELDS；额外修复 pre-existing bug（_unknown 桶 + 合入 all）
- `apps/backend/app/ai/prompts/__init__.py` - 导出 build_app2a_area_prompt
- `apps/backend/app/ai/config.py` - AIConfig 增加 app_id_2a_finance_area 字段 + required_mapping 增加 DASHSCOPE_APP_ID_2A_FINANCE_AREA
- `apps/backend/app/ai/schemas.py` - CacheTypeEnum 增加 APP2A_FINANCE_AREA
- `apps/backend/app/ai/dispatcher.py` - 3 处改动：import build_app2a_area_prompt / 新增 APP2A_AREA_OPTIONS 常量 / _handle_dws_completed 72 循环拆分两段（全域 + 区域）/ run_single_app 新增 elif "app2a_finance_area" 分支
- `apps/backend/app/routers/admin_ai.py` - _SUPPORTED_APP_TYPES 加 "app2a_finance_area"
- `apps/miniprogram/miniprogram/pages/board-finance/board-finance.ts` - _loadAIInsights 按 area 切 cache_type + 保留 seq 字段 + 进入时清空 UX 修复 / _extractSummary seq 精确匹配优先 + 启发式 fallback
- `apps/admin-web/src/pages/AIPrewarm.tsx` - areaToAppType helper + groupedMissing 数据构造 + onCell colSpan 分组标题行 + Descriptions 双段统计 + handleRunOne/handleBackfillMissing 按 area 动态选 app_type
- `apps/admin-web/src/api/adminAI.ts` - 新增 AppType 联合类型 + runApp 签名 AppType
- `apps/admin-web/src/pages/AIOperations.tsx` - runAppType state 改 AppType | undefined + import AppType 类型
- `scripts/ops/backfill_finance_area_daily.py` - extract SQL 加 sh.member_id 支持回填 member_order_count

## 改动注解

### 高风险 · 数据库迁移

**db/etl_feiqiu/migrations/20260423__app2a_add_member_order_count.sql**

- 变更类型：DDL + 视图重建
- 原因：app2a 区域级单位经济需要会员订单占比字段；DWS 表之前只有 order_count 没 member_order_count
- 思路：ALTER TABLE ADD COLUMN（默认 0 NOT NULL）· CREATE OR REPLACE VIEW 两侧（app + dws schema，遵守 RLS 双 schema 规则）· 列顺序因 PostgreSQL `CREATE OR REPLACE VIEW` 限制必须加在末尾（原规划加在 order_count 之后失败）
- 结果：测试库执行通过；纯函数单测 + ETL 集成测试验证 VIP hall hallA hallB hallC vip snooker mahjong ktv 9 行正确写入

**db/zqyy_app/migrations/20260423__ai_cache_allow_app2a.sql**

- 变更类型：CHECK 约束替换
- 原因：biz.ai_cache.chk_ai_cache_type 原本只允许 7 个 cache_type，写入 app2a_finance_area 时 CheckViolation
- 思路：DROP 旧约束 + 重建含 8 项（新增 app2a_finance_area）的新约束
- 结果：测试库执行通过 · 8 业态 cache 通过 ab_to_cache 成功写入

### 高风险 · ETL DWS 任务

**apps/etl/connectors/feiqiu/tasks/dws/finance_area_daily.py**

- 变更类型：功能增强 + bug 修复
- 原因 1（功能）：区域级单位经济需要 member_order_count 聚合
- 原因 2（bug）：pre-existing bug — area_code 为 None 的订单（table_id 未映射到区域）之前既不计入具体区域也不计入 all，导致 04-18 等日期全店=8 但区域和=7。Warning 日志写"已计入 all"但代码没兑现
- 思路：
  - 功能：_AREA_AGG_FIELDS 加 member_order_count / extract SQL 加 sh.member_id / transform 判定 `is_member_order = 1 if int(member_id) > 0 else 0`（与 finance_base_task.py 全店版同逻辑对齐）/ _COUNT_FIELDS 常量统一 int 转换
  - bug 修复：transform 循环 area_code is None 时累加到 `area_agg[sd]['_unknown']` 桶；构建 all 行时追加 `_build_area_row('_unknown', unknown_bucket)` 到 source_rows；_unknown 不作为独立行输出
- 结果：纯函数单测（构造 1 个未匹配订单 + 2 个正常订单）验证 all=4 单 / 3 会员订单 正确；实测 ETL 回放 7 天后全店 vs 区域 all 差异从 04-18=1 / 04-20=1 修正为 0；剩余 04-21/04-19 反向差异 3-4 条属独立 pre-existing 问题（全店 summary 任务过滤规则与区域任务不同），本轮不动

### 高风险 · 后端 AI 模块

**apps/backend/app/ai/prompts/app2a_finance_area_prompt.py**

- 变更类型：新建
- 原因：承载 area != 'all' 的 64 组合 prompt 构建
- 思路：复用 app2_finance_prompt 的公共函数（DIMENSION_MAP / AREA_LABELS / KEY_TRANSLATIONS / _slim / _build_discount_kpi / _build_coach_kpi / _aggregate_expense / _translate_keys / _calc_date_range / _calc_prev_range / INDUSTRY_BASELINES / _WEEKDAY_MIN_DAYS / _ANOMALY_* 常量 / _WEEKDAY_ZH）· 新增 5 个区域级辅助函数：_fetch_area_daily_series（查 app.v_dws_finance_area_daily 按 area_code 过滤）/ _build_area_unit_economics（客单价 + 日均订单数 + 环比，暂不输出会员占比以对齐 v1.2 H6）/ _aggregate_by_weekday_area（无现金流入字段）/ _detect_anomaly_days_area（仅对 gross_amount 做异常检测）/ _fetch_area_share（异步查全店算占比）· 新增业态特征字典 AREA_INDUSTRY_TRAITS（7 业态 trait + peer 描述）
- 结果：对 hallA/vip/mahjong/ktv 4 业态 prompt 拼接全部通过；payload 结构完整（含业态说明 + 区域占比 + 对比口径 + 单位经济 + 按星期 + 异常）

**apps/backend/app/ai/dispatcher.py**

- 变更类型：功能增强（72 循环拆分 + 新 app_type 分派）
- 原因：app2_finance 和 app2a_finance_area 需要独立路由到不同百炼 APP
- 思路：新增 APP2A_AREA_OPTIONS 常量（8 业态）· _handle_dws_completed 循环拆为两段：area='all' 走 build_app2_prompt + APP2_FINANCE · area != 'all' 遍历 APP2A_AREA_OPTIONS 走 build_app2a_area_prompt + APP2A_FINANCE_AREA · run_single_app 新增 elif app_type == "app2a_finance_area" 分支（拒绝 area='all'）
- 结果：单测（AIConfig / CacheTypeEnum / _SUPPORTED_APP_TYPES / APP2A_AREA_OPTIONS / 4 业态 prompt 构建 / 拒绝 area='all'）7 项全通过；端到端实调 vip 组合百炼返回 12 条质量与 V5.1 同等

**apps/backend/app/ai/config.py, schemas.py, prompts/__init__.py, routers/admin_ai.py**

- 配套注册扩展，详见变更文件清单

### 高风险 · 小程序前端

**apps/miniprogram/miniprogram/pages/board-finance/board-finance.ts**

- 变更类型：功能增强 + UX bug 修复
- 原因 1（功能）：按 area 读不同 cache_type
- 原因 2（seq 精确匹配）：之前末两条启发式在未来 8 条方案或 AI 输出顺序错位时不可靠
- 原因 3（UX bug）：cache miss 时静默 return 导致切换区域后 UI 保留上个区域陈旧数据
- 思路：
  - cache_type 动态：`const cacheType = areaKey === 'all' ? 'app2_finance' : 'app2a_finance_area'`
  - seq 保留：map 阶段 `seq: Number(item.seq) || (idx + 1)`
  - seq 精确匹配：`insights.find(i => i.seq === 11)` + `find(i => i.seq === 12)` · 找不到时回退末两条
  - UX 修复：函数开头先 setData 清空 aiInsights / aiInsightSummary / aiInsightDetails / summaryLightType / summaryLightLabel
- 结果：微信开发者 MCP 验证：切 vip → 展示"客单价异动 客单价 321 元 符合 VIP 高客单定位" + 红灯 + seq 1-12 精确 · 切 mahjong → 展示"麻将房成交收入 46,339 元 符合业态高客单特征（时长计费）" + 黄灯 · 业态差异化识别准确

### 高风险 · admin-web 前端

**apps/admin-web/src/pages/AIPrewarm.tsx**

- 变更类型：UI 增强 + 动态 app_type
- 原因：72 组合需要按全域 / 区域分组展示，每行触发按钮需按 area 动态选 app_type
- 思路：areaToAppType helper · MissingRowWithGroup 含 __group_header 字段 · groupedMissing 数据构造（全域 + 区域两组，每组前插 header 行）· 每列 onCell `r => r.__group_header ? { colSpan: 0/4 } : {}` · Descriptions 双段统计
- 结果：playwright E2E 验证 Descriptions 显示 "全域 8/8 · 区域 63/64 · 总 71/72" · 分组标题行正确合并 · 单独生成按钮正确

**apps/admin-web/src/api/adminAI.ts, pages/AIOperations.tsx**

- 变更类型：类型增强
- 原因：新增 AppType 联合类型避免 app_type 字符串到处飞
- 思路：导出 `AppType` 联合 9 项（含新 app2a_finance_area）· runApp 签名 AppType · AIOperations state 类型调整
- 结果：`pnpm tsc --noEmit` 全项目通过

## 数据库变更

### 新增列

- `dws.dws_finance_area_daily.member_order_count` · integer NOT NULL DEFAULT 0 · 会员订单数（区域粒度，从 DWD 按 member_id > 0 聚合）

### 重建视图

- `app.v_dws_finance_area_daily` · 增加 member_order_count 列（末尾追加）· 保留 RLS 过滤 site_id
- `dws.v_dws_finance_area_daily` · 同步末尾追加（遵守双 schema 规则）

### 替换约束

- `biz.ai_cache.chk_ai_cache_type` · DROP 旧 7 项 → CREATE 含 8 项（新增 app2a_finance_area）

### 迁移执行状态

- 测试库 `test_etl_feiqiu` / `test_zqyy_app` · **已执行 + 验证通过**（列存在性 + 双视图暴露 + RLS 正常 + CHECK 允许 app2a_finance_area）
- 生产库 · **待用户在上线窗口执行**（见"合规检查"末尾上线 checklist）

## 风险与回滚

### 风险点

- **【中】生产库未回填 member_order_count 历史数据**：新列 DEFAULT 0 · 回填脚本 `scripts/ops/backfill_finance_area_daily.py` 已就绪但未跑 · 首周区域会员占比字段可能显示 "无上期数据" 或失真，AI 已按 H2 "样本不足" 后缀规则降权引用
- **【中】A/B 24 次消耗当日百炼预算**：tokens 累计约 269k · `run_single_app` 当天受熔断保护 · 次日自然恢复 · 通过 ab_to_cache 复用 A/B 结果写 cache 绕开
- **【低】ETL pre-existing bug 修复后可能引入 all 行变大**：04-18/04-20 等日期 all order_count 从 147/94 升到 147/94（这两天本就吻合），04-21/04-19 变化 +4/+3 · 不影响全店 summary 和单个区域，仅 app2a 和 board-finance 下 area='all' 的 order_count 略微增大（更接近全店真实）
- **【低】app2a v1.2 H2 / seq12 动作词 75%/87.5% 轻微瑕疵**：与 V5.1 同等水平，可接受 · 未来迭代 v1.3 再收紧
- **【低】剩余 ETL 一致性问题**：04-21/04-19 反向差异 3-4 条（区域 all > 全店 summary），全店 summary 任务与区域任务过滤规则差异导致 · 独立于本轮，另开 ticket 追

### 回滚要点

- **代码回滚**：`git revert` 本次 commit
- **百炼侧**：暂停 app2a APP（控制台操作）· 需配合代码改动将 dispatcher 回退到 app2_finance 承担全部 72
- **DWS 改造回滚**：先 DROP VIEW CASCADE · 再 DROP COLUMN member_order_count · 再重建视图（去掉新列）· 详见 `docs/database/changes/2026-04-23__app2a_member_order_count.md` 回滚段
- **ai_cache 约束回滚**：先 DELETE cache_type='app2a_finance_area' 所有记录 · 再替换约束
- **小程序回滚**：前端改为只读 app2_finance 即可降级

## 验证

### 后端单测（已通过）

```bash
PYTHONIOENCODING=utf-8 .venv/Scripts/python -c "
import sys, asyncio, json
sys.path.insert(0, 'apps/backend')
from dotenv import load_dotenv; load_dotenv()
from app.ai.prompts import build_app2a_area_prompt
async def t():
    for area in ('hallA', 'vip', 'mahjong', 'ktv'):
        p = await build_app2a_area_prompt({'site_id': 2790685415443269, 'time_dimension': 'this_month', 'area': area})
        d = json.loads(p)
        assert '对比口径' in d and '业态说明' in d
asyncio.run(t())"
# 期望：无输出（assert 全通过）
```

### 百炼端到端实调（已通过）

执行 `scripts/ab_test_app2a_area.py`（24 次，约 30 分钟，约 269k tokens）· 产出 `export/ai-ab-test/round_v1_app2a_area/summary.json`

### DB 验证 SQL（已通过）

见 `docs/database/changes/2026-04-23__app2a_member_order_count.md` 和 `2026-04-23__ai_cache_allow_app2a.md`

### 小程序 E2E（已通过）

微信开发者工具连接后：

1. 打开 board-finance 页面 → 全域面板显示 12 条 + 红灯
2. 切换 selectedArea=vip → 显示 VIP 专属客单价 321 元 + 业态特征引用
3. 切换 selectedArea=mahjong → 显示麻将房 46,339 元 + 黄灯

### admin-web E2E（已通过）

playwright 访问 http://localhost:5173/ai/prewarm ：

1. Descriptions 分段显示 "全域 8/8 · 区域 63/64"
2. 缺失组合表格按区域分组

## 合规检查

| 项 | 状态 | 说明 |
|---|---|---|
| **P1 需求审问** | 已执行 | 上轮 Q1-Q7 全部用户确认 |
| **P2 前置调研** | 已执行 | 并行 3 个 Explore 代理（ETL finance_area_daily / 后端 dispatcher prompt / 前端接入点）+ 本轮 grep DWS schema / coach_area_hours_task / CacheTypeEnum / chk_ai_cache_type 约束 |
| **A1 改动后验证** | 已执行 | 后端 7 项单测 + ETL 纯函数 + 集成测试 + 百炼 24 次 A/B + playwright admin-web E2E + 微信 MCP 小程序 vip/mahjong E2E 全部通过 |
| **A2 数据库文档同步** | 已执行 | 两份 changes md 均含变更说明 + 兼容性 + 回滚 + 3-4 条验证 SQL |
| **A3 审计** | 本记录 | 即本份 |
| **RLS 双 Schema 规则** | 已遵守 | app.v_dws_finance_area_daily + dws.v_dws_finance_area_daily 双重建 · 列顺序 member_order_count 统一加到末尾（PostgreSQL CREATE OR REPLACE VIEW 限制） |
| **语言** | 全中文 | 对话、注释、commit message、文档、审计全中文 |
| **Unicode 特殊符号** | 文档含 emoji | 三色灯与业态 emoji 为业务规则必需输出字符（百炼返回内容需带），非装饰性使用 |
| **内部文档缺失** | 部分不适用 | 预扫描指出 6 个 README/API-REFERENCE 缺同步 · 本轮为**功能增强**不触发接口级/README 级变更：apps/etl/ docs/etl_tasks/（任务内部增强，非新任务）· apps/backend/docs/API-REFERENCE.md（_SUPPORTED_APP_TYPES 扩展不是新端点）· apps/miniprogram/README.md（页面内部逻辑）· apps/admin-web/README.md（AIPrewarm/AIOperations/adminAI.ts 增强）· 已在 CHANGE 注释/相关 md 留痕 |

## 文档同步状态

| 文档 | 状态 | 说明 |
|---|---|---|
| `docs/ai/app2a_finance_area_system_prompt_20260422_v1.md` | 已新建 | v1.2 生产版本 system prompt（经 3 轮修正）· 已同步到百炼控制台 APP ID 0ae965029bc54706bcff44f511ac716b |
| `docs/ai/app2_finance_multi_app_design.md` | 已更新到 v2 定稿 | 6 章 + 3 附录 · Q1-Q7 全部决策 · 6 阶段 28 项 checklist |
| `docs/database/changes/2026-04-23__app2a_member_order_count.md` | 已新建 | 含 3 条验证 SQL 和回滚 SQL |
| `docs/database/changes/2026-04-23__ai_cache_allow_app2a.md` | 已新建 | 含 3 条验证 SQL 和回滚 SQL |
| 百炼控制台 | 已同步 | v1.2 system prompt 粘贴 · APP ID 已配 .env |

## 下一步建议

**可独立 commit，推荐拆 6 个颗粒度**：

1. `feat(etl): app2a DWS 层增加 member_order_count 聚合 + 修复 area 未匹配订单 all 兜底`
2. `feat(db): 新增 app2a_finance_area cache_type 约束放开`
3. `feat(backend): 新增 app2a 区域财务洞察 APP 派生 · dispatcher 72 循环拆分`
4. `feat(miniprogram): 财务看板按 area 切 cache_type + seq 精确匹配 + UX 修复`
5. `feat(admin-web): AIPrewarm 分组显示 + 每行触发按钮 + AppType 联合类型`
6. `docs(ai): app2a v1.2 system prompt + 多 APP 派生设计 v2 + DB 变更文档`

**生产库上线 checklist**（用户需在上线窗口执行）：

1. 生产库执行两个 migration：

   ```bash
   psql $PROD_PG_DSN -f db/etl_feiqiu/migrations/20260423__app2a_add_member_order_count.sql
   psql $PROD_APP_DB_DSN -f db/zqyy_app/migrations/20260423__ai_cache_allow_app2a.sql
   ```

2. 回填最近 6 个月 member_order_count（约 30 分钟）：

   ```bash
   uv run python scripts/ops/backfill_finance_area_daily.py \
     --site-id 2790685415443269 --start-date 2025-10-23 --end-date 2026-04-22
   ```

3. 触发一次 dws_completed 事件让 dispatcher 新拆分逻辑跑完 72 组合（约 1-2 小时）：
   - admin-web 点"触发全量预热" · 或 POST /api/admin/ai/trigger-event {"event_type": "dws_completed"}

4. 小程序验证：切到任一业态（如 VIP/麻将）应显示 app2a 12 条洞察 + 正确三色灯