@epoint-testtech/stage-create 0.0.3-alpha.1

package/templates/glue/src/report/run-info.ts

@@ -0,0 +1,85 @@
+import fs from 'fs';
+import path from 'path';
+
+import { StagePath } from '@epoint-testtech/stage-core';
+import { addTimeStampPrefix, generateTimeStamp } from '@epoint-testtech/stage-core/utils';
+
+export type GlueRunInfo = {
+  runTimeStamp: string;
+  authFilePath: string;
+  batchReportDirPath: string;
+  playwrightReportDirPath: string;
+  stageGlueReportHtmlPath: string;
+  stageGlueReportJsonPath: string;
+};
+
+export type GlueRunInfoContext = GlueRunInfo & {
+  glueReportRoot: string;
+  reportDir: string;
+  runInfoPath: string;
+};
+
+/**
+ * 读取当前执行批次信息。
+ * @param configDir Playwright 配置文件所在目录。
+ * @returns 已写入的执行批次信息，不存在时返回 undefined。
+ */
+export function readGlueRunInfo(projectRootDir: string): GlueRunInfo | undefined {
+  const runInfoPath = path.join(projectRootDir, 'glue-report', 'run-info.json');
+  if (!fs.existsSync(runInfoPath)) {
+    return undefined;
+  }
+  return JSON.parse(fs.readFileSync(runInfoPath, 'utf-8')) as GlueRunInfo;
+}
+
+/**
+ * 解析当前执行批次下的下载产物目录。
+ * @param testTitle Playwright 用例标题。
+ * @param configDir Playwright 配置文件所在目录，默认使用当前工作目录。
+ * @returns 位于 `glue-report/<runTimeStamp>/downloads/` 下的用例级下载目录。
+ */
+export function resolveGlueDownloadDir(testTitle: string): string {
+  return path.join(StagePath.downloadDirPath, addTimeStampPrefix(testTitle));
+}
+
+/**
+ * 初始化本轮胶水编码运行信息，并确保多次加载配置时复用同一个执行时间戳。
+ * @param configDir Playwright 配置文件所在目录。
+ * @returns 本轮运行信息及常用路径。
+ */
+export function initializeGlueRunInfo(configDir: string): GlueRunInfoContext {
+  const glueReportRoot = path.join(configDir, 'glue-report');
+  const runInfoPath = path.join(glueReportRoot, 'run-info.json');
+  const authFilePath = path.join(glueReportRoot, 'stage-auth.json');
+  const timestamp = process.env.STAGE_REPORT_TIMESTAMP || generateTimeStamp();
+  const reportDir = path.join(glueReportRoot, timestamp);
+  const playwrightReportDirPath = path.join(reportDir, 'playwright-report');
+  const downloadDirPath = path.join(reportDir, 'downloads');
+
+  process.env.STAGE_PROJECT_ROOT_DIR_PATH = configDir;
+  process.env.STAGE_REPORT_ROOT_DIR_PATH = glueReportRoot;
+  process.env.STAGE_REPORT_DIR_PATH = reportDir;
+  process.env.STAGE_REPORT_TIMESTAMP = timestamp;
+  process.env.STAGE_AUTH_FILE_PATH = authFilePath;
+  process.env.STAGE_GLUE_PLAYWRIGHT_REPORT_DIR = reportDir;
+  process.env.STAGE_DOWNLOAD_DIR_PATH = downloadDirPath;
+
+  const runInfo: GlueRunInfo = {
+    runTimeStamp: timestamp,
+    authFilePath,
+    batchReportDirPath: reportDir,
+    playwrightReportDirPath,
+    stageGlueReportHtmlPath: path.join(reportDir, `stage-glue-${timestamp}.html`),
+    stageGlueReportJsonPath: path.join(reportDir, `stage-glue-${timestamp}.json`),
+  };
+
+  fs.mkdirSync(glueReportRoot, { recursive: true });
+  fs.writeFileSync(runInfoPath, JSON.stringify(runInfo, null, 2), 'utf-8');
+
+  return {
+    ...runInfo,
+    glueReportRoot,
+    reportDir,
+    runInfoPath,
+  };
+}

package/templates/glue/src/skeletons/crud.skeleton.ts

@@ -0,0 +1,450 @@
+import { expect, type FrameLocator, type Page } from '@playwright/test';
+import { stageLocator } from '@epoint-testtech/stage-core';
+import { addTimeStampPrefix, log } from '@epoint-testtech/stage-core/utils';
+import { ListBoxComponent } from '../web/component';
+
+export type CrudDeletePolicy = 'success_delete' | 'blocked_by_business_rule';
+export type CrudDataValueStrategy = 'timestamp_prefix' | 'fixed_value';
+
+export type CrudDataKeySlot = {
+  field: string;
+  seedValue: string;
+  strategy?: CrudDataValueStrategy;
+  fixedValue?: string;
+  updatePrefix?: string;
+};
+
+export type CrudListboxSelectionSlot = {
+  field: string;
+  label: string;
+  value: string;
+};
+
+export type CrudInputSearchConditionSlot = CrudDataKeySlot & {
+  component: 'input';
+  label: string;
+  addLocator: string;
+  editLocator: string;
+  listLocator: string;
+  searchSeedValue?: string;
+};
+
+export type CrudListboxSearchConditionSlot = {
+  component: 'listbox';
+  field: string;
+  label: string;
+  value: string;
+  createSelections?: CrudListboxSelectionSlot[];
+};
+
+export type CrudSearchConditionSlot = CrudInputSearchConditionSlot | CrudListboxSearchConditionSlot;
+
+/**
+ * CRUD 骨架输入槽位。
+ *
+ * 这是“外部传给骨架的参数定义”，不是运行过程中自动算出来的数据。
+ * 可以理解为：黄金脚本里所有会随业务模块变化的动态信息，都收敛到这个对象里。
+ *
+ * 结构分工：
+ * - moduleId: 当前业务模块标识，只用于日志和问题定位
+ * - searchConditions: 列表页搜索条件清单，Read 工作流会逐项校验，Create 工作流补选其中的 listbox 条目
+ * - frames: 各业务页面 iframe 的进入关键字
+ * - locators: CRUD 流程需要用到的通用页面控件定位表达式
+ * - assertions: 删除阶段的断言策略
+ */
+export type CrudFlowSlots = {
+  moduleId: string;
+  searchConditions: CrudSearchConditionSlot[];
+  frames: {
+    listIframeSrcKeyword: string;
+    addIframeSrcKeyword: string;
+    editIframeSrcKeyword: string;
+  };
+  locators: {
+    createButton: string;
+    addAutofillTrigger?: string;
+    addSaveButton: string;
+    listSearchSubmit: string;
+    listResultValueLocatorTemplate: string;
+    listEditActionLocatorTemplate: string;
+    editSaveButton: string;
+    listRowSelectLocatorTemplate: string;
+    listDeleteButton: string;
+    deleteConfirmButton?: string;
+  };
+  assertions: {
+    deletePolicy: CrudDeletePolicy;
+    blockedDeleteMessage?: string;
+  };
+};
+
+/**
+ * 单个搜索条件的 CRUD 流程运行时数据。
+ */
+export type CrudFlowRuntimeData = {
+  createValue: string;
+  updateValue: string;
+  searchValue: string;
+};
+
+export type CrudSearchConditionRuntimeData = CrudFlowRuntimeData & {
+  field: string;
+  label: string;
+  component: CrudSearchConditionSlot['component'];
+};
+
+/**
+ * CRUD 工作流运行时数据。
+ *
+ * 在 CrudFlowRuntimeData 基础上额外携带 dataKey，
+ * 作为 Create/Read/Update/Delete 各阶段独立调用时共享的行定位锚点。
+ */
+export type CrudWorkflowData = CrudFlowRuntimeData & {
+  dataKey: CrudInputSearchConditionSlot;
+};
+
+export class CrudPage {
+  private readonly repoIFrame列表页: FrameLocator;
+  private readonly repoIFrame新增页: FrameLocator;
+  private readonly repoIFrame修改页: FrameLocator;
+
+  /**
+   * 初始化 CRUD 页面对象。
+   * @param page Playwright 页面对象
+   * @param slots CRUD 骨架运行所需的动态槽位
+   */
+  constructor(
+    public readonly page: Page,
+    private readonly slots: CrudFlowSlots
+  ) {
+    this.repoIFrame列表页 = page.locator(`iframe[src*="${slots.frames.listIframeSrcKeyword}"]`).contentFrame();
+    this.repoIFrame新增页 = page.locator(`iframe[src*="${slots.frames.addIframeSrcKeyword}"]`).contentFrame();
+    this.repoIFrame修改页 = page.locator(`iframe[src*="${slots.frames.editIframeSrcKeyword}"]`).contentFrame();
+  }
+
+  /**
+   * 准备 CRUD 工作流运行时数据。
+   * @returns 用于 Create/Read/Update/Delete 串联的数据
+   * @throws 当没有 input 搜索条件时抛出异常
+   */
+  prepareWorkflowData(): CrudWorkflowData {
+    const dataKey = this.resolveInputRowAnchor();
+    return {
+      ...this.buildRuntimeData(dataKey),
+      dataKey,
+    };
+  }
+
+  /**
+   * 执行 Create 工作流。
+   * @param workflowData 工作流运行时数据
+   */
+  async runCreateWorkflow(workflowData: CrudWorkflowData): Promise<void> {
+    const listboxSelections = this.resolveCreateSelections();
+    await this.createRecord(workflowData.createValue, workflowData.dataKey.addLocator, listboxSelections);
+    await this.searchByInputAndAssertCount(workflowData.dataKey, workflowData.searchValue, 1);
+  }
+
+  /**
+   * 执行 Read/Search 工作流。
+   * @param workflowData 工作流运行时数据
+   */
+  async runReadWorkflow(workflowData: CrudWorkflowData): Promise<void> {
+    for (const condition of this.slots.searchConditions) {
+      if (condition.component === 'input') {
+        await this.searchByInputAndAssertCount(condition, workflowData.searchValue, 1);
+      } else {
+        await this.searchByListboxAndAssertRecord(condition, workflowData.dataKey, workflowData.createValue, 1);
+      }
+    }
+  }
+
+  /**
+   * 执行 Update 工作流。
+   * @param workflowData 工作流运行时数据
+   */
+  async runUpdateWorkflow(workflowData: CrudWorkflowData): Promise<void> {
+    await this.updateRecord(workflowData.createValue, workflowData.updateValue, workflowData.dataKey.editLocator);
+    await this.searchByInputAndAssertCount(workflowData.dataKey, workflowData.updateValue, 1);
+  }
+
+  /**
+   * 执行 Delete 工作流。
+   * @param workflowData 工作流运行时数据
+   */
+  async runDeleteWorkflow(workflowData: CrudWorkflowData): Promise<void> {
+    await this.deleteRecord(workflowData.updateValue);
+
+    if (this.slots.assertions.deletePolicy === 'success_delete') {
+      await this.searchByInputAndAssertCount(workflowData.dataKey, workflowData.updateValue, 0);
+    } else {
+      await this.assertDeleteBlocked();
+    }
+  }
+
+  /**
+   * 为 listbox 流程解析唯一行锚点。
+   * @returns 用于新增、修改、删除定位的 input 搜索条件
+   * @throws 当 searchConditions 中不存在 input 条件时抛出异常
+   */
+  private resolveInputRowAnchor(): CrudInputSearchConditionSlot {
+    const inputCondition = this.slots.searchConditions.find(
+      (condition): condition is CrudInputSearchConditionSlot => condition.component === 'input'
+    );
+    if (!inputCondition) {
+      throw new Error('listbox CRUD 流程需要至少一个 input 搜索条件作为唯一行锚点');
+    }
+    return inputCondition;
+  }
+
+  /**
+   * 解析新增工作流需要补选的 listbox 条目。
+   * @returns 去重后的 listbox 选择项
+   */
+  private resolveCreateSelections(): CrudListboxSelectionSlot[] {
+    const selections = this.slots.searchConditions
+      .filter((condition): condition is CrudListboxSearchConditionSlot => condition.component === 'listbox')
+      .flatMap((condition) => condition.createSelections ?? [
+        { field: condition.field, label: condition.label, value: condition.value },
+      ]);
+
+    const seen = new Set<string>();
+    return selections.filter((selection) => {
+      const key = `${selection.field}::${selection.label}::${selection.value}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+  }
+
+  /**
+   * 构建当前流程运行时使用的关键数据。
+   * @param dataKey 当前流程的数据主锚点槽位
+   * @returns 包含新增值、修改值和搜索值的运行时数据
+   */
+  private buildRuntimeData(dataKey: CrudDataKeySlot & { searchSeedValue?: string }): CrudFlowRuntimeData {
+    const createValue = this.buildCreateValue(dataKey);
+    const updatePrefix = dataKey.updatePrefix ?? '修改';
+    const updateValue = `${updatePrefix}${createValue}`;
+
+    return {
+      createValue,
+      updateValue,
+      searchValue: dataKey.searchSeedValue ?? createValue,
+    };
+  }
+
+  /**
+   * 按策略生成新增阶段的数据主键值。
+   * @param dataKey 当前流程的数据主锚点槽位
+   * @returns 本次新增要写入页面的数据值
+   */
+  private buildCreateValue(dataKey: CrudDataKeySlot): string {
+    if (dataKey.strategy === 'fixed_value') {
+      return dataKey.fixedValue ?? dataKey.seedValue;
+    }
+    return addTimeStampPrefix(dataKey.seedValue);
+  }
+
+  /**
+   * 将动态值渲染到 locator 模板中。
+   * @param template 含有 `{{value}}` 占位符的模板
+   * @param value 需要替换进去的运行时值
+   * @returns 渲染后的定位表达式
+   */
+  private 渲染动态定位模板(template: string, value: string): string {
+    return template.replaceAll('{{value}}', value);
+  }
+
+  /**
+   * 执行新增记录流程。
+   * @param createValue 本次新增写入的数据主键值
+   * @param inputLocator 新增表单中需要补填的 input 定位表达式
+   * @param listboxSelections 新增表单中需要补选的 listbox 条目
+   */
+  private async createRecord(
+    createValue: string,
+    inputLocator: string,
+    listboxSelections: CrudListboxSelectionSlot[] = []
+  ): Promise<void> {
+    log.info(`新增数据-->点击新增按钮, 模块: ${this.slots.moduleId}`);
+    await this.repoIFrame列表页.locator(this.slots.locators.createButton).click();
+
+    await this.repoIFrame新增页.locator(inputLocator).waitFor();
+
+    if (this.slots.locators.addAutofillTrigger) {
+      await stageLocator(this.repoIFrame新增页.locator(this.slots.locators.addAutofillTrigger), '新增页默认填充').clickIfExist({ timeout: 2_000 });
+    }
+
+    log.info(`新增数据-->补填input锚点: ${createValue}`);
+    await this.repoIFrame新增页.locator(inputLocator).fill(createValue);
+
+    for (const selection of listboxSelections) {
+      log.info(`新增数据-->补选listbox: ${selection.field}, 标签: ${selection.label}, 值: ${selection.value}`);
+      await this.selectListbox(this.repoIFrame新增页, selection.label, selection.value);
+    }
+
+    await this.repoIFrame新增页.locator(this.slots.locators.addSaveButton).click();
+  }
+
+  /**
+   * 选择指定上下文中的 listbox 项。
+   * @param context 包含 locator 方法的页面或 iframe 上下文
+   * @param label listbox 的 label
+   * @param value 要选择的文本值
+   */
+  private async selectListbox(context: FrameLocator, label: string, value: string): Promise<void> {
+    const listbox = new ListBoxComponent(context, label);
+    await listbox.selectItem(value);
+  }
+
+  /**
+   * 使用 listbox 搜索条件搜索，并按唯一行锚点校验结果是否出现。
+   * @param condition listbox 搜索条件槽位
+   * @param rowAnchor 唯一行锚点槽位
+   * @param resultValue 需要在列表结果中校验的数据主锚点值
+   * @param expectedCount 期望匹配条数
+   */
+  private async searchByListboxAndAssertRecord(
+    condition: CrudListboxSearchConditionSlot,
+    rowAnchor: CrudInputSearchConditionSlot,
+    resultValue: string,
+    expectedCount: number
+  ): Promise<void> {
+    log.info(`ListBox搜索校验-->字段: ${condition.field}, 标签: ${condition.label}, 值: ${condition.value}, 结果锚点: ${resultValue}, 期望条数: ${expectedCount}`);
+    await this.repoIFrame列表页.locator(rowAnchor.listLocator).fill('');
+    await this.selectListbox(this.repoIFrame列表页, condition.label, condition.value);
+    await this.repoIFrame列表页.locator(this.slots.locators.listSearchSubmit).click();
+
+    const repo搜索结果值 = this.repoIFrame列表页.locator(
+      this.渲染动态定位模板(this.slots.locators.listResultValueLocatorTemplate, resultValue)
+    );
+    const actualCount = await repo搜索结果值.count();
+    expect(actualCount).toBe(expectedCount);
+  }
+
+  /**
+   * 执行 input 搜索并校验搜索结果条数。
+   * @param condition input 搜索条件槽位
+   * @param searchValue 搜索输入值
+   * @param expectedCount 期望结果条数
+   */
+  private async searchByInputAndAssertCount(
+    condition: CrudInputSearchConditionSlot,
+    searchValue: string,
+    expectedCount: number
+  ): Promise<void> {
+    log.info(`搜索校验-->字段: ${condition.field}, 标签: ${condition.label}, 值: ${searchValue}, 期望条数: ${expectedCount}`);
+    await this.repoIFrame列表页.locator(condition.listLocator).fill(searchValue);
+    await this.repoIFrame列表页.locator(this.slots.locators.listSearchSubmit).click();
+
+    const repo搜索结果值 = this.repoIFrame列表页.locator(
+      this.渲染动态定位模板(this.slots.locators.listResultValueLocatorTemplate, searchValue)
+    );
+    const actualCount = await repo搜索结果值.count();
+    expect(actualCount).toBe(expectedCount);
+  }
+
+  /**
+   * 执行修改记录流程。
+   * @param currentValue 当前列表中用于定位待修改记录的旧值
+   * @param updateValue 修改后写入的新值
+   * @param inputLocator 修改表单中需要补填的 input 定位表达式
+   */
+  private async updateRecord(currentValue: string, updateValue: string, inputLocator: string): Promise<void> {
+    const repoBtn修改行操作 = this.渲染动态定位模板(this.slots.locators.listEditActionLocatorTemplate, currentValue);
+    log.info(`修改数据-->旧值: ${currentValue}, 新值: ${updateValue}`);
+    await this.repoIFrame列表页.locator(repoBtn修改行操作).click();
+
+    await this.repoIFrame修改页.locator(inputLocator).waitFor();
+    await this.repoIFrame修改页.locator(inputLocator).fill(updateValue);
+    await this.repoIFrame修改页.locator(this.slots.locators.editSaveButton).click();
+  }
+
+  /**
+   * 执行删除记录流程。
+   * @param targetValue 列表中用于选中待删除记录的目标值
+   */
+  private async deleteRecord(targetValue: string): Promise<void> {
+    const repo选中待删除记录 = this.渲染动态定位模板(this.slots.locators.listRowSelectLocatorTemplate, targetValue);
+
+    log.info(`删除数据-->目标值: ${targetValue}, 预期策略: ${this.slots.assertions.deletePolicy}`);
+    await this.repoIFrame列表页.locator(repo选中待删除记录).click();
+    await this.repoIFrame列表页.locator(this.slots.locators.listDeleteButton).click();
+
+    if (this.slots.locators.deleteConfirmButton) {
+      await this.clickDeleteConfirmButton();
+    }
+  }
+
+  /**
+   * 点击删除确认弹框中的确认按钮。
+   *
+   * 黄金参考脚本中的确认按钮优先出现在列表页 iframe 内，
+   * 但不同页面实现也可能挂在顶层 page，因此这里按“列表 iframe -> 顶层 page”顺序回退。
+   */
+  private async clickDeleteConfirmButton(): Promise<void> {
+    const deleteConfirmButton = this.slots.locators.deleteConfirmButton;
+    if (!deleteConfirmButton) {
+      return;
+    }
+
+    const repoBtn删除确认候选 = [
+      {
+        locator: this.repoIFrame列表页.locator(deleteConfirmButton),
+        name: '删除确认(列表页iframe)',
+      },
+      {
+        locator: this.page.locator(deleteConfirmButton),
+        name: '删除确认(顶层页面)',
+      },
+    ];
+
+    for (const candidate of repoBtn删除确认候选) {
+      const repoStageLocator = stageLocator(candidate.locator, candidate.name);
+      const isExist = await repoStageLocator.waitForExist({ timeout: 2_000, state: 'visible' });
+      if (isExist) {
+        await candidate.locator.click();
+        log.info(`元素：${candidate.name}存在，并点击`);
+        return;
+      }
+    }
+  }
+
+  /**
+   * 校验删除被业务规则阻塞。
+   * @throws 当未提供阻塞提示消息时抛出异常
+   */
+  private async assertDeleteBlocked(): Promise<void> {
+    if (!this.slots.assertions.blockedDeleteMessage) {
+      throw new Error('deletePolicy=blocked_by_business_rule 时必须提供 blockedDeleteMessage');
+    }
+    log.info(`删除阻塞校验-->消息: ${this.slots.assertions.blockedDeleteMessage}`);
+    const blockedDeleteMessage = this.slots.assertions.blockedDeleteMessage;
+    const repo删除阻塞消息候选 = [
+      this.repoIFrame列表页.locator(`text=${blockedDeleteMessage}`),
+      this.page.locator(`text=${blockedDeleteMessage}`),
+      this.repoIFrame列表页.locator('body'),
+      this.page.locator('body'),
+    ];
+
+    for (const candidate of repo删除阻塞消息候选) {
+      try {
+        if (await candidate.count() === 0) {
+          continue;
+        }
+
+        if (candidate === repo删除阻塞消息候选[0] || candidate === repo删除阻塞消息候选[1]) {
+          await expect(candidate).toBeVisible({ timeout: 5_000 });
+        } else {
+          await expect(candidate).toContainText(blockedDeleteMessage, { timeout: 5_000 });
+        }
+        return;
+      } catch {
+        continue;
+      }
+    }
+
+    throw new Error(`未找到删除阻塞提示消息: ${blockedDeleteMessage}`);
+  }
+}

package/templates/glue/src/skeletons/export.skeleton.ts

@@ -0,0 +1,114 @@
+import { expect, type FrameLocator, type Page, type TestInfo } from '@playwright/test';
+import { log } from '@epoint-testtech/stage-core/utils';
+import fs from 'fs';
+import path from 'path';
+import { resolveGlueDownloadDir } from '../report/run-info';
+import { DataExportComponent } from '../web/component';
+
+export type ExportMode = 'all' | 'current_page' | 'page_range';
+
+export type ExportFlowSlots = {
+  moduleId: string;
+  frames: {
+    listIframeSrcKeyword: string;
+  };
+  locators: {
+    exportButton: string;
+  };
+  export: {
+    label: string;
+    mode: ExportMode;
+    startPage?: number;
+    endPage?: number;
+  };
+};
+
+export type ExportWorkflowResult = {
+  filePath: string;
+  suggestedFilename: string;
+  size: number;
+};
+
+export class ExportPage {
+  private readonly repoIFrame列表页: FrameLocator;
+
+  /**
+   * 初始化导出工作流页面对象。
+   * @param page Playwright 页面对象
+   * @param slots 导出工作流动态槽位
+   */
+  constructor(
+    public readonly page: Page,
+    private readonly slots: ExportFlowSlots
+  ) {
+    this.repoIFrame列表页 = page.locator(`iframe[src*="${slots.frames.listIframeSrcKeyword}"]`).contentFrame();
+  }
+
+  /**
+   * 执行导出工作流并校验下载文件。
+   * @param testInfo Playwright 测试信息，用于生成下载目录
+   * @returns 下载文件信息
+   */
+  async runExportWorkflow(testInfo: TestInfo): Promise<ExportWorkflowResult> {
+    const repoBtn触发导出弹窗 = this.repoIFrame列表页.locator(this.slots.locators.exportButton);
+    await repoBtn触发导出弹窗.click();
+
+    const repoDataExportComponent = new DataExportComponent(this.repoIFrame列表页, this.slots.export.label);
+    const [download] = await Promise.all([
+      this.page.waitForEvent('download', { timeout: 60_000 }),
+      this.triggerExport(repoDataExportComponent),
+    ]);
+
+    const downloadDir = resolveGlueDownloadDir(testInfo.title);
+    fs.mkdirSync(downloadDir, { recursive: true });
+    const filePath = path.join(downloadDir, download.suggestedFilename());
+    await download.saveAs(filePath);
+
+    expect(fs.existsSync(filePath), `文件不存在: ${filePath}`).toBe(true);
+    const stat = fs.statSync(filePath);
+    expect(stat.size, '文件大小为 0').toBeGreaterThan(0);
+    this.assertXlsxFile(filePath);
+
+    log.info(`[导出工作流] 文件已保存到: ${filePath}`);
+    return {
+      filePath,
+      suggestedFilename: download.suggestedFilename(),
+      size: stat.size,
+    };
+  }
+
+  /**
+   * 按导出策略触发导出组件动作。
+   * @param component 数据导出组件
+   */
+  private async triggerExport(component: DataExportComponent): Promise<void> {
+    if (this.slots.export.mode === 'all') {
+      await component.exportAll();
+      return;
+    }
+
+    if (this.slots.export.mode === 'current_page') {
+      await component.exportCurrentPage();
+      return;
+    }
+
+    if (this.slots.export.startPage === undefined || this.slots.export.endPage === undefined) {
+      throw new Error('page_range 导出模式需要提供 startPage 和 endPage');
+    }
+
+    await component.exportByPageRange(this.slots.export.startPage, this.slots.export.endPage);
+  }
+
+  /**
+   * 校验下载文件是 xlsx/OOXML 文件。
+   * @param filePath 下载文件路径
+   */
+  private assertXlsxFile(filePath: string): void {
+    const buffer = Buffer.alloc(4);
+    const fd = fs.openSync(filePath, 'r');
+    fs.readSync(fd, buffer, 0, 4, 0);
+    fs.closeSync(fd);
+    const isXlsx = buffer[0] === 0x50 && buffer[1] === 0x4b && buffer[2] === 0x03 && buffer[3] === 0x04;
+    expect(isXlsx, `文件不是有效 xlsx 格式，实际头字节: ${buffer.toString('hex')}`).toBe(true);
+  }
+}

package/templates/glue/src/skeletons/index.ts

@@ -0,0 +1,18 @@
+export { MenuPage } from './menu.skeleton';
+export { LoginPage } from './login.skeleton';
+export { CrudPage } from './crud.skeleton';
+export { ExportPage } from './export.skeleton';
+export type {
+  CrudDataKeySlot,
+  CrudDataValueStrategy,
+  CrudDeletePolicy,
+  CrudFlowRuntimeData,
+  CrudFlowSlots,
+  CrudInputSearchConditionSlot,
+  CrudListboxSearchConditionSlot,
+  CrudListboxSelectionSlot,
+  CrudSearchConditionRuntimeData,
+  CrudSearchConditionSlot,
+  CrudWorkflowData,
+} from './crud.skeleton';
+export type { ExportFlowSlots, ExportMode, ExportWorkflowResult } from './export.skeleton';