@veltra/sheet 2.1.1 → 2.2.0

package/dist/types/report-viewer.d.ts

@@ -0,0 +1,38 @@
+import { ReportColWidthEntry } from "../report/export-xlsx.js";
+import { DataConnector } from "../report/connector.js";
+import { ReportTemplate } from "../report/template.js";
+import "../report/index.js";
+import { DeconstructValue } from "@veltra/utils";
+import { Workbook } from "@veltra/sheet-core/core/workbook";
+//#region src/types/report-viewer.d.ts
+/** 报表查看器组件属性（ADR-0003 决策 2） */
+interface ReportViewerProps {
+  /** 数据连接器（如 `createHttpConnector({ endpoint })`） */
+  connector: DataConnector;
+  /**
+   * 自包含 Report Template（SheetSnapshot + 内嵌数据集定义，见 `ReportTemplate`）：
+   * 查看器据此提取实际绑定数据集的查询参数并集生成 Filter Bar，并经连接器取数展开渲染
+   */
+  template: ReportTemplate;
+  /** 承载填充报表的工作簿（USheet 先例：缺省内部自建单 sheet 工作簿） */
+  workbook?: Workbook;
+  /**
+   * 列宽（sheet-core 列宽未进 SheetSnapshot）：载入填充结果后写入 VTable 运行时，
+   * 供 `exportXlsx()` 读取保真列宽（设计器预览态传入设计态捕获值）
+   */
+  colWidths?: ReadonlyArray<ReportColWidthEntry>;
+}
+/** 在组件内部引用 */
+interface _ReportViewerExposed {
+  /** 重新取数并展开渲染（外部状态变化后主动刷新报表） */
+  refresh: () => Promise<void>;
+  /**
+   * 导出填充报表为 XLSX（取数完成前拒绝；内部读取填充 sheet 与运行时列宽）。
+   * 不内置导出按钮，工具栏由下游决定。
+   */
+  exportXlsx: () => Promise<void>;
+}
+/** 报表查看器组件暴露的方法 */
+type ReportViewerExposed = DeconstructValue<_ReportViewerExposed>;
+//#endregion
+export { ReportViewerExposed, ReportViewerProps, _ReportViewerExposed };

package/dist/types/sheet.d.ts

@@ -1,7 +1,7 @@
 import { SheetContext } from "../tools/context.js";
 import { ComputedRef } from "vue";
 import { DeconstructValue } from "@veltra/utils";
-import { SheetGrid } from "@veltra/sheet-core/grid/sheet-grid";
+import { ResolveCellRenderer, ResolveCellStyleHook, ResolveDisplayValue, SheetGrid } from "@veltra/sheet-core/grid/sheet-grid";
 import { Workbook } from "@veltra/sheet-core/core/workbook";
 import { Sheet } from "@veltra/sheet-core/core/sheet";
 //#region src/types/sheet.d.ts
@@ -13,12 +13,28 @@ interface SheetProps {
   rows?: number;
   /** 渲染列数，默认 26（A..Z） */
   cols?: number;
+  /**
+   * 显示值覆盖（设计态 Binding Placeholder 等）：覆盖 VTable record，不写 CellData.v
+   */
+  resolveDisplayValue?: ResolveDisplayValue;
+  /**
+   * 动态单元格样式：视口渲染时叠加条件样式补丁，不写 CellData.s / StylePool
+   */
+  resolveCellStyle?: ResolveCellStyleHook;
+  /**
+   * 动态单元格渲染（ADR-0004）：视口布局时按格自定义渲染形态（VTable
+   * customLayout，布局构建用 sheet-core 导出的 CustomLayout），返回 undefined
+   * 回落默认渲染；不写模型、不进快照
+   */
+  resolveCellRenderer?: ResolveCellRenderer;
   /** 是否显示工具栏，默认 true */
   showToolbar?: boolean;
   /** 是否显示顶部公式栏（名称框 + fx 输入栏），默认 true */
   showFormulaBar?: boolean;
   /** 是否显示底部 sheet 标签栏，默认 true */
   showTabs?: boolean;
+  /** 只读预览（关闭编辑回写、填充柄等写入口） */
+  readonly?: boolean;
 }
 interface SheetEmits {
   /** 激活 sheet 切换（点击 tab 或宿主调用 workbook.activateSheet） */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veltra/sheet",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "files": [
     "dist",
     "src"
@@ -30,14 +30,12 @@
   "peerDependencies": {
     "@cat-kit/core": ">=1.1.8",
     "@cat-kit/fe": ">=1.1.8",
+    "@veltra/compositions": "^1.5.0",
     "@veltra/desktop": "^1.5.0",
     "@veltra/icons": "^1.5.0",
-    "@veltra/sheet-core": "^2.1.1",
+    "@veltra/sheet-core": "^2.2.0",
     "@veltra/styles": "^1.5.0",
     "@veltra/utils": "^1.5.0",
     "vue": ">=3.5.41"
-  },
-  "devDependencies": {
-    "@visactor/vtable": "^1.26.6"
   }
 }

package/src/components/report/__test__/conditional-rules-helpers.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from 'vitest'
+
+import type { ConditionalRule } from '../../../report/types'
+import {
+  cloneRulesFromDraft,
+  coerceValueForOperator,
+  createDraftItem,
+  defaultRuleValue,
+  initDraftFromRules,
+  operatorsForFieldType,
+  readBetweenValue,
+  resolveEvalFieldType,
+  ruleEvalFieldOptions,
+  RULE_SCOPE_OPTIONS,
+  writeBetweenValue
+} from '../designer/conditional-rules/helpers'
+
+describe('conditional-rules helpers', () => {
+  it('按字段类型返回运算符列表', () => {
+    expect(operatorsForFieldType('number').map((o) => o.value)).toEqual([
+      'gt',
+      'gte',
+      'lt',
+      'lte',
+      'eq',
+      'between'
+    ])
+    expect(operatorsForFieldType('string').map((o) => o.value)).toEqual(['eq', 'contains'])
+  })
+
+  it('运算符切换时重置比较值', () => {
+    expect(coerceValueForOperator('between', 'number', 42)).toEqual([0, 100])
+    expect(coerceValueForOperator('contains', 'string', 42)).toBe('')
+    expect(coerceValueForOperator('gt', 'number', '12')).toBe(12)
+  })
+
+  it('between 读写辅助', () => {
+    const value = defaultRuleValue('between', 'number')
+    expect(readBetweenValue(value, 0, 'number')).toBe(0)
+    expect(readBetweenValue(value, 1, 'number')).toBe(100)
+    expect(writeBetweenValue(value, 1, 250, 'number')).toEqual([0, 250])
+  })
+
+  it('草稿与规则互转保持深拷贝', () => {
+    const rules: ConditionalRule[] = [
+      { operator: 'gt', value: 10, style: { fill: { color: '#FFCCCC' }, font: { bold: true } } }
+    ]
+    const draft = initDraftFromRules(rules, 'number')
+    expect(draft).toHaveLength(1)
+
+    const cloned = cloneRulesFromDraft(draft)
+    expect(cloned[0]).toEqual(rules[0])
+    expect(cloned[0]).not.toBe(rules[0])
+
+    draft[0]!.rule.style.fill!.color = '#000000'
+    expect(rules[0]!.style.fill!.color).toBe('#FFCCCC')
+  })
+
+  it('新建草稿项带默认样式', () => {
+    const item = createDraftItem(undefined, 'string')
+    expect(item.rule.operator).toBe('eq')
+    expect(item.rule.value).toBe('')
+    expect(item.rule.style.fill?.color).toBeTruthy()
+  })
+
+  it('求值字段与作用范围选项', () => {
+    const fields = [
+      { name: 'amount', label: '金额', type: 'number' as const },
+      { name: 'region', label: '地区', type: 'string' as const }
+    ]
+    expect(ruleEvalFieldOptions('amount', fields).map((item) => item.label)).toEqual([
+      '本格字段',
+      '地区'
+    ])
+    expect(RULE_SCOPE_OPTIONS.map((item) => item.label)).toEqual(['本格', '整行'])
+    expect(resolveEvalFieldType({ operator: 'eq', value: '', style: {} }, 'amount', fields)).toBe(
+      'number'
+    )
+    expect(
+      resolveEvalFieldType(
+        { operator: 'eq', value: '', style: {}, field: 'region' },
+        'amount',
+        fields
+      )
+    ).toBe('string')
+  })
+})

package/src/components/report/__test__/field-panel-helpers.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'vitest'
+
+import type { DatasetCatalogItem } from '../../../report/types'
+import {
+  fieldTypeGlyph,
+  filterDatasetsByQuery,
+  formatFieldDragPayload,
+  parseFieldDragPayload
+} from '../field-panel-helpers'
+
+// ---- 内联 fixtures ----
+
+const ORDERS: DatasetCatalogItem = {
+  id: 'orders',
+  label: '销售明细',
+  fields: [
+    { name: 'customer', label: '客户', type: 'string' },
+    { name: 'amount', label: '金额', type: 'number' }
+  ]
+}
+
+const INVENTORY: DatasetCatalogItem = {
+  id: 'inventory',
+  label: '库存',
+  fields: [
+    { name: 'sku', label: 'SKU', type: 'string' },
+    { name: 'qty', label: '数量', type: 'number' }
+  ]
+}
+
+describe('field-panel helpers', () => {
+  it('fieldTypeGlyph 按字段类型返回短标识', () => {
+    expect(fieldTypeGlyph('string')).toBe('文')
+    expect(fieldTypeGlyph('number')).toBe('#')
+    expect(fieldTypeGlyph('date')).toBe('日')
+  })
+
+  it('filterDatasetsByQuery 按中文名或英文字段名过滤', () => {
+    const datasets = [ORDERS, INVENTORY]
+
+    expect(filterDatasetsByQuery(datasets, '客户')).toEqual([
+      { ...ORDERS, fields: [ORDERS.fields[0]!] }
+    ])
+
+    expect(filterDatasetsByQuery(datasets, 'qty')).toEqual([
+      { ...INVENTORY, fields: [INVENTORY.fields[1]!] }
+    ])
+
+    expect(filterDatasetsByQuery(datasets, '  ')).toEqual(datasets)
+    expect(filterDatasetsByQuery(datasets, '不存在')).toEqual([])
+  })
+
+  it('字段拖拽负载编解码往返；非法负载返回 null', () => {
+    const payload = formatFieldDragPayload('orders', 'customer')
+    expect(payload).toBe('orders:customer')
+    expect(parseFieldDragPayload(payload)).toEqual({ datasetId: 'orders', fieldName: 'customer' })
+
+    // 字段名含冒号时按首个分隔符切分
+    expect(parseFieldDragPayload('orders:a:b')).toEqual({ datasetId: 'orders', fieldName: 'a:b' })
+
+    expect(parseFieldDragPayload('')).toBeNull()
+    expect(parseFieldDragPayload(':customer')).toBeNull()
+    expect(parseFieldDragPayload('orders:')).toBeNull()
+  })
+})

package/src/components/report/__test__/float-panel-position.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest'
+
+import type { CellOverlayRect, GridOverlayLayout } from '../designer/cell-coords'
+import { resolveBindingFloatPanelPosition } from '../designer/use-grid-overlay'
+
+function cellRect(top: number, height = 24): CellOverlayRect {
+  const bottom = top + height
+  return {
+    left: 100,
+    top,
+    right: 180,
+    bottom,
+    width: 80,
+    height,
+    centerX: 140,
+    centerY: top + height / 2
+  }
+}
+
+const layout: GridOverlayLayout = { offsetX: 0, offsetY: 77, viewW: 640, viewH: 400 }
+
+describe('resolveBindingFloatPanelPosition', () => {
+  it('顶行格空间不足时改在单元格下方', () => {
+    const rect = cellRect(101)
+    const position = resolveBindingFloatPanelPosition(rect, layout, 320, 68, 640)
+
+    expect(position.placement).toBe('below')
+    expect(position.top).toBe(rect.bottom + 8)
+  })
+
+  it('中部格优先在单元格上方', () => {
+    const rect = cellRect(200)
+    const position = resolveBindingFloatPanelPosition(rect, layout, 320, 68, 640)
+
+    expect(position.placement).toBe('above')
+    expect(position.top).toBe(rect.top - 8)
+  })
+
+  it('水平居中并限制在宿主宽度内', () => {
+    const rect = cellRect(200)
+    const position = resolveBindingFloatPanelPosition(rect, layout, 320, 68, 340)
+
+    expect(position.left).toBe(170)
+  })
+})

package/src/components/report/__test__/report-designer.test.ts

@@ -0,0 +1,388 @@
+import { Workbook } from '@veltra/sheet-core'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { createApp, h, nextTick, ref, type App } from 'vue'
+
+import { UReportDesigner } from '../../../index'
+import { REPORT_META_NAMESPACE } from '../../../report/binding'
+import type { DataConnection, DataConnector } from '../../../report/connector'
+import type { ReportTemplate } from '../../../report/template'
+import type { ParamValues, ReportBinding } from '../../../report/types'
+import type { ReportDesignerExposed } from '../../../types'
+import * as cellCoords from '../designer/cell-coords'
+import * as gridOverlay from '../designer/use-grid-overlay'
+import { FIELD_DRAG_MIME } from '../field-panel-helpers'
+
+// ---- 内联 fixtures：stub connector（实现 DataConnector 接口的内存测试夹具）----
+
+function createStubConnector() {
+  const calls = {
+    test: [] as DataConnection[],
+    describe: [] as Array<{ connection: DataConnection; sql: string }>,
+    query: [] as Array<{ connection: DataConnection; sql: string; values: ParamValues }>
+  }
+  /** test 结果可变（失败路径用例切换为业务错误） */
+  const state = {
+    testOutcome: { ok: true, data: undefined } as Awaited<ReturnType<DataConnector['test']>>
+  }
+  const connector: DataConnector = {
+    test: (connection) => {
+      calls.test.push(connection)
+      return Promise.resolve(state.testOutcome)
+    },
+    describe: (connection, sql) => {
+      calls.describe.push({ connection, sql })
+      return Promise.resolve({
+        ok: true,
+        data: [
+          { name: 'customer', label: '客户', type: 'string' as const },
+          { name: 'amount', label: '金额', type: 'number' as const }
+        ]
+      })
+    },
+    query: (connection, sql, values) => {
+      calls.query.push({ connection, sql, values })
+      return Promise.resolve({
+        ok: true,
+        data: {
+          fields: [
+            { name: 'customer', label: '客户', type: 'string' as const },
+            { name: 'amount', label: '金额', type: 'number' as const }
+          ],
+          rows: [
+            { customer: '甲公司', amount: 100 },
+            { customer: '乙公司', amount: 400 }
+          ]
+        }
+      })
+    }
+  }
+  return { connector, calls, state }
+}
+
+// ---- 挂载与等待 ----
+
+const apps: App[] = []
+const containers: HTMLElement[] = []
+
+function mountDesigner(workbook: Workbook, options?: { template?: ReportTemplate }) {
+  const { connector, calls, state } = createStubConnector()
+  const el = document.createElement('div')
+  el.style.width = '960px'
+  el.style.height = '600px'
+  document.body.appendChild(el)
+  containers.push(el)
+  const connections = ref<DataConnection[]>([])
+  const exposedRef = { value: undefined as ReportDesignerExposed | undefined }
+  const app = createApp({
+    render: () =>
+      h(UReportDesigner, {
+        connector,
+        workbook,
+        connections: connections.value,
+        template: options?.template,
+        'onUpdate:connections': (value: DataConnection[]) => {
+          connections.value = value
+        },
+        ref: (value: unknown) => {
+          exposedRef.value = value as ReportDesignerExposed | undefined
+        }
+      })
+  })
+  app.mount(el)
+  apps.push(app)
+  return { app, el, connections, exposedRef, calls, state }
+}
+
+/** 等待抽屉（teleport + transition）与连接器微任务落定 */
+async function flush(): Promise<void> {
+  await nextTick()
+  await new Promise((resolve) => setTimeout(resolve, 0))
+  await nextTick()
+  await nextTick()
+}
+
+/** 按文本定位按钮（drawer 经 Teleport 挂到 body，统一在 document 范围找） */
+function findButton(text: string): HTMLButtonElement | undefined {
+  return [...document.querySelectorAll<HTMLButtonElement>('button')].find((button) =>
+    button.textContent?.includes(text)
+  )
+}
+
+async function click(button: HTMLElement): Promise<void> {
+  button.dispatchEvent(new MouseEvent('click', { bubbles: true }))
+  await flush()
+}
+
+/** 构造字段拖拽 drop 事件（happy-dom 无 DataTransfer 构造器，注入最小桩） */
+function dispatchFieldDrop(target: HTMLElement, payload: string): void {
+  const event = new Event('drop', { bubbles: true, cancelable: true })
+  Object.defineProperty(event, 'dataTransfer', {
+    value: {
+      types: [FIELD_DRAG_MIME],
+      getData: (type: string) => (type === FIELD_DRAG_MIME ? payload : '')
+    }
+  })
+  // 落点超出网格视口 → hit-test 落空，回退当前选区（确定性断言）
+  Object.defineProperty(event, 'clientX', { value: 99999 })
+  Object.defineProperty(event, 'clientY', { value: 99999 })
+  target.dispatchEvent(event)
+}
+
+/** 构造字段拖拽 dragover 事件 */
+function dispatchFieldDragOver(target: HTMLElement, clientX = 100, clientY = 100): void {
+  const event = new Event('dragover', { bubbles: true, cancelable: true })
+  Object.defineProperty(event, 'dataTransfer', {
+    value: { types: [FIELD_DRAG_MIME], dropEffect: 'copy' }
+  })
+  Object.defineProperty(event, 'clientX', { value: clientX })
+  Object.defineProperty(event, 'clientY', { value: clientY })
+  target.dispatchEvent(event)
+}
+
+afterEach(() => {
+  while (apps.length) apps.pop()!.unmount()
+  while (containers.length) containers.pop()!.remove()
+  // drawer Teleport 到 body，卸载后清理残留
+  document.querySelectorAll('.u-drawer-overlay').forEach((node) => node.remove())
+})
+
+describe('UReportDesigner 最小闭环（数据中枢 + 拖拽绑定 + getTemplate）', () => {
+  it('连接 CRUD / 真实测试连接走 v-model:connections 与连接器；落格写 meta；getTemplate 吐出快照', async () => {
+    const workbook = new Workbook()
+    const { el, connections, exposedRef, calls } = mountDesigner(workbook)
+    await flush()
+
+    // 打开数据中枢 drawer（Teleport 到 body）
+    const hubTrigger = el.querySelector<HTMLButtonElement>('.u-report-designer__toolbar button')!
+    expect(hubTrigger.textContent).toContain('数据中枢')
+    await click(hubTrigger)
+    expect(document.querySelector('.u-report-hub')).toBeTruthy()
+
+    // 新建连接：表单出现 → 真实测试连接（经 stub connector）→ 保存
+    await click(findButton('新建连接')!)
+    expect(document.querySelector('.u-report-hub-connection-form')).toBeTruthy()
+
+    await click(findButton('测试连接')!)
+    expect(calls.test).toHaveLength(1)
+    expect(calls.test[0]).toMatchObject({ label: '新连接', type: 'mysql' })
+    expect(document.querySelector('.u-report-hub-connection-form__test')?.textContent).toContain(
+      '连接成功'
+    )
+
+    await click(findButton('保存')!)
+    expect(connections.value).toHaveLength(1)
+    expect(connections.value[0]).toMatchObject({ label: '新连接', type: 'mysql' })
+    const connectionId = connections.value[0]!.id
+
+    // 在该连接下新建数据集（编辑器出现，含 SQL 编辑与 schema/preview tabs）
+    await click(findButton('+ 新建数据集')!)
+    expect(document.querySelector('.u-report-hub-dataset-editor')).toBeTruthy()
+    const datasetId = document.querySelector('.u-report-hub__dataset-id')!.textContent!
+
+    // 关闭 drawer，回到设计态
+    await click(findButton('完成')!)
+
+    // 拖拽字段落格 → 写入 Cell Meta 绑定（落点 hit-test 落空 → 回退当前选区 A1）
+    const gridHost = el.querySelector<HTMLElement>('.u-report-designer__grid')!
+    dispatchFieldDrop(gridHost, `${datasetId}:customer`)
+    await flush()
+
+    const metas = [...workbook.activeSheet.entriesCellMeta()].filter(
+      ([, namespace]) => namespace === REPORT_META_NAMESPACE
+    )
+    expect(metas).toHaveLength(1)
+    const [addr, , payload] = metas[0]!
+    expect(addr).toEqual({ row: 0, col: 0 })
+    expect(payload as ReportBinding).toMatchObject({
+      dataset: datasetId,
+      field: 'customer',
+      preset: 'detail',
+      aggregate: 'list',
+      expand: 'down'
+    })
+
+    // getTemplate() 返回含 meta 绑定与内嵌数据集定义（连接对象内嵌，凭据随模板流转）
+    const template = exposedRef.value!.getTemplate()
+    expect(template.version).toBe(1)
+    expect(template.meta).toHaveLength(1)
+    expect(template.meta![0]).toMatchObject({ row: 0, col: 0, namespace: 'report' })
+    expect(template.datasets).toEqual([
+      {
+        id: datasetId,
+        label: '新数据集',
+        connection: { ...connections.value[0]!, id: connectionId },
+        sql: ''
+      }
+    ])
+  })
+
+  it('测试连接业务失败（ok:false）时展示可读错误提示', async () => {
+    const workbook = new Workbook()
+    const { el, state } = mountDesigner(workbook)
+    state.testOutcome = {
+      ok: false,
+      error: { code: 'CONNECTION_FAILED', message: '数据库连接失败' }
+    }
+    await flush()
+
+    await click(el.querySelector<HTMLButtonElement>('.u-report-designer__toolbar button')!)
+    await click(findButton('新建连接')!)
+    await click(findButton('测试连接')!)
+
+    const banner = document.querySelector('.u-report-hub-connection-form__test')
+    expect(banner?.textContent).toContain('数据库连接失败')
+    expect(banner?.classList.contains('is-ok')).toBe(false)
+  })
+})
+
+describe('UReportDesigner 全量：template 载入与预览模式（内嵌查看器路径）', () => {
+  const TEMPLATE_CONNECTION: DataConnection = {
+    id: 'conn-template',
+    label: '模板连接',
+    type: 'mysql',
+    host: '127.0.0.1',
+    port: 3306,
+    database: 'demo',
+    username: 'root',
+    password: ''
+  }
+
+  function buildTemplate(): ReportTemplate {
+    const group: ReportBinding = {
+      dataset: 'ds-template',
+      field: 'customer',
+      preset: 'groupHeader',
+      aggregate: 'group',
+      expand: 'down',
+      sort: 'none',
+      conditionalRules: []
+    }
+    return {
+      version: 1,
+      cells: [{ row: 0, col: 0, v: '客户' }],
+      styles: [],
+      merges: [],
+      frozen: { rows: 0, cols: 0 },
+      rows: 24,
+      cols: 10,
+      meta: [{ row: 1, col: 0, namespace: REPORT_META_NAMESPACE, payload: group }],
+      datasets: [
+        {
+          id: 'ds-template',
+          label: '订单',
+          connection: TEMPLATE_CONNECTION,
+          sql: 'SELECT customer, amount FROM orders'
+        }
+      ]
+    }
+  }
+
+  function reportMetas(workbook: Workbook) {
+    return [...workbook.activeSheet.entriesCellMeta()].filter(
+      ([, namespace]) => namespace === REPORT_META_NAMESPACE
+    )
+  }
+
+  it('template prop 载入恢复绑定与连接；预览切换经内嵌查看器取数展开；切回设计态绑定不丢', async () => {
+    const workbook = new Workbook()
+    const { el, connections, exposedRef, calls } = mountDesigner(workbook, {
+      template: buildTemplate()
+    })
+    await flush()
+
+    // 模板载入：绑定恢复 + 内嵌连接合并进 v-model 列表
+    expect(reportMetas(workbook)).toHaveLength(1)
+    expect(connections.value.map((item) => item.id)).toEqual(['conn-template'])
+
+    // 切预览：内嵌查看器按模板内嵌数据集取数（含 Filter Bar 参数默认值）
+    await click(findButton('预览模式')!)
+    expect(el.querySelector('.u-report-viewer')).toBeTruthy()
+    expect(calls.query).toHaveLength(1)
+    expect(calls.query[0]!.connection.id).toBe('conn-template')
+    expect(calls.query[0]!.sql).toBe('SELECT customer, amount FROM orders')
+    // 取数成功：无业务错误 banner；设计格线已卸载
+    expect(el.querySelector('.u-report-viewer__error')).toBeFalsy()
+    expect(el.querySelector('.u-report-designer__grid')).toBeFalsy()
+
+    // 切回设计态：绑定不丢，可继续设计
+    await click(findButton('设计模式')!)
+    expect(el.querySelector('.u-report-viewer')).toBeFalsy()
+    expect(el.querySelector('.u-report-designer__grid')).toBeTruthy()
+    expect(reportMetas(workbook)).toHaveLength(1)
+
+    // getTemplate 往返：绑定与内嵌数据集定义完整
+    const roundTrip = exposedRef.value!.getTemplate()
+    expect(roundTrip.meta).toHaveLength(1)
+    expect(roundTrip.datasets).toHaveLength(1)
+    expect(roundTrip.datasets![0]).toMatchObject({ id: 'ds-template', label: '订单' })
+    expect(roundTrip.datasets![0]!.connection.id).toBe('conn-template')
+  })
+
+  it('预览态导出 XLSX 按钮可见且转调查看器 exportXlsx()', async () => {
+    const workbook = new Workbook()
+    const { el } = mountDesigner(workbook, { template: buildTemplate() })
+    await flush()
+
+    // 设计态无导出按钮
+    expect(findButton('导出 XLSX')).toBeUndefined()
+
+    await click(findButton('预览模式')!)
+    const exportButton = findButton('导出 XLSX')
+    expect(exportButton).toBeTruthy()
+    await flush()
+
+    const exportModule = await import('../../../report/export-xlsx')
+    const catKitFe = await import('@cat-kit/fe')
+    const exportSpy = vi
+      .spyOn(exportModule, 'exportFilledReportXlsx')
+      .mockResolvedValue(new Uint8Array([80, 75, 3, 4]))
+    const saveBlobSpy = vi.spyOn(catKitFe, 'saveBlob').mockImplementation(() => {})
+
+    await click(exportButton!)
+    expect(exportSpy).toHaveBeenCalled()
+    expect(saveBlobSpy).toHaveBeenCalled()
+    expect(el.querySelector('.u-report-viewer')).toBeTruthy()
+
+    exportSpy.mockRestore()
+    saveBlobSpy.mockRestore()
+  })
+
+  it('字段拖拽 dragover 时落点高亮随 hit-test 更新；落空时提示回退当前选区', async () => {
+    const workbook = new Workbook()
+    workbook.activeSheet.selectCell({ row: 2, col: 1 })
+    const { el } = mountDesigner(workbook)
+    await flush()
+
+    const gridHost = el.querySelector<HTMLElement>('.u-report-designer__grid')!
+    const overlayRect = {
+      left: 10,
+      top: 20,
+      right: 90,
+      bottom: 44,
+      width: 80,
+      height: 24,
+      centerX: 50,
+      centerY: 32
+    }
+    const hitTestSpy = vi
+      .spyOn(cellCoords, 'resolveGridDropAddress')
+      .mockReturnValueOnce({ row: 1, col: 2 })
+      .mockReturnValue(null)
+    const overlaySpy = vi.spyOn(gridOverlay, 'readCellOverlayRect').mockReturnValue(overlayRect)
+
+    dispatchFieldDragOver(gridHost, 120, 140)
+    await flush()
+    expect(el.querySelector('.u-report-drop-highlight')).toBeTruthy()
+    expect(el.querySelector('.u-report-drop-highlight__fallback')).toBeNull()
+
+    dispatchFieldDragOver(gridHost, 99999, 99999)
+    await flush()
+    expect(el.querySelector('.u-report-drop-highlight')).toBeNull()
+    const fallback = el.querySelector('.u-report-drop-highlight__fallback')
+    expect(fallback).toBeTruthy()
+    expect(fallback!.textContent).toContain('B3')
+
+    hitTestSpy.mockRestore()
+    overlaySpy.mockRestore()
+  })
+})