@tmagic/editor 1.8.0-beta.4 → 1.8.0-beta.5

package/src/services/codeBlock.ts

@@ -38,6 +38,7 @@ import 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 { describeRevertStep } from '@editor/utils/history';
 
 import BaseService from './BaseService';
 
@@ -48,18 +49,6 @@ 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,
@@ -69,6 +58,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 })),
@@ -187,13 +187,14 @@ class CodeBlock extends BaseService {
     const newContent = cloneDeep(codeDsl[id]);
 
     if (!doNotPushHistory) {
-      historyService.pushCodeBlock(id, {
-        oldContent,
-        newContent,
-        changeRecords,
-        historyDescription,
-        source: historySource,
-      });
+      this.lastPushedHistoryId =
+        historyService.pushCodeBlock(id, {
+          oldContent,
+          newContent,
+          changeRecords,
+          historyDescription,
+          source: historySource,
+        })?.uuid ?? null;
     }
 
     this.emit('addOrUpdate', id, codeDsl[id]);
@@ -295,6 +296,8 @@ class CodeBlock extends BaseService {
 
     if (!currentDsl) return;
 
+    this.lastDeletedHistoryIds = [];
+
     codeIds.forEach((id) => {
       // 历史记录：删除前快照内容；不存在的 id 直接跳过历史推入
       const oldContent: CodeBlockContent | null = currentDsl[id] ? cloneDeep(currentDsl[id]) : null;
@@ -302,13 +305,62 @@ class CodeBlock extends BaseService {
       delete currentDsl[id];
 
       if (oldContent && !doNotPushHistory) {
-        historyService.pushCodeBlock(id, { oldContent, newContent: null, historyDescription, source: historySource });
+        const uuid = historyService.pushCodeBlock(id, {
+          oldContent,
+          newContent: null,
+          historyDescription,
+          source: historySource,
+        })?.uuid;
+        if (uuid) this.lastDeletedHistoryIds.push(uuid);
       }
 
       this.emit('remove', id);
     });
   }
 
+  // #region AndGetHistoryId
+  /**
+   * 下列 *AndGetHistoryId 方法与对应的写入方法行为完全一致，
+   * 唯一区别是返回值为本次写入历史栈的历史记录 uuid（{@link CodeBlockStepValue.uuid}），
+   * 可用于精确引用 / 定位该条历史记录（埋点、revert、跨端同步等）。
+   *
+   * 当本次操作未写入历史（doNotPushHistory 为 true、或无对应记录）时：单条写入返回 null，批量删除返回空数组。
+   */
+
+  /** 等价于 {@link setCodeDslById}，但返回本次写入历史记录的 uuid（未入栈时返回 null）。 */
+  public async setCodeDslByIdAndGetHistoryId(
+    id: Id,
+    codeConfig: Partial<CodeBlockContent>,
+    options: HistoryOpOptionsWithChangeRecords = {},
+  ): Promise<string | null> {
+    this.lastPushedHistoryId = null;
+    await this.setCodeDslById(id, codeConfig, options);
+    return this.lastPushedHistoryId;
+  }
+
+  /** 等价于 {@link setCodeDslByIdSync}，但返回本次写入历史记录的 uuid（未入栈时返回 null）。 */
+  public setCodeDslByIdSyncAndGetHistoryId(
+    id: Id,
+    codeConfig: Partial<CodeBlockContent>,
+    force = true,
+    options: HistoryOpOptionsWithChangeRecords = {},
+  ): string | null {
+    this.lastPushedHistoryId = null;
+    this.setCodeDslByIdSync(id, codeConfig, force, options);
+    return this.lastPushedHistoryId;
+  }
+
+  /**
+   * 等价于 {@link deleteCodeDslByIds}，但返回本次写入的全部历史记录 uuid（按删除顺序）。
+   * 一次删除多个代码块会产生多条历史记录，因此返回数组；未写入任何历史时返回空数组。
+   */
+  public async deleteCodeDslByIdsAndGetHistoryId(codeIds: Id[], options: HistoryOpOptions = {}): Promise<string[]> {
+    this.lastDeletedHistoryIds = [];
+    await this.deleteCodeDslByIds(codeIds, options);
+    return [...this.lastDeletedHistoryIds];
+  }
+  // #endregion AndGetHistoryId
+
   public setParamsColConfig(config: TableColumnConfig): void {
     this.state.paramsColConfig = config;
   }
@@ -395,11 +447,27 @@ class CodeBlock extends BaseService {
     const entry = list[index];
     if (!entry?.applied) return null;
     // 更新类步骤（前后 content 都存在）必须带 changeRecords 才支持回滚，否则只能整内容替换，会冲掉后续无关变更。
-    if (entry.step.oldContent && entry.step.newContent && !entry.step.changeRecords?.length) return null;
-    const description = `回滚 #${index + 1}: ${describeRevertCodeBlockStep(entry.step)}`;
+    const { oldSchema, newSchema, changeRecords } = entry.step.diff?.[0] ?? {};
+
+    if (oldSchema && newSchema && !changeRecords?.length) return null;
+    const description = `回滚 #${index + 1}: ${describeRevertStep<CodeBlockContent>(entry.step.id, entry.step.diff?.[0], (s) => s.name)}`;
     return await this.applyRevertStep(entry.step, description);
   }
 
+  /**
+   * 通过历史记录 uuid 回滚某条代码块历史步骤，语义同 {@link revert}，
+   * 仅无需调用方再传 codeBlockId 与 index：内部会按 uuid（{@link CodeBlockStepValue.uuid}）
+   * 在全部代码块栈中定位对应步骤后再回滚。
+   *
+   * @param uuid 目标历史记录的 uuid，通常由 {@link setCodeDslByIdAndGetHistoryId} 等方法返回
+   * @returns 反向后产生的新 step；找不到对应 uuid / 未应用时返回 null
+   */
+  public async revertById(uuid: string): Promise<CodeBlockStepValue | null> {
+    const location = historyService.findCodeBlockStepLocationByUuid(uuid);
+    if (!location) return null;
+    return await this.revert(location.id, location.index);
+  }
+
   /**
    * 生成代码块唯一id
    * @returns {Id} 代码块唯一id
@@ -490,21 +558,22 @@ class CodeBlock extends BaseService {
     step: CodeBlockStepValue,
     historyDescription: string,
   ): Promise<CodeBlockStepValue | null> {
-    const { id, oldContent, newContent, changeRecords } = step;
+    const { id } = step;
+    const { oldSchema, newSchema, changeRecords } = step.diff?.[0] ?? {};
 
     // 原本是新增 → revert 即删除
-    if (oldContent === null && newContent) {
+    if (!oldSchema && newSchema) {
       await this.deleteCodeDslByIds([id], { historyDescription, historySource: 'rollback' });
       return historyService.getCodeBlockStepList(id).slice(-1)[0]?.step ?? null;
     }
 
     // 原本是删除 → revert 即写回
-    if (oldContent && newContent === null) {
-      this.setCodeDslByIdSync(id, cloneDeep(oldContent), true, { historyDescription, historySource: 'rollback' });
+    if (oldSchema && !newSchema) {
+      this.setCodeDslByIdSync(id, cloneDeep(oldSchema), true, { historyDescription, historySource: 'rollback' });
       return historyService.getCodeBlockStepList(id).slice(-1)[0]?.step ?? null;
     }
 
-    if (!oldContent || !newContent) return null;
+    if (!oldSchema || !newSchema) return null;
 
     // 原本是更新 → 把 oldContent 写回；优先按 changeRecords 局部 patch
     if (changeRecords?.length) {
@@ -517,10 +586,10 @@ class CodeBlock extends BaseService {
           fallbackToFullReplace = true;
           break;
         }
-        const value = cloneDeep(getValueByKeyPath(record.propPath, oldContent));
+        const value = cloneDeep(getValueByKeyPath(record.propPath, oldSchema));
         setValueByKeyPath(record.propPath, value, patched);
       }
-      this.setCodeDslByIdSync(id, fallbackToFullReplace ? cloneDeep(oldContent) : patched, true, {
+      this.setCodeDslByIdSync(id, fallbackToFullReplace ? cloneDeep(oldSchema) : patched, true, {
         changeRecords,
         historyDescription,
         historySource: 'rollback',
@@ -528,7 +597,7 @@ class CodeBlock extends BaseService {
       return historyService.getCodeBlockStepList(id).slice(-1)[0]?.step ?? null;
     }
 
-    this.setCodeDslByIdSync(id, cloneDeep(oldContent), true, { historyDescription, historySource: 'rollback' });
+    this.setCodeDslByIdSync(id, cloneDeep(oldSchema), true, { historyDescription, historySource: 'rollback' });
     return historyService.getCodeBlockStepList(id).slice(-1)[0]?.step ?? null;
   }
 
@@ -547,31 +616,32 @@ class CodeBlock extends BaseService {
    * @param reverse true=撤销，false=重做
    */
   private async applyHistoryStep(step: CodeBlockStepValue, reverse: boolean): Promise<void> {
-    const { id, oldContent, newContent, changeRecords } = step;
+    const { id } = step;
+    const { oldSchema, newSchema, changeRecords } = step.diff?.[0] ?? {};
 
     // 新增 / 删除：直接 set 或 delete，不走 patch 逻辑
-    if (oldContent === null && newContent) {
+    if (!oldSchema && newSchema) {
       if (reverse) {
         await this.deleteCodeDslByIds([id], { doNotPushHistory: true });
       } else {
-        this.setCodeDslByIdSync(id, cloneDeep(newContent), true, { doNotPushHistory: true });
+        this.setCodeDslByIdSync(id, cloneDeep(newSchema), true, { doNotPushHistory: true });
       }
       return;
     }
 
-    if (oldContent && newContent === null) {
+    if (oldSchema && !newSchema) {
       if (reverse) {
-        this.setCodeDslByIdSync(id, cloneDeep(oldContent), true, { doNotPushHistory: true });
+        this.setCodeDslByIdSync(id, cloneDeep(oldSchema), true, { doNotPushHistory: true });
       } else {
         await this.deleteCodeDslByIds([id], { doNotPushHistory: true });
       }
       return;
     }
 
-    if (!oldContent || !newContent) return;
+    if (!oldSchema || !newSchema) return;
 
     // 更新场景：优先按 changeRecords 局部 patch；缺省退化为整内容替换
-    const sourceForValues = reverse ? oldContent : newContent;
+    const sourceForValues = reverse ? oldSchema : newSchema;
 
     if (changeRecords?.length) {
       const current = this.getCodeContentById(id);

package/src/services/dataSource.ts

@@ -19,6 +19,7 @@ import type {
 } from '@editor/type';
 import { getFormConfig, getFormValue } from '@editor/utils/data-source';
 import { COPY_DS_STORAGE_KEY } from '@editor/utils/editor';
+import { describeRevertStep } from '@editor/utils/history';
 
 import BaseService from './BaseService';
 
@@ -54,19 +55,6 @@ 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: [],
@@ -78,6 +66,13 @@ class DataSource extends BaseService {
     methods: {},
   });
 
+  /**
+   * 最近一次写入历史栈的数据源历史记录 uuid。
+   * 供 *AndGetHistoryId 系列方法在调用 add / update / remove 后取回本次产生的历史记录 id；
+   * 普通方法不读取它，调用前由 *AndGetHistoryId 重置为 null。
+   */
+  private lastPushedHistoryId: string | null = null;
+
   constructor() {
     super(canUsePluginMethods.sync.map((methodName) => ({ name: methodName, isAsync: false })));
   }
@@ -141,12 +136,13 @@ class DataSource extends BaseService {
     this.get('dataSources').push(newConfig);
 
     if (!doNotPushHistory) {
-      historyService.pushDataSource(newConfig.id, {
-        oldSchema: null,
-        newSchema: newConfig,
-        historyDescription,
-        source: historySource,
-      });
+      this.lastPushedHistoryId =
+        historyService.pushDataSource(newConfig.id, {
+          oldSchema: null,
+          newSchema: newConfig,
+          historyDescription,
+          source: historySource,
+        })?.uuid ?? null;
     }
 
     this.emit('add', newConfig);
@@ -181,13 +177,14 @@ class DataSource extends BaseService {
     dataSources[index] = newConfig;
 
     if (!doNotPushHistory) {
-      historyService.pushDataSource(newConfig.id, {
-        oldSchema: oldConfig ? cloneDeep(oldConfig) : null,
-        newSchema: newConfig,
-        changeRecords,
-        historyDescription,
-        source: historySource,
-      });
+      this.lastPushedHistoryId =
+        historyService.pushDataSource(newConfig.id, {
+          oldSchema: oldConfig ? cloneDeep(oldConfig) : null,
+          newSchema: newConfig,
+          changeRecords,
+          historyDescription,
+          source: historySource,
+        })?.uuid ?? null;
     }
 
     this.emit('update', newConfig, {
@@ -212,17 +209,52 @@ class DataSource extends BaseService {
     dataSources.splice(index, 1);
 
     if (oldConfig && !doNotPushHistory) {
-      historyService.pushDataSource(id, {
-        oldSchema: cloneDeep(oldConfig),
-        newSchema: null,
-        historyDescription,
-        source: historySource,
-      });
+      this.lastPushedHistoryId =
+        historyService.pushDataSource(id, {
+          oldSchema: cloneDeep(oldConfig),
+          newSchema: null,
+          historyDescription,
+          source: historySource,
+        })?.uuid ?? null;
     }
 
     this.emit('remove', id);
   }
 
+  // #region AndGetHistoryId
+  /**
+   * 下列 *AndGetHistoryId 方法与对应的 add / update / remove 行为完全一致，
+   * 唯一区别是返回值为本次写入历史栈的历史记录 uuid（{@link DataSourceStepValue.uuid}），
+   * 而非数据源配置。可用于精确引用 / 定位该条历史记录（埋点、revert、跨端同步等）。
+   *
+   * 当本次操作未写入历史（doNotPushHistory 为 true、或无对应记录）时返回 null。
+   */
+
+  /** 等价于 {@link add}，但返回本次写入历史记录的 uuid（未入栈时返回 null）。 */
+  public addAndGetHistoryId(config: DataSourceSchema, options: HistoryOpOptions = {}): string | null {
+    this.lastPushedHistoryId = null;
+    this.add(config, options);
+    return this.lastPushedHistoryId;
+  }
+
+  /** 等价于 {@link update}，但返回本次写入历史记录的 uuid（未入栈时返回 null）。 */
+  public updateAndGetHistoryId(
+    config: DataSourceSchema,
+    options: HistoryOpOptionsWithChangeRecords = {},
+  ): string | null {
+    this.lastPushedHistoryId = null;
+    this.update(config, options);
+    return this.lastPushedHistoryId;
+  }
+
+  /** 等价于 {@link remove}，但返回本次写入历史记录的 uuid（未入栈时返回 null）。 */
+  public removeAndGetHistoryId(id: string, options: HistoryOpOptions = {}): string | null {
+    this.lastPushedHistoryId = null;
+    this.remove(id, options);
+    return this.lastPushedHistoryId;
+  }
+  // #endregion AndGetHistoryId
+
   /**
    * 撤销指定数据源的最近一次变更。
    *
@@ -298,11 +330,26 @@ class DataSource extends BaseService {
     const entry = list[index];
     if (!entry?.applied) return null;
     // 更新类步骤（前后 schema 都存在）必须带 changeRecords 才支持回滚，否则只能整 schema 替换，会冲掉后续无关变更。
-    if (entry.step.oldSchema && entry.step.newSchema && !entry.step.changeRecords?.length) return null;
-    const description = `回滚 #${index + 1}: ${describeRevertDataSourceStep(entry.step)}`;
+    const { oldSchema, newSchema, changeRecords } = entry.step.diff?.[0] ?? {};
+    if (oldSchema && newSchema && !changeRecords?.length) return null;
+    const description = `回滚 #${index + 1}: ${describeRevertStep<DataSourceSchema>(entry.step.id, entry.step.diff?.[0], (s) => s.title)}`;
     return this.applyRevertStep(entry.step, description);
   }
 
+  /**
+   * 通过历史记录 uuid 回滚某条数据源历史步骤，语义同 {@link revert}，
+   * 仅无需调用方再传 dataSourceId 与 index：内部会按 uuid（{@link DataSourceStepValue.uuid}）
+   * 在全部数据源栈中定位对应步骤后再回滚。
+   *
+   * @param uuid 目标历史记录的 uuid，通常由 {@link addAndGetHistoryId} 等方法返回
+   * @returns 反向后产生的新 step；找不到对应 uuid / 未应用时返回 null
+   */
+  public revertById(uuid: string): DataSourceStepValue | null {
+    const location = historyService.findDataSourceStepLocationByUuid(uuid);
+    if (!location) return null;
+    return this.revert(location.id, location.index);
+  }
+
   public createId(): string {
     return `ds_${guid()}`;
   }
@@ -383,16 +430,17 @@ class DataSource extends BaseService {
    * 同构，差异仅在于走对应的公共 add / update / remove 而不是带 doNotPushHistory 的版本。
    */
   private applyRevertStep(step: DataSourceStepValue, historyDescription: string): DataSourceStepValue | null {
-    const { id, oldSchema, newSchema, changeRecords } = step;
+    const { id } = step;
+    const { oldSchema, newSchema, changeRecords } = step.diff?.[0] ?? {};
 
     // 原本是新增 → revert 即删除
-    if (oldSchema === null && newSchema) {
+    if (!oldSchema && newSchema) {
       this.remove(`${id}`, { historyDescription, historySource: 'rollback' });
       return historyService.getDataSourceStepList(id).slice(-1)[0]?.step ?? null;
     }
 
     // 原本是删除 → revert 即重新加回
-    if (oldSchema && newSchema === null) {
+    if (oldSchema && !newSchema) {
       this.add(cloneDeep(oldSchema), { historyDescription, historySource: 'rollback' });
       return historyService.getDataSourceStepList(id).slice(-1)[0]?.step ?? null;
     }
@@ -440,10 +488,11 @@ class DataSource extends BaseService {
    * @param reverse true=撤销，false=重做
    */
   private applyHistoryStep(step: DataSourceStepValue, reverse: boolean): void {
-    const { id, oldSchema, newSchema, changeRecords } = step;
+    const { id } = step;
+    const { oldSchema, newSchema, changeRecords } = step.diff?.[0] ?? {};
 
     // 新增 / 删除：直接 add 或 remove，不走 patch 逻辑
-    if (oldSchema === null && newSchema) {
+    if (!oldSchema && newSchema) {
       if (reverse) {
         this.remove(`${id}`, { doNotPushHistory: true });
       } else {
@@ -452,7 +501,7 @@ class DataSource extends BaseService {
       return;
     }
 
-    if (oldSchema && newSchema === null) {
+    if (oldSchema && !newSchema) {
       if (reverse) {
         this.add(cloneDeep(oldSchema), { doNotPushHistory: true });
       } else {