dataops-sdk 0.3.0__py3-none-any.whl

dataops_sdk/schemas/widget.py

@@ -0,0 +1,651 @@
+from enum import StrEnum
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, Field, model_validator
+
+from .meta import Meta
+
+# ============================================================
+# 共享字段类型（所有卡片类型共用）
+# ============================================================
+
+
+class DimensionField(BaseModel):
+    """维度字段"""
+
+    id: Annotated[str, Field(description="维度ID")]
+    name: Annotated[str, Field(description="字段名")]
+    title: Annotated[str, Field(description="显示标题")]
+    dbType: Annotated[str | None, Field(description="数据库类型")] = None
+    relId: Annotated[str | None, Field(description="关联ID")] = None
+    relType: Annotated[str | None, Field(description="关联类型")] = None
+
+
+class MeasureField(BaseModel):
+    """度量字段"""
+
+    id: Annotated[str, Field(description="度量ID")]
+    name: Annotated[str, Field(description="字段名")]
+    title: Annotated[str, Field(description="显示标题")]
+    dbType: Annotated[str | None, Field(description="数据库类型")] = None
+    relId: Annotated[str | None, Field(description="关联ID")] = None
+    relType: Annotated[str | None, Field(description="关联类型")] = None
+    aggregation: Annotated[
+        Literal["avg", "count", "distinct_count", "max", "min", "sum"] | None,
+        Field(description="聚合方式"),
+    ] = None
+
+
+class FilterField(BaseModel):
+    """过滤字段"""
+
+    id: Annotated[str, Field(description="过滤ID")]
+    name: Annotated[str, Field(description="字段名")]
+    title: Annotated[str, Field(description="显示标题")]
+    operator: Annotated[str | None, Field(description="操作符")] = None
+    value: Annotated[Any, Field(description="过滤值")] = None
+
+
+class SortField(BaseModel):
+    """排序字段"""
+
+    id: Annotated[str, Field(description="排序ID")]
+    relId: Annotated[str | None, Field(description="关联ID")] = None
+    relType: Annotated[Literal["dimension", "measure"] | None, Field(description="关联类型")] = None
+    title: Annotated[str | None, Field(description="显示标题")] = None
+    asc: Annotated[bool, Field(description="是否升序")] = True
+
+
+# ============================================================
+# Chart 卡片 Schema (v1 + v2 统一)
+# 前端 IdealChartView / IdealChartViewV2 共用
+# 后端 subType="chart"，数据 key 也叫 "chart"
+# ============================================================
+
+
+class ChartType(StrEnum):
+    """图表子类型"""
+
+    LINE = "line"
+    BAR = "bar"
+    PIE = "pie"
+    DOUGHNUT = "doughnut"
+    RADAR = "radar"
+    SCATTER = "scatter"
+    FUNNEL = "funnel"
+
+
+class TextStyle(BaseModel):
+    """文本样式（legend/xAxis/yAxis/label等使用）"""
+
+    fontSize: Annotated[int | None, Field(description="字体大小")] = None
+    color: Annotated[str | None, Field(description="颜色")] = None
+    fontWeight: Annotated[Literal["normal", "bold"] | None, Field(description="字重")] = None
+    fontStyle: Annotated[Literal["normal", "italic"] | None, Field(description="字体风格")] = None
+    textDecoration: Annotated[Literal["none", "underline"] | None, Field(description="装饰")] = None
+    textAlign: Annotated[Literal["left", "center", "right"] | None, Field(description="对齐")] = (
+        None
+    )
+
+
+class ChartAxis(BaseModel):
+    """坐标轴配置"""
+
+    show: Annotated[bool, Field(description="是否显示")] = True
+    showLabel: Annotated[bool, Field(description="是否显示标签")] = True
+    labelRotate: Annotated[
+        Literal[0, 45, 90, -45, -90] | None, Field(description="标签旋转角度")
+    ] = None
+    labelGap: Annotated[int | None, Field(description="标签间距")] = None
+    showAxisLine: Annotated[bool, Field(description="是否显示轴线")] = True
+    labelTextStyle: Annotated[TextStyle | None, Field(description="标签文本样式")] = None
+
+
+class ChartLegend(BaseModel):
+    """图例配置"""
+
+    show: Annotated[bool, Field(description="是否显示")] = True
+    position: Annotated[
+        Literal["top", "bottom", "left", "right"] | None, Field(description="位置")
+    ] = None
+    textStyle: Annotated[TextStyle | None, Field(description="文本样式")] = None
+
+
+class ChartLabel(BaseModel):
+    """标签配置"""
+
+    show: Annotated[bool, Field(description="是否显示")] = True
+
+
+class ChartGrid(BaseModel):
+    """网格配置"""
+
+    show: Annotated[bool, Field(description="是否显示")] = True
+
+
+class ChartBackground(BaseModel):
+    """背景配置"""
+
+    color: Annotated[
+        Literal["default", "#ffffff", "#f5f7fa", "#e8f4fd", "#1a1a2e", "#0d1b2a"] | str | None,
+        Field(description="背景色"),
+    ] = "default"
+
+
+class ChartAxisTitle(BaseModel):
+    """轴标题配置"""
+
+    xAxis: Annotated[TextStyle | None, Field(description="X轴标题")] = None
+    yAxis: Annotated[TextStyle | None, Field(description="Y轴标题")] = None
+
+
+class LineSeriesConfig(BaseModel):
+    """折线图系列配置"""
+
+    lineStyle: Annotated[TextStyle | None, Field(description="线条样式")] = None
+    itemStyle: Annotated[TextStyle | None, Field(description="数据项样式")] = None
+    symbol: Annotated[
+        Literal["circle", "rect", "triangle", "diamond", "pin", "arrow", "none"] | None,
+        Field(description="图标类型"),
+    ] = "circle"
+    symbolSize: Annotated[int | None, Field(description="图标大小")] = None
+    yAxisIndex: Annotated[Literal[0, 1] | None, Field(description="Y轴索引")] = None
+    label: Annotated[TextStyle | None, Field(description="标签")] = None
+
+
+class BarSeriesConfig(BaseModel):
+    """柱状图系列配置"""
+
+    borderStyle: Annotated[TextStyle | None, Field(description="边框样式")] = None
+    yAxisIndex: Annotated[Literal[0, 1] | None, Field(description="Y轴索引")] = None
+    label: Annotated[TextStyle | None, Field(description="标签")] = None
+
+
+class PieLabel(BaseModel):
+    """饼图标签配置"""
+
+    show: Annotated[bool, Field(description="是否显示")] = True
+    position: Annotated[
+        Literal["default", "outside", "inside", "center"] | None, Field(description="位置")
+    ] = None
+    content: Annotated[
+        list[Literal["category", "value", "percent"]] | None, Field(description="显示内容")
+    ] = None
+    textStyle: Annotated[TextStyle | None, Field(description="文本样式")] = None
+
+
+class PieSeriesConfig(BaseModel):
+    """饼图系列配置"""
+
+    borderColor: Annotated[str | None, Field(description="边框颜色")] = None
+    donutHole: Annotated[
+        Literal["0%", "10%", "20%", "30%", "40%", "50%", "60%", "70%", "80%"] | None,
+        Field(description="环形挖空"),
+    ] = "0%"
+    startAngle: Annotated[int | None, Field(description="起始角度")] = None
+    label: Annotated[PieLabel | None, Field(description="标签")] = None
+
+
+class SectorConfig(BaseModel):
+    """扇区配置"""
+
+    backgroundColor: Annotated[str | None, Field(description="背景色")] = None
+    borderColor: Annotated[str | None, Field(description="边框颜色")] = None
+
+
+class ChartOptions(BaseModel):
+    """完整图表选项"""
+
+    theme: Annotated[str | None, Field(description="主题")] = None
+    gradientFill: Annotated[bool | None, Field(description="渐变填充")] = None
+    legend: Annotated[ChartLegend | None, Field(description="图例")] = None
+    label: Annotated[ChartLabel | None, Field(description="标签")] = None
+    xAxis: Annotated[ChartAxis | None, Field(description="X轴")] = None
+    yAxis: Annotated[ChartAxis | None, Field(description="Y轴")] = None
+    grid: Annotated[ChartGrid | None, Field(description="网格")] = None
+    fontStyle: Annotated[TextStyle | None, Field(description="字体样式")] = None
+    background: Annotated[ChartBackground | None, Field(description="背景")] = None
+    titleStyle: Annotated[TextStyle | None, Field(description="标题样式")] = None
+    axisTitle: Annotated[ChartAxisTitle | None, Field(description="轴标题")] = None
+    series: Annotated[LineSeriesConfig | BarSeriesConfig | None, Field(description="系列配置")] = (
+        None
+    )
+    seriesList: Annotated[
+        list[LineSeriesConfig | BarSeriesConfig],
+        Field(description="系列列表", default_factory=list),
+    ]
+    pieSeries: Annotated[PieSeriesConfig | None, Field(description="饼图系列")] = None
+    sectors: Annotated[list[SectorConfig], Field(description="扇区配置", default_factory=list)]
+
+
+class WidgetChartData(BaseModel):
+    """图表卡片"""
+
+    type: Annotated[Literal["chart"], Field(description="卡片类型")] = "chart"
+    chartType: Annotated[ChartType, Field(description="图表类型")]
+    dimensions: Annotated[list[DimensionField], Field(description="维度列表", default_factory=list)]
+    measures: Annotated[list[MeasureField], Field(description="度量列表", default_factory=list)]
+    filters: Annotated[list[FilterField], Field(description="过滤条件", default_factory=list)]
+    sorts: Annotated[list[SortField], Field(description="排序列表", default_factory=list)]
+    pageSize: Annotated[int | None, Field(description="页面大小")] = 1000
+    options: Annotated[ChartOptions | None, Field(description="图表选项")] = None
+    datasource: Annotated[str, Field(description="数据源")]
+    metaType: Annotated[str, Field(description="元数据类型")]
+    metaName: Annotated[str, Field(description="元数据名称")]
+
+
+# ============================================================
+# Metric 卡片 Schema
+# ============================================================
+
+
+class MetricFontSizeType(StrEnum):
+    """指标字体大小类型"""
+
+    PRESET = "preset"
+    CUSTOM = "custom"
+
+
+class MetricTitleStyle(BaseModel):
+    """指标标题样式"""
+
+    text: Annotated[str, Field(description="标题文本")] = "指标卡"
+    color: Annotated[str | None, Field(description="颜色")] = None
+    fontSize: Annotated[int | None, Field(description="字体大小")] = None
+
+
+class MetricValueStyle(BaseModel):
+    """指标值样式"""
+
+    color: Annotated[str | None, Field(description="颜色")] = None
+    fontSize: Annotated[int | None, Field(description="字体大小")] = None
+
+
+class MetricBackground(BaseModel):
+    """指标背景样式"""
+
+    color: Annotated[str | None, Field(description="背景色")] = None
+
+
+class MetricStyle(BaseModel):
+    """指标样式配置"""
+
+    fontSizeType: Annotated[MetricFontSizeType | None, Field(description="字体大小类型")] = None
+    title: Annotated[MetricTitleStyle | None, Field(description="标题样式")] = None
+    value: Annotated[MetricValueStyle | None, Field(description="值样式")] = None
+    background: Annotated[MetricBackground | None, Field(description="背景样式")] = None
+
+
+class MetricFormatType(StrEnum):
+    """指标数值格式类型"""
+
+    NUMBER = "number"
+    PERCENT = "percent"
+    THOUSAND = "thousand"
+    CUSTOM = "custom"
+
+
+class MetricSuffixStyle(BaseModel):
+    """指标后缀样式"""
+
+    color: Annotated[str | None, Field(description="颜色")] = None
+    fontSize: Annotated[int | None, Field(description="字体大小")] = None
+
+
+class MetricFormat(BaseModel):
+    """指标数值格式配置"""
+
+    type: Annotated[MetricFormatType | None, Field(description="格式类型")] = None
+    precision: Annotated[Literal[0, 1, 2, 3, 4] | None, Field(description="精度")] = None
+    prefix: Annotated[str | None, Field(description="前缀")] = None
+    suffix: Annotated[str | None, Field(description="后缀")] = None
+    suffixStyle: Annotated[MetricSuffixStyle | None, Field(description="后缀样式")] = None
+    thousandSeparator: Annotated[bool | None, Field(description="千分位分隔符")] = None
+
+
+class WidgetMetricData(BaseModel):
+    """指标卡片"""
+
+    type: Annotated[Literal["metric"], Field(description="卡片类型")] = "metric"
+    style: Annotated[MetricStyle | None, Field(description="样式配置")] = None
+    format: Annotated[MetricFormat | None, Field(description="格式配置")] = None
+    dimensions: Annotated[list[DimensionField], Field(description="维度列表", default_factory=list)]
+    measures: Annotated[list[MeasureField], Field(description="度量列表", default_factory=list)]
+    filters: Annotated[list[FilterField], Field(description="过滤条件", default_factory=list)]
+    datasource: Annotated[str, Field(description="数据源")]
+    metaType: Annotated[str, Field(description="元数据类型")]
+    metaName: Annotated[str, Field(description="元数据名称")]
+
+
+# ============================================================
+# Detail 卡片 Schema
+# ============================================================
+
+
+class DetailDirection(StrEnum):
+    """明细卡片方向"""
+
+    HORIZONTAL = "horizontal"
+    VERTICAL = "vertical"
+
+
+class DetailSize(StrEnum):
+    """明细卡片尺寸"""
+
+    LARGE = "large"
+    DEFAULT = "default"
+    SMALL = "small"
+
+
+class DetailConfig(BaseModel):
+    """明细卡片配置"""
+
+    title: Annotated[str | None, Field(description="标题")] = None
+    column: Annotated[int, Field(description="列数", ge=1, le=10)] = 2
+    border: Annotated[bool, Field(description="是否显示边框")] = True
+    direction: Annotated[DetailDirection, Field(description="方向")] = DetailDirection.HORIZONTAL
+    size: Annotated[DetailSize, Field(description="尺寸")] = DetailSize.DEFAULT
+    labelWidth: Annotated[str | None, Field(description="标签宽度")] = None
+
+
+class WidgetDetailData(BaseModel):
+    """明细卡片"""
+
+    type: Annotated[Literal["detail"], Field(description="卡片类型")] = "detail"
+    config: Annotated[DetailConfig, Field(description="配置")]
+    dimensions: Annotated[list[DimensionField], Field(description="维度列表", default_factory=list)]
+    measures: Annotated[list[MeasureField], Field(description="度量列表", default_factory=list)]
+    filters: Annotated[list[FilterField], Field(description="过滤条件", default_factory=list)]
+    datasource: Annotated[str, Field(description="数据源")]
+    metaType: Annotated[str, Field(description="元数据类型")]
+    metaName: Annotated[str, Field(description="元数据名称")]
+
+
+# ============================================================
+# Topology 卡片 Schema
+# ============================================================
+
+
+class TopologyNodeStyle(BaseModel):
+    """拓扑节点样式"""
+
+    shape: Annotated[str | None, Field(description="形状")] = None
+    color: Annotated[str | None, Field(description="颜色")] = None
+    size: Annotated[str | None, Field(description="大小")] = None
+
+
+class TopologyEdgeStyle(BaseModel):
+    """拓扑边样式"""
+
+    color: Annotated[str | None, Field(description="颜色")] = None
+    lineStyle: Annotated[str | None, Field(description="线条样式")] = None
+    width: Annotated[int | None, Field(description="宽度")] = None
+
+
+class WorkflowInputItem(BaseModel):
+    """工作流输入参数"""
+
+    name: Annotated[str, Field(description="参数名")]
+    title: Annotated[str | None, Field(description="显示标题")] = None
+    type: Annotated[str, Field(description="参数类型")]
+    required: Annotated[bool, Field(description="是否必填")] = False
+    defaultValue: Annotated[Any, Field(description="默认值")] = None
+    description: Annotated[str | None, Field(description="描述")] = None
+
+
+class WorkflowTreeNode(BaseModel):
+    """工作流树节点"""
+
+    id: Annotated[str, Field(description="节点ID")]
+    label: Annotated[str, Field(description="显示标签")]
+    name: Annotated[str | None, Field(description="节点名称")] = None
+    type: Annotated[Literal["group", "workflow"], Field(description="节点类型")]
+    children: Annotated[list["WorkflowTreeNode"], Field(description="子节点", default_factory=list)]
+    code: Annotated[str | None, Field(description="编码")] = None
+
+
+class WorkflowConfig(BaseModel):
+    """工作流配置"""
+
+    flowCode: Annotated[str | None, Field(description="流程编码")] = None
+    params: Annotated[dict[str, Any] | None, Field(description="流程参数")] = None
+    topologyStyle: Annotated[dict[str, Any] | None, Field(description="拓扑样式")] = None
+
+
+class WidgetTopologyData(BaseModel):
+    """拓扑卡片"""
+
+    type: Annotated[Literal["topology"], Field(description="卡片类型")] = "topology"
+    layoutType: Annotated[str, Field(description="布局类型")] = "dagre"
+    nodeStyle: Annotated[TopologyNodeStyle | None, Field(description="节点样式")] = None
+    edgeStyle: Annotated[TopologyEdgeStyle | None, Field(description="边样式")] = None
+    metaType: Annotated[str, Field(description="元数据类型")]
+    metaName: Annotated[str, Field(description="元数据名称")]
+    workflowConfig: Annotated[WorkflowConfig | None, Field(description="工作流配置")] = None
+    inputItems: Annotated[
+        list[WorkflowInputItem], Field(description="输入项", default_factory=list)
+    ]
+    treeData: Annotated[list[WorkflowTreeNode], Field(description="树形数据", default_factory=list)]
+
+
+# ============================================================
+# 旧版 Table 卡片 Schema（向后兼容）
+# ============================================================
+
+
+class WidgetDimension(BaseModel):
+    """卡片表格维度"""
+
+    name: Annotated[str, Field(description="字段名")]
+    title: Annotated[str, Field(description="显示标题")]
+    nullable: Annotated[bool, Field(description="是否可空")]
+    dbType: Annotated[str, Field(description="数据库类型")]
+    length: Annotated[int, Field(description="长度")]
+    labelKey: Annotated[bool | None, Field(description="是否为标签字段")] = None
+    pk: Annotated[bool | None, Field(description="是否主键")] = None
+    relId: Annotated[str | None, Field(description="关联ID")] = None
+    relType: Annotated[str | None, Field(description="关联类型")] = None
+    id: Annotated[str, Field(description="维度ID")]
+    type: Annotated[str | None, Field(description="类型")] = None
+    remark: Annotated[str | None, Field(description="备注")] = None
+    format: Annotated["WidgetFormat | None", Field(description="格式化")] = None
+    link: Annotated["WidgetLink | None", Field(description="链接")] = None
+    cellStyle: Annotated["WidgetCellStyle | None", Field(description="单元格样式")] = None
+    typeExt: Annotated["WidgetTypeExt | None", Field(description="类型扩展")] = None
+
+
+class WidgetQuery(BaseModel):
+    """卡片表格查询条件"""
+
+    id: Annotated[str, Field(description="查询条件ID")]
+    name: Annotated[str, Field(description="字段名")]
+    title: Annotated[str, Field(description="显示标题")]
+    dbType: Annotated[str, Field(description="数据库类型")]
+    plugin: Annotated["WidgetPlugin", Field(description="插件配置")]
+    condition: Annotated["WidgetCondition", Field(description="条件配置")]
+
+
+class WidgetFormat(BaseModel):
+    """格式化配置"""
+
+    type: Annotated[str, Field(description="格式类型")]
+
+
+class WidgetLink(BaseModel):
+    """链接配置"""
+
+    type: Annotated[str, Field(description="链接类型")]
+
+
+class WidgetCellStyle(BaseModel):
+    """单元格样式"""
+
+    rules: Annotated[list, Field(description="样式规则")] = []
+
+
+class WidgetPlugin(BaseModel):
+    """插件配置"""
+
+    type: Annotated[str, Field(description="插件类型")]
+
+
+class WidgetCondition(BaseModel):
+    """查询条件"""
+
+    expression: Annotated[str, Field(description="表达式")] = "eq"
+
+
+class WidgetTypeExt(BaseModel):
+    """类型扩展"""
+
+    ref__table: Annotated["WidgetRefTable | None", Field(description="引用表")] = None
+    ref__valueField: Annotated["WidgetRefValueField | None", Field(description="引用值字段")] = None
+
+
+class WidgetRefTable(BaseModel):
+    """引用表"""
+
+    type: Annotated[str, Field(description="类型")] = "table"
+    code: Annotated[str | None, Field(description="编码")] = None
+
+
+class WidgetRefValueField(BaseModel):
+    """引用值字段"""
+
+    type: Annotated[str, Field(description="类型")] = "table"
+    code: Annotated[str | None, Field(description="编码")] = None
+    subtype: Annotated[str | None, Field(description="子类型")] = None
+    subcode: Annotated[str | None, Field(description="子编码")] = None
+
+
+class WidgetTable(BaseModel):
+    """卡片表格配置（兼容旧版）"""
+
+    type: Annotated[Literal["table"], Field(description="卡片类型")] = "table"
+    filters: Annotated[list, Field(description="过滤条件")] = []
+    datasource: Annotated[str, Field(description="数据源")]
+    metaType: Annotated[str, Field(description="元数据类型")]
+    metaName: Annotated[str, Field(description="元数据名称")]
+    dimensions: Annotated[list[WidgetDimension], Field(description="维度列表")] = []
+    querys: Annotated[list[WidgetQuery], Field(description="查询条件列表")] = []
+
+
+# ============================================================
+# GIS 卡片 Schema (v1)
+# 前端 IdealGisView 共用
+# 后端 subType="gis"，数据 key 为 "gis"
+# ============================================================
+
+
+class GisLayer(BaseModel):
+    """GIS 图层"""
+
+    id: Annotated[str, Field(description="图层ID")]
+    name: Annotated[str, Field(description="图层名称")]
+    color: Annotated[str | None, Field(description="颜色")] = None
+    layerType: Annotated[str | None, Field(description="图层类型")] = None
+
+
+class WidgetGisData(BaseModel):
+    """GIS 卡片"""
+
+    type: Annotated[Literal["gis"], Field(description="卡片类型")] = "gis"
+    mapToken: Annotated[str | None, Field(description="Mapbox Token")] = None
+    layers: Annotated[list[GisLayer], Field(description="图层列表", default_factory=list)]
+    datasource: Annotated[str, Field(description="数据源")]
+    metaType: Annotated[str, Field(description="元数据类型")]
+    metaName: Annotated[str, Field(description="元数据名称")]
+
+
+# ============================================================
+# AI 设计卡片 Schema (v1)
+# 前端 IdealStatisticView 共用
+# 后端 subType="statistic"，数据 key 为 "statistic"
+# ============================================================
+
+
+class WidgetStatisticData(BaseModel):
+    """AI 设计卡片"""
+
+    type: Annotated[Literal["statistic"], Field(description="卡片类型")] = "statistic"
+    cssText: Annotated[str | None, Field(description="自定义 CSS")] = None
+    datasource: Annotated[str, Field(description="数据源")]
+    metaType: Annotated[str, Field(description="元数据类型")]
+    metaName: Annotated[str, Field(description="元数据名称")]
+
+
+# ============================================================
+# 统一卡片数据联合类型（带 pydantic discriminator）
+# ============================================================
+
+
+# 所有卡片数据类型的联合（用于 pydantic discriminated union）
+# pydantic 根据每个子类的 `type` 字段自动识别具体类型
+WidgetData = Annotated[
+    WidgetChartData
+    | WidgetMetricData
+    | WidgetDetailData
+    | WidgetTopologyData
+    | WidgetTable
+    | WidgetGisData
+    | WidgetStatisticData,
+    Field(discriminator="type"),
+]
+
+
+class WidgetMetaData(BaseModel):
+    """卡片元数据.
+
+    后端 rawData 结构: {"<subType>": {...}, "tenantId": ..., "code": ..., ...}
+    其中 subType 的值 (chart/metric/detail/topology/table/gis/statistic) 对应子类型 key 名称。
+
+    通过 model_validator 将 meta.data[subType] 路由到 widget_data 字段，
+    使 meta.data 成为 discriminated union 类型，方便 CLI 层做子类型分派渲染。
+    """
+
+    widget_data: Annotated[
+        WidgetChartData
+        | WidgetMetricData
+        | WidgetDetailData
+        | WidgetTopologyData
+        | WidgetTable
+        | WidgetGisData
+        | WidgetStatisticData,
+        Field(discriminator="type", description="卡片子类型数据（按 subType 路由）"),
+    ]
+    tenantId: Annotated[str, Field(description="租户ID")]
+    enterpriseCuid: Annotated[str, Field(description="企业CUID")]
+    name: Annotated[str, Field(description="名称")]
+    code: Annotated[str, Field(description="编码")]
+    title: Annotated[str, Field(description="标题")]
+    subType: Annotated[str | None, Field(description="子类型")] = None
+    groupCode: Annotated[str | None, Field(description="分组编码")] = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def _route_subtype(cls, values: dict) -> dict:
+        """根据 subType 将 meta.data[subType] 路由到 widget_data 字段."""
+        sub_type: str | None = values.get("subType")
+        data: dict = values.get("data") or {}
+        if sub_type and sub_type in data:
+            # 子类型数据在 meta.data[subType] 中
+            values["widget_data"] = data[sub_type]
+        elif not sub_type:
+            # 兜底：遍历所有已知子类型 key，找第一个匹配的
+            for key in (
+                "chart",
+                "metric",
+                "detail",
+                "topology",
+                "table",
+                "gis",
+                "statistic",
+            ):
+                if key in data:
+                    values["widget_data"] = data[key]
+                    break
+        return values
+
+
+class WidgetMeta(Meta[WidgetMetaData]):
+    """卡片 Meta"""