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

package/docs/mvp-usage-guide.md

@@ -0,0 +1,298 @@
+# glue-test CRUD 契约生成器 — MVP 使用手册
+
+## 概述
+
+`glue-test` 是一个 TypeScript agent skill，用于从上游业务模块物料中提取结构化信息，归一化为 `crud-business-module/v1` 契约 JSON。该契约作为 AI Agent 生成 Playwright 测试脚本的地基，确保 Agent 不需要自己编造 selector、按钮文本或业务预期。
+
+当前 MVP 只面向公司自研 `zwplace` CRUD 场景，负责：
+
+- 确定性提取：从 `spec.yaml`、HTML、`code_list.md`、Java Action 中抽取结构事实。
+- 策略补齐：通过 `ModuleHints` 显式补充 `dataKey`、数据生成策略、按钮别名、auto-fill 覆盖字段、删除策略和断言策略。
+
+当前 MVP 已包含胶水模板骨架测试代码组装，但不负责直接替代骨架中的登录、菜单和 CRUD 模块实现。
+
+## 数据流
+
+```
+上游物料                          glue-test                        输出
+┌──────────────┐               ┌──────────────┐               ┌──────────────┐
+│ HTML 页面    │──extractor──→ │              │               │              │
+│ spec.yaml    │──extractor──→ │  normalizer  │──CLI 输出──→  │ 契约 JSON    │
+│ code_list.md │──extractor──→ │              │               │              │
+│ Java Action  │──extractor──→ │              │               │              │
+└──────────────┘               └──────────────┘               └──────────────┘
+```
+
+## 前置条件
+
+- Node.js 18+（注意：Node v24 下 `--module` 与 Node 内置 flag 冲突，需用 `tsx` 直接调用）
+- pnpm 10+
+
+## 安装
+
+```bash
+cd src/test-glue
+pnpm install
+```
+
+## 快速开始
+
+### 1. 运行 CLI 生成契约
+
+```bash
+cd src/test-glue
+
+# 方式一：通过 pnpm script
+pnpm generate:crud-contract -- \
+  --module-id zwplace \
+  --docs ../../knowledge-project/epoint-web-v9.5.2/_docs/003-场所窗口信息管理-20260518 \
+  --code-list ../../knowledge-project/epoint-web-v9.5.2/_bmad-output/code_list.md \
+  --webapp ../../knowledge-project/epoint-web-v9.5.2/src/webapp/perpage/zwplace \
+  --java-actions ../../knowledge-project/epoint-web-v9.5.2/src/main/java/com/epoint/zwplace/action \
+  --hints examples/zwplace.module-hints.json \
+  --out output/zwplace.crud.contract.json
+
+# 方式二：直接用 tsx
+npx tsx src/cli/generate-crud-contract.ts \
+  --module-id zwplace \
+  --docs ../../knowledge-project/epoint-web-v9.5.2/_docs/003-场所窗口信息管理-20260518 \
+  --code-list ../../knowledge-project/epoint-web-v9.5.2/_bmad-output/code_list.md \
+  --webapp ../../knowledge-project/epoint-web-v9.5.2/src/webapp/perpage/zwplace \
+  --java-actions ../../knowledge-project/epoint-web-v9.5.2/src/main/java/com/epoint/zwplace/action \
+  --hints examples/zwplace.module-hints.json \
+  --out output/zwplace.crud.contract.json
+```
+
+输出：`Wrote output/zwplace.crud.contract.json`
+
+### 1.1 `ModuleHints` 示例
+
+```json
+{
+  "dataKey": {
+    "selectedField": "placename",
+    "generationStrategy": "timestamp_prefix"
+  },
+  "autofill": {
+    "overrideFields": [
+      {
+        "field": "placename",
+        "strategy": "timestamp_prefix",
+        "value": "自动化测试场所名称"
+      }
+    ]
+  },
+  "deletePolicy": "blocked_by_business_rule"
+}
+```
+
+建议直接从 [examples/zwplace.module-hints.json](/Users/taurus/0-ws/01-work-repo/test-tech/BG-ZW/stage-glue/src/test-glue/examples/zwplace.module-hints.json) 起步。
+
+### 2. 生成胶水模板测试脚本
+
+在契约生成后，直接生成调用骨架模块的 Playwright `.spec.ts`：
+
+```bash
+pnpm generate:playwright-tests -- \
+  --contract output/zwplace.crud.contract.json \
+  --out ../stage-project/src/tests/generated-zwplace.skeleton.spec.ts \
+  --menu "场所窗口信息管理>场所窗口信息列表"
+```
+
+参数说明：
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--contract` | 是 | 契约 JSON 文件路径 |
+| `--out` | 是 | 输出 `.spec.ts` 文件路径 |
+| `--menu` | 是 | 菜单路径，传给 `MenuPage.navigateToMenu()` |
+
+输出示例（片段）：
+
+```typescript
+import { test } from '@playwright/test';
+import { CrudPage, LoginPage, MenuPage } from '../skeletons';
+
+test('zwplace CRUD 胶水生成链路', async ({ page }) => {
+  const loginPage = new LoginPage(page);
+  const menuPage = new MenuPage(page);
+  const crudPage = new CrudPage(page, crudSlots);
+
+  await loginPage.login();
+  await menuPage.navigateToMenu('场所窗口信息管理>场所窗口信息列表');
+  await crudPage.runCrudFlow();
+});
+```
+
+先做编译验证：
+
+```bash
+cd ../stage-project
+pnpm exec tsc --noEmit
+```
+
+再执行 Playwright：
+
+```bash
+npx playwright test src/tests/generated-zwplace.skeleton.spec.ts
+```
+
+### 2. 检查契约内容
+
+```bash
+cat output/zwplace.crud.contract.json | head -20
+```
+
+### 3. 检查 unresolvedSlots
+
+```bash
+cat output/zwplace.crud.contract.json | python3 -c "
+import json,sys
+d=json.load(sys.stdin)
+for s in d['unresolvedSlots']:
+    print(f\"[{s['slotId']}] {s['reason']}\")
+    print(f\"  需要由: {s['expectedProvider']} 提供\")
+    print(f\"  格式建议: {s['suggestedFormat']}\")
+"
+```
+
+## CLI 参数说明
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--module-id` | 是 | 模块 ID（如 `zwplace`），作为契约中 `module.id` 的权威值 |
+| `--docs` | 是 | 需求文档目录路径，需包含 `spec.yaml` |
+| `--code-list` | 是 | `_bmad-output/code_list.md` 文件路径 |
+| `--webapp` | 是 | webapp 页面目录路径（含 `.html` 文件） |
+| `--java-actions` | 是 | Java Action 源码目录路径（含 `*Action.java` 文件） |
+| `--hints` | 否 | `ModuleHints` JSON 文件路径，用于补充测试策略槽位 |
+| `--out` | 是 | 输出 JSON 文件路径（父目录不存在会自动创建） |
+
+## 契约结构
+
+生成的 JSON 契约遵循 `crud-business-module/v1` 版本，顶层结构：
+
+```json
+{
+  "contractVersion": "crud-business-module/v1",
+  "module": { "id": "zwplace", "label": "场所信息管理" },
+  "pages": { "list": {...}, "add": {...}, "edit": {...}, "detail": {...} },
+  "dataKey": { "field": "placename", "label": "场所名称", "availability": "derivable", ... },
+  "flows": { "create": {...}, "search": {...}, "update": {...}, "delete": {...} },
+  "assertions": [...],
+  "businessRules": [...],
+  "unresolvedSlots": [...]
+}
+```
+
+### 核心字段说明
+
+**pages** — 四个 CRUD 页面的结构化描述：
+
+| 字段 | 说明 |
+|------|------|
+| `fields` | 页面表单字段（含 locator、controlType、bind、required） |
+| `buttons` | 页面按钮（含 XPath locator） |
+| `grids` | 数据表格（含列定义） |
+| `dialogs` | 弹窗（含触发函数、标题、目标页） |
+
+**dataKey** — 测试数据的关键标识：
+
+| 字段 | 说明 |
+|------|------|
+| `field` | 唯一标识字段名（如 `placename`） |
+| `generationStrategy` | 数据生成策略（`timestamp_prefix` / `fixed_value` / `external_data_pool`） |
+| `availability` | 可获取性（`auto_extractable` / `derivable` / `human_required`） |
+
+**flows** — 四个 CRUD 操作流程：
+
+| 流程 | 关键内容 |
+|------|----------|
+| `create` | 入口按钮、目标页面、保存按钮、需要覆盖的字段 |
+| `search` | 搜索字段、提交控件、结果表格 |
+| `update` | 入口操作、目标页面、修改字段、保存按钮 |
+| `delete` | 入口按钮、预期结果（`blocked_by_business_rule` / `success_delete`） |
+
+**unresolvedSlots** — 需要人工补充的信息缺口：
+
+每个 slot 包含 `slotId`（缺口标识）、`reason`（原因）、`expectedProvider`（应由谁补充：tester / developer / runtime_config）、`suggestedFormat`（建议格式）。
+
+当前规则：
+
+- 如果 `searchable` 字段不止一个，且没有 `ModuleHints.dataKey.selectedField`，则 `dataKey.selectedField` 必须进入 `unresolvedSlots`。
+- 如果没有传入 `ModuleHints.dataKey.generationStrategy`、`ModuleHints.autofill.overrideFields`、`ModuleHints.deletePolicy`，对应策略槽位也必须进入 `unresolvedSlots`。
+- 已由 `ModuleHints` 明确确认的策略槽位，不应再出现在 `unresolvedSlots`。
+
+### 来源溯源（sources）
+
+契约中每个字段都带有 `sources` 数组，记录信息来源：
+
+```json
+{
+  "kind": "html",
+  "path": "../../knowledge-project/.../gxhzwplacelist.html",
+  "confidence": "high"
+}
+```
+
+| kind | 说明 |
+|------|------|
+| `html` | 来自 HTML 页面 |
+| `spec` | 来自 spec.yaml |
+| `code_list` | 来自 code_list.md |
+| `java_action` | 来自 Java Action 源码 |
+| `human_required` | 找不到来源，需人工补充 |
+
+## 编程接口
+
+除了 CLI，也可以在 TypeScript 中直接调用：
+
+```typescript
+import {
+  extractHtmlPage,
+  extractSpecYaml,
+  extractCodeListSummary,
+  extractJavaAction,
+  buildCrudBusinessModuleContract
+} from './index.js';
+
+const spec = extractSpecYaml('path/to/spec.yaml');
+const codeList = extractCodeListSummary('path/to/code_list.md');
+const pages = ['list.html', 'add.html'].map(f => extractHtmlPage(f));
+const actions = ['ListAction.java'].map(f => extractJavaAction(f));
+
+const contract = buildCrudBusinessModuleContract({
+  moduleId: 'zwplace',
+  spec,
+  codeList,
+  pages,
+  actions,
+  hints: {
+    dataKey: {
+      selectedField: 'placename',
+      generationStrategy: 'timestamp_prefix'
+    }
+  }
+});
+```
+
+## 运行测试
+
+```bash
+cd src/test-glue
+
+# 运行全部测试
+pnpm test
+
+# 类型检查
+pnpm typecheck
+```
+
+测试使用本地 `knowledge-project/` 中的真实 zwplace 物料，覆盖 extractor、normalizer 和 CLI 三个层面。
+
+## 已知限制
+
+1. **只覆盖 zwplace 同栈 CRUD**：当前不考虑外部技术栈，但已接入登录、菜单和 CRUD 骨架模块编排。
+2. **策略值仍需显式输入**：`dataKey`、auto-fill 覆盖策略、删除预期、断言策略不能只靠源码结构盲猜。
+3. **断言策略已消费**：`ModuleHints.assertionPolicy` 现影响 `buildAssertions` 输出，`afterCreate`/`afterDelete` 策略已生效。
+4. **组装链路已切到骨架模式**：`pnpm generate:playwright-tests` 现在只生成基于 skeleton 的 `.spec.ts`，旧的平铺 `page.fill()` / `page.click()` 生成器已移除。

package/examples/schemeresource-observable-docs/schemeresource.context.md

@@ -0,0 +1,20 @@
+# 方案资源文档可观测入口补充说明
+
+本文件是 `packages/ep-stage-skill/examples/schemeresource.observable.code_list.md` 的配套文档物料，用于模拟
+`stage-glue` 在交互补齐后，为 `code_list.md` 增补的可消费上下文。
+
+## 当前确定信息
+
+- 模块：方案资源文档（`schemeresource`）
+- 菜单（当前模拟值）：`方案资源文档>方案资源文档列表`
+- 列表页标题：`方案资源文档列表`
+- 当前结构判断：标准单列表 CRUD，列表页具备 `新增记录 / 删除选定 / 修改记录 / 详细信息`
+- 已知约束：新增页要求上传附件，`类型` 字段来自下拉代码项 `方案资源类型`
+- 已知删除策略：列表页 `deleteSelect()` 调用 `service.deleteByGuid(sel)`，成功后回调消息为 `成功删除！`，当前样例已写入 `deletePolicy=success_delete`
+- 当前一期目标：先把第二个真实业务模块的 `code_list.md` 默认入口样例落出来，再在 e2e 中验证是否需要交互补齐附件、下拉值和菜单真值
+
+## 备注
+
+- 上游真实 HTML / Java Action 仍来自 `knowledge-project/epoint-web-v9.5.2`
+- 当前样例的价值在于：让 `--code-list` 默认入口对第二个普通 CRUD 样本也可以只依赖一个可写文件完成物料扎口
+- 本样例不预设附件文件、不猜测 `方案资源类型` 的实际取值；这些属于后续 e2e 联调时的交互补齐范围

package/examples/schemeresource.module-hints.json

@@ -0,0 +1,38 @@
+{
+  "dataKey": {
+    "selectedField": "scheme_name",
+    "generationStrategy": "timestamp_prefix"
+  },
+  "searchConditions": [
+    {
+      "field": "scheme_name",
+      "component": "input",
+      "seedValue": "自动化测试方案资源",
+      "strategy": "timestamp_prefix",
+      "updatePrefix": "修改"
+    }
+  ],
+  "buttonAliases": {
+    "create": ["新增记录", "新增"],
+    "saveAndClose": ["保存并关闭"],
+    "search": ["搜索", "查询"],
+    "edit": ["修改记录", "修改"],
+    "delete": ["删除选定"],
+    "confirm": ["确定"]
+  },
+  "autofill": {
+    "overrideFields": [
+      {
+        "field": "scheme_name",
+        "strategy": "timestamp_prefix",
+        "value": "自动化测试方案资源"
+      }
+    ]
+  },
+  "deletePolicy": "success_delete",
+  "assertionPolicy": {
+    "afterCreate": "record_exists",
+    "afterUpdate": "record_exists",
+    "afterDelete": "toast_message"
+  }
+}

package/examples/schemeresource.observable.code_list.md

@@ -0,0 +1,37 @@
+# 方案资源文档代码清单
+
+> 此文件用于模拟 `stage-glue` 在交互补齐后回写到 `code_list.md` 的结果。
+> 当前样例面向 `schemeresource` 普通 CRUD；真实 e2e 时仍允许继续通过交互补齐菜单真值和业务种子值。
+
+knowledgeRoot: ../../../knowledge-project/epoint-web-v9.5.2
+menu: 方案资源文档>方案资源文档列表
+
+---
+
+## 已补齐入口字段
+
+- `knowledgeRoot`：用于把 `code_list.md` 中的相对物料路径统一解析到真实上游物料根目录。
+- `menu`：先给默认入口一个可消费的菜单路径，避免链路一开始就停在 menu gate。
+- `./schemeresource.module-hints.json`：补齐当前已知的 `dataKey`、按钮别名、删除策略和断言策略；附件文件、下拉值等未确认业务值留待 e2e 交互补齐。
+
+## 文档物料（模拟交互补齐后的可消费 docsDir）
+
+- `./schemeresource-observable-docs/schemeresource.context.md`
+
+## 前端文件
+
+- `src/main/webapp/perpage/schemeresource/schemeresourcelist.html`
+- `src/main/webapp/perpage/schemeresource/schemeresourceadd.html`
+- `src/main/webapp/perpage/schemeresource/schemeresourceedit.html`
+- `src/main/webapp/perpage/schemeresource/schemeresourcedetail.html`
+
+## 后端文件
+
+- `src/main/java/com/epoint/schemeresource/action/SchemeResourceListAction.java`
+- `src/main/java/com/epoint/schemeresource/action/SchemeResourceAddAction.java`
+- `src/main/java/com/epoint/schemeresource/action/SchemeResourceEditAction.java`
+- `src/main/java/com/epoint/schemeresource/action/SchemeResourceDetailAction.java`
+
+## 提示物料
+
+- `./schemeresource.module-hints.json`

package/examples/zwplace-observable-docs/zwplace.context.md

@@ -0,0 +1,16 @@
+# 场所窗口信息管理可观测入口补充说明
+
+本文件是 `packages/ep-stage-skill/examples/zwplace.observable.code_list.md` 的配套文档物料，用于模拟
+`stage-glue` 在交互补齐后，为 `code_list.md` 增补的可消费上下文。
+
+## 当前确定信息
+
+- 模块：场所窗口信息管理（`zwplace`）
+- 菜单：`场所窗口信息管理>场所窗口信息列表`
+- 列表页标题：`场所信息管理列表`
+- 当前一期目标：验证普通 CRUD 场景的可观测链路，不把嵌套 CRUD 写入正式契约
+
+## 备注
+
+- 上游真实 HTML / Java Action 仍来自 `knowledge-project/epoint-web-v9.5.2`
+- 当前样例的价值在于：让 `--code-list` 默认入口可以只依赖一个可写文件完成物料扎口

package/examples/zwplace-placecategory-validation.json

@@ -0,0 +1,29 @@
+{
+  "dataKey": {
+    "selectedField": "placecategory",
+    "generationStrategy": "timestamp_prefix"
+  },
+  "buttonAliases": {
+    "create": ["新增场所信息管理", "新增"],
+    "saveAndClose": ["保存并关闭"],
+    "search": ["搜索", "查询"],
+    "edit": ["修改", "编辑"],
+    "delete": ["删除选定"],
+    "confirm": ["确定"]
+  },
+  "autofill": {
+    "overrideFields": [
+      {
+        "field": "placecategory",
+        "strategy": "timestamp_prefix",
+        "value": "自动化测试场所分类"
+      }
+    ]
+  },
+  "deletePolicy": "blocked_by_business_rule",
+  "assertionPolicy": {
+    "afterCreate": "record_exists",
+    "afterUpdate": "record_exists",
+    "afterDelete": "toast_message"
+  }
+}

package/examples/zwplace.module-hints.json

@@ -0,0 +1,69 @@
+{
+  "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": ["搜索", "查询"],
+    "edit": ["修改", "编辑"],
+    "delete": ["删除选定"],
+    "confirm": ["确定"]
+  },
+  "autofill": {
+    "overrideFields": [
+      {
+        "field": "placename",
+        "strategy": "timestamp_prefix",
+        "value": "自动化测试场所名称"
+      }
+    ]
+  },
+  "deletePolicy": "blocked_by_business_rule",
+  "assertionPolicy": {
+    "afterCreate": "record_exists",
+    "afterUpdate": "record_exists",
+    "afterDelete": "toast_message"
+  },
+  "customWorkflows": [
+    {
+      "label": "同步窗口管理系统",
+      "actionAlias": ["同步窗口管理系统"],
+      "expectedIntent": "同步窗口管理系统数据",
+      "expectedAssertion": "同步完成",
+      "include": true
+    }
+  ]
+}

package/examples/zwplace.observable.code_list.md

@@ -0,0 +1,37 @@
+# 场所窗口信息管理代码清单
+
+> 此文件是 `knowledge-project/epoint-web-v9.5.2/_docs/code_list.md` 的**可写镜像**。
+> 真实上游 `knowledge-project/.../_docs/code_list.md` 是当前唯一真相源；本文件只用于开发期模拟交互补齐后的回写结果，以及只读真相源无法落盘时的 e2e 入口验证。
+
+knowledgeRoot: ../../../knowledge-project/epoint-web-v9.5.2
+menu: 场所窗口信息管理>场所窗口信息列表
+
+---
+
+## 已补齐入口字段
+
+- `knowledgeRoot`：用于把 `code_list.md` 中的相对物料路径统一解析到真实上游物料根目录。
+- `menu`：用于默认入口直达菜单导航，避免链路停在菜单候选 gate。
+- `./zwplace.module-hints.json`：用于补齐 `ModuleHints`，避免 custom workflow 只停留在 candidate。
+
+## 文档物料（模拟交互补齐后的可消费 docsDir）
+
+- `./zwplace-observable-docs/zwplace.context.md`
+
+## 前端文件
+
+- `src/main/webapp/perpage/zwplace/gxhzwplacelist.html`
+- `src/main/webapp/perpage/zwplace/gxhzwplaceadd.html`
+- `src/main/webapp/perpage/zwplace/gxhzwplaceedit.html`
+- `src/main/webapp/perpage/zwplace/gxhzwplacedetail.html`
+
+## 后端文件
+
+- `src/main/java/com/epoint/zwplace/action/GxhZwPlaceListAction.java`
+- `src/main/java/com/epoint/zwplace/action/GxhZwPlaceAddAction.java`
+- `src/main/java/com/epoint/zwplace/action/GxhZwPlaceEditAction.java`
+- `src/main/java/com/epoint/zwplace/action/GxhZwPlaceDetailAction.java`
+
+## 提示物料
+
+- `./zwplace.module-hints.json`

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@epoint-testtech/ep-stage-skill",
+  "version": "0.0.3-alpha.1",
+  "type": "module",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "files": [
+    "dist",
+    "codex-skill",
+    "docs",
+    "examples",
+    "SKILL.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "description": "Agent skills and TypeScript tools for ep-stage glue-code workflows.",
+  "dependencies": {
+    "cheerio": "^1.0.0",
+    "json5": "^2.2.3",
+    "yaml": "^2.8.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "tsx": "^4.20.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.0.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "build": "tsc",
+    "generate:crud-contract": "node --import tsx src/cli/generate-crud-contract.ts",
+    "generate:playwright-tests": "node --import tsx src/cli/generate-playwright-tests.ts",
+    "run:gap-pipeline": "node --import tsx src/cli/run-gap-pipeline.ts"
+  }
+}