@veltra/sheet 2.1.1 → 2.2.0

package/src/report/render/index.ts

@@ -0,0 +1,30 @@
+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

@@ -0,0 +1,68 @@
+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

@@ -0,0 +1,200 @@
+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

@@ -0,0 +1,113 @@
+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

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

package/src/report/template.ts

@@ -0,0 +1,141 @@
+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'
+
+/**
+ * 模板内嵌的数据集定义（Dataset = Data Connection + SQL，ADR-0002 决策 2）。
+ * 与 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'>>>
+}
+
+/** 当前支持的报表模板版本（ADR-0005 决策 4） */
+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 序列化流转（凭据随之流转，持久化与安全存储由下游负责，ADR-0003 决策 4）。
+ *
+ * 注意：`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 */
+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

@@ -0,0 +1,96 @@
+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 ReportBinding {
+  dataset: string
+  field: string
+  expand: ReportExpand
+  aggregate: ReportAggregate
+  /** 纵向从属父格：本格数据受该格当前行实例的值约束 */
+  rowParent?: CellAddress
+  /** 横向从属父格：本格数据受该格当前列实例的值约束 */
+  colParent?: CellAddress
+  /** 扩展实例是否合并为单个单元格；缺省 true */
+  mergeSpan?: boolean
+  /** 分组/明细排序；缺省视为 none */
+  sort?: ReportSort
+  /** 条件样式规则（按数组顺序优先级依次求值并合并样式） */
+  conditionalRules?: ConditionalRule[]
+  /** 设计器预设；引擎不读 */
+  preset?: ReportPreset
+}
+
+/**
+ * 字段 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>

package/src/tools/builtin.ts

@@ -393,8 +393,8 @@ registerTool({
 })
 
 // ─── file（导入 / 导出）────────────────────────────────────
-// 导出 = 弹层选 xlsx / csv；导入 = 点击直接系统文件选择（vue/import-file.ts，
-// sheet.vue 覆盖 onClick；tools 层不 import vue）。
+// 导出 = 弹层选 xlsx / csv；导入 = 点击直接系统文件选择（components/sheet/import-file.ts，
+// sheet.vue 覆盖 onClick；tools 层不 import 组件层）。
 // 下载逻辑见 tools/download.ts（core/io 保持纯 TS 无头可测）。
 
 registerTool({

package/src/types/index.ts

@@ -1,7 +1,3 @@
 export * from './sheet'
-export type {
-  SheetImageType,
-  SheetImageAnchor,
-  SheetImage,
-  ImageInput
-} from '@veltra/sheet-core/core/image'
+export * from './report-viewer'
+export * from './report-designer'