# Dify 模块 API 接口文档

> 版本：2.3
> 更新时间：2025-01-22
> 基础路径：`/api/v3`


---

## 目录


1. [概述](#概述)
2. [权限说明](#权限说明)
3. [安全设计](#安全设计)
4. [地区知识库管理接口](#地区知识库管理接口)
   - [获取当前用户可访问的知识库](#1-获取当前用户可访问的知识库)
   - [获取所有知识库绑定列表](#2-获取所有知识库绑定列表管理员)
   - [获取可用地区列表](#3-获取可用地区列表)
   - [获取知识库绑定详情](#4-获取知识库绑定详情)
   - [创建知识库绑定](#5-创建知识库绑定)

- [更新知识库绑定](#6-更新知识库绑定)
  - [删除知识库绑定](#7-删除知识库绑定)
  - [检查用户知识库访问权限](#8- [对话应用管理接口](#9-检查用户知识库访问权限)
  - [获取可用的对话应用列表](#9-获取可用的对话应用列表)
  - [获取默认对话应用](#10-获取默认对话应用)


5. [对话应用多实例支持](#对话应用多实例支持)
   - [配置方式](#配置方式)
   - [前端切换应用](#前端切换应用)
   - [端口多实例特性](#端口多实例特性)
6. [错误码说明](#错误码说明)
   - [接口说明](#接口说明)
7. [数据字典](#数据字典)


---

## 概述

Dify 模块提供 AI 对话和知识库管理功能。本文档主要描述**地区-知识库绑定管理**相关接口。

### 核心概念

|概念 |说明 |
|---|---|
|**地区（area）** |用户所属地区，如：梅州、云浮、揭阳、潮州 |
|**知识库绑定** |将 Dify 平台的知识库与特定地区关联，控制用户可访问的知识库范围 |
|**公共知识库** |`is_public=true` 的知识库，所有地区用户均可访问（如省级知识库） |
|**默认知识库** |`is_default=true` 的知识库，该地区用户的首选知识库 |

### 业务规则


1. **普通用户（common）只能访问**本地区绑定的知识库 + **公共知识库**
2. **市级管理员（admin）只能访问**本地区绑定的知识库 + **公共知识库**，可编辑本地区知识库内容
3. **省级管理员（provincial_admin）可以访问和管理**所有地区的知识库
4. 只有**省级管理员**可以管理知识库绑定（增删改查绑定关系）
5. 同一地区不能重复绑定同一知识库
6. 删除为软删除，可恢复


---

## 权限说明

### 权限键定义（无通配符）

|权限键 |说明 |适用角色 |
|---|---|---|
|`dify:chat:use` |使用 AI 对话 |common, provincial_admin, admin |
|`dify:conversation:read` |查看对话历史（仅自己） |common, provincial_admin, admin |
|`dify:conversation:delete` |删除对话（仅自己） |common, provincial_admin, admin |
|`dify:message:feedback` |消息反馈 |common, provincial_admin, admin |
|`dify:dataset:read` |查看知识库列表 |common, admin, provincial_admin |
|`dify:dataset:write` |编辑知识库内容 |admin（仅本地区）, provincial_admin（全部） |
|`dify:dataset:manage` |管理知识库绑定（增删改查） |provincial_admin（仅省级管理员） |
|`dify:file:read` |下载/预览文件 |common, provincial_admin, admin |
|`dify:file:upload` |上传文件 |common, provincial_admin, admin |

### 角色权限矩阵

|接口 |common |admin（市级管理员） |provincial_admin（省级管理员） |
|---|---|---|---|
|获取用户可访问的知识库 |✅ 本地区+公共 |✅ 本地区+公共 |✅ 全部 |
|编辑知识库内容 |❌ |✅ 仅本地区 |✅ 全部 |
|获取所有绑定列表（管理） |❌ |❌ |✅ |
|创建/更新/删除绑定 |❌ |❌ |✅ |
|检查访问权限 |✅ |✅ |✅ |

### 数据范围说明

|数据范围 |代码值 |说明 |
|---|---|---|
|全部 |`ALL` |可访问所有地区数据（仅 provincial_admin） |
|本地区 |`DEPT` |只能访问本地区数据 + 公共数据（common, admin） |
|仅自己 |`SELF` |只能操作自己的数据（对话历史） |


---

## 安全设计

### 1. 对话数据越权防护

**问题**：用户 A 不能查看/删除用户 B 的对话

**解决方案**：


1. **Dify 端隔离**：请求时强制注入 `user` 参数为当前登录用户的 `username`，无法伪造
2. **本地数据库隔离**：`dify_conversation` 表的操作都带 `user_id` 条件

```sql
-- 删除对话时的 SQL
UPDATE dify_conversation
SET deleted_at = CURRENT_TIMESTAMP
WHERE user_id = $1 AND conversation_id = $2  -- 必须是自己的
```

### 2. 知识库数据范围控制

**问题**：普通用户和市级管理员不能访问其他地区的知识库

**解决方案**：

```python
# 根据用户角色控制数据范围
if user_role == "provincial_admin":
    # 仅省级管理员返回所有知识库
else:
    # 市级管理员和普通用户：只返回本地区 + 公共知识库
    WHERE area = {user_area} OR is_public = true
```

### 3. 请求伪造防护

**问题**：用户伪造请求参数访问他人数据

**解决方案**：

- 所有用户身份信息从 JWT Token 解析，不信任请求参数
- `user` 参数强制覆盖，不允许前端传入

```python
# process_request_body 中
body_data['user'] = username  # 强制使用当前用户
```


---

## 地区知识库管理接口

### 1. 获取当前用户可访问的知识库

根据当前登录用户的地区和角色，返回可访问的知识库列表。

**请求**

```
GET /api/v3/dify/area-datasets/my
```

**请求头**

|参数 |类型 |必填 |说明 |
|---|---|---|---|
|Authorization |string |是 |Bearer {token} |

**数据范围控制**

|角色 |返回数据 |
|---|---|
|common（普通员工） |用户所属地区的知识库 + 公共知识库 |
|admin（市级管理员） |用户所属地区的知识库 + 公共知识库 |
|provincial_admin（省级管理员） |所有地区的知识库 |

**响应**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "data": [
      {
        "id": 1,
        "area": "省级",
        "dataset_id": "fd680642-4493-416b-b592-972c69b3f595",
        "dataset_name": "省级法务知识库",
        "dataset_description": "全省通用法务知识库",
        "is_default": false,
        "is_public": true,
        "sort_order": 0,
        "status": 1,
        "created_at": "2025-01-22T10:00:00",
        "updated_at": "2025-01-22T10:00:00"
      },
      {
        "id": 2,
        "area": "梅州",
        "dataset_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
        "dataset_name": "梅州法务知识库",
        "dataset_description": "梅州地区专用知识库",
        "is_default": true,
        "is_public": false,
        "sort_order": 10,
        "status": 1,
        "created_at": "2025-01-22T10:30:00",
        "updated_at": "2025-01-22T10:30:00"
      }
    ],
    "total": 2,
    "user_area": "梅州",
    "user_role": "common"
  }
}
```

**响应字段说明**

|字段 |类型 |说明 |
|---|---|---|
|data.data |array |知识库列表 |
|data.total |int |知识库总数 |
|data.user_area |string |当前用户所属地区 |
|data.user_role |string |当前用户角色 |

**错误响应**

|HTTP 状态码 |错误信息 |说明 |
|---|---|---|
|400 |用户未设置地区，无法获取知识库列表 |用户 area 字段为空（非管理员） |
|401 |JWT 认证失败 |Token 无效或过期 |
|403 |Permission denied |无 `dify:dataset:read` 权限 |


---

### 2. 获取所有知识库绑定列表（管理员）

获取系统中所有地区的知识库绑定记录，支持按地区筛选和分页。

**权限要求**：`dify:dataset:manage`（仅 provincial_admin）

**请求**

```
GET /api/v3/dify/area-datasets
```

**请求头**

|参数 |类型 |必填 |说明 |
|---|---|---|---|
|Authorization |string |是 |Bearer {token} |

**查询参数**

|参数 |类型 |必填 |默认值 |说明 |
|---|---|---|---|---|
|area |string |否 |- |筛选地区，如：梅州 |
|only_enabled |boolean |否 |true |是否只返回启用的记录 |
|page |int |否 |1 |页码，从 1 开始 |
|page_size |int |否 |20 |每页数量，范围 1-100 |

**请求示例**

```bash
curl -X GET "http://localhost:8000/api/v3/dify/area-datasets?area=梅州&page=1&page_size=20" \
  -H "Authorization: Bearer {token}"
```

**响应**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "data": [
      {
        "id": 2,
        "area": "梅州",
        "dataset_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
        "dataset_name": "梅州法务知识库",
        "dataset_description": "梅州地区专用知识库",
        "is_default": true,
        "is_public": false,
        "sort_order": 10,
        "status": 1,
        "created_by": 1,
        "created_at": "2025-01-22T10:30:00",
        "updated_by": null,
        "updated_at": "2025-01-22T10:30:00"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20,
    "has_more": false
  }
}
```


---

### 3. 获取可用地区列表

获取系统中所有可用的地区列表，用于管理员创建绑定时选择地区。

**权限要求**：`dify:dataset:manage`

**请求**

```
GET /api/v3/dify/area-datasets/areas
```

**响应**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "data": ["云浮", "揭阳", "梅州", "潮州"]
  }
}
```


---

### 4. 获取知识库绑定详情

根据绑定记录 ID 获取详情。

**权限要求**：`dify:dataset:manage`

**请求**

```
GET /api/v3/dify/area-datasets/{dataset_bind_id}
```

**路径参数**

|参数 |类型 |必填 |说明 |
|---|---|---|---|
|dataset_bind_id |int |是 |绑定记录 ID |

**响应**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "data": {
      "id": 2,
      "area": "梅州",
      "dataset_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "dataset_name": "梅州法务知识库",
      "dataset_description": "梅州地区专用知识库",
      "is_default": true,
      "is_public": false,
      "sort_order": 10,
      "status": 1,
      "created_by": 1,
      "created_at": "2025-01-22T10:30:00",
      "updated_by": null,
      "updated_at": "2025-01-22T10:30:00"
    }
  }
}
```


---

### 5. 创建知识库绑定

将 Dify 知识库绑定到指定地区。

**权限要求**：`dify:dataset:manage`

**请求**

```
POST /api/v3/dify/area-datasets
```

**请求体**

|参数 |类型 |必填 |默认值 |说明 |
|---|---|---|---|---|
|area |string |是 |- |地区名称（1-50字符） |
|dataset_id |string |是 |- |Dify 知识库 ID（1-100字符） |
|dataset_name |string |是 |- |知识库名称（1-255字符） |
|dataset_description |string |否 |null |知识库描述 |
|is_default |boolean |否 |false |是否为该地区默认知识库 |
|is_public |boolean |否 |false |是否对所有地区公开 |
|sort_order |int |否 |0 |排序顺序，越小越靠前 |

**请求示例**

```bash
curl -X POST "http://localhost:8000/api/v3/dify/area-datasets" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "area": "梅州",
    "dataset_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "dataset_name": "梅州法务知识库",
    "dataset_description": "梅州地区专用知识库",
    "is_default": true,
    "is_public": false,
    "sort_order": 10
  }'
```

**响应**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "data": {
      "id": 2,
      "area": "梅州",
      "dataset_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "dataset_name": "梅州法务知识库",
      "dataset_description": "梅州地区专用知识库",
      "is_default": true,
      "is_public": false,
      "sort_order": 10,
      "status": 1,
      "created_at": "2025-01-22T10:30:00"
    },
    "message": "创建成功"
  }
}
```

**错误响应**

|HTTP 状态码 |错误信息 |说明 |
|---|---|---|
|400 |地区 '梅州' 已绑定知识库 'xxx' |重复绑定 |
|422 |Validation Error |参数校验失败 |


---

### 6. 更新知识库绑定

更新知识库绑定信息，支持部分更新。

**权限要求**：`dify:dataset:manage`

**请求**

```
PUT /api/v3/dify/area-datasets/{dataset_bind_id}
```

**请求体**

|参数 |类型 |必填 |说明 |
|---|---|---|---|
|dataset_name |string |否 |知识库名称 |
|dataset_description |string |否 |知识库描述 |
|is_default |boolean |否 |是否默认 |
|is_public |boolean |否 |是否公开 |
|sort_order |int |否 |排序顺序 |
|status |int |否 |状态：1=启用, 0=禁用 |

**响应**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "data": {
      "id": 2,
      "area": "梅州",
      "dataset_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "dataset_name": "梅州法务知识库（更新）",
      "is_default": true,
      "sort_order": 5,
      "status": 1,
      "updated_at": "2025-01-22T11:00:00"
    },
    "message": "更新成功"
  }
}
```


---

### 7. 删除知识库绑定

软删除知识库绑定记录。

**权限要求**：`dify:dataset:manage`

**请求**

```
DELETE /api/v3/dify/area-datasets/{dataset_bind_id}
```

**响应**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "message": "删除成功"
  }
}
```


---

### 8. 检查用户知识库访问权限

检查当前用户是否有权访问指定的 Dify 知识库。

**权限要求**：`dify:dataset:read`

**请求**

```
GET /api/v3/dify/area-datasets/check/{dataset_id}
```

**路径参数**

|参数 |类型 |必填 |说明 |
|---|---|---|---|
|dataset_id |string |是 |Dify 知识库 ID |

**响应（有权限）**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "has_access": true,
    "user_area": "梅州",
    "dataset_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
  }
}
```

**响应（无权限）**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "has_access": false,
    "user_area": "梅州",
    "dataset_id": "xyz-not-allowed"
  }
}
```


---

## 错误码说明

### HTTP 状态码

|状态码 |说明 |
|---|---|
|200 |请求成功 |
|400 |请求参数错误 |
|401 |未认证或 Token 无效 |
|403 |权限不足 |
|404 |资源不存在 |
|422 |参数校验失败 |
|500 |服务器内部错误 |

### 业务错误码

|code |说明 |
|---|---|
|0 |成功 |
|-1 |通用错误 |


---

## 数据字典

### dify_area_dataset 表

|字段 |类型 |说明 |
|---|---|---|
|id |int |主键 ID |
|area |varchar(50) |地区名称 |
|dataset_id |varchar(100) |Dify 知识库 ID |
|dataset_name |varchar(255) |知识库名称 |
|dataset_description |text |知识库描述 |
|is_default |boolean |是否为该地区默认知识库 |
|is_public |boolean |是否对所有地区公开 |
|sort_order |int |排序顺序，越小越靠前 |
|status |smallint |状态：1=启用, 0=禁用 |
|created_by |int |创建人 ID |
|created_at |timestamp |创建时间 |
|updated_by |int |更新人 ID |
|updated_at |timestamp |更新时间 |
|deleted_at |timestamp |删除时间（软删除） |

### 地区枚举值

|值 |说明 |
|---|---|
|梅州 |梅州地区 |
|云浮 |云浮地区 |
|揭阳 |揭阳地区 |
|潮州 |潮州地区 |
|省级 |省级（用于公共知识库） |


---

## 使用示例

### 场景1：管理员配置知识库

```bash
# 1. 创建省级公共知识库（所有用户可见）
curl -X POST "/api/v3/dify/area-datasets" \
  -H "Authorization: Bearer {admin_token}" \
  -d '{
    "area": "省级",
    "dataset_id": "省级知识库ID",
    "dataset_name": "省级法务知识库",
    "is_public": true,
    "sort_order": 0
  }'

# 2. 为各地区创建专属知识库（仅该地区用户可见）
curl -X POST "/api/v3/dify/area-datasets" \
  -d '{"area": "梅州", "dataset_id": "梅州知识库ID", "dataset_name": "梅州法务知识库", "is_default": true}'

curl -X POST "/api/v3/dify/area-datasets" \
  -d '{"area": "云浮", "dataset_id": "云浮知识库ID", "dataset_name": "云浮法务知识库", "is_default": true}'
```

### 场景2：普通用户获取可访问的知识库

```bash
# 梅州用户（common 角色）
curl -X GET "/api/v3/dify/area-datasets/my" \
  -H "Authorization: Bearer {meizhou_user_token}"

# 返回：省级公共知识库 + 梅州专属知识库（2条）
```

### 场景3：省级管理员获取所有知识库

```bash
# 省级管理员（provincial_admin 角色）
curl -X GET "/api/v3/dify/area-datasets/my" \
  -H "Authorization: Bearer {provincial_admin_token}"

# 返回：所有地区的知识库（包括梅州、云浮、揭阳、潮州、省级）
```

### 场景4：前端调用 Dify API 前检查权限

```bash
# 检查用户是否有权访问某个知识库
curl -X GET "/api/v3/dify/area-datasets/check/某知识库ID" \
  -H "Authorization: Bearer {token}"

# 根据 has_access 字段决定是否允许调用 Dify API
```


---

## 9. 对话应用管理接口

### 9.1 获取可用的对话应用列表

**接口**: `GET /api/v3/dify/chat-apps`

**权限**: `dify:chat:use`

**说明**: 获取当前实例配置的所有对话应用列表，供前端切换使用。

**请求示例**:

```bash
curl -X GET "http://localhost:8000/api/v3/dify/chat-apps" \
  -H "Authorization: Bearer <token>"
```

**Response Body**: `success (data)`

```json
{
  "code": 200,
  "msg": "OK",
  "data": {
    "data": [
      {
        "app_id": "app-xxx",
        "app_name": "AI法务助手",
        "description": "通用法律咨询助手",
        "is_default": true
      },
      {
        "app_id": "app-yyy",
        "app_name": "合同审查助手",
        "description": "专业合同分析",
        "is_default": false
      }
    ],
    "total": 2
  }
}
```

**字段说明**:

|字段 |类型 |说明 |
|---|---|---|
|`app_id` |string |对话应用 ID |
|`app_name` |string |对话应用名称 |
|`description` |string |应用描述 |
|`is_default` |boolean |是否为默认应用 |

### 9.2 获取默认对话应用

**接口**: `GET /api/v3/dify/chat-apps/default`

**权限**: `dify:chat:use`

**说明**: 获取当前配置的默认对话应用。

**请求示例**:

```bash
curl -X GET "http://localhost:8000/api/v3/dify/chat-apps/default" \
  -H "Authorization: Bearer <token>"
```

**Response Body**: `success (data)`

```json
{
  "code": 200,
  "msg": "OK",
  "data": {
    "data": {
      "app_id": "app-xxx",
      "app_name": "AI法务助手",
      "description": "通用法律咨询助手",
      "is_default": true
    }
  }
}
```


---

## 10. 对话应用多实例支持

### 10.1 配置方式

在 `config/env.{port}` 配置文件中添加 `DIFY_CHAT_APPS` 配置项：

**格式**:

```ini
DIFY_CHAT_APPS=app_id:api_key:app_name:description|app_id2:api_key2:app_name2:description

**说明**:
- 多个应用用 `|` 分隔
- 每个应用格式：`app_id`:`api_key`:`app_name`:`description`
- 第一个应用为默认应用

**示例**:
```ini
DIFY_CHAT_APPS=app-dmYZISz60ZGQHlJAPHmngoZZ:app-dmYZISz60ZGQHlJAPHmngoZZ:AI法务助手:通用法律咨询助手|app-xxx:app-xxx:合同审查助手:专业合同分析
```

### 10.2 前端切换应用

发送对话消息时，可通过以下方式指定应用：

**方式 1：请求头（推荐）**

```javascript
axios.post('/api/dify/chat/chat-messages', data, {
  headers: {
    'Authorization': 'Bearer {token}',
    'X-Dify-App-Id': 'app-xxx'  // 指定应用 ID
  }
})
```

**方式 2：查询参数**

```javascript
axios.post('/api/dify/chat/chat-messages?app_id=app-xxx', data, {
  headers: {
    'Authorization': 'Bearer {token}'
  }
})
```

**使用默认应用**:

不指定 `X-Dify-App-Id` 或 `app_id` 时，使用配置文件中的第一个应用作为默认应用。

### 10.3 端口多实例特性

本系统的特点是**端口多实例**部署架构，每个端口读取对应的配置文件：

|端口 |配置文件 |默认对话应用 |
|---|---|---|
|8073 |`config/env.8073` |梅州实例的对话应用 |
|8000 |`config/env.8000` |云浮实例的对话应用 |
|8001 |`config/env.8001` |揭阳实例的对话应用 |
|8002 |`config/env.8002` |潮州实例的对话应用 |

因此，前端请求不同端口时，会获得不同的对话应用列表：

```javascript
// 请求梅州实例
GET http://172.16.0.55:8073/api/v3/dify/chat-apps
// 返回梅州配置: [梅州法务助手, 梅州合同审查]

// 请求云浮实例
GET http://172.16.0.55:8000/api/v3/dify/chat-apps
// 返回云浮配置: [云浮法务助手, 云浮合同审查]
```

这种设计实现了区域间的业务隔离，无需后端代码判断，完全由配置驱动。


---

## 11. 更新日志

|版本 |日期 |说明 |
|---|---|---|
|2.3 |2025-01-22 |新增对话应用多实例支持，支持配置多个对话应用供前端切换 |
|2.2 |2025-01-22 |修正角色权限：市级管理员(admin)只能访问本地区，省级管理员(provincial_admin)可访问全部；知识库绑定管理仅限省级管理员 |
|2.1 |2025-01-22 |修正权限角色（去掉 area_admin），添加数据范围控制和越权防护说明 |
|2.0 |2025-01-22 |新增地区-知识库绑定管理接口 |
|1.0 |2025-01-20 |初始版本，Dify 代理接口 |