feat(freelance): 编译 WASM 并验证安装 — 10 实体/20 权限已创建

2026-04-19 23:59:03 +08:00
parent 813df3688c
commit fc76793d6d
13 changed files with 4140 additions and 203 deletions
--- a/docs/superpowers/plans/2026-04-19-shantou-zhijie-it-services-plugins-plan.md
+++ b/docs/superpowers/plans/2026-04-19-shantou-zhijie-it-services-plugins-plan.md
@@ -0,0 +1,484 @@
+# 汕头市智界科技 IT 服务插件 — 实施计划
+
+> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 为汕头市智界科技有限公司创建 freelance（自由职业者工作台）和 itops（IT 运维服务台）两个 WASM 插件，覆盖其全部 12 条经营范围。
+
+**Architecture:** 两个独立的 WASM 插件 crate，每个包含 Cargo.toml（cdylib）、src/lib.rs（Guest trait 实现）、plugin.toml（声明式 schema）。通过插件安装 API 上传到系统，平台自动创建动态表、注册权限、生成前端页面。itops 通过 ref_plugin 跨插件引用 freelance 的 client 实体。
+
+**Tech Stack:** Rust (wit-bindgen 0.55, cdylib → WASM Component)、TOML manifest、Axum Host API
+
+**Spec:** `docs/superpowers/specs/2026-04-19-shantou-zhijie-it-services-plugins-design.md`
+
+---
+
+## Chunk 1: freelance 插件
+
+### Task 1: 创建 crate 目录和 Cargo.toml
+
+**Files:**
+- Create: `crates/erp-plugin-freelance/Cargo.toml`
+- Create: `crates/erp-plugin-freelance/src/lib.rs`（空文件占位）
+
+- [ ] **Step 1: 创建目录结构**
+
+```bash
+mkdir -p crates/erp-plugin-freelance/src
+```
+
+- [ ] **Step 2: 编写 Cargo.toml**
+
+创建 `crates/erp-plugin-freelance/Cargo.toml`：
+
+```toml
+[package]
+name = "erp-plugin-freelance"
+version = "0.1.0"
+edition = "2024"
+description = "自由职业者工作台 WASM 插件"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+wit-bindgen = "0.55"
+```
+
+- [ ] **Step 3: 编写 src/lib.rs**
+
+创建 `crates/erp-plugin-freelance/src/lib.rs`：
+
+```rust
+//! 自由职业者工作台 WASM 插件
+
+wit_bindgen::generate!({
+    path: "../erp-plugin-prototype/wit/plugin.wit",
+    world: "plugin-world",
+});
+
+use crate::exports::erp::plugin::plugin_api::Guest;
+
+struct FreelancePlugin;
+
+impl Guest for FreelancePlugin {
+    fn init() -> Result<(), String> {
+        Ok(())
+    }
+
+    fn on_tenant_created(_tenant_id: String) -> Result<(), String> {
+        Ok(())
+    }
+
+    fn handle_event(_event_type: String, _payload: Vec<u8>) -> Result<(), String> {
+        Ok(())
+    }
+}
+
+export!(FreelancePlugin);
+```
+
+- [ ] **Step 4: 注册到 workspace**
+
+编辑根 `Cargo.toml`，在 `members` 数组末尾添加：
+
+```toml
+    "crates/erp-plugin-freelance",
+```
+
+- [ ] **Step 5: 验证编译**
+
+```bash
+cargo check -p erp-plugin-freelance
+```
+
+Expected: 编译通过，无错误
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add crates/erp-plugin-freelance/ Cargo.toml
+git commit -m "feat(freelance): 创建插件 crate 骨架"
+```
+
+---
+
+### Task 2: 编写 plugin.toml（freelance）
+
+**Files:**
+- Create: `crates/erp-plugin-freelance/plugin.toml`
+
+- [ ] **Step 1: 从设计规格文档复制完整 plugin.toml 内容**
+
+从设计规格 `docs/superpowers/specs/2026-04-19-shantou-zhijie-it-services-plugins-design.md` 中提取 2.1（元数据）+ 2.2（权限）+ 2.3（10 个实体）+ 2.4（编号规则）+ 2.5（页面声明）的所有 TOML 内容，合并为完整的 `plugin.toml` 文件。
+
+文件结构：
+1. `[metadata]` 段
+2. `[[permissions]]` × 20
+3. `[[schema.entities]]` × 10（client, opportunity, quote, quote_line, contract, project, task, time_entry, invoice, expense），每个实体包含 fields 和 relations
+4. `[[numbering]]` × 3（quote_number, contract_number, invoice_number）
+5. `[[ui.pages]]` × 7（dashboard, tabs+detail+kanban for client, crud+detail for project, tabs for finance, crud for expense）
+
+注意要点：
+- client 实体必须标记 `is_public = true`（被 itops 跨插件引用）
+- quote 到 quote_line 有 cascade 关系
+- project 到 task 和 time_entry 有 cascade 关系
+- 所有 uuid 引用字段使用 `ui_widget = "entity_select"` + `ref_label_field` + `ref_search_fields`
+- 所有 select 字段使用 `options = [{ label = "X", value = "x" }]` 格式
+- 长文本使用 `field_type = "string"` + `ui_widget = "textarea"`
+- 金额使用 `field_type = "decimal"`
+- 时间戳使用 `field_type = "date_time"`
+
+- [ ] **Step 2: 验证 TOML 格式**
+
+```bash
+cargo check -p erp-plugin-freelance
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add crates/erp-plugin-freelance/plugin.toml
+git commit -m "feat(freelance): 添加 plugin.toml — 10 实体/20 权限/7 页面"
+```
+
+---
+
+### Task 3: 编译 WASM 并安装
+
+- [ ] **Step 1: 编译为 WASM**
+
+```bash
+cargo build -p erp-plugin-freelance --target wasm32-unknown-unknown --release
+```
+
+Expected: 编译成功，产出 `target/wasm32-unknown-unknown/release/erp_plugin_freelance.wasm`
+
+- [ ] **Step 2: 转换为 Component**
+
+```bash
+wasm-tools component new target/wasm32-unknown-unknown/release/erp_plugin_freelance.wasm -o target/erp_plugin_freelance.component.wasm
+```
+
+- [ ] **Step 3: 检查产物大小**
+
+```bash
+ls -la target/erp_plugin_freelance.component.wasm
+```
+
+Expected: < 100KB（CRM 约 22KB）
+
+- [ ] **Step 4: 启动后端服务**
+
+```bash
+cd crates/erp-server && cargo run
+```
+
+等待服务启动完成（看到 "listening on 0.0.0.0:3000" 日志）
+
+- [ ] **Step 5: 登录获取 Token**
+
+```bash
+curl -s -X POST http://localhost:3000/api/v1/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"username":"admin","password":"admin123"}' | jq -r '.data.access_token'
+```
+
+保存输出的 token。
+
+- [ ] **Step 6: 上传安装插件**
+
+```bash
+TOKEN="<上一步的 token>"
+MANIFEST=$(cat crates/erp-plugin-freelance/plugin.toml)
+
+curl -s -X POST http://localhost:3000/api/v1/admin/plugins/upload \
+  -H "Authorization: Bearer $TOKEN" \
+  -F "wasm=@target/erp_plugin_freelance.component.wasm" \
+  -F "manifest=$MANIST"
+```
+
+Expected: 返回插件 ID，状态为 `installed`
+
+- [ ] **Step 7: 启用插件**
+
+使用上一步返回的插件 ID：
+
+```bash
+PLUGIN_ID="<返回的插件 ID>"
+curl -s -X POST "http://localhost:3000/api/v1/admin/plugins/$PLUGIN_ID/enable" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+Expected: 状态变为 `running`
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add -A
+git commit -m "feat(freelance): 编译 WASM 并验证安装"
+```
+
+---
+
+### Task 4: 浏览器验证 freelance 插件
+
+- [ ] **Step 1: 打开浏览器访问 http://localhost:5174**
+
+- [ ] **Step 2: 登录后检查侧边栏**
+
+Expected: 看到"自由职业者工作台"菜单组，包含：工作台、客户管理、商机看板、项目管理、项目详情、财务中心、支出管理
+
+- [ ] **Step 3: 测试客户 CRUD**
+
+进入客户管理 → 新增客户（填写名称、联系人、电话、行业等）→ 保存 → 列表中可见
+
+- [ ] **Step 4: 测试项目 → 任务级联**
+
+进入项目管理 → 新增项目 → 进入项目详情 → 新增任务 → 验证任务关联到项目
+
+- [ ] **Step 5: 测试报价 → 报价明细级联**
+
+进入财务中心 → 报价管理 tab → 新增报价 → 验证明细行可添加
+
+- [ ] **Step 6: 测试商机看板**
+
+进入商机看板 → 新增商机 → 拖拽改变阶段 → 验证数据更新
+
+- [ ] **Step 7: 验证数据库表创建**
+
+```bash
+PGPASSWORD=123123 "D:\postgreSQL\bin\psql.exe" -U postgres -h localhost -d erp -c "\dt plugin_erp_freelance_*"
+```
+
+Expected: 看到 10 张动态表
+
+---
+
+## Chunk 2: itops 插件
+
+### Task 5: 创建 itops 插件 crate
+
+**Files:**
+- Create: `crates/erp-plugin-itops/Cargo.toml`
+- Create: `crates/erp-plugin-itops/src/lib.rs`
+- Create: `crates/erp-plugin-itops/plugin.toml`
+
+- [ ] **Step 1: 创建目录结构**
+
+```bash
+mkdir -p crates/erp-plugin-itops/src
+```
+
+- [ ] **Step 2: 编写 Cargo.toml**
+
+创建 `crates/erp-plugin-itops/Cargo.toml`：
+
+```toml
+[package]
+name = "erp-plugin-itops"
+version = "0.1.0"
+edition = "2024"
+description = "IT 运维服务台 WASM 插件"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+wit-bindgen = "0.55"
+```
+
+- [ ] **Step 3: 编写 src/lib.rs**
+
+创建 `crates/erp-plugin-itops/src/lib.rs`：
+
+```rust
+//! IT 运维服务台 WASM 插件
+
+wit_bindgen::generate!({
+    path: "../erp-plugin-prototype/wit/plugin.wit",
+    world: "plugin-world",
+});
+
+use crate::exports::erp::plugin::plugin_api::Guest;
+
+struct ItopsPlugin;
+
+impl Guest for ItopsPlugin {
+    fn init() -> Result<(), String> {
+        Ok(())
+    }
+
+    fn on_tenant_created(_tenant_id: String) -> Result<(), String> {
+        Ok(())
+    }
+
+    fn handle_event(_event_type: String, _payload: Vec<u8>) -> Result<(), String> {
+        Ok(())
+    }
+}
+
+export!(ItopsPlugin);
+```
+
+- [ ] **Step 4: 编写 plugin.toml**
+
+从设计规格文档 Section 3 提取完整内容：
+1. `[metadata]` — id="erp-itops"，无 dependencies（松耦合）
+2. `[[permissions]]` × 8
+3. `[[schema.entities]]` × 4（service_contract, ticket, check_plan, check_record），每个实体包含 fields 和 relations
+4. `[[numbering]]` × 1（contract_number）
+5. `[[ui.pages]]` × 4（crud+detail for service_contract, tabs for ticket center）
+
+关键注意点：
+- 4 个实体的 `client_id` 字段都使用 `ref_plugin = "erp-freelance"` + `ref_fallback_label = "外部客户"`
+- `filterable` 只用于 string 类型的 status/type/category 字段，不用于 uuid 字段
+- `check_items` 和 `items_data` 使用 `field_type = "json"`
+- `responded_at` / `resolved_at` / `closed_at` 使用 `field_type = "date_time"`
+
+- [ ] **Step 5: 注册到 workspace**
+
+编辑根 `Cargo.toml`，在 members 数组末尾添加：
+
+```toml
+    "crates/erp-plugin-itops",
+```
+
+- [ ] **Step 6: 验证编译**
+
+```bash
+cargo check -p erp-plugin-itops
+```
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add crates/erp-plugin-itops/ Cargo.toml
+git commit -m "feat(itops): 创建 IT 运维服务台插件 — 4 实体/8 权限/4 页面"
+```
+
+---
+
+### Task 6: 编译 WASM 并安装 itops
+
+- [ ] **Step 1: 编译为 WASM**
+
+```bash
+cargo build -p erp-plugin-itops --target wasm32-unknown-unknown --release
+```
+
+- [ ] **Step 2: 转换为 Component**
+
+```bash
+wasm-tools component new target/wasm32-unknown-unknown/release/erp_plugin_itops.wasm -o target/erp_plugin_itops.component.wasm
+```
+
+- [ ] **Step 3: 上传安装插件**
+
+```bash
+TOKEN="<之前获取的 token>"
+MANIFEST=$(cat crates/erp-plugin-itops/plugin.toml)
+
+curl -s -X POST http://localhost:3000/api/v1/admin/plugins/upload \
+  -H "Authorization: Bearer $TOKEN" \
+  -F "wasm=@target/erp_plugin_itops.component.wasm" \
+  -F "manifest=$MANIFEST"
+```
+
+- [ ] **Step 4: 启用插件**
+
+```bash
+PLUGIN_ID="<返回的插件 ID>"
+curl -s -X POST "http://localhost:3000/api/v1/admin/plugins/$PLUGIN_ID/enable" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+---
+
+### Task 7: 浏览器验证 itops 插件
+
+- [ ] **Step 1: 检查侧边栏**
+
+Expected: 看到"IT 运维服务台"菜单组，包含：合同管理、合同详情、工单中心
+
+- [ ] **Step 2: 测试维保合同 CRUD**
+
+进入合同管理 → 新增维保合同（选择客户时验证：如 freelance 已安装，客户下拉显示 freelance 的客户列表）
+
+- [ ] **Step 3: 测试跨插件引用**
+
+场景 A（freelance 已安装）：创建工单时 client_id 字段显示为下拉选择器，可搜索 freelance.client
+场景 B（freelance 未安装）：client_id 降级为文本输入，显示"外部客户"
+
+- [ ] **Step 4: 测试合同 → 工单 → 巡检级联**
+
+进入合同详情 → 工单 tab → 新增工单 → 巡检计划 tab → 新增巡检计划 → 巡检记录 tab → 新增巡检记录
+
+- [ ] **Step 5: 验证数据库表**
+
+```bash
+PGPASSWORD=123123 "D:\postgreSQL\bin\psql.exe" -U postgres -h localhost -d erp -c "\dt plugin_erp_itops_*"
+```
+
+Expected: 看到 4 张动态表
+
+---
+
+## Chunk 3: 集成验证
+
+### Task 8: 全链路端到端验证
+
+- [ ] **Step 1: 创建客户**
+
+freelance → 客户管理 → 新增客户"汕头市XX科技有限公司"
+
+- [ ] **Step 2: 创建商机**
+
+商机看板 → 新增商机 → 选择客户 → 填写"官网开发"→ 拖拽到"成交"阶段
+
+- [ ] **Step 3: 创建报价单**
+
+财务中心 → 报价管理 → 新增报价 → 选择客户 → 添加明细行 → 保存
+
+- [ ] **Step 4: 创建合同**
+
+财务中心 → 合同管理 → 新增合同 → 选择客户 → 填写金额和日期 → 保存
+
+- [ ] **Step 5: 创建项目**
+
+项目管理 → 新增项目 → 选择客户和合同 → 填写"官网开发项目" → 添加任务 → 记录工时
+
+- [ ] **Step 6: 创建发票**
+
+财务中心 → 发票/收款 → 新增发票 → 选择客户和项目 → 填写金额 → 标记已收款
+
+- [ ] **Step 7: 创建运维工单**
+
+itops → 合同管理 → 新增维保合同 → 选择客户（验证跨插件引用）→ 保存
+itops → 工单中心 → 新增工单 → 选择客户和合同 → 保存
+
+- [ ] **Step 8: 记录支出**
+
+freelance → 支出管理 → 新增支出 → 选择类别"云服务" → 填写金额 → 保存
+
+- [ ] **Step 9: 提交并推送**
+
+```bash
+git add -A
+git commit -m "feat(freelance,itops): 汕头市智界科技 IT 服务行业插件验证通过"
+git push
+```
+
+---
+
+## 关键参考文件
+
+| 文件 | 用途 |
+|------|------|
+| `crates/erp-plugin-crm/Cargo.toml` | Cargo.toml 模板参考 |
+| `crates/erp-plugin-crm/src/lib.rs` | lib.rs 代码模式参考 |
+| `crates/erp-plugin-crm/plugin.toml` | plugin.toml 格式参考（同插件内引用） |
+| `crates/erp-plugin-inventory/plugin.toml` | 跨插件引用格式参考（ref_plugin） |
+| `crates/erp-plugin/src/manifest.rs` | PluginField/PluginFieldType 完整定义 |
+| `crates/erp-plugin-prototype/wit/plugin.wit` | WIT 接口定义 |
+| `wiki/infrastructure.md` | 数据库连接、端口、登录凭据 |
+| `wiki/wasm-plugin.md` | 插件制作完整流程 |