# 企业端 / 代理端接口清单

baseUrl: https://api.example.com

> 所有接口统一走 `/api/auth` + `/api/admin/*`  
> 使用 JWT 鉴权，通过 `user_type` 自动区分身份（企业 / 代理）  
> 数据隔离由后端 GORM Callback 自动处理  

---

# 🔐 认证接口（企业 + 代理共用）

| 接口 | 方法 | 路径 | 说明 |
|------|------|------|------|
| 登录 | POST | /api/auth/login | username + password，返回 access_token / refresh_token / 权限 |
# 统一登录（后台+H5）

## 接口信息

- **页面**：/login
- **按钮名称**：登录
- **权限编码**：auth_login

---

## URL

`POST /api/auth/login`

---

## 请求参数

### Body 参数（application/json）

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| username | string | 是 | 用户名 |
| password | string | 是 | 密码 |
| device | string | 否 | 设备标识 |

---

## 响应说明

### Response 字段

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

---

## data 字段（登录响应对象）

| 字段 | 类型 | 说明 |
|------|------|------|
| access_token | string | 访问令牌 |
| refresh_token | string | 刷新令牌 |
| expires_in | integer | 过期时间（秒） |
| user | object | 用户信息 |

---

## user 字段（用户信息对象）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | integer | 用户ID |
| username | string | 用户名 |
| phone | string | 手机号 |
| user_type | integer | 用户类型（1:超级管理员, 2:平台用户, 3:代理账号, 4:企业账号） |
| user_type_name | string | 用户类型名称 |
| enterprise_id | integer | 企业ID |
| enterprise_name | string | 企业名称 |
| shop_id | integer | 店铺ID |
| shop_name | string | 店铺名称 |

---

---

## 错误响应

| HTTP 状态码 | 说明 |
|------------|------|
| 400 | 请求参数错误 |
| 500 | 服务器内部错误 |

---

## 请求示例

```json
{
  "username": "admin",
  "password": "password123",
  "device": "web"
}
```

---

## 响应示例

```json
{
  "code": 0,
  "msg": "success",
  "timestamp": "2024-03-30T10:30:00Z",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 3600,
    "user": {
      "id": 123,
      "username": "admin",
      "phone": "13800138000",
      "user_type": 1,
      "user_type_name": "超级管理员",
      "enterprise_id": 1,
      "enterprise_name": "测试企业",
      "shop_id": 10,
      "shop_name": "测试店铺"
    }
  }
}
```

---

## 认证

- **认证方式**：无需认证（开放接口）
- **响应中获取**：access_token 用于后续请求的认证

---

## 使用说明

1. **登录流程**：提交用户名和密码获取 access_token
2. **Token 使用**：在后续请求 header 中使用 `Authorization: Bearer <access_token>`
3. **Token 刷新**：使用 refresh_token 刷新过期的 access_token


| 刷新 Token | POST | /api/auth/refresh-token | 使用 refresh_token 换新 token |
# 刷新 Token

## 接口信息

- **页面**：/path/to/page
- **按钮名称**：刷新 Token
- **权限编码**：permission_code

---

## URL

`POST /api/auth/refresh-token`

---

## 请求参数

### Body 参数（application/json）

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| param_name | string | 是 | 参数说明 |

---

## 响应说明

### Response 字段

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

### data 字段

| 字段 | 类型 | 说明 |
|------|------|------|
| field_name | string | 字段说明 |

---

## 错误响应

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

---

## 请求示例

```json
{
  "param_name": "value"
}
```

---

## 响应示例

```json
{
  "code": 0,
  "msg": "success",
  "timestamp": "2024-03-30T10:30:00Z",
  "data": {
    "field_name": "value"
  }
}
```



| 登出 | POST | /api/auth/logout | 🔒 |
# 统一登出

## 接口信息

- **页面**：/path/to/page
- **按钮名称**：统一登出
- **权限编码**：permission_code

---

## URL

`POST /api/auth/logout`

---

## 请求参数

### Body 参数（application/json）

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| param_name | string | 是 | 参数说明 |

---

## 响应说明

### Response 字段

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

### data 字段

| 字段 | 类型 | 说明 |
|------|------|------|
| field_name | string | 字段说明 |

---

## 错误响应

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

---

## 请求示例

```json
{
  "param_name": "value"
}
```

---

## 响应示例

```json
{
  "code": 0,
  "msg": "success",
  "timestamp": "2024-03-30T10:30:00Z",
  "data": {
    "field_name": "value"
  }
}
```


| 获取用户信息 | GET | /api/auth/me | 🔒 返回 user_type / shop_id / enterprise_id |
# 获取用户信息

## 接口信息

- **页面**：/path/to/page
- **按钮名称**：获取用户信息
- **权限编码**：permission_code

---

## URL

`GET /api/auth/me`

---

## 请求参数

无请求参数

---

## 响应说明

### Response 字段

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

### data 字段

| 字段 | 类型 | 说明 |
|------|------|------|
| field_name | string | 字段说明 |

---

## 错误响应

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

---

## 请求示例

```
GET /api/auth/me
```

---

## 响应示例

```json
{
  "code": 0,
  "msg": "success",
  "timestamp": "2024-03-30T10:30:00Z",
  "data": {
    "field_name": "value"
  }
}
```


| 修改密码 | PUT | /api/auth/password | 🔒 |
# 修改密码

## 接口信息

- **页面**：/path/to/page
- **按钮名称**：修改密码
- **权限编码**：permission_code

---

## URL

`PUT /api/auth/password`

---

## 请求参数

### Body 参数（application/json）

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| param_name | string | 是 | 参数说明 |

---

## 响应说明

### Response 字段

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

### data 字段

| 字段 | 类型 | 说明 |
|------|------|------|
| field_name | string | 字段说明 |

---

## 错误响应

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

---

## 请求示例

```json
{
  "param_name": "value"
}
```

---

## 响应示例

```json
{
  "code": 0,
  "msg": "success",
  "timestamp": "2024-03-30T10:30:00Z",
  "data": {
    "field_name": "value"
  }
}
```


---

# 🏢 企业端可用接口

| 模块 | 方法 | 路径 | 说明 |
|------|------|------|------|
| 资产查询 | GET | /api/admin/assets/resolve/:identifier | 通过 ICCID / 虚拟号 / IMEI 查询 |
# 解析资产

## 接口信息

- **页面**：/path/to/page
- **按钮名称**：解析资产
- **权限编码**：permission_code

---

## URL

`GET /api/admin/assets/resolve/{identifier}`

---

## 请求参数

无请求参数

---

## 响应说明

### Response 字段

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

### data 字段

| 字段 | 类型 | 说明 |
|------|------|------|
| field_name | string | 字段说明 |

---

## 错误响应

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

---

## 请求示例

```
GET /api/admin/assets/resolve/{identifier}
```

---

## 响应示例

```json
{
  "code": 0,
  "msg": "success",
  "timestamp": "2024-03-30T10:30:00Z",
  "data": {
    "field_name": "value"
  }
}
```


| 实时状态 | GET | /api/admin/assets/:asset_type/:id/realtime-status | 查询持久化状态 |
# 资产实时状态

## 接口信息

- **页面**：/path/to/page
- **按钮名称**：资产实时状态
- **权限编码**：permission_code

---

## URL

`GET /api/admin/assets/{asset_type}/{id}/realtime-status`

---

## 请求参数

无请求参数

---

## 响应说明

### Response 字段

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

### data 字段

| 字段 | 类型 | 说明 |
|------|------|------|
| field_name | string | 字段说明 |

---

## 错误响应

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

---

## 请求示例

```
GET /api/admin/assets/{asset_type}/{id}/realtime-status
```

---

## 响应示例

```json
{
  "code": 0,
  "msg": "success",
  "timestamp": "2024-03-30T10:30:00Z",
  "data": {
    "field_name": "value"
  }
}
```


| 刷新状态 | POST | /api/admin/assets/:asset_type/:id/refresh | 主动同步网关 |
# 刷新资产状态

## 接口信息

- **页面**：/path/to/page
- **按钮名称**：刷新资产状态
- **权限编码**：permission_code

---

## URL

`POST /api/admin/assets/{asset_type}/{id}/refresh`

---

## 请求参数

### Body 参数（application/json）

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| param_name | string | 是 | 参数说明 |

---

## 响应说明

### Response 字段

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

### data 字段

| 字段 | 类型 | 说明 |
|------|------|------|
| field_name | string | 字段说明 |

---

## 错误响应

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

---

## 请求示例

```json
{
  "param_name": "value"
}
```

---

## 响应示例

```json
{
  "code": 0,
  "msg": "success",
  "timestamp": "2024-03-30T10:30:00Z",
  "data": {
    "field_name": "value"
  }
}
```


| 套餐列表 | GET | /api/admin/assets/:asset_type/:id/packages | 查询套餐记录 |
# 资产套餐列表

## 接口信息

- **页面**：/path/to/page
- **按钮名称**：资产套餐列表
- **权限编码**：permission_code

---

## URL

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

---

## 请求参数

### Query 参数

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

---

## 响应说明

### Response 字段

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

### data 字段

| 字段 | 类型 | 说明 |
|------|------|------|
| field_name | string | 字段说明 |

---

## 错误响应

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

---

## 请求示例

```
GET /api/admin/assets/{asset_type}/{id}/packages?page=value&page_size=value
```

---

## 响应示例

```json
{
  "code": 0,
  "msg": "success",
  "timestamp": "2024-03-30T10:30:00Z",
  "data": {
    "field_name": "value"
  }
}
```


| 当前套餐 | GET | /api/admin/assets/:asset_type/:id/current-package | 当前生效套餐 |
# 当前生效套餐

## 接口信息

- **页面**：/path/to/page
- **按钮名称**：当前生效套餐
- **权限编码**：permission_code

---

## URL

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

---

## 请求参数

无请求参数

---

## 响应说明

### Response 字段

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

### data 字段

| 字段 | 类型 | 说明 |
|------|------|------|
| field_name | string | 字段说明 |

---

## 错误响应

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

---

## 请求示例

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

---

## 响应示例

```json
{
  "code": 0,
  "msg": "success",
  "timestamp": "2024-03-30T10:30:00Z",
  "data": {
    "field_name": "value"
  }
}
```



| 设备停机 | POST | /api/admin/assets/device/:device_id/stop | 批量停机 |
# 设备停机

## 接口信息

- **页面**：/path/to/page
- **按钮名称**：设备停机
- **权限编码**：permission_code

---

## URL

`POST /api/admin/assets/device/{device_id}/stop`

---

## 请求参数

### Body 参数（application/json）

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| param_name | string | 是 | 参数说明 |

---

## 响应说明

### Response 字段

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

### data 字段

| 字段 | 类型 | 说明 |
|------|------|------|
| field_name | string | 字段说明 |

---

## 错误响应

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

---

## 请求示例

```json
{
  "param_name": "value"
}
```

---

## 响应示例

```json
{
  "code": 0,
  "msg": "success",
  "timestamp": "2024-03-30T10:30:00Z",
  "data": {
    "field_name": "value"
  }
}
```


| 设备复机 | POST | /api/admin/assets/device/:device_id/start | 批量复机 |
# 设备复机

## 接口信息

- **页面**：/path/to/page
- **按钮名称**：设备复机
- **权限编码**：permission_code

---

## URL

`POST /api/admin/assets/device/{device_id}/start`

---

## 请求参数

### Body 参数（application/json）

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| param_name | string | 是 | 参数说明 |

---

## 响应说明

### Response 字段

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

### data 字段

| 字段 | 类型 | 说明 |
|------|------|------|
| field_name | string | 字段说明 |

---

## 错误响应

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

---

## 请求示例

```json
{
  "param_name": "value"
}
```

---

## 响应示例

```json
{
  "code": 0,
  "msg": "success",
  "timestamp": "2024-03-30T10:30:00Z",
  "data": {
    "field_name": "value"
  }
}
```


| 单卡停机 | POST | /api/admin/assets/card/:iccid/stop | 单卡停机 |
# 单卡停机

## 接口信息

- **页面**：/path/to/page
- **按钮名称**：单卡停机
- **权限编码**：permission_code

---

## URL

`POST /api/admin/assets/card/{iccid}/stop`

---

## 请求参数

### Body 参数（application/json）

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| param_name | string | 是 | 参数说明 |

---

## 响应说明

### Response 字段

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

### data 字段

| 字段 | 类型 | 说明 |
|------|------|------|
| field_name | string | 字段说明 |

---

## 错误响应

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

---

## 请求示例

```json
{
  "param_name": "value"
}
```

---

## 响应示例

```json
{
  "code": 0,
  "msg": "success",
  "timestamp": "2024-03-30T10:30:00Z",
  "data": {
    "field_name": "value"
  }
}
```


| 单卡复机 | POST | /api/admin/assets/card/:iccid/start | 单卡复机 |
# 单卡复机

## 接口信息

- **页面**：/path/to/page
- **按钮名称**：单卡复机
- **权限编码**：permission_code

---

## URL

`POST /api/admin/assets/card/{iccid}/start`

---

## 请求参数

### Body 参数（application/json）

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| param_name | string | 是 | 参数说明 |

---

## 响应说明

### Response 字段

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

### data 字段

| 字段 | 类型 | 说明 |
|------|------|------|
| field_name | string | 字段说明 |

---

## 错误响应

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

---

## 请求示例

```json
{
  "param_name": "value"
}
```

---

## 响应示例

```json
{
  "code": 0,
  "msg": "success",
  "timestamp": "2024-03-30T10:30:00Z",
  "data": {
    "field_name": "value"
  }
}
```


| 企业卡列表 | GET | /api/admin/enterprises/:id/cards | 企业授权卡 |
# 企业卡列表

## 接口信息

- **页面**：/path/to/page
- **按钮名称**：企业卡列表
- **权限编码**：permission_code

---

## URL

`GET /api/admin/enterprises/{id}/cards`

---

## 请求参数

### Query 参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | integer | 否 | 页码 |
| page_size | integer | 否 | 每页数量 |
| status | integer | 否 | 卡状态 |
| carrier_id | integer | 否 | 运营商ID |
| iccid | string | 否 | ICCID（模糊查询） |
| virtual_no | string | 否 | 虚拟号（模糊查询） |

---

## 响应说明

### Response 字段

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

### data 字段

| 字段 | 类型 | 说明 |
|------|------|------|
| field_name | string | 字段说明 |

---

## 错误响应

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

---

## 请求示例

```
GET /api/admin/enterprises/{id}/cards?page=value&page_size=value&status=value&carrier_id=value&iccid=value&virtual_no=value
```

---

## 响应示例

```json
{
  "code": 0,
  "msg": "success",
  "timestamp": "2024-03-30T10:30:00Z",
  "data": {
    "field_name": "value"
  }
}
```


| 企业设备列表 | GET | /api/admin/enterprises/:id/devices | 企业授权设备 |
# 企业设备列表

## 接口信息

- **页面**：/path/to/page
- **按钮名称**：企业设备列表
- **权限编码**：permission_code

---

## URL

`GET /api/admin/enterprises/{id}/devices`

---

## 请求参数

### Query 参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | integer | 否 | 页码 |
| page_size | integer | 否 | 每页数量 |
| virtual_no | string | 否 | 虚拟号（模糊搜索） |

---

## 响应说明

### Response 字段

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

### data 字段

| 字段 | 类型 | 说明 |
|------|------|------|
| field_name | string | 字段说明 |

---

## 错误响应

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

---

## 请求示例

```
GET /api/admin/enterprises/{id}/devices?page=value&page_size=value&virtual_no=value
```

---

## 响应示例

```json
{
  "code": 0,
  "msg": "success",
  "timestamp": "2024-03-30T10:30:00Z",
  "data": {
    "field_name": "value"
  }
}
```



---

## ❌ 企业端不可用接口

- 钱包相关（/assets/:type/:id/wallet）
- 刷新资产（部分写操作）
- 订单创建 / 套餐购买
- 所有管理类接口（账号 / 角色 / 运营商等）

---

# 🏪 代理端可用接口

| 模块 | 方法 | 路径 |
|------|------|------|
| 资产查询 | GET | /api/admin/assets/resolve/:identifier |
| 实时状态 | GET | /api/admin/assets/:asset_type/:id/realtime-status |
| 刷新状态 | POST | /api/admin/assets/:asset_type/:id/refresh |
| 套餐列表 | GET | /api/admin/assets/:asset_type/:id/packages |
| 当前套餐 | GET | /api/admin/assets/:asset_type/:id/current-package |
| 设备停/复机 | POST | /api/admin/assets/device/:device_id/stop / start |
| 单卡停/复机 | POST | /api/admin/assets/card/:iccid/stop / start |
| 资产钱包 | GET | /api/admin/assets/:type/:id/wallet |
# 资产钱包概况

## 接口信息

- **页面**：/path/to/page
- **按钮名称**：资产钱包概况
- **权限编码**：permission_code

---

## URL

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

---

## 请求参数

无请求参数

---

## 响应说明

### Response 字段

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

### data 字段

| 字段 | 类型 | 说明 |
|------|------|------|
| field_name | string | 字段说明 |

---

## 错误响应

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

---

## 请求示例

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

---

## 响应示例

```json
{
  "code": 0,
  "msg": "success",
  "timestamp": "2024-03-30T10:30:00Z",
  "data": {
    "field_name": "value"
  }
}
```



| 钱包流水 | GET | /api/admin/assets/:type/:id/wallet/transactions |
# 资产钱包流水列表

## 接口信息

- **页面**：/path/to/page
- **按钮名称**：资产钱包流水列表
- **权限编码**：permission_code

---

## URL

`GET /api/admin/assets/{asset_type}/{id}/wallet/transactions`

---

## 请求参数

### Query 参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | integer | 否 | 页码，默认1 |
| page_size | integer | 否 | 每页数量，默认20，最大100 |
| transaction_type | string | 否 | 交易类型过滤：recharge/deduct/refund |
| start_time | string | 否 | 开始时间（RFC3339） |
| end_time | string | 否 | 结束时间（RFC3339） |

---

## 响应说明

### Response 字段

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

### data 字段

| 字段 | 类型 | 说明 |
|------|------|------|
| field_name | string | 字段说明 |

---

## 错误响应

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

---

## 请求示例

```
GET /api/admin/assets/{asset_type}/{id}/wallet/transactions?page=value&page_size=value&transaction_type=value&start_time=value&end_time=value
```

---

## 响应示例

```json
{
  "code": 0,
  "msg": "success",
  "timestamp": "2024-03-30T10:30:00Z",
  "data": {
    "field_name": "value"
  }
}
```


| 佣金概览 | GET | /api/admin/my/commission-summary |
# 我的佣金概览

## 接口信息

- **页面**：/path/to/page
- **按钮名称**：我的佣金概览
- **权限编码**：permission_code

---

## URL

`GET /api/admin/my/commission-summary`

---

## 请求参数

无请求参数

---

## 响应说明

### Response 字段

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

### data 字段

| 字段 | 类型 | 说明 |
|------|------|------|
| field_name | string | 字段说明 |

---

## 错误响应

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

---

## 请求示例

```
GET /api/admin/my/commission-summary
```

---

## 响应示例

```json
{
  "code": 0,
  "msg": "success",
  "timestamp": "2024-03-30T10:30:00Z",
  "data": {
    "field_name": "value"
  }
}
```


| 佣金明细 | GET | /api/admin/my/commission-records |
# 我的佣金明细

## 接口信息

- **页面**：/path/to/page
- **按钮名称**：我的佣金明细
- **权限编码**：permission_code

---

## URL

`GET /api/admin/my/commission-records`

---

## 请求参数

### Query 参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | integer | 否 | 页码 |
| page_size | integer | 否 | 每页数量 |
| commission_source | string | 否 | 佣金来源 (cost_diff:成本价差, one_time:一次性佣金, tier_bonus(已废弃):梯度奖励) |
| iccid | string | 否 | ICCID（模糊查询） |
| virtual_no | string | 否 | 设备虚拟号（模糊查询） |
| order_no | string | 否 | 订单号（模糊查询） |

---

## 响应说明

### Response 字段

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

### data 字段

| 字段 | 类型 | 说明 |
|------|------|------|
| field_name | string | 字段说明 |

---

## 错误响应

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

---

## 请求示例

```
GET /api/admin/my/commission-records?page=value&page_size=value&commission_source=value&iccid=value&virtual_no=value&order_no=value
```

---

## 响应示例

```json
{
  "code": 0,
  "msg": "success",
  "timestamp": "2024-03-30T10:30:00Z",
  "data": {
    "field_name": "value"
  }
}
```


| 佣金统计 | GET | /api/admin/my/commission-stats |
# 我的佣金统计

## 接口信息

- **页面**：/path/to/page
- **按钮名称**：我的佣金统计
- **权限编码**：permission_code

---

## URL

`GET /api/admin/my/commission-stats`

---

## 请求参数

### Query 参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| shop_id | integer | 否 | 店铺ID |
| start_time | string | 否 | 开始时间 |
| end_time | string | 否 | 结束时间 |

---

## 响应说明

### Response 字段

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

### data 字段

| 字段 | 类型 | 说明 |
|------|------|------|
| field_name | string | 字段说明 |

---

## 错误响应

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

---

## 请求示例

```
GET /api/admin/my/commission-stats?shop_id=value&start_time=value&end_time=value
```

---

## 响应示例

```json
{
  "code": 0,
  "msg": "success",
  "timestamp": "2024-03-30T10:30:00Z",
  "data": {
    "field_name": "value"
  }
}
```


| 每日佣金 | GET | /api/admin/my/commission-daily-stats |
# 我的每日佣金统计

## 接口信息

- **页面**：/path/to/page
- **按钮名称**：我的每日佣金统计
- **权限编码**：permission_code

---

## URL

`GET /api/admin/my/commission-daily-stats`

---

## 请求参数

### Query 参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| shop_id | integer | 否 | 店铺ID |
| start_date | string | 否 | 开始日期（YYYY-MM-DD） |
| end_date | string | 否 | 结束日期（YYYY-MM-DD） |
| days | integer | 否 | 查询天数（默认30天） |

---

## 响应说明

### Response 字段

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

### data 字段

| 字段 | 类型 | 说明 |
|------|------|------|
| field_name | string | 字段说明 |

---

## 错误响应

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

---

## 请求示例

```
GET /api/admin/my/commission-daily-stats?shop_id=value&start_date=value&end_date=value&days=value
```

---

## 响应示例

```json
{
  "code": 0,
  "msg": "success",
  "timestamp": "2024-03-30T10:30:00Z",
  "data": {
    "field_name": "value"
  }
}
```


| 发起提现 | POST | /api/admin/my/withdrawal-requests |
# 发起提现申请

## 接口信息

- **页面**：/path/to/page
- **按钮名称**：发起提现申请
- **权限编码**：permission_code

---

## URL

`POST /api/admin/my/withdrawal-requests`

---

## 请求参数

### Body 参数（application/json）

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| param_name | string | 是 | 参数说明 |

---

## 响应说明

### Response 字段

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

### data 字段

| 字段 | 类型 | 说明 |
|------|------|------|
| field_name | string | 字段说明 |

---

## 错误响应

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

---

## 请求示例

```json
{
  "param_name": "value"
}
```

---

## 响应示例

```json
{
  "code": 0,
  "msg": "success",
  "timestamp": "2024-03-30T10:30:00Z",
  "data": {
    "field_name": "value"
  }
}
```


| 提现记录 | GET | /api/admin/my/withdrawal-requests |
# 我的提现记录

## 接口信息

- **页面**：/path/to/page
- **按钮名称**：我的提现记录
- **权限编码**：permission_code

---

## URL

`GET /api/admin/my/withdrawal-requests`

---

## 请求参数

### Query 参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | integer | 否 | 页码 |
| page_size | integer | 否 | 每页数量 |
| status | integer | 否 | 状态（1=待审批, 2=已通过, 3=已拒绝） |
| start_time | string | 否 | 申请开始时间 |
| end_time | string | 否 | 申请结束时间 |

---

## 响应说明

### Response 字段

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

### data 字段

| 字段 | 类型 | 说明 |
|------|------|------|
| field_name | string | 字段说明 |

---

## 错误响应

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

---

## 请求示例

```
GET /api/admin/my/withdrawal-requests?page=value&page_size=value&status=value&start_time=value&end_time=value
```

---

## 响应示例

```json
{
  "code": 0,
  "msg": "success",
  "timestamp": "2024-03-30T10:30:00Z",
  "data": {
    "field_name": "value"
  }
}
```


---

# 📊 接口可用性矩阵

```
┌────────────────────────┬──────────┬──────────┬───────────────┐
│ 接口模块               │ 企业端   │ 代理端   │ 备注          │
├────────────────────────┼──────────┼──────────┼───────────────┤
│ 认证（登录/登出/me）    │ ✅       │ ✅       │ 共用          │
│ 资产解析               │ ✅       │ ✅       │               │
│ 实时状态               │ ✅       │ ✅       │               │
│ 刷新资产               │ ❌       │ ✅       │ 企业只读      │
│ 套餐列表/当前套餐      │ ✅       │ ✅       │               │
│ 停复机（设备+单卡）    │ ✅       │ ✅       │               │
│ 资产钱包/流水          │ ❌       │ ✅       │ 企业无钱包    │
│ 佣金/提现              │ ❌       │ ✅       │ 企业无佣金    │
│ 企业卡列表             │ ✅       │ ✅       │               │
│ 企业设备列表           │ ✅       │ ✅       │               │
│ 订单/购买/充值         │ ❌       │ ❌(*)    │ *代理走后台   │
│ 管理类（账号/角色等）  │ ❌       │ ❌(*)    │ *后台管理     │
└────────────────────────┴──────────┴──────────┴───────────────┘
```

---

# ⚠️ 前端注意事项

企业端查询接口：

- `/api/admin/enterprises/:id/cards`
- `/api/admin/enterprises/:id/devices`

👉 `:id` 获取方式：

```js
const { enterprise_id } = await getUserInfo() // /api/auth/me
```

然后拼接：

```js
const url = `/api/admin/enterprises/${enterprise_id}/cards`
```

---

# ✅ 总结

- 所有接口统一鉴权（JWT）
- 企业 / 代理权限通过 `user_type` 自动区分
- 数据隔离后端自动处理（无需前端关心）
- 前端只需控制：
  - 是否展示功能
  - 是否调用接口