From ec4f7df84e2274441ac7351fb0f5f9ee90f74a4c Mon Sep 17 00:00:00 2001 From: TermiNexus Date: Thu, 30 Jul 2026 00:49:33 +0800 Subject: [PATCH] Updated the GVSDSDK README 2 --- gvsdsdk/README.md | 108 ++++++++++++++++++++++++++++++++-------------- 1 file changed, 75 insertions(+), 33 deletions(-) diff --git a/gvsdsdk/README.md b/gvsdsdk/README.md index 67960153..510d3b9a 100644 --- a/gvsdsdk/README.md +++ b/gvsdsdk/README.md @@ -1,33 +1,45 @@ # GVSDS - SDK -> **薄封装层**：直接包装 `gvsds/apps/msync` 原生层，作为子服务器（如 `ATestCServer`）和主服务器（`gvsds`）之间共享的通信桥梁。 +> **GVSDS 分布式 SDK**：为 GVSDS 平台子服务器（如 `ATestCServer`）和主服务器（`gvsds`）提供共享的协议契约、ORM 模型、权限体系与通信引擎。 > -> **设计原则**：所有方法名 1:1 对应原生层 PascalCase；零业务逻辑；纯转发。 +> **混合实现策略**： +> - **自有实现**（无 Django 依赖，子服务器开箱即用）：`msync.auth`（HMAC 签名 + `ServiceTokenEncoder`）、`msync.client`（REST 客户端）、`msync.local_tx`（本地事务）、`fluent`（FluentQuery ORM）、`models`（SAAS 数据模型）、`form_service`（通用 CRUD 引擎） +> - **转发自主服务器**（依赖 Django ORM，仅主服务器可加载）：`msync.auth` 中的 `AuthenticateService` / `RefreshServiceToken` / `ValidateAccessToken` / `IssueServiceToken`、`msync.registry`、`msync.ogm`、`msync.transaction` +> - **完整业务模块**：`auth`（用户认证/权限）、`commission`（分佣引擎）、`payment`（支付网关）、`order`（订单）、`minecraft`（MC 插件） > -> **双端版本严格一致**：主从两端必须使用同一 SDK 版本（当前 `1.0.0`），通过 `pyproject.toml` 锁定。 +> **版本兼容**：主从两端必须使用同一 SDK 版本（当前 `1.0.0`）。 --- ## 1. 简介 -`gvsdsdk` 把 `gvsds/apps/msync` 的**所有公共类/函数**原样转发导出，使得： +`gvsdsdk` 是 GVSDS 平台的官方 SDK，提供共享的协议契约、ORM 模型、权限体系与通信引擎。 -- **主服务器**（`gvsds`）：可继续使用自己的 `gvsds.apps.msync` 模块 -- **子服务器**（`ATestCServer`）：可从 `gvsdsdk` 导入**完全相同的 API**，但**不依赖 gvsds 模型层** -- **第三方服务**：可以独立引入 `gvsdsdk` 即可使用全部 MSYNC 能力 +**子服务器可独立使用**（不依赖 GVSDS 主服务器代码）： -被转发的原生模块： +- **用户认证与权限**（`gvsdsdk.auth`）：密码哈希、AES 加密、文件/字节摘要、CurrentRoleMiddleware、RBAC/ABAC 权限、RoleManager / ShopManager / PositionManager +- **MSYNC 认证**（`gvsdsdk.msync.auth`）：HMAC-SHA256 签名 / 验签、`ServiceTokenEncoder` 为自有实现；`AuthenticateService` / `IssueServiceToken` / `ValidateAccessToken` / `RefreshServiceToken` 转发自主服务器 +- **分布式通信**（`gvsdsdk.msync`）：签名 / 客户端 / 本地事务为自有实现；服务注册 / OGM / Saga 事务转发自主服务器 +- **数据模型**（`gvsdsdk.models`）：User / Role / Permission / UserRole / Position 等 SAAS 核心表（managed=False） +- **ORM 查询层**（`gvsdsdk.fluent`）：FluentQuery 链式查询 +- **CRUD 引擎**（`gvsdsdk.form_service`）：FormService 通用增改删查 API +- **业务模块**：`commission`（分佣）/ `payment`（支付）/ `order`（订单）/ `minecraft`（MC 插件） -| SDK 模块 | 包装的原生模块 | 提供的类/函数 | -|---|---|---| -| `gvsdsdk.auth` | `gvsds.apps.msync.auth` | `SignPayload`, `GenerateChallenge`, `BuildAuthPayload`, `AuthenticateService`, `ServiceTokenEncoder`, … | -| `gvsdsdk.registry` | `gvsds.apps.msync.registry` | `ServiceRegistry` | -| `gvsdsdk.ogm` | `gvsds.apps.msync.ogm` | `OGMManager` | -| `gvsdsdk.transaction` | `gvsds.apps.msync.transaction` | `TransactionManager` | -| `gvsdsdk.local_tx` | `gvsds.apps.msync.local_tx` | `LocalTransactionManager`, `StepHandler`, `local_tx` | -| `gvsdsdk.client` | `gvsds.apps.msync.client` | `ServiceClient` | +**主服务器**（`gvsds`）：通过 `gvsdsdk` 与子服务器共享同一份 API 契约，同时直接 import `gvsds.apps.msync` 内部模块。 -每个类在 SDK 与原生层是**完全同一个对象**（`is` 比较为 `True`），无任何运行时包装开销。 +**MSYNC 模块分类**（按依赖关系）： + +| SDK 模块 | 实现方式 | 提供的类/函数 | 是否需 Django | +|---|---|---|---| +| `gvsdsdk.msync.auth`（自有部分） | **自有实现** | `SignPayload`, `VerifySignature`, `GenerateChallenge`, `BuildAuthPayload`, `SignAuthPayload`, `VerifyAuthPayload`, `ServiceTokenEncoder` | 否 | +| `gvsdsdk.msync.auth`（转发部分） | **转发**自 `gvsds.apps.msync.auth` | `AuthenticateService`, `RefreshServiceToken`, `ValidateAccessToken`, `IssueServiceToken` | 是 | +| `gvsdsdk.msync.client` | **自有实现** | `ServiceClient`, `ServiceClientError` | 否 | +| `gvsdsdk.msync.local_tx` | **自有实现** | `LocalTransactionManager`, `StepHandler`, `local_tx` | 否 | +| `gvsdsdk.msync.registry` | **转发**自 `gvsds.apps.msync.registry` | `ServiceRegistry`, `RegistryError` | 是 | +| `gvsdsdk.msync.ogm` | **转发**自 `gvsds.apps.msync.ogm` | `OGMManager`, `OGMError` | 是 | +| `gvsdsdk.msync.transaction` | **转发**自 `gvsds.apps.msync.transaction` | `TransactionManager`, `TransactionError`, `StepExecutionError` | 是 | + +**转发模块**的类在 SDK 与原生层是**同一个对象**（`is` 比较为 `True`）；**自有实现**的类是独立代码。 ## 2. 安装 @@ -40,7 +52,7 @@ sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) 无需额外配置。 -**独立使用**（非 gvsds 生态项目）： +**独立使用**（非 GVSDS 生态项目）： ```bash $env:PYTHONPATH = "D:\SMANAGE\gvsdsdk" @@ -49,27 +61,57 @@ export PYTHONPATH=/path/to/SMANAGE/gvsdsdk ``` 依赖： -- **核心**：`gvsds.apps.msync`（位于 `gvsds/` 项目内） -- **Python**：仅使用标准库 +- **核心**：`gvsdsdk` 自带 ORM 模型（`models.py`）、数据库路由（`db_router.py`）、CRUD 引擎（`form_service.py`） +- **Django**（仅在主服务器场景）：`msync.registry` / `msync.ogm` / `msync.transaction` 三个模块依赖 Django ORM ## 3. 目录结构 ``` gvsdsdk/ -├── __init__.py # 公共导出（re-export） -├── auth.py # → gvsds.apps.msync.auth -├── registry.py # → gvsds.apps.msync.registry -├── ogm.py # → gvsds.apps.msync.ogm -├── transaction.py # → gvsds.apps.msync.transaction -├── local_tx.py # → gvsds.apps.msync.local_tx -└── client.py # → gvsds.apps.msync.client +├── __init__.py # 惰性加载入口（_LAZY_SYMBOLS 字典 + __getattr__） +├── apps.py # Django AppConfig +├── db_router.py # SAASDatabaseRouter +├── form_service.py # FormService 通用 CRUD 引擎 +├── fluent.py # FluentQuery 链式 ORM 查询 +├── model_base.py # QModel / QModelBase +├── model_utils.py # UUIDObj +├── models.py # SAAS 核心数据模型（User/Role/Permission 等） +│ +├── msync/ # MSYNC 服务间通信子包 +│ ├── __init__.py # 模块导出 +│ ├── auth.py # HMAC-SHA256 签名 + ServiceTokenEncoder（自有实现，7 个函数） +│ ├── client.py # REST 微服务客户端（自有实现） +│ ├── local_tx.py # 本地事务步骤（自有实现） +│ ├── orm_handler.py # ORM 处理器 +│ ├── ogm.py # OGM（转发自 gvsds.apps.msync.ogm） +│ ├── registry.py # 服务注册/发现（转发自 gvsds.apps.msync.registry） +│ └── transaction.py # Saga 分布式事务（转发自 gvsds.apps.msync.transaction） +│ +├── auth/ # 用户认证与权限子包 +│ ├── __init__.py +│ ├── admin_service.py # IsAdmin / IsSuperAdmin / IsTenantAdmin +│ ├── cookie.py +│ ├── crypto.py +│ ├── jwt_auth.py +│ ├── managers.py +│ ├── middleware.py # CurrentRoleMiddleware +│ └── permissions.py # RBAC/ABAC 权限 +│ +├── commission/ # 分佣引擎 +├── payment/ # 支付网关 +├── order/ # 订单模板与订单 +├── minecraft/ # MC 插件扩展 +├── management/ # Django management 命令 +└── migrations/ # Django 数据迁移（gvsdsdk 自身表的） ``` -每个文件只有 5-25 行代码，纯粹是 `from gvsds.apps.msync.X import Y` 的重新导出。 +**转发模块**（`msync.registry` / `msync.ogm` / `msync.transaction`）每个文件仅 15-17 行，是 `from gvsds.apps.msync.X import Y` 的纯转发；`msync.auth` 中 `AuthenticateService` 等 4 个函数通过 `msync/__init__.py` 的 `__getattr__` 转发，无独立文件。**其他模块**都是完整业务实现。 ## 4. 核心 API（PascalCase） -### 4.1 认证 (gvsdsdk.auth) +### 4.1 MSYNC 认证 (gvsdsdk.msync.auth) + +> 下表前 7 项为**自有实现**（子服务器可用，无 Django 依赖）；后 4 项为**转发**自 `gvsds.apps.msync.auth`（仅主服务器可用）。 | 函数 / 类 | 描述 | |---|---| @@ -302,7 +344,7 @@ dtx = TransactionManager.Create( └──────────────────┘ └──────────────────┘ ``` -`gvsdsdk` 与 `gvsds.apps.msync` 中的类是**完全同一个对象**——`from gvsdsdk import ServiceRegistry` 与 `from gvsds.apps.msync.registry import ServiceRegistry` 拿到的是同一个类。 +**转发模块**的类在 `gvsdsdk` 与 `gvsds.apps.msync` 中是**完全同一个对象**——例如 `from gvsdsdk import ServiceRegistry` 与 `from gvsds.apps.msync.registry import ServiceRegistry` 拿到的是同一个类。**自有实现**模块（`msync.auth` / `msync.client` / `msync.local_tx`）的类不依赖主服务器，在子服务器中是独立代码。 ## 8. 与项目原生层的集成 @@ -353,8 +395,8 @@ print('SDK 薄封装校验通过') |---|---| | **gvsdsdk** | 1.0.0 | | **协议版本** | v1.0 (PascalCase 严格模式) | -| **Python** | >= 3.8 | -| **兼容 gvsds** | >= 1.0 | +| **Python** | >= 3.11 | +| **兼容 GVSDS** | >= 1.0 | | **兼容 ATestCServer** | >= 1.0 | ## 11. 错误码速查 @@ -373,4 +415,4 @@ print('SDK 薄封装校验通过') - **SDK 仓库**：`gvsdsdk/`（薄封装） - **子服务器示例**：`ATestCServer/msync_client/` -修改原生层时，**SDK 无需改动**——所有类/函数会通过 `from … import …` 自动反映最新行为。 +修改原生层时，**转发类/函数无需改动 SDK**——它们通过 `from … import …` 直接引用 `gvsds.apps.msync` 原生对象，自动反映最新行为；**自有实现**模块（`msync.auth` 自有部分 / `msync.client` / `msync.local_tx`）为独立代码，需同步维护。