# 审计记录：App2 财务洞察全筛选组合预热 + 字段中文化

**日期**：2026-04-21
**会话**：board-finance AI 洞察改造
**影响范围**：backend / miniprogram / db / admin-web

---

## 变更摘要

用户需求：
1. 每日 10:00 为所有门店的 board-finance 页面所有筛选组合（时间 × 区域 = 72 组）生成 AI 洞察并缓存
2. 前端根据当前筛选条件读取对应缓存
3. 发送给 AI 的 prompt 字段名翻译为中文（避免英文变量名，提升可读性）
4. 切换默认模型为 claude-opus-4-7（max 1M 上下文）

---

## 变更文件清单

### 修改

| 文件 | 关键变更 |
|------|----------|
| `~/.claude/settings.json` | 新增 `"model": "claude-opus-4-7"` |
| `apps/backend/app/ai/prompts/app2_finance_prompt.py` | 新增 `area` 参数（与 board-finance.ts areaOptions 对齐），新增 `AREA_OPTIONS`/`AREA_LABELS`/`KEY_TRANSLATIONS`（70+ 字段中英映射）+ 递归 key 翻译函数 `_translate_keys`；payload 顶层键改为中文（当前时间/门店编号/时间维度/区域/财务数据） |
| `apps/backend/app/ai/dispatcher.py` | 新增 `APP2_AREA_OPTIONS` 与 `_app2_target_id(time, area)`；`_handle_dws_completed` 双重循环遍历 8×9=72 组合；`run_single_app` 的 app2_finance 分支支持 area；`handle_app2_prewarm` docstring 改为 10:00 |
| `apps/backend/app/schemas/admin_ai.py` | `RunAppRequest` 新增 `area: str \| None` 字段 |
| `apps/admin-web/src/api/adminAI.ts` | `RunAppRequest` 接口新增 `area?: string` |
| `apps/miniprogram/miniprogram/pages/board-finance/board-finance.ts` | `_loadAIInsights(selectedTime, selectedArea)` 签名，`target_id` 改为 `{timeKey}__{areaKey}`；`_loadData` 传入两个参数 |

### 新建

| 文件 | 说明 |
|------|------|
| `db/zqyy_app/migrations/20260421_app2_prewarm_cron_reschedule.sql` | UPDATE biz.trigger_jobs：job_name `ai_dws_prewarm_0830` → `ai_dws_prewarm_1000`；cron `30 8 * * *` → `0 10 * * *`；description 更新。已在 pg-app-test 执行 |

---

## 缓存键规则变更

- 旧：`target_id = time_dimension`（如 `this_month`，仅 8 条/门店）
- 新：`target_id = {time_dimension}__{area}`（双下划线分隔，72 条/门店）
- 前后端用相同拼装函数：后端 `_app2_target_id`、前端 `board-finance.ts _loadAIInsights` 内联实现
- 旧格式缓存已清理（仅保留 `__` 格式）

## 字段中文化实现

`KEY_TRANSLATIONS` 覆盖 `board_service.get_finance_board` 返回的所有层级字段：
- 顶层板块：overview → 经营一览、recharge → 预收资产 等
- 经营一览：occurrence → 发生额、discount_rate → 优惠率 等
- 环比后缀：`*_compare` / `*_down` / `*_flat` 全覆盖
- 通用字段：label → 名称、amount → 金额、total → 合计 等

`_translate_keys` 递归遍历 dict/list，只翻译键名，不改变值与结构。

## 触发与执行验证

- 2026-04-21 01:54 首次通过 `POST /api/internal/ai/trigger` 触发 `dws_completed + is_forced=true`
- prompt 已验证为完整中文键：`{"当前时间": "2026-04-21 01:56", "门店编号": 2790685415443269, "时间维度": "本月", "区域": "全部区域", "财务数据": {"经营一览": {"发生额": 287315.98, ...}}}`
- 后续 72 组合后台异步执行，结果写入 `biz.ai_cache`

---

## 遗留风险点

1. **AI 调用时间增加**：中文 key 使 prompt 体积膨胀约 15%，部分请求已触发 `_STEP_TIMEOUT=120s` 超时。若超时率高需将 `_STEP_TIMEOUT` 上调至 180-240s，或裁剪 board_data 中次要字段
2. **72 组合全量执行时长**：每组约 30-60s 串行，单门店 36-72 分钟；多门店场景下 cron 10:00 启动后可能跨小时结束
3. **dispatcher `_execute_chain` 外层超时**：`_STEP_TIMEOUT * 5 = 600s = 10 min`，只够覆盖 ~10 组合；dws_completed 场景需单独放宽该超时，否则只能写入前 10 组缓存

## 回滚策略

- cron 回滚：`UPDATE biz.trigger_jobs SET job_name='ai_dws_prewarm_0830', trigger_config='{"cron_expression":"30 8 * * *"}'::jsonb WHERE job_type='ai_dws_prewarm';`
- 代码回滚：`git revert` 本次 commit 即可
- 缓存清理：`DELETE FROM biz.ai_cache WHERE cache_type='app2_finance' AND target_id LIKE '%\_\_%' ESCAPE '\';`
