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. 安装依赖

# 克隆仓库
git clone <仓库地址>
cd SMANAGE

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

3. 配置文件

• 确保 Utils/Config.py 中的配置正确
• 准备 SSL 证书并放置在 SSL/ 目录

4. 启动开发服务器

# 启动开发服务器
python Main.py

如何添加新 API

1. 创建 API 文件

在 TempLateAPI/ 目录下创建 .api 文件，文件路径将自动映射为路由。

2. API 文件结构

# __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

__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 证书，检查配置文件

联系信息

• 项目负责人：<负责人姓名>
• 技术支持：<支持邮箱>
• 团队沟通：<沟通工具>

---

注意：本文档会根据项目发展持续更新，请定期查看最新版本。