# SAAS 架构概览

> 面向技术决策会议的架构说明文档。本文档聚焦 SAAS 多租户-公司-部门-用户-角色架构设计、当前实现状态与未来发展方向。

---

## 1. 项目定位

**GVS-DSDK** 是一套面向中小企业（SMB）的 SAAS 化企业管理平台，包含：

- **多租户 SAAS 框架**：支持租户入驻、审核、隔离
- **企业资源管理（GERP）**：组织、角色、权限、菜单、工单、资产、文档
- **三大业务引擎**：分佣引擎、支付网关、统计引擎
- **分布式通信底座（MSYNC）**：服务注册、发现、分布式事务

## 2. 技术栈

| 层 | 技术 |
|---|---|
| 后端框架 | Django 4.2+ / DRF / SimpleJWT |
| 异步任务 | Celery + Redis（可降级同步） |
| 实时通信 | Socket.IO（python-socketio） |
| 数据库 | MySQL 5.7+（7 库分库路由） |
| 缓存 | Redis（可降级 locmem） |
| 安全 | bcrypt / AES-256-GCM / JWT |
| 前端 | 原生 HTML/JS + 自研 NeoUI/GERPUI 组件 |
| 部署 | Gunicorn + Nginx 反向代理 |

## 3. 双包架构

```
┌─────────────────────────────────────────────────────┐
│              d:\SMANAGE（项目根）                    │
│                                                     │
│  ┌──────────────────────┐  ┌──────────────────────┐│
│  │   gvsds              │  │   gvsdsdk            ││
│  │   主服务器（业务层）  │◄─┤   分布式 SDK（薄封装）││
│  │   - Django 项目      │  │   - 协议契约层       ││
│  │   - 14 个业务 App    │  │   - 惰性加载         ││
│  │   - 完整业务实现     │  │   - PascalCase 协议  ││
│  └──────────────────────┘  └──────────────────────┘│
│              ▲                              ▲       │
│              │                              │       │
│  ┌──────────────────────┐  ┌──────────────────────┐│
│  │  ATestCServer        │  │  TempLate/          ││
│  │  子服务器示例        │  │  前端模板资源       ││
│  │  通过 SDK 接入       │  │  GERP/AKS/MSOC 等   ││
│  └──────────────────────┘  └──────────────────────┘│
└─────────────────────────────────────────────────────┘
```

### 3.1 `gvsds` — 主服务器

- 14 个 Django App：`core / gerp / ugm / crb / invite / ccgo / sve / t4 / mc / doc / api / msync / payment / commission / stats`
- 7 库分库路由：`Users / GerpCore / Plans / Tasks / T4PC / Document / Minecraft`
- 6 个自定义中间件：IP 过滤、域名注入、当前角色注入、服务认证、攻击检测、错误日志

### 3.2 `gvsdsdk` — 分布式 SDK / 通用 SAAS 服务层

- **服务层**：从薄封装演进为**通用 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）
- **msync 原生实现（1.1.0）**：通信底座已从 `gvsds.apps.msync` 整体迁入 `gvsdsdk/msync`（models/registry/ogm/transaction/auth + Django 集成层），可脱离 gvsds 独立部署（屏蔽 gvsds 后全模块独立导入验证通过）
- **引擎**：`CommissionEngine`（分佣）、`PaymentManager`（支付）、`OrderManager`（订单状态机）、`StatsManager`（统计）、`TransactionManager`（分布式事务）

### 3.3 主从通信机制

- **版本校验**：启动时 `gvsdsdk.check_min_version('1.1.0')`，主从必须一致（版本兼容矩阵见 `gvsdsdk/VERSION_MATRIX.md`）
- **Socket.IO 协议**：20+ 事件，全程 PascalCase 字段
- **支付网关自动注册**：`gvsdsdk/apps.py` 的 `ready()` 钩子

---

## 4. SAAS 多租户架构（核心）

### 4.1 组织四层架构

```
┌──────────────────────────────────────────────────────────┐
│ 第 4 层：鉴权规则层（运行时）                              │
│   操作权限 (RBAC)         数据权限 (ABAC + RoleScope)     │
├──────────────────────────────────────────────────────────┤
│ 第 3 层：角色权限载体层                                   │
│   Role + UserRole + RolePermission                       │
├──────────────────────────────────────────────────────────┤
│ 第 2 层：岗位模板层（初始化快照）                          │
│   PositionTemplate + PositionTemplatePermission          │
│   CopyToRole 一次性复制，后续独立演进                     │
├──────────────────────────────────────────────────────────┤
│ 第 1 层：组织人事层                                       │
│   Tenant → Company → Department                          │
│   UserDept（员工-部门多对多）                             │
│   Position（人事职务标签，与权限解耦）                     │
│   Workgroup（跨部门工作组）  Shop（商铺，归公司）         │
└──────────────────────────────────────────────────────────┘
```

### 4.2 数据模型核心表（共 17 张 SAAS 表）

| 分类 | 表名 | 职责 |
|---|---|---|
| **租户** | `Tenant` | 多租户根，含审核状态/到期时间 |
| **组织** | `Company` / `CompanyInfo` / `Department` / `Workgroup` | 公司树/工商信息/部门树/跨部门组 |
| **用户** | `User` / `UserAvatar` / `User2FA` / `UserPending2FA` / `UserLoginLog` / `AccountActivation` / `Password` / `UserIDCard` | 用户身份与认证 |
| **角色权限** | `Role` / `Permission` / `UserRole` / `RolePermission` | RBAC 核心 |
| **岗位模板** | `PositionTemplate` / `PositionTemplatePermission` | 权限初始化快照 |
| **人事标签** | `Position` | 职务标签（与权限解耦） |
| **商铺** | `Shop` / `RoleShop` | 多商铺体系 |
| **ABAC** | `UserABAC` | 属性访问控制（补充） |
| **审计** | `AuditLog` / `AbnormalUserLog` | 操作审计 + 攻击溯源 |

### 4.3 关键设计决策

#### (1) Position 与权限**完全解耦**
- 人事职务标签（`Position`）仅用于人事管理，**不直接绑定权限**
- 调岗/升职只修改 `Position`，权限只通过 `UserRole → RolePermission → Permission` 走
- 规避了业界常见错误：把职务直接绑权限导致调岗时权限树重算

#### (2) PositionTemplate 的"快照复制"机制
- 模板 → 角色 = **一次性复制**（`CopyToRole`），复制后两者无运行时绑定
- 模板调整只影响**之后新建**的角色，已有角色不被动变更
- 避免了"模板改一个字段，全员权限突然变了"的运维灾难

#### (3) UserRole 实体化 + 关联表（部门/工作组多对多）
`UserRole` 是"用户↔角色"的**实体化中间表**（联合唯一：同一用户+同一角色仅一行）：
- **权限分配**：User ↔ Role 多对多（`UserRoleUUID` 作为全局唯一关联实体）
- **组织归属**：不再放 UserRole 上，改走关联表（多对多）：
  - `UserRoleDepartment`：(用户-角色对) ↔ 部门（`UserRoleUUID + DeptUUID`）
  - `UserRoleWorkgroup`：(用户-角色对) ↔ 工作组（`UserRoleUUID + WorkgroupUUID`）
- **成员类型**：`RoleType`（0=成员 / 1=负责人/组长）冗余在关联表，**按部门/工作组区分**

**优势**：一个用户-角色对可同时挂多个部门/工作组，且在不同部门可分别标注成员/负责人
**注意**：UserRole 上的遗留字段（`DeptUUID / WorkgroupUUID / RoleType`）已废弃删除（见 gvsdsdk 0002 迁移），
全部语义以关联表为准。

#### (4) 角色作用域四档数据权限（`RoleScope`）

| 类型 | 判定条件 | 可见范围 |
|---|---|---|
| `admin` | IsSuperuser/IsStaff 或 `admin:super` 权限 | 全公司 |
| `dept_manager` | `UserRoleDepartment.RoleType=1`（按当前公司过滤，可多部门） | 本部门成员 |
| `workgroup_lead` | `UserRoleWorkgroup.RoleType=1`（按当前公司过滤，可多工作组） | 本工作组成员 |
| `member` | 其他 | 仅自己 |

### 4.4 运行时鉴权流程

```
HTTP Request
    │
    ├─► JWTAuthentication → User 实例
    ├─► CurrentRoleMiddleware → request.current_role (Role)
    ├─► DomainMiddleware → request.current_company_uuid
    │
    ├──► 操作权限校验：PermissionVerifier(permission, attrs, user, request)
    │      ├─ ABAC：UserABAC.HierarchicalPermissionIdentifiers ∋ attr?
    │      └─ RBAC：RolePermission(角色)→Permission.PermCode ∋ attr?
    │      （含请求级缓存，消除 N+1）
    │
    └──► 数据权限校验：RoleScope.GetUserScope(request)
           └─ ApplyScopeToQueryset(qs, scope, table_name)
                  按 admin/dept_manager/workgroup_lead/member 差异化过滤
```

### 4.5 主键设计

- 全程使用 `BINARY(16)` UUID 主键
- 优势：分布式生成、无 ID 冲突、不暴露顺序信息
- 代价：InnoDB 聚簇索引无序，写入有页分裂开销（可考虑改 UUIDv7）

---

## 5. 三大业务引擎

### 5.1 分佣引擎（`CommissionEngine`）

| 策略 | Type | 说明 |
|---|---|---|
| `PercentageStrategy` | `percentage` | 比例分账，支持保底/封顶 |
| `FixedStrategy` | `fixed` | 固定金额 |
| `TieredStrategy` | `tiered` | 阶梯分账 |
| `RemainderStrategy` | `remainder` | 剩余归平台 |
| `WithdrawalFeeStrategy` | `withdrawal_fee` | 提现手续费 |

支持：规则配置 → 触发分佣 → 预结算 → 邀请链分佣 → 查询统计

### 5.2 支付网关（`PaymentManager`）

| 渠道 | 支付方式 | 转账 |
|---|---|---|
| 微信支付 | JSAPI/Native/H5/小程序 | 支持 |
| 支付宝 | APP/H5/Native | 支持 |
| 银行卡 | APP/H5/Native | 仅 bank 类型 |

支持：网关配置 → 支付/查询/退款/转账 → 回调处理

### 5.3 统计引擎（`stats`）

- Celery 定时任务：每日重置 / 每月重置 / 排行榜构建 / 过期清理
- 按角色差异化仪表盘

---

## 6. 当前实现状态

### 6.1 已完成

- ✅ 14 个业务 App 完整实现
- ✅ 多租户入驻审核工作流
- ✅ RBAC + ABAC 混合鉴权
- ✅ 分佣引擎 + 支付网关 + 统计引擎
- ✅ MSYNC 分布式通信（注册/发现/OGM/Saga 事务）
- ✅ 文件分片上传 + 资产管理
- ✅ 操作审计日志 + 攻击检测
- ✅ **服务层化迁移（P0/P1/P2 全部完成，2026-08-07）**：role_scope 数据权限底座、form_service 角色/用户链路、菜单/工单/消息/物品/背包/文档/文件资产、25 个 ViewSet queryset、form_service 通用增删改落库、doc 视图/统计任务/审计清理等全部收敛到 gvsdsdk（详见项目记忆「服务层化迁移进度」）；invite/sve/t4/ccgo 已定性为业务定制留在 gvsds（与 CRB/MC 同边界）

### 6.2 已知技术债

| 优先级 | 问题 | 影响 |
|---|---|---|
| ~~高~~ | ~~Role/Permission 模型双份定义~~：✅ 已收敛（2026-08-10）——gvsds 各 app 模型统一 `from gvsdsdk.models import`，SDK 为唯一模型源 | — |
| 高 | 部分表（User/Dept/Workgroup/Shop）无 TenantUUID | 跨租户查询需 JOIN，删除租户困难（待迁移脚本补列回填） |
| 中 | ABAC 实现本质是 RBAC（字符串集合） | 已文档更正为"属性标识符补充层"，真 ABAC 重构列入中期规划 |
| 中 | 数据权限硬编码 `if table_name == 'X'` | 违反开闭原则 |
| 中 | 缺乏软删除机制 | 误删不可恢复 |
| ~~中~~ | ~~stats 双轨~~：✅ 已统一（2026-08-07）——`StatEngine`（gvsds/apps/stats/manager.py）已删除，编排方法全部并入 gvsdsdk `StatsManager`，视图/Celery 任务统一走 SDK | — |
| 低 | UUID 主键无序导致索引膨胀 | 大数据量写入性能下降 |

---

## 7. 未来发展方向（会议讨论建议项）

### 7.1 短期（1-3 个月）

1. ~~统一 Role/Permission 模型~~：✅ 已收敛（2026-08-10）——视图层统一经 gvsdsdk Manager 访问，模型层 gvsds 统一从 gvsdsdk import，双份定义消除
2. **补全 TenantUUID 字段**：所有租户语义表直接打 `TenantUUID`，简化跨租户查询与租户删除
3. **数据权限策略化**：用策略模式替代 `if table_name == 'X'`，每个模型注册自己的 `ScopeFilter`
4. ~~更新根 README.md~~：✅ 已反映当前 Django 架构
5. ~~统一 stats 双轨实现~~：✅ 已收敛——`StatEngine` 删除，`StatsManager` 补齐编排方法（DefineMetric/GenerateDailyRanking/QueryRanking/RunScheduledResets/BuildRankings 等），视图与 Celery 任务统一经 gvsdsdk 访问

### 7.2 中期（3-6 个月）

1. **重构 ABAC 为真正的属性访问控制**：支持时间/IP/资源所有者/字段级权限
2. **引入软删除机制**：`DeletedAt` + `DeletedByUUID`，配合审计日志实现数据恢复
3. **支付网关扩展**：增加 PayPal/Stripe 适配（出海场景）
4. **租户配额管理**：用户数/数据量/API 调用次数配额

### 7.3 长期（6+ 个月）

1. **拆分协议层**：把 gvsdsdk 拆为 `gvsds-protocol`（纯协议）+ `gvsds-business`（业务能力），主从各自依赖
2. **改用 UUIDv7 或 Snowflake**：解决主键无序问题
3. **多区域部署**：基于 MSYNC 实现跨地域多活
4. **微服务化拆分**：gerp/payment/commission/stats 可独立部署

---

## 8. 关键架构原则

1. **PascalCase 全链路一致**：从数据库字段 → Python 类 → Socket.IO 事件 → 前端，无转换层
2. **优雅降级**：Redis/Celery/网关依赖缺失时自动降级，开发环境零依赖启动
3. **配置外置**：`app.ini` + `secrets.ini` + 环境变量三层配置，支持 12-factor 部署
4. **薄封装 SDK**：协议契约层与业务实现层分离，主从可独立演进
5. **Position 与权限解耦**：人事标签不绑权限，避免调岗重算

---

## 9. 联系与维护

- **主仓库**：`d:\SMANAGE`
- **SDK 包**：`gvsdsdk/`（pyproject.toml v1.0.0）
- **子服务器示例**：`ATestCServer/`
- **设计文档**：`docs/commission_engine.md` / `docs/payment_gateway.md` / `docs/stats_engine.md`

---

**本架构文档用于技术决策会议参考，详细 API 与字段定义见 [gvsdsdk/API.md](file:///d:/SMANAGE/gvsdsdk/API.md) 与 [gvsdsdk/README.md](file:///d:/SMANAGE/gvsdsdk/README.md)。**