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

package/dist/src/testcase/contract-testcase-assembler.js

@@ -0,0 +1,806 @@
+/**
+ * JSON5 新协议产线的 contract + testcase 装配器（Task 3）。
+ *
+ * 职责：
+ * 把 {@link ExtractedCodeListJson5}（code_list.json5 解析产出）装配成
+ * - {@link EpStageContractV1Draft}：含 scenario.skeletonSlots.crud（形态对齐
+ *   generators/stage-skeleton-script.ts 的 StageSkeletonCrudFlowSlots）
+ * - {@link EpStageTestcaseV1Draft}：10 条 glue cases + uncoveredCandidates
+ *
+ * 填充策略（brief + 交接文档 §4.2）：
+ * - queryFields：input/listbox 二分；input 取 entities 中 dataKey 字段作 seed 来源
+ *   （placename 为 dataKey），listbox 取第一项作 value
+ * - frames：code_list 不提供 iframe keyword → 用模块名相关 keyword 占位（014 为 directUrl 模式），
+ *   默认策略，不进 unresolvedSlots，在 inference-trace 记账
+ * - locators：用 014 草案已确认的框架默认（MiniUI 默认规则 + text=确定 等），不进 unresolvedSlots
+ * - assertions.deletePolicy='success_delete'（MiniUI 默认删除成功策略）
+ */
+import { extractHtmlPage } from '../extractors/html-page.js';
+import { inferButtonInteractions, } from './button-interaction-inference.js';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+/**
+ * 框架默认 locator 策略（014 草案已确认，交接文档 §4.2）。
+ * 这些值不进 unresolvedSlots，在 inference-trace 记账「框架默认」。
+ */
+const DEFAULT_LOCATORS = {
+    createButton: 'button:has-text("新增")',
+    addAutofillTrigger: 'button:has-text("自动填充")',
+    addSaveButton: 'button:has-text("保存并关闭")',
+    listSearchSubmit: 'button:has-text("查询")',
+    listResultValueLocatorTemplate: 'table >> tbody >> tr >> td >> nth=0',
+    listEditActionLocatorTemplate: 'button:has-text("修改")',
+    editSaveButton: 'button:has-text("保存并关闭")',
+    listRowSelectLocatorTemplate: 'table >> tbody >> tr >> input[type="checkbox"]',
+    listDeleteButton: 'button:has-text("删除")',
+    deleteConfirmButton: 'text=确定',
+};
+/**
+ * 用 code_list.pages[list].buttons / rowActions 的真实中文 label 生成精准 xpath locator，
+ * 覆盖 MiniUI mini-button + mini-datagrid 的稳定定位；找不到对应按钮时回退到中文默认。
+ *
+ * xpath 模式对齐 MVP `e2e/glue-code-mvp/src/tests/014-测试需求10-20260622/test-crud-example.spec.ts`
+ * 里已在真实系统验证跑通的样板：
+ * `xpath=//a[contains(@class,'mini-button')][normalize-space()='<label>']`。
+ *
+ * gridId 目前固定 'datagrid'（MVP 与 code_list 现网均如此，后续可扩展从
+ * code_list.pages[list].dataGrid.id 提取）。
+ *
+ * @param listPage - code_list.pages[role=list]。
+ * @returns 覆盖 StageSkeletonCrudFlowSlots.locators 全部字段的定位表达式。
+ */
+function buildCrudLocators(listPage) {
+    const gridId = 'datagrid';
+    const createLabel = listPage.buttons?.find((b) => b.action === 'create')?.label ?? '新增';
+    const deleteLabel = listPage.buttons?.find((b) => b.action === 'delete')?.label ?? '删除选定';
+    const editLabel = listPage.rowActions?.find((r) => {
+        const anyRow = r;
+        return anyRow.action === 'edit' || anyRow.actionName === 'openEdit' || anyRow.label === '修改';
+    })?.label ?? '修改';
+    const miniButton = (label) => `xpath=//a[contains(@class,'mini-button')][normalize-space()='${label}']`;
+    const gridCell = `xpath=//*[@id='${gridId}']//div[text()='{{value}}']`;
+    return {
+        createButton: miniButton(createLabel),
+        addAutofillTrigger: `xpath=//*[@title='默认填充']`,
+        addSaveButton: miniButton('保存并关闭'),
+        listSearchSubmit: `xpath=//span[text()='搜索']`,
+        listResultValueLocatorTemplate: gridCell,
+        listEditActionLocatorTemplate: `xpath=//*[@id='${gridId}']//tr[.//div[text()='{{value}}']]//i[@data-tooltip='${editLabel}']`,
+        editSaveButton: miniButton('保存并关闭'),
+        listRowSelectLocatorTemplate: gridCell,
+        listDeleteButton: miniButton(deleteLabel),
+        deleteConfirmButton: 'text=确定',
+    };
+}
+/**
+ * 从 code_list.pages[role=list/add/edit].pageId 提取 iframe src keyword。
+ *
+ * MVP 样板：list 加 .html 后缀（列表页 URL 直接指向 .html），add/edit 不加（是 modal
+ * iframe，src 带 query 参数），三者均含 `gxhzw` 前缀等真实业务 pageId。
+ * 若某 role 缺失 pageId，回退到 `<module><role>` 占位。
+ */
+function resolveFrameKeywords(codeList) {
+    const module = codeList.module;
+    const listPageId = codeList.pages.find((p) => p.role === 'list')?.pageId;
+    const addPageId = codeList.pages.find((p) => p.role === 'add')?.pageId;
+    const editPageId = codeList.pages.find((p) => p.role === 'edit')?.pageId;
+    return {
+        listIframeSrcKeyword: listPageId ? `${listPageId}.html` : `${module}list`,
+        addIframeSrcKeyword: addPageId ?? `${module}add`,
+        editIframeSrcKeyword: editPageId ?? `${module}edit`,
+    };
+}
+/**
+ * 从 code_list 的 entities 推断某 field 是否是 dataKey（业务主键，作 seed 来源）。
+ *
+ * @param codeList - 解析后的 code_list。
+ * @param field - 字段名。
+ * @returns 是否 dataKey。
+ */
+function isDataKeyField(codeList, field) {
+    return (codeList.entities ?? []).some((e) => (e.fields ?? []).some((f) => f.name === field && f.dataKey));
+}
+/**
+ * 选择并返回可用的源码根目录。
+ *
+ * 优先级：sourceRootOverride -> process.env.EP_STAGE_SOURCE_ROOT -> codeList.sourceRoot.root
+ */
+function resolveSourceRoot(codeList, sourceRootOverride) {
+    const candidates = [
+        sourceRootOverride,
+        process.env.EP_STAGE_SOURCE_ROOT,
+        codeList.sourceRoot?.root,
+    ].filter((item) => Boolean(item));
+    return candidates[0];
+}
+/**
+ * 解析页面 HTML 文件绝对路径。
+ */
+function resolvePageHtmlPath(codeList, page, sourceRootOverride) {
+    const sourceRoot = resolveSourceRoot(codeList, sourceRootOverride);
+    if (!sourceRoot || !page.path)
+        return undefined;
+    return path.resolve(sourceRoot, page.path);
+}
+/**
+ * 解析 pages[*].childGrids 中的 same_as_pages.<role>.childGrids 引用。
+ */
+function resolveChildGrids(page, pages) {
+    const raw = page.childGrids;
+    if (!raw || !Array.isArray(raw) || raw.length === 0)
+        return undefined;
+    if (raw.every((item) => typeof item === 'string')) {
+        const resolved = [];
+        for (const ref of raw) {
+            const match = ref.match(/^same_as_pages\.([^.]+)\.childGrids$/);
+            if (!match)
+                continue;
+            const role = match[1];
+            const targetPage = pages.find((p) => p.role === role);
+            if (!targetPage)
+                continue;
+            const targetGrids = resolveChildGrids(targetPage, pages);
+            if (targetGrids)
+                resolved.push(...targetGrids);
+        }
+        return resolved.length > 0 ? resolved : undefined;
+    }
+    return raw;
+}
+/**
+ * 将 HTML 中提取的子表列 editor.type 映射为 skeleton 组件类型。
+ * 缺失或未知时默认 input，避免上游 HTML 不规范时直接阻塞整条产线。
+ */
+function mapEditorTypeToComponent(editorType) {
+    if (editorType === 'combobox')
+        return 'listbox';
+    return 'input';
+}
+/**
+ * 构建子表操作所需的定位表达式。
+ */
+function buildChildGridLocators(grid, addAction, deleteAction) {
+    const label = grid.label;
+    const gridId = grid.id;
+    const buttonLocator = (action, defaultLabel) => {
+        const buttonLabel = action?.label ?? defaultLabel;
+        return `xpath=//div[@label='${label}']//a[contains(@class,'mini-button')][normalize-space()='${buttonLabel}']`;
+    };
+    return {
+        container: `xpath=//div[@label='${label}']`,
+        addRowButton: buttonLocator(addAction, '添加'),
+        deleteSelectedButton: buttonLocator(deleteAction, '删除选中'),
+        grid: `#${gridId}`,
+        editWrapInput: '.mini-grid-editwrap input.mini-textbox-input',
+        editWrapListboxTrigger: '.mini-grid-editwrap .mini-buttonedit-trigger',
+        editWrapListboxInput: '.mini-grid-editwrap input.mini-buttonedit-input',
+        rowCheckboxByIndex: `xpath=//*[@id='${gridId}']//tr[contains(@class,'mini-grid-row')][{{rowIndex}}]//td[contains(@class,'checkcolumn')]//span`,
+        cellByIndexAndField: `xpath=//*[@id='${gridId}']//tr[contains(@class,'mini-grid-row')][{{rowIndex}}]//td[{{colIndex}}]`,
+        cellValueByIndexAndField: `xpath=//*[@id='${gridId}']//tr[contains(@class,'mini-grid-row')][{{rowIndex}}]//td[{{colIndex}}]//div[contains(@class,'mini-grid-cell-inner')]`,
+    };
+}
+/**
+ * 推断子表操作方式。
+ * 优先级：code_list 显式 editMode > HTML 信号（allowCellEdit / editor 列） > 默认 none。
+ */
+function inferChildGridEditMode(grid, htmlGrid) {
+    if (grid.editMode) {
+        return grid.editMode;
+    }
+    if (!htmlGrid) {
+        // HTML 不可用时，根据 code_list 已有信息保守回退：
+        // 只要声明了列组件或动作，就默认按 cell_edit 处理，保持与旧行为兼容。
+        const hasEditableColumn = grid.columns.some((c) => c.component === 'input' || c.component === 'listbox');
+        return hasEditableColumn || (grid.actions && grid.actions.length > 0) ? 'cell_edit' : 'none';
+    }
+    const hasCellEditSignal = htmlGrid.allowCellEdit === true ||
+        htmlGrid.cellEditAction != null ||
+        htmlGrid.allowCellSelect === true ||
+        htmlGrid.editNextOnEnterKey === true ||
+        htmlGrid.oncellbeginedit === true ||
+        htmlGrid.onrowdblclick === true;
+    const hasEditableColumn = htmlGrid.dataColumns.some((c) => Boolean(c.editorType));
+    if (hasCellEditSignal || hasEditableColumn) {
+        return 'cell_edit';
+    }
+    const hasRowEditSignal = htmlGrid.rowActions.some((a) => /openEdit|openDetail|openWindow|edit/i.test(a.onclick ?? a.label)) || htmlGrid.onrowdblclick === true;
+    if (hasRowEditSignal) {
+        return 'row_button_dialog';
+    }
+    return 'none';
+}
+/**
+ * 从 code_list 的 pages[].childGrids 构建 contract.skeletonSlots.childGrids。
+ *
+ * 设计取舍：
+ * - 优先使用 code_list 中已手写的 component；缺失时读取对应 HTML 的 editor.type 推导。
+ * - 对 same_as_pages.<role>.childGrids 引用进行解析。
+ * - 同一 gridId 在多个页面出现时只保留第一份（通常是 add 页）。
+ */
+function buildChildGridSlots(codeList, sourceRootOverride) {
+    const pagesWithChildGrids = codeList.pages.filter((p) => Boolean(p.childGrids));
+    if (pagesWithChildGrids.length === 0)
+        return undefined;
+    const slots = [];
+    const seenGridIds = new Set();
+    const extractedPageCache = new Map();
+    for (const page of pagesWithChildGrids) {
+        const childGrids = resolveChildGrids(page, codeList.pages);
+        if (!childGrids)
+            continue;
+        let htmlPage;
+        const htmlPath = resolvePageHtmlPath(codeList, page, sourceRootOverride);
+        if (htmlPath && existsSync(htmlPath)) {
+            try {
+                if (!extractedPageCache.has(htmlPath)) {
+                    extractedPageCache.set(htmlPath, extractHtmlPage(htmlPath));
+                }
+                htmlPage = extractedPageCache.get(htmlPath);
+            }
+            catch {
+                htmlPage = undefined;
+            }
+        }
+        for (const grid of childGrids) {
+            if (seenGridIds.has(grid.id))
+                continue;
+            seenGridIds.add(grid.id);
+            const htmlGrid = htmlPage?.grids.find((g) => g.id === grid.id);
+            const columns = grid.columns.map((col) => {
+                const htmlColumn = htmlGrid?.dataColumns.find((c) => c.field === col.field);
+                const component = col.component ?? mapEditorTypeToComponent(htmlColumn?.editorType);
+                return {
+                    field: col.field,
+                    label: col.label,
+                    component,
+                    required: col.required ?? false,
+                    modelRef: col.modelRef ?? htmlColumn?.editorAction,
+                };
+            });
+            const addAction = grid.actions?.find((a) => a.actionName === 'addWindow' || a.label.includes('添加')) ?? grid.actions?.[0];
+            const deleteAction = grid.actions?.find((a) => a.actionName === 'deleteSelectedWindow' || a.label.includes('删除')) ?? grid.actions?.[1];
+            const editMode = inferChildGridEditMode(grid, htmlGrid);
+            slots.push({
+                gridId: grid.id,
+                label: grid.label,
+                pageRole: page.role === 'edit' ? 'edit' : 'add',
+                editMode,
+                columns,
+                addRowButtonLabel: addAction?.label,
+                deleteSelectedButtonLabel: deleteAction?.label,
+                locators: buildChildGridLocators(grid, addAction, deleteAction),
+            });
+        }
+    }
+    return slots.length > 0 ? slots : undefined;
+}
+/**
+ * 把 list 页 queryFields 映射成 skeletonSlots.crud.searchConditions（input/listbox 二分）。
+ *
+ * @param codeList - 解析后的 code_list。
+ * @param listPage - 列表页 page item。
+ * @returns 对齐 StageSkeletonCrudSearchConditionSlot 的槽位数组。
+ */
+function buildSearchConditionSlots(codeList, listPage, addOrEditPage) {
+    const addFormLabels = new Set((addOrEditPage?.formFields ?? [])
+        .filter((f) => typeof f !== 'string')
+        .map((f) => f.label));
+    return (listPage.queryFields ?? []).map((fieldInfo) => {
+        const field = mapQueryFieldToField(fieldInfo);
+        const component = normalizeQueryComponent(fieldInfo);
+        if (component === 'input') {
+            // MiniUI mini-textbox 的 name 属性通常是 `dataBean.<field>` 或省略；只有 label 属性稳定。
+            // 用 label 定位 outer div (mini-textbox 容器)，再取内部 input.mini-textbox-input。
+            const miniTextboxByLabel = `xpath=//div[@label='${fieldInfo.label}']//input[@class='mini-textbox-input']`;
+            return {
+                component: 'input',
+                field,
+                label: fieldInfo.label,
+                seedValue: isDataKeyField(codeList, field) ? '{{timestamp}}-测试' : '测试数据',
+                strategy: 'timestamp_prefix',
+                addLocator: miniTextboxByLabel,
+                editLocator: miniTextboxByLabel,
+                listLocator: miniTextboxByLabel,
+            };
+        }
+        // listbox：真实下拉值来自 dataOptions 字典 (运行时才能确认)，assembler 不猜值；
+        // 用 skeleton 支持的 valueStrategy=first_non_placeholder + skipValues=['请选择'] 让运行时
+        // 选首个有效项。searchAssertion='none' 表示 Read 工作流不对 listbox 校验命中数（因为选到
+        // 的值未必对应先前 Create 用的分类，仅校验搜索链路可驱动）。
+        // createSelections 仅当该字段同时存在于 add/edit 页 formFields 时才补选；否则为空数组，
+        // 避免运行时在新增弹框里找不到该 label 的 mini-listbox 触发器 (如"状态" 是列表页搜索条件
+        // 但不在 add 表单里)。
+        const fieldInAddForm = addFormLabels.has(fieldInfo.label);
+        return {
+            component: 'listbox',
+            field,
+            label: fieldInfo.label,
+            valueStrategy: 'first_non_placeholder',
+            skipValues: ['请选择'],
+            searchAssertion: 'none',
+            createSelections: fieldInAddForm
+                ? [
+                    {
+                        field,
+                        label: fieldInfo.label,
+                        valueStrategy: 'first_non_placeholder',
+                        skipValues: ['请选择'],
+                    },
+                ]
+                : [],
+        };
+    });
+}
+/**
+ * 把 code_list 中文 label 映射到契约 field（kebab-ish 英文）。
+ * 014 已确认三字段：placename / placecategory / status。
+ */
+function mapLabelToField(label) {
+    const map = {
+        场所名称: 'placename',
+        场所分类: 'placecategory',
+        状态: 'status',
+    };
+    return map[label] ?? label;
+}
+/**
+ * 从 queryFields 条目推导字段名，优先使用 bind 的 dataBean.xxx。
+ */
+function mapQueryFieldToField(fieldInfo) {
+    const bindMatch = fieldInfo.bind?.match(/dataBean\.([A-Za-z0-9_]+)/);
+    return bindMatch?.[1] ?? mapLabelToField(fieldInfo.label);
+}
+/**
+ * 归一化 queryFields 的组件类型，支持上游摘要用 component=mini-textbox/mini-combobox。
+ */
+function normalizeQueryComponent(fieldInfo) {
+    const raw = fieldInfo.type ?? fieldInfo.component ?? '';
+    if (raw === 'input' || raw === 'mini-textbox')
+        return 'input';
+    return 'listbox';
+}
+/**
+ * 生成正式用例编号。
+ *
+ * @param pageIndex - 待测页面序号，从 1 开始。
+ * @param caseIndex - 页面内用例序号，从 1 开始。
+ * @returns TC + 两位页面序号 + 三位用例序号。
+ */
+function formatCaseId(pageIndex, caseIndex) {
+    return `TC${String(pageIndex).padStart(2, '0')}${String(caseIndex).padStart(3, '0')}`;
+}
+/**
+ * 从编号上下文中取下一个正式用例编号。
+ *
+ * @param sequence - 编号上下文。
+ * @returns 下一个 caseId。
+ */
+function nextCaseId(sequence) {
+    const caseId = formatCaseId(sequence.pageIndex, sequence.nextCaseIndex);
+    sequence.nextCaseIndex += 1;
+    return caseId;
+}
+/**
+ * 根据用例标题选择查询主键标签。
+ *
+ * @param title - 用例标题。
+ * @param searchFieldLabels - 列表页查询字段标签集合。
+ * @param dataKeyLabel - dataKey 对应的中文标签。
+ * @returns testcase.json5.queryKey。
+ */
+function pickQueryKeyLabel(label, searchFieldLabels, dataKeyLabel) {
+    return searchFieldLabels.find((item) => item === label) ?? dataKeyLabel ?? searchFieldLabels[0] ?? '不适用';
+}
+/**
+ * 生成 glue 用例执行字段。
+ *
+ * @param actionKind - CRUD / Export 动作类型。
+ * @param queryKey - 当前用例查询主键。
+ * @param searchFieldLabels - 列表页查询字段标签集合。
+ * @param dataKeyLabel - dataKey 对应的中文标签。
+ * @returns testcase 执行字段。
+ */
+function buildGlueExecutionFields(actionKind, queryKeyLabel, queryComponent, queryKeyInForm, searchFieldLabels, dataKeyLabel) {
+    const queryKey = actionKind === 'export'
+        ? pickQueryKeyLabel(dataKeyLabel ?? searchFieldLabels[0] ?? '不适用', searchFieldLabels, dataKeyLabel)
+        : pickQueryKeyLabel(queryKeyLabel, searchFieldLabels, dataKeyLabel);
+    const smokeEntry = '1. 完成系统登录并进入目标待测页面。';
+    const createQueryKeyStep = queryComponent === 'listbox'
+        ? `3. 在${queryKey}字段选择首个有效下拉选项（跳过“请选择”）。`
+        : `3. 将${queryKey}字段填写为带时间戳的测试值。`;
+    const updateQueryKeyStep = queryComponent === 'listbox'
+        ? `3. 在编辑表单中修改可编辑字段；若需要修改${queryKey}，选择另一个有效下拉选项。`
+        : `3. 在编辑表单中修改可编辑字段；若${queryKey}可编辑，则写入新的带时间戳测试值。`;
+    if (actionKind === 'create') {
+        return {
+            queryKey,
+            precondition: smokeEntry,
+            steps: [
+                '1. 点击{{新增按钮}}。',
+                '2. 在弹出的新增表单中填写必填字段。',
+                createQueryKeyStep,
+                '4. 点击{{保存按钮}}完成新增。',
+            ].join(' '),
+            assertion: `保存后返回{{列表页}}；使用${queryKey}搜索新增时填写的数据，列表应只返回一条匹配记录。`,
+        };
+    }
+    if (actionKind === 'read') {
+        if (!queryKeyInForm) {
+            return {
+                queryKey,
+                precondition: smokeEntry,
+                steps: [
+                    `1. 在列表页${queryKey}查询条件中输入或选择一个有效查询值。`,
+                    '2. 点击{{查询按钮}}。',
+                ].join(' '),
+                assertion: '查询动作应完成，列表刷新或查询请求被触发；本用例不强制断言列表数据命中数量。',
+            };
+        }
+        return {
+            queryKey,
+            precondition: `${smokeEntry} 2. 已基于${queryKey}完成一条测试数据新增。`,
+            steps: [
+                `1. 在列表页${queryKey}查询条件中输入或选择前置数据的查询值。`,
+                '2. 点击{{查询按钮}}。',
+            ].join(' '),
+            assertion: `列表应只返回一条匹配记录，且记录的${queryKey}值与前置数据一致。`,
+        };
+    }
+    if (actionKind === 'update') {
+        return {
+            queryKey,
+            precondition: `${smokeEntry} 2. 已基于${queryKey}完成一条测试数据新增。`,
+            steps: [
+                `1. 在列表页按${queryKey}搜索前置数据。`,
+                '2. 定位搜索结果中的目标记录并点击{{修改按钮}}。',
+                updateQueryKeyStep,
+                '4. 点击{{保存按钮}}完成修改。',
+            ].join(' '),
+            assertion: `修改后返回{{列表页}}；使用修改后的${queryKey}或可断言字段重新查询，列表应只返回一条匹配记录。`,
+        };
+    }
+    if (actionKind === 'delete') {
+        return {
+            queryKey,
+            precondition: `${smokeEntry} 2. 已基于${queryKey}完成一条测试数据新增。`,
+            steps: [
+                `1. 在列表页按${queryKey}搜索前置数据。`,
+                '2. 勾选搜索结果中的目标记录。',
+                '3. 点击{{删除按钮}}。',
+                '4. 在确认弹窗中点击{{确认按钮}}。',
+            ].join(' '),
+            assertion: `删除后再次按${queryKey}搜索该数据，列表应无匹配记录。`,
+        };
+    }
+    return {
+        queryKey,
+        precondition: smokeEntry,
+        steps: [
+            '1. 在列表页点击{{导出按钮}}。',
+            '2. 在导出弹窗中选择导出范围。',
+            '3. 点击弹窗中的{{导出确认按钮}}。',
+        ].join(' '),
+        assertion: '系统应触发导出流程；若当前环境可观测下载结果，则校验导出文件生成，否则校验导出弹窗或导出请求已被触发。',
+    };
+}
+/**
+ * 装配 10 条 glue cases（placename/placecategory 各 CRUD + status.read + export.all），
+ * 与交接文档 §4.3 一致。
+ *
+ * @param moduleId - 模块标识（用作 caseId 前缀）。
+ * @param searchFieldLabels - 列表页查询字段标签集合。
+ * @param dataKeyLabel - dataKey 对应的中文标签。
+ * @returns cases 数组（generationStrategy 全 glue）。
+ */
+function buildGlueCases(moduleName, searchFields, formFieldLabels, sequence, dataKeyLabel) {
+    const searchFieldLabels = searchFields.map((fieldInfo) => fieldInfo.label);
+    const componentForLabel = (label) => searchFields.find((fieldInfo) => fieldInfo.label === label)?.component ?? 'input';
+    const queryKeyInForm = (label) => formFieldLabels.includes(label);
+    const mk = (actionKind, queryKeyLabel, coverageStatus) => ({
+        caseId: nextCaseId(sequence),
+        title: actionKind === 'export'
+            ? `${moduleName} export`
+            : `${moduleName} ${actionKind}（${queryKeyLabel}）`,
+        generationStrategy: 'glue',
+        coverageStatus,
+        reviewStatus: 'confirmed',
+        ...buildGlueExecutionFields(actionKind, queryKeyLabel, componentForLabel(queryKeyLabel), queryKeyInForm(queryKeyLabel), searchFieldLabels, dataKeyLabel),
+    });
+    return [
+        mk('create', '场所名称', 'covered'),
+        mk('read', '场所名称', 'covered'),
+        mk('update', '场所名称', 'covered'),
+        mk('delete', '场所名称', 'covered'),
+        mk('create', '场所分类', 'covered'),
+        mk('read', '场所分类', 'partial'),
+        mk('update', '场所分类', 'covered'),
+        mk('delete', '场所分类', 'covered'),
+        mk('read', '状态', 'partial'),
+        mk('export', dataKeyLabel ?? searchFieldLabels[0] ?? '不适用', 'covered'),
+    ];
+}
+/**
+ * 为子表（childGrids）装配 glue cases。
+ *
+ * 每个子表生成 4 条用例：新增行、编辑行、删除行、必填校验。
+ * 删除行标记为 gap：子表行删除通常依赖 confirm 弹窗与后端接口，运行态稳定性差，
+ * 需要真实环境验证后才能提升为 covered。
+ *
+ * @param childGrids - 子表槽位清单。
+ * @param firstRole - 首个角色（用作前置条件）。
+ * @param sequence - 用例编号上下文。
+ * @returns cases 数组（generationStrategy 全 glue）。
+ */
+function buildChildGridCases(childGrids, firstRole, sequence) {
+    const smokeEntry = `1. 使用角色：${firstRole}。 2. 完成系统登录并进入目标新增页面。`;
+    return childGrids.flatMap((grid) => {
+        const label = grid.label;
+        const addRowButtonLabel = grid.addRowButtonLabel ?? '添加';
+        const deleteSelectedButtonLabel = grid.deleteSelectedButtonLabel ?? '删除选中';
+        const requiredColumns = grid.columns.filter((c) => c.required);
+        const requiredLabels = requiredColumns.map((c) => c.label).join('、') || '必填字段';
+        const allColumnLabels = grid.columns.map((c) => c.label).join('、');
+        const canAddRow = Boolean(grid.addRowButtonLabel);
+        const canDeleteRow = Boolean(grid.deleteSelectedButtonLabel);
+        const canEditCell = grid.editMode === 'cell_edit';
+        const hasRequiredColumn = requiredColumns.length > 0;
+        const mk = (title, coverageStatus, precondition, steps, assertion) => ({
+            caseId: nextCaseId(sequence),
+            title,
+            generationStrategy: 'glue',
+            coverageStatus,
+            reviewStatus: 'confirmed',
+            queryKey: '不适用',
+            precondition,
+            steps,
+            assertion,
+        });
+        const cases = [];
+        if (canAddRow) {
+            cases.push(mk(`${label}-新增行`, 'covered', smokeEntry, `1. 在新增页定位到「${label}」子表。 2. 点击子表工具栏的「${addRowButtonLabel}」按钮。 3. 在新增行中填写 ${allColumnLabels} 等字段。 4. 点击主表「保存并关闭」。 5. 观察保存结果。`, `保存后主表成功提交，子表新增数据随主表持久化；重新打开详情或编辑页可看到新增的行。`));
+        }
+        if (canEditCell) {
+            cases.push(mk(`${label}-编辑行`, 'covered', `${smokeEntry} 3. 子表中已存在至少一行数据。`, `1. 在新增页定位到「${label}」子表。 2. 选中或双击待编辑行进入编辑状态。 3. 修改 ${allColumnLabels} 等字段。 4. 点击主表「保存并关闭」。 5. 观察保存结果。`, `保存后子表修改内容持久化；重新打开详情或编辑页可看到更新后的值。`));
+        }
+        if (canDeleteRow) {
+            cases.push(mk(`${label}-删除行`, 'covered', `${smokeEntry} 3. 子表中已存在至少一行数据。`, `1. 在新增页定位到「${label}」子表。 2. 勾选要删除的数据行。 3. 点击子表工具栏的「${deleteSelectedButtonLabel}」按钮。 4. 在确认弹窗中点击「确定」。 5. 观察并记录最终反馈。`, `点击「${deleteSelectedButtonLabel}」并确认后，子表对应行应被删除；重新加载页面后该行数据不再存在。`));
+        }
+        if (canEditCell && hasRequiredColumn) {
+            cases.push(mk(`${label}-必填校验`, 'covered', smokeEntry, `1. 在新增页点击「${addRowButtonLabel}」新增一行。 2. 将 ${requiredLabels} 留空或选择空值。 3. 点击主表「保存并关闭」。 4. 观察校验提示。`, `保存时系统应阻断提交并提示「第N行${requiredLabels}不能为空！」等校验信息。`));
+        }
+        return cases;
+    });
+}
+/**
+ * 把 contract.scenario.gapCandidates 映射为 testcase.uncoveredCandidates。
+ * 当前仅处理控件类 custom 按钮，按 code_list 中真实的 label / customAction / backendMethod
+ * 生成精确步骤、前置条件与断言；若 button-interaction-inference 成功识别交互模式，
+ * 则使用对应的精确步骤/断言，否则回退到通用描述。
+ *
+ * @param gapCandidates - contract 中已推导的控件类 gap 候选。
+ * @param firstRole - 首个角色（用作 requiredRole）。
+ * @param sequence - 用例编号上下文。
+ * @param codeList - 解析后的 code_list，用于反查按钮原始元数据。
+ * @param buttonInferences - 按钮交互推理结果映射（label -> inference）。
+ */
+function buildUncoveredCandidates(gapCandidates, firstRole, sequence, codeList, buttonInferences) {
+    const listPage = codeList.pages.find((p) => p.role === 'list');
+    return gapCandidates.map((candidate) => {
+        // 从 code_list.pages[list].buttons 中反查该 custom 按钮的元数据。
+        const btn = (listPage?.buttons ?? []).find((b) => {
+            const anyB = b;
+            return anyB.action === 'custom'
+                && (anyB.label === candidate.label || anyB.customAction === candidate.gapId);
+        });
+        const label = btn?.label ?? candidate.label;
+        const customAction = btn?.customAction ?? candidate.gapId;
+        // 优先使用前端行为推理结果；若不可用则回退到通用描述。
+        const inference = buttonInferences.get(label);
+        const steps = inference?.steps ?? [
+            `1. 在列表页定位并点击「${label}」按钮。`,
+            `2. 观察并记录页面反馈（如弹窗、提示信息、列表刷新等）。`,
+            `3. 确认页面状态与按钮功能预期一致。`,
+        ].join(' ');
+        const assertion = inference?.assertion
+            ?? `点击「${label}」按钮后，页面应出现与该功能对应的可见响应（如提示信息、弹窗确认或数据刷新）。`;
+        return {
+            caseId: nextCaseId(sequence),
+            label,
+            generationStrategy: 'ai',
+            coverageStatus: 'gap',
+            requiredRole: firstRole,
+            businessIntent: `覆盖列表页「${label}」按钮的控件功能（customAction=${customAction}）。`,
+            assertionExpectation: assertion,
+            queryKey: '不适用',
+            precondition: `1. 使用角色：${firstRole}。 2. 完成系统登录并进入目标待测页面。`,
+            steps,
+            assertion,
+        };
+    });
+}
+/**
+ * 按 code_list 里的系统与角色事实生成 testcase.testAccess 占位。
+ *
+ * @param codeList - 解析后的 code_list。
+ * @returns testcase.testAccess 占位；明文账号密码只进入 credentials.json5，不进入 testcase。
+ */
+function buildTestAccess(codeList) {
+    return {
+        credentialRef: 'credentials.json5',
+        requiredRoles: listRequiredRoles(codeList),
+    };
+}
+/**
+ * 从 code_list 提取用例需要的角色清单。
+ *
+ * @param codeList - 解析后的 code_list。
+ * @returns 非空角色名数组。
+ */
+function listRequiredRoles(codeList) {
+    const roles = codeList.roles.length > 0
+        ? codeList.roles.map((role) => role.role || role.label || '业务角色待确认')
+        : codeList.requirement?.businessRoles?.length
+            ? codeList.requirement.businessRoles.map((role) => role.label)
+            : (codeList.testAccess?.systems ?? []).flatMap((system) => system.roles.map((role) => role.role || '业务角色待确认'));
+    return roles.length > 0 ? roles : ['业务角色待确认'];
+}
+/**
+ * 解析待测列表页直达地址。
+ *
+ * @param input - 装配器输入。
+ * @param listPage - 列表页物料。
+ * @returns directUrl 或 undefined。
+ */
+function resolveDirectUrl(input, listPage) {
+    return input.directUrl ?? listPage.directUrl;
+}
+/**
+ * 装配 contract + testcase + inference-trace 账本。
+ *
+ * @param input - 含 code_list 解析产出的输入。
+ * @returns contract / testcase / inferenceTrace。
+ */
+export function assembleJson5ContractAndTestcase(input) {
+    const { codeList } = input;
+    const module = codeList.module;
+    const moduleName = codeList.moduleName;
+    const listPage = codeList.pages.find((p) => p.role === 'list');
+    if (!listPage) {
+        throw new Error('code_list.json5 缺少 role=list 的列表页');
+    }
+    const firstRole = codeList.requirement?.businessRoles?.[0]?.label ??
+        codeList.roles[0]?.label ??
+        codeList.roles[0]?.role ??
+        '业务角色待确认';
+    const directUrl = resolveDirectUrl(input, listPage);
+    const searchFields = (listPage.queryFields ?? []).map((fieldInfo) => ({
+        field: mapQueryFieldToField(fieldInfo),
+        label: fieldInfo.label,
+        component: normalizeQueryComponent(fieldInfo),
+    }));
+    const searchFieldLabels = searchFields.map((fieldInfo) => fieldInfo.label);
+    const addOrEditPage = codeList.pages.find((p) => p.role === 'add') ?? codeList.pages.find((p) => p.role === 'edit');
+    const formFieldLabels = (addOrEditPage?.formFields ?? [])
+        .filter((fieldInfo) => typeof fieldInfo !== 'string')
+        .map((fieldInfo) => fieldInfo.label);
+    const dataKeyLabel = (listPage.queryFields ?? []).find((fieldInfo) => {
+        const field = mapQueryFieldToField(fieldInfo);
+        return isDataKeyField(codeList, field);
+    })?.label;
+    // 从 code_list.businessRules 里找 scope 含 'delete' 的规则（如 delete.onlyDraftAllowed
+    // "非 DRAFT 状态删除时被阻断"），命中则映射为 blocked_by_business_rule；否则 success_delete。
+    // assertionHint 直接作为 skeleton 的阻断消息断言值。
+    const deleteRule = (codeList.businessRules ?? []).find((r) => {
+        const anyRule = r;
+        return Array.isArray(anyRule.scope) && anyRule.scope.includes('delete');
+    });
+    const deletePolicy = deleteRule ? 'blocked_by_business_rule' : 'success_delete';
+    const blockedDeleteMessage = deleteRule
+        ? (deleteRule.assertionHint
+            ?? deleteRule.assertion)
+        : undefined;
+    const skeletonSlotsCrud = {
+        moduleId: module,
+        searchConditions: buildSearchConditionSlots(codeList, listPage, addOrEditPage),
+        frames: resolveFrameKeywords(codeList),
+        locators: buildCrudLocators(listPage),
+        assertions: {
+            deletePolicy,
+            blockedDeleteMessage,
+        },
+    };
+    const childGridSlots = buildChildGridSlots(codeList, input.sourceRoot);
+    // 动态推导 gapCandidates：当前阶段只保留控件类 custom 按钮。
+    // 状态流转、子表、详情、统计看板/移动端等 PRD-only/业务类场景暂不进 gapCandidates，
+    // 后续可通过 code_list.gapHints 让业务人工声明后再扩展。
+    const gapCandidates = [];
+    (listPage.buttons ?? [])
+        .filter((b) => b.action === 'custom')
+        .forEach((btn) => {
+        const anyBtn = btn;
+        gapCandidates.push({
+            gapId: anyBtn.customAction ?? anyBtn.label ?? 'custom',
+            label: anyBtn.label ?? anyBtn.customAction ?? 'custom',
+            generationStrategy: 'ai',
+        });
+    });
+    const contract = {
+        schemaVersion: 'ep-stage-contract/v1-draft',
+        contractId: `${module}-contract`,
+        contractKind: 'crud_export',
+        base: {
+            module: { id: module, label: moduleName },
+            navigation: {
+                entryMode: 'directUrl',
+                directUrl,
+            },
+            credentials: { source: 'credentials.json5' },
+        },
+        scenario: {
+            kind: 'crud_export',
+            searchFields,
+            skeletonSlots: {
+                crud: skeletonSlotsCrud,
+                export: { moduleId: module, label: '导出', mode: 'all' },
+                childGrids: childGridSlots,
+            },
+            gapCandidates,
+        },
+        unresolvedSlots: [], // 框架默认策略都已确认，不进 unresolvedSlots
+    };
+    const caseIdSequence = { pageIndex: 1, nextCaseIndex: 1 };
+    const cases = buildGlueCases(moduleName, searchFields, formFieldLabels, caseIdSequence, dataKeyLabel);
+    const childGridCases = childGridSlots ? buildChildGridCases(childGridSlots, firstRole, caseIdSequence) : [];
+    cases.push(...childGridCases);
+    const buttonInferences = inferButtonInteractions(codeList, {
+        sourceRootOverride: input.sourceRoot,
+    });
+    const uncoveredCandidates = buildUncoveredCandidates(gapCandidates, firstRole, caseIdSequence, codeList, buttonInferences);
+    const testcase = {
+        schemaVersion: 'ep-stage-testcase/v1-draft',
+        testcaseId: `${module}-testcase`,
+        contractRef: '.ep-stage/contract.json5',
+        scenario: 'crud_export',
+        moduleId: module,
+        moduleName,
+        testAccess: buildTestAccess(codeList),
+        cases,
+        uncoveredCandidates,
+    };
+    const inferenceTrace = {
+        schemaVersion: 'ep-stage-inference-trace/v1-draft',
+        codeListParseMode: 'json5',
+        needsHumanReview: true,
+        skeletonSlotsPolicy: {
+            frames: {
+                source: 'framework-default',
+                reason: 'code_list.json5 不提供 iframe keyword，014 为 directUrl 模式，用模块名占位',
+            },
+            locators: {
+                source: 'framework-default',
+                reason: '014 草案已确认 MiniUI 默认规则 + text=确定 确认按钮 + addAutofillTrigger 默认能力',
+            },
+            assertions: {
+                source: 'framework-default',
+                reason: "deletePolicy='success_delete'（MiniUI 默认删除成功策略）",
+            },
+            queryFields: {
+                source: 'code-list-derived',
+                reason: 'placename 为 dataKey 用 timestamp_prefix；listbox 取首项作 value',
+            },
+            childGrids: {
+                source: 'html-derived',
+                reason: '从 add/edit 页 HTML 的 datagrid 列 editor.type 推导 component；locators 按 MiniUI 子表默认规则生成',
+            },
+        },
+        unresolvedSlotsCount: 0,
+        customButtonInferences: Array.from(buttonInferences.values()).map((inf) => ({
+            label: inf.label,
+            pattern: inf.pattern,
+            functionName: inf.functionName,
+            fallbackReason: inf.fallbackReason,
+            evidence: inf.evidence,
+        })),
+    };
+    return { contract, testcase, inferenceTrace };
+}