license-manager-sdk-python/docs/design.md

# License Manager Python SDK 设计

## 1. 设计目标
- 提供统一、低侵入的 Python SDK 以封装激活、校验、心跳、许可证管理流程。
- 兼容现有 License Manager 服务端接口，在线/离线模式对业务透明。
- 高可扩展与可测试性：硬件指纹、存储、网络协议处理器等核心可替换（duck typing 理念）。

## 2. 交付范围
- 符合 PEP 标准的 Python 包源码。
- 依赖描述文件（`requirements.txt` / `setup.py`）。
- 示例：最小化直接调用的基础示例 `examples/basic/main.py`。
- 面向 Python 的技术文档。

## 3. 核心模块设计说明
- **client.Client (门面模式)**
  - 组合各模块，提供 `__init__`, `validate`, `current_license`, `close` 等方法。
  - 维护内部状态，并通过 `threading.Lock` 等保证线程安全访问当前 License 版本。
- **config (配置与数据校验)**
  - 定义明确具有 Type hints 的类或 `dataclasses`，支持将环境及文件属性覆盖。
  - 静态检查：在线模式验证服务端必须 URL / 密码文件；离线模式检验证书位置。
- **activation (激活)**
  - 基于标准的 `requests`（带连接池和自动超时重试策略）发起网络激活通信。
  - 接收加密串后调用 validator 核验，成功后通过 storage 保存。
- **validator (强安全验证)**
  - 依托强大的 `cryptography` 包处理 RSA (建议为 PSS padding 等现代方法，具体匹配服务端实现)。
  - 对解包出的许可证时间 `ExpiresAt`、硬件指纹进行 CPU 负载级的精确比较并验证未发生人为修改。
- **heartbeat (心跳维护)**
  - 取代 Go 的 goroutine 使用，改用由 `threading.Thread` 的轮询服务。设置 `daemon=True` 防止卡顿主进程。
  - 设计线程安全的 `threading.Event()` 实现如 `pause`, `resume`, `stop` 这些外部调度接口。
  - 对于网络闪断具有一定指数回退 (Exponential backoff) 容量。
- **hardware (多态指纹搜集)**
  - 抽象采集策略，利用系统底层命令及 `uuid`、`platform` 以避免绑定复杂的原生编译依赖（如果在 CPython 环境可引入 psutil 或仅靠 standard libs 执行降级采集策略）。
- **storage (凭证安全落地)**
  - 文件加解密适配 `cryptography` 在 AES-GCM 算法下使用 256bit 动态密钥做密文打包，防本地脱机逆向嗅探。
- **logger & exceptions (日志体系监控)**
  - 使用标准的 `logging` 获取当前全局记录器。
  - 设计带有分类标记的 `LicenseManagerError`, `NetworkError`, `ValidationError` 提供可分辨的控制流分支。

## 4. 关键生命周期总结
1. **实例化**：加载配置 → 初始化硬件信息/日志/存储机制 → 调用 validator 验算本地既有证书 → 按需挂起并调用 activation 发在线网路激活申请。
2. **后台伴生**：启动 heartbeat daemon → 在给定 `interval` 进行上游 pinging → 若上游发来更新证，回调主线程数据结构；若请求重新激活，则触发 callback 进入阻塞警报。
3. **断网本地态**：应用随时拉起 `client.validate()`。验证不通过抛出 SDK 特有 `Exception`，应用层捕获异常并决定关停自身业务。

## 5. 对比补充与潜在风险
- **包依赖风险**：为降低部署繁杂度，若系统有条件应考虑避免引用含有大量 C 扩展的包，优先利用 Python 3 自带库封装；必须时则明确说明并列在依赖清单首位 (如 `cryptography`)。
- **定时锁和 GIL 干扰**：心跳网络收发本质是 I/O 阻塞型操作，采用线程天然适合，且不易阻断业务代码，但在多线程中覆盖验证缓存 `current_license` 必须添加明确锁保护（`threading.RLock()`），确保不产生竞争读写现象。