@veltra/sheet 2.4.0 → 2.5.1

package/src/report/render/index.ts

@@ -1,30 +0,0 @@
-import type { SheetSnapshot } from '@veltra/sheet-core'
-
-import type { ReportColWidthEntry } from '../export-xlsx'
-import type { DatasetRecords } from '../types'
-import { buildFilledReport, mapFilledColWidths } from './builder'
-import { computeExpansionLayout } from './coordinate'
-import { buildTemplateIndex } from './template-index'
-
-/**
- * 将 Report Template 按 Dataset 渲染为 Filled Report 快照。
- * 基于显式展开方向与父格关系展开，不做坐标推断。
- */
-export function renderReport(template: SheetSnapshot, data: DatasetRecords): SheetSnapshot {
-  const index = buildTemplateIndex(template)
-  const layout = computeExpansionLayout(index, data)
-  return buildFilledReport(template, index, layout, data)
-}
-
-/** 将设计态模板列宽映射为填充报表物理列宽（横向展开列继承父格列宽） */
-export function resolveFilledColWidths(
-  template: SheetSnapshot,
-  data: DatasetRecords,
-  templateColWidths: ReadonlyArray<ReportColWidthEntry>
-): ReportColWidthEntry[] {
-  const index = buildTemplateIndex(template)
-  const layout = computeExpansionLayout(index, data)
-  return mapFilledColWidths(templateColWidths, layout, index)
-}
-
-export { mapFilledColWidths } from './builder'

package/src/report/render/style-resolver.ts

@@ -1,68 +0,0 @@
-import type { CellStyle, SheetSnapshot } from '@veltra/sheet-core'
-import { StylePool } from '@veltra/sheet-core'
-import { mergeCellStyle } from '@veltra/sheet-core/core/command/set-cell-style'
-
-import { evaluateConditionalStyle, type ConditionalEvalContext } from '../rules'
-import type { ConditionalRule } from '../types'
-
-/** 静态样式经 StylePool 复用 + 条件样式打平（含 `scope: 'row'` 两阶段叠加） */
-export class StyleResolver {
-  private readonly pool = new StylePool()
-  private readonly rowStyleByPhysRow = new Map<number, CellStyle>()
-
-  constructor(private readonly template: SheetSnapshot) {
-    if (template.styles.length > 0) this.pool.restore(template.styles)
-  }
-
-  /** 收集 `scope: 'row'` 命中样式，按物理行累加（须在输出静态格之前完成） */
-  collectRowStyle(
-    physicalRow: number,
-    ctx: ConditionalEvalContext,
-    rules: readonly ConditionalRule[] | undefined
-  ): void {
-    if (!rules?.some((rule) => rule.scope === 'row')) return
-
-    const patch = evaluateConditionalStyle(ctx, undefined, rules, 'row')
-    if (!patch) return
-
-    const existing = this.rowStyleByPhysRow.get(physicalRow)
-    this.rowStyleByPhysRow.set(physicalRow, mergeCellStyle(existing, patch) ?? patch)
-  }
-
-  /** 解析模板格基础样式 + `scope: 'cell'` 条件样式 */
-  resolveCell(
-    templateRow: number,
-    templateCol: number,
-    ctx: ConditionalEvalContext,
-    rules: readonly ConditionalRule[] | undefined
-  ): number | undefined {
-    const tpl = this.template.cells.find((c) => c.row === templateRow && c.col === templateCol)
-    const baseStyle = tpl?.s !== undefined ? this.pool.get(tpl.s) : undefined
-    const merged = evaluateConditionalStyle(ctx, baseStyle, rules, 'cell')
-    if (!merged) return tpl?.s
-    if (merged === baseStyle) return tpl?.s
-    return this.pool.intern(merged)
-  }
-
-  /** 无绑定的静态格：仅模板样式 */
-  resolveStatic(templateRow: number, templateCol: number): number | undefined {
-    const tpl = this.template.cells.find((c) => c.row === templateRow && c.col === templateCol)
-    return tpl?.s
-  }
-
-  /** 将行级样式叠加到格级样式 id */
-  mergeRowStyle(styleId: number | undefined, physicalRow: number): number | undefined {
-    const rowPatch = this.rowStyleByPhysRow.get(physicalRow)
-    if (!rowPatch) return styleId
-
-    const base = styleId !== undefined ? this.pool.get(styleId) : undefined
-    const merged = mergeCellStyle(base, rowPatch)
-    if (!merged) return styleId
-    if (merged === base) return styleId
-    return this.pool.intern(merged)
-  }
-
-  snapshot(): CellStyle[] {
-    return this.pool.snapshot()
-  }
-}

package/src/report/render/template-index.ts

@@ -1,200 +0,0 @@
-import type { CellAddress, CellRange, CellSnapshotItem, SheetSnapshot } from '@veltra/sheet-core'
-import { cellKey, formatAddress } from '@veltra/sheet-core'
-
-import { REPORT_META_NAMESPACE, formatCellAddress } from '../binding'
-import type { ReportBinding } from '../types'
-
-/** 模板结构约束违反时抛出（附 A1 标签） */
-export class TemplateStructureError extends Error {
-  constructor(message: string) {
-    super(message)
-    this.name = 'TemplateStructureError'
-  }
-}
-
-export interface IndexedBinding {
-  addr: CellAddress
-  binding: ReportBinding
-}
-
-/** 模板一次性索引：绑定直查、静态格直查、行/列父子树 */
-export interface TemplateIndex {
-  readonly bindings: ReadonlyMap<number, IndexedBinding>
-  readonly staticCells: ReadonlyMap<number, CellSnapshotItem>
-  readonly rowChildren: ReadonlyMap<number, readonly CellAddress[]>
-  readonly colChildren: ReadonlyMap<number, readonly CellAddress[]>
-  readonly logicalRows: readonly number[]
-  readonly logicalCols: readonly number[]
-  readonly merges: readonly CellRange[]
-  bindingAt(addr: CellAddress): ReportBinding | undefined
-  cellAt(addr: CellAddress): CellSnapshotItem | undefined
-  bindingsOnRow(row: number): readonly IndexedBinding[]
-  bindingsOnCol(col: number): readonly IndexedBinding[]
-  isBindingAddr(addr: CellAddress): boolean
-}
-
-function addressesEqual(a: CellAddress, b: CellAddress): boolean {
-  return a.row === b.row && a.col === b.col
-}
-
-function collectLogicalRows(template: SheetSnapshot): number[] {
-  const rows = new Set<number>()
-  for (const cell of template.cells) rows.add(cell.row)
-  for (const item of template.meta ?? []) rows.add(item.row)
-  return [...rows].sort((a, b) => a - b)
-}
-
-function collectLogicalCols(template: SheetSnapshot): number[] {
-  const cols = new Set<number>()
-  for (const cell of template.cells) cols.add(cell.col)
-  for (const item of template.meta ?? []) cols.add(item.col)
-  return [...cols].sort((a, b) => a - b)
-}
-
-function validateParentExists(
-  addr: CellAddress,
-  parent: CellAddress | undefined,
-  bindings: Map<number, IndexedBinding>,
-  direction: 'row' | 'col'
-): void {
-  if (!parent) return
-  const label = formatCellAddress(addr)
-  const parentLabel = formatCellAddress(parent)
-  if (!bindings.has(cellKey(parent))) {
-    throw new TemplateStructureError(
-      `单元格 ${label} 的${direction === 'row' ? '行' : '列'}方向父格 ${parentLabel} 不存在绑定`
-    )
-  }
-}
-
-function detectParentCycle(
-  start: CellAddress,
-  bindings: Map<number, IndexedBinding>,
-  direction: 'row' | 'col'
-): void {
-  const label = formatCellAddress(start)
-  const visited = new Set<number>()
-  let current: CellAddress | undefined = start
-
-  while (current) {
-    const key = cellKey(current)
-    if (visited.has(key)) {
-      throw new TemplateStructureError(
-        `单元格 ${label} 的${direction === 'row' ? '行' : '列'}方向父链存在环`
-      )
-    }
-    visited.add(key)
-    const entry = bindings.get(key)
-    if (!entry) break
-    current = direction === 'row' ? entry.binding.rowParent : entry.binding.colParent
-  }
-}
-
-function appendChild(map: Map<number, CellAddress[]>, parentKey: number, child: CellAddress): void {
-  const list = map.get(parentKey)
-  if (list) {
-    list.push(child)
-    return
-  }
-  map.set(parentKey, [child])
-}
-
-/** 由模板快照构建索引并校验结构约束（ADR-0005 决策 3） */
-export function buildTemplateIndex(template: SheetSnapshot): TemplateIndex {
-  const bindings = new Map<number, IndexedBinding>()
-  const bindingAddrs = new Set<number>()
-
-  for (const item of template.meta ?? []) {
-    if (item.namespace !== REPORT_META_NAMESPACE) continue
-    const addr = { row: item.row, col: item.col }
-    const key = cellKey(addr)
-    if (bindings.has(key)) {
-      throw new TemplateStructureError(`单元格 ${formatCellAddress(addr)} 存在重复绑定`)
-    }
-    bindings.set(key, { addr, binding: item.payload as ReportBinding })
-    bindingAddrs.add(key)
-  }
-
-  const staticCells = new Map<number, CellSnapshotItem>()
-  for (const cell of template.cells) {
-    const key = cellKey({ row: cell.row, col: cell.col })
-    if (bindingAddrs.has(key)) continue
-    staticCells.set(key, cell)
-  }
-
-  const rowChildren = new Map<number, CellAddress[]>()
-  const colChildren = new Map<number, CellAddress[]>()
-
-  for (const { addr, binding } of bindings.values()) {
-    validateParentExists(addr, binding.rowParent, bindings, 'row')
-    validateParentExists(addr, binding.colParent, bindings, 'col')
-    detectParentCycle(addr, bindings, 'row')
-    detectParentCycle(addr, bindings, 'col')
-
-    if (binding.rowParent) {
-      appendChild(rowChildren, cellKey(binding.rowParent), addr)
-    }
-    if (binding.colParent) {
-      appendChild(colChildren, cellKey(binding.colParent), addr)
-    }
-  }
-
-  const logicalRows = collectLogicalRows(template)
-  const logicalCols = collectLogicalCols(template)
-  const merges = template.merges ?? []
-
-  const bindingsByRow = new Map<number, IndexedBinding[]>()
-  for (const entry of bindings.values()) {
-    const list = bindingsByRow.get(entry.addr.row)
-    if (list) list.push(entry)
-    else bindingsByRow.set(entry.addr.row, [entry])
-  }
-  for (const list of bindingsByRow.values()) {
-    list.sort((a, b) => a.addr.col - b.addr.col)
-  }
-
-  const bindingsByCol = new Map<number, IndexedBinding[]>()
-  for (const entry of bindings.values()) {
-    const list = bindingsByCol.get(entry.addr.col)
-    if (list) list.push(entry)
-    else bindingsByCol.set(entry.addr.col, [entry])
-  }
-  for (const list of bindingsByCol.values()) {
-    list.sort((a, b) => a.addr.row - b.addr.row)
-  }
-
-  return {
-    bindings,
-    staticCells,
-    rowChildren,
-    colChildren,
-    logicalRows,
-    logicalCols,
-    merges,
-    bindingAt(addr) {
-      return bindings.get(cellKey(addr))?.binding
-    },
-    cellAt(addr) {
-      return staticCells.get(cellKey(addr))
-    },
-    bindingsOnRow(row) {
-      return bindingsByRow.get(row) ?? []
-    },
-    bindingsOnCol(col) {
-      return bindingsByCol.get(col) ?? []
-    },
-    isBindingAddr(addr) {
-      return bindings.has(cellKey(addr))
-    }
-  }
-}
-
-/** 判断两地址是否相同（供 coordinate 层使用） */
-export function sameAddress(a: CellAddress, b: CellAddress): boolean {
-  return addressesEqual(a, b)
-}
-
-/** 地址键 → A1 标签 */
-export function addressLabel(addr: CellAddress): string {
-  return formatAddress(addr)
-}

package/src/report/rules/evaluate.ts

@@ -1,113 +0,0 @@
-import type { CellStyle } from '@veltra/sheet-core'
-import { mergeCellStyle } from '@veltra/sheet-core/core/command/set-cell-style'
-
-import type { ConditionalRule } from '../types'
-
-/** 条件样式求值上下文：当前展示值 + 可选同记录字段 */
-export interface ConditionalEvalContext {
-  cellValue: unknown
-  bindingField: string
-  record?: Record<string, unknown>
-}
-
-function ruleScope(rule: ConditionalRule): 'cell' | 'row' {
-  return rule.scope ?? 'cell'
-}
-
-/** 按规则配置的求值字段从上下文取比较值 */
-export function resolveRuleCompareValue(
-  ctx: ConditionalEvalContext,
-  rule: ConditionalRule
-): unknown {
-  if (rule.field !== undefined && ctx.record !== undefined) {
-    return ctx.record[rule.field]
-  }
-  return ctx.cellValue
-}
-
-/** 将单元格值转为可比较的有限数值；无法转换时返回 null */
-export function toComparableNumber(value: unknown): number | null {
-  if (typeof value === 'number' && Number.isFinite(value)) return value
-  if (typeof value === 'string' && value.trim() !== '') {
-    const parsed = Number(value)
-    if (Number.isFinite(parsed)) return parsed
-  }
-  return null
-}
-
-function isBetweenValue(value: unknown): value is [unknown, unknown] {
-  return Array.isArray(value) && value.length === 2
-}
-
-/**
- * 评估单条条件规则是否命中。
- * 数值比较运算符在双方均可解析为有限数时按数值比较；`eq` 在无法数值化时回退字符串相等。
- */
-export function evaluateCondition(cellValue: unknown, rule: ConditionalRule): boolean {
-  const { operator, value: ruleValue } = rule
-
-  switch (operator) {
-    case 'gt':
-    case 'gte':
-    case 'lt':
-    case 'lte':
-    case 'eq': {
-      const left = toComparableNumber(cellValue)
-      const right = toComparableNumber(ruleValue)
-      if (left !== null && right !== null) {
-        if (operator === 'gt') return left > right
-        if (operator === 'gte') return left >= right
-        if (operator === 'lt') return left < right
-        if (operator === 'lte') return left <= right
-        return left === right
-      }
-      if (operator === 'eq') {
-        if (typeof cellValue === 'string' && typeof ruleValue === 'string') {
-          return cellValue === ruleValue
-        }
-        return Object.is(cellValue, ruleValue)
-      }
-      return false
-    }
-    case 'between': {
-      if (!isBetweenValue(ruleValue)) return false
-      const left = toComparableNumber(cellValue)
-      const min = toComparableNumber(ruleValue[0])
-      const max = toComparableNumber(ruleValue[1])
-      if (left === null || min === null || max === null) return false
-      return left >= min && left <= max
-    }
-    case 'contains': {
-      if (typeof cellValue !== 'string') return false
-      if (typeof ruleValue !== 'string') return false
-      return cellValue.includes(ruleValue)
-    }
-    default:
-      return false
-  }
-}
-
-/**
- * 按规则数组顺序评估条件样式，将命中规则的 style 增量依次合并到 baseStyle。
- * 无规则或未命中时原样返回 baseStyle。
- */
-export function evaluateConditionalStyle(
-  ctx: ConditionalEvalContext,
-  baseStyle: CellStyle | undefined,
-  rules: readonly ConditionalRule[] | undefined,
-  scope: 'cell' | 'row' = 'cell'
-): CellStyle | undefined {
-  if (!rules || rules.length === 0) return baseStyle
-
-  let merged = baseStyle
-  let matched = false
-
-  for (const rule of rules) {
-    if (ruleScope(rule) !== scope) continue
-    if (!evaluateCondition(resolveRuleCompareValue(ctx, rule), rule)) continue
-    merged = mergeCellStyle(merged, rule.style)
-    matched = true
-  }
-
-  return matched ? merged : baseStyle
-}

package/src/report/rules/index.ts

@@ -1,7 +0,0 @@
-export {
-  evaluateCondition,
-  evaluateConditionalStyle,
-  resolveRuleCompareValue,
-  toComparableNumber,
-  type ConditionalEvalContext
-} from './evaluate'

package/src/report/template.ts

@@ -1,145 +0,0 @@
-import type { SheetSnapshot } from '@veltra/sheet-core'
-
-import { REPORT_META_NAMESPACE } from './binding'
-import type { DataConnection, DataConnector, Result } from './connector'
-import { buildParamDefs } from './params'
-import type {
-  DatasetField,
-  DatasetRecords,
-  ParamValues,
-  QueryParamDef,
-  ReportBinding
-} from './types'
-
-/**
- * 模板内嵌的数据集定义
- * 与 playground DatasetDef 同构，connectionId 替换为内嵌的完整连接对象。
- */
-export interface ReportDatasetDef {
-  id: string
-  label: string
-  connection: DataConnection
-  sql: string
-  /** 参数元数据覆盖（label / 类型 / 默认值 / 选项） */
-  paramOverrides?: Record<string, Partial<Omit<QueryParamDef, 'id'>>>
-  /** 字段中文名覆盖（name → label）；查看器不消费，随模板序列化往返供设计器还原 */
-  fieldOverrides?: Record<string, Partial<Pick<DatasetField, 'label'>>>
-}
-
-/** 当前支持的报表模板版本 */
-export const REPORT_TEMPLATE_VERSION = 1
-
-/** 模板版本不兼容时抛出 */
-export class IncompatibleTemplateVersionError extends Error {
-  constructor(message: string) {
-    super(message)
-    this.name = 'IncompatibleTemplateVersionError'
-  }
-}
-
-/**
- * 自包含 Report Template：SheetSnapshot + 内嵌数据集定义 + 版本段。
- * 查看器仅凭 `template` + `connector` 即可完成「参数提取 → 取数 → 展开渲染」闭环；
- * 模板可 JSON 序列化流转。
- *
- * `colWidths` 继承自 `SheetSnapshot.colWidths`（模型列索引 → 像素）。
- * 注意：`Sheet.snapshot()` 不产生 `datasets` / `version` 字段，经 `restore()`/`snapshot()` 往返会丢失，
- * 由设计器 `getTemplate()` 在吐出快照时重新附加。
- */
-export interface ReportTemplate extends SheetSnapshot {
-  /** 模板结构版本；当前值为 `REPORT_TEMPLATE_VERSION` */
-  version?: number
-  datasets?: ReportDatasetDef[]
-}
-
-/** 载入模板前校验版本：缺失或高于当前支持版本时抛可读错误 */
-export function assertCompatibleTemplateVersion(template: ReportTemplate): void {
-  if (template.version === undefined) {
-    throw new IncompatibleTemplateVersionError(
-      '报表模板缺少 version 字段，请在设计器中重建模板后重试'
-    )
-  }
-  if (template.version > REPORT_TEMPLATE_VERSION) {
-    throw new IncompatibleTemplateVersionError(
-      `报表模板版本 ${template.version} 高于当前支持的版本 ${REPORT_TEMPLATE_VERSION}，请升级组件库后重试`
-    )
-  }
-}
-
-/**
- * 由工作簿快照构造带版本段的 Report Template。
- * `colWidths` 随 `snapshot` 展开（已在 `SheetSnapshot.colWidths`）。
- */
-export function createReportTemplate(
-  snapshot: SheetSnapshot,
-  datasets?: ReportDatasetDef[]
-): ReportTemplate {
-  return { ...snapshot, version: REPORT_TEMPLATE_VERSION, datasets }
-}
-
-/** 读取模板内嵌的数据集定义（旧模板未内嵌时回退空数组） */
-export function getTemplateDatasets(template: ReportTemplate): ReportDatasetDef[] {
-  return Array.isArray(template.datasets) ? template.datasets : []
-}
-
-/** 模板实际绑定的数据集 id（按绑定在 meta 中的出现顺序去重；绑定即真相，ADR-0002 决策 4） */
-export function getBoundDatasetIds(template: SheetSnapshot): string[] {
-  const ids: string[] = []
-  for (const item of template.meta ?? []) {
-    if (item.namespace !== REPORT_META_NAMESPACE) continue
-    const dataset = (item.payload as ReportBinding).dataset
-    if (typeof dataset === 'string' && dataset && !ids.includes(dataset)) ids.push(dataset)
-  }
-  return ids
-}
-
-/**
- * Filter Bar 参数来源（ADR-0002 决策 4）：模板实际绑定的数据集的查询参数并集，
- * 同名参数合并、先见数据集为准；绑定引用了模板未定义的数据集时跳过。
- */
-export function resolveTemplateParams(template: ReportTemplate): QueryParamDef[] {
-  const datasets = getTemplateDatasets(template)
-  const map = new Map<string, QueryParamDef>()
-  for (const datasetId of getBoundDatasetIds(template)) {
-    const dataset = datasets.find((item) => item.id === datasetId)
-    if (!dataset) continue
-    for (const param of buildParamDefs(dataset.sql, dataset.paramOverrides)) {
-      if (!map.has(param.id)) map.set(param.id, param)
-    }
-  }
-  return Array.from(map.values())
-}
-
-/** 以参数定义的默认值生成 Filter Bar 初始运行时值 */
-export function resolveParamDefaults(params: readonly QueryParamDef[]): ParamValues {
-  const values: ParamValues = {}
-  for (const param of params) values[param.id] = param.defaultValue
-  return values
-}
-
-/**
- * 经数据连接器为模板实际绑定的数据集取数（并行），按数据集 id 折叠为 DatasetRecords。
- * 任一数据集返回业务错误（`ok: false`）则整体透传该错误；绑定但未定义的数据集跳过。
- */
-export async function fetchTemplateRecords(
-  connector: DataConnector,
-  template: ReportTemplate,
-  values: ParamValues
-): Promise<Result<DatasetRecords>> {
-  const datasets = getTemplateDatasets(template)
-  const targets = getBoundDatasetIds(template)
-    .map((datasetId) => datasets.find((item) => item.id === datasetId))
-    .filter((dataset): dataset is ReportDatasetDef => dataset !== undefined)
-
-  const results = await Promise.all(
-    targets.map((dataset) => connector.query(dataset.connection, dataset.sql, values))
-  )
-
-  const records: DatasetRecords = {}
-  for (let i = 0; i < targets.length; i++) {
-    const result = results[i]!
-    if (!result.ok) return result
-    records[targets[i]!.id] = result.data.rows
-  }
-  return { ok: true, data: records }
-}

package/src/report/types.ts

@@ -1,116 +0,0 @@
-import type { CellAddress, CellStylePatch } from '@veltra/sheet-core'
-
-/** 报表绑定扩展方向 */
-export type ReportExpand = 'down' | 'right' | 'none'
-
-/** 报表绑定聚合方式 */
-export type ReportAggregate = 'list' | 'group' | 'sum' | 'avg' | 'count' | 'max' | 'min'
-
-/** 报表绑定排序 */
-export type ReportSort = 'asc' | 'desc' | 'none'
-
-/**
- * 设计器预设标签：引擎不读，仅用于 UI 展示与一键切换。
- * 缺失时 Action Pill 显示「自定义」。
- */
-export type ReportPreset = 'groupHeader' | 'detail' | 'subtotal' | 'grandTotal' | 'cross'
-
-/** 条件样式比较运算符 */
-export type ConditionalOperator = 'gt' | 'gte' | 'lt' | 'lte' | 'eq' | 'between' | 'contains'
-
-/** 条件样式规则：命中后叠加 CellStyle 增量 */
-export interface ConditionalRule {
-  operator: ConditionalOperator
-  /** 单值比较用标量；`between` 用 `[min, max]`（含端点） */
-  value: unknown
-  style: CellStylePatch
-  /** 求值字段；缺省取绑定格自身字段 */
-  field?: string
-  /** 作用范围；缺省 `'cell'` */
-  scope?: 'cell' | 'row'
-}
-
-/** 绑定格下钻配置（存于 Cell Meta namespace `report`，随绑定序列化；旧查看器忽略该字段） */
-export interface ReportDrillConfig {
-  /** 目标模板引用（宿主模板列表项的 ref，不支持手填） */
-  target: string
-  /** 字段 → 详情报参数映射：源记录字段名 → 目标报表 Filter Bar 参数 id */
-  mapping: Record<string, string>
-  /** 打开方式：查看器内切换 | UDialog 弹框 */
-  openMode: 'switch' | 'dialog'
-}
-
-/** 宿主提供的可下钻模板列表项（设计器下拉与查看器 resolveTemplate 契约共用） */
-export interface ReportTemplateListItem {
-  /** 模板引用，作为下钻 target 并传给宿主 resolveTemplate */
-  ref: string
-  /** 可读名，用于设计器下拉展示 */
-  label: string
-}
-
-/** 设计格上的报表绑定（存于 Cell Meta namespace `report`） */
-export interface ReportBinding {
-  dataset: string
-  field: string
-  expand: ReportExpand
-  aggregate: ReportAggregate
-  /** 纵向从属父格：本格数据受该格当前行实例的值约束 */
-  rowParent?: CellAddress
-  /** 横向从属父格：本格数据受该格当前列实例的值约束 */
-  colParent?: CellAddress
-  /** 扩展实例是否合并为单个单元格；缺省 true */
-  mergeSpan?: boolean
-  /** 分组/明细排序；缺省视为 none */
-  sort?: ReportSort
-  /** 条件样式规则（按数组顺序优先级依次求值并合并样式） */
-  conditionalRules?: ConditionalRule[]
-  /** 设计器预设；引擎不读 */
-  preset?: ReportPreset
-  /** 下钻配置；缺省不可下钻 */
-  drill?: ReportDrillConfig
-}
-
-/**
- * 字段 schema（来自数据集配置，非运行时推断）。
- * - `name`：绑定键（写入 Binding.field，英文标识）
- * - `label`：中文显示名（字段面板与占位可读名）
- */
-export interface DatasetField {
-  name: string
-  label: string
-  type: 'string' | 'number' | 'date'
-}
-
-/**
- * 全局数据集目录项（catalog）：系统里可用的数据集定义。
- * 与「本报表选用哪些」无关。
- */
-export interface DatasetCatalogItem {
-  id: string
-  label: string
-  fields: DatasetField[]
-}
-
-/** Dataset id → 行记录（渲染 Filled Report 用） */
-export type DatasetRecords = Record<string, Record<string, unknown>[]>
-
-/** 查询参数控件类型 */
-export type QueryParamType = 'text' | 'number' | 'date' | 'date-range' | 'select'
-
-/** 下拉选项 */
-export interface QueryParamOption {
-  label: string
-  value: string
-}
-
-/** 查询参数定义（从 SQL `${param}` 提取，可在数据集编辑器覆盖元数据） */
-export interface QueryParamDef {
-  id: string
-  label: string
-  type: QueryParamType
-  defaultValue: unknown
-  options?: QueryParamOption[]
-}
-
-/** 运行时参数值 */
-export type ParamValues = Record<string, unknown>