yunrui_asset/docs/api

API接口文档

本文档描述IDC设备管理系统的后端API接口，遵循RESTful设计规范。

---

目录

• 基础信息
• 认证接口
• 机房管理接口
• 机柜管理接口
• 设备管理接口
• 设备字段接口
• 设备端口接口
• 网卡接口
• 线缆接口
• 工单管理接口
• 工单分类接口
• 工单字段接口
• 耗材管理接口
• 耗材分类接口
• 耗材记录接口
• 盘点管理接口
• 空闲设备接口
• 操作日志接口
• 备份管理接口
• 仓库管理接口
• 拓扑管理接口
• 用户管理接口
• 角色管理接口
• 系统设置接口
• 背景配置接口
• 健康检查接口
• 错误码说明

---

基础信息

项目	值
Base URL	http://localhost:8000/api
Content-Type	application/json
认证方式	Bearer Token (JWT)

通用请求头

Content-Type: application/json
Authorization: Bearer <token>

通用响应格式

成功响应

{
  "success": true,
  "data": {...},
  "message": "操作成功"
}

错误响应

{
  "success": false,
  "error": "错误信息",
  "message": "详细描述"
}

分页参数

列表接口支持以下分页参数：

参数名	类型	必填	默认值	描述
page	number	否	1	页码
pageSize	number	否	10	每页数量

分页响应示例：

{
  "success": true,
  "data": {
    "list": [...],
    "total": 100,
    "page": 1,
    "pageSize": 10,
    "totalPages": 10
  },
  "message": "操作成功"
}

---

认证接口

用户登录

POST /api/auth/login

请求参数：

参数名	类型	必填	描述
username	string	是	用户名
password	string	是	密码

请求示例：

{
  "username": "admin",
  "password": "password123"
}

响应示例：

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "userId": "user001",
      "username": "admin",
      "email": "admin@example.com",
      "phone": "13800138000",
      "status": "active",
      "Roles": [
        {
          "roleId": "role001",
          "roleName": "管理员"
        }
      ]
    }
  },
  "message": "登录成功"
}

用户注册

POST /api/auth/register

请求参数：

参数名	类型	必填	描述
username	string	是	用户名（3-20字符）
password	string	是	密码（6-20字符）
email	string	否	邮箱
phone	string	否	电话

请求示例：

{
  "username": "newuser",
  "password": "password123",
  "email": "user@example.com",
  "phone": "13800138000"
}

获取当前用户信息

GET /api/auth/me

响应示例：

{
  "success": true,
  "data": {
    "userId": "user001",
    "username": "admin",
    "email": "admin@example.com",
    "Roles": [...]
  },
  "message": "操作成功"
}

---

机房管理接口

获取机房列表

GET /api/rooms

查询参数：

参数名	类型	描述
keyword	string	按名称搜索
status	string	按状态筛选

响应示例：

{
  "roomId": "room001",
  "name": "A区机房",
  "location": "一楼东侧",
  "area": 500,
  "description": "主要服务器机房",
  "status": "active",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

获取单个机房

GET /api/rooms/:roomId

创建机房

POST /api/rooms

请求参数：

参数名	类型	必填	描述
roomId	string	是	机房ID（唯一标识）
name	string	是	机房名称
location	string	否	机房位置
area	number	否	面积(平方米)
description	string	否	描述
status	string	否	状态（active/inactive）

请求示例：

{
  "roomId": "room002",
  "name": "B区机房",
  "location": "二楼西侧",
  "area": 600,
  "description": "网络设备机房",
  "status": "active"
}

更新机房

PUT /api/rooms/:roomId

请求参数： 同创建机房（roomId除外）

删除机房

DELETE /api/rooms/:roomId

说明： 删除机房前需确保机房下无机柜

---

机柜管理接口

获取机柜列表

GET /api/racks

查询参数：

参数名	类型	描述
roomId	string	按机房ID筛选
status	string	按状态筛选
keyword	string	按名称搜索
page	number	页码
pageSize	number	每页数量

响应示例：

{
  "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
}

获取单个机柜

GET /api/racks/:rackId

创建机柜

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	否	描述

请求示例：

{
  "name": "机柜A2",
  "height": 42,
  "maxPower": 5000,
  "roomId": "room001",
  "status": "active",
  "description": "核心交换机机柜"
}

更新机柜

PUT /api/racks/:rackId

删除机柜

DELETE /api/racks/:rackId

说明： 删除机柜前需确保机柜下无设备

获取机柜导入模板

GET /api/racks/import-template

响应： 返回Excel模板文件

导出机柜数据

GET /api/racks/export

响应： 返回Excel文件

导入机柜数据

POST /api/racks/import

Content-Type: multipart/form-data

请求参数：

参数名	类型	必填	描述
file	File	是	Excel格式的机柜数据文件

---

设备管理接口

获取设备列表

GET /api/devices

查询参数：

参数名	类型	描述
rackId	string	按机柜ID筛选
type	string	按设备类型筛选
status	string	按状态筛选
keyword	string	按名称/IP/序列号搜索
page	number	页码，默认1
pageSize	number	每页数量，默认10

响应示例：

{
  "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
}

获取单个设备

GET /api/devices/:deviceId

创建设备

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	否	自定义字段值

请求示例：

{
  "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"
  }
}

更新设备

PUT /api/devices/:deviceId

删除设备

DELETE /api/devices/:deviceId

批量删除设备

DELETE /api/devices/batch-delete

请求参数：

参数名	类型	必填	描述
deviceIds	array	是	设备ID列表

请求示例：

{
  "deviceIds": ["dev001", "dev002", "dev003"]
}

删除所有设备

DELETE /api/devices/delete-all

批量上线设备

PUT /api/devices/batch-online

请求参数：

参数名	类型	必填	描述
deviceIds	array	是	设备ID列表

批量下线设备

PUT /api/devices/batch-offline

请求参数：

参数名	类型	必填	描述
deviceIds	array	是	设备ID列表

批量变更设备状态

PUT /api/devices/batch-status

请求参数：

参数名	类型	必填	描述
deviceIds	array	是	设备ID列表
status	string	是	目标状态（running/maintenance/offline/fault）

批量移动设备

PUT /api/devices/batch-move

请求参数：

参数名	类型	必填	描述
deviceIds	array	是	设备ID列表
targetRackId	string	是	目标机柜ID
startPosition	number	否	起始位置

获取设备导入模板

GET /api/devices/import-template

响应： 返回CSV模板文件

导出设备数据

GET /api/devices/export

查询参数：

参数名	类型	描述
deviceIds	string/array	指定导出的设备ID

响应： 返回CSV文件

导入设备数据

POST /api/devices/import

Content-Type: multipart/form-data

请求参数：

参数名	类型	必填	描述
csvFile	File	是	CSV格式的设备数据文件

增强导出设备数据

POST /api/devices/enhanced-export

请求体参数：

参数名	类型	描述
deviceIds	array	指定导出的设备ID列表（与filters二选一）
format	string	导出格式（csv/json），默认csv
filters	object	筛选条件（导出全部设备时使用）
filters.keyword	string	搜索关键词
filters.status	string	设备状态筛选
filters.type	string	设备类型筛选
filters.roomId	string	机房ID筛选
filters.rackId	string	机柜ID筛选

获取设备的工单列表

GET /api/devices/:deviceId/tickets

查询参数：

参数名	类型	描述
status	string	按状态筛选
page	number	页码
pageSize	number	每页数量

---

设备字段接口

获取设备字段列表

GET /api/deviceFields

响应示例：

{
  "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": "操作成功"
}

创建设备字段

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

更新设备字段

PUT /api/deviceFields/:id

删除设备字段

DELETE /api/deviceFields/:id

说明： 系统字段（isSystem=true）不可删除

---

设备端口接口

获取端口列表

GET /api/device-ports

查询参数：

参数名	类型	描述
deviceId	string	按设备ID筛选
status	string	按状态筛选（free/occupied/fault）
portType	string	按端口类型筛选
portSpeed	string	按端口速率筛选
page	number	页码
pageSize	number	每页数量

获取设备的所有端口

GET /api/device-ports/device/:deviceId

获取单个端口详情

GET /api/device-ports/:portId

创建端口

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	否	描述

批量创建端口

POST /api/device-ports/batch

请求参数：

参数名	类型	必填	描述
ports	array	是	端口数据列表

更新端口

PUT /api/device-ports/:portId

删除端口

DELETE /api/device-ports/:portId

批量删除端口

DELETE /api/device-ports/batch

请求参数：

参数名	类型	必填	描述
portIds	array	是	端口ID列表

---

网卡接口

获取网卡列表

GET /api/network-cards

查询参数：

参数名	类型	描述
deviceId	string	按设备ID筛选

获取设备的所有网卡

GET /api/network-cards/device/:deviceId

获取设备的网卡及端口信息

GET /api/network-cards/device/:deviceId/with-ports

获取单个网卡详情

GET /api/network-cards/:nicId

获取网卡的端口列表

GET /api/network-cards/:nicId/ports

创建网卡

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

更新网卡

PUT /api/network-cards/:nicId

删除网卡

DELETE /api/network-cards/:nicId

说明： 删除网卡前需确保网卡下无端口

---

线缆接口

获取线缆列表

GET /api/cables

查询参数：

参数名	类型	描述
sourceDeviceId	string	按源设备筛选
targetDeviceId	string	按目标设备筛选
status	string	按状态筛选
cableType	string	按线缆类型筛选
page	number	页码
pageSize	number	每页数量

获取设备的所有接线

GET /api/cables/device/:deviceId

获取机柜内所有设备的接线

GET /api/cables/rack/:rackId

检查接线冲突

POST /api/cables/check-conflict

请求参数：

参数名	类型	必填	描述
sourceDeviceId	string	是	源设备ID
sourcePort	string	是	源端口名称
targetDeviceId	string	是	目标设备ID
targetPort	string	是	目标端口名称
excludeCableId	string	否	排除的线缆ID（用于编辑时）

获取单个线缆详情

GET /api/cables/:cableId

创建线缆

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	否	是否强制创建（覆盖已有连接）

批量创建线缆

POST /api/cables/batch

请求参数：

参数名	类型	必填	描述
cables	array	是	线缆数据列表

更新线缆

PUT /api/cables/:cableId

删除线缆

DELETE /api/cables/:cableId

批量删除线缆

DELETE /api/cables/batch

请求参数：

参数名	类型	必填	描述
cableIds	array	是	线缆ID列表

---

工单管理接口

获取工单列表

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	每页数量

响应示例：

{
  "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
}

获取工单统计

GET /api/tickets/stats

查询参数：

参数名	类型	描述
startDate	string	开始日期
endDate	string	结束日期

获取单个工单详情

GET /api/tickets/:ticketId

创建工单

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	否	标签列表

更新工单

PUT /api/tickets/:ticketId

更新工单状态

PUT /api/tickets/:ticketId/status

请求参数：

参数名	类型	必填	描述
status	string	是	目标状态
resolution	string	否	解决方案（完成时填写）
operatorId	string	否	操作人ID
operatorName	string	否	操作人姓名
operatorRole	string	否	操作人角色

处理工单

PUT /api/tickets/:ticketId/process

请求参数：

参数名	类型	必填	描述
solution	string	否	解决方案
result	string	否	处理结果（resolved/unresolved）
notes	string	否	备注
usedParts	string	否	使用配件
operatorId	string	否	操作人ID
operatorName	string	否	操作人姓名

添加工单操作记录

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	否	操作人角色

获取工单操作记录

GET /api/tickets/:ticketId/operations

删除工单

DELETE /api/tickets/:ticketId

评价工单

POST /api/tickets/:ticketId/evaluate

请求参数：

参数名	类型	必填	描述
evaluation	string	是	评价内容
evaluationRating	number	是	评分(1-5)
operatorId	string	否	操作人ID
operatorName	string	否	操作人姓名

---

工单分类接口

获取分类列表

GET /api/ticket-categories

创建分类

POST /api/ticket-categories

请求参数：

参数名	类型	必填	描述
categoryId	string	是	分类ID（唯一标识）
name	string	是	分类名称
description	string	否	描述
sortOrder	number	否	排序顺序

更新分类

PUT /api/ticket-categories/:id

删除分类

DELETE /api/ticket-categories/:id

---

工单字段接口

获取字段列表

GET /api/ticket-fields

创建字段

POST /api/ticket-fields

请求参数：

参数名	类型	必填	描述
fieldName	string	是	字段名（英文，唯一）
displayName	string	是	显示名称（中文）
fieldType	string	是	字段类型（text/number/date/select/textarea）
isRequired	boolean	否	是否必填
defaultValue	string	否	默认值
options	string	否	选项（逗号分隔）
sortOrder	number	否	排序顺序

更新字段

PUT /api/ticket-fields/:id

删除字段

DELETE /api/ticket-fields/:id

---

耗材管理接口

获取耗材列表

GET /api/consumables

查询参数：

参数名	类型	描述
category	string	按分类筛选
status	string	按状态筛选
keyword	string	按名称搜索
page	number	页码
pageSize	number	每页数量

响应示例：

{
  "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
}

获取单个耗材

GET /api/consumables/:id

创建耗材

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	否	描述

更新耗材

PUT /api/consumables/:id

删除耗材

DELETE /api/consumables/:id

导入耗材

POST /api/consumables/import

请求参数：

参数名	类型	必填	描述
items	array	是	耗材数据列表
operator	string	否	操作人

获取耗材分类列表

GET /api/consumables/categories/list

获取低库存耗材

GET /api/consumables/low-stock

获取耗材统计汇总

GET /api/consumables/statistics/summary

获取出入库记录

GET /api/consumables/inout/records

查询参数：

参数名	类型	描述
page	number	页码
pageSize	number	每页数量

快速出入库

POST /api/consumables/quick-inout

请求参数：

参数名	类型	必填	描述
consumableId	string	是	耗材ID
type	string	是	类型（in/out）
quantity	number	是	数量
operator	string	否	操作人
reason	string	否	原因
notes	string	否	备注
snList	array	否	SN列表

出入库操作

POST /api/consumables/inout

请求参数：

参数名	类型	必填	描述
consumableId	string	是	耗材ID
type	string	是	类型（in/out）
quantity	number	是	数量
operator	string	否	操作人
reason	string	否	原因
recipient	string	否	领用人
notes	string	否	备注
snList	array	否	SN列表

库存调整

POST /api/consumables/adjust

请求参数：

参数名	类型	必填	描述
consumableId	string	是	耗材ID
adjustType	string	是	调整类型（add/subtract/set）
quantity	number	是	数量
operator	string	否	操作人
reason	string	否	原因
notes	string	否	备注

获取耗材操作日志

GET /api/consumables/logs

查询参数：

参数名	类型	描述
consumableId	string	按耗材筛选
operationType	string	按操作类型筛选（多个用逗号分隔）
startDate	string	开始日期
endDate	string	结束日期
page	number	页码
pageSize	number	每页数量

导出耗材日志

GET /api/consumables/logs/export

查询参数：

参数名	类型	描述
consumableId	string	按耗材筛选
operationType	string	按操作类型筛选
startDate	string	开始日期
endDate	string	结束日期

导入耗材日志

POST /api/consumables/logs/import

请求参数：

参数名	类型	必填	描述
logs	array	是	日志数据列表
operator	string	否	操作人

修改日志记录

PUT /api/consumables/logs/:id

请求参数：

参数名	类型	必填	描述
reason	string	否	原因
notes	string	否	备注
operator	string	否	操作人
modificationReason	string	否	修改原因

获取日志修改历史

GET /api/consumables/logs/:id/history

获取归档记录列表

GET /api/consumables/archives

查询参数：

参数名	类型	描述
keyword	string	关键词搜索
page	number	页码
pageSize	number	每页数量

获取归档记录详情

GET /api/consumables/archives/:archiveId

根据SN查询耗材

GET /api/consumables/by-sn/:sn

---

耗材分类接口

获取分类列表

GET /api/consumable-categories

创建分类

POST /api/consumable-categories

请求参数：

参数名	类型	必填	描述
categoryId	string	是	分类ID（唯一标识）
name	string	是	分类名称
description	string	否	描述

更新分类

PUT /api/consumable-categories/:id

删除分类

DELETE /api/consumable-categories/:id

---

耗材记录接口

获取领用记录列表

GET /api/consumable-records

查询参数：

参数名	类型	描述
consumableId	string	按耗材筛选
userId	string	按用户筛选
type	string	按类型筛选（领用/归还/报废）
startDate	string	开始日期
endDate	string	结束日期

创建领用记录

POST /api/consumable-records

请求参数：

参数名	类型	必填	描述
consumableId	string	是	耗材ID
quantity	number	是	数量
type	string	是	类型（领用/归还/报废）
userId	string	是	用户ID
deviceId	string	否	关联设备ID
description	string	否	说明

---

用户管理接口

获取用户列表

GET /api/users

查询参数：

参数名	类型	描述
username	string	按用户名搜索
realName	string	按姓名搜索
status	string	按状态筛选
page	number	页码
pageSize	number	每页数量

响应示例：

{
  "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"
      }
    ]
  }
}

获取所有用户（简要信息）

GET /api/users/all

获取单个用户

GET /api/users/:userId

创建用户

POST /api/users

请求参数：

参数名	类型	必填	描述
username	string	是	用户名
password	string	是	密码
email	string	否	邮箱
phone	string	否	电话
realName	string	否	真实姓名
status	string	否	状态（active/inactive/pending），默认active
roleIds	array	否	角色ID列表
remark	string	否	备注

更新用户

PUT /api/users/:userId

请求参数：

参数名	类型	必填	描述
username	string	否	用户名
email	string	否	邮箱
phone	string	否	电话
realName	string	否	真实姓名
status	string	否	状态
roleIds	array	否	角色ID列表
remark	string	否	备注
newPassword	string	否	新密码

删除用户

DELETE /api/users/:userId

重置密码

PUT /api/users/:userId/password

请求参数：

参数名	类型	必填	描述
newPassword	string	是	新密码

上传头像

POST /api/users/:userId/avatar

Content-Type: multipart/form-data

请求参数：

参数名	类型	必填	描述
avatar	File	是	头像图片文件（JPG/PNG/GIF/WebP）

删除头像

DELETE /api/users/:userId/avatar

审核通过用户

PUT /api/users/:userId/approve

拒绝用户注册

PUT /api/users/:userId/reject

---

角色管理接口

获取角色列表

GET /api/roles

响应示例：

{
  "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": "操作成功"
}

创建角色

POST /api/roles

请求参数：

参数名	类型	必填	描述
roleId	string	是	角色ID（唯一标识）
roleName	string	是	角色名称
roleCode	string	否	角色代码
description	string	否	描述
permissionIds	array	否	权限ID列表

更新角色

PUT /api/roles/:roleId

删除角色

DELETE /api/roles/:roleId

---

系统设置接口

获取系统设置

GET /api/system-settings

响应示例：

{
  "success": true,
  "data": {
    "siteName": "IDC设备管理系统",
    "siteLogo": "/uploads/logo.png",
    "siteDescription": "专业的数据中心设备管理平台",
    "copyright": "© 2024 IDC Management",
    "version": "1.0.0"
  },
  "message": "操作成功"
}

更新系统设置

PUT /api/system-settings

请求参数：

参数名	类型	必填	描述
siteName	string	否	站点名称
siteLogo	string	否	站点Logo路径
siteDescription	string	否	站点描述
copyright	string	否	版权信息

---

背景配置接口

获取背景配置

GET /api/background

响应示例：

{
  "success": true,
  "data": {
    "loginBackground": "/uploads/bg/login.jpg",
    "dashboardBackground": "/uploads/bg/dashboard.jpg",
    "primaryColor": "#1890ff"
  },
  "message": "操作成功"
}

更新背景配置

PUT /api/background

请求参数：

参数名	类型	必填	描述
loginBackground	string	否	登录页背景图
dashboardBackground	string	否	仪表盘背景图
primaryColor	string	否	主题主色

---

盘点管理接口

获取盘点计划列表

GET /api/inventory/plans

查询参数：

参数名	类型	描述
status	string	按状态筛选（draft/pending/in_progress/completed）
keyword	string	关键词搜索
page	number	页码
pageSize	number	每页数量

获取单个盘点计划

GET /api/inventory/plans/:planId

创建盘点计划

POST /api/inventory/plans

请求参数：

参数名	类型	必填	描述
name	string	是	计划名称
type	string	否	盘点类型（full/partial），默认full
description	string	否	描述
scheduledDate	string	否	计划执行日期
targetRooms	array	否	目标机房ID列表
targetRacks	array	否	目标机柜ID列表

更新盘点计划

PUT /api/inventory/plans/:planId

删除盘点计划

DELETE /api/inventory/plans/:planId

启动盘点计划

POST /api/inventory/plans/:planId/start

完成盘点计划

POST /api/inventory/plans/:planId/complete

获取盘点任务详情

GET /api/inventory/tasks/:taskId

更新盘点任务

PUT /api/inventory/tasks/:taskId

请求参数：

参数名	类型	必填	描述
assignedTo	string	否	指派人员ID
status	string	否	任务状态

盘点记录核查

POST /api/inventory/records/:recordId/check

请求参数：

参数名	类型	必填	描述
actualSerialNumber	string	否	实际序列号
actualRackId	string	否	实际机柜ID
actualPosition	number	否	实际位置
status	string	是	核查状态（normal/abnormal/not_found）
remark	string	否	备注
photoUrl	string	否	照片URL

获取盘点记录列表

GET /api/inventory/records

查询参数：

参数名	类型	描述
planId	string	按计划筛选
taskId	string	按任务筛选
status	string	按状态筛选
page	number	页码
pageSize	number	每页数量

获取盘点统计

GET /api/inventory/stats/dashboard

快速添加设备（盘点时）

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	否	备注

获取暂存设备列表

GET /api/inventory/pending-devices

查询参数：

参数名	类型	描述
status	string	按状态筛选（pending/synced）
planId	string	按盘点计划筛选
roomId	string	按机房筛选
keyword	string	关键词搜索
page	number	页码
pageSize	number	每页数量

获取暂存设备统计

GET /api/inventory/pending-devices/stats

获取暂存设备详情

GET /api/inventory/pending-devices/:pendingId

更新暂存设备

PUT /api/inventory/pending-devices/:pendingId

删除暂存设备

DELETE /api/inventory/pending-devices/:pendingId

同步暂存设备到设备管理

POST /api/inventory/pending-devices/:pendingId/sync

批量同步暂存设备

POST /api/inventory/pending-devices/batch-sync

请求参数：

参数名	类型	必填	描述
pendingIds	array	是	暂存设备ID列表

---

健康检查接口

服务状态检查

GET /health

响应示例：

{
  "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	服务暂不可用

常见错误示例

认证失败：

{
  "success": false,
  "error": "UNAUTHORIZED",
  "message": "Token已过期，请重新登录"
}

参数错误：

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "设备ID不能为空"
}

资源不存在：

{
  "success": false,
  "error": "NOT_FOUND",
  "message": "设备不存在"
}

权限不足：

{
  "success": false,
  "error": "FORBIDDEN",
  "message": "您没有权限执行此操作"
}

资源冲突：

{
  "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	POST	增强导出设备数据
/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	批量同步暂存设备

---

空闲设备接口

获取空闲设备列表

GET /api/idle-devices

查询参数：

参数名	类型	描述
keyword	string	关键词搜索
roomId	string	按机房筛选
page	number	页码
pageSize	number	每页数量

添加空闲设备

POST /api/idle-devices

请求参数：

参数名	类型	必填	描述
deviceId	string	是	设备ID

激活空闲设备

PUT /api/idle-devices/:deviceId/activate

删除空闲设备

DELETE /api/idle-devices/:deviceId

---

操作日志接口

获取操作日志列表

GET /api/operation-logs

查询参数：

参数名	类型	描述
module	string	按模块筛选
operationType	string	按操作类型筛选
startDate	string	开始日期
endDate	string	结束日期
operator	string	按操作人筛选
keyword	string	关键词搜索
page	number	页码
pageSize	number	每页数量

获取模块列表

GET /api/operation-logs/modules

获取操作类型列表

GET /api/operation-logs/types

获取操作日志统计

GET /api/operation-logs/statistics

查询参数：

参数名	类型	描述
startDate	string	开始日期
endDate	string	结束日期

获取操作日志详情

GET /api/operation-logs/:recordId

---

备份管理接口

创建备份

POST /api/backup

获取备份列表

GET /api/backup/list

验证备份文件

GET /api/backup/validate/:filename

获取恢复进度（SSE）

GET /api/backup/restore-progress/:filename

说明： 返回 Server-Sent Events 流，实时推送恢复进度

恢复备份

POST /api/backup/restore

请求参数：

参数名	类型	必填	描述
filename	string	是	备份文件名

上传备份文件

POST /api/backup/upload

Content-Type: multipart/form-data

下载备份文件

GET /api/backup/download/:filename

删除备份文件

DELETE /api/backup/:filename

获取备份信息

GET /api/backup/info

清理旧备份

POST /api/backup/clean

请求参数：

参数名	类型	必填	描述
keepCount	number	否	保留的备份数量

获取自动备份状态

GET /api/backup/auto/status

更新自动备份设置

POST /api/backup/auto/settings

请求参数：

参数名	类型	必填	描述
enabled	boolean	是	是否启用
cronExpression	string	否	Cron 表达式
keepCount	number	否	保留数量

立即执行自动备份

POST /api/backup/auto/execute

测试 Cron 表达式

POST /api/backup/auto/test-cron

请求参数：

参数名	类型	必填	描述
cronExpression	string	是	Cron 表达式

获取远端备份目标列表

GET /api/backup/remote/targets

获取单个远端备份目标

GET /api/backup/remote/targets/:id

添加远端备份目标

POST /api/backup/remote/targets

请求参数：

参数名	类型	必填	描述
name	string	是	目标名称
protocol	string	是	协议（ftp/sftp/webdav/smb）
host	string	是	主机地址
port	number	否	端口号
username	string	否	用户名
password	string	否	密码
remotePath	string	否	远程目录

更新远端备份目标

PUT /api/backup/remote/targets/:id

删除远端备份目标

DELETE /api/backup/remote/targets/:id

测试远端连接

POST /api/backup/remote/test

测试指定远端连接

POST /api/backup/remote/targets/:id/test

获取远端备份设置

GET /api/backup/remote/settings

更新远端备份设置

PUT /api/backup/remote/settings

获取支持的协议列表

GET /api/backup/remote/protocols

手动上传备份到远端

POST /api/backup/remote/upload

请求参数：

参数名	类型	必填	描述
filename	string	是	备份文件名
targetId	string	是	远端目标ID

获取备份日志列表

GET /api/backup/logs

获取备份日志详情

GET /api/backup/logs/:id

清理旧备份日志

DELETE /api/backup/logs/clean

---

仓库管理接口

获取仓库列表

GET /api/warehouses

创建仓库

POST /api/warehouses

请求参数：

参数名	类型	必填	描述
name	string	是	仓库名称
location	string	否	仓库位置
description	string	否	描述
manager	string	否	负责人
contact	string	否	联系方式

获取单个仓库

GET /api/warehouses/:warehouseId

更新仓库

PUT /api/warehouses/:warehouseId

删除仓库

DELETE /api/warehouses/:warehouseId

---

拓扑管理接口

获取交换机拓扑

GET /api/topology/switch/:switchId

响应示例：

{
  "success": true,
  "data": {
    "switch": {
      "deviceId": "dev001",
      "name": "核心交换机",
      "type": "switch"
    },
    "connections": [
      {
        "deviceId": "dev002",
        "name": "服务器01",
        "type": "server",
        "port": "eth0",
        "cableId": "cable001"
      }
    ]
  }
}

获取设备拓扑

GET /api/topology/device/:deviceId

---

健康检查接口

端点	方法	说明
/health	GET	服务健康检查

---

文档版本： 2.0.0
最后更新： 2026年5月