# CRM WASM 插件架构审查报告

> 审查人：后端架构师
> 日期：2026-04-15
> 审查对象：CRM 客户管理 WASM 插件设计方案

---

## 0. 审查前提：当前系统实际状态

经过对代码库的详细审查，我确认以下事实作为审查基础：

- **WIT 接口** (`crates/erp-plugin/wit/plugin.wit`)：9 个 Host API 函数（db-insert/db-query/db-update/db-delete/event-publish/config-get/log-write/current-user/check-permission）
- **动态表结构** (`crates/erp-plugin/src/dynamic_table.rs`)：每张表只有 `id`, `tenant_id`, `data`(JSONB), `created_at`, `updated_at`, `created_by`, `updated_by`, `deleted_at`, `version` 这 9 列。所有业务字段存储在 `data` JSONB 列中。
- **索引策略**：只为 `required` 和 `unique` 字段创建 GIN 索引（`data->>'field_name'`），没有复合索引能力。
- **查询能力** (`data_service.rs`)：`list()` 方法只支持按 tenant_id 过滤 + 分页，**不支持任何业务字段过滤**。`PluginDataListParams` 只有 `page`, `page_size`, `search` 三个参数。
- **前端 CRUD** (`PluginCRUDPage.tsx`)：纯粹的表单驱动，无过滤、无关联实体展示、无自定义操作。
- **设计规格文档** (`docs/superpowers/specs/2026-04-13-wasm-plugin-system-design.md`) 附录 D 中规划了 `db-aggregate` 接口，但**实际 WIT 文件中并未实现**。
- **设计规格文档**规划了 `render-page` / `handle-action` 插件导出函数，但**实际 WIT 中也没有**。

**结论：当前系统是一个 MVP 级别的插件原型，距离支撑 CRM 这种多实体、多关系的业务插件还有显著差距。**

---

## 1. JSONB 动态表能否支撑 CRM 数据模型？

### 1.1 结论：基本可行，但需要大幅增强查询能力

JSONB 存储本身不是问题。PostgreSQL 的 JSONB 在索引支持下，单字段等值查询和范围查询性能完全可以接受（毫秒级）。关键问题在于当前系统的**查询能力几乎为零**。

### 1.2 关系查询的实现路径

对于 CRM 中"A 的所有子客户"这类关系查询：

**方案 A：利用 JSONB 索引的等值过滤（推荐）**

`parent_id` 存储在 `data` JSONB 中。当前系统已有为 `required` 字段创建索引的逻辑：

```sql
-- 动态表已有的索引模式
CREATE INDEX idx_xxx_parent_id ON plugin_crm_customer (data->>'parent_id') WHERE deleted_at IS NULL;
```

查询"A 的直接子节点"只需：

```sql
SELECT * FROM plugin_crm_customer
WHERE tenant_id = $1 AND data->>'parent_id' = $2 AND deleted_at IS NULL;
```

这在有索引的情况下性能完全没问题，10 万条记录也能在 5ms 内返回。

**方案 B：递归查询（查询所有子孙节点）需要 db-query 增强**

当前的 `db_query` Host API 是预填充模式——Host 在执行 WASM 前就把查询结果塞进 `query_results` HashMap。WASM 内部只是读缓存。这意味着**插件无法控制 SQL 的构建过程**。

递归查询需要 PostgreSQL 的 `WITH RECURSIVE` CTE：

```sql
WITH RECURSIVE descendants AS (
    SELECT id, data, 0 as depth FROM plugin_crm_customer
    WHERE id = $1 AND tenant_id = $2 AND deleted_at IS NULL
    UNION ALL
    SELECT c.id, c.data, d.depth + 1 FROM plugin_crm_customer c
    JOIN descendants d ON c.data->>'parent_id' = d.id::text
    WHERE c.tenant_id = $2 AND c.deleted_at IS NULL AND d.depth < 10
)
SELECT * FROM descendants ORDER BY depth;
```

**当前系统无法执行这种查询。** 需要 Host API 层面支持。

### 1.3 具体建议

1. **为外键字段显式声明索引**：在 `PluginField` 中新增 `indexed: bool` 属性，或者引入 `references` 属性自动创建索引。CRM 中 `contact.customer_id`、`communication.customer_id`、`customer_tag.customer_id`、`customer_relationship.from_customer_id`、`customer_relationship.to_customer_id` 这些外键字段必须有索引。

2. **对 unique 约束的处理需要修正**：当前 `customer.code` 声明为 unique，但索引只过滤了 `deleted_at IS NULL`。如果软删除后重建同名 code，唯一索引会冲突。需要在索引中加入排除已删除记录的逻辑，或使用 partial unique index：

   ```sql
   CREATE UNIQUE INDEX idx_xxx_code_uniq ON plugin_crm_customer (data->>'code') WHERE deleted_at IS NULL;
   ```

   当前代码已经使用了 `WHERE deleted_at IS NULL`，这一点做得正确。但要确认 `sanitize_identifier` 生成的索引名不会因为表名过长而截断。

---

## 2. Host API 限制：跨实体查询

### 2.1 问题诊断

这是 CRM 插件面临的最严重的架构缺陷。CRM 的核心场景全部涉及跨实体：

- **客户列表 + 联系人数量**：需要 JOIN 或子查询
- **客户详情页展示联系人列表**：需要按 `customer_id` 过滤 contact
- **沟通记录按客户筛选**：需要按 `customer_id` 过滤 communication
- **标签筛选客户**：需要按 `tag_name` 在 customer_tag 中查，再反查 customer

当前 `db_query` 的实现（`host.rs` 第 99-109 行）只是从预填充的 HashMap 中取缓存：

```rust
fn db_query(&mut self, entity: String, _filter: Vec<u8>, _pagination: Vec<u8>) -> Result<Vec<u8>, String> {
    self.query_results.get(&entity).cloned()
        .ok_or_else(|| format!("实体 '{}' 的查询结果未预填充", entity))
}
```

`_filter` 和 `_pagination` 参数被完全忽略了。

### 2.2 解决方案：引入结构化查询 API

不是加 JOIN（那会让 Host API 变成 SQL 构建器），而是引入**两级查询增强**：

**第一级（必须实现）：单实体过滤查询**

在 Host API 中新增 `db-query-filtered`，或在现有 `db_query` 中实际处理 filter 参数：

```wit
/// 结构化过滤查询
db-query: func(entity: string, filter: list<u8>, pagination: list<u8>) -> result<list<u8>, string>;
```

filter 的 JSON 结构：

```json
{
  "conditions": [
    {"field": "customer_id", "op": "eq", "value": "uuid-here"},
    {"field": "status", "op": "in", "value": ["active", "vip"]},
    {"field": "occurred_at", "op": "gte", "value": "2026-01-01"}
  ],
  "order_by": [{"field": "created_at", "dir": "desc"}],
  "search": "关键词"
}
```

Host 层将其安全转换为参数化 SQL：

```sql
SELECT id, data, created_at, updated_at, version
FROM plugin_crm_contact
WHERE tenant_id = $1 AND deleted_at IS NULL
  AND data->>'customer_id' = $2
ORDER BY created_at DESC
LIMIT $3 OFFSET $4
```

这样 CRM 插件就能实现"查某个客户的所有联系人"、"查某个客户的所有沟通记录"。

**第二级（必须实现）：聚合查询**

设计规格中规划了 `db-aggregate` 但未实现。CRM 需要它来显示统计信息：

```wit
db-aggregate: func(entity: string, query: list<u8>) -> result<list<u8>, string>;
```

query 结构：

```json
{
  "group_by": ["data->>'status'"],
  "aggregates": [
    {"alias": "count", "func": "count", "field": "id"},
    {"alias": "total_value", "func": "sum", "field": "data->>'amount'"}
  ],
  "filter": {"field": "data->>'level'", "op": "eq", "value": "vip"}
}
```

**第三级（推荐实现）：跨实体关联查询**

不要实现通用 JOIN（太复杂且安全风险高），而是实现一种受限的"关联加载"模式：

```wit
/// 按外键值批量查询（一次加载多个关联记录）
db-query-batch: func(entity: string, field: string, ids: list<string>) -> result<list<u8>, string>;
```

这解决了 CRM 中最常见的 N+1 查询问题。例如加载 20 个客户后，一次性查出所有关联的联系人：

```json
// 请求：查 contact 表中 customer_id 在 [id1, id2, ...] 中的记录
{
  "entity": "contact",
  "field": "customer_id",
  "ids": ["uuid-1", "uuid-2", "..."]
}
```

Host 生成：

```sql
SELECT id, data, created_at, updated_at, version
FROM plugin_crm_contact
WHERE tenant_id = $1 AND deleted_at IS NULL
  AND data->>'customer_id' = ANY($2::text[])
```

### 2.3 关于"多次 API 调用"的问题

在 WASM 插件模型下，**每次 API 调用都是在同一个 Store 内完成的**，不涉及网络开销。多次 `db_query` 调用的成本是：

- WASM 到 Host 的函数调用（纳秒级）
- Host 从预填充缓存中读取（纳秒级）

所以即使需要多次调用，性能也不是问题。**真正的问题是当前预填充机制不支持按业务字段过滤**。只要实现了第一级的结构化过滤，CRM 插件的跨实体查询就可以通过以下模式实现：

```
// 插件内伪代码
let contacts = db_query("contact", {"field": "customer_id", "op": "eq", "value": customer_id}, pagination);
let communications = db_query("communication", {"field": "customer_id", "op": "eq", "value": customer_id}, pagination);
```

前端也可以直接通过 REST API 调用：

```
GET /api/v1/plugins/crm/contact?filter={"field":"customer_id","op":"eq","value":"uuid"}&page=1&page_size=20
```

---

## 3. 关系图谱的可行性

### 3.1 结论：可行但有数据量上限

CRM 关系图谱的核心查询是：给定一个客户，找出它的所有直接关系（parent_child/partner/supplier 等）。

**查询模式**：

```sql
-- 查询 A 的所有关系
SELECT * FROM plugin_crm_customer_relationship
WHERE tenant_id = $1 AND deleted_at IS NULL
  AND (data->>'from_customer_id' = $2 OR data->>'to_customer_id' = $2);
```

这个查询在索引支持下完全可行。需要为 `from_customer_id` 和 `to_customer_id` 都创建索引。

**前端加载策略**：

"加载全量关系+客户来渲染图谱"这个方案在以下条件下可行：
- 单租户客户量 < 5000
- 关系记录 < 10000

超出这个量级，需要改为"按中心节点展开"的模式：
1. 先加载中心客户的直接关系（1 跳）
2. 用户点击某个关联客户时，加载该客户的直接关系（2 跳）
3. 前端用力导向图逐步渲染

### 3.2 建议

1. **不要设计成全量加载**。manifest 页面类型 `graph` 应支持配置 `depth` 参数（默认 1 跳，最大 3 跳），以及 `center_entity_id` 参数。

2. **后端提供"关系网络"专用查询**。不是新增 Host API，而是在 data_handler 层增加一个通用的关系查询端点：

   ```
   GET /api/v1/plugins/{plugin_id}/{entity}/graph?center_id=uuid&depth=2&relationship_types=parent_child,partner
   ```

   这可以由基座的前端通用组件调用，不需要插件 WASM 参与。

3. **前端 graph 组件选型**：推荐 Ant Design 的 `@ant-design/graph` 或 G6。图谱渲染是纯前端能力，不需要 WASM 介入。

---

## 4. parent_id 层级（递归查询）

### 4.1 问题分析

"查询某客户的所有子孙节点"在当前架构下确实是个难题。三种场景需要递归：

1. **组织架构式展示**：树形组件显示客户层级
2. **汇总统计**：某集团下所有子公司的总交易额
3. **权限继承**：父客户的负责人可以看到子客户

### 4.2 解决方案

**方案 A：Host 端提供递归查询 API（推荐）**

新增 Host API：

```wit
/// 递归查询树形结构的所有子孙节点
db-query-tree: func(entity: string, parent-field: string, root-id: string, max-depth: s32) -> result<list<u8>, string>;
```

Host 层使用 `WITH RECURSIVE` 实现：

```sql
WITH RECURSIVE tree AS (
    -- 锚点：根节点
    SELECT id, data, 0 as depth
    FROM plugin_crm_customer
    WHERE id = $1 AND tenant_id = $2 AND deleted_at IS NULL
    UNION ALL
    -- 递归：子节点
    SELECT c.id, c.data, t.depth + 1
    FROM plugin_crm_customer c
    JOIN tree t ON c.data->>'parent_id' = t.id::text
    WHERE c.tenant_id = $2 AND c.deleted_at IS NULL AND t.depth < $3
)
SELECT id, data, depth FROM tree ORDER BY depth;
```

**方案 B：物化路径（denormalization）**

在 customer 的 data 中存储物化路径 `path: "root_id/parent_id/self_id"`，然后可以用前缀匹配：

```sql
SELECT * FROM plugin_crm_customer
WHERE data->>'path' LIKE 'root_id/%' AND tenant_id = $1 AND deleted_at IS NULL;
```

这需要 GIN 索引支持 `LIKE` 前缀查询（`pg_trgm` 扩展或 `text_pattern_ops`）。

**推荐方案 A**。物化路径有数据一致性问题（移动节点时需要更新所有子节点的 path），而递归 CTE 是 PostgreSQL 原生支持的，一次查询搞定。`max_depth` 参数防止无限递归。

### 4.3 对 tree 页面类型的建议

manifest 中 `type: tree` 的页面需要额外的配置：

```toml
[[ui.pages]]
route = "/crm/customer-tree"
entity = "customer"
type = "tree"
tree_config = { parent_field = "parent_id", label_field = "name", icon_field = "customer_type", max_depth = 5 }
```

基座前端根据 `tree_config` 渲染 Ant Design Tree 组件，使用 `db-query-tree` API 加载数据。

---

## 5. 缺失的关键能力

### 5.1 必须新增的 Host API

按优先级排序：

| 优先级 | API | 原因 |
|--------|-----|------|
| P0 | **db-query-filtered**（结构化过滤） | 没有它 CRM 插件完全无法工作。当前 db_query 的 filter 参数被忽略。 |
| P0 | **db-aggregate**（聚合查询） | CRM 仪表盘需要"按状态统计客户数"、"按级别统计客户数"等。设计规格中已规划但未实现。 |
| P0 | **db-query-by-id**（按 ID 查单条） | 当前 `db_query` 不支持按 ID 查询。虽然 REST API 有 GET by ID，但 WASM 内部没有。 |
| P1 | **db-query-batch**（批量外键查询） | 解决 N+1 问题，关联实体加载。 |
| P1 | **db-query-tree**（递归树查询） | 支持客户层级树、组织架构等树形结构。 |
| P1 | **db-batch-insert**（批量插入） | 导入客户数据、批量创建联系人。 |
| P2 | **db-exists**（存在性检查） | 检查 code 是否已存在，比 count 更高效。 |
| P2 | **db-count**（计数） | 单独的计数查询，不返回数据。 |

### 5.2 必须增强的基座能力

| 能力 | 现状 | 需要 |
|------|------|------|
| **REST API 过滤** | `PluginDataListParams` 只有 `page/page_size/search` | 需要支持 `filter` 查询参数，支持 JSONB 字段的等值/范围/IN 查询 |
| **REST API 排序** | 固定 `ORDER BY created_at DESC` | 需要支持 `order_by` 参数 |
| **REST API 关联加载** | 无 | 需要支持 `?include=contact,communication` 参数，一次返回客户+联系人+沟通记录 |
| **Schema 唯一约束校验** | 只创建了索引，没有插入前校验 | 需要在 `PluginDataService::create` 中检查 unique 字段 |
| **实体间引用完整性** | 无 | 删除客户时应提示有关联的联系人/沟通记录。至少提供 `GET /plugins/{id}/{entity}/{record_id}/references` 端点 |

### 5.3 WASM 插件端需要的能力

设计规格中规划了 `render-page` 和 `handle-action`，但 WIT 中未实现。对于 CRM 插件，以下场景需要这两个函数：

- **客户 360 度视图**：在同一个页面展示客户基本信息 + 联系人列表 + 最近沟通记录 + 标签 + 关系图谱。这不是一个简单的 CRUD 页面，需要 WASM 返回复合 UI 指令。
- **自定义操作**："转为正式客户"、"合并客户"、"批量分配"等操作需要 WASM 处理业务逻辑。

建议在 WIT 中新增：

```wit
interface plugin-api {
    init: func() -> result<_, string>;
    on-tenant-created: func(tenant-id: string) -> result<_, string>;
    handle-event: func(event-type: string, payload: list<u8>) -> result<_, string>;
    // 新增
    render-page: func(page-path: string, params: list<u8>) -> result<list<u8>, string>;
    handle-action: func(page-path: string, action: string, data: list<u8>) -> result<list<u8>, string>;
}
```

---

## 6. Manifest ui.pages 设计审查

### 6.1 当前类型覆盖度评估

| 类型 | CRM 场景 | 是否覆盖 | 说明 |
|------|---------|---------|------|
| `crud` | 客户列表、联系人列表、沟通记录列表 | 覆盖 | 基本够用 |
| `tree` | 客户层级树 | 需增强 | 需要增加 `tree_config` 配置 |
| `graph` | 关系图谱 | 需增强 | 需要增加 `graph_config`（relationship_entity, center_id, depth） |
| `timeline` | 沟通记录时间线 | 新增 | Ant Design Timeline 组件天然支持 |
| `tabs` | 客户 360 度视图 | 需增强 | 需要支持嵌套子页面 |
| `dashboard` | CRM 首页统计 | 缺失 | 需要 `stat_cards` + `charts` 配置 |
| `kanban` | 客户跟进阶段看板 | 缺失 | 按客户等级/跟进状态分列 |
| `detail` | 客户详情页 | 缺失 | 不是 CRUD，是复合视图 |

### 6.2 建议的页面类型扩展

```typescript
interface PluginPage {
  route: string;
  entity: string;
  display_name: string;
  icon?: string;
  menu_group?: string;

  // 页面类型扩展
  type: "crud" | "tree" | "graph" | "timeline" | "tabs" | "dashboard" | "detail" | "custom";

  // 类型专属配置
  crud_config?: CrudConfig;     // 列/过滤/排序/表单/操作
  tree_config?: TreeConfig;     // 父节点字段/标签字段/最大深度
  graph_config?: GraphConfig;   // 关系实体/关系类型/默认深度
  dashboard_config?: DashboardConfig; // 统计卡片/图表
  detail_config?: DetailConfig; // 关联实体/布局
  tabs_config?: TabsConfig;     // 子标签页列表
}
```

### 6.3 对 CRM 最关键的缺失：detail 页面类型

CRM 最核心的交互不是列表 CRUD，而是**客户 360 度详情页**：

```
┌────────────────────────────────────────────────┐
│ 客户名称：某某集团              [编辑] [更多 ▾] │
│ 类型：企业 | 行业：制造业 | 级别：VIP           │
├────────────────────────────────────────────────┤
│ [基本信息] [联系人] [沟通记录] [关系图谱] [标签] │
├────────────────────────────────────────────────┤
│ 联系人列表（联系人的 CRUD，自动过滤当前客户）   │
│ + 新增联系人                                   │
│ ┌─────┬──────┬──────┬───────┬────┐            │
│ │姓名 │职位   │电话   │邮箱    │操作│            │
│ └─────┴──────┴──────┴───────┴────┘            │
└────────────────────────────────────────────────┘
```

这种页面需要：
1. 顶部展示主实体详情
2. 底部 tabs 展示关联实体列表
3. 关联实体自动按主实体 ID 过滤

建议 `detail` 类型配置：

```toml
[[ui.pages]]
route = "/crm/customer/:id"
entity = "customer"
type = "detail"
display_name = "客户详情"

[ui.pages.detail_config.header]
title_field = "name"
subtitles = [
  { field = "customer_type", label = "类型" },
  { field = "industry", label = "行业" },
  { field = "level", label = "级别", tag_colors = {vip = "gold", svip = "red"} }
]
actions = ["edit", "delete", { label = "转为正式客户", action = "activate", permission = "crm.customer.update" }]

[[ui.pages.detail_config.tabs]]
label = "联系人"
entity = "contact"
filter_field = "customer_id"
type = "crud"

[[ui.pages.detail_config.tabs]]
label = "沟通记录"
entity = "communication"
filter_field = "customer_id"
type = "timeline"

[[ui.pages.detail_config.tabs]]
label = "关系图谱"
entity = "customer_relationship"
type = "graph"
graph_config = { center_from = "from_customer_id", center_to = "to_customer_id" }
```

---

## 7. 权限模型审查

### 7.1 当前方案的 8 个权限码

根据 CRM 插件常见需求，推测 8 个权限码为：
- `crm.customer.list` / `crm.customer.create` / `crm.customer.update` / `crm.customer.delete`
- `crm.contact.list` / `crm.contact.create` / `crm.contact.update` / `crm.contact.delete`

### 7.2 不足之处

**问题 1：缺少沟通记录和关系图谱的权限**

沟通记录（communication）和关系图谱（customer_relationship）是独立实体，应该有独立的权限码。

**问题 2：缺少数据范围权限（data scope）**

CRM 中最常见的权限需求不是"能不能看联系人"，而是"能看到哪些客户的联系人"。典型的数据范围：

- **本人**：只看自己创建的客户
- **本部门**：看本部门所有人创建的客户
- **本部门及下级**：看本部门及子部门创建的客户
- **全部**：看所有客户

当前的 `check_permission` 只支持布尔型权限检查（有没有这个权限），不支持数据范围过滤。

**问题 3：级联权限问题**

"联系人/沟通记录的访问是否应该依赖客户级别的权限？"——**是的，应该依赖**。如果用户看不到某个客户，就不应该看到该客户下的联系人和沟通记录。

### 7.3 建议的权限模型

**权限码（16 个）**：

```
crm.customer.list          # 查看客户列表
crm.customer.create        # 创建客户
crm.customer.update        # 编辑客户
crm.customer.delete        # 删除客户
crm.customer.export        # 导出客户数据

crm.contact.list           # 查看联系人
crm.contact.create         # 创建联系人
crm.contact.update         # 编辑联系人
crm.contact.delete         # 删除联系人

crm.communication.list     # 查看沟通记录
crm.communication.create   # 创建沟通记录
crm.communication.update   # 编辑沟通记录
crm.communication.delete   # 删除沟通记录

crm.relationship.view      # 查看关系图谱
crm.tag.manage             # 管理标签分类

crm.customer.all           # 数据范围：查看所有客户（默认只看自己的）
```

**数据范围过滤的实现**：

这不是插件自身能解决的，需要基座支持。建议在 `current_user` API 返回的数据中包含数据范围信息，或者在 Host API 层增加数据范围过滤：

```wit
/// 扩展 current_user 返回值
current-user: func() -> result<list<u8>, string>;
// 返回结构增加 data_scope 字段
// { "id": "...", "tenant_id": "...", "data_scope": "all" | "department" | "department_tree" | "self" }
```

然后在 `db_query` 的过滤逻辑中自动注入 `created_by` 过滤。

**关于级联权限**：建议在 REST API 层处理。当查询联系人时，如果用户没有 `crm.customer.all`，则联系人查询自动 JOIN customer 表检查 `created_by`：

```sql
SELECT c.* FROM plugin_crm_contact c
JOIN plugin_crm_customer cu ON c.data->>'customer_id' = cu.id::text
WHERE c.tenant_id = $1 AND c.deleted_at IS NULL
  AND (cu.data->>'created_by' = $2 OR cu.data->>'level' IN ('vip', 'svip'))
  -- VIP 客户所有人可见
```

这种过滤逻辑复杂且与业务强相关，建议在 WASM 插件的 `handle_action` 中实现，或者作为基座的通用数据范围机制。

---

## 8. 综合评估与实施建议

### 8.1 可行性评估

| 维度 | 评分 | 说明 |
|------|------|------|
| JSONB 数据存储 | 8/10 | PostgreSQL JSONB 足够支撑，索引机制需增强 |
| 单实体 CRUD | 6/10 | 基本可用，但查询/排序/过滤能力严重不足 |
| 跨实体关联 | 3/10 | 当前完全不支持，是最需要补强的部分 |
| 树形层级 | 3/10 | 需要递归查询支持 |
| 关系图谱 | 5/10 | 存储可行，查询/渲染需要增强 |
| 权限模型 | 5/10 | 权限码够用，数据范围权限缺失 |
| UI 配置驱动 | 4/10 | 缺少 detail/dashboard/kanban 类型 |

### 8.2 实施路径建议

**Phase 1：基座查询能力增强（前置条件，约 3-5 天）**

1. 实现 `db_query` 的 filter 参数解析和 SQL 构建
2. 实现 `db-aggregate` Host API
3. REST API 支持 filter / order_by 参数
4. 为外键字段自动创建索引
5. 实现 unique 约束的插入前校验

**Phase 2：CRM 核心功能（约 5-7 天）**

1. 创建 CRM 插件 crate（5 个实体）
2. 实现客户 + 联系人 + 沟通记录的 CRUD
3. 实现 `type: detail` 前端通用组件
4. 实现客户详情页（tabs 嵌套关联实体）

**Phase 3：高级功能（约 3-5 天）**

1. 实现 `db-query-tree` 支持客户层级
2. 实现关系图谱页面
3. 实现数据范围权限过滤
4. 实现 `render-page` / `handle-action` 支持自定义操作

### 8.3 风险提示

1. **最大的风险不是技术，是 Host API 的演进方向**。每增加一个 Host API 函数，就意味着所有已安装的插件都依赖这个接口。建议在 CRM 插件开发前先冻结 Host API v2（包含上述增强），然后所有插件基于 v2 开发。

2. **JSONB 动态表的性能天花板**。单表数据量超过 100 万条时，JSONB 的查询性能会显著下降（相比原生列）。如果 CRM 模块被高频使用，长期应考虑将高频实体（customer）升级为原生列存储。

3. **前端通用组件的复杂度**。detail + graph + tree + timeline 这四种页面类型，每种都需要基座提供通用实现。这不是 CRM 独有的需求，而是所有行业插件的共同需求。建议将这些组件沉淀为基座的 `PluginUI` 组件库，而不是 CRM 插件的一部分。

---

## 附录：Host API v2 建议的 WIT 定义

```wit
package erp:plugin;

interface host-api {
    // === 基础 CRUD ===
    db-insert: func(entity: string, data: list<u8>) -> result<list<u8>, string>;
    db-get-by-id: func(entity: string, id: string) -> result<list<u8>, string>;
    db-query: func(entity: string, filter: list<u8>, pagination: list<u8>) -> result<list<u8>, string>;
    db-update: func(entity: string, id: string, data: list<u8>, version: s64) -> result<list<u8>, string>;
    db-delete: func(entity: string, id: string) -> result<_, string>;
    db-exists: func(entity: string, filter: list<u8>) -> result<bool, string>;
    db-count: func(entity: string, filter: list<u8>) -> result<s64, string>;

    // === 批量操作 ===
    db-query-batch: func(entity: string, field: string, ids: list<string>) -> result<list<u8>, string>;
    db-batch-insert: func(entity: string, items: list<list<u8>>) -> result<list<list<u8>>, string>;

    // === 高级查询 ===
    db-aggregate: func(entity: string, query: list<u8>) -> result<list<u8>, string>;
    db-query-tree: func(entity: string, parent-field: string, root-id: string, max-depth: s32) -> result<list<u8>, string>;

    // === 事件总线 ===
    event-publish: func(event-type: string, payload: list<u8>) -> result<_, string>;

    // === 配置 ===
    config-get: func(key: string) -> result<list<u8>, string>;

    // === 日志 ===
    log-write: func(level: string, message: string);

    // === 用户/权限 ===
    current-user: func() -> result<list<u8>, string>;
    check-permission: func(permission: string) -> result<bool, string>;
}

interface plugin-api {
    init: func() -> result<_, string>;
    on-tenant-created: func(tenant-id: string) -> result<_, string>;
    on-tenant-deleted: func(tenant-id: string) -> result<_, string>;
    handle-event: func(event-type: string, payload: list<u8>) -> result<_, string>;
    render-page: func(page-path: string, params: list<u8>) -> result<list<u8>, string>;
    handle-action: func(page-path: string, action: string, data: list<u8>) -> result<list<u8>, string>;
}

world plugin-world {
    import host-api;
    export plugin-api;
}
```

共计 15 个 Host API 函数（vs 当前 9 个），6 个 Plugin API 函数（vs 当前 3 个）。