@epoint-testtech/ep-stage-skill 0.0.3-alpha.1

package/dist/src/generators/stage-skeleton-script.js

@@ -0,0 +1,607 @@
+/**
+ * stage-skeleton CRUD 骨架脚本生成器。
+ *
+ * 核心职责：
+ * - 将 crud-business-module/v1 契约映射为胶水模板骨架使用的 CrudFlowSlots
+ * - 生成调用 LoginPage、MenuPage、CrudPage 的 Playwright 测试文件
+ * - 避免直接拼接 page.fill/page.click，保证测试流程复用骨架层
+ */
+/**
+ * 将字符串渲染为 TypeScript 单引号字面量。
+ *
+ * @param value 原始字符串
+ * @returns 可直接写入 TypeScript 源码的单引号字符串
+ */
+function singleQuoted(value) {
+    return `'${value.replaceAll('\\', '\\\\').replaceAll("'", "\\'")}'`;
+}
+/**
+ * 将 locator 渲染为 TypeScript 字符串字面量。
+ *
+ * @param value locator 字符串
+ * @returns 可直接写入 TypeScript 源码的字符串
+ */
+function locatorLiteral(value) {
+    return JSON.stringify(value);
+}
+/**
+ * 为 XPath locator 补齐 Playwright locator 引擎前缀。
+ *
+ * @param locator 契约中的 locator
+ * @returns 可传给 Playwright locator 的表达式
+ */
+function toPlaywrightLocator(locator) {
+    if (locator.startsWith('xpath=') || locator.startsWith('css=')) {
+        return locator;
+    }
+    if (locator.startsWith('//') || locator.startsWith('(')) {
+        return `xpath=${locator}`;
+    }
+    return locator;
+}
+/**
+ * 优先使用契约中的 locator，缺失时再退回骨架默认 locator。
+ *
+ * @param control 流程控件契约
+ * @param fallbackLocator 骨架回退 locator
+ * @returns 最终用于骨架脚本的 locator
+ */
+function resolveControlLocator(control, fallbackLocator) {
+    if (control?.locator) {
+        return toPlaywrightLocator(control.locator);
+    }
+    return fallbackLocator;
+}
+/**
+ * 优先使用字段契约中已有的 locator，缺失时再按字段类型推导。
+ *
+ * @param field 字段契约
+ * @returns 最终用于骨架脚本的字段 locator
+ */
+function resolveFieldLocator(field) {
+    if (field.locator) {
+        return toPlaywrightLocator(field.locator);
+    }
+    return toMiniInputLocator(field);
+}
+/**
+ * 将页面字段转换为 zwplace mini 输入框定位。
+ *
+ * @param field 字段契约
+ * @returns 适配 stage-skeleton 骨架的输入框 locator
+ */
+function toMiniInputLocator(field) {
+    if (field.controlType === 'mini-textbox') {
+        return `xpath=//div[@label=${singleQuoted(field.label)}]//input[@class='mini-textbox-input']`;
+    }
+    if (field.locator) {
+        return toPlaywrightLocator(field.locator);
+    }
+    return `xpath=//div[@label=${singleQuoted(field.label)}]//input`;
+}
+/**
+ * 将按钮标签转换为 zwplace mini 按钮定位。
+ *
+ * @param label 按钮中文文本
+ * @returns 按钮 locator
+ */
+function buttonLocatorByLabel(label) {
+    return `xpath=//span[contains(normalize-space(),${singleQuoted(label)})]`;
+}
+/**
+ * 将保存按钮标签转换为精确文本定位。
+ *
+ * @param label 按钮中文文本
+ * @returns 保存按钮 locator
+ */
+function exactButtonLocatorByLabel(label) {
+    return `xpath=//span[normalize-space()=${singleQuoted(label)}]`;
+}
+/**
+ * 生成 iframe src 关键字。
+ *
+ * @param pageId 页面 ID
+ * @param shouldAppendHtml 是否补齐 .html 后缀
+ * @returns iframe src 关键字
+ */
+function iframeKeyword(pageId, shouldAppendHtml = false) {
+    if (!pageId)
+        return '';
+    if (shouldAppendHtml && !pageId.endsWith('.html')) {
+        return `${pageId}.html`;
+    }
+    return pageId;
+}
+/**
+ * 将结果表格 ID 转为 XPath 根节点。
+ *
+ * @param gridId 表格 ID
+ * @returns XPath 根路径
+ */
+function gridRootXPath(gridId) {
+    return `//*[@id='${gridId}']`;
+}
+/**
+ * 将 contract 中的行操作 locator 嵌入到目标行模板中。
+ *
+ * @param locator 行操作 locator
+ * @returns 可拼接到行模板后的相对 XPath
+ */
+function toRowActionRelativeXPath(locator) {
+    if (!locator) {
+        return "//i[@data-tooltip='修改']";
+    }
+    const rawLocator = locator.replace(/^xpath=/, '');
+    if (rawLocator.startsWith('.//')) {
+        return rawLocator.slice(1);
+    }
+    if (rawLocator.startsWith('//')) {
+        return rawLocator;
+    }
+    if (rawLocator.startsWith('/')) {
+        return `/${rawLocator.replace(/^\/+/, '')}`;
+    }
+    return `//${rawLocator}`;
+}
+/**
+ * 获取契约中的字段定义。
+ *
+ * @param fields 字段列表
+ * @param fieldName 字段名
+ * @param roleName 页面角色说明，用于错误消息
+ * @returns 匹配的字段契约
+ * @throws 当字段不存在时抛出异常，避免生成不可执行的骨架代码
+ */
+function requireField(fields, fieldName, roleName) {
+    const field = fields?.find((item) => item.name === fieldName);
+    if (!field) {
+        throw new Error(`无法在${roleName}中找到字段: ${fieldName}`);
+    }
+    return field;
+}
+/**
+ * 将契约中的删除结果映射为骨架支持的删除策略。
+ *
+ * @param outcome 契约删除预期
+ * @returns 骨架删除策略
+ * @throws 当删除策略仍需要人工确认时抛出异常
+ */
+function mapDeletePolicy(outcome) {
+    if (outcome === 'success_delete' || outcome === 'blocked_by_business_rule') {
+        return outcome;
+    }
+    throw new Error(`当前删除策略无法自动映射到 CrudFlowSlots: ${outcome ?? 'undefined'}`);
+}
+/**
+ * 查找删除被阻塞时的提示消息。
+ *
+ * @param contract CRUD 业务模块契约
+ * @returns 删除阻塞提示消息
+ */
+function findBlockedDeleteMessage(contract) {
+    return contract.assertions.find((assertion) => assertion.type === 'toast_message' && assertion.expectedMessage.includes('不可删除'))?.expectedMessage;
+}
+/**
+ * 将契约中的数据生成策略映射为骨架支持的策略。
+ *
+ * @param strategy 契约数据生成策略
+ * @returns 骨架数据生成策略
+ */
+function mapDataStrategy(strategy) {
+    if (strategy === 'fixed_value')
+        return 'fixed_value';
+    if (strategy === 'timestamp_prefix')
+        return 'timestamp_prefix';
+    throw new Error(`当前数据生成策略无法自动映射到 CrudFlowSlots: ${strategy}`);
+}
+/**
+ * 从 create.overrideFields 中读取数据主键种子值。
+ *
+ * @param contract CRUD 业务模块契约
+ * @returns 数据主键种子值
+ */
+function resolveSeedValue(contract) {
+    const dataKeyOverride = contract.flows.create?.overrideFields.find((field) => field.field === contract.dataKey.field);
+    return dataKeyOverride?.value ?? `自动化测试${contract.dataKey.label}`;
+}
+function resolveConditionSeedValue(contract, condition) {
+    const override = contract.flows.create?.overrideFields.find((field) => field.field === condition.field);
+    return condition.seedValue ?? override?.value ?? `自动化测试${condition.label}`;
+}
+function requireSearchConditions(contract) {
+    if (contract.searchConditions && contract.searchConditions.length > 0) {
+        return contract.searchConditions;
+    }
+    return [{
+            field: contract.dataKey.field,
+            label: contract.dataKey.label,
+            component: 'input',
+            seedValue: resolveSeedValue(contract),
+            generationStrategy: contract.dataKey.generationStrategy,
+            updatePrefix: '修改',
+            sources: contract.dataKey.sources
+        }];
+}
+function mapSearchConditions(contract) {
+    return requireSearchConditions(contract).map((condition) => {
+        if (condition.component === 'listbox') {
+            if (!condition.value) {
+                throw new Error(`listbox 搜索条件 ${condition.field} 缺少测试值，请在 ModuleHints.searchConditions 中补充 value`);
+            }
+            return {
+                component: 'listbox',
+                field: condition.field,
+                label: condition.label,
+                value: condition.value,
+                createSelections: condition.createSelections,
+            };
+        }
+        const addField = requireField(contract.pages.add?.fields, condition.field, '新增页');
+        const editField = requireField(contract.pages.edit?.fields, condition.field, '修改页');
+        const listField = requireField(contract.pages.list.fields, condition.field, '列表页');
+        return {
+            component: 'input',
+            field: condition.field,
+            label: condition.label,
+            seedValue: resolveConditionSeedValue(contract, condition),
+            strategy: mapDataStrategy(condition.generationStrategy ?? contract.dataKey.generationStrategy),
+            updatePrefix: condition.updatePrefix ?? '修改',
+            addLocator: resolveFieldLocator(addField),
+            editLocator: resolveFieldLocator(editField),
+            listLocator: resolveFieldLocator(listField),
+        };
+    });
+}
+/**
+ * 将 CRUD 业务模块契约映射为 stage-skeleton 的 CrudFlowSlots。
+ *
+ * @param contract CRUD 业务模块契约
+ * @returns 可传给 CrudPage 的槽位对象
+ * @throws 当关键页面、字段或策略缺失时抛出异常
+ */
+export function mapContractToStageSkeletonCrudSlots(contract) {
+    const createFlow = contract.flows.create;
+    const searchFlow = contract.flows.search;
+    const updateFlow = contract.flows.update;
+    const deleteFlow = contract.flows.delete;
+    if (!createFlow || !searchFlow || !updateFlow || !deleteFlow) {
+        throw new Error('生成 stage-skeleton 骨架前，contract 必须包含完整的 create/search/update/delete flows');
+    }
+    const deletePolicy = mapDeletePolicy(deleteFlow.expectedOutcome);
+    const blockedDeleteMessage = deletePolicy === 'blocked_by_business_rule' ? findBlockedDeleteMessage(contract) : undefined;
+    const resultGridId = searchFlow.resultGrid;
+    if (deletePolicy === 'blocked_by_business_rule' && !blockedDeleteMessage) {
+        throw new Error('删除策略为 blocked_by_business_rule 时，必须能从契约断言中解析 blockedDeleteMessage');
+    }
+    return {
+        moduleId: contract.module.id,
+        searchConditions: mapSearchConditions(contract),
+        frames: {
+            listIframeSrcKeyword: iframeKeyword(contract.pages.list.iframeSrcKeyword, true),
+            addIframeSrcKeyword: iframeKeyword(contract.pages.add?.iframeSrcKeyword),
+            editIframeSrcKeyword: iframeKeyword(contract.pages.edit?.iframeSrcKeyword),
+        },
+        locators: {
+            createButton: resolveControlLocator(createFlow.entryButton, buttonLocatorByLabel(createFlow.entryButton.label ?? '新增')),
+            addAutofillTrigger: "xpath=//*[@title='默认填充']",
+            addSaveButton: resolveControlLocator(createFlow.saveButton, exactButtonLocatorByLabel(createFlow.saveButton.label ?? '保存并关闭')),
+            listSearchSubmit: resolveControlLocator(searchFlow.submitControl, "xpath=//span[text()='搜索']"),
+            listResultValueLocatorTemplate: `xpath=${gridRootXPath(resultGridId)}//div[text()='{{value}}']`,
+            listEditActionLocatorTemplate: `xpath=${gridRootXPath(resultGridId)}//tr[.//div[text()='{{value}}']]${toRowActionRelativeXPath(updateFlow.entryAction.locator)}`,
+            editSaveButton: resolveControlLocator(updateFlow.saveButton, exactButtonLocatorByLabel(updateFlow.saveButton.label ?? '保存并关闭')),
+            listRowSelectLocatorTemplate: `xpath=${gridRootXPath(resultGridId)}//div[text()='{{value}}']`,
+            listDeleteButton: resolveControlLocator(deleteFlow.entryButton, buttonLocatorByLabel(deleteFlow.entryButton.label ?? '删除选定')),
+            deleteConfirmButton: resolveControlLocator(deleteFlow.confirmControl, 'text=确定'),
+        },
+        assertions: {
+            deletePolicy,
+            blockedDeleteMessage,
+        },
+    };
+}
+/**
+ * 渲染对象中的可选字符串属性。
+ *
+ * @param key 属性名
+ * @param value 属性值
+ * @param level 缩进层级
+ * @returns 属性源码行，值不存在时返回空字符串
+ */
+function renderOptionalStringProperty(key, value, level) {
+    if (value === undefined)
+        return '';
+    return `${' '.repeat(level)}${key}: ${singleQuoted(value)},\n`;
+}
+function renderListboxSelections(selections, level) {
+    if (!selections || selections.length === 0) {
+        return '';
+    }
+    const indent = ' '.repeat(level);
+    const itemIndent = ' '.repeat(level + 4);
+    const items = selections
+        .map((selection) => `${itemIndent}{ field: ${singleQuoted(selection.field)}, label: ${singleQuoted(selection.label)}, value: ${singleQuoted(selection.value)} }`)
+        .join(',\n');
+    return `${indent}createSelections: [\n${items},\n${indent}],\n`;
+}
+function renderSearchCondition(condition, level) {
+    const indent = ' '.repeat(level);
+    const innerIndent = ' '.repeat(level + 4);
+    if (condition.component === 'listbox') {
+        return `${indent}{
+${innerIndent}component: 'listbox',
+${innerIndent}field: ${singleQuoted(condition.field)},
+${innerIndent}label: ${singleQuoted(condition.label)},
+${innerIndent}value: ${singleQuoted(condition.value)},
+${renderListboxSelections(condition.createSelections, level + 4)}${indent}}`;
+    }
+    return `${indent}{
+${innerIndent}component: 'input',
+${innerIndent}field: ${singleQuoted(condition.field)},
+${innerIndent}label: ${singleQuoted(condition.label)},
+${innerIndent}seedValue: ${singleQuoted(condition.seedValue)},
+${renderOptionalStringProperty('strategy', condition.strategy, level + 4)}${renderOptionalStringProperty('fixedValue', condition.fixedValue, level + 4)}${renderOptionalStringProperty('updatePrefix', condition.updatePrefix, level + 4)}${renderOptionalStringProperty('searchSeedValue', condition.searchSeedValue, level + 4)}${innerIndent}addLocator: ${locatorLiteral(condition.addLocator)},
+${innerIndent}editLocator: ${locatorLiteral(condition.editLocator)},
+${innerIndent}listLocator: ${locatorLiteral(condition.listLocator)},
+${indent}}`;
+}
+function renderSearchConditions(conditions, level) {
+    const indent = ' '.repeat(level);
+    const items = conditions.map((condition) => renderSearchCondition(condition, level + 4)).join(',\n');
+    return `${indent}searchConditions: [\n${items},\n${indent}],`;
+}
+/**
+ * 将 CrudFlowSlots 渲染为 TypeScript 对象字面量。
+ *
+ * @param slots CRUD 骨架槽位
+ * @returns TypeScript 对象源码
+ */
+export function renderStageSkeletonCrudSlots(slots) {
+    return `{
+        moduleId: ${singleQuoted(slots.moduleId)},
+${renderSearchConditions(slots.searchConditions, 8)}
+        frames: {
+            listIframeSrcKeyword: ${singleQuoted(slots.frames.listIframeSrcKeyword)},
+            addIframeSrcKeyword: ${singleQuoted(slots.frames.addIframeSrcKeyword)},
+            editIframeSrcKeyword: ${singleQuoted(slots.frames.editIframeSrcKeyword)},
+        },
+        locators: {
+            createButton: ${locatorLiteral(slots.locators.createButton)},
+${renderOptionalStringProperty('addAutofillTrigger', slots.locators.addAutofillTrigger, 12)}
+            addSaveButton: ${locatorLiteral(slots.locators.addSaveButton)},
+            listSearchSubmit: ${locatorLiteral(slots.locators.listSearchSubmit)},
+            listResultValueLocatorTemplate: ${locatorLiteral(slots.locators.listResultValueLocatorTemplate)},
+            listEditActionLocatorTemplate: ${locatorLiteral(slots.locators.listEditActionLocatorTemplate)},
+            editSaveButton: ${locatorLiteral(slots.locators.editSaveButton)},
+            listRowSelectLocatorTemplate: ${locatorLiteral(slots.locators.listRowSelectLocatorTemplate)},
+            listDeleteButton: ${locatorLiteral(slots.locators.listDeleteButton)},
+${renderOptionalStringProperty('deleteConfirmButton', slots.locators.deleteConfirmButton, 12)}        },
+        assertions: {
+            deletePolicy: ${singleQuoted(slots.assertions.deletePolicy)},
+${renderOptionalStringProperty('blockedDeleteMessage', slots.assertions.blockedDeleteMessage, 12)}        },
+    }`;
+}
+/**
+ * 渲染导出骨架槽位对象。
+ *
+ * @param contract CRUD 业务模块契约
+ * @returns TypeScript 对象字面量源码
+ */
+function renderExportSlots(contract) {
+    return `{
+        moduleId: ${singleQuoted(contract.module.id)},
+        frames: {
+            listIframeSrcKeyword: ${singleQuoted(iframeKeyword(contract.pages.list.iframeSrcKeyword, true))},
+        },
+        locators: {
+            exportButton: '.mini-button.mini-dataexport',
+        },
+        export: {
+            label: '导出',
+            mode: 'all' as const,
+        },
+    }`;
+}
+/**
+ * 生成动作级 CRUD + Export Playwright 测试脚本。
+ *
+ * 每个标准工作流（Create / Read / Update / Delete / Export）独立输出为
+ * 一个 test case，使用 GlueWorkflowRecorder 记录执行报告。
+ * 末尾保留 `// @stage-gap-append` 标记供 gap Custom test 追加。
+ *
+ * @param options 生成参数
+ * @returns 完整的 `.spec.ts` 源码
+ */
+export function generateStageSkeletonCrudSpec(options) {
+    const { contract, menuNavigation } = options;
+    const slots = mapContractToStageSkeletonCrudSlots(contract);
+    const moduleId = contract.module.id;
+    const moduleLabel = contract.module.label;
+    const suiteTitle = `${moduleLabel} CRUD + Export`;
+    const deletePolicy = mapDeletePolicy(contract.flows.delete?.expectedOutcome);
+    const blockedDeleteMessage = deletePolicy === 'blocked_by_business_rule' ? findBlockedDeleteMessage(contract) : undefined;
+    // 删除工作流的业务意图和断言取决于 deletePolicy
+    const deleteIntent = deletePolicy === 'blocked_by_business_rule'
+        ? `在列表页选择${moduleLabel}记录后点击删除，验证业务规则拦截删除操作${blockedDeleteMessage ? `（${blockedDeleteMessage}）` : ''}。`
+        : `在列表页选择${moduleLabel}记录后点击删除并确认，验证列表中不再存在该记录。`;
+    const deleteAssertion = deletePolicy === 'blocked_by_business_rule'
+        ? `删除操作应被业务规则拦截${blockedDeleteMessage ? `，提示「${blockedDeleteMessage}」` : ''}，列表保留该记录。`
+        : '删除成功后，列表中不再存在该记录，搜索结果为空。';
+    return `import { test, expect, type Page } from '@playwright/test';
+import { StagePath } from '@epoint-testtech/stage-core';
+import { CrudPage, ExportPage, LoginPage, MenuPage, type CrudFlowSlots, type ExportFlowSlots, type CrudWorkflowData } from '../skeletons';
+import { GlueWorkflowRecorder, runRecordedWorkflow, type GlueWorkflowRecordInput } from '../report/glue-report';
+
+test.describe(${singleQuoted(suiteTitle)}, () => {
+  const menuRoute = ${singleQuoted(menuNavigation)};
+  const crudSlots: CrudFlowSlots = ${renderStageSkeletonCrudSlots(slots)};
+  const exportSlots = ${renderExportSlots(contract)};
+
+  test.describe.configure({ mode: 'serial' });
+  let workflowData: CrudWorkflowData | undefined;
+
+  const recorder = new GlueWorkflowRecorder({
+    outputRoot: StagePath.projectRootDirPath,
+    moduleId: ${singleQuoted(moduleId)},
+    moduleName: ${singleQuoted(moduleLabel)},
+    suiteTitle: ${singleQuoted(suiteTitle)},
+    generatedSpecFile: import.meta.url,
+  });
+
+  test.beforeAll(async ({ browser }) => {
+    recorder.updateEnvironment({
+      browserName: browser.browserType().name(),
+      browserVersion: browser.version(),
+    });
+  });
+
+  test.afterAll(() => {
+    recorder.writeReport();
+  });
+
+  async function openModule(page: Page): Promise<void> {
+    const loginPage = new LoginPage(page);
+    const menuPage = new MenuPage(page);
+    await loginPage.login();
+    await menuPage.navigateToMenu(menuRoute);
+  }
+
+  function workflowMeta(
+    input: Omit<
+      GlueWorkflowRecordInput,
+      'moduleId' | 'executionSource' | 'evidenceSources' | 'evidenceRefs' | 'playwrightSuiteTitle'
+    >,
+  ): GlueWorkflowRecordInput {
+    return {
+      moduleId: ${singleQuoted(moduleId)},
+      executionSource: 'glue_code' as const,
+      evidenceSources: ['crud_flow_slots'],
+      evidenceRefs: [],
+      playwrightSuiteTitle: ${singleQuoted(suiteTitle)},
+      ...input,
+    };
+  }
+
+  test('Create：新增${moduleLabel}并校验列表存在对应记录', async ({ page }) => {
+    test.slow();
+
+    await runRecordedWorkflow(
+      recorder,
+      workflowMeta({
+        workflowId: ${singleQuoted(`${moduleId}.create`)},
+        workflowKind: 'create',
+        workflowName: '新增${moduleLabel}',
+        businessIntent: '在列表页点击新增按钮，填写表单并保存，验证列表中存在新增的记录。',
+        elementActions: ['点击列表页新增按钮打开新增弹框', '在新增弹框中填写表单字段', '点击保存并关闭提交表单', '在列表页搜索并验证记录存在'],
+        assertionExpectation: '新增成功后，列表页应能通过搜索找到刚新增的记录。',
+        playwrightTestTitle: 'Create：新增${moduleLabel}并校验列表存在对应记录',
+      }),
+      async () => {
+        await openModule(page);
+        const crudPage = new CrudPage(page, crudSlots);
+        workflowData = crudPage.prepareWorkflowData();
+        await crudPage.runCreateWorkflow(workflowData);
+      },
+    );
+  });
+
+  test('Read：搜索${moduleLabel}并校验搜索结果', async ({ page }) => {
+    test.slow();
+
+    await runRecordedWorkflow(
+      recorder,
+      workflowMeta({
+        workflowId: ${singleQuoted(`${moduleId}.read`)},
+        workflowKind: 'read',
+        workflowName: '搜索${moduleLabel}',
+        businessIntent: '使用搜索条件查询记录，验证搜索结果与搜索条件匹配。',
+        elementActions: ['在搜索区域填写搜索条件', '点击搜索按钮提交查询', '在结果列表中校验搜索结果'],
+        assertionExpectation: '搜索结果列表中应包含符合搜索条件的记录。',
+        playwrightTestTitle: 'Read：搜索${moduleLabel}并校验搜索结果',
+      }),
+      async () => {
+        await openModule(page);
+        if (!workflowData) {
+          throw new Error('Read 工作流依赖 Create 工作流先行生成 workflowData');
+        }
+        const crudPage = new CrudPage(page, crudSlots);
+        await crudPage.runReadWorkflow(workflowData);
+      },
+    );
+  });
+
+  test('Update：修改${moduleLabel}并校验修改结果', async ({ page }) => {
+    test.slow();
+
+    await runRecordedWorkflow(
+      recorder,
+      workflowMeta({
+        workflowId: ${singleQuoted(`${moduleId}.update`)},
+        workflowKind: 'update',
+        workflowName: '修改${moduleLabel}',
+        businessIntent: '定位目标记录行，点击修改按钮进入编辑弹框，修改字段后保存，验证修改生效。',
+        elementActions: ['在列表中定位目标记录行', '点击行操作中的修改按钮打开编辑弹框', '修改表单字段', '点击保存并关闭提交修改'],
+        assertionExpectation: '修改成功后，列表页应显示修改后的字段值。',
+        playwrightTestTitle: 'Update：修改${moduleLabel}并校验修改结果',
+      }),
+      async () => {
+        await openModule(page);
+        if (!workflowData) {
+          throw new Error('Update 工作流依赖 Create 工作流先行生成 workflowData');
+        }
+        const crudPage = new CrudPage(page, crudSlots);
+        await crudPage.runUpdateWorkflow(workflowData);
+      },
+    );
+  });
+
+  test('Delete：删除${moduleLabel}并校验${deletePolicy === 'blocked_by_business_rule' ? '业务规则拦截' : '删除结果'}', async ({ page }) => {
+    test.slow();
+
+    await runRecordedWorkflow(
+      recorder,
+      workflowMeta({
+        workflowId: ${singleQuoted(`${moduleId}.delete`)},
+        workflowKind: 'delete',
+        workflowName: '删除${moduleLabel}',
+        businessIntent: ${singleQuoted(deleteIntent)},
+        elementActions: ['在列表中选择目标记录', '点击删除按钮触发删除确认', ${deletePolicy === 'blocked_by_business_rule' ? "'确认删除操作并验证拦截提示'" : "'确认删除操作'"}],
+        assertionExpectation: ${singleQuoted(deleteAssertion)},
+        playwrightTestTitle: 'Delete：删除${moduleLabel}并校验${deletePolicy === 'blocked_by_business_rule' ? '业务规则拦截' : '删除结果'}',
+      }),
+      async () => {
+        await openModule(page);
+        if (!workflowData) {
+          throw new Error('Delete 工作流依赖 Create 工作流先行生成 workflowData');
+        }
+        const crudPage = new CrudPage(page, crudSlots);
+        await crudPage.runDeleteWorkflow(workflowData);
+      },
+    );
+  });
+
+  test('Export：导出${moduleLabel}列表并校验下载文件', async ({ page }, testInfo) => {
+    test.slow();
+
+    await runRecordedWorkflow(
+      recorder,
+      workflowMeta({
+        workflowId: ${singleQuoted(`${moduleId}.export`)},
+        workflowKind: 'export',
+        workflowName: '导出${moduleLabel}列表',
+        businessIntent: '在列表页触发全部导出，验证导出弹框可驱动并成功下载数据文件。',
+        elementActions: ['点击列表页数据导出按钮打开导出弹框', '在导出弹框选择「全部」并确认导出', '等待 download 事件并断言下载文件存在且非空'],
+        assertionExpectation: '导出操作应触发下载，落盘文件存在且大小大于 0。',
+        playwrightTestTitle: 'Export：导出${moduleLabel}列表并校验下载文件',
+      }),
+      async () => {
+        await openModule(page);
+        const exportPage = new ExportPage(page, exportSlots);
+        await exportPage.runExportWorkflow(testInfo);
+      },
+    );
+  });
+
+  // @stage-gap-append
+});
+`;
+}

package/dist/src/index.d.ts

@@ -0,0 +1,52 @@
+export type { AssertionContract, BusinessRuleContract, ButtonContract, Confidence, CreateFlowContract, CrudBusinessModuleContract, DataKeyContract, DeleteExpectedOutcome, DeleteFlowContract, DialogContract, EvidenceKind, EvidenceRef, FieldContract, FlowControlRef, GridActionContract, GridColumnContract, GridContract, ModuleHints, ModuleIdentity, OverrideFieldContract, PageContract, PageRole, RecordExistenceAssertionContract, SearchFlowContract, SearchConditionContract, SlotAvailability, SlotResolution, SourceKind, SourceRef, ToastMessageAssertionContract, UnresolvedSlot, UpdateFlowContract } from './contracts/crud-business-module.js';
+export { extractHtmlPage } from './extractors/html-page.js';
+export type { ExtractedHtmlButton, ExtractedHtmlDialog, ExtractedHtmlField, ExtractedHtmlGrid, ExtractedHtmlGridColumn, ExtractedHtmlRowAction, ExtractedHtmlPage } from './extractors/html-page.js';
+export { extractSpecYaml } from './extractors/spec-yaml.js';
+export type { ExtractedSpecBusinessRule, ExtractedSpecField, ExtractedSpecYaml } from './extractors/spec-yaml.js';
+export { extractCodeListSummary } from './extractors/code-list.js';
+export type { ExtractedCodeListSummary } from './extractors/code-list.js';
+export { extractJavaAction } from './extractors/java-action.js';
+export type { ExtractedJavaAction } from './extractors/java-action.js';
+export { buildCrudBusinessModuleContract } from './normalizers/crud-contract.js';
+export type { BuildCrudContractInput, ButtonLabelConfig } from './normalizers/crud-contract.js';
+export { generateStageSkeletonCrudSpec, mapContractToStageSkeletonCrudSlots, renderStageSkeletonCrudSlots } from './generators/stage-skeleton-script.js';
+export type { StageSkeletonCrudDataValueStrategy, StageSkeletonCrudDeletePolicy, StageSkeletonCrudFlowSlots, StageSkeletonScriptOptions } from './generators/stage-skeleton-script.js';
+export type { ActionCandidate, AgentInferredWorkflow, GapActionType, GapExplorationResult, GapInferDraft, GapListItem, GapSignalType, GapWorkflowStatus, SkeletonCoverage } from './contracts/gap-inference.js';
+export type { ObservableArtifactRef, ObservableGate, ObservableStageName, ObservableStagePayload, ObservableStageSummary, ReasoningEvidence, ReasoningSummary, TraceWriterOptions } from './contracts/observable-chain.js';
+export { createTraceWriter, } from './trace/trace-writer.js';
+export type { TraceWriter, } from './trace/trace-writer.js';
+export { readStageContext, resolveStageContext, writeProjectIndex, } from './context/stage-context.js';
+export type { ProjectIndex, ProjectIndexEntry, ResolveStageContextInput, ResolveStageContextResult, StageContext, StageContextMode, } from './context/stage-context.js';
+export { renderReviewSummary, } from './trace/review-summary.js';
+export type { ReviewSummaryInput, } from './trace/review-summary.js';
+export { collectActionCandidates, } from './gap-planner/action-candidates.js';
+export { createSkeletonCoverage, } from './gap-planner/skeleton-coverage.js';
+export { stableActionHash, stableActionId, stableWorkflowId, } from './gap-planner/stable-id.js';
+export { planAgentInferredWorkflows, } from './gap-planner/plan-agent-workflows.js';
+export { listGapWorkflows, } from './gap-planner/list-gap-workflows.js';
+export { appendAgentWorkflowTest, renderAgentWorkflowTest, } from './generators/agent-inferred-workflow-script.js';
+export { resolveMaterialInventory, } from './material/material-inventory.js';
+export type { MaterialResolution, ResolvedMaterialInventory, ResolveMaterialInventoryInput, ResolveMaterialInventoryResult, ValueResolution, } from './material/material-inventory.js';
+export { summarizePageStructure, } from './capability/page-structure.js';
+export type { PageStructureSummary, } from './capability/page-structure.js';
+export type { ExtractedPageStructureSignal, ExtractedPageStructureSignals, } from './extractors/html-page.js';
+export { applyScenarioHumanCorrection, inferPageScenarios, } from './capability/scenario-inference.js';
+export type { InferPageScenariosInput, } from './capability/scenario-inference.js';
+export type { PageScenario, ScenarioCandidate, ScenarioInferenceTrace, } from './contracts/observable-chain.js';
+export { createCoverageDiff, } from './capability/coverage-diff.js';
+export type { CreateCoverageDiffInput, } from './capability/coverage-diff.js';
+export type { CoverageDiffAction, CoverageDiffTrace, NestedCrudCandidateTrace, } from './contracts/observable-chain.js';
+export { generateGlueTestcases, } from './testcase/testcase-generator.js';
+export type { GenerateGlueTestcasesInput, GenerateGlueTestcasesOutput, } from './testcase/testcase-generator.js';
+export { mapContractToCrudTestcaseSlots, renderGlueTestcaseSkeleton, selectTestcaseSkeletonByScenario, } from './testcase/testcase-skeleton.js';
+export { validateGlueTestcaseDocumentForSpecAssembly, } from './testcase/testcase-spec-assembly.js';
+export type { CrudTestcaseSlots, MapContractToCrudTestcaseSlotsInput, TestcaseSkeletonSelection, } from './testcase/testcase-skeleton.js';
+export type { GlueTestcase, GlueTestcaseDocument, } from './contracts/observable-chain.js';
+export { applyCodeListWriteBack, collectCodeListMaterialRefsFromPath, isProtectedKnowledgeProjectPath, parseObservablePipelineArgs, resolveMenuRouteForPipeline, } from './cli/run-gap-pipeline.js';
+export type { CodeListWriteBackInput, InteractiveCodeListSupplements, InteractiveSupplementResult, ObservablePipelineArgs, } from './cli/run-gap-pipeline.js';
+export { createRuntimeFailureSummary, extractLoginSystemUrlFromEnvFile, parseRuntimeSummaryOutput, runtimeSummaryToTrace, } from './cli/run-gap-pipeline.js';
+export { glueReportToTrace, glueSpecAssemblyToTrace, playwrightExecutionToTrace, } from './cli/run-gap-pipeline.js';
+export type { GlueReportSummary, GlueSpecAssemblySummary, PlaywrightExecutionSummary, } from './cli/run-gap-pipeline.js';
+export { compareObservableRuns, summarizeGeneralizationRun, } from './generalization/generalization-eval.js';
+export type { GeneralizationComparison, GeneralizationRunMetrics, MaterialResolutionStatus, SummarizeGeneralizationRunInput, } from './generalization/generalization-eval.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}