1. 设计哲学：契约优先，中心最小化

EAMX 的插件化架构遵守两条核心原则：

中心只做注册和调度：PluginRegistry 不关心业务逻辑，只管"谁注册了""有什么权限""路由前缀是什么"
一切通过契约交互：插件只需实现 PluginManifest 接口，不关心其他插件的存在

这与微内核架构一致：内核越小，系统越稳定。

2. PluginManifest 契约

``typescript interface PluginManifest { id: string; // 唯一标识，如 "equipment" name: string; // 显示名称 version: string; // 语义化版本 description?: string; dependencies?: string[]; // 插件依赖（加载顺序约束） tier: 0 | 1 | 2 | 3; // 插件分层 // 生命周期钩子 lifecycleHandlers?: Partial<LifecycleHandlerMap>; // 资源注册 createRouter?: () => Router; // Express Router 工厂 routePrefix?: string; // 路由前缀，如 "/api/equipment" permissions: PermissionDefinition[]; // CASL 权限定义 navItems?: NavItem[]; // 前端导航项 cronJobs?: CronJobDefinition[]; // 定时任务 } ``

Tier 分层设计：

| Tier | 说明 | 示例 | |---|---|---| | Tier 0 | 平台核心（不可卸载） | auth、tenant | | Tier 1 | 基础业务（EAM 基础功能） | equipment、spare-part | | Tier 2 | 业务增强（可选） | pm-plan、purchase | | Tier 3 | 实验/社区（可热拔插） | mockup、sandbox |

Tier 决定了卸载时的影响范围和降级策略。

3. PluginRegistry 核心实现

```typescript class PluginRegistry { private plugins = new Map<string, PluginManifest>();

register(plugin: PluginManifest): void { // ① 幂等检查：不允许重复注册 if (this.plugins.has(plugin.id)) throw new Error(Plugin "${plugin.id}" is already registered);

// ② 依赖检查：所有 dependencies 必须已注册 for (const dep of plugin.dependencies ?? []) { if (!this.plugins.has(dep)) throw new Error(Plugin "${plugin.id}" depends on "${dep}" which is not registered); }

// ③ 自动注册生命周期钩子 if (plugin.lifecycleHandlers) { for (const [event, handler] of Object.entries(plugin.lifecycleHandlers)) { lifecycle.on(event as LifecycleEvent, handler); } }

this.plugins.set(plugin.id, plugin); }

// 将所有已注册插件的路由挂载到父 Router mountAll(router: Router): void { for (const [, plugin] of this.plugins) { if (!plugin.createRouter) continue; router.use(plugin.routePrefix ?? "/", plugin.createRouter()); } }

// 聚合所有插件的权限定义 getAllPermissions(): PermissionDefinition[] { return [...this.plugins.values()].flatMap(p => p.permissions); }

// 聚合所有导航项，按 order 排序 getAllNavItems(): NavItem[] { return [...this.plugins.values()] .flatMap(p => p.navItems ?? []) .sort((a, b) => (a.order ?? 99) - (b.order ?? 99)); } } ```

74 行，6 个方法，没有状态机、没有复杂配置——这正是"核心最小化"的体现。

4. LifecycleBus：观察 + 拦截双模式

```typescript class LifecycleBus { private handlers = new Map<string, AnyHandler[]>();

// 观察型事件：并行执行，单个失败不阻断主流程 async emit<T>(event: string, payload: T, ctx: RequestContext): Promise<void> { const handlers = this.handlers.get(event) ?? []; const results = await Promise.allSettled( handlers.map(h => h({ payload, ctx })) ); // 失败仅打日志，不抛异常 }

// 拦截型事件：串行执行，支持修改 payload 或中断（AbortError） async intercept<T>(event: string, payload: T, ctx: RequestContext): Promise<T> { let current = { ...payload }; for (const handler of handlers) { await handler({ payload: current, ctx, intercept: (modified) => { current = { ...current, ...modified }; }, abort: (reason) => { abortReason = reason; }, }); if (abortReason) throw new AbortError(abortReason); } return current; } } ```

双模式设计解决了两类核心需求：

| 模式 | 用例 | 行为 | |---|---|---| | emit（观察） | 通知、日志、缓存失效 | 并行，失败不阻塞，fire-and-forget | | intercept（拦截） | 审批流、数据校验、权限注入 | 串行，可修改 payload，可 AbortError 中断 |

典型拦截场景：设备创建前 → approval 插件检查审批策略 → 满足条件继续 / 不满足则 abort("需要审批")。

5. 插件示例：审批流插件

``typescript // approval-plugin.ts（简化版） export const approvalPlugin: PluginManifest = { id: "approval", name: "审批流", version: "1.0.0", tier: 1, dependencies: ["auth"], permissions: [ { action: "approve", subject: "WorkOrder" }, { action: "approve", subject: "PurchaseRequest" }, ], routePrefix: "/api/approval", createRouter: () => { const router = Router(); router.get("/pending", listPendingApprovals); router.post("/:id/approve", approveRequest); router.post("/:id/reject", rejectRequest); return router; }, lifecycleHandlers: { "equipment:beforeCreate": async ({ payload, abort }) => { if (payload.value > 100000) { // 超过 10 万元需要审批 abort("设备价值超过10万元，需要主管审批"); } }, }, }; ``

插件完全通过契约定义自己的行为——PluginRegistry 不需要知道审批流的存在。

6. 与 Tier 0 插件的依赖关系

`` Tier 0: auth, tenant (不可卸载) ↑ Tier 1: equipment, spare-part, work-order, fault-report, pm-plan, approval, notification ↑ Tier 2: purchase, inventory, report ↑ Tier 3: mockup (实验性) ``

启动时按依赖拓扑排序加载，确保 Tier 0 最先注册。Tier 3 插件加载失败不影响系统启动。

7. 核心文件索引

| 文件 | 行数 | 职责 | |---|---|---| | packages/core/src/plugin-registry.ts | 74 | 插件注册、路由挂载、权限/导航聚合 | | packages/core/src/lifecycle-bus.ts | 79 | emit/拦截事件总线 | | packages/core/src/types.ts | — | PluginManifest 接口定义 |

下一篇：CASL 同构权限系统——15 个 Actions × 26 个 Subjects，前后端零差异鉴权。