Demo

Plugin ဖန်တီးခြင်း

@quan-erp/cli ဖြင့် quan-erp new ကို အသုံးပြု၍ plugin ကို scaffold လုပ်ပါ။ အမည်နှင့် ဗားရှင်းများကို ကိုက်ညီအောင် ညှိပြီး၊ quan-erp watch ဖြင့် တည်ဆောက်ကာ၊ ဒေသခံ stack တွင် မှတ်ပုံတင်ပြီး ထည့်သွင်းအသုံးပြုပါသည်။

အနှစ်ချုပ်

Plugin တစ်ခုသည် plugins/ အောက်ရှိ folder တစ်ခုဖြစ်ပြီး၊ module.metadata.json၊ backend package နှင့် frontend package ပါဝင်ပါသည်။ Scaffold လုပ်ရန် quan-erp new / new-plugin ကို ဦးစားပေး အသုံးပြုပါ။ နမူနာ layout အပြည့်အစုံ လိုအပ်ပါက plugins/sample-es ကို ကူးယူနိုင်ပါသည်။

  • @quan-erp/cli ကို ဦးစွာ သွင်းထားရပါမည် (Installation / CLI ကို ကြည့်ပါ)
  • quan-erp command အားလုံးကို project root မှ run ရပါမည်
  • Folder အမည်၊ module.metadata.json ၏ name နှင့် npm package suffix တို့ တူညီရပါမည်
  • Base stack ကို ကြိုတင် လည်ပတ်ထားရပါမည် (quan-erp base:dev)
@quan-erp/cli on npm →

1. မစတင်မီ

CLI ဖြင့် ဖန်တီးထားသော Quark ERP project တစ်ခုနှင့် လည်ပတ်နေသော base app လိုအပ်ပါသည်။

  • quan-erp new-project ဖြင့် project ကို scaffold လုပ်ပြီးသား ဖြစ်ရပါမည် (Installation)
  • @quan-erp/cli ကို global သွင်းထားရပါမည် — npm i -g @quan-erp/cli
  • Base stack လည်ပတ်နေရပါမည် — quan-erp base:dev
  • Node.js 18+ နှင့် @quan-erp/* အတွက် အသုံးပြုနိုင်သော ~/.npmrc လိုအပ်ပါသည်
  • Plugin အမည်ကို lowercase kebab-case ဖြင့် ရွေးချယ်ပါ (ဥပမာ fleet-management၊ hr၊ inventory)
TSQuick check
quan-erp help quan-erp base:dev # if base is not already up

2. Plugin ကို scaffold လုပ်ခြင်း

ဗလာ plugin အသစ် လိုအပ်ပါက CLI ကို အသုံးပြုပါ။ Menu၊ page နှင့် API ပုံစံများ ပါရှိသော နမူနာ လိုအပ်ပါက 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. အမည်များ ကိုက်ညီအောင် ညှိခြင်း (အရေးကြီး)

Folder၊ metadata.name နှင့် package.json အမည်များ မတူညီပါက watch၊ install နှင့် DI တို့တွင် ရှုပ်ထွေးသော အမှားများ ဖြစ်နိုင်ပါသည်။ CLI က အများအားဖြင့် ဖြည့်ပေးသော်လည်း၊ scaffold ပြီးတိုင်း ထပ်မံ စစ်ဆေးရပါမည်။

  • 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 package.json ရှိ @quan-erp/* မှီခိုမှုများသည် base image / BASE_VERSION နှင့် တူညီရပါမည်။ ဗားရှင်း မတူညီပါက မျှဝေအသုံးပြုသည့် သဘောတူညီချက်များ ချိုးဖျက်နိုင်ပါသည်။

  • 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. ပထမဆုံး feature ထည့်သွင်းခြင်း

ပထမ ပြောင်းလဲမှုကို သေးငယ်အောင် ထားရှိပါ — backend တွင် entity + service + controller တစ်ခု၊ frontend တွင် page + api hook + menu/route တို့ ဖြစ်ပါသည်။ Folder အမည်များကို 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 ဖြင့် တည်ဆောက်ခြင်း

Project root မှ watch သည် backend နှင့် frontend ကို compile လုပ်ပြီး၊ artifact များကို base/available-plugins/<name>/<version>/ သို့ ကူးယူပါသည်။

  • 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 row ကို INSERT လုပ်၍ plugin ကို ERP UI တွင် ပေါ်စေပြီး၊ Install ဖြင့် installed-plugins သို့ ကူးယူပါသည်။ UAT သို့မဟုတ် production တွင် 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 output၊ ဒေသခံ seed နှင့် UI install တို့ကို စစ်ဆေးပါ။

  • @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၊ Folder structure၊ CLI၊ Backend / Frontend 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