diff --git a/README.md b/README.md index ada7ea05..a93f774d 100644 --- a/README.md +++ b/README.md @@ -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 证书，检查配置文件 - -## 联系信息 - -- **项目负责人**：<负责人姓名> -- **技术支持**：<支持邮箱> -- **团队沟通**：<沟通工具> - ---- - -**注意**：本文档会根据项目发展持续更新，请定期查看最新版本。 \ No newline at end of file +# 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///` +- 鉴权：JWT（HttpOnly Cookie）+ `admin_verify=1` 特权模式 +- 核心 API： + - `/API/FormAPI/CheckAdmin` — 权限查询 + - `/API/FormAPI/Get/` — 列表查询（带 company_scope / tenant_scope） + - `/API/FormAPI/Add/Modify/Delete/
` — 增改删 + +### 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:` → 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 / 企业微信群