@josephyan/qingflow-cli 1.1.4 → 1.1.5

package/skills/qingflow-cli/reference/builder/reference/legacy-playbooks/build-complete-system.md

@@ -0,0 +1,809 @@
+# 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
+
+> CLI-only note: this is the payload from former internal surface `package_list`. Execute it through the matching `qingflow` CLI command and `--*-file` flags from SKILL.md / builder reference; do not call internal tool JSON.
+
+- **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:
+
+> CLI-only note: this is the payload from former internal surface `package_apply`. Execute it through the matching `qingflow` CLI command and `--*-file` flags from SKILL.md / builder reference; do not call internal tool JSON.
+
+```json
+{
+  "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**: [30-schema-fields.md](../../30-schema-fields.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)
+
+> CLI-only note: this is the payload from former internal surface `app_schema_apply`. Execute it through the matching `qingflow` CLI command and `--*-file` flags from SKILL.md / builder reference; do not call internal tool JSON.
+
+```json
+{
+  "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**: [40-layout.md](../../40-layout.md)
+
+Run for each app in sequence. Group fields into logical sections with 2–3 fields per row.
+
+> CLI-only note: this is the payload from former internal surface `app_layout_apply`. Execute it through the matching `qingflow` CLI command and `--*-file` flags from SKILL.md / builder reference; do not call internal tool JSON.
+
+```json
+{
+  "app_key": "APP_KEY",
+  "mode": "merge",
+  "publish": true,
+  "sections": [
+    {
+      "title": "基础信息",
+      "rows": [
+        [
+          "客户名称",
+          "客户编号"
+        ],
+        [
+          "客户类型",
+          "行业"
+        ],
+        [
+          "客户状态",
+          "负责人"
+        ]
+      ]
+    },
+    {
+      "title": "联系信息",
+      "rows": [
+        [
+          "联系人",
+          "联系电话"
+        ],
+        [
+          "所在地区"
+        ]
+      ]
+    },
+    {
+      "title": "业务数据",
+      "rows": [
+        [
+          "首次合作日期",
+          "累计合同金额"
+        ],
+        [
+          "客户简介"
+        ]
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## Phase 3 — Per-app: Flow
+
+> **Read first**: [90-workflow.md](../../90-workflow.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.
+
+> CLI-only note: this is the payload from former internal surface `role_search`. Execute it through the matching `qingflow` CLI command and `--*-file` flags from SKILL.md / builder reference; do not call internal tool JSON.
+
+```json
+{
+  "query": "审批"
+}
+```
+
+> CLI-only note: this is the payload from former internal surface `app_flow_apply`. Execute it through the matching `qingflow` CLI command and `--*-file` flags from SKILL.md / builder reference; do not call internal tool JSON.
+
+```json
+{
+  "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**: [50-views.md](../../50-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` |
+
+> CLI-only note: this is the payload from former internal surface `app_views_apply`. Execute it through the matching `qingflow` CLI command and `--*-file` flags from SKILL.md / builder reference; do not call internal tool JSON.
+
+```json
+{
+  "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.
+
+> CLI-only note: this is the payload from former internal surface `portal_apply`. Execute it through the matching `qingflow` CLI command and `--*-file` flags from SKILL.md / builder reference; do not call internal tool JSON.
+
+```json
+{
+  "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
+
+> **Use CLI record insert rules**: read [record/insert](../../../record/insert/README.md) before inserting sample data.
+
+**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.
+
+> CLI-only note: this is the payload from former internal surface `qingflow record schema insert`. Execute it through the matching `qingflow` CLI command and `--*-file` flags from SKILL.md / builder reference; do not call internal tool JSON.
+
+```json
+{
+  "app_key": "APP_KEY"
+}
+```
+
+> CLI-only note: this is the payload from former internal surface `record_insert`. Execute it through the matching `qingflow` CLI command and `--*-file` flags from SKILL.md / builder reference; do not call internal tool JSON.
+
+```json
+{
+  "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.
+
+> CLI-only note: this is the payload from former internal surface `app_publish_verify`. Execute it through the matching `qingflow` CLI command and `--*-file` flags from SKILL.md / builder reference; do not call internal tool JSON.
+
+```json
+{
+  "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. |