LinaPro Plugins

official-plugins is the official source-plugin workspace for LinaPro.

When mounted into the main linapro repository, this workspace appears at apps/lina-plugins/.

At the current open-source stage, the host keeps only stable core capabilities such as user management, role management, menu management, dictionary management, parameter settings, file management, scheduled job management, plugin governance, and developer support. Non-core business modules are delivered as source plugins under apps/lina-plugins/<plugin-id>/.

What Lives Here

LinaPro currently ships these plugin references in this directory:

• linapro-demo-source: sample source plugin structure and coding reference
• linapro-demo-dynamic: sample dynamic WASM plugin structure and lifecycle reference
• official source plugins: first-party business plugins compiled into the host through explicit wiring

Using as a Submodule

The main linapro repository mounts this repository at apps/lina-plugins using:

git submodule update --init --recursive

For local submodule management in a checked-out linapro workspace, the SSH remote is:

git@github.com:linaproai/official-plugins.git

Official Source Plugins

The repository currently includes these first-party source plugins:

• linapro-ops-demo-guard: demo-environment read-only request guard
• linapro-org-core: department management and post management
• linapro-content-notice: notice management
• linapro-monitor-online: online user query and force logout
• linapro-monitor-server: server monitor collection, cleanup, and query
• linapro-monitor-operlog: operation log persistence and governance
• linapro-monitor-loginlog: login log persistence and governance

Each official plugin has its own directory and follows the same baseline structure:

apps/lina-plugins/<plugin-id>/
  backend/
    api/                Plugin API DTOs and route contracts
    internal/
      controller/       Plugin HTTP controllers
      service/          Plugin business services
      dao/              Plugin-local generated DAO objects when database access exists
      model/do/         Plugin-local generated DO objects when database access exists
      model/entity/     Plugin-local generated entity objects when database access exists
    hack/config.yaml    Plugin-local GoFrame codegen config
    plugin.go           Plugin backend registration entry
  frontend/pages/       Plugin pages mounted by host menus
  manifest/sql/         Plugin-owned install SQL assets
  manifest/sql/mock-data/ Optional plugin-owned mock/demo SQL assets
  manifest/sql/uninstall/ Plugin-owned uninstall SQL assets
  hack/tests/e2e/       Optional plugin-owned E2E TC files
  hack/tests/pages/     Optional plugin-owned E2E page objects
  hack/tests/support/   Optional plugin-owned E2E helpers
  plugin.yaml           Plugin manifest
  plugin_embed.go       Embedded asset registration
  README.md             English plugin guide
  README.zh-CN.md       Chinese plugin guide

backend/internal/service/ is the only valid location for plugin service components. Do not create backend/service/.

Host and Plugin Boundary

The host and source plugins are intentionally decoupled through stable seams instead of scattered if pluginEnabled branches.

• The host owns stable top-level menu catalogs such as dashboard, iam, setting, scheduler, extension, and developer.
• Plugin manifests choose their own parent_key mount points. The host only resolves the referenced menu record during sync and rejects missing parents to avoid orphaned menu trees.
• Official plugins keep their intended menu placement in their own plugin.yaml; the host does not hard-code official plugin IDs or force specific parent catalogs.
• The host publishes stable capability seams for optional collaboration, such as auth events, audit events, org capability access, and plugin lifecycle hooks.
• Plugin-owned tables, menus, pages, hooks, and cron jobs live in the plugin directory and are installed or removed through the plugin lifecycle.

HTTP Routes and Public Assets

Source-plugin HTTP routes are implementation details registered by plugin backend code. Do not declare public routes, portal routes, workspace API routes, or route groups in plugin.yaml.

Use registrar.Routes().APIPrefix() for source-plugin APIs. The returned prefix is /x/{plugin-id}; this plugin-owned namespace is mandatory, while segments after it are plugin-defined route content. A plugin may choose conventional paths such as /api/v1, /api/v2, or /interface/m1 under that prefix. Source plugins may still register non-reserved public routes such as /, /portal/*, or /assets/* for pages, portals, static resources, or plugin-managed fallback handlers.

plugin.yaml menus remains the source of truth for management workspace navigation and permissions. Registering an HTTP route does not create menus, permission nodes, OpenAPI entries, or workspace route metadata.

Source plugins and dynamic plugins may declare public static asset directories through plugin.yaml public_assets. The host serves only declared public assets from /x-assets/{plugin-id}/{version}/..., and treats each declaration as the plugin author's explicit publication boundary. Declarations must stay inside the plugin-owned resource set; traversal, absolute paths, URLs, wildcard paths, overlapping mounts, and symlink escapes are rejected.

Source Plugin Development Flow

1. Create apps/lina-plugins/<plugin-id>/.
2. Follow the structure used by linapro-demo-source/.
3. Declare metadata, menus, frontend pages, SQL assets, and optional hooks in plugin.yaml.
4. Keep plugin-owned backend code inside the plugin directory, place service logic under backend/internal/service/, and depend only on published host packages.
5. Register the plugin explicitly in apps/lina-plugins/lina-plugins.go.

Plugin-Owned E2E Tests

Source plugins should keep plugin-specific Playwright coverage under apps/lina-plugins/<plugin-id>/hack/tests/e2e/. Plugin page objects and helpers should stay beside them in hack/tests/pages/ and hack/tests/support/. The host test runner discovers these tests through the generic plugins scope, and a single plugin can be run with pnpm -C hack/tests test:module -- plugin:<plugin-id> without adding a plugin-specific entry to the execution manifest.

Source Plugin Version Upgrade

When a source plugin has already been installed in the host and you bump its plugin.yaml version, discovery no longer replaces the effective host version automatically.

• The current effective version stays pinned in sys_plugin.version and release_id.
• The higher discovered source version is stored as a prepared sys_plugin_release.
• Before the host is allowed to start, update the source plugin through the supported plugin workspace update flow.
• If you skip that step, host startup fails fast and prints the plugins that still need attention.

Dynamic Plugin Notes

Dynamic WASM plugins remain supported for runtime-managed delivery scenarios. Use linapro-demo-dynamic/ as the reference when the plugin must be uploaded, installed, enabled, disabled, and uninstalled without recompiling the host.

References

• apps/lina-plugins/linapro-demo-source/README.md
• apps/lina-plugins/linapro-demo-dynamic/README.md
• apps/lina-plugins/OPERATIONS.md