项目工程规范

本文档主要介绍项目开发规范以及构建成品的标准规范。

开发项目工程规范

在项目开发过程中，良好的工程结构至关重要，它能够帮助开发者快速定位问题，降低项目复杂度，提高开发效率。

前端开发规范

前端开发时请遵循以下目录结构规范，所有前端项目文件需要放置在项目根目录下的 web 目录中：

HTML

web/
├── index.html    # 主入口 HTML 文件
└── build.sh      # 构建脚本

Vue

web/
├── index.html        # 主入口 HTML 文件
├── package.json      # 项目依赖和脚本配置
├── public/           # 静态资源目录
├── src/              # 源代码目录
│   ├── assets/       # 静态资源目录
│   ├── components/   # 组件目录
│   ├── App.vue       # 根组件
│   ├── main.js       # 应用入口文件
│   └── style.css     # 全局样式文件
├── vite.config.js    # Vite 配置文件
├── yarn.lock         # Yarn 包管理器锁文件
└── build.sh          # 构建脚本

React

web/
├── index.html        # 主入口 HTML 文件
├── public/           # 公共资源文件夹
│   └── vite.svg      # Vite 图标
├── src/              # 源代码目录
│   ├── assets/       # 静态资源目录
│   ├── components/   # 组件目录
│   ├── App.jsx       # 根组件
│   ├── main.jsx      # 应用入口文件
│   └── style.css     # 全局样式文件
├── vite.config.js    # Vite 配置文件
├── yarn.lock         # Yarn 包管理器锁文件
└── build.sh          # 构建脚本

后端开发规范

后端开发时请使用以下目录结构进行开发，所有后端项目文件需要存放在 backend 目录下：

backend/
├── app/
│   ├── consts/           # 常量定义（如状态码、配置项等）
│   ├── i18n/             # 国际化模块（默认支持中英文）
│   ├── middlewares/      # 中间件（如鉴权、请求拦截等）
│   ├── schemas/          # 入参校验（Pydantic 或自定义规则）
│   ├── services/         # 核心业务逻辑处理
│   ├── utils/            # 工具模块（如日志、RPC调用等）
├── config.yaml           # 应用配置文件（日志、端口、元信息等）
├── install.sh            # 安装脚本（如 Redis、依赖库等）
├── main.py               # 应用入口，含服务注册与启动逻辑
├── Makefile              # 编译/打包等命令定义
├── requirements.txt      # Python 依赖列表（可选用 Poetry 管理）

完整项目结构

完整的应用项目目录结构应该如下所示：

my-gmssh-app/
├── web/                  # 前端目录
│   ├── index.html        # 主入口 HTML 文件
│   └── build.sh          # 构建脚本
├── backend/              # 后端目录
│   ├── app/
│   │   ├── consts/       # 常量定义（如状态码、配置项等）
│   │   ├── i18n/         # 国际化模块（默认支持中英文）
│   │   ├── middlewares/  # 中间件（如鉴权、请求拦截等）
│   │   ├── schemas/      # 入参校验（Pydantic 或自定义规则）
│   │   ├── services/     # 核心业务逻辑处理
│   │   └── utils/        # 工具模块（如日志、RPC调用等）
│   ├── config.yaml       # 应用配置文件（日志、端口、元信息等）
│   ├── install.sh        # 安装脚本（如 Redis、依赖库等）
│   ├── main.py           # 应用入口，含服务注册与启动逻辑
│   ├── Makefile          # 编译/打包等命令定义
│   └── requirements.txt  # Python 依赖列表（可选用 Poetry 管理）
├── Makefile              # 项目根目录构建脚本
└── .gitignore            # Git 版本控制忽略文件

应用成品规范

为了确保应用的一致性和标准化，我们需要使用以下目录结构来组织构建后的应用成品。

构建产物部署规范

在执行 Makefile 构建时，请按照以下规则部署构建产物：

• 后端构建产物：放置在 app/bin 目录下，主可执行文件必须命名为 main
• 前端构建产物：放置在 app/www 目录下，主入口文件必须命名为 index.html

重要提示

如果您的后端服务类型是 socket 服务，生成的 socket 文件必须放置在 tmp 目录下并命名为 app.sock，否则会导致应用无法正常运行。

omc/
├── app/                  # 应用程序目录
│   ├── bin/              # 可执行文件目录
│   │   └── min           # 主应用程序可执行文件
│   └── www/              # Web静态资源目录
│       └── index.html    # 前端入口页面
├── config/               # 配置文件目录
├── data/                 # 数据存储目录
├── logs/                 # 日志文件目录
└── tmp/                  # 临时文件目录

应用部署路径

应用包审核通过并上架后，用户下载的应用将存放在服务器的以下路径：

/.__gmssh/plugin/{组织名}/{应用名}/

其中 {组织名} 和 {应用名} 将根据实际的组织和应用信息进行替换。