diff --git a/docs/.vitepress/sidebar/index.ts b/docs/.vitepress/sidebar/index.ts index 4afe89995..097819382 100644 --- a/docs/.vitepress/sidebar/index.ts +++ b/docs/.vitepress/sidebar/index.ts @@ -3,10 +3,12 @@ import ui from './ui'; import typedoc from './typedoc'; import utils from './utils'; import wiki from './wiki'; +import service from './service'; export default { '/guide/': guide, '/wiki/': wiki, '/ui/': ui, '/typedoc/': typedoc, - '/utils/': utils + '/utils/': utils, + '/service/': service }; diff --git a/docs/.vitepress/sidebar/service.ts b/docs/.vitepress/sidebar/service.ts new file mode 100644 index 000000000..6a75e2bc7 --- /dev/null +++ b/docs/.vitepress/sidebar/service.ts @@ -0,0 +1,36 @@ +export default [ + { + text: '高级服务', + base: '/service', + items: [ + { + text: '📦 在线版低代码平台源码', + link: '/', + items: [ + { + text: '源码说明', + link: '/intro' + }, + { + text: '平台概述', + link: '/wiki/', + items: [ + { + text: '项目结构', + link: '/wiki/1.1' + }, + { + text: '多平台构建系统', + link: '/wiki/1.2' + } + ] + }, + { + text: '架构概述', + link: '/wiki/2' + } + ] + } + ] + } +]; diff --git a/docs/src/guide/start.md b/docs/src/guide/start.md index 80d0ae04b..549cfe6ad 100644 --- a/docs/src/guide/start.md +++ b/docs/src/guide/start.md @@ -1,62 +1,92 @@ -# 快速上手 +# VTJ.PRO 快速上手指南 -## 创建一个 VTJ 应用 +## 创建 VTJ 应用 -VTJ.PRO 提供了开箱即用的项目脚手架,可以快速创建基于VTJ低代码的开发项目工程,并默认最佳实践的配置,非常适用新项目开发。 +VTJ.PRO 提供开箱即用的项目脚手架,可快速创建基于 VTJ 低代码的开发工程,预置最佳实践配置,特别适合新项目开发。 :::tip 前提条件 -- 熟悉命令行 -- 已安装 v20 或更高版本的 Node.js +- **命令行基础**:熟悉终端基本操作 +- **Node.js 环境**:已安装 v20 或更高版本(推荐使用 [LTS 版本](https://nodejs.org/)) + ::: -::: +### 通过脚手架创建项目 -### 使用脚手架创建项目 - -打开终端工具输入命令运行 +执行以下命令创建项目(根据网络情况选择命令): ```sh +# 标准创建(推荐网络畅通时使用) npm create vtj@latest -- -t app -``` -如`npm`访问不了,可以尝试使用镜像: - -```sh +# 国内用户加速方案(使用淘宝镜像) npm create vtj@latest --registry=https://registry.npmmirror.com -- -t app ``` -项目创建完成后进入,按提示进入目录 安装依赖 和 启动开发环境 +### 初始化与启动项目 + +创建完成后按提示操作: ```sh -npm run setup && npm run dev +# 进入项目目录(目录名根据提示输入) +cd your-project-name + +# 安装依赖(首次执行可能需 1-3 分钟) +npm run setup + +# 启动开发服务器 +npm run dev ``` -看到以下页面,项目已正常运行,你可以开始使用设计器以低代码的方式开发应用了。 +成功启动后,终端将显示本地访问地址(通常为 `http://localhost:5173`),浏览器访问该地址看到如下界面即表示运行成功: -![startup](../assets//startup.png) +![启动页面](../assets/startup.png) -:::info 使用VTJ提供的项目脚手架,可快速创建开发项目工程。 命令: +> **低代码开发提示**:此时可打开设计器开始可视化开发,设计器入口通常为 `http://localhost:5173/__vtj__/` -1. Web应用(PC端) +--- - ```sh - npm create vtj@latest --registry=https://registry.npmmirror.com -- -t app - ``` +### 项目类型选择 -1. H5应用(移动端) +根据目标平台选择创建命令: - ```sh - npm create vtj@latest --registry=https://registry.npmmirror.com -- -t h5 - ``` +| 平台类型 | 命令 | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| **Web应用** (PC端) | `npm create vtj@latest -- -t app`
或镜像加速版:
`npm create vtj@latest --registry=https://registry.npmmirror.com -- -t app` | +| **H5应用** (移动端) | `npm create vtj@latest -- -t h5`
或镜像加速版:
`npm create vtj@latest --registry=https://registry.npmmirror.com -- -t h5` | - ::: +--- -### 项目工程 +### 项目工程资源 -项目工程配置及说明请参考 [项目工程模板章节](./base/project-template.md) +- **配置文档**:[项目工程模板详解](./base/project-template.md) + - 包含目录结构说明、环境配置、构建部署等核心配置 +- **示例代码库**:[https://gitee.com/newgateway/examples-vtj/tree/master/packages/app](https://gitee.com/newgateway/examples-vtj/tree/master/packages/app) -项目工程示例代码:[https://gitee.com/newgateway/examples-vtj/tree/master/packages/app](https://gitee.com/newgateway/examples-vtj/tree/master/packages/app) +--- -### 设计器 +### 设计器使用 -低代码设计器的功能及使用说明请参考 [设计器使用手册](./base/designer.md) +- **设计器手册**:[低代码设计器完全指南](./base/designer.md) + - 组件拖拽配置 · 数据绑定 · 事件联动 · 主题定制 + +--- + +### 常见问题排查 + +1. **依赖安装失败**: + - 尝试删除 `node_modules` 后重新执行 `npm run setup` + - 检查网络代理设置或切换 npm 镜像源 +2. **端口冲突**: + + - 修改 `vite.config.js` 中的 `server.port` 配置项 + +3. **设计器加载异常**: + - 确保使用 Chrome/Edge 等现代浏览器 + - 清除浏览器缓存后重试 + +> 获取实时支持:加入 [VTJ 开发者社区](https://gitee.com/newgateway/vtj) 或提交 Issue + +--- + +**下一步建议**: +完成创建后,建议优先阅读 [设计器使用手册](./base/designer.md) 掌握核心开发工作流,再参考示例工程进行模块化开发。 diff --git a/docs/src/service/index.md b/docs/src/service/index.md index c8109b651..26381cb09 100644 --- a/docs/src/service/index.md +++ b/docs/src/service/index.md @@ -6,7 +6,7 @@ **VTJ.PRO** 作者倾力打造在线低代码平台样例项目源码,无需编码即可拥有全功能、同时支持Web、H5、UniApp的专属低代码开发平台。 -- [源码简介](./intro.md) +- [源码详情](./intro.md) - [效果体验](https://vtj.pro/demo/) :::warning 特别说明 diff --git a/docs/src/service/intro.md b/docs/src/service/intro.md index 8729a381e..2b241538a 100644 --- a/docs/src/service/intro.md +++ b/docs/src/service/intro.md @@ -1,4 +1,4 @@ -# 在线版低代码平台源码 +# 基于VTJ的在线低代码平台 —— 源码说明 这是一个基于 **VTJ** 低代码引擎实现的在线开发平台全功能示例项目,支持多平台应用开发。项目包含以下核心功能: diff --git a/docs/src/service/wiki/1.1.md b/docs/src/service/wiki/1.1.md new file mode 100644 index 000000000..b3d5dc762 --- /dev/null +++ b/docs/src/service/wiki/1.1.md @@ -0,0 +1,87 @@ +# 项目结构 + +本文档全面概述了 VTJ Low-Code Development Platform 存储库结构,涵盖前端 Vue.js 组件、后端 NestJS 模块、构建系统配置和多平台部署架构的组织。 + +有关多平台构建系统配置的详细信息,请参阅多平台构建系统 。组件之间的架构关系,请参见架构概述 。 + +## 仓库组织 + +VTJ LCDP 存储库遵循整体式结构,将前端、后端和构建配置集成到一个支持多个部署目标的统一代码库中。 + +### 顶级目录结构 + +![](./image/1/1.png) + +## 前端结构 + +前端遵循 Vue.js 3 种支持 TypeScript 的组合式 API 模式,组织成基于逻辑功能的模块。 + +### Vue.js 组件架构 + +![](./image/1/2.png) + +## 后端模块结构 + +后端实现了模块化的 NestJS 架构,明确地分离了跨功能域的关注点。 + +### NestJS 模块组织 + +![](./image/1/3.png) + +### 后端模块映射 + +| 模块 | 中文描述 | 主要功能 | +| ---------- | ---------------- | ------------------------ | +| apps/ | 应用管理模块 | 核心应用程序生命周期管理 | +| access/ | 权限控制模块 | 分层权限控制 | +| cache/ | 缓存模块 | 双层缓存系统 | +| oauth/ | 第三方登录模块 | OAuth 2.0 身份验证流程 | +| users/ | 用户模块 | 用户帐户管理 | +| roles/ | 角色模块 | 基于角色的访问控制 | +| schemas/ | Service 接口 | Schema 服务实现 | +| templates/ | 模版模块业务逻辑 | 模板业务逻辑 | +| shared/ | 公共模块 | 共享实用程序和类型 | + +## 构建系统配置 + +该项目通过复杂的构建配置系统支持多个构建目标和环境。 + +### 多环境构建矩阵 + +![](./image/1/4.png) + +### 构建脚本配置 + +| 脚本命令 | 环境 | 目标 | TypeScript 检查 | +| -------------------- | ----- | ---------- | --------------- | +| npm run dev | local | 开发服务器 | 不 | +| npm run sit:main | sit | main | 是的 | +| npm run sit:web | sit | web | 是的 | +| npm run sit:h5 | sit | h5 | 是的 | +| npm run sit:uniapp | sit | uniapp | 是的 | +| npm run build:main | live | main | 是的 | +| npm run build:web | live | web | 是的 | +| npm run build:h5 | live | h5 | 是的 | +| npm run build:uniapp | live | uniapp | 是的 | + +## 依赖项和生态系统集成 + +该项目通过专门的平台包和开发工具与 VTJ 生态系统集成。 + +### VTJ 生态系统依赖项 + +![](./image/1/5.png) + +## 配置文件结构 + +### 主配置文件 + +| 文件 | 目的 | 主要特点 | +| ----------------- | ---------------- | ------------------------ | +| package.json | 项目元数据和脚本 | 多目标构建、VTJ 生态系统 | +| vite.config.ts | 构建配置 | 基于环境的构建 | +| tsconfig.json | TypeScript 配置 | 构建的类型检查 | +| scripts/clean.mjs | 清理实用程序 | 构建工件管理 | +| scripts/ssh.mjs | 部署脚本 | 基于 SSH 的部署 | + +项目结构反映了专为多平台部署而设计的复杂低代码平台架构,同时保持前端演示、后端业务逻辑和构建系统配置之间的明确分离。模块化后端设计支持可扩展的功能开发,而前端结构支持通过 TypeScript 支持进行可维护的 Vue.js 组件开发。 diff --git a/docs/src/service/wiki/1.2.md b/docs/src/service/wiki/1.2.md new file mode 100644 index 000000000..cf021b687 --- /dev/null +++ b/docs/src/service/wiki/1.2.md @@ -0,0 +1,77 @@ +# 多平台构建系统 + +## 目的和范围 + +本文档介绍了 VTJ 低代码开发平台的多平台构建系统,该系统支持跨多个目标平台(Web、H5、UniApp)进行部署,并支持不同的环境(SIT、Live)。构建系统利用 VTJ 生态系统包,并为跨平台部署提供自动化编译工作流。 + +有关整体项目结构的信息,请参阅项目结构 。有关开发设置和配置的详细信息,请参阅 开发配置 。 + +## 构建环境 + +构建系统支持两个主要部署环境,每个环境都有不同的配置和优化设置: + +| 环境 | 目的 | 环境变量 | 构建脚本 | +| ---- | -------------- | ------------- | ---------------------------------------------------- | +| SIT | 集成测试和暂存 | ENV_TYPE=sit | sit:main, sit:web, sit:h5, sit:uniapp | +| LIVE | 生产部署 | ENV_TYPE=live | build:main, build:web, build:h5, build:uniapp | + +### 环境配置流程 + +![](./image/1/6.png) + +## 平台目标 + +构建系统为四个不同的平台目标生成优化的捆绑包,每个目标都使用特定的 VTJ 生态系统包: + +### 构建目标架构 + +![](./image/1/7.png) + +### 特定于平台的配置 + +| 平台 | 生成类型 | 运行时包 | 目标用例 | +| ------ | ----------------- | -------- | ---------------------- | +| 主应用 | BUILD_TYPE=main | @vtj/web | 功能齐全的核心应用程序 | +| Web | BUILD_TYPE=web | @vtj/web | 标准 Web 浏览器部署 | +| H5 | BUILD_TYPE=h5 | @vtj/h5 | 移动 Web 应用程序 | +| UniApp | BUILD_TYPE=uniapp | @vtj/uni | 跨平台移动应用程序 | + +## VTJ 生态系统集成 + +构建系统通过运行时依赖项和开发工具与 VTJ 生态系统紧密集成: + +### 运行时依赖项 + +- **@vtj/web**:Web 平台运行时引擎 +- **@vtj/h5**:H5 移动 Web 运行时引擎 +- **@vtj/uni**:UniApp 跨平台运行时引擎 +- **vue**:Core Vue.js 框架 (~3.5.0) +- **vue-router**:客户端路由 (~4.5.0) + +### 开发工具 + +- **@vtj/cli**:用于 VTJ 作的命令行界面 +- **@vtj/pro** :专业的开发工具和实用程序 + +## 构建脚本编排 + +构建系统提供对各个平台构建和全面批处理作的精细控制: + +### 单个平台脚本 + +![](./image/1/8.png) + +### 批量构建作 + +系统提供了两个全面的构建命令,可按顺序执行所有平台目标: + +- **npm run sit**:执行 sit:main、sit:web、sit:h5、sit:uniapp +- **npm run build**:执行 build:main、build:web、build:h5、build:uniapp + +## 部署和分发 + +构建系统在 dist/ 目录结构中生成可部署的工件,每个平台目标都创建自己的子目录。package.json 中的 files 数组指定 npm 包分发中包含哪些工件: + +- **dist/** - 所有已编译的平台 bundle +- **package.json** - 包元数据和依赖项 +- **README.md** - 文档 diff --git a/docs/src/service/wiki/2.md b/docs/src/service/wiki/2.md new file mode 100644 index 000000000..4b0489ded --- /dev/null +++ b/docs/src/service/wiki/2.md @@ -0,0 +1,61 @@ +# 架构概述 + +本文档简要概述了 VTJ 低代码开发平台架构,包括前端组件、后端模块和多平台构建系统之间的关系。它涵盖了支持平台低代码开发功能的整体系统设计模式和核心架构决策。 + +具体前端组件的详细实现请参见 前端组件 。有关后端服务实施的详细信息,请参阅后端服务 。有关构建系统配置,请参阅多平台构建系统 。 + +## 系统架构 + +VTJ 平台遵循现代全栈架构,在表示层、业务逻辑层和数据持久层之间实现了明确分离。该系统旨在支持多个部署目标,同时保持单个代码库。 + +### 整体系统架构 + +![](./image/2/1.png) + +### 后端模块依赖项 + +后端遵循 NestJS 模块化架构,业务模块和基础设施服务之间有明确的依赖关系。 + +![](./image/2/2.png) + +## 前端-后端通信流程 + +前端组件通过 RESTful API 与后端服务通信,状态管理由 Vue 组合式 API 钩子处理。 + +### 应用程序管理数据流 + +![](./image/2/3.png) + +## 多平台构建架构 + +该平台通过利用 VTJ 生态系统软件包的统一构建系统支持多个部署目标。 + +### 构建目标架构 + +![](./image/2/4.png) + +## 模块交互模式 + +### 服务层依赖项 + +后端服务遵循分层架构,具有由 NestJS 管理的明确依赖关系注入模式。 + +### 数据流模式 + +该平台实现了几个关键的数据流模式: + +1. 请求-响应模式 :前端钩子通过 HTTP API 与后端控制器通信 +1. 事件驱动更新 :状态更改通过 Vue 的响应式系统传播 +1. 分层访问控制 :权限在访问控制树中级联 +1. 多层缓存 :应用程序和基础设施级别的数据缓存 + +### 跨领域关注点 + +该架构通过以下方式解决横切关注点: + +- 身份验证 :OAuth 与 Gitee 和会话管理的集成 +- 授权 :具有基于角色的权限的分层访问控制系统 +- 缓存 :具有可配置 TTL 和命中跟踪的全局缓存模块 +- 日志记录 :用于审计跟踪和调试的集中式报告模块 +- 配置 :用于环境特定配置的设置模块 +- 文件管理 :用于安全文件上传和存储的 OSS 模块 diff --git a/docs/src/service/wiki/image/1.png b/docs/src/service/wiki/image/1.png new file mode 100644 index 000000000..50e89e912 Binary files /dev/null and b/docs/src/service/wiki/image/1.png differ diff --git a/docs/src/service/wiki/image/1/1.png b/docs/src/service/wiki/image/1/1.png new file mode 100644 index 000000000..da0d10946 Binary files /dev/null and b/docs/src/service/wiki/image/1/1.png differ diff --git a/docs/src/service/wiki/image/1/2.png b/docs/src/service/wiki/image/1/2.png new file mode 100644 index 000000000..7e4d5cec7 Binary files /dev/null and b/docs/src/service/wiki/image/1/2.png differ diff --git a/docs/src/service/wiki/image/1/3.png b/docs/src/service/wiki/image/1/3.png new file mode 100644 index 000000000..bdfc98a3e Binary files /dev/null and b/docs/src/service/wiki/image/1/3.png differ diff --git a/docs/src/service/wiki/image/1/4.png b/docs/src/service/wiki/image/1/4.png new file mode 100644 index 000000000..7e441e2a2 Binary files /dev/null and b/docs/src/service/wiki/image/1/4.png differ diff --git a/docs/src/service/wiki/image/1/5.png b/docs/src/service/wiki/image/1/5.png new file mode 100644 index 000000000..f406aa38e Binary files /dev/null and b/docs/src/service/wiki/image/1/5.png differ diff --git a/docs/src/service/wiki/image/1/6.png b/docs/src/service/wiki/image/1/6.png new file mode 100644 index 000000000..ea3316765 Binary files /dev/null and b/docs/src/service/wiki/image/1/6.png differ diff --git a/docs/src/service/wiki/image/1/7.png b/docs/src/service/wiki/image/1/7.png new file mode 100644 index 000000000..dc1a171ed Binary files /dev/null and b/docs/src/service/wiki/image/1/7.png differ diff --git a/docs/src/service/wiki/image/1/8.png b/docs/src/service/wiki/image/1/8.png new file mode 100644 index 000000000..b09c122af Binary files /dev/null and b/docs/src/service/wiki/image/1/8.png differ diff --git a/docs/src/service/wiki/image/2.png b/docs/src/service/wiki/image/2.png new file mode 100644 index 000000000..7e7b7b5f7 Binary files /dev/null and b/docs/src/service/wiki/image/2.png differ diff --git a/docs/src/service/wiki/image/2/1.png b/docs/src/service/wiki/image/2/1.png new file mode 100644 index 000000000..a9408c071 Binary files /dev/null and b/docs/src/service/wiki/image/2/1.png differ diff --git a/docs/src/service/wiki/image/2/2.png b/docs/src/service/wiki/image/2/2.png new file mode 100644 index 000000000..99937ea7e Binary files /dev/null and b/docs/src/service/wiki/image/2/2.png differ diff --git a/docs/src/service/wiki/image/2/3.png b/docs/src/service/wiki/image/2/3.png new file mode 100644 index 000000000..235d952df Binary files /dev/null and b/docs/src/service/wiki/image/2/3.png differ diff --git a/docs/src/service/wiki/image/2/4.png b/docs/src/service/wiki/image/2/4.png new file mode 100644 index 000000000..0d91731d7 Binary files /dev/null and b/docs/src/service/wiki/image/2/4.png differ diff --git a/docs/src/service/wiki/image/3.png b/docs/src/service/wiki/image/3.png new file mode 100644 index 000000000..a4e87e51e Binary files /dev/null and b/docs/src/service/wiki/image/3.png differ diff --git a/docs/src/service/wiki/index.md b/docs/src/service/wiki/index.md new file mode 100644 index 000000000..70ce9e7fb --- /dev/null +++ b/docs/src/service/wiki/index.md @@ -0,0 +1,102 @@ +# 基于 VTJ 的在线低代码平台概述 + +## 目的和范围 + +本文档全面概述了 VTJ 低代码开发平台(LCDP),这是一个支持快速创建和部署应用程序的多平台开发环境。该平台由 Vue.js 前端应用程序和 NestJS 后端 API 组成,支持多种部署目标,包括 Web 浏览器、移动 H5 应用和跨平台 UniApp 环境。 + +本文档涵盖平台架构、核心技术和系统组织。有关特定子系统的详细信息,请参考: + +- 项目结构 +- 前端组件 +- 后端服务 + +有关设置和配置的详细信息,请参阅: + +- 开发配置 +- 入门指南 + +## 系统架构概述 + +VTJ LCDP 采用现代 Web 应用程序架构,实现了前端展示、后端服务和多平台构建之间的明确分离。 + +![](./image/1.png) + +## 平台架构 + +平台采用分层架构模式,各层职责分明: + +![](./image/2.png) + +## 多平台构建系统 + +平台支持四个不同的构建目标,每个目标针对特定部署场景优化: + +| 构建目标 | 环境变量 | 输出类型 | 主要应用场景 | +| -------- | ------------------- | -------------- | -------------- | +| main | `BUILD_TYPE=main` | 核心应用程序包 | 主 Web 部署 | +| web | `BUILD_TYPE=web` | Web 优化包 | 浏览器特定功能 | +| h5 | `BUILD_TYPE=h5` | 移动 H5 包 | 移动 Web 应用 | +| uniapp | `BUILD_TYPE=uniapp` | 跨平台包 | 多平台应用部署 | + +### 构建脚本配置 + +构建系统通过 npm 脚本使用环境特定配置: + +```bash +# 开发环境 (热重载) +npm run dev # ENV_TYPE=local + +# SIT 环境构建 (系统集成测试) +npm run sit:main # ENV_TYPE=sit BUILD_TYPE=main +npm run sit:web # ENV_TYPE=sit BUILD_TYPE=web +npm run sit:h5 # ENV_TYPE=sit BUILD_TYPE=h5 +npm run sit:uniapp # ENV_TYPE=sit BUILD_TYPE=uniapp + +# 生产环境构建 +npm run build:main # ENV_TYPE=live BUILD_TYPE=main +npm run build:web # ENV_TYPE=live BUILD_TYPE=web +npm run build:h5 # ENV_TYPE=live BUILD_TYPE=h5 +npm run build:uniapp # ENV_TYPE=live BUILD_TYPE=uniapp +``` + +## 核心技术和依赖项 + +### 前端核心依赖 + +| 包 | 版本 | 功能描述 | +| -------------------- | ---------------------- | ------------------------- | +| vue | ~3.5.0 | 核心 Vue.js 框架 | +| vue-router | ~4.5.0 | 客户端路由管理 | +| @vtj/web | latest | VTJ Web 平台集成库 | +| @vtj/h5 | latest | VTJ 移动 H5 平台适配 | +| @vtj/uni | latest | VTJ UniApp 跨平台支持 | +| @dcloudio/uni-h5-vue | 3.0.0-4050720250324001 | UniApp H5 环境 Vue 运行时 | + +### 开发工具依赖 + +| 包 | 版本 | 功能描述 | +| -------- | ------- | --------------------- | +| @vtj/cli | latest | VTJ 命令行工具 | +| @vtj/pro | latest | VTJ 专业开发工具套件 | +| node-ssh | ~13.2.0 | 支持 SSH 远程部署功能 | + +## 后端模块概述 + +后端采用模块化 NestJS 架构,包含以下核心模块: + +![](./image/3.png) + +## 开发环境配置 + +平台支持三种环境配置: + +- **ENV_TYPE=local**:热重载开发环境,支持实时代码更新 +- **ENV_TYPE=sit**:系统集成测试环境,用于预发布验证 +- **ENV_TYPE=live**:生产环境,优化性能和安全性 + +### 构建配置说明 + +1. **多目标支持**:每个环境可针对四个平台目标构建,共提供 12 种构建配置组合 +2. **TypeScript 处理**:构建过程通过 `vue-tsc` 自动处理 TypeScript 编译 +3. **环境变量注入**:使用 `cross-env` 实现跨平台环境变量注入 +4. **构建优化**:生产环境构建启用代码压缩、Tree Shaking 等优化措施。