# freelance + itops 插件增强实施计划

> 日期: 2026-04-20
> 对应规格: `docs/superpowers/specs/2026-04-20-freelance-itops-plugin-enhancement-design.md`
> 前置: 两插件已部署（freelance 10 实体/20 权限，itops 4 实体/8 权限）

---

## 总览

| Phase | 内容 | 类型 | 依赖 |
|-------|------|------|------|
| P1 | freelance Layer 1 — 智能业务引擎 | 纯 plugin.toml | 无 |
| P2 | itops Layer 1 — 智能业务引擎 | 纯 plugin.toml | 无 |
| P3 | freelance Layer 3 — PDF 模板 | 纯 plugin.toml | 无 |
| P4 | itops Layer 3 — PDF 模板 | 纯 plugin.toml | 无 |
| P5 | 平台 dashboard widgets 扩展 | manifest.rs + 前端 | P1-P4 完成 |
| P6 | freelance + itops Layer 2 — 仪表盘 | plugin.toml + 前端 | P5 完成 |

P1-P4 可并行，P5-P6 顺序依赖。

---

## Phase 1: freelance Layer 1 — 智能业务引擎

**目标文件:** `crates/erp-plugin-freelance/plugin.toml`

### Task 1.1: 新增 `[settings]` 段落

在 `[[numbering]]` 之前插入 7 个配置项：

```toml
[settings]

  [[settings.fields]]
  name = "company_name"
  display_name = "公司名称"
  field_type = "text"
  required = true
  group = "基本信息"

  [[settings.fields]]
  name = "currency_symbol"
  display_name = "货币符号"
  field_type = "text"
  default_value = "¥"
  group = "基本信息"

  [[settings.fields]]
  name = "default_tax_rate"
  display_name = "默认税率(%)"
  field_type = "number"
  default_value = 6
  range = [0.0, 100.0]
  group = "财务"

  [[settings.fields]]
  name = "payment_reminder_days"
  display_name = "收款提前提醒(天)"
  field_type = "number"
  default_value = 3
  range = [1.0, 30.0]
  group = "提醒"

  [[settings.fields]]
  name = "notify_contract_expiring"
  display_name = "合同到期提醒"
  field_type = "boolean"
  default_value = true
  group = "提醒"

  [[settings.fields]]
  name = "notify_payment_overdue"
  display_name = "逾期收款提醒"
  field_type = "boolean"
  default_value = true
  group = "提醒"

  [[settings.fields]]
  name = "notify_opportunity_followup"
  display_name = "商机跟进提醒"
  field_type = "boolean"
  default_value = true
  group = "提醒"
```

### Task 1.2: 新增 `[[trigger_events]]` 段落

在 `[settings]` 之后插入 5 个触发事件：

```toml
[[trigger_events]]
name = "opportunity_stage_changed"
display_name = "商机阶段变更"
description = "商机阶段发生变化时通知，特别是成交或失败"
entity = "opportunity"
on = "update"

[[trigger_events]]
name = "contract_status_changed"
display_name = "合同状态变更"
description = "合同状态变化时检查到期预警"
entity = "contract"
on = "update"

[[trigger_events]]
name = "invoice_status_changed"
display_name = "发票状态变更"
description = "发票状态变化时检查逾期收款"
entity = "invoice"
on = "update"

[[trigger_events]]
name = "task_status_changed"
display_name = "任务状态变更"
description = "任务完成或取消时通知"
entity = "task"
on = "update"

[[trigger_events]]
name = "expense_created"
display_name = "新支出记录"
description = "记录新支出时通知"
entity = "expense"
on = "create"
```

### Task 1.3: 追加 cascade 属性（5 处已有字段）

**1.3a** contract.opportunity_id（第 450-454 行）追加：
```toml
  cascade_from = "client_id"
  cascade_filter = "client_id"
```

**1.3b** contract.quote_id（第 456-460 行）追加：
```toml
  cascade_from = "client_id"
  cascade_filter = "client_id"
```

**1.3c** invoice.project_id（第 796-800 行）追加：
```toml
  cascade_from = "client_id"
  cascade_filter = "client_id"
```

**1.3d** invoice.contract_id（第 802-806 行）追加：
```toml
  cascade_from = "client_id"
  cascade_filter = "client_id"
```

**1.3e** time_entry.task_id（第 745-751 行）追加：
```toml
  cascade_from = "project_id"
  cascade_filter = "project_id"
```

### Task 1.4: 追加 visible_when 属性（4 处已有字段）

**1.4a** invoice.payment_date（第 860-863 行）追加：
```toml
  visible_when = "status == 'paid' || status == 'partial'"
```

**1.4b** contract.paid_amount（第 516-520 行）追加：
```toml
  visible_when = "status != 'drafting'"
```

**1.4c** task.actual_hours（第 727-730 行）追加：
```toml
  visible_when = "status != 'todo'"
```

**1.4d** quote.total_amount（第 357-361 行）追加：
```toml
  visible_when = "status != 'draft'"
```

### Task 1.5: 追加 validation 属性（2 处已有字段）

**1.5a** client.phone（第 135-138 行）追加：
```toml
  validation = { pattern = "^1[3-9]\\d{9}$", message = "请输入有效的手机号" }
```

**1.5b** client.email（第 140-143 行）追加：
```toml
  validation = { pattern = "^[^@]+@[^@]+\\.[^@]+$", message = "请输入有效的邮箱地址" }
```

### Task 1.6: 编译 WASM + 升级插件

```bash
cargo build -p erp-plugin-freelance --target wasm32-unknown-unknown --release
wasm-tools component new target/wasm32-unknown-unknown/release/erp_plugin_freelance.wasm -o target/erp_plugin_freelance.component.wasm
```

通过 API 升级：
```bash
# 上传新版本 WASM
curl -X POST http://localhost:3000/api/v1/admin/plugins/{plugin_id}/upgrade \
  -H "Authorization: Bearer {token}" \
  -F "wasm=@target/erp_plugin_freelance.component.wasm" \
  -F "manifest=@crates/erp-plugin-freelance/plugin.toml"
```

### Task 1.7: 验证

- [ ] `cargo check` 通过
- [ ] 重新登录获取新 JWT（权限可能变化）
- [ ] 前端打开 freelance 插件 → 设置页面可见 7 个配置项
- [ ] 创建客户 → phone 格式错误时提示校验信息
- [ ] 创建客户 → email 格式错误时提示校验信息
- [ ] 创建合同 → 选客户后 opportunity_id 和 quote_id 自动过滤
- [ ] 创建发票 → 选客户后 project_id 和 contract_id 自动过滤
- [ ] 创建工时 → 选项目后 task_id 自动过滤
- [ ] invoice 状态为 pending 时，payment_date 字段不显示
- [ ] contract 状态为 drafting 时，paid_amount 字段不显示
- [ ] 触发事件：更新商机阶段 → 消息中心收到通知
- [ ] `git add && git commit && git push`

---

## Phase 2: itops Layer 1 — 智能业务引擎

**目标文件:** `crates/erp-plugin-itops/plugin.toml`

### Task 2.1: 新增 `[settings]` 段落

在 `[[numbering]]` 之前插入 4 个配置项：

```toml
[settings]

  [[settings.fields]]
  name = "default_sla_response"
  display_name = "默认SLA响应时间(小时)"
  field_type = "number"
  default_value = 8
  range = [1.0, 72.0]
  group = "SLA"

  [[settings.fields]]
  name = "default_sla_resolve"
  display_name = "默认SLA解决时间(小时)"
  field_type = "number"
  default_value = 48
  range = [1.0, 168.0]
  group = "SLA"

  [[settings.fields]]
  name = "notify_sla_breach"
  display_name = "SLA超标提醒"
  field_type = "boolean"
  default_value = true
  group = "提醒"

  [[settings.fields]]
  name = "notify_check_due"
  display_name = "巡检到期提醒"
  field_type = "boolean"
  default_value = true
  group = "提醒"
```

### Task 2.2: 新增 `[[trigger_events]]` 段落

在 `[settings]` 之后插入 4 个触发事件：

```toml
[[trigger_events]]
name = "ticket_created"
display_name = "新工单"
description = "创建工单时开始SLA计时并通知"
entity = "ticket"
on = "create"

[[trigger_events]]
name = "ticket_status_changed"
display_name = "工单状态变更"
description = "工单状态变化时检查SLA是否达标"
entity = "ticket"
on = "update"

[[trigger_events]]
name = "contract_status_changed"
display_name = "维保合同状态变更"
description = "合同状态变化时检查到期预警"
entity = "service_contract"
on = "update"

[[trigger_events]]
name = "check_plan_updated"
display_name = "巡检计划更新"
description = "巡检计划更新时检查下次巡检日期"
entity = "check_plan"
on = "update"
```

### Task 2.3: 追加 cascade 属性（2 处已有字段）

**2.3a** ticket.contract_id（第 186-192 行）追加：
```toml
  cascade_from = "client_id"
  cascade_filter = "client_id"
```

**2.3b** check_record.contract_id（第 398-400 行）追加：
```toml
  cascade_from = "plan_id"
  cascade_filter = "contract_id"
```

### Task 2.4: 追加 visible_when 属性（6 处已有字段）

**2.4a** ticket.resolution → `visible_when = "status == 'resolved' || status == 'closed'"`
**2.4b** ticket.responded_at → `visible_when = "status != 'open'"`
**2.4c** ticket.resolved_at → `visible_when = "status == 'resolved' || status == 'closed'"`
**2.4d** ticket.closed_at → `visible_when = "status == 'closed'"`
**2.4e** check_record.issues_found → `visible_when = "result == 'abnormal'"`
**2.4f** check_record.actions_taken → `visible_when = "result == 'abnormal'"`

### Task 2.5: 追加 validation 属性（1 处已有字段）

**2.5a** service_contract.contract_number（第 73-78 行）追加：
```toml
  validation = { pattern = "^SC-\\d{4}-\\d{4}$", message = "格式：SC-YYYY-NNNN" }
```

### Task 2.6: 编译 WASM + 升级插件

```bash
cargo build -p erp-plugin-itops --target wasm32-unknown-unknown --release
wasm-tools component new target/wasm32-unknown-unknown/release/erp_plugin_itops.wasm -o target/erp_plugin_itops.component.wasm
```

### Task 2.7: 验证

- [ ] `cargo check` 通过
- [ ] 重新登录获取新 JWT
- [ ] 前端打开 itops 插件 → 设置页面可见 4 个配置项
- [ ] 创建工单 → 选客户后 contract_id 自动过滤
- [ ] 工单状态为 open 时，resolution/resolved_at/closed_at 不显示
- [ ] 工单状态改为 resolved → resolution 和 resolved_at 出现
- [ ] 巡检记录结果为 normal → issues_found/actions_taken 不显示
- [ ] 巡检记录结果改为 abnormal → issues_found/actions_taken 出现
- [ ] 触发事件：创建工单 → 消息中心收到通知
- [ ] `git add && git commit && git push`

---

## Phase 3: freelance Layer 3 — PDF 模板

**目标文件:** `crates/erp-plugin-freelance/plugin.toml`

### Task 3.1: 新增 `[[templates]]` 段落（3 个模板）

在 `[[ui.pages]]` 之前插入报价单、发票、合同 3 个 PDF 模板。

**报价单模板** (`quote_pdf`)：
- entity = "quote"
- 包含 Handlebars 语法：`{{quote_number}}`, `{{client.name}}`, `{{#each lines}}`
- 表格渲染：item_name / description / quantity / unit_price / amount
- 底部：subtotal / tax_rate / total_amount

**发票模板** (`invoice_pdf`)：
- entity = "invoice"
- grid 布局：client.name / type / issue_date / due_date
- 大字金额：`¥{{amount}}`
- 状态 badge

**合同模板** (`contract_pdf`)：
- entity = "contract"
- 签章区域：甲方/乙方
- parties 区块：client.name / amount / paid_amount / 期限 / payment_terms

### Task 3.2: 编译 WASM + 升级

同 Task 1.6 流程。

### Task 3.3: 验证

- [ ] 前端打开报价单详情 → 可见"生成 PDF"按钮
- [ ] 点击生成 → 下载 PDF，内容包含正确的字段值
- [ ] 发票 PDF → 金额/客户名正确
- [ ] 合同 PDF → 签章区域正确
- [ ] `git add && git commit && git push`

---

## Phase 4: itops Layer 3 — 维保合同 PDF 模板

**目标文件:** `crates/erp-plugin-itops/plugin.toml`

### Task 4.1: 新增 `[[templates]]` 段落（1 个模板）

维保合同模板 (`service_contract_pdf`)：
- entity = "service_contract"
- SLA 承诺框：响应/解决时间
- grid 布局：client.name / amount / 期限 / status
- 服务范围 / 付款条款 / 签章区

### Task 4.2: 编译 WASM + 升级

同 Task 2.6 流程。

### Task 4.3: 验证

- [ ] 前端打开维保合同详情 → 可见"生成 PDF"按钮
- [ ] 点击生成 → 下载 PDF，SLA 承诺正确
- [ ] `git add && git commit && git push`

---

## Phase 5: 平台 dashboard widgets 扩展

> **注意：** 此阶段需要修改平台 Rust 代码 + 前端代码，不是纯 plugin.toml 改动。

### Task 5.1: 扩展 manifest.rs — 定义 PluginWidget 类型

**目标文件:** `crates/erp-plugin/src/manifest.rs`

在 `PluginPageType::Dashboard` 结构体中新增 `widgets` 字段：

```rust
// PluginPageType::Dashboard 新增字段
Dashboard {
    label: String,
    #[serde(default)]
    icon: Option<String>,
    #[serde(default)]
    widgets: Option<Vec<PluginWidget>>,  // 新增
},
```

定义 `PluginWidget` 枚举及其子类型：

```rust
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum PluginWidget {
    StatCards {
        label: String,
        cards: Vec<StatCard>,
    },
    ActionList {
        label: String,
        #[serde(default)]
        max_items: Option<u32>,
        queries: Vec<ActionQuery>,
    },
    Funnel {
        label: String,
        entity: String,
        lane_field: String,
        #[serde(default)]
        value_field: Option<String>,
        lane_order: Vec<String>,
    },
    CardList {
        label: String,
        entity: String,
        #[serde(default)]
        filter: Option<String>,
        #[serde(default)]
        max_items: Option<u32>,
        title_field: String,
        #[serde(default)]
        subtitle_field: Option<String>,
        #[serde(default)]
        tags: Vec<String>,
    },
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct StatCard {
    pub entity: String,
    #[serde(default)]
    pub aggregate: Option<String>,  // count, sum
    #[serde(default)]
    pub field: Option<String>,
    #[serde(default)]
    pub filter: Option<String>,
    pub label: String,
    #[serde(default)]
    pub icon: Option<String>,
    #[serde(default)]
    pub color: Option<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ActionQuery {
    pub entity: String,
    #[serde(default)]
    pub filter: Option<String>,
    #[serde(default)]
    pub sort: Option<String>,
    pub label_field: String,
    #[serde(default)]
    pub subtitle_field: Option<String>,
    pub action: String,
    #[serde(default)]
    pub icon: Option<String>,
}
```

### Task 5.2: 扩展插件 API — 返回 widgets 数据

**目标文件:** `crates/erp-plugin/src/module.rs`

新增 API 端点，为 dashboard widgets 提供数据：

- `GET /api/v1/plugins/{plugin_id}/dashboard/widgets` — 返回 widgets 定义
- `GET /api/v1/plugins/{plugin_id}/dashboard/data` — 返回 widgets 聚合数据（调用已有 count/aggregate API）

### Task 5.3: 前端渲染 dashboard widgets

**目标目录:** `apps/web/src/`

新增组件：
- `PluginDashboard.tsx` — 仪表盘容器，读取 widgets 定义并渲染
- `StatCardsWidget.tsx` — 统计卡片组件（4 个指标卡片）
- `ActionListWidget.tsx` — 待办列表组件
- `FunnelWidget.tsx` — 漏斗图组件
- `CardListWidget.tsx` — 卡片列表组件

### Task 5.4: 验证

- [ ] `cargo check` 通过
- [ ] 前端 `pnpm build` 通过
- [ ] manifest.rs 正确解析 widgets TOML
- [ ] API 返回 widgets 定义和聚合数据
- [ ] `git add && git commit && git push`

---

## Phase 6: freelance + itops Layer 2 — 仪表盘 widgets

> **前置：** Phase 5 完成（平台支持 widgets）

### Task 6.1: freelance — 替换仪表盘页面为 widgets 版本

**目标文件:** `crates/erp-plugin-freelance/plugin.toml`

将现有的空仪表盘（第 949-952 行）替换为包含 4 个 widgets 的完整仪表盘：
1. stat_cards — 财务概览（4 张卡片）
2. action_list — 紧急待办（4 种查询）
3. funnel — 商机漏斗
4. card_list — 活跃项目

### Task 6.2: itops — 新增仪表盘页面到最前面

**目标文件:** `crates/erp-plugin-itops/plugin.toml`

在现有页面列表最前面插入仪表盘页面（2 个 widgets）：
1. stat_cards — 运维概览（4 张卡片）
2. action_list — 紧急待办（3 种查询）

### Task 6.3: 两个插件各自编译 WASM + 升级

### Task 6.4: 验证

- [ ] freelance 仪表盘 → 4 个 widget 正确渲染
- [ ] itops 仪表盘 → 2 个 widget 正确渲染
- [ ] 财务卡片数值正确（调用 aggregate API）
- [ ] 紧急待办列表有数据时显示条目
- [ ] 商机漏斗按阶段显示金额分布
- [ ] `git add && git commit && git push`

---

## 执行策略

**P1-P4 并行策略：** P1 和 P2 可以同时开始（不同文件），P3 和 P4 在 P1/P2 完成后立即跟进。每个 Phase 独立编译 WASM、独立验证、独立提交。

**P5-P6 顺序策略：** P5 是平台改动（Rust + 前端），P6 依赖 P5 的平台能力才能生效。

**预估工作量：**
- P1: 30-40 分钟（plugin.toml 编辑 + 编译 + 验证）
- P2: 20-30 分钟（规模小于 P1）
- P3: 15-20 分钟（3 个模板插入）
- P4: 10-15 分钟（1 个模板插入）
- P5: 60-90 分钟（manifest 扩展 + API + 前端组件）
- P6: 20-30 分钟（plugin.toml widgets 声明）