演示

创建插件

端到端配方：用 @quan-erp/cli 脚手架、对齐名称与 @quan-erp/* 版本、加入第一个功能、watch 到 available-plugins，再在运行中的 base 栈上安装。

目标

在 plugins/ 下得到一个可构建、可安装并在 Quark ERP shell 中注册菜单/路由的插件目录。

  • 一个目录：module.metadata.json + backend/ + frontend/
  • 目录名 === metadata.name === 包标识
  • 产物进入 available-plugins，Install 后进入 installed-plugins

1. 前置条件

脚手架之前需要已有 Quark ERP 项目并运行 base 栈。

  • 已用 quan-erp new-project 创建项目（见安装）
  • 已安装 @quan-erp/cli：npm i -g @quan-erp/cli
  • Base 已启动：quan-erp base:dev
  • Node.js 18+（推荐 20+ LTS）
  • 使用小写 kebab-case 名称（如 fleet-management）
TSQuick check
quan-erp help quan-erp base:dev # if base is not already up
@quan-erp/cli on npm →安装 →

2. 脚手架插件

空白插件用 CLI；需要可运行的菜单、页面与 API 模式时复制 sample-es。

  • quan-erp new / new-plugin — 适合全新插件
  • sample-es — IPlugin、register、api/、page/ 的最佳参考
  • 保持顶层布局：backend/ + frontend/ + module.metadata.json
TSOption A — quan-erp new
1# From project root 2quan-erp new 3# or: quan-erp new-plugin 4# optional: quan-erp new-plugin --version latest 5# Prompts: name, description, module entry object, version 6# Creates plugins/<name>/{backend,frontend,module.metadata.json}
TSOption B — copy sample-es
cp -R plugins/sample-es plugins/my-plugin # Then rename packages + metadata.name (next section)

3. 对齐名称（关键）

这些字符串不一致时，watch、安装与 DI 会以难排查的方式失败。每次脚手架后都要核对。

  • name — API 前缀、菜单与 @Inject 作用域的唯一 id
  • pluginVersion — available-plugins/<name>/<version>/ 目录
  • requiredBasedVersion — 须与 base / @quan-erp/* 对齐
  • moduleEntryObject — 根 @Module 类名（通常为 Module）
  • pluginDependencies — 必须先加载的插件
TSIdentity checklist
1plugins/<name>/ # folder 2module.metadata.json → "name": "<name>" 3backend/package.json → "@quan-erp-plugins/<name>-backend" 4frontend/package.json → "@quan-erp-plugins/<name>-frontend" 5@Module({ name: metadata.name, ... }) # backend root module
JSONmodule.metadata.json
1{ 2 "name": "my-plugin", 3 "type": "", 4 "pluginVersion": "1.0.0", 5 "description": "My first plugin", 6 "moduleEntryObject": "Module", 7 "requiredBasedVersion": "1.0.0", 8 "pluginDependencies": {} 9}

4. 对齐 @quan-erp/* 版本

后端与前端的 @quan-erp/* 依赖必须与 base 镜像 / BASE_VERSION 一致。

  • 从 sample-es 或同 base 上可用的插件复制版本钉
  • 改版本后在 backend / frontend 重新 npm install
  • 依赖变更后重新 quan-erp watch
SHInstall deps
cd plugins/my-plugin/backend && npm install cd ../frontend && npm install cd ../../.. # back to project root

5. 加入第一个功能

第一次改动保持精简：后端一个实体 + 服务 + 控制器；前端一个页面 + api hook + 菜单/路由。

  • 后端 — IPlugin、功能目录、entity、根 @Module 注册
  • 前端 — register(AppRegistry)：Axios、menu.add、route.add
  • API — React Query hooks；页面只导入 hooks
  • 表名与 HTTP 路径用插件名做命名空间
  • 不要导入其他插件的 src/

6. 用 quan-erp watch 构建

在项目根目录，watch 将 backend + frontend 编译到 base/available-plugins/<name>/<version>/。

  • 参数是 plugins/ 下的文件夹名
  • 确认 available-plugins 含 backend/、frontend/、module.metadata.json
  • 若已安装，开发时 watch 也会刷新 installed 副本
TSTerminal
quan-erp watch my-plugin # one-shot production build quan-erp build:prod my-plugin

7. 在 ERP UI 中安装

watch 只写入 available-plugins；shell 加载 installed-plugins。从 Modules UI 安装。

  • 在 Modules 中 Install
  • 确认 installed-plugins/<name>/ 存在
  • 强制刷新浏览器；检查 register() 的菜单/路由
  • 若不出现 — 见故障排查 → 已安装但前端未加载
创建插件（快速开始）→CLI →目录结构 →