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

package/codex-skill/ep-stage/glue-generate-testcase/references/testcase-schema.md

@@ -1,112 +1,95 @@
-# glue-testcase schema (v2)
-
-`testcase.json5` 顶层 schema：
-
-```json5
-{
-  schemaVersion: "v2",
-  scenario: "crud",                  // ★ v2 新增（REQ-SCENE-01）：场景类型。**由 testcase 子命令运行时决定后写入此字段**（产物，非输入）。决策优先级：①--scenario CLI 参数 ②ModuleHints 推断 ③默认 "crud"
-  moduleId: "zwplace",
-  moduleName: "场所窗口信息管理",
-  menuPath: "场所窗口信息管理>场所窗口信息列表",  // ★ v2 新增（REQ-MENU-01）：从 code_list.md 搬到 testcase 扎口
-
-  // ★ v2 新增：上游推断的需求系统/角色集
-  requiredSystems: [
-    { url: "http://192.168.x.x:8100/.../login", systemName: "主业务系统" }
-  ],
-  requiredRoles: [
-    { role: "admin", hint: "默认操作员" }
-  ],
-
-  // ★ v2 新增：骨架命中清单（run 阶段直接组装）
-  // evidence 格式约定：<kind>=<ref>，kind ∈ {html, java, spec, contract, skeleton, hint}
-  coveredActions: [
-    {
-      actionId: "zwplace.create",
-      kind: "create",
-      evidence: [
-        "html=src/main/webapp/.../gxhzwplaceadd.html",
-        "java=src/main/java/.../ZwplaceAction.java"
-      ]
-    },
-    { actionId: "zwplace.read",   kind: "read",   evidence: ["html=src/main/webapp/.../gxhzwplacelist.html", "java=..."] },
-    { actionId: "zwplace.update", kind: "update", evidence: ["html=...", "java=..."] },
-    { actionId: "zwplace.delete", kind: "delete", evidence: ["html=...", "java=..."] }
-  ],
-
-  // ★ v2 新增：骨架未命中候选（run 阶段 AI 推理）
-  uncoveredCandidates: [
-    {
-      actionId: "zwplace.sync",
-      label: "同步窗口管理系统",
-      status: "planned",            // planned | candidate | unresolved | resolved
-      requiredRole: "admin",        // ★ v2 新增：AI 推理时知道用哪个角色操作
-      businessIntent: "同步窗口数据",
-      assertionExpectation: "同步完成提示",
-      evidence: ["html=...", "hint=ModuleHints.customWorkflows.zwplace.sync"]
-    }
-  ],
-
-  // 既有 v1 字段（cases 内部行为不变）
-  cases: [
-    {
-      caseId: "zwplace.create",
-      title: "新增场所窗口信息管理",
-      scenario: "crud.single-page",
-      reviewStatus: "confirmed",    // v1 字段保留：confirmed | needs_review | blocked
-      requiredRole: "admin",        // ★ v2 新增：该用例由哪个角色操作
-      evidence: ["skeleton=crud.skeleton-testcase/v1", "contract=crud-business-module/v1"],
-      steps: ["进入菜单", "点击新增", "填写并保存测试数据"],
-      assertions: ["新增后可查询到记录"],
-      unresolved: []
-    }
-  ],
-
-  reasoningSummary: {
-    conclusion: "生成 4 条 CRUD 胶水测试用例。",
-    evidenceChain: [],
-    alternatives: ["crud.single-page"],
-    confidence: "high",
-    risks: [],
-    needsHumanReview: false
-  }
-}
-```
-
-## v1 → v2 升级点
-
-- 顶层新增 `schemaVersion: "v2"`
-- 顶层新增 `scenario`（REQ-SCENE-01）
-- 顶层新增 `menuPath`（REQ-MENU-01 修订）
-- 顶层新增 `requiredSystems[]` / `requiredRoles[]`
-- 顶层新增 `coveredActions[]` / `uncoveredCandidates[]`（钻探产物前移）
-- `cases[]` 新增 `requiredRole`
-- `uncoveredCandidates[]` 新增 `requiredRole`
-- `evidence` 字段格式约定 `<kind>=<ref>`
-- **顶层不引入** `reviewStatus`（REQ-DATA-04）；仅 `cases[].reviewStatus` 保留
-
-## 字段说明（v2 新增字段）
-
-- `schemaVersion`：必为字符串 `"v2"`。Task 1.1 `validateTestcase` 强制校验；其他值或缺失会拒绝并提示重跑 `glue-generate-testcase`。
-- `scenario`：场景类型（**产物**，非输入）。由 testcase 子命令运行时按 3 档优先级决定：① CLI `--scenario` 显式参数 → ② 从 `ModuleHints` 推断 → ③ 默认 `"crud"`。本轮仅支持 `"crud"`；未来 `"statistic"` / `"approval"` 等场景扩展时不增加新 CLI 命令，仅扩展 testcase 内部分发（REQ-SCENE-01）。
-- `menuPath`：菜单路径，从 `code_list.md` 搬到 testcase 扎口（REQ-MENU-01 修订）。glue-run-test 的 spec 子命令从此读取，不再从 code_list 二次解析。
-- `requiredSystems[]`：上游钻探推断的需求涉及的系统集，每项 `{ url, systemName? }`。驱动 `credentials.template.json5` 生成 + 引导用户在 glue-generate-testcase 第 5 步交互确认（REQ-UX-02）。
-- `requiredRoles[]`：上游钻探推断的需求涉及的角色集，每项 `{ role, hint? }`。同上驱动 template + 确认。
-- `coveredActions[]`：骨架命中清单。run 阶段直接组装胶水部分 spec，按 `evidence` 引用源码与契约。
-- `uncoveredCandidates[]`：骨架未命中候选；`status` 取 `planned`（可进 AI 推理）/ `candidate`（不得进 spec，要求补 hints）/ `unresolved`（缺证据）/ `resolved`（已通过推理）。
-- `uncoveredCandidates[].requiredRole`：AI 推理时该动作由哪个角色操作（多角色场景必需）。
-- `cases[].requiredRole`：该用例由哪个角色操作。spec 子命令据此映射 credentials.json5 + cases 登录切换。
-- `evidence`：字符串数组，每项格式 `<kind>=<ref>`。`kind` ∈ `{html, java, spec, contract, skeleton, hint}`。
-
-## 既有 v1 字段说明（保留语义）
-
-- `cases[].reviewStatus`：`confirmed` / `needs_review` / `blocked`。`needs_review` 的用例不得进入 spec assembly（run 阶段按 case 粒度阻断）。
-- `caseId`：spec assembly 需要与生成脚本工作流粒度一致。CRUD 用例固定为 `<moduleId>.create` / `.read` / `.update` / `.delete`。
-- `unresolved`：未确认项（如嵌套 CRUD 子表保存后断言）。必须落盘，不能只在对话解释。
-- `reasoningSummary`：与 `.stage/trace/<run-id>/testcase-generation.json` 同构。
-
-## Schema 演化策略
-
-- 破坏性升级走 major 版本号（如 v2 → v3）
-- CLI 读取时校验 `schemaVersion`：不匹配抛结构化错误（含期望版本 + 修复建议「重跑 `glue-generate-testcase <需求路径>`」）
-- 顶层 `reviewStatus` 字段**永远不引入**（REQ-DATA-04）；审阅意见请直接在 `testcase.json5` 加 JSON5 `// 注释`
+# testcase.json5 schema v1-draft
+
+`testcase.json5` 是测试意图账本，由 `/glue-generate-testcase` 基于 `code_list.json5` 和 `contract.json5` 生成，供 `/glue-run-test` 的 `spec` / `run` 消费。
+
+## 顶层结构
+
+```json5
+{
+  schemaVersion: 'ep-stage-testcase/v1-draft',
+  testcaseId: 'zwplace-testcase',
+  contractRef: '.ep-stage/contract.json5',
+  scenario: 'crud_export',
+  moduleId: 'zwplace',
+  moduleName: '场所窗口信息管理',
+
+  // 可选历史展示字段；新链路不要求 menuPath，directUrl/route 由 contract + runtime 配置解决。
+  menuPath: undefined,
+  runtimeContext: {
+    testProjectDir: '/abs/path/to/glue-project',
+    caseDir: '/abs/path/to/glue-project/src/tests/014-测试需求10-20260622',
+    specPath: '/abs/path/to/glue-project/src/tests/014-测试需求10-20260622/crud.spec.ts',
+  },
+  testAccess: {
+    systems: [
+      {
+        systemName: '政务系统',
+        loginUrl: 'https://example.com/login',
+        roles: [
+          {
+            role: '业务管理员',
+            username: 'qa-admin',
+            password: 'plain-text-for-dev',
+            permissions: ['新增', '修改', '删除', '导出'],
+          },
+        ],
+      },
+    ],
+  },
+
+  cases: [
+    {
+      caseId: 'zwplace-placename-create',
+      title: '场所名称-新增',
+      generationStrategy: 'glue',
+      coverageStatus: 'covered',
+      reviewStatus: 'confirmed',
+      queryKey: '场所名称',
+      precondition: '使用具备权限的测试角色登录系统并进入目标列表页',
+      steps: '按查询主键完成新增、查询、编辑、删除或导出流程',
+      assertion: '按查询主键、列表结果或导出行为验证执行结果',
+    },
+  ],
+
+  uncoveredCandidates: [
+    {
+      caseId: 'businessState.transitions',
+      label: '状态流转',
+      generationStrategy: 'ai',
+      coverageStatus: 'gap',
+      requiredRole: '业务管理员',
+      businessIntent: '覆盖在用不可删除等业务规则边界',
+      assertionExpectation: '在用状态场所执行删除时应被业务规则阻断',
+      queryKey: '不适用',
+      precondition: '使用角色：业务管理员',
+      steps: '按 AI Runtime Task 观察页面并执行：覆盖在用不可删除等业务规则边界',
+      assertion: '在用状态场所执行删除时应被业务规则阻断',
+    },
+    {
+      caseId: 'statisticsDashboard',
+      label: '统计看板（无入口）',
+      generationStrategy: 'ai',
+      coverageStatus: 'blocked',
+      requiredRole: '业务管理员',
+      businessIntent: 'code_list.json5 标记 PRD 提到统计大屏，但本次出码未发现对应实现文件',
+      assertionExpectation: '运行态推理若仍无入口则记录 blocked，不生成胶水骨架步骤',
+      queryKey: '不适用',
+      precondition: '使用角色：业务管理员',
+      steps: '按 AI Runtime Task 观察页面并执行：code_list.json5 标记 PRD 提到统计大屏，但本次出码未发现对应实现文件',
+      assertion: '运行态推理若仍无入口则记录 blocked，不生成胶水骨架步骤',
+    },
+  ],
+}
+```
+
+## 约束
+
+- 顶层可选写入 `runtimeContext`，字段固定为 `testProjectDir / caseDir / specPath`，供 `glue-run-test` 直接定位工程与 spec。
+- 顶层可选写入 `testAccess`，结构为 `systems[].{systemName, loginUrl?, roles[]}`；`roles[]` 字段固定为 `role / username? / password? / permissions[]`。
+- 当前开发调试阶段允许把 `username / password` 明文写入 `testcase.json5.testAccess`，便于 generate → run 直接串联；`credentials.json5` 仅作为兼容兜底与人工补齐入口。
+- `cases[]` 只承载 `generationStrategy: 'glue'`。
+- `cases[]` 中正式执行字段为 `queryKey / precondition / steps / assertion`，缺任一字段都不应再视为最新结构。
+- `uncoveredCandidates[]` 只承载 `generationStrategy: 'ai'`，同时也必须携带 `queryKey / precondition / steps / assertion` 执行字段。
+- 缺入口、缺权限、缺运行态数据等阻断状态用 `coverageStatus: 'blocked'` 表达，不再引入 `manual` 生成策略。
+- `menuPath` 不是必填字段；不要从 `code_list.json5` 或历史菜单字段反推为必需导航入口。
+- `testcase.md` 只是人审视图，事实源仍是 `testcase.json5`。

package/codex-skill/ep-stage/glue-generate-testcase/references/testcase-tpl.md

@@ -0,0 +1,72 @@
+<!--
+testcase.md 渲染模板（AI 用）。
+
+用法（由 glue-generate-testcase SKILL Step 6 驱动）：
+- 数据源：`<需求名>/testcase.json5`（cases 结构 = 事实源） + `<需求名>/.ep-stage/contract.json`（业务槽位）+ `<需求名>/credentials.json5`（环境信息）
+- AI 按本模板渲染 testcase.md，重跑覆盖
+- 忠实性约束：cases 数量 / caseId / title / reviewStatus / requiredRole 必须**逐字**取自 testcase.json5；步骤/断言/前置条件中的具体槽位标签（菜单/列表页/按钮文字/查询字段）必须**逐字**取自 contract.json，AI 只组织自然语言句式，不得新增/捏造 contract 没有的槽位
+
+下面是格式骨架。`{{...}}` 是占位，AI 渲染时全部替换；不要把这段说明注释写进产出的 testcase.md。
+-->
+
+---
+schemaVersion: {{testcase.schemaVersion}}            # 取自 testcase.json5 顶层
+scenario: {{testcase.scenario}}                       # 取自 testcase.json5 顶层
+moduleId: {{testcase.moduleId}}                       # 取自 testcase.json5 顶层
+contractVersion: {{contract.contractVersion}}         # 取自 contract.json
+---
+
+# {{testcase.moduleName}}胶水测试用例
+
+## 环境信息
+
+- 登录地址：{{credentials[0].url}}
+- 登录账号：{{credentials[0].username}}
+- 登录密码：（已配置在 credentials.json5，不在此展示）
+- 菜单路由：{{testcase.menuPath || "（未填写，待 testcase.json5 审阅补齐）"}}
+- 列表页：{{contract.pages.list.title}}
+- 查询字段：{{contract.flows.search.searchField.label}}
+- 操作角色：{{testcase.requiredRoles[0].role}}
+- 未解析槽位：{{contract.unresolvedSlots.length > 0 ? contract.unresolvedSlots.map(s => s.slotId).join("、") : "无"}}
+
+## CRUD 冒烟用例
+
+| 用例 ID | 标题 | 前置条件 | 步骤 | 断言 |
+|---|---|---|---|---|
+| {{case.caseId}} | {{case.title}} | {{case.preconditions}} | {{case.steps_joined}} | {{case.assertions_joined}} |
+
+<!--
+说明（仅供 AI 渲染时参考，不写入产出 md）：
+
+「步骤」「断言」「前置条件」列的填充规则——
+
+cases[].steps / cases[].assertions 当前若为占位（如「执行 create 主流程（详见 .spec.ts）」、「验证 create 完成后业务断言」），
+AI 应该**基于 contract.json 槽位组装具体的自然语言表述**：
+
+- create 步骤（caseId 含 .create）：`进入菜单 {testcase.menuPath || "<未填写菜单>"}；确认列表页 {contract.pages.list.title}；点击 {contract.flows.create.entryButton.label}；填写 {contract.dataKey.label} 等字段；点击 {contract.flows.create.saveButton.label}`
+- create 断言：`新增后可在 {contract.pages.list.title} 按 {contract.flows.search.searchField.label} 查询到记录`
+- create 前置条件：`已登录并进入 {testcase.menuPath || "<未填写菜单>"}`
+
+- read 步骤（caseId 含 .read）：`进入菜单 {testcase.menuPath || "<未填写菜单>"}；按查询字段：{contract.flows.search.searchField.label} 输入测试值；点击 {contract.flows.search.submitControl.label}`
+- read 断言：`查询结果包含 {contract.flows.search.searchField.label} 对应的测试记录`
+- read 前置条件：`已存在可查询测试数据`
+
+- update 步骤（caseId 含 .update）：`在 {contract.pages.list.title} 中定位测试记录；点击 {contract.flows.update.entryAction.label}；修改 {contract.dataKey.label} 字段；点击 {contract.flows.update.saveButton.label}`
+- update 断言：`修改后可按 {contract.flows.search.searchField.label} 查询到更新后的记录`
+- update 前置条件：`已定位到待修改记录`
+
+- delete 步骤（caseId 含 .delete）：`在 {contract.pages.list.title} 中定位测试记录；点击 {contract.flows.delete.entryButton.label}；按契约策略 {contract.flows.delete.expectedOutcome} 确认删除结果`
+- delete 断言：`删除结果符合 contract.flows.delete.expectedOutcome={contract.flows.delete.expectedOutcome} 的预期`
+- delete 前置条件：`已定位到待删除记录`
+
+- 非 CRUD 用例（uncoveredCandidates 转入的 candidate / planned 用例）：AI 按 testcase.json5 cases[].businessIntent + assertionExpectation 直译；缺时填「待人工补充」，不发挥
+
+testcase.json5 的 cases[].evidence 不展示在 md 表格（人审不需要技术性溯源）；
+若 testcase.json5 cases 数量为 0，testcase.md 表格只保留表头，下方追加一段说明「本需求未生成任何用例，请审阅 .ep-stage/inference-trace.json 排查」。
+-->
+
+## 审阅引导
+
+1. 表格中**步骤、断言列若仍含占位**（如「执行 X 主流程」），表示 contract.json 对应槽位证据不足；请检查 `.ep-stage/inference-trace.json` 的 `moduleHintsInference.unresolved` 与 `contract.json.unresolvedSlots`，补齐后重跑。
+2. 如对推断步骤/断言不认可，**修改 `testcase.json5` 的 cases[] 字段**（非本 md 文件），重跑 `/glue-generate-testcase` 重新渲染本 md。
+3. 凭据信息在 `credentials.json5`；登录密码不显示在本审阅视图。