Neo-ZQYY/docs/audit/changes/2026-04-23__app2a_finance_area_integrated.md

变更审计记录：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 即可降级

验证

后端单测（已通过）

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：

   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 分钟）：

   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 条洞察 + 正确三色灯