From 222fae6fbee4c61838ade448337c8e74d7b8ccba Mon Sep 17 00:00:00 2001 From: TermiNexus Date: Fri, 7 Aug 2026 21:14:09 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=85=A8=E9=9D=A2=E6=9B=B4=E6=96=B0=20?= =?UTF-8?q?SAAS=20=E6=9E=B6=E6=9E=84=E6=96=87=E6=A1=A3=EF=BC=8C=E5=8F=8D?= =?UTF-8?q?=E6=98=A0=E6=9C=8D=E5=8A=A1=E5=B1=82=E5=8C=96=20P0/P1=20?= =?UTF-8?q?=E5=AE=8C=E6=88=90=E4=B8=8E=20stats=20=E5=8F=8C=E8=BD=A8?= =?UTF-8?q?=E6=8A=80=E6=9C=AF=E5=80=BA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 6 +++--- SAAS_ARCHITECTURE.md | 18 ++++++++++-------- docs/stats_engine.md | 3 ++- gvsdsdk/README.md | 10 +++++----- 4 files changed, 20 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index a93f774d..6267396a 100644 --- a/README.md +++ b/README.md @@ -91,13 +91,13 @@ d:\SMANAGE\ │ ├── payment/ # 支付 │ ├── commission/ # 分佣 │ └── stats/ # 统计 -├── gvsdsdk/ # 分布式 SDK（薄封装 + 协议契约） -│ ├── auth/ # 认证（IsAdmin/IsSuperAdmin/IsTenantAdmin） +├── gvsdsdk/ # 分布式 SDK / 通用 SAAS 服务层 +│ ├── auth/ # 认证与权限（RoleManager/AuthManager/AdminUserManager 等 17 个 Manager） │ ├── msync/ # 服务注册/发现 │ ├── commission/ # 分佣引擎 │ ├── payment/ # 支付网关 │ ├── order/ # 订单 -│ ├── minecraft/ # MC 业务 +│ ├── stats/ # 统计引擎 │ └── management/ # 管理工具 ├── ATestCServer/ # 子服务器示例（通过 SDK 接入主服务） ├── TempLate/ # 前端模板与静态资源 diff --git a/SAAS_ARCHITECTURE.md b/SAAS_ARCHITECTURE.md index b2a83ea3..44ba2124 100644 --- a/SAAS_ARCHITECTURE.md +++ b/SAAS_ARCHITECTURE.md @@ -55,12 +55,12 @@ - 7 库分库路由：`Users / GerpCore / Plans / Tasks / T4PC / Document / Minecraft` - 6 个自定义中间件：IP 过滤、域名注入、当前角色注入、服务认证、攻击检测、错误日志 -### 3.2 `gvsdsdk` — 分布式 SDK +### 3.2 `gvsdsdk` — 分布式 SDK / 通用 SAAS 服务层 -- **薄封装层**：1:1 包装 `gvsds.apps.msync` 原生层，无运行时开销 -- **惰性加载（PEP 562）**：90+ 符号按需 import +- **服务层**：从薄封装演进为**通用 SAAS 服务层**——`RoleManager / AuthManager / AdminUserManager / TenantManager / CompanyManager / DepartmentManager / MessageManager / MenuManager / WorkOrderManager / InventoryManager / AssetManager / AuditManager / OrderManager / StatsManager / UserService` 等，gvsds 视图层通过它们访问数据（裸 ORM 已基本消除） +- **惰性加载（PEP 562）**：130+ 符号按需 import - **双类导出**：自有实现（无 Django 依赖，子服务器可用）+ 服务端转发（依赖 Django ORM） -- **三大引擎**：`CommissionEngine`（分佣）、`PaymentManager`（支付）、`TransactionManager`（分布式事务） +- **引擎**：`CommissionEngine`（分佣）、`PaymentManager`（支付）、`OrderManager`（订单状态机）、`StatsManager`（统计）、`TransactionManager`（分布式事务） ### 3.3 主从通信机制 @@ -207,18 +207,19 @@ HTTP Request - ✅ MSYNC 分布式通信（注册/发现/OGM/Saga 事务） - ✅ 文件分片上传 + 资产管理 - ✅ 操作审计日志 + 攻击检测 +- ✅ **服务层化迁移（P0/P1 全部完成）**：role_scope 数据权限底座、form_service 角色/用户链路、菜单/工单/消息/物品/背包/文档/文件资产等视图层裸 ORM 全部委托 gvsdsdk（详见项目记忆「服务层化迁移进度」） ### 6.2 已知技术债 | 优先级 | 问题 | 影响 | |---|---|---| -| 高 | Role/Permission 模型在 gvsds 与 gvsdsdk 双份定义 | 字段漂移风险 | +| 高 | Role/Permission 模型在 gvsds 与 gvsdsdk 双份定义 | 字段漂移风险（服务层化已缓解视图层裸访问，模型层残留） | | 高 | 部分表（User/Dept/Workgroup/Shop）无 TenantUUID | 跨租户查询需 JOIN，删除租户困难 | | 中 | ABAC 实现本质是 RBAC（字符串集合） | 名实不符，扩展受限 | | 中 | 数据权限硬编码 `if table_name == 'X'` | 违反开闭原则 | | 中 | 缺乏软删除机制 | 误删不可恢复 | +| 中 | stats 双轨：`StatEngine`（gvsds/apps/stats/manager.py，22 方法）与 gvsdsdk `StatsManager` 并存 | 需统一收敛 | | 低 | UUID 主键无序导致索引膨胀 | 大数据量写入性能下降 | -| 低 | 根 README.md 仍为 Flask 时代文档 | 新人易误读 | --- @@ -226,10 +227,11 @@ HTTP Request ### 7.1 短期（1-3 个月） -1. **统一 Role/Permission 模型**：让 gerp 直接复用 gvsdsdk 的模型定义，消除双份漂移 +1. ~~统一 Role/Permission 模型~~：✅ 服务层化已让视图层统一经 gvsdsdk Manager 访问（模型层双份仍待收敛） 2. **补全 TenantUUID 字段**：所有租户语义表直接打 `TenantUUID`，简化跨租户查询与租户删除 3. **数据权限策略化**：用策略模式替代 `if table_name == 'X'`，每个模型注册自己的 `ScopeFilter` -4. **更新根 README.md**：反映当前 Django 架构 +4. ~~更新根 README.md~~：✅ 已反映当前 Django 架构 +5. **统一 stats 双轨实现**：`StatEngine` 方法收敛到 gvsdsdk `StatsManager` ### 7.2 中期（3-6 个月） diff --git a/docs/stats_engine.md b/docs/stats_engine.md index 3cf6442f..ef58a7f4 100644 --- a/docs/stats_engine.md +++ b/docs/stats_engine.md @@ -380,4 +380,5 @@ engine.Decrement( |------|------| | `settings.py` | 新增 `'gvsds.apps.stats'` 到 `INSTALLED_APPS` | | `db_router.py` | 新增 `'stats': 'default'` 到 `app_db_map` | -| `urls.py` | 新增 `path('api/stats/', include('gvsds.apps.stats.urls'))` | \ No newline at end of file +| `urls.py` | 新增 `path('api/stats/', include('gvsds.apps.stats.urls'))` | +| `gvsds/apps/stats/engine.py` | **已删除（2026-08-07）**：8 个模块级函数并入 gvsdsdk `StatsManager`；`StatEngine`（gvsds/apps/stats/manager.py）与 Celery 任务底层统一走 `gvsdsdk.stats.manager.StatsManager`，签名 1:1 不变 | \ No newline at end of file diff --git a/gvsdsdk/README.md b/gvsdsdk/README.md index 510d3b9a..c43f7bf1 100644 --- a/gvsdsdk/README.md +++ b/gvsdsdk/README.md @@ -5,7 +5,7 @@ > **混合实现策略**： > - **自有实现**（无 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 插件） +> - **完整业务模块**：`auth`（用户认证/权限）、`commission`（分佣引擎）、`payment`（支付网关）、`order`（订单）、`stats`（统计引擎） > > **版本兼容**：主从两端必须使用同一 SDK 版本（当前 `1.0.0`）。 @@ -17,13 +17,13 @@ **子服务器可独立使用**（不依赖 GVSDS 主服务器代码）： -- **用户认证与权限**（`gvsdsdk.auth`）：密码哈希、AES 加密、文件/字节摘要、CurrentRoleMiddleware、RBAC/ABAC 权限、RoleManager / ShopManager / PositionManager +- **用户认证与权限**（`gvsdsdk.auth`）：密码哈希、AES 加密、文件/字节摘要、CurrentRoleMiddleware、RBAC/ABAC 权限、RoleManager / ShopManager / PositionManager / AuthManager / AdminUserManager / TenantManager / CompanyManager / DepartmentManager / MessageManager / MenuManager / WorkOrderManager / InventoryManager / AssetManager / AuditManager / UserService - **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） +- **数据模型**（`gvsdsdk.models`）：User / Role / Permission / UserRole / Position / Menu / WorkOrder / AuditLog / ItemReference / Backpack / FileAsset 等 SAAS 核心表（managed=False） - **ORM 查询层**（`gvsdsdk.fluent`）：FluentQuery 链式查询 - **CRUD 引擎**（`gvsdsdk.form_service`）：FormService 通用增改删查 API -- **业务模块**：`commission`（分佣）/ `payment`（支付）/ `order`（订单）/ `minecraft`（MC 插件） +- **业务模块**：`commission`（分佣）/ `payment`（支付）/ `order`（订单）/ `stats`（统计） **主服务器**（`gvsds`）：通过 `gvsdsdk` 与子服务器共享同一份 API 契约，同时直接 import `gvsds.apps.msync` 内部模块。 @@ -100,7 +100,7 @@ gvsdsdk/ ├── commission/ # 分佣引擎 ├── payment/ # 支付网关 ├── order/ # 订单模板与订单 -├── minecraft/ # MC 插件扩展 +├── stats/ # 统计引擎 ├── management/ # Django management 命令 └── migrations/ # Django 数据迁移（gvsdsdk 自身表的） ```