VTJ.PRO 在线应用开发平台入门与项目初始化

入门与项目初始化

本文档提供了设置 VTJ.PRO 开发环境的技术规范。涵盖了 monorepo 配置、通过 pnpm 进行的依赖管理，以及在本地运行前端和后端服务所需的初始化步骤。

环境要求

该平台以 monorepo 形式构建，需要特定的 node-linker 行为和注册表配置来处理低代码引擎的复杂依赖关系。

包管理器配置

项目使用 pnpm，并需要在根目录的 .npmrc 文件中定义特定的提升（hoisting）设置。这些设置确保了构建工具和运行时能够访问到对等依赖项以及深度嵌套的包（例如 @vtj/core 或 @vtj/renderer）。

Key	Value	Purpose
hoist	true	启用将依赖提升到根 node_modules 目录。
shamefully-hoist	true	强制提升所有依赖，解决嵌套对等依赖的问题。
node-linker	hoisted	使用标准的 node_modules 结构，而不是符号链接。
registry	https://registry.npmmirror.com	将默认注册表设置为 npmmirror，以便在特定区域更快地访问。

项目结构与 Monorepo 初始化

VTJ.PRO 平台分为几个核心目录，必须按顺序进行初始化。该系统依赖于 NestJS 后端和 Vue 3 前端的组合，并由静态模板和文档提供支持。

核心目录

• backend/： 处理 DSL 管理、AI 代理和 RBAC 的 NestJS 服务器。
• frontend/： 包含工作台和管理界面的 Vue 3 应用程序。
• templates/： 用于代码生成的 Web、H5 和 UniApp 项目模板的源代码。
• scripts/： 维护和发布的自动化脚本。
• _docs/： 技术文档和初始化指南。

初始化流程

初始化过程遵循从环境配置到依赖安装，最后到服务执行的特定数据流。

1. 依赖安装

由于 .npmrc 中设置了 shamefully-hoist，开发者应从根目录运行 pnpm install。这将为所有工作区（包括前端和后端）填充 node_modules。

2. 环境配置

前端和后端都需要 .env 文件。

• 后端： 需要数据库凭据（MySQL）、Redis 配置（用于缓存）和用于文件管理的 OSS（对象存储服务）密钥。
• 前端： 需要将 VITE_API_URL 指向本地或远程的后端服务。

3. 数据库播种

后端包含一个迁移和播种系统。首次运行时，MigrationService 会检查所需表是否存在，并填充初始数据（角色、权限和默认的 LLM 提供商）。

技术架构：初始化序列

下图说明了配置文件、包管理器以及最终环境状态之间的关系。

系统引导图

"此图将设置步骤的'自然语言空间'映射到配置文件的'代码实体空间'。"

flowchart subgraph Configuration Space direction LR NPMRC[".npmrc"] ENV_BACKEND["backend/.env"] ENV_FRONTEND["frontend/.env"] end subgraph Process Space PNPM_INSTALL["pnpm install"] DB_MIGRATION["MigrationService.run()"] VITE_DEV["vite dev"] NEST_START["nest start"] end subgraph Code Entity Space HOIST_CONFIG["shamefully-hoist=true"] NODE_MODULES["root/node_modules"] DB_SCHEMA["MySQL Tables"] FRONTEND_APP["Vue 3 Workbench"] end NPMRC -- Configures --> PNPM_INSTALL PNPM_INSTALL -- Generates --> NODE_MODULES HOIST_CONFIG -- Impacts --> NODE_MODULES ENV_BACKEND -- Configures --> NEST_START NEST_START -- Triggers --> DB_MIGRATION DB_MIGRATION -- Creates --> DB_SCHEMA ENV_FRONTEND -- Configures --> VITE_DEV VITE_DEV -- Serves --> FRONTEND_APP

本地运行平台

一旦依赖安装完成且数据库配置好，就可以使用以下脚本启动平台。

后端执行

后端是平台的核心，为低代码引擎提供 API。它处理 DslService 和 AiService。

cd backend
npm run start:dev

前端执行

前端提供可视化编辑器和管理仪表板。

cd frontend
npm run dev

模板打包

在平台可以生成新项目之前，必须将模板打包到后端的发布文件夹中。这由一个自定义脚本处理。

node scripts/template.mjs

此脚本压缩 templates/ 目录的内容，并将其放置到 backend/zip/ 中，DslService 可以在那里访问这些内容以进行项目初始化。

配置实体总结

下表列出了初始化过程中涉及的关键文件及其作用。

File/Path	Entity Role	Description
.npmrc	环境配置	定义了 @vtj 包所需的 hoisted node-linker 策略。
scripts/template.mjs	构建工具	将 templates/ 源代码与 backend/ 运行时资源同步。
backend/src/main.ts	入口点	初始化 NestJS 应用程序和全局拦截器。
frontend/src/main.ts	入口点	挂载 Vue 3 应用程序并初始化 vtj/renderer。

参考资料

• 官方文档：vtj.pro/
• 在线平台：app.vtj.pro/
• 开源仓库：gitee.com/newgateway/...