演示

创建插件

用 @quan-erp/cli 的 quan-erp new 脚手架插件，对齐名称与版本，quan-erp watch，然后在本地注册并安装。

概述

一个插件 = plugins/<name>/ + module.metadata.json + backend + frontend。优先 quan-erp new / new-plugin，或复制 sample-es。

  • 先安装 @quan-erp/cli（见 Installation / CLI）
  • 在项目根目录运行 quan-erp
  • 文件夹名 = metadata.name = npm 包后缀
  • 需先启动 base 栈（quan-erp base:dev）
@quan-erp/cli on npm →

1. 开始之前

需要用 CLI 创建的 Quark ERP 项目，以及正在运行的 base。

  • 已用 quan-erp new-project 脚手架（Installation）
  • npm i -g @quan-erp/cli
  • quan-erp base:dev
  • Node.js 18+ 与可用的 ~/.npmrc
  • 选用 kebab-case 插件名
TSQuick check
quan-erp help quan-erp base:dev # if base is not already up

2. 脚手架

quan-erp new / new-plugin 生成空白插件；复制 sample-es 可获得完整参考结构。

  • quan-erp new / new-plugin — interactive; good for greenfield plugins
  • sample-es — best reference for IPlugin, register(AppRegistry), api/, page/
  • Do not invent a custom top-level layout — keep 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. 对齐名称（关键）

文件夹、metadata.name、package.json 名称必须一致。CLI 通常会填好，脚手架后仍请核对。

  • name — unique plugin id used for API path prefixes, menus, and @Inject scope
  • pluginVersion — becomes the folder under available-plugins/<name>/<version>/
  • requiredBasedVersion — must match the base / @quan-erp/* version line
  • moduleEntryObject — root @Module class name exported from backend entry (usually Module)
  • pluginDependencies — other plugins that must load first (add later when you consume exports)
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/* 版本

backend/frontend 中的 @quan-erp/* 必须与 base 镜像版本线一致。

  • Copy version pins from sample-es or from another working plugin on the same base
  • After changing versions, reinstall deps in plugins/<name>/backend and frontend
  • Rebuild with quan-erp watch after dependency changes
SHInstall deps
cd plugins/my-plugin/backend && npm install cd ../frontend && npm install cd ../../.. # back to project root

5. 添加第一个功能

后端实体+服务+控制器，前端页面+api+菜单；对照 sample-es。

  • Backend — backend/src/index.ts (IPlugin), feature folder, schema/*.entity.ts, register providers on root @Module
  • Frontend — frontend/src/index.tsx register(AppRegistry): setAxiosClient, menu.add, route.add
  • API layer — frontend/src/api/<domain>/ with React Query; pages import hooks only
  • Namespace tables and HTTP paths with the plugin name (host prefixes routes automatically)
  • Do not import another plugin’s src/ — use Export services / frontend Export & expose APIs later

6. 使用 quan-erp watch

在项目根目录执行 watch，产物写入 available-plugins。

  • Argument is the folder name under plugins/
  • Confirm base/available-plugins/my-plugin/<version>/ contains backend/, frontend/, module.metadata.json
  • Leave watch running while you iterate
TSTerminal
quan-erp watch my-plugin # one-shot production build quan-erp build:prod my-plugin

7. 本地 seed + UI 安装

仅在 local/dev 插入 module 行，再在 ERP UI 中安装。切勿对 UAT/生产 SQL seed。

  • name / plugin_version / module_entry_object must match metadata
  • dependencies JSON should mirror pluginDependencies (use '{}' when empty)
  • After install, hard-refresh the browser if menus do not appear
  • If watch is running and the plugin is already installed, it also refreshes installed-plugins
SQLSQL (local/dev)
INSERT INTO module ("name","displayName","description","unInstallable","module_entry_object","plugin_version","dependencies","base_version","version") VALUES ('my-plugin','My Plugin','My first plugin',true,'Module','1.0.0','{}','1.0.0',1);
TSThen in ERP UI
# Open the running frontend # Find the plugin under available / modules # Install → copies to base/backend/installed-plugins/my-plugin/

清单

检查 CLI、new-project、名称、版本、watch 输出、seed 与 UI 安装。

  • @quan-erp/cli installed; project created with quan-erp new-project
  • plugins/<name>/ exists with backend/, frontend/, module.metadata.json
  • metadata.name === folder name
  • package.json names are @quan-erp-plugins/<name>-backend|frontend
  • @quan-erp/* versions match the base stack
  • quan-erp watch <name> wrote available-plugins/<name>/<version>/
  • Local module row inserted (dev only)
  • Installed from ERP UI → installed-plugins/<name>/
  • register() adds at least one menu + route you can open

下一步

继续阅读 Installation、目录结构、CLI、后端/前端 Doc 与 AI Agent 指南。

  • Installation — project setup with quan-erp new-project
  • Folder structure — detailed trees for backend/frontend
  • CLI — watch / build:prod / pack:prod / new-project reference
  • Backend → Module lifecycle, Export services
  • Frontend → Plugins lifecycle, Export & expose APIs
  • Build with AI Agent — skills and pre-build prompts for faster scaffolding
InstallationFolder structureCLIBackend exportFrontend export