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

package/template/src/components/AppTable/engine/table/editing/baselineStore.ts

@@ -0,0 +1,134 @@
+import {
+  cloneTableRows,
+  flattenTableRows,
+  removeTableRows,
+  replaceTableRow,
+  replaceTableRows,
+} from '../../shared/treeRows'
+import type { TableRow } from '../../shared/types'
+import { cloneTableValue } from '../../shared/valueSnapshot'
+
+/**
+ * 最近一次服务端基线。树快照负责放弃修改，按 key 索引负责 patch/版本查询；两者只能
+ * 通过本类同步更新，避免提交结算遗漏其中一份状态。
+ */
+export class TableBaselineStore<T extends TableRow> {
+  private rows: T[] = []
+  private byKey = new Map<string, T>()
+  private versions = new Map<string, string | number | undefined>()
+
+  prepareReset(
+    rows: readonly T[],
+    getEncodedKey: (row: T) => string,
+    getVersion?: (row: T) => string | number | undefined,
+    resolvedEncodedKeys?: readonly string[]
+  ) {
+    const snapshot = cloneTableRows(rows)
+    const byKey = new Map<string, T>()
+    const versions = new Map<string, string | number | undefined>()
+    const flattened = flattenTableRows(snapshot)
+    if (
+      resolvedEncodedKeys &&
+      resolvedEncodedKeys.length !== flattened.length
+    ) {
+      throw new Error(
+        '[TableComponent] Prepared row identity count does not match the data tree.'
+      )
+    }
+    flattened.forEach((row, index) => {
+      const key = resolvedEncodedKeys?.[index] ?? getEncodedKey(row)
+      byKey.set(key, row)
+      versions.set(key, getVersion?.(row))
+    })
+    return () => {
+      this.rows = snapshot
+      this.byKey.clear()
+      byKey.forEach((row, key) => this.byKey.set(key, row))
+      this.versions.clear()
+      versions.forEach((version, key) => this.versions.set(key, version))
+    }
+  }
+
+  cloneRows() {
+    return cloneTableRows(this.rows)
+  }
+
+  getRow(key: string) {
+    return this.byKey.get(key)
+  }
+
+  getVersion(key: string) {
+    return this.versions.get(key)
+  }
+
+  set(key: string, row: T, version?: string | number) {
+    this.byKey.set(key, row)
+    this.versions.set(key, version)
+  }
+
+  delete(key: string) {
+    this.byKey.delete(key)
+    this.versions.delete(key)
+  }
+
+  replaceRow(
+    key: string,
+    row: T,
+    version: string | number | undefined,
+    matches: (row: T) => boolean
+  ) {
+    this.set(key, row, version)
+    this.rows = replaceTableRow(this.rows, matches, cloneTableValue(row)).rows
+  }
+
+  /**
+   * 在不修改当前基线的前提下计算完整提交结果。调用返回的 commit 只交换已经构建
+   * 完成的集合，业务 rowKey/getVersion 回调不会进入最终提交区。
+   */
+  prepareSettlement(options: {
+    upserts: readonly {
+      key: string
+      row: T
+      version: string | number | undefined
+      rootIndex?: number
+    }[]
+    removedKeys: ReadonlySet<string>
+    getEncodedKey: (row: T) => string
+  }) {
+    const nextByKey = new Map(this.byKey)
+    const nextVersions = new Map(this.versions)
+    const replacements = new Map<string, T>()
+    let nextRows = this.rows
+
+    options.upserts.forEach(({ key, row, version, rootIndex }) => {
+      const snapshot = cloneTableValue(row)
+      nextByKey.set(key, snapshot)
+      nextVersions.set(key, version)
+      replacements.set(key, snapshot)
+      if (rootIndex !== undefined) {
+        nextRows = [...nextRows]
+        nextRows.splice(
+          rootIndex < 0 ? nextRows.length : rootIndex,
+          0,
+          cloneTableValue(snapshot)
+        )
+      }
+    })
+    options.removedKeys.forEach((key) => {
+      nextByKey.delete(key)
+      nextVersions.delete(key)
+    })
+    nextRows = replaceTableRows(nextRows, options.getEncodedKey, replacements)
+    if (options.removedKeys.size) {
+      nextRows = removeTableRows(nextRows, (row) =>
+        options.removedKeys.has(options.getEncodedKey(row))
+      ).rows
+    }
+
+    return () => {
+      this.rows = nextRows
+      this.byKey = nextByKey
+      this.versions = nextVersions
+    }
+  }
+}

package/template/src/components/AppTable/engine/table/editing/changeSet.ts

@@ -0,0 +1,492 @@
+import { TABLE_ENGINE_MESSAGES_ZH_CN } from '../../shared/messages'
+import {
+  deleteTableRowValue,
+  getTableRowValue,
+  setTableRowValue,
+} from '../../shared/row'
+import { findTableRowEntry } from '../../shared/treeRows'
+import type { TableRow } from '../../shared/types'
+import { cloneTableValue } from '../../shared/valueSnapshot'
+import { TableBaselineStore } from './baselineStore'
+import {
+  applyTableCommitSettlement,
+  type PendingCreate,
+  type PendingRemove,
+} from './changeSetSettlement'
+import { TABLE_CLIENT_ROW_KEY_PREFIX } from './constants'
+import {
+  createDirtyCellKey as cellKey,
+  TableDirtyCellIndex,
+} from './dirtyCellIndex'
+import { encodeTableRowKey, isRowKey } from './rowKey'
+import type {
+  ChangeSet,
+  ChangeTrackerOptions,
+  CommitResult,
+  ConflictResolution,
+  DirtyCell,
+  RowKey,
+  TableCommitSettlement,
+  TableChangeSubmission,
+  VersionConflict,
+} from './types'
+
+export type {
+  ChangeSet,
+  ChangeSetHandler,
+  CommitResult,
+  ConflictResolution,
+  DirtyCell,
+  RowKey,
+  RowKeyResolver,
+  TableChangeSubmission,
+  VersionConflict,
+} from './types'
+
+let fallbackClientKey = 0
+
+const defaultClientKey = () => {
+  const id = globalThis.crypto?.randomUUID?.()
+  return `${TABLE_CLIENT_ROW_KEY_PREFIX}${id ?? `${Date.now()}:${++fallbackClientKey}`}`
+}
+
+/**
+ * 显式保存模式的变更跟踪器。
+ *
+ * baseline 保存最近一次查询或成功提交后的服务端状态；dirtyCells/creates/removes 只
+ * 保存相对基线的增量。部分提交失败不会清空成功以外的变更，版本冲突也保留用户
+ * patch，供调用方选择“使用服务端”或“基于新版本保留我的修改”。
+ */
+export class TableChangeTracker<T extends TableRow = TableRow> {
+  private readonly baseline = new TableBaselineStore<T>()
+  private dirtyCells = new TableDirtyCellIndex()
+  private creates = new Map<string, PendingCreate<T>>()
+  private removes = new Map<string, PendingRemove<T>>()
+  private versionConflicts = new Map<string, VersionConflict<T>>()
+  private conflictListCache: readonly VersionConflict<T>[] | null = null
+  private conflictCellKeys = new Set<string>()
+  private generation = 0
+  private fieldGenerations = new Map<string, number>()
+  private activeSubmissionGeneration: number | null = null
+
+  constructor(private readonly options: ChangeTrackerOptions<T>) {}
+
+  /** 返回 Controller 装配时验证过的统一行身份解析器。 */
+  get rowKeyResolver() {
+    return this.options.rowKey
+  }
+
+  get isDirty() {
+    return Boolean(
+      this.dirtyCells.size ||
+      this.creates.size ||
+      this.removes.size ||
+      this.versionConflicts.size
+    )
+  }
+
+  get dirtyCount() {
+    return this.dirtyCells.size + this.creates.size + this.removes.size
+  }
+
+  get pendingCreateCount() {
+    return this.creates.size
+  }
+
+  get pendingRemoveCount() {
+    return this.removes.size
+  }
+
+  get cells(): readonly DirtyCell[] {
+    return this.dirtyCells.cells
+  }
+
+  get conflicts(): readonly VersionConflict<T>[] {
+    this.conflictListCache ??= Object.freeze(
+      [...this.versionConflicts.values()].map((conflict) =>
+        Object.freeze({
+          ...conflict,
+          fields: [...conflict.fields],
+          userPatch: cloneTableValue(conflict.userPatch),
+          serverRow: cloneTableValue(conflict.serverRow),
+        })
+      )
+    )
+    return this.conflictListCache
+  }
+
+  /** 按行身份和字段常量时间读取最近一次提交错误。 */
+  getCellError(rowKey: RowKey, prop: string) {
+    return this.dirtyCells.get(cellKey(rowKey, prop))?.error
+  }
+
+  /** 按行身份和字段常量时间判断是否存在版本冲突。 */
+  hasCellConflict(rowKey: RowKey, prop: string) {
+    return this.conflictCellKeys.has(cellKey(rowKey, prop))
+  }
+
+  /** 返回变更世代，用于保存前确认异步校验期间没有发生新编辑。 */
+  get revision() {
+    return this.generation
+  }
+
+  getRowKey(row: T): RowKey {
+    const value =
+      typeof this.options.rowKey === 'function'
+        ? this.options.rowKey(row)
+        : getTableRowValue(row, this.options.rowKey)
+    if (!isRowKey(value)) {
+      throw new Error('[TableComponent] Every editable row requires a rowKey.')
+    }
+    return value
+  }
+
+  private setRowKey(row: T, rowKey: RowKey) {
+    const resolver = this.options.rowKey
+    if (typeof resolver === 'function') return
+    setTableRowValue(row, resolver, rowKey)
+  }
+
+  /** 预先构建完整编辑基线；返回函数执行前不会改写 tracker。 */
+  prepareReset(rows: readonly T[], resolvedKeys?: readonly RowKey[]) {
+    const commitBaseline = this.baseline.prepareReset(
+      rows,
+      (row) => encodeTableRowKey(this.getRowKey(row)),
+      this.options.getVersion,
+      resolvedKeys?.map(encodeTableRowKey)
+    )
+    return () => {
+      commitBaseline()
+      this.clearPendingState()
+    }
+  }
+
+  reset(rows: readonly T[], resolvedKeys?: readonly RowKey[]) {
+    // reset 只允许在数据整体替换或确认提交基线后调用，会清除全部待处理事务状态。
+    this.prepareReset(rows, resolvedKeys)()
+  }
+
+  private clearPendingState() {
+    this.clearDirtyCells()
+    this.creates.clear()
+    this.removes.clear()
+    this.versionConflicts.clear()
+    this.conflictListCache = null
+    this.conflictCellKeys.clear()
+    this.fieldGenerations.clear()
+    this.activeSubmissionGeneration = null
+  }
+
+  trackCell(row: T, prop: string, oldValue: unknown, newValue: unknown) {
+    const rowKey = this.getRowKey(row)
+    const generation = ++this.generation
+    const key = cellKey(rowKey, prop)
+    const created = this.creates.get(String(rowKey))
+    if (created) {
+      created.row = row
+      created.error = undefined
+      if (this.activeSubmissionGeneration !== null)
+        this.fieldGenerations.set(key, generation)
+      else this.fieldGenerations.delete(key)
+      return
+    }
+
+    const existing = this.dirtyCells.get(key)
+    const original = existing?.original ?? oldValue
+    // 用户改回原值时删除脏记录，而不是生成空 patch。
+    if (Object.is(original, newValue)) {
+      this.removeDirtyCell(key)
+      if (this.activeSubmissionGeneration === null)
+        this.fieldGenerations.delete(key)
+      else this.fieldGenerations.set(key, generation)
+    } else {
+      this.fieldGenerations.set(key, generation)
+      this.upsertDirtyCell(key, {
+        rowKey,
+        prop,
+        original,
+        current: newValue,
+      })
+    }
+
+    const conflictKey = encodeTableRowKey(rowKey)
+    const conflict = this.versionConflicts.get(conflictKey)
+    if (conflict) {
+      const userPatch = cloneTableValue(conflict.userPatch)
+      if (Object.is(getTableRowValue(conflict.serverRow, prop), newValue)) {
+        deleteTableRowValue(userPatch, prop)
+      } else {
+        setTableRowValue(userPatch, prop, newValue)
+      }
+      this.versionConflicts.set(conflictKey, {
+        ...conflict,
+        userPatch,
+        fields: Object.keys(userPatch),
+      })
+      this.invalidateConflictCaches()
+    }
+  }
+
+  /** 为新增行预留 client key；提交前失败可恢复调用方原始行对象。 */
+  prepareAdd(
+    row: T,
+    clientKey = this.options.createClientKey?.() ?? defaultClientKey()
+  ) {
+    // client: 前缀把未落库行与真实后端身份隔离，也供选择状态机识别。
+    if (!clientKey.startsWith(TABLE_CLIENT_ROW_KEY_PREFIX)) {
+      throw new Error(
+        `[TableComponent] Client row keys must start with "${TABLE_CLIENT_ROW_KEY_PREFIX}".`
+      )
+    }
+    const resolver = this.options.rowKey
+    const previousKey =
+      typeof resolver === 'function'
+        ? undefined
+        : cloneTableValue(getTableRowValue(row, resolver))
+    this.setRowKey(row, clientKey)
+    let completed = false
+    return {
+      clientKey,
+      commit: () => {
+        if (completed) return
+        completed = true
+        this.creates.set(clientKey, { row })
+        this.generation += 1
+      },
+      rollback: () => {
+        if (completed || typeof resolver === 'function') return
+        if (previousKey === undefined) deleteTableRowValue(row, resolver)
+        else setTableRowValue(row, resolver, previousKey)
+      },
+    }
+  }
+
+  add(
+    row: T,
+    clientKey = this.options.createClientKey?.() ?? defaultClientKey()
+  ) {
+    const prepared = this.prepareAdd(row, clientKey)
+    prepared.commit()
+    return prepared.clientKey
+  }
+
+  /** 预解析整批行身份；返回的提交只修改内部集合且不再调用业务 rowKey 函数。 */
+  prepareRemoveRows(rows: readonly T[]) {
+    const prepared = rows.map((row) => ({ row, rowKey: this.getRowKey(row) }))
+    return () => {
+      prepared.forEach(({ row, rowKey }) => this.removePrepared(row, rowKey))
+    }
+  }
+
+  remove(row: T) {
+    this.prepareRemoveRows([row])()
+  }
+
+  private removePrepared(row: T, rowKey: RowKey) {
+    if (typeof rowKey === 'string' && this.creates.delete(rowKey)) {
+      this.deleteDirtyCells(rowKey)
+      return
+    }
+    this.removes.set(encodeTableRowKey(rowKey), { row: { ...row } })
+    this.generation += 1
+    this.deleteDirtyCells(rowKey)
+    if (this.versionConflicts.delete(encodeTableRowKey(rowKey)))
+      this.invalidateConflictCaches()
+  }
+
+  private deleteDirtyCells(rowKey: RowKey) {
+    const rowPrefix = `${encodeTableRowKey(rowKey)}\u0000`
+    this.dirtyCells.deleteRow(rowKey)
+    for (const key of this.fieldGenerations.keys()) {
+      if (key.startsWith(rowPrefix)) this.fieldGenerations.delete(key)
+    }
+  }
+
+  private upsertDirtyCell(key: string, cell: DirtyCell) {
+    return this.dirtyCells.upsert(key, cell)
+  }
+
+  private removeDirtyCell(key: string) {
+    return this.dirtyCells.delete(key)
+  }
+
+  private clearDirtyCells() {
+    this.dirtyCells.clear()
+  }
+
+  private invalidateConflictCaches() {
+    this.conflictListCache = null
+    this.conflictCellKeys = new Set(
+      [...this.versionConflicts.values()].flatMap((conflict) =>
+        conflict.fields.map((prop) => cellKey(conflict.rowKey, prop))
+      )
+    )
+  }
+
+  /** 代际只服务于进行中的保存结算；事务结束后只保留仍脏字段，避免长期编辑泄漏。 */
+  private pruneFieldGenerations() {
+    for (const key of this.fieldGenerations.keys()) {
+      if (!this.dirtyCells.has(key)) this.fieldGenerations.delete(key)
+    }
+  }
+
+  getChangeSet(): ChangeSet<T> {
+    // 多个脏单元格按 rowKey 聚合成一条 update patch。
+    const updates = new Map<string, ChangeSet<T>['updates'][number]>()
+    for (const cell of this.dirtyCells.values()) {
+      if (this.removes.has(encodeTableRowKey(cell.rowKey))) continue
+      const key = encodeTableRowKey(cell.rowKey)
+      const baseline = this.baseline.getRow(key)
+      let update = updates.get(key)
+      if (!update) {
+        const patch: Partial<T> = {}
+        update = {
+          rowKey: cell.rowKey,
+          baseVersion: baseline ? this.baseline.getVersion(key) : undefined,
+          patch,
+        }
+      }
+      setTableRowValue(update.patch, cell.prop, cell.current)
+      updates.set(key, update)
+    }
+
+    return {
+      creates: [...this.creates.entries()].map(([clientKey, item]) => ({
+        clientKey,
+        value: { ...item.row },
+      })),
+      updates: [...updates.values()],
+      removes: [...this.removes.entries()].map(([key, item]) => ({
+        rowKey: this.getRowKey(item.row),
+        baseVersion:
+          this.baseline.getVersion(key) ?? this.options.getVersion?.(item.row),
+      })),
+    }
+  }
+
+  /** 捕获保存请求对应的不可变 ChangeSet 与字段世代。 */
+  createSubmission(): TableChangeSubmission<T> {
+    this.activeSubmissionGeneration = this.generation
+    const submittedCellsByRow = new Map<string, Map<string, number>>()
+    this.dirtyCells.forEach((cell) => {
+      const key = cellKey(cell.rowKey, cell.prop)
+      const rowKey = encodeTableRowKey(cell.rowKey)
+      let rowCells = submittedCellsByRow.get(rowKey)
+      if (!rowCells) {
+        rowCells = new Map()
+        submittedCellsByRow.set(rowKey, rowCells)
+      }
+      rowCells.set(cell.prop, this.fieldGenerations.get(key) ?? 0)
+    })
+    return {
+      generation: this.generation,
+      changeSet: cloneTableValue(this.getChangeSet()),
+      cellGenerationsByRow: submittedCellsByRow,
+    }
+  }
+
+  /** 无论保存成功、失败或取消，都关闭 submission 世代并回收非脏字段记录。 */
+  finishSubmission(submission: TableChangeSubmission<T>) {
+    if (this.activeSubmissionGeneration !== submission.generation) return
+    this.activeSubmissionGeneration = null
+    this.pruneFieldGenerations()
+  }
+
+  discardRows(): T[] {
+    const rows = this.baseline.cloneRows()
+    // baseline 本身就是最近一次服务端快照，无需为了放弃修改再复制第二次。
+    this.clearPendingState()
+    return rows
+  }
+
+  resolveConflict(
+    rows: T[],
+    rowKey: RowKey,
+    resolution: ConflictResolution
+  ): T[] {
+    const key = encodeTableRowKey(rowKey)
+    const conflict = this.versionConflicts.get(key)
+    if (!conflict) {
+      throw new Error(
+        `[TableComponent] No version conflict exists for row "${String(rowKey)}".`
+      )
+    }
+    const entry = findTableRowEntry(
+      rows,
+      (row) => this.getRowKey(row) === rowKey
+    )
+    if (!entry) {
+      throw new Error(
+        `[TableComponent] Cannot resolve conflict for missing row "${String(rowKey)}".`
+      )
+    }
+
+    const serverRow = cloneTableValue(conflict.serverRow)
+    this.baseline.replaceRow(
+      key,
+      serverRow,
+      conflict.serverVersion ?? this.options.getVersion?.(serverRow),
+      (row) => this.getRowKey(row) === rowKey
+    )
+    if (this.versionConflicts.delete(key)) this.invalidateConflictCaches()
+    if (resolution === 'server') {
+      // 接受服务端版本：替换当前行并清除该行所有本地修改。
+      entry.parentRows[entry.index] = cloneTableValue(serverRow)
+      this.deleteDirtyCells(rowKey)
+      return rows
+    }
+
+    // 保留我的修改：先更新基线，再把用户 patch 重新叠加为新的待提交变更。
+    const rebasedRow: T = { ...serverRow, ...conflict.userPatch }
+    entry.parentRows[entry.index] = rebasedRow
+    this.deleteDirtyCells(rowKey)
+    Object.entries(conflict.userPatch).forEach(([prop, current]) => {
+      const original = getTableRowValue(serverRow, prop)
+      if (!Object.is(original, current)) {
+        this.upsertDirtyCell(cellKey(rowKey, prop), {
+          rowKey,
+          prop,
+          original,
+          current,
+        })
+      }
+    })
+    return rows
+  }
+
+  /**
+   * 结算请求发出前捕获的 submission。所有业务回调在修改 tracker 前完成；主键迁移
+   * 作为返回值交给 Controller，避免外部副作用进入 engine 提交区。
+   */
+  applyCommitResult(
+    rows: T[],
+    result: CommitResult<T> | undefined,
+    submission: TableChangeSubmission<T>
+  ): TableCommitSettlement<T> {
+    const settlement = applyTableCommitSettlement({
+      host: {
+        baseline: this.baseline,
+        dirtyCells: this.dirtyCells,
+        creates: this.creates,
+        removes: this.removes,
+        fieldGenerations: this.fieldGenerations,
+        versionConflicts: this.versionConflicts,
+        getRowKey: (row) => this.getRowKey(row),
+        setRowKey: (row, rowKey) => this.setRowKey(row, rowKey),
+        getVersion: this.options.getVersion,
+        deleteDirtyCells: (rowKey) => this.deleteDirtyCells(rowKey),
+        invalidateConflictCaches: () => this.invalidateConflictCaches(),
+        messages: this.options.messages ?? TABLE_ENGINE_MESSAGES_ZH_CN,
+      },
+      rows,
+      result,
+      submission,
+    })
+    this.finishSubmission(submission)
+    return settlement
+  }
+}
+
+export const createTableChangeTracker = <T extends TableRow>(
+  options: ChangeTrackerOptions<T>
+) => new TableChangeTracker(options)