# 资产套餐列表

## 接口信息

- **页面**：/asset-management/packages
- **按钮名称**：套餐列表
- **权限编码**：asset_packages_list

---

## URL

`GET /api/admin/assets/{asset_type}/{id}/packages`

---

## 请求参数

### Path 参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| asset_type | string | 是 | 资产类型：card 或 device |
| id | integer | 是 | 资产ID |

### Query 参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | integer | 否 | 页码（默认1） |
| page_size | integer | 否 | 每页条数（默认50，最大100） |

---

## 响应说明

### Response 字段

| 字段 | 类型 | 说明 |
|------|------|------|
| code | integer | 响应码 |
| msg | string | 响应消息 |
| timestamp | string | 时间戳 |
| data | object | 返回数据 |

---

## data 字段（资产套餐结果对象）

| 字段 | 类型 | 说明 |
|------|------|------|
| items | array | 套餐列表 |
| page | integer | 当前页码 |
| page_size | integer | 每页条数 |
| total | integer | 总条数 |

---

## items 字段（资产套餐响应对象）

| 字段 | 类型 | 说明 |
|------|------|------|
| package_id | integer | 套餐ID |
| package_name | string | 套餐名称 |
| package_type | string | 套餐类型：formal/addon |
| status | integer | 状态：0待生效 1生效中 2已用完 3已过期 4已失效 |
| status_name | string | 状态名称 |
| usage_type | string | 使用类型：single_card/device |
| priority | integer | 优先级 |
| package_usage_id | integer | 套餐使用记录ID |
| master_usage_id | integer | 主套餐ID（加油包时有值） |
| data_limit_mb | integer | 套餐真流量总量(MB) |
| data_usage_mb | integer | 已用真流量(MB) |
| virtual_limit_mb | integer | 套餐虚流量总量(MB)，按virtual_ratio换算 |
| virtual_used_mb | number | 已用虚流量(MB)，按virtual_ratio换算 |
| virtual_remain_mb | number | 剩余虚流量(MB)，按virtual_ratio换算 |
| virtual_ratio | number | 虚流量比例(real/virtual) |
| created_at | string | 创建时间 |
| activated_at | string | 激活时间（待生效套餐为空） |
| expires_at | string | 到期时间（待生效套餐为空） |

---

## 错误响应

| HTTP 状态码 | 说明 |
|------------|------|
| 400 | 请求参数错误 |
| 401 | 未认证或认证已过期 |
| 403 | 无权访问 |
| 500 | 服务器内部错误 |

---

## 请求示例

```
GET /api/admin/assets/card/12345/packages?page=1&page_size=50
```

---

## 响应示例

```json
{
  "code": 0,
  "msg": "success",
  "timestamp": "2024-03-30T10:30:00Z",
  "data": {
    "page": 1,
    "page_size": 50,
    "total": 5,
    "items": [
      {
        "package_id": 101,
        "package_name": "套餐A-10GB",
        "package_type": "formal",
        "status": 1,
        "status_name": "生效中",
        "usage_type": "single_card",
        "priority": 1,
        "package_usage_id": 1001,
        "master_usage_id": null,
        "data_limit_mb": 10240,
        "data_usage_mb": 2560,
        "virtual_limit_mb": 15360,
        "virtual_used_mb": 3840,
        "virtual_remain_mb": 11520,
        "virtual_ratio": 1.5,
        "created_at": "2024-01-15T08:00:00Z",
        "activated_at": "2024-01-15T08:00:00Z",
        "expires_at": "2024-04-15T08:00:00Z"
      },
      {
        "package_id": 102,
        "package_name": "加油包-2GB",
        "package_type": "addon",
        "status": 1,
        "status_name": "生效中",
        "usage_type": "single_card",
        "priority": 2,
        "package_usage_id": 1002,
        "master_usage_id": 1001,
        "data_limit_mb": 2048,
        "data_usage_mb": 512,
        "virtual_limit_mb": 3072,
        "virtual_used_mb": 768,
        "virtual_remain_mb": 2304,
        "virtual_ratio": 1.5,
        "created_at": "2024-03-01T10:00:00Z",
        "activated_at": "2024-03-01T10:00:00Z",
        "expires_at": "2024-03-31T23:59:59Z"
      },
      {
        "package_id": 103,
        "package_name": "套餐B-20GB",
        "package_type": "formal",
        "status": 0,
        "status_name": "待生效",
        "usage_type": "single_card",
        "priority": 3,
        "package_usage_id": 1003,
        "master_usage_id": null,
        "data_limit_mb": 20480,
        "data_usage_mb": 0,
        "virtual_limit_mb": 30720,
        "virtual_used_mb": 0,
        "virtual_remain_mb": 30720,
        "virtual_ratio": 1.5,
        "created_at": "2024-03-25T14:00:00Z",
        "activated_at": null,
        "expires_at": null
      }
    ]
  }
}
```

---

## 认证

- **认证方式**：Bearer Token (JWT)
- **Header**：`Authorization: Bearer <token>`

---

## API 分类

- **模块**：资产管理
- **状态**：已发布

---

## 服务器地址

- **测试环境**：https://cmp-api.xm-iot.cn


# 当前生效套餐

## 接口信息

- **页面**：/asset-management/current-package
- **按钮名称**：当前套餐
- **权限编码**：asset_current_package

---

## URL

`GET /api/admin/assets/{asset_type}/{id}/current-package`

---

## 请求参数

### Path 参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| asset_type | string | 是 | 资产类型：card 或 device |
| id | integer | 是 | 资产ID |

---

## 响应说明

### Response 字段

| 字段 | 类型 | 说明 |
|------|------|------|
| code | integer | 响应码 |
| msg | string | 响应消息 |
| timestamp | string | 时间戳 |
| data | object | 返回数据 |

---

## data 字段（资产套餐响应对象）

| 字段 | 类型 | 说明 |
|------|------|------|
| package_id | integer | 套餐ID |
| package_name | string | 套餐名称 |
| package_type | string | 套餐类型：formal/addon |
| status | integer | 状态：0待生效 1生效中 2已用完 3已过期 4已失效 |
| status_name | string | 状态名称 |
| usage_type | string | 使用类型：single_card/device |
| priority | integer | 优先级 |
| package_usage_id | integer | 套餐使用记录ID |
| master_usage_id | integer | 主套餐ID（加油包时有值） |
| data_limit_mb | integer | 套餐真流量总量(MB) |
| data_usage_mb | integer | 已用真流量(MB) |
| virtual_limit_mb | integer | 套餐虚流量总量(MB)，按virtual_ratio换算 |
| virtual_used_mb | number | 已用虚流量(MB)，按virtual_ratio换算 |
| virtual_remain_mb | number | 剩余虚流量(MB)，按virtual_ratio换算 |
| virtual_ratio | number | 虚流量比例(real/virtual) |
| created_at | string | 创建时间 |
| activated_at | string | 激活时间（待生效套餐为空） |
| expires_at | string | 到期时间（待生效套餐为空） |

---

## 错误响应

| HTTP 状态码 | 说明 |
|------------|------|
| 400 | 请求参数错误 |
| 401 | 未认证或认证已过期 |
| 403 | 无权访问 |
| 500 | 服务器内部错误 |

---

## 请求示例

```
GET /api/admin/assets/card/12345/current-package
```

---

## 响应示例

```json
{
  "code": 0,
  "msg": "success",
  "timestamp": "2024-03-30T10:30:00Z",
  "data": {
    "package_id": 101,
    "package_name": "套餐A-10GB",
    "package_type": "formal",
    "status": 1,
    "status_name": "生效中",
    "usage_type": "single_card",
    "priority": 1,
    "package_usage_id": 1001,
    "master_usage_id": null,
    "data_limit_mb": 10240,
    "data_usage_mb": 2560,
    "virtual_limit_mb": 15360,
    "virtual_used_mb": 3840,
    "virtual_remain_mb": 11520,
    "virtual_ratio": 1.5,
    "created_at": "2024-01-15T08:00:00Z",
    "activated_at": "2024-01-15T08:00:00Z",
    "expires_at": "2024-04-15T08:00:00Z"
  }
}
```

---

## 认证

- **认证方式**：Bearer Token (JWT)
- **Header**：`Authorization: Bearer <token>`

---

## API 分类

- **模块**：资产管理
- **状态**：已发布

---

## 服务器地址

- **测试环境**：https://cmp-api.xm-iot.cn