@quan-erp/shared-types 1.0.0

package/README.md

@@ -0,0 +1,80 @@
+# Quan ERP Shared Types
+
+The central contract repository for the Quan ERP system. This library defines the standardized interfaces, enums, and type aliases that provide type safety and structural consistency across the backend, frontend, and all modular plugins.
+
+---
+
+## 🔌 Plugin Architecture Contracts
+
+These interfaces define how plugins interact with the core kernel during their lifecycle.
+
+### `IPlugin`
+The primary interface for all backend plugins. It dictates the required hooks for installation, uninstallation, and readiness:
+-   **`onInstall`**: Triggered when the plugin is first added, receiving the `IAppInstance` bridge.
+-   **`onReady`**: Triggered once the plugin and all its dependencies are fully initialized.
+-   **`onMigrate`**: Handles versioned database schema transformations.
+-   **`getMigrations`**: Returns the list of `IDatabaseMigrationClass` to be executed.
+
+### `PluginMetadata`
+Defines the structure of the mandatory `module.metadata.json` file.
+-   **`name`**: Unique identifier for the plugin.
+-   **`pluginDependencies`**: A map of required plugins and their semantic versions.
+-   **`requiredBasedVersion`**: The minimum kernel version required for compatibility.
+
+### `IAppInstance`
+The "Bridge" provided by the kernel to a plugin during `onInstall`. It allows plugins to:
+-   Resolve services from the core container.
+-   Access data sources from other plugins.
+-   Check installation status of optional dependencies.
+
+---
+
+## 🎨 Frontend Orchestration Types
+
+Standardizes the way frontend modules register their UI elements into the global ERP shell.
+
+### `AppRegistryState`
+The contract for the global Zustand store managed by the frontend core. It includes:
+-   **`route.add()`**: For registering new page routes.
+-   **`menu.add()`**: For injecting items into the sidebar navigation.
+-   **`portal.add()`**: For injecting elements into global UI zones (e.g., header, status bar).
+-   **`report.add()`**: For registering items in the centralized reporting module.
+
+### Navigation Hierarchy
+-   **`Menu`**: Unified type for navigation items.
+-   **`GroupMenu`**: A parent item with nested `children`.
+-   **`SingleMenu`**: A terminal navigation item mapped to a specific path.
+
+---
+
+## 🏗️ Backend & Infrastructure Types
+
+### Database Migrations
+-   **`IDatabaseMigration`**: The contract for `up` and `down` database transformations.
+-   **`IDatabaseMigrationClass`**: Type alias for the constructor of a migration.
+
+### Cross-Plugin Features
+-   **`PluginExposedFeature`**: Defines how a plugin exposes its internal APIs to other modules in the system.
+
+---
+
+## 👤 Common Domain Entities
+
+Basic structures shared across all layers of the ERP to ensure data consistency.
+
+-   **`UserInfo`**: Comprehensive user profile including role metadata and status.
+-   **`ApiPermission`**: Mapping of HTTP methods and URLs to formal system permissions.
+-   **`HttpMethod`**: Standardized string literal types for RESTful operations.
+
+---
+
+## 📜 Usage Guidelines
+
+1.  **Strict Compliance**: All plugins MUST implement the `IPlugin` interface to be recognized by the `AppFactory`.
+2.  **Metadata Accuracy**: Ensure `module.metadata.json` aligns with the `PluginMetadata` interface to prevent dependency resolution errors.
+3.  **Cross-Plugin Safety**: Use the `PluginExposedFeature` types when interacting with APIs from other modules.
+
+---
+
+> [!NOTE]
+> This package should be considered a **stable contract**. Breaking changes here will require updates across the entire plugin ecosystem.

package/dist/backend-plugin-type.d.ts

@@ -0,0 +1,66 @@
+import { DataSource, QueryRunner } from 'typeorm';
+export interface IAppInstance {
+    getAppId(): string;
+    getPlugin(name: string): PluginExposedFeature | undefined;
+    getPluginInfo(name: string): PluginMetadata | undefined;
+    getDetail(): BaseDetail;
+    getBuildin(): any;
+    getDataSource(pluginName: string, name: string): Promise<DataSource | undefined | null>;
+    getEntity(cls: any, pluginName: string, name: string): any | null;
+    checkIsInstalled(name: string): boolean;
+    findInstance<T>(cls: new (...args: any[]) => T, pluginName: string, name: string): T;
+}
+export type MobilePluginType = 'mobile-frontend';
+export type WebPluginType = 'web-frontend';
+export type DesktopPluginType = 'desktop-frontend';
+export type BackendPluginType = 'backend' | 'middleware' | 'datasource' | 'assets';
+export type PluginType = MobilePluginType | WebPluginType | DesktopPluginType | BackendPluginType;
+export interface PluginMetadata {
+    name: string;
+    displayName?: string;
+    pluginVersion: string;
+    type: PluginType | string;
+    description: string;
+    moduleEntryObject: string;
+    requiredBasedVersion: string;
+    pluginDependencies: {
+        [key: string]: string;
+    };
+}
+export interface IDatabaseMigration {
+    getName(): string;
+    up(queryRunner: QueryRunner): Promise<void>;
+    down(queryRunner: QueryRunner): Promise<void>;
+    getSource(): {
+        plugin: string;
+        name: string;
+    };
+}
+export interface PluginExposedFeature {
+    getApi<T>(name: string): T;
+    info(): PluginMetadata;
+}
+export type IDatabaseMigrationClass = new () => IDatabaseMigration;
+export type GetMigrationsType = (IDatabaseMigrationClass | IDatabaseMigrationClass[])[];
+export interface IPlugin {
+    getName(): string;
+    getVersion(): string;
+    getAppModule(): PluginExposedFeature | undefined;
+    getRootModule(): any;
+    getMetadata(): PluginMetadata;
+    getMigrations(): GetMigrationsType;
+    onInstall(appContext: IAppInstance): void;
+    onUninstall(): Promise<void>;
+    onInstallError(err: any): void;
+    onUninstallError(err: any): void;
+    onMigrate(options: {
+        installedPluginVersion: number;
+    }): void;
+    onReady(): void;
+    isReady(): boolean;
+    isHealthy(): boolean;
+}
+export interface BaseDetail {
+    version: number;
+    name: string;
+}

package/dist/backend-plugin-type.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './plugin.js';
+export * from './backend-plugin-type.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './plugin.js';
+export * from './backend-plugin-type.js';

package/dist/plugin.d.ts

@@ -0,0 +1,153 @@
+import type { ReactElement } from "react";
+import type { AxiosInstance } from 'axios';
+import type { PluginMetadata } from "./backend-plugin-type.js";
+import type { QueryClient } from "@tanstack/react-query";
+export interface PluginModule {
+    register: (AppRegistry: any) => Promise<void> | void;
+    onAllPluginInstalled?: (AppRegistry: any) => Promise<void> | void;
+    onPluginInstalled?: (AppRegistry: any) => Promise<void> | void;
+    onBeforeInstall?: (AppRegistry: any) => Promise<void> | void;
+    pickFile?: () => Promise<string | string[]>;
+}
+export interface UserInfo {
+    username: string;
+    name: string;
+    roleId: number;
+    accessToken: string;
+    refreshToken: string;
+    isOwner: boolean;
+    createDate: string;
+    updateDate: string;
+    deleteDate: string | null;
+    version: number;
+    id: number;
+}
+export interface SettingComponents {
+    pluginName: string;
+    element: ReactElement;
+    routes?: {
+        path: string;
+        element: ReactElement;
+    }[];
+}
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS' | 'HEAD';
+export type ApiPermission = {
+    method: HttpMethod;
+    url: string;
+};
+export type WithApiMetadataFetchFn<T extends (...args: any[]) => any = (...args: any[]) => any> = {
+    api: ApiPermission;
+    fetchFn: T;
+};
+export declare function withApiMetadataFetchFn<T extends (...args: any[]) => any>(p: WithApiMetadataFetchFn<T>): WithApiMetadataFetchFn<T>;
+export type Route = {
+    path: string;
+    element: ReactElement;
+    description?: string;
+};
+export type PageRoute = Route | Route[];
+export type Component = string | ReactElement | ReactElement[];
+export type SingleMenu = {
+    name: Component;
+    path: string;
+    pluginName?: string;
+    description?: string;
+    sortNumber?: number;
+    requiredApis?: ApiPermission | ApiPermission[] | (() => ApiPermission | ApiPermission[]) | WithApiMetadataFetchFn<any> | WithApiMetadataFetchFn<any>[] | (ApiPermission | WithApiMetadataFetchFn<any>)[];
+};
+export type GroupMenu = {
+    name: Component;
+    path?: string;
+    pluginName?: string;
+    description?: string;
+    sortNumber?: number;
+    requiredApis?: ApiPermission | ApiPermission[] | (() => ApiPermission | ApiPermission[]);
+    children: Menu[];
+};
+export type Menu = SingleMenu | GroupMenu;
+export type RootRoute = {
+    path: string;
+    pluginName?: string;
+    element?: ReactElement;
+    children?: RootRoute[];
+};
+export type PagePermissionRouteStore = Record<string, Record<string, {
+    description: string;
+}>>;
+export type Optional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+export type NavMenuItem = {
+    pluginName: string;
+    element: ReactElement;
+};
+export type DashboardItems = {
+    id: string;
+    pluginName: string;
+    element: ReactElement;
+};
+export type Report = {
+    pluginName: string;
+    page: ReactElement;
+};
+export type PluginInfo = {
+    name: string;
+    displayName: string;
+    version: string;
+};
+export interface AppRegistryState {
+    locale: string;
+    setLocale: (locale: string) => void;
+    routes: PageRoute[];
+    route: {
+        add: (route: PageRoute) => void;
+    };
+    menus: Optional<Menu, 'pluginName'>[];
+    menuState: {
+        isMinimize: boolean;
+        allowSwipeToOpen: boolean;
+    };
+    menu: {
+        add: (menu: Menu) => void;
+        minimize(): void;
+        maximize(): void;
+        allowSwipeToOpen(allow: boolean): void;
+    };
+    queryClient: QueryClient;
+    rootRoutes: RootRoute[];
+    rootRoute: {
+        add: (route: RootRoute) => void;
+    };
+    userInfo: UserInfo | null;
+    user: {
+        getInfo: () => void;
+        getAccessToken: () => void;
+        isLogin: () => boolean;
+        setUser: (user: UserInfo) => void;
+        logout: () => void;
+    };
+    getAxiosClient: () => AxiosInstance;
+    plugins: PluginInfo[];
+    plugin: {
+        getInstalled: () => [];
+        install: (plugin: PluginInfo) => void;
+        isInstalled: (name: string) => boolean;
+    };
+    settings: SettingComponents[];
+    setting: {
+        add(setting: SettingComponents): void;
+    };
+    dashboards: DashboardItems[];
+    dashboard: {
+        add(item: DashboardItems): void;
+    };
+    portals: ReactElement[];
+    portal: {
+        add(element: ReactElement): void;
+    };
+    reports: Record<string, ReactElement>;
+    report: {
+        add(item: Report): void;
+    };
+}
+export type PluginMetadataInfo = PluginMetadata & {
+    installed: boolean;
+};

package/dist/plugin.js

@@ -0,0 +1,3 @@
+export function withApiMetadataFetchFn(p) {
+    return p;
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@quan-erp/shared-types",
+  "version": "1.0.0",
+  "description": "",
+  "main": "types/index.d.ts",
+  "types": "types/index.d.ts",
+  "scripts": {
+    "publish:registry": "npm run build && npm publish --tag beta",
+    "publish:npm-registry": "npm run build && npm publish --access public --tag beta --registry https://registry.npmjs.org/ --@quan-erp:registry=https://registry.npmjs.org/",
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "release:beta": "npm publish --tag beta",
+    "build": "tsc"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "keywords": [],
+  "author": "",
+  "license": "UNLICENSED",
+  "type": "module",
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.2.7",
+    "react": "19.2.6",
+    "@tanstack/react-query": "5.90.10"
+  },
+  "peerDependencies": {
+    "axios": "^1.13.2",
+    "react": "19.2.6",
+    "typeorm": "^0.3.27",
+    "@tanstack/react-query": "^5.90.10"
+  },
+  "dependencies": {}
+}