Neo-ZQYY/docs/specs/P14-ai-dashscope-migration/requirements.md

# 需求文档 — P14：AI 模块改造 — DashScope 迁移 + 调度器完善

## 简介

当前 AI 模块使用 `openai` SDK 的通用模型 API（`chat.completions.create`），但项目的 8 个 App 均为百炼控制台创建的智能体应用（各有独立 `app_id`）。通用模型 API 不接受 `app_id`，等于绕过了百炼控制台配置的 System Prompt、MCP 工具等全部能力。

本 spec 将 SDK 从 `openai` 切换到 `dashscope`（Application API），一步到位完成迁移，同时修复调度器 asyncio 嵌套问题、打通事件触发链、新增熔断/限流/Token 预算控制，并完成相关数据库变更。

### 依赖

- P5（AI 集成层）— 现有 AI 模块基础架构、8 个 App 实现、缓存/对话服务
- RNS1.4（CHAT 对齐）— CHAT 路径迁移、SSE 端点、对话复用规则

### 来源文档

- `docs/prd/specs/P14-ai-dashscope-migration.md` — PRD 主文档
- `docs/reports/2026-03-21__ai_module_issues.md` — 18 个问题清单（4 P0 / 6 P1 / 5 P2 / 3 P3）

### 不在本 spec 范围

- admin-web AI 监控后台（P15）
- 全链路测试重建与历史回填（P15）
- 多门店支持（BACKLOG，当前写死 `2790685415443269`）
- 消息队列替代 HTTP 触发（单独 PRD）
- Prompt 版本管理（BACKLOG）
- 前端刷新机制（前端改动，不在本 spec）

## 术语表

- **Backend**：FastAPI 后端应用，位于 `apps/backend/`
- **ETL**：飞球 Connector ETL 管道，位于 `apps/etl/connectors/feiqiu/`
- **DashScope_Client**：新的 DashScope Application API 客户端，替代现有 `BailianClient`
- **Application_API**：`dashscope.Application.call()` 方法，百炼智能体应用的原生调用接口
- **App1**：通用对话应用（流式，支持多轮 session_id）
- **App2**：财务洞察应用（单轮，DWS 完成后预生成）
- **App3**：维客线索应用（单轮，消费事件触发）
- **App4**：关系分析应用（单轮，消费/任务事件触发）
- **App5**：话术参考应用（单轮，依赖 App4 结果）
- **App6**：备注分析应用（单轮，备注事件触发）
- **App7**：客户分析应用（单轮，消费事件触发）
- **App8**：维客线索整理应用（单轮，整合 App3/App6 线索）
- **session_id**：百炼云端对话管理标识，格式 `conv_{conversation_id}_{created_timestamp}`
- **Circuit_Breaker**：熔断器，按 app_id 独立计数，连续失败后暂停请求
- **Rate_Limiter**：限流器，按用户/门店维度控制请求频率
- **Budget_Tracker**：Token 预算追踪器，按日/月聚合 token 消耗
- **Internal_AI_API**：内部触发接口 `POST /api/internal/ai/trigger`，ETL 通过此接口触发 AI 调用链
- **Dispatcher**：AI 事件调度与调用链编排器，位于 `apps/backend/app/ai/dispatcher.py`
- **ai_run_logs**：AI 运行记录表，记录每次 Application API 调用的输入/输出/耗时/token
- **ai_trigger_jobs**：调度运行记录表，记录事件触发的调用链执行状态

## 需求

### 需求 1：SDK 替换 — openai 切换到 dashscope Application API

**用户故事：** 作为后端开发者，我希望将 AI 客户端从 `openai` SDK 切换到 `dashscope` Application API，以便 8 个百炼智能体应用能通过各自的 `app_id` 调用，使用百炼控制台配置的 System Prompt 和 MCP 工具。

#### 验收标准

1. THE DashScope_Client SHALL 使用 `dashscope.Application.call()` 替代 `openai.AsyncOpenAI.chat.completions.create()`，所有 8 个 App 通过各自的 `app_id` 参数调用 Application API
2. THE DashScope_Client SHALL 使用 `asyncio.to_thread()` 包装同步的 `Application.call()` 方法，避免阻塞 FastAPI 事件循环
3. WHEN App1 进行流式调用时，THE DashScope_Client SHALL 在独立线程中消费 `Application.call(stream=True)` 返回的同步迭代器，通过 `asyncio.Queue` 桥接到 async generator，逐 chunk 输出文本
4. WHEN App2~8 进行单轮调用时，THE DashScope_Client SHALL 通过 `prompt` 参数传入后端拼好的完整数据 JSON，不使用 `messages` 数组
5. THE DashScope_Client SHALL 保留指数退避重试机制：最多 3 次重试，间隔 1s → 2s → 4s；HTTP 4xx 不重试，5xx/超时/连接错误重试
6. WHEN Application API 返回非合法 JSON 时，THE DashScope_Client SHALL 纯重试（最大 3 次），不做本地解析修复
7. THE Backend SHALL 在 `pyproject.toml` 中移除 `openai` 依赖，新增 `dashscope` 依赖

### 需求 2：环境变量统一 — BAILIAN_* 迁移到 DASHSCOPE_*

**用户故事：** 作为运维人员，我希望环境变量从 `BAILIAN_*` 统一迁移到 `DASHSCOPE_*` 前缀，以便与 DashScope SDK 的命名规范保持一致。

#### 验收标准

1. THE Backend SHALL 废弃并删除以下环境变量：`BAILIAN_API_KEY`、`BAILIAN_BASE_URL`、`BAILIAN_MODEL`
2. THE Backend SHALL 新增以下环境变量：`DASHSCOPE_API_KEY`（DashScope API Key）、`DASHSCOPE_WORKSPACE_ID`（百炼工作空间 ID，可选）
3. THE Backend SHALL 将 8 个 App ID 环境变量从 `BAILIAN_APP_ID_*` 前缀重命名为 `DASHSCOPE_APP_ID_*` 前缀（`DASHSCOPE_APP_ID_1_CHAT` 至 `DASHSCOPE_APP_ID_8_CONSOLIDATE`）
4. THE Backend SHALL 更新 `.env` 和 `.env.template` 文件，反映所有环境变量变更
5. THE Backend SHALL 在启动时校验必需环境变量（`DASHSCOPE_API_KEY` 和 8 个 `DASHSCOPE_APP_ID_*`），缺失时立即报错，禁止静默回退空字符串

### 需求 3：App1 对话管理 — session_id 云端 + 本地双轨

**用户故事：** 作为助教用户，我希望与 AI 助手的多轮对话能通过百炼 session_id 保持上下文连贯，同时本地持久化消息记录，以便在 session 过期后仍能恢复对话。

#### 验收标准

1. WHEN App1 创建新对话时，THE Backend SHALL 生成 session_id（格式 `conv_{conversation_id}_{created_timestamp}`），存储到 `ai_conversations.session_id` 字段
2. WHEN App1 发送消息时，THE DashScope_Client SHALL 携带 `session_id` 参数调用 Application API，由百炼云端管理对话上下文
3. THE DashScope_Client SHALL 通过 `biz_params.user_prompt_params` 传递用户信息：`User_ID`（用户 ID）、`Role`（角色）、`Nickname`（昵称）
4. THE Backend SHALL 同时将每条消息写入本地 `ai_messages` 表，实现云端 + 本地双轨持久化
5. IF session_id 过期（百炼返回 session 无效错误），THEN THE Backend SHALL 从本地 `ai_messages` 加载最近 20 条历史消息，用 `messages` 数组（不带 session_id）重新调用百炼，并将百炼返回的新 session_id 更新到本地
6. THE Backend SHALL 保持现有对话复用规则不变：task 入口无时限复用、customer/coach 入口 3 天时限、general 入口始终新建

### 需求 4：App2~8 单轮 Prompt 调用

**用户故事：** 作为后端开发者，我希望 App2~8 统一使用单轮 `prompt` 调用模式，以便简化调用逻辑并充分利用百炼控制台配置的 System Prompt。

#### 验收标准

1. THE Backend SHALL 为 App2~8 的每次调用使用 `build_prompt()` 函数拼好完整数据 JSON，通过 `Application.call(app_id=..., prompt=data_json)` 传入
2. THE Backend SHALL 不再为 App2~8 在代码中维护 System Prompt，以百炼控制台配置为准
3. THE Backend SHALL 不再为 App2~8 使用 `messages` 数组或 `response_format` 参数
4. WHEN Application API 返回结果时，THE Backend SHALL 解析 `response.output.text` 字段获取 JSON 内容，解析失败时按需求 1 第 6 条重试
5. THE Backend SHALL 为每次 App2~8 调用记录 `ai_run_logs`（详见需求 10）

### 需求 5：熔断器

**用户故事：** 作为系统管理员，我希望 AI 调用具备熔断保护，以便在百炼服务异常时快速降级，避免无效请求堆积。

#### 验收标准

1. THE Circuit_Breaker SHALL 按 `app_id` 独立计数，App1 熔断不影响 App2~8，反之亦然
2. WHEN 某个 app_id 连续 5 次调用失败时，THE Circuit_Breaker SHALL 进入熔断状态，持续 60 秒内所有该 app_id 的请求直接返回降级响应
3. WHEN 熔断 60 秒后，THE Circuit_Breaker SHALL 进入半开状态，放行 1 个请求进行探测
4. WHEN 半开状态的探测请求成功时，THE Circuit_Breaker SHALL 关闭熔断，恢复正常调用
5. WHEN 半开状态的探测请求失败时，THE Circuit_Breaker SHALL 重新进入熔断状态，再等待 60 秒
6. WHILE Circuit_Breaker 处于熔断状态，THE Backend SHALL 对 App1 请求返回友好提示"AI 服务暂时不可用，请稍后重试"，对 App2~8 后台任务记录 `circuit_open` 状态并跳过执行

### 需求 6：限流

**用户故事：** 作为系统管理员，我希望 AI 调用具备限流保护，以便防止单个用户或门店过度消耗 AI 资源。

#### 验收标准

1. THE Rate_Limiter SHALL 对 App1 实施每用户每分钟 10 次的请求频率限制
2. THE Rate_Limiter SHALL 对 App2~8 实施每门店每小时 100 次（合计）的请求频率限制
3. WHEN 请求超过限流阈值时，THE Rate_Limiter SHALL 对 App1 返回友好提示"请求过于频繁，请稍后再试"，对 App2~8 后台任务记录 `rate_limited` 状态并跳过执行
4. THE Rate_Limiter SHALL 使用内存计数器实现（单实例部署），不依赖外部 Redis

### 需求 7：Token 预算控制

**用户故事：** 作为系统管理员，我希望 AI 调用具备 Token 预算控制，以便防止 API 费用失控。

#### 验收标准

1. THE Budget_Tracker SHALL 从 `ai_run_logs.tokens_used` 按日/月聚合计算已消耗 token 数
2. THE Budget_Tracker SHALL 支持日预算上限（默认 100,000 tokens）和月预算上限（默认 2,000,000 tokens）
3. WHEN 日预算或月预算超限时，THE Backend SHALL 对 App1 用户对话返回友好提示"AI 服务今日额度已用完，请明天再试"
4. WHEN 日预算或月预算超限时，THE Backend SHALL 对 App2~8 后台任务跳过执行，记录 `budget_exceeded` 状态到 `ai_run_logs`
5. THE Budget_Tracker SHALL 在每次 AI 调用前检查预算，调用后更新 token 消耗记录

### 需求 8：调度器 asyncio 修复

**用户故事：** 作为后端开发者，我希望修复 dispatcher.py 中的 asyncio 嵌套问题，以便事件处理器在 FastAPI 事件循环中正常工作，不再因 `asyncio.run()` 嵌套而报错。

#### 验收标准

1. THE Dispatcher SHALL 移除所有 `asyncio.run()` 和 `asyncio.new_event_loop()` 调用
2. THE Dispatcher SHALL 将所有事件处理器入口改为 `async def`，使用 `asyncio.create_task()` 发起后台异步任务
3. THE Dispatcher SHALL 使用 `asyncio.wait_for()` 实现超时控制，替代同步超时机制
4. THE Dispatcher SHALL 确保事件处理器在 FastAPI lifespan 中注册后，能在已有事件循环中正常执行调用链

### 需求 9：事件触发链打通

**用户故事：** 作为系统管理员，我希望消费事件、备注事件、任务分配事件能正确触发对应的 AI 调用链，以便 AI 分析结果能自动生成，无需人工干预。

#### 验收标准

1. WHEN ETL DWS 任务完成后发送消费事件时，THE Dispatcher SHALL 执行调用链：App3 → App8 → App7（无助教时），或 App3 → App8 → App7 + App4 → App5（有助教时）
2. WHEN 小程序助教提交备注时，THE Dispatcher SHALL 执行调用链：App6 → App8
3. WHEN task_manager 自动分配任务时，THE Dispatcher SHALL 执行调用链：App4 → App5
4. THE Dispatcher SHALL 在调用链中某步失败时记录错误日志，后续应用使用已有缓存继续执行，不中断整条链
5. THE Dispatcher SHALL 将每次事件触发记录到 `ai_trigger_jobs` 表，包含事件类型、执行链、状态、耗时

### 需求 10：ETL → 后端内部触发 API

**用户故事：** 作为 ETL 开发者，我希望 DWS 任务完成后能通过 HTTP 接口触发后端 AI 调用链，以便实现 ETL 与 AI 模块的自动联动。

#### 验收标准

1. THE Backend SHALL 实现 `POST /api/internal/ai/trigger` 端点，接受 JSON 请求体包含：`event_type`（事件类型）、`connector_type`（连接器类型，默认 `feiqiu`）、`site_id`（门店 ID）、`member_id`（会员 ID，可选）、`payload`（事件附加数据）
2. THE Internal_AI_API SHALL 使用独立的 `INTERNAL_API_TOKEN` 环境变量进行认证，通过 HTTP Header `Authorization: Internal-Token {token}` 传递，不走 JWT
3. IF 认证 token 缺失或不匹配，THEN THE Internal_AI_API SHALL 返回 HTTP 401
4. THE Internal_AI_API SHALL 将事件写入 `ai_trigger_jobs` 表后立即返回 `{ trigger_job_id, status: "pending" }`，调用链在后台异步执行
5. THE Internal_AI_API SHALL 设计为连接器无关接口，`connector_type` 字段标识来源，为多平台扩展预留
6. THE ETL SHALL 在 DWS 任务完成后通过 HTTP POST 调用 Internal_AI_API，传递消费事件或 DWS 完成事件

### 需求 11：App2 预生成

**用户故事：** 作为门店管理者，我希望财务洞察（App2）在每日 DWS 数据刷新后自动预生成，以便打开页面时能立即看到最新分析结果，无需等待。

#### 验收标准

1. WHEN ETL 通过 Internal_AI_API 发送 `event_type: "dws_completed"` 事件时，THE Dispatcher SHALL 触发 App2 预生成任务
2. THE Dispatcher SHALL 为当前门店（`site_id: 2790685415443269`）生成 8 个时间维度的财务洞察：今日、昨日、本周、上周、本月、上月、本季、上季
3. THE Dispatcher SHALL 将 App2 预生成结果写入 `ai_cache`（cache_type: `app2_finance`），过期时间为当日 23:59:59
4. THE Dispatcher SHALL 确保 App2 预生成每日调用量为 1 门店 × 8 维度 = 8 次

### 需求 12：幂等与去重

**用户故事：** 作为系统管理员，我希望 AI 事件触发具备幂等去重能力，以便重复事件不会导致重复执行和资源浪费。

#### 验收标准

1. THE Dispatcher SHALL 对自动触发的事件按 `(event_type, member_id, site_id, date)` 进行去重，重复事件跳过执行并记录 `skipped_duplicate` 状态
2. WHEN 手动重跑时（`is_forced = true`），THE Dispatcher SHALL 允许强制执行，跳过去重检查，在 `ai_trigger_jobs` 中明确标记 `is_forced`
3. THE Backend SHALL 对 App8 写入 `member_retention_clue` 业务表时实施强幂等：在事务中先 DELETE 再 INSERT，同一 member 同一天只执行一次
4. IF App8 幂等写入事务失败，THEN THE Backend SHALL 自动回滚，记录错误到 `ai_trigger_jobs.error_message`

### 需求 13：缓存策略

**用户故事：** 作为后端开发者，我希望 AI 缓存按 App 类型设置不同的过期时间和状态管理，以便缓存数据的新鲜度与业务需求匹配。

#### 验收标准

1. THE Backend SHALL 为每个 App 设置独立的缓存过期策略：App2 当日 23:59:59、App3/App4/App5/App7/App8 为 7 天、App6 为 30 天
2. THE Backend SHALL 在 `ai_cache` 表新增 `status` 字段，支持四种状态：`valid`（有效）、`expired`（已过期）、`invalidated`（手动失效）、`generating`（生成中）
3. WHEN 写入新缓存前，THE Backend SHALL 将 `status` 设为 `generating`，写入完成后更新为 `valid`，防止并发读取到不完整数据
4. THE Backend SHALL 在查询缓存时仅返回 `status = 'valid'` 且未过期（`expires_at > now()` 或 `expires_at IS NULL`）的记录
5. THE Backend SHALL 对 App2~8 每个 App 保留最新 20,000 条 `ai_cache` 记录，超限时清理最旧记录；App1 对话记录不自动删除

### 需求 14：数据库变更

**用户故事：** 作为后端开发者，我希望新增必要的数据库表和字段，以便支持 AI 运行日志、事件调度记录、session_id 管理和缓存状态管理。

#### 验收标准

1. THE Backend SHALL 在 `biz` schema 新增 `ai_run_logs` 表，包含字段：`id`（BIGSERIAL PK）、`site_id`（BIGINT NOT NULL）、`app_type`（VARCHAR(30)）、`trigger_type`（VARCHAR(20)）、`member_id`（BIGINT 可空）、`request_prompt`（TEXT，截断前 2000 字符）、`response_text`（TEXT）、`tokens_used`（INTEGER）、`latency_ms`（INTEGER）、`status`（VARCHAR(20)）、`error_message`（TEXT）、`session_id`（VARCHAR(100)）、`created_at`（TIMESTAMPTZ）、`finished_at`（TIMESTAMPTZ）
2. THE Backend SHALL 在 `biz` schema 新增 `ai_trigger_jobs` 表，包含字段：`id`（BIGSERIAL PK）、`site_id`（BIGINT NOT NULL）、`event_type`（VARCHAR(30)）、`connector_type`（VARCHAR(30) 默认 `feiqiu`）、`member_id`（BIGINT 可空）、`payload`（JSONB）、`status`（VARCHAR(20)）、`is_forced`（BOOLEAN 默认 false）、`app_chain`（VARCHAR(100)）、`started_at`（TIMESTAMPTZ）、`finished_at`（TIMESTAMPTZ）、`error_message`（TEXT）、`created_at`（TIMESTAMPTZ）
3. THE Backend SHALL 在 `ai_conversations` 表新增 `session_id` 字段（VARCHAR(100)），用于存储百炼 session_id
4. THE Backend SHALL 在 `ai_cache` 表新增 `status` 字段（VARCHAR(20) 默认 `valid`），CHECK 约束限制为 `valid`/`expired`/`invalidated`/`generating`
5. THE Backend SHALL 为 `ai_run_logs` 创建索引：`(site_id, app_type)`、`(created_at)`、`(status)`
6. THE Backend SHALL 为 `ai_trigger_jobs` 创建索引：`(site_id, event_type)`、去重索引 `(event_type, member_id, site_id, created_at::date)` WHERE status NOT IN ('skipped_duplicate')、`(status)`
7. THE Backend SHALL 编写迁移脚本 `db/zqyy_app/migrations/YYYYMMDD_p14_ai_module.sql`，包含所有 DDL 变更，并编写对应的回滚脚本

### 需求 15：SSE 端点适配

**用户故事：** 作为助教用户，我希望 AI 对话的 SSE 流式端点能适配 DashScope Application API 的流式输出，以便继续获得逐字显示的对话体验。

#### 验收标准

1. THE Backend SHALL 适配 SSE 端点（`POST /api/xcx/chat/stream`），将 DashScope_Client 的 async generator 输出转换为 SSE 事件流
2. THE Backend SHALL 保持现有 SSE 事件格式不变：`event: message`（逐 token）、`event: done`（流结束）、`event: error`（错误）
3. WHEN DashScope_Client 流式调用过程中发生错误时，THE Backend SHALL 发送 `event: error` 事件并关闭连接，不导致客户端挂起
4. THE Backend SHALL 在流式调用完成后记录 `ai_run_logs`，包含 token 消耗和响应耗时

### 需求 16：AI 运行日志记录

**用户故事：** 作为系统管理员，我希望每次 AI 调用都有完整的运行日志，以便追踪调用状态、排查问题和统计 token 消耗。

#### 验收标准

1. THE Backend SHALL 在每次 Application API 调用前创建 `ai_run_logs` 记录（status: `pending`），调用开始时更新为 `running`
2. WHEN 调用成功时，THE Backend SHALL 更新 `ai_run_logs` 状态为 `success`，记录 `response_text`、`tokens_used`、`latency_ms`、`finished_at`
3. WHEN 调用失败时，THE Backend SHALL 更新 `ai_run_logs` 状态为 `failed`，记录 `error_message`、`latency_ms`、`finished_at`
4. WHEN 调用超时时，THE Backend SHALL 更新 `ai_run_logs` 状态为 `timeout`
5. WHEN 预算超限跳过执行时，THE Backend SHALL 创建 `ai_run_logs` 记录，状态为 `budget_exceeded`
6. THE Backend SHALL 将 `request_prompt` 截断为前 2000 字符后存储，避免大 prompt 占用过多存储空间