# WASM 插件系统设计 — 可行性分析与原型验证计划

> 基于 `docs/superpowers/specs/2026-04-13-wasm-plugin-system-design.md` 的全面审查

---

## 1. 总体评估

**结论：技术可行，但需要对设计做重要调整。**

设计方案的核心思路（WASM 沙箱 + 宿主代理 API + 配置驱动 UI）是正确的架构方向。Wasmtime v43.x + Component Model + WASI 0.2/0.3 已达到生产就绪状态。但设计中有 **7 个关键问题** 和 **5 个改进点** 需要在实施前解决。

**可行性评分：**

| 维度 | 评分 | 说明 |
|------|------|------|
| 技术可行性 | 8/10 | Wasmtime 成熟，核心 API 可用；动态表和事务支持需额外封装 |
| 架构兼容性 | 6/10 | 与现有 FromRef 状态模式、静态路由模式存在结构性冲突 |
| 安全性 | 9/10 | WASM 沙箱 + 权限模型 + 租户隔离设计扎实 |
| 前端可行性 | 7/10 | PluginCRUDPage 概念正确但实现细节不足 |
| 实施复杂度 | 高 | 估计 3 个 Phase、6-8 周工作量 |

---

## 2. 与现有代码的兼容性分析

### 2.1 现有架构快照

| 组件 | 现状 | 设计目标 | 差距 |
|------|------|----------|------|
| ErpModule trait | 7 个方法（name/version/dependencies/register_event_handlers/on_tenant_created/on_tenant_deleted/as_any） | 15+ 方法（新增 id/module_type/on_startup/on_shutdown/health_check/public_routes/protected_routes/migrations/config_schema） | **重大差距** |
| ModuleRegistry | `Arc<Vec<Arc<dyn ErpModule>>>`，Builder 模式注册，无路由收集 | 需要 build_routes()、topological_sort()、load_wasm_plugins()、health_check_all() | **重大差距** |
| EventBus | `tokio::broadcast`，仅有 subscribe()（全量订阅） | 需要 subscribe_filtered() + unsubscribe() | **中等差距** |
| 路由 | main.rs 手动 merge 静态方法 | registry.build_routes() 自动收集 | **中等差距** |
| 状态注入 | FromRef 模式（编译时桥接 AppState → 各模块 State） | WASM 插件需要运行时状态注入 | **结构性冲突** |
| 前端菜单 | MainLayout.tsx 硬编码 3 组菜单 | 从 PluginStore 动态生成 | **中等差距** |
| 前端路由 | App.tsx 静态定义，React.lazy 懒加载 | DynamicRouter 根据插件配置动态生成 | **中等差距** |

### 2.2 关键差距详解

**差距 1：ErpModule trait 路由方法缺失**

当前路由不是 trait 的一部分，而是每个模块的关联函数：

```rust
// 当前（静态关联函数，非 trait 方法）
impl AuthModule {
    pub fn public_routes<S: Clone + Send + Sync + 'static>() -> Router<S> { ... }
    pub fn protected_routes<S: Clone + Send + Sync + 'static>() -> Router<S> { ... }
}
```

设计将路由提升为 trait 方法，但这引入了泛型参数问题：`Router<S>` 中的 `S` 是 `AppState` 类型，而 trait 不能有泛型方法（会导致 trait 不是 object-safe）。需要设计新的路由注入机制。

**差距 2：FromRef 状态模式与 WASM 插件的冲突**

当前每个模块有自己的 State 类型（`AuthState`、`ConfigState` 等），通过 `FromRef` 从 `AppState` 桥接。WASM 插件无法定义编译时的 `FromRef` 实现，需要运行时状态传递机制。

**差距 3：EventBus 缺少类型化订阅**

`subscribe()` 返回 `broadcast::Receiver<DomainEvent>`，订阅者需要自行过滤。这会导致每个插件都收到所有事件，增加不必要的开销。设计中的 `subscribe_filtered()` 是必要的扩展。

---

## 3. 关键问题（Critical Issues）

### C1: 路由注入机制设计不完整

**问题：** 设计中的 `fn public_routes(&self) -> Option<Router>` 和 `fn protected_routes(&self) -> Option<Router>` 缺少泛型参数 `S`（AppState）。Axum 的 Router 依赖状态类型，而 trait object 不能携带泛型。

**影响：** 这是路由自动收集的基础。如果无法解决，整个 `registry.build_routes()` 的设计就不能实现。

**建议方案：**

```rust
// 方案：使用 Router<()>, 由 ModuleRegistry 在 build_routes() 时添加 .with_state()

pub trait ErpModule: Send + Sync {
    fn protected_routes(&self) -> Option<Router<()>> { None }
    fn public_routes(&self) -> Option<Router<()>> { None }
}

impl ModuleRegistry {
    pub fn build_routes(&self, state: AppState) -> (Router, Router) {
        let public = self.modules.iter()
            .filter_map(|m| m.public_routes())
            .fold(Router::new(), |acc, r| acc.merge(r))
            .with_state(state.clone());

        let protected = self.modules.iter()
            .filter_map(|m| m.protected_routes())
            .fold(Router::new(), |acc, r| acc.merge(r))
            .with_state(state);

        (public, protected)
    }
}
```

### C2: 事务支持缺失

**问题：** Host API 每次 db 调用都是独立事务。但 ERP 业务经常需要多步骤原子操作。

**建议：** 增加声明式事务，插件提交一组操作，宿主在单事务中执行。

### C3: 插件间依赖未解决

**建议：** Phase 7 暂不实现，在 plugin.toml 中预留 `plugins = [...]` 字段。

### C4: 版本号严重过时

**建议：** 锁定 `wasmtime = "43"` + `wit-bindgen = "0.55"`。

### C5: 动态表 Schema 迁移策略缺失

**建议：** 添加 schema_version + 迁移 SQL 机制。

### C6: PluginCRUDPage 实现细节不足

**建议：** 扩展关联数据、主从表、文件上传支持。

### C7: 错误传播机制不完整

**建议：** 定义结构化插件错误协议。

---

## 4. 替代方案比较

**结论：WASM 方案优于 Lua 脚本和进程外 gRPC。** dylib 因安全性排除。

---

## 5. Wasmtime 原型验证计划

### 5.1 验证目标

验证 Wasmtime Component Model 与 ERP 插件系统核心需求的集成可行性：

| # | 验证项 | 关键问题 |
|---|--------|---------|
| V1 | WIT 接口定义 + bindgen! 宏 | C4: 版本兼容性 |
| V2 | Host 调用插件导出函数 | init / handle_event 能否正常工作 |
| V3 | 插件调用 Host 导入函数 | db_insert / log_write 能否正常回调 |
| V4 | async 支持 | Host async 函数（数据库操作）能否正确桥接 |
| V5 | Fuel + Epoch 资源限制 | 是否能限制插件 CPU 时间和内存 |
| V6 | 从二进制动态加载 | 从数据库/文件加载 WASM 并实例化 |

### 5.2 原型项目结构

在 workspace 中创建独立的原型 crate（不影响现有代码）：

```
crates/
  erp-plugin-prototype/           ← 新增原型 crate
    Cargo.toml
    wit/
      plugin.wit                  ← WIT 接口定义
    src/
      lib.rs                      ← Host 端：运行时 + Host API 实现
      main.rs                     ← 测试入口：加载插件并调用
    tests/
      test_plugin_integration.rs  ← 集成测试

  erp-plugin-test-sample/         ← 新增测试插件 crate
    Cargo.toml
    src/
      lib.rs                      ← 插件端：实现 Guest trait
```

### 5.3 WIT 接口（验证用最小子集）

```wit
package erp:plugin;

interface host {
    db-insert: func(entity: string, data: list<u8>) -> result<list<u8>, string>;
    log-write: func(level: string, message: string);
}

interface plugin {
    init: func() -> result<_, string>;
    handle-event: func(event-type: string, payload: list<u8>) -> result<_, string>;
}

world plugin-world {
    import host;
    export plugin;
}
```

### 5.4 Host 端实现（验证要点）

```rust
// crates/erp-plugin-prototype/src/lib.rs

use wasmtime::component::*;
use wasmtime::{Config, Engine, Store};
use wasmtime::StoreLimitsBuilder;

// bindgen! 生成类型化绑定
bindgen!({
    path: "./wit/plugin.wit",
    world: "plugin-world",
    async: true,                           // ← 验证 V4: async 支持
    imports: { default: async | trappable },
    exports: { default: async },
});

struct HostState {
    fuel_consumed: u64,
    logs: Vec<(String, String)>,
    db_ops: Vec<(String, Vec<u8>)>,
}

// 实现 bindgen 生成的 Host trait
impl Host for HostState {
    async fn db_insert(&mut self, entity: String, data: Vec<u8>) -> Result<Vec<u8>, String> {
        // 模拟数据库操作
        self.db_ops.push((entity, data.clone()));
        Ok(br#"{"id":"test-uuid","tenant_id":"tenant-1"}"#.to_vec())
    }

    async fn log_write(&mut self, level: String, message: String) {
        self.logs.push((level, message));
    }
}
```

### 5.5 测试插件

```rust
// crates/erp-plugin-test-sample/src/lib.rs

wit_bindgen::generate!({
    path: "../../erp-plugin-prototype/wit/plugin.wit",
    world: "plugin-world",
});

struct TestPlugin;

impl Guest for TestPlugin {
    fn init() -> Result<(), String> {
        host::log_write("info", "测试插件初始化成功");
        Ok(())
    }

    fn handle_event(event_type: String, payload: Vec<u8>) -> Result<(), String> {
        // 调用 Host API 验证双向通信
        let result = host::db_insert("test_entity", br#"{"name":"test"}"#.to_vec())
            .map_err(|e| format!("db_insert 失败: {}", e))?;
        host::log_write("info", &format!("处理事件 {} 成功", event_type));
        Ok(())
    }
}

export!(TestPlugin);
```

### 5.6 验证测试用例

```rust
// crates/erp-plugin-prototype/tests/test_plugin_integration.rs

#[tokio::test]
async fn test_plugin_lifecycle() {
    // V1: WIT 接口 + bindgen 编译通过（隐式验证）

    // V6: 从文件加载 WASM 二进制
    let wasm_bytes = std::fs::read("../erp-plugin-test-sample/target/.../test_plugin.wasm")
        .expect("请先编译测试插件");
    let engine = setup_engine();  // V5: 启用 fuel + epoch
    let module = Module::from_binary(&engine, &wasm_bytes).unwrap();

    let mut store = setup_store(&engine);  // V5: 设置资源限制
    let instance = instantiate(&mut store, &module).await.unwrap();

    // V2: Host 调用插件 init()
    instance.plugin().call_init(&mut store).await.unwrap();

    // V3: Host 调用插件 handle_event()，插件回调 Host API
    instance.plugin().call_handle_event(
        &mut store,
        "test.event".to_string(),
        vec![],
    ).await.unwrap();

    // 验证 Host 端收到了插件的操作
    let state = store.data();
    assert!(state.logs.iter().any(|(l, m)| m.contains("测试插件初始化成功")));
    assert_eq!(state.db_ops.len(), 1);
}

#[tokio::test]
async fn test_fuel_limit() {
    // V5: 验证 fuel 耗尽时正确 trap
    let mut store = setup_store_with_fuel(100);  // 极低 fuel
    let result = instance.plugin().call_init(&mut store).await;
    assert!(result.is_err());  // 应该因 fuel 耗尽而失败
}
```

### 5.7 验证步骤

```
步骤 1: 添加 crate 和 Cargo.toml 依赖
  - crates/erp-plugin-prototype/Cargo.toml
    wasmtime = "43", wasmtime-wasi = "43", tokio, anyhow
  - crates/erp-plugin-test-sample/Cargo.toml
    wit-bindgen = "0.55", serde, serde_json, crate-type = ["cdylib"]

步骤 2: 编写 WIT 接口文件
  - crates/erp-plugin-prototype/wit/plugin.wit

步骤 3: 实现 Host 端（bindgen + Host trait）
  - crates/erp-plugin-prototype/src/lib.rs

步骤 4: 实现测试插件
  - crates/erp-plugin-test-sample/src/lib.rs

步骤 5: 编译测试插件为 WASM
  - cargo build -p erp-plugin-test-sample --target wasm32-unknown-unknown --release

步骤 6: 运行集成测试
  - cargo test -p erp-plugin-prototype

步骤 7: 验证资源限制
  - fuel 耗尽 trap
  - 内存限制
  - epoch 中断
```

### 5.8 验证成功标准

| 标准 | 衡量方式 |
|------|---------|
| V1 编译通过 | Host 和插件 crate 均能 `cargo check` 通过 |
| V2 Host→插件调用 | `init()` 返回 Ok，Host 端日志记录初始化成功 |
| V3 插件→Host回调 | `handle_event()` 中调用 `host::db_insert()` 成功返回数据 |
| V4 async 正确 | Host 的 async db_insert 在 tokio runtime 中正确执行 |
| V5 资源限制 | 低 fuel 时 init() 返回错误而非无限循环 |
| V6 动态加载 | 从 .wasm 文件加载并实例化成功 |
| 编译大小 | 测试插件 WASM < 2MB |
| 启动耗时 | 单个插件实例化 < 100ms |

### 5.9 关键文件清单

| 文件 | 用途 |
|------|------|
| `crates/erp-plugin-prototype/Cargo.toml` | 新建 - Host 端 crate 配置 |
| `crates/erp-plugin-prototype/wit/plugin.wit` | 新建 - WIT 接口定义 |
| `crates/erp-plugin-prototype/src/lib.rs` | 新建 - Host 运行时 + API 实现 |
| `crates/erp-plugin-prototype/src/main.rs` | 新建 - 手动测试入口 |
| `crates/erp-plugin-prototype/tests/test_plugin_integration.rs` | 新建 - 集成测试 |
| `crates/erp-plugin-test-sample/Cargo.toml` | 新建 - 插件 crate 配置 |
| `crates/erp-plugin-test-sample/src/lib.rs` | 新建 - 测试插件实现 |
| `Cargo.toml` | 修改 - 添加两个新 workspace member |