Initial commit

2026-01-04 23:00:21 +08:00
commit d3178871eb
124 changed files with 19300 additions and 0 deletions
--- a/license-system-backend/docs/frontend-handoff.md
+++ b/license-system-backend/docs/frontend-handoff.md
@@ -0,0 +1,296 @@
+# 前端对接文档（管理后台 + 客户端）
+
+本文档基于已实现的后端接口，提供给前端开发使用。
+
+## 统一响应格式
+
+```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` 外为预留接口。