前端项目初始化提交

2026-06-03 13:16:30 +08:00
commit 0910ba9cbe
163 changed files with 110032 additions and 0 deletions
--- a/AI接口使用规范.md
+++ b/AI接口使用规范.md
@@ -0,0 +1,396 @@
+# AI接口使用规范
+
+## 1. 接口概览
+
+| 接口路径 | 方法 | 功能描述 |
+|---------|------|----------|
+| `/ai/chat/stream` | 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/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": "sess_123456",
+      "role": "user",
+      "content": "公司的出差补助标准是什么？",
+      "messageType": "text",
+      "isFinished": 1,
+      "createTime": "2026-04-21 09:00:00"
+    },
+    {
+      "id": 2,
+      "conversationId": "sess_123456",
+      "role": "assistant",
+      "content": "根据公司政策，出差补助标准如下：\n1. 一线城市：500元/天\n2. 二线城市：350元/天\n3. 三线城市：250元/天",
+      "messageType": "text",
+      "isFinished": 1,
+      "createTime": "2026-04-21 09:01:30"
+    }
+  ],
+  "total": 2,
+  "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
+
+---
+
+*本规范文档由系统自动生成，如有变更请以实际接口为准。*