Plugin app data

Plugin များ persistent runtime files သိမ်းရန်နှင့် bundled backend assets ဖတ်ရန် အသုံးပြုပါသည်။ @quan-erp/shared-backend-core မှ AppFolder ကို အသုံးပြုရပါသည် — APP_DATA_FOLDER path ကို hardcode မလုပ်ရပါ။

ခြုံငုံသုံးသပ်ချက်

Data နှင့် assets ကို platform folder များတွင် ထားမှ Docker / staging / production တို့တွင် path များ တည်ငြိမ်ပါသည်။ AppFolder က process.env path များကို resolve ပေးပါသည်။

Runtime files → plugin data folder (APP_DATA_FOLDER အောက်)
Bundled static → backend/assets (install ပြီးနောက် read-only)
Temp / partial upload → app temp (ရှင်းလင်းနိုင်ပါသည်)
APP_DATA_FOLDER root သို့ တိုက်ရိုက် မရေးရပါ — plugin subdirectory သုံးရပါသည်

1. Application & plugin folders

Folder လေးခု အရေးကြီးပါသည်။ Global သည် env မှ၊ plugin folder များသည် plugin name (နှင့် assets အတွက် version) မှ ဆင်းသက်ပါသည်။

Folder	Path	Utility	အသုံး
App data (global)	process.env.APP_DATA_FOLDER	AppFolder.getAppDataFolder()	Persistent app data root — တိုက်ရိုက် မရေးရပါ
App temp	process.env.UPLOAD_FILE_TEMP_FOLDER	AppFolder.getAppTempDataFolder()	Temp / scratch — durable data မထားရပါ
Plugin data	<APP_DATA_FOLDER>/<pluginName>	AppFolder.getPluginDataFolder(pluginName)	Runtime data: export, report, disk cache
Plugin assets	<INSTALLED_PLUGINS_FOLDER>/<pluginName>/<version>/backend/assets	AppFolder.getPluginAssetFolder(pluginName, version)	Plugin package နှင့်ပါသော read-only assets

2. Data folder vs asset folder

App run နေစဉ် ဖန်တီး/ပြင်သော ဖိုင်များအတွက် data folder ကို အသုံးပြုရပါသည်။ Source နှင့်အတူ ship လုပ်ပြီး runtime တွင် မပြင်သော ဖိုင်များအတွက် asset folder ကို အသုံးပြုရပါသည်။

Data ဥပမာ — CSV, PDF report, local SQLite, runtime config
Asset ဥပမာ — document template, seed JSON, default icon

	Asset folder	Data folder
Purpose	Code နှင့် bundle လုပ်သော static files	Runtime တွင် ဖန်တီးသော dynamic files
Persistence	Reinstall / update တွင် အစားထိုးနိုင်ပါသည်	Plugin update ကျော်လွန် တည်ရှိပါသည်
Utility	getPluginAssetFolder(name, version)	getPluginDataFolder(name)
Source in repo	plugins/<name>/backend/assets/	Runtime တွင် disk ပေါ် ဖန်တီးပါသည်

3. AppFolder API

@quan-erp/shared-backend-core မှ AppFolder ကို import လုပ်ရပါသည်။ metadata.name နှင့် metadata.pluginVersion ကို အသုံးပြုရပါသည်။

Method	ဖော်ပြချက်
getAppDataFolder()	APP_DATA_FOLDER root
getAppTempDataFolder()	Temp upload / scratch
getPluginDataFolder(pluginName)	Plugin တစ်ခု၏ persistent data
getPluginAssetFolder(pluginName, version)	Installed backend/assets (versioned)

TSXresolve paths

import { AppFolder } from "@quan-erp/shared-backend-core";
import metadata from "../../module.metadata.json" with { type: "json" };
import fs from "node:fs/promises";
import path from "node:path";

const dataDir = AppFolder.getPluginDataFolder(metadata.name);
const assetDir = AppFolder.getPluginAssetFolder(
  metadata.name,
  metadata.pluginVersion,
);

// Persistent runtime file
await fs.mkdir(dataDir, { recursive: true });
await fs.writeFile(path.join(dataDir, "export.csv"), csv, "utf8");

// Bundled template (read-only)
const template = await fs.readFile(
  path.join(assetDir, "invoice-template.html"),
  "utf8",
);

4. Backend assets bundling

Static backend files ကို plugins/<name>/backend/assets/ တွင် ထားရှိရပါသည်။ Build / pack က bundle ထဲသို့ ကူးပြီး၊ install ပြီးနောက် getPluginAssetFolder ဖြင့် resolve လုပ်နိုင်ပါသည်။

backend/assets/ အောက်ရှိ အရာအားလုံး pack ပါဝင်ပါသည်
Install ပြီး getPluginAssetFolder(name, pluginVersion) သုံးရပါသည်
Asset folder သို့ runtime write မလုပ်ရပါ — getPluginDataFolder သုံးရပါသည်

SHsource layout

plugins/<plugin-name>/
└── backend/
    ├── assets/
    │   ├── invoice-template.html
    │   └── seed/
    │       └── defaults.json
    └── src/

စည်းမျဉ်းများ

Isolation — getPluginDataFolder(yourPluginName) အောက်တွင်သာ ရေးရပါသည်
Persistence — getAppTempDataFolder တွင် durable data မထားရပါ
Portability — AppFolder သုံးရပါသည်; path hardcode မလုပ်ရပါ
Versioned assets — getPluginAssetFolder သို့ pluginVersion ပေးရပါသည်