@tmagic/editor 1.8.0-beta.1 → 1.8.0-beta.11

package/src/services/codeBlock.ts

@@ -23,13 +23,23 @@ 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,
+  DslOpWithHistoryIdsResult,
+  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';
+import { createStackStep, describeRevertStep, getLastPushedHistoryIds } from '@editor/utils/history';
 
 import BaseService from './BaseService';
 
@@ -49,6 +59,17 @@ class CodeBlock extends BaseService {
     paramsColConfig: undefined,
   });
 
+  /**
+   * 最近一次写入历史栈的代码块历史记录 uuid（单条写入场景：新增 / 更新）。
+   * 供 setCodeDslById(Sync)AndGetHistoryId 取回，普通方法不读取它。
+   */
+  private lastPushedHistoryId: string | null = null;
+  /**
+   * deleteCodeDslByIds 一次删除多个代码块时，按写入顺序收集的历史记录 uuid 列表。
+   * 在 deleteCodeDslByIds 入口处重置，供 deleteCodeDslByIdsAndGetHistoryId 取回。
+   */
+  private lastDeletedHistoryIds: string[] = [];
+
   constructor() {
     super([
       ...canUsePluginMethods.async.map((methodName) => ({ name: methodName, isAsync: true })),
@@ -64,6 +85,7 @@ class CodeBlock extends BaseService {
   public async setCodeDsl(codeDsl: CodeBlockDSL): Promise<void> {
     this.state.codeDsl = codeDsl;
     this.emit('code-dsl-change', this.state.codeDsl);
+    this.emit('change', this.state.codeDsl);
   }
 
   /**
@@ -92,10 +114,27 @@ 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,
+      historyDescription,
+      historySource,
+    }: HistoryOpOptionsWithChangeRecords = {},
+  ): Promise<void> {
+    this.setCodeDslByIdSync(id, codeConfig, true, {
+      changeRecords,
+      doNotPushHistory,
+      historyDescription,
+      historySource,
+    });
   }
 
   /**
@@ -104,9 +143,23 @@ 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,
+      historySource,
+    }: HistoryOpOptionsWithChangeRecords = {},
+  ): void {
     const codeDsl = this.getCodeDsl();
 
     if (!codeDsl) {
@@ -123,6 +176,9 @@ class CodeBlock extends BaseService {
       }
     }
 
+    // 历史记录：在写入前快照旧内容，区分新增/更新
+    const oldContent: CodeBlockContent | null = codeDsl[id] ? cloneDeep(codeDsl[id]) : null;
+
     const existContent = codeDsl[id] || {};
 
     codeDsl[id] = {
@@ -130,7 +186,21 @@ class CodeBlock extends BaseService {
       ...codeConfigProcessed,
     };
 
+    const newContent = cloneDeep(codeDsl[id]);
+
+    if (!doNotPushHistory) {
+      const step = createStackStep<CodeBlockContent, CodeBlockStepValue>(id, {
+        oldValue: oldContent,
+        newValue: newContent,
+        changeRecords,
+        historyDescription,
+        source: historySource,
+      });
+      this.lastPushedHistoryId = (step ? historyService.push('codeBlock', step, id) : null)?.uuid ?? null;
+    }
+
     this.emit('addOrUpdate', id, codeDsl[id]);
+    this.emit('change', this.getCodeDsl());
   }
 
   /**
@@ -218,19 +288,88 @@ 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, historySource }: HistoryOpOptions = {},
+  ): Promise<void> {
     const currentDsl = await this.getCodeDsl();
 
     if (!currentDsl) return;
 
+    this.lastDeletedHistoryIds = [];
+
     codeIds.forEach((id) => {
+      // 历史记录：删除前快照内容；不存在的 id 直接跳过历史推入
+      const oldValue: CodeBlockContent | null = currentDsl[id] ? cloneDeep(currentDsl[id]) : null;
+
       delete currentDsl[id];
 
+      if (oldValue && !doNotPushHistory) {
+        const step = createStackStep<CodeBlockContent, CodeBlockStepValue>(id, {
+          oldValue,
+          newValue: null,
+          historyDescription,
+          source: historySource,
+        });
+        const uuid = step ? historyService.push('codeBlock', step, id)?.uuid : undefined;
+        if (uuid) this.lastDeletedHistoryIds.push(uuid);
+      }
+
       this.emit('remove', id);
     });
+
+    this.emit('change', this.getCodeDsl());
   }
 
+  // #region AndGetHistoryId
+  /**
+   * 下列 *AndGetHistoryId 方法与对应的写入方法行为完全一致，
+   * 返回值在 {@link DslOpWithHistoryIdsResult} 中同时包含原操作结果与本次写入的历史 uuid 列表，
+   * 可用于精确引用 / 定位该条历史记录（埋点、revert、跨端同步等）。
+   *
+   * 当本次操作未写入历史（doNotPushHistory 为 true、或无对应记录）时 historyIds 为 `[]`。
+   */
+
+  /** 等价于 {@link setCodeDslById}，并额外返回本次写入历史记录的 uuid 列表（未入栈时 historyIds 为 `[]`）。 */
+  public async setCodeDslByIdAndGetHistoryId(
+    id: Id,
+    codeConfig: Partial<CodeBlockContent>,
+    options: HistoryOpOptionsWithChangeRecords = {},
+  ): Promise<DslOpWithHistoryIdsResult<void>> {
+    this.lastPushedHistoryId = null;
+    await this.setCodeDslById(id, codeConfig, options);
+    return { result: undefined, historyIds: getLastPushedHistoryIds(this.lastPushedHistoryId) };
+  }
+
+  /** 等价于 {@link setCodeDslByIdSync}，并额外返回本次写入历史记录的 uuid 列表（未入栈时 historyIds 为 `[]`）。 */
+  public setCodeDslByIdSyncAndGetHistoryId(
+    id: Id,
+    codeConfig: Partial<CodeBlockContent>,
+    force = true,
+    options: HistoryOpOptionsWithChangeRecords = {},
+  ): DslOpWithHistoryIdsResult<void> {
+    this.lastPushedHistoryId = null;
+    this.setCodeDslByIdSync(id, codeConfig, force, options);
+    return { result: undefined, historyIds: getLastPushedHistoryIds(this.lastPushedHistoryId) };
+  }
+
+  /**
+   * 等价于 {@link deleteCodeDslByIds}，并额外返回本次写入的全部历史记录 uuid（按删除顺序）。
+   * 一次删除多个代码块会产生多条历史记录；未写入任何历史时 historyIds 为 `[]`。
+   */
+  public async deleteCodeDslByIdsAndGetHistoryId(
+    codeIds: Id[],
+    options: HistoryOpOptions = {},
+  ): Promise<DslOpWithHistoryIdsResult<void>> {
+    this.lastDeletedHistoryIds = [];
+    await this.deleteCodeDslByIds(codeIds, options);
+    return { result: undefined, historyIds: [...this.lastDeletedHistoryIds] };
+  }
+  // #endregion AndGetHistoryId
+
   public setParamsColConfig(config: TableColumnConfig): void {
     this.state.paramsColConfig = config;
   }
@@ -239,6 +378,107 @@ 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.undo('codeBlock', 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.redo('codeBlock', id);
+    if (!step) return null;
+    await this.applyHistoryStep(step, false);
+    return step;
+  }
+
+  /** 是否可对指定代码块撤销。 */
+  public canUndo(id: Id): boolean {
+    return historyService.canUndo('codeBlock', id);
+  }
+
+  /** 是否可对指定代码块重做。 */
+  public canRedo(id: Id): boolean {
+    return historyService.canRedo('codeBlock', id);
+  }
+
+  /**
+   * 跳转指定代码块的历史栈到目标游标。语义同 editor.gotoPageStep。
+   *
+   * @param id          代码块 id
+   * @param targetCursor 目标游标位置（已应用步骤数量）
+   * @returns 实际移动到的最终游标位置
+   */
+  public async goto(id: Id, targetCursor: number): Promise<number> {
+    let cursor = historyService.getCursor('codeBlock', 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.getStepList('codeBlock', id);
+    const entry = list[index];
+    if (!entry?.applied) return null;
+    // 更新类步骤（前后 content 都存在）必须带 changeRecords 才支持回滚，否则只能整内容替换，会冲掉后续无关变更。
+    const { oldSchema, newSchema, changeRecords } = entry.step.diff?.[0] ?? {};
+
+    if (oldSchema && newSchema && !changeRecords?.length) return null;
+    const description = `回滚 #${index + 1}: ${describeRevertStep<CodeBlockContent>(entry.step.data.id, entry.step.diff?.[0], (s) => s.name)}`;
+    return await this.applyRevertStep(entry.step, description);
+  }
+
+  /**
+   * 通过历史记录 uuid 回滚代码块历史步骤，语义同 {@link revert}，
+   * 仅无需调用方再传 codeBlockId 与 index：内部会按 uuid 在全部代码块栈中定位对应步骤后再回滚。
+   * 按数组顺序依次回滚，返回与入参同序的结果列表（某项失败时为 `null`）。
+   *
+   * @param uuids 目标历史记录的 uuid 列表，通常由 {@link setCodeDslByIdAndGetHistoryId} 等方法返回的 `historyIds`
+   */
+  public async revertById(uuids: string[]): Promise<(CodeBlockStepValue | null)[]> {
+    const results: (CodeBlockStepValue | null)[] = [];
+    for (const uuid of uuids) {
+      const location = historyService.findStepLocationByUuid('codeBlock', uuid);
+      results.push(location ? await this.revert(location.id, location.index) : null);
+    }
+    return results;
+  }
+
   /**
    * 生成代码块唯一id
    * @returns {Id} 代码块唯一id
@@ -320,6 +560,122 @@ 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 } = step.data;
+    const { oldSchema, newSchema, changeRecords } = step.diff?.[0] ?? {};
+
+    // 原本是新增 → revert 即删除
+    if (!oldSchema && newSchema) {
+      await this.deleteCodeDslByIds([id], { historyDescription, historySource: 'rollback' });
+      return historyService.getStepList('codeBlock', id).slice(-1)[0]?.step ?? null;
+    }
+
+    // 原本是删除 → revert 即写回
+    if (oldSchema && !newSchema) {
+      this.setCodeDslByIdSync(id, cloneDeep(oldSchema), true, { historyDescription, historySource: 'rollback' });
+      return historyService.getStepList('codeBlock', id).slice(-1)[0]?.step ?? null;
+    }
+
+    if (!oldSchema || !newSchema) 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, oldSchema));
+        setValueByKeyPath(record.propPath, value, patched);
+      }
+      this.setCodeDslByIdSync(id, fallbackToFullReplace ? cloneDeep(oldSchema) : patched, true, {
+        changeRecords,
+        historyDescription,
+        historySource: 'rollback',
+      });
+      return historyService.getStepList('codeBlock', id).slice(-1)[0]?.step ?? null;
+    }
+
+    this.setCodeDslByIdSync(id, cloneDeep(oldSchema), true, { historyDescription, historySource: 'rollback' });
+    return historyService.getStepList('codeBlock', 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 } = step.data;
+    const { oldSchema, newSchema, changeRecords } = step.diff?.[0] ?? {};
+
+    // 新增 / 删除：直接 set 或 delete，不走 patch 逻辑
+    if (!oldSchema && newSchema) {
+      if (reverse) {
+        await this.deleteCodeDslByIds([id], { doNotPushHistory: true });
+      } else {
+        this.setCodeDslByIdSync(id, cloneDeep(newSchema), true, { doNotPushHistory: true });
+      }
+      return;
+    }
+
+    if (oldSchema && !newSchema) {
+      if (reverse) {
+        this.setCodeDslByIdSync(id, cloneDeep(oldSchema), true, { doNotPushHistory: true });
+      } else {
+        await this.deleteCodeDslByIds([id], { doNotPushHistory: true });
+      }
+      return;
+    }
+
+    if (!oldSchema || !newSchema) return;
+
+    // 更新场景：优先按 changeRecords 局部 patch；缺省退化为整内容替换
+    const sourceForValues = reverse ? oldSchema : newSchema;
+
+    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;