184 lines
6.2 KiB
Markdown
184 lines
6.2 KiB
Markdown
# 插件系统增强设计规格
|
||
|
||
## Context
|
||
|
||
插件系统是 ERP 平台的核心差异化能力，当前声明式层面（manifest schema、动态表、前端页面）已达 90% 成熟度。但 WASM 逻辑层存在根本性限制：
|
||
|
||
1. **插件无法自主查询数据** — `db_query` 的 filter/pagination 参数被忽略，只能使用预填充结果
|
||
2. **无读后写一致性** — 延迟刷新模型导致插件在一次调用中无法读取自己刚写入的数据
|
||
3. **聚合只有 COUNT** — 缺少 SUM/AVG/MAX/MIN，无法支撑财务、统计类场景
|
||
4. **热更新无原子回滚** — 旧版本先卸载再加载新版本，中间失败无保障
|
||
5. **Schema 变更只支持新增实体** — 不支持已有实体的字段演进
|
||
|
||
这些限制使插件系统只能支撑"数据管理+展示"型轻量场景（CRM、简单进销存），无法支撑需要复杂业务逻辑的行业（财务、制造、电商）。
|
||
|
||
本次增强的目标：**让插件逻辑层从 40% 提升到 80%+，使系统能真正承载不同行业的定制化需求。**
|
||
|
||
---
|
||
|
||
## 改动 1：混合执行模型（解决查询和读后写一致性）
|
||
|
||
### 问题
|
||
|
||
`host.rs:99-109` — `db_query` 忽略 `_filter` 和 `_pagination` 参数，只从 `query_results` 预填充缓存取数据。插件无法自主构造查询。
|
||
|
||
### 方案：读操作走实时 SQL + 写操作保持延迟批量 + 读前自动 flush
|
||
|
||
核心流程变更：
|
||
|
||
```
|
||
当前：
|
||
WASM 调用 db_insert() → 入队 pending_ops
|
||
WASM 调用 db_query() → 从预填充缓存读（忽略 filter/pagination）
|
||
WASM 结束 → flush 全部 pending_ops
|
||
|
||
改为：
|
||
WASM 调用 db_insert() → 入队 pending_ops
|
||
WASM 调用 db_query() → 先 flush pending_ops → 执行真实 SQL 查询 → 返回结果
|
||
WASM 结束 → flush 剩余 pending_ops
|
||
```
|
||
|
||
### 改动文件
|
||
|
||
#### 1. `crates/erp-plugin/src/host.rs`
|
||
|
||
HostState 新增字段：
|
||
|
||
```rust
|
||
pub struct HostState {
|
||
// ... 现有字段保留 ...
|
||
pub(crate) db: Option<DatabaseConnection>,
|
||
pub(crate) event_bus: Option<EventBus>,
|
||
}
|
||
```
|
||
|
||
db_query 实现变更 — 使用 `tokio::runtime::Handle::current()` 在 `spawn_blocking` 内执行异步 DB 操作：
|
||
|
||
1. 先 `block_on(flush_ops(...))` 清空 pending writes
|
||
2. 解析 filter/pagination 参数
|
||
3. 调用 `DynamicTableManager::build_query_sql()` 构建查询
|
||
4. `block_on` 执行查询并返回结果
|
||
|
||
向后兼容：`db = None` 时走旧的预填充路径。
|
||
|
||
#### 2. `crates/erp-plugin/src/dynamic_table.rs`
|
||
|
||
新增 `build_query_sql` 方法，复用 `data_service.rs` 中的查询构建逻辑。
|
||
|
||
### 向后兼容
|
||
|
||
- `HostState::new()` 不传 db → 走旧的预填充路径
|
||
- `execute_wasm()` 传 db → 走新的实时查询路径
|
||
- 现有 WASM 插件无需修改
|
||
|
||
---
|
||
|
||
## 改动 2：扩展聚合查询
|
||
|
||
### 问题
|
||
|
||
`data_service.rs:655` 的 `aggregate` 方法只支持 `GROUP BY + COUNT(*)`。
|
||
|
||
### 方案
|
||
|
||
新增 `aggregate_multi` 方法支持 SUM/AVG/MAX/MIN。
|
||
|
||
改动文件：
|
||
|
||
1. `data_service.rs` — 新增 `AggregateDef`、`AggregateFunc`、`AggregateResult` 类型和 `aggregate_multi` 方法
|
||
2. `dynamic_table.rs` — 新增 `build_aggregate_multi_sql` 方法
|
||
3. `data_handler.rs` — 扩展聚合 API 端点
|
||
4. 前端 Dashboard Widget 适配多聚合返回格式
|
||
|
||
SQL 示例：
|
||
```sql
|
||
SELECT _f_status as key,
|
||
COUNT(*) as count,
|
||
COALESCE(SUM(_f_amount), 0) as sum_amount,
|
||
COALESCE(AVG(_f_price), 0) as avg_price
|
||
FROM plugin_erp_crm__order
|
||
WHERE tenant_id = $1 AND deleted_at IS NULL
|
||
GROUP BY _f_status
|
||
```
|
||
|
||
---
|
||
|
||
## 改动 3：热更新原子回滚
|
||
|
||
### 问题
|
||
|
||
`service.rs:578-585` — 先 `unload(old)` 再 `load(new)`，中间失败无回滚。
|
||
|
||
### 方案：先加载新版本到临时 key，成功后原子替换
|
||
|
||
改动文件：
|
||
|
||
1. `service.rs` — upgrade 方法改用临时 key 加载新版本
|
||
2. `engine.rs` — 新增 `rename_plugin` 方法
|
||
|
||
安全保证：新版本加载失败 → 旧版本仍在运行，零停机。
|
||
|
||
---
|
||
|
||
## 改动 4：Schema 演进（ALTER TABLE 支持）
|
||
|
||
### 问题
|
||
|
||
升级时只处理新增实体（CREATE TABLE），不处理已有实体的字段变更。
|
||
|
||
### 方案：利用 JSONB 特性实现轻量级 Schema 演进
|
||
|
||
大部分字段变更不需要 DDL（JSONB 天然支持），仅新增 filterable/sortable 字段需 ALTER TABLE ADD Generated Column + 索引。
|
||
|
||
改动文件：
|
||
|
||
1. `service.rs` — upgrade 方法增加 schema diff 逻辑
|
||
2. `dynamic_table.rs` — 新增 `FieldDiff`、`diff_entity_fields`、`alter_add_generated_columns`
|
||
|
||
---
|
||
|
||
## 实施顺序
|
||
|
||
| 阶段 | 改动 | 复杂度 | 影响范围 |
|
||
|------|------|--------|---------|
|
||
| 1 | 热更新原子回滚 | 低 | engine.rs + service.rs |
|
||
| 2 | Schema 演进（ALTER TABLE） | 中低 | service.rs + dynamic_table.rs |
|
||
| 3 | 扩展聚合查询 | 中 | data_service.rs + data_handler.rs + dynamic_table.rs |
|
||
| 4 | 混合执行模型（查询能力） | 高 | host.rs + engine.rs + dynamic_table.rs |
|
||
|
||
---
|
||
|
||
## 验证方案
|
||
|
||
### 阶段 1：热更新回滚
|
||
1. 上传损坏的 WASM 二进制 → 验证旧版本仍在运行
|
||
2. 上传正确的新版本 → 验证成功切换
|
||
|
||
### 阶段 2：Schema 演进
|
||
1. 升级插件增加 filterable 字段 → 验证 ALTER TABLE 正确执行
|
||
2. 旧数据上新 Generated Column 值正确填充
|
||
|
||
### 阶段 3：聚合查询
|
||
1. 创建测试数据，调用聚合 API → 验证 SUM/AVG 结果正确
|
||
2. 前端 Dashboard 展示正确
|
||
|
||
### 阶段 4：混合执行模型
|
||
1. 插件 WASM 中 db_insert 后立即 db_query → 读后写一致性
|
||
2. 带 filter 的 db_query → 过滤结果正确
|
||
3. 旧插件（预填充模式）仍能正常工作
|
||
4. 多次连续 db_query 不超过 Fuel 限制
|
||
|
||
---
|
||
|
||
## 关键文件清单
|
||
|
||
| 文件 | 改动类型 |
|
||
|------|---------|
|
||
| `crates/erp-plugin/src/host.rs` | 重构 db_query + 新增 db/事件总线字段 |
|
||
| `crates/erp-plugin/src/engine.rs` | 调整 execute_wasm + 新增 rename_plugin |
|
||
| `crates/erp-plugin/src/service.rs` | 升级流程回滚安全 + schema diff |
|
||
| `crates/erp-plugin/src/dynamic_table.rs` | 新增 build_query_sql + alter_add_generated_columns + diff_entity_fields |
|
||
| `crates/erp-plugin/src/data_service.rs` | 新增 aggregate_multi + AggregateDef |
|
||
| `crates/erp-plugin/src/data_handler.rs` | 扩展聚合 API |
|
||
| `apps/web/src/pages/PluginDashboardPage.tsx` | 适配多聚合返回格式 |
|