@qingflow-tech/qingflow-cli 1.1.33 → 1.1.35

package/skills/qingflow-cli/reference/builder/reference/legacy-playbooks/README.md

@@ -1,308 +0,0 @@
-# Qingflow CLI App Builder Playbooks
-
-## Overview
-
-This section is for the current **public builder surface** through `qingflow builder ...`, not for legacy low-level builder writes.
-
-Before any write or verification flow, identify whether the task targets `test` or `prod` and read [environments.md](./environments.md). If the user did not specify one, default to `prod`.
-
-Before choosing a route, skim the shared maintenance baseline: [public-surface-sync.md](./public-surface-sync.md).
-
-## CLI-only Execution Rule
-
-Examples in this directory are CLI payload examples and workflow notes. Execute through the matching `qingflow` command from [SKILL.md](../../../../SKILL.md), the command index, or the canonical builder reference files; do not call internal tool JSON.
-
-## Current Public Mental Model
-
-Model builder requests in four layers and keep them separate:
-
-- `package`: the app bundle or solution container
-- `app`: one form/app inside that package
-- `field`: one field inside one app
-- `relation`: a field that links one app to another app
-
-Default modeling rules:
-
-- One business object -> one app
-- Attributes of that object -> fields inside that app
-- Another business object -> a separate app, not a text field
-- Cross-object links -> relation fields, not text fields
-
-## Public Tools You Should Think In
-
-- Package: `qingflow builder package get/apply`
-- App reads: `qingflow builder app resolve/get`, including batch `--app-keys`
-- Builder reads: `qingflow builder portal/view/chart/contract`
-- Directory: `qingflow builder member/role`
-- Writes: `qingflow builder schema/layout/flow/views/button/associated-resource/charts/portal apply`
-- Verification: `qingflow builder publish verify`
-
-Treat these as the official surface. Do not default to `package_create`, `package_attach_app`, raw `portal_*` writes, or raw `qingbi_report_*` writes.
-
-## Current Public Defaults
-
-- Package work:
-  - use `package_get(package_id=...)` to read one known package
-  - use `package_apply(...)` for package creation, rename, icon, visibility, grouping, ordering, and app/portal layout
-- Multi-app schema work:
-  - use one CLI `builder schema apply --apps-file` when creating several apps in one package
-  - same-call relation fields may use `target_app_ref` to point at another `apps[].client_key`
-- Batch reads:
-  - `builder app get`, `button get`, `associated-resource get`, and `publish verify` accept `--app-keys`
-  - when reading several apps, prefer one batch read and inspect both `apps[]` and `errors[]`
-- Batch writes:
-  - `builder layout/views/button/associated-resource/charts apply --apps-file` accepts multi-app batch writes
-  - each `apps[]` item carries its own `app_key` plus that tool's normal single-app payload
-- App base permissions:
-  - trust `app_get.editability.can_edit_app_base` for app base-info writes like app name, icon, and visibility
-  - `can_edit_form` only means schema/form-route capability; it no longer implies app base-info write capability
-- Partial update rule:
-  - for existing views, custom buttons, associated resources, and charts, prefer `patch_views` / `patch_buttons` / `patch_resources` / `patch_charts`
-  - for existing workflow nodes, use `builder flow apply --patch-nodes-file` instead of rewriting the full `spec`
-  - for existing portal sections, use `builder portal apply --patch-sections-file` instead of replacing all `sections`
-  - each patch item uses the object's real selector field (`view_key` / `button_id` / `associated_item_id` / `chart_id`, or unique name where supported) plus `set` and optional `unset`; do not send a literal `selector` key for these tools
-  - use `upsert_*` for creation or full target configuration; do not send a partial `upsert_*` and expect the backend to merge missing required fields
-- Portal work:
-  - `portal_apply` is the public write path
-  - in edit mode, omitting `sections` means “preserve existing layout and update base info only”
-  - supplying `sections` means full replace semantics for sections
-  - portal sections use a 24-column PC grid; all components sharing the same `y` coordinate must have identical `rows` values and their `cols` must sum to exactly 24; mixing `rows` in the same row causes height misalignment, and a `cols` sum under 24 leaves blank space at the row end; the next row's `y` must equal the previous row's `y` + `rows`
-  - standard workbench heights: metric cards `rows=5`, BI charts `rows=7`, data views `rows=11`
-  - business-entry grid sections must include real `config.items[]`; do not submit an empty grid container
-- Chart work:
-  - `app_charts_apply` is the public write path for app-source QingBI report bodies/configs; it creates/updates reports with `dataSourceType=qingflow`
-  - dataset BI reports are not created or edited by `app_charts_apply` yet; create them in QingBI first, then attach the existing report with `app_associated_resources_apply` and `report_source="dataset"`
-  - it does not attach the report to the Qingflow app associated-resource display; use `app_associated_resources_apply` for that
-  - choose chart type by goal: `target/indicator` for one KPI, `bar/columnar/pie` for distribution, `line/area` for trend, `table/detail/summary` for tabular summaries, `dualaxes` for two-metric comparison
-  - use semantic metrics: `count(*)`, `sum(金额)`, `avg(工时)`, `group_by`, `where`; do not handwrite raw `indicator_field_ids`, `selectedMetrics`, or QingBI filter matrices on the main path
-  - supported `chart_type` values include legacy public aliases `target`, `table` and QingBI types such as `summary`, `columnar`, `area`, `stacked_area`, `funnel`, `waterfall`, `gauge`, `heatmap`, `histogram`, `treemap`, `radar`, `stacked_bar`, `stacked_column`, `scatter`, `ring`, `rose`, `dualaxes`, `map`, and `timeline`
-  - use `patch_charts` for changing a chart name, visibility, filters, or one config fragment on an existing chart
-  - `visibility` is a public capability and should be treated as a base-only permission update
-  - do not model chart visibility changes as raw config rewrites
-- Button work:
-  - ordinary view-specific buttons should be declared through `app_views_apply.action_buttons`
-  - `app_custom_buttons_apply` is for advanced button maintenance: style/icon changes, cross-view reuse, deleting button bodies, bulk binding reorder, or exact qRobot/wings configs
-  - use `patch_buttons` for changing a single existing button parameter such as URL, text, icon, style, or add-data mapping
-  - action choice:
-    - current record -> downstream/child record: use `add_data` in view `action_buttons`, or `addData` in standalone buttons, with `target_app_key + field_mappings`
-    - global independent create: use `add_data`/`addData` on `header` without current-record `source_field`
-    - SOP/external/fixed page: use `link` with `url`
-    - existing automation only: use `qRobot`/`wings` only when the user provides exact config
-    - approval/status transition/close task is not a generic button action; model workflow/task action first, or use existing automation. Do not fake it with `link`
-  - for add-data buttons, use `trigger_add_data_config.target_app_key + field_mappings/default_values`; do not handwrite raw `que_relation`
-  - use `field_mappings` for dynamic current-record values, including system fields such as `数据ID` (`field_id=-17`) and `编号` (`field_id=0`)
-  - to prefill a target relation field with the current source record, map `{"source_field": "数据ID", "target_field": "目标引用字段"}`; use `default_values` only for static constants
-  - if field type compatibility is unclear, read [match-rules.md](./match-rules.md)
-  - placement choice: `header` is global and has no current-row context; `list` is row/list action and maps to backend `INSIDE`; `detail` is the safest current-record context action. Do not use current-record `field_mappings` on `header`
-  - bind advanced standalone buttons to views through `view_configs[].buttons[]`; default to `placement`: `header` or `detail`
-  - builder `view_configs[].view_key` uses the raw key from `app_get.views[].view_key`, without a `custom:` prefix
-  - `buttons` is required in merge mode; do not send a view config with only `view_key`
-  - `view_configs[].mode` defaults to `merge`; use `mode: "replace"` or an explicit empty `buttons: []` to clear a view's custom button bindings
-  - `placement=list` configures row/list buttons and maps to the backend `INSIDE` button position
-  - advanced bindings may use `button_limit`, `button_formula`, `button_formula_type`, and `print_tpls` only when visibility or print-template behavior is required
-- Associated resources:
-  - `app_associated_resources_apply` is the public write path for the Qingflow app-level associated report/view pool and per-view display config
-  - for multi-app systems, use `apps[]` to batch associated-resource writes; each item carries its own `app_key` plus `upsert_resources` / `patch_resources` / `view_configs`
-  - it attaches existing BI reports/views for in-app display; it does not create or edit QingBI report bodies/configs, including dataset reports
-  - use `patch_resources` for changing match rules or other existing associated-resource parameters; the tool preserves backend-required raw fields internally
-  - `associated_item_id` is the backend internal associated-resource id; for `view_configs`, `remove_associated_item_ids`, and `reorder_associated_item_ids`, you may pass `associated_item_id` or an existing resource's `chart_id`/`chart_key`/`view_key`, and the tool resolves it to the internal id
-  - before creating a resource, check `app_get.associated_resources` for the same `target_app_key + view_key/chart_key`; if it already exists, use `patch_resources` with that `associated_item_id`
-  - `client_key` is only a same-call reference for `view_configs[].associated_item_refs`; it is not saved and cannot deduplicate later calls
-  - do not pass backend raw `sourceType`; view resources infer the internal Qingflow view source, report/chart resources default to BI app reports, and existing dataset reports use `report_source="dataset"`
-  - use `match_mappings` for associated view/report filters; dynamic conditions use `source_field`, static conditions use `value`
-  - if field type compatibility is unclear, read [references/match-rules.md](./match-rules.md)
-- Views and flows:
-  - stay on `app_views_apply` / `app_flow_apply`
-  - use `patch_views` for existing-view parameter changes such as `query_conditions`, `filters`, `columns`, or visibility
-  - builder view writes use raw `view_key` values from `app_get.views`; `custom:<viewKey>` is a record-data `view_id` form, not a builder `view_key`
-  - use `qingflow --json builder contract` whenever the minimal legal shape is unclear
-  - keep view `filters` and `query_conditions` separate: `filters` are fixed saved filters; `query_conditions` configure the frontend query panel fields and only take effect after users enter query values
-  - when creating any new table or card view, always include `query_conditions` with `enabled: true`; populate `rows` with the fields most useful for searching — typically the data-title field, any status/type select fields, date fields, and member fields; do not omit `query_conditions` or leave `rows` empty on a new view
-  - new views default the associated report/view display area to visible with `limit_type="all"`; existing views preserve their current associated-resource display unless `associated_resources` is explicitly patched
-  - configure associated reports/views through `app_associated_resources_apply`, not through `app_views_apply`
-
-## Standard Operating Order
-
-1. Ensure auth exists
-2. Ensure workspace is selected
-3. Confirm whether the task is read-only or write-impacting
-4. Resolve the smallest stable target:
-   - app-scoped work -> `app_resolve`
-   - package-scoped work with known id -> `package_get`
-   - portal inventory -> `portal_list`
-5. Read only the smallest config slice needed:
-   - app map -> `app_get` (default entry; includes compact views, charts, custom buttons, and associated resource pool)
-   - fields -> `app_get_fields`
-   - layout -> `app_get_layout`
-   - views -> `app_get_views` only when the app_get compact list is not enough
-   - flow -> `app_get_flow`
-   - charts -> `app_get_charts` only when the app_get compact list is not enough
-   - portal -> `portal_get`
-6. If the public shape is unclear, call `qingflow --json builder contract`
-7. Apply the smallest patch tool that fits:
-   - fields -> `app_schema_apply`
-   - layout -> `app_layout_apply`
-   - flow -> `app_flow_apply`
-   - existing views -> `app_views_apply.patch_views`; new/full views -> `app_views_apply.upsert_views`
-   - existing buttons -> `app_custom_buttons_apply.patch_buttons`; new/full buttons -> `app_custom_buttons_apply.upsert_buttons`
-   - existing associated resources -> `app_associated_resources_apply.patch_resources`; new/full resources -> `app_associated_resources_apply.upsert_resources`
-   - existing charts -> `app_charts_apply.patch_charts`; new/full charts -> `app_charts_apply.upsert_charts`
-   - portal -> `portal_apply`
-   - package metadata/layout -> `package_apply`
-8. Use `app_publish_verify` only when the user explicitly wants final publish/live verification or you need a dedicated verification pass
-
-## Safe Usage Rules
-
-- Do not guess package identity from a loose name. Public package work assumes a known `package_id`, or an explicit create/update intent through `package_apply`.
-- If `package_id` is unknown, derive it from related app/portal readback when possible; otherwise ask the user instead of falling back to hidden package lookup tools.
-- Do not use `package_create` or `package_attach_app` as a public default path. If they still appear in low-level code, treat them as internal/legacy implementation details.
-- Do not use raw `portal_*` writes or raw `qingbi_report_*` writes as the default builder strategy.
-- Always pass `publish: true` (or CLI `--publish`) explicitly on `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, `app_views_apply`, and `portal_apply` — do not rely on the default. `app_custom_buttons_apply` and `app_associated_resources_apply` publish automatically after at least one write succeeds and do not accept a `publish` parameter. `app_charts_apply` is immediate-live without a publish step.
-- When creating or updating fields, configure the app data title/cover directly in field JSON: `as_data_title: true` is required on exactly one readable top-level title field; `as_data_cover: true` is optional and only valid on one top-level `attachment` field.
-- When any tool returns `error_code` or `VALIDATION_ERROR`, read the `message` field verbatim first before guessing at parameter or CLI parsing issues. A clear `message` like "relation field requires visible_fields" is the root cause — do not redirect to unrelated hypotheses such as `create_if_missing` parsing or flag conflicts.
-- If the same validation error repeats twice, stop guessing and re-read `qingflow --json builder contract`.
-- For workflow assignees, prefer `role_search` over explicit members unless the user explicitly wants named members.
-- Public flow building is still intentionally limited to stable linear workflows. If a requirement sounds like branches/conditions, explain the limitation instead of freehanding unsupported graph shapes.
-- Respect collaborative edit locks. Only use `app_release_edit_lock_if_mine` when the lock owner is the current authenticated user.
-- If the supported builder surface is still awkward or blocked after reasonable use, summarize the gap, ask whether to submit feedback, and call `feedback_submit` only after explicit user confirmation.
-
-## Response Interpretation
-
-- All builder apply/write tools return a standard UI envelope in addition to legacy fields:
-  `schema_version`, `operation`, `summary`, and `resources[]`.
-- For UI cards or quick narration, read `resources[]` first. Each resource has `resource_type`, `operation`, `status`, `id`, `key`, `name`, typed `ids`, and `parent`.
-- Use legacy fields such as `field_diff`, `views_diff`, `chart_results`, `created/updated/removed`, and `verification` only for compatibility and troubleshooting.
-- Treat post-write readback as the source of truth, not just write status codes.
-- `success` means write and verification completed; `partial_success` means the write landed but verification is incomplete.
-- For portals, distinguish clearly between:
-  - base-info-only update with layout preserved
-  - full sections replace
-  - patching one section with `patch_sections[]`
-  - layout validity: same-row `rows`, same-row `cols` sum, and non-empty grid `items`
-- For object apply tools, distinguish clearly between:
-  - `patch_*`: public partial parameter replacement; the tool hydrates current config and full-saves internally
-  - `upsert_*`: create or full target configuration; omitted fields may mean default/clear depending on that object
-- For charts, distinguish clearly between:
-  - base / visibility change
-  - real chart-config change
-- For app permissions, report `can_edit_app_base` separately from `can_edit_form / can_edit_flow / can_edit_views / can_edit_charts`.
-
-## Practical Patterns
-
-- Read one package: `package_get`
-- Create or update one package: `package_apply`
-- Resolve one app: `app_resolve`
-- Read one app map: `app_get`
-- Batch read app maps/slices: `app_get_*` with `app_keys[]`
-- Read fields only: `app_get_fields`
-- Read layout summary: `app_get_layout`
-- Read views summary: `app_get_views`
-- Read flow summary: `app_get_flow`
-- Read chart summary: `app_get_charts`
-- Read portal config: `portal_get`
-- Search members or roles: `member_search`, `role_search`
-- Create reusable role: `role_create`
-- Add/update/remove fields: `app_schema_apply`
-- Merge or replace layout: `app_layout_apply` (single app) or `apps[]` batch
-- Replace workflow or patch nodes: `app_flow_apply`
-- Upsert/patch/remove views: `app_views_apply` (single app) or `apps[]` batch
-- Upsert/patch/remove views, including ordinary view-specific buttons: `app_views_apply`
-- Advanced custom button maintenance and cross-view binding: `app_custom_buttons_apply` (single app) or `apps[]` batch
-- Upsert/patch/remove app associated reports/views and per-view display: `app_associated_resources_apply`
-- Upsert/patch/remove/reorder charts: `app_charts_apply` (single app) or `apps[]` batch
-- Create, update, or patch portal pages: `portal_apply`
-- Release your own stale edit lock: `app_release_edit_lock_if_mine`
-- Final publish verification: `app_publish_verify`
-
-## Advanced Button Pattern
-
-For ordinary view-specific buttons, prefer `app_views_apply.action_buttons`. Use `app_custom_buttons_apply` only for standalone/advanced maintenance: custom style or icon, cross-view reuse, deleting button bodies, bulk binding reorder, or exact qRobot/wings config.
-
-> 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": "EMPLOYEE_APP",
-  "upsert_buttons": [
-    {
-      "client_key": "add_worklog",
-      "button_text": "快捷添加工时",
-      "style_preset": "primary_blue",
-      "button_icon": "ex-plus-circle",
-      "trigger_action": "addData",
-      "trigger_add_data_config": {
-        "target_app_key": "WORKLOG_APP",
-        "field_mappings": [
-          {
-            "source_field": "数据ID",
-            "target_field": "关联员工"
-          },
-          {
-            "source_field": "员工名称",
-            "target_field": "员工姓名"
-          },
-          {
-            "source_field": "所属部门",
-            "target_field": "部门名称"
-          }
-        ],
-        "default_values": {
-          "工时类型": "日常工作",
-          "状态": "待提交"
-        }
-      }
-    }
-  ],
-  "remove_buttons": [],
-  "view_configs": [
-    {
-      "view_key": "EMPLOYEE_VIEW",
-      "mode": "merge",
-      "buttons": [
-        {
-          "button_ref": "add_worklog",
-          "placement": "detail",
-          "primary": true
-        }
-      ]
-    }
-  ]
-}
-```
-
-`button_ref` may be a same-call `client_key` or an existing `button_id`. Supported placements are `header`, `detail`, and `list`; `list` maps to the backend `INSIDE` row/list button position.
-
-For add-data buttons that create a child record linked back to the current record, map `source_field: "数据ID"` to the target relation field. Do not use raw `que_relation` unless maintaining an existing backend config.
-
-## Historical Playbook Selection
-
-This file is historical supporting material. For the current main route, start from [../../README.md](../../README.md). If you still use this page, route to the current resource document first:
-
-| User intent | Signal phrases | Playbook |
-|-------------|---------------|---------|
-| Multi-app business system with cross-app relations, shared workflow, and a portal dashboard | "建一套系统"、"包含 N 个模块"、"这几个表单之间建立关联"、"完整的业务系统" | [20-build-complete-system.md](../../20-build-complete-system.md) |
-| Single app end-to-end: rich schema, layout, flow, multiple view types, custom buttons, in-app charts, associated resources, and sample data | "建一个应用"、"帮我搭一个XX管理"、"从零开始建一个XX"、"我需要一个管理XX的应用" | [10-build-single-app.md](../../10-build-single-app.md) |
-| Add one new app inside an existing package | "在这个包里加一个表单"、"现有系统里新增一个模块" | [create-app.md](./create-app.md) |
-| Update fields or schema only | "加一个字段"、"改字段名"、"删除字段" | [30-schema-fields.md](../../30-schema-fields.md) |
-| Update layout only | "调整分组"、"改排列顺序" | [40-layout.md](../../40-layout.md) |
-| Update workflow only | "修改审批流"、"加一个审批节点" | [90-workflow.md](../../90-workflow.md) |
-| Update views only | "加一个看板"、"改筛选条件"、"新增视图" | [50-views.md](../../50-views.md) |
-
-Decision rule: if the user mentions **multiple related apps or a portal**, use [20-build-complete-system.md](../../20-build-complete-system.md). If it is **one app** with a from-scratch setup request, use [10-build-single-app.md](../../10-build-single-app.md). If the target app already exists and the user only wants to change one layer, use the matching resource document.
-
-## Resources
-
-- Shared public-surface baseline: [public-surface-sync.md](./public-surface-sync.md)
-- Environment switching: [environments.md](./environments.md)
-- Tool choice and sequencing: [tool-selection.md](./tool-selection.md)
-- Field matching rules: [../match-rules.md](../match-rules.md)
-- Result semantics and gotchas: [gotchas.md](./gotchas.md)
-- Create one app in an existing package: [create-app.md](./create-app.md)
-- Update fields only: [../../30-schema-fields.md](../../30-schema-fields.md)
-- Update layout only: [../../40-layout.md](../../40-layout.md)
-- Update workflow only: [../../90-workflow.md](../../90-workflow.md)
-- Workflow assignees and node permissions: [flow-actors-and-permissions.md](./flow-actors-and-permissions.md)
-- Update views only: [../../50-views.md](../../50-views.md)
-- Standard end-to-end builder sequences: [solution-playbooks.md](./solution-playbooks.md)
-- Build a complete multi-app system from scratch: [../../20-build-complete-system.md](../../20-build-complete-system.md)
-- Build a single app end-to-end: [../../10-build-single-app.md](../../10-build-single-app.md)