create-react-admin-template 0.0.0-stage → 0.1.0

package/template/src/components/AppTable/engine/table/controller/TableController.ts

@@ -0,0 +1,802 @@
+import type { CellChange } from 'handsontable'
+import { normalizeTableTotal } from '../../pagination/config'
+import type {
+  PreferenceStatus,
+  TablePreference,
+  TablePreferenceSession,
+  TablePreferenceUpdater,
+} from '../../preference'
+import type { TableQuery, TableQueryParams } from '../../search/types'
+import {
+  createEmptyTableSelectionState,
+  type TableRowSelectionUpdate,
+  type TableSelection,
+  type TableSelectionOptions,
+} from '../../selection/selection'
+import type { SelectionState } from '../../selection/types'
+import { resolveTableKey } from '../../shared/tableKey'
+import type { TableRow } from '../../shared/types'
+import type {
+  TableExportProvider,
+  TableExportTask,
+  TableXlsxWriter,
+} from '../../summary/export'
+import type {
+  TableSummaryProvider,
+  TableSummaryResult,
+} from '../../summary/summary'
+import type { RowKeyResolver } from '../editing'
+import type {
+  ChangeSet,
+  ChangeSetHandler,
+  ConflictResolution,
+  TableChangeTracker,
+  VersionConflict,
+} from '../editing/changeSet'
+import type {
+  TableMutationBatchResult,
+  TableMutationColumn,
+} from '../editing/mutation'
+import type {
+  TableValidation,
+  TableValidationOptions,
+  TableValidationResult,
+} from '../editing/validation'
+import type { GridSettings } from '../grid'
+import { TableDirtyReloadError, assertTableSaveIdle } from './errors'
+import { prepareTableDataReplacement } from './tableDataReplacement'
+import { prepareTableDomainConfiguration } from './tableDomainConfiguration'
+import { TableEditingCommands } from './tableEditingCommands'
+import { TableGridHost } from './tableGridHost'
+import { resolveTableRowKey } from './tableIdentity'
+import { TableMutationPipeline } from './tableMutationPipeline'
+import { TableQueryCoordinator } from './tableQueryCoordinator'
+import { TableReportingCoordinator } from './tableReportingCoordinator'
+import { TableSaveCoordinator } from './tableSaveCoordinator'
+import { TableSnapshotPublisher } from './tableSnapshot'
+import type {
+  TableControllerOptions,
+  TableControllerConfigurationPatch,
+  TableDataSourceConfiguration,
+  TableDataProjection,
+  TableCellState,
+  TableEditingOptions,
+  TableExportExecutionOptions,
+  TableQueryExecutionOptions,
+  TableSnapshot,
+  TableSnapshotListener,
+  TableSummaryExecutionOptions,
+} from './types'
+
+/**
+ * TableComponent 的框架无关控制中枢。
+ *
+ * 它统一持有数据、远程查询、选择、编辑事务、校验、汇总、导出以及 Handsontable
+ * 实例生命周期。React 层只负责把快照映射到界面和把用户事件转成这里的命令，
+ * 不能在适配层复制一套业务状态。
+ */
+export class TableController<T extends TableRow = TableRow> {
+  private readonly grid: TableGridHost<T>
+  private readonly snapshots: TableSnapshotPublisher<T>
+  private readonly query: TableQueryCoordinator<T>
+  private changeTracker: TableChangeTracker<T> | null = null
+  private selection: TableSelection<T> | null = null
+  private validation: TableValidation<T> | null = null
+  private mutation = new TableMutationPipeline<T>()
+  private readonly reporting: TableReportingCoordinator<T>
+  private readonly save: TableSaveCoordinator<T>
+  private readonly editingCommands: TableEditingCommands<T>
+  private commitChanges: ChangeSetHandler<T> | null = null
+  private rowKeyResolver: RowKeyResolver<T> | null = null
+  private rows: T[]
+  private total: number
+  private baselineTotal: number
+  private error: unknown = null
+  private snapshotRows: readonly T[]
+  private currentDataRevision = 0
+  private notificationBatchDepth = 0
+  private notificationPending = false
+  private notificationRowsChanged = false
+  private preferenceSession: TablePreferenceSession | null = null
+
+  /** 创建控制器并装配已显式启用的查询、选择、编辑、校验、汇总和导出能力。 */
+  constructor(readonly options: TableControllerOptions<T>) {
+    this.rows = [...(options.initialData ?? [])]
+    this.snapshotRows = Object.freeze([...this.rows])
+    this.total = this.rows.length
+    this.baselineTotal = this.total
+    this.snapshots = new TableSnapshotPublisher(() => this.createSnapshot())
+    this.grid = new TableGridHost({
+      tableKey: options.tableKey,
+      runtime: options.runtime,
+      getRows: () => this.rows,
+      getDataRevision: () => this.currentDataRevision,
+    })
+    this.query = new TableQueryCoordinator({
+      tableKey: options.tableKey,
+      getRows: () => this.rows,
+      getTotal: () => this.total,
+      guardReload: () => {
+        if (this.hasDirtyChanges())
+          throw new TableDirtyReloadError(this.tableKey)
+      },
+      applyResult: (rows, total, params, queryIdentity) => {
+        const preparedData = this.prepareDataReplacement(rows, total)
+        this.batchStateNotifications(() => {
+          preparedData.commit()
+          this.query.commitAppliedParams(params, queryIdentity)
+          this.selection?.applyQueryIdentity(queryIdentity)
+          this.publishRowsChanged(preparedData.render)
+        })
+      },
+      applyLocalResult: (params, queryIdentity) => {
+        this.batchStateNotifications(() => {
+          this.query.commitAppliedParams(params, queryIdentity)
+          this.selection?.applyQueryIdentity(queryIdentity)
+          this.notify()
+        })
+      },
+      commitState: (commitPreparedState) => {
+        this.batchStateNotifications(() => {
+          commitPreparedState()
+          this.notify()
+        })
+      },
+      setError: (error) => {
+        this.error = error
+      },
+      notify: () => this.notify(),
+    })
+    this.reporting = new TableReportingCoordinator({
+      tableKey: options.tableKey,
+      getRows: () => this.rows,
+      getSelection: () => this.getSelection(),
+      isRemote: () => this.query.remote,
+      getQuery: () => this.query.params,
+      notify: () => this.notify(),
+    })
+    this.save = new TableSaveCoordinator({
+      tableKey: options.tableKey,
+      getRows: () => this.rows,
+      getDataRevision: () => this.currentDataRevision,
+      getTracker: () => this.changeTracker,
+      getValidation: () => this.validation,
+      getCommitChanges: () => this.commitChanges,
+      applyCommitResult: (tracker, result, submission) => {
+        const settlement = tracker.applyCommitResult(
+          this.rows,
+          result,
+          submission
+        )
+        this.rows = settlement.rows
+        settlement.keyRemaps.forEach(({ previousKey, nextKey, row }) => {
+          this.selection?.remapKey(previousKey, nextKey, row)
+          this.validation?.remapKey(previousKey, nextKey)
+        })
+        this.refreshSnapshotRows()
+        this.baselineTotal =
+          this.total - tracker.pendingCreateCount + tracker.pendingRemoveCount
+        // 服务端和编辑基线已经提交后，展示层失败只能进入 error 状态，不能把保存伪装成失败。
+        this.runGridEffect(() => this.grid.render())
+      },
+      setError: (error) => {
+        this.error = error
+      },
+      notify: () => this.notify(),
+    })
+    this.editingCommands = new TableEditingCommands({
+      tableKey: options.tableKey,
+      getSavePromise: () => this.save.inFlight,
+      getRows: () => this.rows,
+      setRows: (rows) => {
+        this.rows = rows
+      },
+      getTotal: () => this.total,
+      setTotal: (total) => {
+        this.total = total
+      },
+      getBaselineTotal: () => this.baselineTotal,
+      getRow: (visualRow) => this.getRow(visualRow),
+      getTracker: () => this.changeTracker,
+      getSelection: () => this.selection,
+      getValidation: () => this.validation,
+      getRowIdentity: (row) =>
+        this.rowKeyResolver
+          ? resolveTableRowKey(row, this.rowKeyResolver)
+          : row,
+      refreshRevision: () => this.refreshSnapshotRevision(),
+      reloadRows: () => this.publishRowsChanged(),
+      notify: () => this.notify(),
+    })
+    this.reconfigure({
+      editing: options.editing,
+      selection: options.selection,
+      validation: options.validation,
+      mutation: options.mutation,
+    })
+    this.setSummaryProvider(options.summaryProvider)
+    this.setExport(options.export)
+    this.setQuery(options.query)
+  }
+
+  /** 返回控制器稳定身份，用于实例隔离、查询上下文和诊断信息。 */
+  get tableKey() {
+    return this.options.tableKey
+  }
+
+  /** 返回当前 Handsontable 实例；尚未挂载或已销毁时为 null。 */
+  get instance() {
+    return this.grid.instance
+  }
+
+  /** 判断有效 Handsontable 实例是否已经挂载。 */
+  get mounted() {
+    return this.grid.mounted
+  }
+
+  /** 返回业务行集版本；替换、增删或单元格变更后递增。 */
+  get dataRevision() {
+    return this.currentDataRevision
+  }
+
+  /** 返回按通知周期缓存的结构只读状态快照。 */
+  get snapshot(): TableSnapshot<T> {
+    return this.snapshots.snapshot
+  }
+
+  /** 从当前领域状态组装一次完整快照，由发布器负责缓存。 */
+  private createSnapshot(): TableSnapshot<T> {
+    // Set/Map 等复杂状态由各子状态机返回防御性副本；rows 冻结集合外壳但不深冻结 DTO。
+    return {
+      tableKey: this.tableKey,
+      rows: this.snapshotRows,
+      dataRevision: this.currentDataRevision,
+      total: this.total,
+      loading: this.query.loading,
+      saving: this.save.saving,
+      isDirty: this.changeTracker?.isDirty ?? false,
+      dirtyCount: this.changeTracker?.dirtyCount ?? 0,
+      dirtyCells: this.changeTracker?.cells ?? [],
+      conflicts: this.changeTracker?.conflicts ?? [],
+      selection: this.getSelection(),
+      validating: this.save.validating,
+      validationIssues: this.validation?.issues ?? [],
+      summarizing: this.reporting.summarizing,
+      exporting: this.reporting.exporting,
+      error: this.error,
+      requestId: this.query.requestId,
+      mounted: this.mounted,
+    }
+  }
+
+  /** 订阅状态快照并立即接收当前值；返回幂等取消函数。 */
+  subscribe(listener: TableSnapshotListener<T>) {
+    return this.snapshots.subscribe(listener)
+  }
+
+  /** 在业务行集合结构变化后推进版本，并生成新的只读 rows 集合外壳。 */
+  private refreshSnapshotRows() {
+    this.currentDataRevision += 1
+    this.snapshotRows = Object.freeze([...this.rows])
+  }
+
+  /** 在行对象原地变化后只推进版本，避免为每次单元格编辑复制完整 rows。 */
+  private refreshSnapshotRevision() {
+    this.currentDataRevision += 1
+  }
+
+  /** 失效快照缓存并通知全部订阅者；结构变化时同时刷新 rows 集合外壳。 */
+  private notify(rowsChanged = false) {
+    if (this.notificationBatchDepth > 0) {
+      this.notificationPending = true
+      this.notificationRowsChanged ||= rowsChanged
+      return
+    }
+    if (rowsChanged) this.refreshSnapshotRows()
+    this.snapshots.notify()
+  }
+
+  /** 发布一致快照后再执行网格副作用；渲染失败只进入 error 状态。 */
+  private publishRowsChanged(render = () => this.grid.loadData()) {
+    this.refreshSnapshotRows()
+    this.notify()
+    this.runGridEffect(render)
+  }
+
+  private runGridEffect(effect: () => void) {
+    try {
+      effect()
+    } catch (error) {
+      this.error = error
+      this.notify()
+    }
+  }
+
+  /** 预检领域状态和网格投影，返回不再调用业务代码的同步提交。 */
+  private prepareDataReplacement(rows: readonly T[], total = rows.length) {
+    const prepared = prepareTableDataReplacement({
+      tableKey: this.tableKey,
+      rows,
+      total,
+      savePromise: this.save.inFlight,
+      dirty: this.hasDirtyChanges(),
+      rowKey: this.rowKeyResolver,
+      tracker: this.changeTracker,
+      selection: this.selection,
+      validation: this.validation,
+    })
+    const render = this.grid.prepareLoadData(
+      prepared.rows,
+      this.currentDataRevision + 1
+    )
+    return {
+      render,
+      commit: () => {
+        this.rows = prepared.rows
+        this.total = prepared.total
+        this.baselineTotal = prepared.total
+        prepared.commitDomains()
+      },
+    }
+  }
+
+  /** 把多个领域状态变更合并为一个可观察快照。 */
+  private batchStateNotifications<R>(action: () => R): R {
+    this.notificationBatchDepth += 1
+    try {
+      return action()
+    } finally {
+      this.notificationBatchDepth -= 1
+      if (this.notificationBatchDepth === 0 && this.notificationPending) {
+        const rowsChanged = this.notificationRowsChanged
+        this.notificationPending = false
+        this.notificationRowsChanged = false
+        if (rowsChanged) this.refreshSnapshotRows()
+        this.snapshots.notify()
+      }
+    }
+  }
+
+  /** 热切换远程查询实现，取消旧请求并清除旧查询上下文。 */
+  setQuery(query?: TableQuery<T>) {
+    this.query.setQuery(query)
+  }
+
+  /**
+   * 原子切换查询 provider 与可选本地数据。remote → local 时先完成全部数据预检，
+   * 再一次发布新 provider、rows、total 和领域基线。
+   */
+  reconfigureDataSource(configuration: TableDataSourceConfiguration<T>) {
+    const commitQuery =
+      'query' in configuration
+        ? this.query.prepareQuery(configuration.query)
+        : () => {}
+    const preparedData =
+      'rows' in configuration
+        ? this.prepareDataReplacement(
+            [...(configuration.rows ?? [])],
+            configuration.total ?? configuration.rows?.length ?? 0
+          )
+        : undefined
+    this.batchStateNotifications(() => {
+      commitQuery()
+      preparedData?.commit()
+      if (preparedData) this.publishRowsChanged(preparedData.render)
+      else this.notify()
+    })
+  }
+
+  /**
+   * 先在控制器外构造并验证所有候选领域对象，全部成功后才交换引用和发布快照。
+   */
+  reconfigure(configuration: TableControllerConfigurationPatch<T>) {
+    const changesEditing = 'editing' in configuration
+    const changesValidation = 'validation' in configuration
+    if (changesEditing || changesValidation) {
+      assertTableSaveIdle(this.save.inFlight, this.tableKey, 'reconfigure')
+    }
+    if (changesEditing && this.hasDirtyChanges()) {
+      throw new Error(
+        `[TableComponent] Table "${this.tableKey}" cannot reconfigure editing while dirty.`
+      )
+    }
+    const next = prepareTableDomainConfiguration({
+      configuration,
+      rows: this.rows,
+      tracker: this.changeTracker,
+      selection: this.selection,
+      validation: this.validation,
+      mutation: this.mutation,
+      commitChanges: this.commitChanges,
+    })
+    this.batchStateNotifications(() => {
+      if (next.changesEditing) {
+        this.changeTracker = next.tracker
+        this.baselineTotal = this.total
+      }
+      if (next.changesSelection) this.selection = next.selection
+      if (next.changesValidation) {
+        this.save.resetValidation()
+        this.validation = next.validation
+      }
+      if (next.changesMutation) this.mutation = next.mutation
+      this.rowKeyResolver = next.rowKey
+      this.commitChanges = next.commitChanges
+      this.notify()
+    })
+  }
+
+  /** 配置显式保存事务；存在脏数据时拒绝重建变更跟踪基线。 */
+  setEditing(options?: TableEditingOptions<T>) {
+    this.reconfigure({ editing: options })
+  }
+
+  /** 重建行选择状态机，并以当前业务行作为已加载集合。 */
+  setSelection(options?: TableSelectionOptions<T>) {
+    this.reconfigure({ selection: options })
+  }
+
+  /** 热切换校验规则，取消进行中的校验并清理旧问题。 */
+  setValidation(options?: TableValidationOptions<T>) {
+    this.reconfigure({ validation: options })
+  }
+
+  /** 编译各列的输入解析、准入和派生变更规则。 */
+  setMutation(columns?: readonly TableMutationColumn<T>[]) {
+    this.reconfigure({ mutation: columns })
+  }
+
+  /** 热切换远程汇总 provider，并取消进行中的旧汇总。 */
+  setSummaryProvider(provider?: TableSummaryProvider) {
+    this.reporting.setSummaryProvider(provider)
+  }
+
+  /** 热切换导出 provider/XLSX writer，并取消进行中的旧导出。 */
+  setExport(options?: {
+    provider?: TableExportProvider
+    xlsxWriter?: TableXlsxWriter<T>
+  }) {
+    this.reporting.setExport(options)
+  }
+
+  /** 执行受竞态保护的查询；存在脏数据时拒绝替换 rows，避免静默丢改。 */
+  runQuery(params: TableQueryParams, options: TableQueryExecutionOptions = {}) {
+    return this.query.run(params, options)
+  }
+
+  /** 取消进行中的远程查询，但保留查询 provider 供下一次用户意图复用。 */
+  cancelQuery() {
+    this.query.cancel()
+  }
+
+  /** 创建并占有网格实例；仍存活的重复挂载会失败，脱离文档的旧实例可安全接管。 */
+  mount(container: HTMLElement, settings: GridSettings) {
+    const instance = this.grid.mount(container, settings)
+    this.notify()
+    return instance
+  }
+
+  /**
+   * 释放指定组件创建的 Handsontable 挂载，但保留查询、选择、编辑和订阅状态。
+   * 传入 mount 返回的实例可避免旧组件卸载时销毁已经由新组件接管的网格。
+   */
+  unmountGrid(expectedInstance = this.instance) {
+    if (!expectedInstance) return false
+    const unmounted = this.grid.unmount(expectedInstance)
+    if (unmounted) this.notify()
+    return unmounted
+  }
+
+  /** 将增量网格设置转交给当前 Handsontable 实例。 */
+  updateSettings(settings: GridSettings) {
+    this.grid.updateSettings(settings)
+  }
+
+  /** 订阅列宽、行高和数据投影等会改变网格内容尺寸的布局变化。 */
+  subscribeGridLayout(listener: () => void) {
+    return this.grid.subscribeLayout(listener)
+  }
+
+  /**
+   * 注册适配层展示数据投影。Controller 始终只持有业务 rows，Handsontable 可以额外
+   * 接收 summary 等只读展示行。返回的 disposer 只释放本次注册，避免旧组件卸载时
+   * 清除新挂载组件的投影。
+   */
+  setDataProjection = (projection: TableDataProjection<T>) =>
+    this.grid.setDataProjection(projection)
+
+  /** 当 summary 等只读展示投影改变时，由 Controller 统一刷新 HOT。 */
+  refreshDataProjection = () => this.runGridEffect(() => this.grid.loadData())
+
+  /** 替换完整业务行集和总数，并重置编辑、选择、校验的加载基线。 */
+  replaceData(rows: T[], total = rows.length) {
+    const prepared = this.prepareDataReplacement(rows, total)
+    this.batchStateNotifications(() => {
+      prepared.commit()
+      this.publishRowsChanged(prepared.render)
+    })
+  }
+
+  /**
+   * 只更新分页总数，不替换当前业务行。
+   *
+   * 编辑事务期间会把待新增/待删除数量从外部总数中反推到加载基线，确保随后放弃
+   * 修改时仍回到本次更新后的服务端总数，而不是过期的初始值。
+   */
+  setTotal(total: number) {
+    const nextTotal = normalizeTableTotal(total)
+    const tracker = this.changeTracker
+    this.baselineTotal = normalizeTableTotal(
+      nextTotal -
+        (tracker?.pendingCreateCount ?? 0) +
+        (tracker?.pendingRemoveCount ?? 0)
+    )
+    if (nextTotal === this.total) return
+    this.total = nextTotal
+    this.notify()
+  }
+
+  /** 返回业务行数组副本，防止调用方直接改变控制器集合结构。 */
+  getData = () => [...this.rows]
+
+  /** 按视觉行定位业务行；已挂载时自动处理排序后的物理行映射。 */
+  getRow(visualRow: number) {
+    return this.grid.getRow(visualRow)
+  }
+
+  /** 通过 Handsontable 公共 API 写入单元格，并保留来源标记。 */
+  setCell(visualRow: number, key: string, value: unknown, source?: string) {
+    this.grid.setCell(visualRow, key, value, source)
+  }
+
+  /** 通过受控来源提交框架浮层值，并同步返回 mutation 门禁是否接受。 */
+  commitControlledCell(visualRow: number, key: string, value: unknown) {
+    return this.grid.commitControlledCell(visualRow, key, value)
+  }
+
+  /** 对一次编辑批次执行解析、准入与派生字段计算，返回接受/拒绝明细。 */
+  processChanges(
+    changes: Array<CellChange | null>,
+    rawSource = 'edit'
+  ): TableMutationBatchResult<T> {
+    return this.mutation.process(changes, (row) => this.getRow(row), rawSource)
+  }
+
+  /** 将 HOT 已落库的变更登记到事务基线，并清除对应单元格旧校验问题。 */
+  recordChanges(changes: CellChange[]) {
+    this.editingCommands.recordChanges(changes)
+  }
+
+  /** 为网格 cells() 热路径提供常量时间的错误和冲突查询。 */
+  getCellState(rowKey: unknown, prop: string): TableCellState {
+    return this.editingCommands.getCellState(rowKey, prop)
+  }
+
+  /** 在指定位置插入业务行，并同步 total、选择模型和网格投影。 */
+  addRow(row: T, index = this.rows.length) {
+    this.editingCommands.addRow(row, index)
+  }
+
+  /** 按稳定行身份批量删除实际存在的行，并同步关联领域状态。 */
+  removeRows(rows: readonly T[]) {
+    this.editingCommands.removeRows(rows)
+  }
+
+  /** 返回当前待提交的新增、更新和删除集合；未启用编辑时返回空集合。 */
+  getChangeSet(): ChangeSet<T> {
+    return (
+      this.changeTracker?.getChangeSet() ?? {
+        creates: [],
+        updates: [],
+        removes: [],
+      }
+    )
+  }
+
+  /** 返回当前未解决的乐观锁版本冲突。 */
+  getConflicts(): readonly VersionConflict<T>[] {
+    return this.changeTracker?.conflicts ?? []
+  }
+
+  /** 应用某一行冲突解决策略，并同步选择、校验和网格数据。 */
+  resolveConflict(rowKey: string | number, resolution: ConflictResolution) {
+    this.editingCommands.resolveConflict(rowKey, resolution)
+  }
+
+  /** 判断当前是否存在尚未提交或丢弃的显式编辑。 */
+  hasDirtyChanges() {
+    return this.changeTracker?.isDirty ?? false
+  }
+
+  /** 取消旧公开校验并校验当前完整业务行集，同时发布 validating 状态。 */
+  async validate(): Promise<TableValidationResult> {
+    return this.save.validate()
+  }
+
+  /** 校验并提交完整变更集，合并服务端结果和主键映射，保留 HOT 撤销历史。 */
+  saveChanges() {
+    return this.save.save()
+  }
+
+  /** 放弃全部未保存修改，恢复编辑基线及其 total、校验和网格状态。 */
+  discardChanges() {
+    this.editingCommands.discardChanges()
+  }
+
+  /** 判断 Handsontable 撤销栈当前是否可用。 */
+  canUndo() {
+    return this.grid.instance?.getPlugin('undoRedo').isUndoAvailable() ?? false
+  }
+  /** 判断 Handsontable 重做栈当前是否可用。 */
+  canRedo() {
+    return this.grid.instance?.getPlugin('undoRedo').isRedoAvailable() ?? false
+  }
+  /** 执行一次 Handsontable 撤销命令。 */
+  undo() {
+    this.grid.instance?.getPlugin('undoRedo').undo()
+  }
+  /** 执行一次 Handsontable 重做命令。 */
+  redo() {
+    this.grid.instance?.getPlugin('undoRedo').redo()
+  }
+  /** 返回选择状态的防御性快照；未启用选择时返回空显式选择。 */
+  getSelection(): SelectionState<T> {
+    return this.selection?.state ?? createEmptyTableSelectionState<T>()
+  }
+
+  /** 返回当前已加载页面中被选中的业务行。 */
+  getLoadedSelectedRows() {
+    return this.selection?.loadedSelectedRows ?? []
+  }
+
+  /** 判断某业务行是否处于当前选择语义下的选中状态。 */
+  isRowSelected(row: T) {
+    return this.selection?.isSelected(row) ?? false
+  }
+
+  /** 判断某业务行是否通过 selectable 准入规则。 */
+  canSelectRow(row: T) {
+    return this.selection?.canSelect(row) ?? false
+  }
+
+  /** 切换单行业务选择状态并发布新快照。 */
+  toggleRowSelection(row: T, selected: boolean) {
+    this.selection?.toggle(row, selected)
+    this.notify()
+  }
+
+  /** 按批量更新指令改变给定行集合的选择状态。 */
+  updateRowSelection(rows: readonly T[], update: TableRowSelectionUpdate) {
+    this.selection?.updateRows(rows, update)
+    this.notify()
+  }
+
+  /** 选中或取消当前页可选择行，默认作用于全部已加载业务行。 */
+  selectPage(rows: readonly T[] = this.rows, selected = true) {
+    this.selection?.selectPage(rows, selected)
+    this.notify()
+  }
+
+  /** 用指定业务行替换显式选择集合。 */
+  setSelectedRows(rows: readonly T[]) {
+    this.selection?.replaceExplicit(rows)
+    this.notify()
+  }
+
+  /** 进入“选择全部查询结果”模式，并绑定不可变查询令牌和结果集身份。 */
+  selectAllMatching(queryToken: string) {
+    const queryIdentity = this.query.identity
+    if (!queryIdentity) {
+      throw new Error(
+        `[TableComponent] Table "${this.tableKey}" must apply a query before selecting all matching rows.`
+      )
+    }
+    if (!this.selection) {
+      throw new Error(
+        `[TableComponent] Table "${this.tableKey}" has no selection model.`
+      )
+    }
+    this.selection.selectAllMatching(queryToken, queryIdentity, this.rows)
+    this.notify()
+  }
+
+  /** 当查询身份变化时使旧的全量选择失效；返回是否发生状态变化。 */
+  invalidateSelectionQuery(nextQueryToken?: string) {
+    const invalidated =
+      this.selection?.invalidateQueryToken(nextQueryToken) ?? false
+    if (invalidated) this.notify()
+    return invalidated
+  }
+
+  /** 清空显式选择或全量选择状态。 */
+  clearSelection() {
+    this.selection?.clear()
+    this.notify()
+  }
+
+  /** 返回最近一次成功应用的查询参数，供汇总和导出复用。 */
+  getQueryParams() {
+    return this.query.params
+  }
+
+  /** 执行当前页、选择范围或远程全量汇总，并取消同类旧任务。 */
+  async summarize(
+    options: TableSummaryExecutionOptions<T>
+  ): Promise<TableSummaryResult> {
+    return this.reporting.summarize(options)
+  }
+
+  /** 执行指定范围和格式的数据导出，并取消同类旧任务。 */
+  async exportData(
+    options: TableExportExecutionOptions<T>
+  ): Promise<TableExportTask> {
+    return this.reporting.exportData(options)
+  }
+
+  /** 请求 Handsontable 重绘当前视图。 */
+  render() {
+    this.grid.render()
+  }
+
+  /** 通知 Handsontable 重新测量宿主尺寸。 */
+  refreshDimensions() {
+    this.grid.refreshDimensions()
+  }
+
+  /**
+   * 标记外层布局正在连续改变可用尺寸；结束时 Core 会合并为一次最终尺寸刷新。
+   */
+  setLayoutTransitioning(active: boolean) {
+    this.grid.setLayoutTransitioning(active)
+  }
+
+  /** 由框架适配器绑定当前表格唯一的偏好会话。 */
+  bindPreferenceSession(session: TablePreferenceSession | null) {
+    this.preferenceSession = session
+  }
+
+  /** 获取当前规范化偏好；适配器尚未绑定偏好会话时返回 undefined。 */
+  getPreference(): TablePreference | undefined {
+    return this.preferenceSession?.snapshot.value
+  }
+
+  /** 获取偏好加载状态；适配器尚未绑定偏好会话时为 idle。 */
+  getPreferenceStatus(): PreferenceStatus {
+    return this.preferenceSession?.status ?? 'idle'
+  }
+
+  /** 从配置的存储适配器重新加载偏好。 */
+  async reloadPreference() {
+    return this.preferenceSession?.load()
+  }
+
+  /** 基于会话最新值原子更新偏好。 */
+  async updatePreference(updater: TablePreferenceUpdater) {
+    return this.preferenceSession?.update(updater)
+  }
+
+  /** 删除当前表格持久化偏好并恢复组件默认值。 */
+  async resetPreference() {
+    return this.preferenceSession?.reset()
+  }
+
+  /** 取消全部异步任务，销毁网格并释放所有快照订阅者。 */
+  destroy() {
+    // 先取消全部异步任务，再销毁网格和订阅者，防止卸载后继续回写适配层。
+    this.query.destroy()
+    this.save.destroy()
+    this.reporting.destroy()
+    this.preferenceSession = null
+    this.grid.destroy()
+    this.snapshots.destroy()
+  }
+}
+
+/** 创建框架无关的 TableController。 */
+export const createTableController = <T extends TableRow = TableRow>(
+  options: TableControllerOptions<T>
+) =>
+  new TableController<T>({
+    ...options,
+    tableKey: resolveTableKey(options.tableKey),
+  })