# 康达机器人管理系统 API 接口文档

## 1. 文档概述

本文档详细描述了康达机器人管理系统的所有API接口，包括接口地址、请求方式、请求参数、响应格式和接口功能说明等。

## 2. 技术栈

- **后端框架**: FastAPI
- **数据库**: MySQL + SQLAlchemy (异步)
- **认证方式**: JWT Token
- **缓存**: Redis
- **异步请求**: httpx
- **人脸识别**: CompreFace API
- **门禁控制**: 海康威视平台

## 3. 接口认证

系统采用 JWT Token 认证机制，所有需要认证的接口都需要在请求头中添加 `Authorization: Bearer {token}`。

### 获取 Token

```
POST /login
```

## 4. 接口分类

### 4.1 认证模块

#### 4.1.1 用户登录

**接口地址**: `/login`
**请求方式**: POST
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| username | String | 是 | 用户名 |
| password | String | 是 | 密码 |
| code | String | 否 | 验证码（当前未启用） |
| uuid | String | 否 | 验证码UUID（当前未启用） |
| login_info | String | 否 | 登录信息 |

**响应格式**:
```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "access_token": "{jwt_token}",
    "token_type": "bearer"
  }
}
```

#### 4.1.2 获取用户信息

**接口地址**: `/system/user/getInfo`
**请求方式**: GET
**认证要求**: 是

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "user": {
      "user_id": 1,
      "user_name": "admin",
      "dept_id": 1,
      "status": "0",
      "email": "admin@example.com",
      "phonenumber": "13800138000",
      "sex": "1",
      "avatar": null
    },
    "roles": ["admin"],
    "permissions": ["*:*:*"]
  }
}
```

#### 4.1.3 获取用户路由

**接口地址**: `/system/user/getRouters`
**请求方式**: GET
**认证要求**: 是

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": [
    {
      "name": "System",
      "path": "/system",
      "component": "Layout",
      "redirect": "/system/user",
      "meta": {
        "title": "系统管理",
        "icon": "system",
        "roles": ["admin"]
      },
      "children": [
        {
          "name": "User",
          "path": "user",
          "component": "system/user/index",
          "meta": {
            "title": "用户管理",
            "icon": "user",
            "roles": ["admin"]
          }
        }
      ]
    }
  ]
}
```

### 4.2 人脸识别与门禁模块

#### 4.2.1 人脸检测

**接口地址**: `/system/compreface/face_detection`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
- 表单数据或字节流：图片文件

**响应格式**:
```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "result": [
      {
        "box": {
          "x_max": 100,
          "y_max": 100,
          "x_min": 50,
          "y_min": 50
        },
        "probability": 0.99
      }
    ]
  }
}
```

#### 4.2.2 人脸识别

**接口地址**: `/system/compreface/face_recognition`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
- 表单数据或字节流：图片文件

**响应格式**:
```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "result": [
      {
        "box": {
          "x_max": 100,
          "y_max": 100,
          "x_min": 50,
          "y_min": 50
        },
        "probability": 0.99,
        "subject": "张三",
        "similarity": 0.95
      }
    ]
  }
}
```

#### 4.2.3 门禁控制

**接口地址**: `/system/door/control_door`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| door_index_code | String | 是 | 门设备索引码 |
| control_type | Integer | 是 | 控制类型（1: 开门, 0: 关门） |

**响应格式**:
```json
{
  "code": 200,
  "message": "门控制成功",
  "data": {
    "result": "success"
  }
}
```

#### 4.2.4 获取门禁设备列表

**接口地址**: `/system/door/list`
**请求方式**: GET
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| pageNum | Integer | 否 | 页码 |
| pageSize | Integer | 否 | 每页条数 |
| door_name | String | 否 | 门名称 |
| door_code | String | 否 | 门编号 |

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "total": 10,
    "rows": [
      {
        "door_id": 1,
        "door_name": "前门",
        "door_code": "DOOR001",
        "door_index_code": "123456",
        "status": "1",
        "create_time": "2023-01-01 10:00:00"
      }
    ]
  }
}
```

#### 4.2.5 添加门禁设备

**接口地址**: `/system/door/add`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| door_name | String | 是 | 门名称 |
| door_code | String | 是 | 门编号 |
| door_index_code | String | 是 | 门设备索引码 |
| status | String | 是 | 状态（0: 禁用, 1: 启用） |

**响应格式**:
```json
{
  "code": 200,
  "message": "添加成功",
  "data": null
}
```

### 4.3 机器人管理模块

#### 4.3.1 获取机器人动作列表

**接口地址**: `/system/robot_action/list`
**请求方式**: GET
**认证要求**: 是
**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": [
    {
      "action_id": 1,
      "action_name": "前进",
      "action_code": "forward",
      "action_desc": "机器人前进",
      "status": "1"
    }
  ]
}
```

#### 4.3.2 修改机器人动作

**接口地址**: `/system/robot_action`
**请求方式**: PUT
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| action_id | Integer | 是 | 动作ID |
| action_name | String | 否 | 动作名称 |
| action_code | String | 否 | 动作代码 |
| action_desc | String | 否 | 动作描述 |
| status | String | 否 | 状态 |

**响应格式**:
```json
{
  "code": 200,
  "message": "修改成功",
  "data": null
}
```

### 4.4 内容管理模块

#### 4.4.1 获取讲解内容列表

**接口地址**: `/system/explanation_content/list`
**请求方式**: GET
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| pageNum | Integer | 否 | 页码 |
| pageSize | Integer | 否 | 每页条数 |
| content_name | String | 否 | 内容名称 |
| content_type | String | 否 | 内容类型 |

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": [
    {
      "content_id": 1,
      "content_name": "公司介绍",
      "content_type": "text",
      "content": "这是公司介绍内容",
      "status": "0",
      "create_time": "2023-01-01 10:00:00"
    }
  ]
}
```

#### 4.4.2 添加讲解内容

**接口地址**: `/system/explanation_content/add_explanation`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| content_name | String | 是 | 内容名称 |
| content_type | String | 是 | 内容类型 |
| content | String | 是 | 内容 |
| status | String | 是 | 状态 |

**响应格式**:
```json
{
  "code": 200,
  "message": "添加成功",
  "data": null
}
```

#### 4.4.3 修改讲解内容

**接口地址**: `/system/explanation_content/edit_explanation`
**请求方式**: PUT
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| content_id | Integer | 是 | 内容ID |
| content_name | String | 否 | 内容名称 |
| content_type | String | 否 | 内容类型 |
| content | String | 否 | 内容 |
| status | String | 否 | 状态 |

**响应格式**:
```json
{
  "code": 200,
  "message": "修改成功",
  "data": null
}
```

#### 4.4.4 删除讲解内容

**接口地址**: `/system/explanation_content/{explanation_content_ids}`
**请求方式**: DELETE
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| explanation_content_ids | String | 是 | 内容ID，多个用逗号分隔 |

**响应格式**:
```json
{
  "code": 200,
  "message": "删除成功",
  "data": null
}
```

### 4.5 系统管理模块

#### 4.5.1 验证码管理

**获取验证码图片**
**接口地址**: `/captchaImage`
**请求方式**: GET
**认证要求**: 否
**功能说明**: 获取登录验证码图片，包括验证码开关和注册开关信息

**响应格式**:
```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "captchaEnabled": true,
    "registerEnabled": true,
    "img": "base64编码的图片数据",
    "uuid": "验证码会话ID"
  }
}
```

#### 4.5.2 通用功能

**文件上传**
**接口地址**: `/common/upload`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| file | File | 是 | 要上传的文件 |

**响应格式**:
```json
{
  "code": 200,
  "message": "上传成功",
  "data": {
    "fileName": "uploaded_file.jpg",
    "filePath": "/upload/path/uploaded_file.jpg"
  }
}
```

**文件下载**
**接口地址**: `/common/download`
**请求方式**: GET
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| fileName | String | 是 | 文件名 |
| delete | Boolean | 是 | 是否删除文件 |

**响应格式**: 文件流

#### 4.5.3 用户管理

**获取用户列表**
**接口地址**: `/system/user/list`
**请求方式**: GET
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| pageNum | Integer | 否 | 页码 |
| pageSize | Integer | 否 | 每页条数 |
| user_name | String | 否 | 用户名 |
| phonenumber | String | 否 | 手机号 |

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "total": 10,
    "rows": [
      {
        "user_id": 1,
        "user_name": "admin",
        "dept_id": 1,
        "status": "0",
        "email": "admin@example.com",
        "phonenumber": "13800138000",
        "sex": "1",
        "avatar": null
      }
    ]
  }
}
```

**获取部门树**
**接口地址**: `/system/user/deptTree`
**请求方式**: GET
**认证要求**: 是

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": [
    {
      "dept_id": 1,
      "dept_name": "总公司",
      "children": [
        {
          "dept_id": 2,
          "dept_name": "技术部"
        }
      ]
    }
  ]
}
```

**添加用户**
**接口地址**: `/system/user`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| user_name | String | 是 | 用户名 |
| dept_id | Integer | 是 | 部门ID |
| email | String | 否 | 邮箱 |
| phonenumber | String | 否 | 手机号 |
| status | String | 是 | 状态 |
| password | String | 是 | 密码 |

**响应格式**:
```json
{
  "code": 200,
  "message": "添加成功",
  "data": null
}
```

#### 4.5.4 部门管理

**获取部门列表**
**接口地址**: `/system/dept/list`
**请求方式**: GET
**认证要求**: 是

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": [
    {
      "dept_id": 1,
      "dept_name": "总公司",
      "parent_id": 0,
      "order_num": 1,
      "status": "1",
      "children": [
        {
          "dept_id": 2,
          "dept_name": "技术部",
          "parent_id": 1,
          "order_num": 2,
          "status": "1"
        }
      ]
    }
  ]
}
```

**添加部门**
**接口地址**: `/system/dept`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| dept_name | String | 是 | 部门名称 |
| parent_id | Integer | 是 | 父部门ID |
| order_num | Integer | 是 | 排序 |
| status | String | 是 | 状态 |

**响应格式**:
```json
{
  "code": 200,
  "message": "添加成功",
  "data": null
}
```

**修改部门**
**接口地址**: `/system/dept`
**请求方式**: PUT
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| dept_id | Integer | 是 | 部门ID |
| dept_name | String | 否 | 部门名称 |
| parent_id | Integer | 否 | 父部门ID |
| order_num | Integer | 否 | 排序 |
| status | String | 否 | 状态 |

**响应格式**:
```json
{
  "code": 200,
  "message": "修改成功",
  "data": null
}
```

#### 4.5.5 角色管理

**获取角色列表**
**接口地址**: `/system/role/list`
**请求方式**: GET
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| pageNum | Integer | 否 | 页码 |
| pageSize | Integer | 否 | 每页条数 |
| role_name | String | 否 | 角色名称 |
| status | String | 否 | 状态 |

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "total": 5,
    "rows": [
      {
        "role_id": 1,
        "role_name": "管理员",
        "role_key": "admin",
        "status": "1",
        "create_time": "2023-01-01 10:00:00"
      }
    ]
  }
}
```

**添加角色**
**接口地址**: `/system/role`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| role_name | String | 是 | 角色名称 |
| role_key | String | 是 | 角色标识 |
| status | String | 是 | 状态 |
| menu_ids | String | 是 | 菜单权限ID列表 |

**响应格式**:
```json
{
  "code": 200,
  "message": "添加成功",
  "data": null
}
```

**获取角色部门树**
**接口地址**: `/system/role/deptTree/{role_id}`
**请求方式**: GET
**认证要求**: 是

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "depts": [
      {
        "dept_id": 1,
        "dept_name": "总公司",
        "children": []
      }
    ],
    "checkedKeys": [1]
  }
}
```

#### 4.5.6 菜单管理

**获取菜单树**
**接口地址**: `/system/menu/treeselect`
**请求方式**: GET
**认证要求**: 是

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": [
    {
      "menu_id": 1,
      "menu_name": "系统管理",
      "parent_id": 0,
      "order_num": 1,
      "path": "/system",
      "component": "Layout",
      "is_frame": 1,
      "menu_type": "M",
      "visible": "0",
      "status": "0",
      "children": [
        {
          "menu_id": 2,
          "menu_name": "用户管理",
          "parent_id": 1,
          "order_num": 2,
          "path": "user",
          "component": "system/user/index",
          "is_frame": 1,
          "menu_type": "C",
          "visible": "0",
          "status": "0"
        }
      ]
    }
  ]
}
```

**获取菜单列表**
**接口地址**: `/system/menu/list`
**请求方式**: GET
**认证要求**: 是

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": [
    {
      "menu_id": 1,
      "menu_name": "系统管理",
      "parent_id": 0,
      "order_num": 1,
      "path": "/system",
      "component": "Layout",
      "is_frame": 1,
      "menu_type": "M",
      "visible": "0",
      "status": "0"
    }
  ]
}
```

**添加菜单**
**接口地址**: `/system/menu`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| menu_name | String | 是 | 菜单名称 |
| parent_id | Integer | 是 | 父菜单ID |
| order_num | Integer | 是 | 排序 |
| path | String | 否 | 路由地址 |
| component | String | 否 | 组件路径 |
| is_frame | Integer | 是 | 是否是外部链接 |
| menu_type | String | 是 | 菜单类型 |
| visible | String | 是 | 显示状态 |
| status | String | 是 | 菜单状态 |

**响应格式**:
```json
{
  "code": 200,
  "message": "添加成功",
  "data": null
}
```

#### 4.5.7 字典管理

**获取字典类型列表**
**接口地址**: `/system/dict/type/list`
**请求方式**: GET
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| pageNum | Integer | 否 | 页码 |
| pageSize | Integer | 否 | 每页条数 |
| dict_name | String | 否 | 字典名称 |
| dict_type | String | 否 | 字典类型 |

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "total": 10,
    "rows": [
      {
        "dict_id": 1,
        "dict_name": "用户状态",
        "dict_type": "sys_normal_disable",
        "status": "0",
        "create_time": "2023-01-01 10:00:00"
      }
    ]
  }
}
```

**获取字典数据列表**
**接口地址**: `/system/dict/data/list`
**请求方式**: GET
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| pageNum | Integer | 否 | 页码 |
| pageSize | Integer | 否 | 每页条数 |
| dict_type | String | 是 | 字典类型 |

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "total": 2,
    "rows": [
      {
        "dict_code": 1,
        "dict_sort": 1,
        "dict_label": "正常",
        "dict_value": "0",
        "dict_type": "sys_normal_disable",
        "status": "0"
      },
      {
        "dict_code": 2,
        "dict_sort": 2,
        "dict_label": "禁用",
        "dict_value": "1",
        "dict_type": "sys_normal_disable",
        "status": "0"
      }
    ]
  }
}
```

#### 4.5.8 系统配置

**获取配置列表**
**接口地址**: `/system/config/list`
**请求方式**: GET
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| pageNum | Integer | 否 | 页码 |
| pageSize | Integer | 否 | 每页条数 |
| config_name | String | 否 | 配置名称 |
| config_key | String | 否 | 配置键名 |

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "total": 10,
    "rows": [
      {
        "config_id": 1,
        "config_name": "系统名称",
        "config_key": "sys.name",
        "config_value": "康达机器人管理系统",
        "status": "0",
        "create_time": "2023-01-01 10:00:00"
      }
    ]
  }
}
```

**根据键名获取配置**
**接口地址**: `/system/config/configKey/{config_key}`
**请求方式**: GET
**认证要求**: 是

**响应格式**:
```json
{
  "code": 200,
  "message": "康达机器人管理系统",
  "data": null
}
```

**刷新配置缓存**
**接口地址**: `/system/config/refreshCache`
**请求方式**: DELETE
**认证要求**: 是

**响应格式**:
```json
{
  "code": 200,
  "message": "刷新成功",
  "data": null
}
```

#### 4.5.9 日志管理

#### 4.5.10 缓存监控

**获取缓存统计信息**
**接口地址**: `/monitor/cache/statistics`
**请求方式**: GET
**认证要求**: 是

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "memory_used": "100MB",
    "memory_total": "1GB",
    "key_count": 100
  }
}
```

**获取缓存名称列表**
**接口地址**: `/monitor/cache/keys`
**请求方式**: GET
**认证要求**: 是

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "keys": ["user:1", "role:2", "menu:3"]
  }
}
```

**获取缓存键值对**
**接口地址**: `/monitor/cache/values`
**请求方式**: GET
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| cache_keys | String | 是 | 缓存键（多个用逗号分隔） |

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "user:1": {"user_id": 1, "user_name": "admin"},
    "role:2": {"role_id": 2, "role_name": "管理员"}
  }
}
```

**清除单个缓存**
**接口地址**: `/monitor/cache/clearCache`
**请求方式**: DELETE
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| cache_key | String | 是 | 缓存键 |

**响应格式**:
```json
{
  "code": 200,
  "message": "清除成功",
  "data": null
}
```

**清除所有缓存**
**接口地址**: `/monitor/cache/clearCacheAll`
**请求方式**: DELETE
**认证要求**: 是

**响应格式**:
```json
{
  "code": 200,
  "message": "清除成功",
  "data": null
}
```

#### 4.5.11 定时任务管理

**获取定时任务列表**
**接口地址**: `/monitor/job/list`
**请求方式**: GET
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| pageNum | Integer | 否 | 页码 |
| pageSize | Integer | 否 | 每页条数 |
| job_name | String | 否 | 任务名称 |
| job_group | String | 否 | 任务组名 |
| status | String | 否 | 任务状态 |

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "total": 5,
    "rows": [
      {
        "job_id": 1,
        "job_name": "数据备份",
        "job_group": "system",
        "invoke_target": "com.example.job.BackupJob",
        "cron_expression": "0 0 2 * * ?",
        "status": "0",
        "create_time": "2023-01-01 10:00:00"
      }
    ]
  }
}
```

**添加定时任务**
**接口地址**: `/monitor/job`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| job_name | String | 是 | 任务名称 |
| job_group | String | 是 | 任务组名 |
| invoke_target | String | 是 | 调用目标 |
| cron_expression | String | 是 | cron表达式 |
| status | String | 是 | 任务状态 |
| remark | String | 否 | 备注 |

**响应格式**:
```json
{
  "code": 200,
  "message": "添加成功",
  "data": null
}
```

**修改定时任务状态**
**接口地址**: `/monitor/job/changeStatus`
**请求方式**: PUT
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| job_id | Integer | 是 | 任务ID |
| status | String | 是 | 任务状态 |

**响应格式**:
```json
{
  "code": 200,
  "message": "修改成功",
  "data": null
}
```

#### 4.5.12 系统统计

**获取统计数据**
**接口地址**: `/system/sys_statistics/get_data`
**请求方式**: GET
**认证要求**: 是

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "total_visitors": 1000,
    "today_visitors": 100,
    "success_rate": 0.95,
    "total_records": 10000
  }
}
```

**获取访问趋势**
**接口地址**: `/system/sys_statistics/get_visitor_count/{day}`
**请求方式**: GET
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| day | Integer | 是 | 天数 |

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": [
    {
      "date": "2023-01-01",
      "count": 100
    },
    {
      "date": "2023-01-02",
      "count": 150
    }
  ]
}
```

**获取门禁识别成功率**
**接口地址**: `/system/sys_statistics/access_control_success_rate/{day}`
**请求方式**: GET
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| day | Integer | 是 | 天数 |

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "date": "2023-01-01",
    "success_count": 95,
    "total_count": 100,
    "success_rate": 0.95
  }
}
```

#### 4.5.13 通知公告管理

**获取通知列表**
**接口地址**: `/system/notice/list`
**请求方式**: GET
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| pageNum | Integer | 否 | 页码 |
| pageSize | Integer | 否 | 每页条数 |
| notice_title | String | 否 | 公告标题 |
| status | String | 否 | 公告状态 |

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "total": 5,
    "rows": [
      {
        "notice_id": 1,
        "notice_title": "系统更新通知",
        "notice_type": "1",
        "status": "0",
        "create_by": "admin",
        "create_time": "2023-01-01 10:00:00"
      }
    ]
  }
}
```

**添加通知公告**
**接口地址**: `/system/notice`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| notice_title | String | 是 | 公告标题 |
| notice_type | String | 是 | 公告类型 |
| notice_content | String | 是 | 公告内容 |
| status | String | 是 | 公告状态 |

**响应格式**:
```json
{
  "code": 200,
  "message": "添加成功",
  "data": null
}
```

**获取通知详情**
**接口地址**: `/system/notice/{notice_id}`
**请求方式**: GET
**认证要求**: 是

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "notice_id": 1,
    "notice_title": "系统更新通知",
    "notice_type": "1",
    "notice_content": "系统将于2023-01-01进行更新",
    "status": "0",
    "create_by": "admin",
    "create_time": "2023-01-01 10:00:00"
  }
}
```

#### 4.5.14 识别记录管理

**获取识别记录列表**
**接口地址**: `/system/identification_record/list`
**请求方式**: GET
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| pageNum | Integer | 否 | 页码 |
| pageSize | Integer | 否 | 每页条数 |
| device_id | String | 否 | 设备ID |
| visitor_name | String | 否 | 访客姓名 |
| start_time | String | 否 | 开始时间 |
| end_time | String | 否 | 结束时间 |

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "total": 10,
    "rows": [
      {
        "record_id": 1,
        "device_id": "device_001",
        "visitor_name": "张三",
        "visitor_type": "0",
        "identification_time": "2023-01-01 10:00:00",
        "status": "0"
      }
    ]
  }
}
```

**添加识别记录**
**接口地址**: `/system/identification_record`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| device_id | String | 是 | 设备ID |
| visitor_name | String | 是 | 访客姓名 |
| visitor_type | String | 是 | 访客类型 |
| identification_time | String | 是 | 识别时间 |
| status | String | 是 | 状态 |

**响应格式**:
```json
{
  "code": 200,
  "message": "添加成功",
  "data": null
}
```

**导出识别记录**
**接口地址**: `/system/identification_record/export`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| device_id | String | 否 | 设备ID |
| visitor_name | String | 否 | 访客姓名 |
| start_time | String | 否 | 开始时间 |
| end_time | String | 否 | 结束时间 |

**响应格式**: 文件流

#### 4.5.15 讲解内容管理

**获取讲解内容列表**
**接口地址**: `/system/explanation_content/list`
**请求方式**: GET
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| pageNum | Integer | 否 | 页码 |
| pageSize | Integer | 否 | 每页条数 |
| content_name | String | 否 | 内容名称 |
| status | String | 否 | 状态 |
| type_id | Integer | 否 | 类型ID |

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": [
    {
      "content_id": 1,
      "content_name": "展厅介绍",
      "type_id": 1,
      "content_text": "这是展厅的详细介绍...",
      "status": "0",
      "create_time": "2023-01-01 10:00:00"
    }
  ]
}
```

**添加讲解内容**
**接口地址**: `/system/explanation_content/add_explanation`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| content_name | String | 是 | 内容名称 |
| type_id | Integer | 是 | 类型ID |
| content_text | String | 是 | 内容文本 |
| status | String | 是 | 状态 |

**响应格式**:
```json
{
  "code": 200,
  "message": "添加成功",
  "data": null
}
```

**编辑讲解内容**
**接口地址**: `/system/explanation_content/edit_explanation`
**请求方式**: PUT
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| content_id | Integer | 是 | 内容ID |
| content_name | String | 是 | 内容名称 |
| type_id | Integer | 是 | 类型ID |
| content_text | String | 是 | 内容文本 |
| status | String | 是 | 状态 |

**响应格式**:
```json
{
  "code": 200,
  "message": "编辑成功",
  "data": null
}
```

**删除讲解内容**
**接口地址**: `/system/explanation_content/{explanation_content_ids}`
**请求方式**: DELETE
**认证要求**: 是

**响应格式**:
```json
{
  "code": 200,
  "message": "删除成功",
  "data": null
}
```

**获取讲解内容类型列表**
**接口地址**: `/system/explanation_content/type_list`
**请求方式**: GET
**认证要求**: 是

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": [
    {
      "type_id": 1,
      "type_name": "展厅介绍",
      "create_time": "2023-01-01 10:00:00"
    }
  ]
}
```

#### 4.5.16 机器人动作管理

**获取机器人动作列表**
**接口地址**: `/system/robot_action/list`
**请求方式**: GET
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| pageNum | Integer | 否 | 页码 |
| pageSize | Integer | 否 | 每页条数 |
| action_name | String | 否 | 动作名称 |
| robot_id | Integer | 否 | 机器人ID |

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": [
    {
      "action_id": 1,
      "action_name": "欢迎动作",
      "robot_id": 1,
      "action_data": "{...}",
      "create_time": "2023-01-01 10:00:00"
    }
  ]
}
```

**编辑机器人动作**
**接口地址**: `/system/robot_action`
**请求方式**: PUT
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| action_id | Integer | 是 | 动作ID |
| action_name | String | 是 | 动作名称 |
| robot_id | Integer | 是 | 机器人ID |
| action_data | String | 是 | 动作数据 |

**响应格式**:
```json
{
  "code": 200,
  "message": "编辑成功",
  "data": null
}
```

#### 4.5.17 门禁控制管理

**机器人控制开门**
**接口地址**: `/system/door/control_door`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| door_index_code | String | 是 | 门禁设备索引码 |
| control_type | Integer | 是 | 控制类型（0-开，1-关） |

**响应格式**:
```json
{
  "code": 200,
  "message": "门控制成功",
  "data": null
}
```

**获取门禁设备列表**
**接口地址**: `/system/door/list`
**请求方式**: GET
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| pageNum | Integer | 否 | 页码 |
| pageSize | Integer | 否 | 每页条数 |
| device_name | String | 否 | 设备名称 |
| device_code | String | 否 | 设备编码 |

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "total": 5,
    "rows": [
      {
        "device_id": 1,
        "device_name": "前门",
        "device_code": "DOOR_001",
        "door_index_code": "123456",
        "status": "0",
        "create_time": "2023-01-01 10:00:00"
      }
    ]
  }
}
```

**添加门禁设备**
**接口地址**: `/system/door/add`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| device_name | String | 是 | 设备名称 |
| device_code | String | 是 | 设备编码 |
| door_index_code | String | 是 | 门禁设备索引码 |
| status | String | 是 | 设备状态 |

**响应格式**:
```json
{
  "code": 200,
  "message": "添加成功",
  "data": null
}
```

**编辑门禁设备**
**接口地址**: `/system/door/edit`
**请求方式**: PUT
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| device_id | Integer | 是 | 设备ID |
| device_name | String | 是 | 设备名称 |
| device_code | String | 是 | 设备编码 |
| door_index_code | String | 是 | 门禁设备索引码 |
| status | String | 是 | 设备状态 |

**响应格式**:
```json
{
  "code": 200,
  "message": "编辑成功",
  "data": null
}
```

#### 4.5.18 海康设备管理

**查询访客预约记录**
**接口地址**: `/system/haikang/get_visitor_list`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| visitor_name | String | 否 | 访客姓名 |
| visitor_phone | String | 否 | 访客电话 |
| start_time | String | 否 | 开始时间 |
| end_time | String | 否 | 结束时间 |
| pageNum | Integer | 否 | 页码 |
| pageSize | Integer | 否 | 每页条数 |

**响应格式**:
```json
{
  "code": 200,
  "message": "查询成功",
  "data": {
    "total": 3,
    "rows": [
      {
        "reservation_id": "123456",
        "visitor_name": "张三",
        "visitor_phone": "13800138000",
        "visit_time": "2023-01-01 10:00:00",
        "status": "0"
      }
    ]
  }
}
```

#### 4.5.19 告警消息管理

**查看告警类型分布**
**接口地址**: `/system/message/alarm_type_distribution`
**请求方式**: GET
**认证要求**: 是

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "type1": 10,
    "type2": 5,
    "type3": 3
  }
}
```

**一键处理未处理的告警消息**
**接口地址**: `/system/message/handle_all`
**请求方式**: GET
**认证要求**: 是

**响应格式**:
```json
{
  "code": 200,
  "message": "处理成功",
  "data": null
}
```

**查询告警数量信息**
**接口地址**: `/system/message/count_message`
**请求方式**: GET
**认证要求**: 是

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "total": 18,
    "unhandled": 5,
    "handled": 13
  }
}
```

**获取告警消息列表**
**接口地址**: `/system/message/alert_message`
**请求方式**: GET
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| pageNum | Integer | 否 | 页码 |
| pageSize | Integer | 否 | 每页条数 |

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "total": 18,
    "rows": [
      {
        "message_id": 1,
        "message_title": "设备异常",
        "message_type": "1",
        "message_content": "前门门禁设备离线",
        "status": "0",
        "create_time": "2023-01-01 10:00:00"
      }
    ]
  }
}
```

#### 4.5.20 人脸识别管理

**人脸检测**
**接口地址**: `/system/compreface/face_detection`
**请求方式**: POST
**认证要求**: 是
**请求参数**: 文件流/字节流形式的图片数据

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "faces": [
      {
        "box": [100, 100, 200, 200],
        "probability": 0.99
      }
    ],
    "image_id": "abc123",
    "time_used": 100
  }
}
```

**人脸识别**
**接口地址**: `/system/compreface/face_recognition`
**请求方式**: POST
**认证要求**: 是
**请求参数**: 文件流/字节流形式的图片数据

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "faces": [
      {
        "box": [100, 100, 200, 200],
        "probability": 0.99,
        "identity": {
          "id": "person_001",
          "name": "张三",
          "score": 0.95
        }
      }
    ],
    "image_id": "abc123",
    "time_used": 150
  }
}
```

#### 4.5.21 验证码管理

**获取验证码图片**
**接口地址**: `/captchaImage`
**请求方式**: GET
**认证要求**: 否
**功能说明**: 获取登录验证码图片，包括验证码开关和注册开关信息

**响应格式**:
```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "captchaEnabled": true,
    "registerEnabled": true,
    "img": "base64编码的图片数据",
    "uuid": "验证码会话ID"
  }
}
```

#### 4.5.22 通用功能

**文件上传**
**接口地址**: `/common/upload`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| file | File | 是 | 要上传的文件 |

**响应格式**:
```json
{
  "code": 200,
  "message": "上传成功",
  "data": {
    "fileName": "uploaded_file.jpg",
    "filePath": "/upload/path/uploaded_file.jpg"
  }
}
```

**文件下载**
**接口地址**: `/common/download`
**请求方式**: GET
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| fileName | String | 是 | 文件名 |
| delete | Boolean | 是 | 是否删除文件 |

**响应格式**: 文件流

**获取操作日志列表**
**接口地址**: `/monitor/operlog/list`
**请求方式**: GET
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| pageNum | Integer | 否 | 页码 |
| pageSize | Integer | 否 | 每页条数 |
| title | String | 否 | 日志标题 |
| business_type | Integer | 否 | 业务类型 |
| oper_name | String | 否 | 操作用户 |

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "total": 100,
    "rows": [
      {
        "oper_id": 1,
        "title": "用户管理",
        "business_type": 1,
        "oper_name": "admin",
        "oper_url": "/system/user/list",
        "oper_ip": "127.0.0.1",
        "oper_time": "2023-01-01 10:00:00"
      }
    ]
  }
}
```

**获取登录日志列表**
**接口地址**: `/monitor/logininfor/list`
**请求方式**: GET
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| pageNum | Integer | 否 | 页码 |
| pageSize | Integer | 否 | 每页条数 |
| user_name | String | 否 | 用户名 |
| status | String | 否 | 登录状态 |

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "total": 50,
    "rows": [
      {
        "info_id": 1,
        "user_name": "admin",
        "ipaddr": "127.0.0.1",
        "login_location": "本地",
        "browser": "Chrome",
        "os": "Windows 10",
        "status": "0",
        "msg": "登录成功",
        "login_time": "2023-01-01 10:00:00"
      }
    ]
  }
}
```

**解锁用户**
**接口地址**: `/monitor/logininfor/unlock/{user_name}`
**请求方式**: GET
**认证要求**: 是

**响应格式**:
```json
{
  "code": 200,
  "message": "解锁成功",
  "data": null
}
```

#### 4.5.10 缓存监控

**获取缓存统计信息**
**接口地址**: `/monitor/cache`
**请求方式**: GET
**认证要求**: 是

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "name": "Redis",
    "uptime": "1000000",
    "connected_clients": 10,
    "used_memory": "1024000",
    "db_num": 16
  }
}
```

**获取缓存名称列表**
**接口地址**: `/monitor/cache/getNames`
**请求方式**: GET
**认证要求**: 是

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": [
    {
      "cacheName": "system",
      "cacheType": "Redis"
    }
  ]
}
```

**获取缓存键列表**
**接口地址**: `/monitor/cache/getKeys/{cache_name}`
**请求方式**: GET
**认证要求**: 是

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": [
    "sys_config:sys.name",
    "sys_config:sys.version"
  ]
}
```

**获取缓存值**
**接口地址**: `/monitor/cache/getValue/{cache_name}/{cache_key}`
**请求方式**: GET
**认证要求**: 是

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "cacheName": "system",
    "cacheKey": "sys_config:sys.name",
    "cacheValue": "康达机器人管理系统",
    "cacheTime": "2023-01-01 10:00:00"
  }
}
```

**清除指定名称缓存**
**接口地址**: `/monitor/cache/clearCacheName/{cache_name}`
**请求方式**: DELETE
**认证要求**: 是

**响应格式**:
```json
{
  "code": 200,
  "message": "清除成功",
  "data": null
}
```

**清除所有缓存**
**接口地址**: `/monitor/cache/clearCacheAll`
**请求方式**: DELETE
**认证要求**: 是

**响应格式**:
```json
{
  "code": 200,
  "message": "清除成功",
  "data": null
}
```

#### 4.5.11 定时任务管理

**获取定时任务列表**
**接口地址**: `/monitor/job/list`
**请求方式**: GET
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| pageNum | Integer | 否 | 页码 |
| pageSize | Integer | 否 | 每页条数 |
| job_name | String | 否 | 任务名称 |
| job_group | String | 否 | 任务组名 |
| status | String | 否 | 任务状态 |

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "total": 5,
    "rows": [
      {
        "job_id": 1,
        "job_name": "数据备份",
        "job_group": "system",
        "invoke_target": "com.example.job.BackupJob",
        "cron_expression": "0 0 2 * * ?",
        "status": "0",
        "create_time": "2023-01-01 10:00:00"
      }
    ]
  }
}
```

**添加定时任务**
**接口地址**: `/monitor/job`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| job_name | String | 是 | 任务名称 |
| job_group | String | 是 | 任务组名 |
| invoke_target | String | 是 | 调用目标 |
| cron_expression | String | 是 | cron表达式 |
| status | String | 是 | 任务状态 |
| remark | String | 否 | 备注 |

**响应格式**:
```json
{
  "code": 200,
  "message": "添加成功",
  "data": null
}
```

**修改定时任务状态**
**接口地址**: `/monitor/job/changeStatus`
**请求方式**: PUT
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| job_id | Integer | 是 | 任务ID |
| status | String | 是 | 任务状态 |

**响应格式**:
```json
{
  "code": 200,
  "message": "修改成功",
  "data": null
}
```

#### 4.5.12 系统统计

**获取统计数据**
**接口地址**: `/system/sys_statistics/get_data`
**请求方式**: GET
**认证要求**: 是

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "total_visitors": 1000,
    "today_visitors": 100,
    "success_rate": 0.95,
    "total_records": 10000
  }
}
```

**获取访问趋势**
**接口地址**: `/system/sys_statistics/get_visitor_count/{day}`
**请求方式**: GET
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| day | Integer | 是 | 天数 |

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": [
    {
      "date": "2023-01-01",
      "count": 100
    },
    {
      "date": "2023-01-02",
      "count": 150
    }
  ]
}
```

**获取门禁识别成功率**
**接口地址**: `/system/sys_statistics/access_control_success_rate/{day}`
**请求方式**: GET
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| day | Integer | 是 | 天数 |

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "date": "2023-01-01",
    "success_count": 95,
    "total_count": 100,
    "success_rate": 0.95
  }
}
```

#### 4.5.13 通知公告管理

**获取通知列表**
**接口地址**: `/system/notice/list`
**请求方式**: GET
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| pageNum | Integer | 否 | 页码 |
| pageSize | Integer | 否 | 每页条数 |
| notice_title | String | 否 | 公告标题 |
| status | String | 否 | 公告状态 |

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "total": 5,
    "rows": [
      {
        "notice_id": 1,
        "notice_title": "系统更新通知",
        "notice_type": "1",
        "status": "0",
        "create_by": "admin",
        "create_time": "2023-01-01 10:00:00"
      }
    ]
  }
}
```

**添加通知公告**
**接口地址**: `/system/notice`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| notice_title | String | 是 | 公告标题 |
| notice_type | String | 是 | 公告类型 |
| notice_content | String | 是 | 公告内容 |
| status | String | 是 | 公告状态 |

**响应格式**:
```json
{
  "code": 200,
  "message": "添加成功",
  "data": null
}
```

**获取通知详情**
**接口地址**: `/system/notice/{notice_id}`
**请求方式**: GET
**认证要求**: 是

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "notice_id": 1,
    "notice_title": "系统更新通知",
    "notice_type": "1",
    "notice_content": "系统将于2023-01-01进行更新",
    "status": "0",
    "create_by": "admin",
    "create_time": "2023-01-01 10:00:00"
  }
}
```

#### 4.5.11 识别记录管理

**获取识别记录列表**
**接口地址**: `/system/identification_record/list`
**请求方式**: GET
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| pageNum | Integer | 否 | 页码 |
| pageSize | Integer | 否 | 每页条数 |
| device_id | String | 否 | 设备ID |
| visitor_name | String | 否 | 访客姓名 |
| start_time | String | 否 | 开始时间 |
| end_time | String | 否 | 结束时间 |

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "total": 10,
    "rows": [
      {
        "record_id": 1,
        "device_id": "device_001",
        "visitor_name": "张三",
        "visitor_type": "0",
        "identification_time": "2023-01-01 10:00:00",
        "status": "0"
      }
    ]
  }
}
```

**添加识别记录**
**接口地址**: `/system/identification_record`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| device_id | String | 是 | 设备ID |
| visitor_name | String | 是 | 访客姓名 |
| visitor_type | String | 是 | 访客类型 |
| identification_time | String | 是 | 识别时间 |
| status | String | 是 | 状态 |

**响应格式**:
```json
{
  "code": 200,
  "message": "添加成功",
  "data": null
}
```

**导出识别记录**
**接口地址**: `/system/identification_record/export`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| device_id | String | 否 | 设备ID |
| visitor_name | String | 否 | 访客姓名 |
| start_time | String | 否 | 开始时间 |
| end_time | String | 否 | 结束时间 |

**响应格式**: 文件流

#### 4.5.12 讲解内容管理

**获取讲解内容列表**
**接口地址**: `/system/explanation_content/list`
**请求方式**: GET
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| pageNum | Integer | 否 | 页码 |
| pageSize | Integer | 否 | 每页条数 |
| content_name | String | 否 | 内容名称 |
| status | String | 否 | 状态 |
| type_id | Integer | 否 | 类型ID |

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": [
    {
      "content_id": 1,
      "content_name": "展厅介绍",
      "type_id": 1,
      "content_text": "这是展厅的详细介绍...",
      "status": "0",
      "create_time": "2023-01-01 10:00:00"
    }
  ]
}
```

**添加讲解内容**
**接口地址**: `/system/explanation_content/add_explanation`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| content_name | String | 是 | 内容名称 |
| type_id | Integer | 是 | 类型ID |
| content_text | String | 是 | 内容文本 |
| status | String | 是 | 状态 |

**响应格式**:
```json
{
  "code": 200,
  "message": "添加成功",
  "data": null
}
```

**编辑讲解内容**
**接口地址**: `/system/explanation_content/edit_explanation`
**请求方式**: PUT
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| content_id | Integer | 是 | 内容ID |
| content_name | String | 是 | 内容名称 |
| type_id | Integer | 是 | 类型ID |
| content_text | String | 是 | 内容文本 |
| status | String | 是 | 状态 |

**响应格式**:
```json
{
  "code": 200,
  "message": "编辑成功",
  "data": null
}
```

**删除讲解内容**
**接口地址**: `/system/explanation_content/{explanation_content_ids}`
**请求方式**: DELETE
**认证要求**: 是

**响应格式**:
```json
{
  "code": 200,
  "message": "删除成功",
  "data": null
}
```

**获取讲解内容类型列表**
**接口地址**: `/system/explanation_content/type_list`
**请求方式**: GET
**认证要求**: 是

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": [
    {
      "type_id": 1,
      "type_name": "展厅介绍",
      "create_time": "2023-01-01 10:00:00"
    }
  ]
}
```

#### 4.5.13 机器人动作管理

**获取机器人动作列表**
**接口地址**: `/system/robot_action/list`
**请求方式**: GET
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| pageNum | Integer | 否 | 页码 |
| pageSize | Integer | 否 | 每页条数 |
| action_name | String | 否 | 动作名称 |
| robot_id | Integer | 否 | 机器人ID |

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": [
    {
      "action_id": 1,
      "action_name": "欢迎动作",
      "robot_id": 1,
      "action_data": "{...}",
      "create_time": "2023-01-01 10:00:00"
    }
  ]
}
```

**编辑机器人动作**
**接口地址**: `/system/robot_action`
**请求方式**: PUT
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| action_id | Integer | 是 | 动作ID |
| action_name | String | 是 | 动作名称 |
| robot_id | Integer | 是 | 机器人ID |
| action_data | String | 是 | 动作数据 |

**响应格式**:
```json
{
  "code": 200,
  "message": "编辑成功",
  "data": null
}
```

#### 4.5.15 门禁控制管理

**机器人控制开门**
**接口地址**: `/system/door/control_door`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| door_index_code | String | 是 | 门禁设备索引码 |
| control_type | Integer | 是 | 控制类型（0-开，1-关） |

**响应格式**:
```json
{
  "code": 200,
  "message": "门控制成功",
  "data": null
}
```

**获取门禁设备列表**
**接口地址**: `/system/door/list`
**请求方式**: GET
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| pageNum | Integer | 否 | 页码 |
| pageSize | Integer | 否 | 每页条数 |
| device_name | String | 否 | 设备名称 |
| device_code | String | 否 | 设备编码 |

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "total": 5,
    "rows": [
      {
        "device_id": 1,
        "device_name": "前门",
        "device_code": "DOOR_001",
        "door_index_code": "123456",
        "status": "0",
        "create_time": "2023-01-01 10:00:00"
      }
    ]
  }
}
```

**添加门禁设备**
**接口地址**: `/system/door/add`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| device_name | String | 是 | 设备名称 |
| device_code | String | 是 | 设备编码 |
| door_index_code | String | 是 | 门禁设备索引码 |
| status | String | 是 | 设备状态 |

**响应格式**:
```json
{
  "code": 200,
  "message": "添加成功",
  "data": null
}
```

**编辑门禁设备**
**接口地址**: `/system/door/edit`
**请求方式**: PUT
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| device_id | Integer | 是 | 设备ID |
| device_name | String | 是 | 设备名称 |
| device_code | String | 是 | 设备编码 |
| door_index_code | String | 是 | 门禁设备索引码 |
| status | String | 是 | 设备状态 |

**响应格式**:
```json
{
  "code": 200,
  "message": "编辑成功",
  "data": null
}
```

#### 4.5.16 海康设备管理

**查询访客预约记录**
**接口地址**: `/system/haikang/get_visitor_list`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| visitor_name | String | 否 | 访客姓名 |
| visitor_phone | String | 否 | 访客电话 |
| start_time | String | 否 | 开始时间 |
| end_time | String | 否 | 结束时间 |
| pageNum | Integer | 否 | 页码 |
| pageSize | Integer | 否 | 每页条数 |

**响应格式**:
```json
{
  "code": 200,
  "message": "查询成功",
  "data": {
    "total": 3,
    "rows": [
      {
        "reservation_id": "123456",
        "visitor_name": "张三",
        "visitor_phone": "13800138000",
        "visit_time": "2023-01-01 10:00:00",
        "status": "0"
      }
    ]
  }
}
```

#### 4.5.17 告警消息管理

**查看告警类型分布**
**接口地址**: `/system/message/alarm_type_distribution`
**请求方式**: GET
**认证要求**: 是

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "type1": 10,
    "type2": 5,
    "type3": 3
  }
}
```

**一键处理未处理的告警消息**
**接口地址**: `/system/message/handle_all`
**请求方式**: GET
**认证要求**: 是

**响应格式**:
```json
{
  "code": 200,
  "message": "处理成功",
  "data": null
}
```

**查询告警数量信息**
**接口地址**: `/system/message/count_message`
**请求方式**: GET
**认证要求**: 是

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "total": 18,
    "unhandled": 5,
    "handled": 13
  }
}
```

**获取告警消息列表**
**接口地址**: `/system/message/alert_message`
**请求方式**: GET
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| pageNum | Integer | 否 | 页码 |
| pageSize | Integer | 否 | 每页条数 |

**响应格式**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "total": 18,
    "rows": [
      {
        "message_id": 1,
        "message_title": "设备异常",
        "message_type": "1",
        "message_content": "前门门禁设备离线",
        "status": "0",
        "create_time": "2023-01-01 10:00:00"
      }
    ]
  }
}
```

### 4.6 搜索服务模块

#### 4.6.1 与聊天助手对话（支持搜索增强）

**接口地址**: `/system/ragflow/converse_with_chat_assistant`
**请求方式**: POST
**认证要求**: 是
**功能说明**: 与聊天助手进行对话，支持根据关键词自动触发搜索增强功能
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| chat_id | String | 是 | 聊天助手ID |
| question | String | 是 | 用户问题 |
| stream | Boolean | 否 | 是否使用流式响应（默认：false） |

**响应格式**:
- 非流式响应:
```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "answer": "搜索结果或对话回复"
  }
}
```
- 流式响应:
```
data: {"answer": "这是"}
data: {"answer": "搜索结果"}
data: {"answer": "的一部分"}
```

**搜索触发条件**:
当用户问题包含以下关键词时，会自动触发搜索功能：
- 中文关键词：搜索、查找、新闻、时事、最新、今天、现在、当前、天气、温度、气温、下雨、晴、多云
- 英文关键词：search、find、news、latest、today、current、now、weather、temperature、rain、sunny、cloudy

### 4.7 RAGFlow 文档管理模块

#### 4.7.1 获取数据集列表

**接口地址**: `/system/ragflow/dataset_list`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| pageNum | Integer | 否 | 页码 |
| pageSize | Integer | 否 | 每页条数 |
| name | String | 否 | 数据集名称 |

**响应格式**:
```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "total": 5,
    "rows": [
      {
        "dataset_id": "12345",
        "name": "技术文档",
        "description": "系统技术文档",
        "create_time": "2023-01-01 10:00:00"
      }
    ]
  }
}
```

#### 4.7.2 创建数据集

**接口地址**: `/system/ragflow/create_dataset`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| name | String | 是 | 数据集名称 |
| description | String | 否 | 数据集描述 |
| engine_name | String | 否 | 搜索引擎名称 |

**响应格式**:
```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "dataset_id": "12345"
  }
}
```

#### 4.7.3 更新数据集

**接口地址**: `/system/ragflow/update_dataset/{dataset_id}`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| name | String | 是 | 数据集名称 |
| description | String | 否 | 数据集描述 |
| engine_name | String | 否 | 搜索引擎名称 |

**响应格式**:
```json
{
  "code": 200,
  "message": "操作成功",
  "data": null
}
```

#### 4.7.4 获取数据集中文档列表

**接口地址**: `/system/ragflow/list_documents/{dataset_id}`
**请求方式**: GET
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| pageNum | Integer | 否 | 页码 |
| pageSize | Integer | 否 | 每页条数 |
| name | String | 否 | 文档名称 |

**响应格式**:
```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "total": 10,
    "rows": [
      {
        "document_id": "67890",
        "name": "API文档.pdf",
        "size": 1024000,
        "status": "parsed"
      }
    ]
  }
}
```

#### 4.7.5 上传文件到数据集

**接口地址**: `/system/ragflow/upload_file/{dataset_id}`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| files | File[] | 是 | 要上传的文件列表 |

**响应格式**:
```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "success_count": 2,
    "failed_count": 0
  }
}
```

#### 4.7.6 更新文档

**接口地址**: `/system/ragflow/update_file/{dataset_id}/{document_id}`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| name | String | 否 | 文档名称 |
| description | String | 否 | 文档描述 |

**响应格式**:
```json
{
  "code": 200,
  "message": "操作成功",
  "data": null
}
```

#### 4.7.7 解析文档

**接口地址**: `/system/ragflow/parse_documents/{dataset_id}`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| document_ids | String[] | 是 | 要解析的文档ID列表 |

**响应格式**:
```json
{
  "code": 200,
  "message": "操作成功",
  "data": null
}
```

#### 4.7.8 停止解析文档

**接口地址**: `/system/ragflow/stop_parse_documents/{dataset_id}`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| document_ids | String[] | 是 | 要停止解析的文档ID列表 |

**响应格式**:
```json
{
  "code": 200,
  "message": "操作成功",
  "data": null
}
```

#### 4.7.9 删除文档

**接口地址**: `/system/ragflow/delete_file/{dataset_id}`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| document_ids | String[] | 是 | 要删除的文档ID列表 |

**响应格式**:
```json
{
  "code": 200,
  "message": "操作成功",
  "data": null
}
```

#### 4.7.10 删除数据集

**接口地址**: `/system/ragflow/delete_datasets`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| dataset_ids | String[] | 是 | 要删除的数据集ID列表 |

**响应格式**:
```json
{
  "code": 200,
  "message": "操作成功",
  "data": null
}
```

#### 4.7.11 获取聊天助手列表

**接口地址**: `/system/ragflow/get_chat_assistant_list`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| pageNum | Integer | 否 | 页码 |
| pageSize | Integer | 否 | 每页条数 |
| name | String | 否 | 助手名称 |

**响应格式**:
```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "total": 3,
    "rows": [
      {
        "chat_id": "chat123",
        "name": "技术助手",
        "description": "提供技术支持",
        "create_time": "2023-01-01 10:00:00"
      }
    ]
  }
}
```

#### 4.7.12 更新聊天助手

**接口地址**: `/system/ragflow/update_chat_assistant`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| chat_id | String | 是 | 聊天助手ID |
| name | String | 否 | 助手名称 |
| description | String | 否 | 助手描述 |
| dataset_ids | String[] | 否 | 关联的数据集ID列表 |

**响应格式**:
```json
{
  "code": 200,
  "message": "操作成功",
  "data": null
}
```

#### 4.7.13 创建聊天会话

**接口地址**: `/system/ragflow/create_session_with_chat`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| chat_id | String | 是 | 聊天助手ID |

**响应格式**:
```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "session_id": "session123"
  }
}
```



#### 4.7.14 与聊天助手对话

**接口地址**: `/system/ragflow/converse_with_chat_assistant`
**请求方式**: POST
**认证要求**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 描述 |
| ------ | ---- | ---- | ---- |
| chat_id | String | 是 | 聊天助手ID |
| question | String | 是 | 问题内容 |
| stream | Boolean | 否 | 是否使用流式响应（默认：false） |

**响应格式**:
- 非流式响应:
```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "answer": "这是一个示例回答"
  }
}
```
- 流式响应:
```
data: {"answer": "这是"}
data: {"answer": "一个示例"}
data: {"answer": "回答"}
```

#### 4.7.15 获取用户权限

**接口地址**: `/system/ragflow/get_user_permission`
**请求方式**: GET
**认证要求**: 是
**请求参数**: 无

**响应格式**:
```json
{
  "code": 200,
  "message": "操作成功",
  "data": [
    "access:device:list",
    "access:record:list"
  ]
}
```

## 5. 通用响应格式

所有接口的响应格式统一为 JSON 格式，包含以下字段：

| 字段名 | 类型 | 描述 |
| ------ | ---- | ---- |
| code | Integer | 响应码（200表示成功，其他表示失败） |
| message | String | 响应消息 |
| data | Object | 响应数据 |

## 6. 错误码说明

| 错误码 | 描述 |
| ------ | ---- |
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未授权 |
| 403 | 权限不足 |
| 404 | 接口不存在 |
| 500 | 服务器内部错误 |

## 7. 附录

### 7.1 数据类型说明

- **String**: 字符串类型
- **Integer**: 整数类型
- **Boolean**: 布尔类型（true/false）
- **Object**: 对象类型
- **Array**: 数组类型

### 7.2 状态码说明

- **0**: 禁用
- **1**: 启用

### 7.3 权限标识说明

系统使用权限标识控制接口访问，部分接口需要特定权限标识才能访问：

| 权限标识 | 描述 |
| -------- | ---- |
| access:device:list | 设备列表访问权限 |
| access:record:list | 识别记录访问权限 |
| system:user:list | 用户列表访问权限 |