@fses/workbench-app 0.2.0 → 0.2.1

package/node_modules/@fses/workbench-card/src/registry/cardRegistry.ts

@@ -0,0 +1,476 @@
+/**
+ * @fileoverview 工作台卡片能力注册表 - 定义可用卡片能力、分类和检索工具。
+ * @author seadon
+ * @created 2026-05-20
+ */
+import type { BlockSubType, BlockType } from '../types/block';
+import type { CardSizePreset } from '../types/canvas';
+import { WORKBENCH_COMPOSITE_CARD_PATTERNS } from './compositeCardPatterns';
+import { ECHARTS_MAIN_CATEGORIES } from './echartsTemplateCategories';
+import { ECHARTS_TEMPLATE_REGISTRY } from './echartsTemplateRegistry';
+import type { EChartsTemplateMetadata } from './echartsTemplateTypes';
+
+export type CardCategoryStatus = 'implemented' | 'placeholder' | 'lifecycle';
+
+export interface CardRegistryEntry {
+  capabilityId: string;
+  category: string;
+  type: string;
+  variant?: string;
+  title: string;
+  description: string;
+  blockType: BlockType;
+  subType: BlockSubType | string;
+  rendererKey: string;
+  dataShape: string;
+  shell: 'card';
+  styleVariants: string[];
+  defaultSize: CardSizePreset;
+  handlerClassName: string;
+  status: CardCategoryStatus;
+  aliasOf?: string;
+  honestFailure?: string;
+  echarts?: EChartsTemplateMetadata;
+}
+
+export interface CardCategoryDefinition {
+  id: string;
+  name: string;
+  status: CardCategoryStatus;
+  description: string;
+}
+
+export const CARD_CATEGORIES: CardCategoryDefinition[] = [
+  { id: 'card.metric_cards', name: '指标卡', status: 'implemented', description: '数值、组合、对比、预警、目标达成等指标表达。' },
+  { id: 'card.chart_cards', name: '图表卡', status: 'implemented', description: '柱状图、折线图、混合图、瀑布图、热力图、饼图、雷达图等图表。' },
+  ...ECHARTS_MAIN_CATEGORIES.map((category) => ({
+    id: category.categoryId,
+    name: category.name,
+    status: 'implemented' as const,
+    description: category.description,
+  })),
+  { id: 'card.table_cards', name: '表格卡', status: 'implemented', description: '清单表、汇总表、对比表、矩阵表等表格。' },
+  { id: 'card.analysis_report_cards', name: '分析报告卡', status: 'implemented', description: '洞察、摘要、根因、风险、建议、复盘。' },
+  { id: 'card.dashboard_cards', name: '大屏卡', status: 'implemented', description: '多图看板和经营驾驶舱。' },
+  { id: 'card.utility_cards', name: '普通能力卡', status: 'implemented', description: '天气、日历、快捷入口、公告、搜索、提醒、收藏。' },
+  { id: 'card.embedded_form_cards', name: '内嵌表单卡', status: 'implemented', description: 'iframe 页面和表单卡。' },
+  { id: 'card.fde_custom_cards', name: 'FDE 定制卡', status: 'implemented', description: 'FDE 定制组件卡。' },
+  { id: 'card.custom_canvas_cards', name: '自定义画布卡', status: 'implemented', description: '空白画布和自定义容器。' },
+  { id: 'card.composite_cards', name: '组合卡片', status: 'implemented', description: '图生工作台沉淀的多区域 customCanvas 组合卡片。' },
+  { id: 'card.graph_cards', name: '关系图卡', status: 'implemented', description: '网络关系、组织关系、依赖关系。' },
+  { id: 'card.geo_cards', name: '地理卡', status: 'implemented', description: '地图、区域分布、全球流向。' },
+  { id: 'card.identity_cards', name: '身份卡', status: 'implemented', description: '客户、项目、员工、供应商等身份摘要。' },
+  { id: 'card.workflow_cards', name: '流程卡', status: 'implemented', description: '审批流、任务流、时间线、状态板。' },
+  { id: 'card.entity_cards', name: '业务对象详情卡', status: 'implemented', description: '客户、项目、合同、供应商、资产、工单详情。' },
+  { id: 'card.lifecycle_mutation', name: '卡片生命周期改卡能力', status: 'lifecycle', description: '出卡后对卡片、对象和画布进行修改。' },
+];
+
+const metricEntries = [
+  ['numeric', '数值卡片'],
+  ['combo', '组合卡片'],
+  ['comparison', '对比卡片'],
+  ['alert', '预警卡片'],
+  ['targetAchievement', '目标达成卡'],
+  ['yoyMom', '同比环比卡'],
+  ['segmentedProgress', '分段进度卡'],
+  ['abnormalMetric', '异常指标卡'],
+  ['slaMetric', 'SLA 指标卡'],
+] as const;
+
+const chartEntries = [
+  ['bar', '柱状图', 'bar', 'multiSeries'],
+  ['customEcharts', '自定义图表', 'customEcharts', 'echartsOption'],
+  ['line', '折线图', 'line', 'singleSeries'],
+  ['mixedBarLine', '柱线混合图', 'mixedBarLine', 'multiSeries'],
+  ['waterfall', '瀑布图', 'waterfall', 'waterfallSteps'],
+  ['heatmap', '热力图', 'heatmap', 'heatmapMatrix'],
+  ['pie', '饼图', 'pie', 'pieSlices'],
+  ['donut', '环形图', 'donut', 'pieSlices'],
+  ['radar', '雷达图', 'radar', 'radarMetrics'],
+  ['scatter', '散点图', 'scatter', 'scatterPoints'],
+  ['bubble', '气泡图', 'bubble', 'scatterPoints'],
+  ['funnel', '漏斗图', 'funnel', 'funnelStages'],
+  ['gauge', '仪表盘', 'gauge', 'gaugeMetric'],
+  ['map', '地图', 'map', 'mapRegions'],
+  ['sankey', '桑基图', 'sankey', 'sankeyFlow'],
+  ['tree', '树图', 'tree', 'treeHierarchy'],
+  ['gantt', '甘特图', 'gantt', 'ganttTasks'],
+  ['candlestick', 'K 线图', 'candlestick', 'candlestickSeries'],
+  ['kline', 'K 线图别名', 'candlestick', 'candlestickSeries'],
+  ['boxplot', '箱线图', 'boxplot', 'boxplotSeries'],
+  ['area', '面积图', 'area', 'singleSeries'],
+  ['stackedBar', '堆叠柱状图', 'stackedBar', 'multiSeries'],
+  ['pareto', '帕累托图', 'pareto', 'paretoSeries'],
+  ['drilldownTree', '下钻树图', 'drilldownTree', 'treeHierarchy'],
+  ['network', '网络关系图', 'network', 'networkGraph'],
+] as const;
+
+const tableEntries = [
+  ['list', '清单表'],
+] as const;
+
+const lifecycleOperations = [
+  'freeModify',
+  'renameTitle',
+  'editBodyText',
+  'editText',
+  'changeChart',
+  'changeDataSource',
+  'adjustLayout',
+  'replaceCard',
+  'locateCard',
+  'modifyCard',
+  'deleteCard',
+  'clearCanvas',
+  'overwriteCanvas',
+  'rollback',
+  'mutateCapability',
+] as const;
+
+function upperFirst(value: string) {
+  return value ? value.slice(0, 1).toUpperCase() + value.slice(1) : value;
+}
+
+function defaultStyleVariants(input: Pick<CardRegistryEntry, 'rendererKey' | 'dataShape' | 'subType'>): string[] {
+  if (input.dataShape === 'metricSummary') return ['standard', 'compact', 'emphasis'];
+  if (input.dataShape === 'rows') return ['standard', 'compact', 'dense'];
+  if (input.dataShape === 'customCanvas' || input.dataShape === 'dashboardGrid') return ['standard', 'compact', 'section'];
+  if (input.rendererKey === 'weatherCard' || input.rendererKey === 'calendarCard') return ['standard', 'compact', 'tile'];
+  if (input.rendererKey === 'insightNarrative' || input.rendererKey === 'reportSummary') return ['standard', 'compact', 'narrative'];
+  return ['standard', 'compact', 'accent'];
+}
+
+function entry(input: Omit<CardRegistryEntry, 'status' | 'shell' | 'styleVariants'> & {
+  shell?: 'card';
+  status?: CardCategoryStatus;
+  styleVariants?: string[];
+}): CardRegistryEntry {
+  return {
+    ...input,
+    shell: input.shell || 'card',
+    styleVariants: input.styleVariants?.length ? input.styleVariants : defaultStyleVariants(input),
+    status: input.status || 'implemented',
+  };
+}
+
+export const CARD_REGISTRY: CardRegistryEntry[] = [
+  ...metricEntries.map(([type, title]) => entry({
+    capabilityId: `card.metric.${type}`,
+    category: 'card.metric_cards',
+    type,
+    title,
+    description: `${title}，展示核心指标和趋势变化。`,
+    blockType: 'display',
+    subType: 'metric',
+    rendererKey: 'metricStrip',
+    dataShape: 'metricSummary',
+    defaultSize: 'medium',
+    handlerClassName: `${upperFirst(type)}MetricCardAbility`,
+  })),
+  ...chartEntries.map(([type, title, rendererKey, dataShape]) => entry({
+    capabilityId: `card.chart.${type}`,
+    category: 'card.chart_cards',
+    type,
+    title,
+    description: `${title}，用于企业经营数据可视化。`,
+    blockType: 'display',
+    subType: 'chart',
+    rendererKey,
+    dataShape,
+    defaultSize: 'medium',
+    handlerClassName: type === 'kline' ? 'CandlestickChartCardAbility' : `${upperFirst(type)}ChartCardAbility`,
+    aliasOf: type === 'kline' ? 'card.chart.candlestick' : undefined,
+  })),
+  ...ECHARTS_TEMPLATE_REGISTRY.map((template) => entry(template)),
+  ...tableEntries.map(([type, title]) => entry({
+    capabilityId: `card.table.${type}`,
+    category: 'card.table_cards',
+    type,
+    title,
+    description: `${title}，按表头、行和备注展示业务数据。`,
+    blockType: 'display',
+    subType: 'table',
+    rendererKey: 'dataTable',
+    dataShape: 'rows',
+    defaultSize: 'medium',
+    handlerClassName: `${upperFirst(type)}TableCardAbility`,
+  })),
+  ...[
+    ['insight', '洞察卡', 'insightNarrative', 'insightNarrative'],
+    ['reportSummary', '报告摘要卡', 'reportSummary', 'reportSummary'],
+    ['rootCause', '根因分析卡', 'insightNarrative', 'insightNarrative'],
+    ['riskInterpretation', '风险解读卡', 'insightNarrative', 'insightNarrative'],
+    ['businessSuggestion', '经营建议卡', 'insightNarrative', 'insightNarrative'],
+    ['weeklyReport', '周报卡', 'reportSummary', 'reportSummary'],
+    ['retrospective', '复盘卡', 'insightNarrative', 'insightNarrative'],
+  ].map(([type, title, rendererKey, dataShape]) => entry({
+    capabilityId: `card.analysis.${type}`,
+    category: 'card.analysis_report_cards',
+    type,
+    title,
+    description: `${title}，沉淀判断、解释、风险和建议。`,
+    blockType: 'display',
+    subType: 'insight',
+    rendererKey,
+    dataShape,
+    defaultSize: 'medium',
+    handlerClassName: `${upperFirst(type)}AnalysisCardAbility`,
+  })),
+  ...['multiPanel', 'executiveCockpit', 'projectCockpit', 'riskCockpit', 'regionalCockpit'].map((type) => entry({
+    capabilityId: `card.dashboard.${type}`,
+    category: 'card.dashboard_cards',
+    type,
+    title: type === 'multiPanel' ? '大屏卡/多图看板' : `${type} 驾驶舱`,
+    description: '用一张大屏卡承载多个关键图表面板。',
+    blockType: 'display',
+    subType: 'customCanvas',
+    rendererKey: 'dashboardGrid',
+    dataShape: 'dashboardGrid',
+    defaultSize: 'screen',
+    handlerClassName: `${upperFirst(type)}DashboardCardAbility`,
+  })),
+  ...[
+    ['weather', '天气卡', 'weatherCard', 'weatherCurrent'],
+    ['calendar', '日历卡', 'calendarCard', 'calendarCard'],
+    ['quickLinks', '快捷入口卡', 'customCanvas', 'customCanvas'],
+    ['announcement', '公告卡', 'customCanvas', 'customCanvas'],
+    ['search', '搜索卡', 'customCanvas', 'customCanvas'],
+    ['reminder', '提醒卡', 'customCanvas', 'customCanvas'],
+    ['favorites', '收藏卡', 'customCanvas', 'customCanvas'],
+  ].map(([type, title, rendererKey, dataShape]) => entry({
+    capabilityId: `card.utility.${type}`,
+    category: 'card.utility_cards',
+    type,
+    title,
+    description: `${title}，提供轻量工作台能力。`,
+    blockType: 'display',
+    subType: type === 'weather' ? 'weather' : type === 'calendar' ? 'calendar' : 'customCanvas',
+    rendererKey,
+    dataShape,
+    defaultSize: 'medium',
+    handlerClassName: `${upperFirst(type)}UtilityCardAbility`,
+  })),
+  entry({
+    capabilityId: 'card.embedded.iframe',
+    category: 'card.embedded_form_cards',
+    type: 'iframe',
+    title: '内嵌表单/iframe 页面卡',
+    description: '通过白名单 URL 嵌入页面。',
+    blockType: 'display',
+    subType: 'embed',
+    rendererKey: 'embeddedFrame',
+    dataShape: 'embeddedFrame',
+    defaultSize: 'medium',
+    handlerClassName: 'EmbeddedIframePageCardAbility',
+  }),
+  entry({
+    capabilityId: 'card.embedded.iframePage',
+    category: 'card.embedded_form_cards',
+    type: 'iframePage',
+    title: '内嵌页面卡别名',
+    description: 'card.embedded.iframe 的历史别名。',
+    blockType: 'display',
+    subType: 'embed',
+    rendererKey: 'embeddedFrame',
+    dataShape: 'embeddedFrame',
+    defaultSize: 'medium',
+    handlerClassName: 'EmbeddedIframePageCardAbility',
+    aliasOf: 'card.embedded.iframe',
+  }),
+  entry({
+    capabilityId: 'card.fde.customComponent',
+    category: 'card.fde_custom_cards',
+    type: 'customComponent',
+    title: 'FDE 定制组件卡',
+    description: '挂载已注册的 FDE 组件。',
+    blockType: 'display',
+    subType: 'fdeCustom',
+    rendererKey: 'fdeCustomComponent',
+    dataShape: 'fdeCustomComponent',
+    defaultSize: 'medium',
+    handlerClassName: 'FdeCustomComponentCardAbility',
+  }),
+  entry({
+    capabilityId: 'card.fde.templateWeather',
+    category: 'card.fde_custom_cards',
+    type: 'templateWeather',
+    title: '天气组件',
+    description: '@byteluck-fe/workbench-template 提供的天气组件，按城市展示实时天气。',
+    blockType: 'display',
+    subType: 'fdeCustom',
+    rendererKey: 'fdeCustomComponent',
+    dataShape: 'fdeCustomComponent',
+    defaultSize: 'componentTall',
+    handlerClassName: 'WorkbenchTemplateWeatherComponentAbility',
+    styleVariants: ['standard', 'compact', 'tile'],
+  }),
+  entry({
+    capabilityId: 'card.custom.blankCanvas',
+    category: 'card.custom_canvas_cards',
+    type: 'blankCanvas',
+    title: '空白画布卡',
+    description: '自定义空白内容容器。',
+    blockType: 'display',
+    subType: 'customCanvas',
+    rendererKey: 'customCanvas',
+    dataShape: 'customCanvas',
+    defaultSize: 'medium',
+    handlerClassName: 'CustomBlankCanvasCardAbility',
+  }),
+  entry({
+    capabilityId: 'card.custom.nestedContainer',
+    category: 'card.dashboard_cards',
+    type: 'nestedContainer',
+    title: '嵌套容器卡',
+    description: '可承载其它工作台卡片的拖拽容器，子卡保留独立问数能力。',
+    blockType: 'display',
+    subType: 'customCanvas',
+    rendererKey: 'customCanvas',
+    dataShape: 'customCanvas',
+    defaultSize: 'large',
+    handlerClassName: 'NestedContainerCardAbility',
+  }),
+  ...WORKBENCH_COMPOSITE_CARD_PATTERNS.map((pattern) => entry({
+    capabilityId: pattern.capabilityId,
+    category: 'card.composite_cards',
+    type: pattern.id,
+    title: pattern.title,
+    description: pattern.description,
+    blockType: 'display',
+    subType: 'customCanvas',
+    rendererKey: pattern.rendererKey,
+    dataShape: pattern.dataShape,
+    defaultSize: pattern.defaultSize,
+    handlerClassName: `${upperFirst(pattern.id)}CompositeCardAbility`,
+  })),
+  ...[
+    ['knowledge', '知识图谱卡'],
+    ['ontology', '本体图谱卡'],
+    ['relationship', '关系网络卡'],
+    ['dataLineage', '数据血缘卡'],
+    ['impactChain', '影响链路卡'],
+    ['metricLineage', '指标血缘卡'],
+    ['permissionRelation', '权限关系图卡'],
+  ].map(([type, title]) => entry({
+    capabilityId: `card.graph.${type}`,
+    category: 'card.graph_cards',
+    type,
+    title,
+    description: '展示节点关系和连接强度。',
+    blockType: 'display',
+    subType: 'chart',
+    rendererKey: 'network',
+    dataShape: 'networkGraph',
+    defaultSize: 'medium',
+    handlerClassName: `${upperFirst(type)}GraphCardAbility`,
+  })),
+  ...[
+    ['earth3d', '3D地球卡', 'geoGlobe', 'geoGlobe', 'large'],
+    ['siteDistribution', '地理网点分布卡', 'map', 'mapRegions', 'medium'],
+    ['regionalHeat', '区域热力卡', 'map', 'mapRegions', 'medium'],
+    ['migrationFlow', '迁徙飞线卡', 'network', 'networkGraph', 'medium'],
+    ['routeTrack', '路线轨迹卡', 'network', 'networkGraph', 'medium'],
+  ].map(([type, title, rendererKey, dataShape, defaultSize]) => entry({
+    capabilityId: `card.geo.${type}`,
+    category: 'card.geo_cards',
+    type,
+    title,
+    description: '展示区域分布和地理流向。',
+    blockType: 'display',
+    subType: 'chart',
+    rendererKey,
+    dataShape,
+    defaultSize: defaultSize as CardSizePreset,
+    handlerClassName: `${upperFirst(type)}GeoCardAbility`,
+  })),
+  ...[
+    ['directory', '企业通讯录卡', 'dataTable', 'rows'],
+    ['orgChart', '组织架构卡', 'tree', 'treeHierarchy'],
+    ['personProfile', '人员画像卡', 'customCanvas', 'customCanvas'],
+    ['teamDistribution', '团队分布卡', 'bar', 'multiSeries'],
+    ['permissionRelation', '权限关系卡', 'network', 'networkGraph'],
+  ].map(([type, title, rendererKey, dataShape]) => entry({
+    capabilityId: `card.identity.${type}`,
+    category: 'card.identity_cards',
+    type,
+    title,
+    description: '展示业务对象身份摘要。',
+    blockType: 'display',
+    subType: rendererKey === 'dataTable' ? 'table' : rendererKey === 'tree' || rendererKey === 'bar' || rendererKey === 'network' ? 'chart' : 'customCanvas',
+    rendererKey,
+    dataShape,
+    defaultSize: 'medium',
+    handlerClassName: `${upperFirst(type)}IdentityCardAbility`,
+  })),
+  ...[
+    ['todoList', '待办清单卡', 'taskSummary', 'taskSummary'],
+    ['approvalList', '审批列表卡', 'dataTable', 'rows'],
+    ['processStatus', '流程状态卡', 'gauge', 'gaugeMetric'],
+    ['approvalChain', '审批链卡', 'tree', 'treeHierarchy'],
+    ['sla', '流程 SLA 卡', 'metricStrip', 'metricSummary'],
+    ['taskTimeline', '任务时间线卡', 'gantt', 'ganttTasks'],
+    ['bottleneck', '流程瓶颈卡', 'bar', 'multiSeries'],
+  ].map(([type, title, rendererKey, dataShape]) => entry({
+    capabilityId: `card.workflow.${type}`,
+    category: 'card.workflow_cards',
+    type,
+    title,
+    description: '展示流程、任务、时间线或状态板。',
+    blockType: 'workflow',
+    subType: type,
+    rendererKey,
+    dataShape,
+    defaultSize: 'medium',
+    handlerClassName: `${upperFirst(type)}WorkflowCardAbility`,
+  })),
+  ...['customerDetail', 'projectDetail', 'contractDetail', 'supplierDetail', 'assetDetail', 'ticketDetail'].map((type) => entry({
+    capabilityId: `card.entity.${type}`,
+    category: 'card.entity_cards',
+    type,
+    title: `${type} 详情卡`,
+    description: '业务对象详情卡。',
+    blockType: 'display',
+    subType: 'customCanvas',
+    rendererKey: 'customCanvas',
+    dataShape: 'customCanvas',
+    defaultSize: 'medium',
+    handlerClassName: `${upperFirst(type)}EntityCardAbility`,
+  })),
+  ...lifecycleOperations.map((operation) => entry({
+    capabilityId: `card.lifecycle.${operation}`,
+    category: 'card.lifecycle_mutation',
+    type: operation,
+    title: `${operation} 改卡能力`,
+    description: '卡片生命周期改卡能力。',
+    blockType: 'display',
+    subType: 'customCanvas',
+    rendererKey: 'customCanvas',
+    dataShape: 'lifecycleOperation',
+    defaultSize: 'small',
+    handlerClassName: `${upperFirst(operation)}LifecycleHandler`,
+    status: 'lifecycle',
+  })),
+];
+
+export function cardRegistryByCapabilityId(capabilityId: string) {
+  const exact = CARD_REGISTRY.find((entryItem) => entryItem.capabilityId === capabilityId);
+  if (exact?.aliasOf) return CARD_REGISTRY.find((entryItem) => entryItem.capabilityId === exact.aliasOf) || exact;
+  return exact;
+}
+
+export function cardRegistryByKey(input: { category?: string; type?: string; variant?: string }) {
+  return CARD_REGISTRY.find((entryItem) =>
+    (!input.category || entryItem.category === input.category)
+    && (!input.type || entryItem.type === input.type)
+    && (!input.variant || entryItem.variant === input.variant),
+  );
+}
+
+export function resolveCardRegistryEntry(input: { capabilityId?: string; category?: string; type?: string; variant?: string }) {
+  if (input.capabilityId) return cardRegistryByCapabilityId(input.capabilityId);
+  return cardRegistryByKey(input);
+}
+
+export function implementedCardRegistryEntries() {
+  return CARD_REGISTRY.filter((entryItem) => entryItem.status === 'implemented' && !entryItem.aliasOf);
+}

package/node_modules/@fses/workbench-card/src/registry/compositeCardPatterns.ts

@@ -0,0 +1,206 @@
+/**
+ * @fileoverview 图生组合卡片模式库 - 公开复合卡片的布局、数据与问数契约。
+ * @author seadon
+ * @created 2026-05-21
+ */
+
+export type CompositeCardPatternId =
+  | 'asset'
+  | 'project'
+  | 'ops'
+  | 'security'
+  | 'bidCollaboration'
+  | 'businessMetricMatrix'
+  | 'threePanelAnalysis';
+
+export type CompositeCardLayoutRule =
+  | 'source-proportion-first'
+  | 'no-card-internal-scrollbar'
+  | 'no-overlap'
+  | 'fill-card-internal-height';
+
+export interface CompositeCardDataContract {
+  requiredShape: 'customCanvas';
+  requiredFields: string[];
+  nestedBlockKinds: string[];
+  notes: string[];
+}
+
+export interface CompositeCardQueryContract {
+  trigger: 'host-dataBinding-refresh';
+  statusFields: string[];
+  retryEntry: string;
+  readyBoundary: string;
+}
+
+export interface CompositeCardPattern {
+  id: CompositeCardPatternId;
+  capabilityId: `card.composite.${CompositeCardPatternId}`;
+  title: string;
+  scene: string;
+  description: string;
+  rendererKey: 'customCanvas';
+  dataShape: 'customCanvas';
+  defaultSize: 'large';
+  layoutRules: CompositeCardLayoutRule[];
+  dataContract: CompositeCardDataContract;
+  queryContract: CompositeCardQueryContract;
+}
+
+const COMMON_LAYOUT_RULES: CompositeCardLayoutRule[] = [
+  'source-proportion-first',
+  'no-card-internal-scrollbar',
+  'no-overlap',
+  'fill-card-internal-height',
+];
+
+const COMMON_DATA_FIELDS = ['shape', 'nestedBlocks', 'nestedLayoutMode'];
+
+const COMMON_QUERY_CONTRACT: CompositeCardQueryContract = {
+  trigger: 'host-dataBinding-refresh',
+  statusFields: [
+    'nestedBlocks[].dataBindingId',
+    'nestedBlocks[].dataBinding.status',
+    'nestedBlocks[].dataBinding.refreshApi',
+    'nestedBlocks[].dataBinding.queryIntent',
+  ],
+  retryEntry: '宿主识别 business_input / error 后，在待补业务口径清单中执行“补口径并问数”。',
+  readyBoundary: '只有宿主通过真实 dataBinding refreshApi/query 返回数据并完成 setData 合并后，才允许进入 ready/refreshed。',
+};
+
+/**
+ * Creates a reusable composite-card pattern with the shared image-compose rules.
+ * @param pattern - Pattern-specific metadata and nested kind hints.
+ * @returns Composite-card pattern contract exported by the card library.
+ */
+function compositePattern(pattern: Omit<CompositeCardPattern, 'layoutRules' | 'queryContract'>): CompositeCardPattern {
+  return {
+    ...pattern,
+    layoutRules: [...COMMON_LAYOUT_RULES],
+    queryContract: { ...COMMON_QUERY_CONTRACT, statusFields: [...COMMON_QUERY_CONTRACT.statusFields] },
+  };
+}
+
+export const WORKBENCH_COMPOSITE_CARD_PATTERNS: CompositeCardPattern[] = [
+  compositePattern({
+    id: 'asset',
+    capabilityId: 'card.composite.asset',
+    title: '资产与成本组合卡片',
+    scene: 'CIO / IT 资产、成本、License、预算执行看板。',
+    description: '用于承载资产台账、成本分析、资产异常和成本优化等多区域信息。',
+    rendererKey: 'customCanvas',
+    dataShape: 'customCanvas',
+    defaultSize: 'large',
+    dataContract: {
+      requiredShape: 'customCanvas',
+      requiredFields: [...COMMON_DATA_FIELDS],
+      nestedBlockKinds: ['metric', 'donut', 'simpleList'],
+      notes: ['nestedBlocks 保留每个子卡的 dataBinding 状态。', '成本/资产子区应填满父卡高度，避免底部大块空白。'],
+    },
+  }),
+  compositePattern({
+    id: 'project',
+    capabilityId: 'card.composite.project',
+    title: '项目与效能组合卡片',
+    scene: '数字化项目、研发效能、待办审批、快捷入口看板。',
+    description: '用于还原重点项目进度、个人待办、研发运维效能和快捷入口的组合区域。',
+    rendererKey: 'customCanvas',
+    dataShape: 'customCanvas',
+    defaultSize: 'large',
+    dataContract: {
+      requiredShape: 'customCanvas',
+      requiredFields: [...COMMON_DATA_FIELDS],
+      nestedBlockKinds: ['progressList', 'todoGrid', 'quickLinks', 'simpleList'],
+      notes: ['优先使用 stack/grid 子布局，不把密集项目面板压成绝对定位小条。', '短面板内按钮和待办入口保持可点击。'],
+    },
+  }),
+  compositePattern({
+    id: 'ops',
+    capabilityId: 'card.composite.ops',
+    title: '运维稳定组合卡片',
+    scene: '基础设施、服务监控、资源负载、故障告警看板。',
+    description: '用于还原服务状态、资源条、近七日趋势和故障告警中心。',
+    rendererKey: 'customCanvas',
+    dataShape: 'customCanvas',
+    defaultSize: 'large',
+    dataContract: {
+      requiredShape: 'customCanvas',
+      requiredFields: [...COMMON_DATA_FIELDS],
+      nestedBlockKinds: ['statusList', 'resourceBars', 'incidentList', 'chart'],
+      notes: ['资源条按父卡可用高度伸展。', '故障/告警列表用轻量状态行，避免遮挡其他区域。'],
+    },
+  }),
+  compositePattern({
+    id: 'security',
+    capabilityId: 'card.composite.security',
+    title: '安全合规组合卡片',
+    scene: '安全健康、账号权限、合规审计、风险项看板。',
+    description: '用于还原安全评分、风险列表、账号权限和审计合规区域。',
+    rendererKey: 'customCanvas',
+    dataShape: 'customCanvas',
+    defaultSize: 'large',
+    dataContract: {
+      requiredShape: 'customCanvas',
+      requiredFields: [...COMMON_DATA_FIELDS],
+      nestedBlockKinds: ['securityScore', 'simpleList'],
+      notes: ['安全评分可以是视觉预览，但 dataBinding 未成功前不能标记为 ready。', '风险项失败时保留可补口径状态。'],
+    },
+  }),
+  compositePattern({
+    id: 'bidCollaboration',
+    capabilityId: 'card.composite.bidCollaboration',
+    title: '标案协同角色工作台组合卡',
+    scene: '销售、生产、采购、物流、仓储、财务等角色围绕目标标案协同判断的截图工作台。',
+    description: '用于还原标案目标信息、供产采储运财关键表格、风险确认和角色结论建议等多区域组合卡。',
+    rendererKey: 'customCanvas',
+    dataShape: 'customCanvas',
+    defaultSize: 'large',
+    dataContract: {
+      requiredShape: 'customCanvas',
+      requiredFields: [...COMMON_DATA_FIELDS],
+      nestedBlockKinds: ['metric', 'table', 'simpleList', 'summary'],
+      notes: ['父 customCanvas 保留源图比例和 nestedBlocks 层级，避免把角色工作台拆成大量顶层卡。', '截图/OCR 行只作为视觉预览；子卡真实问数失败时继续保留 business_input/error 补口径入口。'],
+    },
+  }),
+  compositePattern({
+    id: 'threePanelAnalysis',
+    capabilityId: 'card.composite.threePanelAnalysis',
+    title: '三卡嵌套分析布局',
+    scene: '用户问数指定左柱状图、右上折线图、右下指标卡的三卡嵌套分析布局。',
+    description: '用于一张 customCanvas 父卡承载三张可独立问数和拖拽的子卡，左侧柱状图占满高度，右侧上下分别为折线图和指标卡。',
+    rendererKey: 'customCanvas',
+    dataShape: 'customCanvas',
+    defaultSize: 'large',
+    dataContract: {
+      requiredShape: 'customCanvas',
+      requiredFields: [...COMMON_DATA_FIELDS],
+      nestedBlockKinds: ['bar', 'line', 'metric'],
+      notes: ['父卡必须使用 grid nestedLayoutMode。', '三张子卡各自保留 dataBinding 与 business_input 补口径入口，真实 query/setData 成功前不得标记 ready。'],
+    },
+  }),
+  compositePattern({
+    id: 'businessMetricMatrix',
+    capabilityId: 'card.composite.businessMetricMatrix',
+    title: '业务指标矩阵组合卡片',
+    scene: '营销、经营、组织等混合 KPI + 趋势 + 列表的截图面板。',
+    description: '用于短面板里同时承载多个 KPI、趋势缩略图和业务动态列表。',
+    rendererKey: 'customCanvas',
+    dataShape: 'customCanvas',
+    defaultSize: 'large',
+    dataContract: {
+      requiredShape: 'customCanvas',
+      requiredFields: [...COMMON_DATA_FIELDS],
+      nestedBlockKinds: ['metric', 'chart', 'list'],
+      notes: ['KPI tile 使用一行紧凑格，数字不撑高父行。', '图表缩略预览只作为视觉密度，真实数值以 query/setData 为准。'],
+    },
+  }),
+];
+
+/**
+ * Resolves one composite-card pattern by id.
+ * @param id - Composite-card pattern id.
+ * @returns Matching pattern, or undefined when the id is unknown.
+ */
+export function compositeCardPatternById(id: string): CompositeCardPattern | undefined {
+  return WORKBENCH_COMPOSITE_CARD_PATTERNS.find((pattern) => pattern.id === id);
+}