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

## Context

CRM 插件作为 ERP 平台的第一个行业插件，目前暴露了插件平台的多项基础能力缺口。本次设计的定位不是"CRM 功能最全"，而是"插件平台能力最扎实"——通过 CRM 验证的每个能力都应被所有未来插件（inventory、生产、财务等）零改动复用。

对标一流 CRM（Salesforce/HubSpot/Pipedrive）的差距分析表明，当前 CRM 更接近"客户通讯录+标签+图谱"，距离可用 CRM 有显著差距。但这些差距中，最优先补的是**平台基础设施**，而非 CRM 业务功能。

## 设计决策记录

| 决策点 | 选择 | 理由 |
|--------|------|------|
| 目标定位 | 插件平台标杆 | 打磨通用能力，所有插件受益 |
| 推进节奏 | P0 基础先行 | 基础不扎实，上层的业务功能无法可靠运行 |
| 实体关系复杂度 | 全覆盖 (1:N/N:1/N:N/自引用) | CRM 和 inventory 都需要，一次到位 |
| 字段校验范围 | 完整套件 (6种) | 数据质量是所有插件的生命线 |
| 前端硬编码 | 全部通用化 | 第二个插件必须零改动可用 |

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

### Manifest Schema 扩展

在 entity 下新增 `[[relations]]` 段：

```toml
[[schema.entities.relations]]
name = "contacts"                    # 关系名
target_entity = "contact"            # 目标实体
type = "one_to_many"                 # one_to_many | many_to_one | many_to_many
foreign_key = "customer_id"          # FK 字段
on_delete = "cascade_soft_delete"    # cascade_soft_delete | set_null | restrict
display_field = "name"               # 下拉框显示字段

# N:N 需要中间表
[[schema.entities.relations]]
name = "related_customers"
target_entity = "customer"
type = "many_to_many"
through_entity = "customer_relationship"
through_source_field = "from_customer_id"
through_target_field = "to_customer_id"
```

### 后端实现 (crates/erp-plugin/)

**关键文件:**
- `src/manifest.rs` — ManifestParser 新增 relations 解析
- `src/dynamic_table.rs` — 安装时存储关系到 entity metadata
- `src/data_service.rs` — 删除时执行级联策略，创建/更新时验证 FK
- `src/handler/data_handler.rs` — 错误响应格式

**级联策略执行流程:**
```
DELETE /plugins/{id}/{entity}/{rid}
  → 查询 entity 的所有 incoming relations (被引用的关系)
  → for each relation:
      cascade_soft_delete → UPDATE child SET deleted_at=now() WHERE fk=rid
      set_null            → UPDATE child SET fk=NULL WHERE fk=rid
      restrict            → SELECT COUNT children, if >0 return 409 Conflict
  → 软删除目标记录
```

**FK 存在性校验:**
```
POST/PUT /plugins/{id}/{entity}
  → for each field with ref_entity:
      SELECT EXISTS(SELECT 1 FROM plugin_xxx_{ref_entity} WHERE id=field_value AND deleted_at IS NULL)
      → 不存在则返回 400 + 具体字段错误
```

### 前端实现 (apps/web/)

**关键文件:**
- `src/pages/PluginCRUDPage.tsx` — 自动为 ref_entity 字段渲染 EntitySelect
- `src/pages/PluginDetailPage` — 自动渲染关联子实体内嵌列表
- `src/components/EntitySelect.tsx` — 增强支持 display_field 配置
- `src/api/plugins.ts` — schema 类型新增 relations

**详情页自动关联渲染:**
- 读取 entity 的 outgoing relations (one_to_many)
- 为每个 relation 渲染内嵌 CRUD 表格（compact 模式，带 filter=fk:parent_id）
- 级联删除前弹出确认（"将同时删除 3 条联系人"）

### CRM plugin.toml 改造

为 5 个实体补充 relations 声明：
- customer → contacts (1:N, cascade_soft_delete)
- customer → communications (1:N, cascade_soft_delete)
- customer → tags (1:N, cascade_soft_delete)
- customer → parent (N:1, set_null, 自引用)
- contact → communications (1:N, cascade_soft_delete)

---

## P0-2: 字段校验层

### Manifest Schema 扩展

在 field 下新增 `[validation]` 子结构：

```toml
[[schema.entities.fields]]
name = "phone"
field_type = "string"

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

[[schema.entities.fields]]
name = "email"
field_type = "string"

[schema.entities.fields.validation]
pattern = "^[\\w.-]+@[\\w.-]+\\.\\w+$"
message = "请输入有效的邮箱地址"
max_length = 254
```

### 后端校验器 (crates/erp-plugin/src/validation.rs — 新文件)

6 种校验器统一执行：

| 校验器 | 触发条件 | 错误格式 |
|--------|---------|---------|
| required | `field.required = true` | `{field}: 不能为空` |
| unique | `field.unique = true` | `{field}: 该值已存在` |
| pattern | `validation.pattern` regex match | `{field}: {validation.message}` |
| ref_exists | `field.ref_entity` FK 查询 | `{field}: 引用的{entity}不存在` |
| min_length / max_length | `validation.min_length / max_length` | `{field}: 长度必须在 {min}-{max} 之间` |
| min_value / max_value | `validation.min_value / max_value` | `{field}: 值必须在 {min}-{max} 之间` |

**执行位置:** `data_service.rs` 的 create/update 方法中，数据写入前统一调用。

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

### 前端校验生成

从 schema 自动生成 Ant Design Form rules：
- `required` → `{ required: true, message: "..." }`
- `pattern` → `{ pattern: /regex/, message: "..." }`
- `min_length / max_length` → `{ min: n, max: n, message: "..." }`

### CRM plugin.toml 补充校验

- phone: pattern 手机号
- email: pattern 邮箱
- credit_code: pattern 统一社会信用代码 (18位)
- website: pattern URL
- customer_id: ref_entity = "customer" (FK 校验)

---

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

### Dashboard 通用化

**文件:** `apps/web/src/pages/dashboard/dashboardConstants.tsx`, `PluginDashboardPage.tsx`

改造方案:
- 移除 `ENTITY_COLORS` 和 `ENTITY_ICONS` 硬编码映射
- 颜色自动分配: 8 色调色板按 entity 顺序循环
- 图标从 page schema 的 icon 字段读取
- 标题: `{manifest.name} 统计概览`，副标题: `{manifest.description}`
- Widget 定义从 page schema 的 widgets 数组读取

### Graph 通用化

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

改造方案:
- 移除 `RELATIONSHIP_COLORS` 硬编码
- 关系类型标签从 field.options 读取 (已有 label 映射)
- 颜色用调色板按 option 顺序循环分配
- 未知类型 fallback 到灰色 + 原始 label

### CRUD 表格列可配置

**文件:** `PluginCRUDPage.tsx`

改造方案:
- manifest page 新增 `table_columns: ["name", "customer_type", "level", "status", "owner_id"]`
- 不声明则默认取前 8 个非 hidden 非 FK 字段
- 移除 `fields.slice(0, 5)` 硬编码

### 验证标准

> 换成 inventory 插件，Dashboard/Graph/CRUD 应该零改动正确渲染。

---

## 关键文件清单

| 文件 | 改动类型 | 说明 |
|------|---------|------|
| `crates/erp-plugin/src/manifest.rs` | 修改 | 新增 relations + validation 解析 |
| `crates/erp-plugin/src/validation.rs` | 新建 | 校验引擎 |
| `crates/erp-plugin/src/data_service.rs` | 修改 | 集成级联策略 + 校验 |
| `crates/erp-plugin/src/dynamic_table.rs` | 修改 | 安装时存储关系元数据 |
| `crates/erp-plugin/src/handler/data_handler.rs` | 修改 | FK 校验错误格式 |
| `crates/erp-plugin-crm/plugin.toml` | 修改 | 补充 relations + 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` | 修改 | 可配置列数 |
| `apps/web/src/api/plugins.ts` | 修改 | 类型定义更新 |

---

## 验证方案

1. **编译检查**: `cargo check` 全 workspace 通过
2. **单元测试**: validation.rs 每种校验器独立测试
3. **集成测试**: Testcontainers 验证级联删除/FK 校验/unique 冲突
4. **功能验证**:
   - 重新安装 CRM 插件，确认 5 个 relation 正确注册
   - 删除客户 → 联系人/沟通记录/标签级联软删除
   - 创建联系人 → customer_id 不存在时返回 400
   - 手机号/邮箱格式不正确时返回校验错误
   - Dashboard 切换 inventory 插件时正确渲染
5. **前端验证**: `pnpm dev` 启动后手动测试所有页面

---

## 输出产物

1. 设计规格文档: `docs/superpowers/specs/2026-04-18-crm-plugin-platform-p0-design.md`
2. 实施计划: 通过 writing-plans skill 生成
3. 知识库文档: 记录讨论过程和决策理由