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

package/dist/test/crud-contract.test.js

@@ -0,0 +1,819 @@
+import { cpSync, mkdtempSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, relative, resolve } from 'node:path';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { buildCrudBusinessModuleContract, extractCodeListSummary, extractHtmlPage, extractJavaAction, generateStageSkeletonCrudSpec } from '../src/index.js';
+const packageRoot = process.cwd();
+const srcIndexPath = join(packageRoot, 'src', 'index.ts');
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../../..');
+const zwplaceDocs = join(repoRoot, 'knowledge-project/epoint-web-v9.5.2/_docs');
+const zwplaceWebapp = join(repoRoot, 'knowledge-project/epoint-web-v9.5.2/src/main/webapp/perpage/zwplace');
+const zwplaceActions = join(repoRoot, 'knowledge-project/epoint-web-v9.5.2/src/main/java/com/epoint/zwplace/action');
+const codeListPath = join(repoRoot, 'knowledge-project/epoint-web-v9.5.2/_docs/code_list.md');
+function readZwplaceSpecFixture() {
+    return {
+        path: join(zwplaceDocs, 'spec.yaml'),
+        module: {
+            id: 'zwplace',
+            label: '场所窗口信息管理',
+            description: '场所窗口信息管理模块'
+        },
+        fields: [
+            { name: 'placename', label: '场所名称', component: 'input', required: true, searchable: true, listVisible: true, formVisible: true, length: 50 },
+            { name: 'placecategory', label: '场所分类', component: 'listbox', required: true, searchable: true, listVisible: true, formVisible: true },
+            { name: 'status', label: '状态', component: 'listbox', required: false, searchable: true, listVisible: true, formVisible: false }
+        ],
+        businessRules: []
+    };
+}
+let stageCoreBuilt = false;
+/**
+ * 对单个 TypeScript 夹具做无配置编译，校验导出类型形状。
+ *
+ * @param source 需要编译的 TypeScript 源码。
+ * @returns tsc 执行状态与输出。
+ */
+function compileFixture(source) {
+    const fixtureDir = mkdtempSync(join(tmpdir(), 'crud-contract-'));
+    const fixturePath = join(fixtureDir, 'fixture.ts');
+    const importPath = relative(fixtureDir, srcIndexPath)
+        .replaceAll('\\', '/')
+        .replace(/\.ts$/, '.js');
+    try {
+        writeFileSync(fixturePath, source.replaceAll('__INDEX_PATH__', importPath), 'utf8');
+        const result = spawnSync('pnpm', [
+            'exec',
+            'tsc',
+            '--noEmit',
+            '--ignoreConfig',
+            '--pretty',
+            'false',
+            '--target',
+            'ES2022',
+            '--module',
+            'NodeNext',
+            '--moduleResolution',
+            'NodeNext',
+            '--strict',
+            '--esModuleInterop',
+            '--skipLibCheck',
+            fixturePath
+        ], {
+            cwd: packageRoot,
+            encoding: 'utf8'
+        });
+        return {
+            status: result.status,
+            stdout: result.stdout,
+            stderr: result.stderr
+        };
+    }
+    finally {
+        rmSync(fixtureDir, { recursive: true, force: true });
+    }
+}
+/**
+ * 确保本地 stage-core 已完成构建，便于后续夹具通过真实包结构做类型检查。
+ *
+ * @returns 无返回值。
+ */
+function ensureStageCoreBuilt() {
+    if (stageCoreBuilt) {
+        return;
+    }
+    execFileSync('pnpm', ['--filter', '@epoint-testtech/stage-core', 'build'], {
+        cwd: repoRoot,
+        stdio: 'pipe'
+    });
+    stageCoreBuilt = true;
+}
+/**
+ * 基于 stage-create 的 glue 模板骨架编译生成脚本，验证契约输出能在真实模板里通过类型检查。
+ *
+ * @param source 生成的 Playwright spec 源码。
+ * @returns tsc 执行状态与输出。
+ */
+function compileGlueTemplateSpec(source) {
+    ensureStageCoreBuilt();
+    const fixtureRoot = mkdtempSync(join(tmpdir(), 'stage-create-glue-'));
+    const fixtureSrcRoot = join(fixtureRoot, 'src');
+    const fixtureTestsRoot = join(fixtureSrcRoot, 'tests');
+    const fixtureSkeletonsRoot = join(fixtureSrcRoot, 'skeletons');
+    const fixtureWebRoot = join(fixtureSrcRoot, 'web');
+    const fixtureNodeModulesRoot = join(fixtureRoot, 'node_modules');
+    const fixtureTypesRoot = join(fixtureNodeModulesRoot, '@types');
+    const fixturePath = join(fixtureTestsRoot, '__generated-test-glue-fixture.spec.ts');
+    const glueTemplateRoot = join(repoRoot, 'packages/stage-create/templates/glue');
+    const glueTemplateSkeletonsRoot = join(glueTemplateRoot, 'src/skeletons');
+    const glueTemplateWebRoot = join(glueTemplateRoot, 'src/web');
+    const glueTemplateReportRoot = join(glueTemplateRoot, 'src/report');
+    const fixtureReportRoot = join(fixtureSrcRoot, 'report');
+    const stageCorePackageRoot = join(repoRoot, 'packages/stage-core');
+    const playwrightPackageRoot = join(stageCorePackageRoot, 'node_modules/@playwright/test');
+    const nodeTypesPackageRoot = join(packageRoot, 'node_modules/@types/node');
+    try {
+        mkdirSync(fixtureTestsRoot, { recursive: true });
+        mkdirSync(join(fixtureNodeModulesRoot, '@epoint-testtech'), { recursive: true });
+        mkdirSync(join(fixtureNodeModulesRoot, '@playwright'), { recursive: true });
+        mkdirSync(fixtureTypesRoot, { recursive: true });
+        cpSync(glueTemplateSkeletonsRoot, fixtureSkeletonsRoot, { recursive: true });
+        cpSync(glueTemplateWebRoot, fixtureWebRoot, { recursive: true });
+        cpSync(glueTemplateReportRoot, fixtureReportRoot, { recursive: true });
+        writeFileSync(fixturePath, source, 'utf8');
+        writeFileSync(join(fixtureRoot, 'package.json'), JSON.stringify({ name: 'stage-create-glue-fixture', private: true, type: 'module' }, null, 2), 'utf8');
+        writeFileSync(join(fixtureRoot, 'tsconfig.json'), JSON.stringify({
+            compilerOptions: {
+                target: 'ES2022',
+                module: 'ESNext',
+                moduleResolution: 'bundler',
+                strict: true,
+                esModuleInterop: true,
+                skipLibCheck: true,
+                types: ['node']
+            },
+            include: ['src/**/*.ts']
+        }, null, 2), 'utf8');
+        symlinkSync(stageCorePackageRoot, join(fixtureNodeModulesRoot, '@epoint-testtech/stage-core'), 'dir');
+        symlinkSync(playwrightPackageRoot, join(fixtureNodeModulesRoot, '@playwright/test'), 'dir');
+        symlinkSync(nodeTypesPackageRoot, join(fixtureTypesRoot, 'node'), 'dir');
+        const result = spawnSync(join(packageRoot, 'node_modules/.bin/tsc'), [
+            '--noEmit',
+            '--pretty',
+            'false',
+            '--project',
+            join(fixtureRoot, 'tsconfig.json')
+        ], {
+            cwd: packageRoot,
+            encoding: 'utf8'
+        });
+        return {
+            status: result.status,
+            stdout: result.stdout,
+            stderr: result.stderr
+        };
+    }
+    finally {
+        rmSync(fixtureRoot, { recursive: true, force: true });
+    }
+}
+/**
+ * 使用 zwplace 真实物料与 hints 组装一份完整 CRUD 契约，作为回归样本。
+ *
+ * @returns CRUD 业务模块契约对象。
+ */
+function buildZwplaceContractWithHints() {
+    const spec = readZwplaceSpecFixture();
+    const codeList = extractCodeListSummary(codeListPath);
+    const pages = ['gxhzwplacelist.html', 'gxhzwplaceadd.html', 'gxhzwplaceedit.html', 'gxhzwplacedetail.html']
+        .map((fileName) => extractHtmlPage(join(zwplaceWebapp, fileName)));
+    const actions = ['GxhZwPlaceListAction.java', 'GxhZwPlaceAddAction.java', 'GxhZwPlaceEditAction.java']
+        .map((fileName) => extractJavaAction(join(zwplaceActions, fileName)));
+    return buildCrudBusinessModuleContract({
+        moduleId: 'zwplace',
+        spec,
+        codeList,
+        pages,
+        actions,
+        hints: {
+            dataKey: {
+                selectedField: 'placename',
+                generationStrategy: 'timestamp_prefix'
+            },
+            searchConditions: [
+                {
+                    field: 'placename',
+                    component: 'input',
+                    seedValue: '自动化测试名称',
+                    strategy: 'timestamp_prefix',
+                    updatePrefix: '修改'
+                },
+                {
+                    field: 'placecategory',
+                    component: 'listbox',
+                    value: '条线大厅',
+                    createSelections: [
+                        { field: 'placecategory', value: '条线大厅' }
+                    ]
+                },
+                {
+                    field: 'status',
+                    component: 'listbox',
+                    value: '在用',
+                    createSelections: [
+                        { field: 'placecategory', value: '条线大厅' }
+                    ]
+                }
+            ],
+            buttonAliases: {
+                create: ['新增场所信息管理', '新增'],
+                saveAndClose: ['保存并关闭'],
+                search: ['搜索', '查询']
+            },
+            autofill: {
+                overrideFields: [
+                    { field: 'placename', strategy: 'timestamp_prefix', value: '自动化测试场所名称' }
+                ]
+            },
+            deletePolicy: 'blocked_by_business_rule'
+        }
+    });
+}
+describe('CrudBusinessModuleContract', () => {
+    it('supports the v1 contract shape', () => {
+        const contract = {
+            contractVersion: 'crud-business-module/v1',
+            module: {
+                id: 'zwplace',
+                label: '场所窗口信息管理'
+            },
+            pages: {
+                list: {
+                    role: 'list',
+                    pageId: 'gxhzwplacelist',
+                    title: '场所信息管理列表',
+                    iframeSrcKeyword: 'gxhzwplacelist',
+                    fields: [],
+                    buttons: [],
+                    grids: [],
+                    dialogs: [],
+                    sources: []
+                }
+            },
+            dataKey: {
+                field: 'placename',
+                label: '场所名称',
+                availability: 'derivable',
+                generationStrategy: 'timestamp_prefix',
+                sources: []
+            },
+            flows: {},
+            assertions: [],
+            businessRules: [],
+            unresolvedSlots: []
+        };
+        expect(contract.contractVersion).toBe('crud-business-module/v1');
+        expect(contract.module.id).toBe('zwplace');
+        expect(contract.pages.list.role).toBe('list');
+        expect(contract.dataKey.field).toBe('placename');
+        expect(contract.dataKey.generationStrategy).toBe('timestamp_prefix');
+        expect(Array.isArray(contract.assertions)).toBe(true);
+        expect(Array.isArray(contract.unresolvedSlots)).toBe(true);
+    });
+    it('accepts a valid contract fixture in tsc', () => {
+        const result = compileFixture(`
+      import type { CrudBusinessModuleContract } from '__INDEX_PATH__';
+
+      const contract: CrudBusinessModuleContract = {
+        contractVersion: 'crud-business-module/v1',
+        module: {
+          id: 'zwplace',
+          label: '场所窗口信息管理'
+        },
+        pages: {
+          list: {
+            role: 'list',
+            pageId: 'gxhzwplacelist',
+            title: '场所信息管理列表',
+            iframeSrcKeyword: 'gxhzwplacelist',
+            fields: [],
+            buttons: [],
+            grids: [],
+            dialogs: [],
+            sources: []
+          }
+        },
+        dataKey: {
+          field: 'placename',
+          label: '场所名称',
+          availability: 'derivable',
+          generationStrategy: 'timestamp_prefix',
+          sources: []
+        },
+        flows: {},
+        assertions: [
+          {
+            id: 'exists-check',
+            type: 'record_exists',
+            field: 'placename',
+            expectedCount: 1,
+            availability: 'derivable',
+            sources: []
+          },
+          {
+            id: 'toast-check',
+            type: 'toast_message',
+            expectedMessage: '保存成功',
+            availability: 'derivable',
+            sources: []
+          }
+        ],
+        businessRules: [],
+        unresolvedSlots: []
+      };
+
+      void contract;
+    `);
+        expect(result.status).toBe(0);
+        expect(result.stderr).toBe('');
+    });
+    it('rejects inconsistent page role bindings in tsc', () => {
+        const result = compileFixture(`
+      import type { CrudBusinessModuleContract } from '__INDEX_PATH__';
+
+      const contract: CrudBusinessModuleContract = {
+        contractVersion: 'crud-business-module/v1',
+        module: {
+          id: 'zwplace',
+          label: '场所窗口信息管理'
+        },
+        pages: {
+          list: {
+            role: 'edit',
+            pageId: 'gxhzwplacelist',
+            title: '场所信息管理列表',
+            iframeSrcKeyword: 'gxhzwplacelist',
+            fields: [],
+            buttons: [],
+            grids: [],
+            dialogs: [],
+            sources: []
+          }
+        },
+        dataKey: {
+          field: 'placename',
+          label: '场所名称',
+          availability: 'derivable',
+          generationStrategy: 'timestamp_prefix',
+          sources: []
+        },
+        flows: {},
+        assertions: [],
+        businessRules: [],
+        unresolvedSlots: []
+      };
+
+      void contract;
+    `);
+        expect(result.status).not.toBe(0);
+        expect(result.stdout).toContain(`Type '"edit"' is not assignable to type '"list"'`);
+    });
+    it('rejects invalid assertion variants in tsc', () => {
+        const result = compileFixture(`
+      import type { AssertionContract } from '__INDEX_PATH__';
+
+      const invalidToast: AssertionContract = {
+        id: 'toast-check',
+        type: 'toast_message',
+        availability: 'derivable',
+        sources: []
+      };
+
+      const invalidExists: AssertionContract = {
+        id: 'exists-check',
+        type: 'record_exists',
+        availability: 'derivable',
+        sources: []
+      };
+
+      void invalidToast;
+      void invalidExists;
+    `);
+        expect(result.status).not.toBe(0);
+        expect(result.stdout).toContain(`Property 'expectedMessage' is missing`);
+        expect(result.stdout).toContain(`missing the following properties`);
+        expect(result.stdout).toContain(`field, expectedCount`);
+    });
+    it('accepts module hints and slot resolutions in tsc', () => {
+        const result = compileFixture(`
+      import type { EvidenceRef, ModuleHints, SlotResolution } from '__INDEX_PATH__';
+
+      const evidence: EvidenceRef = {
+        kind: 'test_policy_hint',
+        path: 'examples/zwplace.module-hints.json',
+        evidenceText: 'dataKey.selectedField=placename',
+        confidence: 'high'
+      };
+
+      const hints: ModuleHints = {
+        dataKey: {
+          selectedField: 'placename',
+          generationStrategy: 'timestamp_prefix'
+        },
+        deletePolicy: 'blocked_by_business_rule',
+        buttonAliases: {
+          search: ['搜索', '查询']
+        },
+        autofill: {
+          overrideFields: [
+            { field: 'placename', strategy: 'timestamp_prefix', value: '自动化测试场所名称' }
+          ]
+        }
+      };
+
+      const slot: SlotResolution<string> = {
+        status: 'resolved',
+        value: 'placename',
+        evidence: [evidence]
+      };
+
+      void hints;
+      void slot;
+    `);
+        expect(result.status).toBe(0);
+        expect(result.stderr).toBe('');
+    });
+});
+describe('crud contract normalizer', () => {
+    it('builds a zwplace CRUD contract with unresolved strategy slots', () => {
+        const spec = readZwplaceSpecFixture();
+        const codeList = extractCodeListSummary(codeListPath);
+        const pages = ['gxhzwplacelist.html', 'gxhzwplaceadd.html', 'gxhzwplaceedit.html', 'gxhzwplacedetail.html']
+            .map((fileName) => extractHtmlPage(join(zwplaceWebapp, fileName)));
+        const actions = ['GxhZwPlaceListAction.java', 'GxhZwPlaceAddAction.java', 'GxhZwPlaceEditAction.java']
+            .map((fileName) => extractJavaAction(join(zwplaceActions, fileName)));
+        const contract = buildCrudBusinessModuleContract({
+            moduleId: 'zwplace',
+            spec,
+            codeList,
+            pages,
+            actions
+        });
+        expect(contract.contractVersion).toBe('crud-business-module/v1');
+        expect(contract.pages.list.pageId).toBe('gxhzwplacelist');
+        expect(contract.pages.add?.pageId).toBe('gxhzwplaceadd');
+        expect(contract.dataKey).toMatchObject({
+            field: 'placename',
+            label: '场所名称',
+            availability: 'human_required'
+        });
+        expect(contract.flows.create?.entryButton.label).toBe('新增场所窗口信息管理');
+        expect(contract.flows.delete?.expectedOutcome).toBe('blocked_by_business_rule');
+        expect(contract.unresolvedSlots.map((slot) => slot.slotId)).toContain('dataKey.selectedField');
+        expect(contract.unresolvedSlots.map((slot) => slot.slotId)).toContain('autofill.overrideFields');
+        expect(contract.unresolvedSlots.map((slot) => slot.slotId)).toContain('dataKey.generationStrategy');
+        expect(contract.unresolvedSlots.map((slot) => slot.slotId)).toContain('delete.expectedOutcome');
+        expect(contract.assertions.some((a) => a.type === 'toast_message')).toBe(true);
+        expect(contract.assertions.some((a) => a.type === 'record_exists')).toBe(true);
+    });
+    it('supports custom buttonLabels and dataKeyField config', () => {
+        const spec = readZwplaceSpecFixture();
+        const codeList = extractCodeListSummary(codeListPath);
+        const pages = ['gxhzwplacelist.html', 'gxhzwplaceadd.html']
+            .map((fileName) => extractHtmlPage(join(zwplaceWebapp, fileName)));
+        const actions = [];
+        const contract = buildCrudBusinessModuleContract({
+            moduleId: 'zwplace',
+            spec,
+            codeList,
+            pages,
+            actions,
+            buttonLabels: {
+                create: '自定义新增',
+                saveAndClose: '自定义保存'
+            },
+            dataKeyField: 'placecategory'
+        });
+        expect(contract.dataKey.field).toBe('placecategory');
+        expect(contract.flows.create?.entryButton.label).toBe('自定义新增');
+        expect(contract.flows.create?.saveButton.label).toBe('自定义保存');
+    });
+    it('throws when list page is missing', () => {
+        const spec = readZwplaceSpecFixture();
+        const codeList = extractCodeListSummary(codeListPath);
+        const pages = [extractHtmlPage(join(zwplaceWebapp, 'gxhzwplaceadd.html'))];
+        const actions = [];
+        expect(() => buildCrudBusinessModuleContract({ moduleId: 'zwplace', spec, codeList, pages, actions })).toThrow('List page is required');
+    });
+    it('auto-resolves dataKeyField from spec searchable fields when not provided', () => {
+        const spec = readZwplaceSpecFixture();
+        const codeList = extractCodeListSummary(codeListPath);
+        const pages = [extractHtmlPage(join(zwplaceWebapp, 'gxhzwplacelist.html'))];
+        const actions = [];
+        const contract = buildCrudBusinessModuleContract({
+            moduleId: 'zwplace',
+            spec,
+            codeList,
+            pages,
+            actions
+        });
+        expect(contract.dataKey.field).toBe('placename');
+    });
+    it('uses ModuleHints for dataKey, button aliases, autofill overrides, and delete policy', () => {
+        const spec = readZwplaceSpecFixture();
+        const codeList = extractCodeListSummary(codeListPath);
+        const pages = ['gxhzwplacelist.html', 'gxhzwplaceadd.html', 'gxhzwplaceedit.html', 'gxhzwplacedetail.html']
+            .map((fileName) => extractHtmlPage(join(zwplaceWebapp, fileName)));
+        const actions = ['GxhZwPlaceListAction.java', 'GxhZwPlaceAddAction.java', 'GxhZwPlaceEditAction.java']
+            .map((fileName) => extractJavaAction(join(zwplaceActions, fileName)));
+        const contract = buildCrudBusinessModuleContract({
+            moduleId: 'zwplace',
+            spec,
+            codeList,
+            pages,
+            actions,
+            hints: {
+                dataKey: {
+                    selectedField: 'placecategory',
+                    generationStrategy: 'fixed_value'
+                },
+                buttonAliases: {
+                    search: ['搜索', '查询']
+                },
+                autofill: {
+                    overrideFields: [
+                        { field: 'placecategory', strategy: 'fixed_value', value: '大厅' }
+                    ]
+                },
+                deletePolicy: 'blocked_by_business_rule'
+            }
+        });
+        expect(contract.dataKey).toMatchObject({
+            field: 'placecategory',
+            label: '场所分类',
+            generationStrategy: 'fixed_value'
+        });
+        expect(contract.flows.create?.overrideFields).toEqual([
+            expect.objectContaining({ field: 'placecategory' })
+        ]);
+        expect(contract.flows.delete?.expectedOutcome).toBe('blocked_by_business_rule');
+        expect(contract.unresolvedSlots.map((slot) => slot.slotId)).not.toContain('dataKey.selectedField');
+    });
+    it('marks policy slots unresolved when hints are missing and evidence is weak', () => {
+        const spec = readZwplaceSpecFixture();
+        const codeList = extractCodeListSummary(codeListPath);
+        const pages = ['gxhzwplacelist.html', 'gxhzwplaceadd.html']
+            .map((fileName) => extractHtmlPage(join(zwplaceWebapp, fileName)));
+        const contract = buildCrudBusinessModuleContract({
+            moduleId: 'zwplace',
+            spec,
+            codeList,
+            pages,
+            actions: []
+        });
+        expect(contract.unresolvedSlots.map((slot) => slot.slotId)).toContain('dataKey.selectedField');
+        expect(contract.unresolvedSlots.map((slot) => slot.slotId)).toContain('delete.expectedOutcome');
+    });
+    it('includes agent inferred workflows from ModuleHints customWorkflows', () => {
+        const spec = readZwplaceSpecFixture();
+        const codeList = extractCodeListSummary(codeListPath);
+        const pages = [extractHtmlPage(join(zwplaceWebapp, 'gxhzwplacelist.html'))];
+        const contract = buildCrudBusinessModuleContract({
+            moduleId: 'zwplace',
+            spec,
+            codeList,
+            pages,
+            actions: [],
+            hints: {
+                buttonAliases: {
+                    create: ['新增场所信息管理'],
+                    search: ['搜索'],
+                    edit: ['修改'],
+                    delete: ['删除选定'],
+                    export: ['导出'],
+                },
+                dataKey: { selectedField: 'placename', generationStrategy: 'timestamp_prefix' },
+                deletePolicy: 'blocked_by_business_rule',
+                customWorkflows: [
+                    {
+                        label: '同步窗口管理系统',
+                        expectedIntent: '同步窗口管理系统数据',
+                        expectedAssertion: '出现同步完成提示',
+                        include: true,
+                    },
+                ],
+            },
+        });
+        expect(contract.agentInferredWorkflows?.[0]).toMatchObject({
+            workflowId: 'zwplace.custom_da3d238e',
+            status: 'planned',
+            executionSource: 'agent_inferred',
+        });
+    });
+});
+describe('upstream extractors', () => {
+    it('extracts list page controls from HTML', () => {
+        const page = extractHtmlPage(join(zwplaceWebapp, 'gxhzwplacelist.html'));
+        expect(page.pageId).toBe('gxhzwplacelist');
+        expect(page.title).toBe('场所信息管理列表');
+        expect(page.buttons.map((button) => button.label)).toContain('新增场所信息管理');
+        expect(page.buttons.find((button) => button.label === '新增场所信息管理')?.locator)
+            .toBe("xpath=//a[contains(@class,'mini-button')][normalize-space()='新增场所信息管理']");
+        expect(page.dialogs.find((dialog) => dialog.title === '新增场所信息管理')).toMatchObject({
+            title: '新增场所信息管理',
+            pageId: 'perpage/zwplace/gxhzwplaceadd'
+        });
+        expect(page.grids[0]?.columns.map((column) => column.field)).toContain('placename');
+    });
+    it('extracts required and maxLength from generated zwplace form HTML', () => {
+        const page = extractHtmlPage(join(zwplaceWebapp, 'gxhzwplaceadd.html'));
+        expect(page.fields.find((field) => field.name === 'placename')).toMatchObject({
+            label: '场所名称',
+            required: true,
+            maxLength: 50,
+            locator: "//div[@label='场所名称']//input[@class='mini-textbox-input']"
+        });
+        expect(page.fields.find((field) => field.name === 'address')).toMatchObject({
+            label: '路/弄/号',
+            required: true,
+            maxLength: 50
+        });
+        expect(page.fields.find((field) => field.name === 'consultphone')).toMatchObject({
+            label: '咨询电话',
+            required: false,
+            maxLength: 20
+        });
+    });
+    it('separates grid data columns from selection, index, and row actions', () => {
+        const page = extractHtmlPage(join(zwplaceWebapp, 'gxhzwplacelist.html'));
+        const grid = page.grids[0];
+        expect(grid?.dataColumns.map((column) => column.field)).toEqual([
+            'placename',
+            'placecategory',
+            'address',
+            'servicetime',
+            'consultphone',
+            'complaintphone',
+            'status',
+            'version'
+        ]);
+        expect(grid?.selectionColumn?.columnType).toBe('checkcolumn');
+        expect(grid?.indexColumn?.columnType).toBe('indexcolumn');
+        expect(grid?.rowActions.map((action) => action.label)).toEqual(['修改', '查看']);
+        expect(grid?.columns.some((column) => column.field === '')).toBe(false);
+    });
+    it('uses module and field metadata from the zwplace spec fixture', () => {
+        const spec = readZwplaceSpecFixture();
+        expect(spec.module.id).toBe('zwplace');
+        expect(spec.module.label).toBe('场所窗口信息管理');
+        expect(spec.fields.find((field) => field.name === 'placename')).toMatchObject({
+            label: '场所名称',
+            required: true,
+            searchable: true
+        });
+    });
+    it('extracts code list summaries', () => {
+        const summary = extractCodeListSummary(codeListPath);
+        expect(summary.moduleLabel).toBe('场所窗口信息管理');
+        expect(summary.pages).toContain('gxhzwplacelist.html');
+        expect(summary.methods).toContain('deleteSelect');
+    });
+    it('separates action methods from service and dao methods in code list', () => {
+        const summary = extractCodeListSummary(codeListPath);
+        expect(summary.actionMethods.GxhZwPlaceListAction).toContain('deleteSelect');
+        expect(summary.actionMethods.GxhZwPlaceAddAction).toContain('add');
+        expect(summary.serviceMethods).toContain('insert');
+        expect(summary.daoMethods).toContain('archivePlace');
+        expect(summary.methods).toContain('deleteSelect');
+    });
+    it('extracts Java Action methods and callback messages', () => {
+        const action = extractJavaAction(join(zwplaceActions, 'GxhZwPlaceListAction.java'));
+        expect(action.controllerName).toBe('gxhzwplacelistaction');
+        expect(action.methods).toContain('deleteSelect');
+        expect(action.messages).toContain('在用数据不可删除！');
+    });
+    it('extracts only callback and tip messages from Java Action', () => {
+        const action = extractJavaAction(join(zwplaceActions, 'GxhZwPlaceAddAction.java'));
+        expect(action.messages).toContain('场所名称已存在！');
+        expect(action.messages).toContain('保存成功！');
+        expect(action.messages).not.toContain('黄浦区');
+        expect(action.messages).not.toContain('下拉列表');
+        expect(action.messages.some((message) => message.includes('public class'))).toBe(false);
+    });
+});
+describe('generate-crud-contract CLI', () => {
+    it('generates a contract from CLI with module hints', () => {
+        const outDir = mkdtempSync(join(tmpdir(), 'test-glue-'));
+        const outFile = join(outDir, 'zwplace.crud.contract.json');
+        execFileSync('pnpm', [
+            'generate:crud-contract',
+            '--',
+            '--module-id',
+            'zwplace',
+            '--docs',
+            zwplaceDocs,
+            '--code-list',
+            codeListPath,
+            '--webapp',
+            zwplaceWebapp,
+            '--java-actions',
+            zwplaceActions,
+            '--hints',
+            join(packageRoot, 'examples', 'zwplace.module-hints.json'),
+            '--out',
+            outFile
+        ], { cwd: packageRoot, stdio: 'pipe' });
+        const json = JSON.parse(readFileSync(outFile, 'utf8'));
+        expect(json.contractVersion).toBe('crud-business-module/v1');
+        expect(json.module.id).toBe('zwplace');
+        expect(json.dataKey.field).toBe('placename');
+        expect(json.dataKey.generationStrategy).toBe('timestamp_prefix');
+        expect(json.searchConditions?.map((condition) => condition.field)).toEqual(['placename', 'placecategory', 'status']);
+        expect(json.unresolvedSlots.map((slot) => slot.slotId)).not.toContain('dataKey.selectedField');
+    });
+});
+describe('stage-skeleton Playwright generator', () => {
+    it('maps a zwplace CRUD contract to CrudFlowSlots and generated skeleton spec compiles', () => {
+        const contract = buildZwplaceContractWithHints();
+        const script = generateStageSkeletonCrudSpec({
+            contract,
+            menuNavigation: '场所窗口信息管理>场所窗口信息列表',
+            testName: 'zwplace CRUD 胶水生成链路'
+        });
+        expect(script).toContain("import { CrudPage, ExportPage, LoginPage, MenuPage, type CrudFlowSlots, type ExportFlowSlots, type CrudWorkflowData } from '../skeletons';");
+        expect(script).toContain("import { GlueWorkflowRecorder, runRecordedWorkflow, type GlueWorkflowRecordInput } from '../report/glue-report';");
+        expect(script).toContain("test.describe('场所窗口信息管理 CRUD + Export'");
+        expect(script).toContain("test.describe.configure({ mode: 'serial' });");
+        expect(script).toContain("let workflowData: CrudWorkflowData | undefined;");
+        expect(script).toContain('const crudSlots: CrudFlowSlots =');
+        expect(script).toContain("moduleId: 'zwplace'");
+        expect(script).toContain("workflowId: 'zwplace.create'");
+        expect(script).toContain("workflowId: 'zwplace.read'");
+        expect(script).toContain("workflowId: 'zwplace.update'");
+        expect(script).toContain("workflowId: 'zwplace.delete'");
+        expect(script).toContain("workflowId: 'zwplace.export'");
+        expect(script).toContain('workflowData = crudPage.prepareWorkflowData();');
+        expect(script).toContain('await crudPage.runReadWorkflow(workflowData);');
+        expect(script).toContain('await crudPage.runUpdateWorkflow(workflowData);');
+        expect(script).toContain('await crudPage.runDeleteWorkflow(workflowData);');
+        expect(script).toContain('await exportPage.runExportWorkflow(testInfo);');
+        expect(script).not.toContain('runCrudFlow');
+        const compileResult = compileGlueTemplateSpec(script);
+        expect(compileResult.status).toBe(0);
+        expect(compileResult.stderr).toBe('');
+    });
+    it('generates a stage-skeleton spec from CLI', () => {
+        const outDir = mkdtempSync(join(tmpdir(), 'test-glue-playwright-'));
+        const contractFile = join(outDir, 'zwplace.crud.contract.json');
+        const specFile = join(outDir, 'zwplace.spec.ts');
+        try {
+            writeFileSync(contractFile, JSON.stringify(buildZwplaceContractWithHints(), null, 2), 'utf8');
+            execFileSync('pnpm', [
+                'generate:playwright-tests',
+                '--',
+                '--contract',
+                contractFile,
+                '--out',
+                specFile,
+                '--menu',
+                '场所窗口信息管理>场所窗口信息列表'
+            ], { cwd: packageRoot, stdio: 'pipe' });
+            const script = readFileSync(specFile, 'utf8');
+            expect(script).toContain("import { CrudPage, ExportPage, LoginPage, MenuPage, type CrudFlowSlots, type ExportFlowSlots, type CrudWorkflowData } from '../skeletons';");
+            expect(script).toContain("import { GlueWorkflowRecorder, runRecordedWorkflow, type GlueWorkflowRecordInput } from '../report/glue-report';");
+            expect(script).toContain('const crudSlots: CrudFlowSlots =');
+            expect(script).toContain("workflowId: 'zwplace.create'");
+            expect(script).toContain('workflowData = crudPage.prepareWorkflowData();');
+            expect(script).not.toContain('runCrudFlow');
+            const compileResult = compileGlueTemplateSpec(script);
+            expect(compileResult.status).toBe(0);
+            expect(compileResult.stderr).toBe('');
+        }
+        finally {
+            rmSync(outDir, { recursive: true, force: true });
+        }
+    });
+    it('prefers contract locators and result grid ids over hard-coded zwplace fallbacks', () => {
+        const contract = buildZwplaceContractWithHints();
+        contract.flows.create.entryButton.locator = 'css=[data-create]';
+        contract.flows.create.saveButton.locator = 'css=[data-save-add]';
+        contract.pages.add.fields.find((field) => field.name === 'placename').locator = 'css=[data-add-field]';
+        contract.pages.list.fields.find((field) => field.name === 'placename').locator = 'css=[data-search-field]';
+        contract.pages.edit.fields.find((field) => field.name === 'placename').locator = 'css=[data-edit-field]';
+        contract.flows.search.submitControl.locator = 'css=[data-search-submit]';
+        contract.flows.search.resultGrid = 'custom-grid';
+        contract.flows.update.entryAction.locator = 'xpath=//button[@data-action="edit"]';
+        contract.flows.update.saveButton.locator = 'css=[data-save-edit]';
+        contract.flows.delete.entryButton.locator = 'css=[data-delete]';
+        contract.flows.delete.confirmControl = {
+            pageRole: 'list',
+            label: '确定',
+            locator: 'css=.confirm-delete',
+            sources: []
+        };
+        const script = generateStageSkeletonCrudSpec({
+            contract,
+            menuNavigation: '场所窗口信息管理>场所窗口信息列表'
+        });
+        expect(script).toContain('createButton: "css=[data-create]"');
+        expect(script).toContain('addLocator: "css=[data-add-field]"');
+        expect(script).toContain('editLocator: "css=[data-edit-field]"');
+        expect(script).toContain('listLocator: "css=[data-search-field]"');
+        expect(script).toContain('addSaveButton: "css=[data-save-add]"');
+        expect(script).toContain('listSearchSubmit: "css=[data-search-submit]"');
+        expect(script).toContain('listResultValueLocatorTemplate: "xpath=//*[@id=\'custom-grid\']//div[text()=\'{{value}}\']"');
+        expect(script).toContain('listEditActionLocatorTemplate: "xpath=//*[@id=\'custom-grid\']//tr[.//div[text()=\'{{value}}\']]//button[@data-action=\\"edit\\"]"');
+        expect(script).toContain('editSaveButton: "css=[data-save-edit]"');
+        expect(script).toContain('listDeleteButton: "css=[data-delete]"');
+        expect(script).toContain("deleteConfirmButton: 'css=.confirm-delete'");
+    });
+    it('fails fast when contract uses an unsupported data generation strategy', () => {
+        const contract = buildZwplaceContractWithHints();
+        contract.searchConditions[0].generationStrategy = 'external_data_pool';
+        expect(() => generateStageSkeletonCrudSpec({
+            contract,
+            menuNavigation: '场所窗口信息管理>场所窗口信息列表'
+        })).toThrow('当前数据生成策略无法自动映射到 CrudFlowSlots: external_data_pool');
+    });
+});