338 lines
11 KiB
Markdown
338 lines
11 KiB
Markdown
# ERP 插件平台演进路线图 — 设计规格
|
||
|
||
> 日期: 2026-04-18
|
||
> 来源: 无主题发散式互动探讨
|
||
> 状态: Draft
|
||
|
||
---
|
||
|
||
## 1. 背景与动机
|
||
|
||
ERP 平台已完成 Phase 1-6 核心开发和 Q2-Q4 成熟度路线图。当前有两个行业插件（CRM + 进销存）运行在 WASM 插件系统上。通过分析发现四大系统性缺口：
|
||
|
||
1. **跨插件数据引用完全不支持** — 进销存的 `customer_id` 只能存裸 UUID
|
||
2. **插件无通用业务能力** — 导入导出/打印/配置/视图每个插件都要自己实现
|
||
3. **无质量保障机制** — 第三方插件的安全性和性能无法保证
|
||
4. **无发现和分发渠道** — 用户无法自助发现和安装插件
|
||
|
||
**目标：** 通过搭建财务/应收插件来验证和推动这些平台能力的实现。
|
||
|
||
**核心设计原则：**
|
||
- 插件间**完全独立**，任何插件可自由安装/卸载，不受其他插件影响
|
||
- 跨插件引用**声明式**，通过 plugin.toml 零代码实现
|
||
- 通用业务能力**平台层提供**，插件声明式接入
|
||
- 外部引用问题永远是**软警告**，永不硬阻塞用户操作
|
||
|
||
---
|
||
|
||
## 2. 跨插件数据引用系统
|
||
|
||
### 2.1 Entity Registry (平台实体注册表)
|
||
|
||
插件安装时将其所有实体注册到平台级 Entity Registry，其他插件通过 registry 动态发现和引用。
|
||
|
||
**数据结构：**
|
||
|
||
```
|
||
entity_registry:
|
||
- entity_name: string # 实体名 (如 "customer")
|
||
- plugin_id: string # 注册该实体的插件 ID
|
||
- display_fields: string[] # 用于下拉显示的字段列表
|
||
- search_fields: string[] # 用于搜索的字段列表
|
||
- status: active | inactive # 插件卸载时标记 inactive
|
||
- registered_at: timestamp
|
||
- tenant_id: uuid # 多租户隔离
|
||
```
|
||
|
||
**生命周期：**
|
||
- 插件安装 → 注册所有 entities 到 registry
|
||
- 插件启用 → status = active
|
||
- 插件禁用 → status = inactive（数据保留）
|
||
- 插件卸载 → status = inactive + 标记为 orphaned
|
||
|
||
### 2.2 plugin.toml 扩展
|
||
|
||
```toml
|
||
# 可选依赖声明
|
||
[dependencies.crm]
|
||
optional = true
|
||
description = "客户管理 — 自动关联客户数据，未安装时客户字段为手动输入"
|
||
|
||
[dependencies.inventory]
|
||
optional = true
|
||
description = "进销存 — 自动关联商品数据"
|
||
|
||
# 跨插件引用字段
|
||
[[schema.entities.fields]]
|
||
name = "customer_id"
|
||
field_type = "uuid"
|
||
display_name = "客户"
|
||
ref_entity = "customer" # 目标实体名
|
||
ref_scope = "external" # "internal" (默认) | "external"
|
||
ref_display_field = "name" # 下拉框显示字段
|
||
ref_search_fields = ["name", "phone"] # 搜索字段
|
||
ref_fallback_label = "外部客户" # 降级时显示文本
|
||
```
|
||
|
||
### 2.3 运行时行为
|
||
|
||
**写入时校验：**
|
||
|
||
| 源插件状态 | 写入行为 | 读取行为 | 前端展示 |
|
||
|-----------|---------|---------|---------|
|
||
| 已安装 (active) | 强校验 UUID 存在性 | JOIN 富化 display_field | ✅ 绿色链接 "张三" |
|
||
| 未安装 (inactive) | 无校验，接受任意 UUID | 返回原始 UUID | ⬜ 灰色 "外部客户" |
|
||
| 刚重新启用 | 新写入强校验，不回溯已有 | 后台对账扫描 | ⚠️ 黄色警告 (悬空) |
|
||
|
||
**悬空引用处理 (插件重新启用时)：**
|
||
1. 后台扫描所有 `ref_scope=external` 且指向本插件实体的字段
|
||
2. 验证每个 UUID 是否存在于本插件表中
|
||
3. 生成对账报告: `{ valid: N, dangling: M, details: [...] }`
|
||
4. 前端展示对账结果，用户逐条处理（映射/清空/忽略）
|
||
5. 永不硬阻塞用户操作
|
||
|
||
### 2.4 需要改造的文件
|
||
|
||
| 文件 | 改动 | 复杂度 |
|
||
|------|------|--------|
|
||
| `crates/erp-plugin/src/manifest.rs` | 新增 `ref_scope`, `ref_display_field`, `ref_search_fields`, `ref_fallback_label`; 新增 `DependenciesSection` | 低 |
|
||
| `crates/erp-plugin/src/entity_registry.rs` (新) | 实体注册/发现/inactive 标记/对账 | 中 |
|
||
| `crates/erp-plugin/src/data_service.rs` | `validate_ref_entities` 支持运行时发现外部引用 | 中 |
|
||
| `crates/erp-plugin/src/host.rs` | 新增 `resolve_ref_entity` Host API | 中 |
|
||
| `crates/erp-plugin/wit/plugin.wit` | 新增 `resolve-ref-entity` 接口 | 低 |
|
||
| `crates/erp-plugin/src/service.rs` | 插件安装/卸载时维护 Entity Registry | 中 |
|
||
| `apps/web/src/` 前端 | entity_select 组件支持跨插件数据源 + 降级显示 + 对账 UI | 高 |
|
||
|
||
---
|
||
|
||
## 3. 插件平台通用服务层 (P1)
|
||
|
||
### 3.1 数据导入导出服务
|
||
|
||
插件在 plugin.toml 中声明哪些实体支持导入导出，平台提供统一的导入导出 UI 和引擎。
|
||
|
||
```toml
|
||
[[schema.entities]]
|
||
name = "invoice"
|
||
display_name = "发票"
|
||
importable = true
|
||
exportable = true
|
||
import_template = "invoice_import_template.xlsx"
|
||
```
|
||
|
||
**平台能力：**
|
||
- 自动生成导入模板（基于 schema entities fields）
|
||
- Excel/CSV 解析 + schema 字段校验
|
||
- 批量写入（支持事务 + 错误行级报告）
|
||
- 导出为 Excel/CSV（支持筛选条件）
|
||
- 导入历史记录 + 回滚
|
||
|
||
**实现位置：** `crates/erp-plugin/src/import_export.rs` + 前端 `ImportExportModal` 通用组件
|
||
|
||
### 3.2 打印模板引擎
|
||
|
||
平台提供 HTML → PDF 的模板渲染能力，插件定义模板和字段映射。
|
||
|
||
```toml
|
||
[[templates]]
|
||
name = "invoice_pdf"
|
||
display_name = "发票"
|
||
entity = "invoice"
|
||
format = "pdf"
|
||
template_file = "templates/invoice.html"
|
||
```
|
||
|
||
**平台能力：**
|
||
- HTML 模板渲染 → PDF 下载
|
||
- 模板变量替换（基于实体字段）
|
||
- 租户级模板自定义（覆盖默认模板）
|
||
- 打印预览
|
||
|
||
### 3.3 插件配置 UI
|
||
|
||
插件在 plugin.toml 中声明配置项，平台自动生成配置页面。
|
||
|
||
```toml
|
||
[settings]
|
||
[[settings.fields]]
|
||
name = "default_tax_rate"
|
||
display_name = "默认税率"
|
||
field_type = "number"
|
||
default_value = 0.13
|
||
|
||
[[settings.fields]]
|
||
name = "invoice_prefix"
|
||
display_name = "发票前缀"
|
||
field_type = "text"
|
||
default_value = "INV"
|
||
```
|
||
|
||
**平台能力：**
|
||
- 根据 settings 声明自动生成配置表单
|
||
- 配置数据存储在 `plugin_settings` 表（tenant_id + plugin_id + key/value）
|
||
- 配置变更时通知插件（通过事件）
|
||
- 支持配置权限控制（仅管理员可改）
|
||
|
||
### 3.4 自定义视图
|
||
|
||
用户可以保存列表页的列配置和筛选条件。
|
||
|
||
```
|
||
user_views:
|
||
- id: uuid
|
||
- user_id: uuid
|
||
- plugin_id: string
|
||
- entity_name: string
|
||
- view_name: string
|
||
- columns: string[]
|
||
- filters: json
|
||
- sort: json
|
||
- is_default: boolean
|
||
```
|
||
|
||
### 3.5 通知规则
|
||
|
||
插件在 plugin.toml 中声明可触发的事件，平台提供通知规则配置 UI。
|
||
|
||
```toml
|
||
[[trigger_events]]
|
||
name = "invoice.overdue"
|
||
display_name = "发票逾期"
|
||
description = "发票超过付款期限未收款"
|
||
```
|
||
|
||
**平台能力：**
|
||
- 规则引擎: WHEN event THEN notify [user/role/department]
|
||
- 复用 erp-message 的通知渠道
|
||
- 租户级规则配置
|
||
|
||
### 3.6 编号规则 (已有基础扩展)
|
||
|
||
复用 erp-config 的编号规则服务，扩展为插件可接入。
|
||
|
||
```toml
|
||
[[numbering]]
|
||
entity = "invoice"
|
||
prefix = "INV"
|
||
format = "{PREFIX}-{YEAR}-{SEQ:4}"
|
||
reset_rule = "yearly"
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 插件质量保障
|
||
|
||
### 4.1 上传时校验
|
||
|
||
```
|
||
插件上传 → Schema 校验 → WASM 二进制验证 → 安全扫描 → 性能基准 → 发布/拒绝
|
||
```
|
||
|
||
| 阶段 | 校验内容 | 现状 |
|
||
|------|---------|------|
|
||
| Schema 校验 | plugin.toml 格式、字段类型、权限码一致性 | 部分已有 |
|
||
| WASM 验证 | 二进制格式、WIT 兼容性、导出函数检查 | 已有 |
|
||
| 安全扫描 | 动态表 SQL 注入风险、Fuel 耗尽、内存泄漏 | 缺失 |
|
||
| 性能基准 | 标准 CRUD 操作在 N 条数据下的响应时间 | 缺失 |
|
||
| 兼容性 | 平台版本匹配、依赖插件版本兼容 | 缺失 |
|
||
|
||
### 4.2 运行时监控
|
||
|
||
```
|
||
plugin_runtime_metrics:
|
||
- plugin_id: string
|
||
- error_rate: float
|
||
- avg_response_ms: float
|
||
- fuel_consumption: float
|
||
- memory_peak_mb: float
|
||
- active_instances: int
|
||
```
|
||
|
||
**告警规则：** 错误率 > 5% / 平均响应 > 2s / Fuel 消耗异常 / 内存持续增长
|
||
|
||
---
|
||
|
||
## 5. 插件市场/商店
|
||
|
||
| 功能 | 说明 |
|
||
|------|------|
|
||
| 插件目录 | 按行业/功能分类浏览 |
|
||
| 搜索 | 按名称/标签/行业搜索 |
|
||
| 详情页 | 截图、演示、功能描述、权限说明 |
|
||
| 一键安装 | 上传 → 自动安装 → 配置 → 启用 |
|
||
| 评分/评论 | 用户评分和使用反馈 |
|
||
| 版本管理 | 版本列表、更新日志、回滚 |
|
||
| 依赖提示 | 安装时提示可选依赖 |
|
||
|
||
---
|
||
|
||
## 6. 验证计划 — 财务/应收插件
|
||
|
||
### 6.1 实体设计
|
||
|
||
| 实体 | 字段概要 | 跨插件引用 |
|
||
|------|---------|-----------|
|
||
| invoice (发票) | 编号/客户/金额/税额/状态/到期日 | customer_id → CRM.customer |
|
||
| invoice_line (发票行) | 发票/商品/数量/单价/税额 | product_id → Inventory.product |
|
||
| payment (收款) | 发票/金额/方式/日期/状态 | invoice_id → 本插件内部 |
|
||
| quote (报价单) | 编号/客户/有效期/状态 | customer_id → CRM.customer |
|
||
| quote_line (报价行) | 报价单/商品/数量/单价 | product_id → Inventory.product |
|
||
|
||
### 6.2 验证矩阵
|
||
|
||
| 能力 | 验证方式 | 预期结果 |
|
||
|------|---------|---------|
|
||
| 跨插件引用 (CRM 安装) | 创建发票时选择客户 | entity_select 下拉显示 CRM 客户列表 |
|
||
| 跨插件引用 (CRM 卸载) | 创建发票时输入客户 | 降级为文本输入，不阻塞 |
|
||
| 悬空引用对账 | CRM 卸载→创建发票→重新安装 CRM | 对账报告显示悬空引用，用户可修复 |
|
||
| 数据导入 | 导入 Excel 客户清单 | 解析+校验+批量写入 |
|
||
| 数据导出 | 导出发票列表为 Excel | 筛选+下载 |
|
||
| 打印模板 | 打印发票 PDF | HTML→PDF 渲染 |
|
||
| 插件配置 | 设置税率/发票前缀 | 自动生成的配置页面 |
|
||
| 编号规则 | 创建发票自动编号 | INV-2026-0001 |
|
||
| 通知规则 | 发票逾期通知 | 规则引擎触发通知 |
|
||
| 独立安装 | 不安装 CRM 单独安装财务 | 所有功能正常，客户字段降级 |
|
||
|
||
---
|
||
|
||
## 7. 实施优先级
|
||
|
||
```
|
||
P0 (已完成/进行中): P0 平台能力升级 + 插件系统增强
|
||
|
||
P1 (跨插件引用): Entity Registry + ref_scope 扩展 + 前端 entity_select 改造
|
||
这是所有后续能力的基础
|
||
|
||
P2 (平台通用服务): 数据导入导出 → 插件配置 UI → 编号规则扩展 → 通知规则
|
||
|
||
P3 (质量保障): 上传时安全扫描 → 性能基准 → 运行时监控
|
||
|
||
P4 (插件市场): 插件目录 → 一键安装 → 版本管理 → 评分评论
|
||
|
||
验证: 财务/应收插件贯穿 P1-P2，每完成一个 P 就用财务插件验证
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 风险与缓解
|
||
|
||
| 风险 | 影响 | 缓解措施 |
|
||
|------|------|---------|
|
||
| Entity Registry 查询性能 | 每次数据操作都要查注册表 | 内存缓存 + DashMap，注册表数据量极小 |
|
||
| 悬空引用数据量过大 | 对账扫描耗时长 | 异步后台任务 + 分批处理 + 进度条 |
|
||
| Excel 导入内存占用 | 大文件解析 OOM | 流式解析 + 批量提交 + 文件大小限制 |
|
||
| 打印模板安全 | 模板注入攻击 | 沙箱渲染 + 变量白名单 |
|
||
| 插件市场审核成本 | 人工审核效率低 | 自动化扫描 + 人工抽查 + 社区举报 |
|
||
|
||
---
|
||
|
||
## 9. 讨论溯源
|
||
|
||
本文档基于 2026-04-18 的无主题发散式互动探讨产出，完整讨论过程记录在 `plans/skill-cosmic-pancake.md`。
|
||
|
||
关键决策历程：
|
||
- **Round 1:** 发现跨插件数据引用完全不支持（进销存的 customer_id 是裸 UUID）
|
||
- **Round 2:** 确定声明式引用 + 完全独立（无硬依赖）+ 软警告对账方案
|
||
- **Round 3:** 确定导入导出/打印/配置/视图/通知应为平台通用服务
|
||
- **Round 4:** 收敛为统一设计规格，以财务插件为验证载体
|