@fses/workbench-app 0.1.3 → 0.2.1

package/node_modules/@fses/workbench-card/src/renderers/chart/ChartRegistry.vue

@@ -0,0 +1,221 @@
+<script setup lang="ts">
+import { computed, ref, shallowRef, watch } from 'vue';
+import type { DisplayBlockData, EchartsScriptData, RoleId } from '@fses/workbench-card/types';
+import { buildDynamicEchartOption, normalizeDynamicEchartFieldMapping } from './dynamicEchartOption';
+import { hideDuplicateEchartsTitle } from './echartsTitle';
+import type { WorkbenchChartRefreshRuntime } from './types';
+import { chartNarrative, chartTheme, optionFromWorkbenchData, prepareWorkbenchChartOption, useEchart, type WorkbenchEchartClickParams } from './useEchart';
+
+const props = withDefaults(defineProps<{
+  rendererKey: string;
+  data: DisplayBlockData;
+  cardTitle?: string;
+  roleId?: RoleId | string;
+  userId?: string;
+  density?: 'thumbnail' | 'compact' | 'standard' | 'expanded';
+  blockMeta?: Record<string, unknown>;
+  blockSource?: unknown;
+  refreshRuntime?: WorkbenchChartRefreshRuntime;
+}>(), {
+  density: 'expanded',
+});
+
+const emit = defineEmits<{
+  chartClick: [payload: WorkbenchEchartClickParams];
+}>();
+
+const chartEl = ref<HTMLElement | null>(null);
+const renderError = ref('');
+const option = shallowRef<ReturnType<typeof optionFromWorkbenchData>>(null);
+const script = shallowRef<EchartsScriptData | null>(null);
+const theme = shallowRef<string | undefined>();
+
+const narrative = computed(() => props.density === 'expanded' ? chartNarrative(props.data) : undefined);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+function objectValue(value: unknown, key: string) {
+  return isRecord(value) ? value[key] : undefined;
+}
+
+/**
+ * Builds the full refresh-policy context for dynamic ECharts cards.
+ * @param data - Current renderer data carrying the data-binding metadata.
+ * @returns Context with renderer data plus block-level V2 image provenance.
+ */
+function refreshPolicyContext(data: DisplayBlockData) {
+  return {
+    data,
+    meta: props.blockMeta,
+    source: props.blockSource,
+    sourceType: objectValue(props.blockSource, 'sourceType'),
+    suppressImageComposeAutoRefresh: imageComposeBackfillIsActive(),
+  };
+}
+
+/**
+ * 判断当前页面是否仍在图片编排 SSE 回填期间。
+ * @returns 处于接收、识别、文档生成、逐卡回填或本页刚完成阶段时返回 true。
+ */
+function imageComposeBackfillIsActive(): boolean {
+  return Boolean(props.refreshRuntime?.isImageComposeBackfillActive?.());
+}
+
+function dynamicFieldMapping(dataBinding: unknown) {
+  const fieldMapping = objectValue(dataBinding, 'fieldMapping');
+  return normalizeDynamicEchartFieldMapping({
+    xField: objectValue(dataBinding, 'xField') ?? objectValue(fieldMapping, 'xField'),
+    yFields: objectValue(dataBinding, 'yFields') ?? objectValue(fieldMapping, 'yFields'),
+  });
+}
+
+/**
+ * Extracts the binding id from dynamic ECharts renderer data.
+ * @param data - Current dynamic ECharts card data.
+ * @returns Binding id from direct or nested metadata.
+ */
+function dynamicDataBindingId(data: DisplayBlockData): string {
+  const directId = objectValue(data, 'dataBindingId');
+  if (typeof directId === 'string' && directId.trim()) return directId.trim();
+  const bindingId = objectValue(objectValue(data, 'dataBinding'), 'bindingId');
+  if (typeof bindingId === 'string' && bindingId.trim()) return bindingId.trim();
+  const canonicalId = objectValue(objectValue(data, 'dataBinding'), 'id');
+  return typeof canonicalId === 'string' ? canonicalId.trim() : '';
+}
+
+/**
+ * Returns the role scope used for refresh and stale-binding repair.
+ * @returns Active renderer role with a stable fallback.
+ */
+function currentRoleId(): RoleId | '' {
+  return (props.roleId || props.refreshRuntime?.roleId || '') as RoleId | '';
+}
+
+/**
+ * Returns the active user id supplied by the iframe entry context.
+ * @returns Current user id, or an empty string when absent.
+ */
+function currentUserId(): string {
+  return props.userId?.trim() || props.refreshRuntime?.userId?.trim() || '';
+}
+
+/**
+ * Reads supplemental wording saved on a refreshed data binding.
+ * @param dataBinding - Data-binding metadata.
+ * @returns Saved business wording when present.
+ */
+function dataBindingBusinessWording(dataBinding: unknown): string | undefined {
+  if (!dataBinding || typeof dataBinding !== 'object' || Array.isArray(dataBinding)) return undefined;
+  const record = dataBinding as Record<string, unknown>;
+  const wording = record.supplementalBusinessWording;
+  if (typeof wording === 'string' && wording.trim()) return wording.trim();
+  const originalWording = record.originalSupplementalBusinessWording;
+  return typeof originalWording === 'string' && originalWording.trim() ? originalWording.trim() : undefined;
+}
+
+watch(
+  () => [props.rendererKey, props.data, props.cardTitle, props.blockMeta, props.blockSource, currentRoleId(), props.refreshRuntime?.conversationId] as const,
+  async ([rendererKey, data, cardTitle]) => {
+    try {
+      renderError.value = '';
+      const nextScript = data.shape === 'echartsScript' ? data : null;
+      let nextOption = optionFromWorkbenchData(rendererKey, data);
+      if (data.shape === 'echartsDynamic') {
+        const refreshRuntime = props.refreshRuntime;
+        const refreshApi = refreshRuntime?.refreshApi(data.dataBinding) || '';
+        if (refreshRuntime?.shouldAutoRefresh(data.dataBinding, refreshPolicyContext(data))) {
+          const bindingId = dynamicDataBindingId(data);
+          if (refreshRuntime.claimAutoRefresh && !refreshRuntime.claimAutoRefresh({
+            bindingId,
+            refreshApi,
+            renderer: 'dynamic-echarts',
+            roleId: currentRoleId(),
+          })) return;
+          if (bindingId) refreshRuntime.markRefreshStatus?.(bindingId, 'running');
+          const result = await refreshRuntime.queryDataBinding({
+            userId: currentUserId(),
+            roleId: currentRoleId(),
+            conversationId: refreshRuntime.conversationId,
+          }, refreshApi, { businessWording: dataBindingBusinessWording(data.dataBinding) });
+          refreshRuntime.applyRefreshResult?.(result);
+          if (!result.success) {
+            await refreshRuntime.repairDataBindings?.(
+              { userId: currentUserId(), roleId: currentRoleId() },
+              refreshApi,
+              result,
+            );
+            if (bindingId) {
+              refreshRuntime.markRefreshStatus?.(
+                bindingId,
+                'error',
+                result.errorMessage || result.errorCode || 'Data binding refresh failed',
+              );
+            }
+            throw new Error(result.errorCode || result.errorMessage || '图表数据加载失败');
+          }
+          nextOption = buildDynamicEchartOption(data.optionTemplate, {
+            rows: Array.isArray(result.rows) ? result.rows : [],
+            fieldMapping: dynamicFieldMapping(data.dataBinding),
+          });
+        }
+      }
+      await prepareWorkbenchChartOption(data, nextOption);
+      if (!nextOption && !nextScript && !renderError.value) renderError.value = '该图表类型暂未匹配到 ECharts 配置。';
+      theme.value = chartTheme(data, nextOption);
+      script.value = nextScript;
+      option.value = hideDuplicateEchartsTitle(nextOption, cardTitle);
+    } catch (error) {
+      if (props.data.shape === 'echartsDynamic' && !String((error as Error)?.message || '').includes('DATA_BINDING_NOT_FOUND')) {
+        const refreshRuntime = props.refreshRuntime;
+        const refreshApi = refreshRuntime?.refreshApi(props.data.dataBinding) || '';
+        if (refreshRuntime?.shouldAutoRefresh(props.data.dataBinding, refreshPolicyContext(props.data))) {
+          const bindingId = dynamicDataBindingId(props.data);
+          if (bindingId) {
+            refreshRuntime.markRefreshStatus?.(
+              bindingId,
+              'error',
+              error instanceof Error ? error.message : 'Data binding refresh failed',
+            );
+          }
+          await refreshRuntime.repairDataBindings?.(
+            { userId: currentUserId(), roleId: currentRoleId() },
+            refreshApi,
+            error,
+          );
+        }
+      }
+      theme.value = undefined;
+      script.value = null;
+      option.value = null;
+      renderError.value = error instanceof Error ? error.message : '图表数据格式错误';
+    }
+  },
+  { immediate: true, deep: true },
+);
+
+useEchart(chartEl, option, renderError, theme, script, (payload) => {
+  emit('chartClick', payload);
+});
+</script>
+
+<template>
+  <div class="flex h-full min-h-0 w-full flex-col">
+    <div
+      v-if="renderError"
+      class="flex min-h-0 flex-1 items-center justify-center rounded-md border border-amber-100 bg-amber-50 px-3 py-4 text-center text-xs leading-5 text-amber-800"
+    >
+      {{ renderError }}
+    </div>
+    <div
+      v-else
+      ref="chartEl"
+      class="min-h-0 w-full flex-1"
+      :style="theme === 'dark' ? { backgroundColor: '#000' } : undefined"
+    />
+    <p v-if="narrative" class="shrink-0 px-3 pb-2 text-xs leading-5 text-slate-500">
+      {{ narrative }}
+    </p>
+  </div>
+</template>

package/node_modules/@fses/workbench-card/src/renderers/chart/EChartsProtocolRenderer.vue

@@ -0,0 +1,304 @@
+/**
+ * @fileoverview ECharts protocol renderer - converts protocol config/data
+ * into ECharts options and refreshes bound data through the workbench API.
+ * @author seadon
+ * @created 2026-05-05
+ */
+
+<script setup lang="ts">
+import { onBeforeUnmount, ref, watch, type Ref } from 'vue';
+import type { EChartsOption } from 'echarts';
+import type { DisplayBlockData, RoleId } from '@fses/workbench-card/types';
+import { EChartsProtocolAdapter } from './echarts-protocol';
+import type { ProtocolConfigPayload, ProtocolDataPayload } from './echarts-protocol/types';
+import { hideDuplicateEchartsTitle } from './echartsTitle';
+import type { WorkbenchChartRefreshRuntime } from './types';
+import { chartTheme, prepareWorkbenchChartOption, useEchart, type WorkbenchEchartClickParams } from './useEchart';
+
+const props = defineProps<{
+  configPayload: ProtocolConfigPayload;
+  dataPayload?: ProtocolDataPayload;
+  cardTitle?: string;
+  roleId?: RoleId | string;
+  userId?: string;
+  dataBinding?: {
+    id?: string;
+    bindingId?: string;
+    refreshApi?: string;
+    status?: string;
+    params?: Record<string, unknown>;
+    sourceType?: string;
+  };
+  blockMeta?: Record<string, unknown>;
+  blockSource?: unknown;
+  refreshRuntime?: WorkbenchChartRefreshRuntime;
+}>();
+
+const emit = defineEmits<{
+  chartClick: [payload: WorkbenchEchartClickParams];
+}>();
+
+const chartEl: Ref<HTMLElement | null> = ref(null);
+const optionRef: Ref<EChartsOption | null> = ref(null);
+const errorRef: Ref<string> = ref('');
+const themeRef: Ref<string | undefined> = ref(undefined);
+const adapter = new EChartsProtocolAdapter();
+const remoteDataPayload: Ref<ProtocolDataPayload | undefined> = ref(undefined);
+
+let renderSequence = 0;
+let refreshSequence = 0;
+
+useEchart(chartEl, optionRef, errorRef, themeRef, undefined, (payload) => {
+  emit('chartClick', payload);
+});
+
+/**
+ * Returns the role scope used for refresh and stale-binding repair.
+ * @returns Active renderer role with a stable fallback.
+ */
+function currentRoleId(): RoleId | '' {
+  return (props.roleId || props.refreshRuntime?.roleId || '') as RoleId | '';
+}
+
+/**
+ * Returns the active user id supplied by the iframe entry context.
+ * @returns Current user id, or an empty string when absent.
+ */
+function currentUserId(): string {
+  return props.userId?.trim() || props.refreshRuntime?.userId?.trim() || '';
+}
+
+/**
+ * Selects the latest data source for setData.
+ * @returns API refreshed protocol data first, then snapshot/socket data.
+ */
+function currentDataPayload(): ProtocolDataPayload | undefined {
+  return remoteDataPayload.value || props.dataPayload;
+}
+
+/**
+ * Checks whether a runtime value is a plain record.
+ * @param value - Unknown runtime value.
+ * @returns True when the value can be read as an object map.
+ */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+/**
+ * Reads supplemental wording saved on a refreshed data binding.
+ * @param dataBinding - Data-binding metadata.
+ * @returns Saved business wording when present.
+ */
+function dataBindingBusinessWording(dataBinding: unknown): string | undefined {
+  if (!isRecord(dataBinding)) return undefined;
+  const wording = dataBinding.supplementalBusinessWording;
+  if (typeof wording === 'string' && wording.trim()) return wording.trim();
+  const originalWording = dataBinding.originalSupplementalBusinessWording;
+  return typeof originalWording === 'string' && originalWording.trim() ? originalWording.trim() : undefined;
+}
+
+/**
+ * Reads a property from an object-shaped value.
+ * @param value - Unknown value that may be a record.
+ * @param key - Property name to read.
+ * @returns Property value when the input is a record.
+ */
+function objectValue(value: unknown, key: string) {
+  return isRecord(value) ? value[key] : undefined;
+}
+
+/**
+ * Builds the full refresh-policy context for protocol ECharts cards.
+ * @returns Context with protocol data plus block-level V2 image provenance.
+ */
+function refreshPolicyContext() {
+  return {
+    data: props.dataPayload,
+    meta: props.blockMeta,
+    source: props.blockSource,
+    sourceType: objectValue(props.blockSource, 'sourceType'),
+    suppressImageComposeAutoRefresh: imageComposeBackfillIsActive(),
+  };
+}
+
+/**
+ * 判断当前页面是否仍在图片编排 SSE 回填期间。
+ * @returns 处于接收、识别、文档生成、逐卡回填或本页刚完成阶段时返回 true。
+ */
+function imageComposeBackfillIsActive(): boolean {
+  return Boolean(props.refreshRuntime?.isImageComposeBackfillActive?.());
+}
+
+/**
+ * Resolves the status key for protocol chart data-binding refreshes.
+ * @returns Trimmed binding id from legacy or canonical V2 metadata.
+ */
+function protocolDataBindingId(): string {
+  const bindingId = props.dataBinding?.bindingId;
+  if (typeof bindingId === 'string' && bindingId.trim()) return bindingId.trim();
+  const canonicalId = props.dataBinding?.id;
+  return typeof canonicalId === 'string' ? canonicalId.trim() : '';
+}
+
+/**
+ * 判断刷新接口返回值是否为 ECharts 协议数据，避免原生卡片 payload 混入协议渲染器。
+ * @param value - data-binding refresh 返回的 renderer payload。
+ * @returns 命中协议 payload 时返回 true。
+ */
+function isProtocolDataPayload(value: unknown): value is ProtocolDataPayload {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value) && typeof (value as { protocolType?: unknown }).protocolType === 'string');
+}
+
+/**
+ * 判断刷新接口返回值是否匹配当前图表协议类型。
+ * @param value - data-binding refresh 返回的 renderer payload。
+ * @returns 与当前 config.protocolType 一致时返回 true。
+ */
+function isRefreshProtocolDataPayload(value: unknown): value is ProtocolDataPayload {
+  return isProtocolDataPayload(value) && value.protocolType === props.configPayload.protocolType;
+}
+
+/**
+ * Applies protocol config and protocol data to the ECharts adapter.
+ * @param data - Protocol data returned by snapshot, socket, or refresh API.
+ */
+async function renderProtocolChart(data: ProtocolDataPayload | undefined): Promise<void> {
+  const sequence = ++renderSequence;
+  errorRef.value = '';
+  optionRef.value = null;
+  themeRef.value = undefined;
+
+  try {
+    adapter.setConfig(props.configPayload);
+
+    if (data) {
+      adapter.setData(data);
+    }
+
+    const nextOption = hideDuplicateEchartsTitle(adapter.getOption(), props.cardTitle);
+    const runtimeData = {
+      shape: 'echartsOption',
+      option: nextOption,
+    } as DisplayBlockData;
+    await prepareWorkbenchChartOption(runtimeData, nextOption);
+    if (sequence !== renderSequence) return;
+    themeRef.value = chartTheme(runtimeData, nextOption);
+    optionRef.value = nextOption;
+  } catch (error) {
+    if (sequence !== renderSequence) return;
+    errorRef.value = error instanceof Error
+      ? error.message
+      : '协议图表渲染失败';
+  }
+}
+
+watch(
+  [() => props.configPayload, () => props.dataPayload, () => props.cardTitle, remoteDataPayload],
+  () => {
+    void renderProtocolChart(currentDataPayload());
+  },
+  { immediate: true, deep: true },
+);
+
+watch(
+  () => [props.dataBinding?.refreshApi, props.blockMeta, props.blockSource, currentRoleId(), props.refreshRuntime?.conversationId] as const,
+  async () => {
+    remoteDataPayload.value = undefined;
+
+    const refreshRuntime = props.refreshRuntime;
+    const normalizedRefreshApi = refreshRuntime?.refreshApi(props.dataBinding) || '';
+    if (!refreshRuntime?.shouldAutoRefresh(props.dataBinding, refreshPolicyContext())) return;
+    const sequence = ++refreshSequence;
+
+    try {
+      const bindingId = protocolDataBindingId();
+      if (refreshRuntime.claimAutoRefresh && !refreshRuntime.claimAutoRefresh({
+        bindingId,
+        refreshApi: normalizedRefreshApi,
+        renderer: 'protocol-echarts',
+        roleId: currentRoleId(),
+      })) return;
+      if (bindingId) refreshRuntime.markRefreshStatus?.(bindingId, 'running');
+      const result = await refreshRuntime.queryDataBinding({
+        userId: currentUserId(),
+        roleId: currentRoleId(),
+        conversationId: refreshRuntime.conversationId,
+      }, normalizedRefreshApi, { businessWording: dataBindingBusinessWording(props.dataBinding) });
+      if (sequence !== refreshSequence) return;
+      refreshRuntime.applyRefreshResult?.(result);
+      if (result.success && isRefreshProtocolDataPayload(result.dataPayload)) {
+        remoteDataPayload.value = result.dataPayload;
+        if (bindingId) refreshRuntime.markRefreshStatus?.(bindingId, 'ready');
+      } else if (!result.success) {
+        await refreshRuntime.repairDataBindings?.(
+          { userId: currentUserId(), roleId: currentRoleId() },
+          normalizedRefreshApi,
+          result,
+        );
+        if (bindingId) {
+          refreshRuntime.markRefreshStatus?.(
+            bindingId,
+            'error',
+            result.errorMessage || result.errorCode || 'Data binding refresh failed',
+          );
+        }
+      }
+    } catch (error) {
+      if (sequence !== refreshSequence) return;
+      const bindingId = protocolDataBindingId();
+      if (bindingId) {
+        refreshRuntime.markRefreshStatus?.(
+          bindingId,
+          'error',
+          error instanceof Error ? error.message : 'Data binding refresh failed',
+        );
+      }
+      await refreshRuntime.repairDataBindings?.(
+        { userId: currentUserId(), roleId: currentRoleId() },
+        normalizedRefreshApi,
+        error,
+      );
+      console.warn('[EChartsProtocolRenderer] data binding refresh failed', error);
+    }
+  },
+  { immediate: true },
+);
+
+onBeforeUnmount(() => {
+  renderSequence += 1;
+  refreshSequence += 1;
+});
+</script>
+
+<template>
+  <div class="echarts-protocol-renderer">
+    <div
+      v-if="errorRef"
+      class="rounded-lg border border-amber-200 bg-amber-50 px-4 py-3 text-sm leading-6 text-amber-800"
+    >
+      {{ errorRef }}
+    </div>
+
+    <div
+      v-else
+      ref="chartEl"
+      class="echarts-protocol-chart"
+    />
+  </div>
+</template>
+
+<style scoped>
+.echarts-protocol-renderer {
+  width: 100%;
+  height: 100%;
+  min-height: 0;
+  overflow: hidden;
+}
+
+.echarts-protocol-chart {
+  width: 100%;
+  height: 100%;
+  min-height: 0;
+}
+</style>