# 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](./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](./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 使用（子服务器）

```python
# 子服务器通过 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](./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_ARCHITECTURE.md) — 完整 SAAS 架构与数据模型
- [gvsdsdk/INSTALL.md](./gvsdsdk/INSTALL.md) — SDK 安装与使用
- [gvsdsdk/API.md](./gvsdsdk/API.md) — SDK API 参考
- [BENAME.MD](./BENAME.MD) — 重命名与版本变更日志

---

## 十一、许可证与联系

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