2319 lines
48 KiB
Markdown
2319 lines
48 KiB
Markdown
# API接口文档
|
||
|
||
本文档描述IDC设备管理系统的后端API接口，遵循RESTful设计规范。
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
- [基础信息](#基础信息)
|
||
- [认证接口](#认证接口)
|
||
- [机房管理接口](#机房管理接口)
|
||
- [机柜管理接口](#机柜管理接口)
|
||
- [设备管理接口](#设备管理接口)
|
||
- [设备字段接口](#设备字段接口)
|
||
- [设备端口接口](#设备端口接口)
|
||
- [网卡接口](#网卡接口)
|
||
- [线缆接口](#线缆接口)
|
||
- [工单管理接口](#工单管理接口)
|
||
- [工单分类接口](#工单分类接口)
|
||
- [工单字段接口](#工单字段接口)
|
||
- [耗材管理接口](#耗材管理接口)
|
||
- [耗材分类接口](#耗材分类接口)
|
||
- [耗材记录接口](#耗材记录接口)
|
||
- [用户管理接口](#用户管理接口)
|
||
- [角色管理接口](#角色管理接口)
|
||
- [系统设置接口](#系统设置接口)
|
||
- [背景配置接口](#背景配置接口)
|
||
- [盘点管理接口](#盘点管理接口)
|
||
- [健康检查接口](#健康检查接口)
|
||
- [错误码说明](#错误码说明)
|
||
|
||
---
|
||
|
||
## 基础信息
|
||
|
||
| 项目 | 值 |
|
||
|------|-----|
|
||
| Base URL | `http://localhost:8000/api` |
|
||
| Content-Type | `application/json` |
|
||
| 认证方式 | Bearer Token (JWT) |
|
||
|
||
### 通用请求头
|
||
|
||
```http
|
||
Content-Type: application/json
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
### 通用响应格式
|
||
|
||
#### 成功响应
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {...},
|
||
"message": "操作成功"
|
||
}
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"error": "错误信息",
|
||
"message": "详细描述"
|
||
}
|
||
```
|
||
|
||
### 分页参数
|
||
|
||
列表接口支持以下分页参数：
|
||
|
||
| 参数名 | 类型 | 必填 | 默认值 | 描述 |
|
||
|--------|------|------|--------|------|
|
||
| page | number | 否 | 1 | 页码 |
|
||
| pageSize | number | 否 | 10 | 每页数量 |
|
||
|
||
**分页响应示例：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"list": [...],
|
||
"total": 100,
|
||
"page": 1,
|
||
"pageSize": 10,
|
||
"totalPages": 10
|
||
},
|
||
"message": "操作成功"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 认证接口
|
||
|
||
### 用户登录
|
||
|
||
```http
|
||
POST /api/auth/login
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| username | string | 是 | 用户名 |
|
||
| password | string | 是 | 密码 |
|
||
|
||
**请求示例：**
|
||
|
||
```json
|
||
{
|
||
"username": "admin",
|
||
"password": "password123"
|
||
}
|
||
```
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||
"user": {
|
||
"userId": "user001",
|
||
"username": "admin",
|
||
"email": "admin@example.com",
|
||
"phone": "13800138000",
|
||
"status": "active",
|
||
"Roles": [
|
||
{
|
||
"roleId": "role001",
|
||
"roleName": "管理员"
|
||
}
|
||
]
|
||
}
|
||
},
|
||
"message": "登录成功"
|
||
}
|
||
```
|
||
|
||
### 用户注册
|
||
|
||
```http
|
||
POST /api/auth/register
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| username | string | 是 | 用户名（3-20字符） |
|
||
| password | string | 是 | 密码（6-20字符） |
|
||
| email | string | 否 | 邮箱 |
|
||
| phone | string | 否 | 电话 |
|
||
|
||
**请求示例：**
|
||
|
||
```json
|
||
{
|
||
"username": "newuser",
|
||
"password": "password123",
|
||
"email": "user@example.com",
|
||
"phone": "13800138000"
|
||
}
|
||
```
|
||
|
||
### 获取当前用户信息
|
||
|
||
```http
|
||
GET /api/auth/me
|
||
```
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"userId": "user001",
|
||
"username": "admin",
|
||
"email": "admin@example.com",
|
||
"Roles": [...]
|
||
},
|
||
"message": "操作成功"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 机房管理接口
|
||
|
||
### 获取机房列表
|
||
|
||
```http
|
||
GET /api/rooms
|
||
```
|
||
|
||
**查询参数：**
|
||
|
||
| 参数名 | 类型 | 描述 |
|
||
|--------|------|------|
|
||
| keyword | string | 按名称搜索 |
|
||
| status | string | 按状态筛选 |
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"roomId": "room001",
|
||
"name": "A区机房",
|
||
"location": "一楼东侧",
|
||
"area": 500,
|
||
"description": "主要服务器机房",
|
||
"status": "active",
|
||
"createdAt": "2024-01-01T00:00:00.000Z",
|
||
"updatedAt": "2024-01-01T00:00:00.000Z"
|
||
}
|
||
```
|
||
|
||
### 获取单个机房
|
||
|
||
```http
|
||
GET /api/rooms/:roomId
|
||
```
|
||
|
||
### 创建机房
|
||
|
||
```http
|
||
POST /api/rooms
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| roomId | string | 是 | 机房ID（唯一标识） |
|
||
| name | string | 是 | 机房名称 |
|
||
| location | string | 否 | 机房位置 |
|
||
| area | number | 否 | 面积(平方米) |
|
||
| description | string | 否 | 描述 |
|
||
| status | string | 否 | 状态（active/inactive） |
|
||
|
||
**请求示例：**
|
||
|
||
```json
|
||
{
|
||
"roomId": "room002",
|
||
"name": "B区机房",
|
||
"location": "二楼西侧",
|
||
"area": 600,
|
||
"description": "网络设备机房",
|
||
"status": "active"
|
||
}
|
||
```
|
||
|
||
### 更新机房
|
||
|
||
```http
|
||
PUT /api/rooms/:roomId
|
||
```
|
||
|
||
**请求参数：** 同创建机房（roomId除外）
|
||
|
||
### 删除机房
|
||
|
||
```http
|
||
DELETE /api/rooms/:roomId
|
||
```
|
||
|
||
**说明：** 删除机房前需确保机房下无机柜
|
||
|
||
---
|
||
|
||
## 机柜管理接口
|
||
|
||
### 获取机柜列表
|
||
|
||
```http
|
||
GET /api/racks
|
||
```
|
||
|
||
**查询参数：**
|
||
|
||
| 参数名 | 类型 | 描述 |
|
||
|--------|------|------|
|
||
| roomId | string | 按机房ID筛选 |
|
||
| status | string | 按状态筛选 |
|
||
| keyword | string | 按名称搜索 |
|
||
| page | number | 页码 |
|
||
| pageSize | number | 每页数量 |
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"racks": [
|
||
{
|
||
"rackId": "rack001",
|
||
"name": "机柜A1",
|
||
"height": 42,
|
||
"maxPower": 5000,
|
||
"currentPower": 1200,
|
||
"roomId": "room001",
|
||
"Room": {
|
||
"roomId": "room001",
|
||
"name": "A区机房"
|
||
},
|
||
"Devices": [],
|
||
"status": "active",
|
||
"createdAt": "2024-01-01T00:00:00.000Z",
|
||
"updatedAt": "2024-01-01T00:00:00.000Z"
|
||
}
|
||
],
|
||
"total": 100
|
||
}
|
||
```
|
||
|
||
### 获取单个机柜
|
||
|
||
```http
|
||
GET /api/racks/:rackId
|
||
```
|
||
|
||
### 创建机柜
|
||
|
||
```http
|
||
POST /api/racks
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| rackId | string | 否 | 机柜ID（留空自动生成） |
|
||
| name | string | 是 | 机柜名称 |
|
||
| height | number | 否 | 高度(U)，默认42 |
|
||
| maxPower | number | 否 | 额定功率(W) |
|
||
| roomId | string | 是 | 所属机房ID |
|
||
| status | string | 否 | 状态（active/maintenance/inactive） |
|
||
| description | string | 否 | 描述 |
|
||
|
||
**请求示例：**
|
||
|
||
```json
|
||
{
|
||
"name": "机柜A2",
|
||
"height": 42,
|
||
"maxPower": 5000,
|
||
"roomId": "room001",
|
||
"status": "active",
|
||
"description": "核心交换机机柜"
|
||
}
|
||
```
|
||
|
||
### 更新机柜
|
||
|
||
```http
|
||
PUT /api/racks/:rackId
|
||
```
|
||
|
||
### 删除机柜
|
||
|
||
```http
|
||
DELETE /api/racks/:rackId
|
||
```
|
||
|
||
**说明：** 删除机柜前需确保机柜下无设备
|
||
|
||
### 获取机柜导入模板
|
||
|
||
```http
|
||
GET /api/racks/import-template
|
||
```
|
||
|
||
**响应：** 返回Excel模板文件
|
||
|
||
### 导出机柜数据
|
||
|
||
```http
|
||
GET /api/racks/export
|
||
```
|
||
|
||
**响应：** 返回Excel文件
|
||
|
||
### 导入机柜数据
|
||
|
||
```http
|
||
POST /api/racks/import
|
||
```
|
||
|
||
**Content-Type**: `multipart/form-data`
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| file | File | 是 | Excel格式的机柜数据文件 |
|
||
|
||
---
|
||
|
||
## 设备管理接口
|
||
|
||
### 获取设备列表
|
||
|
||
```http
|
||
GET /api/devices
|
||
```
|
||
|
||
**查询参数：**
|
||
|
||
| 参数名 | 类型 | 描述 |
|
||
|--------|------|------|
|
||
| rackId | string | 按机柜ID筛选 |
|
||
| type | string | 按设备类型筛选 |
|
||
| status | string | 按状态筛选 |
|
||
| keyword | string | 按名称/IP/序列号搜索 |
|
||
| page | number | 页码，默认1 |
|
||
| pageSize | number | 每页数量，默认10 |
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"devices": [
|
||
{
|
||
"deviceId": "dev001",
|
||
"name": "Web服务器01",
|
||
"type": "server",
|
||
"model": "R740",
|
||
"serialNumber": "SN123456",
|
||
"rackId": "rack001",
|
||
"position": 1,
|
||
"height": 2,
|
||
"powerConsumption": 500,
|
||
"ipAddress": "192.168.1.100",
|
||
"status": "running",
|
||
"purchaseDate": "2023-01-01",
|
||
"warrantyExpiry": "2026-01-01",
|
||
"description": "主要Web应用服务器",
|
||
"Rack": {
|
||
"rackId": "rack001",
|
||
"name": "机柜A1",
|
||
"Room": {
|
||
"roomId": "room001",
|
||
"name": "A区机房"
|
||
}
|
||
},
|
||
"createdAt": "2024-01-01T00:00:00.000Z",
|
||
"updatedAt": "2024-01-01T00:00:00.000Z"
|
||
}
|
||
],
|
||
"total": 100,
|
||
"page": 1,
|
||
"pageSize": 10
|
||
}
|
||
```
|
||
|
||
### 获取单个设备
|
||
|
||
```http
|
||
GET /api/devices/:deviceId
|
||
```
|
||
|
||
### 创建设备
|
||
|
||
```http
|
||
POST /api/devices
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| deviceId | string | 否 | 设备ID（留空自动生成） |
|
||
| name | string | 是 | 设备名称 |
|
||
| type | string | 是 | 设备类型（server/switch/router/storage/other） |
|
||
| model | string | 否 | 型号 |
|
||
| serialNumber | string | 是 | 序列号 |
|
||
| rackId | string | 否 | 所属机柜ID |
|
||
| position | number | 否 | 机柜位置（从1开始） |
|
||
| height | number | 否 | 占用高度(U) |
|
||
| powerConsumption | number | 否 | 功耗(W) |
|
||
| ipAddress | string | 否 | IP地址 |
|
||
| status | string | 否 | 状态（running/maintenance/offline/fault） |
|
||
| purchaseDate | string | 否 | 购买日期（YYYY-MM-DD） |
|
||
| warrantyExpiry | string | 否 | 保修到期日期（YYYY-MM-DD） |
|
||
| description | string | 否 | 描述 |
|
||
| customFields | object | 否 | 自定义字段值 |
|
||
|
||
**请求示例：**
|
||
|
||
```json
|
||
{
|
||
"name": "数据库服务器",
|
||
"type": "server",
|
||
"model": "DL380",
|
||
"serialNumber": "SN789012",
|
||
"rackId": "rack001",
|
||
"position": 3,
|
||
"height": 2,
|
||
"powerConsumption": 600,
|
||
"ipAddress": "192.168.1.101",
|
||
"status": "running",
|
||
"customFields": {
|
||
"cpuModel": "Intel Xeon E5-2680",
|
||
"memorySize": "64GB"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 更新设备
|
||
|
||
```http
|
||
PUT /api/devices/:deviceId
|
||
```
|
||
|
||
### 删除设备
|
||
|
||
```http
|
||
DELETE /api/devices/:deviceId
|
||
```
|
||
|
||
### 批量删除设备
|
||
|
||
```http
|
||
DELETE /api/devices/batch-delete
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| deviceIds | array | 是 | 设备ID列表 |
|
||
|
||
**请求示例：**
|
||
|
||
```json
|
||
{
|
||
"deviceIds": ["dev001", "dev002", "dev003"]
|
||
}
|
||
```
|
||
|
||
### 删除所有设备
|
||
|
||
```http
|
||
DELETE /api/devices/delete-all
|
||
```
|
||
|
||
### 批量上线设备
|
||
|
||
```http
|
||
PUT /api/devices/batch-online
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| deviceIds | array | 是 | 设备ID列表 |
|
||
|
||
### 批量下线设备
|
||
|
||
```http
|
||
PUT /api/devices/batch-offline
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| deviceIds | array | 是 | 设备ID列表 |
|
||
|
||
### 批量变更设备状态
|
||
|
||
```http
|
||
PUT /api/devices/batch-status
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| deviceIds | array | 是 | 设备ID列表 |
|
||
| status | string | 是 | 目标状态（running/maintenance/offline/fault） |
|
||
|
||
### 批量移动设备
|
||
|
||
```http
|
||
PUT /api/devices/batch-move
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| deviceIds | array | 是 | 设备ID列表 |
|
||
| targetRackId | string | 是 | 目标机柜ID |
|
||
| startPosition | number | 否 | 起始位置 |
|
||
|
||
### 获取设备导入模板
|
||
|
||
```http
|
||
GET /api/devices/import-template
|
||
```
|
||
|
||
**响应：** 返回CSV模板文件
|
||
|
||
### 导出设备数据
|
||
|
||
```http
|
||
GET /api/devices/export
|
||
```
|
||
|
||
**查询参数：**
|
||
|
||
| 参数名 | 类型 | 描述 |
|
||
|--------|------|------|
|
||
| deviceIds | string/array | 指定导出的设备ID |
|
||
|
||
**响应：** 返回CSV文件
|
||
|
||
### 导入设备数据
|
||
|
||
```http
|
||
POST /api/devices/import
|
||
```
|
||
|
||
**Content-Type**: `multipart/form-data`
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| csvFile | File | 是 | CSV格式的设备数据文件 |
|
||
|
||
### 增强导出设备数据
|
||
|
||
```http
|
||
GET /api/devices/enhanced-export
|
||
```
|
||
|
||
**查询参数：**
|
||
|
||
| 参数名 | 类型 | 描述 |
|
||
|--------|------|------|
|
||
| deviceIds | string/array | 指定导出的设备ID |
|
||
| format | string | 导出格式（csv/json） |
|
||
| fields | string | JSON格式的字段列表 |
|
||
| fieldLabels | string | JSON格式的字段标签映射 |
|
||
|
||
### 获取设备的工单列表
|
||
|
||
```http
|
||
GET /api/devices/:deviceId/tickets
|
||
```
|
||
|
||
**查询参数：**
|
||
|
||
| 参数名 | 类型 | 描述 |
|
||
|--------|------|------|
|
||
| status | string | 按状态筛选 |
|
||
| page | number | 页码 |
|
||
| pageSize | number | 每页数量 |
|
||
|
||
---
|
||
|
||
## 设备字段接口
|
||
|
||
### 获取设备字段列表
|
||
|
||
```http
|
||
GET /api/deviceFields
|
||
```
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"fieldName": "cpuModel",
|
||
"displayName": "CPU型号",
|
||
"fieldType": "string",
|
||
"required": false,
|
||
"defaultValue": "",
|
||
"options": null,
|
||
"order": 1,
|
||
"isSystem": false,
|
||
"createdAt": "2024-01-01T00:00:00.000Z",
|
||
"updatedAt": "2024-01-01T00:00:00.000Z"
|
||
}
|
||
],
|
||
"message": "操作成功"
|
||
}
|
||
```
|
||
|
||
### 创建设备字段
|
||
|
||
```http
|
||
POST /api/deviceFields
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| fieldName | string | 是 | 字段名（英文，唯一） |
|
||
| displayName | string | 是 | 显示名称（中文） |
|
||
| fieldType | string | 是 | 字段类型（string/number/date/select/boolean/textarea） |
|
||
| required | boolean | 否 | 是否必填，默认false |
|
||
| defaultValue | string | 否 | 默认值 |
|
||
| options | array | 否 | 选项（select类型使用） |
|
||
| order | number | 否 | 排序顺序 |
|
||
| visible | boolean | 否 | 是否可见，默认true |
|
||
|
||
### 更新设备字段
|
||
|
||
```http
|
||
PUT /api/deviceFields/:id
|
||
```
|
||
|
||
### 删除设备字段
|
||
|
||
```http
|
||
DELETE /api/deviceFields/:id
|
||
```
|
||
|
||
**说明：** 系统字段（isSystem=true）不可删除
|
||
|
||
---
|
||
|
||
## 设备端口接口
|
||
|
||
### 获取端口列表
|
||
|
||
```http
|
||
GET /api/device-ports
|
||
```
|
||
|
||
**查询参数：**
|
||
|
||
| 参数名 | 类型 | 描述 |
|
||
|--------|------|------|
|
||
| deviceId | string | 按设备ID筛选 |
|
||
| status | string | 按状态筛选（free/occupied/fault） |
|
||
| portType | string | 按端口类型筛选 |
|
||
| portSpeed | string | 按端口速率筛选 |
|
||
| page | number | 页码 |
|
||
| pageSize | number | 每页数量 |
|
||
|
||
### 获取设备的所有端口
|
||
|
||
```http
|
||
GET /api/device-ports/device/:deviceId
|
||
```
|
||
|
||
### 获取单个端口详情
|
||
|
||
```http
|
||
GET /api/device-ports/:portId
|
||
```
|
||
|
||
### 创建端口
|
||
|
||
```http
|
||
POST /api/device-ports
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| portId | string | 否 | 端口ID（留空自动生成） |
|
||
| deviceId | string | 是 | 所属设备ID |
|
||
| nicId | string | 否 | 所属网卡ID |
|
||
| portName | string | 是 | 端口名称 |
|
||
| portType | string | 否 | 端口类型（RJ45/SFP/SFP+/QSFP等），默认RJ45 |
|
||
| portSpeed | string | 否 | 速率（10M/100M/1G/10G/25G/40G/100G），默认1G |
|
||
| status | string | 否 | 状态（free/occupied/fault），默认free |
|
||
| vlanId | string | 否 | VLAN ID |
|
||
| description | string | 否 | 描述 |
|
||
|
||
### 批量创建端口
|
||
|
||
```http
|
||
POST /api/device-ports/batch
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| ports | array | 是 | 端口数据列表 |
|
||
|
||
### 更新端口
|
||
|
||
```http
|
||
PUT /api/device-ports/:portId
|
||
```
|
||
|
||
### 删除端口
|
||
|
||
```http
|
||
DELETE /api/device-ports/:portId
|
||
```
|
||
|
||
### 批量删除端口
|
||
|
||
```http
|
||
DELETE /api/device-ports/batch
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| portIds | array | 是 | 端口ID列表 |
|
||
|
||
---
|
||
|
||
## 网卡接口
|
||
|
||
### 获取网卡列表
|
||
|
||
```http
|
||
GET /api/network-cards
|
||
```
|
||
|
||
**查询参数：**
|
||
|
||
| 参数名 | 类型 | 描述 |
|
||
|--------|------|------|
|
||
| deviceId | string | 按设备ID筛选 |
|
||
|
||
### 获取设备的所有网卡
|
||
|
||
```http
|
||
GET /api/network-cards/device/:deviceId
|
||
```
|
||
|
||
### 获取设备的网卡及端口信息
|
||
|
||
```http
|
||
GET /api/network-cards/device/:deviceId/with-ports
|
||
```
|
||
|
||
### 获取单个网卡详情
|
||
|
||
```http
|
||
GET /api/network-cards/:nicId
|
||
```
|
||
|
||
### 获取网卡的端口列表
|
||
|
||
```http
|
||
GET /api/network-cards/:nicId/ports
|
||
```
|
||
|
||
### 创建网卡
|
||
|
||
```http
|
||
POST /api/network-cards
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| nicId | string | 否 | 网卡ID（留空自动生成） |
|
||
| deviceId | string | 是 | 所属设备ID |
|
||
| name | string | 是 | 网卡名称 |
|
||
| description | string | 否 | 描述 |
|
||
| slotNumber | number | 否 | 插槽号 |
|
||
| model | string | 否 | 型号 |
|
||
| manufacturer | string | 否 | 厂商 |
|
||
| status | string | 否 | 状态（normal/fault），默认normal |
|
||
|
||
### 更新网卡
|
||
|
||
```http
|
||
PUT /api/network-cards/:nicId
|
||
```
|
||
|
||
### 删除网卡
|
||
|
||
```http
|
||
DELETE /api/network-cards/:nicId
|
||
```
|
||
|
||
**说明：** 删除网卡前需确保网卡下无端口
|
||
|
||
---
|
||
|
||
## 线缆接口
|
||
|
||
### 获取线缆列表
|
||
|
||
```http
|
||
GET /api/cables
|
||
```
|
||
|
||
**查询参数：**
|
||
|
||
| 参数名 | 类型 | 描述 |
|
||
|--------|------|------|
|
||
| sourceDeviceId | string | 按源设备筛选 |
|
||
| targetDeviceId | string | 按目标设备筛选 |
|
||
| status | string | 按状态筛选 |
|
||
| cableType | string | 按线缆类型筛选 |
|
||
| page | number | 页码 |
|
||
| pageSize | number | 每页数量 |
|
||
|
||
### 获取设备的所有接线
|
||
|
||
```http
|
||
GET /api/cables/device/:deviceId
|
||
```
|
||
|
||
### 获取机柜内所有设备的接线
|
||
|
||
```http
|
||
GET /api/cables/rack/:rackId
|
||
```
|
||
|
||
### 检查接线冲突
|
||
|
||
```http
|
||
POST /api/cables/check-conflict
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| sourceDeviceId | string | 是 | 源设备ID |
|
||
| sourcePort | string | 是 | 源端口名称 |
|
||
| targetDeviceId | string | 是 | 目标设备ID |
|
||
| targetPort | string | 是 | 目标端口名称 |
|
||
| excludeCableId | string | 否 | 排除的线缆ID（用于编辑时） |
|
||
|
||
### 获取单个线缆详情
|
||
|
||
```http
|
||
GET /api/cables/:cableId
|
||
```
|
||
|
||
### 创建线缆
|
||
|
||
```http
|
||
POST /api/cables
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| cableId | string | 否 | 线缆ID（留空自动生成） |
|
||
| sourceDeviceId | string | 是 | 源设备ID |
|
||
| sourcePort | string | 是 | 源端口名称 |
|
||
| targetDeviceId | string | 是 | 目标设备ID |
|
||
| targetPort | string | 是 | 目标端口名称 |
|
||
| cableType | string | 否 | 线缆类型（ethernet/fiber/optical等），默认ethernet |
|
||
| cableLength | number | 否 | 长度(米) |
|
||
| status | string | 否 | 状态（normal/fault），默认normal |
|
||
| description | string | 否 | 描述 |
|
||
| force | boolean | 否 | 是否强制创建（覆盖已有连接） |
|
||
|
||
### 批量创建线缆
|
||
|
||
```http
|
||
POST /api/cables/batch
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| cables | array | 是 | 线缆数据列表 |
|
||
|
||
### 更新线缆
|
||
|
||
```http
|
||
PUT /api/cables/:cableId
|
||
```
|
||
|
||
### 删除线缆
|
||
|
||
```http
|
||
DELETE /api/cables/:cableId
|
||
```
|
||
|
||
### 批量删除线缆
|
||
|
||
```http
|
||
DELETE /api/cables/batch
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| cableIds | array | 是 | 线缆ID列表 |
|
||
|
||
---
|
||
|
||
## 工单管理接口
|
||
|
||
### 获取工单列表
|
||
|
||
```http
|
||
GET /api/tickets
|
||
```
|
||
|
||
**查询参数：**
|
||
|
||
| 参数名 | 类型 | 描述 |
|
||
|--------|------|------|
|
||
| status | string | 按状态筛选（pending/in_progress/completed/closed） |
|
||
| priority | string | 按优先级筛选（urgent/high/medium/low） |
|
||
| faultCategory | string | 按故障分类筛选 |
|
||
| deviceId | string | 按设备筛选 |
|
||
| reporterId | string | 按报修人筛选 |
|
||
| startDate | string | 开始日期 |
|
||
| endDate | string | 结束日期 |
|
||
| keyword | string | 关键词搜索 |
|
||
| page | number | 页码 |
|
||
| pageSize | number | 每页数量 |
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"total": 50,
|
||
"tickets": [
|
||
{
|
||
"ticketId": "TKT001",
|
||
"title": "服务器故障",
|
||
"description": "Web服务器无法访问",
|
||
"status": "in_progress",
|
||
"priority": "high",
|
||
"faultCategory": "硬件故障",
|
||
"deviceId": "dev001",
|
||
"deviceName": "Web服务器01",
|
||
"serialNumber": "SN123456",
|
||
"reporterId": "user001",
|
||
"reporterName": "张三",
|
||
"createdAt": "2024-01-01T00:00:00.000Z",
|
||
"updatedAt": "2024-01-01T00:00:00.000Z"
|
||
}
|
||
],
|
||
"page": 1,
|
||
"pageSize": 10
|
||
}
|
||
```
|
||
|
||
### 获取工单统计
|
||
|
||
```http
|
||
GET /api/tickets/stats
|
||
```
|
||
|
||
**查询参数：**
|
||
|
||
| 参数名 | 类型 | 描述 |
|
||
|--------|------|------|
|
||
| startDate | string | 开始日期 |
|
||
| endDate | string | 结束日期 |
|
||
|
||
### 获取单个工单详情
|
||
|
||
```http
|
||
GET /api/tickets/:ticketId
|
||
```
|
||
|
||
### 创建工单
|
||
|
||
```http
|
||
POST /api/tickets
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| deviceId | string | 否 | 关联设备ID（与deviceName+serialNumber二选一） |
|
||
| deviceName | string | 否 | 设备名称（手动输入时） |
|
||
| serialNumber | string | 否 | 序列号（手动输入时） |
|
||
| title | string | 否 | 工单标题 |
|
||
| faultCategory | string | 是 | 故障分类 |
|
||
| faultSubCategory | string | 否 | 故障子分类 |
|
||
| priority | string | 否 | 优先级（urgent/high/medium/low），默认medium |
|
||
| description | string | 是 | 问题描述 |
|
||
| expectedCompletionDate | string | 否 | 期望完成日期 |
|
||
| reporterId | string | 否 | 报修人ID |
|
||
| reporterName | string | 否 | 报修人姓名 |
|
||
| attachments | array | 否 | 附件列表 |
|
||
| tags | array | 否 | 标签列表 |
|
||
|
||
### 更新工单
|
||
|
||
```http
|
||
PUT /api/tickets/:ticketId
|
||
```
|
||
|
||
### 更新工单状态
|
||
|
||
```http
|
||
PUT /api/tickets/:ticketId/status
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| status | string | 是 | 目标状态 |
|
||
| resolution | string | 否 | 解决方案（完成时填写） |
|
||
| operatorId | string | 否 | 操作人ID |
|
||
| operatorName | string | 否 | 操作人姓名 |
|
||
| operatorRole | string | 否 | 操作人角色 |
|
||
|
||
### 处理工单
|
||
|
||
```http
|
||
PUT /api/tickets/:ticketId/process
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| solution | string | 否 | 解决方案 |
|
||
| result | string | 否 | 处理结果（resolved/unresolved） |
|
||
| notes | string | 否 | 备注 |
|
||
| usedParts | string | 否 | 使用配件 |
|
||
| operatorId | string | 否 | 操作人ID |
|
||
| operatorName | string | 否 | 操作人姓名 |
|
||
|
||
### 添加工单操作记录
|
||
|
||
```http
|
||
POST /api/tickets/:ticketId/operations
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| operationType | string | 是 | 操作类型 |
|
||
| operationDescription | string | 是 | 操作描述 |
|
||
| operationSteps | array | 否 | 操作步骤 |
|
||
| spareParts | array | 否 | 使用配件 |
|
||
| duration | number | 否 | 耗时(分钟) |
|
||
| result | string | 否 | 结果 |
|
||
| notes | string | 否 | 备注 |
|
||
| operatorId | string | 否 | 操作人ID |
|
||
| operatorName | string | 否 | 操作人姓名 |
|
||
| operatorRole | string | 否 | 操作人角色 |
|
||
|
||
### 获取工单操作记录
|
||
|
||
```http
|
||
GET /api/tickets/:ticketId/operations
|
||
```
|
||
|
||
### 删除工单
|
||
|
||
```http
|
||
DELETE /api/tickets/:ticketId
|
||
```
|
||
|
||
### 评价工单
|
||
|
||
```http
|
||
POST /api/tickets/:ticketId/evaluate
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| evaluation | string | 是 | 评价内容 |
|
||
| evaluationRating | number | 是 | 评分(1-5) |
|
||
| operatorId | string | 否 | 操作人ID |
|
||
| operatorName | string | 否 | 操作人姓名 |
|
||
|
||
---
|
||
|
||
## 工单分类接口
|
||
|
||
### 获取分类列表
|
||
|
||
```http
|
||
GET /api/ticket-categories
|
||
```
|
||
|
||
### 创建分类
|
||
|
||
```http
|
||
POST /api/ticket-categories
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| categoryId | string | 是 | 分类ID（唯一标识） |
|
||
| name | string | 是 | 分类名称 |
|
||
| description | string | 否 | 描述 |
|
||
| sortOrder | number | 否 | 排序顺序 |
|
||
|
||
### 更新分类
|
||
|
||
```http
|
||
PUT /api/ticket-categories/:id
|
||
```
|
||
|
||
### 删除分类
|
||
|
||
```http
|
||
DELETE /api/ticket-categories/:id
|
||
```
|
||
|
||
---
|
||
|
||
## 工单字段接口
|
||
|
||
### 获取字段列表
|
||
|
||
```http
|
||
GET /api/ticket-fields
|
||
```
|
||
|
||
### 创建字段
|
||
|
||
```http
|
||
POST /api/ticket-fields
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| fieldName | string | 是 | 字段名（英文，唯一） |
|
||
| displayName | string | 是 | 显示名称（中文） |
|
||
| fieldType | string | 是 | 字段类型（text/number/date/select/textarea） |
|
||
| isRequired | boolean | 否 | 是否必填 |
|
||
| defaultValue | string | 否 | 默认值 |
|
||
| options | string | 否 | 选项（逗号分隔） |
|
||
| sortOrder | number | 否 | 排序顺序 |
|
||
|
||
### 更新字段
|
||
|
||
```http
|
||
PUT /api/ticket-fields/:id
|
||
```
|
||
|
||
### 删除字段
|
||
|
||
```http
|
||
DELETE /api/ticket-fields/:id
|
||
```
|
||
|
||
---
|
||
|
||
## 耗材管理接口
|
||
|
||
### 获取耗材列表
|
||
|
||
```http
|
||
GET /api/consumables
|
||
```
|
||
|
||
**查询参数：**
|
||
|
||
| 参数名 | 类型 | 描述 |
|
||
|--------|------|------|
|
||
| category | string | 按分类筛选 |
|
||
| status | string | 按状态筛选 |
|
||
| keyword | string | 按名称搜索 |
|
||
| page | number | 页码 |
|
||
| pageSize | number | 每页数量 |
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"total": 100,
|
||
"consumables": [
|
||
{
|
||
"consumableId": "cons001",
|
||
"name": "硬盘",
|
||
"category": "存储设备",
|
||
"specification": "1TB SSD",
|
||
"unit": "个",
|
||
"currentStock": 100,
|
||
"minStock": 10,
|
||
"maxStock": 200,
|
||
"unitPrice": 500,
|
||
"supplier": "供应商A",
|
||
"location": "仓库1",
|
||
"status": "active",
|
||
"createdAt": "2024-01-01T00:00:00.000Z",
|
||
"updatedAt": "2024-01-01T00:00:00.000Z"
|
||
}
|
||
],
|
||
"page": 1,
|
||
"pageSize": 10
|
||
}
|
||
```
|
||
|
||
### 获取单个耗材
|
||
|
||
```http
|
||
GET /api/consumables/:id
|
||
```
|
||
|
||
### 创建耗材
|
||
|
||
```http
|
||
POST /api/consumables
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| consumableId | string | 否 | 耗材ID（留空自动生成） |
|
||
| name | string | 是 | 耗材名称 |
|
||
| category | string | 是 | 分类 |
|
||
| specification | string | 否 | 规格 |
|
||
| unit | string | 否 | 单位 |
|
||
| currentStock | number | 否 | 当前库存，默认0 |
|
||
| minStock | number | 否 | 最低库存预警值 |
|
||
| maxStock | number | 否 | 最高库存值 |
|
||
| unitPrice | number | 否 | 单价 |
|
||
| supplier | string | 否 | 供应商 |
|
||
| location | string | 否 | 存放位置 |
|
||
| status | string | 否 | 状态（active/inactive），默认active |
|
||
| description | string | 否 | 描述 |
|
||
|
||
### 更新耗材
|
||
|
||
```http
|
||
PUT /api/consumables/:id
|
||
```
|
||
|
||
### 删除耗材
|
||
|
||
```http
|
||
DELETE /api/consumables/:id
|
||
```
|
||
|
||
### 导入耗材
|
||
|
||
```http
|
||
POST /api/consumables/import
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| items | array | 是 | 耗材数据列表 |
|
||
| operator | string | 否 | 操作人 |
|
||
|
||
### 获取耗材分类列表
|
||
|
||
```http
|
||
GET /api/consumables/categories/list
|
||
```
|
||
|
||
### 获取低库存耗材
|
||
|
||
```http
|
||
GET /api/consumables/low-stock
|
||
```
|
||
|
||
### 获取耗材统计汇总
|
||
|
||
```http
|
||
GET /api/consumables/statistics/summary
|
||
```
|
||
|
||
### 获取出入库记录
|
||
|
||
```http
|
||
GET /api/consumables/inout/records
|
||
```
|
||
|
||
**查询参数：**
|
||
|
||
| 参数名 | 类型 | 描述 |
|
||
|--------|------|------|
|
||
| page | number | 页码 |
|
||
| pageSize | number | 每页数量 |
|
||
|
||
### 快速出入库
|
||
|
||
```http
|
||
POST /api/consumables/quick-inout
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| consumableId | string | 是 | 耗材ID |
|
||
| type | string | 是 | 类型（in/out） |
|
||
| quantity | number | 是 | 数量 |
|
||
| operator | string | 否 | 操作人 |
|
||
| reason | string | 否 | 原因 |
|
||
| notes | string | 否 | 备注 |
|
||
| snList | array | 否 | SN列表 |
|
||
|
||
### 出入库操作
|
||
|
||
```http
|
||
POST /api/consumables/inout
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| consumableId | string | 是 | 耗材ID |
|
||
| type | string | 是 | 类型（in/out） |
|
||
| quantity | number | 是 | 数量 |
|
||
| operator | string | 否 | 操作人 |
|
||
| reason | string | 否 | 原因 |
|
||
| recipient | string | 否 | 领用人 |
|
||
| notes | string | 否 | 备注 |
|
||
| snList | array | 否 | SN列表 |
|
||
|
||
### 库存调整
|
||
|
||
```http
|
||
POST /api/consumables/adjust
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| consumableId | string | 是 | 耗材ID |
|
||
| adjustType | string | 是 | 调整类型（add/subtract/set） |
|
||
| quantity | number | 是 | 数量 |
|
||
| operator | string | 否 | 操作人 |
|
||
| reason | string | 否 | 原因 |
|
||
| notes | string | 否 | 备注 |
|
||
|
||
### 获取耗材操作日志
|
||
|
||
```http
|
||
GET /api/consumables/logs
|
||
```
|
||
|
||
**查询参数：**
|
||
|
||
| 参数名 | 类型 | 描述 |
|
||
|--------|------|------|
|
||
| consumableId | string | 按耗材筛选 |
|
||
| operationType | string | 按操作类型筛选（多个用逗号分隔） |
|
||
| startDate | string | 开始日期 |
|
||
| endDate | string | 结束日期 |
|
||
| page | number | 页码 |
|
||
| pageSize | number | 每页数量 |
|
||
|
||
### 导出耗材日志
|
||
|
||
```http
|
||
GET /api/consumables/logs/export
|
||
```
|
||
|
||
**查询参数：**
|
||
|
||
| 参数名 | 类型 | 描述 |
|
||
|--------|------|------|
|
||
| consumableId | string | 按耗材筛选 |
|
||
| operationType | string | 按操作类型筛选 |
|
||
| startDate | string | 开始日期 |
|
||
| endDate | string | 结束日期 |
|
||
|
||
### 导入耗材日志
|
||
|
||
```http
|
||
POST /api/consumables/logs/import
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| logs | array | 是 | 日志数据列表 |
|
||
| operator | string | 否 | 操作人 |
|
||
|
||
### 修改日志记录
|
||
|
||
```http
|
||
PUT /api/consumables/logs/:id
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| reason | string | 否 | 原因 |
|
||
| notes | string | 否 | 备注 |
|
||
| operator | string | 否 | 操作人 |
|
||
| modificationReason | string | 否 | 修改原因 |
|
||
|
||
### 获取日志修改历史
|
||
|
||
```http
|
||
GET /api/consumables/logs/:id/history
|
||
```
|
||
|
||
### 获取归档记录列表
|
||
|
||
```http
|
||
GET /api/consumables/archives
|
||
```
|
||
|
||
**查询参数：**
|
||
|
||
| 参数名 | 类型 | 描述 |
|
||
|--------|------|------|
|
||
| keyword | string | 关键词搜索 |
|
||
| page | number | 页码 |
|
||
| pageSize | number | 每页数量 |
|
||
|
||
### 获取归档记录详情
|
||
|
||
```http
|
||
GET /api/consumables/archives/:archiveId
|
||
```
|
||
|
||
### 根据SN查询耗材
|
||
|
||
```http
|
||
GET /api/consumables/by-sn/:sn
|
||
```
|
||
|
||
---
|
||
|
||
## 耗材分类接口
|
||
|
||
### 获取分类列表
|
||
|
||
```http
|
||
GET /api/consumable-categories
|
||
```
|
||
|
||
### 创建分类
|
||
|
||
```http
|
||
POST /api/consumable-categories
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| categoryId | string | 是 | 分类ID（唯一标识） |
|
||
| name | string | 是 | 分类名称 |
|
||
| description | string | 否 | 描述 |
|
||
|
||
### 更新分类
|
||
|
||
```http
|
||
PUT /api/consumable-categories/:id
|
||
```
|
||
|
||
### 删除分类
|
||
|
||
```http
|
||
DELETE /api/consumable-categories/:id
|
||
```
|
||
|
||
---
|
||
|
||
## 耗材记录接口
|
||
|
||
### 获取领用记录列表
|
||
|
||
```http
|
||
GET /api/consumable-records
|
||
```
|
||
|
||
**查询参数：**
|
||
|
||
| 参数名 | 类型 | 描述 |
|
||
|--------|------|------|
|
||
| consumableId | string | 按耗材筛选 |
|
||
| userId | string | 按用户筛选 |
|
||
| type | string | 按类型筛选（领用/归还/报废） |
|
||
| startDate | string | 开始日期 |
|
||
| endDate | string | 结束日期 |
|
||
|
||
### 创建领用记录
|
||
|
||
```http
|
||
POST /api/consumable-records
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| consumableId | string | 是 | 耗材ID |
|
||
| quantity | number | 是 | 数量 |
|
||
| type | string | 是 | 类型（领用/归还/报废） |
|
||
| userId | string | 是 | 用户ID |
|
||
| deviceId | string | 否 | 关联设备ID |
|
||
| description | string | 否 | 说明 |
|
||
|
||
---
|
||
|
||
## 用户管理接口
|
||
|
||
### 获取用户列表
|
||
|
||
```http
|
||
GET /api/users
|
||
```
|
||
|
||
**查询参数：**
|
||
|
||
| 参数名 | 类型 | 描述 |
|
||
|--------|------|------|
|
||
| username | string | 按用户名搜索 |
|
||
| realName | string | 按姓名搜索 |
|
||
| status | string | 按状态筛选 |
|
||
| page | number | 页码 |
|
||
| pageSize | number | 每页数量 |
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"total": 50,
|
||
"page": 1,
|
||
"pageSize": 10,
|
||
"users": [
|
||
{
|
||
"userId": "user001",
|
||
"username": "admin",
|
||
"email": "admin@example.com",
|
||
"phone": "13800138000",
|
||
"realName": "管理员",
|
||
"status": "active",
|
||
"roles": [
|
||
{
|
||
"roleId": "role001",
|
||
"roleName": "管理员",
|
||
"roleCode": "admin"
|
||
}
|
||
],
|
||
"createdAt": "2024-01-01T00:00:00.000Z",
|
||
"updatedAt": "2024-01-01T00:00:00.000Z"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 获取所有用户（简要信息）
|
||
|
||
```http
|
||
GET /api/users/all
|
||
```
|
||
|
||
### 获取单个用户
|
||
|
||
```http
|
||
GET /api/users/:userId
|
||
```
|
||
|
||
### 创建用户
|
||
|
||
```http
|
||
POST /api/users
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| username | string | 是 | 用户名 |
|
||
| password | string | 是 | 密码 |
|
||
| email | string | 否 | 邮箱 |
|
||
| phone | string | 否 | 电话 |
|
||
| realName | string | 否 | 真实姓名 |
|
||
| status | string | 否 | 状态（active/inactive/pending），默认active |
|
||
| roleIds | array | 否 | 角色ID列表 |
|
||
| remark | string | 否 | 备注 |
|
||
|
||
### 更新用户
|
||
|
||
```http
|
||
PUT /api/users/:userId
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| username | string | 否 | 用户名 |
|
||
| email | string | 否 | 邮箱 |
|
||
| phone | string | 否 | 电话 |
|
||
| realName | string | 否 | 真实姓名 |
|
||
| status | string | 否 | 状态 |
|
||
| roleIds | array | 否 | 角色ID列表 |
|
||
| remark | string | 否 | 备注 |
|
||
| newPassword | string | 否 | 新密码 |
|
||
|
||
### 删除用户
|
||
|
||
```http
|
||
DELETE /api/users/:userId
|
||
```
|
||
|
||
### 重置密码
|
||
|
||
```http
|
||
PUT /api/users/:userId/password
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| newPassword | string | 是 | 新密码 |
|
||
|
||
### 上传头像
|
||
|
||
```http
|
||
POST /api/users/:userId/avatar
|
||
```
|
||
|
||
**Content-Type**: `multipart/form-data`
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| avatar | File | 是 | 头像图片文件（JPG/PNG/GIF/WebP） |
|
||
|
||
### 删除头像
|
||
|
||
```http
|
||
DELETE /api/users/:userId/avatar
|
||
```
|
||
|
||
### 审核通过用户
|
||
|
||
```http
|
||
PUT /api/users/:userId/approve
|
||
```
|
||
|
||
### 拒绝用户注册
|
||
|
||
```http
|
||
PUT /api/users/:userId/reject
|
||
```
|
||
|
||
---
|
||
|
||
## 角色管理接口
|
||
|
||
### 获取角色列表
|
||
|
||
```http
|
||
GET /api/roles
|
||
```
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": [
|
||
{
|
||
"roleId": "role001",
|
||
"roleName": "管理员",
|
||
"roleCode": "admin",
|
||
"description": "系统管理员，拥有所有权限",
|
||
"status": "active",
|
||
"Permissions": [
|
||
{
|
||
"permissionId": "perm001",
|
||
"permissionName": "设备管理"
|
||
}
|
||
],
|
||
"createdAt": "2024-01-01T00:00:00.000Z",
|
||
"updatedAt": "2024-01-01T00:00:00.000Z"
|
||
}
|
||
],
|
||
"message": "操作成功"
|
||
}
|
||
```
|
||
|
||
### 创建角色
|
||
|
||
```http
|
||
POST /api/roles
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| roleId | string | 是 | 角色ID（唯一标识） |
|
||
| roleName | string | 是 | 角色名称 |
|
||
| roleCode | string | 否 | 角色代码 |
|
||
| description | string | 否 | 描述 |
|
||
| permissionIds | array | 否 | 权限ID列表 |
|
||
|
||
### 更新角色
|
||
|
||
```http
|
||
PUT /api/roles/:roleId
|
||
```
|
||
|
||
### 删除角色
|
||
|
||
```http
|
||
DELETE /api/roles/:roleId
|
||
```
|
||
|
||
---
|
||
|
||
## 系统设置接口
|
||
|
||
### 获取系统设置
|
||
|
||
```http
|
||
GET /api/system-settings
|
||
```
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"siteName": "IDC设备管理系统",
|
||
"siteLogo": "/uploads/logo.png",
|
||
"siteDescription": "专业的数据中心设备管理平台",
|
||
"copyright": "© 2024 IDC Management",
|
||
"version": "1.0.0"
|
||
},
|
||
"message": "操作成功"
|
||
}
|
||
```
|
||
|
||
### 更新系统设置
|
||
|
||
```http
|
||
PUT /api/system-settings
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| siteName | string | 否 | 站点名称 |
|
||
| siteLogo | string | 否 | 站点Logo路径 |
|
||
| siteDescription | string | 否 | 站点描述 |
|
||
| copyright | string | 否 | 版权信息 |
|
||
|
||
---
|
||
|
||
## 背景配置接口
|
||
|
||
### 获取背景配置
|
||
|
||
```http
|
||
GET /api/background
|
||
```
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"loginBackground": "/uploads/bg/login.jpg",
|
||
"dashboardBackground": "/uploads/bg/dashboard.jpg",
|
||
"primaryColor": "#1890ff"
|
||
},
|
||
"message": "操作成功"
|
||
}
|
||
```
|
||
|
||
### 更新背景配置
|
||
|
||
```http
|
||
PUT /api/background
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| loginBackground | string | 否 | 登录页背景图 |
|
||
| dashboardBackground | string | 否 | 仪表盘背景图 |
|
||
| primaryColor | string | 否 | 主题主色 |
|
||
|
||
---
|
||
|
||
## 盘点管理接口
|
||
|
||
### 获取盘点计划列表
|
||
|
||
```http
|
||
GET /api/inventory/plans
|
||
```
|
||
|
||
**查询参数：**
|
||
|
||
| 参数名 | 类型 | 描述 |
|
||
|--------|------|------|
|
||
| status | string | 按状态筛选（draft/pending/in_progress/completed） |
|
||
| keyword | string | 关键词搜索 |
|
||
| page | number | 页码 |
|
||
| pageSize | number | 每页数量 |
|
||
|
||
### 获取单个盘点计划
|
||
|
||
```http
|
||
GET /api/inventory/plans/:planId
|
||
```
|
||
|
||
### 创建盘点计划
|
||
|
||
```http
|
||
POST /api/inventory/plans
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| name | string | 是 | 计划名称 |
|
||
| type | string | 否 | 盘点类型（full/partial），默认full |
|
||
| description | string | 否 | 描述 |
|
||
| scheduledDate | string | 否 | 计划执行日期 |
|
||
| targetRooms | array | 否 | 目标机房ID列表 |
|
||
| targetRacks | array | 否 | 目标机柜ID列表 |
|
||
|
||
### 更新盘点计划
|
||
|
||
```http
|
||
PUT /api/inventory/plans/:planId
|
||
```
|
||
|
||
### 删除盘点计划
|
||
|
||
```http
|
||
DELETE /api/inventory/plans/:planId
|
||
```
|
||
|
||
### 启动盘点计划
|
||
|
||
```http
|
||
POST /api/inventory/plans/:planId/start
|
||
```
|
||
|
||
### 完成盘点计划
|
||
|
||
```http
|
||
POST /api/inventory/plans/:planId/complete
|
||
```
|
||
|
||
### 获取盘点任务详情
|
||
|
||
```http
|
||
GET /api/inventory/tasks/:taskId
|
||
```
|
||
|
||
### 更新盘点任务
|
||
|
||
```http
|
||
PUT /api/inventory/tasks/:taskId
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| assignedTo | string | 否 | 指派人员ID |
|
||
| status | string | 否 | 任务状态 |
|
||
|
||
### 盘点记录核查
|
||
|
||
```http
|
||
POST /api/inventory/records/:recordId/check
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| actualSerialNumber | string | 否 | 实际序列号 |
|
||
| actualRackId | string | 否 | 实际机柜ID |
|
||
| actualPosition | number | 否 | 实际位置 |
|
||
| status | string | 是 | 核查状态（normal/abnormal/not_found） |
|
||
| remark | string | 否 | 备注 |
|
||
| photoUrl | string | 否 | 照片URL |
|
||
|
||
### 获取盘点记录列表
|
||
|
||
```http
|
||
GET /api/inventory/records
|
||
```
|
||
|
||
**查询参数：**
|
||
|
||
| 参数名 | 类型 | 描述 |
|
||
|--------|------|------|
|
||
| planId | string | 按计划筛选 |
|
||
| taskId | string | 按任务筛选 |
|
||
| status | string | 按状态筛选 |
|
||
| page | number | 页码 |
|
||
| pageSize | number | 每页数量 |
|
||
|
||
### 获取盘点统计
|
||
|
||
```http
|
||
GET /api/inventory/stats/dashboard
|
||
```
|
||
|
||
### 快速添加设备（盘点时）
|
||
|
||
```http
|
||
POST /api/inventory/quick-add-device
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| planId | string | 是 | 盘点计划ID |
|
||
| taskId | string | 否 | 盘点任务ID |
|
||
| serialNumber | string | 是 | 序列号 |
|
||
| name | string | 否 | 设备名称 |
|
||
| type | string | 否 | 设备类型 |
|
||
| roomId | string | 否 | 机房ID |
|
||
| rackId | string | 否 | 机柜ID |
|
||
| position | number | 否 | 位置 |
|
||
| model | string | 否 | 型号 |
|
||
| brand | string | 否 | 品牌 |
|
||
| height | number | 否 | 高度(U) |
|
||
| powerConsumption | number | 否 | 功耗(W) |
|
||
| ipAddress | string | 否 | IP地址 |
|
||
| purchaseDate | string | 否 | 购买日期 |
|
||
| warrantyExpiry | string | 否 | 保修到期日期 |
|
||
| description | string | 否 | 描述 |
|
||
| remark | string | 否 | 备注 |
|
||
|
||
### 获取暂存设备列表
|
||
|
||
```http
|
||
GET /api/inventory/pending-devices
|
||
```
|
||
|
||
**查询参数：**
|
||
|
||
| 参数名 | 类型 | 描述 |
|
||
|--------|------|------|
|
||
| status | string | 按状态筛选（pending/synced） |
|
||
| planId | string | 按盘点计划筛选 |
|
||
| roomId | string | 按机房筛选 |
|
||
| keyword | string | 关键词搜索 |
|
||
| page | number | 页码 |
|
||
| pageSize | number | 每页数量 |
|
||
|
||
### 获取暂存设备统计
|
||
|
||
```http
|
||
GET /api/inventory/pending-devices/stats
|
||
```
|
||
|
||
### 获取暂存设备详情
|
||
|
||
```http
|
||
GET /api/inventory/pending-devices/:pendingId
|
||
```
|
||
|
||
### 更新暂存设备
|
||
|
||
```http
|
||
PUT /api/inventory/pending-devices/:pendingId
|
||
```
|
||
|
||
### 删除暂存设备
|
||
|
||
```http
|
||
DELETE /api/inventory/pending-devices/:pendingId
|
||
```
|
||
|
||
### 同步暂存设备到设备管理
|
||
|
||
```http
|
||
POST /api/inventory/pending-devices/:pendingId/sync
|
||
```
|
||
|
||
### 批量同步暂存设备
|
||
|
||
```http
|
||
POST /api/inventory/pending-devices/batch-sync
|
||
```
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|--------|------|------|------|
|
||
| pendingIds | array | 是 | 暂存设备ID列表 |
|
||
|
||
---
|
||
|
||
## 健康检查接口
|
||
|
||
### 服务状态检查
|
||
|
||
```http
|
||
GET /health
|
||
```
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"message": "IDC设备管理系统后端服务正常运行"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 错误码说明
|
||
|
||
| 状态码 | 错误码 | 说明 |
|
||
|--------|--------|------|
|
||
| 400 | BAD_REQUEST | 请求参数错误 |
|
||
| 401 | UNAUTHORIZED | 未授权访问，Token无效或过期 |
|
||
| 403 | FORBIDDEN | 禁止访问，权限不足 |
|
||
| 404 | NOT_FOUND | 资源不存在 |
|
||
| 409 | CONFLICT | 资源冲突（如重复ID、端口占用） |
|
||
| 422 | VALIDATION_ERROR | 数据验证失败 |
|
||
| 500 | INTERNAL_ERROR | 服务器内部错误 |
|
||
| 503 | SERVICE_UNAVAILABLE | 服务暂不可用 |
|
||
|
||
### 常见错误示例
|
||
|
||
**认证失败：**
|
||
```json
|
||
{
|
||
"success": false,
|
||
"error": "UNAUTHORIZED",
|
||
"message": "Token已过期，请重新登录"
|
||
}
|
||
```
|
||
|
||
**参数错误：**
|
||
```json
|
||
{
|
||
"success": false,
|
||
"error": "VALIDATION_ERROR",
|
||
"message": "设备ID不能为空"
|
||
}
|
||
```
|
||
|
||
**资源不存在：**
|
||
```json
|
||
{
|
||
"success": false,
|
||
"error": "NOT_FOUND",
|
||
"message": "设备不存在"
|
||
}
|
||
```
|
||
|
||
**权限不足：**
|
||
```json
|
||
{
|
||
"success": false,
|
||
"error": "FORBIDDEN",
|
||
"message": "您没有权限执行此操作"
|
||
}
|
||
```
|
||
|
||
**资源冲突：**
|
||
```json
|
||
{
|
||
"error": "端口已被占用",
|
||
"conflict": true,
|
||
"existingCable": {...}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 接口汇总
|
||
|
||
| 接口路径 | 方法 | 描述 |
|
||
|----------|------|------|
|
||
| /api/auth/login | POST | 用户登录 |
|
||
| /api/auth/register | POST | 用户注册 |
|
||
| /api/auth/me | GET | 获取当前用户信息 |
|
||
| /api/rooms | GET/POST | 机房列表/创建 |
|
||
| /api/rooms/:roomId | GET/PUT/DELETE | 机房详情/更新/删除 |
|
||
| /api/racks | GET/POST | 机柜列表/创建 |
|
||
| /api/racks/:rackId | GET/PUT/DELETE | 机柜详情/更新/删除 |
|
||
| /api/racks/import-template | GET | 获取机柜导入模板 |
|
||
| /api/racks/export | GET | 导出机柜数据 |
|
||
| /api/racks/import | POST | 导入机柜数据 |
|
||
| /api/devices | GET/POST | 设备列表/创建 |
|
||
| /api/devices/:deviceId | GET/PUT/DELETE | 设备详情/更新/删除 |
|
||
| /api/devices/batch-delete | DELETE | 批量删除设备 |
|
||
| /api/devices/delete-all | DELETE | 删除所有设备 |
|
||
| /api/devices/batch-online | PUT | 批量上线设备 |
|
||
| /api/devices/batch-offline | PUT | 批量下线设备 |
|
||
| /api/devices/batch-status | PUT | 批量变更设备状态 |
|
||
| /api/devices/batch-move | PUT | 批量移动设备 |
|
||
| /api/devices/import-template | GET | 获取设备导入模板 |
|
||
| /api/devices/export | GET | 导出设备数据 |
|
||
| /api/devices/import | POST | 导入设备数据 |
|
||
| /api/devices/enhanced-export | GET | 增强导出设备数据 |
|
||
| /api/devices/:deviceId/tickets | GET | 获取设备的工单列表 |
|
||
| /api/deviceFields | GET/POST | 设备字段列表/创建 |
|
||
| /api/deviceFields/:id | PUT/DELETE | 设备字段更新/删除 |
|
||
| /api/device-ports | GET/POST | 端口列表/创建 |
|
||
| /api/device-ports/device/:deviceId | GET | 获取设备的所有端口 |
|
||
| /api/device-ports/:portId | GET/PUT/DELETE | 端口详情/更新/删除 |
|
||
| /api/device-ports/batch | POST/DELETE | 批量创建/删除端口 |
|
||
| /api/network-cards | GET/POST | 网卡列表/创建 |
|
||
| /api/network-cards/device/:deviceId | GET | 获取设备的所有网卡 |
|
||
| /api/network-cards/device/:deviceId/with-ports | GET | 获取设备的网卡及端口信息 |
|
||
| /api/network-cards/:nicId | GET/PUT/DELETE | 网卡详情/更新/删除 |
|
||
| /api/network-cards/:nicId/ports | GET | 获取网卡的端口列表 |
|
||
| /api/cables | GET/POST | 线缆列表/创建 |
|
||
| /api/cables/device/:deviceId | GET | 获取设备的所有接线 |
|
||
| /api/cables/rack/:rackId | GET | 获取机柜内所有设备的接线 |
|
||
| /api/cables/check-conflict | POST | 检查接线冲突 |
|
||
| /api/cables/:cableId | GET/PUT/DELETE | 线缆详情/更新/删除 |
|
||
| /api/cables/batch | POST/DELETE | 批量创建/删除线缆 |
|
||
| /api/tickets | GET/POST | 工单列表/创建 |
|
||
| /api/tickets/stats | GET | 工单统计 |
|
||
| /api/tickets/:ticketId | GET/PUT/DELETE | 工单详情/更新/删除 |
|
||
| /api/tickets/:ticketId/status | PUT | 更新工单状态 |
|
||
| /api/tickets/:ticketId/process | PUT | 处理工单 |
|
||
| /api/tickets/:ticketId/operations | GET/POST | 工单操作记录/添加操作记录 |
|
||
| /api/tickets/:ticketId/evaluate | POST | 评价工单 |
|
||
| /api/ticket-categories | GET/POST | 工单分类列表/创建 |
|
||
| /api/ticket-categories/:id | PUT/DELETE | 工单分类更新/删除 |
|
||
| /api/ticket-fields | GET/POST | 工单字段列表/创建 |
|
||
| /api/ticket-fields/:id | PUT/DELETE | 工单字段更新/删除 |
|
||
| /api/consumables | GET/POST | 耗材列表/创建 |
|
||
| /api/consumables/:id | GET/PUT/DELETE | 耗材详情/更新/删除 |
|
||
| /api/consumables/import | POST | 导入耗材 |
|
||
| /api/consumables/categories/list | GET | 获取耗材分类列表 |
|
||
| /api/consumables/low-stock | GET | 获取低库存耗材 |
|
||
| /api/consumables/statistics/summary | GET | 获取耗材统计汇总 |
|
||
| /api/consumables/inout/records | GET | 获取出入库记录 |
|
||
| /api/consumables/quick-inout | POST | 快速出入库 |
|
||
| /api/consumables/inout | POST | 出入库操作 |
|
||
| /api/consumables/adjust | POST | 库存调整 |
|
||
| /api/consumables/logs | GET | 获取耗材操作日志 |
|
||
| /api/consumables/logs/export | GET | 导出耗材日志 |
|
||
| /api/consumables/logs/import | POST | 导入耗材日志 |
|
||
| /api/consumables/logs/:id | PUT | 修改日志记录 |
|
||
| /api/consumables/logs/:id/history | GET | 获取日志修改历史 |
|
||
| /api/consumables/archives | GET | 获取归档记录列表 |
|
||
| /api/consumables/archives/:archiveId | GET | 获取归档记录详情 |
|
||
| /api/consumables/by-sn/:sn | GET | 根据SN查询耗材 |
|
||
| /api/consumable-categories | GET/POST | 耗材分类列表/创建 |
|
||
| /api/consumable-categories/:id | PUT/DELETE | 耗材分类更新/删除 |
|
||
| /api/consumable-records | GET/POST | 耗材记录列表/创建 |
|
||
| /api/users | GET/POST | 用户列表/创建 |
|
||
| /api/users/all | GET | 获取所有用户（简要信息） |
|
||
| /api/users/:userId | GET/PUT/DELETE | 用户详情/更新/删除 |
|
||
| /api/users/:userId/password | PUT | 重置密码 |
|
||
| /api/users/:userId/avatar | POST/DELETE | 上传/删除头像 |
|
||
| /api/users/:userId/approve | PUT | 审核通过用户 |
|
||
| /api/users/:userId/reject | PUT | 拒绝用户注册 |
|
||
| /api/roles | GET/POST | 角色列表/创建 |
|
||
| /api/roles/:roleId | PUT/DELETE | 角色更新/删除 |
|
||
| /api/system-settings | GET/PUT | 系统设置获取/更新 |
|
||
| /api/background | GET/PUT | 背景配置获取/更新 |
|
||
| /api/inventory/plans | GET/POST | 盘点计划列表/创建 |
|
||
| /api/inventory/plans/:planId | GET/PUT/DELETE | 盘点计划详情/更新/删除 |
|
||
| /api/inventory/plans/:planId/start | POST | 启动盘点计划 |
|
||
| /api/inventory/plans/:planId/complete | POST | 完成盘点计划 |
|
||
| /api/inventory/tasks/:taskId | GET/PUT | 盘点任务详情/更新 |
|
||
| /api/inventory/records | GET | 盘点记录列表 |
|
||
| /api/inventory/records/:recordId/check | POST | 盘点记录核查 |
|
||
| /api/inventory/stats/dashboard | GET | 盘点统计 |
|
||
| /api/inventory/quick-add-device | POST | 快速添加设备 |
|
||
| /api/inventory/pending-devices | GET | 暂存设备列表 |
|
||
| /api/inventory/pending-devices/stats | GET | 暂存设备统计 |
|
||
| /api/inventory/pending-devices/:pendingId | GET/PUT/DELETE | 暂存设备详情/更新/删除 |
|
||
| /api/inventory/pending-devices/:pendingId/sync | POST | 同步暂存设备 |
|
||
| /api/inventory/pending-devices/batch-sync | POST | 批量同步暂存设备 |
|
||
| /health | GET | 服务健康检查 |
|
||
|
||
---
|
||
|
||
**文档版本：** 2.0.0
|
||
**最后更新：** 2026-03-11
|