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

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

> 状态：Draft | 创建日期：2026-03-21 | 依赖：P5（AI 集成层）、RNS1.4（CHAT 对齐）
> 后续：P15（监控后台 + 测试重建 + 回填）

---

## 一、执行摘要

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

本 PRD 将 SDK 从 `openai` 切换到 `dashscope`（Application API），一步到位完成迁移，同时修复调度器、事件触发、熔断限流等核心问题。

### 问题来源

- `docs/reports/2026-03-21__ai_module_issues.md`（18 个问题：4 P0 / 6 P1 / 5 P2 / 3 P3）
- AI 全链路测试报告 + 86 项 Gap 审查

### 改动范围

| 模块 | 改动内容 |
|------|---------|
| `apps/backend/app/ai/` | SDK 替换、客户端重写、调度器修复 |
| `apps/backend/app/services/ai/` | 缓存服务、对话服务适配 |
| `apps/backend/app/routers/` | 内部触发 API、SSE 端点适配 |
| `apps/etl/connectors/feiqiu/` | DWS 完成后 HTTP 触发 |
| `db/zqyy_app/` | DDL 迁移（新增表、字段） |
| `.env` / `.env.template` | 环境变量统一 |

---

## 二、技术方案

### 2.1 SDK 替换：openai → dashscope Application API

**当前**：`openai.AsyncOpenAI` + `chat.completions.create`
**目标**：`dashscope.Application.call` + `asyncio.to_thread()` 包装

#### 调用方式对比

```python
# ===== 当前（错误）=====
from openai import AsyncOpenAI
client = AsyncOpenAI(api_key=key, base_url=bailian_url)
response = await client.chat.completions.create(
    model=model, messages=messages, response_format={"type": "json_object"}
)

# ===== 目标（正确）=====
import dashscope
from dashscope import Application

# App1 流式调用
response = Application.call(
    app_id=app_id,
    prompt=user_message,
    session_id=session_id,          # 云端对话管理
    biz_params={"user_prompt_params": {"User_ID": uid, "Role": role, "Nickname": name}},
    stream=True,
    incremental_output=True,
)

# App2~8 单轮调用
response = Application.call(
    app_id=app_id,
    prompt=data_json,               # 后端拼好的完整数据 JSON
)
```

#### async 包装

`dashscope.Application.call()` 是同步方法，当前后端全 async。采用 `asyncio.to_thread()` 包装：

```python
import asyncio

async def call_application(app_id: str, prompt: str, **kwargs) -> dict:
    return await asyncio.to_thread(
        Application.call,
        app_id=app_id,
        prompt=prompt,
        **kwargs
    )
```

流式调用（App1）需特殊处理：`Application.call(stream=True)` 返回同步迭代器，需在线程中消费后通过 `asyncio.Queue` 桥接到 async generator。

### 2.2 环境变量统一

**废弃**（本轮直接删除，不保留兼容）：
- `BAILIAN_API_KEY`
- `BAILIAN_BASE_URL`
- `BAILIAN_MODEL`

**新增**：
- `DASHSCOPE_API_KEY` — DashScope API Key
- `DASHSCOPE_WORKSPACE_ID` — 百炼工作空间 ID（可选）

**保留不变**（仅改前缀注释）：
| 旧变量 | 新变量 | 说明 |
|--------|--------|------|
| `BAILIAN_APP_ID_1_CHAT` | `DASHSCOPE_APP_ID_1_CHAT` | App1 通用对话 |
| `BAILIAN_APP_ID_2_FINANCE` | `DASHSCOPE_APP_ID_2_FINANCE` | App2 财务洞察 |
| `BAILIAN_APP_ID_3_CLUE` | `DASHSCOPE_APP_ID_3_CLUE` | App3 维客线索 |
| `BAILIAN_APP_ID_4_ANALYSIS` | `DASHSCOPE_APP_ID_4_ANALYSIS` | App4 关系分析 |
| `BAILIAN_APP_ID_5_TACTICS` | `DASHSCOPE_APP_ID_5_TACTICS` | App5 话术参考 |
| `BAILIAN_APP_ID_6_NOTE` | `DASHSCOPE_APP_ID_6_NOTE` | App6 备注分析 |
| `BAILIAN_APP_ID_7_CUSTOMER` | `DASHSCOPE_APP_ID_7_CUSTOMER` | App7 客户分析 |
| `BAILIAN_APP_ID_8_CONSOLIDATE` | `DASHSCOPE_APP_ID_8_CONSOLIDATE` | App8 维客线索整理 |

### 2.3 App1 对话管理：session_id 云端 + 本地双轨

**策略**：
1. 每次 App1 调用携带 `session_id`（百炼云端管理上下文）
2. 同时将消息写入本地 `ai_messages` 表（持久化）
3. `session_id` 过期（1 小时无请求）时，从本地 `ai_messages` 重建 `messages` 数组传给百炼
4. 对话复用规则不变：task 入口无时限复用、customer/coach 入口 3 天时限、general 入口始终新建

**session_id 生成规则**：
- 格式：`conv_{conversation_id}_{created_timestamp}`
- 存储在 `ai_conversations.session_id` 字段（新增）

**过期重建流程**：
```
用户发消息 → 查 ai_conversations 获取 session_id
  → 尝试用 session_id 调用百炼
    → 成功 → 正常返回
    → 失败（session 过期）→ 从 ai_messages 加载历史
      → 用 messages 数组（不带 session_id）调用百炼
      → 百炼返回新 session_id → 更新本地
```

### 2.4 App2~8 单轮调用

所有非对话类应用统一为单轮 `prompt` 调用：
- 后端用 `build_prompt()` 拼好完整数据 JSON
- 通过 `prompt` 参数传入 `Application.call`
- 百炼侧 System Prompt 已在控制台配置，代码不再维护

**JSON 兜底策略**：百炼返回非合法 JSON 时，纯重试，最大 3 次。不做本地解析修复。

### 2.5 App1 参数传递

App1 使用 `biz_params.user_prompt_params` 传模板变量：
- `User_ID`：用户 ID
- `Role`：角色（member / assistant / admin）
- `Nickname`：昵称

同时用 `prompt` 传页面上下文（source_page、page_context、screen_content）。

App2~8 不使用 `biz_params`，数据 JSON 直接作为 `prompt` 传入。

---

## 三、熔断 / 限流 / 降级

### 3.1 熔断器

```
连续 5 次失败 → 熔断 60 秒（所有请求直接返回降级响应）
→ 60 秒后进入半开状态 → 放行 1 个请求
  → 成功 → 关闭熔断
  → 失败 → 重新熔断 60 秒
```

熔断粒度：按 `app_id` 独立计数。App1 熔断不影响 App2~8。

### 3.2 Token 预算控制

| 维度 | 默认上限 | 说明 |
|------|---------|------|
| 日预算 | 100,000 tokens | 所有 App 合计 |
| 月预算 | 2,000,000 tokens | 所有 App 合计 |

超预算时：
- App1（用户对话）：返回友好提示"AI 服务今日额度已用完，请明天再试"
- App2~8（后台任务）：跳过执行，记录 `budget_exceeded` 状态

预算数据来源：`ai_run_logs.tokens_used` 按日/月聚合。

### 3.3 限流

- App1：每用户每分钟 10 次
- App2~8：每门店每小时 100 次（合计）

---

## 四、调度器修复

### 4.1 dispatcher.py asyncio 修复

当前问题：`dispatcher.py` 中存在 `asyncio.run()` 嵌套调用，在已有事件循环的 FastAPI 环境中会报错。

修复方案：
- 移除所有 `asyncio.run()` 调用
- 所有调度入口改为 `async def`
- 使用 `asyncio.create_task()` 发起异步任务
- 超时控制用 `asyncio.wait_for()`

### 4.2 事件触发打通

#### 消费事件（ETL 侧发射）

```
ETL DWS 任务完成
  → HTTP POST /api/internal/ai/trigger
    → payload: { event_type: "consumption", connector_type: "feiqiu", site_id, member_id, settlement_id }
  → 后端写 ai_trigger_jobs 记录
  → 异步执行调用链：App3 → App8 → App7（+ App4 → App5 如有助教）
```

内部 API 设计为连接器无关接口，`connector_type` 字段标识来源，为多平台扩展预留。

#### 备注事件（后端 API 路由发射）

```
小程序助教提交备注
  → 后端 API 路由 fire_event
    → event_type: "note_created"
  → 调用链：App6 → App8
```

#### 任务分配事件（task_manager 自动触发）

```
task_manager 自动分配任务
  → fire_event: "task_assigned"
  → 调用链：App4 → App5
```

### 4.3 App2 预生成

- 触发时机：DWS 完成后，ETL 通过内部 API 触发
- 门店范围：当前写死 `2790685415443269`（多门店支持记入 BACKLOG）
- 时间维度：8 个（今日/昨日/本周/上周/本月/上月/本季/上季）
- 每日调用量：1 门店 × 8 维度 = 8 次

### 4.4 幂等与去重

| 场景 | 策略 |
|------|------|
| 自动触发 | 按 `(event_type, member_id, site_id, date)` 去重，重复事件跳过 |
| 手动重跑 | 允许强制执行，`ai_trigger_jobs.is_forced = true`，后台明显标记 "forced" |
| App8 | 强幂等：DELETE + INSERT `member_retention_clue`，同一 member 同一天只执行一次 |

---

## 五、缓存策略

### 5.1 过期时间（按 App 分开）

| App | cache_type | expires_at 策略 |
|-----|-----------|----------------|
| App2 | app2_finance | 当日 23:59:59（每日刷新） |
| App3 | app3_clue | 7 天 |
| App4 | app4_analysis | 7 天 |
| App5 | app5_tactics | 7 天 |
| App6 | app6_note_analysis | 30 天 |
| App7 | app7_customer_analysis | 7 天 |
| App8 | app8_clue_consolidated | 7 天 |

### 5.2 ai_cache 新增字段

```sql
ALTER TABLE biz.ai_cache ADD COLUMN status VARCHAR(20) DEFAULT 'valid'
  CHECK (status IN ('valid', 'expired', 'invalidated', 'generating'));
```

- `valid`：有效缓存
- `expired`：已过期（定时任务标记）
- `invalidated`：手动失效（admin-web 操作）
- `generating`：正在生成中（防并发）

### 5.3 数据保留上限

| App | 保留策略 |
|-----|---------|
| App1 | 不自动删除（用户对话记录） |
| App2~8 | 每个 App 保留最新 20,000 条 `ai_cache` 记录 |

---

## 六、数据库变更

所有新表放在 `biz` schema。

### 6.1 新增表：ai_run_logs（AI 运行记录）

```sql
CREATE TABLE biz.ai_run_logs (
    id              BIGSERIAL PRIMARY KEY,
    site_id         BIGINT NOT NULL,
    app_type        VARCHAR(30) NOT NULL,       -- app1_chat / app2_finance / ...
    trigger_type    VARCHAR(20) NOT NULL,        -- user / scheduled / event / forced
    member_id       BIGINT,                      -- 关联会员（可空）
    request_prompt  TEXT,                        -- 输入 prompt（截断前 2000 字符）
    response_text   TEXT,                        -- 输出全文
    tokens_used     INTEGER DEFAULT 0,
    latency_ms      INTEGER,                     -- 响应耗时（毫秒）
    status          VARCHAR(20) NOT NULL DEFAULT 'pending',
                    -- pending / running / success / failed / timeout / budget_exceeded
    error_message   TEXT,
    session_id      VARCHAR(100),                -- App1 百炼 session_id
    created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
    finished_at     TIMESTAMPTZ
);

CREATE INDEX idx_ai_run_logs_site_app ON biz.ai_run_logs(site_id, app_type);
CREATE INDEX idx_ai_run_logs_created ON biz.ai_run_logs(created_at);
CREATE INDEX idx_ai_run_logs_status ON biz.ai_run_logs(status);
```

### 6.2 新增表：ai_trigger_jobs（调度运行记录）

```sql
CREATE TABLE biz.ai_trigger_jobs (
    id              BIGSERIAL PRIMARY KEY,
    site_id         BIGINT NOT NULL,
    event_type      VARCHAR(30) NOT NULL,        -- consumption / note_created / task_assigned / scheduled / manual
    connector_type  VARCHAR(30) DEFAULT 'feiqiu', -- 连接器类型（多平台预留）
    member_id       BIGINT,
    payload         JSONB,                       -- 事件原始数据
    status          VARCHAR(20) NOT NULL DEFAULT 'pending',
                    -- pending / running / completed / failed / skipped_duplicate / budget_exceeded
    is_forced       BOOLEAN DEFAULT false,       -- 手动强制执行标记
    app_chain       VARCHAR(100),                -- 执行链：如 "app3→app8→app7"
    started_at      TIMESTAMPTZ,
    finished_at     TIMESTAMPTZ,
    error_message   TEXT,
    created_at      TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE INDEX idx_ai_trigger_jobs_site ON biz.ai_trigger_jobs(site_id, event_type);
CREATE INDEX idx_ai_trigger_jobs_dedup ON biz.ai_trigger_jobs(event_type, member_id, site_id, (created_at::date))
    WHERE status NOT IN ('skipped_duplicate');
CREATE INDEX idx_ai_trigger_jobs_status ON biz.ai_trigger_jobs(status);
```

### 6.3 ai_conversations 新增字段

```sql
ALTER TABLE biz.ai_conversations ADD COLUMN session_id VARCHAR(100);
```

### 6.4 ai_cache 新增字段

```sql
ALTER TABLE biz.ai_cache ADD COLUMN status VARCHAR(20) DEFAULT 'valid'
    CHECK (status IN ('valid', 'expired', 'invalidated', 'generating'));
```

---

## 七、内部 API 设计

### 7.1 ETL → 后端触发接口

```
POST /api/internal/ai/trigger
Authorization: Internal-Token {INTERNAL_API_TOKEN}
Content-Type: application/json

{
    "event_type": "consumption",        // consumption / dws_completed
    "connector_type": "feiqiu",
    "site_id": 2790685415443269,
    "member_id": 12345,                 // 可选
    "payload": {                        // 事件附加数据
        "settlement_id": "xxx",
        "dws_task": "DWS_MEMBER_CONSUMPTION"
    }
}

Response 200:
{
    "trigger_job_id": 1001,
    "status": "pending"
}
```

### 7.2 认证方式

内部 API 使用独立的 `INTERNAL_API_TOKEN` 环境变量，不走 JWT。ETL 进程通过 HTTP Header 传递。

---

## 八、文件变更清单

### 需要重写的文件
| 文件 | 说明 |
|------|------|
| `apps/backend/app/ai/bailian_client.py` | 完全重写为 `dashscope_client.py` |
| `apps/backend/app/ai/dispatcher.py` | asyncio 修复 + 事件触发链 |
| `apps/backend/app/ai/config.py` | 环境变量 BAILIAN_* → DASHSCOPE_* |

### 需要新增的文件
| 文件 | 说明 |
|------|------|
| `apps/backend/app/ai/circuit_breaker.py` | 熔断器实现 |
| `apps/backend/app/ai/rate_limiter.py` | 限流器实现 |
| `apps/backend/app/ai/budget_tracker.py` | Token 预算追踪 |
| `apps/backend/app/routers/internal_ai.py` | 内部触发 API 路由 |
| `db/zqyy_app/migrations/YYYYMMDD_ai_run_logs.sql` | DDL 迁移脚本 |

### 需要修改的文件
| 文件 | 说明 |
|------|------|
| `apps/backend/app/services/ai/cache_service.py` | 新增 status 字段处理 |
| `apps/backend/app/services/ai/chat_service.py` | session_id 双轨逻辑 |
| `apps/etl/connectors/feiqiu/tasks/` | DWS 完成后 HTTP 触发 |
| `.env` / `.env.template` | 环境变量更新 |
| `pyproject.toml` | 依赖：移除 openai，新增 dashscope |

---

## 九、问题修复映射

本 PRD 覆盖的问题（来自 `docs/reports/2026-03-21__ai_module_issues.md`）：

| 问题编号 | 优先级 | 描述 | 本 PRD 对应章节 |
|---------|--------|------|----------------|
| P0-1 | P0 | App3~8 JSON 格式化失败 | §2.4（Application API 原生支持） |
| P0-2 | P0 | AI 事件未触发 | §4.2（事件触发打通） |
| P0-3 | P0 | App2 无定时机制 | §4.3（App2 预生成） |
| P0-4 | P0 | ETL→AI 联动断裂 | §4.2 + §7.1（内部 API） |
| P1-1 | P1 | 缓存过期未检查 | §5（缓存策略） |
| P1-2 | P1 | 无限流/熔断 | §3（熔断/限流/降级） |
| P1-3 | P1 | 无 Token 预算控制 | §3.2（Token 预算） |
| P1-4 | P1 | dispatcher asyncio 问题 | §4.1（asyncio 修复） |
| P1-5 | P1 | 前端无刷新机制 | 不在本 PRD 范围（前端改动） |
| P1-6 | P1 | FDW 数据获取不一致 | 不在本 PRD 范围（数据层） |
| P2-3 | P2 | 缓存清理过宽松 | §5.3（保留上限） |
| P2-5 | P2 | 对话记录无清理 | §5.3（App1 不删，其他 2 万条） |
| P3-1 | P3 | 迁移 DashScope SDK | §2.1（核心改动） |
| P3-2 | P3 | 调度器独立化 | §4（调度器修复） |

---

## 十、收尾标准流程

> 参考历史 Spec 收尾模板（P5、P13、RNS1.4）

### 10.1 DDL 迁移

1. 编写迁移脚本 `db/zqyy_app/migrations/YYYYMMDD_p14_ai_module.sql`
2. 在测试库 `test_zqyy_app` 执行并验证
3. 编写回滚脚本（逆序 DROP）
4. 合并到 DDL 基线 `db/zqyy_app/ddl/`

### 10.2 BD 手册更新

- 更新 `docs/database/BD_Manual_ai_tables.md`：新增 `ai_run_logs`、`ai_trigger_jobs` 表结构
- 更新 `ai_cache` 的 `status` 字段说明
- 更新 `ai_conversations` 的 `session_id` 字段说明

### 10.3 文档同步

| 文档 | 更新内容 |
|------|---------|
| `docs/prd/ai-app-prompts.md` | 环境变量映射更新（BAILIAN_* → DASHSCOPE_*） |
| `apps/backend/README.md` | AI 模块架构说明更新 |
| `docs/DOCUMENTATION-MAP.md` | 新增文档条目 |
| `.env.template` | 环境变量模板更新 |
| `docs/deployment/EXPORT-PATHS.md` | 如有新输出路径则更新 |

### 10.4 属性测试

- 更新 `tests/` 下 AI 相关属性测试，适配新的 `dashscope` 调用方式
- 新增属性测试覆盖：熔断器状态转换、Token 预算计算、去重逻辑

### 10.5 最终检查点

- [ ] 所有 8 个 App 通过 Application API 调用成功
- [ ] App1 流式输出正常，session_id 双轨工作
- [ ] App2~8 返回合法 JSON
- [ ] 事件触发链完整（消费→App3→App8→App7）
- [ ] ETL → 后端内部 API 联通
- [ ] 熔断器在连续失败后正确触发
- [ ] Token 预算超限后正确降级
- [ ] 环境变量全部切换到 DASHSCOPE_*
- [ ] DDL 迁移脚本在测试库执行通过
- [ ] BD 手册已更新
- [ ] 属性测试全部通过

---

## 十一、风险与缓解

| 风险 | 影响 | 缓解措施 |
|------|------|---------|
| DashScope SDK 同步调用阻塞事件循环 | App1 响应延迟 | `asyncio.to_thread()` + 线程池大小限制 |
| session_id 过期重建增加 token 消耗 | 成本上升 | 限制重建时的历史消息条数（最近 20 条） |
| 百炼控制台 System Prompt 与代码不一致 | 输出质量下降 | 代码不再维护 System Prompt，以控制台为准 |
| 环境变量一步切换导致部署遗漏 | 服务不可用 | 部署检查清单 + 启动时校验必需变量 |
| App8 写业务表（member_retention_clue）幂等失败 | 数据不一致 | 事务包裹 DELETE + INSERT，失败自动回滚 |

---

## 十二、不在本 PRD 范围

以下内容由 P15 或后续 PRD 处理：

- admin-web AI 监控后台（P15）
- 全链路测试重建（P15）
- 历史回填（P15）
- 旧测试脚本归档（P15）
- 多门店支持（BACKLOG）
- 消息队列（单独 PRD）
- Prompt 版本管理（BACKLOG）
- 前端刷新机制（P1-5，前端改动）
- FDW 数据一致性（P1-6，数据层改动）