@tmagic/editor 1.8.0-beta.0 → 1.8.0-beta.2

package/src/services/codeBlock.ts

@@ -23,10 +23,18 @@ import type { Writable } from 'type-fest';
 import type { CodeBlockContent, CodeBlockDSL, Id, MNode, TargetOptions } from '@tmagic/core';
 import { Target, Watcher } from '@tmagic/core';
 import type { TableColumnConfig } from '@tmagic/form';
+import { getValueByKeyPath, setValueByKeyPath } from '@tmagic/utils';
 
 import editorService from '@editor/services/editor';
+import historyService from '@editor/services/history';
 import storageService, { Protocol } from '@editor/services/storage';
-import type { AsyncHookPlugin, CodeState } from '@editor/type';
+import type {
+  AsyncHookPlugin,
+  CodeBlockStepValue,
+  CodeState,
+  HistoryOpOptions,
+  HistoryOpOptionsWithChangeRecords,
+} from '@editor/type';
 import { CODE_DRAFT_STORAGE_KEY } from '@editor/type';
 import { getEditorConfig } from '@editor/utils/config';
 import { COPY_CODE_STORAGE_KEY } from '@editor/utils/editor';
@@ -40,6 +48,18 @@ const canUsePluginMethods = {
 
 type AsyncMethodName = Writable<(typeof canUsePluginMethods)['async']>;
 
+/**
+ * 「回滚」生成的新 step 简短描述。仅 service 层使用。
+ */
+const describeRevertCodeBlockStep = (step: CodeBlockStepValue): string => {
+  const { oldContent, newContent, changeRecords, id } = step;
+  if (oldContent === null && newContent) return `撤回新增 ${newContent.name || newContent.id || id}`;
+  if (oldContent && newContent === null) return `还原已删除的 ${oldContent.name || oldContent.id || id}`;
+  const name = newContent?.name || oldContent?.name || `${id}`;
+  const propPath = changeRecords?.[0]?.propPath;
+  return propPath ? `还原 ${name} · ${propPath}` : `还原 ${name}`;
+};
+
 class CodeBlock extends BaseService {
   private state = reactive<CodeState>({
     codeDsl: null,
@@ -92,10 +112,17 @@ class CodeBlock extends BaseService {
    * 设置代码块ID和代码内容到源dsl
    * @param {Id} id 代码块id
    * @param {CodeBlockContent} codeConfig 代码块内容配置信息
+   * @param options 可选配置
+   * @param options.changeRecords form 端 propPath/value 列表，用于历史记录的精细化撤销/重做
+   * @param options.doNotPushHistory 是否不写入历史记录（默认 false）
    * @returns {void}
    */
-  public async setCodeDslById(id: Id, codeConfig: Partial<CodeBlockContent>): Promise<void> {
-    this.setCodeDslByIdSync(id, codeConfig, true);
+  public async setCodeDslById(
+    id: Id,
+    codeConfig: Partial<CodeBlockContent>,
+    { changeRecords, doNotPushHistory = false }: HistoryOpOptionsWithChangeRecords = {},
+  ): Promise<void> {
+    this.setCodeDslByIdSync(id, codeConfig, true, { changeRecords, doNotPushHistory });
   }
 
   /**
@@ -104,9 +131,18 @@ class CodeBlock extends BaseService {
    * @param {Id} id 代码块id
    * @param {CodeBlockContent} codeConfig 代码块内容配置信息
    * @param {boolean} force 是否强制写入，默认true
+   * @param options 可选配置
+   * @param options.changeRecords form 端 propPath/value 列表，用于历史记录的精细化撤销/重做
+   * @param options.doNotPushHistory 是否不写入历史记录（默认 false）
+   * @param options.historyDescription 入栈时附带的人类可读描述，用于历史面板展示
    * @returns {void}
    */
-  public setCodeDslByIdSync(id: Id, codeConfig: Partial<CodeBlockContent>, force = true): void {
+  public setCodeDslByIdSync(
+    id: Id,
+    codeConfig: Partial<CodeBlockContent>,
+    force = true,
+    { changeRecords, doNotPushHistory = false, historyDescription }: HistoryOpOptionsWithChangeRecords = {},
+  ): void {
     const codeDsl = this.getCodeDsl();
 
     if (!codeDsl) {
@@ -123,6 +159,9 @@ class CodeBlock extends BaseService {
       }
     }
 
+    // 历史记录：在写入前快照旧内容，区分新增/更新
+    const oldContent: CodeBlockContent | null = codeDsl[id] ? cloneDeep(codeDsl[id]) : null;
+
     const existContent = codeDsl[id] || {};
 
     codeDsl[id] = {
@@ -130,6 +169,12 @@ class CodeBlock extends BaseService {
       ...codeConfigProcessed,
     };
 
+    const newContent = cloneDeep(codeDsl[id]);
+
+    if (!doNotPushHistory) {
+      historyService.pushCodeBlock(id, { oldContent, newContent, changeRecords, historyDescription });
+    }
+
     this.emit('addOrUpdate', id, codeDsl[id]);
   }
 
@@ -218,15 +263,27 @@ class CodeBlock extends BaseService {
   /**
    * 在dsl数据源中删除指定id的代码块
    * @param {Id[]} codeIds 需要删除的代码块id数组
+   * @param options 可选配置
+   * @param options.doNotPushHistory 是否不写入历史记录（默认 false）
    */
-  public async deleteCodeDslByIds(codeIds: Id[]): Promise<void> {
+  public async deleteCodeDslByIds(
+    codeIds: Id[],
+    { doNotPushHistory = false, historyDescription }: HistoryOpOptions = {},
+  ): Promise<void> {
     const currentDsl = await this.getCodeDsl();
 
     if (!currentDsl) return;
 
     codeIds.forEach((id) => {
+      // 历史记录：删除前快照内容；不存在的 id 直接跳过历史推入
+      const oldContent: CodeBlockContent | null = currentDsl[id] ? cloneDeep(currentDsl[id]) : null;
+
       delete currentDsl[id];
 
+      if (oldContent && !doNotPushHistory) {
+        historyService.pushCodeBlock(id, { oldContent, newContent: null, historyDescription });
+      }
+
       this.emit('remove', id);
     });
   }
@@ -239,6 +296,87 @@ class CodeBlock extends BaseService {
     return this.state.paramsColConfig;
   }
 
+  /**
+   * 撤销指定代码块的最近一次变更。
+   *
+   * 内部走 setCodeDslByIdSync / deleteCodeDslByIds，因此会自动触发 codeBlockService 的
+   * `addOrUpdate` / `remove` 事件，由 initService 中的 handler 重新维护 dep target
+   * （DepTargetType.CODE_BLOCK 的 add / remove）。所有写回都带 `doNotPushHistory: true`，
+   * 确保不会在历史栈里产生新的记录。
+   *
+   * @param id 代码块 id
+   * @returns 撤销的 step；栈不存在或已无可撤销时返回 null
+   */
+  public async undo(id: Id): Promise<CodeBlockStepValue | null> {
+    const step = historyService.undoCodeBlock(id);
+    if (!step) return null;
+    await this.applyHistoryStep(step, true);
+    return step;
+  }
+
+  /**
+   * 重做指定代码块的下一次变更。
+   * @param id 代码块 id
+   * @returns 重做的 step；栈不存在或已无可重做时返回 null
+   */
+  public async redo(id: Id): Promise<CodeBlockStepValue | null> {
+    const step = historyService.redoCodeBlock(id);
+    if (!step) return null;
+    await this.applyHistoryStep(step, false);
+    return step;
+  }
+
+  /** 是否可对指定代码块撤销。 */
+  public canUndo(id: Id): boolean {
+    return historyService.canUndoCodeBlock(id);
+  }
+
+  /** 是否可对指定代码块重做。 */
+  public canRedo(id: Id): boolean {
+    return historyService.canRedoCodeBlock(id);
+  }
+
+  /**
+   * 跳转指定代码块的历史栈到目标游标。语义同 editor.gotoPageStep。
+   *
+   * @param id          代码块 id
+   * @param targetCursor 目标游标位置（已应用步骤数量）
+   * @returns 实际移动到的最终游标位置
+   */
+  public async goto(id: Id, targetCursor: number): Promise<number> {
+    let cursor = historyService.getCodeBlockCursor(id);
+    const target = Math.max(0, targetCursor);
+    while (cursor > target) {
+      const step = await this.undo(id);
+      if (!step) break;
+      cursor -= 1;
+    }
+    while (cursor < target) {
+      const step = await this.redo(id);
+      if (!step) break;
+      cursor += 1;
+    }
+    return cursor;
+  }
+
+  /**
+   * 「回滚」指定代码块历史步骤（类 git revert 语义）：
+   * - 不动原始栈结构（不移动 cursor、不丢弃任何步骤）；
+   * - 把目标 step 的修改**反向应用**一次，并作为**新步骤**追加到栈顶；
+   * - 仅对已应用的步骤生效。
+   *
+   * @param id    代码块 id
+   * @param index 目标 step 在该栈中的索引（0 为最早），通常由历史面板传入
+   * @returns 反向后产生的新 step；目标不存在 / 未应用时返回 null
+   */
+  public async revert(id: Id, index: number): Promise<CodeBlockStepValue | null> {
+    const list = historyService.getCodeBlockStepList(id);
+    const entry = list[index];
+    if (!entry?.applied) return null;
+    const description = `回滚 #${index + 1}: ${describeRevertCodeBlockStep(entry.step)}`;
+    return await this.applyRevertStep(entry.step, description);
+  }
+
   /**
    * 生成代码块唯一id
    * @returns {Id} 代码块唯一id
@@ -320,6 +458,119 @@ class CodeBlock extends BaseService {
   public usePlugin(options: AsyncHookPlugin<AsyncMethodName, CodeBlock>): void {
     super.usePlugin(options);
   }
+
+  /**
+   * 反向应用一个 step 并以新 step 入栈。逻辑与 applyHistoryStep(reverse=true) 同构，
+   * 差异仅在于通过公开的 setCodeDslByIdSync / deleteCodeDslByIds 触发 push。
+   */
+  private async applyRevertStep(
+    step: CodeBlockStepValue,
+    historyDescription: string,
+  ): Promise<CodeBlockStepValue | null> {
+    const { id, oldContent, newContent, changeRecords } = step;
+
+    // 原本是新增 → revert 即删除
+    if (oldContent === null && newContent) {
+      await this.deleteCodeDslByIds([id], { historyDescription });
+      return historyService.getCodeBlockStepList(id).slice(-1)[0]?.step ?? null;
+    }
+
+    // 原本是删除 → revert 即写回
+    if (oldContent && newContent === null) {
+      this.setCodeDslByIdSync(id, cloneDeep(oldContent), true, { historyDescription });
+      return historyService.getCodeBlockStepList(id).slice(-1)[0]?.step ?? null;
+    }
+
+    if (!oldContent || !newContent) return null;
+
+    // 原本是更新 → 把 oldContent 写回；优先按 changeRecords 局部 patch
+    if (changeRecords?.length) {
+      const current = this.getCodeContentById(id);
+      if (!current) return null;
+      const patched = cloneDeep(current) as CodeBlockContent;
+      let fallbackToFullReplace = false;
+      for (const record of changeRecords) {
+        if (!record.propPath) {
+          fallbackToFullReplace = true;
+          break;
+        }
+        const value = cloneDeep(getValueByKeyPath(record.propPath, oldContent));
+        setValueByKeyPath(record.propPath, value, patched);
+      }
+      this.setCodeDslByIdSync(id, fallbackToFullReplace ? cloneDeep(oldContent) : patched, true, {
+        changeRecords,
+        historyDescription,
+      });
+      return historyService.getCodeBlockStepList(id).slice(-1)[0]?.step ?? null;
+    }
+
+    this.setCodeDslByIdSync(id, cloneDeep(oldContent), true, { historyDescription });
+    return historyService.getCodeBlockStepList(id).slice(-1)[0]?.step ?? null;
+  }
+
+  /**
+   * 把一条历史 step 应用到当前代码块服务上。
+   *
+   * 复用现有的 setCodeDslByIdSync / deleteCodeDslByIds，目的是借助它们发出的事件
+   * 触发 initService 中的 dep target 维护（CODE_BLOCK 的 add / remove）。
+   * 所有写回都带 `doNotPushHistory: true`，确保不会在历史栈里产生新的记录。
+   *
+   * - oldContent=null, newContent≠null：原始为新增 → undo 删除；redo 再次 setCodeDslByIdSync
+   * - oldContent≠null, newContent=null：原始为删除 → undo 还原写入；redo 再次删除
+   * - 两侧都有：原始为更新 → 按 changeRecords 局部 patch；缺省退化为整内容替换
+   *
+   * @param step 历史 step
+   * @param reverse true=撤销，false=重做
+   */
+  private async applyHistoryStep(step: CodeBlockStepValue, reverse: boolean): Promise<void> {
+    const { id, oldContent, newContent, changeRecords } = step;
+
+    // 新增 / 删除：直接 set 或 delete，不走 patch 逻辑
+    if (oldContent === null && newContent) {
+      if (reverse) {
+        await this.deleteCodeDslByIds([id], { doNotPushHistory: true });
+      } else {
+        this.setCodeDslByIdSync(id, cloneDeep(newContent), true, { doNotPushHistory: true });
+      }
+      return;
+    }
+
+    if (oldContent && newContent === null) {
+      if (reverse) {
+        this.setCodeDslByIdSync(id, cloneDeep(oldContent), true, { doNotPushHistory: true });
+      } else {
+        await this.deleteCodeDslByIds([id], { doNotPushHistory: true });
+      }
+      return;
+    }
+
+    if (!oldContent || !newContent) return;
+
+    // 更新场景：优先按 changeRecords 局部 patch；缺省退化为整内容替换
+    const sourceForValues = reverse ? oldContent : newContent;
+
+    if (changeRecords?.length) {
+      const current = this.getCodeContentById(id);
+      if (!current) return;
+      const patched = cloneDeep(current) as CodeBlockContent;
+      let fallbackToFullReplace = false;
+      for (const record of changeRecords) {
+        if (!record.propPath) {
+          fallbackToFullReplace = true;
+          break;
+        }
+        const value = cloneDeep(getValueByKeyPath(record.propPath, sourceForValues));
+        setValueByKeyPath(record.propPath, value, patched);
+      }
+      this.setCodeDslByIdSync(id, fallbackToFullReplace ? cloneDeep(sourceForValues) : patched, true, {
+        changeRecords,
+        doNotPushHistory: true,
+      });
+      return;
+    }
+
+    this.setCodeDslByIdSync(id, cloneDeep(sourceForValues), true, { doNotPushHistory: true });
+  }
 }
 
 export type CodeBlockService = CodeBlock;

package/src/services/dataSource.ts

@@ -4,12 +4,19 @@ import type { Writable } from 'type-fest';
 
 import type { DataSourceSchema, EventOption, Id, MNode, TargetOptions } from '@tmagic/core';
 import { Target, Watcher } from '@tmagic/core';
-import type { ChangeRecord, FormConfig } from '@tmagic/form';
-import { guid, toLine } from '@tmagic/utils';
+import type { FormConfig } from '@tmagic/form';
+import { getValueByKeyPath, guid, setValueByKeyPath, toLine } from '@tmagic/utils';
 
 import editorService from '@editor/services/editor';
+import historyService from '@editor/services/history';
 import storageService, { Protocol } from '@editor/services/storage';
-import type { DatasourceTypeOption, SyncHookPlugin } from '@editor/type';
+import type {
+  DataSourceStepValue,
+  DatasourceTypeOption,
+  HistoryOpOptions,
+  HistoryOpOptionsWithChangeRecords,
+  SyncHookPlugin,
+} from '@editor/type';
 import { getFormConfig, getFormValue } from '@editor/utils/data-source';
 import { COPY_DS_STORAGE_KEY } from '@editor/utils/editor';
 
@@ -47,6 +54,19 @@ const canUsePluginMethods = {
 
 type SyncMethodName = Writable<(typeof canUsePluginMethods)['sync']>;
 
+/**
+ * 「回滚」生成的新 step 简短描述。
+ * 仅在 service 层使用，避免依赖 UI 层 composables。
+ */
+const describeRevertDataSourceStep = (step: DataSourceStepValue): string => {
+  const { oldSchema, newSchema, changeRecords, id } = step;
+  if (oldSchema === null && newSchema) return `撤回新增 ${newSchema.title || newSchema.id || id}`;
+  if (oldSchema && newSchema === null) return `还原已删除的 ${oldSchema.title || oldSchema.id || id}`;
+  const title = newSchema?.title || oldSchema?.title || `${id}`;
+  const propPath = changeRecords?.[0]?.propPath;
+  return propPath ? `还原 ${title} · ${propPath}` : `还原 ${title}`;
+};
+
 class DataSource extends BaseService {
   private state = reactive<State>({
     datasourceTypeList: [],
@@ -102,7 +122,14 @@ class DataSource extends BaseService {
     this.get('methods')[toLine(type)] = value;
   }
 
-  public add(config: DataSourceSchema) {
+  /**
+   * 新增数据源
+   * @param config 数据源配置
+   * @param options 可选配置
+   * @param options.doNotPushHistory 是否不写入历史记录（默认 false）
+   * @param options.historyDescription 入栈时附带的人类可读描述，用于历史面板展示
+   */
+  public add(config: DataSourceSchema, { doNotPushHistory = false, historyDescription }: HistoryOpOptions = {}) {
     const newConfig = {
       ...config,
       id: config.id && !this.getDataSourceById(config.id) ? config.id : this.createId(),
@@ -110,12 +137,27 @@ class DataSource extends BaseService {
 
     this.get('dataSources').push(newConfig);
 
+    if (!doNotPushHistory) {
+      historyService.pushDataSource(newConfig.id, { oldSchema: null, newSchema: newConfig, historyDescription });
+    }
+
     this.emit('add', newConfig);
 
     return newConfig;
   }
 
-  public update(config: DataSourceSchema, { changeRecords = [] }: { changeRecords?: ChangeRecord[] } = {}) {
+  /**
+   * 更新数据源
+   * @param config 数据源配置
+   * @param data 额外数据
+   * @param data.changeRecords form 端变更记录
+   * @param data.doNotPushHistory 是否不写入历史记录（默认 false）
+   * @param data.historyDescription 入栈时附带的人类可读描述，用于历史面板展示
+   */
+  public update(
+    config: DataSourceSchema,
+    { changeRecords = [], doNotPushHistory = false, historyDescription }: HistoryOpOptionsWithChangeRecords = {},
+  ) {
     const dataSources = this.get('dataSources');
 
     const index = dataSources.findIndex((ds) => ds.id === config.id);
@@ -125,6 +167,15 @@ class DataSource extends BaseService {
 
     dataSources[index] = newConfig;
 
+    if (!doNotPushHistory) {
+      historyService.pushDataSource(newConfig.id, {
+        oldSchema: oldConfig ? cloneDeep(oldConfig) : null,
+        newSchema: newConfig,
+        changeRecords,
+        historyDescription,
+      });
+    }
+
     this.emit('update', newConfig, {
       oldConfig,
       changeRecords,
@@ -133,14 +184,104 @@ class DataSource extends BaseService {
     return newConfig;
   }
 
-  public remove(id: string) {
+  /**
+   * 删除数据源
+   * @param id 数据源 id
+   * @param options 可选配置
+   * @param options.doNotPushHistory 是否不写入历史记录（默认 false）
+   * @param options.historyDescription 入栈时附带的人类可读描述，用于历史面板展示
+   */
+  public remove(id: string, { doNotPushHistory = false, historyDescription }: HistoryOpOptions = {}) {
     const dataSources = this.get('dataSources');
     const index = dataSources.findIndex((ds) => ds.id === id);
+    const oldConfig = index !== -1 ? dataSources[index] : null;
     dataSources.splice(index, 1);
 
+    if (oldConfig && !doNotPushHistory) {
+      historyService.pushDataSource(id, { oldSchema: cloneDeep(oldConfig), newSchema: null, historyDescription });
+    }
+
     this.emit('remove', id);
   }
 
+  /**
+   * 撤销指定数据源的最近一次变更。
+   *
+   * 内部走 add / update / remove，因此会自动触发 dataSourceService 的事件，
+   * 由 initService 中的对应 handler 重新收集 dep（DATA_SOURCE / DATA_SOURCE_COND / DATA_SOURCE_METHOD）。
+   * 所有写回都带 `doNotPushHistory: true`，避免在历史栈里产生新的记录。
+   *
+   * @param id 数据源 id
+   * @returns 撤销的 step；栈不存在或已无可撤销时返回 null
+   */
+  public undo(id: Id) {
+    const step = historyService.undoDataSource(id);
+    if (!step) return null;
+    this.applyHistoryStep(step, true);
+    return step;
+  }
+
+  /**
+   * 重做指定数据源的下一次变更。
+   * @param id 数据源 id
+   * @returns 重做的 step；栈不存在或已无可重做时返回 null
+   */
+  public redo(id: Id) {
+    const step = historyService.redoDataSource(id);
+    if (!step) return null;
+    this.applyHistoryStep(step, false);
+    return step;
+  }
+
+  /** 是否可对指定数据源撤销。 */
+  public canUndo(id: Id): boolean {
+    return historyService.canUndoDataSource(id);
+  }
+
+  /** 是否可对指定数据源重做。 */
+  public canRedo(id: Id): boolean {
+    return historyService.canRedoDataSource(id);
+  }
+
+  /**
+   * 跳转指定数据源的历史栈到目标游标。语义同 editor.gotoPageStep。
+   *
+   * @param id          数据源 id
+   * @param targetCursor 目标游标位置（已应用步骤数量）
+   * @returns 实际移动到的最终游标位置
+   */
+  public goto(id: Id, targetCursor: number): number {
+    let cursor = historyService.getDataSourceCursor(id);
+    const target = Math.max(0, targetCursor);
+    while (cursor > target) {
+      if (!this.undo(id)) break;
+      cursor -= 1;
+    }
+    while (cursor < target) {
+      if (!this.redo(id)) break;
+      cursor += 1;
+    }
+    return cursor;
+  }
+
+  /**
+   * 「回滚」指定数据源历史步骤（类 git revert 语义）：
+   * - 不动原始栈结构（不移动 cursor、不丢弃任何步骤）；
+   * - 把目标 step 的修改**反向应用**一次，并作为**新步骤**追加到栈顶；
+   * - 仅对已应用的步骤生效——未应用步骤本身就不存在于当前 schema 中，反向无意义。
+   *
+   * @param id    数据源 id
+   * @param index 目标 step 在该栈中的索引（0 为最早），通常由历史面板传入
+   * @returns 反向后产生的新 step；目标不存在 / 未应用时返回 null
+   */
+  public revert(id: Id, index: number): DataSourceStepValue | null {
+    const list = historyService.getDataSourceStepList(id);
+    const entry = list[index];
+    if (!entry?.applied) return null;
+    const description = `回滚 #${index + 1}: ${describeRevertDataSourceStep(entry.step)}`;
+    return this.applyRevertStep(entry.step, description);
+  }
+
   public createId(): string {
     return `ds_${guid()}`;
   }
@@ -215,6 +356,116 @@ class DataSource extends BaseService {
       }
     });
   }
+
+  /**
+   * 反向应用一个 step 并以新 step 入栈（不带 doNotPushHistory）。逻辑与 applyHistoryStep(reverse=true)
+   * 同构，差异仅在于走对应的公共 add / update / remove 而不是带 doNotPushHistory 的版本。
+   */
+  private applyRevertStep(step: DataSourceStepValue, historyDescription: string): DataSourceStepValue | null {
+    const { id, oldSchema, newSchema, changeRecords } = step;
+
+    // 原本是新增 → revert 即删除
+    if (oldSchema === null && newSchema) {
+      this.remove(`${id}`, { historyDescription });
+      return historyService.getDataSourceStepList(id).slice(-1)[0]?.step ?? null;
+    }
+
+    // 原本是删除 → revert 即重新加回
+    if (oldSchema && newSchema === null) {
+      this.add(cloneDeep(oldSchema), { historyDescription });
+      return historyService.getDataSourceStepList(id).slice(-1)[0]?.step ?? null;
+    }
+
+    if (!oldSchema || !newSchema) return null;
+
+    // 原本是更新 → 把 oldSchema 写回；优先按 changeRecords 局部 patch
+    if (changeRecords?.length) {
+      const current = this.getDataSourceById(`${id}`);
+      if (!current) return null;
+      const patched = cloneDeep(current) as DataSourceSchema;
+      let fallbackToFullReplace = false;
+      for (const record of changeRecords) {
+        if (!record.propPath) {
+          fallbackToFullReplace = true;
+          break;
+        }
+        const value = cloneDeep(getValueByKeyPath(record.propPath, oldSchema));
+        setValueByKeyPath(record.propPath, value, patched);
+      }
+      this.update(fallbackToFullReplace ? cloneDeep(oldSchema) : patched, {
+        changeRecords,
+        historyDescription,
+      });
+      return historyService.getDataSourceStepList(id).slice(-1)[0]?.step ?? null;
+    }
+
+    this.update(cloneDeep(oldSchema), { historyDescription });
+    return historyService.getDataSourceStepList(id).slice(-1)[0]?.step ?? null;
+  }
+
+  /**
+   * 把一条历史 step 应用到当前数据源服务上。
+   *
+   * 复用现有的 add / update / remove，目的是借助它们发出的事件触发 initService 中
+   * 的依赖收集逻辑（DATA_SOURCE / DATA_SOURCE_COND / DATA_SOURCE_METHOD）。
+   * 所有写回都带 `doNotPushHistory: true`，确保不会在历史栈里产生新的记录。
+   *
+   * - oldSchema=null, newSchema≠null：原始为新增 → undo 删除；redo 再次 add
+   * - oldSchema≠null, newSchema=null：原始为删除 → undo 还原 add；redo 再次删除
+   * - 两侧都有：原始为更新 → 按 changeRecords 局部 patch；缺省退化为整 schema 替换
+   *
+   * @param step 历史 step
+   * @param reverse true=撤销，false=重做
+   */
+  private applyHistoryStep(step: DataSourceStepValue, reverse: boolean): void {
+    const { id, oldSchema, newSchema, changeRecords } = step;
+
+    // 新增 / 删除：直接 add 或 remove，不走 patch 逻辑
+    if (oldSchema === null && newSchema) {
+      if (reverse) {
+        this.remove(`${id}`, { doNotPushHistory: true });
+      } else {
+        this.add(cloneDeep(newSchema), { doNotPushHistory: true });
+      }
+      return;
+    }
+
+    if (oldSchema && newSchema === null) {
+      if (reverse) {
+        this.add(cloneDeep(oldSchema), { doNotPushHistory: true });
+      } else {
+        this.remove(`${id}`, { doNotPushHistory: true });
+      }
+      return;
+    }
+
+    if (!oldSchema || !newSchema) return;
+
+    // 更新场景：优先按 changeRecords 局部 patch；缺省退化为整 schema 替换
+    const sourceForValues = reverse ? oldSchema : newSchema;
+
+    if (changeRecords?.length) {
+      const current = this.getDataSourceById(`${id}`);
+      if (!current) return;
+      const patched = cloneDeep(current) as DataSourceSchema;
+      let fallbackToFullReplace = false;
+      for (const record of changeRecords) {
+        if (!record.propPath) {
+          fallbackToFullReplace = true;
+          break;
+        }
+        const value = cloneDeep(getValueByKeyPath(record.propPath, sourceForValues));
+        setValueByKeyPath(record.propPath, value, patched);
+      }
+      this.update(fallbackToFullReplace ? cloneDeep(sourceForValues) : patched, {
+        changeRecords,
+        doNotPushHistory: true,
+      });
+      return;
+    }
+
+    this.update(cloneDeep(sourceForValues), { doNotPushHistory: true });
+  }
 }
 
 export type DataSourceService = DataSource;