# AI接口规范文档

## 1. 接口概览

| 接口路径 | 方法 | 功能描述 |
|---------|------|----------|
| `/ai/chat/stream` | POST | AI流式问答，实时返回处理过程 |
| `/ai/chat/stop` | POST | 中断指定会话的AI流式问答进程 |
| `/ai/sessions` | GET | 获取用户会话列表，支持分页 |
| `/ai/session/{sessionId}` | GET | 获取指定会话的完整交互记录 |
| `/ai/message/{messageId}/references` | GET | 获取指定消息的引用信息 |
| `/ai/session/{sessionId}/references` | GET | 获取指定会话的所有引用信息 |
| `/ai/session/{sessionId}` | DELETE | 删除指定的会话及其相关信息 |
| `/ai/sessions` | DELETE | 批量删除多个会话及其相关信息 |

## 2. 认证方式

所有接口均需要在请求头中携带 `Authorization` 字段，格式为：

```
Authorization: Bearer {token}
```

其中 `{token}` 是用户登录后获取的JWT令牌。

## 3. 接口详情

### 3.1 AI流式问答接口

**接口路径**: `/ai/chat/stream`
**请求方法**: POST
**功能描述**: 向AI服务发起流式问答请求，实时返回处理过程，完成后自动保存到数据库

**请求参数**:
| 参数名 | 类型 | 必选 | 描述 |
|--------|------|------|------|
| message | String | 是 | 用户提问内容 |
| id | String | 否 | 请求ID，用于追踪请求 |
| session_id | String | 否 | 会话ID，若不提供则自动生成 |

**请求示例**:
```json
{
  "message": "公司的出差补助标准是什么？",
  "id": "req_123456",
  "session_id": "sess_123456"
}
```

**响应格式**: 流式SSE (Server-Sent Events)

**响应示例**:
```
event: message
data: {"type":"message","content":"根据公司政策，出差补助标准如下："}

event: message
data: {"type":"message","content":"1. 一线城市：500元/天"}

event: message
data: {"type":"message","content":"2. 二线城市：350元/天"}

event: message
data: {"type":"message","content":"3. 三线城市：250元/天"}

event: complete
data: {"type":"complete","message":"回答完成"}
```

**错误响应**:
```
event: error
data: {"type":"error","message":"用户未登录"}
```

### 3.2 中断AI流式问答接口

**接口路径**: `/ai/chat/stop`
**请求方法**: POST
**功能描述**: 中断指定会话的AI流式问答进程，用于用户主动取消正在进行的AI回答

**请求参数**:
| 参数名 | 类型 | 必选 | 描述 |
|--------|------|------|------|
| sessionId | String | 是 | 要中断的会话ID |

**请求示例**:
```
POST /ai/chat/stop?sessionId=sess_123456
```

**响应格式**:
```json
// 成功
{
  "success": true,
  "message": "已中断AI回答"
}

// 失败（进程不存在或已结束）
{
  "success": false,
  "message": "未找到活跃的AI进程或已结束"
}

// 错误响应
{
  "success": false,
  "message": "用户未登录"
}
```

**中断后SSE事件**:
当中断成功时，前端会收到一个特殊的stop事件：
```
event: stop
data: {"type":"stopped","message":"用户主动中断"}
```

**使用场景**:
- 用户等待AI回答时间过长，想取消当前问题
- 用户问错问题了，想重新提问
- AI回答跑偏了，想中断重新组织语言

### 3.3 获取用户会话列表接口

**接口路径**: `/ai/sessions`
**请求方法**: GET
**功能描述**: 获取当前登录用户的所有会话列表，按创建时间倒序排列

**请求参数**:
| 参数名 | 类型 | 必选 | 默认值 | 描述 |
|--------|------|------|--------|------|
| page | Integer | 否 | 1 | 页码 |
| pageSize | Integer | 否 | 10 | 每页大小 |

**请求示例**:
```
GET /ai/sessions?page=1&pageSize=10
```

**响应格式**:
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "sessionId": "sess_123456",
      "userId": 1,
      "summary": "用户询问公司政策相关问题",
      "createTime": "2026-04-21 09:00:00"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 10,
  "pages": 1
}
```

**错误响应**:
```json
{
  "success": false,
  "message": "用户未登录"
}
```

### 3.3 获取会话详情接口

**接口路径**: `/ai/session/{sessionId}`
**请求方法**: GET
**功能描述**: 获取指定会话的完整交互记录，包括用户提问与AI回答

**请求参数**:
| 参数名 | 类型 | 必选 | 默认值 | 描述 |
|--------|------|------|--------|------|
| sessionId | String | 是 | - | 会话ID |
| page | Integer | 否 | 1 | 页码 |
| pageSize | Integer | 否 | 20 | 每页大小 |

**请求示例**:
```
GET /ai/session/sess_123456?page=1&pageSize=20
```

**响应格式**:
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "conversationId": 1,
      "role": "assistant",
      "content": "公司的出差补助标准是什么？",
      "answer": "根据公司政策，出差补助标准如下：\n1. 一线城市：500元/天\n2. 二线城市：350元/天\n3. 三线城市：250元/天",
      "messageType": "text",
      "isFinished": 1,
      "kbPaths": "[\"public_kb\"]",
      "durationMs": 1250,
      "createTime": "2026-04-21 09:01:30"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 20,
  "pages": 1
}
```

**错误响应**:
```json
{
  "success": false,
  "message": "无权访问该会话"
}
```

### 3.4 获取消息引用信息接口

**接口路径**: `/ai/message/{messageId}/references`
**请求方法**: GET
**功能描述**: 获取指定消息的引用信息，包括文档来源、页码、片段内容等

**请求参数**:
| 参数名 | 类型 | 必选 | 描述 |
|--------|------|------|------|
| messageId | Long | 是 | 消息ID |

**请求示例**:
```
GET /ai/message/2/references
```

**响应格式**:
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "messageId": 2,
      "chunkId": "chunk_001",
      "docPath": "uploads/policies/travel_policy.pdf",
      "docName": "出差政策.pdf",
      "page": 10,
      "excerpt": "出差补助标准：一线城市500元/天，二线城市350元/天，三线城市250元/天。此标准适用于所有员工。",
      "createTime": "2026-04-21 09:01:30"
    }
  ],
  "total": 1
}
```

**错误响应**:
```json
{
  "success": false,
  "message": "用户未登录"
}
```

### 3.5 获取会话引用信息接口

**接口路径**: `/ai/session/{sessionId}/references`
**请求方法**: GET
**功能描述**: 获取指定会话的所有引用信息，包括文档来源、页码、片段内容等

**请求参数**:
| 参数名 | 类型 | 必选 | 描述 |
|--------|------|------|------|
| sessionId | String | 是 | 会话ID |

**请求示例**:
```
GET /ai/session/sess_123456/references
```

**响应格式**:
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "messageId": 2,
      "chunkId": "chunk_001",
      "docPath": "uploads/policies/travel_policy.pdf",
      "docName": "出差政策.pdf",
      "page": 10,
      "excerpt": "出差补助标准：一线城市500元/天，二线城市350元/天，三线城市250元/天。此标准适用于所有员工。",
      "createTime": "2026-04-21 09:01:30"
    }
  ],
  "total": 1
}
```

**错误响应**:
```json
{
  "success": false,
  "message": "无权访问该会话"
}
```

### 3.6 删除单个会话接口

**接口路径**: `/ai/session/{sessionId}`
**请求方法**: DELETE
**功能描述**: 删除指定的会话及其所有相关消息和引用信息

**请求参数**:
| 参数名 | 类型 | 必选 | 描述 |
|--------|------|------|------|
| sessionId | String | 是 | 会话ID |

**请求示例**:
```
DELETE /ai/session/sess_123456
```

**响应格式**:
```json
{
  "success": true,
  "message": "会话删除成功"
}
```

**错误响应**:
```json
{
  "success": false,
  "message": "无权删除该会话"
}
```

### 3.7 批量删除会话接口

**接口路径**: `/ai/sessions`
**请求方法**: DELETE
**功能描述**: 批量删除多个会话及其所有相关消息和引用信息

**请求参数**:
| 参数名 | 类型 | 必选 | 描述 |
|--------|------|------|------|
| sessionIds | List<String> | 是 | 会话ID列表 |

**请求示例**:
```json
[
  "sess_123456",
  "sess_789012"
]
```

**响应格式**:
```json
{
  "success": true,
  "message": "会话批量删除成功",
  "deletedCount": 2
}
```

**错误响应**:
```json
{
  "success": false,
  "message": "无权删除部分会话"
}
```

## 4. 权限控制

1. **用户认证**：所有接口均需要有效的JWT令牌
2. **会话访问权限**：用户只能访问和删除自己的会话
3. **批量操作验证**：批量删除时，所有会话必须都属于当前用户

## 5. 错误处理

| 错误类型 | 状态码 | 错误信息 | 说明 |
|---------|--------|----------|------|
| 未登录 | 401 | 用户未登录 | 缺少有效的Authorization头 |
| 无权限 | 403 | 无权访问该会话/无权删除该会话 | 会话不属于当前用户 |
| 参数错误 | 400 | 会话ID列表不能为空 | 请求参数不符合要求 |
| 服务器错误 | 500 | 操作失败: {具体错误信息} | 服务器内部错误 |

## 6. 最佳实践

1. **会话管理**：
   - 每次对话使用相同的session_id以保持上下文
   - 定期清理不需要的会话以节省存储空间

2. **请求优化**：
   - 使用分页参数减少返回数据量
   - 合理设置pageSize，避免一次请求过多数据

3. **错误处理**：
   - 捕获并处理接口返回的错误信息
   - 对网络异常和超时进行适当处理

4. **安全性**：
   - 不要在前端存储敏感的会话信息
   - 定期更新JWT令牌

## 7. 接口性能

1. **响应时间**：
   - 会话列表和详情接口：< 500ms
   - 引用信息接口：< 300ms
   - 删除接口：< 200ms

2. **并发处理**：
   - 支持同时处理多个请求
   - 流式接口采用SSE技术，支持长时间连接

3. **数据量限制**：
   - 单个会话最多存储1000条消息
   - 批量删除最多支持100个会话

## 8. 版本控制

| 版本 | 变更内容 | 发布日期 |
|------|----------|----------|
| v1.0 | 初始版本，包含基础AI对话功能 | 2026-04-25 |
| v1.1 | 新增会话管理和引用信息接口 | 2026-04-25 |

## 9. 联系支持

- **技术支持**：tech-support@example.com
- **API文档**：https://api.example.com/docs
- **服务状态**：https://status.example.com

---

*本规范文档由系统自动生成，如有变更请以实际接口为准。*