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

定位

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

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

界面

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

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

安装与运行

uv sync
uv run chongming-license-gui

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

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

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。

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

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

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

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

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

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。

与 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 面向单台/少量、需要人工核对信息的场景。

开发

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

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

打包分发

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。

安全注意

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

README.md Unescape Escape

chongming-license-gui

文档导航

定位

界面