ops/front

Fork 0

Files

wang_yp 73247053dd fix(优化)

2026-08-24 22:02:55 +08:00

30 KiB

Raw Blame History

3D 机房前后端接口对接文档

本文档依据 2026-07-31 工作区内 assets、dc-control、alert 的实际代码整理，供前端开发和联调使用。

1. 对接范围

3D 机房由 Assets 服务提供统一场景接口，支持：

加载单个机房或全部有权限的 3D 场景。
保存机房长、宽、高。
拖拽机柜并保存三维坐标。
将设备放入机柜并调整 U 位。
将智能空调、监控摄像头、智能插座等设备直接放置在机房内。
解除设备在机柜或机房内的位置。
查看设备运行状态、最新指标和活动告警。
将资产与 dc-control 监控资源绑定。

前端渲染和写入场景时主要访问 Assets。Assets 会在后台聚合 dc-control 和 alert，前端不直接调用运行状态及活动告警的内部批量接口。

2. 通用约定

2.1 基础地址和请求头

本文使用 {API_BASE} 表示网关地址，例如：

{API_BASE}/Assets/v1/three-d/rooms/1/scene

所有本文列出的接口均需要 JWT：

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

GET 请求不需要设置 Content-Type。DELETE 设备位置接口需要携带 JSON 请求体。

2.2 统一响应结构

成功响应：

{
  "code": 0,
  "message": "",
  "details": {},
  "timeseq": 1785465600000
}

失败响应示例：

{
  "code": 500,
  "message": "布局版本已变化，当前版本为 5",
  "details": "",
  "timeseq": 1785465600000
}

注意：

业务成功以 code === 0 为准。
当前统一响应即使业务失败，HTTP 状态通常仍为 200，不能只判断 HTTP 状态。
失败时直接展示或记录 message；details 不承载错误详情。
timeseq 是毫秒时间戳。

2.3 数据权限

3D 接口从 JWT 扩展声明中读取数据范围：

JWT 扩展字段	示例	含义
`data_scope_all`	`"true"`	可访问全部机房
`data_scope_datacenter_ids`	`"1,2"`	可访问指定数据中心
`data_scope_room_ids`	`"10,11"`	可访问指定机房

规则：

仅配置数据中心范围时，该数据中心下的机房可访问。
仅配置机房范围时，指定机房可访问。
两种范围同时存在时，数据中心和机房必须同时匹配。
三个字段均未提供时，3D 接口返回“登录凭证缺少机房数据权限”。
前端不能通过自定义请求头或查询参数扩大数据范围。

2.4 坐标和尺寸

坐标系约定：

X：机房长度方向。
Y：高度方向。
Z：机房宽度方向。
场景坐标、机房尺寸和独立设备尺寸单位均为米。
position_x/y/z 表示物体底面中心点，不是包围盒中心点。
设备旋转角度单位为度，合法范围为 [0, 360)，旋转顺序为 X、Y、Z。
机柜只允许绕 Y 轴旋转。
传入的小数会四舍五入到两位后再校验和保存。

机柜尺寸：

width_mm、depth_mm 的单位是毫米。
height 的单位是 U。
后端进行空间碰撞校验时，机柜高度按 height × 0.04445 米计算。

边界范围：

X: 0 ~ scene_length
Y: 0 ~ scene_height
Z: 0 ~ scene_width

后端会对机柜和机房内独立设备做完整三维有向包围盒校验，包括越界、机柜与机柜、机柜与独立设备、独立设备与独立设备的重叠。物体边界接触允许，空间重叠不允许。

机柜内设备不参与场景包围盒碰撞，其位置由机柜和 U 位约束。

2.5 布局版本和并发控制

每个机房包含 layout_version。以下写接口都必须提交当前版本：

保存机房 3D 配置。
保存机柜布局。
保存设备位置。
解除设备位置。

每次成功写入后版本加一，响应会返回新的 layout_version。

前端处理规则：

加载场景后保存 room.layout_version。
同一个机房的写请求串行发送。
写入成功后，用响应中的 layout_version 更新本地版本。
收到“布局版本已变化”时，重新调用场景接口获取最新数据，不覆盖服务端的新布局。

3. 接口总览

3.1 3D 核心接口

方法	路径	用途
GET	`/Assets/v1/three-d/export`	获取权限范围内全部 3D 场景
GET	`/Assets/v1/three-d/rooms/:room_id/scene`	获取单个机房场景
PUT	`/Assets/v1/three-d/rooms/:room_id/config`	保存机房尺寸及初始机柜位置
PUT	`/Assets/v1/three-d/rooms/:room_id/layout`	批量保存机柜位置
PUT	`/Assets/v1/three-d/rooms/:room_id/devices/:asset_id/placement`	保存设备的机柜或机房位置
DELETE	`/Assets/v1/three-d/rooms/:room_id/devices/:asset_id/placement`	解除设备位置
GET	`/Assets/v1/three-d/rooms/:room_id/signals`	获取机房设备状态和告警摘要
GET	`/Assets/v1/three-d/devices/:asset_id/observability`	获取设备状态、指标和告警详情

3.2 资源绑定接口

方法	路径	用途
GET	`/DC-Control/v1/resources/options`	查询可绑定监控资源选项
POST	`/Assets/v1/asset/resource/link`	绑定资产与监控资源
GET	`/Assets/v1/asset/resource/:asset_id`	查询资产资源绑定
DELETE	`/Assets/v1/asset/resource/:asset_id`	解除资产资源绑定

4. 场景数据结构

4.1 `RoomScene`

{
  "room": {
    "id": 1,
    "datacenter_id": 1,
    "floor_id": 2,
    "name": "一号机房",
    "code": "ROOM-001",
    "scene_length": 20,
    "scene_width": 12,
    "scene_height": 4,
    "layout_version": 4
  },
  "racks": [],
  "room_devices": [],
  "summary": {
    "rack_count": 0,
    "unit_count": 0,
    "rack_device_count": 0,
    "room_device_count": 0,
    "device_count": 0
  }
}

4.2 `SceneRack`

字段	类型	说明
`id`	number	机柜 ID
`name`	string	机柜名称
`code`	string	机柜编码
`row`	number	业务行号，不直接参与空间校验
`column`	number	业务列号，不直接参与空间校验
`height`	number	机柜高度，单位 U
`width_mm`	number	机柜宽度，毫米
`depth_mm`	number	机柜深度，毫米
`status`	string	机柜状态
`transform`	object	三维位置和旋转
`utilization_rate`	number	U 位使用率百分比，占用和预留 U 位均计入
`units`	array	全部 U 位，按 `unit_number` 升序
`devices`	array	机柜中已上架设备，每台设备只出现一次

机柜 transform 固定包含全部轴，当前仅 rotation_y 可写：

{
  "position_x": 2,
  "position_y": 0,
  "position_z": 3,
  "rotation_x": 0,
  "rotation_y": 90,
  "rotation_z": 0
}

U 位结构：

{
  "id": 1001,
  "unit_number": 10,
  "status": "occupied",
  "asset_id": 201
}

status 可见值包括：

available：可用。
occupied：已占用。
reserved：已预留。
disabled：已禁用。

U 位编号从 1 开始，自下向上递增。多 U 设备会在连续多个 units 项中使用相同 asset_id，但只在 rack.devices 中出现一次。

4.3 `SceneDevice`

字段	类型	说明
`asset_id`	number	资产 ID
`asset_code`	string	资产编码
`asset_name`	string	资产名称
`category_id`	number/null	资产分类 ID
`category_code`	string	资产分类编码
`category_name`	string	资产分类名称
`placement_type`	string	`rack` 或 `room`
`rack_id`	number/null	所属机柜，独立设备为 `null`
`unit_start`	number/null	起始 U 位
`unit_end`	number/null	结束 U 位
`occupied_units`	number	占用 U 位数；独立设备为 0
`power_consumption`	number	机柜设备功耗，单位 W
`transform`	object/省略	独立设备的三维位置，机柜设备不返回
`size`	object/省略	独立设备的尺寸，机柜设备不返回
`bindings`	array	绑定的监控资源

独立设备尺寸结构：

{
  "width": 1.2,
  "height": 2,
  "depth": 0.8
}

监控资源绑定结构：

{
  "resource_uid": "room_device:ac-01",
  "resource_category": "room_device",
  "service_identity": "ac-01",
  "display_name": "一号智能空调",
  "business_system_id": null
}

5. 获取单个机房场景

GET /Assets/v1/three-d/rooms/{room_id}/scene

路径参数：

参数	类型	说明
`room_id`	正整数	机房 ID

成功响应的 details：

{
  "room": {
    "id": 1,
    "datacenter_id": 1,
    "floor_id": 2,
    "name": "一号机房",
    "code": "ROOM-001",
    "scene_length": 20,
    "scene_width": 12,
    "scene_height": 4,
    "layout_version": 4
  },
  "racks": [
    {
      "id": 101,
      "name": "A01机柜",
      "code": "RACK-A01",
      "row": 1,
      "column": 1,
      "height": 42,
      "width_mm": 600,
      "depth_mm": 1000,
      "status": "in_use",
      "transform": {
        "position_x": 2,
        "position_y": 0,
        "position_z": 2,
        "rotation_x": 0,
        "rotation_y": 0,
        "rotation_z": 0
      },
      "utilization_rate": 4.761904761904762,
      "units": [
        {
          "id": 1001,
          "unit_number": 1,
          "status": "available",
          "asset_id": null
        },
        {
          "id": 1010,
          "unit_number": 10,
          "status": "occupied",
          "asset_id": 201
        }
      ],
      "devices": [
        {
          "asset_id": 201,
          "asset_code": "SRV-001",
          "asset_name": "应用服务器01",
          "category_id": 5,
          "category_code": "server",
          "category_name": "服务器",
          "placement_type": "rack",
          "rack_id": 101,
          "unit_start": 10,
          "unit_end": 11,
          "occupied_units": 2,
          "power_consumption": 850,
          "bindings": [
            {
              "resource_uid": "server:srv-001",
              "resource_category": "server",
              "service_identity": "srv-001",
              "display_name": "应用服务器01",
              "business_system_id": null
            }
          ]
        }
      ]
    }
  ],
  "room_devices": [
    {
      "asset_id": 301,
      "asset_code": "AC-001",
      "asset_name": "一号智能空调",
      "category_id": 12,
      "category_code": "air_conditioner",
      "category_name": "智能空调",
      "placement_type": "room",
      "rack_id": null,
      "unit_start": null,
      "unit_end": null,
      "occupied_units": 0,
      "power_consumption": 0,
      "transform": {
        "position_x": 8,
        "position_y": 0,
        "position_z": 2,
        "rotation_x": 0,
        "rotation_y": 90,
        "rotation_z": 0
      },
      "size": {
        "width": 1.2,
        "height": 2,
        "depth": 0.8
      },
      "bindings": [
        {
          "resource_uid": "room_device:ac-01",
          "resource_category": "room_device",
          "service_identity": "ac-01",
          "display_name": "一号智能空调",
          "business_system_id": null
        }
      ]
    }
  ],
  "summary": {
    "rack_count": 1,
    "unit_count": 42,
    "rack_device_count": 1,
    "room_device_count": 1,
    "device_count": 2
  }
}

说明：

示例为便于阅读只展示了部分 U 位，实际响应返回机柜全部 U 位。
如果机房尚未完成 3D 配置，三个场景尺寸可能为 0。前端应进入初始化配置流程。
场景接口不包含实时运行状态和告警，加载完成后再调用机房信号接口叠加状态。

6. 保存机房 3D 配置

PUT /Assets/v1/three-d/rooms/{room_id}/config

请求体：

{
  "expected_version": 1,
  "scene_length": 20,
  "scene_width": 12,
  "scene_height": 4,
  "racks": [
    {
      "rack_id": 101,
      "row": 1,
      "column": 1,
      "position_x": 2,
      "position_y": 0,
      "position_z": 2,
      "rotation_y": 0
    }
  ]
}

字段说明：

字段	必填	说明
`expected_version`	是	当前布局版本，必须大于 0
`scene_length`	是	机房长度，米，必须大于 0
`scene_width`	是	机房宽度，米，必须大于 0
`scene_height`	是	机房高度，米，必须大于 0
`racks`	条件必填	机柜位置列表

首次配置规则：

如果机房已有机柜，必须一次提交该机房全部机柜的位置。
同一个 rack_id 不能重复。
所有机柜必须属于当前机房。
保存前会统一验证全部机柜是否越界或重叠。

已配置机房再次修改尺寸时，racks 可以为空或只包含需要同步调整的机柜，但后端仍会使用新尺寸验证全部已有机柜和独立设备。

成功响应的 details：

{
  "room_id": 1,
  "layout_version": 2
}

7. 批量保存机柜布局

用于机柜拖拽结束后保存一个或多个机柜的位置。

PUT /Assets/v1/three-d/rooms/{room_id}/layout

请求体：

{
  "expected_version": 2,
  "racks": [
    {
      "rack_id": 101,
      "row": 1,
      "column": 1,
      "position_x": 3.25,
      "position_y": 0,
      "position_z": 2.5,
      "rotation_y": 90
    },
    {
      "rack_id": 102,
      "row": 1,
      "column": 2,
      "position_x": 5,
      "position_y": 0,
      "position_z": 2.5,
      "rotation_y": 90
    }
  ]
}

规则：

racks 不能为空，可以只提交本次变化的机柜。
position_x/y/z 不能小于 0。
rotation_y 范围为 [0, 360)。
后端将未提交机柜的原位置和本次候选位置一起进行全场景校验。
任一机柜失败时整批请求回滚，不会保存部分结果。

成功响应的 details：

{
  "room_id": 1,
  "layout_version": 3
}

8. 保存设备位置

PUT /Assets/v1/three-d/rooms/{room_id}/devices/{asset_id}/placement

同一接口通过 placement_type 区分机柜设备和机房内独立设备。

8.1 放入机柜或调整上架位置

请求体：

{
  "expected_version": 3,
  "placement_type": "rack",
  "rack_id": 101,
  "start_unit": 10,
  "occupied_units": 2,
  "power_consumption": 850
}

字段	必填	说明
`expected_version`	是	当前布局版本
`placement_type`	是	固定为 `rack`
`rack_id`	是	目标机柜 ID
`start_unit`	是	起始 U 位，从 1 开始
`occupied_units`	是	连续占用 U 位数，必须大于 0
`power_consumption`	是	设备功耗，单位 W，可为 0，不能为负数

校验规则：

目标机柜必须属于路径中的机房。
U 位范围必须完整、连续且可用。
调整同一设备的位置时，设备当前占用的 U 位可以作为本次目标位置的一部分。
机柜配置了 power_capacity 时，会校验调整后的剩余电力容量。机柜容量及已用电力单位为 kW，请求功耗单位为 W。
从一个机柜移动到另一个机柜时，原 U 位和原机柜功耗会在同一事务中释放。

8.2 放置在机房内

智能空调、摄像头、智能插座等不在机柜中的设备使用 room：

{
  "expected_version": 3,
  "placement_type": "room",
  "position_x": 8,
  "position_y": 0,
  "position_z": 2,
  "rotation_x": 0,
  "rotation_y": 90,
  "rotation_z": 0,
  "scene_width": 1.2,
  "scene_height": 2,
  "scene_depth": 0.8
}

字段	必填	说明
`expected_version`	是	当前布局版本
`placement_type`	是	固定为 `room`
`position_x/y/z`	是	设备底面中心坐标，米，不能为负数
`rotation_x/y/z`	是	三轴旋转角度，范围 `[0, 360)`
`scene_width`	是	设备本地 X 轴尺寸，米，必须大于 0
`scene_height`	是	设备本地 Y 轴尺寸，米，必须大于 0
`scene_depth`	是	设备本地 Z 轴尺寸，米，必须大于 0

保存时会校验设备是否越界，以及是否与机柜或其他独立设备重叠。从机柜移到机房内时，原 U 位和功耗会在同一事务中释放。

8.3 跨机房限制

已经放置在其他机房的设备不能直接移动到当前机房。必须先调用原机房的解除位置接口，再使用当前机房的 layout_version 放置。

8.4 成功响应

两种放置方式的成功响应结构相同：

{
  "room_id": 1,
  "asset_id": 201,
  "placement_type": "rack",
  "layout_version": 4
}

9. 解除设备位置

DELETE /Assets/v1/three-d/rooms/{room_id}/devices/{asset_id}/placement

请求体：

{
  "expected_version": 4
}

规则：

设备必须已放置在路径指定的机房。
机柜设备会释放原 U 位和机柜功耗。
解除后资产的机房、机柜、U 位、三维坐标、旋转和尺寸均清空。
解除后的 placement_type 为 unplaced。

成功响应的 details：

{
  "room_id": 1,
  "asset_id": 201,
  "placement_type": "unplaced",
  "layout_version": 5
}

10. 获取机房设备信号

该接口用于给整个 3D 场景批量叠加设备颜色、状态标识和告警角标。

GET /Assets/v1/three-d/rooms/{room_id}/signals

成功响应的 details：

{
  "room_id": 1,
  "signals": [
    {
      "asset_id": 201,
      "status": "warning",
      "active_alert_count": 2,
      "highest_alert_severity": {
        "name": "严重",
        "code": "critical",
        "color": "#F5222D",
        "priority": 1
      },
      "resources": [
        {
          "resource_uid": "server:srv-001",
          "resource_category": "server",
          "service_identity": "srv-001",
          "display_name": "应用服务器01",
          "status": "warning",
          "metrics": []
        }
      ],
      "alerts": [
        {
          "resource_uid": "server:srv-001",
          "active_count": 2,
          "highest_severity": {
            "name": "严重",
            "code": "critical",
            "color": "#F5222D",
            "priority": 1
          },
          "alerts": [
            {
              "id": 9001,
              "alert_name": "CPU使用率过高",
              "summary": "CPU使用率持续超过阈值",
              "severity": {
                "name": "严重",
                "code": "critical",
                "color": "#F5222D",
                "priority": 1
              },
              "status": "firing",
              "starts_at": "2026-07-31T09:00:00+08:00",
              "last_seen_at": "2026-07-31T09:05:00+08:00",
              "updated_at": "2026-07-31T09:05:00+08:00"
            }
          ]
        }
      ]
    }
  ]
}

信号状态取值：

状态	含义
`unbound`	资产没有绑定任何监控资源
`unknown`	已绑定资源，但没有可用运行数据，或出现未识别状态
`healthy`	所有可用资源状态正常
`warning`	至少一个资源为警告或降级，且没有异常资源
`abnormal`	至少一个资源为离线、错误或严重异常

后端状态映射：

异常：offline、down、error、critical、unhealthy、failed。
警告：warning、degraded。
健康：online、up、healthy、normal、running、success。

告警规则：

active_alert_count 是该资产全部绑定资源的活动告警数量之和。
highest_alert_severity 取 priority 数字最小的最高级别。
机房信号接口每个资源最多返回最近 3 条活动告警。
活动告警包括 pending、firing、acked、silenced、suppressed，已恢复告警不返回。
该接口不查询指标，因此资源的 metrics 为 []。

当前 3D 接口没有 WebSocket 推送。前端需要刷新状态时，应轮询机房信号接口，不要为场景内每台设备并发调用设备详情接口。

11. 获取设备可观测详情

用户在 3D 场景选中设备后调用：

GET /Assets/v1/three-d/devices/{asset_id}/observability

成功响应的 details：

{
  "device": {
    "asset_id": 201,
    "asset_code": "SRV-001",
    "asset_name": "应用服务器01",
    "category_id": 5,
    "category_code": "server",
    "category_name": "服务器",
    "placement_type": "rack",
    "rack_id": 101,
    "unit_start": 10,
    "unit_end": 11,
    "occupied_units": 2,
    "power_consumption": 850,
    "bindings": [
      {
        "resource_uid": "server:srv-001",
        "resource_category": "server",
        "service_identity": "srv-001",
        "display_name": "应用服务器01",
        "business_system_id": null
      }
    ]
  },
  "resources": [
    {
      "resource_uid": "server:srv-001",
      "resource_category": "server",
      "service_identity": "srv-001",
      "display_name": "应用服务器01",
      "status": "online",
      "metrics_at": "2026-07-31T09:05:00+08:00",
      "metrics": [
        {
          "name": "cpu_usage",
          "value": 63.5,
          "unit": "%",
          "type": "gauge",
          "timestamp": "2026-07-31T09:05:00+08:00"
        }
      ]
    }
  ],
  "alerts": [
    {
      "resource_uid": "server:srv-001",
      "active_count": 1,
      "highest_severity": {
        "name": "警告",
        "code": "warning",
        "color": "#FAAD14",
        "priority": 2
      },
      "alerts": []
    }
  ]
}

说明：

device 使用与场景接口相同的 SceneDevice 结构。
resources 返回每个绑定资源的当前状态和最近一批指标。
没有指标的资源返回 metrics: []，并省略 metrics_at。
每个资源最多返回最近 20 条活动告警。
资产未绑定监控资源时，resources 和 alerts 均为 []。

12. 导出全部 3D 场景

GET /Assets/v1/three-d/export

用于一次获取当前 JWT 数据范围内已启用的数据中心和机房场景。它不包含实时状态、指标和告警。

成功响应的 details：

{
  "datacenters": [
    {
      "id": 1,
      "name": "北京数据中心",
      "code": "DC-BJ-01",
      "status": "running",
      "latitude": "39.9042",
      "longitude": "116.4074",
      "rooms": []
    }
  ],
  "summary": {
    "datacenter_count": 1,
    "room_count": 2,
    "rack_count": 30,
    "unit_count": 1260,
    "device_count": 150
  }
}

rooms 中每一项都是完整的 RoomScene。

13. 资产与监控资源绑定

设备只有绑定 dc-control 统一监控资源后，3D 页面才能展示该设备的实时状态、指标和活动告警。一个资产可以绑定多个资源，一个 resource_uid 在全局只能绑定一个资产。

13.1 查询可绑定资源

GET /DC-Control/v1/resources/options?resource_category=room_device

查询参数：

参数	必填	说明
`resource_category`	否	按资源分类过滤；不传时返回全部分类，最多 500 条

成功响应的 details：

{
  "list": [
    {
      "id": 501,
      "label": "一号智能空调",
      "value": "room_device:ac-01"
    }
  ],
  "count": 1
}

其中 value 就是绑定接口需要的 resource_uid。

当前可查询运行状态的资源分类包括：

host
server
pc
database
middleware
url
network
security
storage
room_device

智能空调、监控摄像头、智能插座等机房设备统一使用 room_device 资源分类，具体设备类型由 dc-control 中的机房设备分类区分。

13.2 绑定资源

POST /Assets/v1/asset/resource/link

请求体：

{
  "asset_id": 301,
  "resource_uid": "room_device:ac-01",
  "display_name": "一号智能空调",
  "business_system_id": null
}

字段	必填	说明
`asset_id`	是	资产 ID
`resource_uid`	是	格式为 `category:identity`
`display_name`	否	为空时使用 `dc-control` 中的资源名称
`business_system_id`	否	关联业务系统 ID

后端会实时调用 dc-control 验证资源存在。重复提交同一资产和资源会更新绑定；资源已绑定其他资产时返回错误。

成功响应的 details 包含绑定记录，例如：

{
  "id": 100,
  "created_at": "2026-07-31T09:00:00+08:00",
  "updated_at": "2026-07-31T09:00:00+08:00",
  "asset_id": 301,
  "resource_uid": "room_device:ac-01",
  "resource_category": "room_device",
  "service_identity": "ac-01",
  "display_name": "一号智能空调",
  "business_system_id": null,
  "health_status": "online",
  "alert_status": "none",
  "created_by": "admin",
  "updated_by": "admin"
}

实时页面不要使用绑定记录中的 health_status 或 alert_status 作为实时值，应使用机房信号或设备可观测接口。

13.3 查询绑定

GET /Assets/v1/asset/resource/{asset_id}

成功响应的 details 是绑定记录数组：

[
  {
    "id": 100,
    "asset_id": 301,
    "resource_uid": "room_device:ac-01",
    "resource_category": "room_device",
    "service_identity": "ac-01",
    "display_name": "一号智能空调",
    "business_system_id": null,
    "health_status": "online",
    "alert_status": "none",
    "created_by": "admin",
    "updated_by": "admin",
    "created_at": "2026-07-31T09:00:00+08:00",
    "updated_at": "2026-07-31T09:00:00+08:00"
  }
]

13.4 解除绑定

DELETE /Assets/v1/asset/resource/{asset_id}?resource_uid=room_device%3Aac-01

resource_uid 必须放在查询参数中，并进行 URL 编码。

成功响应的 details：

"解除绑定成功"

14. 待放置资产

当前没有单独的 3D 待放置资产接口。可使用现有资产下拉接口：

GET /Assets/v1/asset/all?keyword=空调

响应 details 是资产数组，前端可按以下条件筛选：

placement_type === "unplaced"

placement_type 取值：

unplaced：未放置。
rack：已放入机柜。
room：已放置在机房内。

前端筛选只用于交互，最终能否放置仍由设备位置接口的数据权限、版本、机房归属、U 位、边界和碰撞校验决定。

15. 前端推荐调用流程

15.1 打开机房

调用 GET /three-d/rooms/{room_id}/scene 加载几何场景。
保存 room.layout_version。
如果机房尺寸为 0，进入初始化配置；否则渲染机房、机柜、机柜设备和独立设备。
调用 GET /three-d/rooms/{room_id}/signals 叠加状态颜色和告警角标。

15.2 拖拽机柜

前端本地计算候选坐标并更新预览。
拖拽结束后调用机柜布局接口，可批量提交本次变更。
成功后更新本地 layout_version；失败则恢复或重新加载场景。

15.3 设备上架或移动

从待放置资产中选择设备，或选择场景内已有设备。
放入机柜时提交 rack 请求和连续 U 位区间。
放在机房内时提交 room 请求、完整坐标、旋转角度和物体尺寸。
成功后更新 layout_version，再按需刷新场景和信号。

15.4 查看设备状态

场景批量状态使用机房信号接口。
用户点击设备时调用设备可观测接口。
设备没有绑定资源时显示“未绑定监控资源”，不要显示为离线。

15.5 版本冲突

遇到以下任一消息时重新加载场景：

布局版本已变化，当前版本为 N
布局版本已变化，请重新加载

不要用旧坐标自动覆盖新场景。需要保留用户拖拽意图时，应先获取新场景，再由用户确认重新应用。

16. 常见失败场景

`message` 特征	前端处理建议
`登录凭证缺少机房数据权限`	提示权限配置问题，不重试写请求
`无权访问该机房`、`无权移动该资产`	提示无权限并退出编辑状态
`布局版本已变化`	重新加载场景和版本
`机房三维长度、宽度和高度必须大于0`	校验尺寸输入
`首次配置...必须同时提交...全部机柜的位置`	补齐当前机房全部机柜
`超出机房三维边界`	恢复物体到合法位置
`发生空间重叠`	调整位置后重试
`目标U位...不可用`	刷新场景或重新选择连续 U 位
`目标机柜剩余电力容量不足`	调整机柜或功耗值
`资产属于其他机房`	先在原机房解除位置
`环境变量 DC_CONTROL_BASE_URL 未配置`	后端部署配置问题
`环境变量 ALERT_BASE_URL 未配置`	后端部署配置问题
`查询 dc-control 设备状态失败`	状态聚合依赖异常，保留场景并提示状态暂不可用
`查询 alert 活动告警失败`	告警聚合依赖异常，保留场景并提示告警暂不可用

写请求是事务性的。任一校验或数据库操作失败时，不会只保存部分机柜、U 位或设备位置。

17. 后端聚合依赖

以下接口由 Assets 后台调用，前端不直接调用：

服务	内部接口	用途
`dc-control`	`POST /DC-Control/v1/resources/runtime`	按资源 UID 批量读取状态和最新指标
`alert`	`POST /Alert/v1/record/active/by-resources`	按资源 UID 批量读取活动告警

Assets 会转发前端请求中的 Authorization。聚合请求按每批 500 个资源处理，单个下游请求超时为 8 秒。

部署 Assets 时需要配置：

DC_CONTROL_BASE_URL=<dc-control服务根地址>
ALERT_BASE_URL=<alert服务根地址>

18. 代码依据

本文档未读取项目既有文档，接口事实来自以下实际代码：

assets/internal/routers/register.go
assets/internal/logic/three_d/types.go
assets/internal/logic/three_d/scene.go
assets/internal/logic/three_d/layout.go
assets/internal/logic/three_d/placement.go
assets/internal/logic/three_d/geometry.go
assets/internal/logic/three_d/integration.go
assets/internal/logic/three_d/scope.go
assets/internal/logic/asset/resource_binding.go
assets/internal/models/assets_asset.go
assets/internal/models/assets_asset_resource_binding.go
assets/internal/models/assets_rack.go
assets/internal/models/assets_room.go
dc-control/internal/routers/register.go
dc-control/internal/logic/controllers/resource_controller.go
dc-control/internal/logic/controllers/resource_runtime_controller.go
dc-control/internal/logic/resource_runtime/runtime.go
alert/internal/routers/register.go
alert/internal/logic/record/resource.go
bsm-sdk/core@v0.1.7/infra/response.go

30 KiB Raw Blame History Unescape Escape

3D 机房前后端接口对接文档

1. 对接范围

2. 通用约定

2.1 基础地址和请求头

2.2 统一响应结构

2.3 数据权限

2.4 坐标和尺寸

2.5 布局版本和并发控制

3. 接口总览

3.1 3D 核心接口

3.2 资源绑定接口

4. 场景数据结构

4.1 RoomScene

4.2 SceneRack

4.3 SceneDevice

5. 获取单个机房场景

6. 保存机房 3D 配置

7. 批量保存机柜布局

8. 保存设备位置

8.1 放入机柜或调整上架位置

8.2 放置在机房内

8.3 跨机房限制

8.4 成功响应

9. 解除设备位置

10. 获取机房设备信号

11. 获取设备可观测详情

12. 导出全部 3D 场景

13. 资产与监控资源绑定

13.1 查询可绑定资源

13.2 绑定资源

13.3 查询绑定

13.4 解除绑定

14. 待放置资产

15. 前端推荐调用流程

15.1 打开机房

15.2 拖拽机柜

15.3 设备上架或移动

15.4 查看设备状态

15.5 版本冲突

16. 常见失败场景

17. 后端聚合依赖

18. 代码依据

30 KiB

Raw Blame History

4.1 `RoomScene`

4.2 `SceneRack`

4.3 `SceneDevice`