# AI 交互接口规范

## 核心原则

所有与 AI 模型交互的接口必须采用异步轮询模式，严禁前端同步等待 AI 响应。

## 接口模式

```
POST /api/xxx/start   →  立即返回 { genStage: 'xxx_generating' }
GET  /api/xxx/status   →  轮询返回 { genStage, result?, error? }
```

## 超时规范

| 接口类型 | 超时 | 说明 |
|----------|------|------|
| POST 启动接口 | 10s | 仅做参数校验 + 投递异步任务 |
| GET 轮询接口 | 5s | 查询数据库状态，不涉及 AI |
| 前端整体等待上限 | 600s | 超时后提示用户重试 |

## 状态流转

```
plan_generating  →  plan_ready     (Plan 生成完成)
                 →  plan_failed    (Plan 生成失败)

outline_generating → outline_ready (大纲生成完成)
                   → outline_failed (大纲生成失败)

generating_content → completed     (内容生成完成)
                   → failed        (内容生成失败)
```

## 实现要点

### 后端
- POST 端点在 `setImmediate` 中执行 AI 调用，不 `await`
- AI 结果写入数据库对应字段（bookAnalysis / outlineJson）
- 完成后更新 `genStage` 为 `xxx_ready`
- 失败时更新 `genStage` 为 `xxx_failed` + `errorMsg`

### 前端
- POST 后立即进入 `setInterval` 轮询，间隔 3s
- 收到 `xxx_ready` 后停止轮询，渲染结果
- 收到 `xxx_failed` 后显示错误，允许重试
- 超过 600s 整体上限后提示超时

## 禁止事项

- 禁止在 POST 端点中 `await` 异步 AI 调用
- 禁止前端设置超过 10s 的 POST 超时
- 禁止在轮询回调中重新 POST 启动新任务

## 已有交互式接口对照

| 步骤 | POST (启动) | GET (轮询) | 完成标记 |
|------|-------------|------------|----------|
| Step 2 Plan | `POST /books/:id/interactive/plan` | `GET /books/:id/interactive/plan` | `plan_ready` |
| Step 3 Outline | `POST /books/:id/interactive/outline` | `GET /books/:id/interactive/outline` | `outline_ready` |
| Step 4 Content | `POST /books/:id/interactive/generate` | `GET /books/:id/progress` | `progress >= 100` |