@qingflow-tech/qingflow-cli 1.1.2 → 1.1.34

package/skills/qingflow-cli/reference/builder/30-schema-fields.md

@@ -0,0 +1,317 @@
+# Builder Schema And Fields
+
+Read this when the task is about app creation fields, schema updates, field types, data title, data cover, relation fields, or system fields.
+
+## Scope
+
+Responsible for: `builder schema apply`, app creation through `form`, field type aliases, data title/cover, relation field shape, and existing-app schema maintenance.
+
+Not responsible for: standalone form layout operations. For normal app creation, put fields directly under `form` so fields and placement are written together.
+
+## Main chain
+
+```text
+app/package resolve -> schema apply with form -> app get fields/layout readback -> publish/readback verify
+```
+
+For complete systems, use `builder schema apply --apps-file` with `{package_id, apps}` and put each app's fields and form layout under `apps[].form`. For one app, use `--form-file` in create mode. Use `add_fields/update_fields/remove_fields` only for later schema maintenance.
+
+## Demo files
+
+| Scenario | Example |
+|----------|---------|
+| New single app `--form-file` | [schema_single_app_form_standard.example.json](../examples/schema/schema_single_app_form_standard.example.json) |
+| New complete system `--apps-file` | [schema_multi_app_form_relation_layout.example.json](../examples/schema/schema_multi_app_form_relation_layout.example.json) |
+| Existing-app field capability probe | [schema_apply_add_fields_all_types.json](../examples/schema/schema_apply_add_fields_all_types.json) |
+
+## Create app with `form`
+
+`form` is the only recommended creation shape. Each section contains rows; each row contains field objects. For new apps, `form` is both the field schema and the form layout. Do not create a separate `layout` object and do not call `builder layout apply` after app creation just to place those fields.
+
+```json
+[
+  {
+    "section": "基础信息",
+    "rows": [
+      [
+        {"name": "工单编号", "type": "text", "data_title": true},
+        {"name": "产品", "type": "text"},
+        {"name": "状态", "type": "select", "options": ["待排产", "生产中", "已完工"]}
+      ],
+      [
+        {"name": "计划数量", "type": "number"},
+        {"name": "计划完成日期", "type": "date"}
+      ]
+    ]
+  }
+]
+```
+
+Single-app CLI:
+
+```bash
+qingflow --json builder schema apply \
+  --package-id <PACKAGE_ID> \
+  --app-name "生产工单" \
+  --icon table \
+  --color blue \
+  --form-file /abs/path/form.json \
+  > tmp/schema_apply_production_order.json
+```
+
+Complete-system `apps-file` item:
+
+```json
+{
+  "client_key": "production_order",
+  "app_name": "生产工单",
+  "icon": "table",
+  "color": "blue",
+  "form": [
+    {
+      "section": "基础信息",
+      "rows": [[{"name": "工单编号", "type": "text", "data_title": true}]]
+    }
+  ]
+}
+```
+
+Complete-system CLI:
+
+```bash
+qingflow --json builder schema apply \
+  --apps-file /abs/path/apps.json \
+  > tmp/schema_apply_system.json
+```
+
+For the complete-system apps-file, use the object shape below. The same file carries app identity, fields, relation fields, and layout:
+
+```json
+{
+  "package_id": 123456,
+  "apps": [
+    {
+      "client_key": "product",
+      "app_name": "产品台账",
+      "icon": "database",
+      "color": "blue",
+      "form": [
+        {
+          "section": "产品基础信息",
+          "rows": [
+            [
+              {"name": "产品编码", "type": "text", "data_title": true, "required": true},
+              {"name": "产品名称", "type": "text", "required": true},
+              {"name": "产品状态", "type": "select", "options": ["研发中", "量产", "停用"]}
+            ]
+          ]
+        }
+      ]
+    },
+    {
+      "client_key": "production_order",
+      "app_name": "生产工单",
+      "icon": "table",
+      "color": "emerald",
+      "form": [
+        {
+          "section": "工单基础信息",
+          "rows": [
+            [
+              {"name": "工单编号", "type": "text", "data_title": true, "required": true},
+              {
+                "name": "关联产品",
+                "type": "relation",
+                "target_app_ref": "product",
+                "relation_mode": "single",
+                "display_field": {"name": "产品编码"},
+                "visible_fields": [{"name": "产品名称"}, {"name": "产品状态"}]
+              },
+              {"name": "工单状态", "type": "select", "options": ["待排产", "生产中", "已完工"]}
+            ],
+            [
+              {"name": "计划数量", "type": "number"},
+              {"name": "计划完成日期", "type": "date"}
+            ]
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Existing-app schema maintenance only
+
+- Re-read fields before updating; selectors may use `name`, `field_id`, or `que_id`.
+- Switch from `add_fields` to `update_fields` when a field already exists.
+- Use `remove_fields` only when deletion is explicitly intended.
+- If apply returns uncertain write state, re-read fields before retrying.
+- Do not use this section for new complete-system creation. New apps should stay on the `apps[].form` path above.
+
+Example patch:
+
+```json
+{
+  "app_key": "APP_KEY",
+  "publish": true,
+  "add_fields": [{"name": "跟进日期", "type": "date"}],
+  "update_fields": [
+    {
+      "selector": {"name": "金额"},
+      "set": {"name": "订单金额", "required": true}
+    }
+  ],
+  "remove_fields": [{"name": "旧字段"}]
+}
+```
+
+## Field type reference
+
+> **口径**：`field.type` 枚举以 **`qingflow --json builder contract --tool-name app_schema_apply`**（及包内 `PublicFieldType`）为准；**形状校验**以 `qingflow_mcp` 的 **`FieldPatch`**（`builder_facade/models.py`）与 **`app_schema_apply` 编排**（`builder_facade/service.py`）为准。
+> **CLI**：`qingflow [--profile NAME] builder schema apply [--app-key APP_KEY | 创建模式… | --apps-file 多应用对象] [--publish|--no-publish] [--form-file …] [--update-fields-file …] [--remove-fields-file …]`；**`qingflow` 未在 PATH 时**可用 `npx @qingflow-tech/qingflow-cli` 前缀，并把 `--profile` 放在 `builder` 之前。
+> **新建应用主规则**：`form` 里必须有且仅有一个顶层字段标记 `data_title: true`；数据封面可选，只能在顶层 `attachment` 字段标记 `data_cover: true`。
+> **权限**：包内新建应用按后端 `CreateAppBean` 链路只预检目标包 **AddAppAuth**；已有应用的字段/基础信息变更才走应用自身 **EditAppAuth**。
+
+## 0. 字段建模一眼决策表
+
+先按业务语义选字段类型。主路径可以写智能体友好的别名，CLI 会归一化；读回出现 canonical 类型不是失败。
+
+| 业务语义 | 推荐写法 | 注意 |
+| --- | --- | --- |
+| 名称、标题、编号、短文本 | `text` | 新建应用必须且只能有一个顶层可读字段标记 `data_title: true` |
+| 说明、备注、描述、长文本 | `multiline` | 写入归一化为 `long_text`；不要因为读回 `long_text` 而重建字段 |
+| 状态、类型、等级、阶段、是否枚举 | `select` | 写入归一化为 `single_select`；必须同时定义 `options` |
+| 标签、多选项、多个类别 | `multi_select` | `checkbox` 是兼容别名；必须定义 `options` |
+| 数量、比例、分数、工时、百分比、时长 | `number` | 需要小数或计算时优先 `number` |
+| 金额、费用、单价、预算 | `amount` | 只用于货币/金额语义，不要拿它存比例或普通数量 |
+| 日期、计划日、截止日 | `date` | 同时需要时分秒才用 `datetime` |
+| 负责人、审批人、参与人 | `member` | 不要创建“申请人/提交人”等平台系统字段 |
+| 部门、组织 | `department` | 可按需要补 `department_scope` |
+| 图片、文件、附件 | `attachment` | 只有顶层 `attachment` 可标记 `data_cover: true` |
+| 跨应用业务对象关系 | `relation` | 同批应用只用 `target_app_ref`；已存在应用维护才用 `target_app_key`；`display_field` / `visible_fields` 必须写对象选择器 |
+
+禁止创建平台系统字段：`数据ID`、`编号`、`申请人`、`申请时间`、`创建人`、`创建时间`、`提交人`、`提交时间`、`更新时间`、`更新人`、`当前流程状态`、`当前处理人`、`当前处理节点`、`流程标题`。需要引用系统字段时，只在工具明确支持的位置引用，例如按钮 `source_field: "数据ID"`。
+
+---
+
+## 1. 全部 `field.type`（19 种）
+
+与契约一致时，搭建侧 **`add_fields[]` / `update_fields[]`** 可用类型为：
+
+| `type` | 说明（搭建语义） |
+|--------|------------------|
+| `text` | 单行文本 |
+| `long_text` | 多行文本 |
+| `number` | 数字 |
+| `amount` | 金额 |
+| `date` | 日期 |
+| `datetime` | 日期时间 |
+| `member` | 成员 |
+| `department` | 部门（可带 `department_scope`） |
+| `single_select` | 单选 |
+| `multi_select` | 多选 |
+| `phone` | 电话 |
+| `email` | 邮箱 |
+| `address` | 地址 |
+| `attachment` | 附件 |
+| `boolean` | 是否 |
+| `q_linker` | 远程查询 / 数据获取（**`q_linker_binding`**） |
+| `code_block` | 代码块（**`code_block_binding`** + 编译后的 `code_block_config`） |
+| `relation` | 关联记录（**`relation_mode`**：`single` \| `multiple`） |
+| `subtable` | 子表（**`subfields[]`**） |
+
+**`relation_mode`**：仅 **`relation`** 使用，取值为 **`single`** 或 **`multiple`**。一个应用可以有多个 `relation` 字段；不要因为 relation 数量超过 1 就改成文本字段。
+
+### 1.1 智能体友好字段类型别名
+
+主路径可以写更符合直觉的字段类型；工具写入前自动归一化，读回和排障时仍使用 canonical 类型：
+
+| 智能体写法 | canonical 类型 |
+|------------|----------------|
+| `multiline` / `multiline_text` / `textarea` | `long_text` |
+| `select` / `single_choice` / `dropdown` | `single_select` |
+| `multi_select` / `multi_choice` / `multiple_choice` / `checkbox` | `multi_select` |
+
+完整映射以 `builder contract --tool-name app_schema_apply` 的 `$.contract.allowed_values["field.type_aliases"]` 为准。
+
+---
+
+## 2. 按类型的必填 / 常用可选（写意图）
+
+| `type` | 通常必填 | 常见可选 / 约束 |
+|--------|----------|-----------------|
+| 标量与选择器 | `name` + `type`（+ 业务 `required` 等） | `description`、`required`；新建应用时其中一个顶层可读字段须 `data_title: true`；**`single_select` / `multi_select` 的 `options` 可用字符串数组或对象数组**，如 `["A", "B"]` 或 `[{"label":"A","value":"a"}]`，工具会归一化为选项文案 |
+| `department` | 同左 | **`department_scope`**：`mode: all \| custom`；`custom` 时 **`departments[]`**（含 `dept_id` 等） |
+| `relation` | 同批新建：**`target_app_ref`**；已有目标应用维护：**`target_app_key`**；另需 **`display_field`**、**`visible_fields[]`** | **`relation_mode`**；目标应用元数据不可读时可多写 **`name`** 降级 |
+| `subtable` | **`subfields[]` 非空** | 子列递归同父级规则；更新已存在子列优先契约 **`subfield_updates`** |
+| `q_linker` | **`q_linker_binding`**：`inputs`、`request`、**`outputs[]` 每项须含 `target_field`**（能解析到本表单字段） | `request.url` 等须符合**租户/后端远程查询策略**；读回 JSON 可能**缺** `outputs[].target_field`，会导致本地再编译失败（见 §5） |
+| `code_block` | **`code_block_binding`**：`inputs`、`code`、**`outputs[]` + `target_field`**；代码体须能被规范识别 **`qf_output` 赋值** | **`auto_trigger`**、按钮文案；勿与 **`code_block_config.code_content`** 与 **`binding.code`** 冲突 |
+
+别名：契约会把 `title`/`label` 映射到 **`name`** 等；字段类型自然别名见 §1.1。
+
+### 2.1 `relation` 选择器形态
+
+`relation` 的目标应用可以用字符串键，但展示字段选择器必须写对象，不要写裸字符串：
+
+```json
+{
+  "name": "关联产品",
+  "type": "relation",
+  "target_app_ref": "product",
+  "relation_mode": "single",
+  "display_field": {"name": "产品编码"},
+  "visible_fields": [{"name": "产品名称"}, {"name": "产品线"}]
+}
+```
+
+允许的目标应用写法：同批多应用只写 `target_app_ref`，已存在且已读回确认的目标应用才写 `target_app_key`。如果返回 `display_field` / `visible_fields` 的 Pydantic 错误，通常是把选择器写成了字符串；只修这一段字段 payload，不要重建应用或改 app_key。
+
+### 2.2 工作流状态字段
+
+要启用工作流的应用，字段阶段就创建一个明确的业务状态单选字段，例如 `状态`、`处理状态`、`审批状态`、`工单状态`、`计划状态`、`报工状态`、`单据状态`。领域结果字段不等价于流程状态；例如质量场景的 `检验结论` 只能表达结果，仍建议另建 `处理状态` 用于流程节点、视图和报表。
+
+---
+
+## 3. `builder schema apply` 场景矩阵
+
+| 场景 | 必备 CLI 参数 | 说明 |
+|------|----------------|------|
+| 编辑已有应用 | `--app-key`；可选 `--no-publish` | **不要**与 `--package-id` 同用 |
+| 包内新建应用 | `--package-id`、`--app-name`（或 title 映射）、`--form-file` | `form` 内必须有且仅有一个顶层可读字段标记 `data_title: true` |
+| 多应用一次性新建 | `--apps-file`，文件顶层写 `package_id` + `apps`，每个应用写 `apps[].form` | 应用包/系统里有 2 个以上应用，或同批应用之间有 `relation` 时使用；多应用按 `app_name` 直接提交创建，不自动查重或按名称复用；重名/冲突按后端结果和写后读回处理；`apps[].client_key` 被同批 relation 的 `target_app_ref` 引用；不要在主链路使用 raw apps array、singleton wrapper array、单独 layout 或逐个创建后回填 `target_app_key` |
+| 仅增字段 | `--add-fields-file`（JSON 数组） | 与 **`update_fields`/`remove_fields`** 可同次组合（以契约为准） |
+| 改字段 | `--update-fields-file` | 每项 **`selector`**（`name`/`que_id`/`field_id`）+ **`set`** |
+| 删字段 | `--remove-fields-file` | 每项至少 **`name`/`que_id`/`field_id`** 之一 |
+| 可见性（新建/部分元数据） | `--visibility-file` | `mode` / `external_mode` / `selectors` 见交付文 §3.2 |
+| 发布 | 默认或 `--publish`；探针常用 **`--no-publish`** | 与 **`app_publish_verify`** 配合 |
+
+---
+
+## 4. 仓库示例文件（维护参考）
+
+| 内容 | 位置 |
+|------|------|
+| **完整系统新建主示例：多应用 + 同批 relation + form 布局** | [schema_multi_app_form_relation_layout.example.json](../examples/schema/schema_multi_app_form_relation_layout.example.json) |
+| **19 种 `type` + `code_block` + `q_linker` + 1 个 `relation`（字段能力探针，不是新建主模板）** | [schema_apply_add_fields_all_types.json](../examples/schema/schema_apply_add_fields_all_types.json)（用于字段类型覆盖测试；正式新建应用优先用上文 `form`） |
+| **`q_linker_example` / `code_block_example`**（契约内置形状） | `ai_builder_tools.py` 中 `app_schema_apply` 合约 |
+| 最小新建字段（1 个 text 标题字段） | [schema_add_fields_minimal.example.json](../examples/schema/schema_add_fields_minimal.example.json) |
+| 历史 scalar / complex 批测（可选） | [_batch_schema_scalar.json](../examples/schema/_batch_schema_scalar.json)、[_batch_schema_complex.json](../examples/schema/_batch_schema_complex.json) |
+
+---
+
+## 5. 实跑结论
+
+**一次性新建应用**：`--package-id` + `--app-name` + `--form-file` 是当前推荐写法；`form` 同时表达字段和表单分组布局。字段类型覆盖测试文件只用于能力探针，不作为正式业务应用模板。
+
+**一次性新建多个应用**：用 `builder schema apply --apps-file tmp/apps.json`，其中 `tmp/apps.json` 唯一主写法为 `{ "package_id": 123, "apps": [...] }`，每个 `apps[]` 写顶层 `client_key + app_name + icon + color + form`；多应用模式按 `app_name` 直接提交创建，不在工具内查重或按名称复用。若后端返回重名/冲突，或写入结果不确定，先读回应用包和字段，再决定复用、补齐缺失资源或询问用户。`apps[].client_key` 可被同批 relation 字段的 `target_app_ref` 引用，工具会编译成真实 `target_app_key`。CLI 内部会并发创建 app 壳，再并发写入每个 app 的完整 schema；智能体仍只写同一个 `apps-file`。这是应用包/系统搭建的默认路径，尤其适合“商机 + 订单 + 回款”“花名册 + 工时”等互相关联场景；不要为了拿 `app_key` 先逐个创建再二次补关联字段。
+
+**限制（平台硬性）**：`--app-key` 向已有应用追加字段时须 **字段名不重复**；`relation` 字段数量不做“每应用只能一个”的智能体侧限制，按后端实际校验和写后读回为准。**`example.com`** 作 `q_linker` URL 易触发 **`46031`**，本清单改用 httpbin。**读回缺 `outputs[].target_field` 的 `q_linker`** 会拖死后续 `schema apply`，须修复或删除该题。
+
+**排障**：`--json`；**`DUPLICATE_FIELD`**；真实写入失败看 `SCHEMA_APPLY_FAILED` 的 `backend_code`、`details.relation_field_count` 和读回矩阵。
+
+## 6. 交叉引用
+
+- 交付主流程（读场 / 改场 / 发布）：[reference/app-delivery-sop.md](./reference/app-delivery-sop.md)（类型速查与 `relation`/`q_linker`/`code_block` 要点）。
+- 记录读写 `kind`（与搭建 `type` 不同系）：[QINGFLOW_CLI_FIELD_DATA_TYPES.md](../core/QINGFLOW_CLI_FIELD_DATA_TYPES.md)。
+- 主技能：[../SKILL.md](../../SKILL.md)。

package/skills/qingflow-cli/reference/builder/40-layout.md

@@ -0,0 +1,70 @@
+# Builder Layout
+
+Read this only when the task is about repairing or changing the form layout of an existing app.
+
+## Scope
+
+Responsible for: `builder layout apply`, section titles, `rows` matrix, merge/replace mode, and existing-app layout repair.
+
+Not responsible for: creating new apps, adding fields, or complete-system app creation. New apps must put layout directly in `form` through [30-schema-fields.md](./30-schema-fields.md).
+
+Do not read this as part of the normal complete-system creation path. If the app is new, write field objects inside `form[].rows[]` and submit them with `builder schema apply`.
+
+## Main chain
+
+```text
+existing app get fields -> existing app get layout -> prepare sections -> builder layout apply -> readback when needed
+```
+
+## Demo file
+
+Use [layout_sections_full.example.json](../examples/layout/layout_sections_full.example.json) as the existing-app layout maintenance base. Replace `app_key` and field names after reading the app fields.
+
+## Public shape
+
+For existing-app layout maintenance, use section `title + rows`. This is form layout: each `rows[]` item is a row of field names. Do not invent top-level `columns`, and do not use portal `x/y/cols/rows` here.
+
+```json
+{
+  "app_key": "APP_KEY",
+  "mode": "merge",
+  "publish": true,
+  "sections": [
+    {
+      "title": "基础信息",
+      "rows": [
+        ["客户名称", "订单金额"],
+        ["状态", "负责人"]
+      ]
+    }
+  ]
+}
+```
+
+## One-eye form layout rules
+
+| Intent | Correct shape | Avoid |
+| --- | --- | --- |
+| Group fields on a form | `sections[].title + sections[].rows` | Portal `position.pc` / `x` / `y` / `cols` |
+| Put fields on one horizontal form row | `["客户名称", "订单金额"]` inside `rows` | Top-level `columns` |
+| Keep existing layout and add/update groups | `mode: "merge"` | `replace` unless intentionally rewriting everything |
+| Repair missing/unknown field errors | Re-read `app get fields` and remove/correct names | Guessing field ids from old payload |
+
+Short rule: **form layout rows arrange fields; portal rows arrange components. Do not mix the two.**
+
+## Update existing layout
+
+- Prefer `mode: "merge"` unless intentionally replacing the entire layout.
+- Re-read `app get fields` before writing; every field in `rows` must exist.
+- Re-read `app get layout` when apply returns `partial_success` or layout validation details.
+- Batch layout writes are for existing-app maintenance only; each `apps[]` item carries its own `app_key` and layout payload.
+- If you are creating apps, stop and use `builder schema apply --apps-file` with `apps[].form` instead.
+
+## Common failures
+
+| Failure | Action |
+|---------|--------|
+| `UNKNOWN_LAYOUT_FIELD` | Re-read fields and remove or correct the missing field name. |
+| `DUPLICATE_LAYOUT_FIELD` | Keep each field in only one row. |
+| `INCOMPLETE_LAYOUT` | Switch to `merge` unless replacing the whole layout intentionally. |
+| repeated shape errors | Read `builder contract --tool-name app_layout_apply`; reuse the canonical section example. |