# P1-P4 审计修复实施计划

## Context

对 P1-P4 审计发现 8 项高/中优先级缺失：Excel/CSV 导入导出、市场后端 API、对账扫描、运行时监控、通知规则、编号 reset_rule。本计划按优先级分 3 批推进，每批独立可提交。

---

## 第一批：高优先级（Excel/CSV + 市场后端 + 对账扫描）

### 1.1 Excel/CSV 导入导出

**思路**: 后端新增 `csv` + `rust_xlsxwriter` 依赖，export handler 支持 format 参数输出 CSV/XLSX；前端同时支持。

**后端改动**:

1. `Cargo.toml` (workspace): 新增 `csv = "1"` 和 `rust_xlsxwriter = "0.82"`
2. `crates/erp-plugin/Cargo.toml`: 添加 `csv` 和 `rust_xlsxwriter` 依赖
3. `crates/erp-plugin/src/data_service.rs`:
   - `export()` 签名增加 `format: Option<String>` 参数
   - 内部新增 `export_csv()` 和 `export_xlsx()` 私有方法，返回 `Vec<u8>` bytes
   - format 为空/json 时返回原 JSON；csv/xlsx 时返回二进制
   - 返回类型改为 enum `ExportPayload { Json(Vec<Value>), Csv(Vec<u8>), Xlsx(Vec<u8>) }`
4. `crates/erp-plugin/src/data_dto.rs`: ExportParams 的 format 字段已有
5. `crates/erp-plugin/src/handler/data_handler.rs`:
   - `export_plugin_data` 根据 format 参数返回不同 Content-Type:
     - JSON: `application/json`
     - CSV: `text/csv` + `Content-Disposition: attachment`
     - XLSX: `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
   - 返回类型改为 `axum::response::Response`（不是 Json<>）
6. 前端 `pluginData.ts`: `exportPluginData` 支持 format 参数，CSV/XLSX 时用 `responseType: 'blob'`
7. 前端 `PluginCRUDPage.tsx`: 导出按钮增加下拉菜单选择格式（JSON/CSV/Excel）

**注意**: 导入仍保持 JSON（复杂度低），模板生成和导入历史不在本批范围。

### 1.2 P4 市场后端 API

**思路**: 新建 `market_service.rs` + `market_handler.rs`，复用 DB 迁移已建好的 `plugin_market_entries` 和 `plugin_market_reviews` 表。

**新增文件**:
- `crates/erp-plugin/src/service/market_service.rs`: 市场业务逻辑
- `crates/erp-plugin/src/handler/market_handler.rs`: 市场 API handler
- `crates/erp-plugin/src/entity/market_entry.rs`: SeaORM Entity
- `crates/erp-plugin/src/entity/market_review.rs`: SeaORM Entity

**后端 API**:
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/market/entries` | 浏览市场目录（分类/搜索/分页） |
| GET | `/api/v1/market/entries/{id}` | 市场条目详情 |
| POST | `/api/v1/market/entries/{id}/install` | 从市场一键安装 |
| GET | `/api/v1/market/entries/{id}/reviews` | 查看评论 |
| POST | `/api/v1/market/entries/{id}/reviews` | 提交评分/评论 |

**一键安装逻辑**: 从 `plugin_market_entries` 取 `wasm_binary` + `manifest_toml`，调用已有的 `PluginService::upload` + `PluginService::install` + `PluginService::enable`。

**依赖提示**: install 时检查 manifest.dependencies，若目标插件未安装则返回警告（软提示，不阻塞）。

**前端改动**:
- `apps/web/src/api/plugins.ts`: 新增市场 API 函数
- `apps/web/src/pages/PluginMarket.tsx`: 对接真实 API，替换 mock 数据；增加评分提交 UI；安装按钮对接真实 API

### 1.3 P1 对账扫描

**思路**: 新增 `reconcile` service 方法和 handler，在插件重新启用时扫描悬空引用。

**后端改动**:
- `crates/erp-plugin/src/data_service.rs`: 新增 `reconcile_references()` 方法
  - 查找所有指向目标插件的 `ref_entity` 字段（从 plugin_entities schema_json 解析）
  - 扫描这些字段的 UUID 值，验证目标表中是否存在
  - 返回 `ReconciliationReport { valid: N, dangling: M, details: Vec<DanglingRef> }`
- `crates/erp-plugin/src/data_dto.rs`: 新增 DTO
- `crates/erp-plugin/src/handler/data_handler.rs`: 新增 `reconcile_refs` handler
- `crates/erp-plugin/src/module.rs`: 注册路由 `POST /plugins/{plugin_id}/reconcile`

**前端**: 暂不实现完整对账 UI（低优先级），仅提供 API 供后续使用。

---

## 第二批：中优先级（运行时监控 + 通知规则 + 编号 reset）

### 2.1 P3 运行时监控

**后端改动**:
1. 新建迁移 `m20260420_000041_plugin_runtime_metrics.rs`:
   - `plugin_runtime_metrics` 表: plugin_id, tenant_id, error_count, total_invocations, avg_response_ms, fuel_consumption_avg, memory_peak_bytes, last_error, updated_at
2. `crates/erp-plugin/src/engine.rs`:
   - `LoadedPlugin` 新增 `metrics: Arc<RwLock<RuntimeMetrics>>` 字段
   - `execute_wasm` 中采集指标: 记录开始时间、成功/失败计数、fuel 消耗
   - 定期持久化到 DB（每 10 次调用或 60 秒）
3. `crates/erp-plugin/src/handler/plugin_handler.rs`:
   - 扩展 `health_check` 返回 RuntimeMetrics
   - 新增 `GET /admin/plugins/{id}/metrics` 端点

### 2.2 P2 通知规则引擎

**思路**: 复用 EventBus 的 `subscribe_filtered` + erp-message 的 `send_system`，在 plugin 模块启动时监听 `plugin.trigger.*` 前缀事件。

**后端改动**:
- `crates/erp-plugin/src/module.rs`: 启动事件监听（参考 erp-message 的 `start_event_listener` 模式）
- 新建 `crates/erp-plugin/src/notification.rs`:
  - 订阅 `plugin.trigger.*` 事件
  - 查询 trigger_events 声明，匹配事件名
  - 调用 erp-message 的系统消息发送（通过 EventBus 发布 `message.send` 事件，或直接调用 message service 的 REST API）
  - 通知对象: 通过 manifest 声明扩展（当前简化为通知所有管理员）

### 2.3 P2 编号 reset_rule

**思路**: 参考 erp-config 的 `numbering_service.rs` 的 `maybe_reset_sequence` 模式，替换 PostgreSQL 序列为表行 + advisory lock。

**后端改动**:
- `crates/erp-plugin/src/host.rs`: 重写 `numbering_generate`
  - 改用 `pg_advisory_xact_lock` + 表行序列（而非 PostgreSQL SEQUENCE）
  - 在事务内: 读序列行 → 检查 reset_rule 是否需要重置 → 递增/重置 → 写回
  - 序列表: 使用已有的动态表模式，或新建 `plugin_numbering_sequences` 表
- `crates/erp-plugin/src/engine.rs`: `NumberingRule` 中 reset_rule 字段已被传递但未使用，直接在 host.rs 中消费

---

## 第三批：低优先级（配置变更通知 + 自定义视图）

### 3.1 P2 配置变更通知

**后端改动**:
- `crates/erp-plugin/src/service.rs`: `update_config` 增加 `event_bus: &EventBus` 参数，更新成功后发布 `plugin.config.updated` 事件
- `crates/erp-plugin/src/handler/plugin_handler.rs`: `update_plugin_config` handler 从 state 获取 event_bus 传入
- `crates/erp-plugin/src/engine.rs`: 订阅 `plugin.config.updated` 事件，刷新内存中的 `plugin_config`

### 3.2 P2 自定义视图

**后端改动**:
1. 新建迁移 `plugin_user_views` 表
2. 新建 `crates/erp-plugin/src/service/view_service.rs`: CRUD user views
3. 新建 handler: `GET/POST/PUT/DELETE /plugins/{plugin_id}/{entity}/views`
4. **前端**: PluginCRUDPage 增加视图保存/加载 UI

---

## 关键文件清单

| 文件 | 改动类型 |
|------|---------|
| `Cargo.toml` (workspace) | 新增 csv, rust_xlsxwriter 依赖 |
| `crates/erp-plugin/Cargo.toml` | 新增依赖 |
| `crates/erp-plugin/src/data_service.rs` | export format 支持, reconcile 方法 |
| `crates/erp-plugin/src/data_dto.rs` | ExportPayload enum, ReconciliationReport |
| `crates/erp-plugin/src/handler/data_handler.rs` | export 返回 Response, reconcile handler |
| `crates/erp-plugin/src/handler/market_handler.rs` | **新建** 市场 API |
| `crates/erp-plugin/src/service/market_service.rs` | **新建** 市场业务逻辑 |
| `crates/erp-plugin/src/entity/market_entry.rs` | **新建** SeaORM Entity |
| `crates/erp-plugin/src/entity/market_review.rs` | **新建** SeaORM Entity |
| `crates/erp-plugin/src/notification.rs` | **新建** 通知规则引擎 |
| `crates/erp-plugin/src/engine.rs` | LoadedPlugin 增加 metrics, 配置热更新 |
| `crates/erp-plugin/src/host.rs` | numbering_generate 重写 |
| `crates/erp-plugin/src/service.rs` | update_config 增加 event_bus |
| `crates/erp-plugin/src/module.rs` | 注册新路由, 启动通知监听 |
| `crates/erp-plugin/src/lib.rs` | 导出新模块 |
| `crates/erp-server/migration/src/m20260420_*.rs` | **新建** metrics 表迁移 |
| `apps/web/src/api/plugins.ts` | 市场前端 API |
| `apps/web/src/api/pluginData.ts` | export format 支持 |
| `apps/web/src/pages/PluginMarket.tsx` | 对接真实 API |
| `apps/web/src/pages/PluginCRUDPage.tsx` | 导出格式选择 |

## 验证计划

1. `cargo check` — 全 workspace 编译通过
2. `pnpm build` — 前端构建通过
3. 启动后端 + 前端，浏览器中验证:
   - CRM customer 导出 CSV/Excel 下载
   - 市场 API 返回数据（curl 测试）
   - 插件 health 接口返回 metrics
4. 每批完成后独立提交推送