ops/front

Fork 0

Files

zxr 43ce3433ce fix: 机柜使用率浮点精度

2026-08-19 19:27:12 +08:00

7.3 KiB

Raw Blame History

资产设备源地址前端对接文档

1. 变更说明

设备资产新增可选字段 source_address，界面名称为“源地址”。该字段适用于所有设备分类，可用于保存 RTSP、HTTP、HTTPS、HLS 等形式的播放源地址。

属性	内容
JSON 字段	`source_address`
TypeScript 类型	`string`
是否必填	否
最大长度	1000 个字符
协议限制	无
数据库字段	`assets_assets.source_address`
数据库类型	`varchar(1000)`

前端不需要根据设备分类判断是否展示该字段。

2. 接口公共约定

资产接口基础路径：

/Assets/v1/asset

请求头：

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

统一响应结构：

interface ApiResponse<T> {
  code: number
  message: string
  details: T
  timeseq: number
}

code === 0 表示请求成功，业务数据位于 details。

3. 前端类型

在资产表单类型中增加 source_address：

export interface AssetForm {
  id?: number
  asset_name: string
  asset_code: string
  source_address?: string
}

当前项目已经在 src/api/ops/asset.ts 的 AssetForm 中加入该字段。其他以资产对象为基础的详情、列表和批量导入数据可以直接复用该字段。

4. 创建设备资产

4.1 接口

POST /Assets/v1/asset/create

4.2 请求示例

{
  "asset_name": "东门监控摄像头",
  "asset_code": "CAMERA-001",
  "category_id": 12,
  "model": "DS-2CD3T",
  "manufacturer": "海康威视",
  "serial_number": "SN20260817001",
  "source_address": "rtsp://192.168.1.100:554/Streaming/Channels/101",
  "status": "in_use"
}

未填写源地址时可以省略 source_address，也可以传空字符串：

{
  "asset_name": "普通设备",
  "asset_code": "DEVICE-001",
  "source_address": ""
}

4.3 成功响应

{
  "code": 0,
  "message": "",
  "details": {
    "id": 101,
    "asset_name": "东门监控摄像头",
    "asset_code": "CAMERA-001",
    "source_address": "rtsp://192.168.1.100:554/Streaming/Channels/101",
    "status": "in_use"
  },
  "timeseq": 1786932000000
}

4.4 调用方式

import { createAsset, type AssetForm } from '@/api/ops/asset'

const data: AssetForm = {
  asset_name: '东门监控摄像头',
  asset_code: 'CAMERA-001',
  source_address: 'rtsp://192.168.1.100:554/Streaming/Channels/101',
  status: 'in_use',
}

const response = await createAsset(data)
if (response.code !== 0) {
  throw new Error(response.message || '创建设备失败')
}

5. 更新设备资产

5.1 接口

PUT /Assets/v1/asset/update

5.2 请求示例

{
  "id": 101,
  "asset_name": "东门监控摄像头",
  "asset_code": "CAMERA-001",
  "source_address": "https://video.example.com/live/camera-001.m3u8",
  "status": "in_use"
}

更新接口需要同时传入：

id
asset_name
asset_code

source_address 仍为选填字段。传入非空值时更新源地址；不传时保留原值。

当前后端使用 GORM 结构体更新，空字符串属于零值，因此传入 source_address: "" 不会清空已有源地址。前端暂时不要把“传空字符串”作为清空操作。

5.3 调用方式

import { updateAsset, type AssetForm } from '@/api/ops/asset'

const data: AssetForm = {
  id: 101,
  asset_name: '东门监控摄像头',
  asset_code: 'CAMERA-001',
  source_address: 'https://video.example.com/live/camera-001.m3u8',
  status: 'in_use',
}

const response = await updateAsset(data)
if (response.code !== 0) {
  throw new Error(response.message || '更新设备失败')
}

6. 查询设备详情

6.1 接口

GET /Assets/v1/asset/detail/{id}

6.2 成功响应

{
  "code": 0,
  "message": "",
  "details": {
    "id": 101,
    "asset_name": "东门监控摄像头",
    "asset_code": "CAMERA-001",
    "source_address": "rtsp://192.168.1.100:554/Streaming/Channels/101",
    "status": "in_use"
  },
  "timeseq": 1786932000000
}

未填写源地址时，source_address 返回空字符串。

6.3 表单回填

当前编辑页面使用详情对象整体回填：

const response = await fetchAssetDetail(deviceId)
if (response.code === 0) {
  form.value = { ...response.details } as AssetForm
}

source_address 会随其他资产字段自动回填，不需要单独请求。

7. 分页查询设备资产

7.1 接口

POST /Assets/v1/asset/list

7.2 请求示例

{
  "page": 1,
  "page_size": 20,
  "keyword": "",
  "status": "in_use"
}

7.3 响应示例

{
  "code": 0,
  "message": "",
  "details": {
    "total": 1,
    "page": 1,
    "page_size": 20,
    "data": [
      {
        "id": 101,
        "asset_name": "东门监控摄像头",
        "asset_code": "CAMERA-001",
        "source_address": "rtsp://192.168.1.100:554/Streaming/Channels/101"
      }
    ]
  },
  "timeseq": 1786932000000
}

以下接口返回的资产对象同样包含 source_address：

GET /Assets/v1/asset/page
GET /Assets/v1/asset/all
GET /Assets/v1/asset/export

8. 批量导入

8.1 接口

POST /Assets/v1/asset/bulk_import

8.2 请求示例

{
  "dry_run": false,
  "items": [
    {
      "asset_name": "西门监控摄像头",
      "asset_code": "CAMERA-002",
      "source_address": "rtsp://192.168.1.101:554/live",
      "status": "in_use"
    }
  ]
}

每个 items 元素都可以单独填写或省略 source_address。

9. 表单接入

9.1 默认值

const form = ref<AssetForm>({
  asset_name: '',
  asset_code: '',
  source_address: '',
})

9.2 表单组件

<a-form-item label="源地址" field="source_address">
  <a-input
    v-model="form.source_address"
    placeholder="请输入源地址"
    :max-length="1000"
    allow-clear
  />
</a-form-item>

该字段不设置 required 规则，也不校验具体协议格式。

9.3 提交

新增和编辑直接复用现有资产提交逻辑：

const data = { ...form.value }

if (isEdit.value && deviceId.value) {
  await updateAsset({ ...data, id: deviceId.value })
} else {
  await createAsset(data)
}

10. 详情展示

<a-descriptions-item label="源地址" :span="2">
  <span class="source-address">{{ device?.source_address || '-' }}</span>
</a-descriptions-item>

长地址需要允许换行：

.source-address {
  word-break: break-all;
}

11. 播放功能使用建议

获取播放地址时直接读取资产对象的 source_address：

const sourceAddress = record.source_address?.trim()

if (!sourceAddress) {
  Message.warning('该设备未配置源地址')
  return
}

前端不要自动补全协议、转换大小写或修改地址内容。具体播放器需要支持对应的流媒体协议，例如浏览器不能直接原生播放 RTSP 地址。

12. 对接检查项

新增设备时可以不填写源地址。
新增设备时填写源地址后可以正常保存。
编辑设备时能够正确回填源地址。
编辑设备时修改源地址后可以正常保存。
详情接口和详情弹窗能够显示源地址。
列表接口返回的每条资产数据包含 source_address。
超长地址能够在详情区域正常换行。
接口失败时优先显示响应中的 message。

7.3 KiB Raw Blame History Unescape Escape