@guanlin4924/devflow-pi 0.1.94 → 0.1.95

package/plugins/devflow-quality/skills/workflow-generate-mainflow-cases/references/intermediate-format.md

@@ -1,247 +1,170 @@
-# Intermediate Case Description Format
+# Case Descriptions Format (`case-descriptions.json`)
 
-AI 产出的简化用例描述格式。locator 用 `"type:value"` 字符串，不直接写 DSL target。
+`case-descriptions.json` 是 AI 写给 `scripts/compile_dsl.py` 的输入，编译产物是每个冻结 TC 一个 `devflow-test-dsl/v1` 文件 `.devflow/planning/generated-cases/{feature}/TC-xxxx.json`（形状见 `project-dsl-contract.md`）。**不要手写 DSL**：locator 写成 `"type:value"` 字符串，其余键与 DSL 同名，编译器负责生成 `target`、`driver`、`tc_sha256`、步骤默认 ID 并校验。
+
+本文件描述的是 `compile_dsl.py` 实际接受的格式；出现任何不在此列的键都会被拒绝（不会静默丢弃）。
 
 ## Hard Rule: Source-Backed Terminology
 
-**All UI text in locators, step names, and descriptions MUST be exact strings extracted from source code.** Do not invent, translate, or guess.
+**locator 与断言里的所有界面文本必须是从源码逐字取出的字符串。** 不得编造、翻译、改写。
 
 | 来源 | 可以用的 | 不可以用的 |
 |---|---|---|
-| 源码模板/JSX中的button文本 | `"text:查询"` | 自己编的 `"text:搜索"` |
-| 源码中的placeholder属性 | `"placeholder:请输入名称"` | 猜的 `"placeholder:搜索关键词"` |
-| 源码中的dialog title | `"verify:创建成功"` | 改写的 `"verify:操作成功"` |
-| 路由/菜单配置文件 | `name: "项目管理"` | `name: "项目列表页"` |
-
-**Anti-pattern**: AI 看到列表页的查询表单,自己把"查询"按钮改叫"搜索"按钮。源码写的是什么，locator 和 step name 就写什么。
-
-### List Page Pattern Recognition
-
-列表页常见两种模式，必须根据源码区分：
+| 源码里的 `data-testid` | `"testid:submit-order"` | 自己编的 testid |
+| 源码模板/JSX 中的按钮文本 | `"role:button:查询"` | 自己编的 `"role:button:搜索"` |
+| 源码中的 placeholder 属性 | `"placeholder:请输入名称"` | 猜的 `"placeholder:搜索关键词"` |
+| 源码中的 dialog title / 提示文案 | `expected: "创建成功"` | 改写的 `"操作成功"` |
 
-| 模式 | 特征 | 按钮文本 | 行为 |
-|---|---|---|---|
-| **列表查询/筛选** | 输入框+按钮在表格上方,URL含 `/List` 或 `/list` | 通常为"查询"、"筛选" | 过滤当前列表,不跳转 |
-| **全局搜索** | 搜索框在header/侧边栏,触发路由跳转 | 通常为"搜索" | 跳转到搜索页 |
-
-判断依据: **看源码中按钮的实际文本**,不要自己推断。
+列表页“查询/筛选”与全局“搜索”是不同模式，以源码中按钮的实际文本为准，不得自行归类改名。
 
 ## Top-level shape
 
 ```json
 {
-  "tc_id": "TC-0001",
-  "project_id": 6,
-  "name": "Case name",
-  "description": "Positive mainflow purpose",
-  "tags": ["ui-mainflow"],
-  "variables": { "base_url": "http://admin.test.example.com" },
-  "auth": { ... },
-  "steps": [ ... ]
+  "cases": [
+    {
+      "tc_id": "TC-0001",
+      "name": "登录后查看欢迎语",
+      "variables": {
+        "username": "qa-user",
+        "password": { "secret": "QA_PASSWORD" }
+      },
+      "data": { "setup": [], "cleanup": [] },
+      "steps": [ ]
+    }
+  ]
 }
 ```
 
-当当前功能已经存在冻结 `tests.json` 时，`tc_id` 必填，且必须引用一个正向 `test_type` 为 `api` 或 `page` 的冻结 TC。带 `generated_case_key` 且 `execution.expect.error_code` 的 API TC 是异常/边界用例，不得伪装成主流程；源码只能补充所选 TC 的入口和选择器。
-
-## Auth (optional)
-
-Only include if the case needs API login + token injection.
-
-```json
-{
-  "auth": {
-    "method": "api_login",
-    "login_url": "http://auth.test.example.com/admin/auth/login_by_id",
-    "login_body": { "userid": "${userid}", "password": "${password}" },
-    "token_path": "headers.X-Jwt-Token",
-    "app_token_url": "http://auth.test.example.com/admin/app/access",
-    "app_id": 6
-  }
-}
-```
-
-The compiler auto-generates: login API step → app token step → web inject step.
-
-## Steps
-
-### Common fields
+也接受直接写 `[...]` 数组。
 
-| Field | Required | Description |
+| Case 字段 | 必填 | 说明 |
 |---|---|---|
-| `name` | yes | Human-readable step name |
-| `action` | yes | See action types below |
-| `timeout_ms` | no | Default 30000 for navigation, 5000 for UI clicks, 15000 for wait/verify |
+| `tc_id` | 是 | 必须是冻结 suite 中 `status: confirmed`、`automation_mode: automated` 且 `execution_surface` 为 `ui` 或 `api_flow` 的 TC（存量 `page` TC 推导为 `ui`）。其他 TC（`http`、`project_test`、manual、blocked、未冻结）一律被拒绝并说明原因 |
+| `name` | 否 | 缺省为 `tc_id` |
+| `variables` | 否 | 见下 |
+| `data` | 否 | `namespace`、`owner`、`accounts`、`repeatable`、`setup[]`、`cleanup[]` |
+| `steps` | 是 | 非空数组，按顺序执行 |
+| `description`、`tags`、`source_evidence` | 否 | 只是给人看的备注，**不会写入 DSL**；来源证据请写在 `source-map.md` |
 
-### Action types
+其他键（`project_id`、`auth`、`params` 等）都会报错。每个冻结 TC 恰好一个 case，重复 `tc_id` 报错。`tc_sha256` 由编译器用 Core `tc_hash` 计算，AI 不能提供。
 
-#### `navigate` — open a page
+## Variables
 
-```json
-{
-  "name": "导航到页面",
-  "action": "navigate",
-  "url": "${base_url}/admin/page"
-}
-```
+- 标量 `"user": "qa"` → `{ "value": "qa" }`；
+- `{ "value": ..., "sensitive": true }`：值在结果里脱敏；
+- `{ "secret": "ENV_KEY" }`：运行时从已批准环境 profile 的 `secret_env` 取值，永远敏感。
 
-Compiler output: `driver=web, action=goto`
+引用写 `${name}`；内置变量为 `${execution_id}`、`${namespace}`。`Authorization`、`Cookie`、`X-Api-Key` 等敏感请求头只能由 secret/sensitive 变量拼成。**任何位置都不得出现真实密码、token、cookie 字面量**，校验器会拒绝形似密钥的字面值。步骤 `extract` 出来的变量在之后的步骤里可用。
 
-#### `click` — click a UI element
+## Data
 
 ```json
 {
-  "name": "点击编辑",
-  "action": "click",
-  "locator": "text:编辑",
-  "scope": "row:1"
+  "data": {
+    "namespace": "ns-${execution_id}",
+    "setup":   [ { "action": "post", "url": "/api/test-users", "json": { "ns": "${namespace}" }, "expect_status": 201, "covers": { "preconditions": [1] } } ],
+    "cleanup": [ { "action": "delete", "url": "/api/test-users/${namespace}" } ]
+  }
 }
 ```
 
-Compiler output: `driver=ui, action=click, strategy=structured_first`
+`namespace` 缺省 `${execution_id}`。`setup`/`cleanup` **只能是 API 请求步骤**（默认步骤 ID `setup-01…` / `cleanup-01…`）；`cleanup` 步骤不得写 `covers`。需要登录态时写显式的 `setup` API 步骤或 UI 登录步骤；没有 `auth` 快捷方式，也没有 token 注入。
 
-`scope` values:
-- (omit) — page-unique element, compiler adds `exact: true`
-- `"row:N"` — table row N, compiler adds CSS row selector alongside label
-- `"dialog"` — inside a dialog, compiler uses label as-is
+## Steps
 
-#### `fill` — fill a form input
+公共字段：`id`（可选，缺省 `s01`、`s02`…）、`name`（可选备注）、`action`（必填）、`covers`、`timeout_ms`（100–600000）。
 
-```json
-{
-  "name": "输入名称",
-  "action": "fill",
-  "locator": "placeholder:请输入名称",
-  "value": "填写的内容"
-}
-```
+### UI 动作
 
-Compiler output: `driver=ui, action=fill, strategy=structured_first`
+| action | 必填键 | 可选键 |
+|---|---|---|
+| `goto` | `url`（以 `/` 开头相对 profile 的 `base_url`） | — |
+| `click` / `check` / `uncheck` / `assert_visible` | `locator` | `exact` |
+| `fill` | `locator`、`value`（字符串） | `exact` |
+| `select` | `locator`、`value`（字符串或字符串数组，多选） | `exact` |
+| `wait_for` | `locator` | `state`（`visible`\|`hidden`\|`attached`\|`detached`，缺省 `visible`）、`exact` |
+| `assert_text` | `locator`、`expected` | `match`（`exact`\|`contains`，缺省 `exact`）、`normalize_whitespace`、`case_sensitive`、`exact` |
+| `assert_url` | `expected` | `match`（`exact`\|`contains`，缺省 `contains`） |
+| `screenshot` | — | `full_page` |
 
-#### `select` / `hover` — select option or hover
+不存在的动作：`hover`、`navigate`、`wait`（固定/加载等待）、`verify`、`act`、`assert_url_contains`、`assert_any_visible`、`inject_token`、`evaluate_js`。条件等待用 `wait_for`，URL 包含判断用 `assert_url` + `match: "contains"`。`wait_for` 与 `screenshot` 不算断言。
 
-```json
-{
-  "name": "选择类型",
-  "action": "select",
-  "locator": "text:类型A",
-  "value": "option_value"
-}
-```
+### API 步骤
 
-#### `verify` — verify success/result
+`action` 写 `request`（同时给 `method`）或直接写 `get` / `post` / `put` / `patch` / `delete`。
 
-```json
-{
-  "name": "验证操作成功",
-  "action": "verify",
-  "locator": "text:操作成功",
-  "expect": "text:操作成功",
-  "timeout_ms": 15000
-}
-```
+| 键 | 说明 |
+|---|---|
+| `url` | 必填。`/` 开头相对 profile 的 `api_base_url`（缺省 `base_url`）；绝对 URL 的 origin 必须在 profile 的 `api_origins` |
+| `headers`、`query`、`json` | 请求头、查询参数（标量）、JSON 请求体；字符串叶子可用 `${var}` |
+| `expect_status` | 期望 HTTP 状态码 |
+| `assertions` | `[ { "pointer": "/data/status", "op": "equals", "value": "created" } ]`；`op` 为 `equals`/`not_equals`/`contains`/`exists`/`not_exists`（后两者不带 `value`）；`pointer` 是 JSON Pointer |
+| `extract` | `{ "order_id": "/data/id" }` 或 `{ "token": { "pointer": "/t", "sensitive": true } }`；只支持 JSON Pointer |
+| `retry`、`idempotent` | `retry: { "max_attempts": 2-5, "on": ["connection_error"\|"timeout"\|"rate_limited"] }`；POST/PATCH 重试必须 `idempotent: true`；默认不重试 |
 
-Compiler output: `driver=ui, action=act, strategy=ai_only`, with auto-generated prompt.
+API 步骤通过页面同一个 BrowserContext 发送，与 UI 登录态共享 cookie。`HEAD`/`OPTIONS` 不支持。响应体断言只能用 `assertions` 里的 JSON Pointer，不能用 JSONPath、`status_code`/`json_path_exists` 之类旧断言类型。
 
-`expect` values:
-- `"text:xxx"` → check that text "xxx" appears on screen
-- `"dialog_visible"` → check dialog is open
-- `"dialog_closed"` → check dialog closed
-- `"url_contains:xxx"` → check URL contains "xxx"
+## Locators
 
-#### API steps
+| 写法 | 编译为 | 说明 |
+|---|---|---|
+| `testid:<id>` | `{"testid": "<id>"}` | **首选**。源码中存在 `data-testid` 时必须用；`exact` 不适用 |
+| `role:<aria-role>:<accessible name>` | `{"role","name","exact":true}` | 次选；`role:button:确定` |
+| `label:<text>` | `{"label","exact":true}` | 表单控件的 label |
+| `placeholder:<text>` | `{"placeholder","exact":true}` | 输入框 placeholder |
+| `text:<text>` | `{"text","exact":true}` | 可见文本 |
+| `css:<selector>` | `{"css": "..."}` | 最后手段；必须来自源码里确实存在的选择器，并在 `source-map.md` 注明出处；编译器打印警告 |
 
-```json
-{
-  "name": "创建记录",
-  "action": "post",
-  "params": {
-    "url": "${base_url}/api/resource",
-    "json": { "name": "test" }
-  },
-  "assertions": [
-    { "type": "status_code", "expected": 200 },
-    { "type": "json_path_exists", "path": "body.data.id" }
-  ],
-  "extract_vars": {
-    "resource_id": { "path": "body.data.id", "source": "jsonpath" }
-  }
-}
-```
+- 决策顺序：`testid` → `role` → `label` / `placeholder` → `text` → `css`。
+- 定位是 strict 的：匹配到多个元素就会失败，不会去操作其中之一。因此表格行内重复的“编辑/删除/查看”等文本用 `text:`/`role:` 几乎必然失败，编译器对这类文本给出警告；应要求或参考源码里的行级 `data-testid`。
+- **不支持** `xpath:`、`near:`、行/对话框 `scope`，出现即报错。
+- 编造的 CSS 会被拒绝：含 `%`、纯表单容器类（`.el-form-item`、`.el-form-item__content`）、随机字母数字类名、仅位置的 `:nth-child(...)` 选择器、长度不足 10 个字符的选择器。
 
-Compiler output: `driver=api, action=post`
+## covers（覆盖映射，必填）
 
-#### `wait` — wait for page/element
+Core 结构覆盖校验要求：冻结 TC 的**每个** `preconditions[i]` 和 `steps[i]`（下标从 1 开始）至少被一个 DSL 步骤覆盖，`oracle` 至少被一个非弱断言的**断言步骤**覆盖。写法二选一：
 
 ```json
-{
-  "name": "等待加载",
-  "action": "wait",
-  "wait_for": "load",
-  "timeout_ms": 5000
-}
+{ "covers": { "preconditions": [1], "steps": [2, 3], "oracle": true } }
+{ "covers": ["pre:1", "step:2-3", "oracle"] }
 ```
 
-Compiler output: `driver=web, action=wait`
-
-#### `inject_token` — inject auth token
+- `oracle` 只能写在断言步骤上：`assert_visible`/`assert_text`/`assert_url`，或带 `assertions`/`expect_status` 的 API 步骤，且只能在主步骤（不能在 `data.setup`/`cleanup`）。
+- 弱断言不算：在任何交互之前只断言静态入口元素可见；断言的是流程自己刚操作过的元素；只检查 2xx 状态而没有响应体断言。
+- 覆盖下标必须落在冻结 TC 数组范围内，写错会失败。
+- 这只是结构覆盖，不证明语义正确；语义由独立 AI 审查（建议性）和人工批准 `execution_plan`（权威）把关。
 
-Rarely needed directly — prefer using `auth` config. Only use if auth pattern is non-standard.
+## 完整示例
 
 ```json
 {
-  "name": "注入Token",
-  "action": "inject_token",
-  "script": "localStorage.setItem('token', '${jwt_token}')"
+  "cases": [
+    {
+      "tc_id": "TC-0001",
+      "name": "登录后显示欢迎语",
+      "variables": { "user": "qa-user", "password": { "secret": "QA_PASSWORD" } },
+      "data": {
+        "setup": [
+          { "action": "post", "url": "/api/test-users", "json": { "ns": "${namespace}" }, "expect_status": 201, "covers": { "preconditions": [1] } }
+        ],
+        "cleanup": [ { "action": "delete", "url": "/api/test-users/${namespace}" } ]
+      },
+      "steps": [
+        { "action": "goto", "url": "/login", "covers": ["step:1"] },
+        { "action": "fill", "locator": "label:用户名", "value": "${user}" },
+        { "action": "fill", "locator": "label:密码", "value": "${password}" },
+        { "action": "click", "locator": "testid:login-submit", "covers": ["step:2"] },
+        { "action": "assert_text", "locator": "testid:welcome", "match": "contains", "expected": "欢迎", "covers": ["oracle"] }
+      ]
+    }
+  ]
 }
 ```
 
-## Locator Hard Rules — Zero Tolerance for Fabrication
+## 编译行为
 
-**CSS 选择器和 XPath 是精确匹配器，必须来自源码实际存在的 class/结构。禁止 AI 编造任何 CSS class 名或 XPath 表达式。**
-
-编译器检测到以下特征会直接拒绝：
-- CSS 含 `%`（编造的 utility class，如 `.w-100%`）
-- 纯容器类（`.el-form-item`、`.el-form-item__content`）— 匹配所有字段而非特指
-- 随机生成的 class 名模式
-- 长度 < 10 字符的裸 class
-
-### fill 动作的硬决策链
-
-fill 动作按此顺序选择 locator，禁止跳过：
-
-1. 字段有 placeholder？ → `placeholder:xxx`
-2. 没有？字段前有 label 文本？ → `near:label文本`
-3. 都不行？ → `ai_only`（禁止编 CSS）
-
-### click 动作的决策链
-
-1. 页面唯一文本（按钮/菜单/tab） → `text:xxx`
-2. 表格行操作（每行重复） → `text:编辑` + `scope: "row:N"`
-3. ARIA 属性完整 → `role:button:确定`
-4. 对话框内确定/取消 → `css:.el-dialog__footer .el-button--primary`（Element Plus 标准结构，非编造）
-5. 源码中有明确的特定 class（须在 source-map.md 注明出处） → `css:xxx`
-6. 都不行 → `ai_only`
-
-## Locator Format Reference
-
-| Format | Example | Compiler produces |
-|---|---|---|
-| `text:<text>` | `"text:新增项目库"` | `{"label": "新增项目库", "exact": true}` |
-| `placeholder:<text>` | `"placeholder:请输入名称"` | `{"placeholder": "请输入名称"}` |
-| `near:<text>` | `"near:项目介绍"` | `{"near_text": "项目介绍"}` |
-| `css:<selector>` | `"css:.el-dialog__footer .el-button--primary"` | `{"css": ".el-dialog__footer ..."}` |
-| `role:<role>:<name>` | `"role:button:确定"` | `{"role": "button", "name": "确定"}` |
-| `xpath:<expr>` | `"xpath://button[text()='确定']"` | `{"xpath": "//button[text()='确定']"}` |
-
-### Anti-patterns
-
-```
-// WRONG: 编造的 CSS class
-"locator": "css:.w-100% .el-form-item__content"
-
-// WRONG: 纯容器类，不特指字段
-"locator": "css:.el-form-item__content"
-
-// CORRECT: fill 用 near_text
-"locator": "near:项目介绍"
-```
+- **all-or-nothing**：任一 case 出错则一个 DSL 文件也不写，所有错误一并打印；
+- 输出确定性（无时间戳）：描述不变则重编译得到字节相同的文件，已有 `execution_plan` 批准的 `dsl_sha256` 保持有效；DSL 一旦变化，对应 TC 的批准失效，需要重新提案；
+- 每个文件都已通过 Core `dsl_v1`（Schema + 语义）与 `dsl_coverage`；
+- 旧 TestAgent 格式（`verify`/`navigate`/`auth`/`params`/`text:` 行内 scope 等）由 `export_legacy_testagent.py` 单独处理，与门禁无关，见 `project-dsl-contract.md` 末尾。

package/plugins/devflow-quality/skills/workflow-generate-mainflow-cases/references/mainflow-selection.md

@@ -1,36 +1,40 @@
 # Mainflow Selection
 
-Generate only positive API/UI mainflows that represent normal user or system success paths.
+选择单位是**冻结 TC**，不是“从代码里挑几条流程”。只为满足全部条件的 TC 生成 v1 DSL：
+
+- 在已冻结、未 stale 的 `.devflow/planning/requirements/{feature}/tests.json` 中，`status: confirmed`；
+- `automation_mode: automated`；
+- `execution_surface` 为 `ui` 或 `api_flow`（存量 `page` TC 推导为 `ui`；`http`、`project_test`、`legacy_unclassified` 的 `project_test` 不生成 DSL）；
+- 是正向主流程。
+
+对这类 TC，DSL 生成是 `run-acceptance-tests` 的真实前置条件：没有 DSL 并经用户批准 `execution_plan`，该 TC 只会 `blocked(dsl_not_approved)`，不能收口。因此不要“挑选性”地只生成容易的 TC；不能生成的 TC 必须在 `mainflow-analysis.md` 写明原因，并在绑定阶段降级为 `manual`（需 `mode_override` 批准）或 `blocked`。
 
 ## Include
 
-- P0/P1 positive scenarios explicitly implemented by the current feature.
-- API flows that call public API entries in successful order with valid request data.
-- UI flows that cover the primary happy path visible to users.
-- UI flows may include API setup steps if needed to create prerequisites.
-- Assertions that confirm success status, expected response fields, visible UI state, or navigation result.
+- 冻结 TC 中的 P0/P1 正向场景，且当前代码确实实现了它。
+- UI 主路径：用户可见的成功旅程。
+- API 链路：按成功顺序、用有效请求数据调用公开 API 入口，可用 `extract` 串联。
+- UI 流程可用 `data.setup` 的 API 步骤准备前置数据。
+- 断言必须确认成功结果：响应体字段、可见 UI 状态或导航结果，不能只是入口元素存在。
 
-## Exclude
+## Exclude（不生成 DSL）
 
-- Exceptions, error handling, invalid input, missing data, retry, timeout, conflict, and rollback cases.
-- Boundary value tests.
-- Permission/role/security tests.
-- Performance, load, concurrency, soak, and stability tests.
-- Migration-only checks and internal refactor checks.
-- Flows not implemented in actual code, even if mentioned in planning.
-- Historical modules excluded by navigation.
+- 异常、错误处理、非法输入、缺失数据、重试、超时、冲突、回滚。
+- 边界值、权限/角色/安全、性能/负载/并发/稳定性专项。
+- 迁移专项检查、内部重构检查。
+- 纯视觉判断（没有确定性断言）、无稳定 locator 或无法准备/隔离数据的流程。
+- 代码中并未实现的流程，即使规划里提到。
+- 导航文件已排除的历史模块。
 
 ## Selection Method
 
-1. Use planning documents to identify intended feature scope and FP/BR/CR IDs.
-2. Use code to confirm implemented endpoints, UI routes, components, and API client calls.
-3. Keep a case only when planning intent and code reality both support it.
-4. Prefer fewer complete mainflow cases over many shallow fragments.
-5. Record every inclusion and exclusion in `mainflow-analysis.md`.
+1. 读冻结 TC，列出所有 `automated` + `ui`/`api_flow` 的 TC；其余 TC 记录为“不适用”及原因。
+2. 用规划文档确认功能范围及 FP/BR/CR ID，用源码确认实际实现的路由、组件、API client、端点。
+3. 计划与代码现实都支持才保留；计划里有而代码里没有的写成阻塞，交回上游，不得凭猜测补全。
+4. 每个保留/排除都记录到 `mainflow-analysis.md`，包含 TC ID 与来源证据。
 
 ## Case Granularity
 
-- One API case should cover one coherent backend success path.
-- One UI case should cover one coherent user journey.
-- Do not split a single user journey into multiple cases unless the platform requires independent setup.
-- Do not combine unrelated features into one case.
+- 一个 TC 恰好一个 case、一个 DSL 文件；不拆分也不合并 TC。
+- 一个 UI case 覆盖该 TC 的整段用户旅程；一个 `api_flow` case 覆盖该 TC 的整条后端成功链路。
+- 不把无关功能塞进一个 case。