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` (可选)