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