@josephyan/qingflow-cli 1.1.3 → 1.1.5

package/skills/qingflow-cli/reference/builder/reference/legacy-playbooks/build-single-app.md

@@ -0,0 +1,830 @@
+# Build Single App（单应用完整搭建）
+
+Use this when the user wants to set up one Qingflow app end-to-end: a rich field schema, grouped layout, approval flow, multiple view types, custom action buttons, in-app charts, associated reports on views, and sample data.
+
+**Signal phrases**: "创建一个应用"、"帮我搭一个XX管理"、"从零开始建一个XX表单"、"我需要一个管理XX的应用"
+
+For a multi-app system with cross-app relations and a portal dashboard, use [20-build-complete-system.md](../../20-build-complete-system.md) instead.
+
+---
+
+## Execution order (never reorder)
+
+```
+Phase 0 → Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 5 → Phase 6 → Phase 7 → Phase 8 → Phase 9
+ Package   Schema   Layout    Flow      Views    Buttons   Charts  Assoc.   Data    Verify
+                                                                   Res.
+```
+
+- Phase 4 (views) must complete before Phase 7 (associated resources) — `view_key` values must be known first
+- Phase 6 (charts) must complete before Phase 7 (associated resources) — `chart_id`/`chart_key` values must be known first
+- Phase 8 (data) runs after all config phases — fields, flow, and views must be live
+
+---
+
+## 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 exists in workspace** → tell the user, wait for explicit confirmation before adding the app into it
+- **Package name not in workspace** → create 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 — Schema (15–20 fields)
+
+> **Read first**: [30-schema-fields.md](../../30-schema-fields.md)
+
+### Field type distribution
+
+| Type | Count | Examples |
+|------|-------|---------|
+| `text` | 2–3 | 名称、编号、联系人 |
+| `long_text` | 1–2 | 描述、摘要、备注 |
+| `single_select` | 2–3 | 状态、类型、优先级 |
+| `multi_select` | 1–2 | 标签、关联业务线 |
+| `date` / `datetime` | 2–3 | 签署日期、生效日期、到期日期 |
+| `amount` | 1–2 | 合同金额、已付金额 |
+| `number` | 1–2 | 期限（月）、完成率（%） |
+| `member` | 2 | 负责人、审核人 |
+| `department` | 0–1 | 所属部门 |
+| `phone` | 0–1 | 联系电话 |
+| `attachment` | 1 | 附件（`as_data_cover: true` for cover display） |
+
+### Hard rules
+
+- Exactly one field must have `as_data_title: true`
+- `as_data_cover: true` requires `type: attachment`
+- No `relation` fields in a single-app build — use [20-build-complete-system.md](../../20-build-complete-system.md) if cross-app links are needed
+- `single_select`/`multi_select` fields must include an `options` array
+
+### Example — 合同管理
+
+> 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": "contract",
+      "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": "multi_select",
+          "options": [
+            "重点客户",
+            "续签",
+            "新签",
+            "框架协议"
+          ]
+        },
+        {
+          "name": "签署日期",
+          "type": "date"
+        },
+        {
+          "name": "生效日期",
+          "type": "date"
+        },
+        {
+          "name": "到期日期",
+          "type": "date"
+        },
+        {
+          "name": "合同金额",
+          "type": "amount"
+        },
+        {
+          "name": "已付金额",
+          "type": "amount"
+        },
+        {
+          "name": "付款比例",
+          "type": "number"
+        },
+        {
+          "name": "合同期限（月）",
+          "type": "number"
+        },
+        {
+          "name": "负责人",
+          "type": "member"
+        },
+        {
+          "name": "法务审核人",
+          "type": "member"
+        },
+        {
+          "name": "所属部门",
+          "type": "department"
+        },
+        {
+          "name": "甲方联系人",
+          "type": "text"
+        },
+        {
+          "name": "甲方联系电话",
+          "type": "phone"
+        },
+        {
+          "name": "合同内容摘要",
+          "type": "long_text"
+        },
+        {
+          "name": "合同附件",
+          "type": "attachment",
+          "as_data_cover": true
+        }
+      ]
+    }
+  ]
+}
+```
+
+Record the returned `app_key`. All subsequent phases use it.
+
+---
+
+## Phase 2 — Layout
+
+> **Read first**: [40-layout.md](../../40-layout.md)
+
+Group fields into 3–4 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": [
+        [
+          "负责人",
+          "法务审核人"
+        ],
+        [
+          "所属部门"
+        ]
+      ]
+    },
+    {
+      "title": "对方信息与附件",
+      "rows": [
+        [
+          "甲方联系人",
+          "甲方联系电话"
+        ],
+        [
+          "合同内容摘要"
+        ],
+        [
+          "合同附件"
+        ]
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## Phase 3 — Flow
+
+> **Read first**: [90-workflow.md](../../90-workflow.md) and [flow-actors-and-permissions.md](./flow-actors-and-permissions.md)
+
+Search for roles first; create only 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": [
+          "合同状态",
+          "合同内容摘要"
+        ]
+      }
+    },
+    {
+      "id": "approve_2",
+      "type": "approve",
+      "name": "负责人确认",
+      "assignees": {
+        "role_names": [
+          "部门主管"
+        ]
+      },
+      "permissions": {
+        "editable_fields": [
+          "合同状态"
+        ]
+      }
+    }
+  ]
+}
+```
+
+---
+
+## Phase 4 — Views (multiple types)
+
+> **Read first**: [50-views.md](../../50-views.md)
+
+Build all applicable view types in one call. All views require `query_conditions` with `enabled: true`.
+
+| Type | Build condition | Key config |
+|------|----------------|------------|
+| **table** | Always — build first | `columns` covering title/status/date/amount/member |
+| **board** | App has a `single_select` status or stage field | `group_by` = that field name |
+| **gantt** | App has 2+ date fields | `start_field` + `end_field` |
+| **card** | App has `attachment` with `as_data_cover: true` | Visual browsing |
+| **calendar** | App has a key due/expiry date field | `date_field` = that field name |
+
+> 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": "gantt",
+      "columns": [
+        "合同名称",
+        "合同状态",
+        "负责人",
+        "合同金额"
+      ],
+      "start_field": "生效日期",
+      "end_field": "到期日期",
+      "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": [
+          [
+            "合同名称",
+            "合同状态"
+          ]
+        ]
+      }
+    },
+    {
+      "name": "到期日历",
+      "type": "calendar",
+      "columns": [
+        "合同名称",
+        "合同类型",
+        "合同金额",
+        "负责人"
+      ],
+      "date_field": "到期日期",
+      "query_conditions": {
+        "enabled": true,
+        "exact": false,
+        "hide_before_query": false,
+        "rows": [
+          [
+            "合同名称",
+            "合同状态"
+          ]
+        ]
+      }
+    }
+  ]
+}
+```
+
+Record all `view_key` values before Phase 7.
+
+---
+
+## Phase 5 — Custom Buttons
+
+> Call `qingflow --json builder contract --tool-name app_custom_buttons_apply` if the exact button schema is unclear.
+> `app_custom_buttons_apply` publishes automatically — do **not** pass `publish`.
+
+Build 2–3 buttons. Common patterns for a single app:
+
+| Button | Trigger type | Placement | When to use |
+|--------|-------------|-----------|-------------|
+| 快捷创建子记录 | `add_data` | header, detail | When a related app exists in the same package |
+| 外部跳转 | `link` | header, list | Always applicable — jump to external URL or doc |
+| 列表行操作 | `add_data` / `link` | list | Row-level quick action in table view |
+
+**Example — link button (always applicable) + add-data button (requires a related app):**
+
+> CLI-only note: this is the payload from former internal surface `app_custom_buttons_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",
+  "upsert_buttons": [
+    {
+      "name": "查看合同模板",
+      "trigger_type": "link",
+      "style": "default",
+      "placements": [
+        "header",
+        "detail"
+      ],
+      "trigger_link_config": {
+        "url": "https://your-template-url"
+      }
+    },
+    {
+      "name": "发起变更申请",
+      "trigger_type": "add_data",
+      "style": "primary",
+      "placements": [
+        "header",
+        "detail",
+        "list"
+      ],
+      "trigger_add_data_config": {
+        "target_app_key": "CHANGE_REQUEST_APP_KEY",
+        "field_mappings": [
+          {
+            "source_field": "数据ID",
+            "target_field": "关联合同"
+          },
+          {
+            "source_field": "合同名称",
+            "target_field": "合同标题"
+          },
+          {
+            "source_field": "负责人",
+            "target_field": "申请人"
+          }
+        ]
+      }
+    }
+  ],
+  "view_configs": [
+    {
+      "view_key": "TABLE_VIEW_KEY",
+      "mode": "merge",
+      "buttons": [
+        "发起变更申请",
+        "查看合同模板"
+      ]
+    }
+  ]
+}
+```
+
+**Notes:**
+- `placements: ["list"]` maps to the backend row-level `INSIDE` position
+- `view_configs[].buttons` is required in merge mode — do not send a view config with only `view_key`
+- `source_field: "数据ID"` passes the current record's ID to the target relation field
+- If this app has no related app, skip the add-data button and use the link button only
+- Use raw `view_key` from `app_get.views[].view_key`; do not prefix with `custom:`
+
+---
+
+## Phase 6 — Charts
+
+> `app_charts_apply` is immediate-live — no publish step. Record all returned `chart_id`/`chart_key` values before Phase 7.
+
+Build 2–4 charts: 2 indicator cards + 1 distribution chart + 1 trend chart.
+
+> CLI-only note: this is the payload from former internal surface `app_charts_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",
+  "upsert_charts": [
+    {
+      "name": "合同总金额",
+      "chart_type": "target",
+      "config": {
+        "measure_field": "合同金额",
+        "aggregate": "SUM"
+      }
+    },
+    {
+      "name": "有效合同数",
+      "chart_type": "target",
+      "config": {
+        "filter": {
+          "合同状态": [
+            "已生效"
+          ]
+        },
+        "aggregate": "COUNT"
+      }
+    },
+    {
+      "name": "合同状态分布",
+      "chart_type": "columnar",
+      "config": {
+        "dimension_field": "合同状态",
+        "measure_field": "合同金额",
+        "aggregate": "SUM"
+      }
+    },
+    {
+      "name": "月度签约趋势",
+      "chart_type": "area",
+      "config": {
+        "dimension_field": "签署日期",
+        "time_granularity": "month",
+        "measure_field": "合同金额",
+        "aggregate": "SUM"
+      }
+    }
+  ]
+}
+```
+
+---
+
+## Phase 7 — Associated Resources
+
+Attach charts to the app's view area so users can see them inline without leaving the app.
+
+Before running `upsert_resources`, check existing resources with the dedicated read tool:
+
+> CLI-only note: this is the payload from former internal surface `app_get_associated_resources`. 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"
+}
+```
+
+If the result already contains the target chart, use `patch_resources` with its `associated_item_id` instead of re-upserting.
+
+> CLI-only note: this is the payload from former internal surface `app_associated_resources_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",
+  "upsert_resources": [
+    {
+      "client_key": "res_status_chart",
+      "resource_type": "chart",
+      "chart_key": "CHART_KEY_FOR_STATUS_DISTRIBUTION",
+      "display_name": "合同状态分布"
+    },
+    {
+      "client_key": "res_trend_chart",
+      "resource_type": "chart",
+      "chart_key": "CHART_KEY_FOR_TREND",
+      "display_name": "月度签约趋势"
+    }
+  ],
+  "view_configs": [
+    {
+      "view_key": "TABLE_VIEW_KEY",
+      "associated_item_refs": [
+        "res_status_chart",
+        "res_trend_chart"
+      ]
+    }
+  ]
+}
+```
+
+**Notes:**
+- `app_associated_resources_apply` publishes automatically — do **not** pass `publish`
+- `client_key` is a same-call alias only; repeated `upsert_resources` without `associated_item_id` creates duplicates
+- On subsequent edits, use `patch_resources` with `associated_item_id` instead
+
+---
+
+## Phase 8 — Sample Data
+
+> **Use CLI record insert rules**: read [record/insert](../../../record/insert/README.md) before inserting sample data.
+
+Insert **5–8 records** covering all status values and realistic amounts. Call `qingflow record schema insert` first.
+
+> 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": [
+    {
+      "合同名称": "上海科技服务协议",
+      "合同编号": "HT-2024-001",
+      "合同类型": "服务合同",
+      "合同状态": "已生效",
+      "合同金额": 580000,
+      "已付金额": 290000,
+      "负责人": "张三",
+      "签署日期": "2024-01-15",
+      "生效日期": "2024-02-01",
+      "到期日期": "2025-01-31",
+      "优先级": "高",
+      "合同期限（月）": 12
+    },
+    {
+      "合同名称": "北京采购框架合同",
+      "合同编号": "HT-2024-002",
+      "合同类型": "采购合同",
+      "合同状态": "审批中",
+      "合同金额": 1200000,
+      "已付金额": 0,
+      "负责人": "李四",
+      "签署日期": "2024-03-10",
+      "生效日期": "2024-04-01",
+      "到期日期": "2025-03-31",
+      "优先级": "高",
+      "合同期限（月）": 12
+    },
+    {
+      "合同名称": "广州运维服务合同",
+      "合同编号": "HT-2024-003",
+      "合同类型": "服务合同",
+      "合同状态": "已生效",
+      "合同金额": 240000,
+      "已付金额": 120000,
+      "负责人": "王五",
+      "签署日期": "2024-02-20",
+      "生效日期": "2024-03-01",
+      "到期日期": "2024-12-31",
+      "优先级": "中",
+      "合同期限（月）": 10
+    },
+    {
+      "合同名称": "深圳保密协议",
+      "合同编号": "HT-2024-004",
+      "合同类型": "保密协议",
+      "合同状态": "已生效",
+      "合同金额": 0,
+      "已付金额": 0,
+      "负责人": "张三",
+      "签署日期": "2024-04-05",
+      "生效日期": "2024-04-05",
+      "到期日期": "2027-04-04",
+      "优先级": "中",
+      "合同期限（月）": 36
+    },
+    {
+      "合同名称": "杭州合作开发合同",
+      "合同编号": "HT-2024-005",
+      "合同类型": "服务合同",
+      "合同状态": "草稿",
+      "合同金额": 850000,
+      "已付金额": 0,
+      "负责人": "李四",
+      "签署日期": "2024-05-01",
+      "生效日期": "2024-06-01",
+      "到期日期": "2025-05-31",
+      "优先级": "高",
+      "合同期限（月）": 12
+    },
+    {
+      "合同名称": "成都劳务外包合同",
+      "合同编号": "HT-2023-006",
+      "合同类型": "劳务合同",
+      "合同状态": "已到期",
+      "合同金额": 360000,
+      "已付金额": 360000,
+      "负责人": "王五",
+      "签署日期": "2023-01-01",
+      "生效日期": "2023-01-01",
+      "到期日期": "2023-12-31",
+      "优先级": "低",
+      "合同期限（月）": 12
+    }
+  ]
+}
+```
+
+Member and department fields accept natural language values — do not look up IDs manually.
+
+---
+
+## Phase 9 — Publish Verify
+
+> 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_key": "APP_KEY"
+}
+```
+
+Confirm `publish_status` is live and `unplaced_fields` is empty. If `unplaced_fields` is non-empty, run `app_layout_apply` to place them before reporting completion.
+
+---
+
+## Common failures
+
+| Error | Phase | Fix |
+|-------|-------|-----|
+| `VALIDATION_ERROR` on select field | 1 | `single_select`/`multi_select` must include `options` array |
+| `UNKNOWN_LAYOUT_FIELD` | 2 | Re-read with `app_get_fields`; field name in `rows` must match exactly |
+| `FLOW_ASSIGNEE_REQUIRED` | 3 | Run `role_search` first; every approve/fill node must have at least one assignee |
+| View `partial_success` | 4 | Check `verification.view_query_conditions_verified`; read `views_diff.failed` |
+| `calendar` view rejected | 4 | Build calendar only when a date field exists; verify field type |
+| Button `view_configs` blocked | 5 | `buttons` array is required in merge mode; do not send a view config with only `view_key` |
+| Button add-data fails — no related app | 5 | Skip add-data button; use link button only |
+| Chart config rejected | 6 | Call `qingflow --json builder contract --tool-name app_charts_apply` for exact field/aggregate schema |
+| Associated resource duplicate | 7 | Check `app_get.associated_resources` first; use `patch_resources` with `associated_item_id` if already exists |
+| `unplaced_fields` non-empty on verify | 9 | Run `app_layout_apply` to place the missing fields, then re-verify |