@veltra/sheet 2.1.1 → 2.3.0

package/src/report/export-xlsx.ts

@@ -0,0 +1,113 @@
+import type { Sheet } from '@veltra/sheet-core'
+import { rangeToHucre, styleToHucre } from '@veltra/sheet-core/core/io/export'
+import type { Cell, CellValue, ColumnDef, RowDef, WriteSheet } from 'hucre'
+import { writeXlsx } from 'hucre/xlsx'
+
+/** 列宽条目：模型列索引 → 像素宽（与 SheetSnapshot.colWidths 同构） */
+export type ReportColWidthEntry = readonly [number, number]
+
+/** 像素 → Excel points */
+function pxToPt(px: number): number {
+  return px * 0.75
+}
+
+/** VTable 像素列宽 → Excel 字符宽度（近似换算） */
+export function pxToExcelColWidth(px: number): number {
+  return Math.max(1, Math.round((px - 5) / 7))
+}
+
+/** 从列宽条目构建 hucre ColumnDef */
+export function buildColumnDefs(colWidths: ReadonlyArray<ReportColWidthEntry>): ColumnDef[] {
+  if (colWidths.length === 0) return []
+  const maxCol = Math.max(...colWidths.map(([col]) => col))
+  const columns: ColumnDef[] = Array.from({ length: maxCol + 1 }, () => ({}))
+  for (const [col, width] of colWidths) {
+    columns[col] = { width: pxToExcelColWidth(width) }
+  }
+  return columns
+}
+
+/**
+ * 将已填充的 Sheet（Filled Report）导出为保真 XLSX（合并 / 样式 / 行高 / 列宽）。
+ * 条件样式颜色已在 renderReport 展开阶段打平进 StylePool（ADR-0001 决策 2）。
+ * 列宽取自 sheet 模型（`getColWidths`）。
+ */
+export async function exportFilledReportXlsx(sheet: Sheet): Promise<Uint8Array> {
+  const widths: ReportColWidthEntry[] = [...sheet.getColWidths()]
+
+  let maxRow = -1
+  let maxCol = -1
+  for (const [addr] of sheet.store.entries()) {
+    if (addr.row > maxRow) maxRow = addr.row
+    if (addr.col > maxCol) maxCol = addr.col
+  }
+  for (const [row] of sheet.getRowHeights()) {
+    if (row > maxRow) maxRow = row
+  }
+  for (const [col] of widths) {
+    if (col > maxCol) maxCol = col
+  }
+
+  const rows =
+    maxRow < 0
+      ? []
+      : Array.from({ length: maxRow + 1 }, () =>
+          Array.from({ length: maxCol + 1 }, () => null as CellValue)
+        )
+  const cells = new Map<string, Partial<Cell>>()
+
+  for (const [addr, data] of sheet.store.entries()) {
+    const row = rows[addr.row]!
+    const key = `${addr.row},${addr.col}`
+    const cell: Partial<Cell> = {}
+    const style = sheet.getEffectiveStyle(addr)
+    if (style) cell.style = styleToHucre(style)
+    if (data.f != null && data.f !== '') {
+      cell.formula = data.f
+      if (data.v != null) cell.formulaResult = data.v as CellValue
+      row[addr.col] = (data.v as CellValue) ?? null
+      cells.set(key, cell)
+      continue
+    }
+    if (data.t === 'e') {
+      cell.value = data.v as string
+      cell.type = 'error'
+      row[addr.col] = null
+      cells.set(key, cell)
+      continue
+    }
+    if (data.t === 'd') {
+      cell.value = data.v as number
+      cell.type = 'number'
+      cell.style = { ...cell.style, numFmt: 'yyyy-mm-dd' }
+      row[addr.col] = null
+      cells.set(key, cell)
+      continue
+    }
+    row[addr.col] = (data.v as CellValue) ?? null
+    if (Object.keys(cell).length > 0) cells.set(key, cell)
+  }
+
+  const writeSheet: WriteSheet = {
+    name: sheet.name || '报表',
+    rows,
+    ...(cells.size > 0 ? { cells } : {}),
+    ...(sheet.merges.size > 0
+      ? { merges: sheet.merges.getMerges().map((range) => rangeToHucre(range)) }
+      : {}),
+    ...(widths.length > 0 ? { columns: buildColumnDefs(widths) } : {})
+  }
+
+  const frozen = sheet.frozen
+  if (frozen.rows > 0 || frozen.cols > 0) {
+    writeSheet.freezePane = { rows: frozen.rows, columns: frozen.cols }
+  }
+
+  const rowDefs = new Map<number, RowDef>()
+  for (const [row, height] of sheet.getRowHeights()) {
+    rowDefs.set(row, { height: pxToPt(height) })
+  }
+  if (rowDefs.size > 0) writeSheet.rowDefs = rowDefs
+
+  return writeXlsx({ sheets: [writeSheet], activeSheet: 0 })
+}

package/src/report/filter-bar.ts

@@ -0,0 +1,36 @@
+import type { ParamValues } from './types'
+
+// Filter Bar 控件值规范化（自 playground filter-bar-helpers 平移，行为不变）
+
+function toParamString(value: unknown): string {
+  if (value == null || value === '') return ''
+  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+    return String(value)
+  }
+  return ''
+}
+
+/** 将运行时 date-range 参数值规范为 [from, to] 字符串元组 */
+export function parseDateRangeValue(raw: unknown): [string, string] {
+  if (Array.isArray(raw)) {
+    return [toParamString(raw[0]), toParamString(raw[1])]
+  }
+  if (raw && typeof raw === 'object') {
+    const obj = raw as Record<string, unknown>
+    return [toParamString(obj.from ?? obj.start), toParamString(obj.to ?? obj.end)]
+  }
+  return ['', '']
+}
+
+/** 将运行时 number 参数值规范为 UNumberInput 可接受的 number | undefined */
+export function resolveNumberParamValue(raw: unknown): number | undefined {
+  if (raw === '' || raw == null) return undefined
+  if (typeof raw === 'number' && Number.isFinite(raw)) return raw
+  const parsed = Number(raw)
+  return Number.isFinite(parsed) ? parsed : undefined
+}
+
+/** 合并单参数变更，保持其余参数值不变 */
+export function patchParamValues(values: ParamValues, id: string, value: unknown): ParamValues {
+  return { ...values, [id]: value }
+}

package/src/report/index.ts

@@ -0,0 +1,13 @@
+// 报表纯 TS 内核（ADR-0003 决策 1）：渲染引擎 / 绑定 / 条件规则 / 查询参数 / 数据连接器 /
+// Report Template（自包含模板与取数）/ Filter Bar 值规范化。
+// 框架无关、无 DOM 依赖；组件壳（UReportDesigner / UReportViewer）落 components/report/。
+
+export * from './types'
+export * from './binding'
+export * from './rules'
+export * from './params'
+export * from './render'
+export * from './connector'
+export * from './template'
+export * from './filter-bar'
+export * from './export-xlsx'

package/src/report/params.ts

@@ -0,0 +1,96 @@
+import type { QueryParamDef, QueryParamType } from './types'
+
+/** 从 SQL 提取 `${param}` 占位符 id（ADR-0002 决策 2：前端纯函数） */
+export function extractParamIds(sql: string): string[] {
+  const ids: string[] = []
+  const re = /\$\{([^}]+)\}/g
+  let match: RegExpExecArray | null
+  while ((match = re.exec(sql)) !== null) {
+    const id = match[1]!.trim()
+    if (id && !ids.includes(id)) ids.push(id)
+  }
+  return ids
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/** 从 SQL 上下文推断参数控件类型（BETWEEN/LIKE/数值比较） */
+function inferParamTypeFromSql(sql: string, paramId: string): QueryParamType {
+  const betweenSingle = new RegExp(
+    `\\bBETWEEN\\s+\\$\\{${escapeRegExp(paramId)}\\}(?!\\s+AND)`,
+    'i'
+  )
+  if (betweenSingle.test(sql)) return 'date-range'
+
+  const betweenPair = new RegExp(
+    `\\bBETWEEN\\s+\\$\\{${escapeRegExp(paramId)}\\}\\s+AND\\s+\\$\\{([^}]+)\\}`,
+    'i'
+  )
+  const pairMatch = betweenPair.exec(sql)
+  if (pairMatch && pairMatch[1]!.trim() !== paramId) return 'date'
+
+  const like = new RegExp(`\\bLIKE\\s+\\$\\{${escapeRegExp(paramId)}\\}`, 'i')
+  if (like.test(sql)) return 'text'
+
+  const numericCompare = new RegExp(
+    `[<>=]+\\s+\\$\\{${escapeRegExp(paramId)}\\}|\\$\\{${escapeRegExp(paramId)}\\}\\s*[<>=]+`,
+    'i'
+  )
+  if (numericCompare.test(sql)) return 'number'
+
+  return 'text'
+}
+
+function defaultValueForType(type: QueryParamType): unknown {
+  switch (type) {
+    case 'number':
+      return 0
+    case 'date-range':
+      return ['', '']
+    case 'select':
+      return ''
+    default:
+      return ''
+  }
+}
+
+/**
+ * 从 SQL 构建查询参数定义：提取 `${param}` 占位符 + 上下文类型推断，
+ * 再叠加数据集编辑器的元数据覆盖（label / 类型 / 默认值 / 选项）。
+ */
+export function buildParamDefs(
+  sql: string,
+  overrides?: Record<string, Partial<Omit<QueryParamDef, 'id'>>>
+): QueryParamDef[] {
+  const ids = extractParamIds(sql)
+  return ids.map((id) => {
+    const inferred = inferParamTypeFromSql(sql, id)
+    const override = overrides?.[id]
+    return {
+      id,
+      label: override?.label ?? id,
+      type: override?.type ?? inferred,
+      defaultValue: override?.defaultValue ?? defaultValueForType(override?.type ?? inferred),
+      options: override?.options
+    }
+  })
+}
+
+/** 按绑定的数据集 id 合并查询参数（同名参数先见为准） */
+export function resolveBoundDatasetParams(
+  queryParams: QueryParamDef[],
+  boundDatasetIds: readonly string[],
+  getDatasetParams: (datasetId: string) => QueryParamDef[]
+): QueryParamDef[] {
+  const map = new Map<string, QueryParamDef>()
+  for (const datasetId of boundDatasetIds) {
+    const params = getDatasetParams(datasetId)
+    for (const param of params) {
+      if (!map.has(param.id)) map.set(param.id, param)
+    }
+  }
+  if (map.size > 0) return Array.from(map.values())
+  return queryParams
+}

package/src/report/render/__test__/aggregate.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest'
+
+import { aggregateField } from '../aggregate'
+
+describe('aggregateField', () => {
+  it('avg 空集返回 undefined，sum 空集仍为 0', () => {
+    expect(aggregateField([], 'amount', 'avg')).toBeUndefined()
+    expect(aggregateField([], 'amount', 'sum')).toBe(0)
+  })
+
+  it('max / min 对数值集求值', () => {
+    const rows = [{ amount: 10 }, { amount: 30 }, { amount: 20 }]
+    expect(aggregateField(rows, 'amount', 'max')).toBe(30)
+    expect(aggregateField(rows, 'amount', 'min')).toBe(10)
+  })
+})

package/src/report/render/__test__/coordinate.test.ts

@@ -0,0 +1,405 @@
+import { Sheet } from '@veltra/sheet-core'
+import { describe, expect, it } from 'vitest'
+
+import { REPORT_META_NAMESPACE, createReportBinding } from '../../binding'
+import type { DatasetRecords, ReportBinding } from '../../types'
+import {
+  computeExpansionLayout,
+  enumerateExpansionInstances,
+  physicalColSpan,
+  physicalRowSpan,
+  placementsAt
+} from '../coordinate'
+import { TemplateStructureError, buildTemplateIndex } from '../template-index'
+
+// ---- fixtures ----
+
+const ORDERS: DatasetRecords = {
+  orders: [
+    { customer: '甲', region: '华东', orderNo: 'O-1', amount: 100 },
+    { customer: '甲', region: '华东', orderNo: 'O-2', amount: 200 },
+    { customer: '乙', region: '华南', orderNo: 'O-3', amount: 300 },
+    { customer: '丙', region: '华北', orderNo: 'O-4', amount: 400 }
+  ]
+}
+
+const MATRIX: DatasetRecords = {
+  sales: [
+    { region: '华东', category: 'A', amount: 10 },
+    { region: '华东', category: 'B', amount: 20 },
+    { region: '华南', category: 'A', amount: 30 },
+    { region: '华南', category: 'B', amount: 40 }
+  ]
+}
+
+const MULTI_DS: DatasetRecords = { orders: ORDERS.orders!, customers: [{ id: 'C1' }, { id: 'C2' }] }
+
+function bind(sheet: Sheet, addr: { row: number; col: number }, binding: ReportBinding): void {
+  sheet.setCellMeta(addr, REPORT_META_NAMESPACE, binding)
+}
+
+function snapshot(sheet: Sheet) {
+  return sheet.snapshot()
+}
+
+function layoutOf(sheet: Sheet, data: DatasetRecords = ORDERS) {
+  const index = buildTemplateIndex(snapshot(sheet))
+  return computeExpansionLayout(index, data)
+}
+
+function placementRange(
+  layout: ReturnType<typeof layoutOf>,
+  row: number,
+  col: number,
+  listIndex = 0
+) {
+  const items = placementsAt(layout, { row, col })
+  const hit = items[listIndex] ?? items[0]
+  expect(hit, `逻辑格 R${row}C${col} 无映射`).toBeDefined()
+  return hit!.physical
+}
+
+// ---- template-index ----
+
+describe('buildTemplateIndex', () => {
+  it('父格不存在时抛可读错误', () => {
+    const sheet = new Sheet()
+    const binding = createReportBinding({ id: 'orders', label: 'o', fields: [] }, 'customer')
+    binding.rowParent = { row: 0, col: 9 }
+    bind(sheet, { row: 1, col: 0 }, binding)
+
+    expect(() => buildTemplateIndex(snapshot(sheet))).toThrow(TemplateStructureError)
+    expect(() => buildTemplateIndex(snapshot(sheet))).toThrow(/J1/)
+  })
+
+  it('父链成环时抛可读错误', () => {
+    const sheet = new Sheet()
+    const a = createReportBinding({ id: 'orders', label: 'o', fields: [] }, 'customer')
+    const b = createReportBinding({ id: 'orders', label: 'o', fields: [] }, 'region')
+    a.rowParent = { row: 2, col: 0 }
+    b.rowParent = { row: 1, col: 0 }
+    bind(sheet, { row: 1, col: 0 }, a)
+    bind(sheet, { row: 2, col: 0 }, b)
+
+    expect(() => buildTemplateIndex(snapshot(sheet))).toThrow(/父链存在环/)
+  })
+})
+
+// ---- enumerateExpansionInstances ----
+
+describe('enumerateExpansionInstances', () => {
+  const groupBinding: ReportBinding = {
+    dataset: 'orders',
+    field: 'customer',
+    expand: 'down',
+    aggregate: 'group'
+  }
+
+  it('group 取去重值数', () => {
+    const instances = enumerateExpansionInstances(groupBinding, ORDERS, {})
+    expect(instances).toHaveLength(3)
+    expect(instances.map((i) => i.value)).toEqual(['甲', '乙', '丙'])
+  })
+
+  it('list 取记录数', () => {
+    const listBinding: ReportBinding = {
+      dataset: 'orders',
+      field: 'orderNo',
+      expand: 'down',
+      aggregate: 'list'
+    }
+    expect(enumerateExpansionInstances(listBinding, ORDERS, {})).toHaveLength(4)
+  })
+
+  it('expand none 恒为 1 个实例', () => {
+    const noneBinding: ReportBinding = {
+      dataset: 'orders',
+      field: 'amount',
+      expand: 'none',
+      aggregate: 'sum'
+    }
+    expect(enumerateExpansionInstances(noneBinding, ORDERS, {})).toHaveLength(1)
+  })
+
+  it('空数据集 group 产出 0 实例', () => {
+    expect(enumerateExpansionInstances(groupBinding, { orders: [] }, {})).toHaveLength(0)
+  })
+})
+
+// ---- coordinate geometry ----
+
+describe('computeExpansionLayout', () => {
+  it('单级纵向：分组头 merge 跨度 = 明细行数，静态表头不被推移', () => {
+    const sheet = new Sheet()
+    sheet.setCells([
+      { addr: { row: 0, col: 0 }, data: { v: '客户' } },
+      { addr: { row: 0, col: 1 }, data: { v: '订单号' } }
+    ])
+    const group = createReportBinding({ id: 'orders', label: 'o', fields: [] }, 'customer')
+    group.aggregate = 'group'
+    group.expand = 'down'
+    bind(sheet, { row: 1, col: 0 }, group)
+
+    const detail = createReportBinding({ id: 'orders', label: 'o', fields: [] }, 'orderNo')
+    detail.aggregate = 'list'
+    detail.expand = 'down'
+    detail.rowParent = { row: 1, col: 0 }
+    bind(sheet, { row: 1, col: 1 }, detail)
+
+    const layout = layoutOf(sheet)
+    // 表头 1 + 甲2 + 乙1 + 丙1 = 5 行
+    expect(layout.rowCount).toBe(5)
+
+    const header = placementRange(layout, 0, 0)
+    expect(header.start).toEqual({ row: 0, col: 0 })
+
+    const groupA = placementsAt(layout, { row: 1, col: 0 }).find((p) => p.rowPath[0] === 0)!
+    expect(physicalRowSpan(groupA)).toBe(2)
+    expect(groupA.physical.start.row).toBe(1)
+
+    const groupB = placementsAt(layout, { row: 1, col: 0 }).find((p) => p.rowPath[0] === 1)!
+    expect(physicalRowSpan(groupB)).toBe(1)
+    expect(groupB.physical.start.row).toBe(3)
+  })
+
+  it('多级纵向嵌套：子分组在父实例内展开', () => {
+    const sheet = new Sheet()
+    const data: DatasetRecords = {
+      orders: [
+        { region: '华东', customer: '甲', orderNo: '1' },
+        { region: '华东', customer: '甲', orderNo: '2' },
+        { region: '华东', customer: '乙', orderNo: '3' },
+        { region: '华南', customer: '丙', orderNo: '4' }
+      ]
+    }
+
+    const region = createReportBinding({ id: 'orders', label: 'o', fields: [] }, 'region')
+    region.aggregate = 'group'
+    region.expand = 'down'
+    bind(sheet, { row: 1, col: 0 }, region)
+
+    const customer = createReportBinding({ id: 'orders', label: 'o', fields: [] }, 'customer')
+    customer.aggregate = 'group'
+    customer.expand = 'down'
+    customer.rowParent = { row: 1, col: 0 }
+    bind(sheet, { row: 2, col: 0 }, customer)
+
+    const detail = createReportBinding({ id: 'orders', label: 'o', fields: [] }, 'orderNo')
+    detail.aggregate = 'list'
+    detail.expand = 'down'
+    detail.rowParent = { row: 2, col: 0 }
+    bind(sheet, { row: 2, col: 1 }, detail)
+
+    const layout = layoutOf(sheet, data)
+    // 华东(甲2+乙1) + 华南(丙1) = 3 组块 × 各自明细 = 4 明细行
+    expect(layout.rowCount).toBe(4)
+
+    const eastCustomer = placementsAt(layout, { row: 2, col: 0 }).find(
+      (p) => p.rowPath[0] === 0 && p.rowPath[1] === 0
+    )!
+    expect(physicalRowSpan(eastCustomer)).toBe(2)
+  })
+
+  it('单级横向：列分组向右延展', () => {
+    const sheet = new Sheet()
+    sheet.setCells([{ addr: { row: 0, col: 0 }, data: { v: '品类' } }])
+
+    const category = createReportBinding({ id: 'sales', label: 's', fields: [] }, 'category')
+    category.aggregate = 'group'
+    category.expand = 'right'
+    bind(sheet, { row: 0, col: 1 }, category)
+
+    const layout = layoutOf(sheet, MATRIX)
+    expect(layout.colCount).toBe(3) // 标题 + A/B 两列
+    const headers = placementsAt(layout, { row: 0, col: 1 })
+    expect(headers).toHaveLength(2)
+    expect(headers[0]!.physical.start.col).toBe(1)
+    expect(headers[1]!.physical.start.col).toBe(2)
+    expect(physicalColSpan(headers[0]!)).toBe(1)
+  })
+
+  it('多级列头：colParent 链逐级向右嵌套', () => {
+    const sheet = new Sheet()
+    const data: DatasetRecords = {
+      sales: [
+        { year: '2024', quarter: 'Q1', amount: 1 },
+        { year: '2024', quarter: 'Q2', amount: 2 },
+        { year: '2025', quarter: 'Q1', amount: 3 }
+      ]
+    }
+
+    const year = createReportBinding({ id: 'sales', label: 's', fields: [] }, 'year')
+    year.aggregate = 'group'
+    year.expand = 'right'
+    bind(sheet, { row: 0, col: 0 }, year)
+
+    const quarter = createReportBinding({ id: 'sales', label: 's', fields: [] }, 'quarter')
+    quarter.aggregate = 'group'
+    quarter.expand = 'right'
+    quarter.colParent = { row: 0, col: 0 }
+    bind(sheet, { row: 1, col: 0 }, quarter)
+
+    const layout = layoutOf(sheet, data)
+    const yearPlacements = placementsAt(layout, { row: 0, col: 0 })
+    expect(yearPlacements).toHaveLength(2)
+    expect(physicalColSpan(yearPlacements[0]!)).toBe(2)
+    expect(physicalColSpan(yearPlacements[1]!)).toBe(1)
+
+    const quarterPlacements = placementsAt(layout, { row: 1, col: 0 })
+    expect(quarterPlacements).toHaveLength(3)
+  })
+
+  it('行列同时展开：交叉格按双父实例落位', () => {
+    const sheet = new Sheet()
+    sheet.setCells([
+      { addr: { row: 0, col: 0 }, data: { v: '标题' } },
+      { addr: { row: 2, col: 0 }, data: { v: '合计' } }
+    ])
+
+    const category = createReportBinding({ id: 'sales', label: 's', fields: [] }, 'category')
+    category.aggregate = 'group'
+    category.expand = 'right'
+    bind(sheet, { row: 0, col: 1 }, category)
+
+    const region = createReportBinding({ id: 'sales', label: 's', fields: [] }, 'region')
+    region.aggregate = 'group'
+    region.expand = 'down'
+    bind(sheet, { row: 1, col: 0 }, region)
+
+    const cross = createReportBinding({ id: 'sales', label: 's', fields: [] }, 'amount')
+    cross.aggregate = 'sum'
+    cross.expand = 'none'
+    cross.rowParent = { row: 1, col: 0 }
+    cross.colParent = { row: 0, col: 1 }
+    bind(sheet, { row: 1, col: 1 }, cross)
+
+    const layout = layoutOf(sheet, MATRIX)
+    expect(layout.rowCount).toBe(4) // 表头 + 2 地区 + 合计
+    expect(layout.colCount).toBe(3) // 角 + 2 品类
+
+    const crossCells = placementsAt(layout, { row: 1, col: 1 })
+    expect(crossCells).toHaveLength(4)
+    expect(crossCells.map((p) => p.physical.start)).toEqual(
+      expect.arrayContaining([
+        { row: 1, col: 1 },
+        { row: 1, col: 2 },
+        { row: 2, col: 1 },
+        { row: 2, col: 2 }
+      ])
+    )
+  })
+
+  it('mergeSpan: false 时扩展格不合并，逐格占位', () => {
+    const sheet = new Sheet()
+    const group = createReportBinding({ id: 'orders', label: 'o', fields: [] }, 'customer')
+    group.aggregate = 'group'
+    group.expand = 'down'
+    group.mergeSpan = false
+    bind(sheet, { row: 1, col: 0 }, group)
+
+    const detail = createReportBinding({ id: 'orders', label: 'o', fields: [] }, 'orderNo')
+    detail.aggregate = 'list'
+    detail.expand = 'down'
+    detail.rowParent = { row: 1, col: 0 }
+    bind(sheet, { row: 1, col: 1 }, detail)
+
+    const layout = layoutOf(sheet)
+    const groupCells = placementsAt(layout, { row: 1, col: 0 })
+    expect(groupCells.every((p) => !p.mergeSpan)).toBe(true)
+    expect(groupCells.every((p) => physicalRowSpan(p) === 1)).toBe(true)
+    expect(groupCells).toHaveLength(4)
+  })
+
+  it('静态格在扩展带内随明细重复占位', () => {
+    const sheet = new Sheet()
+    sheet.setCells([{ addr: { row: 1, col: 2 }, data: { v: '备注' } }])
+
+    const group = createReportBinding({ id: 'orders', label: 'o', fields: [] }, 'customer')
+    group.aggregate = 'group'
+    group.expand = 'down'
+    bind(sheet, { row: 1, col: 0 }, group)
+
+    const detail = createReportBinding({ id: 'orders', label: 'o', fields: [] }, 'orderNo')
+    detail.aggregate = 'list'
+    detail.expand = 'down'
+    detail.rowParent = { row: 1, col: 0 }
+    bind(sheet, { row: 1, col: 1 }, detail)
+
+    const layout = layoutOf(sheet)
+    const notes = placementsAt(layout, { row: 1, col: 2 })
+    expect(notes).toHaveLength(4)
+    expect(notes.map((p) => p.physical.start.row)).toEqual([0, 1, 2, 3])
+  })
+
+  it('空展开：扩展格 0 跨度，子树不占位，静态表头仍映射', () => {
+    const sheet = new Sheet()
+    sheet.setCells([{ addr: { row: 0, col: 0 }, data: { v: '客户' } }])
+
+    const group = createReportBinding({ id: 'orders', label: 'o', fields: [] }, 'customer')
+    group.aggregate = 'group'
+    group.expand = 'down'
+    bind(sheet, { row: 1, col: 0 }, group)
+
+    const detail = createReportBinding({ id: 'orders', label: 'o', fields: [] }, 'orderNo')
+    detail.aggregate = 'list'
+    detail.expand = 'down'
+    detail.rowParent = { row: 1, col: 0 }
+    bind(sheet, { row: 1, col: 1 }, detail)
+
+    const layout = layoutOf(sheet, { orders: [] })
+    expect(layout.rowCount).toBe(1)
+    expect(placementsAt(layout, { row: 0, col: 0 })).toHaveLength(1)
+    expect(placementsAt(layout, { row: 1, col: 0 })).toHaveLength(0)
+  })
+
+  it('跨数据集：父格过滤不同数据集时不串联', () => {
+    const sheet = new Sheet()
+    sheet.setCells([{ addr: { row: 0, col: 5 }, data: { v: '客户ID' } }])
+
+    const group = createReportBinding({ id: 'orders', label: 'o', fields: [] }, 'customer')
+    group.aggregate = 'group'
+    group.expand = 'down'
+    bind(sheet, { row: 1, col: 0 }, group)
+
+    const detail = createReportBinding({ id: 'orders', label: 'o', fields: [] }, 'orderNo')
+    detail.aggregate = 'list'
+    detail.expand = 'down'
+    detail.rowParent = { row: 1, col: 0 }
+    bind(sheet, { row: 1, col: 1 }, detail)
+
+    const customers = createReportBinding({ id: 'customers', label: 'c', fields: [] }, 'id')
+    customers.aggregate = 'list'
+    customers.expand = 'down'
+    bind(sheet, { row: 4, col: 5 }, customers)
+
+    const layout = layoutOf(sheet, MULTI_DS)
+    // 订单 4 明细行 + 表头 1 + 客户列表 2 行
+    expect(layout.rowCount).toBe(4 + 1 + 2)
+    const customerIds = placementsAt(layout, { row: 4, col: 5 })
+    expect(customerIds).toHaveLength(2)
+    expect(customerIds[0]!.physical.start.row).toBe(5)
+  })
+
+  it('模板合并区域映射到物理表头行', () => {
+    const sheet = new Sheet()
+    sheet.setCells([
+      { addr: { row: 0, col: 0 }, data: { v: '客户' } },
+      { addr: { row: 0, col: 1 }, data: { v: '订单号' } }
+    ])
+    sheet.mergeCells({ start: { row: 0, col: 0 }, end: { row: 0, col: 1 } })
+
+    const group = createReportBinding({ id: 'orders', label: 'o', fields: [] }, 'customer')
+    group.aggregate = 'group'
+    group.expand = 'down'
+    bind(sheet, { row: 1, col: 0 }, group)
+
+    const detail = createReportBinding({ id: 'orders', label: 'o', fields: [] }, 'orderNo')
+    detail.aggregate = 'list'
+    detail.expand = 'down'
+    detail.rowParent = { row: 1, col: 0 }
+    bind(sheet, { row: 1, col: 1 }, detail)
+
+    const layout = layoutOf(sheet)
+    expect(layout.mappedMerges).toEqual([{ start: { row: 0, col: 0 }, end: { row: 0, col: 1 } }])
+  })
+})