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

Updated the README

Browse Source
This commit is contained in:
TermiNexus committed 2026-07-30 00:16:05 +08:00
1 parent fd591a0c94
commit ba540654fc
1 file changed
+299 -250
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+299 -250
View File
@@ -1,250 +1,299 @@
# GVSDS 项目团队协作向导
## 项目简介
这是一个基于 Flask 的 Web 应用框架，采用模块化设计，支持多服务器架构和文件系统路由。项目主要用于构建 API 服务和 Web 应用，具有高性能、安全性和可扩展性的特点。
## 技术栈
- **核心框架**：Flask
- **并发处理**：Gevent
- **数据库**：SQLAlchemy
- **实时通信**：Flask-SocketIO
- **安全**：Flask-Bcrypt, Flask-CORS
- **限流**：Flask-Limiter
- **SSL**：内置支持
## 项目结构
```
├── Main.py # 主入口文件
├── TempLateModule/ # 功能模块
│ ├── FileSystemRoute.py # 文件系统路由管理
│ ├── Main/ # 主模块
│ ├── UGM/ # 用户管理模块
│ ├── GErp/ # 企业资源规划模块
│ └── ... # 其他功能模块
├── TempLateAPI/ # API 定义文件
├── Utils/ # 工具类和配置
│ ├── Config.py # 配置文件
│ ├── Lib.py # 通用库
│ └── Models.py # 数据模型
├── SSL/ # SSL 证书
├── logs/ # 日志文件
└── README.md # 本文档
```
## 开发环境搭建
### 1. 前置要求
- Python 3.7+
- MySQL 5.7+
- Git
### 2. 安装依赖
```powershell
# 克隆仓库
git clone <仓库地址>
cd SMANAGE
# 创建虚拟环境
python -m venv venv
# 激活虚拟环境
venv\Scripts\activate
# 安装依赖
pip install -r requirements.txt
```
### 3. 配置文件
- 确保 `Utils/Config.py` 中的配置正确
- 准备 SSL 证书并放置在 `SSL/` 目录
### 4. 启动开发服务器
```powershell
# 启动开发服务器
python Main.py
```
## 如何添加新 API
### 1. 创建 API 文件
在 `TempLateAPI/` 目录下创建 `.api` 文件，文件路径将自动映射为路由。
### 2. API 文件结构
```python
# __metadata__ 定义路由属性
__metadata__ = {
"methods": ["POST"], # 支持的 HTTP 方法
"route": None, # 自定义路由（可选）
"blueprint": "default", # 蓝图名称
"permission": 0, # 权限级别
"form": [], # 表单参数
"args": [], # URL 参数
"json": [], # JSON 参数
"headers": [], # 头部参数
"cookies": [] # Cookie 参数
}
# 处理请求的函数
def HandleRequest(_CleanedData):
# _CleanedData 包含验证后的参数
# 业务逻辑处理
return {"code": 200, "msg": "success"}
```
### 3. 参数验证
参数验证支持多种类型：
- `str`：字符串
- `int`：整数
- `float`：浮点数
- `dict`：字典
- `list`：列表
- `UUID`：UUID 格式
- `MUUID`：多个 UUID
- `bool`：布尔值
- `json`：JSON 格式
- `timestamp`：时间戳
- `timestampstr`：时间字符串
### 4. 示例 API
```python
__metadata__ = {
"methods": ["POST"],
"form": [
{"Name": "username", "Type": "str", "Required": True, "MinLen": 3, "MaxLen": 20},
{"Name": "password", "Type": "str", "Required": True, "MinLen": 6}
]
}
def HandleRequest(_CleanedData):
username = _CleanedData["form"]["username"]
password = _CleanedData["form"]["password"]
# 处理登录逻辑
return {"code": 200, "msg": "登录成功", "data": {"username": username}}
```
## 代码规范
### 1. 命名规范
- **文件命名**：小写字母，下划线分隔
- **类命名**：帕斯卡命名法（首字母大写）
- **函数命名**：小写字母，下划线分隔
- **变量命名**：小写字母，下划线分隔
- **常量命名**：全大写字母，下划线分隔
### 2. 代码风格
- 使用 4 个空格缩进
- 每行不超过 100 个字符
- 函数和类之间空两行
- 方法之间空一行
- 适当添加注释，解释复杂逻辑
### 3. 提交规范
```
<类型>: <描述>
<详细说明>
<关联 Issue>
```
类型包括：
- `feat`：新功能
- `fix`：修复 bug
- `docs`：文档更新
- `style`：代码风格调整
- `refactor`：代码重构
- `test`：测试代码
- `chore`：构建或依赖更新
## 部署流程
### 1. 测试环境
- 确保代码通过所有测试
- 检查日志输出是否正常
- 验证 API 功能
### 2. 生产环境
1. **准备服务器**：配置 Linux 服务器，安装必要依赖
2. **部署代码**：使用 Git 拉取最新代码
3. **配置环境**：设置环境变量，配置 SSL 证书
4. **启动服务**：使用后台进程启动服务器
5. **监控运行**：检查日志，确保服务正常运行
## 团队协作规范
### 1. 分支管理
- `main`：主分支，仅用于发布
- `develop`：开发分支，集成所有功能
- `feature/xxx`：功能分支，开发新功能
- `bugfix/xxx`：修复分支，修复 bug
### 2. 代码审查
- 所有代码必须经过审查才能合并到主分支
- 审查重点：功能正确性、代码质量、安全性
- 使用 Pull Request 进行代码审查
### 3. 问题管理
- 使用 Issue 跟踪 bug 和功能请求
- 每个 Issue 应该有清晰的描述和重现步骤
- 解决 Issue 后关闭并关联相关提交
### 4. 文档更新
- 代码变更时同步更新文档
- 新功能必须添加相应的文档
- 定期审查文档的准确性
## 常见问题与解决方案
### 1. API 注册失败
**原因**：API 文件格式错误或缺少必要的函数
**解决**：检查 `.api` 文件是否包含 `__metadata__` 和 `HandleRequest` 函数
### 2. 参数验证失败
**原因**：请求参数格式不正确
**解决**：检查请求参数是否符合 API 定义的类型和规则
### 3. 权限不足
**原因**：用户权限级别低于 API 要求
**解决**：检查 API 的 `permission` 设置和用户权限
### 4. 服务器启动失败
**原因**：端口被占用、SSL 证书错误或配置问题
**解决**：检查端口占用情况，验证 SSL 证书，检查配置文件
## 联系信息
- **项目负责人**：<负责人姓名>
- **技术支持**：<支持邮箱>
- **团队沟通**：<沟通工具>
---
**注意**：本文档会根据项目发展持续更新，请定期查看最新版本。
# 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（薄封装 + 协议契约）
│ ├── auth/ # 认证（IsAdmin/IsSuperAdmin/IsTenantAdmin）
│ ├── msync/ # 服务注册/发现
│ ├── commission/ # 分佣引擎
│ ├── payment/ # 支付网关
│ ├── order/ # 订单
│ ├── minecraft/ # MC 业务
│ └── 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 / 企业微信群