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 能力复用

```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. CLI 工具设计

### 5.1 命令结构

```text
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 |