GVSDS/SMANAGE
0
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Updated the GVSDSDK README 2

Browse Source
This commit is contained in:
TermiNexus committed 2026-07-30 00:49:33 +08:00
1 parent 66c87cb0a8
commit ec4f7df84e
1 file changed
+75 -33
Download Patch File Download Diff File Expand all files Collapse all files
gvsdsdk/README.md
+75 -33
View File
@@ -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`）为独立代码，需同步维护。