feat: 将页面添加分页

2026-03-21 17:37:06 +08:00
parent 9edb59d16e
commit 25d782b050
18 changed files with 2220 additions and 154 deletions
@@ -0,0 +1,348 @@
+# 新增接口对接文档
+
+> 来源：`默认模块.openapi.json` 与 `src/api/admin/kvmService.js` 对比
+> 生成时间：2026-03-21
+
+---
+
+## 一、新增接口总览
+
+| # | 模块 | 接口路径 | 方法 | 说明 | 前端状态 |
+|---|------|---------|------|------|---------|
+| 1 | 快照管理 | `/api/v1/admin/server/host_service/point/snapshot/count` | GET | 获取快照数量与上限 | **新增** |
+| 2 | 快照管理 | `/api/v1/admin/server/host_service/point/snapshot/set_limit` | POST | 设置快照数量上限 | **新增** |
+| 3 | 备份管理 | `/api/v1/admin/server/host_service/point/backup/count` | GET | 获取备份数量与上限 | **新增** |
+| 4 | 备份管理 | `/api/v1/admin/server/host_service/point/backup/set_limit` | POST | 设置备份数量上限 | **新增** |
+| 5 | 用户组网 | `/api/v1/admins/service/host_service/point/networking/create` | POST | 创建用户组网 | **新增（全新模块）** |
+| 6 | 用户组网 | `/api/v1/admins/service/host_service/point/networking/assign` | POST | 为虚拟机分配组网IP | **新增（全新模块）** |
+| 7 | 用户组网 | `/api/v1/admins/service/host_service/point/networking/list` | GET | 获取组网列表 | **新增（全新模块）** |
+| 8 | 用户组网 | `/api/v1/admins/service/host_service/point/networking/detail` | GET | 获取组网详情 | **新增（全新模块）** |
+| 9 | 用户组网 | `/api/v1/admins/service/host_service/point/networking/delete` | DELETE | 删除组网 | **新增（全新模块）** |
+| 10 | 用户组网 | `/api/v1/admins/service/host_service/point/networking/remove_network` | POST | 删除组网下指定网络 | **新增（全新模块）** |
+
+> **注意**：用户组网(Networking)接口的URL前缀为 `/api/v1/admins/service/`（admins复数、service单数），与其他接口 `/api/v1/admin/server/` 不同。
+
+---
+
+## 二、接口详细说明
+
+### 2.1 快照管理 - 新增接口
+
+#### 2.1.1 获取快照数量与上限
+
+- **路径**：`GET /api/v1/admin/server/host_service/point/snapshot/count`
+- **标签**：管理员-快照
+- **请求参数**（Query）：
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| service_id | integer | 是 | KVM服务ID |
+| vm_id | integer | 是 | 虚拟机ID |
+
+- **响应**：
+
+```json
+{
+  "code": 200,
+  "data": {
+    "vm_id": 1,
+    "count": 3,
+    "limit": 10
+  }
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| vm_id | int64 | 虚拟机ID |
+| count | uint32 | 当前快照数量 |
+| limit | uint32 | 快照上限 |
+
+- **前端函数名**：`getSnapshotCount`
+
+---
+
+#### 2.1.2 设置快照数量上限
+
+- **路径**：`POST /api/v1/admin/server/host_service/point/snapshot/set_limit`
+- **标签**：管理员-快照
+- **Content-Type**：`multipart/form-data`
+- **请求参数**（FormData）：
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| service_id | integer | 是 | KVM服务ID |
+| vm_id | integer | 是 | 虚拟机ID |
+| limit | integer | 是 | 快照数量上限 |
+
+- **响应**：
+
+```json
+{
+  "code": 200,
+  "data": {
+    "vm_id": 1,
+    "count": 3,
+    "limit": 20
+  }
+}
+```
+
+- **前端函数名**：`setSnapshotLimit`
+
+---
+
+### 2.2 备份管理 - 新增接口
+
+#### 2.2.1 获取备份数量与上限
+
+- **路径**：`GET /api/v1/admin/server/host_service/point/backup/count`
+- **标签**：管理员-备份
+- **请求参数**（Query）：
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| service_id | integer | 是 | KVM服务ID |
+| vm_id | integer | 是 | 虚拟机ID |
+
+- **响应**：
+
+```json
+{
+  "code": 200,
+  "data": {
+    "vm_id": 1,
+    "count": 2,
+    "limit": 5
+  }
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| vm_id | int64 | 虚拟机ID |
+| count | uint32 | 当前备份数量 |
+| limit | uint32 | 备份上限 |
+
+- **前端函数名**：`getBackupCount`
+
+---
+
+#### 2.2.2 设置备份数量上限
+
+- **路径**：`POST /api/v1/admin/server/host_service/point/backup/set_limit`
+- **标签**：管理员-备份
+- **Content-Type**：`multipart/form-data`
+- **请求参数**（FormData）：
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| service_id | integer | 是 | KVM服务ID |
+| vm_id | integer | 是 | 虚拟机ID |
+| limit | integer | 是 | 备份数量上限 |
+
+- **响应**：
+
+```json
+{
+  "code": 200,
+  "data": {
+    "vm_id": 1,
+    "count": 2,
+    "limit": 10
+  }
+}
+```
+
+- **前端函数名**：`setBackupLimit`
+
+---
+
+### 2.3 用户组网管理（全新模块 KVM-UserNetworking）
+
+> **URL 前缀注意**：此模块所有接口使用 `/api/v1/admins/service/` 前缀
+
+#### 2.3.1 获取组网列表
+
+- **路径**：`GET /api/v1/admins/service/host_service/point/networking/list`
+- **请求参数**（Query）：
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| service_id | integer | 是 | KVM 服务 ID |
+| page | integer | 否 | 页码 |
+| count | integer | 否 | 每页数量 |
+| host_id | integer | 否 | 按宿主机 ID 筛选 |
+| user_id | integer | 否 | 按用户 ID 筛选 |
+| keyword | string | 否 | 关键词搜索 |
+
+- **响应**：
+
+```json
+{
+  "meta": { "count": 10 },
+  "data": [
+    {
+      "id": 1,
+      "name": "组网名称",
+      "description": "描述",
+      "user_id": 1,
+      "host_id": 1,
+      "bridge_name": "br0",
+      "gateway": "192.168.1.1",
+      "created_at": "2026-03-21T00:00:00Z",
+      "updated_at": "2026-03-21T00:00:00Z"
+    }
+  ]
+}
+```
+
+- **前端函数名**：`getUserNetworkingList`
+
+---
+
+#### 2.3.2 获取组网详情
+
+- **路径**：`GET /api/v1/admins/service/host_service/point/networking/detail`
+- **请求参数**（Query）：
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| service_id | integer | 是 | KVM 服务 ID |
+| networking_id | integer | 是 | 组网 ID |
+
+- **响应**：
+
+```json
+{
+  "data": { "id": 1, "name": "...", "..." },
+  "networks": [
+    {
+      "network": {},
+      "vm_id": 1,
+      "vm_name": "vm-1",
+      "vm_status": "running"
+    }
+  ]
+}
+```
+
+- **前端函数名**：`getUserNetworkingDetail`
+
+---
+
+#### 2.3.3 创建用户组网
+
+- **路径**：`POST /api/v1/admins/service/host_service/point/networking/create`
+- **Content-Type**：`multipart/form-data`
+- **请求参数**（FormData）：
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| service_id | integer | 是 | KVM 服务 ID |
+| name | string | 是 | 组网名称 |
+| description | string | 否 | 组网描述 |
+| user_id | integer | 是 | 用户 ID |
+| host_id | integer | 是 | 宿主机 ID |
+| bridge_name | string | 是 | 网桥名称 |
+| gateway | string | 是 | 网关地址 |
+
+- **响应**：返回 `UserNetworkingData` 对象
+- **前端函数名**：`createUserNetworking`
+
+---
+
+#### 2.3.4 为虚拟机分配组网 IP
+
+- **路径**：`POST /api/v1/admins/service/host_service/point/networking/assign`
+- **Content-Type**：`multipart/form-data`
+- **请求参数**（FormData）：
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| service_id | integer | 是 | KVM 服务 ID |
+| networking_id | integer | 是 | 组网 ID |
+| vm_id | integer | 是 | 虚拟机 ID |
+| ip | string | 否 | 指定 IP，不传则自动分配 |
+
+- **响应**：返回 `networking`、`network`、`task` 三个对象
+- **前端函数名**：`assignUserNetworking`
+
+---
+
+#### 2.3.5 删除组网
+
+- **路径**：`DELETE /api/v1/admins/service/host_service/point/networking/delete`
+- **请求参数**（Query）：
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| service_id | integer | 是 | KVM 服务 ID |
+| networking_id | integer | 是 | 组网 ID |
+
+- **前端函数名**：`deleteUserNetworking`
+
+---
+
+#### 2.3.6 删除组网下的指定网络
+
+- **路径**：`POST /api/v1/admins/service/host_service/point/networking/remove_network`
+- **Content-Type**：`multipart/form-data`
+- **请求参数**（FormData）：
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| service_id | integer | 是 | KVM 服务 ID |
+| networking_id | integer | 是 | 组网 ID |
+| network_id | integer | 是 | 网络 ID |
+| vm_id | integer | 是 | 虚拟机 ID（用于从 VM 中移除网络） |
+
+- **前端函数名**：`removeUserNetworkingNetwork`
+
+---
+
+## 三、数据模型
+
+### UserNetworkingData
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | int64 | 组网ID |
+| name | string | 组网名称 |
+| description | string | 描述 |
+| user_id | int64 | 用户ID |
+| host_id | int64 | 宿主机ID |
+| bridge_name | string | 网桥名称 |
+| gateway | string | 网关地址 |
+| created_at | datetime | 创建时间 |
+| updated_at | datetime | 更新时间 |
+
+### NetworkingNetworkItem
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| network | Network | 网络对象 |
+| vm_id | int64 | 虚拟机ID |
+| vm_name | string | 虚拟机名称 |
+| vm_status | string | 虚拟机状态 |
+
+---
+
+## 四、已有接口（已对接，无需修改）
+
+以下接口在 `kvmService.js` 中已存在，无需新增：
+
+- 主控服务管理：list / detail / create / update / delete（5个）
+- 宿主机组映射管理：list / sync / bind / update / generate_goods / delete（6个）
+- 远程宿主机组管理：list / detail / tree / optimal_host / create / update / delete（7个）
+- 宿主机管理：list / detail / metrics / add / update / delete（6个）
+- 镜像管理：list / detail / host_status / create / update / delete / reload / sync / reload_host / compare_host（10个）
+- 网络管理：list / detail / create / update / delete（5个）
+- 数据卷管理：list / detail / create / resize / mount / unmount / transfer / delete（8个）
+- 虚拟机管理：list / detail / status / metrics / create / update / rebuild / refactor / update_traffic / start / stop / reboot / suspend / resume / rescue / exit_rescue / delete（17个）
+- 安全组管理：list / detail / create / update / sync / bind / unbind / delete / enable_whitelist / disable_whitelist / create_rule / update_rule / delete_rule / apply / set_shared（15个）
+- VNC节点管理：list / vm_vnc / add / test / update / delete（6个）
+- 快照管理：list / progress / create / restore / delete（5个）
+- 备份管理：list / progress / create / restore / delete（5个）
+
+**共计已对接 95 个接口，新增 10 个接口待对接。**