@fses/workbench-app 0.2.0 → 0.2.2

package/node_modules/@fses/workbench-card/src/renderers/chart/echarts-protocol/converters/series.converter.ts

@@ -0,0 +1,795 @@
+/**
+ * @fileoverview Series 协议转换器 - 将笛卡尔/径向图表协议数据转换为 ECharts option
+ * @author seadon
+ * @created 2026-05-05
+ */
+
+import type { EChartsOption } from 'echarts';
+
+import type {
+  ProtocolConfigPayload,
+  ProtocolConverter,
+  ProtocolDataPayload,
+} from '../types';
+
+interface NormalizedSeriesItem {
+  id?: string;
+  name: string;
+  typeHint?: string;
+  data: unknown[];
+}
+
+interface NormalizedSeriesPayload {
+  categories: string[];
+  indicators: Array<{ name: string; max?: number }>;
+  series: NormalizedSeriesItem[];
+}
+
+const WORKBENCH_METRIC_ROW_CONTEXT_KEY = '__workbenchMetricRowContext';
+
+/**
+ * 判断给定值是否为可读取字段的普通对象。
+ * @param value - 待判断的值
+ * @returns 当值为非数组对象时返回 true
+ */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * 将数组型标签数据统一转换为字符串数组。
+ * @param value - 候选标签数组
+ * @returns 规范化后的标签列表
+ */
+function toStringLabels(value: unknown): string[] {
+  return Array.isArray(value) ? value.map((item) => String(item ?? '')) : [];
+}
+
+/**
+ * 规范化系列值，保留 ECharts 已支持的对象型 data item。
+ * @param value - 原始系列值
+ * @returns 可传给 ECharts series.data 的值
+ */
+function normalizeSeriesValue(value: unknown): unknown {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'string' && value.trim()) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : value;
+  }
+  if (isRecord(value) && 'value' in value) {
+    const rawValue = value.value;
+    const parsedValue = typeof rawValue === 'string' && rawValue.trim()
+      ? Number(rawValue)
+      : rawValue;
+    return {
+      ...value,
+      value: typeof parsedValue === 'number' && Number.isFinite(parsedValue)
+        ? parsedValue
+        : rawValue,
+    };
+  }
+  return value;
+}
+
+/**
+ * 从 canonical 或 dataset 包裹的协议数据中读取类目标签。
+ * @param source - 协议数据对象或其中的 dataset 对象
+ * @returns 主类目轴标签
+ */
+function readCategories(source: Record<string, unknown>): string[] {
+  const categories = source.categories;
+  if (Array.isArray(categories)) return toStringLabels(categories);
+  if (isRecord(categories)) return toStringLabels(categories.xAxis);
+
+  const xAxis = source.xAxis;
+  if (Array.isArray(xAxis)) return toStringLabels(xAxis);
+  if (isRecord(xAxis)) return toStringLabels(xAxis.data);
+
+  return [];
+}
+
+/**
+ * Reads radar indicators from protocol categories.
+ * @param source - Protocol data object or dataset object.
+ * @returns Radar indicator definitions accepted by ECharts.
+ */
+function readRadarIndicators(source: Record<string, unknown>): Array<{ name: string; max?: number }> {
+  const categories = source.categories;
+  if (!isRecord(categories) || !Array.isArray(categories.indicators)) return [];
+  return categories.indicators
+    .filter(isRecord)
+    .map((item) => {
+      const name = typeof item.name === 'string' && item.name.trim() ? item.name.trim() : '';
+      const max = typeof item.max === 'number' && Number.isFinite(item.max) ? item.max : undefined;
+      return name ? { name, ...(max === undefined ? {} : { max }) } : null;
+    })
+    .filter((item): item is { name: string; max?: number } => Boolean(item));
+}
+
+/**
+ * 从协议数据中读取系列数组。
+ * @param source - 协议数据对象或其中的 dataset 对象
+ * @returns 规范化后的系列列表
+ */
+function readSeries(source: Record<string, unknown>): NormalizedSeriesItem[] {
+  const series = source.series;
+  if (!Array.isArray(series)) return [];
+
+  return series.filter(isRecord).map((item, index) => {
+    const id = typeof item.id === 'string' && item.id.trim() ? item.id.trim() : undefined;
+    const name = typeof item.name === 'string' && item.name.trim()
+      ? item.name.trim()
+      : id || `series-${index + 1}`;
+    const typeHint = typeof item.typeHint === 'string' && item.typeHint.trim()
+      ? item.typeHint.trim()
+      : typeof item.type === 'string' && item.type.trim()
+        ? item.type.trim()
+        : undefined;
+    const data = Array.isArray(item.data) ? item.data.map(normalizeSeriesValue) : [];
+
+    return { id, name, typeHint, data };
+  });
+}
+
+/**
+ * Reads runtime metric row contexts from protocol data metadata.
+ * @param sources - Protocol data candidates.
+ * @returns Row contexts aligned with rendered category rows.
+ */
+function readMetricRowContexts(...sources: Array<Record<string, unknown> | undefined>): Record<string, unknown>[] {
+  for (const source of sources) {
+    if (!source) continue;
+    const extension = isRecord(source.extension) ? source.extension : undefined;
+    const metricContext = isRecord(source.metric_context)
+      ? source.metric_context
+      : isRecord(extension?.metric_context)
+        ? extension.metric_context
+        : undefined;
+    const rowContexts = metricContext?.row_contexts;
+    if (Array.isArray(rowContexts)) return rowContexts.filter(isRecord);
+  }
+  return [];
+}
+
+/**
+ * Preserves a stable row-context pointer on ECharts data items.
+ * @param value - Series data value.
+ * @param rowContext - Runtime metric row context for the same category.
+ * @returns ECharts data item with internal workbench metadata.
+ */
+function withMetricRowContext(value: unknown, rowContext: Record<string, unknown> | undefined): unknown {
+  if (!rowContext) return value;
+  if (isRecord(value)) return { ...value, [WORKBENCH_METRIC_ROW_CONTEXT_KEY]: rowContext };
+  return { value, [WORKBENCH_METRIC_ROW_CONTEXT_KEY]: rowContext };
+}
+
+/**
+ * Attaches row contexts to every rendered series by category index.
+ * @param series - Normalized runtime series.
+ * @param rowContexts - Row contexts from protocol metadata.
+ * @returns Series with data items carrying stable metric row identity.
+ */
+function attachMetricRowContexts(
+  series: NormalizedSeriesItem[],
+  rowContexts: Record<string, unknown>[],
+): NormalizedSeriesItem[] {
+  if (rowContexts.length === 0) return series;
+  return series.map((item) => ({
+    ...item,
+    data: item.data.map((value, index) => withMetricRowContext(value, rowContexts[index])),
+  }));
+}
+
+/**
+ * Normalizes series protocol data while preserving runtime metric row identity.
+ * @param data - Raw protocol data received by setData.
+ * @returns Categories, indicators, and renderable series values.
+ */
+function normalizeSeriesPayload(data: ProtocolDataPayload): NormalizedSeriesPayload {
+  const payload: Record<string, unknown> = isRecord(data) ? data : {};
+  const dataset = isRecord(payload.dataset) ? payload.dataset : undefined;
+  const categorySource = dataset && readCategories(dataset).length > 0 ? dataset : payload;
+  const seriesSource = dataset && readSeries(dataset).length > 0 ? dataset : payload;
+  const rowContexts = readMetricRowContexts(payload, dataset);
+
+  return {
+    categories: readCategories(categorySource),
+    indicators: readRadarIndicators(categorySource),
+    series: attachMetricRowContexts(readSeries(seriesSource), rowContexts),
+  };
+}
+
+/**
+ * 判断某个 series option 是否为饼图系列。
+ * @param seriesDef - ECharts series 配置片段
+ * @returns 当 series 类型为 pie 时返回 true
+ */
+function isPieSeries(seriesDef: Record<string, unknown>): boolean {
+  return seriesDef.type === 'pie';
+}
+
+/**
+ * 判断某个 series option 是否为雷达图系列。
+ * @param seriesDef - ECharts series 配置片段
+ * @returns 当 series 类型为 radar 时返回 true
+ */
+function isRadarSeries(seriesDef: Record<string, unknown>): boolean {
+  return seriesDef.type === 'radar';
+}
+
+/**
+ * 判断某个 series option 是否为漏斗图系列。
+ * @param seriesDef - ECharts series 配置片段
+ * @returns 当 series 类型为 funnel 时返回 true
+ */
+function isFunnelSeries(seriesDef: Record<string, unknown>): boolean {
+  return seriesDef.type === 'funnel';
+}
+
+/**
+ * 判断 option 中是否包含饼图系列。
+ * @param option - 当前 ECharts option
+ * @returns 当任意系列为 pie 时返回 true
+ */
+function optionHasPieSeries(option: EChartsOption): boolean {
+  const series = (option as Record<string, unknown>).series;
+  return Array.isArray(series) && series.some((item) => isRecord(item) && isPieSeries(item));
+}
+
+/**
+ * 判断 option 中是否包含雷达图系列。
+ * @param option - 当前 ECharts option
+ * @returns 当任意系列为 radar 时返回 true
+ */
+function optionHasRadarSeries(option: EChartsOption): boolean {
+  const series = (option as Record<string, unknown>).series;
+  return Array.isArray(series) && series.some((item) => isRecord(item) && isRadarSeries(item));
+}
+
+/**
+ * 判断 option 中是否包含漏斗图系列。
+ * @param option - 当前 ECharts option
+ * @returns 当任意系列为 funnel 时返回 true
+ */
+function optionHasFunnelSeries(option: EChartsOption): boolean {
+  const series = (option as Record<string, unknown>).series;
+  return Array.isArray(series) && series.some((item) => isRecord(item) && isFunnelSeries(item));
+}
+
+/**
+ * 判断颜色值是否为透明色。
+ * @param value - 待判断的颜色值
+ * @returns 透明色返回 true
+ */
+function isTransparentColor(value: unknown): boolean {
+  const normalized = typeof value === 'string' ? value.trim().toLowerCase().replace(/\s+/gu, '') : '';
+  return normalized === 'transparent'
+    || normalized === 'rgba(0,0,0,0)'
+    || normalized === 'rgba(255,255,255,0)';
+}
+
+/**
+ * 判断 series option 是否为瀑布图透明占位柱。
+ * @param seriesDef - 候选 series option
+ * @returns 透明占位柱返回 true
+ */
+function isWaterfallHelperSeries(seriesDef: Record<string, unknown>): boolean {
+  if (seriesDef.type !== 'bar' || typeof seriesDef.stack !== 'string') return false;
+  const itemStyle = isRecord(seriesDef.itemStyle) ? seriesDef.itemStyle : {};
+  const emphasis = isRecord(seriesDef.emphasis) ? seriesDef.emphasis : {};
+  const emphasisItemStyle = isRecord(emphasis.itemStyle) ? emphasis.itemStyle : {};
+  return isTransparentColor(itemStyle.color)
+    || isTransparentColor(itemStyle.borderColor)
+    || isTransparentColor(emphasisItemStyle.color)
+    || isTransparentColor(emphasisItemStyle.borderColor);
+}
+
+/**
+ * 将 series 值转换为瀑布图基线计算所需的数值。
+ * @param value - 运行时 series 单项值
+ * @returns 有效数值，无效时返回 0
+ */
+function waterfallNumber(value: unknown): number {
+  const raw = isRecord(value) && 'value' in value ? value.value : value;
+  const parsed = typeof raw === 'string' && raw.trim() ? Number(raw) : raw;
+  return typeof parsed === 'number' && Number.isFinite(parsed) ? Math.max(0, parsed) : 0;
+}
+
+/**
+ * 计算瀑布图透明 helper 的累计基线。
+ * @param values - 可见柱体数值
+ * @returns helper series 数据
+ */
+function waterfallHelperValues(values: unknown[]): number[] {
+  let cumulative = 0;
+  return values.map((value, index) => {
+    const baseline = index === 0 ? 0 : cumulative;
+    cumulative += waterfallNumber(value);
+    return baseline;
+  });
+}
+
+/**
+ * 为旧瀑布图协议把单条真实 series 映射到可见柱体，同时给透明 helper 填充基线。
+ * @param optionSeries - 当前 ECharts series option
+ * @param runtimeSeries - 运行时真实 series 数据
+ * @returns 已修复的瀑布图 series；不适用时返回 undefined
+ */
+function mergeLegacyWaterfallSeries(
+  optionSeries: unknown[],
+  runtimeSeries: NormalizedSeriesItem[],
+): Array<Record<string, unknown>> | undefined {
+  if (runtimeSeries.length !== 1) return undefined;
+  const seriesOptions = optionSeries.filter(isRecord);
+  if (seriesOptions.length !== optionSeries.length) return undefined;
+  const helperIndex = seriesOptions.findIndex(isWaterfallHelperSeries);
+  if (helperIndex < 0) return undefined;
+  const helper = seriesOptions[helperIndex];
+  const helperStack = typeof helper.stack === 'string' ? helper.stack : undefined;
+  const visibleIndex = seriesOptions.findIndex((item, index) => (
+    index !== helperIndex
+    && item.type === 'bar'
+    && typeof item.stack === 'string'
+    && item.stack === helperStack
+    && !isWaterfallHelperSeries(item)
+  ));
+  if (visibleIndex < 0) return undefined;
+
+  const runtime = runtimeSeries[0];
+  return seriesOptions.map((seriesDef, index) => {
+    if (index === helperIndex) {
+      return {
+        ...seriesDef,
+        data: waterfallHelperValues(runtime.data),
+      };
+    }
+    if (index === visibleIndex) {
+      return {
+        ...seriesDef,
+        data: runtime.data,
+        name: runtime.name,
+      };
+    }
+    return seriesDef;
+  });
+}
+
+/**
+ * 保留图例已有样式，仅补充图例展示项。
+ * @param option - 待更新的 ECharts option
+ * @param names - 图例名称列表
+ */
+function applyLegendData(option: EChartsOption, names: string[]): void {
+  if (names.length === 0) return;
+
+  const mutable = option as Record<string, unknown>;
+  const legend = mutable.legend;
+
+  if (Array.isArray(legend)) {
+    mutable.legend = legend.map((item, index) => (
+      index === 0 && isRecord(item) ? { ...item, data: names } : item
+    ));
+    return;
+  }
+
+  if (legend === false) return;
+  mutable.legend = isRecord(legend) ? { ...legend, data: names } : { data: names };
+}
+
+/**
+ * 保留 x 轴已有样式，仅补充类目数据。
+ * @param option - 待更新的 ECharts option
+ * @param categories - x 轴类目标签
+ */
+function applyXAxisData(option: EChartsOption, categories: string[]): void {
+  const mutable = option as Record<string, unknown>;
+  const xAxis = mutable.xAxis;
+
+  if (Array.isArray(xAxis)) {
+    mutable.xAxis = xAxis.map((axis, index) => (
+      index === 0 && isRecord(axis) ? { ...axis, data: categories } : axis
+    ));
+    return;
+  }
+
+  if (isRecord(xAxis)) {
+    mutable.xAxis = { ...xAxis, data: categories };
+  }
+}
+
+/**
+ * 判断 x 轴配置是否为时间轴。
+ * @param axis - 候选 xAxis 配置。
+ * @returns 时间轴返回 true。
+ */
+function isTimeAxis(axis: unknown): axis is Record<string, unknown> {
+  return isRecord(axis) && axis.type === 'time';
+}
+
+/**
+ * 判断 option 是否包含时间 x 轴。
+ * @param option - 当前 ECharts option。
+ * @returns 包含时间 x 轴返回 true。
+ */
+function optionHasTimeXAxis(option: EChartsOption): boolean {
+  const xAxis = (option as Record<string, unknown>).xAxis;
+  return Array.isArray(xAxis) ? xAxis.some(isTimeAxis) : isTimeAxis(xAxis);
+}
+
+/**
+ * 判断类目标签是否可以作为 ECharts time 轴值。
+ * @param value - 类目标签。
+ * @returns 时间类目返回 true。
+ */
+function isTimeLikeCategory(value: string): boolean {
+  const text = value.trim();
+  if (!text) return false;
+  if (/^\d{10,13}$/u.test(text)) return true;
+  if (!/(?:^\d{4}(?:[-/]\d{1,2})?|T\d{2}:\d{2}|\d{1,2}:\d{2})/u.test(text)) return false;
+  return Number.isFinite(Date.parse(text));
+}
+
+/**
+ * 判断所有运行时类目是否都适合 time 轴。
+ * @param categories - 运行时类目标签。
+ * @returns 全部为时间类目返回 true。
+ */
+function hasRuntimeTimeCategories(categories: string[]): boolean {
+  return categories.length > 0 && categories.every(isTimeLikeCategory);
+}
+
+/**
+ * 对运行时 x 轴类型做归一化，避免非时间类目被 time 轴解析成 1970。
+ * @param option - 当前 ECharts option。
+ * @param categories - 运行时类目标签。
+ * @returns 运行时 x 轴类型。
+ */
+function applyRuntimeXAxisData(option: EChartsOption, categories: string[]): 'time' | 'category' {
+  if (!optionHasTimeXAxis(option)) {
+    applyXAxisData(option, categories);
+    return 'category';
+  }
+  if (hasRuntimeTimeCategories(categories)) {
+    applyTimeXAxis(option);
+    return 'time';
+  }
+  applyCategoryXAxis(option, categories);
+  return 'category';
+}
+
+/**
+ * 保留官方 time 轴配置，但移除 category 轴专用 data。
+ * @param option - 当前 ECharts option。
+ */
+function applyTimeXAxis(option: EChartsOption): void {
+  const mutable = option as Record<string, unknown>;
+  const xAxis = mutable.xAxis;
+  const normalize = (axis: unknown): unknown => {
+    if (!isRecord(axis)) return axis;
+    const { data: _data, ...rest } = axis;
+    return { ...rest, type: 'time' };
+  };
+  mutable.xAxis = Array.isArray(xAxis) ? xAxis.map(normalize) : normalize(xAxis);
+}
+
+/**
+ * 将不兼容的 time 轴模板降级为 category 轴以展示真实分类标签。
+ * @param option - 当前 ECharts option。
+ * @param categories - 运行时类目标签。
+ */
+function applyCategoryXAxis(option: EChartsOption, categories: string[]): void {
+  const mutable = option as Record<string, unknown>;
+  const xAxis = mutable.xAxis;
+  const normalize = (axis: unknown, index = 0): unknown => (
+    index === 0 && isRecord(axis) ? { ...axis, type: 'category', data: categories } : axis
+  );
+  mutable.xAxis = Array.isArray(xAxis)
+    ? xAxis.map((axis, index) => normalize(axis, index))
+    : isRecord(xAxis)
+      ? normalize(xAxis)
+      : { type: 'category', data: categories };
+}
+
+/**
+ * 将 time 轴类目与数值配对成 ECharts time series 数据。
+ * @param series - 匹配到的运行时 series。
+ * @param categories - 时间类目标签。
+ * @returns `[time, value]` 数据项列表。
+ */
+function buildTimeAxisData(series: NormalizedSeriesItem, categories: string[]): unknown[] {
+  return series.data.map((value, index) => {
+    const pointValue = isRecord(value) && 'value' in value ? value.value : value;
+    if (isRecord(value)) return { ...value, value: [categories[index], pointValue] };
+    return [categories[index], value];
+  });
+}
+
+/**
+ * 将类目和数值序列转换为饼图需要的 name/value 切片。
+ * @param series - 匹配到的协议系列数据
+ * @param categories - 切片名称来源
+ * @returns ECharts pie series.data
+ */
+function buildPieData(series: NormalizedSeriesItem, categories: string[]): unknown[] {
+  if (series.data.every(isRecord)) {
+    return series.data.map((item, index) => ({
+      ...item,
+      name: typeof item.name === 'string' && item.name.trim()
+        ? item.name.trim()
+        : categories[index] || series.name || `item-${index + 1}`,
+      value: 'value' in item ? item.value : 0,
+    }));
+  }
+
+  return series.data.map((value, index) => ({
+    name: categories[index] || `item-${index + 1}`,
+    value,
+  }));
+}
+
+/**
+ * 将类目和数值序列转换为漏斗图需要的 name/value 阶段数据。
+ * @param series - 匹配到的协议系列数据
+ * @param categories - 漏斗阶段名称来源
+ * @returns ECharts funnel series.data
+ */
+function buildFunnelData(series: NormalizedSeriesItem, categories: string[]): unknown[] {
+  return buildPieData(series, categories);
+}
+
+/**
+ * Converts a radar series into the single-polygon data shape expected by ECharts.
+ * @param series - Matched protocol series.
+ * @returns Radar series data.
+ */
+function buildRadarData(series: NormalizedSeriesItem): unknown[] {
+  return [{
+    name: series.name,
+    value: series.data.map((value) => {
+      const rawValue = isRecord(value) && 'value' in value ? value.value : value;
+      const parsed = typeof rawValue === 'string' && rawValue.trim() ? Number(rawValue) : rawValue;
+      return typeof parsed === 'number' && Number.isFinite(parsed) ? parsed : 0;
+    }),
+  }];
+}
+
+/**
+ * 读取对象型展示配置，忽略后端 boolean 简写。
+ * @param value - presentation 中的配置值
+ * @returns 可合入 ECharts option 的对象配置
+ */
+function presentationObject(value: unknown): Record<string, unknown> {
+  return isRecord(value) ? value : {};
+}
+
+/**
+ * Series 协议转换器，处理标准笛卡尔坐标系和径向坐标系图表。
+ */
+export const seriesConverter: ProtocolConverter = {
+  /**
+   * 根据协议配置构建 ECharts option 骨架。
+   * @param config - 协议配置载荷，包含系列定义和展示配置
+   * @returns 包含标题、提示框、图例、坐标轴和空系列的 ECharts option
+   */
+  buildOption(config: ProtocolConfigPayload): EChartsOption {
+    const hasPieSeries = config.series.some((def) => def.type === 'pie');
+    const hasRadarSeries = config.series.some((def) => def.type === 'radar');
+    const hasFunnelSeries = config.series.some((def) => def.type === 'funnel');
+
+    if (hasPieSeries) {
+      const pieOption: EChartsOption = {
+        title: {
+          text: config.chart.title,
+        },
+        tooltip: {
+          trigger: 'item',
+          ...presentationObject(config.presentation.tooltip),
+        },
+        legend: presentationObject(config.presentation.legend),
+        series: config.series.map((def) => ({
+          id: def.id,
+          type: def.type,
+          radius: ['42%', '68%'],
+          data: [],
+        })) as any[],
+      };
+
+      if (config.optionPatch) {
+        Object.assign(pieOption, config.optionPatch);
+      }
+
+      return pieOption;
+    }
+
+    if (hasRadarSeries) {
+      const radarOption: EChartsOption = {
+        title: {
+          text: config.chart.title,
+        },
+        tooltip: {
+          trigger: 'item',
+          ...presentationObject(config.presentation.tooltip),
+        },
+        legend: presentationObject(config.presentation.legend),
+        radar: {
+          indicator: [],
+          radius: '68%',
+        },
+        series: config.series.map((def) => ({
+          id: def.id,
+          type: def.type,
+          data: [],
+        })) as any[],
+      };
+
+      if (config.optionPatch) {
+        Object.assign(radarOption, config.optionPatch);
+      }
+
+      return radarOption;
+    }
+
+    if (hasFunnelSeries) {
+      const funnelOption: EChartsOption = {
+        title: {
+          text: config.chart.title,
+        },
+        tooltip: {
+          trigger: 'item',
+          ...presentationObject(config.presentation.tooltip),
+        },
+        legend: presentationObject(config.presentation.legend),
+        series: config.series.map((def) => ({
+          id: def.id,
+          type: def.type,
+          data: [],
+        })) as any[],
+      };
+
+      if (config.optionPatch) {
+        Object.assign(funnelOption, config.optionPatch);
+      }
+
+      return funnelOption;
+    }
+
+    const option: EChartsOption = {
+      title: {
+        text: config.chart.title,
+      },
+      tooltip: {
+        trigger: 'axis',
+        ...presentationObject(config.presentation.tooltip),
+      },
+      legend: presentationObject(config.presentation.legend),
+      xAxis: {
+        type: 'category',
+      },
+      yAxis: {
+        type: 'value',
+      },
+      // SeriesDef.type 为通用 string，需断言为 any 以满足 ECharts SeriesOption 字面量联合类型。
+      series: config.series.map((def) => ({
+        id: def.id,
+        type: def.type,
+        data: [],
+      })) as any[],
+    };
+
+    if (config.optionPatch) {
+      Object.assign(option, config.optionPatch);
+    }
+
+    return option;
+  },
+
+  /**
+   * 将数据载荷合并到已有的 ECharts option 中。
+   * @param option - 已有的 ECharts option
+   * @param data - 协议数据载荷，包含类别和系列数值
+   * @returns 更新后的 ECharts option
+   */
+  mergeData(option: EChartsOption, data: ProtocolDataPayload): EChartsOption {
+    const seriesData = normalizeSeriesPayload(data);
+    const merged = { ...option };
+    const isPieChart = optionHasPieSeries(merged);
+    const isRadarChart = optionHasRadarSeries(merged);
+    const isFunnelChart = optionHasFunnelSeries(merged);
+    let cartesianXAxisKind: 'time' | 'category' = 'category';
+
+    if (!isPieChart && !isRadarChart && !isFunnelChart) {
+      cartesianXAxisKind = applyRuntimeXAxisData(merged, seriesData.categories);
+    }
+
+    if (Array.isArray(merged.series)) {
+      const legacyWaterfallSeries = !isPieChart && !isRadarChart && !isFunnelChart
+        ? mergeLegacyWaterfallSeries(merged.series, seriesData.series)
+        : undefined;
+      merged.series = legacyWaterfallSeries ?? merged.series.map((s, index) => {
+        const seriesDef = s as Record<string, unknown>;
+        const seriesId = (seriesDef.id as string) || `series-${index + 1}`;
+        const matched = seriesData.series.find(
+          (item) => item.id === seriesId,
+        ) || seriesData.series[index];
+
+        if (!matched) return seriesDef;
+
+        if (isPieSeries(seriesDef)) {
+          return {
+            ...seriesDef,
+            data: buildPieData(matched, seriesData.categories),
+            name: matched.name,
+          };
+        }
+
+        if (isRadarSeries(seriesDef)) {
+          return {
+            ...seriesDef,
+            data: buildRadarData(matched),
+            name: matched.name,
+          };
+        }
+
+        if (isFunnelSeries(seriesDef)) {
+          return {
+            ...seriesDef,
+            data: buildFunnelData(matched, seriesData.categories),
+            name: matched.name,
+          };
+        }
+
+        return {
+          ...seriesDef,
+          data: cartesianXAxisKind === 'time'
+            ? buildTimeAxisData(matched, seriesData.categories)
+            : matched.data,
+          name: matched.name,
+        };
+      });
+    }
+
+    if (isPieChart) {
+      const mutable = merged as Record<string, unknown>;
+      delete mutable.xAxis;
+      delete mutable.yAxis;
+      const pieLegendData = Array.isArray(merged.series)
+        ? merged.series.flatMap((item) => (
+          isRecord(item) && Array.isArray(item.data)
+            ? item.data.filter(isRecord).flatMap((slice) => (
+              typeof slice.name === 'string' && slice.name.trim() ? [slice.name.trim()] : []
+            ))
+            : []
+        ))
+        : [];
+      applyLegendData(merged, pieLegendData);
+    } else if (isRadarChart) {
+      const mutable = merged as Record<string, unknown>;
+      delete mutable.xAxis;
+      delete mutable.yAxis;
+      const radar = mutable.radar;
+      mutable.radar = isRecord(radar)
+        ? { ...radar, indicator: seriesData.indicators }
+        : { indicator: seriesData.indicators };
+      applyLegendData(
+        merged,
+        seriesData.series.flatMap((item) => (item.name ? [item.name] : [])),
+      );
+    } else if (isFunnelChart) {
+      const mutable = merged as Record<string, unknown>;
+      delete mutable.xAxis;
+      delete mutable.yAxis;
+      delete mutable.grid;
+      applyLegendData(
+        merged,
+        seriesData.series.flatMap((item) => (item.name ? [item.name] : [])),
+      );
+    } else {
+      applyLegendData(
+        merged,
+        seriesData.series.flatMap((item) => (item.name ? [item.name] : [])),
+      );
+    }
+
+    return merged;
+  },
+};