docs: 重写 API 文档，参考 Dify 风格只保留 RAG 调用和知识库检索接口

jk-rag-platform/docs/API.md

@@ -1,4 +1,4 @@
-# API 接口文档
+# RAG 应用 API 接口文档
 
 **项目**: 建科小智开放平台
 **版本**: v3.8
@@ -6,460 +6,551 @@
 
 ---
 
-## 目录
+## 概述
 
-1. [认证 API](#认证-api)
-2. [应用管理 API](#应用管理-api)
-3. [知识库管理 API](#知识库管理-api)
-4. [文档管理 API](#文档管理-api)
-5. [切片管理 API](#切片管理-api)
-6. [审核管理 API](#审核管理-api)
-7. [首页统计 API](#首页统计-api)
-8. [修订工具 API](#修订工具-api)
+本文档介绍如何通过 API 调用 RAG 应用和知识库检索功能。
 
----
-
-## 认证 API
+### 基础信息
 
-### 1. 用户登录
-```
-POST /auth/login
-```
+- **Base URL**: `http://your-domain.com/bigmodel/api`
+- **认证方式**: API Key / Token
+- **数据格式**: JSON
 
-**请求参数**:
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| username | string | 是 | 用户名 |
-| password | string | 是 | 密码 |
-| code | string | 否 | 验证码 |
+### 认证方式
 
-**响应示例**:
-```json
-{
-    "code": 200,
-    "message": "登录成功",
-    "data": {
-        "token": "mock_token_xxx",
-        "refreshToken": "mock_refresh_token_xxx",
-        "expiresAt": 1234567890000,
-        "user": {
-            "id": "current_user",
-            "username": "zhangsan",
-            "realName": "张三",
-            "email": "zhangsan@jianke.com",
-            "department": "技术研发部",
-            "position": "高级开发工程师"
-        }
-    }
-}
-```
+在请求头中携带认证信息：
 
-### 2. 获取验证码
-```
-GET /auth/code?phone=xxx&email=xxx
+```http
+Authorization: Bearer {your_token}
 ```
 
-**响应示例**:
-```json
-{
-    "code": 200,
-    "message": "验证码已发送",
-    "data": {
-        "debugCode": "1234",
-        "expiresInSeconds": 300
-    }
-}
-```
+或
 
-### 3. 获取用户信息
-```
-GET /system/user/getInfo
+```http
+X-API-Key: {your_api_key}
 ```
-**请求头**: `Authorization: Bearer {token}`
 
 ---
 
-## 应用管理 API
+## 应用调用接口
 
-### 1. 获取应用列表
-```
-POST /bigmodel/api/getApplicationList
+通过应用 ID 调用 RAG 应用，实现智能问答功能。
+
+### 发送对话消息
+
+向指定应用发送消息并获取回复。
+
+```http
+POST /chat/{appId}
 ```
 
-**请求参数**:
+**路径参数**:
+
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| pageNum | number | 否 | 页码，默认 1 |
-| pageSize | number | 否 | 每页条数，默认 10 |
-| category | string | 否 | 分类：professional/functional/project |
-| status | string | 否 | 状态：online/offline/auditing/rejected |
-| keyword | string | 否 | 搜索关键词 |
+| appId | string | 是 | RAG 应用 ID |
+
+**请求参数**:
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| query | string | 是 | - | 用户问题内容 |
+| conversationId | string | 否 | - | 会话 ID（用于多轮对话） |
+| userId | string | 否 | - | 用户 ID（用于区分不同用户） |
+| streaming | boolean | 否 | false | 是否使用流式响应 |
+
+**请求示例**:
+
+```bash
+curl -X POST http://your-domain.com/bigmodel/api/chat/app_001 \
+  -H "Authorization: Bearer your_token" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "如何申请年假？",
+    "userId": "user_123",
+    "streaming": false
+  }'
+```
+
+**响应示例**（非流式）:
 
-**响应示例**:
 ```json
 {
     "code": 200,
     "message": "success",
     "data": {
-        "list": [
+        "conversationId": "conv_abc123",
+        "answer": "申请年假的流程如下：\n\n1. 登录公司 OA 系统\n2. 进入\"请假申请\"页面\n3. 选择请假类型为\"年假\"\n4. 填写请假日期和天数\n5. 提交申请等待审批",
+        "sources": [
+            {
+                "documentId": "doc_001",
+                "documentName": "员工手册.pdf",
+                "sliceId": "slice_001",
+                "content": "员工年假申请需提前 3 个工作日在 OA 系统提交...",
+                "score": 0.92
+            },
             {
-                "id": "app_001",
-                "name": "合同审查助手",
-                "description": "基于 RAG 技术的智能合同审查与风险提示工具",
-                "category": "professional",
-                "status": "online",
-                "creatorId": "user_001",
-                "creator": "张三",
-                "maintainers": ["张三", "李四"],
-                "createdAt": "2025-12-15 10:30:00",
-                "updatedAt": "2026-01-05 14:20:00",
-                "knowledgeBaseCount": 3,
-                "conversationCount": 1250
+                "documentId": "doc_002",
+                "documentName": "考勤管理制度.pdf",
+                "sliceId": "slice_045",
+                "content": "年假天数根据工龄计算：1-3 年 5 天，3-5 年 10 天...",
+                "score": 0.85
             }
         ],
-        "total": 18,
-        "pageNum": 1,
-        "pageSize": 10
+        "usage": {
+            "promptTokens": 156,
+            "completionTokens": 89,
+            "totalTokens": 245
+        }
     }
 }
 ```
 
-### 2. 获取应用详情
-```
-GET /bigmodel/api/selectApplication/:id
-```
+**流式响应示例**:
 
-### 3. 创建应用
-```
-POST /bigmodel/api/createApplication
-```
+当 `streaming: true` 时，服务器会以 SSE (Server-Sent Events) 方式推送数据：
 
-**请求参数**:
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| name | string | 是 | 应用名称 |
-| description | string | 是 | 应用描述 |
-| category | string | 是 | 应用分类 |
-| knowledgeBaseIds | array | 否 | 关联的知识库 ID 列表 |
+```text
+data: {"answer": "申", "conversationId": "conv_abc123"}
 
-### 4. 更新应用
-```
-PUT /bigmodel/api/updateApplication/:id
-```
+data: {"answer": "请年假", "conversationId": "conv_abc123"}
+
+data: {"answer": "的流程如下：\n\n", "conversationId": "conv_abc123"}
+
+data: {"answer": "1. 登录 OA 系统", "conversationId": "conv_abc123"}
 
-### 5. 删除应用
+data: [DONE]
 ```
-DELETE /bigmodel/api/delApplication/:id
+
+**错误响应**:
+
+```json
+{
+    "code": 400,
+    "message": "应用不存在或已下线",
+    "data": null
+}
 ```
 
 ---
 
-## 知识库管理 API
+### 获取对话历史
 
-### 1. 获取知识库列表
-```
-POST /bigmodel/api/knowledgeList
-```
+获取指定会话的完整对话历史。
 
-### 2. 获取知识库详情
-```
-GET /bigmodel/api/detailKnowledge/:id
+```http
+GET /chat/{appId}/history/{conversationId}
 ```
 
-### 3. 创建知识库
-```
-POST /bigmodel/api/createKnowledge
-```
+**路径参数**:
 
-### 4. 更新知识库
-```
-PUT /bigmodel/api/updateKnowledge/:id
-```
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| appId | string | 是 | RAG 应用 ID |
+| conversationId | string | 是 | 会话 ID |
 
-### 5. 删除知识库
-```
-DELETE /bigmodel/api/delKnowledge/:id
-```
+**响应示例**:
 
-### 6. 获取 Embedding 列表
-```
-GET /bigmodel/api/embedding
+```json
+{
+    "code": 200,
+    "message": "success",
+    "data": {
+        "conversationId": "conv_abc123",
+        "appId": "app_001",
+        "userId": "user_123",
+        "createdAt": "2026-04-02 10:30:00",
+        "updatedAt": "2026-04-02 11:45:00",
+        "messages": [
+            {
+                "id": "msg_001",
+                "role": "user",
+                "content": "如何申请年假？",
+                "createdAt": "2026-04-02 10:30:00"
+            },
+            {
+                "id": "msg_002",
+                "role": "assistant",
+                "content": "申请年假的流程如下：\n\n1. 登录公司 OA 系统\n2. 进入\"请假申请\"页面...",
+                "createdAt": "2026-04-02 10:30:05",
+                "sources": [
+                    {
+                        "documentName": "员工手册.pdf",
+                        "content": "员工年假申请需提前 3 个工作日..."
+                    }
+                ]
+            },
+            {
+                "id": "msg_003",
+                "role": "user",
+                "content": "年假有多少天？",
+                "createdAt": "2026-04-02 10:31:00"
+            },
+            {
+                "id": "msg_004",
+                "role": "assistant",
+                "content": "年假天数根据工龄计算：\n- 1-3 年：5 天\n- 3-5 年：10 天\n- 5-10 年：15 天",
+                "createdAt": "2026-04-02 10:31:05"
+            }
+        ]
+    }
+}
 ```
 
 ---
 
-## 文档管理 API
+### 删除对话会话
 
-### 1. 获取文档列表
-```
-POST /bigmodel/api/documentList
-```
-
-### 2. 获取文档详情
-```
-GET /bigmodel/api/documentDetail/:id
-```
+删除指定的对话会话及其所有历史记录。
 
-### 3. 更新文档
-```
-PUT /bigmodel/api/updateDocument/:id
+```http
+DELETE /chat/{appId}/history/{conversationId}
 ```
 
-### 4. 删除文档
-```
-DELETE /bigmodel/api/delDocument/:id
-```
+**响应示例**:
 
-### 5. 上传文档
-```
-POST /bigmodel/api/uploadDocument/:knowledgeId
+```json
+{
+    "code": 200,
+    "message": "删除成功",
+    "data": {
+        "conversationId": "conv_abc123"
+    }
+}
 ```
 
-### 6. 获取文档设置
-```
-GET /bigmodel/api/documentSetting/:id
-```
+---
 
-### 7. 更新文档设置
-```
-PUT /bigmodel/api/updateDocumentSetting/:id
-```
+## 知识库检索接口
 
----
+直接调用知识库进行文档检索，不经过应用层。
 
-## 切片管理 API
+### 单一知识库检索
 
-### 1. 获取切片列表
-```
-POST /bigmodel/api/getSliceList
-```
+在单个知识库中进行语义检索。
 
-### 2. 获取切片详情
-```
-GET /bigmodel/api/getSliceDetail/:sliceId/:knowledgeId
+```http
+POST /knowledge/{knowledgeId}/search
 ```
 
-### 3. 添加切片
-```
-POST /bigmodel/api/add/slice
-```
+**路径参数**:
 
-### 4. 更新切片
-```
-PUT /bigmodel/api/updateSliceInfo
-```
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| knowledgeId | string | 是 | 知识库 ID |
 
-### 5. 删除切片
-```
-DELETE /bigmodel/api/deleteSlice/:sliceId/:knowledgeId/:documentId
-```
+**请求参数**:
 
----
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| query | string | 是 | - | 检索关键词或问题 |
+| topK | number | 否 | 5 | 返回结果数量（1-20） |
+| scoreThreshold | number | 否 | 0.5 | 相似度阈值（0-1） |
+| documentIds | array | 否 | - | 指定检索的文档 ID 列表 |
 
-## 审核管理 API
+**请求示例**:
 
-### 1. 获取审核列表
-```
-POST /deepseek/api/app/audit/list
+```bash
+curl -X POST http://your-domain.com/bigmodel/api/knowledge/kb_001/search \
+  -H "Authorization: Bearer your_token" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "年假申请流程",
+    "topK": 10,
+    "scoreThreshold": 0.7
+  }'
 ```
 
-**请求参数**:
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| pageNum | number | 否 | 页码，默认 1 |
-| pageSize | number | 否 | 每页条数，默认 10 |
-| status | string | 否 | 状态：pending/approved/rejected |
-| keyword | string | 否 | 搜索关键词 |
-
 **响应示例**:
+
 ```json
 {
     "code": 200,
     "message": "success",
     "data": {
-        "list": [
+        "knowledgeId": "kb_001",
+        "knowledgeName": "人力资源知识库",
+        "query": "年假申请流程",
+        "total": 5,
+        "results": [
+            {
+                "sliceId": "slice_001",
+                "documentId": "doc_001",
+                "documentName": "员工手册.pdf",
+                "content": "员工年假申请需提前 3 个工作日在 OA 系统提交申请，经部门经理审批后方可休假。",
+                "score": 0.92,
+                "metadata": {
+                    "pageNumber": 15,
+                    "position": "第 3 章 第 2 节"
+                }
+            },
             {
-                "id": "audit_001",
-                "appId": "app_006",
-                "appName": "安全生产管理系统",
-                "appDescription": "安全生产规范、应急预案、事故案例分析",
-                "creatorId": "user_006",
-                "creator": "孙八",
-                "department": "安全管理部",
-                "submitTime": "2026-01-16 15:45:00",
-                "auditStatus": "pending",
-                "auditor": null,
-                "auditTime": null,
-                "auditOpinion": null,
-                "knowledgeBaseCount": 4,
-                "documentCount": 28,
-                "sliceCount": 156
+                "sliceId": "slice_045",
+                "documentId": "doc_002",
+                "documentName": "考勤管理制度.pdf",
+                "content": "年假天数根据工龄计算：1-3 年 5 天，3-5 年 10 天，5-10 年 15 天，10 年以上 20 天。",
+                "score": 0.85,
+                "metadata": {
+                    "pageNumber": 8,
+                    "position": "第 2 章 第 5 条"
+                }
+            },
+            {
+                "sliceId": "slice_112",
+                "documentId": "doc_001",
+                "documentName": "员工手册.pdf",
+                "content": "未休年假可在当年申请折现，折现标准按日工资的 300% 计算。",
+                "score": 0.78,
+                "metadata": {
+                    "pageNumber": 16,
+                    "position": "第 3 章 第 3 节"
+                }
             }
-        ],
-        "total": 6,
-        "pageNum": 1,
-        "pageSize": 10
+        ]
     }
 }
 ```
 
-### 2. 获取审核详情
-```
-GET /deepseek/api/app/audit/detail/:id
-```
+---
 
-### 3. 审核操作
-```
-PUT /deepseek/api/app/audit/auditAction
+### 多知识库联合检索
+
+在多个知识库中进行联合语义检索。
+
+```http
+POST /knowledge/search
 ```
 
 **请求参数**:
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| auditId | string | 是 | 审核 ID |
-| action | string | 是 | 操作：approve/reject |
-| opinion | string | 是 | 审核意见 |
 
-### 4. 获取审核历史
-```
-POST /deepseek/api/app/auditHistory/list
-```
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| query | string | 是 | - | 检索关键词或问题 |
+| knowledgeIds | array | 是 | - | 知识库 ID 列表 |
+| topK | number | 否 | 5 | 每个知识库返回结果数量 |
+| scoreThreshold | number | 否 | 0.5 | 相似度阈值 |
+| rerank | boolean | 否 | false | 是否启用重排序 |
 
-### 5. 获取审核统计
-```
-GET /deepseek/api/app/audit/stats
+**请求示例**:
+
+```bash
+curl -X POST http://your-domain.com/bigmodel/api/knowledge/search \
+  -H "Authorization: Bearer your_token" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "项目报销流程",
+    "knowledgeIds": ["kb_001", "kb_003", "kb_005"],
+    "topK": 5,
+    "rerank": true
+  }'
 ```
 
 **响应示例**:
+
 ```json
 {
     "code": 200,
     "message": "success",
     "data": {
-        "total": 6,
-        "pending": 3,
-        "approved": 2,
-        "rejected": 1,
-        "pendingRate": "50.0",
-        "approvedRate": "33.3",
-        "rejectedRate": "16.7"
+        "query": "项目报销流程",
+        "knowledgeBaseCount": 3,
+        "total": 12,
+        "results": [
+            {
+                "knowledgeId": "kb_003",
+                "knowledgeName": "财务知识库",
+                "slices": [
+                    {
+                        "sliceId": "slice_201",
+                        "documentId": "doc_050",
+                        "documentName": "项目费用报销管理办法.pdf",
+                        "content": "项目报销流程：1. 填写报销单 2. 附上发票和明细 3. 项目经理审批 4. 财务审核 5. 出纳付款",
+                        "score": 0.95,
+                        "rerankScore": 0.98
+                    },
+                    {
+                        "sliceId": "slice_205",
+                        "documentId": "doc_050",
+                        "documentName": "项目费用报销管理办法.pdf",
+                        "content": "差旅费报销需提供往返交通票据和住宿发票，市内交通按每天 80 元包干。",
+                        "score": 0.82,
+                        "rerankScore": 0.85
+                    }
+                ]
+            },
+            {
+                "knowledgeId": "kb_001",
+                "knowledgeName": "人力资源知识库",
+                "slices": [
+                    {
+                        "sliceId": "slice_078",
+                        "documentId": "doc_015",
+                        "documentName": "员工福利手册.pdf",
+                        "content": "项目奖金发放与报销是独立的流程，奖金随工资发放，报销单独走财务流程。",
+                        "score": 0.71,
+                        "rerankScore": 0.72
+                    }
+                ]
+            }
+        ]
     }
 }
 ```
 
 ---
 
-## 首页统计 API
+### 获取知识库文档列表
 
-### 1. 获取概览数据
-```
-GET /deepseek/overview/topData
+获取指定知识库中的文档列表。
+
+```http
+GET /knowledge/{knowledgeId}/documents
 ```
 
+**查询参数**:
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| pageNum | number | 否 | 1 | 页码 |
+| pageSize | number | 否 | 20 | 每页数量 |
+| keyword | string | 否 | - | 文件名关键词 |
+
 **响应示例**:
+
 ```json
 {
     "code": 200,
     "message": "success",
     "data": {
-        "totalApps": 18,
-        "onlineApps": 14,
-        "auditingApps": 2,
-        "offlineApps": 2,
-        "totalKnowledgeBases": 45,
-        "totalDocuments": 328,
-        "totalSlices": 2156,
-        "totalConversations": 12580,
-        "todayConversations": 156,
-        "activeUsers": 89,
-        "pendingAudits": 3,
-        "conversationTrend": [...],
-        "categoryStats": [...],
-        "topApps": [...],
-        "recentActivities": [...]
+        "knowledgeId": "kb_001",
+        "knowledgeName": "人力资源知识库",
+        "total": 15,
+        "pageNum": 1,
+        "pageSize": 20,
+        "documents": [
+            {
+                "documentId": "doc_001",
+                "fileName": "员工手册.pdf",
+                "fileSize": 2048576,
+                "fileType": "pdf",
+                "status": "active",
+                "sliceCount": 45,
+                "createdAt": "2026-01-15 09:30:00",
+                "updatedAt": "2026-01-20 14:20:00"
+            },
+            {
+                "documentId": "doc_002",
+                "fileName": "考勤管理制度.pdf",
+                "fileSize": 1536000,
+                "fileType": "pdf",
+                "status": "active",
+                "sliceCount": 32,
+                "createdAt": "2026-01-16 10:00:00",
+                "updatedAt": "2026-01-22 11:30:00"
+            }
+        ]
     }
 }
 ```
 
-### 2. 获取在线用户数据
-```
-GET /deepseek/overview/onlineUserData
-```
-
-### 3. 获取会话数据
-```
-GET /deepseek/overview/conversationData
-```
-
 ---
 
-## 修订工具 API
-
-### 1. 获取修订列表
-```
-GET /deepseek/revise/pageList
-```
-
-### 2. 获取修订全部列表
-```
-GET /deepseek/revise/list
-```
-
-### 3. 获取修订切片列表
-```
-GET /deepseek/revise/sliceList
-```
-
-### 4. 提交修订切片
-```
-PUT /deepseek/revise/reviseSlice
-```
+## 错误码说明
 
-### 5. 获取修订历史
-```
-GET /deepseek/revise/reviseHistoryList
-```
+| 错误码 | 说明 |
+|--------|------|
+| 200 | 成功 |
+| 400 | 请求参数错误 |
+| 401 | 认证失败（Token 无效或过期） |
+| 403 | 无权限访问 |
+| 404 | 资源不存在（应用/知识库不存在） |
+| 429 | 请求频率超限 |
+| 500 | 服务器内部错误 |
 
 ---
 
-## 字典数据 API
+## 使用示例
 
-### 1. 标准分类
-```
-GET /deepseek/api/standard_classification
-```
-
-### 2. 解析类型
-```
-GET /deepseek/api/parsing_type
-```
+### Python 示例
 
-### 3. 分割类型
-```
-GET /deepseek/api/splitting_type
-```
+```python
+import requests
 
-### 4. 修订状态
-```
-GET /deepseek/api/revision_status
-```
+BASE_URL = "http://your-domain.com/bigmodel/api"
+TOKEN = "your_token"
 
----
+headers = {
+    "Authorization": f"Bearer {TOKEN}",
+    "Content-Type": "application/json"
+}
 
-## 聊天记录 API
+# 调用 RAG 应用
+response = requests.post(
+    f"{BASE_URL}/chat/app_001",
+    headers=headers,
+    json={
+        "query": "如何申请年假？",
+        "userId": "user_123"
+    }
+)
+result = response.json()
+print(result["data"]["answer"])
+
+# 知识库检索
+response = requests.post(
+    f"{BASE_URL}/knowledge/kb_001/search",
+    headers=headers,
+    json={
+        "query": "年假申请流程",
+        "topK": 5
+    }
+)
+result = response.json()
+for item in result["data"]["results"]:
+    print(f"[{item['score']:.2f}] {item['content']}")
+```
+
+### JavaScript 示例
+
+```javascript
+const BASE_URL = 'http://your-domain.com/bigmodel/api';
+const TOKEN = 'your_token';
+
+const headers = {
+    'Authorization': `Bearer ${TOKEN}`,
+    'Content-Type': 'application/json'
+};
+
+// 调用 RAG 应用
+async function chat(appId, query, userId) {
+    const response = await fetch(`${BASE_URL}/chat/${appId}`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ query, userId })
+    });
+    const result = await response.json();
+    return result.data.answer;
+}
 
-### 1. 获取聊天记录列表
-```
-POST /bigmodel/api/chatHistory/list
-```
+// 知识库检索
+async function searchKnowledge(knowledgeId, query, topK = 5) {
+    const response = await fetch(`${BASE_URL}/knowledge/${knowledgeId}/search`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ query, topK })
+    });
+    const result = await response.json();
+    return result.data.results;
+}
 
-### 2. 导出聊天记录
-```
-POST /bigmodel/api/dialog/export/:id
+// 使用示例
+chat('app_001', '如何申请年假？', 'user_123')
+    .then(answer => console.log(answer));
 ```
 
 ---
 
 **备注**:
-- 所有 API 的 Mock 数据位于 `src/mock/` 目录下
+- 所有接口的 Mock 数据位于 `src/mock/` 目录下
 - 在 `src/apis/api.ts` 中通过 `USE_MOCK` 标志切换 Mock/真实 API
+- 生产环境请关闭 Mock 模式