@guanlin4924/devflow-pi 0.1.0

package/plugins/devflow-quality/skills/workflow-generate-mainflow-cases/references/project-dsl-contract.md

@@ -0,0 +1,190 @@
+# Project DSL Contract
+
+Legacy normalization input is an object with metadata and cases:
+
+```json
+{
+  "metadata": {
+    "feature": "Feature name",
+    "phase": "01-Feature",
+    "generated_by": "workflow-generate-mainflow-cases",
+    "project_id": 1
+  },
+  "cases": [
+    {
+      "project_id": 1,
+      "name": "Case name",
+      "description": "Positive mainflow purpose and traceability.",
+      "tags": ["api-mainflow"],
+      "dsl_json": {
+        "name": "Case name",
+        "description": "Same behavior summary.",
+        "tags": ["api-mainflow"],
+        "variables": {},
+        "steps": []
+      },
+      "source_evidence": [
+        {
+          "path": ".planning/features/Feature/后端技术方案.md",
+          "line": 120,
+          "reason": "API contract source"
+        }
+      ]
+    }
+  ]
+}
+```
+
+`cases[*]` must be compatible with backend `CaseCreate` after normalization:
+
+- `project_id`: integer. If no project id is known, use `metadata.project_id` or `1` and record an import note.
+- `name`: non-empty string.
+- `description`: optional string.
+- `dsl_json`: object.
+- `tags`: exactly one of `["api-mainflow"]` or `["ui-mainflow"]` unless the case is intentionally mixed UI flow with API setup; mixed UI flows still use `["ui-mainflow"]`.
+
+`source_evidence` is allowed in drafts. Normalization moves it to metadata and removes it from import payload cases.
+
+## DSL Step Shape
+
+Each step needs:
+
+- `id`
+- `name`
+- `driver`: `api`, `web`, or `ui`
+- `action`
+- `params`
+- `depends_on`
+- `assertions`
+- `timeout_ms`
+- `on_failure`
+
+API steps require `params.url`. Prefer variable placeholders such as `${base_url}` instead of environment-specific hosts when possible.
+
+UI steps with `driver: "ui"` require:
+
+- `strategy`: depends on step type (see below)
+- `target`: non-empty unless `strategy.mode` is `ai_only`
+
+### Strategy Selection
+
+**Action steps** (click, fill, select, hover) — `structured_first` + midscene fallback:
+
+```json
+{ "strategy": { "mode": "structured_first", "fallback": "midscene" } }
+```
+
+**Verification steps** (assert_text, assert_visible, wait for success/result) — prefer `ai_only`. Visual verification of transient UI (toast messages, success prompts, dialog confirmations) is an AI task:
+
+```json
+{ "strategy": { "mode": "ai_only" } }
+```
+
+```json
+{
+  "id": "s06",
+  "name": "验证编辑成功",
+  "driver": "ui",
+  "action": "act",
+  "target": { "label": "操作成功" },
+  "strategy": { "mode": "ai_only" },
+  "prompt": "检查页面是否出现'操作成功'的提示消息，确认编辑操作已成功完成",
+  "depends_on": ["s05"],
+  "timeout_ms": 15000
+}
+```
+
+### Target Field Specification
+
+`target` is a **flat key-value object**. The key IS the locator type. The system resolves them in this priority: `css → xpath → label → placeholder → role+name → near_text`.
+
+**There is NO `by` field. Do NOT invent `{"by": "...", "value": "..."}` format.**
+
+#### Decision Table: Which Key for Which Scenario
+
+| 场景 | 选哪个 key | 示例 | 原因 |
+|---|---|---|---|
+| 页面唯一按钮/菜单/tab | `label` + `exact` | `{"label": "新增项目库", "exact": true}` | 文本最稳定，不受CSS重构影响 |
+| 表格行操作按钮（每行重复） | `css` 精确定位 | `{"css": "tr:nth-child(2) .edit-btn"}` | 必须定位到具体行，"编辑"不唯一 |
+| 对话框底部确定/取消 | `css` 限定作用域 | `{"css": ".el-dialog__footer .el-button--primary"}` | 防止dialog外也有同名按钮 |
+| 输入框（有唯一placeholder） | `placeholder` | `{"placeholder": "请输入后台名称"}` | 语义清晰，自动scope内唯一 |
+| 表单项旁边控件 | `near_text` | `{"near_text": "后台名称"}` | label文本定位，控件自动匹配 |
+| ARIA友好的按钮/组件 | `role` + `name` | `{"role": "button", "name": "确定"}` | 无障碍属性，可访问性最好 |
+| 无他法定位时 | `xpath` | `{"xpath": "//button[text()='确定']"}` | 最后的结构化手段 |
+| 以上均不稳定 | `ai_only` strategy | 不走target，用AI视觉识别 | 放弃结构化，交AI处理 |
+
+#### Key Selection Priority for Generation
+
+1. **先看唯一性**：页面只有一个"新增项目库"按钮 → `label`；每行都有"编辑" → 不能只用 `label`
+2. **再看作用域**：对话框内用 `css` 限定 `.el-dialog__footer .el-button--primary`
+3. **input/textarea 优先用** `placeholder`
+4. **表单项控件用** `near_text`
+5. **都不行再用** `xpath` **或** `ai_only`
+
+#### Correct Format Examples
+
+```json
+// 页面唯一按钮 → label
+{ "label": "新增项目库", "exact": true }
+
+// 表格行按钮 → css 精确定位
+{ "css": "tr:nth-child(2) .edit-btn" }
+
+// 对话框确定按钮 → css 限定作用域
+{ "css": ".el-dialog__footer .el-button--primary" }
+
+// 输入框 → placeholder
+{ "placeholder": "请输入后台名称" }
+```
+
+### Assertion Rules
+
+**API steps** (`driver: "api"`) use `assertions[]` with these types:
+
+| Type | Behavior |
+|---|---|
+| `equals` | `actual == expected` |
+| `status_code` | HTTP 状态码 |
+| `contains` | `expected in actual` |
+| `json_path_equals` | JSONPath 取值相等 |
+| `json_path_exists` | JSONPath 路径存在 |
+| `regex` | 正则匹配 |
+| `not_equals` / `not_contains` / `greater_than` / `less_than` / `in` / `not_in` / `is_empty` / `is_not_empty` |
+
+**`"text"` is NOT a valid assertion type.** It will raise `ValueError: unsupported assertion type: text`.
+
+**Web/UI steps** (`driver: "web"` / `"ui"`) do NOT use `assertions[]` for text/visibility checks. Use assertion **actions** instead:
+
+```json
+// UI verification — use AI-only, not structured
+{
+  "id": "s06",
+  "name": "验证操作成功",
+  "driver": "ui",
+  "action": "act",
+  "target": { "label": "操作成功" },
+  "strategy": { "mode": "ai_only" },
+  "prompt": "检查页面是否出现'操作成功'的提示消息，确认操作已成功完成",
+  "depends_on": ["s05"],
+  "timeout_ms": 15000
+}
+```
+
+Valid assertion actions for web/ui (use ai_only for these): `assert_text`, `assert_visible`, `assert_url_contains`, `assert_any_visible`.
+
+For API steps, assertion example:
+
+```json
+{
+  "id": "api-login",
+  "driver": "api",
+  "action": "post",
+  "params": { "url": "${base_url}/auth/login", "json": { "userid": "${userid}", "password": "${password}" } },
+  "assertions": [
+    { "type": "status_code", "expected": 200 },
+    { "type": "json_path_exists", "path": "headers.X-Jwt-Token" }
+  ]
+}
+```
+
+Do not include real credentials, tokens, cookies, passwords, API keys, or production secrets. Use variables like `${auth_token}` or placeholders like `<token>` only.

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

@@ -0,0 +1,110 @@
+# UI Mainflow Rules
+
+UI cases validate successful user journeys through importable DSL.
+
+## Hard Rule: Source-Backed Terminology
+
+**All UI text in locators, step names, and descriptions MUST be exact strings from source code.** Never invent, translate, guess, or "improve" the text. If the code says "查询" (query button text), the step name and locator must say "查询" — not "搜索", not "查找".
+
+Extract locator values from:
+- Template/JSX: `<el-button>查询</el-button>` → `locator: "text:查询"`
+- Placeholder attrs: `placeholder="请输入名称"` → `locator: "placeholder:请输入名称"`
+- Dialog titles: `<el-dialog title="新增项目">` → verify text "新增项目"
+- Menu/router config: `{ path: '/Project/List', meta: { title: '项目管理' } }`
+
+### List Page Patterns: Query vs Search
+
+| 模式 | 按钮文本(源码) | URL特征 | 行为 |
+|---|---|---|---|
+| 列表查询/筛选 | "查询" 或 "筛选" | `/List`, `/list`, `/index` | 表格上方表单,过滤不跳转 |
+| 全局搜索 | "搜索" | header/侧边栏 | 触发路由跳转 |
+
+**Do not reclassify**: 源码写"查询"就生成"查询",源码写"搜索"就生成"搜索"。不要根据URL或行为推断应该叫什么。
+
+## Step Rules
+
+- Prefer `driver: "ui"` for structured UI operations.
+- Use `driver: "web"` only for plain browser actions that do not need structured target dispatch.
+- `target` must be non-empty unless `strategy.mode` is `ai_only`.
+- Use API setup steps only when needed to make the UI journey deterministic.
+
+### Strategy Selection: Action vs Verification
+
+**Operating steps** (click, fill, select, hover): use `structured_first` + midscene fallback.
+
+```json
+{ "strategy": { "mode": "structured_first", "fallback": "midscene" } }
+```
+
+**Verification steps** (assert_text, assert_visible, wait for success/result): prefer `ai_only`. Visual verification is inherently an AI task — toast messages, success prompts, dialog confirmations are transient and their DOM structure varies. Structured locators waste time on the fallback path.
+
+```json
+{ "strategy": { "mode": "ai_only" } }
+```
+
+```json
+// CORRECT: AI-only verification after critical action
+{
+  "id": "s06",
+  "name": "验证编辑成功",
+  "driver": "ui",
+  "action": "act",
+  "target": { "label": "操作成功" },
+  "strategy": { "mode": "ai_only" },
+  "prompt": "检查页面上是否出现'操作成功'的提示消息，确认编辑操作已成功完成",
+  "depends_on": ["s05"],
+  "timeout_ms": 15000
+}
+```
+
+Use `structured` only when runtime validation proves the locator is unique and stable. Do NOT use `structured` for verification steps.
+
+### Target Format: Scenario → Key Decision Table
+
+`target` is a **flat key-value object** (no `by` field). The system resolves in priority: `css → xpath → label → placeholder → role+name → near_text`. Choose the right key based on the scenario:
+
+| 场景 | key | 示例 |
+|---|---|---|
+| 页面唯一按钮/菜单/tab | `label` + `exact` | `{"label": "新增项目库", "exact": true}` |
+| 表格行操作按钮（每行重复） | `css` 精确定位 | `{"css": "tr:nth-child(2) .edit-btn"}` |
+| 对话框底部确定/取消 | `css` 限定dialog | `{"css": ".el-dialog__footer .el-button--primary"}` |
+| 输入框（有唯一placeholder） | `placeholder` | `{"placeholder": "请输入后台名称"}` |
+| 表单项旁边控件 | `near_text` | `{"near_text": "后台名称"}` |
+| ARIA友好的按钮/组件 | `role` + `name` | `{"role": "button", "name": "确定"}` |
+| 无他法 | `xpath` 或 `ai_only` | `{"xpath": "//button[text()='确定']"}` |
+
+**Decision rule**: 先看唯一性（page-level唯一用label，行级重复用css），再看作用域（dialog内用css限定），input优先placeholder。不存在 `{"by": "xxx", "value": "yyy"}` 这种格式。
+
+### Assertion Rules
+
+**Web/UI steps use assertion ACTIONS, not `assertions[]`:**
+
+```json
+// CORRECT: 文本断言用 action
+{ "action": "assert_text", "target": { "label": "操作成功" }, "params": { "text": "操作成功" } }
+{ "action": "assert_visible", "target": { "css": ".el-dialog" } }
+{ "action": "assert_url_contains", "params": { "text": "/sadmin/a/org/Project/Gift" } }
+```
+
+```json
+// WRONG: "text" 不是合法断言类型，web/ui 不走 assertions[]
+{ "assertions": [{ "type": "text", "expected": "礼物库" }] }
+{ "assertions": [{ "type": "visible", "target": { "by": "css", "selector": ".el-dialog" } }] }
+```
+
+Valid assertion actions: `assert_text`, `assert_visible`, `assert_url_contains`, `assert_any_visible`.
+
+API steps use `assertions[]` with types: `equals`, `contains`, `status_code`, `json_path_equals`, `json_path_exists`, `regex`, etc. See `project-dsl-contract.md` for the full list.
+
+## Source Evidence
+
+Cite at least one planning artifact and one code artifact per case:
+
+- Planning: UI spec, frontend tech spec, feature breakdown, or change list.
+- Code: router, page/view, API client, and relevant component/store/hook files.
+
+## Positive Mainflow Boundary
+
+Allowed: open route, create/edit/run primary record, view success result, save expected state.
+
+Not allowed: validation errors, permission differences, responsive/a11y-only checks, empty state checks, browser compatibility, performance timing, or destructive cleanup beyond normal test setup.