@epoint-testtech/ep-stage-skill 0.0.9 → 0.5.0-alpha.2

package/docs/mvp-usage-guide.md

@@ -1,298 +0,0 @@
-# glue-run-test CRUD 契约生成器 — MVP 使用手册
-
-## 概述
-
-`glue-run-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-run-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()` 生成器已移除。