# chongming-license-gui

机器码授权的**可视化工具（厂商侧）**：密钥管理 / 签发 / 查看校验。

供商务、售后等不习惯命令行的同学使用，功能与 `uv run chongming-license`（CLI）对等。
所有授权逻辑都调用 [`chongming-license`](../license/) 库 —— 本包**只做界面**，
不重复实现密码学、载荷格式或规范化（一旦有两处实现，就会出现"自己签的自己验不过"）。

## 定位

| | 使用者 | 形态 | 签发能力 |
| --- | --- | --- | --- |
| **本工具** | 厂商（商务/售后/研发） | 桌面 GUI | ✅ 持有私钥 |
| `chongming-license` CLI | 厂商（研发/自动化） | 命令行 | ✅ 持有私钥 |
| 设备端「授权」页 | 客户 / 现场装机 | 浏览器 `/static/license` | ❌ 只导出申请码、导入 license |

**本工具不随部署产物分发** —— 签发私钥只应存在于厂商机器上。

## 安装与运行

```bash
cd utils/license-gui
uv sync
uv run chongming-license-gui
```

无图形环境（SSH / CI）下可做冒烟检查：

```bash
QT_QPA_PLATFORM=offscreen uv run python -c "
from PySide6.QtWidgets import QApplication
from chongming_license_gui.app import MainWindow
app = QApplication([]); w = MainWindow(); w.show()
print('界面构建成功')
"
```

## 三个页面

### 签发（默认页）

日常最高频的操作。让操作者在**按下签发之前**就看清"给谁、哪台机器、哪些插件、多久"。

- **签名私钥**：显示当前生效的私钥路径与公钥指纹（签发前核对，避免拿错密钥）
- **签发依据**（三选一）：
  - *申请码*（推荐）—— 粘贴 `CM1-...`，自动解析出机器码与各来源指纹，支持换硬件容错
  - *来源 JSON 文件* —— `show --json` 的导出文件
  - *仅机器码* —— 精确匹配、无容错（界面会明确警示）
- **授权插件**：勾选式列表，自动从 `<项目根>/config/workers/*/config.toml` 读出本项目实际插件；
  也可手工添加任意 type；支持全选/全不选/移除
- **授权信息**：客户、授权编号（留空自动生成）、备注、密钥标识、有效期（N 天 / 指定日期 / 永久）
- **预览与签发**：载荷 JSON 预览（与签名用的是同一个对象，所见即所签）→ 签发并保存

### 台账

已签发授权的检索与管理。**签发页签发的每一份都会自动入库**（含机器指纹）。

- **检索**：客户 / 机器码 / 插件 / 状态 / 关键字 / 即将到期窗口；按到期日升序，最急的在前
- **概览**：总数与有效/即将到期/已过期/永久/未生效计数
- **续期**：选中一条 →「续期选中…」→ 只改要变的部分 → 续期并保存。
  **指纹复用自台账，无需再向客户索取申请码**；默认生成新编号（新旧都留台账可追溯），
  旧记录自动加上 `已续期 → <新编号>` 批注
- **备注**：人工批注，重新导入 license 不会覆盖（载荷里的 `note` 是签名内容的一部分，
  台账的 `note` 是厂商自己的批注）
- **详情**：查看各来源指纹与**原始 license 文件内容**（当初签发的那份）
- **导出**：`.lic`（可选按客户分目录）+ CSV 清单（UTF-8 BOM，Excel 中文不乱码）

台账库默认 `~/.chongming/licenses.db`，可在此页切换；单文件 SQLite，可直接进备份。

### 密钥

- **生成密钥对**：一键生成 Ed25519 密钥对，私钥写为 `0600` 的 PEM，
  公钥自动复制到剪贴板（下一步注入构建就要用）
- **加载现有私钥**：显示对应公钥与指纹，用于确认"这把私钥对应哪把公钥"
- 公钥 base64（可直接填进 `[license] public_key`）与 PEM 都可单独复制

### 查看 / 校验

- 打开 `.lic` 查看全部字段（不验签也能看）
- 填公钥后验签，给出结论 + 原因码 + 命中/不匹配的来源
- **指纹比对基准**可选：
  - *本机指纹* —— 在厂商机器上通常对不上，属正常
  - *指定机器*（填客户设备的申请码）—— **发货前自检**的关键：
    确认这份 license 确实是为目标设备签发的，而不是只验出"签名有效"

## 与 CLI 的对应关系

| GUI 操作 | CLI |
| --- | --- |
| 详情面板 / 状态栏 | `chongming-license verify` |
| 签发 → 签发并保存 | `chongming-license issue` |
| 密钥 → 生成密钥对 | `chongming-license keygen` |
| 密钥 → 加载私钥（显示公钥/指纹） | `chongming-license keygen` 的输出 / `inspect --key` |
| 查看 / 校验 → 仅查看内容 | `chongming-license inspect` |
| 查看 / 校验 → 指定机器 | `chongming-license verify --request-code` |

批量签发（一次几十台）建议直接用 CLI 脚本化；GUI 面向单台/少量、需要人工核对信息的场景。

## 安全注意

- 本工具会在 `QSettings` 里记住**私钥路径、客户名、备注、输出目录**（便于连续签发），
  **不会**记住私钥内容本身。
- 私钥文件权限为 `0600`，且 `.gitignore` 忽略 `license_private*.pem`。
- `uv run build` 会扫描构建产物，发现私钥即终止构建。
- ⚠ 私钥丢失 = 无法再签发新授权；私钥泄漏 = 任何人都能签发授权。请离线备份。

## 完整文档

见仓库 [docs/license.md](../../docs/license.md)：激活流程、命令行参考、机器指纹与容错判定、
强制执行点、安全边界、故障排查（含原因码全表）。