宜搭流程规则配置技能

> 资源边界：本技能只处理普通 OpenYida 流程规则配置；目标不明时先只读确认或询问用户。

Resource-First 使用门槛

本技能是已有流程/表单上下文的默认流程修改入口：

• 已有流程表单、processCode、流程 URL、bound process 或可确认的 workflow form 时，审批节点、条件分支、字段权限、抄送、跳转规则等诉求默认使用本技能。
• 已有普通表单 formUuid 且用户要“配置审批 / 转为审批流程”，先确认是否对该表单启用流程；如果只是转流程且尚无流程，可由 yida-create-process --formUuid 复用该表单，不要新建同名表单。
• 没有目标表单/流程，且用户明确从零创建审批系统时，才改用 yida-create-process。
• 多个流程候选按根技能来源优先级选择；同级冲突或无法判断目标流程时才问用户。

严格禁止 (NEVER DO)

• 不要在流程定义中使用猜测的 fieldId，必须先用 yida-get-schema 获取
• 不要在未加载本技能内容的情况下编写流程定义 JSON，格式复杂且易出错
• 不要用此技能创建流程表单，应使用 yida-create-process
• 不要用 shell heredoc、cat/echo/printf/tee 或重定向生成流程定义 JSON
• 已有 process/form context 时不要新建同类流程表单；在原流程上配置/更新。
• 不要把 configure-process 当作局部 patch；它会替换完整流程图。已有 PUBLISHED 流程或 SAVED 草稿时，未获得用户对替换摘要的明确确认，不得传 --replace。
• NON_IDEMPOTENT_RESULT_UNKNOWN 或 PUBLISHED_UNVERIFIED 后不得自动重试 draft/save/publish；先只读核对平台状态。

严格要求 (MUST DO)

• 发布前必须确认：执行流程发布操作前，必须向用户展示流程配置摘要（节点数、审批人、条件分支），获得用户明确同意后再发布
• 字段 ≥ 3 且审批节点 ≥ 2 时，必须为每个节点配置字段权限
• 存在回退/循环语义时，必须配置 routeRules 跳转规则
• 配置前先用 yida-get-schema 获取所有字段 ID
• 流程定义 JSON 必须用结构化文件写入工具创建到 <projectRoot>/.cache/openyida/<项目名或任务名>/，不要在仓库根目录、系统临时目录或 .cache/ 顶层生成 process-definition.json 等临时文件
• 必须以表单 binding 只读结果证明 processCode 属于目标 formUuid；CONFIGURE_PROCESS_OWNERSHIP_UNVERIFIED 时停止，不得换一个 processCode 猜测重试
• 命令成功必须同时返回 verificationLevel: "PLATFORM_VIEW_VERIFIED" 和 platformViewVerified: true；这只证明平台可见 view 的节点、组件、名称、顺序、审批模式及按钮权限和加签参数，不代表平台返回了可独立验证的 processJson

适用场景

触发条件

正向触发：
- "配置审批流程"、"设置审批节点"、"配置条件分支"
- "设置字段权限"、"配置抄送节点"、"设置跳转规则"
- 已有流程表单（processCode 已知），需要修改或配置审批规则
- yida-create-process 完成后，需要进一步配置复杂流程规则

概述

本技能描述如何通过流程设计器 API 为宜搭流程表单配置审批流程。支持审批节点、办理节点、条件分支、并行分支、嵌套分支、字段权限、抄送节点、跳转规则；同时支持宜搭 yida-simple-flow 官方组件节点的配置透传和 processJson 适配，用于连接器、数据、消息、邮件、Groovy/JavaScript、子流程、卡片、循环、AI 等高级节点。

何时使用

当以下场景发生时使用此技能：
- 用户需要为已有的流程表单配置审批流程
- 用户需要修改已有流程的审批规则
- 用户需要配置条件分支、嵌套分支等复杂流程
- 已有流程表单需要补充或固化流程规则

前提

> 简单判断：有没有现成的流程表单？有 → 本技能；没有 → yida-create-process。

执行本技能前需要已经有目标流程表单、appType、formUuid、字段 ID 和必要的审批人 / 条件信息。

使用方式

openyida configure-process <appType> <formUuid> <processDefinitionFile> [processCode] [--replace]

参数说明：

示例：

openyida configure-process "APP_XXX" "FORM-YYY" .cache/openyida/order/process-definition.json

> 上方路径默认从 OpenYida project 工作目录执行；从 workspace 根执行命令时传 project/.cache/openyida/order/process-definition.json。

输出：日志输出到 stderr，JSON 结果输出到 stdout：

{
  "success": true,
  "processCode": "TPROC--XXX",
  "processId": "83145794990",
  "processVersion": 2,
  "appType": "APP_XXX",
  "formUuid": "FORM-YYY",
  "verificationLevel": "PLATFORM_VIEW_VERIFIED",
  "platformViewVerified": true
}

多人审批（MultiApproval）

多人审批必须使用 type: "multiApproval"、必填 approver，并从固定的三种模式中选择 mode：all（会签）、or（或签）、oneByOne（依次审批）。CLI 会生成前端固定协议：process 侧 mode: "multi" / multiApprove / multiRules，view 侧 MultiApprovalNode / multiApproverRules。

{
  "type": "multiApproval",
  "name": "多人会审",
  "mode": "all",
  "approver": {
    "type": "user",
    "users": [
      { "id": "user001", "name": "审批人 A" },
      { "id": "user002", "name": "审批人 B" }
    ]
  }
}

流程定义 JSON 格式

流程定义文件描述审批流程的节点结构，脚本会自动转换为宜搭平台需要的 processJson 和 viewJson。

节点类型

节点别名

OpenYida 会自动兼容常见别名：

审批节点属性

办理 / 填写节点（operator）

办理节点底层仍是宜搭流程的 approval 类型，但 viewJson 使用 OperatorNode，适合“资料补充”“填写处理结果”“业务办理”等非审批动作。

{
  "type": "operator",
  "name": "资料补充",
  "executor": {
    "type": "user",
    "users": [
      { "id": "operator001", "name": "运营同学" }
    ]
  },
  "formConfig": {
    "behaviorList": [
      { "fieldId": "textareaField_material", "fieldBehavior": "NORMAL" },
      { "fieldId": "numberField_amount", "fieldBehavior": "READONLY" }
    ]
  }
}

条件分支属性

并行分支属性

{
  "type": "parallel",
  "name": "并行会审",
  "branches": [
    {
      "name": "法务会审",
      "childNodes": [
        { "type": "approval", "name": "法务审批", "approver": "originator" }
      ]
    },
    {
      "name": "财务会审",
      "rules": [
        {
          "fieldId": "numberField_amount",
          "fieldName": "金额",
          "componentType": "NumberField",
          "op": "GreaterThan",
          "value": 10000
        }
      ],
      "childNodes": [
        { "type": "approval", "name": "财务审批", "approver": "originator" }
      ]
    }
  ]
}

条件定义

条件规则

支持的操作符

加签和转交（actions）

CLI 支持通过 node.actions.normalActions/appendActions 同时生成按钮和完整加签参数。需要开启加签或转交时，先阅读 操作权限配置；不要仅修改原始 JSON 的 hidden。未配置时保持历史默认权限。

字段权限配置（formConfig）

{
  "formConfig": {
    "behaviorList": [
      { "fieldId": "textField_xxx", "fieldBehavior": "READONLY" },
      { "fieldId": "radioField_xxx", "fieldBehavior": "NORMAL" }
    ]
  }
}

跳转规则（routeRules）

{
  "routeRules": [
    { "when": "disagree", "jumpTo": "部门主管审核" }
  ]
}

jumpTo 的值为目标审批节点的 name，或 "结束" 表示跳到流程结束。

审批人配置

发起人本人

{
  "type": "approval",
  "name": "发起人确认",
  "approver": "originator"
}

指定成员

id 使用宜搭/钉钉通讯录中的 userId。可通过组织成员查询、应用成员配置或已知人员表获取。

{
  "type": "approval",
  "name": "主管审批",
  "approver": {
    "type": "user",
    "users": [
      { "id": "manager7350", "name": "九神" }
    ],
    "multiApproverType": "all"
  }
}

指定角色

roleType 默认为 "YIDA"；钉钉角色可传 "DINGTALK"。多个角色会按 roleType 生成宜搭流程需要的 multiRoles。

{
  "type": "approval",
  "name": "财务审批",
  "approver": {
    "type": "role",
    "roles": [
      { "id": "ROLE-FINANCE", "name": "财务", "roleType": "YIDA" }
    ],
    "multiApproverType": "or"
  }
}

部门主管 / 直属主管

{
  "type": "approval",
  "name": "部门主管审批",
  "approver": {
    "type": "deptLeader",
    "source": "originator",
    "level": 1,
    "needLeaderReplace": true,
    "ignoreNoLeaderDept": false
  }
}

直属主管使用 "type": "directLeader"，其余参数相同。multiApproverType 可选 "all"、"or"、"oneByOne"。

原始审批人配置（高级）

当 DSL 不能覆盖某个租户/版本的特殊审批规则时，可在节点上提供原始审批配置，OpenYida 会透传到 processJson 和 viewJson：

{
  "type": "approval",
  "name": "部门负责人审批",
  "approver": {
    "approvalType": "ext_target_approval_originator",
    "approvals": [["originator"]],
    "approverRules": {
      "type": "ext_target_approval_originator",
      "mode": "ApprovalNode_rules_only",
      "approverList": [{ "type": "ext_target_approval" }],
      "multiApproverType": "all",
      "conditionalMode": "conditional",
      "description": "发起人本人"
    }
  }
}

说明：不同租户/版本下某些高级规则（接口人、第三方服务、连接器、权限矩阵等）的 approverRules 结构可能不同。遇到 DSL 暂未覆盖的类型时，先在宜搭流程设计器中配置一个样例并导出/抓取对应结构，再用该对象固化到流程定义中。

官方组件节点（高级透传）

完整支持清单、连接器示例、数据 / 消息 / 代码节点示例和透传规则详见 references/official-component-nodes.md。

透传规则：

• 常规审批/办理/抄送、条件/并行分支优先用本文件中的简化 DSL。
• 连接器、数据、消息、邮件、Groovy/JavaScript、子流程、卡片、循环、AI 等节点使用真实组件 props 透传，并按线上设计器规则转换 processJson.props。
• 不认识的节点类型会直接报错，不会静默跳过，避免生成断链流程。

AI 自动生成流程特性（必须遵守）

> 📖 AI 生成流程定义的完整规范（字段权限自动生成、回退规则识别、检查清单）详见 references/process-ai-rules.md。

使用示例

示例 1：简单审批流程

{
  "nodes": [
    {
      "type": "approval",
      "name": "主管审批",
      "approver": "originator"
    }
  ]
}

流程：发起 → 主管审批 → 结束

> 📖 更多示例（条件分支、嵌套分支、字段权限、跳转规则、自定义详情页等）详见 references/examples.md。

注意事项

• 所有 fieldId 必须通过 openyida get-schema 获取，不能手写猜测
• 条件分支会自动补一个“其他情况”默认分支；不要手写猜测低层 conditionNode 结构
• 嵌套分支不超过 3 层
• 流程发布前必须先保存
• 本技能不读写 memory：流程定义通过 CLI 命令写入宜搭平台，processCode 等信息输出到 stdout，不依赖跨会话的 memory 状态

异常处理

• Node.js ≥ 16
• 项目根目录存在有效 token session（通过 openyida login 获取）

文件结构

yida-process-rule/
└── SKILL.md                    # 本文档

与其他技能配合

> 快捷方式：使用 yida-create-process 技能可一键完成步骤 2-3（创建表单 + 配置流程）。