ခြုံငုံသုံးသပ်ချက်
Shell က Reports အပိုင်းကို ပိုင်ဆိုင်ပါသည်။ Plugin သည် register() အတွင်း page element တစ်ခု မှတ်ပုံတင်ရပါသည် — အများအားဖြင့် report တစ်ခုချင်းစီအတွက် nested Routes ပါသော hub သေးသေးဖြစ်ပါသည်။ Aggregation အလေးများကို backend တွင် ထားရှိပြီး၊ frontend သည် withApiMetadataFetchFn နှင့် React Query ဖြင့် ဒေတာကို တင်သွင်းပါသည်။
- AppRegistry.report.add({ pluginName, page }) ဖြင့် မှတ်ပုံတင်ပါ
- page သည် အများအားဖြင့် hub နှင့် nested <Routes> ဖြစ်ပါသည်
- Sub-path များသည် relative ဖြစ်ရပါမည် (leading / မပါရပါ)
- Report query များနှင့် တူညီသော API များဖြင့် ခွင့်ပြုချက် ထိန်းချုပ်ပါ
၁။ AppRegistry.report.add ဖြင့် မှတ်ပုံတင်ခြင်း
frontend/src/index.tsx အတွင်း PluginModule.register မှ AppRegistry.report.add ကို ခေါ်ပါ။ ပုံစံမှာ { pluginName, page } ဖြစ်ပြီး page သည် ReactElement ဖြစ်ရပါမည်။
- pluginName သည် module.metadata.json ၏ name နှင့် တူရပါမည်
- page သည် JSX (<MyModuleReports />) ဖြစ်ရပါမည် — component type မဟုတ်ပါ
1import type { AppRegistryState, PluginModule } from "@quan-erp/shared-types";
2import metadata from "../module.metadata.json" with { type: "json" };
3import { MyModuleReports } from "./page/report";
4
5const Plugin: PluginModule = {
6 register(AppRegistry: AppRegistryState) {
7 AppRegistry.report.add({
8 pluginName: metadata.name,
9 page: <MyModuleReports />,
10 });
11 },
12};
13
14export default Plugin;၂။ Report hub နှင့် nested routes
Report များစွာရှိလျှင် landing hub (card grid) တည်ဆောက်ပြီး deep link အလုပ်လုပ်ရန် nested Routes ထားပါ။ Sub-path များသည် parent report route အပေါ် relative ဖြစ်ရပါမည် — employees သုံးပါ၊ /employees မသုံးရပါ။
- Deep-linking အတွက် react-router-dom <Routes> / <Route> သုံးပါ
- Index route = hub၊ child routes = report တစ်ခုချင်း
- ခေါင်းစဉ်နှင့် ဖော်ပြချက်များကို localize လုပ်ပါ — production plugin တွင် user-facing string ကို hardcode မလုပ်ရပါ
1import { Route, Routes, useNavigate } from "react-router-dom";
2import { Page, PageContent, PageTitle } from "@quan-erp/shared-ui";
3import metadata from "../../../module.metadata.json" with { type: "json" };
4import { EmployeesReport } from "./employees-report";
5
6const reportList = [
7 {
8 id: "employees",
9 name: "Employees",
10 description: "Headcount and status breakdown",
11 path: "employees",
12 element: <EmployeesReport />,
13 },
14];
15
16export function MyModuleReports() {
17 const navigate = useNavigate();
18
19 return (
20 <Routes>
21 <Route
22 index
23 element={
24 <Page pluginName={metadata.name}>
25 <PageTitle>
26 <span>Module reports</span>
27 </PageTitle>
28 <PageContent>
29 <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6 mt-4">
30 {reportList.map((item) => (
31 <button
32 key={item.id}
33 type="button"
34 className="text-left border rounded-xl p-4 hover:shadow-md transition"
35 onClick={() => navigate(item.path)}
36 >
37 <div className="font-medium">{item.name}</div>
38 <div className="text-sm text-muted-foreground">
39 {item.description}
40 </div>
41 </button>
42 ))}
43 </div>
44 </PageContent>
45 </Page>
46 }
47 />
48 {reportList.map((item) => (
49 <Route key={item.path} path={item.path} element={item.element} />
50 ))}
51 </Routes>
52 );
53}၃။ Data layer
Report ဒေတာကို src/api မှ withApiMetadataFetchFn နှင့် React Query hooks ဖြင့် တင်သွင်းပါ (Admin Axios & Query ပုံစံအတိုင်း)။ Grouping / filtering အလေးများကို backend တွင် ထားရှိပါ။
- Report endpoint များကို .api.ts တွင် ကြေညာပြီး .queries.ts မှ သုံးပါ
- requiredApis / Protected သို့ တူညီသော API object များ ပေးပါ
- Browser သို့ raw table ကြီးများ မပို့ဘဲ server-side aggregate ကို ဦးစားပေးပါ
၄။ Tables
Report အများစုသည် ဇယားသုံးပါသည်။ DataTable ကို @quan-erp/shared-ui မှ export မလုပ်ပါ — shared-ui Table primitives ပေါ်တွင် တည်ဆောက်ထားသော plugin အတွင်း local DataTable (မကြာခဏ components/ အောက်) ကို သုံးပါ၊ သို့မဟုတ် အခြား plugin (ဥပမာ hr) မှ ပုံစံကို ကူးယူပါ။
import { DataTable } from "../../components/DataTable";
// columns + rows from your report query hook
<DataTable columns={columns} data={rows} />အရေးကြီးသော စည်းကမ်းများ
- register() အတွင်း AppRegistry.report.add ဖြင့်သာ မှတ်ပုံတင်ပါ
- pluginName သည် metadata.name နှင့် တူရပါမည်
- page သည် ReactElement (JSX) ဖြစ်ရပါမည်
- Nested report path များသည် relative ဖြစ်ရပါမည် — leading slash မပါရပါ
- Hub နှင့် report UI string များကို localize လုပ်ပါ
- Hub တွင် entry များစွာရှိလျှင် report page အလေးများကို lazy-load လုပ်ပါ
စစ်ဆေးရန်စာရင်း
- nested Routes ပါသော page/report hub ဖန်တီးပါ
- register() တွင် AppRegistry.report.add({ pluginName, page }) ခေါ်ပါ
- withApiMetadataFetchFn + React Query ဖြင့် report API များ ချိတ်ဆက်ပါ
- Relative sub-path သုံးပြီး label များကို localize လုပ်ပါ
- quan-erp watch နှင့် install ပြီးနောက် Reports အောက်တွင် စစ်ဆေးပါ
အဖြစ်များသော ပြဿနာများ
- Hub တွင် report မပေါ် — မမှတ်ပုံတင်ခြင်း၊ pluginName မှားခြင်း၊ သို့မဟုတ် plugin မ install ရသေးခြင်း
- Nested page ဗလာ — path တွင် leading / သုံးမိခြင်း သို့မဟုတ် Route path နှင့် မကိုက်ခြင်း
- Deep link 404 — nested <Routes> / index route ပျောက်နေခြင်း
- Permission error — report UI ကို query နှင့် တူသော requiredApis ဖြင့် မထိန်းခြင်း
- Payload ကြီး / UI နှေး — aggregation ကို client တွင် လုပ်ထားခြင်း