chongming-license-gui/README.md

# chongming-license-gui

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

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

## 文档导航

| 文档 | 读者 | 内容 |
| --- | --- | --- |
| [docs/使用手册.md](docs/使用手册.md) | 商务 / 售后 / 技术支持 | 三步上手、逐字段说明、场景速查、FAQ、原因码全表 |
| [docs/界面设计.md](docs/界面设计.md) | 维护界面的人 | 设计 token、控件规范、如何改主题、维护红线 |
| [packaging/README.md](packaging/README.md) | 出包的人 | 打包成免安装 exe（PyInstaller / Nuitka）、安全闸门、产物自检 |
| 本文 | 研发 / 集成 | 定位、安装运行、安全边界、与 CLI 对照 |

## 定位

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

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

## 界面

![签发页](docs/images/01-issue.png)

界面为现代浅色卡片风：白底卡片分区、主色 `#2563eb`、状态色规范化
（过期红 / 即将到期橙 / 有效绿 / 永久蓝 / 未生效紫）、全套图标与悬停/焦点态。
四个页签都套了滚动容器，小屏（1366×768）上不会再出现底部按钮被截断的情况。

样式集中在 `theme.py`（token + QSS）与 `icons.py`（内联 SVG，无二进制素材），
改主题见 [docs/界面设计.md](docs/界面设计.md)。

## 安装与运行

```bash
uv sync
uv run chongming-license-gui
```

依赖 `chongming-license` 从内部索引拉取（见 `pyproject.toml` 的 `[[tool.uv.index]]`）。
若在同仓并行开发该库，可改用 `pyproject.toml` 里注释掉的 path 依赖
（**必须带 `editable = true`**，否则改库代码后需重新 `sync` 才生效）。

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

```bash
QT_QPA_PLATFORM=offscreen uv run python smoke_test.py
```

该脚本驱动**真实控件**跑完整流程（生成密钥 → 解析申请码 → 预览 → 签发 →
查看校验（目标机通过、异机拒绝）→ 台账入库/检索/续期/改插件/导出/删除），
并包含一组界面主题断言（样式是否真的渲染、指示器是否会变空白）。
在 Windows / macOS 上它会自动改用合成指纹（硬件指纹来源都是 Linux 侧的）。

## 四个页面

- **签发**（默认页）：私钥状态 → 签发依据（申请码 / 来源 JSON / 仅机器码）→
  勾选授权插件 → 填写授权信息 → 载荷预览 → 签发并保存（可自动记入台账）。
  设计目标是让你**在按下签发之前**看清"给谁、哪台设备、哪些插件、多久"。
- **台账**：已签发授权的检索、**续期**（复用台账指纹，无需再向客户索取申请码）、
  **改插件**（只换插件白名单重签，有效期与生效日原样保留）、
  备注批注、详情查看、`.lic` 与 CSV 导出。默认库 `~/.chongming/licenses.db`（单文件 SQLite）。
- **密钥**：生成/加载 Ed25519 密钥对，显示公钥（base64 / PEM）与公钥指纹。
- **查看 / 校验**：查看 `.lic` 内容、验签，并按"本机"或"指定机器（客户申请码）"
  做指纹比对 —— 后者是**发货前自检**的关键。

每个字段的详细说明见 [docs/使用手册.md](docs/使用手册.md)。

## 台账存储：本地 SQLite 或共享 PostgreSQL

台账默认是**本机单文件**（SQLite）。团队若想共用一份台账（谁签给了谁、哪台设备
快到期，不用互相问），可在「台账」页把「存储」切到 **PostgreSQL**（默认端口 5432）：

- **可选功能**，不装驱动照样能用本地台账；
- 首次连接**自动建表**；账号无建表权限时用 `docs/pg_schema.sql` 交给 DBA 执行；
- 密码**默认不保存**，勾选"记住密码"才写入本机配置（有明文警示）；
- 密码不会出现在日志、标签或错误信息里；DSN 传递用 kwargs，异常不回显凭据。

```bash
uv sync --extra postgres    # 启用 PG 支持（打包产物用 dev 依赖，已包含）
```

**关于"PG 后端是否可靠"**：不是推测 —— `tools/pg_check.py` 会用**同一套契约**
分别跑本地 SQLite 与 PostgreSQL 并逐项对比，全程在一个事务里、最后 `ROLLBACK`
（连建表都回滚，对真实库零残留）：

```bash
uv run python tools/pg_check.py --host 127.0.0.1 --port 5432 \
    --dbname chongming --user postgres        # 密码走 PGPASSWORD 或交互输入
```

已在 PostgreSQL 16 上跑通全部 19 项对比（排序/过滤大小写/状态分桶/批注与入库时间
保留/导出文件名与 CSV 编码/删除），GUI 实际路径（`holder.open_postgres` → 自动建表
→ 入库 → 重连 → 版本校验 → 导出）也做了端到端验证。细节见
[docs/使用手册.md 4.9](docs/使用手册.md)。

## 与 CLI 的对应关系

CLI（`chongming-license`）由 `chongming-license` 包提供，**本仓不安装它**
（当前环境里没有该命令）。装了 CLI 的环境可按下表对照：

| GUI 操作 | CLI |
| --- | --- |
| 签发 → 签发并保存 | `chongming-license issue` |
| 密钥 → 生成密钥对 | `chongming-license keygen` |
| 密钥 → 加载私钥（显示公钥/指纹） | 同上输出 / `inspect --key` |
| 查看 / 校验 → 仅查看内容 | `chongming-license inspect` |
| 查看 / 校验 → 按指定机器 | `chongming-license verify --request-code` |
| 台账 → 详情面板 | `chongming-license verify` |
| 台账 → 改插件 | `chongming-license issue`（`--plugins` 换白名单，机器码与日期照抄台账） |

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

## 开发

```bash
uv run python smoke_test.py        # 全流程 + 主题断言（无头）
uv run python tools/screenshot.py  # 重新生成 docs/images/ 里的文档截图
```

截图脚本会重定向 `QSettings` 与台账库到临时目录、当场生成一次性密钥，
**不接触真实的私钥、台账与配置**。

## 打包分发

```bash
uv sync --group dev                        # 装打包工具
uv run python packaging/build_pyinstaller.py   # 方式一：快，约 2.5 分钟
uv run python packaging/build_nuitka.py        # 方式二：真编译，更小更快但慢
```

产物在 `dist/`，是**免安装单文件 exe**，发给厂商内部同事用。两个脚本都自带：

- **私钥守卫**：源码树里出现私钥 / `*.lic` / `licenses.db` 时**中止构建** ——
  这个工具含签发能力，私钥随包发出去等于任何人都能签发授权；
- **产物自检**：构建后自动跑 `<exe> --selftest`，并在 **offscreen 与系统原生两个
  平台插件**下各验一遍（后者才证明 Qt 的平台插件真的打进产物了），覆盖 QtSvg、
  复选框指示器、Ed25519 签发验签、orjson、台账、插件发现与整窗渲染。

细节、两种方式的取舍与趟坑见 [packaging/README.md](packaging/README.md)。

## 安全注意

- 本工具会在 `QSettings` 里记住**私钥路径、客户名、备注、输出目录**等（便于连续签发），
  **不会**记住私钥内容本身。
- 私钥在 Linux/macOS 上写为 `0600`。⚠ **Windows 没有 POSIX 权限位**，`chmod` 不生效 ——
  Windows 上请把私钥放在只有你能访问的目录，并依赖磁盘加密与账号权限。
- 本仓 `.gitignore` 已忽略私钥与台账产物（`license_private*.pem`、`*_private.pem`、
  `*.lic`、`licenses.db`），但这只是**兜底**：真正的防线是不要把私钥放进仓库目录。
- 发布/发包前请自行确认产物中不含私钥与台账库
  （本仓没有构建脚本钩子；上游项目的构建脚本才有"扫到私钥即终止"的守护检查）。
- ⚠ 私钥丢失 = 无法再签发新授权；私钥泄漏 = 任何人都能签发授权。请离线备份。