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.

License

QuarkERP License — owned by The Paradance, actively maintained and developed by Jian Shang Quan. You may use this package to build Quark ERP plugins. Copying or reuse for any other purpose is not permitted.