# 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:** 升级 CRM 插件基座 — JSONB 存储优化、数据完整性框架、行级数据权限、前端页面能力增强

**Architecture:** 基座优先策略，所有改进沉淀为插件平台通用能力。后端 Rust (Axum + SeaORM + PostgreSQL)，前端 React + Ant Design。依赖顺序：Generated Column → ref_entity → data_scope → 前端增强。

**Tech Stack:** Rust/Axum, PostgreSQL 16 (Generated Column + pg_trgm), Redis 7 (缓存), React 19 + Ant Design 6 + @ant-design/charts, @dnd-kit

**设计规格:** `docs/superpowers/specs/2026-04-17-crm-plugin-base-upgrade-design.md`

---

## 依赖关系图

```
Chunk 1 (JSONB 存储) ──┬──→ Chunk 2 (数据完整性)
                       ├──→ Chunk 3 (行级权限)
                       └──→ Chunk 4 (前端增强)
    │                       │                       │
    │  pg_trgm 迁移         │  manifest 扩展         │  TenantContext 扩展
    │  Generated Column     │  ref_entity/relations  │  data_scope
    │  Keyset Pagination    │  validation/no_cycle   │  permission fallback
    │  Schema 缓存          │  cascade delete        │
    │  聚合 Redis 缓存      │                        │
```

Chunk 1 是其他所有 Chunk 的基础。Chunk 2 和 Chunk 3 互相独立可并行。Chunk 4 依赖 Chunk 1-3 的后端 API。

---

## Chunk 1: JSONB 存储优化

### Task 1.1: 数据库迁移 — pg_trgm 扩展 + plugin_entity_columns 元数据表

**Files:**
- Create: `crates/erp-server/migration/src/m20260418_000035_pg_trgm_and_entity_columns.rs`
- Modify: `crates/erp-server/migration/src/lib.rs`

- [ ] **Step 1: 创建迁移文件**

```rust
// crates/erp-server/migration/src/m20260418_000035_pg_trgm_and_entity_columns.rs
use sea_orm_migration::prelude::*;

#[derive(DeriveMigrationName)]
pub struct Migration;

#[async_trait::async_trait]
impl MigrationTrait for Migration {
    async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
        // 启用 pg_trgm 扩展（加速 ILIKE '%keyword%' 搜索）
        manager
            .get_connection()
            .execute_unprepared("CREATE EXTENSION IF NOT EXISTS pg_trgm")
            .await?;

        // 插件实体列元数据表 — 记录哪些字段被提取为 Generated Column
        manager
            .create_table(
                Table::create()
                    .table(Alias::new("plugin_entity_columns"))
                    .if_not_exists()
                    .col(
                        ColumnDef::new(Alias::new("id"))
                            .uuid()
                            .not_null()
                            .default(Expr::cust("gen_random_uuid()"))
                            .primary_key(),
                    )
                    .col(ColumnDef::new(Alias::new("tenant_id")).uuid().not_null())
                    .col(ColumnDef::new(Alias::new("plugin_entity_id")).uuid().not_null())
                    .col(ColumnDef::new(Alias::new("field_name")).string().not_null())
                    .col(ColumnDef::new(Alias::new("column_name")).string().not_null())
                    .col(ColumnDef::new(Alias::new("sql_type")).string().not_null())
                    .col(
                        ColumnDef::new(Alias::new("is_generated"))
                            .boolean()
                            .not_null()
                            .default(true),
                    )
                    .col(
                        ColumnDef::new(Alias::new("created_at"))
                            .timestamp_with_time_zone()
                            .not_null()
                            .default(Expr::cust("NOW()")),
                    )
                    .to_owned(),
            )
            .await?;

        // plugin_entity_id 外键
        manager
            .create_foreign_key(
                ForeignKey::create()
                    .name("fk_plugin_entity_columns_entity")
                    .from(
                        Alias::new("plugin_entity_columns"),
                        Alias::new("plugin_entity_id"),
                    )
                    .to(Alias::new("plugin_entities"), Alias::new("id"))
                    .to_owned(),
            )
            .await?;

        Ok(())
    }

    async fn down(&self, manager: &SchemaManager) -> Result<(), DbErr> {
        manager
            .drop_table(
                Table::drop()
                    .table(Alias::new("plugin_entity_columns"))
                    .to_owned(),
            )
            .await?;
        // pg_trgm 不卸载（其他功能可能依赖）
        Ok(())
    }
}
```

- [ ] **Step 2: 注册迁移**

在 `crates/erp-server/migration/src/lib.rs` 中添加：

```rust
mod m20260418_000035_pg_trgm_and_entity_columns;
```

在 `migrations()` vec 末尾添加：

```rust
Box::new(m20260418_000035_pg_trgm_and_entity_columns::Migration),
```

- [ ] **Step 3: 验证迁移**

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

Run: `cargo test -p erp-server -- --test-threads=1`（或启动服务让迁移自动执行）
Expected: 迁移成功

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

```bash
git add crates/erp-server/migration/src/m20260418_000035_pg_trgm_and_entity_columns.rs crates/erp-server/migration/src/lib.rs
git commit -m "feat(db): 添加 pg_trgm 扩展 + plugin_entity_columns 元数据表"
```

---

### Task 1.2: manifest.rs — Generated Column 类型映射

**Files:**
- Modify: `crates/erp-plugin/src/manifest.rs:49-84` (PluginField, PluginFieldType)

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

在 `crates/erp-plugin/src/manifest.rs` 的 `#[cfg(test)] mod tests` 中添加：

```rust
#[test]
fn field_type_to_sql_mapping() {
    use crate::manifest::PluginFieldType;
    assert_eq!(PluginFieldType::String.generated_sql_type(), "TEXT");
    assert_eq!(PluginFieldType::Integer.generated_sql_type(), "INTEGER");
    assert_eq!(PluginFieldType::Float.generated_sql_type(), "DOUBLE PRECISION");
    assert_eq!(PluginFieldType::Decimal.generated_sql_type(), "NUMERIC");
    assert_eq!(PluginFieldType::Boolean.generated_sql_type(), "BOOLEAN");
    assert_eq!(PluginFieldType::Date.generated_sql_type(), "DATE");
    assert_eq!(PluginFieldType::DateTime.generated_sql_type(), "TIMESTAMPTZ");
    assert_eq!(PluginFieldType::Uuid.generated_sql_type(), "UUID");
    assert_eq!(PluginFieldType::Json.generated_sql_type(), "TEXT"); // JSON 不适合 Generated Column
}

#[test]
fn field_type_generated_expression() {
    use crate::manifest::PluginFieldType;
    assert_eq!(PluginFieldType::String.generated_expr("name"), "data->>'name'");
    assert_eq!(PluginFieldType::Integer.generated_expr("age"), "(data->>'age')::INTEGER");
    assert_eq!(PluginFieldType::Uuid.generated_expr("ref_id"), "(data->>'ref_id')::UUID");
}
```

- [ ] **Step 2: 验证测试失败**

Run: `cargo test -p erp-plugin -- generated_sql_type`
Expected: 编译失败（方法不存在）

- [ ] **Step 3: 实现 PluginFieldType 扩展**

在 `PluginFieldType` enum 定义之后添加 impl 块：

```rust
impl PluginFieldType {
    /// Generated Column 的 SQL 类型
    pub fn generated_sql_type(&self) -> &'static str {
        match self {
            Self::String | Self::Json => "TEXT",
            Self::Integer => "INTEGER",
            Self::Float => "DOUBLE PRECISION",
            Self::Decimal => "NUMERIC",
            Self::Boolean => "BOOLEAN",
            Self::Date => "DATE",
            Self::DateTime => "TIMESTAMPTZ",
            Self::Uuid => "UUID",
        }
    }

    /// Generated Column 的表达式 — TEXT 类型直接取值，其他类型做类型转换
    pub fn generated_expr(&self, field_name: &str) -> String {
        match self {
            Self::String | Self::Json => format!("data->>'{}'", field_name),
            _ => format!("(data->>'{}')::{}", field_name, self.generated_sql_type()),
        }
    }

    /// 该类型是否适合生成 Generated Column（JSON 类型不适合）
    pub fn supports_generated_column(&self) -> bool {
        !matches!(self, Self::Json)
    }
}
```

- [ ] **Step 4: 运行测试验证通过**

Run: `cargo test -p erp-plugin -- generated`
Expected: 全部 PASS

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

```bash
git add crates/erp-plugin/src/manifest.rs
git commit -m "feat(plugin): PluginFieldType 添加 Generated Column 类型映射"
```

---

### Task 1.3: dynamic_table.rs — Generated Column DDL + 索引策略重写

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

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

在 `dynamic_table.rs` 的 `#[cfg(test)] mod tests` 中添加：

```rust
#[test]
fn test_build_create_table_sql_with_generated_columns() {
    use crate::manifest::{PluginEntity, PluginField, PluginFieldType};

    let entity = PluginEntity {
        name: "customer".to_string(),
        display_name: "客户".to_string(),
        fields: vec![
            PluginField {
                name: "code".to_string(),
                field_type: PluginFieldType::String,
                required: true, unique: true,
                display_name: Some("编码".to_string()),
                searchable: Some(true),
                ..Default::default_for_field()
            },
            PluginField {
                name: "level".to_string(),
                field_type: PluginFieldType::String,
                filterable: true,
                display_name: Some("等级".to_string()),
                ..Default::default_for_field()
            },
            PluginField {
                name: "sort_order".to_string(),
                field_type: PluginFieldType::Integer,
                sortable: true,
                display_name: Some("排序".to_string()),
                ..Default::default_for_field()
            },
        ],
        indexes: vec![],
    };

    let sql = DynamicTableManager::build_create_table_sql("erp_crm", &entity);

    // 验证 Generated Column 存在
    assert!(sql.contains("_f_code"), "应包含 _f_code Generated Column");
    assert!(sql.contains("_f_level"), "应包含 _f_level Generated Column");
    assert!(sql.contains("_f_sort_order"), "应包含 _f_sort_order Generated Column");
    assert!(sql.contains("GENERATED ALWAYS AS"), "应包含 GENERATED ALWAYS AS");
    // Integer 类型需要类型转换
    assert!(sql.contains("::INTEGER"), "Integer 字段应有类型转换");
}

#[test]
fn test_build_create_table_sql_pg_trgm_search_index() {
    use crate::manifest::{PluginEntity, PluginField, PluginFieldType};

    let entity = PluginEntity {
        name: "customer".to_string(),
        display_name: "客户".to_string(),
        fields: vec![
            PluginField {
                name: "name".to_string(),
                field_type: PluginFieldType::String,
                searchable: Some(true),
                display_name: Some("名称".to_string()),
                ..Default::default_for_field()
            },
        ],
        indexes: vec![],
    };

    let sql = DynamicTableManager::build_create_table_sql("erp_crm", &entity);
    assert!(sql.contains("gin_trgm_ops"), "searchable 字段应使用 pg_trgm GIN 索引");
}
```

> **注意：** `PluginField` 当前没有 `Default` 实现。为每个新增字段维护 `default_for_field()` 容易遗漏。
> **推荐做法：** 直接为 `PluginField` 派生 `#[derive(Default)]`，并让 `PluginFieldType` 的 Default 为 `String`：
>
> ```rust
> #[derive(Debug, Clone, Serialize, Deserialize, Default)]
> #[serde(rename_all = "snake_case")]
> pub enum PluginFieldType {
>     #[default]
>     String,
>     Integer, Float, Decimal, Boolean, Date, DateTime, Json, Uuid,
> }
> ```
>
> 这样 `PluginField::default()` 自动包含所有字段的默认值，新增字段无需手动同步。如果派生 Default 不可行（因为 serde 需求），则使用以下手动辅助函数：
>
> ⚠️ **重要：** 每个扩展 `PluginField` 的 Task 都必须同步更新 `default_for_field()`，否则后续 Task 的测试会编译失败。

在 `PluginField` struct 的 `impl PluginField` 块中添加：

```rust
impl PluginField {
    /// 用于测试的默认值构造器
    /// ⚠️ 每次新增 PluginField 字段后必须同步更新此方法
    #[cfg(test)]
    pub fn default_for_field() -> Self {
        Self {
            name: String::new(),
            field_type: PluginFieldType::String,
            required: false,
            unique: false,
            default: None,
            display_name: None,
            ui_widget: None,
            options: None,
            searchable: None,
            filterable: None,
            sortable: None,
            visible_when: None,
            ref_entity: None,        // Task 2.1 新增
            validation: None,        // Task 2.1 新增
            no_cycle: None,          // Task 2.1 新增
            scope_role: None,        // Task 3.4 新增
        }
    }
}
```

- [ ] **Step 2: 验证测试失败**

Run: `cargo test -p erp-plugin -- test_build_create_table`
Expected: 编译失败（`build_create_table_sql` 方法不存在，`default_for_field` 方法不存在）

- [ ] **Step 3: 重写 create_table 为 build_create_table_sql + 新的 create_table**

在 `DynamicTableManager` 中新增纯函数方法（不执行 SQL，只生成 DDL 字符串）：

```rust
/// 生成包含 Generated Column 的建表 DDL
pub fn build_create_table_sql(plugin_id: &str, entity: &PluginEntity) -> String {
    let table_name = Self::table_name(plugin_id, &entity.name);
    let t = sanitize_identifier(&table_name);

    let mut gen_cols = Vec::new();
    let mut indexes = Vec::new();

    for field in &entity.fields {
        if !field.field_type.supports_generated_column() {
            continue;
        }
        // 提取规则：unique / (required && (sortable||filterable)) / sortable / filterable
        let should_extract = field.unique
            || field.sortable == Some(true)
            || field.filterable == Some(true)
            || (field.required && (field.sortable == Some(true) || field.filterable == Some(true)));

        if !should_extract {
            continue;
        }

        let col_name = format!("_f_{}", sanitize_identifier(&field.name));
        let sql_type = field.field_type.generated_sql_type();
        let expr = field.field_type.generated_expr(&sanitize_identifier(&field.name));

        gen_cols.push(format!(
            "    \"{}\" {} GENERATED ALWAYS AS ({}) STORED",
            col_name, sql_type, expr
        ));

        // 索引策略
        let col_idx = format!("{}_{}", sanitize_identifier(&table_name), col_name);
        if field.unique {
            indexes.push(format!(
                "CREATE UNIQUE INDEX IF NOT EXISTS \"idx_{}_uniq\" ON \"{}\" (tenant_id, \"{}\") WHERE deleted_at IS NULL",
                col_idx, table_name, col_name
            ));
        } else {
            indexes.push(format!(
                "CREATE INDEX IF NOT EXISTS \"idx_{}\" ON \"{}\" (tenant_id, \"{}\") WHERE deleted_at IS NULL",
                col_idx, table_name, col_name
            ));
        }
    }

    // pg_trgm 索引（searchable 字段）
    for field in &entity.fields {
        if field.searchable == Some(true) && matches!(field.field_type, PluginFieldType::String) {
            let sf = sanitize_identifier(&field.name);
            indexes.push(format!(
                "CREATE INDEX IF NOT EXISTS \"idx_{}_{}_trgm\" ON \"{}\" USING GIN ((data->>'{}') gin_trgm_ops) WHERE deleted_at IS NULL",
                sanitize_identifier(&table_name), sf, table_name, sf
            ));
        }
    }

    // 覆盖索引（tenant_id + created_at，加速默认排序查询）
    indexes.push(format!(
        "CREATE INDEX IF NOT EXISTS \"idx_{}_tenant_cover\" ON \"{}\" (tenant_id, created_at DESC) INCLUDE (id, data, updated_at, version) WHERE deleted_at IS NULL",
        sanitize_identifier(&table_name), table_name
    ));

    let gen_cols_sql = if gen_cols.is_empty() {
        String::new()
    } else {
        format!(",\n{}", gen_cols.join(",\n"))
    };

    format!(
        "CREATE TABLE IF NOT EXISTS \"{}\" (\
         \"id\" UUID PRIMARY KEY DEFAULT gen_random_uuid(), \
         \"tenant_id\" UUID NOT NULL, \
         \"data\" JSONB NOT NULL DEFAULT '{{}}'{gen_cols}, \
         \"created_at\" TIMESTAMPTZ NOT NULL DEFAULT NOW(), \
         \"updated_at\" TIMESTAMPTZ NOT NULL DEFAULT NOW(), \
         \"created_by\" UUID, \
         \"updated_by\" UUID, \
         \"deleted_at\" TIMESTAMPTZ, \
         \"version\" INT NOT NULL DEFAULT 1);\n\
         {}",
        table_name,
        indexes.join(";\n"),
        gen_cols = gen_cols_sql,
    )
}
```

然后重构现有 `create_table` 方法调用新的 DDL 生成器：

```rust
/// 创建动态表（执行 DDL）
pub async fn create_table(
    db: &DatabaseConnection,
    plugin_id: &str,
    entity: &PluginEntity,
) -> PluginResult<()> {
    let ddl = Self::build_create_table_sql(plugin_id, entity);

    // 分号分割，逐条执行
    for sql in ddl.split(';').map(|s| s.trim()).filter(|s| !s.is_empty()) {
        tracing::info!(sql = %sql, "Executing DDL");
        db.execute_unprepared(sql).await.map_err(|e| {
            tracing::error!(sql = %sql, error = %e, "DDL execution failed");
            PluginError::DatabaseError(e.to_string())
        })?;
    }

    tracing::info!(plugin_id = %plugin_id, entity = %entity.name, "Dynamic table created with Generated Columns");
    Ok(())
}
```

> **重要：** 删除原有的手动索引创建循环（原 `create_table` 中的 for field in &entity.fields 索引创建代码），全部由 `build_create_table_sql` 生成。

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

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

Run: `cargo test -p erp-plugin` (全部测试)
Expected: 原有 15 个测试 + 新增 2 个测试全部 PASS

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

```bash
git add crates/erp-plugin/src/dynamic_table.rs
git commit -m "feat(plugin): create_table 使用 Generated Column + pg_trgm + 覆盖索引"
```

---

### Task 1.4: dynamic_table.rs — SQL 查询路由（Generated Column 优先）

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

当 Generated Column 存在时，查询中 `data->>'field'` 应替换为 `_f_field`，利用 B-tree 索引。

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

```rust
#[test]
fn test_field_reference_uses_generated_column() {
    // 当字段存在 Generated Column 时，SQL 应使用 _f_{name} 而非 data->>'{name}'
    let generated_fields = vec!["code".to_string(), "status".to_string(), "level".to_string()];
    let ref_fn = DynamicTableManager::field_reference_fn(&generated_fields);

    assert_eq!(ref_fn("code"), "_f_code");
    assert_eq!(ref_fn("status"), "_f_status");
    assert_eq!(ref_fn("name"), "data->>'name'"); // 非 Generated Column
    assert_eq!(ref_fn("remark"), "data->>'remark'"); // 非 Generated Column
}

#[test]
fn test_filtered_query_uses_generated_column_for_sort() {
    let generated_fields = vec!["code".to_string(), "level".to_string()];
    let (sql, _) = DynamicTableManager::build_filtered_query_sql_ex(
        "plugin_test",
        Uuid::parse_str("00000000-0000-0000-0000-000000000001").unwrap(),
        20, 0, None, None,
        Some("level".to_string()),
        Some("asc".to_string()),
        &generated_fields,
    ).unwrap();

    assert!(
        sql.contains("ORDER BY \"_f_level\" ASC"),
        "排序应使用 Generated Column，got: {}", sql
    );
}

#[test]
fn test_filtered_query_uses_generated_column_for_filter() {
    let generated_fields = vec!["status".to_string()];
    let (sql, _) = DynamicTableManager::build_filtered_query_sql_ex(
        "plugin_test",
        Uuid::parse_str("00000000-0000-0000-0000-000000000001").unwrap(),
        20, 0,
        Some(serde_json::json!({"status": "active"})),
        None, None, None,
        &generated_fields,
    ).unwrap();

    assert!(
        sql.contains("\"_f_status\" = $"),
        "过滤应使用 Generated Column，got: {}", sql
    );
}
```

- [ ] **Step 2: 验证失败**

Run: `cargo test -p erp-plugin -- field_reference`
Expected: 编译失败

- [ ] **Step 3: 实现字段引用路由**

在 `DynamicTableManager` 中添加：

```rust
/// 返回字段引用函数的闭包 — Generated Column 存在时用 _f_{name}，否则用 data->>'{name}'
pub fn field_reference_fn(generated_fields: &[String]) -> impl Fn(&str) -> String + '_ {
    move |field_name: &str| {
        let clean = sanitize_identifier(field_name);
        if generated_fields.contains(&clean) {
            format!("\"_f_{}\"", clean)
        } else {
            format!("\"data\"->>'{}'", clean)
        }
    }
}

/// 扩展版查询构建 — 支持 Generated Column 路由
pub fn build_filtered_query_sql_ex(
    table_name: &str,
    tenant_id: Uuid,
    limit: u64,
    offset: u64,
    filter: Option<serde_json::Value>,
    search: Option<(String, String)>,
    sort_by: Option<String>,
    sort_order: Option<String>,
    generated_fields: &[String],
) -> Result<(String, Vec<Value>), String> {
    let ref_fn = Self::field_reference_fn(generated_fields);

    let mut conditions = vec![
        format!("\"tenant_id\" = ${}", 1),
        "\"deleted_at\" IS NULL".to_string(),
    ];
    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!("{} = ${}", ref_fn(&clean_key), param_idx));
                values.push(Value::String(Some(Box::new(
                    val.as_str().unwrap_or("").to_string(),
                ))));
                param_idx += 1;
            }
        }
    }

    // search（searchable 字段仍在 JSONB 中，使用 pg_trgm 索引）
    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);
        if clean.is_empty() {
            return Err(format!("无效的排序字段名: {}", sb));
        }
        let dir = match sort_order.as_deref() {
            Some("asc") | Some("ASC") => "ASC",
            _ => "DESC",
        };
        format!("ORDER BY {} {}", ref_fn(&clean), dir)
    } else {
        "ORDER BY \"created_at\" DESC".to_string()
    };

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

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

> 保持原有 `build_filtered_query_sql` 不变（无 generated_fields 参数版本，向后兼容），新方法 `_ex` 后缀。后续 Task 由 data_service 层传入 generated_fields。

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

Run: `cargo test -p erp-plugin`
Expected: 全部 PASS

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

```bash
git add crates/erp-plugin/src/dynamic_table.rs
git commit -m "feat(plugin): SQL 查询路由 — Generated Column 字段优先使用 _f_ 前缀列"
```

---

### Task 1.5: dynamic_table.rs — Keyset Pagination

**Files:**
- Modify: `crates/erp-plugin/src/dynamic_table.rs`
- Modify: `crates/erp-plugin/src/data_dto.rs:28-38` (PluginDataListParams)

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

在 `dynamic_table.rs` tests 中添加：

```rust
#[test]
fn test_keyset_cursor_encode_decode() {
    let cursor = DynamicTableManager::encode_cursor(
        &["测试值".to_string()],
        &Uuid::parse_str("00000000-0000-0000-0000-000000000042").unwrap(),
    );
    let decoded = DynamicTableManager::decode_cursor(&cursor).unwrap();
    assert_eq!(decoded.0, vec!["测试值"]);
    assert_eq!(decoded.1, Uuid::parse_str("00000000-0000-0000-0000-000000000042").unwrap());
}

#[test]
fn test_keyset_sql_first_page() {
    let (sql, _) = DynamicTableManager::build_keyset_query_sql(
        "plugin_test",
        Uuid::parse_str("00000000-0000-0000-0000-000000000001").unwrap(),
        20,
        None, // 第一页无 cursor
        Some("_f_name".to_string()),
        "ASC",
        &[],
    ).unwrap();
    assert!(sql.contains("ORDER BY"), "应有 ORDER BY");
    assert!(!sql.contains(">"), "第一页不应有 cursor 条件");
}

#[test]
fn test_keyset_sql_with_cursor() {
    let cursor = DynamicTableManager::encode_cursor(
        &["Alice".to_string()],
        &Uuid::parse_str("00000000-0000-0000-0000-000000000100").unwrap(),
    );
    let (sql, values) = DynamicTableManager::build_keyset_query_sql(
        "plugin_test",
        Uuid::parse_str("00000000-0000-0000-0000-000000000001").unwrap(),
        20,
        Some(cursor),
        Some("_f_name".to_string()),
        "ASC",
        &[],
    ).unwrap();
    assert!(sql.contains("ROW("), "cursor 条件应使用 ROW 比较");
    assert!(values.len() >= 4, "应有 tenant_id + cursor_val + cursor_id + limit");
}
```

- [ ] **Step 2: 在 data_dto.rs 添加 cursor 字段**

在 `PluginDataListParams` 中添加 `cursor` 字段：

```rust
pub struct PluginDataListParams {
    pub page: Option<u64>,
    pub page_size: Option<u64>,
    pub cursor: Option<String>,  // 新增：Base64 编码的游标（keyset pagination）
    pub search: Option<String>,
    pub filter: Option<String>,
    pub sort_by: Option<String>,
    pub sort_order: Option<String>,
}
```

- [ ] **Step 3: 实现 Keyset Pagination**

在 `DynamicTableManager` 中添加：

```rust
use base64::{Engine, engine::general_purpose::STANDARD as BASE64};

/// 编码游标：JSON { "v": [values], "id": "uuid" } → Base64
pub fn encode_cursor(values: &[String], id: &Uuid) -> String {
    let obj = serde_json::json!({
        "v": values,
        "id": id.to_string(),
    });
    BASE64.encode(obj.to_string())
}

/// 解码游标
pub fn decode_cursor(cursor: &str) -> Result<(Vec<String>, Uuid), String> {
    let json_str = BASE64.decode(cursor)
        .map_err(|e| format!("游标 Base64 解码失败: {}", e))?;
    let obj: serde_json::Value = serde_json::from_slice(&json_str)
        .map_err(|e| format!("游标 JSON 解析失败: {}", e))?;
    let values = obj["v"].as_array()
        .ok_or("游标缺少 v 字段")?
        .iter()
        .map(|v| v.as_str().unwrap_or("").to_string())
        .collect();
    let id = obj["id"].as_str()
        .ok_or("游标缺少 id 字段")?;
    let id = Uuid::parse_str(id).map_err(|e| format!("游标 id 解析失败: {}", e))?;
    Ok((values, id))
}

/// 构建 Keyset 分页 SQL
pub fn build_keyset_query_sql(
    table_name: &str,
    tenant_id: Uuid,
    limit: u64,
    cursor: Option<String>,
    sort_column: Option<String>,
    sort_direction: &str,
    generated_fields: &[String],
) -> Result<(String, Vec<Value>), String> {
    let dir = match sort_direction {
        "ASC" => "ASC",
        _ => "DESC",
    };
    let sort_col = sort_column
        .as_deref()
        .unwrap_or("\"created_at\"");
    let sort_col_name = sort_column.as_deref().unwrap_or("created_at");

    let mut values: Vec<Value> = vec![tenant_id.into()];
    let mut param_idx = 2;

    let cursor_condition = if let Some(c) = cursor {
        let (sort_vals, cursor_id) = Self::decode_cursor(&c)?;
        // ROW(sort_val, id) > ($N, $N+1)
        let cond = format!(
            "ROW({}, \"id\") {} (${}, ${})",
            sort_col,
            if dir == "ASC" { ">" } else { "<" },
            param_idx, param_idx + 1
        );
        values.push(Value::String(Some(Box::new(
            sort_vals.first().cloned().unwrap_or_default()
        ))));
        values.push(cursor_id.into());
        param_idx += 2;
        Some(cond)
    } else {
        None
    };

    let where_extra = cursor_condition
        .map(|c| format!(" AND {}", c))
        .unwrap_or_default();

    let sql = format!(
        "SELECT id, data, created_at, updated_at, version FROM \"{}\" \
         WHERE \"tenant_id\" = $1 AND \"deleted_at\" IS NULL{} \
         ORDER BY {} {}, \"id\" {} LIMIT ${}",
        table_name, where_extra, sort_col, dir, dir, param_idx,
    );
    values.push((limit as i64).into());

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

在 `Cargo.toml` 中添加 `base64` 依赖：

```toml
base64 = { workspace = true }
```

> 如果 workspace 中没有 base64，则添加 `base64 = "0.22"` 到 `[dependencies]`。

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

Run: `cargo test -p erp-plugin`
Expected: 全部 PASS

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

```bash
git add crates/erp-plugin/src/dynamic_table.rs crates/erp-plugin/src/data_dto.rs crates/erp-plugin/Cargo.toml
git commit -m "feat(plugin): Keyset Pagination — cursor 编解码 + 游标分页 SQL"
```

---

### Task 1.6: state.rs — Schema 缓存 (moka)

**Files:**
- Modify: `crates/erp-plugin/src/state.rs`
- Modify: `crates/erp-server/src/state.rs` (**C1 修复：更新 FromRef 实现**)
- Modify: `crates/erp-plugin/Cargo.toml`

- [ ] **Step 0: 将 `dynamic_table.rs` 中的 `sanitize_identifier` 改为 `pub(crate) fn`**

```rust
// dynamic_table.rs — 将 fn sanitize_identifier 改为 pub(crate) fn
pub(crate) fn sanitize_identifier(input: &str) -> String {
```

同时在 `data_service.rs` 中将私有 `EntityInfo` 改为使用 `state::EntityInfo`（避免类型冲突）：
- 删除 `data_service.rs` 中的私有 `struct EntityInfo` 和 `impl EntityInfo`
- 改为引用 `crate::state::EntityInfo`
- 将 `info.fields()` 改为 `fields_from_schema(&info.schema_json)` 辅助函数

```rust
/// 从 schema_json 解析字段列表
fn fields_from_schema(schema_json: &serde_json::Value) -> AppResult<Vec<PluginField>> {
    let entity_def: crate::manifest::PluginEntity =
        serde_json::from_value(schema_json.clone())
            .map_err(|e| AppError::Internal(format!("解析 entity schema 失败: {}", e)))?;
    Ok(entity_def.fields)
}
```

- [ ] **Step 1: 添加 moka 依赖**

在 `crates/erp-plugin/Cargo.toml` 的 `[dependencies]` 中添加：

```toml
moka = { version = "0.12", features = ["sync"] }
```

- [ ] **Step 2: 修改 PluginState**

```rust
use moka::sync::Cache;
use std::time::Duration;

use sea_orm::DatabaseConnection;
use erp_core::events::EventBus;
use crate::engine::PluginEngine;

/// 插件模块共享状态
#[derive(Clone)]
pub struct PluginState {
    pub db: DatabaseConnection,
    pub event_bus: EventBus,
    pub engine: PluginEngine,
    /// Schema 缓存 — key: "{plugin_id}:{entity_name}:{tenant_id}"
    pub entity_cache: Cache<String, EntityInfo>,
}

/// 缓存的实体信息
#[derive(Clone, Debug)]
pub struct EntityInfo {
    pub table_name: String,
    pub schema_json: serde_json::Value,
    pub generated_fields: Vec<String>,
}

impl Default for PluginState {
    fn default() -> Self {
        // 此方法仅用于测试；生产环境由 main.rs 构造
        unimplemented!("PluginState 应通过 new() 构造")
    }
}

impl PluginState {
    pub fn new(db: DatabaseConnection, event_bus: EventBus, engine: PluginEngine) -> Self {
        let entity_cache = Cache::builder()
            .max_capacity(1000)
            .time_to_idle(Duration::from_secs(300)) // TTL 5 分钟
            .build();
        Self { db, event_bus, engine, entity_cache }
    }
}
```

**同时更新 `crates/erp-server/src/state.rs` 的 FromRef 实现：**

```rust
impl FromRef<AppState> for erp_plugin::state::PluginState {
    fn from_ref(state: &AppState) -> Self {
        Self {
            db: state.db.clone(),
            event_bus: state.event_bus.clone(),
            engine: state.plugin_engine.clone(),
            entity_cache: Cache::builder()  // 每次 from_ref 都新建 Cache 不好
                .max_capacity(1000)         // → 应将 cache 存入 AppState
                .time_to_idle(Duration::from_secs(300))
                .build(),
        }
    }
}
```

> **更好的方案：** 将 `entity_cache` 放入 `AppState`，避免每次请求重建缓存：
> 1. 在 `AppState` 中添加 `pub plugin_entity_cache: moka::sync::Cache<String, erp_plugin::state::EntityInfo>`
> 2. 在 `main.rs` 中初始化：`plugin_entity_cache: Cache::builder().max_capacity(1000).time_to_idle(Duration::from_secs(300)).build()`
> 3. `FromRef` 中传递 `state.plugin_entity_cache.clone()`

**涉及文件更新：**
- `crates/erp-server/src/state.rs` — AppState 添加 cache 字段 + FromRef 更新
- `crates/erp-server/src/main.rs` — AppState 初始化时构建 cache
```

- [ ] **Step 3: 更新 data_service.rs 使用缓存**

在 `data_service.rs` 中修改 `resolve_entity_info` 方法签名，增加缓存参数：

```rust
/// 从缓存或数据库获取实体信息
pub async fn resolve_entity_info_cached(
    plugin_id: Uuid,
    entity_name: &str,
    tenant_id: Uuid,
    db: &sea_orm::DatabaseConnection,
    cache: &moka::sync::Cache<String, crate::state::EntityInfo>,
) -> AppResult<crate::state::EntityInfo> {
    let cache_key = format!("{}:{}:{}", plugin_id, entity_name, tenant_id);
    if let Some(info) = cache.get(&cache_key) {
        return Ok(info);
    }

    let entity = 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))
        })?;

    // 解析 generated_fields
    let entity_def: crate::manifest::PluginEntity =
        serde_json::from_value(entity.schema_json.clone())
            .map_err(|e| AppError::Internal(format!("解析 entity schema 失败: {}", e)))?;
    let generated_fields: Vec<String> = entity_def.fields.iter()
        .filter(|f| f.field_type.supports_generated_column())
        .filter(|f| {
            f.unique || f.sortable == Some(true) || f.filterable == Some(true)
                || (f.required && (f.sortable == Some(true) || f.filterable == Some(true)))
        })
        .map(|f| crate::dynamic_table::sanitize_identifier(&f.name))
        .collect();

    let info = crate::state::EntityInfo {
        table_name: entity.table_name,
        schema_json: entity.schema_json,
        generated_fields,
    };

    cache.insert(cache_key, info.clone());
    Ok(info)
}
```

> **注意：** 需要将 `sanitize_identifier` 改为 `pub fn` 或新增一个 `pub fn sanitize_field_name` 包装。将 `dynamic_table.rs` 中的 `fn sanitize_identifier` 改为 `pub fn sanitize_identifier`。

- [ ] **Step 4: 编译验证**

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

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

```bash
git add crates/erp-plugin/src/state.rs crates/erp-plugin/src/data_service.rs crates/erp-plugin/src/dynamic_table.rs crates/erp-plugin/Cargo.toml
git commit -m "feat(plugin): Schema 缓存 — moka LRU Cache 消除 resolve_entity_info 重复查库"
```

---

### Task 1.7: data_service.rs — 聚合 Redis 缓存

**Files:**
- Modify: `crates/erp-plugin/src/data_service.rs`

- [ ] **Step 1: 添加 Redis 缓存逻辑**

在 `data_service.rs` 的 `aggregate` 方法中，新增 Redis 缓存层：

```rust
/// 聚合查询（带 Redis 缓存）
pub async fn aggregate_cached(
    plugin_id: Uuid,
    entity_name: &str,
    tenant_id: Uuid,
    db: &sea_orm::DatabaseConnection,
    group_by_field: &str,
    filter: Option<serde_json::Value>,
    redis: Option<&redis::Client>,
) -> AppResult<Vec<(String, i64)>> {
    // 尝试从 Redis 读取
    if let Some(client) = redis {
        let cache_key = format!(
            "plugin:{}:{}:agg:{}:{}",
            plugin_id, entity_name, group_by_field, tenant_id
        );
        if let Ok(conn) = client.get_multiplexed_async_connection().await {
            // Redis 读取逻辑（如命中则直接返回）
            // 此处省略具体实现，下一 step 补全
        }
    }

    // 回退到数据库查询
    Self::aggregate(plugin_id, entity_name, tenant_id, db, group_by_field, filter).await
}
```

> **注意：** Redis 缓存为可选增强。如果当前 `PluginState` 中没有 Redis 连接，此步骤可先定义接口，后续接入。设计规格中的 SLA 目标在缓存命中时 p50 < 50ms。

- [ ] **Step 2: 编译验证**

Run: `cargo check -p erp-plugin`
Expected: 编译通过（Redis 为 optional 依赖）

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

```bash
git add crates/erp-plugin/src/data_service.rs
git commit -m "feat(plugin): 聚合查询 Redis 缓存骨架"
```

---

### Task 1.8: data_service.rs — list 方法集成 Generated Column 路由 + Keyset

**Files:**
- Modify: `crates/erp-plugin/src/data_service.rs:76-165` (list 方法)

- [ ] **Step 1: 修改 list 方法使用新的查询构建器**

```rust
/// 列表查询（支持过滤/搜索/排序/游标分页）
pub async fn list(
    plugin_id: Uuid,
    entity_name: &str,
    tenant_id: Uuid,
    page: u64,
    page_size: u64,
    db: &sea_orm::DatabaseConnection,
    cache: &moka::sync::Cache<String, crate::state::EntityInfo>,
    filter: Option<serde_json::Value>,
    search: Option<String>,
    sort_by: Option<String>,
    sort_order: Option<String>,
    cursor: Option<String>,
) -> AppResult<(Vec<PluginDataResp>, u64, Option<String>)> {
    let info = Self::resolve_entity_info_cached(plugin_id, entity_name, tenant_id, db, cache).await?;
    let entity_fields = info.fields()?;

    // searchable 字段列表
    let search_tuple = {
        let searchable: Vec<&str> = entity_fields
            .iter()
            .filter(|f| f.searchable == Some(true))
            .map(|f| f.name.as_str())
            .collect();
        match (searchable.is_empty(), &search) {
            (false, Some(kw)) => Some((searchable.join(","), kw.clone())),
            _ => None,
        }
    };

    // Count
    let (count_sql, count_values) =
        DynamicTableManager::build_count_sql(&info.table_name, tenant_id);
    #[derive(FromQueryResult)]
    struct CountResult { count: i64 }
    let total = CountResult::find_by_statement(Statement::from_sql_and_values(
        sea_orm::DatabaseBackend::Postgres, count_sql, count_values,
    )).one(db).await?.map(|r| r.count as u64).unwrap_or(0);

    // Query — 有 cursor 走 keyset，否则走 offset
    let (sql, values) = if let Some(c) = cursor {
        DynamicTableManager::build_keyset_query_sql(
            &info.table_name, tenant_id, page_size,
            Some(c),
            sort_by.clone(),
            sort_order.as_deref().unwrap_or("DESC"),
            &info.generated_fields,
        ).map_err(|e| AppError::Validation(e))?
    } else {
        DynamicTableManager::build_filtered_query_sql_ex(
            &info.table_name, tenant_id, page_size,
            page.saturating_sub(1) * page_size,
            filter, search_tuple, sort_by, sort_order,
            &info.generated_fields,
        ).map_err(|e| AppError::Validation(e))?
    };

    #[derive(FromQueryResult)]
    struct DataRow {
        id: Uuid,
        data: serde_json::Value,
        created_at: chrono::DateTime<chrono::Utc>,
        updated_at: chrono::DateTime<chrono::Utc>,
        version: i32,
    }

    let rows = DataRow::find_by_statement(Statement::from_sql_and_values(
        sea_orm::DatabaseBackend::Postgres, sql, values,
    )).all(db).await?;

    // 生成下一页 cursor（W2 修复：编码排序字段值）
    let next_cursor = rows.last().map(|r| {
        let sort_val = if let Some(ref sb) = sort_by {
            r.data.get(sb).and_then(|v| v.as_str()).unwrap_or("").to_string()
        } else {
            // 默认排序用 created_at 的字符串表示
            r.created_at.to_rfc3339()
        };
        DynamicTableManager::encode_cursor(&[sort_val], &r.id)
    });

    let items = rows.into_iter().map(|r| PluginDataResp {
        id: r.id.to_string(),
        data: r.data,
        created_at: Some(r.created_at),
        updated_at: Some(r.updated_at),
        version: Some(r.version),
    }).collect();

    Ok((items, total, next_cursor))
}
```

- [ ] **Step 2: 更新 handler 调用**

`data_handler.rs` 的 `list_plugin_data` 需要传入 `cache` 和 `cursor`，在后续 Chunk 中统一调整。

- [ ] **Step 3: 编译验证**

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

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

```bash
git add crates/erp-plugin/src/data_service.rs
git commit -m "feat(plugin): list 方法集成 Generated Column 路由 + Keyset Pagination"
```

---

### Task 1.9: CRM plugin.toml — 更新声明以利用 Generated Column

**Files:**
- Modify: `crates/erp-plugin-crm/plugin.toml`

- [ ] **Step 1: 确认当前字段声明已包含必要标记**

CRM 的 `plugin.toml` 已正确声明了 `unique`, `filterable`, `sortable`, `searchable` 标记。`create_table` 方法会自动根据这些标记创建 Generated Column 和索引。**无需修改 plugin.toml。**

验证：重新安装 CRM 插件后，`plugin_erp_crm_customer` 表应自动包含 `_f_code`, `_f_name`, `_f_customer_type`, `_f_status`, `_f_level` 等 Generated Column。

- [ ] **Step 2: 集成验证**

Run: 启动后端服务 `cargo run -p erp-server`，调用 API 卸载+重新安装 CRM 插件
Expected: 动态表包含 Generated Column，pg_trgm 索引已创建

- [ ] **Step 3: 提交（如有改动）**

```bash
git add crates/erp-plugin-crm/plugin.toml
git commit -m "chore(crm): 验证 Generated Column 自动生成 — 无需修改 plugin.toml"
```

---

## Chunk 2: 数据完整性框架

### Task 2.1: manifest.rs — 扩展 PluginField (ref_entity / validation / no_cycle)

**Files:**
- Modify: `crates/erp-plugin/src/manifest.rs:49-69` (PluginField struct)

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

```rust
#[test]
fn parse_field_with_ref_entity() {
    let toml = r#"
[metadata]
id = "test"
name = "Test"
version = "0.1.0"

[schema]
[[schema.entities]]
name = "contact"
display_name = "联系人"

[[schema.entities.fields]]
name = "customer_id"
field_type = "uuid"
required = true
display_name = "所属客户"
ref_entity = "customer"
"#;
    let manifest = parse_manifest(toml).unwrap();
    let field = &manifest.schema.unwrap().entities[0].fields[0];
    assert_eq!(field.ref_entity.as_deref(), Some("customer"));
}

#[test]
fn parse_field_with_validation() {
    let toml = r#"
[metadata]
id = "test"
name = "Test"
version = "0.1.0"

[schema]
[[schema.entities]]
name = "contact"
display_name = "联系人"

[[schema.entities.fields]]
name = "phone"
field_type = "string"
display_name = "手机号"
validation = { pattern = "^1[3-9]\\d{9}$", message = "手机号格式不正确" }
"#;
    let manifest = parse_manifest(toml).unwrap();
    let field = &manifest.schema.unwrap().entities[0].fields[0];
    let v = field.validation.as_ref().unwrap();
    assert_eq!(v.pattern.as_deref(), Some("^1[3-9]\\d{9}$"));
    assert_eq!(v.message.as_deref(), Some("手机号格式不正确"));
}

#[test]
fn parse_field_with_no_cycle() {
    let toml = r#"
[metadata]
id = "test"
name = "Test"
version = "0.1.0"

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

[[schema.entities.fields]]
name = "parent_id"
field_type = "uuid"
display_name = "上级客户"
ref_entity = "customer"
no_cycle = true
"#;
    let manifest = parse_manifest(toml).unwrap();
    let field = &manifest.schema.unwrap().entities[0].fields[0];
    assert_eq!(field.no_cycle, Some(true));
    assert_eq!(field.ref_entity.as_deref(), Some("customer"));
}
```

- [ ] **Step 2: 验证测试失败**

Run: `cargo test -p erp-plugin -- parse_field_with_ref`
Expected: 编译失败（`ref_entity` 字段不存在）

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

在 `PluginField` 中新增三个字段：

```rust
pub struct PluginField {
    // ... 已有字段 ...
    pub ref_entity: Option<String>,           // 外键引用的实体名
    pub validation: Option<FieldValidation>,  // 字段校验规则
    pub no_cycle: Option<bool>,               // 禁止循环引用
}

/// 字段校验规则
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FieldValidation {
    pub pattern: Option<String>,   // 正则表达式
    pub message: Option<String>,   // 校验失败提示
}
```

同时更新 `#[cfg(test)]` 中的 `default_for_field()` 辅助方法：

```rust
pub fn default_for_field() -> Self {
    Self {
        // ... 已有字段 ...
        ref_entity: None,
        validation: None,
        no_cycle: None,
    }
}
```

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

Run: `cargo test -p erp-plugin`
Expected: 全部 PASS

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

```bash
git add crates/erp-plugin/src/manifest.rs
git commit -m "feat(plugin): PluginField 扩展 — ref_entity / validation / no_cycle"
```

---

### Task 2.2: manifest.rs — 新增 PluginRelation (级联删除声明)

**Files:**
- Modify: `crates/erp-plugin/src/manifest.rs` (PluginEntity + OnDeleteStrategy)

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

```rust
#[test]
fn parse_entity_with_relations() {
    let toml = r#"
[metadata]
id = "test"
name = "Test"
version = "0.1.0"

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

[[schema.entities.fields]]
name = "code"
field_type = "string"
required = true
display_name = "编码"

[[schema.entities.relations]]
entity = "contact"
foreign_key = "customer_id"
on_delete = "cascade"

[[schema.entities.relations]]
entity = "customer_tag"
foreign_key = "customer_id"
on_delete = "cascade"
"#;
    let manifest = parse_manifest(toml).unwrap();
    let entity = &manifest.schema.unwrap().entities[0];
    assert_eq!(entity.relations.len(), 2);
    assert_eq!(entity.relations[0].entity, "contact");
    assert_eq!(entity.relations[0].foreign_key, "customer_id");
    assert!(matches!(entity.relations[0].on_delete, OnDeleteStrategy::Cascade));
}
```

- [ ] **Step 2: 实现 PluginRelation + OnDeleteStrategy**

```rust
/// 级联删除策略
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(rename_all = "snake_case")]
pub enum OnDeleteStrategy {
    Nullify,   // 置空外键字段
    Cascade,   // 级联软删除
    Restrict,  // 存在关联时拒绝删除
}

/// 实体关联关系声明
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PluginRelation {
    pub entity: String,                     // 关联实体名
    pub foreign_key: String,                // 关联实体中的外键字段名
    pub on_delete: OnDeleteStrategy,        // 级联策略
}
```

在 `PluginEntity` 中添加：

```rust
pub struct PluginEntity {
    pub name: String,
    pub display_name: String,
    #[serde(default)]
    pub fields: Vec<PluginField>,
    #[serde(default)]
    pub indexes: Vec<PluginIndex>,
    #[serde(default)]
    pub relations: Vec<PluginRelation>,     // 新增
}
```

- [ ] **Step 3: 运行测试**

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

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

```bash
git add crates/erp-plugin/src/manifest.rs
git commit -m "feat(plugin): PluginRelation 级联删除声明 + OnDeleteStrategy"
```

---

### Task 2.3: data_service.rs — 外键校验 (ref_entity)

**Files:**
- Modify: `crates/erp-plugin/src/data_service.rs` (validate_data 扩展)

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

```rust
#[tokio::test]
async fn test_validate_ref_entity_rejects_missing_reference() {
    // 简单验证逻辑单元测试：ref_entity 字段指向不存在的记录时应报错
    // 注意：此测试需要数据库连接，标记为集成测试或使用 mock
    // 此处先验证 validate_ref_entities 函数签名存在
}
```

> 由于外键校验需要数据库查询，此任务更适合集成测试。此处先实现逻辑，集成测试在手动验证阶段进行。

- [ ] **Step 2: 实现 ref_entity 校验函数**

在 `data_service.rs` 中新增：

```rust
/// 校验外键引用 — 检查 ref_entity 字段指向的记录是否存在
async fn validate_ref_entities(
    data: &serde_json::Value,
    fields: &[PluginField],
    current_entity: &str,
    plugin_id: Uuid,
    tenant_id: Uuid,
    db: &sea_orm::DatabaseConnection,
    is_create: bool,
    record_id: Option<Uuid>,
) -> AppResult<()> {
    let obj = data.as_object().ok_or_else(|| {
        AppError::Validation("data 必须是 JSON 对象".to_string())
    })?;

    for field in fields {
        let Some(ref_entity_name) = &field.ref_entity else { continue };

        let Some(val) = obj.get(&field.name) else { continue };
        let str_val = val.as_str().unwrap_or("").trim().to_string();

        // null 或空字符串且非 required → 跳过
        if str_val.is_empty() && !field.required {
            continue;
        }
        if str_val.is_empty() {
            continue;
        }

        // 解析 UUID
        let ref_id = Uuid::parse_str(&str_val).map_err(|_| {
            AppError::Validation(format!(
                "字段 '{}' 的值 '{}' 不是有效的 UUID",
                field.display_name.as_deref().unwrap_or(&field.name),
                str_val
            ))
        })?;

        // 自引用 + create：如果引用的是自身 ID，跳过（记录尚不存在）
        if ref_entity_name == current_entity && is_create {
            if let Some(rid) = record_id {
                if ref_id == rid {
                    continue;
                }
            } else {
                // create 时无 record_id，自引用跳过
                continue;
            }
        }

        // 查询被引用记录是否存在
        let ref_table = DynamicTableManager::table_name(
            &resolve_manifest_id(plugin_id, tenant_id, db).await?,
            ref_entity_name,
        );

        let check_sql = format!(
            "SELECT 1 FROM \"{}\" WHERE id = $1 AND tenant_id = $2 AND deleted_at IS NULL LIMIT 1",
            ref_table
        );
        let result: Option<(i32,)> = sqlx::query_as(&check_sql)
            .bind(ref_id)
            .bind(tenant_id)
            .fetch_optional(db)
            .await
            .map_err(|e| AppError::Internal(format!("外键校验查询失败: {}", e)))?;

        if result.is_none() {
            return Err(AppError::Validation(format!(
                "引用的 {} 记录不存在（ID: {}）",
                ref_entity_name, ref_id
            )));
        }
    }

    Ok(())
}
```

> **注意：** 上述代码使用了 `sqlx` 风格，但项目使用 `sea_orm`。实际实现应使用 `Statement::from_sql_and_values`：

```rust
#[derive(FromQueryResult)]
struct ExistsCheck { exists: Option<i32> }

let check_sql = format!(
    "SELECT 1 as exists FROM \"{}\" WHERE id = $1 AND tenant_id = $2 AND deleted_at IS NULL LIMIT 1",
    ref_table
);
let result = ExistsCheck::find_by_statement(Statement::from_sql_and_values(
    sea_orm::DatabaseBackend::Postgres,
    check_sql,
    [ref_id.into(), tenant_id.into()],
)).one(db).await?;

if result.is_none() {
    return Err(AppError::Validation(format!(
        "引用的 {} 记录不存在（ID: {}）",
        ref_entity_name, ref_id
    )));
}
```

- [ ] **Step 3: 集成到 create/update 方法**

在 `create` 方法的 `validate_data` 调用之后添加：

```rust
validate_ref_entities(&data, &fields, entity_name, plugin_id, tenant_id, db, true, None).await?;
```

在 `update` 方法中添加：

```rust
validate_ref_entities(&data, &fields, entity_name, plugin_id, tenant_id, db, false, Some(id)).await?;
```

- [ ] **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): 外键校验 — ref_entity 字段验证引用记录存在性"
```

---

### Task 2.4: data_service.rs — 字段校验 (validation.pattern)

**Files:**
- Modify: `crates/erp-plugin/src/data_service.rs` (validate_data 扩展)
- Modify: `crates/erp-plugin/Cargo.toml` (添加 regex 依赖)

- [ ] **Step 1: 添加 regex 依赖**

在 `Cargo.toml` 中添加：

```toml
regex = "1"
```

- [ ] **Step 2: 扩展 validate_data**

修改 `validate_data` 函数，在 required 检查之后增加正则校验：

```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 {
        let label = field.display_name.as_deref().unwrap_or(&field.name);

        // required 检查
        if field.required && !obj.contains_key(&field.name) {
            return Err(AppError::Validation(format!("字段 '{}' 不能为空", label)));
        }

        // 正则校验
        if let Some(validation) = &field.validation {
            if let Some(pattern) = &validation.pattern {
                if let Some(val) = obj.get(&field.name) {
                    let str_val = val.as_str().unwrap_or("");
                    if !str_val.is_empty() {
                        let re = regex::Regex::new(pattern)
                            .map_err(|e| AppError::Internal(format!("正则表达式编译失败: {}", e)))?;
                        if !re.is_match(str_val) {
                            let msg = validation.message.as_deref()
                                .unwrap_or(&format!("字段 '{}' 格式不正确", label));
                            return Err(AppError::Validation(msg.to_string()));
                        }
                    }
                }
            }
        }
    }

    Ok(())
}
```

- [ ] **Step 3: 写单元测试**

```rust
#[cfg(test)]
mod validate_tests {
    use super::*;
    use crate::manifest::{FieldValidation, PluginField, PluginFieldType};

    fn make_field(name: &str, pattern: Option<&str>, message: Option<&str>) -> PluginField {
        PluginField {
            name: name.to_string(),
            field_type: PluginFieldType::String,
            required: false,
            validation: pattern.map(|p| FieldValidation {
                pattern: Some(p.to_string()),
                message: message.map(|m| m.to_string()),
            }),
            ..PluginField::default_for_field()
        }
    }

    #[test]
    fn validate_phone_pattern_rejects_invalid() {
        let fields = vec![make_field("phone", Some("^1[3-9]\\d{9}$"), Some("手机号格式不正确"))];
        let data = serde_json::json!({"phone": "1234"});
        let result = validate_data(&data, &fields);
        assert!(result.is_err());
    }

    #[test]
    fn validate_phone_pattern_accepts_valid() {
        let fields = vec![make_field("phone", Some("^1[3-9]\\d{9}$"), Some("手机号格式不正确"))];
        let data = serde_json::json!({"phone": "13812345678"});
        let result = validate_data(&data, &fields);
        assert!(result.is_ok());
    }

    #[test]
    fn validate_empty_optional_field_skips_pattern() {
        let fields = vec![make_field("phone", Some("^1[3-9]\\d{9}$"), None)];
        let data = serde_json::json!({"phone": ""});
        let result = validate_data(&data, &fields);
        assert!(result.is_ok()); // 空值 + 非 required → 跳过校验
    }
}
```

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

Run: `cargo test -p erp-plugin -- validate`
Expected: 全部 PASS

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

```bash
git add crates/erp-plugin/src/data_service.rs crates/erp-plugin/Cargo.toml
git commit -m "feat(plugin): 字段正则校验 — validation.pattern 支持"
```

---

### Task 2.5: data_service.rs — 循环引用检测 (no_cycle)

**Files:**
- Modify: `crates/erp-plugin/src/data_service.rs`

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

```rust
#[test]
fn detect_cycle_in_self_reference() {
    // 循环检测是纯逻辑：A.parent_id = B, B.parent_id = A → 检测到循环
    // 需要数据库查询链，此处测试 detect_cycle 函数签名
}
```

> 循环检测需要数据库交互，此处直接实现，手动集成测试验证。

- [ ] **Step 2: 实现循环检测**

在 `data_service.rs` 中新增：

```rust
/// 循环引用检测 — 用于 no_cycle 字段
/// 从当前记录开始，沿 ref_entity 链向上追溯，检测是否形成环
async fn check_no_cycle(
    record_id: Uuid,
    field: &PluginField,
    data: &serde_json::Value,
    table_name: &str,
    tenant_id: Uuid,
    db: &sea_orm::DatabaseConnection,
) -> AppResult<()> {
    let Some(val) = data.get(&field.name) else { return Ok(()) };
    let new_parent = val.as_str().unwrap_or("").trim().to_string();
    if new_parent.is_empty() {
        return Ok(());
    }
    let new_parent_id = Uuid::parse_str(&new_parent).map_err(|_| {
        AppError::Validation("parent_id 不是有效的 UUID".to_string())
    })?;

    let field_name = sanitize_identifier(&field.name);
    let mut visited = vec![record_id];
    let mut current_id = new_parent_id;

    // 最多追溯 100 层，防止无限循环
    for _ in 0..100 {
        if visited.contains(&current_id) {
            let label = field.display_name.as_deref().unwrap_or(&field.name);
            return Err(AppError::Validation(format!(
                "字段 '{}' 形成循环引用", label
            )));
        }
        visited.push(current_id);

        // 查询 current 的 parent_id
        let query_sql = format!(
            "SELECT data->>'{}' as parent FROM \"{}\" WHERE id = $1 AND tenant_id = $2 AND deleted_at IS NULL",
            field_name, table_name
        );
        #[derive(FromQueryResult)]
        struct ParentRow { parent: Option<String> }
        let row = ParentRow::find_by_statement(Statement::from_sql_and_values(
            sea_orm::DatabaseBackend::Postgres,
            query_sql,
            [current_id.into(), tenant_id.into()],
        )).one(db).await?;

        match row {
            Some(r) => {
                let parent = r.parent.unwrap_or_default().trim().to_string();
                if parent.is_empty() {
                    break; // 到达根节点
                }
                current_id = Uuid::parse_str(&parent).map_err(|_| {
                    AppError::Internal("parent_id 不是有效的 UUID".to_string())
                })?;
            }
            None => break, // 记录不存在或已删除
        }
    }

    Ok(())
}
```

- [ ] **Step 3: 集成到 update 方法**

在 `update` 方法中，`validate_ref_entities` 之后添加：

```rust
// 循环引用检测
for field in &fields {
    if field.no_cycle == Some(true) && data.get(&field.name).is_some() {
        check_no_cycle(id, field, &data, &info.table_name, tenant_id, db).await?;
    }
}
```

- [ ] **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): 循环引用检测 — no_cycle 字段支持"
```

---

### Task 2.6: data_service.rs — 级联删除 (relations)

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

- [ ] **Step 1: 实现级联删除**

修改 `delete` 方法：

```rust
/// 删除（软删除）— 支持级联策略
pub async fn delete(
    plugin_id: Uuid,
    entity_name: &str,
    id: Uuid,
    tenant_id: Uuid,
    db: &sea_orm::DatabaseConnection,
    cache: &moka::sync::Cache<String, crate::state::EntityInfo>,
    event_bus: &EventBus,
) -> AppResult<()> {
    let info = Self::resolve_entity_info_cached(plugin_id, entity_name, tenant_id, db, cache).await?;
    let entity_def: crate::manifest::PluginEntity =
        serde_json::from_value(info.schema_json.clone())
            .map_err(|e| AppError::Internal(format!("解析 entity schema 失败: {}", e)))?;

    // 处理级联关系
    let manifest_id = resolve_manifest_id(plugin_id, tenant_id, db).await?;
    for relation in &entity_def.relations {
        let rel_table = DynamicTableManager::table_name(&manifest_id, &relation.entity);
        let fk = sanitize_identifier(&relation.foreign_key);

        match relation.on_delete {
            OnDeleteStrategy::Restrict => {
                // 检查是否有引用
                let check_sql = format!(
                    "SELECT 1 FROM \"{}\" WHERE data->>'{}' = $1 AND tenant_id = $2 AND deleted_at IS NULL LIMIT 1",
                    rel_table, fk
                );
                #[derive(FromQueryResult)]
                struct RefCheck { exists: Option<i32> }
                let has_ref = RefCheck::find_by_statement(Statement::from_sql_and_values(
                    sea_orm::DatabaseBackend::Postgres,
                    check_sql,
                    [id.to_string().into(), tenant_id.into()],
                )).one(db).await?;
                if has_ref.is_some() {
                    return Err(AppError::Validation(format!(
                        "存在关联的 {} 记录，无法删除",
                        relation.entity
                    )));
                }
            }
            OnDeleteStrategy::Nullify => {
                // 将关联记录的外键置空
                let nullify_sql = format!(
                    "UPDATE \"{}\" SET data = data || {{\\\"{}\\\": null}}, updated_at = NOW() WHERE data->>'{}' = $1 AND tenant_id = $2 AND deleted_at IS NULL",
                    rel_table, fk, fk
                );
                db.execute(Statement::from_sql_and_values(
                    sea_orm::DatabaseBackend::Postgres,
                    nullify_sql,
                    [id.to_string().into(), tenant_id.into()],
                )).await?;
            }
            OnDeleteStrategy::Cascade => {
                // 级联软删除（深度上限 3 层，此处只处理第 1 层）
                let cascade_sql = format!(
                    "UPDATE \"{}\" SET deleted_at = NOW(), updated_at = NOW() WHERE data->>'{}' = $1 AND tenant_id = $2 AND deleted_at IS NULL",
                    rel_table, fk
                );
                db.execute(Statement::from_sql_and_values(
                    sea_orm::DatabaseBackend::Postgres,
                    cascade_sql,
                    [id.to_string().into(), tenant_id.into()],
                )).await?;
            }
        }
    }

    // 软删除主记录
    let (sql, values) = DynamicTableManager::build_delete_sql(&info.table_name, id, tenant_id);
    db.execute(Statement::from_sql_and_values(
        sea_orm::DatabaseBackend::Postgres,
        sql,
        values,
    )).await?;

    Ok(())
}
```

- [ ] **Step 2: 编译验证**

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

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

```bash
git add crates/erp-plugin/src/data_service.rs
git commit -m "feat(plugin): 级联删除 — Restrict/Nullify/Cascade 三种策略"
```

---

### Task 2.7: CRM plugin.toml — 添加 ref_entity / relations / validation / no_cycle

**Files:**
- Modify: `crates/erp-plugin-crm/plugin.toml`

- [ ] **Step 1: 更新 contact 实体 — customer_id 添加 ref_entity**

将 contact 的 customer_id 字段改为：

```toml
[[schema.entities.fields]]
name = "customer_id"
field_type = "uuid"
required = true
display_name = "所属客户"
ref_entity = "customer"
```

- [ ] **Step 2: 更新 communication 实体 — 添加 ref_entity**

```toml
[[schema.entities.fields]]
name = "customer_id"
field_type = "uuid"
required = true
display_name = "关联客户"
ref_entity = "customer"

[[schema.entities.fields]]
name = "contact_id"
field_type = "uuid"
display_name = "关联联系人"
ref_entity = "contact"
```

- [ ] **Step 3: 更新 customer_tag / customer_relationship — 添加 ref_entity**

```toml
# customer_tag
[[schema.entities.fields]]
name = "customer_id"
field_type = "uuid"
required = true
display_name = "关联客户"
ref_entity = "customer"

# customer_relationship
[[schema.entities.fields]]
name = "from_customer_id"
field_type = "uuid"
required = true
display_name = "源客户"
ref_entity = "customer"

[[schema.entities.fields]]
name = "to_customer_id"
field_type = "uuid"
required = true
display_name = "目标客户"
ref_entity = "customer"
```

- [ ] **Step 4: customer 实体 — 添加 relations + no_cycle + validation**

```toml
# customer 的 parent_id 字段添加 ref_entity + no_cycle
[[schema.entities.fields]]
name = "parent_id"
field_type = "uuid"
display_name = "上级客户"
ref_entity = "customer"
no_cycle = true

# customer 实体的 relations
[[schema.entities.relations]]
entity = "contact"
foreign_key = "customer_id"
on_delete = "nullify"

[[schema.entities.relations]]
entity = "communication"
foreign_key = "customer_id"
on_delete = "cascade"

[[schema.entities.relations]]
entity = "customer_tag"
foreign_key = "customer_id"
on_delete = "cascade"
```

contact 的 phone/email 添加 validation：

```toml
[[schema.entities.fields]]
name = "phone"
field_type = "string"
display_name = "手机号"
validation = { pattern = "^1[3-9]\\d{9}$", message = "手机号格式不正确" }

[[schema.entities.fields]]
name = "email"
field_type = "string"
display_name = "邮箱"
validation = { pattern = "^[\\w.-]+@[\\w.-]+\\.\\w+$", message = "邮箱格式不正确" }
```

- [ ] **Step 5: 验证 TOML 解析**

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

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

```bash
git add crates/erp-plugin-crm/plugin.toml
git commit -m "feat(crm): 添加 ref_entity / relations / validation / no_cycle 声明"
```

---

## Chunk 3: 行级数据权限

### Task 3.1: 数据库迁移 — role_permissions 添加 data_scope 列 + 权限补偿

**Files:**
- Create: `crates/erp-server/migration/src/m20260418_000036_add_data_scope_to_role_permissions.rs`
- Modify: `crates/erp-server/migration/src/lib.rs`

- [ ] **Step 1: 创建迁移文件**

```rust
// crates/erp-server/migration/src/m20260418_000036_add_data_scope_to_role_permissions.rs
use sea_orm_migration::prelude::*;

#[derive(DeriveMigrationName)]
pub struct Migration;

#[async_trait::async_trait]
impl MigrationTrait for Migration {
    async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
        // 添加 data_scope 列
        manager
            .alter_table(
                Table::alter()
                    .table(Alias::new("role_permissions"))
                    .add_column(
                        ColumnDef::new(Alias::new("data_scope"))
                            .string()
                            .not_null()
                            .default("all"),
                    )
                    .to_owned(),
            )
            .await?;

        // 权限补偿：为所有拥有 plugin.admin 权限的角色，自动分配所有已安装插件的实体级权限
        // data_scope 默认 'all'（管理员级别）
        let conn = manager.get_connection();
        conn.execute_unprepared(
            r#"
            INSERT INTO role_permissions (id, role_id, permission_id, tenant_id, data_scope, created_at, updated_at)
            SELECT gen_random_uuid(), rp.role_id, p.id, rp.tenant_id, 'all', NOW(), NOW()
            FROM role_permissions rp
            JOIN permissions p ON p.tenant_id = rp.tenant_id
            JOIN role_permissions rp_src ON rp_src.role_id = rp.role_id
            JOIN permissions p_src ON p_src.id = rp.permission_id AND p_src.code = 'plugin.admin'
            WHERE p.code LIKE 'erp-%'
              AND NOT EXISTS (
                SELECT 1 FROM role_permissions rp2
                WHERE rp2.role_id = rp.role_id AND rp2.permission_id = p.id
              )
            GROUP BY rp.role_id, p.id, rp.tenant_id
            "#
        ).await?;

        Ok(())
    }

    async fn down(&self, manager: &SchemaManager) -> Result<(), DbErr> {
        manager
            .alter_table(
                Table::alter()
                    .table(Alias::new("role_permissions"))
                    .drop_column(Alias::new("data_scope"))
                    .to_owned(),
            )
            .await
    }
}
```

- [ ] **Step 2: 注册迁移**

在 `lib.rs` 中添加 `mod m20260418_000036_add_data_scope_to_role_permissions;` 和对应的 `Box::new(...)`。

- [ ] **Step 3: 验证**

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

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

```bash
git add crates/erp-server/migration/src/m20260418_000036_add_data_scope_to_role_permissions.rs crates/erp-server/migration/src/lib.rs
git commit -m "feat(db): role_permissions 添加 data_scope 列 + plugin.admin 权限补偿"
```

---

### Task 3.2: erp-core — TenantContext 扩展 department_ids

**Files:**
- Modify: `crates/erp-core/src/types.rs:150-158` (TenantContext)

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

```rust
#[test]
fn tenant_context_with_departments() {
    let ctx = TenantContext {
        tenant_id: Uuid::now_v7(),
        user_id: Uuid::now_v7(),
        roles: vec!["admin".to_string()],
        permissions: vec!["user.read".to_string()],
        department_ids: vec![Uuid::now_v7(), Uuid::now_v7()],
    };
    assert_eq!(ctx.department_ids.len(), 2);
}
```

- [ ] **Step 2: 修改 TenantContext**

```rust
/// 租户上下文（中间件注入）
#[derive(Debug, Clone)]
pub struct TenantContext {
    pub tenant_id: Uuid,
    pub user_id: Uuid,
    pub roles: Vec<String>,
    pub permissions: Vec<String>,
    pub department_ids: Vec<Uuid>,  // 新增：用户所属部门 ID 列表
}
```

- [ ] **Step 3: 修复现有测试中所有 TenantContext 构造**

所有测试代码中构造 `TenantContext` 的地方需添加 `department_ids: vec![]`。

Run: `cargo test -p erp-core`
Expected: 全部 PASS

- [ ] **Step 4: 修复所有 crate 中的 TenantContext 构造**

在以下文件中搜索 `TenantContext {` 并添加 `department_ids: vec![]`：
- `crates/erp-auth/src/middleware/jwt_auth.rs` — JWT claims 解析时填充 department_ids
- `crates/erp-plugin/src/handler/data_handler.rs` — 无构造，仅使用
- 其他 handler 文件

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

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

```bash
git add crates/erp-core/src/types.rs crates/erp-auth/src/middleware/jwt_auth.rs
git commit -m "feat(core): TenantContext 新增 department_ids 字段"
```

---

### Task 3.3: erp-auth — JWT 中间件填充 department_ids

**Files:**
- Modify: `crates/erp-auth/src/middleware/jwt_auth.rs`

- [ ] **Step 1: 修改 JWT claims 解析**

在 JWT 中间件中，从 token claims 或数据库查询用户的部门 ID：

```rust
// 在构造 TenantContext 时，查询用户所属部门
let department_ids = {
    // 通过 user_positions 表关联 departments 表查询
    let positions = user_position::Entity::find()
        .filter(user_position::Column::UserId.eq(user_id))
        .filter(user_position::Column::TenantId.eq(tenant_id))
        .all(db)
        .await
        .unwrap_or_default();
    positions.iter().map(|p| p.department_id).collect()
};

TenantContext {
    tenant_id,
    user_id,
    roles,
    permissions,
    department_ids,
}
```

> **注意：** 具体查询逻辑取决于 `erp-auth` 中 Position/Department 的 SeaORM Entity 定义。需先确认 entity 路径。

- [ ] **Step 2: 编译验证**

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

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

```bash
git add crates/erp-auth/src/middleware/jwt_auth.rs
git commit -m "feat(auth): JWT 中间件填充 department_ids"
```

---

### Task 3.4: manifest.rs — 实体级 data_scope 声明

**Files:**
- Modify: `crates/erp-plugin/src/manifest.rs` (PluginEntity, PluginField, PluginPermission)

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

```rust
#[test]
fn parse_entity_with_data_scope() {
    let toml = r#"
[metadata]
id = "test"
name = "Test"
version = "0.1.0"

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

[[schema.entities.fields]]
name = "owner_id"
field_type = "uuid"
display_name = "负责人"
scope_role = "owner"

[[permissions]]
code = "customer.list"
name = "查看客户"
data_scope_levels = ["self", "department", "department_tree", "all"]
"#;
    let manifest = parse_manifest(toml).unwrap();
    let entity = &manifest.schema.unwrap().entities[0];
    assert_eq!(entity.data_scope, Some(true));
    assert_eq!(entity.fields[0].scope_role.as_deref(), Some("owner"));

    let perm = &manifest.permissions.unwrap()[0];
    assert_eq!(perm.data_scope_levels.as_ref().unwrap().len(), 4);
}
```

- [ ] **Step 2: 扩展结构体**

```rust
pub struct PluginEntity {
    pub name: String,
    pub display_name: String,
    pub fields: Vec<PluginField>,
    pub indexes: Vec<PluginIndex>,
    pub relations: Vec<PluginRelation>,
    pub data_scope: Option<bool>,  // 新增：是否启用行级数据权限
}

pub struct PluginField {
    // ... 已有字段 ...
    pub scope_role: Option<String>,  // 新增：标记为数据权限的"所有者"字段
}

pub struct PluginPermission {
    pub code: String,
    pub name: String,
    pub description: String,
    pub data_scope_levels: Option<Vec<String>>,  // 新增：支持的数据范围等级
}
```

- [ ] **Step 3: 运行测试**

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

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

```bash
git add crates/erp-plugin/src/manifest.rs
git commit -m "feat(plugin): 实体级 data_scope + scope_role + data_scope_levels 声明"
```

---

### Task 3.5: dynamic_table.rs — SQL 构建支持数据范围条件

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

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

```rust
#[test]
fn test_build_data_scope_condition_self() {
    let condition = DynamicTableManager::build_data_scope_condition(
        "self",
        &Uuid::parse_str("00000000-0000-0000-0000-000000000001").unwrap(),
        "owner_id",
        &[],
    );
    assert!(condition.contains("owner_id"), "self 应包含 owner_id 条件");
}

#[test]
fn test_build_data_scope_condition_department() {
    let dept_members = vec![
        Uuid::parse_str("00000000-0000-0000-0000-000000000001").unwrap(),
        Uuid::parse_str("00000000-0000-0000-0000-000000000002").unwrap(),
    ];
    let (sql, values) = DynamicTableManager::build_data_scope_condition_with_params(
        "department",
        &Uuid::parse_str("00000000-0000-0000-0000-000000000001").unwrap(),
        "owner_id",
        &dept_members,
        2, // 起始参数索引
    );
    assert!(sql.contains("IN"), "department 应使用 IN 条件");
    assert!(sql.contains("$2"), "参数索引应正确");
}
```

- [ ] **Step 2: 实现数据范围 SQL 构建**

```rust
/// 构建数据范围 SQL 条件
/// 返回 (条件 SQL, 附加参数)
pub fn build_data_scope_condition_with_params(
    scope_level: &str,
    current_user_id: &Uuid,
    owner_field: &str,
    dept_member_ids: &[Uuid],
    start_param_idx: usize,
    generated_fields: &[String],  // C4 修复：接受 generated_fields 参数
) -> (String, Vec<Value>) {
    let ref_fn = DynamicTableManager::field_reference_fn(generated_fields);
    let owner_ref = ref_fn(owner_field);  // 如果 owner_id 是 Generated Column，使用 _f_owner_id
    match scope_level {
        "self" => (
            format!("({} = ${} OR \"created_by\" = ${})", owner_ref, start_param_idx, start_param_idx),
            vec![current_user_id.to_string().into(), (*current_user_id).into()],
        ),
        "department" | "department_tree" => {
            if dept_member_ids.is_empty() {
                // 无部门 → 降级为 self
                (
                    format!("({} = ${} OR \"created_by\" = ${})", owner_ref, start_param_idx, start_param_idx),
                    vec![current_user_id.to_string().into(), (*current_user_id).into()],
                )
            } else {
                let placeholders: Vec<String> = dept_member_ids
                    .iter()
                    .enumerate()
                    .map(|(i, _)| format!("${}", start_param_idx + i))
                    .collect();
                let values: Vec<Value> = dept_member_ids
                    .iter()
                    .map(|id| id.to_string().into())
                    .collect();
                (
                    format!("{} IN ({})", owner_ref, placeholders.join(", ")),
                    values,
                )
            }
        }
        "all" | _ => (String::new(), vec![]), // all → 无额外条件
    }
}
```

- [ ] **Step 3: 运行测试**

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

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

```bash
git add crates/erp-plugin/src/dynamic_table.rs
git commit -m "feat(plugin): SQL 构建支持行级数据范围条件"
```

---

### Task 3.6: data_handler.rs — 移除权限 fallback

**Files:**
- Modify: `crates/erp-plugin/src/handler/data_handler.rs`

- [ ] **Step 1: 修改权限检查逻辑**

将所有 handler 中的两级 fallback 改为单级检查：

**当前（危险）：**
```rust
let fine_perm = compute_permission_code(&manifest_id, &entity, "list");
if require_permission(&ctx, &fine_perm).is_err() {
    require_permission(&ctx, "plugin.list")?;
}
```

**修改后：**
```rust
let fine_perm = compute_permission_code(&manifest_id, &entity, "list");
require_permission(&ctx, &fine_perm)?;
```

对所有 handler 方法（list, create, get, update, delete, count, aggregate）执行相同的修改：

- `create` 和 `update` 和 `delete`：删除 `plugin.admin` fallback
- `list` 和 `get` 和 `count` 和 `aggregate`：删除 `plugin.list` fallback

- [ ] **Step 2: 编译验证**

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

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

```bash
git add crates/erp-plugin/src/handler/data_handler.rs
git commit -m "fix(plugin): 移除权限 fallback — 必须显式分配实体级权限"
```

---

### Task 3.7: data_service.rs — 查询注入数据范围

**Files:**
- Modify: `crates/erp-plugin/src/data_service.rs` (list/count/aggregate 方法)

- [ ] **Step 1: 在 list 方法中注入数据范围条件**

**Handler 层（data_handler.rs）— 获取 data_scope 等级并查询部门用户：**

```rust
/// 获取当前用户对指定权限的 data_scope 等级
async fn get_data_scope(
    ctx: &TenantContext,
    permission_code: &str,
    db: &DatabaseConnection,
) -> AppResult<String> {
    #[derive(FromQueryResult)]
    struct ScopeResult { data_scope: Option<String> }

    let result = ScopeResult::find_by_statement(Statement::from_sql_and_values(
        sea_orm::DatabaseBackend::Postgres,
        r#"SELECT rp.data_scope
           FROM user_roles ur
           JOIN role_permissions rp ON rp.role_id = ur.role_id
           JOIN permissions p ON p.id = rp.permission_id
           WHERE ur.user_id = $1 AND ur.tenant_id = $2 AND p.code = $3
           LIMIT 1"#,
        [ctx.user_id.into(), ctx.tenant_id.into(), permission_code.into()],
    )).one(db).await.map_err(|e| AppError::Internal(e.to_string()))?;

    Ok(result.and_then(|r| r.data_scope).unwrap_or("all".to_string()))
}

/// 获取部门成员 ID 列表（含下级部门）
async fn get_dept_members(
    ctx: &TenantContext,
    db: &DatabaseConnection,
    include_sub_depts: bool,
) -> AppResult<Vec<Uuid>> {
    if ctx.department_ids.is_empty() {
        return Ok(vec![]);
    }

    let dept_ids = if include_sub_depts {
        // 递归查询部门树：先获取所有下级部门
        let dept_list = ctx.department_ids.iter()
            .map(|id| id.to_string())
            .collect::<Vec<_>>()
            .join("','");
        #[derive(FromQueryResult)]
        struct DeptId { id: Uuid }
        let sql = format!(
            r#"WITH RECURSIVE dept_tree AS (
                SELECT id FROM departments WHERE id IN ('{}') AND tenant_id = $1
                UNION ALL
                SELECT d.id FROM departments d JOIN dept_tree dt ON d.parent_id = dt.id
            ) SELECT id FROM dept_tree"#,
            dept_list
        );
        let rows = DeptId::find_by_statement(Statement::from_sql_and_values(
            sea_orm::DatabaseBackend::Postgres,
            sql,
            [ctx.tenant_id.into()],
        )).all(db).await?;
        rows.into_iter().map(|r| r.id).collect()
    } else {
        ctx.department_ids.clone()
    };

    // 查询这些部门中的用户 ID（通过 positions 表）
    let dept_list = dept_ids.iter().map(|id| id.to_string())
        .collect::<Vec<_>>()
        .join("','");
    #[derive(FromQueryResult)]
    struct UserId { user_id: Uuid }
    let sql = format!(
        "SELECT DISTINCT user_id FROM positions WHERE dept_id IN ('{}') AND tenant_id = $1",
        dept_list
    );
    let rows = UserId::find_by_statement(Statement::from_sql_and_values(
        sea_orm::DatabaseBackend::Postgres,
        sql,
        [ctx.tenant_id.into()],
    )).all(db).await?;
    Ok(rows.into_iter().map(|r| r.user_id).collect())
}
```

**在 `list_plugin_data` handler 中调用：**

```rust
// 获取 data_scope 等级
let data_scope = get_data_scope(&ctx, &fine_perm, &state.db).await?;

// 获取部门成员（仅 department/department_tree 级别需要）
let dept_members = match data_scope.as_str() {
    "department" => get_dept_members(&ctx, &state.db, false).await?,
    "department_tree" => get_dept_members(&ctx, &state.db, true).await?,
    _ => vec![],
};

// 传入 data_service
let (items, total, next_cursor) = PluginDataService::list_with_scope(
    plugin_id, &entity, ctx.tenant_id, page, page_size,
    &state.db, &state.entity_cache,
    filter, params.search, params.sort_by, params.sort_order, params.cursor,
    &data_scope, &ctx.user_id, &dept_members,
).await?;
```

**data_service.rs 新增 `list_with_scope` 方法：**

在 `build_filtered_query_sql_ex` 的条件列表中追加 data_scope 条件：

```rust
pub async fn list_with_scope(
    /* ... 原有参数 ... */
    data_scope: &str,
    current_user_id: &Uuid,
    dept_members: &[Uuid],
) -> AppResult<(Vec<PluginDataResp>, u64, Option<String>)> {
    let info = Self::resolve_entity_info_cached(...).await?;
    // ... 构建 query（复用 build_filtered_query_sql_ex）...

    // 注入 data_scope 条件
    if data_scope != "all" && info.entity_def.data_scope == Some(true) {
        let scope_condition = DynamicTableManager::build_data_scope_condition_with_params(
            data_scope, current_user_id, "owner_id", dept_members,
            next_param_idx, &info.generated_fields,
        );
        conditions.push(scope_condition.0);
        values.extend(scope_condition.1);
    }

    // ... 执行查询 ...
}
```

> **注意：** 由于 `build_filtered_query_sql_ex` 返回完整 SQL，无法在事后追加条件。
> 实际实现需要将 data_scope 条件作为额外参数传入 `build_filtered_query_sql_ex`，
> 或在 `data_service` 层先调用 `build_filtered_query_sql_ex` 得到条件部分，
> 然后拼接 data_scope 条件后再执行。推荐扩展 `build_filtered_query_sql_ex` 签名，
> 新增 `extra_conditions: Option<(String, Vec<Value>)>` 参数。

- [ ] **Step 2: 编译验证**

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

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

```bash
git add crates/erp-plugin/src/data_service.rs crates/erp-plugin/src/handler/data_handler.rs
git commit -m "feat(plugin): 查询注入行级数据范围条件"
```

---

### Task 3.8: CRM plugin.toml — 添加 data_scope / owner_id

**Files:**
- Modify: `crates/erp-plugin-crm/plugin.toml`

- [ ] **Step 1: customer 实体启用 data_scope**

```toml
[[schema.entities]]
name = "customer"
display_name = "客户"
data_scope = true

# 新增 owner_id 字段
[[schema.entities.fields]]
name = "owner_id"
field_type = "uuid"
display_name = "负责人"
scope_role = "owner"
```

- [ ] **Step 2: 权限声明添加 data_scope_levels**

```toml
[[permissions]]
code = "customer.list"
name = "查看客户"
description = "查看客户列表和详情"
data_scope_levels = ["self", "department", "department_tree", "all"]
```

对 `contact.list`, `communication.list` 等也添加 data_scope_levels。

- [ ] **Step 3: 验证**

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

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

```bash
git add crates/erp-plugin-crm/plugin.toml
git commit -m "feat(crm): customer 实体启用 data_scope + owner_id 字段"
```

---

## Chunk 4: 前端页面能力增强

### Task 4.1: 后端 — PATCH 部分更新端点 + build_patch_sql

**Files:**
- Modify: `crates/erp-plugin/src/dynamic_table.rs` (新增 build_patch_sql)
- Modify: `crates/erp-plugin/src/data_service.rs` (新增 partial_update)
- Modify: `crates/erp-plugin/src/data_dto.rs` (新增 PatchPluginDataReq)
- Modify: `crates/erp-plugin/src/handler/data_handler.rs` (新增 patch_plugin_data handler)
- Modify: `crates/erp-plugin/src/handler/plugin_handler.rs` (注册 PATCH 路由)

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

```rust
#[test]
fn test_build_patch_sql_merges_fields() {
    let (sql, values) = DynamicTableManager::build_patch_sql(
        "plugin_test_customer",
        Uuid::parse_str("00000000-0000-0000-0000-000000000001").unwrap(),
        Uuid::parse_str("00000000-0000-0000-0000-000000000099").unwrap(),
        Uuid::parse_str("00000000-0000-0000-0000-000000000050").unwrap(),
        serde_json::json!({"level": "vip", "status": "active"}),
        3,
    );
    assert!(sql.contains("jsonb_set"), "PATCH 应使用 jsonb_set 合并");
    assert!(sql.contains("version = version + 1"), "PATCH 应更新版本号");
}
```

- [ ] **Step 2: 新增 PatchPluginDataReq**

在 `data_dto.rs` 中添加：

```rust
/// 部分更新请求
#[derive(Debug, Serialize, Deserialize, utoipa::ToSchema)]
pub struct PatchPluginDataReq {
    pub data: serde_json::Value,
    pub version: i32,
}
```

- [ ] **Step 3: 实现 build_patch_sql**

在 `dynamic_table.rs` 中：

```rust
/// 构建 PATCH SQL — 只更新 data 中提供的字段，未提供的保持不变
pub fn build_patch_sql(
    table_name: &str,
    id: Uuid,
    tenant_id: Uuid,
    user_id: Uuid,
    partial_data: serde_json::Value,
    version: i32,
) -> (String, Vec<Value>) {
    // 使用 jsonb_set 逐层合并
    let mut set_expr = "data".to_string();
    if let Some(obj) = partial_data.as_object() {
        for key in obj.keys() {
            set_expr = format!(
                "jsonb_set({}, '{{{}}}', $1::jsonb->'{}', true)",
                set_expr, key, key
            );
        }
    }

    let sql = format!(
        "UPDATE \"{}\" \
         SET data = {}, updated_at = NOW(), updated_by = $2, version = version + 1 \
         WHERE id = $3 AND tenant_id = $4 AND version = $5 AND deleted_at IS NULL \
         RETURNING id, data, created_at, updated_at, version",
        table_name, set_expr
    );
    let values = vec![
        serde_json::to_string(&partial_data).unwrap_or_default().into(),
        user_id.into(),
        id.into(),
        tenant_id.into(),
        version.into(),
    ];
    (sql, values)
}
```

- [ ] **Step 4: data_service.rs 新增 partial_update**

```rust
/// 部分更新（PATCH）
pub async fn partial_update(
    plugin_id: Uuid,
    entity_name: &str,
    id: Uuid,
    tenant_id: Uuid,
    operator_id: Uuid,
    partial_data: serde_json::Value,
    expected_version: i32,
    db: &sea_orm::DatabaseConnection,
    cache: &moka::sync::Cache<String, crate::state::EntityInfo>,
) -> AppResult<PluginDataResp> {
    let info = Self::resolve_entity_info_cached(plugin_id, entity_name, tenant_id, db, cache).await?;

    let (sql, values) = DynamicTableManager::build_patch_sql(
        &info.table_name, id, tenant_id, operator_id, partial_data, expected_version,
    );

    #[derive(FromQueryResult)]
    struct UpdateResult {
        id: Uuid, data: serde_json::Value,
        created_at: chrono::DateTime<chrono::Utc>,
        updated_at: chrono::DateTime<chrono::Utc>,
        version: i32,
    }

    let result = UpdateResult::find_by_statement(Statement::from_sql_and_values(
        sea_orm::DatabaseBackend::Postgres, sql, values,
    )).one(db).await?.ok_or_else(|| AppError::VersionMismatch)?;

    Ok(PluginDataResp {
        id: result.id.to_string(), data: result.data,
        created_at: Some(result.created_at), updated_at: Some(result.updated_at),
        version: Some(result.version),
    })
}
```

- [ ] **Step 5: handler 新增 patch_plugin_data**

```rust
#[utoipa::path(
    patch,
    path = "/api/v1/plugins/{plugin_id}/{entity}/{id}",
    request_body = PatchPluginDataReq,
    responses((status = 200, description = "部分更新成功", body = ApiResponse<PluginDataResp>)),
    security(("bearer_auth" = [])),
    tag = "插件数据"
)]
pub async fn patch_plugin_data<S>(
    State(state): State<PluginState>,
    Extension(ctx): Extension<TenantContext>,
    Path((plugin_id, entity, id)): Path<(Uuid, String, Uuid)>,
    Json(req): Json<PatchPluginDataReq>,
) -> Result<Json<ApiResponse<PluginDataResp>>, AppError>
where
    PluginState: FromRef<S>,
    S: Clone + Send + Sync + 'static,
{
    let manifest_id = resolve_manifest_id(plugin_id, ctx.tenant_id, &state.db).await?;
    let fine_perm = compute_permission_code(&manifest_id, &entity, "update");
    require_permission(&ctx, &fine_perm)?;

    let result = PluginDataService::partial_update(
        plugin_id, &entity, id, ctx.tenant_id, ctx.user_id,
        req.data, req.version, &state.db, &state.entity_cache,
    ).await?;

    Ok(Json(ApiResponse::ok(result)))
}
```

- [ ] **Step 6: 注册路由**

在 `plugin_handler.rs` 的路由定义中，添加 `.patch("/api/v1/plugins/:plugin_id/:entity/:id", patch_plugin_data::<PluginState>)`

> 具体路由注册方式取决于项目使用的 Axum 路由模式。查找现有路由注册位置，按相同模式添加。

- [ ] **Step 7: 编译验证**

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

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

```bash
git add crates/erp-plugin/src/dynamic_table.rs crates/erp-plugin/src/data_service.rs crates/erp-plugin/src/data_dto.rs crates/erp-plugin/src/handler/data_handler.rs crates/erp-plugin/src/handler/plugin_handler.rs
git commit -m "feat(plugin): PATCH 部分更新端点 — jsonb_set 字段合并"
```

---

### Task 4.2: 后端 — 批量操作端点

**Files:**
- Modify: `crates/erp-plugin/src/data_dto.rs` (BatchActionReq)
- Modify: `crates/erp-plugin/src/data_service.rs` (batch 操作)
- Modify: `crates/erp-plugin/src/handler/data_handler.rs` (batch handler)

- [ ] **Step 1: 新增 DTO**

```rust
/// 批量操作请求
#[derive(Debug, Serialize, Deserialize, utoipa::ToSchema)]
pub struct BatchActionReq {
    pub action: String,                      // "batch_delete" 或 "batch_update"
    pub ids: Vec<String>,                    // 记录 ID 列表（上限 100）
    pub data: Option<serde_json::Value>,     // batch_update 时的更新数据
}
```

- [ ] **Step 2: 实现 batch 操作**

在 `data_service.rs` 中：

```rust
/// 批量操作（单个事务）
pub async fn batch(
    plugin_id: Uuid,
    entity_name: &str,
    tenant_id: Uuid,
    operator_id: Uuid,
    req: BatchActionReq,
    db: &sea_orm::DatabaseConnection,
    cache: &moka::sync::Cache<String, crate::state::EntityInfo>,
) -> AppResult<u64> {
    if req.ids.len() > 100 {
        return Err(AppError::Validation("批量操作上限 100 条".to_string()));
    }
    if req.ids.is_empty() {
        return Err(AppError::Validation("ids 不能为空".to_string()));
    }

    let info = Self::resolve_entity_info_cached(plugin_id, entity_name, tenant_id, db, cache).await?;
    let ids: Vec<Uuid> = req.ids.iter()
        .map(|s| Uuid::parse_str(s))
        .collect::<Result<Vec<_>, _>>()
        .map_err(|_| AppError::Validation("ids 中包含无效的 UUID".to_string()))?;

    let affected = match req.action.as_str() {
        "batch_delete" => {
            let placeholders: Vec<String> = ids.iter().enumerate()
                .map(|(i, _)| format!("${}", i + 2))
                .collect();
            let sql = format!(
                "UPDATE \"{}\" SET deleted_at = NOW(), updated_at = NOW() WHERE tenant_id = $1 AND id IN ({}) AND deleted_at IS NULL",
                info.table_name, placeholders.join(", ")
            );
            let mut values = vec![tenant_id.into()];
            for id in &ids { values.push((*id).into()); }
            let result = db.execute(Statement::from_sql_and_values(
                sea_orm::DatabaseBackend::Postgres, sql, values,
            )).await?;
            result.rows_affected()
        }
        "batch_update" => {
            let update_data = req.data.ok_or_else(|| {
                AppError::Validation("batch_update 需要 data 字段".to_string())
            })?;
            // 批量更新使用原始 SQL 绕过乐观锁（管理员操作，可接受）
            // 将 partial_data 中的每个字段通过 jsonb_set 合并到现有 data
            let mut set_expr = "data".to_string();
            if let Some(obj) = update_data.as_object() {
                for key in obj.keys() {
                    set_expr = format!(
                        "jsonb_set({}, '{{{}}}', $1::jsonb->'{}', true)",
                        set_expr, key, key
                    );
                }
            }
            let placeholders: Vec<String> = ids.iter().enumerate()
                .map(|(i, _)| format!("${}", i + 2))
                .collect();
            let sql = format!(
                "UPDATE \"{}\" SET data = {}, updated_at = NOW(), updated_by = $1, version = version + 1 WHERE tenant_id = $1 AND id IN ({}) AND deleted_at IS NULL",
                info.table_name, set_expr, placeholders.join(", ")
            );
            let mut values = vec![operator_id.into()];
            values.push(serde_json::to_string(&update_data).unwrap_or_default().into());
            // 注意：$1 是 operator_id，$2 是 update_data，$3+ 是 ids
            // 需要调整参数索引：
            // $1 = update_data, $2 = operator_id, $3+ = ids
            let placeholders: Vec<String> = ids.iter().enumerate()
                .map(|(i, _)| format!("${}", i + 3))
                .collect();
            let sql = format!(
                "UPDATE \"{}\" SET data = {}, updated_at = NOW(), updated_by = $2, version = version + 1 WHERE tenant_id = $1 AND id IN ({}) AND deleted_at IS NULL",
                info.table_name, set_expr, placeholders.join(", ")
            );
            let mut values = vec![tenant_id.into(), operator_id.into()];
            values.push(serde_json::to_string(&update_data).unwrap_or_default().into());
            for id in &ids { values.push((*id).into()); }
            let result = db.execute(Statement::from_sql_and_values(
                sea_orm::DatabaseBackend::Postgres, sql, values,
            )).await?;
            result.rows_affected()
        }
        _ => return Err(AppError::Validation(format!("不支持的批量操作: {}", req.action))),
    };

    Ok(affected)
}
```

- [ ] **Step 3: handler 注册**

```rust
#[utoipa::path(
    post,
    path = "/api/v1/plugins/{plugin_id}/{entity}/batch",
    request_body = BatchActionReq,
    responses((status = 200, description = "批量操作成功", body = ApiResponse<u64>)),
    security(("bearer_auth" = [])),
    tag = "插件数据"
)]
pub async fn batch_plugin_data<S>(...) -> Result<Json<ApiResponse<u64>>, AppError> {
    // 权限检查 + 调用 PluginDataService::batch
}
```

- [ ] **Step 4: 编译验证 + 提交**

```bash
git add crates/erp-plugin/src/
git commit -m "feat(plugin): 批量操作端点 — batch_delete + batch_update"
```

---

### Task 4.3: 后端 — timeseries 聚合 API

**Files:**
- Modify: `crates/erp-plugin/src/data_dto.rs` (TimeseriesParams)
- Modify: `crates/erp-plugin/src/dynamic_table.rs` (build_timeseries_sql)
- Modify: `crates/erp-plugin/src/data_service.rs` (timeseries 方法)
- Modify: `crates/erp-plugin/src/handler/data_handler.rs` (timeseries handler)

- [ ] **Step 1: 新增 DTO + SQL 构建 + service + handler**

```rust
// data_dto.rs
#[derive(Debug, Serialize, Deserialize, utoipa::IntoParams)]
pub struct TimeseriesParams {
    pub time_field: String,     // 时间字段名
    pub time_grain: String,     // "day" / "week" / "month"
    pub start: Option<String>,  // ISO 日期
    pub end: Option<String>,    // ISO 日期
}

// dynamic_table.rs
pub fn build_timeseries_sql(
    table_name: &str,
    tenant_id: Uuid,
    time_field: &str,
    time_grain: &str,
    start: Option<&str>,
    end: Option<&str>,
) -> Result<(String, Vec<Value>), String> {
    let clean_field = sanitize_identifier(time_field);
    let grain = match time_grain {
        "day" => "day",
        "week" => "week",
        "month" => "month",
        _ => return Err(format!("不支持的 time_grain: {}", time_grain)),
    };

    let mut conditions = vec![
        format!("\"tenant_id\" = $1"),
        "\"deleted_at\" IS NULL".to_string(),
    ];
    let mut values: Vec<Value> = vec![tenant_id.into()];
    let mut param_idx = 2;

    if let Some(s) = start {
        conditions.push(format!("(data->>'{}')::timestamp >= ${}", clean_field, param_idx));
        values.push(Value::String(Some(Box::new(s.to_string()))));
        param_idx += 1;
    }
    if let Some(e) = end {
        conditions.push(format!("(data->>'{}')::timestamp < ${}", clean_field, param_idx));
        values.push(Value::String(Some(Box::new(e.to_string()))));
        param_idx += 1;
    }

    let sql = format!(
        "SELECT to_char(date_trunc('{}', (data->>'{}')::timestamp), 'YYYY-MM-DD') as period, COUNT(*) as count \
         FROM \"{}\" WHERE {} \
         GROUP BY date_trunc('{}', (data->>'{}')::timestamp) \
         ORDER BY period",
        grain, clean_field, table_name, conditions.join(" AND "), grain, clean_field,
    );

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

- [ ] **Step 2: 编译验证 + 提交**

```bash
git add crates/erp-plugin/src/
git commit -m "feat(plugin): timeseries 聚合 API — date_trunc 时间序列"
```

---

### Task 4.4: 前端 — API 层扩展

**Files:**
- Modify: `apps/web/src/api/plugins.ts` (Schema 类型扩展)
- Modify: `apps/web/src/api/pluginData.ts` (新增 batch/timeseries/cursor API)

- [ ] **Step 1: plugins.ts 类型扩展**

```typescript
// PluginFieldSchema 扩展
export interface PluginFieldSchema {
  // ... 已有字段 ...
  ref_entity?: string;
  ref_label_field?: string;
  ref_search_fields?: string[];
  cascade_from?: string;
  cascade_filter?: string;
}

// PluginPageType 新增 Kanban
// 在 tagged union 中添加：
| {
    type: 'kanban';
    entity: string;
    label: string;
    icon?: string;
    lane_field: string;
    lane_order?: string[];
    card_title_field: string;
    card_subtitle_field?: string;
    card_fields?: string[];
    enable_drag?: boolean;
  }

// Dashboard widgets
export interface DashboardWidget {
  type: 'stat_card' | 'bar_chart' | 'pie_chart' | 'funnel_chart' | 'line_chart';
  entity: string;
  title: string;
  icon?: string;
  color?: string;
  dimension_field?: string;
  dimension_order?: string[];
  metric?: string;
}
```

- [ ] **Step 2: pluginData.ts API 扩展**

```typescript
// 批量操作
export async function batchPluginData(
  pluginId: string, entity: string, req: { action: string; ids: string[]; data?: any }
) {
  const { data } = await api.post(`/api/v1/plugins/${pluginId}/${entity}/batch`, req);
  return data;
}

// 部分更新
export async function patchPluginData(
  pluginId: string, entity: string, id: string, req: { data: any; version: number }
) {
  const { data } = await api.patch(`/api/v1/plugins/${pluginId}/${entity}/${id}`, req);
  return data;
}

// 时间序列
export async function getPluginTimeseries(
  pluginId: string, entity: string, params: {
    time_field: string; time_grain: string; start?: string; end?: string;
  }
) {
  const { data } = await api.get(`/api/v1/plugins/${pluginId}/${entity}/timeseries`, { params });
  return data;
}
```

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

```bash
git add apps/web/src/api/plugins.ts apps/web/src/api/pluginData.ts
git commit -m "feat(web): API 层扩展 — batch/patch/timeseries/kanban 类型"
```

---

### Task 4.5: 前端 — EntitySelect 关联选择器组件

**Files:**
- Create: `apps/web/src/components/EntitySelect.tsx`

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

```tsx
// apps/web/src/components/EntitySelect.tsx
import { Select, Spin } from 'antd';
import { useState, useEffect, useCallback } from 'react';
import { listPluginData } from '../api/pluginData';

interface EntitySelectProps {
  pluginId: string;
  entity: string;
  labelField: string;
  searchFields?: string[];
  value?: string;
  onChange?: (value: string, label: string) => void;
  cascadeFrom?: string;       // 级联过滤来源字段
  cascadeFilter?: string;     // 级联过滤目标字段
  cascadeValue?: string;      // 来源字段的当前值
  placeholder?: string;
}

export default function EntitySelect({
  pluginId, entity, labelField, searchFields,
  value, onChange, cascadeFrom, cascadeFilter, cascadeValue,
  placeholder,
}: EntitySelectProps) {
  const [options, setOptions] = useState<{value: string; label: string}[]>([]);
  const [loading, setLoading] = useState(false);
  const [search, setSearch] = useState('');

  const fetchData = useCallback(async (keyword?: string) => {
    setLoading(true);
    try {
      let filter: Record<string, string> | undefined;
      if (cascadeFrom && cascadeFilter && cascadeValue) {
        filter = { [cascadeFilter]: cascadeValue };
      }
      const res = await listPluginData(pluginId, entity, {
        page: 1, page_size: 20,
        search: keyword,
        filter: filter ? JSON.stringify(filter) : undefined,
      });
      const items = (res.data?.data || []).map((item: any) => ({
        value: item.id,
        label: item.data?.[labelField] || item.id,
      }));
      setOptions(items);
    } finally {
      setLoading(false);
    }
  }, [pluginId, entity, labelField, cascadeFrom, cascadeFilter, cascadeValue]);

  useEffect(() => { fetchData(); }, [fetchData]);

  return (
    <Select
      showSearch
      value={value}
      placeholder={placeholder || '请选择'}
      loading={loading}
      options={options}
      onSearch={(v) => { setSearch(v); fetchData(v); }}
      onChange={(v) => {
        const opt = options.find(o => o.value === v);
        onChange?.(v, opt?.label || '');
      }}
      filterOption={false}
      notFoundContent={loading ? <Spin size="small" /> : '无数据'}
      allowClear
    />
  );
}
```

- [ ] **Step 2: 集成到 PluginCRUDPage 的表单渲染**

在 `PluginCRUDPage.tsx` 的表单字段渲染中，当 `ui_widget === 'entity_select'` 时渲染 `EntitySelect`：

```tsx
case 'entity_select':
  return (
    <EntitySelect
      pluginId={pluginId}
      entity={field.ref_entity!}
      labelField={field.ref_label_field || 'name'}
      searchFields={field.ref_search_fields}
      value={formValues[field.name]}
      onChange={(v) => form.setFieldValue(field.name, v)}
      cascadeFrom={field.cascade_from}
      cascadeFilter={field.cascade_filter}
      cascadeValue={field.cascade_from ? formValues[field.cascade_from] : undefined}
      placeholder={field.display_name}
    />
  );
```

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

```bash
git add apps/web/src/components/EntitySelect.tsx apps/web/src/pages/PluginCRUDPage.tsx
git commit -m "feat(web): EntitySelect 关联选择器 — 远程搜索 + 级联过滤"
```

---

### Task 4.6: 前端 — visible_when 表达式增强

**Files:**
- Create: `apps/web/src/utils/exprEvaluator.ts`
- Modify: `apps/web/src/pages/PluginCRUDPage.tsx` (替换 visible_when 解析)

- [ ] **Step 1: 实现表达式解析器**

```typescript
// apps/web/src/utils/exprEvaluator.ts

interface ExprNode {
  type: 'eq' | 'and' | 'or' | 'not';
  field?: string;
  value?: string;
  left?: ExprNode;
  right?: ExprNode;
  operand?: ExprNode;
}

function parseAtom(tokens: string[]): ExprNode | null {
  const token = tokens.shift();
  if (!token) return null;
  if (token === '(') {
    const expr = parseOr(tokens);
    if (tokens[0] === ')') tokens.shift();
    return expr;
  }
  if (token === 'NOT') {
    const operand = parseAtom(tokens);
    return { type: 'not', operand: operand || undefined };
  }
  // field == 'value'
  const field = token;
  const op = tokens.shift();
  if (op !== '==' && op !== '!=') return null;
  const value = tokens.shift()?.replace(/^'(.*)'$/, '$1') || '';
  return { type: 'eq', field, value };
}

function parseAnd(tokens: string[]): ExprNode | null {
  let left = parseAtom(tokens);
  while (tokens[0] === 'AND') {
    tokens.shift();
    const right = parseAtom(tokens);
    if (left && right) left = { type: 'and', left, right };
  }
  return left;
}

function parseOr(tokens: string[]): ExprNode | null {
  let left = parseAnd(tokens);
  while (tokens[0] === 'OR') {
    tokens.shift();
    const right = parseAnd(tokens);
    if (left && right) left = { type: 'or', left, right };
  }
  return left;
}

function tokenize(input: string): string[] {
  const tokens: string[] = [];
  let i = 0;
  while (i < input.length) {
    if (input[i] === ' ') { i++; continue; }
    if (input[i] === '(' || input[i] === ')') { tokens.push(input[i]); i++; continue; }
    if (input[i] === "'") {
      let j = i + 1;
      while (j < input.length && input[j] !== "'") j++;
      tokens.push(input.substring(i, j + 1));
      i = j + 1;
      continue;
    }
    if (input[i] === '=' && input[i + 1] === '=') { tokens.push('=='); i += 2; continue; }
    if (input[i] === '!' && input[i + 1] === '=') { tokens.push('!='); i += 2; continue; }
    let j = i;
    while (j < input.length && !' ()\'='.includes(input[j]) &&
           !(input[j] === '=' && input[j + 1] === '=') &&
               !(input[j] === '!' && input[j + 1] === '=')) j++;
    tokens.push(input.substring(i, j));
    i = j;
  }
  return tokens;
}

export function parseExpr(input: string): ExprNode | null {
  const tokens = tokenize(input);
  return parseOr(tokens);
}

export function evaluateExpr(node: ExprNode, values: Record<string, unknown>): boolean {
  switch (node.type) {
    case 'eq':
      return String(values[node.field!] ?? '') === node.value;
    case 'and':
      return evaluateExpr(node.left!, values) && evaluateExpr(node.right!, values);
    case 'or':
      return evaluateExpr(node.left!, values) || evaluateExpr(node.right!, values);
    case 'not':
      return !evaluateExpr(node.operand!, values);
    default:
      return false;
  }
}

export function evaluateVisibleWhen(expr: string | undefined, values: Record<string, unknown>): boolean {
  if (!expr) return true;
  const ast = parseExpr(expr);
  return ast ? evaluateExpr(ast, values) : true;
}
```

- [ ] **Step 2: 替换 PluginCRUDPage 中的 visible_when 解析**

将现有正则 `/^(\w+)\s*==\s*'([^']*)'$/` 替换为 `evaluateVisibleWhen(field.visible_when, formValues)`。

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

```bash
git add apps/web/src/utils/exprEvaluator.ts apps/web/src/pages/PluginCRUDPage.tsx
git commit -m "feat(web): visible_when 增强 — 支持 AND/OR/NOT/括号 表达式"
```

---

### Task 4.7: 前端 — PluginKanbanPage 看板页面

**Files:**
- Create: `apps/web/src/pages/PluginKanbanPage.tsx`
- Modify: `apps/web/src/App.tsx` (路由注册)

- [ ] **Step 1: 安装 dnd-kit**

Run: `cd apps/web && pnpm add @dnd-kit/core @dnd-kit/sortable`

- [ ] **Step 2: 实现 Kanban 组件**

```tsx
// apps/web/src/pages/PluginKanbanPage.tsx
import { useState, useEffect } from 'react';
import { Card, Spin, Typography, Tag, message } from 'antd';
import { DndContext, DragEndEvent, DragOverlay } from '@dnd-kit/core';
import { listPluginData, patchPluginData, countPluginData } from '../api/pluginData';

interface KanbanPageProps {
  pluginId: string;
  page: any; // PluginPageType.Kanban
}

export default function PluginKanbanPage({ pluginId, page }: KanbanPageProps) {
  const { entity, lane_field, lane_order = [], card_title_field, card_subtitle_field, card_fields, enable_drag } = page;
  const [lanes, setLanes] = useState<Record<string, any[]>>({});
  const [loading, setLoading] = useState(true);

  const fetchData = async () => {
    setLoading(true);
    try {
      const allData: Record<string, any[]> = {};
      for (const lane of lane_order) {
        const res = await listPluginData(pluginId, entity, {
          page: 1, page_size: 100,
          filter: JSON.stringify({ [lane_field]: lane }),
        });
        allData[lane] = res.data?.data || [];
      }
      setLanes(allData);
    } finally {
      setLoading(false);
    }
  };

  useEffect(() => { fetchData(); }, [pluginId, entity]);

  const handleDragEnd = async (event: DragEndEvent) => {
    if (!enable_drag) return;
    const { active, over } = event;
    if (!over) return;

    const recordId = active.id as string;
    const newLane = over.data.current?.lane as string;
    if (!newLane) return;

    try {
      await patchPluginData(pluginId, entity, recordId, {
        data: { [lane_field]: newLane }, version: 0,
      });
      message.success('移动成功');
      fetchData();
    } catch {
      message.error('移动失败');
    }
  };

  if (loading) return <Spin />;

  return (
    <DndContext onDragEnd={handleDragEnd}>
      <div style={{ display: 'flex', gap: 16, overflowX: 'auto', padding: 16 }}>
        {lane_order.map(lane => (
          <div key={lane} style={{ minWidth: 280, flex: 1 }}>
            <Typography.Title level={5} style={{ marginBottom: 8 }}>
              {lane} <Tag>{lanes[lane]?.length || 0}</Tag>
            </Typography.Title>
            <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
              {(lanes[lane] || []).map(item => (
                <Card key={item.id} size="small" id={item.id}
                  data-lane={lane} style={{ cursor: enable_drag ? 'grab' : 'default' }}>
                  <Typography.Text strong>{item.data?.[card_title_field]}</Typography.Text>
                  {card_subtitle_field && (
                    <div><Typography.Text type="secondary">{item.data?.[card_subtitle_field]}</Typography.Text></div>
                  )}
                  {card_fields?.map(f => (
                    item.data?.[f] ? <Tag key={f}>{item.data[f]}</Tag> : null
                  ))}
                </Card>
              ))}
            </div>
          </div>
        ))}
      </div>
    </DndContext>
  );
}
```

- [ ] **Step 3: App.tsx 路由注册**

在插件路由中添加 kanban 页面类型的匹配：

```tsx
case 'kanban':
  return <PluginKanbanPage pluginId={pluginId} page={pageConfig} />;
```

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

```bash
git add apps/web/src/pages/PluginKanbanPage.tsx apps/web/src/App.tsx apps/web/package.json
git commit -m "feat(web): Kanban 看板页面 — dnd-kit 拖拽 + 跨列移动"
```

---

### Task 4.8: 前端 — CRUD 批量操作

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

- [ ] **Step 1: 添加 rowSelection 和批量操作栏**

在 CRUD 页面的 Table 组件中添加：

```tsx
const [selectedRowKeys, setSelectedRowKeys] = useState<string[]>([]);

// Table rowSelection
<Table
  rowSelection={{
    selectedRowKeys,
    onChange: (keys) => setSelectedRowKeys(keys as string[]),
  }}
  // ... 已有 props
/>

// 批量操作栏
{selectedRowKeys.length > 0 && (
  <div style={{ padding: '12px 0', display: 'flex', gap: 8, alignItems: 'center' }}>
    <span>已选择 {selectedRowKeys.length} 项</span>
    <Button danger onClick={() => handleBatchDelete(selectedRowKeys)}>批量删除</Button>
    {/* 根据 page.batch_actions 渲染更多按钮 */}
  </div>
)}
```

- [ ] **Step 2: 实现批量操作函数**

```tsx
const handleBatchDelete = async (ids: string[]) => {
  await batchPluginData(pluginId, entity, { action: 'batch_delete', ids });
  message.success('批量删除成功');
  setSelectedRowKeys([]);
  fetchData();
};
```

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

```bash
git add apps/web/src/pages/PluginCRUDPage.tsx
git commit -m "feat(web): CRUD 页面批量操作 — 多选 + 批量删除"
```

---

### Task 4.9: 前端 — Dashboard 图表增强

**Files:**
- Modify: `apps/web/src/pages/PluginDashboardPage.tsx`
- 新增依赖: `@ant-design/charts`

- [ ] **Step 1: 安装图表库**

Run: `cd apps/web && pnpm add @ant-design/charts`

- [ ] **Step 2: Dashboard 渲染 widgets**

在 `PluginDashboardPage.tsx` 中，根据 widgets 声明渲染不同类型的图表：

```tsx
import { Column, Pie, Funnel, Line } from '@ant-design/charts';

// 根据 widget.type 渲染
const renderWidget = (widget: DashboardWidget) => {
  switch (widget.type) {
    case 'stat_card':
      return <StatCardWidget key={widget.title} widget={widget} />;
    case 'bar_chart':
      return <BarChartWidget key={widget.title} widget={widget} />;
    case 'pie_chart':
      return <PieChartWidget key={widget.title} widget={widget} />;
    case 'funnel_chart':
      return <FunnelChartWidget key={widget.title} widget={widget} />;
    case 'line_chart':
      return <LineChartWidget key={widget.title} widget={widget} />;
  }
};
```

每个 widget 子组件从 `aggregatePluginData` API 获取数据并渲染对应图表。

- [ ] **Step 3: 并行数据加载**

将现有的串行聚合查询改为 `Promise.all` 并行加载：

```tsx
const [counts, aggregates] = await Promise.all([
  Promise.all(entities.map(e => countPluginData(pluginId, e))),
  Promise.all(widgets.map(w => aggregatePluginData(pluginId, w.entity, w.dimension_field!))),
]);
```

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

```bash
git add apps/web/src/pages/PluginDashboardPage.tsx apps/web/package.json
git commit -m "feat(web): Dashboard 图表增强 — bar/pie/funnel/line + 并行加载"
```

---

### Task 4.10: 前端 — 文件拆分重构

**Files:**
- Split: `apps/web/src/pages/PluginGraphPage.tsx` → `graphRenderer.ts` + `graphLayout.ts` + `graphInteraction.ts`
- Split: `apps/web/src/pages/PluginCRUDPage.tsx` → `CrudTable.tsx` + `CrudForm.tsx` + `CrudDetail.tsx`
- Split: `apps/web/src/pages/PluginDashboardPage.tsx` → `DashboardWidgets.tsx` + `dashboardTypes.ts`

- [ ] **Step 1: PluginGraphPage 拆分**

将 1081 行拆分为：
- `graphRenderer.ts` (~300 行) — Canvas 绘制逻辑
- `graphLayout.ts` (~200 行) — 力导向布局算法
- `graphInteraction.ts` (~300 行) — 拖拽/缩放/点击交互
- `PluginGraphPage.tsx` (~200 行) — 组件壳，组装以上模块

- [ ] **Step 2: PluginCRUDPage 拆分**

将 617 行拆分为：
- `CrudTable.tsx` (~250 行) — 表格展示 + 批量操作
- `CrudForm.tsx` (~200 行) — 创建/编辑表单 + EntitySelect
- `CrudDetail.tsx` (~150 行) — 详情 Drawer
- `PluginCRUDPage.tsx` (~100 行) — 页面壳，组装子组件

- [ ] **Step 3: PluginDashboardPage 拆分**

将 647 行拆分为：
- `dashboardTypes.ts` (~50 行) — 类型定义
- `DashboardWidgets.tsx` (~300 行) — 各类型 widget 组件
- `PluginDashboardPage.tsx` (~150 行) — 页面布局 + 数据加载

- [ ] **Step 4: 验证无回归**

Run: `pnpm dev` 并手动验证每个页面功能不变。

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

```bash
git add apps/web/src/pages/ apps/web/src/utils/
git commit -m "refactor(web): 拆分大文件 — Graph/CRUD/Dashboard 每个文件 < 400 行"
```

---

### Task 4.11: CRM plugin.toml — 前端页面声明扩展

**Files:**
- Modify: `crates/erp-plugin-crm/plugin.toml`

- [ ] **Step 1: contact/customer_id 添加 entity_select**

```toml
[[schema.entities.fields]]
name = "customer_id"
field_type = "uuid"
required = true
display_name = "所属客户"
ui_widget = "entity_select"
ref_entity = "customer"
ref_label_field = "name"
ref_search_fields = ["name", "code"]
```

- [ ] **Step 2: communication/contact_id 添加级联 entity_select**

```toml
[[schema.entities.fields]]
name = "contact_id"
field_type = "uuid"
display_name = "关联联系人"
ui_widget = "entity_select"
ref_entity = "contact"
ref_label_field = "name"
ref_search_fields = ["name"]
cascade_from = "customer_id"
cascade_filter = "customer_id"
```

- [ ] **Step 3: 添加 Kanban 页面**

```toml
[[ui.pages]]
type = "kanban"
entity = "customer"
label = "销售漏斗"
icon = "swap"
lane_field = "level"
lane_order = ["potential", "normal", "vip", "svip"]
card_title_field = "name"
card_subtitle_field = "code"
card_fields = ["region", "status"]
enable_drag = true
```

- [ ] **Step 4: 验证**

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

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

```bash
git add crates/erp-plugin-crm/plugin.toml
git commit -m "feat(crm): entity_select + kanban + 级联过滤声明"
```

---

### Task 4.12: 集成验证

- [ ] **Step 1: 后端全量编译 + 测试**

Run: `cargo check --workspace && cargo test --workspace`
Expected: 全部通过

- [ ] **Step 2: 前端编译**

Run: `cd apps/web && pnpm build`
Expected: 构建成功

- [ ] **Step 3: 启动服务 + 手动验证**

Run: `cargo run -p erp-server`
- 卸载 CRM 插件 → 重新安装 → 验证动态表包含 Generated Column
- 创建客户 → 验证 ref_entity 校验
- 删除客户 → 验证级联删除
- 验证 Kanban 页面渲染
- 验证 EntitySelect 组件工作正常

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

```bash
git add -A
git commit -m "chore: CRM 插件基座升级 — 集成验证通过"
```