@josephyan/qingflow-app-builder-mcp 1.1.4 → 1.1.5

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

@@ -1,428 +0,0 @@
-# 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.
-
-**Signal phrases**: "建一套系统"、"包含 X 个模块"、"这几个表单之间建立关联"、"完整的业务系统"
-
-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
-  }
-}
-```
-
-Record the returned `package_id`. All subsequent phases use it.
-
----
-
-## Phase 1 — Create all apps and fields in one call
-
-> **Read first**: [update-schema.md](./update-schema.md)
-
-### 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)
-
-```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"}
-        ]
-      }
-    ]
-  }
-}
-```
-
-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": [
-          ["客户名称", "客户编号"],
-          ["客户类型", "行业"],
-          ["客户状态", "负责人"]
-        ]
-      },
-      {
-        "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)
-
-> **Read first**: [update-views.md](./update-views.md)
-
-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` |
-
-```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": [["客户名称", "负责人"]]
-        }
-      },
-      {
-        "name": "客户卡片",
-        "type": "card",
-        "columns": ["客户名称", "客户类型", "客户状态", "负责人"],
-        "query_conditions": {
-          "enabled": true,
-          "exact": false,
-          "hide_before_query": false,
-          "rows": [["客户名称", "客户状态"]]
-        }
-      }
-    ]
-  }
-}
-```
-
-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)
-
-### 5.1 Build charts — 8 total
-
-**4 indicator cards + 4 visual charts.** Build via `app_charts_apply` per app and record all `chart_id` values before calling `portal_apply`.
-
-| 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.
-
-```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"}
-      }
-    ]
-  }
-}
-```
-
----
-
-## Phase 6 — Sample data
-
-> **Hand off to `qingflow-record-insert` skill**. Read the record-insert skill docs before inserting.
-
-**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.
-
-Per app: insert **3–5 records** covering different status values and realistic business data.
-
-```json
-{"tool_name": "record_insert_schema_get", "arguments": {"profile": "default", "app_key": "APP_KEY"}}
-```
-
-```json
-{
-  "tool_name": "record_insert",
-  "arguments": {
-    "profile": "default",
-    "app_key": "APP_KEY",
-    "items": [
-      {"客户名称": "上海科技有限公司", "客户类型": "企业", "客户状态": "已签约", "负责人": "张三", "累计合同金额": 1200000},
-      {"客户名称": "北京创新集团", "客户类型": "企业", "客户状态": "跟进中", "负责人": "李四", "累计合同金额": 500000},
-      {"客户名称": "广州贸易公司", "客户类型": "企业", "客户状态": "潜在", "负责人": "王五", "累计合同金额": 0},
-      {"客户名称": "深圳数字科技", "客户类型": "企业", "客户状态": "跟进中", "负责人": "张三", "累计合同金额": 300000},
-      {"客户名称": "杭州云计算公司", "客户类型": "企业", "客户状态": "已签约", "负责人": "李四", "累计合同金额": 800000}
-    ]
-  }
-}
-```
-
-Member, department, and relation fields accept natural language values — do not look up IDs manually.
-
----
-
-## Phase 7 — Publish verify
-
-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"]}}
-```
-
----
-
-## 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. |