front/asset-source-address-frontend-integration.md

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

## 1. 变更说明

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

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

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

## 2. 接口公共约定

资产接口基础路径：

```text
/Assets/v1/asset
```

请求头：

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

统一响应结构：

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

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

## 3. 前端类型

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

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

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

## 4. 创建设备资产

### 4.1 接口

```http
POST /Assets/v1/asset/create
```

### 4.2 请求示例

```json
{
  "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`，也可以传空字符串：

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

### 4.3 成功响应

```json
{
  "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 调用方式

```ts
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 接口

```http
PUT /Assets/v1/asset/update
```

### 5.2 请求示例

```json
{
  "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 调用方式

```ts
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 接口

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

### 6.2 成功响应

```json
{
  "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 表单回填

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

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

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

## 7. 分页查询设备资产

### 7.1 接口

```http
POST /Assets/v1/asset/list
```

### 7.2 请求示例

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

### 7.3 响应示例

```json
{
  "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`：

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

## 8. 批量导入

### 8.1 接口

```http
POST /Assets/v1/asset/bulk_import
```

### 8.2 请求示例

```json
{
  "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 默认值

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

### 9.2 表单组件

```vue
<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 提交

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

```ts
const data = { ...form.value }

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

## 10. 详情展示

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

长地址需要允许换行：

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

## 11. 播放功能使用建议

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

```ts
const sourceAddress = record.source_address?.trim()

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

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

## 12. 对接检查项

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