Neo-ZQYY/docs/ai/app2_finance_multi_app_design.md

# App2 财务洞察 72 组合 · 多 APP 派生与 Prompt 拼接方案设计 **v2**（决策已定 · 实施中）

> 文档状态：**v2 定稿 · 实施中**（2026-04-22 用户已确认全部 7 个决策点 · 已进入整包实施阶段）
> 前置版本：v1 草案（2026-04-22 初稿）
> 作者：Claude + Neo
> 适用范围：`apps/backend/app/ai/prompts/` · `apps/backend/app/ai/dispatcher.py` · `apps/etl/connectors/feiqiu/loaders/` · `db/etl_feiqiu/migrations/` · 小程序 `board-finance` · admin-web 3 页 · 百炼控制台新建 APP
> 前置背景：**this_month / all 组合**已通过 V5.1 system prompt 达到生产级（综合分 92.3）；本次针对**其他 64 个区域组合**（8 时间 × 8 业态）派生新 APP `app2a_finance_area`。

---

## 〇 · TL;DR（整包实施总览）

| 维度 | 定案 |
|------|------|
| Prompt 拼接方案 | **2 套**（全域全量 `app2_finance` 不动 · 区域派生 `app2a_finance_area` 新建） |
| 百炼 APP 数量 | **2 个**（新建 `app2a_finance_area`，env: `DASHSCOPE_APP_ID_2A_FINANCE_AREA`） |
| System Prompt | `app2a` v1 [已产出](app2a_finance_area_system_prompt_20260422_v1.md) · 基于 V5.1 派生 · 12 条 · 板块 C/E 重分工 · 新增 H7 业态特征硬约束 |
| DWS 改造 | **必做** · `dws_finance_area_daily` 加 `member_order_count` 列 + ETL loader 改造 + RLS 视图更新（会员订单占比覆盖） |
| 前端 seq 精确匹配 | **必做** · 保留 `seq` 字段，按 `find(i => i.seq === 11)` 定位，降级保留"末两条"启发式 |
| 灰度开关 | **不加**（用户指示作为正式模块上线） |
| admin-web 改动 | **一起做** · AIPrewarm 分两段 + AIDashboard/AIOperations app_type 选择器扩展 |
| DB DDL 改动 | **1 处** · `db/etl_feiqiu/migrations/YYYYMMDD__app2a_member_order_count.sql` |

---

## 一 · 用户确认的决策点（Q1-Q7）

| 问题 | 决策 |
|---|---|
| Q1 · app2a system prompt 条数 | **方案 α · 12 条板块重分工**（前端 seq 11/12 兼容） |
| Q2 · 板块 C/E 替代方向 | **同意** · C = 业态收入结构 / E = 业态定位与对比 |
| Q3 · DWS 改造 | **做** · 区域级单位经济 + 按星期聚合纳入 payload |
| Q4 · seq 精确匹配时机 | **现在做** · 与 app2a 一起上 |
| Q5 · 灰度开关 | **不加** · 作为正式模块上线，要通过测试验收 |
| Q6 · 百炼建 APP 节奏 | 用户拿 [v1 system prompt](app2a_finance_area_system_prompt_20260422_v1.md) 去百炼建 APP → 拿到 APP ID → 写 `.env` → Claude 实施后端 |
| Q7 · admin-web 改动 | **一起做** · 整包交付 |

---

## 二 · 区域粒度字段处理三档（用户已认同）

### 档 1 · 业务本质为"全店级"，区域下**无需补齐**（维持现状隐藏）

| 字段 | 业务理由 |
|---|---|
| 预收资产 / 储值卡余额变化 | 储值卡是会员账户级资产，与消费区域无关 |
| 现金流入来源（纸币/线上/团购 分渠道） | 支付渠道是收银台级属性，区域级无法自然拆分 |
| 现金流出 4 类 | 全店级成本（房租/水电/平台手续费），无法按区域归属 |

### 档 2 · 区域下有业务价值且**技术上可补齐**（本期做）

| 字段 | 实施方式 |
|---|---|
| 单位经济 · 客单价（按成交收入 / 按发生额） | 用 `app.v_dws_finance_area_daily` 现有字段 `gross_amount / confirmed_income / order_count` 可直接算 |
| 单位经济 · 日均订单数 | 用 `order_count` 聚合 |
| 单位经济 · **会员订单占比** | 需新增 `member_order_count` 列 + ETL loader 改造（**本次 DDL**） |
| 按星期聚合（区域级 7 天日均） | 用 `gross_amount / order_count` 聚合（不含 `cash_inflow_total`，区域级不适用） |
| 日粒度异常（同周基线 / 区域级） | 用 `gross_amount` 做异常检测（不含现金流入） |

### 档 3 · 助教分析（区域下"**字段存在 vs 字段整块缺失**"两态，非"稀疏"也非"值 = 0"）

- **数据链路真相**：ODS 助教服务日志每条带 `table_id / room_id` → DWD 层按物理位置→区域映射 → DWS `dws_coach_area_hours` 按 `(assistant_id, area_code, stat_month)` 精确分桶聚合
- **ETL 写入逻辑**（见 [coach_area_hours_task.py:L134](../../apps/etl/connectors/feiqiu/tasks/dws/coach_area_hours_task.py#L134)）：**只在发生过服务时才 INSERT 记录**。没有服务 = 没有聚合键 = 不写入
- **查询结果只有两种状态**：
  - **查到记录且 effective_hours > 0** = 业务真实：本期该区域发生了 N 小时助教服务、M 元薪酬
  - **查不到记录（空集）** = 业务真实：本期该区域**零助教服务发生**（不是数据问题，不是"稀疏"）
- **不存在"单条记录值 = 0"**（除非边角极端：全部服务被标废单 · 概率极低）
- **UI 处置**：
  - 后端返回助教字段 → 正常展示助教板块
  - 后端不返回助教字段（空集） → 不展示助教板块 **或** 展示中性提示"本期本区域无助教服务"（**不**用"数据稀疏"字眼）
- **AI 处置（v1.2 system prompt 板块 D 已改）**：按助教字段"存在 vs 整块缺失" + 业态合理性区分
  - **麻将/KTV 业态缺失**：业态正常，简述一笔带过，不作为隐患
  - **大厅/VIP/斯诺克 业态缺失**：业态异常，提示店长核查（排班未录入/停招/ETL 流水完整性），作为 seq 11 健康度"数据/运营完整性"维度扣分

---

## 三 · DWS 改造详细设计

### 3.1 DDL 改动（1 处）

**文件**：`db/etl_feiqiu/migrations/20260423__app2a_member_order_count.sql`（即将产出）

**内容**：
```sql
BEGIN;

-- 1. 给区域级 DWS 表加 member_order_count 列
ALTER TABLE dws.dws_finance_area_daily
  ADD COLUMN IF NOT EXISTS member_order_count integer DEFAULT 0 NOT NULL;

COMMENT ON COLUMN dws.dws_finance_area_daily.member_order_count IS '会员订单数（区域粒度，DWD 聚合）';

-- 2. 重建 RLS 视图（app schema）
CREATE OR REPLACE VIEW app.v_dws_finance_area_daily AS
SELECT id, site_id, tenant_id, stat_date, area_code,
       table_fee_amount, goods_amount, assistant_pd_amount, assistant_cx_amount,
       gross_amount,
       discount_groupbuy, discount_vip, discount_manual, discount_gift_card,
       discount_rounding, discount_other, discount_total,
       confirmed_income,
       cash_pay_amount, cash_paper_amount, scan_pay_amount, groupbuy_pay_amount,
       recharge_cash_inflow, cash_inflow_total, cash_outflow_total, cash_balance_change,
       card_consume_total, recharge_card_consume, gift_card_consume,
       recharge_cash, first_recharge_cash, renewal_cash,
       order_count,
       member_order_count,  -- 新增
       created_at, updated_at
  FROM dws.dws_finance_area_daily
 WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint);

-- 3. dws schema 视图同步（如存在）
-- 按 CLAUDE.md "RLS 视图双 Schema 规则"，若 dws.v_dws_finance_area_daily 存在需同步创建

COMMIT;
```

### 3.2 ETL loader 改造（飞球 Connector）

**文件**：`apps/etl/connectors/feiqiu/loaders/dws_finance_area_daily.py`（或对应文件，需确认）

**改动**：聚合 DWD 层订单数据时，按 `area_code + stat_date + is_member_order` 分组，将 `is_member_order = true` 的订单数合并到 `member_order_count` 列。

**验证 SQL**：
```sql
-- 全店总数应等于区域总和
SELECT s.site_id, s.stat_date, s.member_order_count AS full_store,
       COALESCE(SUM(a.member_order_count), 0) AS sum_areas
  FROM dws.dws_finance_daily_summary s
  LEFT JOIN dws.dws_finance_area_daily a
    ON s.site_id = a.site_id AND s.stat_date = a.stat_date
 WHERE s.stat_date >= current_date - interval '7 days'
 GROUP BY s.site_id, s.stat_date, s.member_order_count
HAVING s.member_order_count <> COALESCE(SUM(a.member_order_count), 0);
-- 期望：0 行
```

### 3.3 回填策略

- 新列 `DEFAULT 0` → 历史数据 `member_order_count = 0`（区域历史会员占比暂全为 0）
- 用户可选择：① 接受新数据生效即可（P2 上线后生成的数据正确）；② 写回填脚本 `scripts/ops/backfill_area_member_order.py` 从 DWD 重算历史（工作量 1 天）
- **建议当期不回填**，待运行 7 天观察新数据正确后再视需要回填

---

## 四 · 后端实施清单

### 4.1 新建 `app2a_finance_area_prompt.py`

**文件**：`apps/backend/app/ai/prompts/app2a_finance_area_prompt.py`

**关键设计**：
- 复用 `app2_finance_prompt.py` 的：`DIMENSION_MAP / AREA_LABELS / KEY_TRANSLATIONS / _slim / _pct / _build_discount_kpi / _build_coach_kpi / _translate_keys / _calc_date_range / _calc_prev_range`
- **新增** `_fetch_area_daily_series(site_id, start_date, end_date, area_code) -> list[tuple]`：查 `app.v_dws_finance_area_daily` 区域级日粒度
- **新增** `_build_area_unit_economics(series, prev_series)`：区域级单位经济（客单价、日均订单数、会员占比 含环比）
- **新增** `_aggregate_by_weekday_area(series)`：区域级按星期聚合（无现金流入）
- **新增** `_detect_anomaly_days_area(site_id, start, end, area_code, series)`：区域级日粒度异常（仅 gross_amount）
- **新增** `AREA_INDUSTRY_TRAITS`：业态特征字典，按 area_code 映射文字描述
- **新增** `_fetch_area_share(site_id, time_dimension, area_code) -> dict`：查本区域成交收入占全店比（对比区域 total vs 全店 total）

**payload 结构**：
```python
payload = {
    "当前时间": now,
    "门店编号": site_id,
    "时间维度": time_label,
    "区域": area_label,
    "对比口径": compare_caliber,  # H1 依赖
    "业态说明": {"区域编码": area, "区域名称": label, "业态特征": trait, "典型对比项": peer},  # 新增
    "区域占比": {"本区域成交收入": ..., "占全店成交收入": ..., "占比环比": ...},  # 新增
    "核心KPI": {...},
    "派生比率": {"人力成本占成交收入比": ..., "优惠侵蚀率": ...},  # 仅 2 项，其他区域级不可用
    "优惠构成": {...},
    "助教成本": {...},  # 可能为空
    "单位经济": {...},   # 新增（区域级，不含会员占比直到 DWS 改造后）
    "按星期聚合": {...}, # 新增（区域级，当期 ≥ 14 天）
    "日粒度异常": [...], # 新增（区域级，当期 ≥ 7 天）
    "行业基线": {"周中客流规律": ...},
    "原始指标": raw_cn,
}
```

### 4.2 `dispatcher.py` 改动

- 常量拆分：
  ```python
  _ALL_AREA = "all"
  _SUB_AREAS = ("hall", "hallA", "hallB", "hallC", "vip", "snooker", "mahjong", "ktv")
  ```
- `_handle_dws_completed()` 的 72 循环拆分：
  ```python
  for td in _TIME_DIMENSIONS:
      await self._run_step("app2_finance", td, "all", ...)
      for area in _SUB_AREAS:
          await self._run_step("app2a_finance_area", td, area, ...)
  ```
- `run_single_app()` 新增分支：
  ```python
  elif app_type == "app2a_finance_area":
      prompt_str = await build_app2a_area_prompt(context)
      ...
  ```

### 4.3 配置与注册

- `config.py`：`app_id_2a_finance_area: str` （env `DASHSCOPE_APP_ID_2A_FINANCE_AREA`）
- `prompts/__init__.py`：`from .app2a_finance_area_prompt import build_prompt as build_app2a_area_prompt`
- `cache_service.py` `CacheTypeEnum`：新增 `APP2A_FINANCE_AREA = "app2a_finance_area"`（TTL 0 · 当日过期）
- `admin_ai.py` `_SUPPORTED_APP_TYPES`：加 `"app2a_finance_area"`
- `schemas/admin_ai.py` `RunAppRequest`：`app_type` 枚举加入新值

### 4.4 环境变量

**`.env` 追加**：
```
DASHSCOPE_APP_ID_2A_FINANCE_AREA=<用户从百炼控制台粘贴>
```

**`config.py` 启动期校验**：缺失立即 raise（`AIConfig.from_env()` 现有机制）

---

## 五 · 前端实施清单

### 5.1 小程序 seq 精确匹配 + 双 cache key

**文件**：`apps/miniprogram/miniprogram/pages/board-finance/board-finance.ts`

**改动 1** · `_loadAIInsights`：按 area 选 cache_type
```typescript
const cacheType = areaKey === 'all' ? 'app2_finance' : 'app2a_finance_area'
const cache = await fetchAICache(cacheType, targetId)
```

**改动 2** · map 阶段保留 `seq` 字段：
```typescript
const insights = Array.isArray(rj.insights)
  ? rj.insights.map((item: any, idx: number) => ({
      seq: Number(item.seq) || (idx + 1),  // 保留 seq，兼容无 seq 的旧缓存
      title: ...,
      body: ...,
      titleSegs: ...,
      bodySegs: ...,
    }))
  : []
```

**改动 3** · `_extractSummary` 按 seq 精确匹配：
```typescript
const evaluation = insights.find(i => i.seq === 11) || insights[insights.length - 2]
const tracking = insights.find(i => i.seq === 12) || insights[insights.length - 1]
const details = insights.filter(i => i.seq !== 11 && i.seq !== 12)
```

### 5.2 admin-web 改动

**`AIPrewarm.tsx`**：
- 72 组合列表分两段渲染：
  - 段 1：8 个全域组合（cache_type: `app2_finance`）
  - 段 2：64 个区域组合（cache_type: `app2a_finance_area`）
- 每组合显示 `app_type` 标签（蓝=全域，绿=区域）

**`AIDashboard.tsx` + `AIOperations.tsx`**：
- app_type 下拉选择器增加 `app2a_finance_area` 项
- 运行日志筛选器支持新 app_type

**`api/adminAI.ts`**：
- `AppType` 类型增加 `'app2a_finance_area'`

---

## 六 · 整包实施 Checklist（按依赖顺序）

### Phase A · 用户侧准备（独立于 Claude）
- [ ] **A1** · 用户将 [app2a_finance_area_system_prompt_20260422_v1.md](app2a_finance_area_system_prompt_20260422_v1.md) 的 ``` 代码块内全文粘贴到百炼控制台新建 APP
- [ ] **A2** · 获取 APP ID（类似 `1dcdb5f39c3040b6af8ef79215b9b051`）
- [ ] **A3** · 在根 `.env` 追加 `DASHSCOPE_APP_ID_2A_FINANCE_AREA=<APP ID>`
- [ ] **A4** · 告知 Claude APP ID 已配置完成

### Phase B · DWS 改造（Claude 实施）
- [ ] **B1** · 产出 `db/etl_feiqiu/migrations/20260423__app2a_member_order_count.sql`（DDL 迁移）
- [ ] **B2** · 改 ETL loader 增加 `member_order_count` 聚合（`apps/etl/connectors/feiqiu/loaders/` 对应 loader）
- [ ] **B3** · 执行 migration + 运行一次区域级 ETL 回放 7 天验证
- [ ] **B4** · 校验 SQL 确认全店 = 区域和

### Phase C · 后端实施（Claude 实施 · 依赖 A4）
- [ ] **C1** · 新建 `app2a_finance_area_prompt.py`（含业态特征字典 + 5 个区域级辅助函数）
- [ ] **C2** · 改 `prompts/__init__.py` / `config.py` / `cache_service.py` / `admin_ai.py` / `schemas/admin_ai.py`
- [ ] **C3** · 改 `dispatcher.py` 72 循环拆分 + `run_single_app` 新分支
- [ ] **C4** · 单元测试：`build_app2a_area_prompt` 对 hall/vip/mahjong/ktv 4 个代表业态拼接验证
- [ ] **C5** · 集成测试：admin-web 手动触发任一区域组合，验证 `ai_run_logs.app_type = 'app2a_finance_area'` 有记录

### Phase D · 前端实施（Claude 实施 · 独立于 B/C）
- [ ] **D1** · 小程序 `board-finance.ts` 改 `_loadAIInsights` 按 area 切 cache_type + 保留 seq 字段
- [ ] **D2** · 小程序 `_extractSummary` 按 seq 精确匹配（含回退启发式）
- [ ] **D3** · admin-web `AIPrewarm.tsx` 分两段渲染 72 组合
- [ ] **D4** · admin-web `AIDashboard.tsx / AIOperations.tsx / api/adminAI.ts` app_type 扩展

### Phase E · 端到端验证（全部完成后）
- [ ] **E1** · 百炼 APP 端到端实调：单个区域组合（如 `this_month__vip`）触发，AI 返回 12 条完整
- [ ] **E2** · 72 组合预热实调：手动触发 `ai_dws_completed`，全链路走完 ~20 min
- [ ] **E3** · 小程序切换区域 → AI 洞察区正确展示 app2a 结果 · 总结卡片 seq 11/12 精确匹配
- [ ] **E4** · admin-web AIPrewarm 两段正确展示 · AIDashboard 筛选 app2a 可见
- [ ] **E5** · A/B 测试采样 16 组（8 时间 × 2 业态 hall/vip），人工评估 ≥ 12/16 组达标
- [ ] **E6** · 更新 `docs/ai/app2_finance_prompt_version_history.md` 增加 app2a v1 生产版记录

### Phase F · 审计收尾
- [ ] **F1** · `/audit` 生成 `docs/audit/changes/2026-0X-XX__app2a_finance_area_integrated.md`
- [ ] **F2** · 数据库文档同步：`docs/database/` 记录 `member_order_count` 列新增
- [ ] **F3** · 本设计文档切换为 `v2 完成`

---

## 七 · 分阶段时间估算（整包交付）

| Phase | 工作量 | 负责 | 依赖 |
|---|---|---|---|
| A · 百炼 APP 建立 | 10 min | Neo | 无（可立即开始） |
| B · DWS 改造 | 2-3 h | Claude | A1 完成 |
| C · 后端实施 | 3-4 h | Claude | A4（拿 APP ID） + B4（DWS 新列生效） |
| D · 前端实施 | 2-3 h | Claude | 无（与 B/C 并行） |
| E · 端到端验证 | 2-3 h | Neo + Claude | C/D 全部完成 |
| F · 审计 | 30 min | Claude | E 全部通过 |

**总耗时估算**：10-14 小时（1.5 工作日）

---

## 八 · 风险与回滚

| 风险 | 影响 | 缓解 |
|---|---|---|
| app2a system prompt v1 质量不达预期 | 64 组合低质 | E5 人工评估 · 未通过则迭代 v2 系统 prompt |
| DWS `member_order_count` 历史值 = 0（未回填） | 区域级会员占比环比在上线首周失真 | 接受首周降级 · system prompt H2 已定"样本不足后缀"降权引用 |
| ETL loader 改造引入数据错算 | 区域级订单数异常 | 全店 = 区域和校验 SQL · E2 跑完立即验证 |
| 百炼 APP ID 配置错误 | 64 组合全失败 | config.py 启动期校验缺失即报错 |
| dispatcher 72 循环拆分 bug | 预热超时 | 保留原熔断/限流机制 · C3 单测覆盖拆分 |

**回滚**（若整包实施后发现重大问题）：
1. **百炼侧**：将 app2a APP 暂停（控制台操作），dispatcher 自动回退（但需代码改动支持）
2. **代码侧**：`git revert` 整包 commit
3. **DWS 侧**：`ALTER TABLE DROP COLUMN member_order_count`（CASCADE 视图）

由于用户指示"作为正式模块上线、不加灰度"，回滚复杂度较高 · 要求 E5 人工评估严格把关。

---

## 九 · 验证清单（Definition of Done）

**B · DWS**：
- [ ] `SELECT column_name FROM information_schema.columns WHERE table_schema='dws' AND table_name='dws_finance_area_daily' AND column_name='member_order_count';` 返回 1 行
- [ ] 全店 vs 区域和 校验 SQL 返回 0 行
- [ ] `app.v_dws_finance_area_daily` 新视图 SELECT 正常返回带 member_order_count 列

**C · 后端**：
- [ ] `AIConfig.from_env()` 加载通过（新 env 变量识别）
- [ ] 对 hall/vip/mahjong/ktv 4 个代表业态调 `build_app2a_area_prompt` 本地返回 prompt 字符串，"对比口径"/"业态说明"/"区域占比" 三字段齐
- [ ] `ai_run_logs.app_type = 'app2a_finance_area'` 出现
- [ ] 单次预热总耗时 < 25 min

**D · 前端**：
- [ ] 小程序切换到 VIP/大厅/斯诺克 3 个区域，AI 洞察区能正确加载 app2a 缓存结果
- [ ] 本期总结卡片三色灯 + seq 11/12 精确匹配
- [ ] admin-web AIPrewarm 两段分区正常显示 72 组合
- [ ] admin-web AIDashboard 可按 app2a_finance_area 筛选日志

**E · 端到端**：
- [ ] 16 组采样人工评估 ≥ 75% 达标（12/16 组）
- [ ] 7 天成功率 ≥ 95%
- [ ] `insights` 数组长度 = 12 占比 ≥ 90%

---

## 变更记录

| 日期 | 版本 | 变更 | 作者 |
|---|---|---|---|
| 2026-04-22 | v1（草案） | 初版 · 基于 this_month/all 调优结论 + 72 组合数据源调研 | Claude + Neo |
| 2026-04-22 | v2（定稿） | 用户已确认 Q1-Q7 决策 · 纳入 DWS 改造 + seq 精确匹配 · 产出整包 checklist · 删除灰度开关 | Claude + Neo |