插件机制与扩展体系

平台内置能力 vs 长尾需求：
  内置能力覆盖 80% 的通用场景
  长尾 20% 高度定制，平台无法预判

两条路：
  A. 平台内置所有 → 臃肿、迭代慢、永不完备
  B. 开放插件体系 → 平台保持精简，能力外挂

结论：成熟平台必然走向 B
  但 B 的前提是「扩展点设计得当」

前端扩展点：
  - 自定义组件（字段、图表、布局容器）
  - 自定义属性编辑器（属性面板的控件）
  - 自定义动作（事件处理）
  - 自定义主题

后端扩展点：
  - 数据源连接器（连接新数据库/API）
  - 认证方式（SSO、OAuth 提供方）
  - 自定义函数（表达式里可调用的函数）
  - 钩子（数据保存前后的拦截）

流程扩展点：
  - 自定义节点类型
  - 任务分配策略
  - 通知渠道

{
  "id": "com.acme.chart-plugin",
  "name": "Acme 高级图表",
  "version": "1.4.0",
  "platformApi": "^2.0.0",
  "main": "dist/index.js",
  "contributes": {
    "components": [
      { "type": "acmeFunnel", "name": "漏斗图", "group": "图表" }
    ],
    "connectors": [
      { "id": "acme-mq", "name": "Acme 消息队列" }
    ],
    "functions": [
      { "name": "acmeScore", "signature": "(a: number) => number" }
    ]
  },
  "permissions": ["network", "storage"]
}

生命周期：
  install → activate(api) → [运行] → deactivate() → uninstall

interface PluginContext {
  api: PlatformApi;                 // 平台能力
  logger: Logger;
  storage: PluginStorage;           // 插件私有存储
  dispose: () => void;
}

interface PluginModule {
  activate(ctx: PluginContext): void | Promise<void>;
  deactivate?(): void | Promise<void>;
}

版本策略（语义化版本）：
  主版本：破坏性变更，插件需适配
  次版本：新增能力，向后兼容
  补丁：修复，无接口变化

兼容声明：
  插件清单声明 platformApi: "^2.0.0"
  平台加载时校验，不兼容则拒绝激活并告警

function checkCompatibility(plugin: PluginManifest, platform: string): boolean {
  const range = parseRange(plugin.platformApi);
  return satisfies(platform, range);
}

隔离层次：
  1. 前端：iframe / Web Worker / ShadowRealm / 受限全局
  2. 后端：独立进程 / 容器 / WASM
  3. 权限：清单声明 + 运行时校验

前端沙箱方案对比：
  iframe：隔离强，但通信成本高、样式隔离
  Worker：隔离计算，无法操作 DOM
  受限全局：轻量，但难防原型链污染

// 受限全局：把危险 API 从插件作用域中移除
function createSandbox(pluginCode: string) {
  const safeGlobal = {
    console, setTimeout, clearTimeout, JSON, Math, Date,
    // 不提供：fetch（改由 api.network 代理并审计）、eval、Function
  };
  const fn = new Function('api', 'global', `"use strict";${pluginCode}`);
  return fn(pluginApi, safeGlobal);
}

// 插件注册一个自定义字段组件
export function activate(ctx: PluginContext) {
  ctx.api.registerComponent('acmeFunnel', {
    name: '漏斗图',
    group: '图表',
    props: [
      { name: 'data', label: '数据', type: 'expr' },
      { name: 'colors', label: '配色', type: 'select', options: [...] },
    ],
    component: AcmeFunnel,     // React 组件，遵守字段协议
  });
}

interface Connector {
  id: string;
  meta: {
    name: string;
    configFields: PropSchema[];   // 连接配置表单
    capabilities: ('query' | 'write' | 'schemaSync')[];
  };
  testConnection(config: Record<string, unknown>): Promise<boolean>;
  query(config: unknown, query: Query): Promise<ResultSet>;
  schemaSync?(config: unknown): Promise<TableSchema[]>;
}

{
  "id": "acme-mq",
  "meta": {
    "name": "Acme 消息队列",
    "configFields": [
      { "name": "endpoint", "label": "地址", "type": "string" },
      { "name": "token", "label": "令牌", "type": "string", "secret": true }
    ],
    "capabilities": ["query"]
  }
}

// 自定义表达式函数
ctx.api.registerFunction('acmeScore', (args, ctx) => {
  const [base, factor] = args as [number, number];
  return base * factor;
});

// 数据钩子
ctx.api.on('entity.beforeSave', async (event) => {
  if (event.entity === 'order' && event.data.amount > 100000) {
    event.data.requiresReview = true;
  }
});

依赖管理：
  - 插件声明 dependencies: { "com.acme.base": "^1.0.0" }
  - 平台按拓扑序激活
  - 循环依赖必须拒绝

分发方式：
  - 私有市场（企业内部）
  - 公共市场（第三方）
  - 本地安装（开发调试）
  - 离线包（内网环境）

隔离：
  每个插件的依赖应打包进自身 bundle
  避免与平台或其他插件共享可变模块

治理要点：
  - 上架审核：权限声明、代码扫描、性能基线
  - 权限最小化：只授予必要的 network/storage 权限
  - 运行时监控：插件耗时、异常率、内存占用
  - 熔断：某插件异常率超阈值自动禁用
  - 版本锁定：生产环境锁定插件版本，避免自动升级
  - 下线机制：支持远程禁用问题插件

// 插件运行时熔断
class PluginGuard {
  private errors = 0;
  private windowStart = Date.now();

  record(ok: boolean) {
    if (Date.now() - this.windowStart > 60_000) {
      this.errors = 0; this.windowStart = Date.now();
    }
    if (!ok) this.errors++;
    if (this.errors > 50) this.disable('error rate too high');
  }
}