mirror of
https://github.com/hpd840321/craftlabs-authorization-sdk.git
synced 2026-06-09 10:00:30 +08:00
182 lines
6.6 KiB
Markdown
182 lines
6.6 KiB
Markdown
# 客户端授权管理工具设计
|
||
|
||
> **日期**：2026-05-25
|
||
> **目标**：提供桌面 GUI 工具，让客户终端用户自助完成设备授权、授权迁移、撤销授权
|
||
> **技术选型**：Tauri 2.x (Rust 壳) + Vue 3 (UI) + craft-core (授权核心)
|
||
|
||
---
|
||
|
||
## 1. 现有 SDK 能力复用
|
||
|
||
```text
|
||
┌─────────────────────────────────────┐
|
||
│ Client Authorization Tool (Tauri) │
|
||
│ ┌───────────────────────────────┐ │
|
||
│ │ Vue 3 UI Layer │ │
|
||
│ │ (授权状态/激活/迁移/撤销) │ │
|
||
│ └───────────┬───────────────────┘ │
|
||
│ │ IPC (invoke) │
|
||
│ ┌───────────▼───────────────────┐ │
|
||
│ │ Rust Backend (Tauri cmd) │ │
|
||
│ │ - 调用 craft-core C ABI │ │
|
||
│ │ - HTTP 请求平台 API │ │
|
||
│ │ - 本地配置持久化 │ │
|
||
│ └───────────┬───────────────────┘ │
|
||
│ │ FFI │
|
||
│ ┌───────────▼───────────────────┐ │
|
||
│ │ craft-core (Rust cdylib) │ │
|
||
│ │ - activate/check/release │ │
|
||
│ │ - 设备指纹 / 加密 / 心跳 │ │
|
||
│ └───────────────────────────────┘ │
|
||
└─────────────────────────────────────┘
|
||
```
|
||
|
||
### 1.1 可直接复用的 Rust 模块
|
||
|
||
| 模块 | 复用方式 | 现状 |
|
||
|------|---------|------|
|
||
| `craft_initialize` | Tauri 启动时调用 | ✅ 已实现 |
|
||
| `craft_activate` | 用户点击"激活"时调用 | ✅ 已实现 |
|
||
| `craft_check_license` | 首页状态展示 | ✅ 已实现 |
|
||
| `craft_get_license_info` | 授权详情展示 | ✅ 已实现 |
|
||
| `craft_has_feature` | 功能特性开关展示 | ✅ 已实现 |
|
||
| `craft_release` | 撤销授权时调用 | ✅ 已实现 |
|
||
| `craft_heartbeat` | 后台定期心跳 | ✅ 已实现 |
|
||
| `device.rs` | 设备指纹采集 | ✅ 已实现 |
|
||
|
||
### 1.2 需新增的能力
|
||
|
||
| 能力 | 说明 |
|
||
|------|------|
|
||
| **HTTP 客户端** | Tauri Rust 后端调平台 REST API（SN 查询/换机申请/状态同步） |
|
||
| **本地配置持久化** | 保存激活的 SN、授权信息到本地安全存储 |
|
||
| **自动启动/托盘** | 系统托盘常驻，后台心跳，状态变更通知 |
|
||
| **平台 API 客户端** | 封装若干平台 API（查询绑定、提交换机、提交激活结果） |
|
||
|
||
---
|
||
|
||
## 2. 功能设计
|
||
|
||
### 2.1 首页 — 授权概览
|
||
|
||
| 区块 | 内容 |
|
||
|------|------|
|
||
| **授权状态卡片** | 大图标 + 状态（已授权/未授权/已过期）+ 授权类型（正式/试用） |
|
||
| **设备信息** | 设备名称、设备指纹(mid)、操作系统 |
|
||
| **授权摘要** | SN 编码、有效期、剩余天数、功能特性列表 |
|
||
| **操作区** | 激活授权、迁移授权、撤销授权三个主按钮 |
|
||
|
||
### 2.2 激活授权流程
|
||
|
||
```
|
||
1. 用户点击「激活授权」
|
||
2. 弹出对话框：输入 SN 编码（或从剪贴板粘贴）
|
||
3. 工具调用 craft_activate(SN) → 本地验证
|
||
4. 若为 selfhosted 模式 → HTTP 请求平台 API 完成远程验证
|
||
5. 成功 → 显示授权详情，开始心跳
|
||
6. 失败 → 显示错误原因（SN 无效/已吊销/网络超时等）
|
||
```
|
||
|
||
### 2.3 授权迁移流程
|
||
|
||
```
|
||
1. 用户点击「迁移授权」
|
||
2. 工具显示当前绑定的设备信息 + SN
|
||
3. 用户确认「迁移到本设备」
|
||
4. 工具先调用 craft_release() 释放旧设备授权
|
||
5. HTTP 请求平台 API 记录换机申请
|
||
6. 重新调用 craft_activate() 在新设备激活
|
||
7. 完成迁移
|
||
```
|
||
|
||
### 2.4 撤销授权流程
|
||
|
||
```
|
||
1. 用户点击「撤销授权」
|
||
2. 二次确认对话框（含风险提示）
|
||
3. 工具调用 craft_release() 释放本地授权
|
||
4. HTTP 请求平台 API 更新 SN 状态为 REVOKED
|
||
5. 清除本地配置
|
||
```
|
||
|
||
### 2.5 授权详情页
|
||
|
||
| 展示项 | 来源 |
|
||
|--------|------|
|
||
| SN 编码 | craft_get_license_info |
|
||
| 授权状态 | craft_check_license |
|
||
| 有效期 | expiration_date |
|
||
| 已授权特性 | feature_names / feature_values |
|
||
| 设备指纹(mid) | device.rs |
|
||
| 首次激活时间 | 平台 API |
|
||
| 最近心跳时间 | 本地记录 |
|
||
| 绑定历史 | 平台 API |
|
||
|
||
---
|
||
|
||
## 3. 与平台 API 的交互
|
||
|
||
工具需要通过 HTTP 与交付平台后端通信：
|
||
|
||
| 平台 API | 方法 | 用途 |
|
||
|----------|------|------|
|
||
| `/api/v1/auth/client-login` | POST | 客户端登录（获取工具专用 token） |
|
||
| `/api/v1/licenses/verify` | POST | 验证 SN 有效性 |
|
||
| `/api/v1/licenses/activate` | POST | 提交激活结果 + 设备指纹 |
|
||
| `/api/v1/licenses/revoke` | POST | 提交撤销申请 |
|
||
| `/api/v1/devices/swap-request` | POST | 提交换机申请 |
|
||
| `/api/v1/devices/{mid}/bindings` | GET | 查询绑定历史 |
|
||
|
||
### API 安全
|
||
|
||
- 客户端工具使用独立 API Token（非管理后台 JWT）
|
||
- Token 限制：仅可操作本设备关联的 SN
|
||
- 所有请求附带设备指纹签名
|
||
|
||
---
|
||
|
||
## 4. 目录结构
|
||
|
||
```
|
||
client-tool/
|
||
├── src-tauri/
|
||
│ ├── src/
|
||
│ │ ├── main.rs # Tauri 入口 + 命令注册
|
||
│ │ ├── commands.rs # Tauri IPC 命令（activate/check/release/migrate）
|
||
│ │ ├── platform_api.rs # 平台 REST API 客户端
|
||
│ │ ├── license.rs # 授权生命周期管理
|
||
│ │ └── config.rs # 本地持久化配置
|
||
│ ├── Cargo.toml # 依赖 craft-core 等
|
||
│ └── tauri.conf.json # Tauri 配置
|
||
├── src/
|
||
│ ├── App.vue
|
||
│ ├── views/
|
||
│ │ ├── DashboardView.vue # 首页概览
|
||
│ │ ├── ActivateView.vue # 激活向导
|
||
│ │ ├── DetailView.vue # 授权详情
|
||
│ │ └── SettingsView.vue # 设置
|
||
│ └── components/
|
||
│ ├── StatusCard.vue
|
||
│ └── FeatureList.vue
|
||
├── package.json
|
||
└── README.md
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 迭代建议
|
||
|
||
| 阶段 | 内容 | 估计 |
|
||
|------|------|------|
|
||
| **P0** | Tauri 壳搭建 + craft-core 集成 + 激活/查看状态 | 2周 |
|
||
| **P1** | 授权迁移 + 撤销授权 + 平台 API 对接 | 1周 |
|
||
| **P2** | 系统托盘 + 心跳 + 自动更新 + 打包签名 | 1周 |
|
||
|
||
---
|
||
|
||
## 6. 修订记录
|
||
|
||
| 日期 | 说明 |
|
||
|------|------|
|
||
| 2026-05-25 | 初版：基于 PRD 评估和 Tauri 技术选型撰写 |
|