237899745/kami
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
kami/license-system-backend/docs/frontend-handoff.md
yuyx d3178871eb Initial commit
2026-01-04 23:00:21 +08:00

7.0 KiB
Raw Permalink Blame History

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

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

统一响应格式

{
  "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

响应：

{
  "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

{
  "projectId": "PROJ_001",
  "keyCode": "A3D7-K2P9-M8N1-Q4W6",
  "deviceId": "SHA256硬件指纹",
  "clientVersion": "1.0.0",
  "timestamp": 1735000000,
  "signature": "HMAC-SHA256签名"
}

成功返回：

{
  "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

{
  "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 外为预留接口。
Reference in New Issue View Git Blame Copy Permalink