craftlabs-authorization-sdk/docs/superpowers/specs/2026-05-25-client-authorization-tool-design.md

客户端授权管理工具设计

日期：2026-05-25 目标：提供客户端授权管理工具，让客户终端用户自助完成设备授权、授权迁移、撤销授权。分为 CLI 和 GUI 两个形态。 实施顺序：① 完善现有 SDK（JNI 桥接 + 集成测试）→ ② CLI 工具 → ③ GUI 桌面工具 技术选型：CLI = Rust clap + craft-core；GUI = Tauri 2.x + Vue 3 + craft-core

---

1. 现有 SDK 能力复用

┌─────────────────────────────────────┐
│  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. CLI 工具设计

5.1 命令结构

craftlabs-auth-cli
├── craft status          # 查看本地授权状态
├── craft activate <SN>   # 使用 SN 激活本机
├── craft check           # 检查授权是否有效
├── craft info            # 显示授权详情 + 功能特性
├── craft release         # 撤销本机授权
├── craft migrate <SN>    # 迁移授权到本机
├── craft heartbeat       # 手动触发心跳
├── craft device-id       # 显示本机设备指纹
└── craft config          # 查看/修改本地配置

5.2 技术实现

• Rust 二进制 crate，Cargo.toml 中依赖 craft-core（path dependency）
• 使用 clap crate 解析命令行参数
• 平台 API 调用使用 reqwest（已有依赖）
• 输出格式支持 text（默认）和 json（--json 参数）
• 跨平台编译：Linux x86_64 + aarch64, macOS x86_64 + arm64, Windows x86_64

5.3 CLI 与 craft-core 的调用关系

craft activate SN-12345
  └→ clap 解析 args → "activate"
      └→ craft_initialize(config) → 初始化上下文
          └→ craft_activate(handle, "SN-12345")
              ├→ 成功 → 持久化 SN 到本地配置
              └→ 失败 → 打印错误原因

6. 实施路线

阶段	内容	估计	交付物
S1: 完善SDK	JNI bridge 编译+集成测试+CI	1周	可调用的 Java SDK
S2: CLI MVP	基础 CLI（status/activate/check/release）	1周	craftlabs-auth-cli 二进制
S3: CLI 完整	migrate/heartbeat/config + 平台 API 对接	1周	完整 CLI 功能
S4: GUI P0	Tauri 壳 + Vue UI + 激活/状态查看	2周	桌面应用
S5: GUI P1	迁移/撤销 + 系统托盘 + 心跳	1周	完整桌面应用

---

7. 修订记录

日期	说明
2026-05-25	初版：基于 PRD 评估和 Tauri 技术选型撰写
2026-05-25	补充：CLI 工具设计 + 实施顺序调整为 SDK→CLI→GUI