@veltra/sheet 2.1.1 → 2.3.0

package/src/components/report/use-report-designer.ts

@@ -0,0 +1,596 @@
+import type { CellAddress } from '@veltra/sheet-core'
+import type { ResolveCellRenderer, ResolveCellStyleHook } from '@veltra/sheet-core'
+import { Workbook } from '@veltra/sheet-core'
+import { computed, onScopeDispose, ref, watch, type ComputedRef, type Ref } from 'vue'
+
+import {
+  REPORT_META_NAMESPACE,
+  applyReportPreset,
+  createReportBinding,
+  formatCellAddress,
+  inferDropPreset,
+  inferParentsForPreset,
+  isColGroupBinding,
+  isHorizontalExpandBinding,
+  isRowGroupBinding,
+  isVerticalExpandBinding,
+  listColParentCandidates,
+  listRowParentCandidates,
+  prefersGroupParent,
+  presetStillApplies
+} from '../../report/binding'
+import type { DataConnection, QueryResult, Result } from '../../report/connector'
+import { buildParamDefs } from '../../report/params'
+import {
+  assertCompatibleTemplateVersion,
+  createReportTemplate,
+  getTemplateDatasets,
+  resolveParamDefaults,
+  type ReportDatasetDef,
+  type ReportTemplate
+} from '../../report/template'
+import type { DatasetCatalogItem, DatasetField, ReportBinding } from '../../report/types'
+import type { ReportDesignerProps } from '../../types'
+import { createBindingBadgeRenderer, createBindingBadgeStyleResolver } from './binding-badge'
+import type { TopologyBindingEntry } from './designer/topology'
+
+/**
+ * 设计器内部数据集：以 `connectionId` 引用连接（连接列表经 `v-model:connections`
+ * 注入，是单一事实源）；`getTemplate()` 吐出模板时解析为内嵌连接对象（`ReportDatasetDef`）。
+ */
+export interface DesignerDataset {
+  id: string
+  label: string
+  connectionId: string
+  sql: string
+  /** 参数元数据覆盖（label / 类型 / 默认值 / 选项） */
+  paramOverrides?: ReportDatasetDef['paramOverrides']
+  /** 字段中文名覆盖（name → label） */
+  fieldOverrides?: ReportDatasetDef['fieldOverrides']
+  /** describe 解析的字段缓存（字段面板 catalog 的数据源；fieldOverrides 在 catalog 层应用） */
+  fields?: DatasetField[]
+}
+
+/** 数据中枢 drawer 的消费面（`UseReportDesignerReturn` 的子集） */
+export interface DatasetHubController {
+  connections: Ref<DataConnection[]>
+  datasets: Ref<DesignerDataset[]>
+  addConnection: (connection: DataConnection) => void
+  updateConnection: (connection: DataConnection) => void
+  /** 删除连接并级联删除其数据集 */
+  removeConnection: (connectionId: string) => void
+  addDataset: (connectionId: string) => DesignerDataset
+  updateDataset: (datasetId: string, patch: Partial<Omit<DesignerDataset, 'id'>>) => void
+  removeDataset: (datasetId: string) => void
+  /** 真实测试连接（契约无状态，新建草稿同样可测） */
+  testConnection: (connection: DataConnection) => Promise<Result<void>>
+  /** 经连接器 describe 解析字段并写入数据集字段缓存 */
+  describeDataset: (datasetId: string) => Promise<Result<DatasetField[]>>
+  /** 按参数默认值经连接器取数（数据集记录预览） */
+  previewDataset: (datasetId: string) => Promise<Result<QueryResult>>
+}
+
+export type ParentPickMode = 'row' | 'col'
+
+export interface ParentPickState {
+  mode: ParentPickMode
+  source: CellAddress
+}
+
+export interface UseReportDesignerReturn extends DatasetHubController {
+  workbook: ComputedRef<Workbook>
+  /** 字段面板目录（数据集 + 应用 fieldOverrides 后的字段 label） */
+  catalog: ComputedRef<DatasetCatalogItem[]>
+  /** 已绑定字段键集合：`${datasetId}:${fieldName}` */
+  boundKeys: ComputedRef<Set<string>>
+  /** 当前选区地址（跟随模型 selection-change） */
+  activeCell: Ref<CellAddress | null>
+  /** 当前选区 A1 标签 */
+  selectionLabel: ComputedRef<string>
+  /** 当前选区绑定（跟随 meta-change） */
+  activeBinding: ComputedRef<ReportBinding | undefined>
+  /** 当前选区绑定字段的数据类型（条件规则对话框控件映射用；缺省 number） */
+  activeFieldType: ComputedRef<DatasetField['type']>
+  /** 当前绑定所属数据集的字段列表（条件规则求值字段选择） */
+  activeDatasetFields: ComputedRef<DatasetField[]>
+  /** 当前选区绑定的行方向父格 A1 标签（无父格显示 —） */
+  resolvedRowParentLabel: ComputedRef<string>
+  /** 当前选区绑定的列方向父格 A1 标签（无父格显示 —） */
+  resolvedColParentLabel: ComputedRef<string>
+  /** 父格点选态（进入后在网格上点目标格写入父格） */
+  parentPick: Ref<ParentPickState | null>
+  /** 行方向父格下拉候选（同数据集纵向扩展绑定格） */
+  rowParentCandidates: ComputedRef<CellAddress[]>
+  /** 列方向父格下拉候选（同数据集横向扩展绑定格） */
+  colParentCandidates: ComputedRef<CellAddress[]>
+  /** 全部绑定条目（拓扑连线数据源；跟随 meta-change） */
+  bindingEntries: ComputedRef<TopologyBindingEntry[]>
+  /** meta 变更计数（网格覆层组件的同步信号） */
+  metaTick: Ref<number>
+  getBindingAt: (addr: CellAddress) => ReportBinding | undefined
+  /** 字段 label 解析（catalog O(1) 查找；Action Pill 摘要与徽章共用） */
+  resolveFieldLabel: (datasetId: string, fieldName: string) => string
+  /** 拖拽/点击落格写 Cell Meta 绑定（角色推导与 playground 设计器一致） */
+  bindField: (datasetId: string, fieldName: string, addr?: CellAddress) => void
+  /** 就地修补当前选区绑定（Action Pill：预设 / 展开方向 / 父格 / 聚合 / 排序 / 条件规则） */
+  patchActiveBinding: (patch: Partial<ReportBinding>) => void
+  /** 进入父格点选态 */
+  startParentPick: (mode: ParentPickMode) => void
+  /** 取消父格点选态 */
+  cancelParentPick: () => void
+  /** 父格点选：将目标格写入当前编辑格的 rowParent / colParent */
+  pickParentAt: (target: CellAddress) => void
+  /** 清除行 / 列方向父格 */
+  clearParent: (mode: ParentPickMode) => void
+  /** 清除当前选区绑定 */
+  removeActiveBinding: () => void
+  /** 绑定格角色底色样式 hook（与徽章 renderer 配套） */
+  resolveCellStyle: ResolveCellStyleHook
+  /** 绑定格角色徽章渲染 hook（ADR-0004） */
+  resolveCellRenderer: ResolveCellRenderer
+  /** 取回含 meta 绑定与内嵌数据集定义的 Report Template */
+  getTemplate: () => ReportTemplate
+}
+
+export interface UseReportDesignerOptions {
+  props: ReportDesignerProps
+  /** `v-model:connections` 可写代理（get 读 props，set 触发 `update:connections`） */
+  connections: Ref<DataConnection[]>
+}
+
+/**
+ * UReportDesigner 的 headless 编排：连接 / 数据集状态、绑定写 Cell Meta、
+ * 角色徽章渲染 hook、`getTemplate()` 模板吐出。不持有 DOM / 网格引用。
+ */
+export function useReportDesigner(options: UseReportDesignerOptions): UseReportDesignerReturn {
+  const { props, connections } = options
+
+  /** 设计态工作簿：宿主可注入（USheet / UReportViewer 先例），缺省内部自建 */
+  const internalWorkbook = new Workbook()
+  const workbook = computed(() => props.workbook ?? internalWorkbook)
+
+  const datasets = ref<DesignerDataset[]>([])
+
+  /** meta 变更计数：boundKeys 等派生状态的响应式触发（绑定经命令系统写入后由模型发 meta-change） */
+  const metaTick = ref(0)
+  const parentPick = ref<ParentPickState | null>(null)
+  const offMeta = workbook.value.activeSheet.on('meta-change', () => {
+    metaTick.value++
+  })
+  onScopeDispose(offMeta)
+
+  /** 稳定选区地址引用（值未变时不替换对象，避免触发下游 watcher） */
+  const activeCell = ref<CellAddress | null>(null)
+  function syncActiveCell(): void {
+    const next = workbook.value.activeSheet.getSelection().activeCell ?? null
+    const prev = activeCell.value
+    if (!next) {
+      activeCell.value = null
+      return
+    }
+    if (prev && prev.row === next.row && prev.col === next.col) return
+    activeCell.value = { row: next.row, col: next.col }
+  }
+  const offSelection = workbook.value.activeSheet.on('selection-change', syncActiveCell)
+  onScopeDispose(offSelection)
+  syncActiveCell()
+
+  const selectionLabel = computed(() =>
+    activeCell.value ? formatCellAddress(activeCell.value) : '—'
+  )
+
+  const catalog = computed((): DatasetCatalogItem[] =>
+    datasets.value.map((dataset) => ({
+      id: dataset.id,
+      label: dataset.label,
+      fields: (dataset.fields ?? []).map((field) => ({
+        ...field,
+        label: dataset.fieldOverrides?.[field.name]?.label ?? field.label
+      }))
+    }))
+  )
+
+  /** 字段 label 的 O(1) 查找表（徽章 hook 性能契约） */
+  const fieldLabelMap = computed(() => {
+    const map = new Map<string, string>()
+    for (const dataset of catalog.value) {
+      for (const field of dataset.fields) map.set(`${dataset.id}:${field.name}`, field.label)
+    }
+    return map
+  })
+
+  function resolveFieldLabel(datasetId: string, fieldName: string): string {
+    return fieldLabelMap.value.get(`${datasetId}:${fieldName}`) ?? fieldName
+  }
+
+  const boundKeys = computed(() => {
+    metaTick.value
+    const keys = new Set<string>()
+    for (const [, namespace, payload] of workbook.value.activeSheet.entriesCellMeta()) {
+      if (namespace !== REPORT_META_NAMESPACE) continue
+      const binding = payload as ReportBinding
+      keys.add(`${binding.dataset}:${binding.field}`)
+    }
+    return keys
+  })
+
+  function getBindingAt(addr: CellAddress): ReportBinding | undefined {
+    return workbook.value.activeSheet.getCellMeta<ReportBinding>(addr, REPORT_META_NAMESPACE)
+  }
+
+  function bindField(datasetId: string, fieldName: string, addr?: CellAddress): void {
+    const dataset = catalog.value.find((item) => item.id === datasetId)
+    if (!dataset) return
+
+    const field = dataset.fields.find((item) => item.name === fieldName)
+    const target = addr ?? workbook.value.activeSheet.getSelection().activeCell
+    if (!target) return
+
+    const preset = inferDropPreset(target, field?.type ?? 'string', getBindingAt)
+    let binding = createReportBinding(dataset, fieldName)
+    binding = applyReportPreset(binding, preset)
+
+    const parents = inferParentsForPreset(target, preset, getBindingAt)
+    if (parents.rowParent) binding.rowParent = parents.rowParent
+    if (parents.colParent) binding.colParent = parents.colParent
+
+    workbook.value.activeSheet.setCellMeta(target, REPORT_META_NAMESPACE, binding)
+  }
+
+  // ---- Action Pill / 拓扑连线（playground 设计器平移，行为不变） ----
+
+  const activeBinding = computed((): ReportBinding | undefined => {
+    metaTick.value
+    const cell = activeCell.value
+    if (!cell) return undefined
+    return getBindingAt(cell)
+  })
+
+  const activeFieldType = computed((): DatasetField['type'] => {
+    const binding = activeBinding.value
+    if (!binding) return 'number'
+    const dataset = catalog.value.find((item) => item.id === binding.dataset)
+    const field = dataset?.fields.find((item) => item.name === binding.field)
+    return field?.type ?? 'number'
+  })
+
+  const activeDatasetFields = computed((): DatasetField[] => {
+    const binding = activeBinding.value
+    if (!binding) return []
+    return catalog.value.find((item) => item.id === binding.dataset)?.fields ?? []
+  })
+
+  const resolvedRowParentLabel = computed(() => {
+    metaTick.value
+    const binding = activeBinding.value
+    if (!binding?.rowParent) return '—'
+    return formatCellAddress(binding.rowParent)
+  })
+
+  const resolvedColParentLabel = computed(() => {
+    metaTick.value
+    const binding = activeBinding.value
+    if (!binding?.colParent) return '—'
+    return formatCellAddress(binding.colParent)
+  })
+
+  const rowParentCandidates = computed((): CellAddress[] => {
+    metaTick.value
+    const binding = activeBinding.value
+    if (!binding) return []
+    return listRowParentCandidates(binding, bindingEntries.value, {
+      preferGroup: prefersGroupParent(binding)
+    })
+  })
+
+  const colParentCandidates = computed((): CellAddress[] => {
+    metaTick.value
+    const binding = activeBinding.value
+    if (!binding) return []
+    return listColParentCandidates(binding, bindingEntries.value, {
+      preferGroup: prefersGroupParent(binding)
+    })
+  })
+
+  const bindingEntries = computed((): TopologyBindingEntry[] => {
+    metaTick.value
+    const entries: TopologyBindingEntry[] = []
+    for (const [addr, namespace, payload] of workbook.value.activeSheet.entriesCellMeta()) {
+      if (namespace !== REPORT_META_NAMESPACE) continue
+      entries.push({ addr, binding: payload as ReportBinding })
+    }
+    return entries
+  })
+
+  function parentNeedsCorrection(addr: CellAddress | undefined): boolean {
+    if (!addr) return true
+    const parent = getBindingAt(addr)
+    return !parent || parent.aggregate === 'list'
+  }
+
+  function patchActiveBinding(patch: Partial<ReportBinding>): void {
+    const cell = activeCell.value
+    const binding = activeBinding.value
+    if (!cell || !binding) return
+
+    const next: ReportBinding = { ...binding, ...patch }
+    if ('rowParent' in patch && patch.rowParent === undefined) delete next.rowParent
+    if ('colParent' in patch && patch.colParent === undefined) delete next.colParent
+    if (
+      ('aggregate' in patch || 'expand' in patch) &&
+      !('preset' in patch) &&
+      !presetStillApplies(next)
+    ) {
+      delete next.preset
+    }
+
+    if (patch.preset === 'subtotal') {
+      const inferred = inferParentsForPreset(cell, 'subtotal', getBindingAt)
+      if (parentNeedsCorrection(next.rowParent)) {
+        if (inferred.rowParent) next.rowParent = inferred.rowParent
+        else delete next.rowParent
+      }
+      if (parentNeedsCorrection(next.colParent)) {
+        if (inferred.colParent) next.colParent = inferred.colParent
+        else delete next.colParent
+      }
+    }
+
+    workbook.value.activeSheet.setCellMeta(cell, REPORT_META_NAMESPACE, next)
+  }
+
+  function startParentPick(mode: ParentPickMode): void {
+    const cell = activeCell.value
+    if (!cell || !activeBinding.value) return
+    parentPick.value = { mode, source: { row: cell.row, col: cell.col } }
+  }
+
+  function cancelParentPick(): void {
+    parentPick.value = null
+  }
+
+  function isValidParentTarget(
+    mode: ParentPickMode,
+    source: ReportBinding,
+    target: ReportBinding | undefined
+  ): boolean {
+    if (!target) return false
+    if (target.dataset !== source.dataset) return false
+    const groupOnly = prefersGroupParent(source)
+    if (mode === 'row') {
+      return groupOnly ? isRowGroupBinding(target) : isVerticalExpandBinding(target)
+    }
+    return groupOnly ? isColGroupBinding(target) : isHorizontalExpandBinding(target)
+  }
+
+  function pickParentAt(target: CellAddress): void {
+    const pick = parentPick.value
+    if (!pick) return
+    if (target.row === pick.source.row && target.col === pick.source.col) return
+
+    const sourceBinding = getBindingAt(pick.source)
+    if (!sourceBinding) {
+      parentPick.value = null
+      return
+    }
+
+    const targetBinding = getBindingAt(target)
+    if (!isValidParentTarget(pick.mode, sourceBinding, targetBinding)) {
+      workbook.value.activeSheet.selectCell(pick.source)
+      return
+    }
+
+    const patch = pick.mode === 'row' ? { rowParent: { ...target } } : { colParent: { ...target } }
+    const next: ReportBinding = { ...sourceBinding, ...patch }
+    workbook.value.activeSheet.setCellMeta(pick.source, REPORT_META_NAMESPACE, next)
+    parentPick.value = null
+    workbook.value.activeSheet.selectCell(pick.source)
+  }
+
+  function clearParent(mode: ParentPickMode): void {
+    if (mode === 'row') patchActiveBinding({ rowParent: undefined })
+    else patchActiveBinding({ colParent: undefined })
+  }
+
+  function removeActiveBinding(): void {
+    const cell = activeCell.value
+    if (!cell) return
+    workbook.value.activeSheet.clearCellMeta(cell, REPORT_META_NAMESPACE)
+  }
+
+  // ---- 数据中枢：连接 / 数据集 CRUD 与连接器调用 ----
+
+  function addConnection(connection: DataConnection): void {
+    connections.value = [...connections.value, connection]
+  }
+
+  function updateConnection(connection: DataConnection): void {
+    connections.value = connections.value.map((item) =>
+      item.id === connection.id ? connection : item
+    )
+  }
+
+  function removeConnection(connectionId: string): void {
+    connections.value = connections.value.filter((item) => item.id !== connectionId)
+    // 级联删除其数据集（playground 设计器平移）
+    datasets.value = datasets.value.filter((dataset) => dataset.connectionId !== connectionId)
+  }
+
+  let datasetSeq = 0
+  function addDataset(connectionId: string): DesignerDataset {
+    const dataset: DesignerDataset = {
+      id: `dataset-${Date.now()}-${datasetSeq++}`,
+      label: '新数据集',
+      connectionId,
+      sql: ''
+    }
+    datasets.value = [...datasets.value, dataset]
+    return dataset
+  }
+
+  function updateDataset(datasetId: string, patch: Partial<Omit<DesignerDataset, 'id'>>): void {
+    datasets.value = datasets.value.map((item) =>
+      item.id === datasetId ? { ...item, ...patch } : item
+    )
+  }
+
+  function removeDataset(datasetId: string): void {
+    datasets.value = datasets.value.filter((item) => item.id !== datasetId)
+  }
+
+  function resolveDatasetConnection(dataset: DesignerDataset): DataConnection | undefined {
+    return connections.value.find((item) => item.id === dataset.connectionId)
+  }
+
+  function datasetNotFound(): Result<never> {
+    return { ok: false, error: { code: 'DATASET_NOT_FOUND', message: '数据集不存在' } }
+  }
+
+  function connectionNotFound(): Result<never> {
+    return { ok: false, error: { code: 'CONNECTION_NOT_FOUND', message: '数据集所属连接不存在' } }
+  }
+
+  function testConnection(connection: DataConnection): Promise<Result<void>> {
+    return props.connector.test(connection)
+  }
+
+  async function describeDataset(datasetId: string): Promise<Result<DatasetField[]>> {
+    const dataset = datasets.value.find((item) => item.id === datasetId)
+    if (!dataset) return datasetNotFound()
+    const connection = resolveDatasetConnection(dataset)
+    if (!connection) return connectionNotFound()
+
+    const sql = dataset.sql
+    const result = await props.connector.describe(connection, sql)
+    // 并发守卫：describe 返回时 SQL 已再变更则丢弃过期结果
+    if (result.ok) {
+      const current = datasets.value.find((item) => item.id === datasetId)
+      if (current && current.sql === sql) updateDataset(datasetId, { fields: result.data })
+    }
+    return result
+  }
+
+  async function previewDataset(datasetId: string): Promise<Result<QueryResult>> {
+    const dataset = datasets.value.find((item) => item.id === datasetId)
+    if (!dataset) return datasetNotFound()
+    const connection = resolveDatasetConnection(dataset)
+    if (!connection) return connectionNotFound()
+
+    const values = resolveParamDefaults(buildParamDefs(dataset.sql, dataset.paramOverrides))
+    return props.connector.query(connection, dataset.sql, values)
+  }
+
+  // ---- 渲染与模板 ----
+
+  const resolveCellStyle = createBindingBadgeStyleResolver(getBindingAt)
+  const resolveCellRenderer = createBindingBadgeRenderer(getBindingAt, resolveFieldLabel)
+
+  function getTemplate(): ReportTemplate {
+    const resolved: ReportDatasetDef[] = datasets.value.flatMap((dataset) => {
+      const connection = resolveDatasetConnection(dataset)
+      if (!connection) return []
+      return [
+        {
+          id: dataset.id,
+          label: dataset.label,
+          connection: { ...connection },
+          sql: dataset.sql,
+          ...(dataset.paramOverrides ? { paramOverrides: dataset.paramOverrides } : {}),
+          ...(dataset.fieldOverrides ? { fieldOverrides: dataset.fieldOverrides } : {})
+        }
+      ]
+    })
+    // `Sheet.snapshot()` 不产生 datasets 字段（restore 往返会丢失），吐出时附加内嵌数据集定义
+    return createReportTemplate(workbook.value.activeSheet.snapshot(), resolved)
+  }
+
+  /**
+   * 载入既有 Report Template 继续设计（`template` prop）：
+   * 快照恢复网格绑定（restore + restoreContent 与查看器同路径）；
+   * 内嵌数据集定义还原为设计态（connectionId 引用），内嵌连接按 id 合并进
+   * v-model 连接列表（仅缺省追加，宿主列表是单一事实源）；
+   * describe 恢复字段缓存（字段面板数据源），业务错误忽略（字段留空，可在数据中枢重试）。
+   */
+  function loadTemplate(template: ReportTemplate): void {
+    assertCompatibleTemplateVersion(template)
+    const sheet = workbook.value.activeSheet
+    sheet.restore(template)
+    sheet.restoreContent(template)
+    sheet.history.clear()
+    syncActiveCell()
+
+    const defs = getTemplateDatasets(template)
+    datasets.value = defs.map((def) => ({
+      id: def.id,
+      label: def.label,
+      connectionId: def.connection.id,
+      sql: def.sql,
+      ...(def.paramOverrides ? { paramOverrides: def.paramOverrides } : {}),
+      ...(def.fieldOverrides ? { fieldOverrides: def.fieldOverrides } : {})
+    }))
+
+    const missing = defs
+      .map((def) => def.connection)
+      .filter((connection) => !connections.value.some((item) => item.id === connection.id))
+    if (missing.length > 0) {
+      connections.value = [
+        ...connections.value,
+        ...missing.map((connection) => ({ ...connection }))
+      ]
+    }
+
+    for (const dataset of datasets.value) {
+      if (dataset.sql.trim()) void describeDataset(dataset.id)
+    }
+  }
+
+  // 模板更换：重新载入（仅在提供了 template 时；缺省为空白设计态）
+  watch(
+    () => props.template,
+    (template) => {
+      if (template) loadTemplate(template)
+    },
+    { immediate: true }
+  )
+
+  return {
+    workbook,
+    connections,
+    datasets,
+    catalog,
+    boundKeys,
+    activeCell,
+    selectionLabel,
+    activeBinding,
+    activeFieldType,
+    activeDatasetFields,
+    resolvedRowParentLabel,
+    resolvedColParentLabel,
+    parentPick,
+    rowParentCandidates,
+    colParentCandidates,
+    bindingEntries,
+    metaTick,
+    getBindingAt,
+    resolveFieldLabel,
+    bindField,
+    patchActiveBinding,
+    startParentPick,
+    cancelParentPick,
+    pickParentAt,
+    clearParent,
+    removeActiveBinding,
+    resolveCellStyle,
+    resolveCellRenderer,
+    getTemplate,
+    addConnection,
+    updateConnection,
+    removeConnection,
+    addDataset,
+    updateDataset,
+    removeDataset,
+    testConnection,
+    describeDataset,
+    previewDataset
+  }
+}

package/src/components/report/use-report-viewer.ts

@@ -0,0 +1,88 @@
+import type { SheetSnapshot } from '@veltra/sheet-core'
+import { computed, ref, shallowRef, watch, type ComputedRef, type Ref, type ShallowRef } from 'vue'
+
+import type { ConnectorError } from '../../report/connector'
+import type { ReportColWidthEntry } from '../../report/export-xlsx'
+import { renderReport, resolveFilledColWidths } from '../../report/render'
+import {
+  fetchTemplateRecords,
+  resolveParamDefaults,
+  resolveTemplateParams
+} from '../../report/template'
+import type { ParamValues, QueryParamDef } from '../../report/types'
+import type { ReportViewerProps } from '../../types'
+
+export interface UseReportViewerReturn {
+  /** Filter Bar 参数（模板实际绑定的数据集的查询参数并集） */
+  params: ComputedRef<QueryParamDef[]>
+  /** 当前运行时参数值（初始为参数默认值） */
+  values: Ref<ParamValues>
+  /** 取数中 */
+  loading: Ref<boolean>
+  /** 最近一次取数的业务错误（可读提示；成功或重新取数时清空） */
+  error: ShallowRef<ConnectorError | null>
+  /** 最近一次成功展开渲染的 Filled Report 快照（组件壳据此替换网格内容） */
+  filledSnapshot: ShallowRef<SheetSnapshot | null>
+  /** 展开后物理列宽（由模板 colWidths 映射；无模板列宽时为 undefined） */
+  filledColWidths: ShallowRef<ReadonlyArray<ReportColWidthEntry> | undefined>
+  /** 重新取数并展开渲染 */
+  refresh: () => Promise<void>
+  /** Filter Bar 改值：写入新参数值并重新取数 */
+  setValues: (next: ParamValues) => void
+}
+
+/**
+ * UReportViewer 的 headless 编排：参数提取 → 取数 → renderReport 展开。
+ * 不持有 DOM / 网格引用；填充快照经 `filledSnapshot` 交给组件壳应用。
+ */
+export function useReportViewer(props: ReportViewerProps): UseReportViewerReturn {
+  const loading = ref(false)
+  const error = shallowRef<ConnectorError | null>(null)
+  const filledSnapshot = shallowRef<SheetSnapshot | null>(null)
+  const filledColWidths = shallowRef<ReadonlyArray<ReportColWidthEntry> | undefined>(undefined)
+
+  const params = computed(() => resolveTemplateParams(props.template))
+  // 初始值由下方 immediate watch 播种（参数默认值）
+  const values = shallowRef<ParamValues>({})
+
+  // 并发守卫：只应用最后一次取数结果（Filter Bar 连续改值时前序结果作废）
+  let fetchSeq = 0
+
+  async function refresh(): Promise<void> {
+    const current = ++fetchSeq
+    const template = props.template
+    loading.value = true
+    error.value = null
+    const result = await fetchTemplateRecords(props.connector, template, values.value)
+    if (current !== fetchSeq) return
+    loading.value = false
+    if (!result.ok) {
+      error.value = result.error
+      filledColWidths.value = undefined
+      return
+    }
+    filledSnapshot.value = renderReport(template, result.data)
+    filledColWidths.value = template.colWidths?.length
+      ? resolveFilledColWidths(template, result.data, template.colWidths)
+      : undefined
+  }
+
+  function setValues(next: ParamValues): void {
+    values.value = next
+    void refresh()
+  }
+
+  // 模板更换：清空上一模板的填充结果，参数值重置为新模板默认值并重新取数
+  watch(
+    () => props.template,
+    () => {
+      filledSnapshot.value = null
+      filledColWidths.value = undefined
+      values.value = resolveParamDefaults(params.value)
+      void refresh()
+    },
+    { immediate: true }
+  )
+
+  return { params, values, loading, error, filledSnapshot, filledColWidths, refresh, setValues }
+}