# 小维AI问答系统接口文档

## 1. /upload_qa

- **方法**: POST
- **描述**: 该端点用于上传问答文件。上传的文件可以是 `.txt`, `.md`, `.xls`, `.xlsx` 格式。系统会对上传的文件进行以下处理：
  - 文本分割：将大文本拆分为小段落以提高向量化的效率。
  - 向量化：使用嵌入模型将文本转化为向量。
  - 存储：将向量和元数据存储到数据库和本地向量文件中。
  - **异步处理**：若上传文件较大，处理可能耗时较长，任务会以异步方式执行，前端需通过 `/task_status/<task_id>` 查询任务状态。

- **请求参数**:
  - `token` (Header): 用户的身份验证令牌。
  - `method` (FormData): 上传操作的类型，如 `create` 或 `delete`。
  - `qa_name` (FormData): 问答库的名称。
  - `private_flag` (FormData): 问答库的私有标志（整数，1 表示私有，0 表示公开）。
  - `files` (FormData): 上传的文件列表。

- **返回值**:
  ```json
  {
    "code": 1,
    "message": "任务已提交",
    "task_id": "unique-task-id",
    "qa_name": "知识库名称",
    "time_left": "预计剩余时间（秒）"
  }
  ```

---

## 2. /operate_qa

- **方法**: POST
- **描述**: 该端点用于操作向量库，包括以下功能：
  - 查询问答库中的文件或内容。
  - 编辑现有问答记录。
  - 删除指定问答内容。
  - 新增问答记录。

- **请求参数**:
  - `token` (Header): 用户的身份验证令牌。
  - `method` (JSON): 操作类型，支持以下值：
    - `list_qa_files`: 列出问答库中的文件。
    - `list_qa_content`: 列出问答内容。
    - `query_qa_content`: 根据条件查询问答内容。
    - `edit_qa_content`: 编辑问答内容。
    - `delete_qa_content`: 删除指定问答内容。
    - `add_qa_content`: 新增问答内容。
  - `query_fields` (JSON): 查询条件字段（用于精确匹配）。
  - `fuzzy_fields` (JSON): 模糊查询字段（仅对 `query_qa_content` 有效）。
  - `edit_fields` (JSON): 编辑字段（仅对 `edit_qa_content` 有效）。

- **返回值**:
  ```json
  {
    "code": 1,
    "message": "操作成功",
    "records": [
      {
        "sys_id": "记录ID",
        "question": "问题内容",
        "answer": "回答内容",
        "qa_name": "知识库名称",
        "source": "来源文件名",
        "raw_text": "原始文本",
        "score": "相似度分数"
      }
    ]
  }
  ```

---

## 3. /chat_qa

- **方法**: POST
- **描述**: 用户可以通过该端点与问答系统进行交互。系统会根据用户输入的问题，从向量库中查找最相关的问答记录并返回结果。

- **请求参数**:
  - `token` (Header): 用户的身份验证令牌。
  - `qa_name` (JSON): 问答库的名称（支持多个）。
  - `query` (JSON): 用户输入的问题。
  - `uuid` (JSON): 用户会话的唯一标识符（可选）。

- **返回值**:
  ```json
  {
    "code": 1,
    "message": "问题答案",
    "qa_name": "相关知识库",
    "source": "来源文件名",
    "flag": true,
    "related_content": [
      {
        "question": "相关问题",
        "answer": "相关回答",
        "qa_name": "知识库名称",
        "source": "来源文件名",
        "score": "相似度分数"
      }
    ]
  }
  ```

---

## 4. /task_status/<task_id>

- **方法**: GET
- **描述**: 查询后台任务的状态。通过任务 ID 检查任务的执行情况。

- **请求参数**:
  - `task_id` (Path): 任务的唯一标识符。

- **返回值**:
  ```json
  {
    "code": 200,
    "message": "任务已完成",
    "status": "SUCCESS"
  }
  ```
  或：
  ```json
  {
    "code": 200,
    "message": "后台任务正在运行",
    "status": "PENDING"
  }
  ```

---

## 5. /change_question

- **方法**: POST
- **描述**: 用户可以通过该端点更改问题的内容，系统会返回相关的问答记录。

- **请求参数**:
  - `qa_name` (JSON): 问答库的名称（支持多个）。
  - `query` (JSON): 用户输入的问题。
  - `cur_page` (JSON): 当前页码（默认为 1）。

- **返回值**:
  ```json
  {
    "code": 1,
    "message": "",
    "flag": true,
    "related_content": [
      {
        "question": "相关问题",
        "answer": "相关回答",
        "qa_name": "知识库名称",
        "source": "来源文件名",
        "score": "相似度分数"
      }
    ],
    "question_counts": "相关问题总数",
    "cur_page": 1
  }
  ```

---

## 6. /default_answers

- **方法**: POST
- **描述**: 管理默认回答，包括新增、更新、删除和查询。

- **请求参数**:
  - `token` (Header): 用户的身份验证令牌。
  - `method` (JSON): 操作类型（`add`, `update`, `delete`, `list`）。
  - `qa_name` (JSON): 知识库的名称。
  - `answer` (JSON): 默认回答内容（新增或更新时必填）。
  - `keywords` (JSON): 关键字（可选）。

- **返回值**:
  ```json
  {
    "code": 1,
    "message": "操作成功",
    "data": [
      {
        "sys_id": "回答ID",
        "answer": "回答内容",
        "keywords": "相关关键字",
        "create_time": "创建时间"
      }
    ]
  }
  ```

---

## 7. /transfer_qa

- **方法**: POST
- **描述**: 将问答记录从一个知识库转移到另一个知识库。

- **请求参数**:
  - `token` (Header): 用户的身份验证令牌。
  - `target_qa` (JSON): 目标知识库的名称。
  - `qa_ids` (JSON): 要转移的问答记录 ID 列表。

- **返回值**:
  ```json
  {
    "code": 1,
    "message": "成功转移 3 条问答对",
    "data": {
      "transferred_records": [
        {
          "sys_id": "记录ID",
          "question": "问题",
          "answer": "答案",
          "source_qa": "源知识库"
        }
      ],
      "target_qa": "目标知识库"
    }
  }
  ```

---

## 8. /update_qa_fields

- **方法**: POST
- **描述**: 更新问答记录的字段。

- **请求参数**:
  - `token` (Header): 用户的身份验证令牌。
  - `sys_id` (JSON): 要更新的问答记录的 ID。
  - `answer_type` (JSON): 新的答案类型。
  - `category` (JSON): 新的分类。

- **返回值**:
  ```json
  {
    "code": 1,
    "message": "更新成功",
    "data": {
      "sys_id": "记录ID",
      "question": "问题",
      "answer_type": "新答案类型",
      "category": "新分类"
    }
  }
  ```

---

## 数据结构描述

### 数据库结构
- **Roles**: 用户角色表，包含角色 ID 和角色名称。
- **Users**: 用户表，包含用户 ID、账号、密码哈希和角色 ID。
- **QAKnowledge**: 问答知识库表，包含问题、答案、来源、知识库名称等。
- **DefaultAnswers**: 默认回答表，包含默认回答 ID、回答内容、关键字等。
- **DefaultAnswerConfig**: 默认回答配置表，包含配置的回答 ID 列表、随机使用标志等。

---

## 交互逻辑

1. **前端应用**: 用户通过前端应用发送请求。
2. **Java 服务**: 接收请求并调用本服务的 API。
3. **本服务**: 处理 API 请求并返回结果。
4. **数据库更新**: Java 服务和本服务分别更新其数据库。

```mermaid
graph TD;
A[前端应用] -->|发送请求| B[Java 服务]
B -->|处理请求| C[本服务]
C -->|返回结果| B
B -->|返回结果| A
A -->|用户输入| B
B -->|更新数据库| D[Java 服务数据库]
C -->|更新数据库| E[本服务数据库]
```

在上述代码中，涉及 **异步操作** 的部分主要集中在需要执行时间较长的任务，例如文件处理、向量化、模型预测等。以下是需要前端轮询 `task_status` 以获取任务完成状态的部分，以及每个部分的详细说明。

---

## **异步操作**
### 1. **`upload_qa` 方法的异步任务**
```python
future = executor.submit(add_qa_task_, upload_path, vs_path, create_id, private_flag, file_list, hash_list, qa_name)
tasks[task_id] = future
```

**描述**：
- 在 `upload_qa` 接口中，`add_qa_task_` 函数通过 `ThreadPoolExecutor` 异步执行。
- 该任务负责对上传的文件进行处理，包括文本加载、拆分、向量化、存储和数据库操作。
- 返回的 `task_id` 供前端使用，通过轮询 `/task_status/<task_id>` 获取任务进度。

**需要轮询字段**：
- `task_id`: 任务唯一标识。
- 状态值包括：
  - `PENDING`: 正在处理。
  - `SUCCESS`: 完成。
  - `ERROR`: 出错。

---

### 2. **`test_qa` 方法的异步任务**
```python
future = executor.submit(add_qa_task_, upload_path, vs_path, 3, False, file_list, hash_list, 'test')
tasks[task_id] = future
```

**描述**：
- 用于测试上传和处理文件的功能，逻辑与 `upload_qa` 类似。
- 前端需要通过 `task_id` 查询任务状态。

**需要轮询字段**：
- 同上，`task_id` 是关键字段。

---

### **通用异步任务的状态查询接口**
#### `task_status` 接口
```python
@app.route('/task_status/<task_id>', methods=['GET'])
def task_status(task_id):
    ...
    if task.done():
        ...
        ret_dict['status'] = "SUCCESS" if result else "ERROR"
    else:
        ret_dict['status'] = "PENDING"
```

**描述**：
- 通用接口，用于查询所有异步任务的状态。
- 返回值 `status` 表示任务的当前状态：
  - `PENDING`: 任务尚未完成。
  - `SUCCESS`: 任务成功完成。
  - `ERROR`: 任务失败。

---

### **轮询场景详细说明**
1. **轮询间隔**：
   - 前端每隔 1-2 秒向 `/task_status/<task_id>` 发起一次请求。
   - 使用任务完成 (`SUCCESS` 或 `ERROR`) 的响应作为停止轮询的标志。

2. **任务完成后的操作**：
   - **任务成功 (`SUCCESS`)**：
     - 显示任务处理完成的消息。
     - 根据任务结果更新页面数据或触发后续操作。
   - **任务失败 (`ERROR`)**：
     - 显示失败原因，允许用户重新发起任务。

3. **接口使用示例**：
   - `GET /task_status/<task_id>`：
     - **请求参数**：`task_id`。
     - **响应示例**：
       ```json
       {
         "code": 200,
         "message": "后台任务已完成",
         "status": "SUCCESS"
       }
       ```

---