dwf-platform-cli 0.2.0__py3-none-any.whl

dwf_cli/mcp/server.py

@@ -0,0 +1,411 @@
+"""DWF MCP Server — exposes DWF platform operations as MCP tools."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+from dwf_cli.api.client import APIClient
+from dwf_cli.core.config import Config
+from dwf_cli.core.errors import DWFError
+
+mcp = FastMCP(
+    "dwf",
+    instructions=(
+        "DWF platform tools for managing data models, objects, "
+        "function models, and form models. "
+        "Run dwf_auth_status first to check connection."
+    ),
+)
+
+
+def _get_client() -> APIClient:
+    """Build an APIClient from saved config."""
+    cfg = Config()
+    if not cfg.server:
+        raise ValueError(
+            "DWF server not configured. Run: dwf-cli config set server <url>"
+        )
+    if not cfg.token:
+        raise ValueError("Not authenticated. Run: dwf-cli auth login --username <user>")
+    return APIClient(cfg.server, cfg.token)
+
+
+def _get_app_client() -> APIClient | None:
+    """Build an app-server APIClient if configured differently."""
+    cfg = Config()
+    app_url = cfg.app_server
+    if app_url and app_url != cfg.server and cfg.token:
+        return APIClient(app_url, cfg.token)
+    return None
+
+
+def _fmt(result: Any) -> str:
+    """Format API result as JSON string."""
+    if result is None:
+        return json.dumps({"success": True})
+    if isinstance(result, (dict, list)):
+        return json.dumps(result, ensure_ascii=False, default=str)
+    return str(result)
+
+
+def _safe_call(fn, *args, **kwargs) -> str:
+    """Call an API function and return formatted result or error."""
+    try:
+        result = fn(*args, **kwargs)
+        return _fmt(result)
+    except DWFError as e:
+        return json.dumps({"error": str(e), "suggestion": e.suggestion})
+    except ValueError as e:
+        return json.dumps({"error": str(e)})
+
+
+# ── Auth & Config ─────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def dwf_auth_status() -> str:
+    """Check current DWF authentication status and server configuration."""
+    try:
+        cfg = Config()
+    except DWFError as e:
+        return json.dumps({"error": str(e)})
+    return json.dumps(
+        {
+            "server": cfg.server,
+            "app_server": cfg.app_server,
+            "authenticated": cfg.token is not None,
+        }
+    )
+
+
+@mcp.tool()
+def dwf_config_list() -> str:
+    """List all DWF CLI configuration values."""
+    try:
+        cfg = Config()
+        return json.dumps(cfg.list_all(), ensure_ascii=False)
+    except DWFError as e:
+        return json.dumps({"error": str(e)})
+
+
+# ── Data Model ────────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def dwf_datamodel_list(
+    model_type: str = "entity",
+    page: int = 0,
+    page_size: int = 25,
+    search: str | None = None,
+) -> str:
+    """List data models (entity/relation/external).
+
+    Args:
+        model_type: One of 'entity', 'relation', 'external'
+        page: Page index (0-based)
+        page_size: Items per page
+        search: Fuzzy search keyword
+    """
+    from dwf_cli.api.datamodel import ModelType, list_models
+
+    client = _get_client()
+    mt = ModelType(model_type)
+    return _safe_call(
+        list_models, client, mt, page=page, page_size=page_size, search=search
+    )
+
+
+@mcp.tool()
+def dwf_datamodel_show(class_name: str) -> str:
+    """Show details of a data model including its attributes.
+
+    Args:
+        class_name: The class name of the data model
+    """
+    from dwf_cli.api.datamodel import get_attributes, get_class
+
+    client = _get_client()
+    try:
+        cls_info = get_class(client, class_name)
+        attrs = get_attributes(client, class_name)
+        return json.dumps(
+            {"class": cls_info, "attributes": attrs}, ensure_ascii=False, default=str
+        )
+    except DWFError as e:
+        return json.dumps({"error": str(e), "suggestion": e.suggestion})
+
+
+@mcp.tool()
+def dwf_datamodel_create(
+    class_name: str,
+    display_name: str = "",
+    zone_name: str = "",
+) -> str:
+    """Create a new entity data model.
+
+    Args:
+        class_name: Unique class name (English, no spaces)
+        display_name: Human-readable display name
+        zone_name: Zone/category name
+    """
+    from dwf_cli.api.datamodel import create_entity
+
+    client = _get_client()
+    data = [{"className": class_name, "displayName": display_name or class_name}]
+    if zone_name:
+        data[0]["zoneName"] = zone_name
+    return _safe_call(create_entity, client, data)
+
+
+@mcp.tool()
+def dwf_datamodel_delete(class_name: str, cascade: bool = False) -> str:
+    """Delete a data model.
+
+    Args:
+        class_name: The class name to delete
+        cascade: Whether to cascade delete related data
+    """
+    from dwf_cli.api.datamodel import delete_class
+
+    client = _get_client()
+    return _safe_call(delete_class, client, class_name, cascade=cascade)
+
+
+# ── Attributes ────────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def dwf_attribute_list(keyword: str | None = None) -> str:
+    """List global attributes, optionally filtered by keyword.
+
+    Args:
+        keyword: Filter keyword
+    """
+    from dwf_cli.api.datamodel import list_attributes
+
+    client = _get_client()
+    return _safe_call(list_attributes, client, keyword=keyword)
+
+
+@mcp.tool()
+def dwf_attribute_create(
+    name: str,
+    display_name: str = "",
+    value_type: str = "String",
+) -> str:
+    """Create a new attribute.
+
+    Args:
+        name: Attribute name (English)
+        display_name: Human-readable name
+        value_type: Data type (String, Integer, Float, Boolean, DateTime, etc.)
+    """
+    from dwf_cli.api.datamodel import create_attributes
+
+    client = _get_client()
+    data = [
+        {"name": name, "displayName": display_name or name, "valueType": value_type}
+    ]
+    return _safe_call(create_attributes, client, data)
+
+
+@mcp.tool()
+def dwf_attribute_bind(
+    class_name: str,
+    attribute_name: str,
+    is_relation: bool = False,
+) -> str:
+    """Bind an existing attribute to a data model.
+
+    Args:
+        class_name: Target class name
+        attribute_name: Attribute name to bind
+        is_relation: Whether the target is a relation model
+    """
+    from dwf_cli.api.datamodel import bind_attributes
+
+    client = _get_client()
+    data = [{"name": attribute_name}]
+    return _safe_call(
+        bind_attributes, client, class_name, data, is_relation=is_relation
+    )
+
+
+# ── Objects ───────────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def dwf_object_list(
+    class_name: str,
+    page: int = 0,
+    page_size: int = 25,
+    condition: str | None = None,
+) -> str:
+    """List objects of a data model.
+
+    Args:
+        class_name: The class name
+        page: Page index (0-based)
+        page_size: Items per page
+        condition: DWF query condition string
+    """
+    from dwf_cli.api.datamodel import list_objects
+
+    client = _get_client()
+    return _safe_call(
+        list_objects,
+        client,
+        class_name,
+        page=page,
+        page_size=page_size,
+        condition=condition,
+    )
+
+
+@mcp.tool()
+def dwf_object_get(class_name: str, oid: str) -> str:
+    """Get a single object by OID.
+
+    Args:
+        class_name: The class name
+        oid: Object ID
+    """
+    from dwf_cli.api.datamodel import get_object
+
+    client = _get_client()
+    return _safe_call(get_object, client, class_name, oid)
+
+
+@mcp.tool()
+def dwf_object_create(class_name: str, data_json: str) -> str:
+    """Create one or more objects.
+
+    Args:
+        class_name: The class name
+        data_json: JSON string of object(s) to create. Single dict or list of dicts.
+    """
+    from dwf_cli.api.datamodel import create_objects
+
+    client = _get_client()
+    parsed = json.loads(data_json)
+    if isinstance(parsed, dict):
+        parsed = [parsed]
+    return _safe_call(create_objects, client, class_name, parsed)
+
+
+@mcp.tool()
+def dwf_object_update(class_name: str, data_json: str) -> str:
+    """Update one or more objects.
+
+    Args:
+        class_name: The class name
+        data_json: JSON string of object(s) with oid field. Single dict or list of dicts.
+    """
+    from dwf_cli.api.datamodel import update_objects
+
+    client = _get_client()
+    parsed = json.loads(data_json)
+    if isinstance(parsed, dict):
+        parsed = [parsed]
+    return _safe_call(update_objects, client, class_name, parsed)
+
+
+@mcp.tool()
+def dwf_object_delete(class_name: str, oids_json: str) -> str:
+    """Delete objects by OID list.
+
+    Args:
+        class_name: The class name
+        oids_json: JSON array of OID strings, e.g. '["oid1","oid2"]'
+    """
+    from dwf_cli.api.datamodel import delete_objects
+
+    client = _get_client()
+    oids = json.loads(oids_json)
+    return _safe_call(delete_objects, client, class_name, oids)
+
+
+@mcp.tool()
+def dwf_object_count(class_name: str, condition: str | None = None) -> str:
+    """Count objects in a data model.
+
+    Args:
+        class_name: The class name
+        condition: Optional DWF query condition
+    """
+    from dwf_cli.api.datamodel import count_objects
+
+    client = _get_client()
+    return _safe_call(count_objects, client, class_name, condition=condition)
+
+
+# ── Function Model ────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def dwf_funcmodel_app_list() -> str:
+    """List all applications in the function model."""
+    from dwf_cli.api.funcmodel import list_apps
+
+    client = _get_client()
+    app_client = _get_app_client()
+    return _safe_call(list_apps, app_client or client)
+
+
+@mcp.tool()
+def dwf_funcmodel_operation_list(
+    operation_type: str = "global",
+    page: int = 0,
+    page_size: int = 25,
+    search: str | None = None,
+) -> str:
+    """List function operations.
+
+    Args:
+        operation_type: One of 'global', 'entity', 'relation'
+        page: Page index (0-based)
+        page_size: Items per page
+        search: Fuzzy search keyword
+    """
+    from dwf_cli.api.funcmodel import list_operations
+
+    client = _get_client()
+    return _safe_call(
+        list_operations,
+        client,
+        operation_type,
+        page=page,
+        page_size=page_size,
+        fuzzy_search=search,
+    )
+
+
+# ── Form Model ────────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def dwf_formmodel_view_list(class_name: str) -> str:
+    """List form views for a data model.
+
+    Args:
+        class_name: The class name
+    """
+    from dwf_cli.api.formmodel import list_views
+
+    client = _get_client()
+    return _safe_call(list_views, client, class_name)
+
+
+# ── Entry point ───────────────────────────────────────────────────────
+
+
+def main() -> None:
+    """Run the MCP server (stdio transport)."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

dwf_cli/schemas/__init__.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+_SCHEMAS_DIR = Path(__file__).parent
+_REGISTRY: dict[str, dict] = {}
+
+
+def _load_all() -> None:
+    if _REGISTRY:
+        return
+    for group_dir in sorted(_SCHEMAS_DIR.iterdir()):
+        if not group_dir.is_dir() or group_dir.name.startswith("_"):
+            continue
+        for schema_file in sorted(group_dir.glob("*.schema.json")):
+            name = schema_file.name.removesuffix(".schema.json")
+            cmd_parts = [group_dir.name]
+            cmd_parts.extend(name.split("_"))
+            key = " ".join(cmd_parts)
+            with open(schema_file, encoding="utf-8") as f:
+                _REGISTRY[key] = json.load(f)
+
+
+def lookup(command_path: str) -> dict | None:
+    _load_all()
+    return _REGISTRY.get(command_path)
+
+
+def all_schemas() -> dict[str, dict]:
+    _load_all()
+    return dict(_REGISTRY)
+
+
+def all_commands() -> list[str]:
+    _load_all()
+    return sorted(_REGISTRY.keys())

dwf_cli/schemas/datamodel/attribute_bind.schema.json

@@ -0,0 +1,21 @@
+{
+  "description": "批量绑定属性库的属性到类（实体类/关联类）。只允许修改 displayName、defaultValue、note",
+  "api": "POST /dwf/v1/meta/entities/{name}/attributes-bind 或 /dwf/v1/meta/relations/{name}/attributes-bind",
+  "type": "array",
+  "fields": [
+    {"name": "id", "type": "string", "required": false, "description": "属性ID"},
+    {"name": "attributeName", "type": "string", "required": true, "description": "属性英文名（指定要绑定的属性）", "example": "actorId"},
+    {"name": "displayName", "type": "string", "required": false, "description": "属性显示名（绑定时可修改）", "example": "任务执行人"},
+    {"name": "attributeCategory", "type": "string", "required": false, "description": "属性类别", "enum": ["Constant", "Variable"]},
+    {"name": "valueType", "type": "string", "required": false, "description": "字段取值类型", "example": "String"},
+    {"name": "valueLength", "type": "integer", "required": false, "description": "字段取值最大字节长度"},
+    {"name": "nullable", "type": "boolean", "required": false, "description": "字段是否可空"},
+    {"name": "defaultValue", "type": "string", "required": false, "description": "字段默认值（绑定时可修改）"},
+    {"name": "isPrimaryKey", "type": "boolean", "required": false, "description": "字段是否为主键"},
+    {"name": "isIdentity", "type": "boolean", "required": false, "description": "字段是否自增"},
+    {"name": "note", "type": "string", "required": false, "description": "备注（绑定时可修改）"}
+  ],
+  "examples": [
+    [{"attributeName": "age", "displayName": "年龄", "note": "绑定到User类"}]
+  ]
+}

dwf_cli/schemas/datamodel/attribute_create.schema.json

@@ -0,0 +1,24 @@
+{
+  "description": "批量创建属性。id 必须留空（后台自动生成）",
+  "api": "POST /dwf/v1/meta/attributes-create",
+  "type": "array",
+  "fields": [
+    {"name": "id", "type": "string", "required": false, "description": "属性ID（创建时留空，后台自动生成）"},
+    {"name": "attributeName", "type": "string", "required": true, "description": "属性英文名", "example": "actorId"},
+    {"name": "displayName", "type": "string", "required": false, "description": "属性显示名（一般为中文）", "example": "任务执行人"},
+    {"name": "attributeCategory", "type": "string", "required": false, "description": "属性类别：常量或变量", "enum": ["Constant", "Variable"], "example": "Variable"},
+    {"name": "valueType", "type": "string", "required": true, "description": "字段取值类型（如 String, Integer, Boolean, Long, UUID, Date, Double, Clob, TimeStamp, Time, Json, Timeseries, LocalFile）", "example": "String"},
+    {"name": "valueLength", "type": "integer", "required": false, "description": "字段取值最大字节长度", "example": 50},
+    {"name": "nullable", "type": "boolean", "required": false, "description": "字段是否可空", "example": true},
+    {"name": "defaultValue", "type": "string", "required": false, "description": "字段默认值", "example": "0"},
+    {"name": "isPrimaryKey", "type": "boolean", "required": false, "description": "字段是否为主键", "example": false},
+    {"name": "isIdentity", "type": "boolean", "required": false, "description": "字段是否自增", "example": false},
+    {"name": "note", "type": "string", "required": false, "description": "备注", "example": "备注"}
+  ],
+  "examples": [
+    [
+      {"attributeName": "age", "displayName": "年龄", "valueType": "Integer", "nullable": true},
+      {"attributeName": "name", "displayName": "姓名", "valueType": "String", "valueLength": 100}
+    ]
+  ]
+}

dwf_cli/schemas/datamodel/attribute_update.schema.json

@@ -0,0 +1,21 @@
+{
+  "description": "更新属性。id 和 attributeName 标识要更新的属性",
+  "api": "POST /dwf/v1/meta/attributes-update",
+  "type": "object",
+  "fields": [
+    {"name": "id", "type": "string", "required": false, "description": "属性ID（更新时用于标识属性）"},
+    {"name": "attributeName", "type": "string", "required": true, "description": "属性英文名", "example": "actorId"},
+    {"name": "displayName", "type": "string", "required": false, "description": "属性显示名（一般为中文）", "example": "任务执行人"},
+    {"name": "attributeCategory", "type": "string", "required": false, "description": "属性类别：常量或变量", "enum": ["Constant", "Variable"], "example": "Variable"},
+    {"name": "valueType", "type": "string", "required": false, "description": "字段取值类型", "example": "String"},
+    {"name": "valueLength", "type": "integer", "required": false, "description": "字段取值最大字节长度", "example": 50},
+    {"name": "nullable", "type": "boolean", "required": false, "description": "字段是否可空", "example": true},
+    {"name": "defaultValue", "type": "string", "required": false, "description": "字段默认值", "example": "0"},
+    {"name": "isPrimaryKey", "type": "boolean", "required": false, "description": "字段是否为主键", "example": false},
+    {"name": "isIdentity", "type": "boolean", "required": false, "description": "字段是否自增", "example": false},
+    {"name": "note", "type": "string", "required": false, "description": "备注"}
+  ],
+  "examples": [
+    {"attributeName": "age", "displayName": "年龄（更新）", "valueType": "Integer", "nullable": false}
+  ]
+}

dwf_cli/schemas/datamodel/create.schema.json

@@ -0,0 +1,27 @@
+{
+  "description": "批量新增类（实体类/关联类/模块类）。className 必填且唯一，id 可留空（后台自动生成），isSystem 默认 false",
+  "api": "POST /dwf/v1/meta/entities-create?withParentOid=false",
+  "type": "array",
+  "fields": [
+    {"name": "id", "type": "string", "required": false, "description": "类的ID（创建时留空，后台自动生成）"},
+    {"name": "className", "type": "string", "required": true, "description": "类的英文名（必填，唯一）", "example": "UserTest"},
+    {"name": "displayName", "type": "string", "required": false, "description": "类的显示名", "example": "测试用户类"},
+    {"name": "classType", "type": "string", "required": false, "description": "持久类或动态类", "enum": ["DynamicClass", "PersistentClass"], "example": "PersistentClass"},
+    {"name": "classCategory", "type": "string", "required": false, "description": "类类别：实体类、关联类、外部实体类、模块类、操作、根", "enum": ["OperationClass", "ItemClass", "ExternalItemClass", "RelationClass", "ModuleClass", "Root"], "example": "ItemClass"},
+    {"name": "parentClass", "type": "string", "required": false, "description": "父类名", "example": "ItemClass"},
+    {"name": "isSystem", "type": "boolean", "required": false, "description": "是否系统类（默认 false）", "example": false},
+    {"name": "state", "type": "integer", "required": false, "description": "状态（保留字段）"},
+    {"name": "packagePath", "type": "string", "required": false, "description": "扩展字段：模块类存图标名，外部实体类存属性映射信息"},
+    {"name": "zoneName", "type": "string", "required": false, "description": "自定义域名", "example": "CUS"},
+    {"name": "appId", "type": "string", "required": false, "description": "应用ID（仅模块类有意义）"},
+    {"name": "dataSourceOid", "type": "string", "required": false, "description": "数据源oid（仅外部实体类有意义）"},
+    {"name": "primaryKey", "type": "string", "required": false, "description": "自定义主键"},
+    {"name": "isDeletable", "type": "boolean", "required": false, "description": "是否可删改", "example": true},
+    {"name": "note", "type": "string", "required": false, "description": "备注", "example": "备注"},
+    {"name": "isExternalClassView", "type": "boolean", "required": false, "description": "是否为外部实体类创建view"}
+  ],
+  "examples": [
+    [{"className": "Asset", "displayName": "设备资产", "classCategory": "ItemClass", "zoneName": "CUS"}],
+    [{"className": "User", "displayName": "用户", "classCategory": "ItemClass", "zoneName": "CUS", "isDeletable": true, "note": "用户信息表"}]
+  ]
+}

dwf_cli/schemas/datamodel/excel_confirm.schema.json

@@ -0,0 +1,65 @@
+{
+  "description": "Excel 快速建表确认信息。由 excel-upload 返回的数据经校验、补全 attributeName/displayName 后提交",
+  "api": "POST /dwf/v1/quickStartFromExcel/confirmClassInfo",
+  "type": "object",
+  "fields": [
+    {"name": "uuid", "type": "string", "required": true, "description": "上传 Excel 后获得的唯一标识", "example": "E395B9103325E64AB25698B4E933CEC2"},
+    {"name": "useFirstRowAsClassName", "type": "boolean", "required": false, "description": "是否使用第一行作为类名", "example": true},
+    {"name": "useSecondRowAsDisplayName", "type": "boolean", "required": false, "description": "是否使用第二行作为显示名", "example": true},
+    {
+      "name": "allSheetInfo",
+      "type": "array",
+      "required": true,
+      "description": "所有 Sheet 信息列表",
+      "item_schema": {
+        "fields": [
+          {"name": "sheetName", "type": "string", "required": false, "description": "Sheet 名称", "example": "Asset"},
+          {"name": "className", "type": "string", "required": false, "description": "类英文名", "example": "Asset"},
+          {"name": "displayName", "type": "string", "required": false, "description": "类显示名", "example": "Asset"},
+          {"name": "zoneName", "type": "string", "required": false, "description": "自定义域名", "example": "CUS"},
+          {"name": "isTree", "type": "boolean", "required": false, "description": "是否为树形结构", "example": false},
+          {"name": "useThisSheet", "type": "boolean", "required": false, "description": "是否使用此 Sheet", "example": true},
+          {
+            "name": "infoFromColumnList",
+            "type": "array",
+            "required": false,
+            "description": "列信息列表",
+            "item_schema": {
+              "fields": [
+                {"name": "useThisColumn", "type": "boolean", "required": false, "description": "是否使用此列", "example": true},
+                {"name": "firstRowData", "type": "string", "required": false, "description": "第一行数据（原始值，作为属性英文名参考）", "example": "assetName"},
+                {"name": "firstRowDataPinyin", "type": "string", "required": false, "description": "第一行数据的拼音", "example": "assetName"},
+                {"name": "secondRowData", "type": "string", "required": false, "description": "第二行数据（中文显示名参考）", "example": "设备名称"},
+                {"name": "dataType", "type": "string", "required": false, "description": "数据类型", "example": "String"},
+                {"name": "index", "type": "integer", "required": false, "description": "列索引（从0开始）", "example": 1},
+                {"name": "attributeName", "type": "string", "required": false, "description": "属性英文名（确认时补全，通常取 firstRowData）", "example": "assetName"},
+                {"name": "displayName", "type": "string", "required": false, "description": "属性显示名（确认时补全，通常取 secondRowData）", "example": "设备名称"}
+              ]
+            }
+          }
+        ]
+      }
+    }
+  ],
+  "examples": [
+    {
+      "uuid": "E395B9103325E64AB25698B4E933CEC2",
+      "useFirstRowAsClassName": true,
+      "useSecondRowAsDisplayName": true,
+      "allSheetInfo": [
+        {
+          "sheetName": "Asset",
+          "className": "Asset",
+          "displayName": "Asset",
+          "zoneName": "CUS",
+          "isTree": false,
+          "useThisSheet": true,
+          "infoFromColumnList": [
+            {"useThisColumn": true, "firstRowData": "id", "secondRowData": "代号", "dataType": "String", "index": 0, "attributeName": "id", "displayName": "代号"},
+            {"useThisColumn": true, "firstRowData": "assetName", "secondRowData": "设备名称", "dataType": "String", "index": 1, "attributeName": "assetName", "displayName": "设备名称"}
+          ]
+        }
+      ]
+    }
+  ]
+}

dwf_cli/schemas/datamodel/external_create.schema.json

@@ -0,0 +1,47 @@
+{
+  "description": "批量新增外部实体类",
+  "api": "POST /dwf/v1/meta/external-entities-create",
+  "type": "object",
+  "fields": [
+    {
+      "name": "classList",
+      "type": "array",
+      "required": true,
+      "description": "模型类元信息列表（MetaClassDO），classCategory 应为 ExternalItemClass",
+      "item_schema": {
+        "fields": [
+          {"name": "id", "type": "string", "required": false, "description": "类的ID（创建时留空）"},
+          {"name": "className", "type": "string", "required": true, "description": "类的英文名（必填，唯一）", "example": "ExtUser"},
+          {"name": "displayName", "type": "string", "required": false, "description": "类的显示名", "example": "外部用户"},
+          {"name": "classType", "type": "string", "required": false, "description": "持久类或动态类", "enum": ["DynamicClass", "PersistentClass"]},
+          {"name": "classCategory", "type": "string", "required": false, "description": "类类别（外部实体类应为 ExternalItemClass）", "enum": ["OperationClass", "ItemClass", "ExternalItemClass", "RelationClass", "ModuleClass", "Root"]},
+          {"name": "parentClass", "type": "string", "required": false, "description": "父类名"},
+          {"name": "isSystem", "type": "boolean", "required": false, "description": "是否系统类"},
+          {"name": "state", "type": "integer", "required": false, "description": "状态（保留字段）"},
+          {"name": "packagePath", "type": "string", "required": false, "description": "扩展字段：外部实体类存属性映射信息"},
+          {"name": "zoneName", "type": "string", "required": false, "description": "自定义域名", "example": "CUS"},
+          {"name": "appId", "type": "string", "required": false, "description": "应用ID"},
+          {"name": "dataSourceOid", "type": "string", "required": false, "description": "数据源oid"},
+          {"name": "primaryKey", "type": "string", "required": false, "description": "自定义主键"},
+          {"name": "isDeletable", "type": "boolean", "required": false, "description": "是否可删改"},
+          {"name": "note", "type": "string", "required": false, "description": "备注"},
+          {"name": "isExternalClassView", "type": "boolean", "required": false, "description": "是否为外部实体类创建view"}
+        ]
+      }
+    },
+    {
+      "name": "customSqlMap",
+      "type": "object",
+      "required": false,
+      "description": "外部实体类与其视图自定义SQL对应关系（key=className, value=SQL）"
+    }
+  ],
+  "examples": [
+    {
+      "classList": [
+        {"className": "ExtUser", "displayName": "外部用户", "classCategory": "ExternalItemClass", "zoneName": "CUS"}
+      ],
+      "customSqlMap": {"ExtUser": "SELECT * FROM ext_users"}
+    }
+  ]
+}