From f82a2a7b24c6c147f4327fab2911ddb117efe769 Mon Sep 17 00:00:00 2001
From: huangping <huangping@craftlabs.cn>
Date: Mon, 25 May 2026 15:12:08 +0800
Subject: [PATCH] docs: add CLI tool design and update implementation order
 (SDK->CLI->GUI)

---
 ...-05-25-client-authorization-tool-design.md | 58 ++++++++++++++++---
 1 file changed, 49 insertions(+), 9 deletions(-)

diff --git a/docs/superpowers/specs/2026-05-25-client-authorization-tool-design.md b/docs/superpowers/specs/2026-05-25-client-authorization-tool-design.md
index 1295aac..640d2cb 100644
--- a/docs/superpowers/specs/2026-05-25-client-authorization-tool-design.md
+++ b/docs/superpowers/specs/2026-05-25-client-authorization-tool-design.md
@@ -1,8 +1,9 @@
 # 客户端授权管理工具设计
 
 > **日期**：2026-05-25
-> **目标**：提供桌面 GUI 工具，让客户终端用户自助完成设备授权、授权迁移、撤销授权
-> **技术选型**：Tauri 2.x (Rust 壳) + Vue 3 (UI) + craft-core (授权核心)
+> **目标**：提供客户端授权管理工具，让客户终端用户自助完成设备授权、授权迁移、撤销授权。分为 CLI 和 GUI 两个形态。
+> **实施顺序**：① 完善现有 SDK（JNI 桥接 + 集成测试）→ ② CLI 工具 → ③ GUI 桌面工具
+> **技术选型**：CLI = Rust clap + craft-core；GUI = Tauri 2.x + Vue 3 + craft-core
 
 ---
 
@@ -164,18 +165,57 @@ client-tool/
 
 ---
 
-## 5. 迭代建议
+## 5. CLI 工具设计
 
-| 阶段 | 内容 | 估计 |
-|------|------|------|
-| **P0** | Tauri 壳搭建 + craft-core 集成 + 激活/查看状态 | 2周 |
-| **P1** | 授权迁移 + 撤销授权 + 平台 API 对接 | 1周 |
-| **P2** | 系统托盘 + 心跳 + 自动更新 + 打包签名 | 1周 |
+### 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周 | 完整桌面应用 |
 
 ---
 
-## 6. 修订记录
+## 7. 修订记录
 
 | 日期 | 说明 |
 |------|------|
 | 2026-05-25 | 初版：基于 PRD 评估和 Tauri 技术选型撰写 |
+| 2026-05-25 | 补充：CLI 工具设计 + 实施顺序调整为 SDK→CLI→GUI |