first

docs/企业卡授权列表和设备授权列表.md

@@ -0,0 +1,130 @@
+# 授权卡列表
+
+## 接口说明
+获取**某个企业下的卡列表**，支持分页和简单筛选。
+
+- 请求方式：GET  
+- 接口地址：`/api/admin/enterprises/{id}/cards`  
+- 认证方式：Bearer Token  
+
+---
+
+## 请求参数
+
+### Path 参数
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| id | integer | 是 | 企业ID |
+
+---
+
+### Query 参数
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| page | integer | 否 | 页码（默认1） |
+| page_size | integer | 否 | 每页数量（最大100） |
+| status | integer | 否 | 卡状态 |
+| carrier_id | integer | 否 | 运营商ID |
+| iccid | string | 否 | ICCID（模糊查询） |
+| virtual_no | string | 否 | 虚拟号（模糊查询） |
+
+---
+
+## 返回结构
+
+```json
+{
+  "code": 0,
+  "msg": "success",
+  "data": {
+    "items": [],
+    "page": 1,
+    "size": 10,
+    "total": 100
+  },
+  "timestamp": "2026-03-31T12:00:00Z"
+}
+
+```
+
+items 字段说明（企业卡信息）
+字段	类型	说明
+id	integer	卡ID
+iccid	string	卡号
+msisdn	string	手机号
+virtual_no	string	虚拟号
+carrier_id	integer	运营商ID
+carrier_name	string	运营商名称
+status	integer	卡状态
+status_name	string	状态名称
+network_status	integer	网络状态
+network_status_name	string	网络状态名称
+package_id	integer	套餐ID
+package_name	string	套餐名称
+device_id	integer	绑定设备ID（可能为空）
+常见状态说明
+卡状态 status
+1：在库
+2：已分配
+3：已激活
+4：已停用
+
+网络状态 network_status
+0：停机 / 异常
+1：正常
+
+# 授权设备列表
+
+## 接口说明
+获取**某个企业下已授权的设备列表**。
+
+- 请求方式：GET  
+- 接口地址：`/api/admin/enterprises/{id}/devices`  
+- 认证方式：Bearer Token  
+
+---
+
+## 请求参数
+
+### Path 参数
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| id | integer | 是 | 企业ID |
+
+---
+
+### Query 参数
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| page | integer | 否 | 页码 |
+| page_size | integer | 否 | 每页数量 |
+| virtual_no | string | 否 | 设备虚拟号（模糊查询） |
+
+---
+
+## 返回结构
+
+```json
+{
+  "code": 0,
+  "msg": "success",
+  "data": {
+    "items": [],
+    "total": 100
+  },
+  "timestamp": "2026-03-31T12:00:00Z"
+}
+```
+
+items 字段说明（企业设备）
+字段	类型	说明
+device_id	integer	设备ID
+device_name	string	设备名称
+device_model	string	设备型号
+virtual_no	string	设备虚拟号
+card_count	integer	已绑定卡数量
+authorized_at	string	授权时间