# 企业端 / 代理端接口清单 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 ` 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` 自动区分 - 数据隔离后端自动处理（无需前端关心） - 前端只需控制： - 是否展示功能 - 是否调用接口