license-manager-sdk-python/docs/翻写计划.md

License Manager SDK (Python) 翻写计划

目标与概述

将 license-manager-sdk-go 的核心功能完整翻写为 Python 版本，保持相同的架构设计模式，以便在 Python 项目中无缝集成。SDK 需要支持：

1. 在线/离线激活与校验
2. 硬件指纹采集（MAC, Hostname, CPU, Memory）
3. 本地加密存储（AES-GCM）
4. RSA 签名验证
5. 后台心跳与生命周期管理（自动心跳、断网重试、手动控制）

架构与模块映射映射 (Go -> Python)

Go Module	Python Module	功能描述
config	license_manager.config	SDK 配置定义与校验（Config 类）
models	license_manager.models	数据模型定义（Pydantic 或 Dataclasses）
hardware	license_manager.hardware	硬件特征采集（跨平台 mac, hostname, cpu, memory 获取）
validator	license_manager.validator	对 payload 的 RSA 校验与防篡改验证
storage	license_manager.storage	基于 AES-GCM 的本地凭证加解密与存储
activation	license_manager.activation	封装向远端发起的激活 HTTP 请求
heartbeat	license_manager.heartbeat	封装心跳请求，及基于守护线程的 HeartbeatManager 心跳定时发送
license	license_manager.client	暴露给业务的核心入口 Client
logger	license_manager.logger	标准 logging 封装
internal/httpclient	融合到请求中	推荐依赖 requests 库或内置 urllib，统一超时和重试

详细实施步骤

1. 基础模型与配置 (Day 1)

• models.py: 定义 ActivateRequest, ActivateResponse, HeartbeatRequest, HeartbeatResponse, LicensePayload。使用 Python 内置的 dataclasses 或 pydantic（如允许第三方依赖）。
• config.py: 定义 Config 类，实现参数校验、默认值填充（如默认 5 分钟心跳，默认拉取文件等）。

2. 硬件指纹采集 (Day 1)

• hardware.py:
  • mac: 使用 uuid.getnode() 或第三方 getmac 库处理跨平台网卡 MAC 获取。
  • hostname: 使用 socket.gethostname()。
  • cpu/memory: 使用内置 os, platform 或第三方 psutil 获取。

3. 加解密与校验核验 (Day 2)

• 需要依赖常用的加解密库，如 cryptography 或 pycryptodome。
• storage.py: 实现 AES-GCM 加密，保存到本地文件。
• validator.py: 实现 RSA (PKCS#1 v1.5 或 PSS) 签名验证模块，确认下发的 License 数据未被篡改，并校验 ExpiresAt 以及硬件指纹比对。

4. HTTP 网络与心跳守护线程 (Day 3)

• activation.py: 封装激活接口。
• heartbeat.py:
  • HeartbeatService: 封装心跳请求接口。
  • HeartbeatManager: 包含一个 threading.Thread 或 asyncio 任务，支持 start(), pause(), resume(), stop() 机制。

5. 核心 Client 组装 (Day 4)

• client.py:
  • 实现 Client 类作为门面 (Facade)。
  • __init__: 组织 config, hardware, validator, storage 等初始化，并自动尝试加载本地缓存或发起在线请求。
  • 实现 current_license(), validate(), pause_heartbeat(), resume_heartbeat(), close()。

6. 测试与示例 (Day 5)

• examples/basic/main.py: 对标 Go 的 examples/basic，展示线上模式、配置回调、获取许可限制等用法。
• 单元测试: 对硬件采集、加解密、校验算法编写 pytest 测试。

Python 依赖建议

• HTTP/网络: requests
• 加密与签名: cryptography
• 模型验证: pydantic (可选)
• 硬件指标扩展: psutil (可选)