# CRM 客户管理插件实施计划

> **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:** 实施 ERP 平台第一个行业插件——CRM 客户管理，同时增强基座的插件系统（过滤查询、动态权限、配置驱动 UI）。

**Architecture:** WASM 插件 + JSONB 动态表 + 配置驱动前端。先修基座（Phase 1），再建插件（Phase 2），最后高级功能（Phase 3）。

**Tech Stack:** Rust (Axum + SeaORM + Wasmtime) / TypeScript (React 18 + Ant Design + Zustand) / PostgreSQL (JSONB)

**Design Spec:** `docs/superpowers/specs/2026-04-16-crm-plugin-design.md` v1.1

---

## Chunk 1: Phase 1 — Rust 后端 Bug 修复与查询增强

### Task 1: 修复唯一索引 Bug

**Files:**
- Modify: `crates/erp-plugin/src/dynamic_table.rs:67-87`

- [ ] **Step 1: 写失败测试**

在 `crates/erp-plugin/src/dynamic_table.rs` 底部的 `#[cfg(test)]` 模块中添加：

```rust
#[test]
fn test_unique_index_sql_uses_create_unique_index() {
    // 验证 unique 字段生成的 SQL 包含 UNIQUE 关键字
    let entity = PluginEntity {
        name: "test".to_string(),
        display_name: "Test".to_string(),
        fields: vec![PluginField {
            name: "code".to_string(),
            field_type: PluginFieldType::String,
            required: true,
            unique: true,
            default: None,
            display_name: "Code".to_string(),
            ui_widget: None,
            options: None,
        }],
        indexes: vec![],
    };
    // 验证 create_table 生成的 SQL 中 unique 字段的索引包含 UNIQUE
    let sql = DynamicTableManager::build_unique_index_sql("plugin_test", &entity.fields[0]);
    assert!(sql.contains("CREATE UNIQUE INDEX"), "Expected UNIQUE index, got: {}", sql);
}
```

- [ ] **Step 2: 运行测试确认失败**

Run: `cargo test -p erp-plugin -- test_unique_index_sql_uses_create_unique_index`
Expected: 编译失败或测试失败（因为 `build_unique_index_sql` 方法尚不存在）

- [ ] **Step 3: 实现修复**

在 `crates/erp-plugin/src/dynamic_table.rs` 中：

1. 在 `create_table` 方法（第 67-87 行区域）中，将 `unique` 字段的索引创建从 `CREATE INDEX` 改为 `CREATE UNIQUE INDEX`。修改索引创建循环中判断 `field.unique` 的分支：

```rust
// 在 create_table 方法的索引创建循环中
if field.unique {
    let idx_name = format!("{}_{}_uniq", table_name, field.name);
    let idx_sql = format!(
        "CREATE UNIQUE INDEX IF NOT EXISTS \"{}\" ON \"{}\" (data->>'{}')",
        idx_name, table_name, field.name
    );
    // 执行 idx_sql...
}
```

2. 添加辅助方法 `build_unique_index_sql` 供测试使用：

```rust
pub fn build_unique_index_sql(table_name: &str, field: &PluginField) -> String {
    let idx_name = format!("{}_{}_uniq", table_name, field.name);
    format!(
        "CREATE UNIQUE INDEX IF NOT EXISTS \"{}\" ON \"{}\" (data->>'{}')",
        idx_name, table_name, field.name
    )
}
```

3. **无需在 data_service.rs 手动处理 23505 错误**。`erp-core/src/error.rs` 的 `From<sea_orm::DbErr> for AppError` 已经将 `duplicate key` 错误自动转换为 `AppError::Conflict("记录已存在")`。`data_service.rs` 使用 `?` 传播错误，会自动走这个转换路径。

- [ ] **Step 4: 运行测试确认通过**

Run: `cargo test -p erp-plugin -- test_unique_index_sql_uses_create_unique_index`
Expected: PASS

- [ ] **Step 5: 提交**

```bash
git add crates/erp-plugin/src/dynamic_table.rs crates/erp-plugin/src/data_service.rs
git commit -m "fix(plugin): 修复唯一索引使用 CREATE UNIQUE INDEX 并捕获 23505 错误"
```

---

### Task 2: 修复插件权限注册（跨 crate 方案）

**Files:**
- Modify: `crates/erp-core/src/module.rs` — ErpModule trait 新增 `register_permissions` 方法
- Modify: `crates/erp-plugin/src/module.rs` — PluginModule 实现权限注册
- Modify: `crates/erp-server/src/main.rs` — 模块注册时调用权限注册

**架构约束**：`erp-plugin` 不能直接依赖 `erp-auth`（业务 crate 间禁止直接依赖）。解决方案：通过 `ErpModule` trait 新增方法，在 `erp-server`（唯一组装点）中桥接。

- [ ] **Step 1: 在 ErpModule trait 中新增权限注册方法**

在 `crates/erp-core/src/module.rs` 的 `ErpModule` trait 中添加：

```rust
/// 返回此模块需要注册的权限列表，在 install/启用时由 ModuleRegistry 调用
fn permissions(&self) -> Vec<PermissionDescriptor> {
    vec![]
}

/// 返回此模块需要清理的权限前缀，在 uninstall 时调用
fn permission_prefix(&self) -> Option<String> {
    None
}
```

在 `erp-core` 中定义 `PermissionDescriptor`：

```rust
#[derive(Clone, Debug)]
pub struct PermissionDescriptor {
    pub code: String,
    pub name: String,
    pub description: String,
    pub module: String,
}
```

- [ ] **Step 2: 在 PluginModule 中实现 permissions()**

在 `crates/erp-plugin/src/module.rs` 中，`PluginModule` 实现从已加载插件的 manifest 中提取权限：

```rust
fn permissions(&self) -> Vec<PermissionDescriptor> {
    // 从 engine 中获取所有已安装插件的 manifest
    // 遍历 manifest.permissions，生成 PermissionDescriptor 列表
    // module 字段设为 format!("plugin:{}", plugin_id)
}
```

- [ ] **Step 3: 在 ModuleRegistry 中添加权限注册流程**

在 `crates/erp-core/src/module.rs` 的 `ModuleRegistry` 中添加：

```rust
pub async fn register_permissions(&self, tenant_id: Uuid, operator_id: Uuid, db: &DatabaseConnection) -> AppResult<()> {
    for module in &self.modules {
        let perms = module.permissions();
        for perm in perms {
            // 使用 raw SQL 插入到 permissions 表
            // INSERT INTO permissions (id, tenant_id, code, name, description, module, ...)
            // VALUES ($1, $2, $3, $4, $5, $6, ...)
            // ON CONFLICT DO NOTHING
        }
    }
    Ok(())
}
```

使用 raw SQL 而非 entity 操作，避免 `erp-core` 依赖 `erp-auth`。

- [ ] **Step 4: 在 install 流程中调用权限注册**

在 `crates/erp-plugin/src/service.rs` 的 `install` 方法中，调用 `registry.register_permissions()` 注册新插件的权限。在 `uninstall` 中使用 raw SQL 清理。

- [ ] **Step 5: 运行编译检查**

Run: `cargo check --workspace`
Expected: 编译通过

- [ ] **Step 6: 提交**

```bash
git add crates/erp-core/src/module.rs crates/erp-plugin/src/module.rs crates/erp-plugin/src/service.rs
git commit -m "fix(plugin): 通过 ErpModule trait 桥接实现插件权限注册，解决跨 crate 依赖问题"
```

---

### Task 3: 扩展 Manifest Schema

**Files:**
- Modify: `crates/erp-plugin/src/manifest.rs:49-61` (PluginField)
- Modify: `crates/erp-plugin/src/manifest.rs:94-109` (PluginUi + PluginPage)
- Modify: `crates/erp-plugin/src/service.rs` (manifest 引用点)
- Modify: `crates/erp-plugin/src/host.rs` (manifest 引用点)

**迁移策略**：直接替换 `PluginPage` 结构体为 tagged enum `PluginPageType`，同步更新所有引用点。不保留旧结构体——现有 `parse_full_manifest` 测试使用旧的 `route/entity/display_name/icon/menu_group` 格式，需同步更新测试的 TOML 内容。这个 crate 还没有外部消费者，直接迁移最干净。

- [ ] **Step 1: 写失败测试**

在 `crates/erp-plugin/src/manifest.rs` 测试模块中添加：

```rust
#[test]
fn test_parse_manifest_with_new_fields() {
    let toml = r#"
[metadata]
id = "test-plugin"
name = "Test"
version = "0.1.0"
description = "Test"
author = "Test"
min_platform_version = "0.1.0"

[[schema.entities]]
name = "customer"
display_name = "客户"

[[schema.entities.fields]]
name = "code"
field_type = "string"
required = true
display_name = "编码"
unique = true
searchable = true
filterable = true
visible_when = "customer_type == 'enterprise'"

[[ui.pages]]
type = "tabs"
label = "客户管理"
icon = "team"

[[ui.pages.tabs]]
label = "客户列表"
type = "crud"
entity = "customer"
enable_search = true
enable_views = ["table", "timeline"]

[[ui.pages]]
type = "detail"
entity = "customer"
label = "客户详情"

[[ui.pages.sections]]
type = "fields"
label = "基本信息"
fields = ["code", "name"]
"#;
    let manifest = parse_manifest(toml).expect("should parse");
    let field = &manifest.schema.as_ref().unwrap().entities[0].fields[0];
    assert_eq!(field.searchable, Some(true));
    assert_eq!(field.filterable, Some(true));
    assert_eq!(field.visible_when.as_deref(), Some("customer_type == 'enterprise'"));
    // 验证页面类型解析
    let ui = manifest.ui.as_ref().unwrap();
    assert_eq!(ui.pages.len(), 2);
    // tabs 页面
    match &ui.pages[0] {
        PluginPageType::Tabs { label, tabs, .. } => {
            assert_eq!(label, "客户管理");
            assert_eq!(tabs.len(), 1);
        }
        _ => panic!("Expected Tabs page type"),
    }
    // detail 页面
    match &ui.pages[1] {
        PluginPageType::Detail { entity, sections, .. } => {
            assert_eq!(entity, "customer");
            assert_eq!(sections.len(), 1);
        }
        _ => panic!("Expected Detail page type"),
    }
}
```

- [ ] **Step 2: 运行测试确认失败**

Expected: FAIL（新字段 `searchable`/`filterable`/`visible_when` 尚不存在，`PluginPageType` 尚未定义）

- [ ] **Step 3: 扩展 PluginField 结构体**

在 `manifest.rs` 的 `PluginField`（第 49-61 行）中新增字段。注意 `display_name` 现有类型是 `Option<String>`，保持不变：

```rust
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PluginField {
    pub name: String,
    pub field_type: PluginFieldType,
    #[serde(default)]
    pub required: bool,
    #[serde(default)]
    pub unique: bool,
    pub default: Option<serde_json::Value>,
    pub display_name: Option<String>,  // 注意：现有是 Option<String>
    pub ui_widget: Option<String>,
    pub options: Option<Vec<serde_json::Value>>,
    // 新增字段 — 全部 Optional + serde(default) 保证向后兼容
    #[serde(default)]
    pub searchable: Option<bool>,
    #[serde(default)]
    pub filterable: Option<bool>,
    #[serde(default)]
    pub sortable: Option<bool>,
    #[serde(default)]
    pub visible_when: Option<String>,
}
```

- [ ] **Step 4: 替换 PluginPage 为 tagged enum PluginPageType**

直接删除 `PluginPage`（第 100-109 行），替换为：

```rust
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
#[serde(tag = "type")]
pub enum PluginPageType {
    #[serde(rename = "crud")]
    Crud {
        entity: String,
        label: String,
        icon: Option<String>,
        enable_search: Option<bool>,
        enable_views: Option<Vec<String>>,
    },
    #[serde(rename = "tree")]
    Tree {
        entity: String,
        label: String,
        icon: Option<String>,
        id_field: String,
        parent_field: String,
        label_field: String,
    },
    #[serde(rename = "detail")]
    Detail {
        entity: String,
        label: String,
        sections: Vec<PluginSection>,
    },
    #[serde(rename = "tabs")]
    Tabs {
        label: String,
        icon: Option<String>,
        tabs: Vec<PluginPageType>,
    },
}

#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
#[serde(tag = "type")]
pub enum PluginSection {
    #[serde(rename = "fields")]
    Fields {
        label: String,
        fields: Vec<String>,
    },
    #[serde(rename = "crud")]
    Crud {
        label: String,
        entity: String,
        filter_field: Option<String>,
        enable_views: Option<Vec<String>>,
    },
}
```

更新 `PluginUi`：

```rust
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PluginUi {
    pub pages: Vec<PluginPageType>,
}
```

**删除旧的 `PluginPage` 结构体**（第 100-109 行）。

- [ ] **Step 5: 更新所有引用点**

搜索 `PluginPage` 的所有使用位置并更新：

1. **`service.rs`** — `install()` 中如果遍历了 `ui.pages`，更新字段访问方式（改为 match 分支）
2. **`host.rs`** — 如果引用了 `PluginPage`，更新为新 enum
3. **`data_handler.rs`** — 同上

使用 `grep -rn "PluginPage" crates/erp-plugin/src/` 查找所有引用。

- [ ] **Step 6: 更新现有测试**

更新 `parse_full_manifest` 测试中的 TOML，将旧格式：

```toml
[[ui.pages]]
route = "/products"
entity = "product"
display_name = "商品管理"
icon = "ShoppingOutlined"
menu_group = "进销存"
```

改为新格式：

```toml
[[ui.pages]]
type = "crud"
entity = "product"
label = "商品管理"
icon = "ShoppingOutlined"
```

同时更新断言（`display_name` → `label`，去掉 `route`/`menu_group`）。

- [ ] **Step 7: 添加页面类型验证**

在 `parse_manifest` 中添加：

```rust
if let Some(ui) = &manifest.ui {
    for page in &ui.pages {
        match page {
            PluginPageType::Crud { entity, .. } => {
                if entity.is_empty() {
                    return Err(PluginError::InvalidManifest("crud page 的 entity 不能为空".into()));
                }
            }
            PluginPageType::Tree { id_field, parent_field, label_field, .. } => {
                if id_field.is_empty() || parent_field.is_empty() || label_field.is_empty() {
                    return Err(PluginError::InvalidManifest("tree page 的 id/parent/label_field 不能为空".into()));
                }
            }
            PluginPageType::Detail { entity, sections } => {
                if entity.is_empty() || sections.is_empty() {
                    return Err(PluginError::InvalidManifest("detail page 的 entity 和 sections 不能为空".into()));
                }
            }
            PluginPageType::Tabs { tabs, .. } => {
                if tabs.is_empty() {
                    return Err(PluginError::InvalidManifest("tabs page 的 tabs 不能为空".into()));
                }
            }
        }
    }
}
```

- [ ] **Step 8: 运行全部测试**

Run: `cargo test -p erp-plugin`
Expected: ALL PASS

Run: `cargo check --workspace`
Expected: 编译通过

- [ ] **Step 9: 提交**

```bash
git add crates/erp-plugin/src/
git commit -m "feat(plugin): 扩展 manifest schema 支持 searchable/filterable/visible_when 和 tagged enum 页面类型"
```

---

### Task 4: 实现过滤查询 SQL 构建器

**Files:**
- Modify: `crates/erp-plugin/src/dynamic_table.rs` (新增方法)
- Modify: `crates/erp-plugin/src/data_dto.rs:28-33` (PluginDataListParams)

- [ ] **Step 1: 写失败测试**

```rust
#[test]
fn test_build_filtered_query_sql_with_filter() {
    let sql_result = DynamicTableManager::build_filtered_query_sql(
        "plugin_test_customer",
        Uuid::parse_str("00000000-0000-0000-0000-000000000001").unwrap(),
        20,
        0,
        Some(serde_json::json!({"customer_id": "abc-123"})),
        None,
        None,
        None,
    );
    let (sql, params) = sql_result;
    assert!(sql.contains("data->>'customer_id' ="), "Expected filter in SQL, got: {}", sql);
    assert!(sql.contains("tenant_id"), "Expected tenant_id filter");
}

#[test]
fn test_build_filtered_query_sql_sanitizes_keys() {
    // 恶意 key 应被拒绝
    let result = DynamicTableManager::build_filtered_query_sql(
        "plugin_test",
        Uuid::parse_str("00000000-0000-0000-0000-000000000001").unwrap(),
        20, 0,
        Some(serde_json::json!({"evil'; DROP TABLE--": "value"})),
        None, None, None,
    );
    assert!(result.is_err() || !result.as_ref().unwrap().0.contains("DROP TABLE"));
}

#[test]
fn test_build_filtered_query_sql_with_search() {
    let (sql, _) = DynamicTableManager::build_filtered_query_sql(
        "plugin_test",
        Uuid::parse_str("00000000-0000-0000-0000-000000000001").unwrap(),
        20, 0, None,
        Some(("name,code".to_string(), "测试关键词".to_string())),
        None, None,
    );
    assert!(sql.contains("ILIKE"), "Expected ILIKE in SQL, got: {}", sql);
}
```

- [ ] **Step 2: 运行测试确认失败**

Run: `cargo test -p erp-plugin -- test_build_filtered_query_sql`
Expected: FAIL（方法不存在）

- [ ] **Step 3: 扩展 PluginDataListParams**

在 `data_dto.rs` 中：

```rust
#[derive(Debug, Deserialize, IntoParams)]
pub struct PluginDataListParams {
    pub page: Option<u64>,
    pub page_size: Option<u64>,
    pub search: Option<String>,
    // 新增
    pub filter: Option<String>,  // JSON 格式: {"field":"value"}
    pub sort_by: Option<String>,
    pub sort_order: Option<String>,  // "asc" or "desc"
}
```

- [ ] **Step 4: 实现 build_filtered_query_sql**

在 `dynamic_table.rs` 中新增方法：

```rust
pub fn build_filtered_query_sql(
    table_name: &str,
    tenant_id: Uuid,
    limit: u64,
    offset: u64,
    filter: Option<serde_json::Value>,
    search: Option<(String, String)>,  // (searchable_fields_csv, keyword)
    sort_by: Option<String>,
    sort_order: Option<String>,
) -> Result<(String, Vec<Value>), String> {
    let mut conditions = vec![
        format!("\"tenant_id\" = ${}", 1),
        format!("\"deleted_at\" IS NULL"),
    ];
    let mut param_idx = 2;
    let mut values: Vec<Value> = vec![tenant_id.into()];

    // 处理 filter
    if let Some(f) = filter {
        if let Some(obj) = f.as_object() {
            for (key, val) in obj {
                let clean_key = sanitize_identifier(key);
                if clean_key.is_empty() {
                    return Err(format!("无效的过滤字段名: {}", key));
                }
                conditions.push(format!("\"data\"->>'{}' = ${}", clean_key, param_idx));
                values.push(Value::String(Some(Box::new(val.as_str().unwrap_or("").to_string()))));
                param_idx += 1;
            }
        }
    }

    // 处理 search — 所有字段共享同一个 ILIKE 参数（同一个关键词）
    if let Some((fields_csv, keyword)) = search {
        let escaped = keyword.replace('%', "\\%").replace('_', "\\_");
        let fields: Vec<&str> = fields_csv.split(',').collect();
        let search_param_idx = param_idx;
        let search_conditions: Vec<String> = fields.iter().map(|f| {
            let clean = sanitize_identifier(f.trim());
            format!("\"data\"->>'{}' ILIKE ${}", clean, search_param_idx)
        }).collect();
        conditions.push(format!("({})", search_conditions.join(" OR ")));
        values.push(Value::String(Some(Box::new(format!("%{}%", escaped)))));
        param_idx += 1;
    }

    // 处理 sort
    let order_clause = if let Some(sb) = sort_by {
        let clean = sanitize_identifier(&sb);
        let dir = match sort_order.as_deref() {
            Some("asc") | Some("ASC") => "ASC",
            _ => "DESC",
        };
        format!("ORDER BY \"data\"->>'{}' {}", clean, dir)
    } else {
        "ORDER BY \"created_at\" DESC".to_string()
    };

    let sql = format!(
        "SELECT * FROM \"{}\" WHERE {} {} LIMIT ${} OFFSET ${}",
        table_name,
        conditions.join(" AND "),
        order_clause,
        param_idx,
        param_idx + 1,
    );
    values.push(limit.into());
    values.push(offset.into());

    Ok((sql, values))
}
```

注意：`Value` 类型即 `sea_orm::Value`（文件头部已有 `use sea_orm::Value`）。`Value::String(Some(Box::new(...)))` 是 SeaORM 的 `String` variant 包装方式。

- [ ] **Step 5: 运行测试确认通过**

Run: `cargo test -p erp-plugin -- test_build_filtered_query_sql`
Expected: PASS

Run: `cargo check -p erp-plugin`
Expected: 编译通过

- [ ] **Step 6: 提交**

```bash
git add crates/erp-plugin/src/dynamic_table.rs crates/erp-plugin/src/data_dto.rs
git commit -m "feat(plugin): 实现过滤查询 SQL 构建器，支持 filter/search/sort"
```

---

### Task 5: 集成过滤查询到 data_service 和 handler

**Files:**
- Modify: `crates/erp-plugin/src/data_service.rs:57-116` (list 方法)
- Modify: `crates/erp-plugin/src/handler/data_handler.rs:25-57` (list handler)

- [ ] **Step 1: 修改 data_service.rs 的 list 方法签名**

将 `list` 方法签名从：

```rust
pub async fn list(plugin_id: Uuid, entity_name: &str, tenant_id: Uuid, page: u64, page_size: u64, db: &DatabaseConnection) -> AppResult<(Vec<PluginDataResp>, u64)>
```

改为：

```rust
pub async fn list(
    plugin_id: Uuid,
    entity_name: &str,
    tenant_id: Uuid,
    page: u64,
    page_size: u64,
    db: &DatabaseConnection,
    filter: Option<serde_json::Value>,
    search: Option<String>,
    search_fields: Option<String>,
    sort_by: Option<String>,
    sort_order: Option<String>,
) -> AppResult<(Vec<PluginDataResp>, u64)>
```

在方法内部，将 `DynamicTableManager::build_query_sql` 替换为 `build_filtered_query_sql`。`search_fields` 参数来源：从 `plugin_entities` 表的 `schema_json` 字段反序列化出 entity 的 fields，筛选 `searchable == Some(true)` 的字段名，用逗号拼接成 CSV。如无可搜索字段则传 `None`。

```rust
// 在 list 方法内部获取 searchable fields
let entity_fields = resolve_entity_fields(plugin_id, entity_name, tenant_id, db).await?;
let search_fields_csv: Option<String> = {
    let searchable: Vec<&str> = entity_fields.iter()
        .filter(|f| f.searchable == Some(true))
        .map(|f| f.name.as_str())
        .collect();
    if searchable.is_empty() { None } else { Some(searchable.join(",")) }
};
let search_tuple = match (&search_fields_csv, &search) {
    (Some(fields), Some(kw)) => Some((fields.clone(), kw.clone())),
    _ => None,
};
let (sql, values) = DynamicTableManager::build_filtered_query_sql(
    &table_name, tenant_id, page_size, offset, filter, search_tuple, sort_by, sort_order,
)?;
```

- [ ] **Step 2: 修改 data_handler.rs 的 list handler**

在 `list_plugin_data` 函数中，提取 `Query(params)` 并传递给 service。注意 handler **不需要**传 `search_fields`——service 层自己从 manifest 查找 searchable 字段：

```rust
let filter: Option<serde_json::Value> = params.filter.as_ref()
    .and_then(|f| serde_json::from_str(f).ok());
let result = PluginDataService::list(
    plugin_id, &entity, ctx.tenant_id, page, page_size,
    &state.db, filter, params.search, params.sort_by, params.sort_order,
).await?;
```

- [ ] **Step 3: 修改 data_handler.rs 的动态权限检查**

将所有 handler 的 `require_permission` 从硬编码改为动态计算：

```rust
// 辅助函数：计算插件数据操作所需的权限码
// 格式：{plugin_id}.{entity}.{action}，如 crm.customer.list
fn compute_permission_code(plugin_id: &str, entity_name: &str, action: &str) -> String {
    let action_suffix = match action {
        "list" | "get" => "list",
        _ => "manage",
    };
    format!("{}.{}.{}", plugin_id, entity_name, action_suffix)
}
```

替换每个 handler 中的权限检查：

```rust
// 原来: require_permission(&ctx, "plugin.list")?;
// 改为:
let perm = compute_permission_code(&plugin_id, &entity_name, "list");
require_permission(&ctx, &perm)?;
```

- [ ] **Step 4: 运行编译检查**

Run: `cargo check -p erp-plugin`
Expected: 编译通过

Run: `cargo test -p erp-plugin`
Expected: ALL PASS

- [ ] **Step 5: 提交**

```bash
git add crates/erp-plugin/src/data_service.rs crates/erp-plugin/src/handler/data_handler.rs
git commit -m "feat(plugin): 集成过滤查询到 REST API，改造动态权限检查"
```

---

### Task 6: 添加 searchable 字段 GIN 索引

**Files:**
- Modify: `crates/erp-plugin/src/dynamic_table.rs` (create_table 方法)

- [ ] **Step 1: 在 create_table 中为 searchable 字段创建 GIN 索引**

在 `create_table` 方法的索引创建循环后，添加 searchable 字段的 GIN 索引：

```rust
// 为 searchable 字段创建 GIN 索引以加速 ILIKE 查询
for field in &entity.fields {
    if field.searchable == Some(true) {
        let idx_name = format!("{}_{}_gin", sanitized_table, field.name);
        let gin_sql = format!(
            "CREATE INDEX IF NOT EXISTS \"{}\" ON \"{}\" USING GIN (\"data\" gin_path_ops)",
            idx_name, sanitized_table
        );
        // 执行 gin_sql...
    }
}
```

注意：`gin_path_ops` 适用于 `@>` 操作符。对于 `ILIKE` 查询，可能需要 `btree(data->>'field')` 索引或 pg_trgm 扩展的 GIN 索引。根据实际查询模式选择合适的索引类型。

- [ ] **Step 2: 运行编译检查**

Run: `cargo check -p erp-plugin`
Expected: 编译通过

- [ ] **Step 3: 提交**

```bash
git add crates/erp-plugin/src/dynamic_table.rs
git commit -m "feat(plugin): 为 searchable 字段自动创建 GIN 索引"
```

---

### Task 7: 添加数据校验层

**Files:**
- Modify: `crates/erp-plugin/src/data_service.rs` (create/update 方法)

- [ ] **Step 1: 实现 resolve_entity_fields 辅助函数**

在 `data_service.rs` 中添加——从 `plugin_entities` 表的 `schema_json` 字段获取 entity 的字段定义：

```rust
use crate::manifest::PluginField;

/// 从 plugin_entities 表获取 entity 的字段定义
async fn resolve_entity_fields(
    plugin_id: Uuid,
    entity_name: &str,
    tenant_id: Uuid,
    db: &sea_orm::DatabaseConnection,
) -> AppResult<Vec<PluginField>> {
    let entity_model = plugin_entity::Entity::find()
        .filter(plugin_entity::Column::PluginId.eq(plugin_id))
        .filter(plugin_entity::Column::TenantId.eq(tenant_id))
        .filter(plugin_entity::Column::EntityName.eq(entity_name))
        .filter(plugin_entity::Column::DeletedAt.is_null())
        .one(db)
        .await?
        .ok_or_else(|| AppError::NotFound(format!("插件实体 {}/{} 不存在", plugin_id, entity_name)))?;

    let entity_def: crate::manifest::PluginEntity =
        serde_json::from_value(entity_model.schema_json)
            .map_err(|e| AppError::Internal(format!("解析 entity schema 失败: {}", e)))?;

    Ok(entity_def.fields)
}
```

注意：`resolve_entity_fields` 同时被 Task 5 的 `list` 方法和本 Task 的 `validate_data` 使用。

- [ ] **Step 2: 实现 validate_data 辅助函数**

```rust
fn validate_data(data: &serde_json::Value, fields: &[PluginField]) -> AppResult<()> {
    let obj = data.as_object()
        .ok_or_else(|| AppError::Validation("data 必须是 JSON 对象".to_string()))?;
    for field in fields {
        if field.required && !obj.contains_key(&field.name) {
            let label = field.display_name.as_deref().unwrap_or(&field.name);
            return Err(AppError::Validation(format!("字段 '{}' 不能为空", label)));
        }
    }
    Ok(())
}
```

注意：`field.display_name` 类型是 `Option<String>`，使用 `as_deref().unwrap_or()` 提供回退值。

- [ ] **Step 3: 在 create/update 中调用验证**

在 `create` 方法中（在 `build_insert_sql` 之前）：

```rust
let fields = resolve_entity_fields(plugin_id, entity_name, tenant_id, db).await?;
validate_data(&data, &fields)?;
```

在 `update` 方法中同理。

- [ ] **Step 4: 运行编译检查**

Run: `cargo check -p erp-plugin`
Expected: 编译通过

- [ ] **Step 5: 提交**

```bash
git add crates/erp-plugin/src/data_service.rs
git commit -m "feat(plugin): 添加数据校验层，检查 required 字段"
```

---

## Chunk 2: Phase 1 — 前端 CRUD 增强、detail 页面、visible_when

### Task 8: 扩展前端 pluginData API

**Files:**
- Modify: `apps/web/src/api/pluginData.ts:19-30`
- Modify: `apps/web/src/api/plugins.ts:116-121`

- [ ] **Step 1: 扩展 listPluginData 函数签名**

将 `pluginData.ts` 的 `listPluginData` 改为：

```typescript
export interface PluginDataListOptions {
  filter?: Record<string, string>;
  search?: string;
  sort_by?: string;
  sort_order?: 'asc' | 'desc';
}

export async function listPluginData(
  pluginId: string,
  entity: string,
  page = 1,
  pageSize = 20,
  options?: PluginDataListOptions
) {
  const params: Record<string, string> = {
    page: String(page),
    page_size: String(pageSize),
  };
  if (options?.filter) params.filter = JSON.stringify(options.filter);
  if (options?.search) params.search = options.search;
  if (options?.sort_by) params.sort_by = options.sort_by;
  if (options?.sort_order) params.sort_order = options.sort_order;
  const { data } = await client.get<{
    success: boolean;
    data: PaginatedDataResponse<PluginDataRecord>;
  }>(`/plugins/${pluginId}/${entity}`, { params });
  return data.data;
}
```

- [ ] **Step 2: 扩展 getPluginSchema 返回类型**

在 `plugins.ts` 中定义精确的 schema 类型：

```typescript
export interface PluginFieldSchema {
  name: string;
  field_type: string;
  required: boolean;
  display_name: string;
  ui_widget?: string;
  options?: { label: string; value: string }[];
  searchable?: boolean;
  filterable?: boolean;
  sortable?: boolean;
  visible_when?: string;
  unique?: boolean;
}

export interface PluginEntitySchema {
  name: string;
  display_name: string;
  fields: PluginFieldSchema[];
}

export interface PluginSchemaResponse {
  entities: PluginEntitySchema[];
}
```

更新 `getPluginSchema` 返回类型。

- [ ] **Step 3: 提交**

```bash
git add apps/web/src/api/pluginData.ts apps/web/src/api/plugins.ts
git commit -m "feat(web): 扩展插件 API 支持 filter/search/sort 参数和精确 schema 类型"
```

---

### Task 9: 增强 PluginCRUDPage — 筛选/搜索/排序

**Files:**
- Modify: `apps/web/src/pages/PluginCRUDPage.tsx`

- [ ] **Step 1: 在表格上方添加搜索框和筛选栏**

在 `PluginCRUDPage` 组件中：

1. 添加 state：`searchText`, `filters`, `sortBy`, `sortOrder`
2. 从 schema fields 中提取 `filterable` 字段列表，渲染 `Select` 组件
3. 当 `enable_search` 为 true 时渲染 `Input.Search`
4. 修改 `fetchData` 传递 filter/search/sort 参数

```typescript
// 搜索和筛选栏（在 Table 上方）
<Space style={{ marginBottom: 16 }} wrap>
  {enableSearch && (
    <Input.Search
      placeholder="搜索..."
      allowClear
      style={{ width: 240 }}
      onSearch={(value) => { setSearchText(value); fetchData(1, pageSize, value, filters); }}
    />
  )}
  {filterableFields.map(field => (
    <Select
      key={field.name}
      placeholder={field.display_name}
      allowClear
      style={{ width: 150 }}
      options={field.options}
      onChange={(value) => {
        const newFilters = { ...filters };
        if (value) newFilters[field.name] = value;
        else delete newFilters[field.name];
        setFilters(newFilters);
        fetchData(1, pageSize, searchText, newFilters);
      }}
    />
  ))}
</Space>
```

- [ ] **Step 2: 添加视图切换（timeline）**

当 `enable_views` 包含多个视图时，在右上角添加 `Segmented` 组件切换视图模式。Phase 1 先只实现 table 视图，timeline 留到 Phase 2。

- [ ] **Step 3: 提交**

```bash
git add apps/web/src/pages/PluginCRUDPage.tsx
git commit -m "feat(web): PluginCRUDPage 增加搜索框、筛选栏和排序支持"
```

---

### Task 10: 实现 PluginDetailPage — Drawer + Tabs + 嵌套 CRUD

**Files:**
- Create: `apps/web/src/pages/PluginDetailPage.tsx`

- [ ] **Step 1: 创建 PluginDetailPage 组件**

```typescript
import { Drawer, Tabs, Descriptions, Table, Spin } from 'antd';
import { useState, useEffect } from 'react';
import { getPluginSchema, PluginEntitySchema } from '../api/plugins';
import { listPluginData, PluginDataRecord } from '../api/pluginData';

interface PluginDetailPageProps {
  open: boolean;
  onClose: () => void;
  pluginId: string;
  entityId: string;
  recordId: string;
  recordData: Record<string, unknown>;
  schema: PluginEntitySchema | null;
}

export function PluginDetailPage({ open, onClose, pluginId, entityId, recordId, recordData, schema }: PluginDetailPageProps) {
  // 1. 获取完整的 plugin schema（包含所有 entity）
  // 2. 找到 detail 页面配置的 sections
  // 3. 渲染 Drawer + Tabs，每个 section 渲染不同内容
  // ...
}
```

核心逻辑：
- `fields` section → `Descriptions` 组件展示字段值
- `crud` section → 嵌套的 `Table` 组件，通过 `filter_field` 自动过滤

- [ ] **Step 2: 在 PluginCRUDPage 中集成详情按钮**

当 manifest 中声明了同实体的 `detail` 页面时，在操作列自动添加"详情"按钮：

```typescript
// 在 PluginCRUDPage 的操作列中
{hasDetailPage && (
  <Button type="link" size="small" onClick={() => setDetailRecord(record)}>
    详情
  </Button>
)}
```

- [ ] **Step 3: 提交**

```bash
git add apps/web/src/pages/PluginDetailPage.tsx apps/web/src/pages/PluginCRUDPage.tsx
git commit -m "feat(web): 新增 PluginDetailPage Drawer 详情页，支持嵌套 CRUD"
```

---

### Task 11: 实现 visible_when 条件表单字段

**Files:**
- Modify: `apps/web/src/pages/PluginCRUDPage.tsx:166-192` (renderFormField)

- [ ] **Step 1: 实现 visible_when 解析函数**

```typescript
function parseVisibleWhen(expression: string): { field: string; value: string } | null {
  const regex = /^(\w+)\s*==\s*'([^']*)'$/;
  const match = expression.trim().match(regex);
  if (!match) return null;
  return { field: match[1], value: match[2] };
}
```

- [ ] **Step 2: 在表单渲染中集成条件显示**

在 `renderFormField` 中，如果字段有 `visible_when`，用 `Form.useWatch` 监听条件字段：

```typescript
// 在表单渲染的 map 中
{fields.map(field => {
  const visible = field.visible_when
    ? shouldShowField(form.getFieldsValue(), field.visible_when)
    : true;
  if (!visible) return null;
  return <Form.Item key={field.name} ...>{renderFormField(field)}</Form.Item>;
})}
```

需要在组件中添加 `form.getFieldsValue()` 的响应式监听。可以使用 `Form.useWatch` 或在 `onValuesChanged` 回调中触发重渲染。

- [ ] **Step 3: 提交**

```bash
git add apps/web/src/pages/PluginCRUDPage.tsx
git commit -m "feat(web): 表单字段支持 visible_when 条件显示"
```

---

### Task 12: Phase 1 端到端验证

- [ ] **Step 1: 启动 Docker 环境**

Run: `cd docker && docker compose up -d`

- [ ] **Step 2: 编译并启动后端**

Run: `cargo run -p erp-server`

- [ ] **Step 3: 启动前端**

Run: `cd apps/web && pnpm dev`

- [ ] **Step 4: 运行全量测试**

Run: `cargo test --workspace`

- [ ] **Step 5: 手动验证验收标准**

- [ ] 使用已有的测试插件验证：唯一字段重复插入返回冲突错误
- [ ] REST API 支持 `?filter={"field":"value"}&search=keyword`
- [ ] PluginCRUDPage 自动渲染筛选栏和搜索框
- [ ] visible_when 条件字段正常工作

---

## Chunk 3: Phase 2 — CRM WASM 插件核心

### Task 13: 创建 CRM 插件 crate 骨架

**Files:**
- Create: `crates/erp-plugin-crm/Cargo.toml`
- Create: `crates/erp-plugin-crm/src/lib.rs`
- Create: `crates/erp-plugin-crm/plugin.toml`
- Modify: `Cargo.toml` (workspace members)

- [ ] **Step 1: 创建 Cargo.toml**

```toml
[package]
name = "erp-plugin-crm"
version = "0.1.0"
edition = "2024"

[lib]
crate-type = ["cdylib"]

[dependencies]
wit-bindgen = "0.55"
serde = { version = "1", features = ["derive"] }
serde_json = "1"
```

- [ ] **Step 2: 创建 src/lib.rs**

参考 `erp-plugin-test-sample` 的结构，实现 Guest trait 的三个方法：

```rust
wit_bindgen::generate!({
    path: "../erp-plugin-prototype/wit/plugin.wit",
    world: "plugin-world",
});

use crate::exports::erp::plugin::plugin_api::Guest;

struct CrmPlugin;

impl Guest for CrmPlugin {
    fn init() -> Result<(), String> {
        Ok(())
    }

    fn on_tenant_created(tenant_id: String) -> Result<(), String> {
        let _ = tenant_id;
        Ok(())
    }

    fn handle_event(event_type: String, payload: Vec<u8>) -> Result<(), String> {
        let _ = (event_type, payload);
        Ok(())
    }
}

export!(CrmPlugin);
```

注意：`wit_bindgen::generate!` 的 path 指向 `erp-plugin-prototype`（非 `erp-plugin`），因为 WIT 文件在 prototype crate 中。`export!` 宏由 `generate!` 自动生成。完整参考 `crates/erp-plugin-test-sample/src/lib.rs`。

- [ ] **Step 3: 创建 plugin.toml**

使用设计规格 §4.1 中完整的 manifest 配置。

- [ ] **Step 4: 注册到 workspace**

在根 `Cargo.toml` 的 `[workspace] members` 中添加 `"crates/erp-plugin-crm"`。

- [ ] **Step 5: 编译 WASM**

Run: `cargo build -p erp-plugin-crm --target wasm32-unknown-unknown --release`
Expected: 编译成功，生成 `.wasm` 文件

- [ ] **Step 6: 转换为 Component**

Run: `wasm-tools component new target/wasm32-unknown-unknown/release/erp_plugin_crm.wasm -o target/erp_plugin_crm.component.wasm`

- [ ] **Step 7: 提交**

```bash
git add crates/erp-plugin-crm/ Cargo.toml
git commit -m "feat(crm): 创建 CRM 插件 crate 骨架和 manifest"
```

---

### Task 14: 通过 PluginAdmin 上传并测试 CRM 插件

- [ ] **Step 1: 上传插件**

通过 PluginAdmin 页面上传 `erp_plugin_crm.component.wasm` 和 `plugin.toml`。

- [ ] **Step 2: 安装插件**

验证：5 个动态表创建成功、9 个权限注册成功。

- [ ] **Step 3: 启用插件**

验证：WASM 初始化成功，侧边栏出现 CRM 菜单项。

- [ ] **Step 4: 基础 CRUD 测试**

- 创建客户（企业/个人）
- 创建联系人（关联客户）
- 创建沟通记录（关联客户）
- 列表查询（验证 filter 按客户过滤）
- 编辑/删除

---

## Chunk 4: Phase 2 — 前端 tree/timeline/tabs 页面类型

### Task 15: 实现 PluginTabsPage

**Files:**
- Create: `apps/web/src/pages/PluginTabsPage.tsx`

- [ ] **Step 1: 创建 tabs 容器组件**

使用 Ant Design `Tabs` 组件，每个 tab 根据子页面类型渲染对应组件：

```typescript
export function PluginTabsPage({ pluginId, tabs, schema }: TabsPageProps) {
  const [activeKey, setActiveKey] = useState(tabs[0]?.label);
  
  return (
    <Tabs activeKey={activeKey} onChange={setActiveKey} items={tabs.map(tab => ({
      key: tab.label,
      label: tab.label,
      children: renderPageContent(pluginId, tab, schema),
    }))} />
  );
}
```

- [ ] **Step 2: 提交**

```bash
git add apps/web/src/pages/PluginTabsPage.tsx
git commit -m "feat(web): 新增 PluginTabsPage 通用标签页容器"
```

---

### Task 16: 实现 PluginTreePage

**Files:**
- Create: `apps/web/src/pages/PluginTreePage.tsx`

- [ ] **Step 1: 创建树形页面组件**

使用 Ant Design `DirectoryTree`，从 REST API 加载全量数据，前端构建树结构：

```typescript
export function PluginTreePage({ pluginId, config, schema }: TreePageProps) {
  // config: { entity, id_field, parent_field, label_field }
  // 1. 加载全量数据
  // 2. 构建树结构（根据 parent_field 建立父子关系）
  // 3. 渲染 DirectoryTree
  // 4. 点击节点显示右侧详情面板
}
```

- [ ] **Step 2: 提交**

```bash
git add apps/web/src/pages/PluginTreePage.tsx
git commit -m "feat(web): 新增 PluginTreePage 通用树形页面"
```

---

### Task 17: 实现 timeline 视图模式

**Files:**
- Modify: `apps/web/src/pages/PluginCRUDPage.tsx`

- [ ] **Step 1: 添加 timeline 视图渲染**

在 PluginCRUDPage 中，当 `enable_views` 包含 `"timeline"` 时，添加 timeline 渲染逻辑：

```typescript
const renderTimeline = () => (
  <Timeline items={data.map(item => ({
    children: (
      <div>
        <p><strong>{item[titleField]}</strong></p>
        <p>{item[contentField]}</p>
        <p style={{ color: '#999' }}>{item[dateField]}</p>
      </div>
    ),
    color: getTypeColor(item[typeField]),
  }))} />
);
```

- [ ] **Step 2: 集成 Segmented 切换**

```typescript
{enableViews.length > 1 && (
  <Segmented
    options={enableViews.map(v => ({ label: v === 'table' ? '表格' : '时间线', value: v }))}
    value={viewMode}
    onChange={setViewMode}
  />
)}
{viewMode === 'table' ? <Table ... /> : renderTimeline()}
```

- [ ] **Step 3: 提交**

```bash
git add apps/web/src/pages/PluginCRUDPage.tsx
git commit -m "feat(web): PluginCRUDPage 添加 timeline 视图模式切换"
```

---

### Task 18: 侧边栏动态菜单集成

**Files:**
- Modify: `apps/web/src/stores/plugin.ts:38-58` (refreshMenuItems)
- Modify: `apps/web/src/layouts/MainLayout.tsx:172-192` (插件菜单渲染)
- Modify: `apps/web/src/pages/PluginCRUDPage.tsx` 或 `App.tsx` (路由)

- [ ] **Step 1: 修改 plugin store 的菜单生成逻辑**

从 manifest 的 `ui.pages` 生成菜单项（而非仅遍历 entities）：

```typescript
// refreshMenuItems 中
for (const plugin of plugins) {
  if (plugin.status !== 'running') continue;
  const schema = await getPluginSchema(plugin.id); // 或从缓存读取
  for (const page of schema.ui?.pages || []) {
    if (page.type === 'tabs') {
      // tabs 类型聚合为一个菜单项
      items.push({
        key: `/plugins/${plugin.id}/${page.label}`,
        label: page.label,
        icon: page.icon,
        pluginId: plugin.id,
        pageType: 'tabs',
      });
    } else if (page.type !== 'detail') {
      // crud/tree 各生成一个菜单项
      items.push({
        key: `/plugins/${plugin.id}/${page.entity}`,
        label: page.label,
        icon: page.icon,
        pluginId: plugin.id,
        entity: page.entity,
        pageType: page.type,
      });
    }
  }
}
```

- [ ] **Step 2: 修改 MainLayout 支持动态图标**

将 182 行的固定 `<AppstoreOutlined />` 改为根据 `item.icon` 选择图标。

- [ ] **Step 3: 修改路由分发**

在 `App.tsx` 或路由配置中，根据 `pageType` 匹配不同的页面组件：
- `crud` → `PluginCRUDPage`
- `tabs` → `PluginTabsPage`
- `tree` → `PluginTreePage`

- [ ] **Step 4: 提交**

```bash
git add apps/web/src/stores/plugin.ts apps/web/src/layouts/MainLayout.tsx apps/web/src/App.tsx
git commit -m "feat(web): 侧边栏动态菜单集成，支持 manifest pages 配置"
```

---

### Task 19: Phase 2 端到端验证

- [ ] **Step 1: 启动全栈环境**

Run: `.\dev.ps1`

- [ ] **Step 2: 验收 CRM 插件**

- 上传 → 安装 → 启用，侧边栏出现 CRM 菜单（"客户管理"、"联系人"、"沟通记录"、"标签管理"、"客户关系"）
- 客户 CRUD：创建企业客户、个人客户，验证差异化字段
- 客户详情 Drawer：点击详情按钮，看到关联联系人和沟通记录
- 客户层级树：展开/折叠正常
- 沟通记录 timeline 视图切换
- 权限控制：不同角色看到不同数据

---

## Chunk 5: Phase 3 — 高级功能 + Skill 提炼

### Task 20: 实现 graph 页面类型（AntV G6）

**Files:**
- Create: `apps/web/src/pages/PluginGraphPage.tsx`

- [ ] **Step 1: 安装 @antv/g6**

Run: `cd apps/web && pnpm add @antv/g6`

- [ ] **Step 2: 实现 graph 页面组件**

- Dynamic import 按需加载 G6
- 以选中客户为中心，展示 1 跳关系
- 点击节点继续扩展
- 节点标签用客户名称，边标签用关系类型

- [ ] **Step 3: 提交**

```bash
git add apps/web/src/pages/PluginGraphPage.tsx apps/web/package.json apps/web/pnpm-lock.yaml
git commit -m "feat(web): 新增 PluginGraphPage 关系图谱页面（AntV G6）"
```

---

### Task 21: 实现 dashboard 页面类型

**Files:**
- Create: `apps/web/src/pages/PluginDashboardPage.tsx`

- [ ] **Step 1: 实现 dashboard 组件**

使用 Ant Design `Statistic` / `Card` + `@ant-design/charts` 渲染统计概览。

- [ ] **Step 2: 提交**

```bash
git add apps/web/src/pages/PluginDashboardPage.tsx
git commit -m "feat(web): 新增 PluginDashboardPage 统计概览页面"
```

---

### Task 22: Host API 扩展 — db-count / db-aggregate

**Files:**
- Modify: `crates/erp-plugin/wit/plugin.wit` (新增接口)
- Modify: `crates/erp-plugin/src/host.rs` (实现)
- Modify: `crates/erp-plugin/src/dynamic_table.rs` (SQL 构建)

- [ ] **Step 1: 在 WIT 中新增 db-count 和 db-aggregate 接口**

- [ ] **Step 2: 实现 Host 端方法**

- [ ] **Step 3: 更新 CRM 插件 bindgen**

- [ ] **Step 4: 提交**

```bash
git add crates/erp-plugin/wit/ crates/erp-plugin/src/ crates/erp-plugin-crm/
git commit -m "feat(plugin): Host API 新增 db-count 和 db-aggregate"
```

---

### Task 23: 提炼插件开发 Skill

**Files:**
- Create: `.claude/skills/plugin-development/SKILL.md`

- [ ] **Step 1: 编写 skill 文档**

基于 CRM 开发经验，提炼以下内容：
1. 插件开发流程指南（需求 → manifest → Rust → 编译 → 上传 → 测试）
2. 各页面类型的 manifest 配置模板
3. Rust 插件脚手架（init/on_tenant_created/handle_event 模板）
4. 可用页面类型清单（crud/detail/tree/timeline/tabs/graph/dashboard）
5. 可用字段属性清单（searchable/filterable/sortable/visible_when/unique）
6. 权限声明指南
7. 测试检查清单
8. 常见问题与陷阱

- [ ] **Step 2: 提交**

```bash
git add .claude/skills/plugin-development/
git commit -m "docs: 提炼 CRM 插件开发经验为可复用 skill"
```

---

### Task 24: Phase 3 端到端验证 + 最终提交

- [ ] **Step 1: 全量测试**

Run: `cargo test --workspace`

- [ ] **Step 2: 手动验证关系图谱**

- 打开客户关系页面
- 以某客户为中心展示关系
- 点击节点扩展
- 筛选关系类型

- [ ] **Step 3: 手动验证统计概览**

- 客户数量统计
- 分类分布
- 等级分布

- [ ] **Step 4: 最终提交**

```bash
git add -A
git commit -m "feat(crm): CRM 客户管理插件 Phase 3 完成 — 关系图谱 + 统计概览 + Host API 扩展"
```

---

## 文件结构总览

### Phase 1 新增/修改文件

```
crates/erp-plugin/src/
  dynamic_table.rs      — Bug 修复 + filtered query + GIN 索引
  service.rs            — 权限注册/清理
  manifest.rs           — PluginField/PluginPage/PluginSection 扩展
  data_service.rs       — filter/search/sort 集成 + 数据校验
  data_handler.rs       — 动态权限检查 + 过滤参数
  data_dto.rs           — PluginDataListParams 扩展
  host.rs               — （Phase 1 不改，仅标记待实现）
  dto.rs                — （如需）

apps/web/src/
  api/pluginData.ts     — listPluginData 参数扩展
  api/plugins.ts        — schema 类型定义
  pages/PluginCRUDPage.tsx  — 搜索/筛选/排序/visible_when
  pages/PluginDetailPage.tsx — 新增 Drawer 详情页
```

### Phase 2 新增/修改文件

```
crates/erp-plugin-crm/  — 新增 crate
  Cargo.toml
  src/lib.rs
  plugin.toml

apps/web/src/
  pages/PluginTabsPage.tsx    — 新增
  pages/PluginTreePage.tsx    — 新增
  stores/plugin.ts            — 菜单生成逻辑改造
  layouts/MainLayout.tsx      — 动态图标/分组
  App.tsx                     — 路由分发改造
```

### Phase 3 新增/修改文件

```
crates/erp-plugin/
  wit/plugin.wit              — 新增 db-count/db-aggregate
  src/host.rs                 — 实现
  src/dynamic_table.rs        — 聚合 SQL

apps/web/src/
  pages/PluginGraphPage.tsx   — 新增
  pages/PluginDashboardPage.tsx — 新增

.claude/skills/plugin-development/
  SKILL.md                    — 插件开发 skill
```