# 前端对接文档（管理后台 + 客户端）

本文档基于已实现的后端接口，提供给前端开发使用。

## 统一响应格式

```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` 外为预留接口。