@epoint-testtech/ep-stage-skill 0.0.4-alpha.0 → 0.0.5

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

@@ -6,6 +6,15 @@
  * - 生成调用 LoginPage、MenuPage、CrudPage 的 Playwright 测试文件
  * - 避免直接拼接 page.fill/page.click，保证测试流程复用骨架层
  */
+/**
+ * 生成 stage-skeleton 测试脚本的输入参数。
+ *
+ * @property contract CRUD 业务模块契约
+ * @property directUrl 待测列表页直达链接，登录后由 LoginPage.gotoDirectUrl 打开
+ * @property primaryRole credentials.json5 中的主执行角色
+ * @property requirementName 需求目录名，用于拼接 credentialsPath
+ * @property testName 生成的测试用例名称
+ */
 /**
  * 将字符串渲染为 TypeScript 单引号字面量。
  *
@@ -24,7 +33,11 @@ function singleQuoted(value) {
 function locatorLiteral(value) {
     return JSON.stringify(value);
 }
+// --- 以下为旧 v2 协议（CrudBusinessModuleContract → slots 映射）专用辅助函数 ---
+// 新链路 generateStageSkeletonCrudSpecFromSlots 不再使用这些函数。
+// @deprecated 旧 v2 协议残留，新链路不引用，保留作历史参考，待后续整体清理。
 /**
+ * @deprecated 旧 v2 协议残留，新链路不引用。
  * 为 XPath locator 补齐 Playwright locator 引擎前缀。
  *
  * @param locator 契约中的 locator
@@ -184,6 +197,13 @@ function findBlockedDeleteMessage(contract) {
 /**
  * 将契约中的数据生成策略映射为骨架支持的策略。
  *
+ * 设计取舍：契约把"测试人员定"的策略标成 `human_required`（属于 unresolvedSlots，由 tester 决策）。
+ * 但 spec 组装阶段缺少喂策略的顺滑入口（spec CLI 不收 hints、contract 禁手编），
+ * 若硬抛错会导致测试人员审过用例后仍卡死。
+ * 故 `human_required` / 缺省时统一**默认到 `timestamp_prefix`**——这正是 unresolvedSlots
+ * `suggestedFormat` 自身给出的建议值，也是 CRUD 冒烟造唯一数据的标配；
+ * unresolvedSlots 仍保留作审计标记，测试人员后续可通过 ModuleHints 显式覆盖。
+ *
  * @param strategy 契约数据生成策略
  * @returns 骨架数据生成策略
  */
@@ -192,6 +212,8 @@ function mapDataStrategy(strategy) {
         return 'fixed_value';
     if (strategy === 'timestamp_prefix')
         return 'timestamp_prefix';
+    if (strategy === 'human_required' || strategy === undefined)
+        return 'timestamp_prefix';
     throw new Error(`当前数据生成策略无法自动映射到 CrudFlowSlots: ${strategy}`);
 }
 /**
@@ -313,13 +335,32 @@ function renderOptionalStringProperty(key, value, level) {
     return `${' '.repeat(level)}${key}: ${singleQuoted(value)},\n`;
 }
 function renderListboxSelections(selections, level) {
-    if (!selections || selections.length === 0) {
+    if (!selections) {
         return '';
     }
     const indent = ' '.repeat(level);
+    // 空数组必须显式渲染 `createSelections: [],`，否则 skeleton 走 `condition.createSelections ?? [默认]`
+    // fallback 生成默认 selection，反把不在 add 表单里的字段（如列表页搜索条件"状态"）当作要在
+    // 新增弹框里补选，运行时找不到 trigger 30s timeout。
+    if (selections.length === 0) {
+        return `${indent}createSelections: [],\n`;
+    }
     const itemIndent = ' '.repeat(level + 4);
     const items = selections
-        .map((selection) => `${itemIndent}{ field: ${singleQuoted(selection.field)}, label: ${singleQuoted(selection.label)}, value: ${singleQuoted(selection.value)} }`)
+        .map((selection) => {
+        const parts = [
+            `field: ${singleQuoted(selection.field)}`,
+            `label: ${singleQuoted(selection.label)}`,
+        ];
+        if (selection.value !== undefined)
+            parts.push(`value: ${singleQuoted(selection.value)}`);
+        if (selection.valueStrategy !== undefined)
+            parts.push(`valueStrategy: ${singleQuoted(selection.valueStrategy)}`);
+        if (selection.skipValues && selection.skipValues.length > 0) {
+            parts.push(`skipValues: [${selection.skipValues.map((v) => singleQuoted(v)).join(', ')}]`);
+        }
+        return `${itemIndent}{ ${parts.join(', ')} }`;
+    })
         .join(',\n');
     return `${indent}createSelections: [\n${items},\n${indent}],\n`;
 }
@@ -327,21 +368,35 @@ 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)},
+        const lines = [
+            `${innerIndent}component: 'listbox',`,
+            `${innerIndent}field: ${singleQuoted(condition.field)},`,
+            `${innerIndent}label: ${singleQuoted(condition.label)},`,
+        ];
+        if (condition.value !== undefined) {
+            lines.push(`${innerIndent}value: ${singleQuoted(condition.value)},`);
+        }
+        if (condition.valueStrategy !== undefined) {
+            lines.push(`${innerIndent}valueStrategy: ${singleQuoted(condition.valueStrategy)},`);
+        }
+        if (condition.skipValues && condition.skipValues.length > 0) {
+            lines.push(`${innerIndent}skipValues: [${condition.skipValues.map((v) => singleQuoted(v)).join(', ')}],`);
+        }
+        if (condition.searchAssertion !== undefined) {
+            lines.push(`${innerIndent}searchAssertion: ${singleQuoted(condition.searchAssertion)},`);
+        }
+        return `${indent}{
+${lines.join('\n')}
 ${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)},
+    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) {
@@ -356,30 +411,333 @@ function renderSearchConditions(conditions, level) {
  * @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)}        },
+    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)}        },
     }`;
 }
+function renderChildGridColumns(columns, level) {
+    const indent = ' '.repeat(level);
+    const innerIndent = ' '.repeat(level + 4);
+    const items = columns.map((col) => {
+        const parts = [
+            `field: ${singleQuoted(col.field)}`,
+            `label: ${singleQuoted(col.label)}`,
+            `component: ${singleQuoted(col.component)}`,
+            `required: ${String(col.required)}`,
+        ];
+        if (col.modelRef !== undefined) {
+            parts.push(`modelRef: ${singleQuoted(col.modelRef)}`);
+        }
+        return `${innerIndent}{ ${parts.join(', ')} }`;
+    }).join(',\n');
+    return `${indent}[\n${items},\n${indent}]`;
+}
+function renderChildGridLocators(locators, level) {
+    const indent = ' '.repeat(level);
+    const innerIndent = ' '.repeat(level + 4);
+    const fields = [
+        ['container', locators.container],
+        ['addRowButton', locators.addRowButton],
+        ['deleteSelectedButton', locators.deleteSelectedButton],
+        ['grid', locators.grid],
+        ['editWrapInput', locators.editWrapInput],
+        ['editWrapListboxTrigger', locators.editWrapListboxTrigger],
+        ['editWrapListboxInput', locators.editWrapListboxInput],
+        ['rowCheckboxByIndex', locators.rowCheckboxByIndex],
+        ['cellByIndexAndField', locators.cellByIndexAndField],
+        ['cellValueByIndexAndField', locators.cellValueByIndexAndField],
+    ];
+    const lines = fields.map(([key, value]) => `${innerIndent}${key}: ${locatorLiteral(value)},`).join('\n');
+    return `${indent}{\n${lines}\n${indent}}`;
+}
+/**
+ * 将子表槽位数组渲染为 TypeScript 对象字面量。
+ *
+ * @param slots - 子表槽位数组
+ * @returns TypeScript 源码
+ */
+export function renderChildGridSlots(slots) {
+    if (slots.length === 0)
+        return '[]';
+    const items = slots.map((slot) => `{
+        gridId: ${singleQuoted(slot.gridId)},
+        label: ${singleQuoted(slot.label)},
+        pageRole: ${singleQuoted(slot.pageRole)},
+        editMode: ${singleQuoted(slot.editMode)},
+        columns: ${renderChildGridColumns(slot.columns, 8).trimStart()},
+        locators: ${renderChildGridLocators(slot.locators, 8).trimStart()},
+    }`).join(',\n');
+    return `[\n${items}\n]`;
+}
+/**
+ * 渲染子表行内编辑的填写步骤。
+ *
+ * @param slot 子表槽位
+ * @param valuePrefix 填充值前缀，例如 "测试" / "修改后"
+ * @param indent 语句块缩进空格数，默认 10
+ * @returns 可直接嵌入生成测试源码的语句块
+ */
+function renderChildGridFillSteps(slot, valuePrefix, indent = 10) {
+    const spaces = ' '.repeat(indent);
+    return slot.columns.map((col) => {
+        if (col.component === 'input') {
+            return `${spaces}await childGridPage.editCell(1, ${singleQuoted(col.field)});
+${spaces}await childGridPage.fillInputCell(${singleQuoted(`${valuePrefix}${col.label}`)});`;
+        }
+        return `${spaces}await childGridPage.editCell(1, ${singleQuoted(col.field)});
+${spaces}await childGridPage.selectListboxCell(childGridSlots[0].columns.find((c) => c.field === ${singleQuoted(col.field)})!);`;
+    }).join('\n');
+}
+/**
+ * 渲染子表持久化后的单元格断言步骤。
+ *
+ * @param slot 子表槽位
+ * @param valuePrefix 填充值前缀，用于 input 类型精确匹配
+ * @returns 可直接嵌入生成测试源码的语句块（已含 8 空格缩进）
+ */
+function renderChildGridVerifyAssertions(slot, valuePrefix) {
+    return slot.columns
+        .map((col) => {
+        if (col.component === 'input') {
+            return `        await verifyChildGridPage.assertCellValue(1, ${singleQuoted(col.field)}, ${singleQuoted(`${valuePrefix}${col.label}`)});`;
+        }
+        return `        await verifyChildGridPage.assertCellNotEmpty(1, ${singleQuoted(col.field)});`;
+    })
+        .join('\n');
+}
+/**
+ * 渲染单个子表的新增行测试。
+ */
+function renderChildGridCreateTest(slot, crudSlots, moduleLabel, moduleId) {
+    const label = slot.label;
+    const fillSteps = renderChildGridFillSteps(slot, '测试');
+    const verifyAssertions = renderChildGridVerifyAssertions(slot, '测试');
+    return `  test(${singleQuoted(`${label}-新增行并随主表保存`)}, async ({ page }) => {
+    test.slow();
+
+    await runRecordedWorkflow(
+      recorder,
+      workflowMeta({
+        workflowId: ${singleQuoted(`${moduleId}.childGrid.${slot.gridId}.create`)},
+        workflowKind: 'create',
+        workflowName: ${singleQuoted(`${label}-新增行`)},
+        businessIntent: ${singleQuoted(`在新增${moduleLabel}时维护${label}子表，验证子表数据随主表保存并持久化。`)},
+        elementActions: ['进入新增页', '点击子表新增行', '填写子表单元格', '保存主表', '返回列表搜索并校验子表数据'],
+        assertionExpectation: ${singleQuoted(`保存后重新打开编辑页，${label}子表应显示新增的行数据。`)},
+        playwrightTestTitle: ${singleQuoted(`${label}-新增行并随主表保存`)},
+      }),
+      async () => {
+        await openModule(page);
+        const crudPage = new CrudPage(page, crudSlots);
+        const childWorkflowData = crudPage.prepareWorkflowData();
+        await crudPage.runCreateWorkflowWithChildGrid(childWorkflowData, async (addContext) => {
+          const childGridPage = new ChildGridPage(page, addContext, childGridSlots[0]);
+          await childGridPage.addRow();
+${fillSteps}
+        });
+
+        // 验证子表数据持久化：搜索主记录并重新打开编辑页
+        const editActionLocator = ${locatorLiteral(crudSlots.locators.listEditActionLocatorTemplate)}.replace('{{value}}', childWorkflowData.searchValue);
+        await page.locator(editActionLocator).click();
+        const editFrame = page.locator(\`iframe[src*="${crudSlots.frames.editIframeSrcKeyword}"]\`).contentFrame();
+        const verifyChildGridPage = new ChildGridPage(page, editFrame, childGridSlots[0]);
+${verifyAssertions}
+      },
+    );
+  });`;
+}
+/**
+ * 渲染单个子表的编辑行测试。
+ */
+function renderChildGridUpdateTest(slot, crudSlots, moduleLabel, moduleId) {
+    const label = slot.label;
+    const createFillSteps = renderChildGridFillSteps(slot, '测试');
+    const verifyAssertions = renderChildGridVerifyAssertions(slot, '修改后');
+    return `  test(${singleQuoted(`${label}-编辑行并随主表保存`)}, async ({ page }) => {
+    test.slow();
+
+    await runRecordedWorkflow(
+      recorder,
+      workflowMeta({
+        workflowId: ${singleQuoted(`${moduleId}.childGrid.${slot.gridId}.update`)},
+        workflowKind: 'update',
+        workflowName: ${singleQuoted(`${label}-编辑行`)},
+        businessIntent: ${singleQuoted(`在修改${moduleLabel}时维护${label}子表，验证子表数据随主表保存并持久化。`)},
+        elementActions: ['进入列表页', '创建带窗口信息子表的主记录', '打开编辑页', '修改子表单元格', '保存主表', '重新搜索并校验子表数据'],
+        assertionExpectation: ${singleQuoted(`保存后重新打开编辑页，${label}子表应显示更新后的行数据。`)},
+        playwrightTestTitle: ${singleQuoted(`${label}-编辑行并随主表保存`)},
+      }),
+      async () => {
+        await openModule(page);
+        const crudPage = new CrudPage(page, crudSlots);
+        const childWorkflowData = crudPage.prepareWorkflowData();
+
+        // 前置：创建带${label}子表的主记录
+        await crudPage.runCreateWorkflowWithChildGrid(childWorkflowData, async (addContext) => {
+          const childGridPage = new ChildGridPage(page, addContext, childGridSlots[0]);
+          await childGridPage.addRow();
+${createFillSteps}
+        });
+
+        // 打开编辑页并修改子表行
+        const editActionLocator = ${locatorLiteral(crudSlots.locators.listEditActionLocatorTemplate)}.replace('{{value}}', childWorkflowData.searchValue);
+        await page.locator(editActionLocator).click();
+        const editFrame = page.locator(\`iframe[src*="${crudSlots.frames.editIframeSrcKeyword}"]\`).contentFrame();
+        const childGridPage = new ChildGridPage(page, editFrame, childGridSlots[0]);
+${renderChildGridFillSteps(slot, '修改后', 8)}
+
+        // 保存主表
+        await editFrame.locator(crudSlots.locators.editSaveButton).click();
+
+        // 验证子表数据持久化：重新搜索主记录并打开编辑页
+        const verifyEditActionLocator = ${locatorLiteral(crudSlots.locators.listEditActionLocatorTemplate)}.replace('{{value}}', childWorkflowData.searchValue);
+        await page.locator(verifyEditActionLocator).click();
+        const verifyEditFrame = page.locator(\`iframe[src*="${crudSlots.frames.editIframeSrcKeyword}"]\`).contentFrame();
+        const verifyChildGridPage = new ChildGridPage(page, verifyEditFrame, childGridSlots[0]);
+${verifyAssertions}
+      },
+    );
+  });`;
+}
+/**
+ * 渲染单个子表的删除行测试。
+ *
+ * 注意：本测试会断言删除成功后子表行被真正移除。若系统存在 confirm 确定后仍删除失败的 bug，
+ * 该断言将失败，从而暴露问题，而不是为了绕过 bug 而降低断言标准。
+ */
+function renderChildGridDeleteTest(slot, crudSlots, moduleLabel, moduleId) {
+    const label = slot.label;
+    const createFillSteps = renderChildGridFillSteps(slot, '测试');
+    return `  test(${singleQuoted(`${label}-删除行`)}, async ({ page }) => {
+    test.slow();
+
+    await runRecordedWorkflow(
+      recorder,
+      workflowMeta({
+        workflowId: ${singleQuoted(`${moduleId}.childGrid.${slot.gridId}.delete`)},
+        workflowKind: 'delete',
+        workflowName: ${singleQuoted(`${label}-删除行`)},
+        businessIntent: ${singleQuoted(`验证${moduleLabel}的${label}子表删除选中行后，数据应被真正移除。`)},
+        elementActions: ['进入列表页', '创建带窗口信息子表的主记录', '打开编辑页', '勾选子表行', '点击删除选中', '确认删除', '校验子表行已移除'],
+        assertionExpectation: ${singleQuoted(`确认删除后，${label}子表的数据行数应为 0，被删除的数据不再存在。`)},
+        playwrightTestTitle: ${singleQuoted(`${label}-删除行`)},
+      }),
+      async () => {
+        await openModule(page);
+        const crudPage = new CrudPage(page, crudSlots);
+        const childWorkflowData = crudPage.prepareWorkflowData();
+
+        // 前置：创建带${label}子表的主记录
+        await crudPage.runCreateWorkflowWithChildGrid(childWorkflowData, async (addContext) => {
+          const childGridPage = new ChildGridPage(page, addContext, childGridSlots[0]);
+          await childGridPage.addRow();
+${createFillSteps}
+        });
+
+        // 打开编辑页
+        const editActionLocator = ${locatorLiteral(crudSlots.locators.listEditActionLocatorTemplate)}.replace('{{value}}', childWorkflowData.searchValue);
+        await page.locator(editActionLocator).click();
+        const editFrame = page.locator(\`iframe[src*="${crudSlots.frames.editIframeSrcKeyword}"]\`).contentFrame();
+
+        const childGridPage = new ChildGridPage(page, editFrame, childGridSlots[0]);
+        const confirmPromise = childGridPage.acceptCustomConfirm('确定要删除');
+        await childGridPage.selectRow(1);
+        await childGridPage.deleteSelected();
+
+        await confirmPromise;
+
+        // 断言删除成功：子表数据行数应为 0
+        await page.waitForTimeout(500);
+        await childGridPage.assertRowCount(0);
+      },
+    );
+  });`;
+}
+/**
+ * 渲染单个子表的必填校验测试。
+ */
+function renderChildGridRequiredTest(slot, moduleLabel, moduleId) {
+    const label = slot.label;
+    const requiredFields = slot.columns.filter((c) => c.required);
+    const requiredLabels = requiredFields.map((c) => c.label).join('、');
+    return `  test(${singleQuoted(`${label}-必填校验`)}, async ({ page }) => {
+    test.slow();
+
+    await runRecordedWorkflow(
+      recorder,
+      workflowMeta({
+        workflowId: ${singleQuoted(`${moduleId}.childGrid.${slot.gridId}.required`)},
+        workflowKind: 'create',
+        workflowName: ${singleQuoted(`${label}-必填校验`)},
+        businessIntent: ${singleQuoted(`验证${label}子表必填字段未填写时，主表保存应被阻断并给出校验提示。`)},
+        elementActions: ['进入新增页', '点击子表新增行', '不填必填字段', '保存主表', '观察校验提示'],
+        assertionExpectation: ${singleQuoted(`系统应阻断保存并提示「${requiredLabels}不能为空」。`)},
+        playwrightTestTitle: ${singleQuoted(`${label}-必填校验`)},
+      }),
+      async () => {
+        await openModule(page);
+        const crudPage = new CrudPage(page, crudSlots);
+        const childWorkflowData = crudPage.prepareWorkflowData();
+
+        let alertPromise: Promise<void> | undefined;
+
+        await crudPage.runCreateWorkflowWithChildGridWithoutSearch(childWorkflowData, async (addContext) => {
+          const childGridPage = new ChildGridPage(page, addContext, childGridSlots[0]);
+          alertPromise = childGridPage.assertAlert('不能为空');
+          await childGridPage.addRow();
+        });
+
+        if (!alertPromise) {
+          throw new Error('alertPromise 未初始化');
+        }
+        await alertPromise;
+      },
+    );
+  });`;
+}
+/**
+ * 渲染所有子表测试块（新增行、编辑行、删除行、必填校验）。
+ */
+function renderChildGridTests(slots, crudSlots, moduleLabel, moduleId) {
+    if (slots.length === 0)
+        return '';
+    return slots
+        .flatMap((slot) => {
+        if (slot.editMode === 'none') {
+            return [];
+        }
+        if (slot.editMode === 'row_button_dialog') {
+            return [`  // TODO: ${slot.label} 子表为行按钮弹窗编辑模式，测试待实现`];
+        }
+        return [
+            renderChildGridCreateTest(slot, crudSlots, moduleLabel, moduleId),
+            renderChildGridUpdateTest(slot, crudSlots, moduleLabel, moduleId),
+            renderChildGridDeleteTest(slot, crudSlots, moduleLabel, moduleId),
+            renderChildGridRequiredTest(slot, moduleLabel, moduleId),
+        ];
+    })
+        .join('\n\n');
+}
 /**
  * 渲染导出骨架槽位对象。
  *
@@ -387,38 +745,67 @@ ${renderOptionalStringProperty('blockedDeleteMessage', slots.assertions.blockedD
  * @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,
-        },
+    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,
+        },
+    }`;
+}
+/**
+ * 基于 skeletonSlots.export 槽位渲染导出骨架对象（新协议 fromSlots 入口专用）。
+ *
+ * 与 {@link renderExportSlots} 输出等价的 TypeScript 对象字面量，但消费
+ * `{ moduleId, label, mode }` 三元槽位而非完整 contract。
+ * `frames.listIframeSrcKeyword` 与 crud 槽位共享同一列表页 iframe keyword
+ * （导出动作发生在列表页），由调用方从 crudSlots.frames.listIframeSrcKeyword 传入。
+ *
+ * @param exportSlot contract.scenario.skeletonSlots.export 槽位
+ * @param listIframeSrcKeyword 列表页 iframe keyword（来自 crudSlots.frames.listIframeSrcKeyword）
+ * @returns TypeScript 对象字面量源码
+ */
+function renderExportSlotsFromSlot(exportSlot, listIframeSrcKeyword) {
+    return `{
+        moduleId: ${singleQuoted(exportSlot.moduleId)},
+        frames: {
+            listIframeSrcKeyword: ${singleQuoted(listIframeSrcKeyword)},
+        },
+        locators: {
+            exportButton: '.mini-button.mini-dataexport',
+        },
+        export: {
+            label: ${singleQuoted(exportSlot.label)},
+            mode: ${exportSlot.mode === 'all' ? "'all' as const" : singleQuoted(exportSlot.mode)},
+        },
     }`;
 }
 /**
- * 生成动作级 CRUD + Export Playwright 测试脚本。
+ * 基于 skeletonSlots 槽位生成动作级 CRUD + Export Playwright 测试脚本（新协议 fromSlots 入口）。
+ *
+ * 与 {@link generateStageSkeletonCrudSpec} 输出同构的 spec 模板
+ * （test.describe / recorder / openModule / Create-Read-Update-Delete-Export），
+ * 但所有数据来自入参槽位，**不接收 CrudBusinessModuleContract、不 import 它、
+ * 不调 mapContractToStageSkeletonCrudSlots**。
  *
- * 每个标准工作流（Create / Read / Update / Delete / Export）独立输出为
- * 一个 test case，使用 GlueWorkflowRecorder 记录执行报告。
- * 末尾保留 `// @stage-gap-append` 标记供 gap Custom test 追加。
+ * - crudSlots 直接调 {@link renderStageSkeletonCrudSlots}（复用现有 render）。
+ * - exportSlot 调 {@link renderExportSlotsFromSlot}（listIframeSrcKeyword 取自 crudSlots.frames）。
+ * - deletePolicy 从 crudSlots.assertions.deletePolicy 取（不再从 contract.flows.delete 推）。
  *
- * @param options 生成参数
+ * @param options 生成参数（全部来自 contract.skeletonSlots + testcase 导航/模块信息）
  * @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;
+export function generateStageSkeletonCrudSpecFromSlots(options) {
+    const { moduleId, moduleLabel, directUrl, primaryRole, requirementName, crudSlots, exportSlot, childGridSlots } = options;
     const suiteTitle = `${moduleLabel} CRUD + Export`;
-    const deletePolicy = mapDeletePolicy(contract.flows.delete?.expectedOutcome);
-    const blockedDeleteMessage = deletePolicy === 'blocked_by_business_rule' ? findBlockedDeleteMessage(contract) : undefined;
+    const deletePolicy = crudSlots.assertions.deletePolicy;
+    const blockedDeleteMessage = crudSlots.assertions.blockedDeleteMessage;
     // 删除工作流的业务意图和断言取决于 deletePolicy
     const deleteIntent = deletePolicy === 'blocked_by_business_rule'
         ? `在列表页选择${moduleLabel}记录后点击删除，验证业务规则拦截删除操作${blockedDeleteMessage ? `（${blockedDeleteMessage}）` : ''}。`
@@ -426,182 +813,213 @@ export function generateStageSkeletonCrudSpec(options) {
     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
-});
+    const childGridImport = childGridSlots?.length
+        ? ', ChildGridPage, type ChildGridFlowSlots'
+        : '';
+    return `import { test, expect, type Page } from '@playwright/test';
+import { loadCredentials, StagePath, type Credential } from '@epoint-testtech/stage-core';
+import { CrudPage, ExportPage, LoginPage${childGridImport}, type CrudFlowSlots, type ExportFlowSlots, type CrudWorkflowData } from '../../skeletons';
+import { GlueWorkflowRecorder, runRecordedWorkflow, type GlueWorkflowRecordInput } from '../../report/glue-report';
+
+test.describe(${singleQuoted(suiteTitle)}, () => {
+  const directListUrl = ${singleQuoted(directUrl)};
+  const credentialsPath = \`\${StagePath.projectRootDirPath}/src/tests/${requirementName}/credentials.json5\`;
+  const primaryRole = ${singleQuoted(primaryRole)};
+  const crudSlots: CrudFlowSlots = ${renderStageSkeletonCrudSlots(crudSlots)};
+  const exportSlots = ${renderExportSlotsFromSlot(exportSlot, crudSlots.frames.listIframeSrcKeyword)};
+${childGridSlots?.length ? `  const childGridSlots: ChildGridFlowSlots[] = ${renderChildGridSlots(childGridSlots)};` : ''}
+
+  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();
+  });
+
+  function resolveCredential(role: string): Credential {
+    const [credential] = loadCredentials(credentialsPath, role);
+    if (!credential) {
+      throw new Error(\`credentials.json5 中未找到角色: \${role}\`);
+    }
+    return credential;
+  }
+
+  function applyLoginCredential(credential: Credential): void {
+    process.env.LOGIN_SYSTEM_URL = credential.url;
+    process.env.LOGIN_USERNAME = credential.username;
+    process.env.LOGIN_PASSWORD = credential.password;
+  }
+
+  async function openModule(page: Page): Promise<void> {
+    applyLoginCredential(resolveCredential(primaryRole));
+    const loginPage = new LoginPage(page);
+    await loginPage.login();
+    await loginPage.gotoDirectUrl(directListUrl);
+  }
+
+  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.describe('主表 CRUD 流程', () => {
+    test.describe.configure({ mode: 'serial' });
+    let workflowData: CrudWorkflowData | undefined;
+
+    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);
+      },
+    );
+  });
+
+${childGridSlots?.length ? renderChildGridTests(childGridSlots, crudSlots, moduleLabel, moduleId) : ''}
+
+  // @stage-gap-append
+});
 `;
 }
+/**
+ * @deprecated 旧 v2 协议入口已删除（新链路改用 {@link generateStageSkeletonCrudSpecFromSlots}）。
+ * 原实现接收 CrudBusinessModuleContract 并经 mapContractToStageSkeletonCrudSlots 映射，
+ * 新协议不再依赖 contract 直传，故整段移除。下方保留的 contract→slots 辅助函数
+ * 与 renderExportSlots(contract) 仅为历史参考，新链路不引用。
+ */