GVSDS · 多租户 SAAS 管理平台

GVS Distributed System — 基于 Django + gevent 的企业级 SAAS 框架，配套分布式 SDK 与多模板前端。

---

⚠️ 重要声明 · IMPORTANT

本仓库为 GVSDS 平台生产环境核心代码，不允许在本地或非授权环境中部署运行。

• 🚫 禁止本地部署：本仓库代码仅供已授权的运维人员通过内部部署系统在受控环境中运行
• 🚫 禁止私自 clone 后跑通：任何 python Main.py / gunicorn / python manage.py runserver 的本地启动行为均属违规
• 🚫 禁止公开演示/截图/录屏：核心业务逻辑、特权流程、数据库结构、API 设计不得外传
• ✅ 允许的用途：阅读源码学习架构、参与授权下的代码审查、提交合规的 PR
• ✅ 如需调试：请联系平台运维团队申请独立的测试沙盒环境

违规者将依据《服务协议》追究责任。

---

一、项目定位⚠️ 重要声明 · IMPORTANT

本仓库为 GVSDS 平台生产环境核心代码，不允许在本地或非授权环境中部署运行。

• 🚫 禁止本地部署：本仓库代码仅供已授权的运维人员通过内部部署系统在受控环境中运行
• 🚫 禁止私自 clone 后跑通：任何 python Main.py / gunicorn / python manage.py runserver 的本地启动行为均属违规
• 🚫 禁止公开演示/截图/录屏：核心业务逻辑、特权流程、数据库结构、API 设计不得外传
• ✅ 允许的用途：阅读源码学习架构、参与授权下的代码审查、提交合规的 PR
• ✅ 如需调试：请联系平台运维团队申请独立的测试沙盒环境

违规者将依据《GVSDS 平台使用协议》追究责任。

---

一、项目定位

GVSDS 是面向中小企业的多租户企业管理平台，核心能力：

• 多租户 SAAS 框架：租户入驻、审核、数据隔离（公司 / 部门 / 工作组 / 商铺 四级）
• 企业资源管理（GERP）：组织、角色、权限、菜单、工单、文件资产、文档
• 三大业务引擎：分佣引擎（Commission）、支付网关（Payment）、分布式事务（Transaction）
• 分布式通信底座（MSYNC）：服务注册 / 发现 / 跨服务调用
• 多模板前端：GERP / CCCRB / AKS / MSOC / librok 等多套站点
• 多域名部署：单一进程同时服务 gvsds.com / gvsds.org / gvsds.dev / gvsds.studio / yc8z.org / ycbz.org / librok.gvsds.com 等多个域名

详细架构说明参见 SAAS_ARCHITECTURE.md。

---

二、技术栈

层	技术
后端框架	Django 4.2+ / DRF / SimpleJWT
WSGI 服务器	gevent + pywsgi（单进程多协程）/ Gunicorn 兼容
异步任务	Celery + Redis（可降级同步执行）
实时通信	python-socketio
数据库	MySQL 5.7+（7 库分库路由）
缓存 / 锁	Redis（可降级 locmem）
安全	bcrypt / AES-256-GCM / JWT / 自研 IP 过滤 + 攻击检测
前端	原生 HTML / JS + 自研 NeoUI / GERPUI 组件 + Tailwind
反向代理	Nginx

---

三、目录结构

d:\SMANAGE\
├── Main.py                # WSGI 入口（gevent 启动 + 域名路由 + 中间件链）
├── manage.py              # Django 命令行
├── gvsds/                 # 主服务器（Django 项目）
│   ├── settings.py        # 全局配置
│   ├── urls.py            # 路由聚合
│   ├── auth.py            # CustomJWTAuthentication
│   ├── middleware.py      # 6 个自定义中间件
│   ├── db_router.py       # 分库路由器
│   └── apps/              # 14 个业务 App
│       ├── core/          # 用户/认证基础设施
│       ├── gerp/          # ERP 主模块（FormAPI / CheckAdmin / 角色权限）
│       ├── ugm/           # 用户管理
│       ├── crb/           # 货币钱包/企业
│       ├── invite/        # 邀请码
│       ├── ccgo/          # 协同办公
│       ├── sve/           # 工单
│       ├── t4/            # T4 计划
│       ├── mc/            # 我的世界
│       ├── doc/           # 文档
│       ├── api/           # API 网关
│       ├── msync/         # 分布式通信
│       ├── payment/       # 支付
│       ├── commission/    # 分佣
│       └── stats/         # 统计
├── gvsdsdk/               # 分布式 SDK / 通用 SAAS 服务层
│   ├── auth/              # 认证与权限（RoleManager/AuthManager/AdminUserManager 等 17 个 Manager）
│   ├── msync/             # 服务注册/发现
│   ├── commission/        # 分佣引擎
│   ├── payment/           # 支付网关
│   ├── order/             # 订单
│   ├── stats/             # 统计引擎
│   └── management/        # 管理工具
├── ATestCServer/          # 子服务器示例（通过 SDK 接入主服务）
├── TempLate/              # 前端模板与静态资源
│   ├── GERP/              # ERP 主前端（pages/ + assets/ + DbTableHelper）
│   ├── CCCRB/             # 货币钱包前端
│   ├── AKS/  MSOC/  ...   # 其他模板
│   ├── rok/lib/           # 静态资源库（librok.gvsds.com）
│   └── Errors/            # 错误页（404 / 反盗链）
├── SSL/                   # SSL 证书
├── nginx/                 # Nginx 配置
├── deploy/                # 部署脚本
├── logs/                  # 运行日志
├── secrets.ini            # 数据库/Redis 凭据（不入库）
├── gunicorn.conf.py       # Gunicorn 配置
└── app.ini                # 应用配置

---

四、核心架构

4.1 双包架构

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

4.2 SAAS 多租户四层架构

第 4 层  鉴权规则层       RBAC 操作权限 + ABAC 数据权限（RoleScope）
第 3 层  角色权限载体层   Role + UserRole + RolePermission
第 2 层  岗位模板层       PositionTemplate → CopyToRole（一次性快照）
第 1 层  组织人事层       Tenant → Company → Department / Workgroup
                          UserDept（员工-部门多对多）+ Position（标签）

4.3 权限模型（角色超级管理员标记）

特权级采用角色级标记而非用户级 IsSuperuser：

• admin:super（跨租户超级管理员，最高）
• admin:tenant（租户内管理员）
• 权限码查询走 RolePermission → Permission
• 详见 gvsdsdk/auth/admin_service.py

4.4 分库路由（7 库）

Users / GerpCore / Plans / Tasks / T4PC / Document / Minecraft，由 gvsds/db_router.py 路由。

---

五、多域名与静态站点

Main.py 内置域名路由：

域名	用途
gvsds.com / www.gvsds.com / api.gvsds.com	主站 + API
gvsds.dev / gvsds.studio	备用主域
gvsds.org	主域别名
yc8z.org / ycbz.org	镜像站
librok.gvsds.com	静态站点（TempLate/rok/lib/）

新增静态站点：在 Main.py 的 STATIC_SITES 字典中添加 host → Path 映射。

---

六、严禁本地部署

再次强调：本仓库为平台生产环境核心代码，不允许本地部署。

1. 禁止行为

• ❌ 任何个人或团队成员不得在本地（开发机、笔记本、虚拟机）clone 后启动 Main.py / gunicorn / python manage.py runserver
• ❌ 不得使用本地 MySQL / Redis 模拟生产环境"试跑"
• ❌ 不得在公网演示环境部署本仓库代码
• ❌ 不得将本仓库代码上传至 GitHub / GitLab / Gitee 等任何公开平台

2. 允许的运行方式

• ✅ 仅通过内部部署系统（deploy/ 目录脚本 + Ansible / SaltStack）部署到已审批的生产服务器
• ✅ 部署目标服务器需满足：
  • 内网 IP，不暴露公网
  • 防火墙白名单限定运维来源 IP
  • 与生产数据库主从同步
  • 启用审计日志（logs/ 实时收集）
• ✅ 沙盒调试需向运维团队申请独立的测试沙盒环境（与生产数据完全隔离）

3. 违规处理

• 首次违规：警告 + 撤销代码访问权限 7 天
• 二次违规：撤销代码访问权限 30 天 + 通报
• 三次违规：依据《GVSDS 平台使用协议》追究法律责任

4. 如何申请部署 / 调试

1. 通过企业微信联系 平台运维团队
2. 提交申请单（用途 / 环境 / 时段 / 审批人）
3. 审批通过后由运维团队协助完成

---

七、API 与 SDK

7.1 REST API

• 路由前缀：/API/<AppName>/<Action>/<Resource>
• 鉴权：JWT（HttpOnly Cookie）+ admin_verify=1 特权模式
• 核心 API：
  • /API/FormAPI/CheckAdmin — 权限查询
  • /API/FormAPI/Get/<Table> — 列表查询（带 company_scope / tenant_scope）
  • /API/FormAPI/Add/Modify/Delete/<Table> — 增改删

7.2 SDK 使用（子服务器）

# 子服务器通过 gvsdsdk 接入主服务
from gvsdsdk.auth.admin_service import IsAdmin, IsSuperAdmin
from gvsdsdk.commission.engine import CommissionEngine
from gvsdsdk.msync.client import MSyncClient

# 权限判断（统一走角色级 admin:super / admin:tenant 标记）
if IsSuperAdmin(request):
    # 跨租户超级管理员逻辑
    ...

# 注册到主服务
client = MSyncClient('sub-server-01', version='1.0.0')
client.register()

---

八、命名与代码规范

• 类名 / 模型字段：PascalCase（UserName, RoleUUID, CurrentRoleUUID）
• 函数 / 变量：snake_case（get_user_role, current_role_uuid）
• 常量：UPPER_SNAKE（WHITE_HOSTS, STATIC_SITES）
• 文件名：业务模块小写、Python 类用 PascalCase
• DB 字段：所有 UUID 字段以 UUID 后缀，类型 BINARY(16)
• 前端：Tailwind utility-first + 自研 GERPUI 组件
• 详见 SAAS_ARCHITECTURE.md

---

九、部署

9.1 目录约定

• deploy/ — 部署脚本
• nginx/ — 反向代理配置
• gunicorn.conf.py — Gunicorn worker / 超时 / 绑定
• SSL/ — 证书（生产用 Let's Encrypt / 商业证书）

9.2 启动顺序

1. MySQL / Redis
2. 启动 Main.py（或 Gunicorn）
3. Nginx 反向代理 127.0.0.1:<port> → HTTPS
4. 防火墙放行 80/443

9.3 日志

• logs/ — 应用日志
• 控制台：彩色输出（colorama）

---

十、相关文档

• SAAS_ARCHITECTURE.md — 完整 SAAS 架构与数据模型
• gvsdsdk/INSTALL.md — SDK 安装与使用
• gvsdsdk/API.md — SDK API 参考
• BENAME.MD — 重命名与版本变更日志

---

十一、许可证与联系

• 项目所有者：GVSDS Team
• 内部仓库，不对外开放
• 问题反馈：通过 Issue / 企业微信群