license-manager-sdk-python/docs/项目全局认知.md

项目全局认知

本文档主要负责梳理 License Manager 面向 Python 开发者翻写过程中的整体文件存放策略，以及包结构的宏观认知。

由于原始开发使用 Go 语言，部分文件习惯（如根域名即包名）并不完全适用 Python（考虑到 Python 中不合法的 "-" 命名）。因此，对于 Python SDK，我们采取如下被业界广泛遵循的标准 Python 包（Package）部署和命名规范。

目录结构（全景）

license-manager-sdk-python/        # 项目根目录（Repo）
├── docs/                          # 相关的工程文档目录
│   ├── 项目全局认知.md            # 当前文档：建立对项目文件夹分布的宏观理解
│   ├── design.md                  # 核心设计决策（基于 Python 特性适配过的系统模型）
│   ├── 翻写计划.md                # 各个批次的 DAG 执行计划和阶段任务
│   ├── iteration-log.md           # TaskLoop：执行反馈及尝试日志
│   └── project-context.md         # TaskLoop：微观状态记忆
├── license_manager/               # 【核心源码包】符合 PEP8 的包名，供外部导入
│   ├── __init__.py                # 暴露出 SDK 的唯一公开类 Client
│   ├── client.py                  # 门面层Facade，聚合 Config/Hardware/Validator 等模块
│   ├── config.py                  # 配置解析（DataClass / Pydantic 等模型）
│   ├── models.py                  # 数据结构，涵盖 Request/Response 及许可证字段定义
│   ├── hardware.py                # 跨平台的硬件信息（mac, hostname, cpu等）采集器
│   ├── storage.py                 # AES-GCM 安全存储持久化器
│   ├── validator.py               # 面向 payload 进行 RSA 验签与防篡改逻辑
│   ├── activation.py              # 将 HTTP 调用隔离：专职负责 /api/v1/activate 请求
│   ├── heartbeat.py               # 定时服务调度（依托 threading.Thread）和心跳接口
│   ├── logger.py                  # 适配 Python 原生 logging 的单例构造器
│   └── exceptions.py              # SDK 中抛出的所有专有异常定义（如网络超时、无授权等）
├── tests/                         # 测试代码集 (Pytest 等框架)
│   ├── test_hardware.py
│   ├── test_validator.py
│   └── ...
├── examples/                      # 对客户公开的应用集成示例
│   └── basic/
│       └── main.py                # 照搬 Go 版 demo 逻辑的 Python 实现
├── requirements.txt               # 运行必须的核心第三方依赖 (如 requests, cryptography)
├── setup.py                       # 模块构建、打包配置文件（可选也可使用 pyproject.toml）
├── .gitignore                     # Git 提交忽略配置文件
└── README.md                      # 针对 Python 版本的接口快速使用说明

Python 设计与 Go 的核心差异

1. 统一入口：所有模块收拢在合规的包名 license_manager 下，用户只需在外部调用 import license_manager as license，然后使用 license.Client(cfg)。
2. 并发与定时任务：相较于 Go 语言轻量级的 Goroutine 处理后台心跳和回调触发，Python 需要通过启动后台 Daemon 线程 threading.Thread 进行心跳轮询，并在进行锁处理或休眠时关注 GIL 和中断异常捕获结构。
3. 日志框架对接：Python 提供更系统完整的 logging 模块机制，在此不一定需要过多自定义，只需注入正确的 logger 组件即可。