# 字典管理系统API接口文档

## 概述
字典管理系统提供字典类型和字典项的管理功能，支持树形结构展示、增删改查、批量操作等功能。

## 基础信息
- 基础路径: `/api/v1`
- 认证方式: Bearer Token
- 响应格式: JSON

## 通用响应格式
```json
{
  "code": "000000",
  "message": "成功",
  "data": {},
  "timestamp": "2026-02-22T10:00:00.000Z"
}
```

## 错误码说明
- `000000`: 成功
- `100001`: 参数验证失败
- `200002`: 令牌失效
- `300001`: 资源不存在
- `400001`: 业务逻辑错误
- `500001`: 服务器内部错误

---

## 字典类型管理接口

### 1. 获取字典类型树形结构
获取所有字典类型的树形结构，用于左侧树形展示。

**接口地址**: `GET /api/v1/dict/category/tree`

**请求头**:
```
Authorization: Bearer {token}
```

**响应示例**:
```json
{
  "code": "000000",
  "message": "成功",
  "data": [
    {
      "category_id": "file_type",
      "category_name": "文件类型枚举定义",
      "parent_field": "0",
      "children": []
    },
    {
      "category_id": "professional_type",
      "category_name": "专业类型枚举定义",
      "parent_field": "0",
      "children": []
    }
  ],
  "timestamp": "2026-02-22T10:00:00.000Z"
}
```

---

### 2. 获取字典类型列表（分页）
获取字典类型列表，支持关键字搜索和分页。

**接口地址**: `POST /api/v1/dict/category/list`

**请求头**:
```
Authorization: Bearer {token}
Content-Type: application/json
```

**请求参数**:
```json
{
  "keyword": "文件",
  "page": 1,
  "page_size": 10
}
```

**参数说明**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| keyword | string | 否 | 关键字搜索（搜索类型名称和编号） |
| page | int | 是 | 页码，从1开始 |
| page_size | int | 是 | 每页数量，1-100 |

**响应示例**:
```json
{
  "code": "000000",
  "message": "成功",
  "data": {
    "list": [
      {
        "category_id": "file_type",
        "category_no": "file_type",
        "category_name": "文件类型枚举定义",
        "category_desc": "文件类型枚举定义",
        "parent_field": "0",
        "category_level": "1",
        "del_flag": "0",
        "created_by": "user_id",
        "created_time": "2026-02-22T10:00:00",
        "updated_by": "user_id",
        "updated_time": "2026-02-22T10:00:00",
        "created_by_name": "管理员",
        "updated_by_name": "管理员"
      }
    ],
    "total": 8,
    "page": 1,
    "page_size": 10
  },
  "timestamp": "2026-02-22T10:00:00.000Z"
}
```

---

### 3. 获取字典类型详情
根据ID获取字典类型详细信息。

**接口地址**: `GET /api/v1/dict/category/{category_id}`

**请求头**:
```
Authorization: Bearer {token}
```

**路径参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| category_id | string | 是 | 字典类型ID |

**响应示例**:
```json
{
  "code": "000000",
  "message": "成功",
  "data": {
    "category_id": "file_type",
    "category_no": "file_type",
    "category_name": "文件类型枚举定义",
    "category_desc": "文件类型枚举定义",
    "parent_field": "0",
    "category_level": "1",
    "del_flag": "0",
    "created_by": "user_id",
    "created_time": "2026-02-22T10:00:00",
    "updated_by": "user_id",
    "updated_time": "2026-02-22T10:00:00",
    "created_by_name": "管理员",
    "updated_by_name": "管理员"
  },
  "timestamp": "2026-02-22T10:00:00.000Z"
}
```

---

### 4. 创建字典类型
创建新的字典类型。

**接口地址**: `POST /api/v1/dict/category`

**请求头**:
```
Authorization: Bearer {token}
Content-Type: application/json
```

**请求参数**:
```json
{
  "category_no": "custom_type",
  "category_name": "自定义类型",
  "category_desc": "自定义类型说明",
  "parent_field": "0",
  "category_level": "1"
}
```

**参数说明**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| category_no | string | 否 | 字典类型编号，最大512字符 |
| category_name | string | 是 | 字典类型名称，最大512字符 |
| category_desc | string | 否 | 字典类型备注，最大512字符 |
| parent_field | string | 否 | 父节点ID，默认"0"表示根节点 |
| category_level | string | 否 | 字典层级 |

**响应示例**:
```json
{
  "code": "000000",
  "message": "字典类型创建成功",
  "data": {
    "category_id": "uuid-generated-id"
  },
  "timestamp": "2026-02-22T10:00:00.000Z"
}
```

---

### 5. 更新字典类型
更新字典类型信息。

**接口地址**: `PUT /api/v1/dict/category/{category_id}`

**请求头**:
```
Authorization: Bearer {token}
Content-Type: application/json
```

**路径参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| category_id | string | 是 | 字典类型ID |

**请求参数**:
```json
{
  "category_name": "更新后的类型名称",
  "category_desc": "更新后的说明"
}
```

**参数说明**: 所有字段均为可选，只更新提供的字段

**响应示例**:
```json
{
  "code": "000000",
  "message": "字典类型更新成功",
  "data": null,
  "timestamp": "2026-02-22T10:00:00.000Z"
}
```

---

### 6. 删除字典类型
删除字典类型（逻辑删除）。

**接口地址**: `DELETE /api/v1/dict/category/{category_id}`

**请求头**:
```
Authorization: Bearer {token}
```

**路径参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| category_id | string | 是 | 字典类型ID |

**响应示例**:
```json
{
  "code": "000000",
  "message": "字典类型删除成功",
  "data": null,
  "timestamp": "2026-02-22T10:00:00.000Z"
}
```

**注意事项**:
- 如果字典类型下有子节点，无法删除
- 如果字典类型下有字典项，无法删除

---

## 字典项管理接口

### 1. 获取字典项列表（分页）
获取字典项列表，支持按字典类型、关键字、启用状态筛选。

**接口地址**: `POST /api/v1/dict/item/list`

**请求头**:
```
Authorization: Bearer {token}
Content-Type: application/json
```

**请求参数**:
```json
{
  "category_id": "file_type",
  "keyword": "标准",
  "enable_flag": "1",
  "page": 1,
  "page_size": 10
}
```

**参数说明**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| category_id | string | 否 | 字典类型ID |
| keyword | string | 否 | 关键字搜索（搜索名称、值、备注） |
| enable_flag | string | 否 | 启用状态：1启用，0禁用 |
| page | int | 是 | 页码，从1开始 |
| page_size | int | 是 | 每页数量，1-100 |

**响应示例**:
```json
{
  "code": "000000",
  "message": "成功",
  "data": {
    "list": [
      {
        "dict_id": 1,
        "dict_name": "国家标准",
        "dict_value": "GB",
        "dict_desc": "National Standard",
        "category_id": "file_type",
        "category_name": "文件类型枚举定义",
        "enable_flag": "1",
        "del_flag": "0",
        "sort": 1,
        "created_by": "user_id",
        "created_time": "2026-02-22T10:00:00",
        "updated_by": "user_id",
        "updated_time": "2026-02-22T10:00:00",
        "created_by_name": "管理员",
        "updated_by_name": "管理员"
      }
    ],
    "total": 12,
    "page": 1,
    "page_size": 10
  },
  "timestamp": "2026-02-22T10:00:00.000Z"
}
```

---

### 2. 获取字典项详情
根据ID获取字典项详细信息。

**接口地址**: `GET /api/v1/dict/item/{dict_id}`

**请求头**:
```
Authorization: Bearer {token}
```

**路径参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| dict_id | int | 是 | 字典项ID |

**响应示例**:
```json
{
  "code": "000000",
  "message": "成功",
  "data": {
    "dict_id": 1,
    "dict_name": "国家标准",
    "dict_value": "GB",
    "dict_desc": "National Standard",
    "category_id": "file_type",
    "category_name": "文件类型枚举定义",
    "enable_flag": "1",
    "del_flag": "0",
    "sort": 1,
    "created_by": "user_id",
    "created_time": "2026-02-22T10:00:00",
    "updated_by": "user_id",
    "updated_time": "2026-02-22T10:00:00",
    "created_by_name": "管理员",
    "updated_by_name": "管理员"
  },
  "timestamp": "2026-02-22T10:00:00.000Z"
}
```

---

### 3. 创建字典项
创建新的字典项。

**接口地址**: `POST /api/v1/dict/item`

**请求头**:
```
Authorization: Bearer {token}
Content-Type: application/json
```

**请求参数**:
```json
{
  "dict_name": "自定义项",
  "dict_value": "CUSTOM",
  "dict_desc": "Custom Item",
  "category_id": "file_type",
  "enable_flag": "1",
  "sort": 100
}
```

**参数说明**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| dict_name | string | 是 | 字典名称，最大512字符 |
| dict_value | string | 是 | 字典值，最大512字符 |
| dict_desc | string | 否 | 字典备注，最大512字符 |
| category_id | string | 是 | 字典类型ID |
| enable_flag | string | 否 | 启用标志：1启用，0禁用，默认1 |
| sort | int | 否 | 排序值 |

**响应示例**:
```json
{
  "code": "000000",
  "message": "字典项创建成功",
  "data": {
    "dict_id": 100
  },
  "timestamp": "2026-02-22T10:00:00.000Z"
}
```

---

### 4. 更新字典项
更新字典项信息。

**接口地址**: `PUT /api/v1/dict/item/{dict_id}`

**请求头**:
```
Authorization: Bearer {token}
Content-Type: application/json
```

**路径参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| dict_id | int | 是 | 字典项ID |

**请求参数**:
```json
{
  "dict_name": "更新后的名称",
  "dict_desc": "更新后的备注",
  "sort": 50
}
```

**参数说明**: 所有字段均为可选，只更新提供的字段

**响应示例**:
```json
{
  "code": "000000",
  "message": "字典项更新成功",
  "data": null,
  "timestamp": "2026-02-22T10:00:00.000Z"
}
```

---

### 5. 删除字典项
删除字典项（逻辑删除）。

**接口地址**: `DELETE /api/v1/dict/item/{dict_id}`

**请求头**:
```
Authorization: Bearer {token}
```

**路径参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| dict_id | int | 是 | 字典项ID |

**响应示例**:
```json
{
  "code": "000000",
  "message": "字典项删除成功",
  "data": null,
  "timestamp": "2026-02-22T10:00:00.000Z"
}
```

---

### 6. 批量删除字典项
批量删除多个字典项（逻辑删除）。

**接口地址**: `POST /api/v1/dict/item/batch-delete`

**请求头**:
```
Authorization: Bearer {token}
Content-Type: application/json
```

**请求参数**:
```json
{
  "dict_ids": [1, 2, 3, 4, 5]
}
```

**参数说明**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| dict_ids | array | 是 | 字典项ID列表 |

**响应示例**:
```json
{
  "code": "000000",
  "message": "成功删除5个字典项",
  "data": null,
  "timestamp": "2026-02-22T10:00:00.000Z"
}
```

---

### 7. 切换字典项启用状态
启用或禁用字典项。

**接口地址**: `PUT /api/v1/dict/item/{dict_id}/toggle-status?enable_flag={flag}`

**请求头**:
```
Authorization: Bearer {token}
```

**路径参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| dict_id | int | 是 | 字典项ID |

**查询参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| enable_flag | string | 是 | 启用标志：1启用，0禁用 |

**响应示例**:
```json
{
  "code": "000000",
  "message": "字典项启用成功",
  "data": null,
  "timestamp": "2026-02-22T10:00:00.000Z"
}
```

---

## 使用示例

### Python示例
```python
import requests

# 基础配置
BASE_URL = "http://localhost:8000/api/v1"
TOKEN = "your_access_token"

headers = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json"
}

# 1. 获取字典类型树
response = requests.get(f"{BASE_URL}/dict/category/tree", headers=headers)
print(response.json())

# 2. 获取字典项列表
data = {
    "category_id": "file_type",
    "page": 1,
    "page_size": 10
}
response = requests.post(f"{BASE_URL}/dict/item/list", headers=headers, json=data)
print(response.json())

# 3. 创建字典项
data = {
    "dict_name": "测试项",
    "dict_value": "TEST",
    "dict_desc": "Test Item",
    "category_id": "file_type",
    "enable_flag": "1",
    "sort": 100
}
response = requests.post(f"{BASE_URL}/dict/item", headers=headers, json=data)
print(response.json())
```

### JavaScript示例
```javascript
const BASE_URL = "http://localhost:8000/api/v1";
const TOKEN = "your_access_token";

const headers = {
    "Authorization": `Bearer ${TOKEN}`,
    "Content-Type": "application/json"
};

// 1. 获取字典类型树
fetch(`${BASE_URL}/dict/category/tree`, { headers })
    .then(res => res.json())
    .then(data => console.log(data));

// 2. 获取字典项列表
fetch(`${BASE_URL}/dict/item/list`, {
    method: "POST",
    headers,
    body: JSON.stringify({
        category_id: "file_type",
        page: 1,
        page_size: 10
    })
})
    .then(res => res.json())
    .then(data => console.log(data));

// 3. 创建字典项
fetch(`${BASE_URL}/dict/item`, {
    method: "POST",
    headers,
    body: JSON.stringify({
        dict_name: "测试项",
        dict_value: "TEST",
        dict_desc: "Test Item",
        category_id: "file_type",
        enable_flag: "1",
        sort: 100
    })
})
    .then(res => res.json())
    .then(data => console.log(data));
```

---

## 注意事项

1. 所有接口都需要Bearer Token认证
2. 字典类型ID使用字符串类型，字典项ID使用整数类型
3. 删除操作均为逻辑删除，不会物理删除数据
4. 创建人、修改人、创建时间、修改时间由系统自动维护
5. 字典项按sort字段升序排序，sort相同时按dict_id升序
6. 字段长度限制需严格遵守，避免数据库异常