297 lines
7.0 KiB
Markdown
297 lines
7.0 KiB
Markdown
# 前端对接文档（管理后台 + 客户端）
|
||
|
||
本文档基于已实现的后端接口，提供给前端开发使用。
|
||
|
||
## 统一响应格式
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {},
|
||
"timestamp": 1735000000
|
||
}
|
||
```
|
||
|
||
## 统一错误码
|
||
|
||
- 200 success
|
||
- 400 bad_request
|
||
- 401 unauthorized
|
||
- 403 forbidden
|
||
- 404 not_found
|
||
- 1001 card_invalid
|
||
- 1002 card_expired
|
||
- 1003 card_banned
|
||
- 1005 device_limit_exceeded
|
||
- 1006 device_not_found
|
||
- 1007 signature_invalid
|
||
- 1008 timestamp_expired
|
||
- 1009 rate_limit_exceeded
|
||
- 1010 invalid_version
|
||
- 1011 project_disabled
|
||
- 1012 force_update_required
|
||
- 500 internal_error
|
||
|
||
## 分页参数
|
||
|
||
- page: 页码，默认 1
|
||
- pageSize: 每页数量，默认 20，最大 100
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"items": [],
|
||
"pagination": {
|
||
"page": 1,
|
||
"pageSize": 20,
|
||
"total": 100,
|
||
"totalPages": 5
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 鉴权方式
|
||
|
||
### 管理员后台
|
||
|
||
登录后获得 JWT，前端需在请求头加入：
|
||
|
||
```
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
### 代理商
|
||
|
||
代理商登录后也使用 JWT，同上。
|
||
|
||
### 客户端授权
|
||
|
||
`/api/auth/verify` 成功后返回 `accessToken`，后续心跳/下载使用。
|
||
|
||
## 角色与权限
|
||
|
||
- role:
|
||
- `super_admin`：全部权限（含代理商管理、系统设置、管理员管理）
|
||
- `admin`：仅可访问所属项目
|
||
- permissions:
|
||
- JSON 数组，内容为允许的 `projectId`，示例：`["PROJ_001","PROJ_002"]`
|
||
- 若为 `["*"]` 表示可访问全部项目
|
||
- 非超管且权限为空时，默认无项目访问权限
|
||
- 权限生效范围：
|
||
- 非超管只能查看/操作允许项目的项目、卡密、设备、日志、统计
|
||
- 代理商管理与系统设置仅超管可访问
|
||
|
||
## 管理后台接口
|
||
|
||
### 1) 管理员认证
|
||
|
||
- POST `/api/admin/login`
|
||
- POST `/api/admin/logout`
|
||
- GET `/api/admin/profile`
|
||
- PUT `/api/admin/profile`
|
||
- POST `/api/admin/change-password`
|
||
|
||
### 2) 项目管理
|
||
|
||
- POST `/api/admin/projects`
|
||
- GET `/api/admin/projects`
|
||
- GET `/api/admin/projects/{id}`
|
||
- PUT `/api/admin/projects/{id}`
|
||
- DELETE `/api/admin/projects/{id}`
|
||
- GET `/api/admin/projects/{id}/stats`
|
||
- GET `/api/admin/projects/{id}/docs`
|
||
- PUT `/api/admin/projects/{id}/docs`
|
||
|
||
#### 价格管理
|
||
|
||
- GET `/api/admin/projects/{id}/pricing`
|
||
- POST `/api/admin/projects/{id}/pricing`
|
||
- PUT `/api/admin/projects/{id}/pricing/{priceId}`
|
||
- DELETE `/api/admin/projects/{id}/pricing/{priceId}`
|
||
|
||
#### 版本管理
|
||
|
||
- GET `/api/admin/projects/{id}/versions`
|
||
- POST `/api/admin/projects/{id}/versions` (multipart/form-data)
|
||
- version (string)
|
||
- file (file)
|
||
- changelog (string)
|
||
- isForceUpdate (bool)
|
||
- isStable (bool)
|
||
- PUT `/api/admin/projects/{id}/versions/{versionId}`
|
||
- DELETE `/api/admin/projects/{id}/versions/{versionId}`
|
||
|
||
说明：项目创建时返回 `projectSecret`，后续查询不再返回该字段（仅保留 `projectKey`）。请前端在创建时提示管理员保存。
|
||
|
||
### 3) 卡密管理
|
||
|
||
- POST `/api/admin/cards/generate`
|
||
- GET `/api/admin/cards`
|
||
- GET `/api/admin/cards/{id}`
|
||
- GET `/api/admin/cards/{id}/logs`
|
||
- PUT `/api/admin/cards/{id}` (更新备注)
|
||
- POST `/api/admin/cards/{id}/ban`
|
||
- POST `/api/admin/cards/{id}/unban`
|
||
- POST `/api/admin/cards/{id}/extend`
|
||
- POST `/api/admin/cards/{id}/reset-device`
|
||
- DELETE `/api/admin/cards/{id}`
|
||
|
||
#### 批量操作
|
||
|
||
- POST `/api/admin/cards/ban-batch`
|
||
- POST `/api/admin/cards/unban-batch`
|
||
- DELETE `/api/admin/cards/batch`
|
||
|
||
#### 导入/导出
|
||
|
||
- GET `/api/admin/cards/export`
|
||
- POST `/api/admin/cards/import` (CSV)
|
||
|
||
说明：导出支持 `format=excel` 生成 `xlsx`，导入支持 CSV 或 Excel（首行可带表头）。卡密生成支持请求头 `X-Idempotency-Key` 防止重复提交。
|
||
|
||
### 4) 代理商管理
|
||
|
||
- 仅超管可访问
|
||
- POST `/api/admin/agents`
|
||
- GET `/api/admin/agents`
|
||
- GET `/api/admin/agents/{id}`
|
||
- PUT `/api/admin/agents/{id}`
|
||
- POST `/api/admin/agents/{id}/disable`
|
||
- POST `/api/admin/agents/{id}/enable`
|
||
- DELETE `/api/admin/agents/{id}`
|
||
- POST `/api/admin/agents/{id}/recharge`
|
||
- POST `/api/admin/agents/{id}/deduct`
|
||
- GET `/api/admin/agents/{id}/transactions`
|
||
|
||
### 5) 设备管理
|
||
|
||
- GET `/api/admin/devices`
|
||
- DELETE `/api/admin/devices/{id}`
|
||
- POST `/api/admin/devices/{id}/kick`
|
||
|
||
### 6) 统计报表
|
||
|
||
- GET `/api/admin/stats/dashboard`
|
||
- GET `/api/admin/stats/projects` (项目维度统计)
|
||
- GET `/api/admin/stats/agents` (代理商销售统计，仅超管)
|
||
- GET `/api/admin/stats/logs?days=7` (按 action 聚合统计)
|
||
- GET `/api/admin/stats/export?days=30` (CSV 导出)
|
||
|
||
### 7) 日志审计
|
||
|
||
- GET `/api/admin/logs`
|
||
- GET `/api/admin/logs/{id}`
|
||
|
||
### 8) 系统设置 & 管理员
|
||
|
||
- 仅超管可访问
|
||
- GET `/api/admin/settings`
|
||
- PUT `/api/admin/settings`
|
||
- GET `/api/admin/admins`
|
||
- POST `/api/admin/admins`
|
||
- PUT `/api/admin/admins/{id}`
|
||
- DELETE `/api/admin/admins/{id}`
|
||
|
||
## 代理商接口
|
||
|
||
- POST `/api/agent/login`
|
||
- POST `/api/agent/logout`
|
||
- GET `/api/agent/profile`
|
||
- PUT `/api/agent/profile`
|
||
- POST `/api/agent/change-password`
|
||
- GET `/api/agent/transactions`
|
||
|
||
### 代理商售卡
|
||
|
||
- POST `/api/agent/cards/generate`
|
||
- GET `/api/agent/cards`
|
||
|
||
说明：代理商售卡会按项目价格 * 折扣扣减余额，支持 `X-Idempotency-Key` 防重复扣款。
|
||
|
||
## 客户端/SDK 接口
|
||
|
||
### 1) 卡密验证
|
||
|
||
POST `/api/auth/verify`
|
||
|
||
```json
|
||
{
|
||
"projectId": "PROJ_001",
|
||
"keyCode": "A3D7-K2P9-M8N1-Q4W6",
|
||
"deviceId": "SHA256硬件指纹",
|
||
"clientVersion": "1.0.0",
|
||
"timestamp": 1735000000,
|
||
"signature": "HMAC-SHA256签名"
|
||
}
|
||
```
|
||
|
||
成功返回：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"valid": true,
|
||
"expireTime": "2025-12-31T23:59:59Z",
|
||
"remainingDays": 30,
|
||
"downloadUrl": "/api/software/download?version=1.2.0&token=xxx",
|
||
"fileHash": "sha256...",
|
||
"version": "1.2.0",
|
||
"heartbeatInterval": 60,
|
||
"accessToken": "jwt_token"
|
||
}
|
||
}
|
||
```
|
||
|
||
若客户端版本低于强制更新版本，将返回 `1012 force_update_required`（HTTP 426）。
|
||
|
||
### 2) 心跳验证
|
||
|
||
POST `/api/auth/heartbeat`
|
||
|
||
```json
|
||
{
|
||
"accessToken": "jwt_token",
|
||
"deviceId": "xxx",
|
||
"timestamp": 1735000000,
|
||
"signature": "xxx"
|
||
}
|
||
```
|
||
|
||
### 3) 版本检查
|
||
|
||
POST `/api/software/check-update`
|
||
|
||
### 4) 软件下载
|
||
|
||
GET `/api/software/download?version=1.2.0&token=jwt_token`
|
||
|
||
响应头（加密开启时）：
|
||
|
||
- `X-File-Hash`
|
||
- `X-File-Size`
|
||
- `X-Encryption-Method: AES-256-GCM`
|
||
- `X-Encryption-Key: <Base64>`
|
||
- `X-Encryption-Nonce: <Base64>`
|
||
|
||
## 注意事项
|
||
|
||
- 上传软件版本需要 `multipart/form-data`。
|
||
- 当 `Storage.ClientRsaPublicKeyPem` 未配置时，文件存储为明文，不返回加密头。
|
||
- `/api/software/check-update` 返回的 `downloadUrl` 需要客户端自行追加 `token` 参数（来自 `/api/auth/verify`）。
|
||
- 目前导入卡密仅支持 CSV。
|
||
- 设备限流可通过请求头 `X-Device-Id` 识别设备（建议 SDK 统一加上）。
|
||
- 当系统配置 `feature.auto_update=false` 时，`/api/software/check-update` 将返回 `hasUpdate=false`。
|
||
|
||
## 公共配置接口
|
||
|
||
- GET `/api/config/public`
|
||
|
||
返回所有 `IsPublic = true` 的系统配置（用于客户端功能开关/心跳间隔等）。
|
||
- `/api/admin/stats/*` 除 `dashboard` 外为预留接口。
|