erp/docs/superpowers/specs/2026-04-18-crm-plugin-platform-p0-design.md

# CRM 插件平台标杆 — P0 基础能力设计规格

> **版本**: v1.1 (修正版 — 基于代码审查发现，对齐现有实现)
> **日期**: 2026-04-18
> **状态**: Draft
> **定位**: 插件平台标杆 — CRM 是试金石，打磨通用能力

---

## 1. 背景与动机

### 1.1 为什么要做这个

CRM 插件是 ERP 平台的第一个行业插件，当前状态是"客户通讯录 + 标签 + 关系图谱"，距离一流 CRM（Salesforce/HubSpot/Pipedrive）有显著差距。但更大的问题是：**CRM 暴露的差距不在于 CRM 本身，而在于插件平台的基础能力缺失。**

具体来说：
- ~~5 个实体之间有明确的 FK 关系，但 manifest 无法声明~~ → **已有 `PluginRelation` + 级联删除**，但缺少 `name`/`display_field`/关系类型等前端渲染信息
- 35+ 字段有 required/unique/pattern 校验，但缺少 `min_length`/`max_length`/`min_value`/`max_value` 扩展校验
- Dashboard/Graph 页面硬编码了 CRM 专属颜色和标题，第二个插件无法复用
- CRM 的 `plugin.toml` 没有声明 `relations`，导致现有级联能力未被使用
- 批量删除和 PATCH 部分更新绕过了现有校验

如果不在 P0 阶段补齐这些基础，所有后续业务功能（商机、合同、报价）都会建在不稳固的地基上。

### 1.2 设计原则

| 原则 | 含义 |
|------|------|
| **平台优先** | 每个能力都是平台层的，CRM 只是第一个使用者 |
| **零改动复用** | inventory/生产/财务插件不应为这些能力写任何额外代码 |
| **Manifest 驱动** | 所有行为由 plugin.toml 声明驱动，不写硬编码 |
| **双层保障** | 前端即时反馈 + 后端最终防线，缺一不可 |

### 1.3 一流 CRM 差距分析摘要

| 类别 | 差距 | 本规格是否覆盖 |
|------|------|--------------|
| 实体关系 + 级联删除 | 致命 — 删除客户产生孤儿数据 | **P0-1 覆盖** |
| 字段校验 + FK 完整性 | 严重 — 数据质量无保障 | **P0-2 覆盖** |
| 前端通用化 | 中等 — 第二个插件无法复用 Dashboard/Graph | **P0-3 覆盖** |
| 商机/漏斗/合同 | 严重 — 核心业务缺失 | P2（本规格不覆盖） |
| 导入导出/批量操作 | 中等 — ERP 刚需 | P1（后续规格） |
| 全局搜索/保存视图 | 中等 — UX 缺失 | P1（后续规格） |
| WASM 活化 | 低 — 当前空操作不影响功能 | P2（后续规格） |

---

## 2. P0-1: 实体关系声明 + ref_entity + 级联策略

### 2.1 Manifest Schema 扩展

**现有基础**：`PluginRelation` 已存在（`manifest.rs:184-189`），包含 `entity`、`foreign_key`、`on_delete` 三个字段。级联删除已在 `data_service.rs:330-395` 中实现。

**扩展方向**：在现有结构上新增字段，保持向后兼容。

```toml
# === 一对多关系 (customer → contacts) ===
[[schema.entities.relations]]
entity = "contact"                      # 目标实体 (已有字段)
foreign_key = "customer_id"             # FK 字段 (已有字段)
on_delete = "cascade"                   # cascade | nullify | restrict (已有枚举)
# ↓ 新增字段 (可选，向后兼容)
name = "contacts"                       # 关系显示名，用于前端标签
type = "one_to_many"                    # 关系类型 (one_to_many | many_to_one | many_to_many)
display_field = "name"                  # EntitySelect 下拉显示字段

# === 多对一关系 (contact → customer，含自引用) ===
[[schema.entities.relations]]
entity = "customer"
foreign_key = "parent_id"
on_delete = "nullify"
name = "parent"
type = "many_to_one"
display_field = "name"

# === 多对多关系 (customer ↔ customer，通过中间表) ===
[[schema.entities.relations]]
entity = "customer"
foreign_key = "from_customer_id"         # 中间表中的源 FK
on_delete = "nullify"
name = "related_customers"
type = "many_to_many"
through_entity = "customer_relationship"
through_source_field = "from_customer_id"
through_target_field = "to_customer_id"
```

#### 关系类型定义 (新增 `type` 字段)

| 类型 | 含义 | foreign_key 位置 | CRM 场景 |
|------|------|-----------------|---------|
| `one_to_many` | 一个父 → 多个子 | 子实体上 | customer → contacts |
| `many_to_one` | 多个子 → 一个父 | 本实体上 | contact → customer |
| `many_to_many` | 双向多对多 | 中间表上 | customer ↔ customer |

> `type` 字段为 `Option<RelationType>`，默认 `OneToMany`。不声明则现有行为不变。

#### 级联策略 (保持现有枚举不变)

| 策略 | TOML 值 | 行为 | 适用场景 |
|------|---------|------|---------|
| `Cascade` | `"cascade"` | 子记录 `deleted_at = now()` | 强所有权：客户→联系人 |
| `Nullify` | `"nullify"` | FK 字段设 NULL | 弱引用：联系人→上级客户 |
| `Restrict` | `"restrict"` | 有子记录时阻止删除(409) | 关键数据：不允许孤立 |

### 2.2 后端实现

#### 数据结构扩展 (`manifest.rs`)

**在现有 `PluginRelation` 上新增字段**（不替换）：

```rust
// 现有字段保持不变
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PluginRelation {
    pub entity: String,          // 已有
    pub foreign_key: String,     // 已有
    pub on_delete: OnDeleteStrategy,  // 已有 (Cascade | Nullify | Restrict)
    // ↓ 新增可选字段
    #[serde(default)]
    pub name: Option<String>,
    #[serde(default, rename = "type")]
    pub relation_type: Option<RelationType>,
    #[serde(default)]
    pub display_field: Option<String>,
    // many_to_many 专属
    #[serde(default)]
    pub through_entity: Option<String>,
    #[serde(default)]
    pub through_source_field: Option<String>,
    #[serde(default)]
    pub through_target_field: Option<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
#[serde(rename_all = "snake_case")]
pub enum RelationType {
    #[default]
    OneToMany,
    ManyToOne,
    ManyToMany,
}
```

#### 级联删除 (已有，需增强)

`data_service.rs:330-395` 已实现 `Restrict`/`Nullify`/`Cascade` 三种策略。需增强：

1. **级联影响信息返回**：Restrict 时返回 `affected_count` 和 `relation.name`，方便前端展示
2. **批量删除级联**：`batch_delete` (data_service.rs:417-520) 当前绕过级联，需补充
3. **many_to_many 级联**：基于 `through_entity` 清理中间表记录

#### 级联策略执行 (已有，需增强错误信息)

现有 `data_service.rs:330-395` 已实现。增强点：

1. **Restrict 错误增强**：返回 `affected_count` 和 `relation.name`
2. **批量删除级联**：`batch_delete` (data_service.rs:417-520) 当前绕过级联，需补充
3. **PATCH 校验**：`partial_update` (data_service.rs:291-327) 当前绕过 `validate_data`，需补充
4. **many_to_many 级联**：基于 `through_entity` 清理中间表记录

#### FK 存在性校验 (已有 `validate_ref_entities`)

`data_service.rs:834-899` 已实现 `validate_ref_entities`。需确保 `partial_update` (PATCH) 也调用此函数。

### 2.3 前端实现

#### 前端类型扩展

`apps/web/src/api/plugins.ts` 需更新：

```typescript
// PluginEntitySchema 新增
interface PluginEntitySchema {
  // ... existing fields
  relations?: PluginRelationSchema[];
}

interface PluginRelationSchema {
  entity: string;
  foreign_key: string;
  on_delete: 'cascade' | 'nullify' | 'restrict';
  name?: string;
  type?: 'one_to_many' | 'many_to_one' | 'many_to_many';
  display_field?: string;
}

// PluginFieldSchema 新增 validation 属性
interface PluginFieldSchema {
  // ... existing fields
  validation?: {
    pattern?: string;
    message?: string;
    min_length?: number;
    max_length?: number;
    min_value?: number;
    max_value?: number;
  };
}
```

#### EntitySelect 增强 (已有基础)

字段有 `ref_entity` 属性时，CRUD 表单已自动渲染为 EntitySelect。增强点：
- 优先使用 `relation.display_field` 作为下拉显示字段（fallback 到现有 `ref_label_field`）
- 关联子表标题使用 `relation.name`

#### 详情页关联子表自动渲染

Entity 的 `one_to_many` relations 自动在详情页渲染为内嵌 CRUD 表格：
- Compact 模式 + 自动过滤 `fk = parent_record.id`
- 支持新增/编辑/删除子记录
- 标题使用 `relation.name`

#### 级联删除确认

删除有 incoming relations 的记录时，弹出确认：
```
确定删除客户「{name}」？
此操作将同时删除：
- 3 条联系人记录
- 5 条沟通记录
- 2 条标签记录
```

### 2.4 CRM plugin.toml 改造

为 customer 实体补充 relations：

```toml
[[schema.entities.relations]]
entity = "contact"
foreign_key = "customer_id"
on_delete = "cascade"
name = "contacts"
type = "one_to_many"
display_field = "name"

[[schema.entities.relations]]
entity = "communication"
foreign_key = "customer_id"
on_delete = "cascade"
name = "communications"
type = "one_to_many"
display_field = "subject"

[[schema.entities.relations]]
entity = "customer_tag"
foreign_key = "customer_id"
on_delete = "cascade"
name = "tags"
type = "one_to_many"
display_field = "tag_name"

[[schema.entities.relations]]
entity = "customer"
foreign_key = "parent_id"
on_delete = "nullify"
name = "parent"
type = "many_to_one"
display_field = "name"
```

为 contact 实体补充 relations：

```toml
[[schema.entities.relations]]
entity = "communication"
foreign_key = "contact_id"
on_delete = "cascade"
name = "communications"
type = "one_to_many"
display_field = "subject"
```

---

## 3. P0-2: 字段校验层

### 3.1 现有基础

**已有实现**：
- `validate_data` (`data_service.rs:797-831`): required + pattern 正则校验
- `validate_ref_entities` (`data_service.rs:834-899`): FK 引用存在性校验
- `FieldValidation` (`manifest.rs:53-57`): `pattern` + `message` 字段
- unique 检查已在 `create`/`update` 流程中实现

**缺失部分**：
- `min_length` / `max_length` 校验器
- `min_value` / `max_value` 校验器
- PATCH (partial_update) 绕过所有校验
- 前端 TypeScript 类型缺少 `validation` 属性

### 3.2 Manifest Schema 扩展

在现有 `[validation]` 上新增字段（`manifest.rs:53-57` 已有 `pattern` + `message`）：

```toml
[[schema.entities.fields]]
name = "phone"
field_type = "string"
display_name = "手机号"

[schema.entities.fields.validation]
pattern = "^1[3-9]\\d{9}$"
message = "请输入有效的手机号码"
min_length = 11
max_length = 11

[[schema.entities.fields]]
name = "credit_limit"
field_type = "decimal"

[schema.entities.fields.validation]
min_value = 0
max_value = 99999999
message = "信用额度必须在 0-99999999 之间"
```

#### 校验类型定义

| 校验器 | manifest 字段 | 状态 | 说明 |
|--------|-------------|------|------|
| `required` | `field.required` | **已有** | 值不能为 null/空字符串 |
| `unique` | `field.unique` | **已有** | 同 tenant 内值唯一 |
| `pattern` | `validation.pattern` + `validation.message` | **已有** | 正则匹配 |
| `ref_exists` | `field.ref_entity` | **已有** | FK 指向的记录存在且未删除 |
| `min_length` / `max_length` | `validation.min_length` / `validation.max_length` | **新增** | 字符串长度范围 |
| `min_value` / `max_value` | `validation.min_value` / `validation.max_value` | **新增** | 数值范围 |

### 3.3 后端实现

#### 扩展 `FieldValidation` (`manifest.rs:53-57`)

在现有结构上新增 4 个可选字段：

```rust
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FieldValidation {
    pub pattern: Option<String>,     // 已有
    pub message: Option<String>,     // 已有
    // ↓ 新增
    pub min_length: Option<usize>,
    pub max_length: Option<usize>,
    pub min_value: Option<f64>,
    pub max_value: Option<f64>,
}
```

#### 扩展 `validate_data` (`data_service.rs:797-831`)

在现有函数中追加 min_length/max_length/min_value/max_value 检查：

```rust
// 现有: required + pattern 检查 (已实现)
// 新增:
if let Some(validation) = &field.validation {
    // min_length / max_length
    if let Some(str_val) = val.as_str() {
        if let Some(min) = validation.min_length {
            if str_val.len() < min { return Err(...); }
        }
        if let Some(max) = validation.max_length {
            if str_val.len() > max { return Err(...); }
        }
    }
    // min_value / max_value (适用于 number/integer/decimal)
    if let Some(num_val) = val.as_f64() {
        if let Some(min) = validation.min_value {
            if num_val < min { return Err(...); }
        }
        if let Some(max) = validation.max_value {
            if num_val > max { return Err(...); }
        }
    }
}
```

#### 修复 PATCH 校验缺失

`partial_update` (`data_service.rs:291-327`) 需要添加 `validate_data` 和 `validate_ref_entities` 调用，与 `update` 保持一致。

**执行位置:** `data_service.rs` 的 `create_record` 和 `update_record` 方法中，数据写入前调用 `validate_record`。

**错误响应格式:**

```json
{
  "success": false,
  "error": "数据验证失败",
  "details": [
    { "field": "phone", "message": "请输入有效的手机号码" },
    { "field": "customer_id", "message": "引用的客户不存在" }
  ]
}
```

### 3.4 前端实现

从 schema 自动生成 Ant Design Form rules（需先修复 TypeScript 类型缺失）：

```typescript
function generateFormRules(field: PluginFieldSchema): Rule[] {
  const rules: Rule[] = [];

  if (field.required) {
    rules.push({ required: true, message: `${field.display_name}不能为空` });
  }

  if (field.validation?.pattern) {
    rules.push({
      pattern: new RegExp(field.validation.pattern),
      message: field.validation.message || `${field.display_name}格式不正确`,
    });
  }

  if (field.validation?.min_length || field.validation?.max_length) {
    rules.push({
      min: field.validation.min_length,
      max: field.validation.max_length,
      message: field.validation.message || `${field.display_name}长度不正确`,
    });
  }

  return rules;
}
```

### 3.5 CRM plugin.toml 补充校验

```toml
# phone 字段
[schema.entities.fields.validation]
pattern = "^1[3-9]\\d{9}$"
message = "请输入有效的手机号码"

# email 字段
[schema.entities.fields.validation]
pattern = "^[\\w.+-]+@[\\w.-]+\\.[a-zA-Z]{2,}$"
message = "请输入有效的邮箱地址"

# credit_code 字段
[schema.entities.fields.validation]
pattern = "^[0-9A-HJ-NP-RTUW-Y]{2}\\d{6}[0-9A-HJ-NP-RTUW-Y]{10}$"
message = "请输入有效的统一社会信用代码"

# website 字段
[schema.entities.fields.validation]
pattern = "^https?://[\\w.-]+(?:\\.[\\w.-]+)+[/#?]?.*$"
message = "请输入有效的网址"
```

---

## 4. P0-3: 前端去硬编码

### 4.1 Dashboard 通用化

**涉及文件:**
- `apps/web/src/pages/dashboard/dashboardConstants.tsx`
- `apps/web/src/pages/dashboard/DashboardWidgets.tsx`
- `apps/web/src/pages/PluginDashboardPage.tsx`

**改造方案:**

| 当前硬编码 | 通用化方案 |
|-----------|-----------|
| `ENTITY_COLORS`: customer→indigo, contact→green, ... | 8 色调色板按 entity 顺序自动分配 |
| `ENTITY_ICONS`: customer→TeamOutlined, ... | 从 page schema 的 icon 字段读取 |
| 标题 "CRM 数据全景视图" | `{manifest.name} 统计概览` |
| 副标题 "实时掌握业务动态" | `{manifest.description}` 截取前 50 字 |

**通用调色板:**

```typescript
const UNIVERSAL_PALETTE = [
  '#6366f1', // indigo
  '#22c55e', // green
  '#f59e0b', // amber
  '#8b5cf6', // violet
  '#ef4444', // red
  '#06b6d4', // cyan
  '#f97316', // orange
  '#ec4899', // pink
];
```

### 4.2 Graph 通用化

**涉及文件:** `apps/web/src/pages/plugins/graph/graphConstants.ts`

**改造方案:**

| 当前硬编码 | 通用化方案 |
|-----------|-----------|
| `RELATIONSHIP_COLORS`: parent_child→indigo, ... | 调色板按 option 顺序循环 |
| `RELATIONSHIP_LABELS`: parent_child→"母子", ... | 从 field.options[].label 读取 |
| `RELATIONSHIP_TYPES` 固定 5 种 | 从 schema 动态生成 |

### 4.3 CRUD 表格列可配置

**涉及文件:** `apps/web/src/pages/PluginCRUDPage.tsx`

**改造方案:**

manifest page 新增可选字段 `table_columns`:

```toml
[[ui.pages]]
type = "crud"
entity = "customer"
table_columns = ["code", "name", "customer_type", "level", "status", "owner_id", "region", "industry"]
```

不声明时默认行为：
- 取前 8 个非 hidden 非 FK 字段
- 替换当前 `fields.slice(0, 5)` 硬编码

### 4.4 验证标准

> **测试: 将 CRM 插件替换为 inventory 插件，Dashboard/Graph/CRUD 页面应零改动正确渲染。**

具体验证：
1. Dashboard 显示 inventory 的 6 个实体统计，颜色按顺序分配
2. Graph 如果 inventory 有关系数据，渲染正确（无数据则显示空状态）
3. CRUD 表格按 `table_columns` 或默认 8 列显示

---

## 5. 关键文件清单

### 后端 Rust

| 文件 | 改动类型 | 说明 |
|------|---------|------|
| `crates/erp-plugin/src/manifest.rs` | 修改 | `PluginRelation` 新增 name/type/display_field/through_* 字段；`FieldValidation` 新增 min_length/max_length/min_value/max_value |
| `crates/erp-plugin/src/data_service.rs` | 修改 | 扩展 `validate_data` 增加 min/max 校验；`partial_update` 补充校验调用；`batch_delete` 补充级联 |
| `crates/erp-plugin-crm/plugin.toml` | 修改 | 补充 relations 声明 + validation 规则 |

> 注意：不新建 `validation.rs`，直接扩展现有 `validate_data` 和 `validate_ref_entities`。

### 前端 TypeScript

| 文件 | 改动类型 | 说明 |
|------|---------|------|
| `apps/web/src/api/plugins.ts` | 修改 | `PluginEntitySchema` 新增 `relations`；`PluginFieldSchema` 新增 `validation` |
| `apps/web/src/pages/dashboard/dashboardConstants.tsx` | 修改 | 去硬编码，通用调色板自动分配 |
| `apps/web/src/pages/dashboard/DashboardWidgets.tsx` | 修改 | schema 驱动颜色/图标 |
| `apps/web/src/pages/PluginDashboardPage.tsx` | 修改 | 通用标题/副标题 |
| `apps/web/src/pages/plugins/graph/graphConstants.ts` | 修改 | 关系类型从 options 动态读取 |
| `apps/web/src/pages/PluginCRUDPage.tsx` | 修改 | 可配置列数 + Form rules 自动生成 |

---

## 6. 验证方案

### 6.1 编译与测试

```bash
cargo check                              # 全 workspace 编译
cargo test --workspace                   # 全量测试
```

### 6.2 单元测试

- `validation.rs`: 每种校验器独立测试 (required/unique/pattern/ref_exists/length/value range)
- `data_service.rs`: 级联策略测试 (cascade_soft_delete/set_null/restrict)

### 6.3 集成测试 (Testcontainers)

- 删除客户 → 验证联系人/沟通记录/标签级联软删除
- 删除有 restrict 关系的记录 → 验证 409 响应
- 创建联系人 → customer_id 不存在时验证 400
- 创建客户 → phone 格式不正确时验证 400 + 错误详情
- 创建客户 → code 已存在时验证 409

### 6.4 功能验证

1. 重新安装 CRM 插件，确认 5 个 relation 正确注册到 entity metadata
2. 删除客户 → 确认关联数据正确级联
3. 手机号/邮箱格式校验 → 确认前后端双重拦截
4. Dashboard → 确认标题/颜色从 schema 动态生成
5. 切换 inventory 插件 → Dashboard/Graph 零改动渲染

### 6.5 前端验证

```bash
cd apps/web && pnpm dev
```

手动测试所有 CRM 页面，确认无回归。

---

## 7. 不在本规格范围内

| 项 | 原因 | 计划 |
|----|------|------|
| 商机 (Opportunity) / 销售漏斗 | CRM 业务功能，P2 范畴 | 后续规格 |
| 数据导入导出 (Excel) | 平台能力但工作量大 | P1 规格 |
| 通知规则 + 消息中心联动 | 需要跨模块协作 | P1 规格 |
| WASM 校验/计算 Hook | 平台能力但依赖 WASM 运行时增强 | P2 规格 |
| 全局搜索 / 保存视图 | UX 增强 | P1 规格 |
| Lead 线索实体 | CRM 业务功能 | P2 规格 |