@josephyan/qingflow-app-builder-mcp 1.1.26 → 1.1.28

package/skills/qingflow-app-builder/references/build-complete-system.md

@@ -1,428 +1,234 @@
-# Build Complete System（完整系统搭建）
+# Build Complete System
 
-Use this when the user wants a multi-app business system: multiple related forms, shared workflow, cross-app relation fields, a portal dashboard, and sample data.
+Use this when the user asks for a system, app package, workspace module set, or several related apps/forms.
+Do not compress several business objects into one app.
 
-**Signal phrases**: "建一套系统"、"包含 X 个模块"、"这几个表单之间建立关联"、"完整的业务系统"
+## Main Chain
 
-For a single new app inside an existing package, use [create-app.md](./create-app.md) instead.
-
----
-
-## Execution order (never reorder)
-
-```
-Phase 0 → Phase 1 → [Phase 2 → 3 → 4] per app → Phase 5 → Phase 6 → Phase 7
-```
-
-- Phase 1 (schema) must complete for **all apps** before Phase 2/3/4 begins — all `app_key` values must be known first
-- Phase 5 (portal) runs after **all** Phase 4 views are created — `view_key` values must be available
-- Phase 6 (data) runs after Phase 5 — fields and flows must be live before inserting records
-
----
-
-## Phase 0 — Scan workspace packages
-
-```json
-{"tool_name": "package_list", "arguments": {"profile": "default"}}
-```
-
-- **Package name already exists in workspace** → tell the user, wait for explicit confirmation before continuing
-- **Package name not in workspace** → run `package_apply` immediately, no confirmation needed:
-
-```json
-{
-  "tool_name": "package_apply",
-  "arguments": {
-    "profile": "default",
-    "package_name": "客户管理系统",
-    "create_if_missing": true
-  }
-}
+```text
+package_apply
+-> app_schema_apply(apps[] with fields, relations, form.sections)
+-> app_views_apply(views[])
+-> portal_apply(sections[] with inline QingBI chart)
+-> workflow / associated resources only when requested or required
+-> readback + publish/visibility summary
 ```
 
-Record the returned `package_id`. All subsequent phases use it.
-
----
+This is the only recommended chain for a new complete system. Do not split it into separate app creates, separate layout writes, or separate chart creation before portal.
 
-## Phase 1 — Create all apps and fields in one call
+## Required Shape
 
-> **Read first**: [update-schema.md](./update-schema.md)
+- Create or resolve the package with `package_apply` / `package_get`.
+- Create all related apps in one `app_schema_apply(package_id=..., apps=[...])`.
+- Every app item must include stable `client_key`, `app_name`, `icon`, `color`, `add_fields`, and exactly one readable `as_data_title: true`.
+- Put form layout directly in `apps[].form.sections`. Do not make `app_layout_apply` a standard second step for new apps.
+- Same-call relations must use `target_app_ref` pointing to another `apps[].client_key`.
+- Use `target_app_key` only for an app that already exists and has been confirmed by readback.
+- Do not create platform fields: `数据ID`, `编号`, `申请人`, `申请时间`, `创建人`, `创建时间`, `提交人`, `提交时间`, `更新时间`, `更新人`, `当前流程状态`, `当前处理人`, `当前处理节点`, `流程标题`.
 
-### Field count requirement
-
-**12–20 fields per app.** Distribute across types:
-
-| Type | Count per app | Examples |
-|------|--------------|---------|
-| `text` / `long_text` | 2–3 | 名称、编号、描述 |
-| `single_select` / `multi_select` | 2–4 | 状态、类型、优先级、阶段 |
-| `date` / `datetime` | 1–2 | 开始日期、截止日期 |
-| `number` / `amount` | 1–3 | 金额、数量、完成率 |
-| `member` | 1–2 | 负责人、创建人 |
-| `attachment` | 0–1 | 封面图或附件 |
-| `relation` | 1–2 | 跨表关联字段 |
-
-### Hard rules
-
-- Exactly one top-level field per app must have `as_data_title: true`
-- Every `relation` field must include both `display_field: {"name": "..."}` and `visible_fields: [{"name": "..."}]` — missing either causes `VALIDATION_ERROR` and the entire batch fails with `write_executed=false`; read the `message` field verbatim first before guessing at other causes
-- Use `target_app_ref` to reference another app in the same batch by its `client_key`; do not create apps separately and patch relations later
-- If part of the batch fails, only resubmit the failed apps by `row_number`; do not resubmit the entire batch
-
-### Example (customer + opportunity system)
+## Schema Payload Pattern
 
 ```json
 {
-  "tool_name": "app_schema_apply",
-  "arguments": {
-    "profile": "default",
-    "package_id": 1218950,
-    "create_if_missing": true,
-    "publish": true,
-    "apps": [
-      {
-        "client_key": "customer",
-        "app_name": "客户",
-        "add_fields": [
-          {"name": "客户名称", "type": "text", "required": true, "as_data_title": true},
-          {"name": "客户编号", "type": "text"},
-          {"name": "客户类型", "type": "single_select", "options": ["企业", "个人", "政府"]},
-          {"name": "行业", "type": "single_select", "options": ["制造业", "互联网", "金融", "零售", "其他"]},
-          {"name": "客户状态", "type": "single_select", "options": ["潜在", "跟进中", "已签约", "流失"]},
-          {"name": "负责人", "type": "member"},
-          {"name": "联系人", "type": "text"},
-          {"name": "联系电话", "type": "phone"},
-          {"name": "所在地区", "type": "address"},
-          {"name": "首次合作日期", "type": "date"},
-          {"name": "累计合同金额", "type": "amount"},
-          {"name": "客户简介", "type": "long_text"},
-          {"name": "客户封面", "type": "attachment", "as_data_cover": true}
-        ]
-      },
-      {
-        "client_key": "opportunity",
-        "app_name": "商机",
-        "add_fields": [
-          {"name": "商机名称", "type": "text", "required": true, "as_data_title": true},
-          {"name": "关联客户", "type": "relation", "target_app_ref": "customer",
-           "display_field": {"name": "客户名称"}, "visible_fields": [{"name": "客户名称"}, {"name": "客户类型"}]},
-          {"name": "商机阶段", "type": "single_select", "options": ["初步接触", "需求确认", "方案报价", "商务谈判", "赢单", "输单"]},
-          {"name": "预计金额", "type": "amount"},
-          {"name": "赢单概率", "type": "number"},
-          {"name": "负责人", "type": "member"},
-          {"name": "预计成交日期", "type": "date"},
-          {"name": "商机来源", "type": "single_select", "options": ["官网", "转介绍", "市场活动", "电话开发", "其他"]},
-          {"name": "竞争对手", "type": "text"},
-          {"name": "跟进记录", "type": "long_text"},
-          {"name": "优先级", "type": "single_select", "options": ["高", "中", "低"]},
-          {"name": "创建日期", "type": "date"}
+  "package_id": 123,
+  "apps": [
+    {
+      "client_key": "customer",
+      "app_name": "客户",
+      "icon": "user-group",
+      "color": "blue",
+      "add_fields": [
+        {"name": "客户名称", "type": "text", "as_data_title": true},
+        {"name": "客户状态", "type": "select", "options": ["潜在", "跟进中", "已成交"]},
+        {"name": "负责人", "type": "member"}
+      ],
+      "form": {
+        "sections": [
+          {"title": "基础信息", "rows": [["客户名称", "客户状态"], ["负责人"]]}
         ]
       }
-    ]
-  }
-}
-```
-
-Record all `app_key` values from the response. Do not proceed to Phase 2 until all apps show `status: created`.
-
----
-
-## Phase 2 — Per-app: Layout
-
-> **Read first**: [update-layout.md](./update-layout.md)
-
-Run for each app in sequence. Group fields into logical sections with 2–3 fields per row.
-
-```json
-{
-  "tool_name": "app_layout_apply",
-  "arguments": {
-    "profile": "default",
-    "app_key": "APP_KEY",
-    "mode": "merge",
-    "publish": true,
-    "sections": [
-      {
-        "title": "基础信息",
-        "rows": [
-          ["客户名称", "客户编号"],
-          ["客户类型", "行业"],
-          ["客户状态", "负责人"]
+    },
+    {
+      "client_key": "opportunity",
+      "app_name": "商机",
+      "icon": "business-trend-up",
+      "color": "green",
+      "add_fields": [
+        {"name": "商机名称", "type": "text", "as_data_title": true},
+        {
+          "name": "关联客户",
+          "type": "relation",
+          "target_app_ref": "customer",
+          "display_field": {"name": "客户名称"},
+          "visible_fields": [{"name": "客户名称"}, {"name": "客户状态"}]
+        },
+        {"name": "商机阶段", "type": "select", "options": ["初步接触", "方案报价", "赢单", "输单"]},
+        {"name": "预计金额", "type": "amount"}
+      ],
+      "form": {
+        "sections": [
+          {"title": "基础信息", "rows": [["商机名称", "关联客户"], ["商机阶段", "预计金额"]]}
         ]
-      },
-      {
-        "title": "联系信息",
-        "rows": [
-          ["联系人", "联系电话"],
-          ["所在地区"]
-        ]
-      },
-      {
-        "title": "业务数据",
-        "rows": [
-          ["首次合作日期", "累计合同金额"],
-          ["客户简介"]
-        ]
-      }
-    ]
-  }
-}
-```
-
----
-
-## Phase 3 — Per-app: Flow
-
-> **Read first**: [update-flow.md](./update-flow.md) and [flow-actors-and-permissions.md](./flow-actors-and-permissions.md)
-
-Run for each app. Search for an existing role first; create one if none fits.
-
-```json
-{"tool_name": "role_search", "arguments": {"profile": "default", "query": "审批"}}
-```
-
-```json
-{
-  "tool_name": "app_flow_apply",
-  "arguments": {
-    "profile": "default",
-    "app_key": "APP_KEY",
-    "preset": "basic_approval",
-    "publish": true,
-    "nodes": [
-      {
-        "id": "approve_1",
-        "type": "approve",
-        "name": "主管审批",
-        "assignees": {"role_names": ["部门主管"]},
-        "permissions": {"editable_fields": ["客户状态"]}
       }
-    ]
-  }
+    }
+  ]
 }
 ```
 
----
-
-## Phase 4 — Per-app: Views (multiple types)
+Agent-friendly field type aliases are allowed: `multiline -> long_text`, `select -> single_select`, `amount -> amount`. Readback may show canonical types; do not treat that as a mismatch.
 
-> **Read first**: [update-views.md](./update-views.md)
+## Views
 
-Build all applicable view types for each app in one `app_views_apply` call. All views require `query_conditions` with `enabled: true`.
-
-| Type | Build condition | Key config |
-|------|----------------|------------|
-| **table** | Always — build first | `columns` + `query_conditions` on title / status / date / member fields |
-| **board** | App has a `single_select` status or stage field | `group_by` = that field name |
-| **gantt** | App has two date fields | `start_field` + `end_field` |
-| **card** | App has an `attachment` field with `as_data_cover: true` | Visual browsing; same `query_conditions` |
+- Use one `app_views_apply(views=[...])` batch for same-app and cross-app views.
+- Do not create platform default views named `全部数据`, `我的数据`, `我发起的`, `待办`, `已办`, or `抄送`.
+- Use business-specific view names.
+- If a view needs business actions, put them directly inside that view item with `action_buttons`.
+- Keep `filters` and `query_conditions` separate:
+  - `filters`: fixed saved filters.
+  - `query_conditions`: frontend query panel fields.
 
 ```json
 {
-  "tool_name": "app_views_apply",
-  "arguments": {
-    "profile": "default",
-    "app_key": "APP_KEY",
-    "publish": true,
-    "upsert_views": [
-      {
-        "name": "全部客户",
-        "type": "table",
-        "columns": ["客户名称", "客户类型", "客户状态", "负责人", "首次合作日期", "累计合同金额"],
-        "query_conditions": {
-          "enabled": true,
-          "exact": false,
-          "hide_before_query": false,
-          "rows": [["客户名称", "客户类型"], ["客户状态", "负责人"]]
-        }
-      },
-      {
-        "name": "客户看板",
-        "type": "board",
-        "columns": ["客户名称", "客户类型", "负责人", "累计合同金额"],
-        "group_by": "客户状态",
-        "query_conditions": {
-          "enabled": true,
-          "exact": false,
-          "hide_before_query": false,
-          "rows": [["客户名称", "负责人"]]
-        }
+  "views": [
+    {
+      "operation": "upsert",
+      "app_key": "CUSTOMER_APP_KEY",
+      "name": "客户跟进视图",
+      "type": "table",
+      "columns": ["客户名称", "客户状态", "负责人"],
+      "query_conditions": {
+        "enabled": true,
+        "rows": [["客户名称", "客户状态"], ["负责人"]]
       },
-      {
-        "name": "客户卡片",
-        "type": "card",
-        "columns": ["客户名称", "客户类型", "客户状态", "负责人"],
-        "query_conditions": {
-          "enabled": true,
-          "exact": false,
-          "hide_before_query": false,
-          "rows": [["客户名称", "客户状态"]]
+      "action_buttons": [
+        {
+          "text": "新建商机",
+          "action": "add_data",
+          "target_app_key": "OPPORTUNITY_APP_KEY",
+          "placement": "detail",
+          "field_mappings": [
+            {"source_field": "数据ID", "target_field": "关联客户"}
+          ]
         }
-      }
-    ]
-  }
+      ]
+    }
+  ]
 }
 ```
 
-Record all `view_key` values from the response before proceeding to Phase 5.
-
----
-
-## Phase 5 — Charts + Portal
-
-> **Read first**: [tool-selection.md — portal_apply section](./tool-selection.md)
+## Portal
 
-### 5.1 Build charts — 8 total
+Use `portal_apply` only after apps and view keys are read back. QingBI charts for the portal are created inline in `sections[].chart`; do not pre-create charts as a separate standard step.
 
-**4 indicator cards + 4 visual charts.** Build via `app_charts_apply` per app and record all `chart_id` values before calling `portal_apply`.
+Portal layout rules:
 
-| Row | Count | Type | Examples |
-|-----|-------|------|---------|
-| Indicator row | 4 | `target`（指标卡） | 客户总数、商机总金额、赢单数、合同总额 |
-| Visual row 1 | 2 | `funnel` / `columnar` | 商机阶段漏斗、客户类型分布 |
-| Visual row 2 | 2 | `area` / `columnar` | 月度商机趋势、合同金额趋势 |
-
-### 5.2 Portal layout
-
-```
-y=0,  rows=4: 九宫格业务入口 (cols=24)
-y=4,  rows=3: 指标1(x=0,cols=6) 指标2(x=6,cols=6) 指标3(x=12,cols=6) 指标4(x=18,cols=6)
-y=7,  rows=8: 可视化图1(x=0,cols=12) 可视化图2(x=12,cols=12)
-y=15, rows=8: 可视化图3(x=0,cols=12) 可视化图4(x=12,cols=12)
-y=23, rows=8: 数据视图 (cols=24)
-```
-
-Same-row rule: all components at the same `y` must have identical `rows` and `cols` summing to 24.
+- PC grid has 24 columns.
+- Components in the same row must share the same `y` and `rows`.
+- Same-row `cols` should sum to 24.
+- Recommended order: business entry -> metric cards -> BI charts -> concrete data views.
+- Business entry `grid` must contain real `config.items[]`; never submit an empty grid container.
+- Metric cards: `rows=5`.
+- BI charts: `rows=7`.
+- Data views: `rows=11`.
+- Do not use platform default views such as `全部数据` / `我的数据` as main portal data views.
 
 ```json
-{
-  "tool_name": "portal_apply",
-  "arguments": {
-    "profile": "default",
-    "package_id": 1218950,
-    "dash_name": "客户管理工作台",
-    "publish": true,
-    "sections": [
-      {
-        "title": "业务入口",
-        "source_type": "grid",
-        "position": {"pc": {"x": 0, "y": 0, "cols": 24, "rows": 4}, "mobile": {"x": 0, "y": 0, "cols": 6, "rows": 4}},
-        "config": {"gridTitle": "业务入口", "beingShowTitle": true}
-      },
-      {
-        "title": "客户总数",
-        "source_type": "chart",
-        "position": {"pc": {"x": 0, "y": 4, "cols": 6, "rows": 3}, "mobile": {"x": 0, "y": 4, "cols": 6, "rows": 3}},
-        "chart_ref": {"app_key": "CUSTOMER_APP_KEY", "chart_id": "INDICATOR_CHART_ID_1"}
-      },
-      {
-        "title": "商机总金额",
-        "source_type": "chart",
-        "position": {"pc": {"x": 6, "y": 4, "cols": 6, "rows": 3}, "mobile": {"x": 0, "y": 7, "cols": 6, "rows": 3}},
-        "chart_ref": {"app_key": "OPPORTUNITY_APP_KEY", "chart_id": "INDICATOR_CHART_ID_2"}
-      },
-      {
-        "title": "赢单数",
-        "source_type": "chart",
-        "position": {"pc": {"x": 12, "y": 4, "cols": 6, "rows": 3}, "mobile": {"x": 0, "y": 10, "cols": 6, "rows": 3}},
-        "chart_ref": {"app_key": "OPPORTUNITY_APP_KEY", "chart_id": "INDICATOR_CHART_ID_3"}
-      },
-      {
-        "title": "合同总额",
-        "source_type": "chart",
-        "position": {"pc": {"x": 18, "y": 4, "cols": 6, "rows": 3}, "mobile": {"x": 0, "y": 13, "cols": 6, "rows": 3}},
-        "chart_ref": {"app_key": "CONTRACT_APP_KEY", "chart_id": "INDICATOR_CHART_ID_4"}
-      },
-      {
-        "title": "商机阶段漏斗",
-        "source_type": "chart",
-        "position": {"pc": {"x": 0, "y": 7, "cols": 12, "rows": 8}, "mobile": {"x": 0, "y": 16, "cols": 6, "rows": 8}},
-        "chart_ref": {"app_key": "OPPORTUNITY_APP_KEY", "chart_id": "VISUAL_CHART_ID_1"}
-      },
-      {
-        "title": "客户类型分布",
-        "source_type": "chart",
-        "position": {"pc": {"x": 12, "y": 7, "cols": 12, "rows": 8}, "mobile": {"x": 0, "y": 24, "cols": 6, "rows": 8}},
-        "chart_ref": {"app_key": "CUSTOMER_APP_KEY", "chart_id": "VISUAL_CHART_ID_2"}
-      },
-      {
-        "title": "月度商机趋势",
-        "source_type": "chart",
-        "position": {"pc": {"x": 0, "y": 15, "cols": 12, "rows": 8}, "mobile": {"x": 0, "y": 32, "cols": 6, "rows": 8}},
-        "chart_ref": {"app_key": "OPPORTUNITY_APP_KEY", "chart_id": "VISUAL_CHART_ID_3"}
-      },
-      {
-        "title": "合同金额趋势",
-        "source_type": "chart",
-        "position": {"pc": {"x": 12, "y": 15, "cols": 12, "rows": 8}, "mobile": {"x": 0, "y": 40, "cols": 6, "rows": 8}},
-        "chart_ref": {"app_key": "CONTRACT_APP_KEY", "chart_id": "VISUAL_CHART_ID_4"}
-      },
-      {
-        "title": "客户列表",
-        "source_type": "view",
-        "position": {"pc": {"x": 0, "y": 23, "cols": 24, "rows": 8}, "mobile": {"x": 0, "y": 48, "cols": 6, "rows": 8}},
-        "view_ref": {"app_key": "CUSTOMER_APP_KEY", "view_key": "CUSTOMER_TABLE_VIEW_KEY"}
-      }
-    ]
+[
+  {
+    "title": "业务入口",
+    "source_type": "grid",
+    "position": {
+      "pc": {"x": 0, "y": 0, "cols": 24, "rows": 4},
+      "mobile": {"x": 0, "y": 0, "cols": 6, "rows": 4}
+    },
+    "config": {
+      "items": [
+        {"type": 1, "jumpMode": 1, "linkAppKey": "CUSTOMER_APP_KEY", "linkFormType": 1, "title": "客户"},
+        {"type": 1, "jumpMode": 1, "linkAppKey": "OPPORTUNITY_APP_KEY", "linkFormType": 1, "title": "商机"}
+      ]
+    }
+  },
+  {
+    "title": "客户总数",
+    "source_type": "chart",
+    "role": "metric",
+    "position": {
+      "pc": {"x": 0, "y": 4, "cols": 6, "rows": 5},
+      "mobile": {"x": 0, "y": 4, "cols": 6, "rows": 5}
+    },
+    "chart": {
+      "app_key": "CUSTOMER_APP_KEY",
+      "name": "客户总数",
+      "chart_type": "target",
+      "metric": "count(*)"
+    }
+  },
+  {
+    "title": "客户状态分布",
+    "source_type": "chart",
+    "position": {
+      "pc": {"x": 0, "y": 9, "cols": 8, "rows": 7},
+      "mobile": {"x": 0, "y": 9, "cols": 6, "rows": 7}
+    },
+    "chart": {
+      "app_key": "CUSTOMER_APP_KEY",
+      "name": "客户状态分布",
+      "chart_type": "bar",
+      "group_by": ["客户状态"],
+      "metric": "count(*)"
+    }
+  },
+  {
+    "title": "客户跟进视图",
+    "source_type": "view",
+    "position": {
+      "pc": {"x": 0, "y": 16, "cols": 12, "rows": 11},
+      "mobile": {"x": 0, "y": 16, "cols": 6, "rows": 11}
+    },
+    "view_ref": {"app_key": "CUSTOMER_APP_KEY", "view_key": "CUSTOMER_VIEW_KEY"}
   }
-}
+]
 ```
 
----
+## Optional Resources
 
-## Phase 6 — Sample data
+Only add workflow or associated resources when the user asks for them or the business process cannot work without them.
 
-> **Hand off to `qingflow-record-insert` skill**. Read the record-insert skill docs before inserting.
+- Workflow: use `app_flow_apply` after schema fields exist.
+- Associated resources: use `app_associated_resources_apply` after target views/charts exist.
 
-**Insertion order**: insert apps with no inbound relation dependencies first. If App A has a relation field pointing to App B, insert B's records before A — otherwise the relation field has no candidates.
+Do not create workflow just to make the system look complete.
 
-Per app: insert **3–5 records** covering different status values and realistic business data.
+## Recovery
 
-```json
-{"tool_name": "record_insert_schema_get", "arguments": {"profile": "default", "app_key": "APP_KEY"}}
-```
+- Timeout, `partial_success`, `write_executed=true`, `safe_to_retry=false`, or incomplete readback means write state is uncertain, not definitely failed.
+- Next action is always readback: package -> app resolve -> fields/views/portal as needed.
+- Retry only verified missing or incorrect slices.
+- Do not create `V2`, `测试`, timestamp, or random-suffix apps to bypass conflicts.
+
+## Final Summary
+
+Before final response, write `tmp/qingflow_system_build_summary.json` and make the response match it:
 
 ```json
 {
-  "tool_name": "record_insert",
-  "arguments": {
-    "profile": "default",
-    "app_key": "APP_KEY",
-    "items": [
-      {"客户名称": "上海科技有限公司", "客户类型": "企业", "客户状态": "已签约", "负责人": "张三", "累计合同金额": 1200000},
-      {"客户名称": "北京创新集团", "客户类型": "企业", "客户状态": "跟进中", "负责人": "李四", "累计合同金额": 500000},
-      {"客户名称": "广州贸易公司", "客户类型": "企业", "客户状态": "潜在", "负责人": "王五", "累计合同金额": 0},
-      {"客户名称": "深圳数字科技", "客户类型": "企业", "客户状态": "跟进中", "负责人": "张三", "累计合同金额": 300000},
-      {"客户名称": "杭州云计算公司", "客户类型": "企业", "客户状态": "已签约", "负责人": "李四", "累计合同金额": 800000}
-    ]
-  }
+  "package_id": 0,
+  "package_name": "",
+  "portal_dash_key": "",
+  "portal_live_status": "verified | unverified | not_created",
+  "front_end_visible": true,
+  "apps": [],
+  "warnings": [],
+  "partial_items": [],
+  "needs_followup": []
 }
 ```
 
-Member, department, and relation fields accept natural language values — do not look up IDs manually.
-
----
-
-## Phase 7 — Publish verify
+Final response must state:
 
-Run `app_publish_verify` with `app_keys[]` for all apps in one call. Confirm `publish_status` is live and `unplaced_fields` is empty for each.
-
-```json
-{"tool_name": "app_publish_verify", "arguments": {"profile": "default", "app_keys": ["APP_KEY_1", "APP_KEY_2"]}}
+```text
+已完成：...
+未完成/未验证：...
+前端可见：是/否/未确认
+需要继续修复：是/否；原因...
 ```
-
----
-
-## Common failures
-
-| Error | Phase | Fix |
-|-------|-------|-----|
-| `VALIDATION_ERROR` on relation field | 1 | Read `message` verbatim first. Add `display_field` + `visible_fields` to the failing relation field. |
-| Partial app batch failure | 1 | Only resubmit failed apps by `row_number`. Do not resubmit the entire batch. |
-| `UNKNOWN_LAYOUT_FIELD` | 2 | Re-read fields with `app_get_fields`. Field name in `rows` must match exactly. |
-| `FLOW_ASSIGNEE_REQUIRED` | 3 | Run `role_search` first. Assign at least one role to every approve/fill node. |
-| `FLOW_DEPENDENCY_MISSING` | 3 | Fix schema first, then retry flow. |
-| View `partial_success` | 4 | Check `verification.view_query_conditions_verified`. Read `views_diff.failed`. |
-| Portal height mismatch or blank space | 5 | All components at the same `y` must have identical `rows` and `cols` summing to 24. |
-| `PORTAL_CHART_CARD_TOO_SMALL` | 5 | Indicator cards: `rows ≥ 3`. Visual charts: `rows ≥ 6`. |
-| Relation field has no candidates on insert | 6 | The referenced app has no records yet. Insert that app's records first, then retry. |