first

2026-03-31 18:41:52 +08:00
commit 3c62cc1cd1
527 changed files with 96725 additions and 0 deletions
--- a/docs/资产详情.md
+++ b/docs/资产详情.md
@@ -0,0 +1,333 @@
+# 资产套餐列表
+
+## 接口信息
+
+- **页面**：/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.boss160.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.boss160.cn