@veltra/sheet 2.2.0 → 2.3.0

package/src/report/binding.ts

@@ -76,14 +76,71 @@ export function isVerticalExpandBinding(binding: ReportBinding): boolean {
 }
 
 export function isHorizontalExpandBinding(binding: ReportBinding): boolean {
+  return (
+    binding.expand === 'right' && (binding.aggregate === 'group' || binding.aggregate === 'list')
+  )
+}
+
+export function isRowGroupBinding(binding: ReportBinding): boolean {
+  return binding.expand === 'down' && binding.aggregate === 'group'
+}
+
+export function isColGroupBinding(binding: ReportBinding): boolean {
   return binding.expand === 'right' && binding.aggregate === 'group'
 }
 
+export function isReductionAggregate(aggregate: ReportAggregate): boolean {
+  return (
+    aggregate === 'sum' ||
+    aggregate === 'avg' ||
+    aggregate === 'count' ||
+    aggregate === 'max' ||
+    aggregate === 'min'
+  )
+}
+
+/** 小计 / 汇总 / 交叉格的父格候选只列分组头 */
+export function prefersGroupParent(binding: ReportBinding): boolean {
+  if (
+    binding.preset === 'subtotal' ||
+    binding.preset === 'grandTotal' ||
+    binding.preset === 'cross'
+  ) {
+    return true
+  }
+  return binding.expand === 'none' && isReductionAggregate(binding.aggregate)
+}
+
+/** 当前 expand / aggregate 是否仍属于已写入的预设族（同族内改聚合不掉到「自定义」） */
+export function presetStillApplies(binding: ReportBinding): boolean {
+  const preset = binding.preset
+  if (!preset) return false
+  if (preset === 'groupHeader') {
+    return (
+      binding.aggregate === 'group' && (binding.expand === 'down' || binding.expand === 'right')
+    )
+  }
+  if (preset === 'detail') {
+    return binding.aggregate === 'list' && (binding.expand === 'down' || binding.expand === 'right')
+  }
+  return binding.expand === 'none' && isReductionAggregate(binding.aggregate)
+}
+
+const DEFAULT_SCAN_COLS = 64
+const DEFAULT_SCAN_ROWS = 64
+
+type GetBindingAt = (addr: CellAddress) => ReportBinding | undefined
+
+export interface InferParentOptions {
+  /** 小计落格：必须优先分组头，禁止把同列/同行明细当成父格 */
+  preferGroup?: boolean
+}
+
 /** 指定模板行是否含纵向扩展绑定（展开带行） */
 export function isExpansionBandRow(
   row: number,
-  getBindingAt: (addr: CellAddress) => ReportBinding | undefined,
-  scanCols = 64
+  getBindingAt: GetBindingAt,
+  scanCols = DEFAULT_SCAN_COLS
 ): boolean {
   for (let col = 0; col < scanCols; col++) {
     const binding = getBindingAt({ row, col })
@@ -92,27 +149,50 @@ export function isExpansionBandRow(
   return false
 }
 
-/** 落格时推断预设：默认明细；数值字段且位于展开带正下方相邻行 → 小计 */
+/** 指定模板列是否含横向扩展绑定（展开带列） */
+export function isExpansionBandCol(
+  col: number,
+  getBindingAt: GetBindingAt,
+  scanRows = DEFAULT_SCAN_ROWS
+): boolean {
+  for (let row = 0; row < scanRows; row++) {
+    const binding = getBindingAt({ row, col })
+    if (binding && isHorizontalExpandBinding(binding)) return true
+  }
+  return false
+}
+
+/** 落格时推断预设：默认明细；数值字段且位于展开带正下方或正右相邻 → 小计 */
 export function inferDropPreset(
   addr: CellAddress,
   fieldType: DatasetCatalogItem['fields'][number]['type'],
-  getBindingAt: (addr: CellAddress) => ReportBinding | undefined
+  getBindingAt: GetBindingAt
 ): ReportPreset {
-  if (fieldType === 'number' && addr.row > 0 && isExpansionBandRow(addr.row - 1, getBindingAt)) {
-    return 'subtotal'
-  }
+  if (fieldType !== 'number') return 'detail'
+  if (addr.row > 0 && isExpansionBandRow(addr.row - 1, getBindingAt)) return 'subtotal'
+  if (addr.col > 0 && isExpansionBandCol(addr.col - 1, getBindingAt)) return 'subtotal'
   return 'detail'
 }
 
+export interface ListParentCandidateOptions {
+  preferGroup?: boolean
+}
+
 /** 同数据集纵向扩展绑定格（行方向父格下拉候选） */
 export function listRowParentCandidates(
   binding: ReportBinding,
-  entries: ReadonlyArray<{ addr: CellAddress; binding: ReportBinding }>
+  entries: ReadonlyArray<{ addr: CellAddress; binding: ReportBinding }>,
+  options?: ListParentCandidateOptions
 ): CellAddress[] {
+  const preferGroup = options?.preferGroup === true
   const candidates: CellAddress[] = []
   for (const entry of entries) {
     if (entry.binding.dataset !== binding.dataset) continue
-    if (!isVerticalExpandBinding(entry.binding)) continue
+    if (preferGroup) {
+      if (!isRowGroupBinding(entry.binding)) continue
+    } else if (!isVerticalExpandBinding(entry.binding)) {
+      continue
+    }
     candidates.push(entry.addr)
   }
   return candidates
@@ -121,73 +201,204 @@ export function listRowParentCandidates(
 /** 同数据集横向扩展绑定格（列方向父格下拉候选） */
 export function listColParentCandidates(
   binding: ReportBinding,
-  entries: ReadonlyArray<{ addr: CellAddress; binding: ReportBinding }>
+  entries: ReadonlyArray<{ addr: CellAddress; binding: ReportBinding }>,
+  options?: ListParentCandidateOptions
 ): CellAddress[] {
+  const preferGroup = options?.preferGroup === true
   const candidates: CellAddress[] = []
   for (const entry of entries) {
     if (entry.binding.dataset !== binding.dataset) continue
-    if (!isHorizontalExpandBinding(entry.binding)) continue
+    if (preferGroup) {
+      if (!isColGroupBinding(entry.binding)) continue
+    } else if (!isHorizontalExpandBinding(entry.binding)) {
+      continue
+    }
     candidates.push(entry.addr)
   }
   return candidates
 }
 
-/** 同列向上找最近的纵向扩展绑定，作为 rowParent 候选 */
+interface ScanHit {
+  addr: CellAddress
+  group: boolean
+  distance: number
+}
+
+function betterHit(current: ScanHit | null, next: ScanHit): boolean {
+  if (!current) return true
+  if (next.distance !== current.distance) return next.distance < current.distance
+  return next.addr.col + next.addr.row < current.addr.col + current.addr.row
+}
+
+function pickExpandHit(hits: ScanHit[], preferGroup: boolean): CellAddress | null {
+  let group: ScanHit | null = null
+  let expand: ScanHit | null = null
+  for (const hit of hits) {
+    if (hit.group && betterHit(group, hit)) group = hit
+    if (betterHit(expand, hit)) expand = hit
+  }
+  if (preferGroup) return group?.addr ?? null
+  return group?.addr ?? expand?.addr ?? null
+}
+
+function scanVerticalOnRow(
+  row: number,
+  originCol: number,
+  colStart: number,
+  colEnd: number,
+  getBindingAt: GetBindingAt
+): ScanHit[] {
+  const hits: ScanHit[] = []
+  for (let col = colStart; col < colEnd; col++) {
+    const binding = getBindingAt({ row, col })
+    if (!binding || !isVerticalExpandBinding(binding)) continue
+    hits.push({
+      addr: { row, col },
+      group: isRowGroupBinding(binding),
+      distance: Math.abs(col - originCol)
+    })
+  }
+  return hits
+}
+
+function scanHorizontalOnCol(
+  col: number,
+  originRow: number,
+  rowStart: number,
+  rowEnd: number,
+  getBindingAt: GetBindingAt
+): ScanHit[] {
+  const hits: ScanHit[] = []
+  for (let row = rowStart; row < rowEnd; row++) {
+    const binding = getBindingAt({ row, col })
+    if (!binding || !isHorizontalExpandBinding(binding)) continue
+    hits.push({
+      addr: { row, col },
+      group: isColGroupBinding(binding),
+      distance: Math.abs(row - originRow)
+    })
+  }
+  return hits
+}
+
+/**
+ * 行方向父格推断：
+ * 1. 同行向左：先找分组头，否则最近纵向扩展格
+ * 2. 上方各行整行扫描：每行先找分组头，再退回任意纵向扩展格
+ * 小计（preferGroup）禁止把明细当成父格
+ */
 export function inferRowParentCandidate(
   addr: CellAddress,
-  getBindingAt: (addr: CellAddress) => ReportBinding | undefined
+  getBindingAt: GetBindingAt,
+  options?: InferParentOptions
 ): CellAddress | null {
+  const preferGroup = options?.preferGroup === true
+
+  const sameRow = pickExpandHit(
+    scanVerticalOnRow(addr.row, addr.col, 0, addr.col, getBindingAt),
+    preferGroup
+  )
+  if (sameRow) return sameRow
+
   for (let row = addr.row - 1; row >= 0; row--) {
-    const binding = getBindingAt({ row, col: addr.col })
-    if (binding && isVerticalExpandBinding(binding)) {
-      return { row, col: addr.col }
-    }
+    const found = pickExpandHit(
+      scanVerticalOnRow(row, addr.col, 0, DEFAULT_SCAN_COLS, getBindingAt),
+      preferGroup
+    )
+    if (found) return found
   }
   return null
 }
 
-/** 同行向左找最近的横向扩展绑定，作为 colParent 候选 */
+/**
+ * 列方向父格推断（与行方向对称）：
+ * 1. 同列向上：先找列分组头，否则最近横向扩展格
+ * 2. 左侧各列整列扫描：每列先找列分组头
+ * 列小计（preferGroup）禁止把交叉格/明细当成列父格
+ */
 export function inferColParentCandidate(
   addr: CellAddress,
-  getBindingAt: (addr: CellAddress) => ReportBinding | undefined
+  getBindingAt: GetBindingAt,
+  options?: InferParentOptions
 ): CellAddress | null {
+  const preferGroup = options?.preferGroup === true
+
+  const sameCol = pickExpandHit(
+    scanHorizontalOnCol(addr.col, addr.row, 0, addr.row, getBindingAt),
+    preferGroup
+  )
+  if (sameCol) return sameCol
+
   for (let col = addr.col - 1; col >= 0; col--) {
-    const binding = getBindingAt({ row: addr.row, col })
-    if (binding && isHorizontalExpandBinding(binding)) {
-      return { row: addr.row, col }
-    }
+    const found = pickExpandHit(
+      scanHorizontalOnCol(col, addr.row, 0, DEFAULT_SCAN_ROWS, getBindingAt),
+      preferGroup
+    )
+    if (found) return found
   }
   return null
 }
 
+function suggestsColumnSubtotal(above: ReportBinding | undefined): boolean {
+  if (!above) return false
+  return isHorizontalExpandBinding(above) || !!above.colParent || above.preset === 'cross'
+}
+
+function suggestsRowSubtotal(left: ReportBinding | undefined): boolean {
+  if (!left) return false
+  return isVerticalExpandBinding(left) || !!left.rowParent || left.preset === 'cross'
+}
+
+/**
+ * 按预设写入落格父格：明细/分组/交叉双方向推断；小计按「下方行小计 / 右侧列小计」只挂对应轴。
+ */
+export function inferParentsForPreset(
+  addr: CellAddress,
+  preset: ReportPreset,
+  getBindingAt: GetBindingAt
+): Pick<ReportBinding, 'rowParent' | 'colParent'> {
+  if (preset === 'grandTotal') return {}
+
+  const preferGroup = preset === 'subtotal' || preset === 'cross'
+  const rowParent = inferRowParentCandidate(addr, getBindingAt, { preferGroup }) ?? undefined
+  const colParent = inferColParentCandidate(addr, getBindingAt, { preferGroup }) ?? undefined
+
+  if (preset !== 'subtotal') {
+    return { ...(rowParent ? { rowParent } : {}), ...(colParent ? { colParent } : {}) }
+  }
+
+  const above = addr.row > 0 ? getBindingAt({ row: addr.row - 1, col: addr.col }) : undefined
+  const left = addr.col > 0 ? getBindingAt({ row: addr.row, col: addr.col - 1 }) : undefined
+  const belowBand = addr.row > 0 && isExpansionBandRow(addr.row - 1, getBindingAt)
+  const rightOfBand = addr.col > 0 && isExpansionBandCol(addr.col - 1, getBindingAt)
+
+  const columnSubtotal =
+    suggestsColumnSubtotal(above) || (rightOfBand && !suggestsRowSubtotal(left))
+  const rowSubtotal = suggestsRowSubtotal(left) || (belowBand && !columnSubtotal)
+
+  const result: Pick<ReportBinding, 'rowParent' | 'colParent'> = {}
+  if (rowSubtotal && rowParent) result.rowParent = rowParent
+  if (columnSubtotal && colParent) result.colParent = colParent
+  if (!rowSubtotal && !columnSubtotal) {
+    if (belowBand && rowParent) result.rowParent = rowParent
+    else if (rightOfBand && colParent) result.colParent = colParent
+    else {
+      if (rowParent) result.rowParent = rowParent
+      if (colParent) result.colParent = colParent
+    }
+  }
+  return result
+}
+
 /** 从绑定字段推断预设；不匹配任何预设时返回 null（自定义） */
 export function inferReportPreset(binding: ReportBinding): ReportPreset | null {
   if (binding.preset) return binding.preset
 
-  if (
-    binding.expand === 'none' &&
-    binding.aggregate === 'sum' &&
-    binding.rowParent &&
-    binding.colParent
-  ) {
-    return 'cross'
-  }
-  if (
-    binding.expand === 'none' &&
-    binding.aggregate === 'sum' &&
-    !binding.rowParent &&
-    !binding.colParent
-  ) {
+  if (binding.expand === 'none' && isReductionAggregate(binding.aggregate)) {
+    if (binding.rowParent && binding.colParent) return 'cross'
+    if (binding.rowParent || binding.colParent) return 'subtotal'
     return 'grandTotal'
   }
-  if (
-    binding.expand === 'none' &&
-    binding.aggregate === 'sum' &&
-    binding.rowParent &&
-    !binding.colParent
-  ) {
-    return 'subtotal'
-  }
   if (binding.aggregate === 'group' && (binding.expand === 'down' || binding.expand === 'right')) {
     return 'groupHeader'
   }
@@ -233,11 +444,31 @@ function resolveFieldLabel(
   return field?.label ?? fieldName
 }
 
+/** Binding Placeholder 分段文案（聚合标签 + 字段标签），供徽章分色渲染等场景使用 */
+export function formatBindingPlaceholderParts(
+  binding: ReportBinding,
+  resolveLabel?: (datasetId: string, fieldName: string) => string
+): { tag: string; label: string } {
+  return {
+    tag: AGGREGATE_PLACEHOLDER_TAG[binding.aggregate],
+    label: resolveFieldLabel(binding.dataset, binding.field, resolveLabel)
+  }
+}
+
 /** Binding Placeholder 中文可读文案（如「分组 · 客户」） */
 export function formatBindingPlaceholder(
   binding: ReportBinding,
   resolveLabel?: (datasetId: string, fieldName: string) => string
 ): string {
-  const tag = AGGREGATE_PLACEHOLDER_TAG[binding.aggregate]
-  return `${tag} · ${resolveFieldLabel(binding.dataset, binding.field, resolveLabel)}`
+  const { tag, label } = formatBindingPlaceholderParts(binding, resolveLabel)
+  return `${tag} · ${label}`
+}
+
+/** 父格下拉候选文案（如「分组 · 客户 (A2)」） */
+export function formatParentCandidateLabel(
+  addr: CellAddress,
+  binding: ReportBinding,
+  resolveLabel?: (datasetId: string, fieldName: string) => string
+): string {
+  return `${formatBindingPlaceholder(binding, resolveLabel)} (${formatCellAddress(addr)})`
 }

package/src/report/connector.ts

@@ -73,9 +73,10 @@ export interface CreateHttpConnectorOptions {
 // ---- HTTP 契约响应形状（ADR-0003 决策 3）----
 // 传输层错误用 HTTP 状态码；业务错误一律 `200 + { ok: false, error }`。
 
-/** 契约字段 schema：`{ name, type? }`（type 缺省视为 string） */
+/** 契约字段 schema：`{ name, label?, type? }`（label 缺省视为 name，type 缺省视为 string） */
 interface ContractField {
   name: string
+  label?: string
   type?: DatasetField['type']
 }
 
@@ -113,7 +114,7 @@ function toConnectorError(value: unknown): ConnectorError {
 
 /** 契约字段 → 内核 DatasetField（label 缺省回退 name，type 缺省 string） */
 function normalizeField(field: ContractField): DatasetField {
-  return { name: field.name, label: field.name, type: field.type ?? 'string' }
+  return { name: field.name, label: field.label ?? field.name, type: field.type ?? 'string' }
 }
 
 /** 校验并归一化契约 fields；形状不合法返回 null */

package/src/report/export-xlsx.ts

@@ -3,7 +3,7 @@ import { rangeToHucre, styleToHucre } from '@veltra/sheet-core/core/io/export'
 import type { Cell, CellValue, ColumnDef, RowDef, WriteSheet } from 'hucre'
 import { writeXlsx } from 'hucre/xlsx'
 
-/** 列宽条目：模型列索引 → 像素宽（sheet-core 列宽未进 SheetSnapshot，导出时由调用方显式传入） */
+/** 列宽条目：模型列索引 → 像素宽（与 SheetSnapshot.colWidths 同构） */
 export type ReportColWidthEntry = readonly [number, number]
 
 /** 像素 → Excel points */
@@ -30,14 +30,11 @@ export function buildColumnDefs(colWidths: ReadonlyArray<ReportColWidthEntry>):
 /**
  * 将已填充的 Sheet（Filled Report）导出为保真 XLSX（合并 / 样式 / 行高 / 列宽）。
  * 条件样式颜色已在 renderReport 展开阶段打平进 StylePool（ADR-0001 决策 2）。
- *
- * 与 `exportWorkbookXlsx`（sheet-core）的差异：列宽未进 SheetSnapshot，
- * 只能经 VTable 运行时读取，故这里接收显式列宽并写入 columns 定义。
+ * 列宽取自 sheet 模型（`getColWidths`）。
  */
-export async function exportFilledReportXlsx(
-  sheet: Sheet,
-  colWidths: ReadonlyArray<ReportColWidthEntry>
-): Promise<Uint8Array> {
+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()) {
@@ -47,7 +44,7 @@ export async function exportFilledReportXlsx(
   for (const [row] of sheet.getRowHeights()) {
     if (row > maxRow) maxRow = row
   }
-  for (const [col] of colWidths) {
+  for (const [col] of widths) {
     if (col > maxCol) maxCol = col
   }
 
@@ -63,10 +60,8 @@ export async function exportFilledReportXlsx(
     const row = rows[addr.row]!
     const key = `${addr.row},${addr.col}`
     const cell: Partial<Cell> = {}
-    if (data.s != null) {
-      const style = sheet.stylePool.get(data.s)
-      if (style) cell.style = styleToHucre(style)
-    }
+    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
@@ -100,7 +95,7 @@ export async function exportFilledReportXlsx(
     ...(sheet.merges.size > 0
       ? { merges: sheet.merges.getMerges().map((range) => rangeToHucre(range)) }
       : {}),
-    ...(colWidths.length > 0 ? { columns: buildColumnDefs(colWidths) } : {})
+    ...(widths.length > 0 ? { columns: buildColumnDefs(widths) } : {})
   }
 
   const frozen = sheet.frozen

package/src/report/render/aggregate.ts

@@ -55,9 +55,20 @@ function isColExpanding(binding: ReportBinding): boolean {
   )
 }
 
+function isReductionAggregate(aggregate: ReportAggregate): boolean {
+  return (
+    aggregate === 'sum' ||
+    aggregate === 'avg' ||
+    aggregate === 'count' ||
+    aggregate === 'max' ||
+    aggregate === 'min'
+  )
+}
+
 function rowExpandingAncestors(
   binding: ReportBinding,
-  index: TemplateIndex
+  index: TemplateIndex,
+  groupsOnly: boolean
 ): Array<{ addr: CellAddress; binding: ReportBinding }> {
   const chain: Array<{ addr: CellAddress; binding: ReportBinding }> = []
   let current = binding.rowParent
@@ -66,12 +77,17 @@ function rowExpandingAncestors(
     if (parentBinding) chain.unshift({ addr: current, binding: parentBinding })
     current = parentBinding?.rowParent
   }
-  return chain.filter((item) => isRowExpanding(item.binding))
+  return chain.filter((item) => {
+    if (!isRowExpanding(item.binding)) return false
+    if (groupsOnly && item.binding.aggregate !== 'group') return false
+    return true
+  })
 }
 
 function colExpandingAncestors(
   binding: ReportBinding,
-  index: TemplateIndex
+  index: TemplateIndex,
+  groupsOnly: boolean
 ): Array<{ addr: CellAddress; binding: ReportBinding }> {
   const chain: Array<{ addr: CellAddress; binding: ReportBinding }> = []
   let current = binding.colParent
@@ -80,7 +96,11 @@ function colExpandingAncestors(
     if (parentBinding) chain.unshift({ addr: current, binding: parentBinding })
     current = parentBinding?.colParent
   }
-  return chain.filter((item) => isColExpanding(item.binding))
+  return chain.filter((item) => {
+    if (!isColExpanding(item.binding)) return false
+    if (groupsOnly && item.binding.aggregate !== 'group') return false
+    return true
+  })
 }
 
 function mergeFilters(
@@ -99,8 +119,9 @@ function resolveAncestorFilters(
   const rowFilter: Record<string, unknown> = {}
   const colFilter: Record<string, unknown> = {}
   let parentFilter: Record<string, unknown> = {}
+  const groupsOnly = isReductionAggregate(binding.aggregate)
 
-  const rowAncestors = rowExpandingAncestors(binding, index)
+  const rowAncestors = rowExpandingAncestors(binding, index, groupsOnly)
   for (let i = 0; i < rowAncestors.length; i++) {
     const ancestor = rowAncestors[i]!
     if (ancestor.binding.dataset !== binding.dataset) continue
@@ -114,7 +135,7 @@ function resolveAncestorFilters(
   }
 
   parentFilter = {}
-  const colAncestors = colExpandingAncestors(binding, index)
+  const colAncestors = colExpandingAncestors(binding, index, groupsOnly)
   for (let i = 0; i < colAncestors.length; i++) {
     const ancestor = colAncestors[i]!
     if (ancestor.binding.dataset !== binding.dataset) continue
@@ -136,8 +157,8 @@ function resolveOwnGroupValue(
   index: TemplateIndex,
   data: DatasetRecords
 ): unknown {
-  const rowAncestors = rowExpandingAncestors(binding, index)
-  const colAncestors = colExpandingAncestors(binding, index)
+  const rowAncestors = rowExpandingAncestors(binding, index, false)
+  const colAncestors = colExpandingAncestors(binding, index, false)
   let parentFilter: Record<string, unknown> = {}
 
   for (let i = 0; i < rowAncestors.length; i++) {

package/src/report/template.ts

@@ -12,7 +12,7 @@ import type {
 } from './types'
 
 /**
- * 模板内嵌的数据集定义（Dataset = Data Connection + SQL，ADR-0002 决策 2）。
+ * 模板内嵌的数据集定义
  * 与 playground DatasetDef 同构，connectionId 替换为内嵌的完整连接对象。
  */
 export interface ReportDatasetDef {
@@ -26,7 +26,7 @@ export interface ReportDatasetDef {
   fieldOverrides?: Record<string, Partial<Pick<DatasetField, 'label'>>>
 }
 
-/** 当前支持的报表模板版本（ADR-0005 决策 4） */
+/** 当前支持的报表模板版本 */
 export const REPORT_TEMPLATE_VERSION = 1
 
 /** 模板版本不兼容时抛出 */
@@ -40,8 +40,9 @@ export class IncompatibleTemplateVersionError extends Error {
 /**
  * 自包含 Report Template：SheetSnapshot + 内嵌数据集定义 + 版本段。
  * 查看器仅凭 `template` + `connector` 即可完成「参数提取 → 取数 → 展开渲染」闭环；
- * 模板可 JSON 序列化流转（凭据随之流转，持久化与安全存储由下游负责，ADR-0003 决策 4）。
+ * 模板可 JSON 序列化流转。
  *
+ * `colWidths` 继承自 `SheetSnapshot.colWidths`（模型列索引 → 像素）。
  * 注意：`Sheet.snapshot()` 不产生 `datasets` / `version` 字段，经 `restore()`/`snapshot()` 往返会丢失，
  * 由设计器 `getTemplate()` 在吐出快照时重新附加。
  */
@@ -65,7 +66,10 @@ export function assertCompatibleTemplateVersion(template: ReportTemplate): void
   }
 }
 
-/** 由工作簿快照构造带版本段的 Report Template */
+/**
+ * 由工作簿快照构造带版本段的 Report Template。
+ * `colWidths` 随 `snapshot` 展开（已在 `SheetSnapshot.colWidths`）。
+ */
 export function createReportTemplate(
   snapshot: SheetSnapshot,
   datasets?: ReportDatasetDef[]