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

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

@@ -0,0 +1,143 @@
+import type { TableQueryParams } from '../../search/types'
+import type { SelectionState } from '../../selection'
+import type { TableRow } from '../../shared'
+import {
+  runTableExport,
+  type TableExportProvider,
+  type TableExportTask,
+  type TableXlsxWriter,
+} from '../../summary/export'
+import {
+  runTableSummary,
+  type TableSummaryProvider,
+  type TableSummaryResult,
+} from '../../summary/summary'
+import { LatestAbortableTask } from './latestAbortableTask'
+import type {
+  TableExportExecutionOptions,
+  TableSummaryExecutionOptions,
+} from './types'
+
+interface TableReportingCoordinatorContext<T extends TableRow> {
+  tableKey: string
+  getRows: () => T[]
+  getSelection: () => SelectionState<T>
+  isRemote: () => boolean
+  getQuery: () => TableQueryParams | undefined
+  notify: () => void
+}
+
+/** 汇总和导出的独立协调器，统一管理 provider、取消语义和运行状态。 */
+export class TableReportingCoordinator<T extends TableRow> {
+  private readonly summaryTask = new LatestAbortableTask()
+  private readonly exportTask = new LatestAbortableTask()
+  private summaryProvider: TableSummaryProvider | null = null
+  private exportProvider: TableExportProvider | null = null
+  private xlsxWriter: TableXlsxWriter<T> | null = null
+  private summaryRunning = false
+  private exportRunning = false
+
+  constructor(private readonly context: TableReportingCoordinatorContext<T>) {}
+
+  /** 当前是否正在执行汇总。 */
+  get summarizing() {
+    return this.summaryRunning
+  }
+
+  /** 当前是否正在执行导出。 */
+  get exporting() {
+    return this.exportRunning
+  }
+
+  /** 切换远程汇总 provider，并取消进行中的旧汇总。 */
+  setSummaryProvider(provider?: TableSummaryProvider) {
+    this.summaryTask.cancel()
+    this.summaryRunning = false
+    this.summaryProvider = provider ?? null
+    this.context.notify()
+  }
+
+  /** 切换导出 provider/XLSX writer，并取消进行中的旧导出。 */
+  setExport(options?: {
+    provider?: TableExportProvider
+    xlsxWriter?: TableXlsxWriter<T>
+  }) {
+    this.exportTask.cancel()
+    this.exportRunning = false
+    this.exportProvider = options?.provider ?? null
+    this.xlsxWriter = options?.xlsxWriter ?? null
+    this.context.notify()
+  }
+
+  /** 执行汇总；后发调用会取消先发调用，只有最新任务可以结束运行状态。 */
+  async summarize(
+    options: TableSummaryExecutionOptions<T>
+  ): Promise<TableSummaryResult> {
+    const controller = this.summaryTask.start()
+    this.summaryRunning = true
+    this.context.notify()
+    try {
+      return await runTableSummary({
+        tableKey: this.context.tableKey,
+        scope: options.scope,
+        rows: this.context.getRows(),
+        selection: this.context.getSelection(),
+        columns: options.columns,
+        remote: this.context.isRemote(),
+        query: this.context.getQuery(),
+        provider: this.summaryProvider ?? undefined,
+        locale: options.locale,
+        timeZone: options.timeZone,
+        signal: controller.signal,
+      })
+    } finally {
+      if (this.summaryTask.finish(controller)) {
+        this.summaryRunning = false
+        this.context.notify()
+      }
+    }
+  }
+
+  /** 执行导出；从同一查询和选择快照构造请求，并采用最后任务生效语义。 */
+  async exportData(
+    options: TableExportExecutionOptions<T>
+  ): Promise<TableExportTask> {
+    const controller = this.exportTask.start()
+    this.exportRunning = true
+    this.context.notify()
+    try {
+      return await runTableExport({
+        tableKey: this.context.tableKey,
+        scope: options.scope,
+        format: options.format,
+        fileName: options.fileName,
+        sheetName: options.sheetName,
+        rows: this.context.getRows(),
+        rangeRows: options.rangeRows,
+        rangeColumns: options.rangeColumns,
+        selection: this.context.getSelection(),
+        columns: options.columns,
+        remote: this.context.isRemote(),
+        query: this.context.getQuery(),
+        provider: this.exportProvider ?? undefined,
+        xlsxWriter: this.xlsxWriter ?? undefined,
+        locale: options.locale,
+        timeZone: options.timeZone,
+        signal: controller.signal,
+      })
+    } finally {
+      if (this.exportTask.finish(controller)) {
+        this.exportRunning = false
+        this.context.notify()
+      }
+    }
+  }
+
+  /** 取消全部报表任务并清理运行状态。 */
+  destroy() {
+    this.summaryTask.cancel()
+    this.exportTask.cancel()
+    this.summaryRunning = false
+    this.exportRunning = false
+  }
+}

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

@@ -0,0 +1,227 @@
+import type { TableRow } from '../../shared'
+import type {
+  ChangeSetHandler,
+  CommitResult,
+  TableChangeSubmission,
+  TableChangeTracker,
+} from '../editing/changeSet'
+import type {
+  TableValidation,
+  TableValidationResult,
+} from '../editing/validation'
+import { TableUnresolvedConflictError } from './errors'
+import { LatestAbortableTask } from './latestAbortableTask'
+import { createValidatedTableSubmission } from './tableSaveValidation'
+
+interface TableSaveCoordinatorContext<T extends TableRow> {
+  tableKey: string
+  getRows: () => readonly T[]
+  getDataRevision: () => number
+  getTracker: () => TableChangeTracker<T> | null
+  getValidation: () => TableValidation<T> | null
+  getCommitChanges: () => ChangeSetHandler<T> | null
+  applyCommitResult: (
+    tracker: TableChangeTracker<T>,
+    result: CommitResult<T> | undefined,
+    submission: TableChangeSubmission<T>
+  ) => void
+  setError: (error: unknown) => void
+  notify: () => void
+}
+
+/**
+ * 保存事务协调器。独立管理公开校验、保存校验和提交三个任务槽，并只把稳定的
+ * submission 交给服务端；业务 rows 的最终写入仍由 TableController 单点完成。
+ */
+export class TableSaveCoordinator<T extends TableRow> {
+  private readonly validationTask = new LatestAbortableTask()
+  private readonly saveValidationTask = new LatestAbortableTask()
+  private readonly commitTask = new LatestAbortableTask()
+  private currentSave: Promise<CommitResult<T> | void> | null = null
+  private validationRuns = 0
+  private validationPublicationGeneration = 0
+  private savingState = false
+  private validatingState = false
+
+  constructor(private readonly context: TableSaveCoordinatorContext<T>) {}
+
+  get inFlight() {
+    return this.currentSave
+  }
+
+  get saving() {
+    return this.savingState
+  }
+
+  get validating() {
+    return this.validatingState
+  }
+
+  private beginValidation() {
+    this.validationRuns += 1
+    if (this.validatingState) return
+    this.validatingState = true
+    this.context.notify()
+  }
+
+  private finishValidation() {
+    this.validationRuns = Math.max(0, this.validationRuns - 1)
+    if (this.validationRuns > 0 || !this.validatingState) return
+    this.validatingState = false
+    this.context.notify()
+  }
+
+  /** 取消旧公开校验并校验当前完整业务行集。 */
+  async validate(): Promise<TableValidationResult> {
+    const validation = this.context.getValidation()
+    if (!validation) return { valid: true, issues: [] }
+    const controller = this.validationTask.start()
+    const publicationGeneration = this.savingState
+      ? undefined
+      : ++this.validationPublicationGeneration
+    this.beginValidation()
+    try {
+      for (;;) {
+        const dataRevision = this.context.getDataRevision()
+        const result = await validation.validate(
+          this.context.getRows(),
+          controller.signal,
+          { publish: false }
+        )
+        if (dataRevision !== this.context.getDataRevision()) continue
+        if (
+          publicationGeneration !== undefined &&
+          publicationGeneration === this.validationPublicationGeneration &&
+          !this.savingState
+        ) {
+          validation.publish(result)
+        }
+        return result
+      }
+    } finally {
+      this.validationTask.finish(controller)
+      this.finishValidation()
+    }
+  }
+
+  private async validateChanges(
+    validation: TableValidation<T> | null,
+    tracker: TableChangeTracker<T>
+  ): Promise<TableValidationResult> {
+    if (!validation) return { valid: true, issues: [] }
+    const changeSet = tracker.getChangeSet()
+    const rowKeys = new Set([
+      ...changeSet.creates.map((item) => item.clientKey),
+      ...changeSet.updates.map((item) => item.rowKey),
+    ])
+    if (!rowKeys.size) return { valid: true, issues: [] }
+    const controller = this.saveValidationTask.start()
+    this.beginValidation()
+    try {
+      return await validation.validate(
+        this.context.getRows(),
+        controller.signal,
+        { rowKeys, publish: false }
+      )
+    } finally {
+      this.saveValidationTask.finish(controller)
+      this.finishValidation()
+    }
+  }
+
+  /** 复用进行中的保存 Promise，禁止重复写请求。 */
+  save(): Promise<CommitResult<T> | void> {
+    if (this.currentSave) return this.currentSave
+    const execution = this.execute()
+    const tracked = execution.finally(() => {
+      if (this.currentSave === tracked) this.currentSave = null
+    })
+    this.currentSave = tracked
+    return tracked
+  }
+
+  private async execute(): Promise<CommitResult<T> | void> {
+    const tracker = this.context.getTracker()
+    if (!tracker?.isDirty) return
+    if (tracker.conflicts.length) {
+      throw new TableUnresolvedConflictError(
+        this.context.tableKey,
+        tracker.conflicts
+      )
+    }
+    const commitChanges = this.context.getCommitChanges()
+    if (!commitChanges) {
+      throw new Error(
+        `[TableComponent] Table "${this.context.tableKey}" cannot save without commitChanges.`
+      )
+    }
+    const validation = this.context.getValidation()
+    const controller = this.commitTask.start()
+    const validationPublicationGeneration = ++this
+      .validationPublicationGeneration
+    this.validationTask.cancel()
+    this.savingState = true
+    this.context.setError(null)
+    this.context.notify()
+    let submission: TableChangeSubmission<T> | undefined
+    let submissionFinishedBySettlement = false
+
+    try {
+      submission = await createValidatedTableSubmission({
+        tracker,
+        validate: () => this.validateChanges(validation, tracker),
+        publish: (result) => {
+          if (
+            validationPublicationGeneration ===
+            this.validationPublicationGeneration
+          ) {
+            validation?.publish(result)
+          }
+        },
+      })
+      const result = await commitChanges(submission.changeSet, {
+        tableKey: this.context.tableKey,
+        signal: controller.signal,
+      })
+      if (controller.signal.aborted) return result
+      this.context.applyCommitResult(
+        tracker,
+        result && typeof result === 'object' ? result : undefined,
+        submission
+      )
+      submissionFinishedBySettlement = true
+      return result
+    } catch (error) {
+      if (!controller.signal.aborted) this.context.setError(error)
+      throw error
+    } finally {
+      if (submission && !submissionFinishedBySettlement) {
+        tracker.finishSubmission(submission)
+      }
+      if (this.commitTask.finish(controller)) {
+        this.savingState = false
+        this.context.notify()
+      }
+    }
+  }
+
+  /** 热切换校验规则前取消旧的公开校验结果；保存期间由 Controller 拒绝切换。 */
+  resetValidation() {
+    this.validationPublicationGeneration += 1
+    this.validationTask.cancel()
+    this.saveValidationTask.cancel()
+    this.validationRuns = 0
+    this.validatingState = false
+  }
+
+  destroy() {
+    this.validationPublicationGeneration += 1
+    this.commitTask.cancel()
+    this.validationTask.cancel()
+    this.saveValidationTask.cancel()
+    this.currentSave = null
+    this.validationRuns = 0
+    this.savingState = false
+    this.validatingState = false
+  }
+}

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

@@ -0,0 +1,29 @@
+import type { TableRow } from '../../shared'
+import type {
+  TableChangeSubmission,
+  TableChangeTracker,
+  TableValidationResult,
+} from '../editing'
+import { TableValidationError } from './errors'
+
+interface StableSubmissionOptions<T extends TableRow> {
+  tracker: TableChangeTracker<T>
+  validate: () => Promise<TableValidationResult>
+  publish: (result: TableValidationResult) => void
+}
+
+/** 只为通过稳定数据世代校验的 ChangeSet 创建保存 submission。 */
+export const createValidatedTableSubmission = async <T extends TableRow>({
+  tracker,
+  validate,
+  publish,
+}: StableSubmissionOptions<T>): Promise<TableChangeSubmission<T>> => {
+  for (;;) {
+    const revision = tracker.revision
+    const result = await validate()
+    if (revision !== tracker.revision) continue
+    publish(result)
+    if (!result.valid) throw new TableValidationError(result)
+    return tracker.createSubmission()
+  }
+}

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

@@ -0,0 +1,58 @@
+import type { TableRow } from '../../shared'
+import type { TableSnapshot, TableSnapshotListener } from './types'
+
+const reportSubscriberError = (error: unknown) => {
+  const reporter = Reflect.get(globalThis, 'reportError')
+  if (typeof reporter === 'function') {
+    Reflect.apply(reporter, globalThis, [error])
+    return
+  }
+  // 与浏览器事件监听器一致：不破坏发布者状态机，但仍把异常交给全局错误通道。
+  setTimeout(() => {
+    throw error
+  })
+}
+
+/**
+ * 维护不可变快照缓存和订阅者隔离。状态所有权仍在 Controller，发布机制不感知
+ * 查询、选择、编辑等领域，避免这些能力共享一套易出错的监听器样板代码。
+ */
+export class TableSnapshotPublisher<T extends TableRow = TableRow> {
+  private cached: TableSnapshot<T> | null = null
+  private readonly listeners = new Set<TableSnapshotListener<T>>()
+
+  constructor(private readonly createSnapshot: () => TableSnapshot<T>) {}
+
+  get snapshot() {
+    this.cached ??= this.createSnapshot()
+    return this.cached
+  }
+
+  subscribe(listener: TableSnapshotListener<T>) {
+    this.listeners.add(listener)
+    this.publish(listener, this.snapshot)
+    return () => this.listeners.delete(listener)
+  }
+
+  notify() {
+    this.cached = null
+    const snapshot = this.snapshot
+    this.listeners.forEach((listener) => this.publish(listener, snapshot))
+  }
+
+  destroy() {
+    this.cached = null
+    this.listeners.clear()
+  }
+
+  private publish(
+    listener: TableSnapshotListener<T>,
+    snapshot: TableSnapshot<T>
+  ) {
+    try {
+      listener(snapshot)
+    } catch (error) {
+      reportSubscriberError(error)
+    }
+  }
+}

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

@@ -0,0 +1,202 @@
+import type { TableQuery } from '../../search/types'
+import type { SelectionState, TableSelectionOptions } from '../../selection'
+import type { TableRow } from '../../shared'
+import type { TableEngineMessages } from '../../shared/messages'
+import type {
+  TableExportColumn,
+  TableExportFormat,
+  TableExportProvider,
+  TableExportScope,
+  TableXlsxWriter,
+} from '../../summary/export'
+import type {
+  TableSummaryColumn,
+  TableSummaryProvider,
+  TableSummaryScope,
+} from '../../summary/summary'
+import type {
+  ChangeSetHandler,
+  DirtyCell,
+  RowKeyResolver,
+  VersionConflict,
+} from '../editing/changeSet'
+import type { TableMutationColumn } from '../editing/mutation'
+import type {
+  TableValidationIssue,
+  TableValidationOptions,
+} from '../editing/validation'
+import type { GridSettings, TableRuntimeOptions } from '../grid'
+
+/** 显式保存模式所需的行身份、版本和服务端提交函数。 */
+export interface TableEditingOptions<T extends TableRow = TableRow> {
+  /** 返回稳定行主键，供变更跟踪和冲突定位使用。 */
+  rowKey: RowKeyResolver<T>
+  /** 返回后端乐观锁版本；省略时不进行版本冲突比对。 */
+  getVersion?: (row: T) => string | number | undefined
+  /** 将完整变更集提交到业务服务端。 */
+  commitChanges: ChangeSetHandler<T>
+  /** 保存结算阶段展示给用户的错误文案。 */
+  messages?: TableEngineMessages
+}
+
+/** 创建纯 JS 表格控制器的完整能力配置。未提供的能力不会被隐式开启。 */
+export interface TableControllerOptions<T extends TableRow = TableRow> {
+  /** 控制器稳定身份；同一页面内必须唯一。 */
+  tableKey: string
+  /** Handsontable 自定义模块注册配置，且不依赖任何框架。 */
+  runtime?: TableRuntimeOptions
+  /** 控制器创建时载入的初始行数据，默认空数组。 */
+  initialData?: T[]
+  /** 框架无关查询函数；提供后可通过 runQuery 管理并发和取消。 */
+  query?: TableQuery<T>
+  /** 显式保存、行身份和乐观锁配置。 */
+  editing?: TableEditingOptions<T>
+  /** 行选择状态机配置。 */
+  selection?: TableSelectionOptions<T>
+  /** 保存前及命令式校验配置。 */
+  validation?: TableValidationOptions<T>
+  /** 各列的解析、准入和派生变更策略。 */
+  mutation?: readonly TableMutationColumn<T>[]
+  /** 全量或选择范围汇总的远程 provider。 */
+  summaryProvider?: TableSummaryProvider
+  /** 导出 provider 与 XLSX 写入适配器。 */
+  export?: {
+    /** 远程导出 provider；适合全量数据或异步任务导出。 */
+    provider?: TableExportProvider
+    /** 客户端 XLSX 文件写入实现。 */
+    xlsxWriter?: TableXlsxWriter<T>
+  }
+}
+
+/**
+ * Controller 领域配置补丁。字段是否存在代表是否参与本次事务，因而可以用
+ * `editing: undefined` 等形式显式关闭某项能力。
+ */
+export interface TableControllerConfigurationPatch<
+  T extends TableRow = TableRow,
+> {
+  /** 替换或关闭显式保存、行身份与乐观锁能力。 */
+  editing?: TableEditingOptions<T>
+  /** 替换或关闭当前行选择状态机配置。 */
+  selection?: TableSelectionOptions<T>
+  /** 替换或关闭保存前与命令式校验配置。 */
+  validation?: TableValidationOptions<T>
+  /** 替换或关闭各列的值解析和变更策略。 */
+  mutation?: readonly TableMutationColumn<T>[]
+  /** 只替换后续保存使用的传输函数，不重建编辑基线。 */
+  commitChanges?: ChangeSetHandler<T> | null
+}
+
+/** 以一次原子提交切换查询 provider，并可同时切换本地数据源。 */
+export interface TableDataSourceConfiguration<T extends TableRow = TableRow> {
+  /** 后续查询使用的 provider；省略表示保持当前 provider。 */
+  query?: TableQuery<T>
+  /** 与 provider 同事务切换的本地行数据。 */
+  rows?: readonly T[]
+  /** 与 rows 对应的业务总行数。 */
+  total?: number
+}
+
+/** 网格渲染热路径使用的 O(1) 单元格事务状态。 */
+export interface TableCellState {
+  /** 当前单元格最近一次校验或变更错误。 */
+  error?: unknown
+  /** 当前单元格是否处于版本冲突状态。 */
+  conflict: boolean
+}
+
+/** Controller 对外发布的结构只读状态快照。 */
+export interface TableSnapshot<T extends TableRow = TableRow> {
+  /** 当前表格实例的稳定业务标识。 */
+  tableKey: string
+  /** 当前控制器持有的业务行快照。 */
+  rows: readonly T[]
+  /** 业务行集每次替换或编辑后递增，供展示投影拒绝陈旧结果。 */
+  dataRevision: number
+  /** 当前查询报告的业务总行数。 */
+  total: number
+  /** 是否正在执行远程查询。 */
+  loading: boolean
+  /** 是否正在提交显式变更集。 */
+  saving: boolean
+  /** 当前是否存在尚未提交的变更。 */
+  isDirty: boolean
+  /** 尚未提交的单元格与行级变更数量。 */
+  dirtyCount: number
+  /** 尚未提交的单元格变更明细。 */
+  dirtyCells: readonly DirtyCell[]
+  /** 当前未解决的服务端版本冲突。 */
+  conflicts: readonly VersionConflict<T>[]
+  /** 当前选择状态及已加载选择行。 */
+  selection: SelectionState<T>
+  /** 是否正在运行异步校验。 */
+  validating: boolean
+  /** 最近一次已发布的校验问题。 */
+  validationIssues: readonly TableValidationIssue[]
+  /** 是否正在计算本地或远程汇总。 */
+  summarizing: boolean
+  /** 是否正在生成或请求导出文件。 */
+  exporting: boolean
+  /** 最近一次控制器命令产生的未处理错误。 */
+  error: unknown
+  /** 最近一次查询请求编号，用于识别陈旧响应。 */
+  requestId: number
+  /** Handsontable 网格是否已经挂载。 */
+  mounted: boolean
+}
+
+export type TableSnapshotListener<T extends TableRow = TableRow> = (
+  snapshot: TableSnapshot<T>
+) => void
+
+export interface TableDataProjectionResult<T extends TableRow = TableRow> {
+  /** 交给网格渲染的业务行与展示行集合。 */
+  data: T[]
+  /** 与投影行数必须原子同步的 HOT 设置，例如 fixedRowsBottom。 */
+  settings?: GridSettings
+}
+
+/** 框架适配器可在不污染业务 rows 的前提下追加 summary 等展示行。 */
+export type TableDataProjection<T extends TableRow = TableRow> = (
+  rows: T[],
+  dataRevision: number
+) => T[] | TableDataProjectionResult<T>
+
+export interface TableQueryExecutionOptions {
+  /** 在结果写入表格前拒绝超过此行数的响应。 */
+  maxRows?: number
+  /** 要求 list 数量与 total 严格一致，用于检测后端 pageSize 截断。 */
+  requireComplete?: boolean
+}
+
+export interface TableSummaryExecutionOptions<T extends TableRow = TableRow> {
+  /** 本次汇总覆盖当前页、选择项或全部数据。 */
+  scope: TableSummaryScope
+  /** 参与汇总的列及其聚合规则。 */
+  columns: readonly TableSummaryColumn<T>[]
+  /** 数值、日期等展示格式使用的区域标识。 */
+  locale?: string
+  /** 日期时间格式化使用的 IANA 时区。 */
+  timeZone?: string
+}
+
+export interface TableExportExecutionOptions<T extends TableRow = TableRow> {
+  /** 本次导出覆盖当前页、选择项、范围或全部数据。 */
+  scope: TableExportScope
+  /** 目标文件格式。 */
+  format: TableExportFormat
+  /** 下载文件名，可不含格式扩展名。 */
+  fileName: string
+  /** XLSX 工作表名称。 */
+  sheetName?: string
+  /** 导出列顺序、标题与值转换配置。 */
+  columns: readonly TableExportColumn<T>[]
+  /** 范围导出时实际包含的行。 */
+  rangeRows?: readonly T[]
+  /** 范围导出时实际包含的列。 */
+  rangeColumns?: readonly TableExportColumn<T>[]
+  /** 导出值格式化使用的区域标识。 */
+  locale?: string
+  /** 导出日期时间格式化使用的 IANA 时区。 */
+  timeZone?: string
+}