# 百炼平台 AI 应用集成实现规范

> **2026-05-05 起,9 APP(含 App2a)system prompt 内容已迁移到 [`docs/ai/system-prompts/`](../ai/system-prompts/) 目录**,每个 APP 一份独立 MD,便于逐个对照/逐个 commit/逐个 diff。
>
> **本文件不再包含 system prompt 全文**,职责调整为"AI 应用集成实现规范":
> - **NS2 后端实现要点**(应用 1 的 10 种 contextType 数据来源映射、应用 3-7 的 biz_params 注入机制、Token 预算约束)
> - **应用 ID 与环境变量映射表**(2026-03-22 P14 DashScope 迁移 + 2026-04-23 App2a 注册)
> - **前端消费方式速查**(各 APP 展示位置 + 缓存键)
> - **附录:代码审计对照表**(2026-03-21 代码 vs 文档差异修正记录)
>
> **System prompt 内容请去这些位置**:
> - 索引:[`docs/ai/system-prompts/_INDEX.md`](../ai/system-prompts/_INDEX.md)
> - 各 APP 独立文件:`app1_chat.md` / `app2_finance.md` / `app2a_finance_area.md` / `app3_clue.md` ... `app8_consolidation.md`
> - 2026-05-05 全量快照源(8 APP,不含 App2a):[`docs/ai/system-prompts/_snapshot-20260505-source.md`](../ai/system-prompts/_snapshot-20260505-source.md)
>
> ---
>
> 模型:Qwen3.5-Plus(应用 1、5)/ Qwen3-Max-Preview(应用 2、2a、3、4、6、7、8)
> 所有应用均启用深度思考模式(enable_thinking=true)
> 权威来源:`docs/prd/specs/P5-miniapp-ai-integration.md` + `docs/prd/AI需求2.md`
> 首条 Prompt(用户消息)由后端代码在调用时拼接 JSON 数据,结构定义见 P5 spec「首条 Prompt 数据结构」章节。
> NS2 实现代码:`apps/backend/app/ai/`(data_fetchers + apps 子包),属性测试:`tests/test_data_fetchers/` + `tests/test_ai_apps/`

### NS2 后端实现要点(2026-03-21 更新)

应用 1 支持 10 种页面入口上下文(contextType),由 `page_context.py` 文本化后注入首条消息:

| contextType | 入口页面 | 数据来源(代码实际查询) |
|-------------|---------|------------------------|
| `task-detail` | 任务详情 | App: `biz.coach_tasks` + `biz.coach_tasks_member_view` + `biz.coach_tasks_assistant_view` + `biz.notes` + `biz.ai_cache`(app4_analysis) |
| `task-list` | 任务列表 | App: `biz.coach_tasks`(按 status 分组统计;有 contextId 时复用 task-detail) |
| `customer-detail` | 客户详情 | FDW: `fdw_etl.v_dim_member`(scd2_is_current=1) + `fdw_etl.v_dwd_settlement_head` + `fdw_etl.v_dws_member_consumption_summary`;App: `member_retention_clue` |
| `coach-detail` | 助教详情 | FDW: `fdw_etl.v_dim_assistant`;App: `biz.coach_tasks`(按 status 分组统计) |
| `board-finance` | 财务看板 | FDW: `fdw_etl.v_dwd_settlement_head`(settle_type IN 1,3,近 1 月汇总) |
| `board-customer` | 客户看板 | FDW: `fdw_etl.v_dwd_settlement_head` JOIN `fdw_etl.v_dim_member`(Top 10 客户) |
| `board-coach` | 助教看板 | FDW: `fdw_etl.v_dwd_assistant_service_log` JOIN `fdw_etl.v_dim_assistant`(Top 10 助教) |
| `performance` | 绩效页 | FDW: `fdw_etl.v_dws_assistant_salary_calc` JOIN `fdw_etl.v_dim_assistant` |
| `customer-service-records` | 服务记录 | FDW: `fdw_etl.v_dwd_assistant_service_log`(is_trash=false,近 10 条) |
| `my-profile` | 个人中心 | 无查询(静态文本:"当前为个人信息页面,可查询个人绩效和任务情况") |

应用 3-7 的 `biz_params` 注入机制:后端 `run()` 函数接收 `member_id`/`assistant_id`/`site_id` 等参数,通过 data_fetchers 层查询数据库拼接 JSON,作为首条用户消息发送。

App2a 的 `biz_params` 注入机制:后端接收 `area`(非 'all')+ `time_dimension` + `site_id`,通过 `board_service.get_finance_board(time, area, compare=1, site_id)` 取数,使用 DWS `dws_coach_area_hours` 按 area_code 精确聚合的助教数据。

Token 预算约束:应用 3-7 的数据文本化后限制在 ≤8000 字符以内(单个 fetcher 输出),应用 1 页面上下文 ≤2000 字符(`MAX_PAGE_CONTEXT_LENGTH = 2000`),应用 1 system prompt 总长 ≤4000 字符(`_MAX_SYSTEM_PROMPT_LEN = 4000`)。超限时按优先级截断。

### 应用 ID 与环境变量映射(2026-03-22 P14 DashScope 迁移 / 2026-04-23 App2a 注册 / 2026-05-05 同步对齐)

| 应用 | 名称 | 百炼显示名 | 环境变量 Key | 百炼应用 ID | 选用模型 | temperature |
|------|------|---------|-------------|------------|----------|-------------|
| 应用 1 | 通用对话 | - | `DASHSCOPE_APP_ID_1_CHAT` | `979dabe6f22a43989632b8c662cac97c` | Qwen3.5-Plus | 0.7 |
| 应用 2 | 财务洞察 | - | `DASHSCOPE_APP_ID_2_FINANCE` | `1dcdb5f39c3040b6af8ef79215b9b051` | Qwen3-Max-Preview | 0 |
| 应用 2a | 财务洞察(区域) | `ZQYY-APP2a-指定区域财务洞察` | `DASHSCOPE_APP_ID_2A_FINANCE_AREA` | `0ae965029bc54706bcff44f511ac716b` | Qwen3-Max-Preview | 0 |
| 应用 3 | 客户数据维客线索分析 | - | `DASHSCOPE_APP_ID_3_CLUE` | `708bf45439cd48c7ab9a514d03482890` | Qwen3-Max-Preview | 0 |
| 应用 4 | 关系分析/任务建议 | - | `DASHSCOPE_APP_ID_4_ANALYSIS` | `ea7b1c374f574b9a925a2fb5789a9b90` | Qwen3-Max-Preview | 0 |
| 应用 5 | 话术参考 | - | `DASHSCOPE_APP_ID_5_TACTICS` | `46f54e6053df4bb0b83be29366025cf6` | Qwen3.5-Plus | 0.8 |
| 应用 6 | 备注分析 | - | `DASHSCOPE_APP_ID_6_NOTE` | `025bb344146b4e4e8be30c444adab3b4` | Qwen3-Max-Preview | 0 |
| 应用 7 | 客户分析 | - | `DASHSCOPE_APP_ID_7_CUSTOMER` | `df35e06991b24d49971c03c6428a9c87` | Qwen3-Max-Preview | 0 |
| 应用 8 | 维客线索整理 | - | `DASHSCOPE_APP_ID_8_CONSOLIDATE` | `407dfb89283b4196934eec5fefe3ebc2` | Qwen3-Max-Preview | 0 |

> P14 变更(2026-03-22):环境变量前缀从 `BAILIAN_*` 迁移到 `DASHSCOPE_*`,SDK 从 `openai` 迁移到 `dashscope`(Application API)。
> 新增环境变量:`DASHSCOPE_API_KEY`、`DASHSCOPE_WORKSPACE_ID`(可选)、`INTERNAL_API_TOKEN`、`BACKEND_API_URL`。
> 已删除:`BAILIAN_BASE_URL`、`BAILIAN_MODEL`(Application API 通过 app_id 指定应用,不需要 base_url 和 model)。
> App2a 注册(2026-04-23):新增 `DASHSCOPE_APP_ID_2A_FINANCE_AREA`(`apps/backend/app/ai/config.py:21,41` 已注册)。

### 前端消费方式速查

| 应用 | 展示位置 | 数据来源 | 备注 |
|------|---------|---------|------|
| 应用 1 | chat 页面 | SSE 流式 + `ai_messages` | 实时对话 |
| 应用 2 | board-finance(area=all) | `ai_cache (app2_finance)` | 全店总览洞察卡片(72 组合预热) |
| 应用 2a | board-finance(area≠all) | `ai_cache (app2a_finance_area)` | 单业态区域洞察卡片(64 组合) |
| 应用 3 | 不展示 | `ai_cache (app3_clue)` | 供应用 8 整合 |
| 应用 4 | task-detail + task-list 卡片摘要 | `ai_cache (app4_analysis)` | summary 在卡片显示 |
| 应用 5 | task-detail | `ai_cache (app5_tactics)` | 话术列表 |
| 应用 6 | task-detail 备注卡片(打星) | `ai_cache (app6_note_analysis)` | 线索供应用 8 |
| 应用 7 | customer-detail | `ai_cache (app7_customer_analysis)` | 策略+总结 |
| 应用 8 | customer-detail + task-detail | `member_retention_clue` | By:系统/By:备注 |

---

## 附录:代码审计对照表(2026-03-21)

> 基于 `apps/backend/app/ai/` 实际代码与本文档(当时含 system prompt 全文)描述的逐项对比。
> 2026-05-05 system prompt 全文已迁移到 `docs/ai/system-prompts/`,本附录保留作为历史回溯。

### 已修正的差异

| # | 位置 | 原文档描述 | 代码实际实现 | 修正说明 |
|---|------|-----------|-------------|---------|
| 1 | 应用 1 · `board-finance` | `v_dws_finance_daily_summary` | `fdw_etl.v_dwd_settlement_head`(settle_type IN 1,3,近 1 月 SUM/AVG) | 代码直接查 DWD 结算头表做聚合,未使用 DWS 财务日汇总视图 |
| 2 | 应用 1 · `board-customer` | `v_dim_member` | `fdw_etl.v_dwd_settlement_head` JOIN `fdw_etl.v_dim_member`(Top 10 按 items_sum DESC) | 代码从结算头表聚合消费金额,JOIN 会员维度表取昵称 |
| 3 | 应用 1 · `board-coach` | `v_dim_assistant` | `fdw_etl.v_dwd_assistant_service_log` JOIN `fdw_etl.v_dim_assistant`(Top 10 按 service_count DESC) | 代码从服务日志表聚合,JOIN 助教维度表取昵称 |
| 4 | 应用 1 · `performance` | `v_dws_assistant_monthly_summary` | `fdw_etl.v_dws_assistant_salary_calc` JOIN `fdw_etl.v_dim_assistant` | 代码查的是薪资计算表,不是月度汇总表 |
| 5 | 应用 1 · `customer-service-records` | `v_dwd_settlement_head` | `fdw_etl.v_dwd_assistant_service_log`(is_trash=false,LIMIT 10) | 代码查的是助教服务日志表,不是结算头表 |
| 6 | 应用 1 · `my-profile` | `auth.users` | 无数据库查询(返回静态文本) | 代码未查 auth.users,直接返回固定提示文本 |
| 7 | 应用 1 · `task-detail` | `v_dwd_settlement_head` | `biz.coach_tasks` + `biz.notes` + `biz.ai_cache` | 代码未查 ETL 结算头表,仅查业务库任务/备注/AI缓存 |
| 8 | 应用 1 · `customer-detail` | `biz.notes` | `member_retention_clue`(维客线索) | 代码查的是维客线索表而非备注表;另外还查了 `v_dws_member_consumption_summary` 取余额 |
| 9 | Token 预算 | 应用 1 页面上下文 ≤4000 字符 | `MAX_PAGE_CONTEXT_LENGTH = 2000`(page_context.py),`_MAX_SYSTEM_PROMPT_LEN = 4000`(app1_chat.py) | 页面上下文截断阈值是 2000,4000 是 system prompt 总长上限 |

### 确认一致的部分

- ✅ 应用 1 的 10 种 contextType 名称与 `SUPPORTED_PAGE_TYPES` 完全一致
- ✅ 应用 2 的 8 个时间维度编码与 `TIME_DIMENSIONS` 完全一致
- ✅ 应用 2 的 prompt 结构(task + data + reference)与 `app2_finance_prompt.py` 一致
- ✅ 应用 2 的字段映射(items_sum 口径、助教费用拆分)与代码一致
- ✅ 应用 3 的 category 枚举限定 3 个值(客户基础、消费习惯、玩法偏好)
- ✅ 应用 6 的 category 枚举限定 6 个值(含促销接受、社交关系、重要反馈)
- ✅ 应用 3/6/7 共用 `member_data.py`(fetch_member_consumption_data)
- ✅ 应用 4/5 共用 `assistant_data.py`(fetch_assistant_info + fetch_service_history)
- ✅ 应用 8 的 source 判断规则(ai_consumption / ai_note / 混合→ai_consumption)
- ✅ 所有 FDW 查询使用 `is_trash=false` 排除废单
- ✅ 会员信息通过 `scd2_is_current=1` 过滤
- ✅ 金额口径统一使用 items_sum,禁止 consume_money
- ✅ 应用 ID 与环境变量映射表与代码常量一致
- ✅ 前端消费方式速查表与缓存写入逻辑一致
- ✅ 应用 3-7 的 system message 上限 ≤8000 字符

---

## 改造历史

| 日期 | 动作 | 备注 |
|---|---|---|
| 2026-03-21 | 创建 | 8 APP system prompt + NS2 实现要点统一汇总 |
| 2026-03-22 | P14 DashScope 迁移 | 环境变量 `BAILIAN_*` → `DASHSCOPE_*`,SDK 切换 |
| 2026-04-23 | App2a 注册 | 新增 `DASHSCOPE_APP_ID_2A_FINANCE_AREA` |
| **2026-05-05** | **F3-2C 改造瘦身** | **8 APP system prompt 全文迁移到 `docs/ai/system-prompts/`,本文件改造为"AI 应用集成实现规范",仅保留 NS2 实现要点 + APP ID 映射 + 前端消费方式 + 附录代码审计** |
