@veltra/sheet 2.3.3 → 2.4.0

package/src/components/sheet/popups/import.worker.ts

@@ -1,15 +1,16 @@
 /// <reference lib="webworker" />
 /**
- * XLSX 解析 Worker：hucre 解析 + 模型构建（大文件 3~4s 同步重活）
+ * XLSX 解析 Worker：xlsx 解析 + 模型构建（大文件 3~4s 同步重活）
  * 移到独立线程，主线程保持空闲（loading 动画正常、交互不冻结）。
  *
  * 协议：主线程 postMessage({ buffer: ArrayBuffer }) → worker 返回
- * - { type: 'progress', done, total }（模型分片构建进度，readXlsx 同步解析段无进度）
+ * - { type: 'progress', done, total }（模型分片构建进度，xlsx 解析段无进度）
  * - { type: 'done', ok: true, sheets: [{ name, snapshot }], activeIndex }（快照为
  *   纯数据，可结构化克隆）；失败 { type: 'done', ok: false, error }。
  *
- * 名字唯一化与活动表对齐由 buildWorkbookFromHucre 完成（worker 内），主线程
- * 直接把快照替换进目标（无 undo 历史——替换语义由确认后的 replaceWorkbook 负责）。
+ * 解析与构建经 sheet-core importXlsx 完成（hucre 仅由 sheet-core 依赖）；
+ * 名字唯一化与活动表对齐在 worker 内完成，主线程直接把快照替换进目标
+ * （无 undo 历史——替换语义由确认后的 replaceWorkbookWithSnapshots 负责）。
  *
  * 注意：必须用**运行时动态 import**——worker 顶层静态 import 在 vite dev 的
  * worker 上下文中会因模块图加载顺序导致 `Workbook is not defined`（实测）。
@@ -30,15 +31,11 @@ self.onmessage = (e: MessageEvent<{ buffer: ArrayBuffer }>): void => {
   const { buffer } = e.data
   void (async () => {
     try {
-      const [{ readXlsx }, { buildWorkbookFromHucre, XLSX_READ_OPTIONS }] = await Promise.all([
-        import('hucre/xlsx'),
-        import('@veltra/sheet-core/core/io/import')
-      ])
-      const hucreWb = await readXlsx(new Uint8Array(buffer), XLSX_READ_OPTIONS)
+      const { importXlsx } = await import('@veltra/sheet-core/core/io/import')
       // 分片构建：按 10% 粒度回报进度（避免 196 条/秒的消息风暴与文字跳变过快；
       // 模型构建段约 1s，10 次更新肉眼可见数字推进）
       let lastPercent = -1
-      const wb = buildWorkbookFromHucre(hucreWb, (done, total) => {
+      const wb = await importXlsx(new Uint8Array(buffer), (done, total) => {
         const percent = total > 0 ? Math.floor((done / total) * 10) : 10
         if (percent !== lastPercent || done === total) {
           lastPercent = percent

package/src/components/sheet/use-sheet-state.ts

@@ -123,8 +123,8 @@ export function useSheetState(props: SheetProps, emit: Emit, hooks: SheetStateHo
   }
 
   /**
-   * 工作簿内容被结构性替换后同步（如导入 xlsx 的 replaceWorkbook）：
-   * replaceWorkbook 未必触发 active-sheet-change（同 index），需显式同步 tabs、
+   * 工作簿内容被结构性替换后同步（如导入 xlsx 的 replaceWorkbookWithSnapshots）：
+   * 整簿替换未必触发 active-sheet-change（同 index），需显式同步 tabs、
    * 重绑 sheet 事件并重建网格。
    */
   function syncFromWorkbook(): void {

package/src/report/__test__/drill.test.ts

@@ -0,0 +1,194 @@
+import { Sheet, cellKey } from '@veltra/sheet-core'
+import { describe, expect, it } from 'vitest'
+
+import { REPORT_META_NAMESPACE } from '../binding'
+import {
+  buildDrillHitMap,
+  createDrillStack,
+  currentDrillLayer,
+  popDrillLayer,
+  pushDrillLayer,
+  resolveDrillParams
+} from '../drill'
+import { createReportTemplate, type ReportTemplate } from '../template'
+import type { ReportBinding, ReportDrillConfig } from '../types'
+
+// ---- 内联 fixtures ----
+
+/** 最小 Report Template：下钻栈只关心引用与参数，不消费快照内容 */
+function makeTemplate(rows: number): ReportTemplate {
+  return {
+    version: 1,
+    cells: [],
+    styles: [],
+    merges: [],
+    frozen: { rows: 0, cols: 0 },
+    rows,
+    cols: 0
+  }
+}
+
+const TPL_A = makeTemplate(10)
+const TPL_B = makeTemplate(20)
+const TPL_C = makeTemplate(30)
+
+const DRILL: ReportDrillConfig = {
+  target: 'tpl-detail',
+  mapping: { region: 'p_region', amount: 'p_amount' },
+  openMode: 'switch'
+}
+
+describe('resolveDrillParams', () => {
+  it('按映射从记录取值为详情报参数', () => {
+    const values = resolveDrillParams(DRILL, { region: '华东', amount: 100 })
+    expect(values).toEqual({ p_region: '华东', p_amount: 100 })
+  })
+
+  it('记录缺字段时跳过对应参数，null 值保留', () => {
+    const values = resolveDrillParams(DRILL, { region: '华东', amount: null })
+    expect(values).toEqual({ p_region: '华东', p_amount: null })
+    expect(
+      'p_missing' in resolveDrillParams({ ...DRILL, mapping: { missing: 'p_missing' } }, {})
+    ).toBe(false)
+  })
+
+  it('空映射返回空参数', () => {
+    expect(resolveDrillParams({ ...DRILL, mapping: {} }, { region: '华东' })).toEqual({})
+  })
+})
+
+describe('下钻栈', () => {
+  it('根层即当前层', () => {
+    const stack = createDrillStack({ template: TPL_A, params: { p: 'a0' } })
+    expect(stack).toHaveLength(1)
+    expect(currentDrillLayer(stack)).toEqual({ template: TPL_A, params: { p: 'a0' } })
+  })
+
+  it('push 后当前层为新层，前层参数定格为离开时的值', () => {
+    const stack = createDrillStack({ template: TPL_A, params: { p: 'a0' } })
+    const next = pushDrillLayer(stack, { template: TPL_B, params: { p: 'b1' } }, { p: 'a1' })
+    expect(next).toHaveLength(2)
+    expect(currentDrillLayer(next)).toEqual({ template: TPL_B, params: { p: 'b1' } })
+    expect(next[0]).toEqual({ template: TPL_A, params: { p: 'a1' } })
+    // 不可变更新：原栈不受影响
+    expect(stack).toHaveLength(1)
+  })
+
+  it('push 缺省 currentParams 时保留前层原参数', () => {
+    const stack = createDrillStack({ template: TPL_A, params: { p: 'a0' } })
+    const next = pushDrillLayer(stack, { template: TPL_B, params: {} })
+    expect(next[0]).toEqual({ template: TPL_A, params: { p: 'a0' } })
+  })
+
+  it('pop 逐级回退并保留各层当时参数', () => {
+    let stack = createDrillStack({ template: TPL_A, params: { p: 'a0' } })
+    stack = pushDrillLayer(stack, { template: TPL_B, params: { p: 'b1' } }, { p: 'a1' })
+    stack = pushDrillLayer(stack, { template: TPL_C, params: { p: 'c1' } }, { p: 'b2' })
+
+    stack = popDrillLayer(stack)
+    expect(currentDrillLayer(stack)).toEqual({ template: TPL_B, params: { p: 'b2' } })
+    stack = popDrillLayer(stack)
+    expect(currentDrillLayer(stack)).toEqual({ template: TPL_A, params: { p: 'a1' } })
+  })
+
+  it('仅剩根层时 pop 原样返回', () => {
+    const stack = createDrillStack({ template: TPL_A, params: {} })
+    expect(popDrillLayer(stack)).toBe(stack)
+  })
+
+  it('指向自身照常压栈，靠 pop 逐级退出', () => {
+    let stack = createDrillStack({ template: TPL_A, params: { p: 'a0' } })
+    stack = pushDrillLayer(stack, { template: TPL_A, params: { p: 'a1' } })
+    stack = pushDrillLayer(stack, { template: TPL_A, params: { p: 'a2' } })
+    expect(stack).toHaveLength(3)
+
+    stack = popDrillLayer(stack)
+    expect(currentDrillLayer(stack)).toEqual({ template: TPL_A, params: { p: 'a1' } })
+    stack = popDrillLayer(stack)
+    expect(currentDrillLayer(stack)).toEqual({ template: TPL_A, params: { p: 'a0' } })
+  })
+
+  it('成环照常压栈，回退沿压栈路径逐级退出', () => {
+    let stack = createDrillStack({ template: TPL_A, params: { p: 'root' } })
+    stack = pushDrillLayer(stack, { template: TPL_B, params: { p: 'b1' } })
+    stack = pushDrillLayer(stack, { template: TPL_A, params: { p: 'a-from-b' } })
+    stack = pushDrillLayer(stack, { template: TPL_B, params: { p: 'b2' } })
+    expect(stack.map((layer) => layer.template)).toEqual([TPL_A, TPL_B, TPL_A, TPL_B])
+
+    stack = popDrillLayer(stack)
+    expect(currentDrillLayer(stack)).toEqual({ template: TPL_A, params: { p: 'a-from-b' } })
+    stack = popDrillLayer(stack)
+    expect(currentDrillLayer(stack)).toEqual({ template: TPL_B, params: { p: 'b1' } })
+    stack = popDrillLayer(stack)
+    expect(currentDrillLayer(stack)).toEqual({ template: TPL_A, params: { p: 'root' } })
+  })
+})
+
+describe('buildDrillHitMap 与上下文解析', () => {
+  it('分组格与汇总聚合格均生成正确命中上下文（含汇总格自身聚合值）', () => {
+    const sheet = new Sheet()
+    sheet.setCellMeta({ row: 0, col: 0 }, REPORT_META_NAMESPACE, {
+      dataset: 'ds',
+      field: 'region',
+      aggregate: 'group',
+      expand: 'down',
+      drill: { target: 't2', mapping: { region: 'p_region' }, openMode: 'switch' }
+    })
+    sheet.setCellMeta({ row: 0, col: 1 }, REPORT_META_NAMESPACE, {
+      dataset: 'ds',
+      field: 'amount',
+      aggregate: 'sum',
+      expand: 'none',
+      rowParent: { row: 0, col: 0 },
+      drill: {
+        target: 't2',
+        mapping: { region: 'p_region', amount: 'p_amount' },
+        openMode: 'dialog'
+      }
+    })
+
+    const template = sheet.snapshot()
+    const data = {
+      ds: [
+        { region: '华东', amount: 100 },
+        { region: '华东', amount: 200 },
+        { region: '华南', amount: 50 }
+      ]
+    }
+
+    const hitMap = buildDrillHitMap(template, data)
+    // 华东分组格 (0,0)
+    const hitGroup0 = hitMap.get(cellKey({ row: 0, col: 0 }))
+    expect(hitGroup0?.record).toEqual({ region: '华东' })
+
+    // 华东汇总格 (0,1) 拥有祖先分组 region 与自身的求和计算值 300
+    const hitSum0 = hitMap.get(cellKey({ row: 0, col: 1 }))
+    expect(hitSum0?.record).toEqual({ region: '华东', amount: 300 })
+    expect(resolveDrillParams(hitSum0!.config, hitSum0!.record)).toEqual({
+      p_region: '华东',
+      p_amount: 300
+    })
+
+    // 华南汇总格 (1,1)
+    const hitSum1 = hitMap.get(cellKey({ row: 1, col: 1 }))
+    expect(hitSum1?.record).toEqual({ region: '华南', amount: 50 })
+    expect(resolveDrillParams(hitSum1!.config, hitSum1!.record)).toEqual({
+      p_region: '华南',
+      p_amount: 50
+    })
+  })
+})
+
+describe('旧绑定兼容', () => {
+  it('无 drill 字段的旧绑定序列化往返后不出现 drill 键', () => {
+    const binding: ReportBinding = {
+      dataset: 'orders',
+      field: 'region',
+      expand: 'down',
+      aggregate: 'list'
+    }
+    const restored = JSON.parse(JSON.stringify(binding)) as ReportBinding
+    expect('drill' in restored).toBe(false)
+    expect(restored.drill).toBeUndefined()
+  })
+})

package/src/report/__test__/export-xlsx.test.ts

@@ -1,10 +1,9 @@
 import { Sheet } from '@veltra/sheet-core'
-import { buildWorkbookFromHucre, XLSX_READ_OPTIONS } from '@veltra/sheet-core/core/io/import'
-import { readXlsx } from 'hucre/xlsx'
+import { importXlsx } from '@veltra/sheet-core/core/io/import'
 import { describe, expect, it } from 'vitest'
 
 import { REPORT_META_NAMESPACE, createReportBinding } from '../binding'
-import { buildColumnDefs, exportFilledReportXlsx, pxToExcelColWidth } from '../export-xlsx'
+import { exportFilledReportXlsx } from '../export-xlsx'
 import { renderReport } from '../render'
 import type { DatasetCatalogItem } from '../types'
 
@@ -69,8 +68,7 @@ describe('exportFilledReportXlsx', () => {
     expect(buffer[0]).toBe(0x50)
     expect(buffer[1]).toBe(0x4b)
 
-    const hucreWb = await readXlsx(buffer, XLSX_READ_OPTIONS)
-    const workbook = buildWorkbookFromHucre(hucreWb)
+    const workbook = await importXlsx(buffer)
     const sheet = workbook.getSheets()[0]!
 
     // 展开值保真（分组头 + 明细值）
@@ -96,23 +94,3 @@ describe('exportFilledReportXlsx', () => {
     expect(headerStyle?.fill?.color).toBe('#E8EEF7')
   })
 })
-
-describe('buildColumnDefs / pxToExcelColWidth', () => {
-  it('像素列宽换算为 Excel 字符宽度并写入对应列', () => {
-    expect(pxToExcelColWidth(120)).toBe(16)
-    expect(pxToExcelColWidth(0)).toBe(1)
-
-    const columns = buildColumnDefs([
-      [0, 120],
-      [2, 145]
-    ])
-    expect(columns).toHaveLength(3)
-    expect(columns[0]).toEqual({ width: 16 })
-    expect(columns[1]).toEqual({})
-    expect(columns[2]).toEqual({ width: 20 })
-  })
-
-  it('空列宽不产生 columns 定义', () => {
-    expect(buildColumnDefs([])).toEqual([])
-  })
-})

package/src/report/__test__/print.test.ts

@@ -0,0 +1,170 @@
+import { Sheet } from '@veltra/sheet-core'
+import { describe, expect, it } from 'vitest'
+
+import { buildFilledReportPrintHtml } from '../print'
+
+/** 基础填充表：表头 + 两列数据 */
+function createFilledSheet(name = '销售报表'): Sheet {
+  const sheet = new Sheet(name)
+  sheet.setCells([
+    { addr: { row: 0, col: 0 }, data: { v: '客户' } },
+    { addr: { row: 0, col: 1 }, data: { v: '金额' } },
+    { addr: { row: 1, col: 0 }, data: { v: '甲公司' } },
+    { addr: { row: 1, col: 1 }, data: { v: 100 } }
+  ])
+  return sheet
+}
+
+describe('buildFilledReportPrintHtml', () => {
+  it('输出完整打印文档：值为文本、默认 A4 纵向、缺省标题取 sheet 名', () => {
+    const html = buildFilledReportPrintHtml(createFilledSheet())
+
+    expect(html).toContain('<!doctype html>')
+    expect(html).toContain('<title>销售报表</title>')
+    expect(html).toContain('@page { size: A4 portrait;')
+    expect(html).toContain('<td>客户</td>')
+    expect(html).toContain('<td>100</td>')
+    // 默认列宽 80 / 行高 28（对齐 grid 默认）
+    expect(html).toContain('<col style="width:80px">')
+    expect(html).toContain('<tr style="height:28px">')
+    // 背景色打印保色
+    expect(html).toContain('print-color-adjust: exact')
+  })
+
+  it('选项：title 覆盖、landscape 方向；空名 sheet 回落「报表」', () => {
+    const html = buildFilledReportPrintHtml(createFilledSheet(), {
+      title: '月度报表',
+      orientation: 'landscape'
+    })
+    expect(html).toContain('<title>月度报表</title>')
+    expect(html).toContain('@page { size: A4 landscape;')
+
+    const fallback = buildFilledReportPrintHtml(new Sheet(''))
+    expect(fallback).toContain('<title>报表</title>')
+  })
+
+  it('合并格映射 rowspan/colspan，被覆盖格不输出', () => {
+    const sheet = createFilledSheet()
+    sheet.mergeCells({ start: { row: 0, col: 0 }, end: { row: 1, col: 1 } })
+
+    const html = buildFilledReportPrintHtml(sheet)
+    expect(html).toContain('<td colspan="2" rowspan="2">客户</td>')
+    // 2×2 合并后只剩 1 个 td（锚点），覆盖格跳过
+    const tdCount = (html.match(/<td/g) ?? []).length
+    expect(tdCount).toBe(1)
+  })
+
+  it('有效样式序列化为内联 CSS（fill/border/font/align/wrap）', () => {
+    const sheet = createFilledSheet()
+    sheet.setCellStyle(
+      { start: { row: 0, col: 0 }, end: { row: 0, col: 0 } },
+      {
+        fill: { color: '#ff0000' },
+        border: { top: { style: 'thin', width: 1, color: '#000000' } },
+        font: {
+          bold: true,
+          italic: true,
+          underline: true,
+          strikethrough: true,
+          size: 14,
+          color: '#111111'
+        },
+        align: { horizontal: 'center', vertical: 'middle', wrap: true }
+      }
+    )
+    sheet.setCellStyle(
+      { start: { row: 1, col: 1 }, end: { row: 1, col: 1 } },
+      { align: { horizontal: 'right' } }
+    )
+
+    const html = buildFilledReportPrintHtml(sheet)
+    expect(html).toContain('background-color:#ff0000')
+    expect(html).toContain('border-top:1px solid #000000')
+    expect(html).toContain('font-weight:bold')
+    expect(html).toContain('font-style:italic')
+    expect(html).toContain('text-decoration:underline line-through')
+    expect(html).toContain('font-size:14pt')
+    expect(html).toContain('color:#111111')
+    expect(html).toContain('text-align:center')
+    expect(html).toContain('vertical-align:middle')
+    expect(html).toContain('white-space:normal;word-break:break-all')
+    expect(html).toContain('text-align:right')
+  })
+
+  it('虚线/点线边框线型映射 CSS dashed/dotted', () => {
+    const sheet = createFilledSheet()
+    sheet.setCellStyle(
+      { start: { row: 0, col: 0 }, end: { row: 0, col: 0 } },
+      {
+        border: {
+          left: { style: 'dashed', width: 1, color: '#000000' },
+          right: { style: 'dotted', width: 2, color: '#00ff00' }
+        }
+      }
+    )
+    const html = buildFilledReportPrintHtml(sheet)
+    expect(html).toContain('border-left:1px dashed #000000')
+    expect(html).toContain('border-right:2px dotted #00ff00')
+  })
+
+  it('自定义列宽 / 行高写入 colgroup 与 tr', () => {
+    const sheet = createFilledSheet()
+    sheet.setColWidth(1, 160)
+    sheet.setRowHeight(1, 40)
+
+    const html = buildFilledReportPrintHtml(sheet)
+    expect(html).toContain('<col style="width:160px">')
+    expect(html).toContain('<tr style="height:40px">')
+  })
+
+  it('文本与标题 HTML 转义', () => {
+    const sheet = new Sheet('报表<Q>')
+    sheet.setCells([{ addr: { row: 0, col: 0 }, data: { v: '<b>"x"</b> & y' } }])
+
+    const html = buildFilledReportPrintHtml(sheet)
+    expect(html).toContain('<title>报表&lt;Q&gt;</title>')
+    expect(html).toContain('<td>&lt;b&gt;"x"&lt;/b&gt; &amp; y</td>')
+    expect(html).not.toContain('<td><b>')
+  })
+
+  it('浮动图：data URL 内嵌，锚点格左上 + 格内偏移定位，显式宽高直出', () => {
+    const sheet = createFilledSheet()
+    sheet.setColWidth(0, 100)
+    sheet.insertImage({
+      data: new Uint8Array([1, 2, 3]),
+      type: 'png',
+      anchor: { from: { row: 1, col: 1, offsetX: 10, offsetY: 5 } },
+      width: 48,
+      height: 24,
+      altText: '图章'
+    })
+
+    const html = buildFilledReportPrintHtml(sheet)
+    // left = col0 宽 100 + 默认列宽 80（col1 前）→ 取 col1 左缘 100... colWidths=[100,80]，col1 左缘=100，+offsetX=110
+    // top = row0 高 28，+offsetY=5 → 33
+    expect(html).toContain(`<img src="data:image/png;base64,AQID"`)
+    expect(html).toContain('left:110px;top:33px;width:48px;height:24px;')
+    expect(html).toContain('alt="图章"')
+  })
+
+  it('浮动图：宽高缺失且有 to 时按 from→to 跨度兜底', () => {
+    const sheet = createFilledSheet()
+    sheet.insertImage({
+      data: new Uint8Array([0]),
+      type: 'jpeg',
+      anchor: { from: { row: 0, col: 0 }, to: { row: 1, col: 1 } }
+    })
+
+    const html = buildFilledReportPrintHtml(sheet)
+    // 跨度：col0+col1 = 80+80 = 160；row0+row1 = 28+28 = 56
+    expect(html).toContain('left:0px;top:0px;width:160px;height:56px;')
+    expect(html).toContain('data:image/jpeg;base64,')
+  })
+
+  it('空 sheet 输出合法空表文档', () => {
+    const html = buildFilledReportPrintHtml(new Sheet('空白'))
+    expect(html).toContain('<title>空白</title>')
+    expect(html).toContain('<table>')
+    expect(html).not.toContain('<tr')
+  })
+})

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

@@ -325,6 +325,32 @@ describe('renderReport', () => {
     expect(firstAmount?.s).toBe(styleId)
   })
 
+  it('模板格对齐样式直通 Filled Report 快照（静态格与绑定扩展格）', () => {
+    const sheet = new Sheet()
+    seedGroupDetailTemplate(sheet)
+    // 静态表头格（resolveStatic 路径）
+    sheet.setCellStyle(
+      { start: { row: 0, col: 0 }, end: { row: 0, col: 0 } },
+      { align: { horizontal: 'right' } }
+    )
+    // 绑定明细格（resolveCell 路径，样式随扩展实例复制）
+    sheet.setCellStyle(
+      { start: { row: 1, col: 3 }, end: { row: 1, col: 3 } },
+      { align: { horizontal: 'center' } }
+    )
+
+    const filled = renderReport(sheet.snapshot(), MOCK_DATA_RECORDS)
+    const header = filled.cells.find((c) => c.row === 0 && c.col === 0)
+    expect(filled.styles[(header!.s ?? 1) - 1]?.align?.horizontal).toBe('right')
+
+    const firstAmount = filled.cells.find((c) => c.row === 1 && c.col === 3)
+    expect(firstAmount?.s).toBeDefined()
+    expect(filled.styles[(firstAmount!.s ?? 1) - 1]?.align?.horizontal).toBe('center')
+    // 展开带后续实例同样携带对齐
+    const secondAmount = filled.cells.find((c) => c.row === 2 && c.col === 3)
+    expect(filled.styles[(secondAmount!.s ?? 1) - 1]?.align?.horizontal).toBe('center')
+  })
+
   it('subtotal 支持 avg / count 聚合', () => {
     const sheet = new Sheet()
     seedGroupDetailTemplate(sheet)

package/src/report/drill.ts

@@ -0,0 +1,112 @@
+import type { SheetSnapshot } from '@veltra/sheet-core'
+import { cellKey } from '@veltra/sheet-core'
+
+import { AggregateIndex, resolvePlacementContext } from './render/aggregate'
+import { computeExpansionLayout } from './render/coordinate'
+import { buildTemplateIndex } from './render/template-index'
+import type { ReportTemplate } from './template'
+import type { DatasetRecords, ParamValues, ReportDrillConfig } from './types'
+
+/**
+ * 宿主模板解析契约：按下钻 target 引用取回目标模板（允许同步/异步）。
+ * 失败抛错——查看器提示可读错误并停留当前报；设计器配置对话框据此解析目标模板查询参数。
+ */
+export type ResolveReportTemplate = (ref: string) => ReportTemplate | Promise<ReportTemplate>
+
+/**
+ * 按下钻映射从该格对应记录取值，生成详情报 Filter Bar 参数值。
+ * 记录缺字段（值为 `undefined`）时跳过对应参数，由详情报回退默认值；空映射返回空参数。
+ */
+export function resolveDrillParams(
+  config: ReportDrillConfig,
+  record: Record<string, unknown>
+): ParamValues {
+  const values: ParamValues = {}
+  for (const [field, paramId] of Object.entries(config.mapping)) {
+    const value = record[field]
+    if (value === undefined) continue
+    values[paramId] = value
+  }
+  return values
+}
+
+/** 下钻栈层：一张报表模板 + 当时 Filter Bar 参数值（回退时据此恢复并重新取数） */
+export interface DrillStackLayer {
+  template: ReportTemplate
+  params: ParamValues
+}
+
+/**
+ * 下钻栈：自根（初始报表）到顶的层序列，至少一层。
+ * 只经下方纯函数做不可变更新（返回新栈），便于组件层直接挂响应式。
+ */
+export type DrillStack = DrillStackLayer[]
+
+/** 以初始报表为根层创建下钻栈 */
+export function createDrillStack(root: DrillStackLayer): DrillStack {
+  return [{ template: root.template, params: { ...root.params } }]
+}
+
+/**
+ * 压入详情报新层并使其成为当前层；`currentParams` 把当前层参数定格为离开时的值
+ * （缺省保留原值）。指向自身或成环不做检测，照常压栈，靠 pop 逐级退出。
+ */
+export function pushDrillLayer(
+  stack: DrillStack,
+  next: DrillStackLayer,
+  currentParams?: ParamValues
+): DrillStack {
+  const top = stack[stack.length - 1]!
+  const layers = currentParams
+    ? [...stack.slice(0, -1), { template: top.template, params: { ...currentParams } }]
+    : [...stack]
+  layers.push({ template: next.template, params: { ...next.params } })
+  return layers
+}
+
+/** 弹出当前层返回上一层；仅剩根层时原样返回（查看器始终保留一张报表） */
+export function popDrillLayer(stack: DrillStack): DrillStack {
+  if (stack.length <= 1) return stack
+  return stack.slice(0, -1)
+}
+
+/** 当前层（栈顶） */
+export function currentDrillLayer(stack: DrillStack): DrillStackLayer {
+  return stack[stack.length - 1]!
+}
+
+/** 下钻命中：物理格对应的下钻配置与该格记录 */
+export interface DrillHit {
+  config: ReportDrillConfig
+  record: Record<string, unknown>
+}
+
+/**
+ * 构建填充报表的物理格 → 下钻命中索引（每次成功取数后重建）。
+ * 仅含配了下钻的绑定格落点（含分组/汇总格与展开后的实例格，合并跨度内每格都命中）；
+ * 记录由 `resolvePlacementContext` 解析：list 明细取源数据行，分组/汇总取分组上下文。
+ */
+export function buildDrillHitMap(
+  template: SheetSnapshot,
+  data: DatasetRecords
+): Map<number, DrillHit> {
+  const hits = new Map<number, DrillHit>()
+  const index = buildTemplateIndex(template)
+  const layout = computeExpansionLayout(index, data)
+  const aggregateIndex = new AggregateIndex(data)
+
+  for (const placement of layout.placements) {
+    const config = placement.binding?.drill
+    if (!config) continue
+    const record = resolvePlacementContext(placement, index, data, aggregateIndex)
+    if (!record) continue
+
+    const hit: DrillHit = { config, record }
+    for (let row = placement.physical.start.row; row <= placement.physical.end.row; row++) {
+      for (let col = placement.physical.start.col; col <= placement.physical.end.col; col++) {
+        hits.set(cellKey({ row, col }), hit)
+      }
+    }
+  }
+  return hits
+}