@qingflow-tech/qingflow-cli 1.1.49 → 1.1.50-beta.2

package/skills/qingflow-cli/reference/builder/reference/app-delivery-sop.md

@@ -201,8 +201,8 @@ qingflow builder schema apply \
 - 如果返回 `MULTI_APP_STATIC_VALIDATION_FAILED`，读取 `details.issues[]` 的 `path/error_code/fix_hint` 修 payload；这是写入前失败，通常可以修正后重试，不需要 readback。
 - 多应用 schema apply 不做事务回滚；如果部分失败，只补失败的 `apps[].row_number`，不要整批重复提交。
 - 这个模式只负责应用壳与字段；视图、按钮、关联资源、报表仍拿返回的 `app_key` 继续走各自 apply 工具。
-- `target_app_ref`、`as_data_title`、`display_field` 等只属于旧载荷。迁移时将关系改写为 AppForm `config.targetAppKey`、`config.displayField`、`config.visibleFields`，并使用已确认的真实 app key。
-- 历史 schema adapter 写入后可读 `details.relation_readback_matrix[]`：逐项核对旧 `target_app_key`、`relation_mode`、`display_field`、`visible_fields`。迁移到当前 AppForm 后，改为读取 draft/published form 的 `config.targetAppKey`、`config.relationMode`、`config.displayField`、`config.visibleFields`，不要提交旧 `update_fields` patch。
+- `target_app_ref`、`as_data_title`、`display_field` 等只属于旧载荷。迁移时将关系改写为 AppForm `config.targetAppKey`、`config.displayFields[]`（含 `auth`）、`config.twoWayBoundField`，并使用已确认的真实 app key。
+- 历史 schema adapter 写入后可读 `details.relation_readback_matrix[]`：逐项核对旧 `target_app_key`、`relation_mode`、`display_field`、`visible_fields`。迁移到当前 AppForm 后，改为读取 draft/published form 的 `config.targetAppKey`、`config.relationMode`、`config.twoWayBoundField`、`config.displayFields[]`，不要提交旧 `update_fields` patch。
 - 一个应用可以包含多个 `relation` 字段；不要因为 relation 数量超过 1 就降级成文本。若真实写入失败或 relation readback mismatch，只按实际错误和 `details.relation_repair_plan[]` 做最小修复。
 - 完整系统遇到超时、`partial_success`、`write_executed=true`、`safe_to_retry=false` 或 readback 不完整时，先按 §3.4 读回，不要直接拆成单应用创建。
 
@@ -349,7 +349,7 @@ qingflow builder flow apply \
 | **`address`** | 地址复合字段。 |
 | **`attachment`** | 附件。 |
 | **`boolean`** | 是否。 |
-| **`relation`** | 旧载荷使用 `target_app_key` / `target_app_ref`；当前 AppForm 使用 `config.targetAppKey`、`config.relationMode`、`config.displayField`、`config.visibleFields`。 |
+| **`relation`** | 旧载荷使用 `target_app_key` / `target_app_ref`；当前 AppForm 使用 `config.targetAppKey`、`config.relationMode`、`config.twoWayBoundField`、`config.displayFields[]`。 |
 | **`subtable`** | 当前 AppForm 使用 `subfields[]` 及 Schema 返回的 camelCase 配置；旧 `subfield_updates` 只作迁移线索。 |
 | **`q_linker`** | 当前 AppForm 使用 `config.qLinkerBinding`，其 `outputs[].targetField` 必须按字段 Schema 配置。 |
 | **`code_block`** | 当前 AppForm 使用 `config.codeBlockBinding`，其 `outputs[].targetField` 必须按字段 Schema 配置。 |

package/skills/qingflow-cli/reference/builder/workflow/03-flow-patterns.md

@@ -27,14 +27,22 @@ n1 → n2 → g1 ──┤
 ```
 
 **关键点**：
-- 分支起点必须是 `gateway`（`mode: parallel`），终点必须是 `gateway`（`mode: join`）
-- 每条分支边都需要配置 `condition`，其中至少一条为 `kind: rules` 带 `autoJudges`
-- 没有条件的边使用 `kind: default` 作为兜底
-- 所有分支并行进入，条件只决定分支内逻辑是否执行，不存在"条件匹配就跳过其他分支"的互斥语义
+- 分支起点必须是 `gateway`（`mode: parallel`）；需要汇合时使用 `gateway`（`mode: join`）。
+- join 必须有至少 2 条入边、恰好 1 条出边。`GET` 根据 legacy 路径终点共享目标的拓扑合成 `id=join_<目标id>`；`apply` 将其折叠回拓扑，不生成独立 legacy 节点。
+- join 出边目标节点的 `sync` 表达等待语义；并行路径汇合通常应设 `sync: true`，写面按 spec 原值保真。
+- join 的 `name` / `role` / `enabled` / `sync` 不持久化；规范值为 `name: "Join"`, `enabled: true`, `sync: false`。
+- 每条分支边都需要配置 `condition`，其中至少一条为 `kind: rules` 带 `autoJudges`。
+- 没有条件的边使用 `kind: default` 作为兜底。
+- 所有分支并行进入，条件只决定分支内逻辑是否执行，不存在"条件匹配就跳过其他分支"的互斥语义。
 
 ## 循环/回退
 
-**轻流工作流引擎不支持循环结构**。不要通过 gateway 或其他方式构建回到前序节点的环。
+**轻流工作流引擎的环判定口径**（与后端 apply 校验一致）：
+
+- **禁止自环**：任何节点不得有指向自身的边（A→A），会被后端 `INVALID_FLOW_TOPOLOGY`（G2）拒绝。
+- **无根纯环拒绝**：不经 gateway 的纯环（如 A→B→A）映射后无根节点，被 G1 拒绝。
+- **经 gateway 回指的驳回环合法**：approval→gateway→approval 形态（分叉回退边）是引擎合法形态，离线与后端均不做通用 DAG 无环检查。
+- **单节点流程合法**：仅 applicant 节点 + 空边（`edges.edges=[]`）是新建表单的自然形态，提交即结束。
 
 如需回退到前序节点重新处理，应使用审批节点的回退开关：
 

package/skills/qingflow-cli/reference/builder/workflow/07-stage4-validate-spec.md

@@ -17,13 +17,15 @@ python3 scripts/workflow/validate_flow_spec.py \
 ## 验证内容
 
 1. JSON Schema 结构校验（基于 `qingflow builder flow schema` 的官方 schema）
-2. DAG 无环检查
+2. 边结构检查：边端点存在于 nodes、禁止自环（与后端 G2/G4 口径镜像；经 gateway 回指的驳回环合法，不做通用无环检查）
 3. 单 applicant 节点检查
 4. Gateway 出边条件完整性检查（rules 边必须有 autoJudges）
-5. 审批/填写/抄送节点必要字段检查
+5. 审批/填写/抄送节点必要字段检查（含 responsible/receivers 非空）
 6. 自动化节点配置检查
 7. 孤立节点检查
-8. 入口节点和需要继续路由的节点显式 `sync: true`
+8. 入口节点和需要继续路由的节点显式 `sync: true`（单节点流程——仅 applicant 无出边——合法，降为警告：提交即结束）
+
+注：单节点流程（仅 applicant + 空边数组）是新建表单的自然形态，结构与语义检查均放行；多节点流程要求 edges 非空。
 
 ## 验证不通过时的处理
 

package/skills/qingflow-cli/reference/builder/workflow/08-stage5-apply-verify.md

@@ -26,7 +26,7 @@ qingflow --json builder flow apply \
 
 - `status: success` → 进入验证
 - `status: failed` → 查看 `error_code` / `message` / `blocking_issues`，修正后重试
-- `missing_input_node_ids` 警告（新建时常见）→ 可忽略，是正常现象
+- `status: partial_success` + `MISSING_INPUT_NODE` 警告（新建时常见，`missing_input_node_ids` 非空）→ 属预期：首次 apply 节点 id 由后端重分配，**不要忽略**，执行 5.2 的 `builder flow get` 回读确认节点已落库后即可继续
 - 成功写入应读取 `write_executed=true`、`write_succeeded=true`、`safe_to_retry=false`；不要因中间读回 pending 立刻重放。
 
 ## 5.2 验证部署结果

package/skills/qingflow-cli/reference/builder/workflow/11-troubleshooting.md

@@ -6,7 +6,7 @@
 |------|------|------|
 | `autoJudges` apply 后为空 | 使用了一维数组 `[{...}]` 格式 | 改为二维 `[[{...}]]` |
 | 条件分支不生效 | `autoJudges` 中的 `values` 与表单选项 label 不一致 | 核对字段选项文本，确保完全一致 |
-| apply 返回 `missing_input_node_ids` | 新建 flow 首次 apply 的正常提示 | 可忽略，再次 get 验证即可 |
+| apply 返回 `partial_success` + `MISSING_INPUT_NODE`（`missing_input_node_ids` 非空） | 提交节点未出现在 appliedSpec：新建 flow 首次 apply 节点 id 会被后端重分配，属预期 | **不要忽略**；`builder flow get` 回读 spec 确认节点已落库（拓扑完整）即可视为成功，无需重试 |
 | 录入数据后只留下“提交申请”日志，不进入下一节点 | WorkflowSpec 入口节点没有出边，或入口/路由节点缺少 `sync: true` | `builder flow get` 读回 spec，确认 applicant 出边和节点 `sync`，修正后用 `--spec-file` 发布 |
 | 回退边（gateway → 前序节点）不生效 | 引擎不支持通过 gateway 实现回退 | 改用审批节点 `revert: true` |
 | 审批节点无审批人 | `responsible` 中的 UID/角色 ID 无效或缺失 | 使用 `builder member search` / `role search` 确认 |