@stalfh233/omc-cli 0.4.15 → 0.4.17

package/skills/omc-business-configuration.md

@@ -1,257 +1,258 @@
----
-name: omc-business-configuration
-description: 中文 CloudPivot 业务配置 runbook。用于把模型、字段、表单、视图、子表、流程权限、业务规则、按钮、在线 JS 和现存业务集成方法按需求落地并验收。
----
-
-# CloudPivot 业务配置 Runbook
-
-本技能讲业务需求如何落成配置包；底层 wire 形状和白屏陷阱见 `omc-write-hazards`。
-
-## 入口
-
-```bash
-CLI="packages/omc-cli/dist/cli.js"
-node "$CLI" commands --json
-node "$CLI" describe <tool>
-node "$CLI" contract <lane>
-node "$CLI" call discover_environment --env <env> --args '{}'
-node "$CLI" help omc-config-draft-review
-node "$CLI" help omc-five-piece-flow
-```
-
-## 需求五维
-
-把需求拆成五个维度（注意：这是**需求维度**，不同于 `omc-five-piece-flow` 的"五件套"执行五阶段）：
-
-1. **模型**：主对象、应用、业务 code。
-2. **字段**：类型、选项、关联目标、模型可空性。
-3. **表单与视图**：控件、子表 Sheet201、列表列、排序、筛选、按钮。
-4. **流程**：节点、参与人、每节点字段权限。
-5. **自动化**：规则、流程绑定、按钮、业务集成、在线 JS。
-
-## 标准顺序
-
-**配置顺序以 `omc-config-draft-review` §8 为唯一真相**（模型 → 字段 → 发布 → 表单 → 视图 → 规则 → 流程）；执行阶段见 `omc-five-piece-flow`。本 runbook 只补充业务侧要点：
-
-1. 读环境基线：应用、模型、字段、表单、视图、流程、规则、服务。
-2. 出中文草稿（`omc-config-draft-review`）：环境、应用、资源 code、字段表、流程图、映射、按钮、清理方案。
-3. 取得用户明确确认；确认前不写环境。
-4. 需求包含运行行为时，用 CLI 真实触发；测试数据的保留/清理要写进草稿。
-
-完成标准：每项资源有 readback；每个运行写入有 delivery 状态；每个映射字段都有目标值；失败步骤、已完成步骤和清理动作可追踪。
-
-## 模型与字段
-
-- 模型层字段默认可空；必填、只读、可见性在表单和流程节点配置。
-- `propertyEmpty` 默认 `false`，不要把业务必填硬编码在数据模型。
-- 关联单选优先读目标模型已发布字段，明确显示字段；无映射不要写空数组字符串。
-
-## 子表
-
-一个主表可以有多个子表，但子表不能嵌套子表。
-
-创建父字段：
-
-```json
-{
-  "schemaCode": "expense",
-  "code": "expense_items",
-  "name": "费用明细",
-  "propertyType": "CHILD_TABLE",
-  "subFields": [
-    { "code": "item_name", "name": "费用项目", "propertyType": "SHORT_TEXT" },
-    { "code": "item_amount", "name": "金额", "propertyType": "NUMERICAL" },
-    { "code": "item_date", "name": "发生日期", "propertyType": "DATE" }
-  ]
-}
-```
-
-子列像主表字段一样 CRUD，但 schemaCode 是父字段 code：
-
-```bash
-omc call field.create --env local --args '{"schemaCode":"expense_items","code":"item_note","name":"明细备注","propertyType":"LONG_TEXT"}'
-omc call field.update --env local --args '{"schemaCode":"expense_items","code":"item_note","name":"备注"}'
-omc call field.delete --env local --args '{"schemaCode":"expense_items","code":"item_note"}'
-omc call field.publish --env local --args '{"schemaCode":"expense"}'
-```
-
-父表单重建后，Sheet201 控件应有业务子列，子列 key 不应出现在普通 `viewJson`。
-
-声明式面同样支持子表（`intent.yaml`），子列写在父字段的 `subFields` 下；子列只接受标量族，不能嵌套子表/关联/公式：
-
-```yaml
-models:
-  - code: expense
-    name: 费用报销单
-    fields:
-      - code: expense_items
-        name: 费用明细
-        type: CHILD_TABLE
-        subFields:
-          - code: item_name
-            name: 费用项目
-            type: SHORT_TEXT
-          - code: item_amount
-            name: 金额
-            type: NUMERICAL
-```
-
-`intent plan/apply/readback` 会把子列的缺失、改名、类型漂移当成独立差异（`subfield:` 资源）；新增子列自动编译成 `field.create --schemaCode <父字段 code>` 并触发模型级 `field.publish`。父字段本身改名仍用 `field.update`，`field.update` 不接受 `subFields`。
-
-`intent apply` 默认在交付后自动做一次最终读回等价确认：等价则 `verification.status:"ok"`；不等价则整体 `refused` + `blocker:"intent-readback-mismatch"`（exit 12），**绝不当作成功**——按 `verification.differences` 定位后重新 `intent plan`，不要盲重试。`--no-verify` 可关闭该确认（只在你已单独跑 readback 时）。
-
-业务规则也进了声明式面（`models[].rules[]`）。常用数据事件规则用紧凑 `actions`，编译器合成 nodeGraph；复杂图用 `nodeGraph` 原样透传（二选一）：
-
-```yaml
-rules:
-  - code: Update                 # 平台预置码（Create/Update/Delete…）或自定义码
-    name: 更新归档
-    enabled: true                # true → 额外 rule.enable（publish+启用）；false → 已启用则 rule.disable
-    actions:
-      - type: UPDATE
-        target: archive_model     # 同模型可省略 target（默认本模型）；跨模型才必须写
-        filter:
-          - field: source_no
-            from: doc_no          # from = 动态（触发字段）；或比较键：equals/notEquals/gt/gte/lt/lte: <标量>
-        set:
-          - field: amount
-            from: total           # from = 动态；也可 value: <字面量>
-```
-
-- **每个 filter 项必须有且只有一个条件来源**：`from`（动态 EQ）或一个比较键（`equals`/`notEquals`/`gt`/`gte`/`lt`/`lte` + 标量）。缺来源 `intent-rule-leaf-source-missing` 拒绝；**绝不**静默成 `EQ null`。
-- 动作节点的条件分「定位数据」与「执行门」两类，**别混**（详见下「规则图的触发条件」）。
-- **跨模型写（`targetObjectCode`≠规则模型）平台支持、可运行时生效**（2026-09-28 真机复核）。两个前提：① 承载它的规则必须真的触发——`Create` 规则在提交时触发；`Update` 规则只在 `data.update` 触发，**submit 不执行它**（放进 `Update` 是典型静默空转，lint 警告 `rule-graph-cross-model-update-trigger-inert`；也可绑定流程事件如 `end`）。② 目标行必须已提交——目标查询不匹配 DRAFT 行，`data.save` 未 submit 的行不回写。
-- 关联字段：`type: WORK_SHEET` + `relativeCode: <目标模型>` + `options.displayField`，与 `field.create` 行形状一致。（键名是 `relativeCode`，wire 键 `relativeSchemaCode`，别混。）
-- 节点显示名用 activity 级的 `name`（`participant.name` 只作参与者说明，平台不认作节点名；`{type: Originator, name: 部门负责人}` 会被工具提升为节点名）。
-- **字段级数据规则**（`models[].datarules[]`，`dataRuleType` 1校验/2计算/3拼接/4必填/5只读）——注意是 `dataRuleType`（不是 `type`）：
-  ```yaml
-  datarules:
-    - { propertyCode: order_note, dataRuleType: 4, options: { requiredFormula: '{amount} 大于 {"valueType":"custom","value":5000}' }, name: 金额超5000说明必填 }
-  ```
-  ⚠️ **type 3/4/5 不驱动门户表单控件**（真机复核）：平台存成 bizdatarule，只镜像进控件 `historyOpt`，运行时门户读的是控件 `options`。门户条件（如「金额>5000 时必填」）必须写在 `fields[].options`（`requiredFormula`/`readonlyCondition`/`shortTextStitch`）；写进 `datarules[]` 设计器可见但门户不拦（validate/plan 给 `datarule-not-portal-facing` 警告）。datarule 只用于服务端引擎（校验/计算）。
-
-- 规则排在字段发布之后（编译器按能力排序：先建全部模型/字段，再跑规则）。
-- `rule.save` 只写草稿；`enabled` 由 `rule.enable` 保证（publish+启用）——readback 用 `enabled` 和**语义图摘要**（忽略画布几何）判等价。
-
-## 表单与视图
-
-- 新字段加入已有表单：`form.draft --rebuild`，然后 `form.publish`。
-- rebuild 会保留已识别的关系映射、显示和布局 options；Sheet201 columns 按最新子表字段刷新。
-- **配置列表视图用 `listview.configure`（省略 `code` 即平台自动生成的默认视图 code=schemaCode），不要先 `listview.create`——那会多出一个视图。** 只有确实要第二个视图才 create；两者职责分开。
-- 数值控件：`scale` 是小数位数（0=整数,1=1位,2=2位…）；「金额两位小数」用 `scale:2`。列表列 displayFormat 由 scale 推导。
-- **列表列只放业务字段**：平台 `listview.create` 会预置系统列（`name/creater/createdTime/sequenceNo`）和一条 `createdTime` 默认筛选；intent 的 `fieldCodes` 是权威集合，编译器用 `replaceColumns:true + hideDefaultSystemFields:true + conditions:[]` 清掉预置项。要展示某系统列/筛选就显式点名。
-- 筛选条件默认显示：`conditions[].visible` 不传也应为 true。
-- 配置默认视图后即可用 `data.list`；否则部分 8.6.26 读面业务列可能为 null，单行用 `data.load` 核对。
-- 读回视图用 `listview.get`（默认回列/排序/条件/动作紧凑清单）与 `listview.list`。
-
-## 流程字段权限
-
-新增字段后，必须重新检查每个参与节点的 `propertyPermissions`：
-
-- 填写节点：需求要求的字段可编辑，必要字段必填。
-- 审批节点：通常 `visible:true, editable:false, required:false`。
-- 不需要展示的字段明确 `visible:false`。
-
-**怎么配**（没有单独的权限工具，别把「找不到入口」当不支持→假阻塞）：`workflow.get_draft --full` 读节点正文，改目标
-`ParticipantActivity.propertyPermissions[]`（`{propertyCode, visible, editable, required, summary, subPropertyPermissions}`），
-用 `workflow.update` 原样回写，再 `workflow.publish`。**要生效必须 `summary:true`**（只有它进运行时 `activitySummaries`；
-否则 `form/load` 的 `formPermission.dataPermissions` 回退默认，读不到你的 `editable:false`）；子表列用 `subPropertyPermissions`。
-验收用 `npm run test:live-permission` + **非管理员参与者**（管理员会被后端强制 `e:true` 掩盖）。
-
-声明式流程（intent）的 `workflow.template` 用 **`activities` + `routes`**（不是 `nodes`/`edges`）：活动 `{id, type: START|END|PARTICIPANT|…, participant?}`，路由 `{preNode, postNode}` 必须指向已声明活动 code；`workflow.update` 只从 `activities` 读节点，写 `nodes` 会在 apply 时 `rules[0] references an unknown activity`（validate 会提前拦）。
-
-示例：
-
-```text
-开始 → 填写申请单 → 部门审批 → 财务审批 → 结束
-```
-
-如果环境里存在测试节点，先确认保留还是删除，不要静默覆盖。
-
-## 业务规则
-
-**先选对机制，别一律上规则图**（三者代价差很大）：
-
-| 需求形态 | 用哪个 | 入口 |
-| --- | --- | --- |
-| 条件必填 / 条件只读 / 恒只读（表单交互层） | 字段 `options` | `field.update --example form-conditional-required` / `form-conditional-readonly` / `form-always-readonly` |
-| 服务端字段级校验 / 计算 / 拼接 / 显示（type 1..5） | 数据规则 | `datarule.create`（字段级引擎） |
-| 数据事件自动化（创建/更新时改字段、调服务、发起流程） | 规则图 | 本节 `rule.save`（`--example standard-business-rule-graph`） |
-
-「超过某值必填 / 等于某值只读」= **字段 options**，**不要**建规则图、也**不要**用 `datarule.create`
-（实测：`datarule` type3/4/5 不会让门户表单控件变必填/只读，且符号式经 `historyOpt` 镜像会让表单渲染崩溃；
-平台的 bizdatarule 会被镜像进表单控件 `historyOpt`，而设计器/运行时读的是控件 `options`）。
-
-### 条件式（必填/只读/显示）怎么写
-
-- **恒必填**：`requiredFormula: "true"`（字面量）；**条件必填**：`requiredFormula: "{触发字段} 操作符 {\"valueType\":...,\"value\":...}"`。
-- 操作符用**中文**（设计器产出）：等于/不等于/大于/小于/大于等于/小于等于/包含/包含全部/等于任意一个/为空/不为空；也接受符号 `== != > >= <= Contains IsEmpty`。为空/不为空**不带值**。
-- 写完后 `field.publish` → `configure_form`（同步进控件）→ **门户打开表单改触发字段的值**，断言目标控件变 `required` / `disabled`（存储回读不算验证）。
-- 恒只读：`readonlyFormula: true`。
-
-### 规则图的触发条件（关键）
-
-规则支持**触发条件**，不要用「两条无条件规则」表达互斥结果：
-
-- **节点级条件有两大类，别混**（各节点类型都可能有，完整字段/样例见 `describe rule.save --full` 的 RULE_NODE_TEMPLATES）：
-  - **定位要操作哪些数据**（`filterCondition`：叶 `targetSchemaDataItem`+`ruleConditionType`）：UPDATE=改哪条（空=整表）、DELETE=删哪条、CREATE=存在符合则不新增+`findMainData`、QUERY=`targetConditionGroups`、**ASSIGN=在输入数据源匹配要取值的行（不是执行门！）**。⚠️ 非唯一字段（金额等）会命中**多条**；改「当前/关联那一条」用唯一键（`id` 或 `from`）。`actions.filter` 表达这类（同模型省略→默认 `id=id`；跨模型省略 fail-closed）。
-  - **执行门 / 满足条件触发**（`dataCondition`，BIZ_ACTION 用 `execConditionGroups`）：**与定位两码事**——决定「要不要执行」，不决定「改哪条」。compact `actions.when` 表达 UPDATE 执行门（叶 `currentSchemaDataItem`+`ruleDataConditionType`）；其它节点用 `nodeGraph`。**条件改自身**：`when: [{field: amount, gt: 10000}]` + 省略 `filter`（默认 `id=id`）——别把条件写进 `filter`，那会改掉所有符合的行（bench66 多行互覆）。
-  - 子表定位 `filterSubCondition`；子表触发范围 `childTriggerConditionType∈ADD/MODIFY/DELETE`。
-- **触发时机**：数据事件（`Create`/`Update`/`Delete`）**只分发到平台预置 code 行**；流程相关用预置 `Available`（流程生效）/`Cancel`（流程作废），或流程事件绑定 `workflow.bindRule` 的 `end`/`cancel`/`start`/`activate`。
-- **预置规则身份不可改**：`Create`/`Update`/`Delete`/`Load`/`GetList`/`Available`/`Cancel` 名称由平台维护（`Create`=数据新增）；传 `name` 不生效（仅自定义规则名称可改），可改的是节点名 `nodeName`。
-- **流程事件只绑自定义规则**：`workflow.bindRule` 的 `ruleCodes` 只能给自定义 code——设计器的事件规则选择器不提供预置触发行（绑 `Create` 到 `end` 非法，工具 fail closed）。要「审批通过后执行某逻辑」：新建自定义规则承载动作节点再绑 `end`。
-- **审批通过/驳回回写**：通过绑 `end`（或 `Available`）、驳回绑 `cancel`（或 `Cancel`）——**不要**把两条各自 FIXED 赋值的规则都绑到 `endEventHandler`（两条都会执行、后者覆盖前者；工具会在 `bizActions.length>1` 时回读 `advisory` 提醒）。真实生产只在 `endEventHandler` 绑**一条**多分支规则图。
-
-规则图需要显式：
-
-- `ruleCode`、名称、触发方式
-- 每个节点 `nodeName`
-- `nodeType`、路由、目标模型
-- 主表/子表 `findMainData`
-- 每个映射的 source/target 字段：**新增/更新节点的字段映射 = `dataActions`**（每目标字段一条叶：`{targetDataItem, ruleValueType:"DYNAMIC"/"FIXED", value:""/字面量, ruleActionType:"EQUALS", currentDataItemValue:"<来源字段>"}`）。**`execFormMapping` 只是展示开关，不是映射来源**——只写 `execFormMapping:true` 不写 `dataActions`，「主表字段值设置」是空的、新增行业务字段全 null（工具对 `execFormMapping:true` 缺 `dataActions` fail closed `rule-graph-create-mapping-missing`）。**写跨表节点前先 `rule.get` 读一条真实同型规则（如 `purchase_request`/`Create`）当基线**，不要从模板推断。
-
-流程结束后新增目标表单，配置发布后要真实跑完流程，再读目标表单每个字段（`data.load`，不是 `data.list`——后者只投影列表列）；只看到规则 `ENABLED` 不等于映射成功。
-
-## 业务集成
-
-优先复用现存 service/method，不做无必要的部署：
-
-```bash
-omc call service.get --env local --args '{"serviceCode":"omc_demo_restful"}'
-```
-
-- **新写一个接口 ≠ 新建一个服务**。同一个服务下可以挂多个方法：新服务用 `service.register`（`serviceCode` 已存在会 `duplicate-service` 拒绝），**往已有服务加方法用 `method.create`**（服务不存在 → 拒绝并提示先用 `service.register`；方法已存在 → 拒绝并提示改用 `method.update`）。不要为加一个方法而删服务重建（会连带丢掉服务的其它方法与规则绑定）。
-
-BIZ_ACTION：
-
-- 先读方法输入/输出参数面。
-- `codeType: 1` 的 PROPERTY 输入：`bizCode` 是源字段 code，`propertyName` 是显示名，`serviceMethodParameterCode` 必须命中方法参数。
-- **常量入参用 `codeType: 0`(CONST)**（如固定请求头 `X-LowCode-Corpid`）：值可放 `bizCode`，也可放 `value`（工具会自动移入 `bizCode`）。平台 CONST **只读 `bizCode`**——`value`/`expressionValue` 原样存着的话，运行时取到的是字面 `null`。
-- 参数面每参数必带 `bizPropertyType`（参数类型），否则业务规则按类型匹配字段会失败、映射不到（缺失即拒绝）；`externParameterType`/`description` 工具补齐。**返回值参数默认不必填（`required:false`），入参按需必填**——返回值声明为必填会经规则 designer 的 `required` 镜像强制每条输出映射也必填，是绑定摩擦的常见来源。
-- `rule.save` 自动补 `serviceName`/`serviceMethodName`/节点 `nodeCategory:"actionNode"`/映射元素 `index`（弹窗异步加载，稍候再判空）。
-- 配规则后读回 methodMapping，再用按钮或流程实际触发一次。
-- 服务、方法、参数不确定时拒绝猜，先读证据。
-
-## 按钮与在线 JS
-
-- 直接执行规则：`useLocation: ROW` + `operateType: WITH_OUT_VIEW`。
-- `WITH_VIEW` 是打开表单。
-- FLOW 按钮需要 workflowCode；CLI 会补安全的 actionConfig。
-- **在线 JS 分两条**：本 CLI 只做**发布与回读**——用 `onlinejs.compose` 把已定稿的 `source` 组合进平台 skeleton 的 `customScript` 再 publish，回读 `publishedHtmlJson`+SHA-256。**脚本内容的编写/增量合并不在本 CLI**：若当前项目自带在线 JS 编写规范（例如其 `.cpdocs`/技能或项目文档），遵循它；否则向用户/设计者索取已定稿的 `source`。不要在 omc 侧手写或臆造 JS 逻辑。
-
-## 运行验收与清理
-
-运行测试前在草稿里列出：
-
-- 测试输入值
-- 预计生成的记录/调用
-- 每个字段的验收值
-- 清理哪些测试数据，保留哪些配置
-
-推荐顺序：
-
-```text
-配置读回 → CLI 运行触发 → workitem/data/service 读回 → 比较字段 → 清理测试数据
-```
-
-浏览器不是常规验收步骤；只有用户报告 UI 回归时才做专项诊断。
+---
+name: omc-business-configuration
+description: 中文 CloudPivot 业务配置 runbook。用于把模型、字段、表单、视图、子表、流程权限、业务规则、按钮、在线 JS 和现存业务集成方法按需求落地并验收。
+---
+
+# CloudPivot 业务配置 Runbook
+
+本技能讲业务需求如何落成配置包；底层 wire 形状和白屏陷阱见 `omc-write-hazards`。
+
+## 入口
+
+```bash
+CLI="packages/omc-cli/dist/cli.js"
+node "$CLI" commands --json
+node "$CLI" describe <tool>
+node "$CLI" contract <lane>
+node "$CLI" call discover_environment --env <env> --args '{}'
+node "$CLI" help omc-config-draft-review
+node "$CLI" help omc-five-piece-flow
+```
+
+## 需求五维
+
+把需求拆成五个维度（注意：这是**需求维度**，不同于 `omc-five-piece-flow` 的"五件套"执行五阶段）：
+
+1. **模型**：主对象、应用、业务 code。
+2. **字段**：类型、选项、关联目标、模型可空性。
+3. **表单与视图**：控件、子表 Sheet201、列表列、排序、筛选、按钮。
+4. **流程**：节点、参与人、每节点字段权限。
+5. **自动化**：规则、流程绑定、按钮、业务集成、在线 JS。
+
+## 标准顺序
+
+**配置顺序以 `omc-config-draft-review` §8 为唯一真相**（模型 → 字段 → 发布 → 表单 → 视图 → 规则 → 流程）；执行阶段见 `omc-five-piece-flow`。本 runbook 只补充业务侧要点：
+
+1. 读环境基线：应用、模型、字段、表单、视图、流程、规则、服务。
+2. 出中文草稿（`omc-config-draft-review`）：环境、应用、资源 code、字段表、流程图、映射、按钮、清理方案。
+3. 取得用户明确确认；确认前不写环境。
+4. 需求包含运行行为时，用 CLI 真实触发；测试数据的保留/清理要写进草稿。
+
+完成标准：每项资源有 readback；每个运行写入有 delivery 状态；每个映射字段都有目标值；失败步骤、已完成步骤和清理动作可追踪。
+
+## 模型与字段
+
+- 模型层字段默认可空；必填、只读、可见性在表单和流程节点配置。
+- `propertyEmpty` 默认 `false`，不要把业务必填硬编码在数据模型。
+- 关联单选优先读目标模型已发布字段，明确显示字段；无映射不要写空数组字符串。
+
+## 子表
+
+一个主表可以有多个子表，但子表不能嵌套子表。
+
+创建父字段：
+
+```json
+{
+  "schemaCode": "expense",
+  "code": "expense_items",
+  "name": "费用明细",
+  "propertyType": "CHILD_TABLE",
+  "subFields": [
+    { "code": "item_name", "name": "费用项目", "propertyType": "SHORT_TEXT" },
+    { "code": "item_amount", "name": "金额", "propertyType": "NUMERICAL" },
+    { "code": "item_date", "name": "发生日期", "propertyType": "DATE" }
+  ]
+}
+```
+
+子列像主表字段一样 CRUD，但 schemaCode 是父字段 code：
+
+```bash
+# --env 在单环境项目（.omc-env 在位）可省；显式写出仅为多环境演示
+omc call field.create --env local --args '{"schemaCode":"expense_items","code":"item_note","name":"明细备注","propertyType":"LONG_TEXT"}'
+omc call field.update --env local --args '{"schemaCode":"expense_items","code":"item_note","name":"备注"}'
+omc call field.delete --env local --args '{"schemaCode":"expense_items","code":"item_note"}'
+omc call field.publish --env local --args '{"schemaCode":"expense"}'
+```
+
+父表单重建后，Sheet201 控件应有业务子列，子列 key 不应出现在普通 `viewJson`。
+
+声明式面同样支持子表（`intent.yaml`），子列写在父字段的 `subFields` 下；子列只接受标量族，不能嵌套子表/关联/公式：
+
+```yaml
+models:
+  - code: expense
+    name: 费用报销单
+    fields:
+      - code: expense_items
+        name: 费用明细
+        type: CHILD_TABLE
+        subFields:
+          - code: item_name
+            name: 费用项目
+            type: SHORT_TEXT
+          - code: item_amount
+            name: 金额
+            type: NUMERICAL
+```
+
+`intent plan/apply/readback` 会把子列的缺失、改名、类型漂移当成独立差异（`subfield:` 资源）；新增子列自动编译成 `field.create --schemaCode <父字段 code>` 并触发模型级 `field.publish`。父字段本身改名仍用 `field.update`，`field.update` 不接受 `subFields`。
+
+`intent apply` 默认在交付后自动做一次最终读回等价确认：等价则 `verification.status:"ok"`；不等价则整体 `refused` + `blocker:"intent-readback-mismatch"`（exit 12），**绝不当作成功**——按 `verification.differences` 定位后重新 `intent plan`，不要盲重试。`--no-verify` 可关闭该确认（只在你已单独跑 readback 时）。
+
+业务规则也进了声明式面（`models[].rules[]`）。常用数据事件规则用紧凑 `actions`，编译器合成 nodeGraph；复杂图用 `nodeGraph` 原样透传（二选一）：
+
+```yaml
+rules:
+  - code: Update                 # 平台预置码（Create/Update/Delete…）或自定义码
+    name: 更新归档
+    enabled: true                # true → 额外 rule.enable（publish+启用）；false → 已启用则 rule.disable
+    actions:
+      - type: UPDATE
+        target: archive_model     # 同模型可省略 target（默认本模型）；跨模型才必须写
+        filter:
+          - field: source_no
+            from: doc_no          # from = 动态（触发字段）；或比较键：equals/notEquals/gt/gte/lt/lte: <标量>
+        set:
+          - field: amount
+            from: total           # from = 动态；也可 value: <字面量>
+```
+
+- **每个 filter 项必须有且只有一个条件来源**：`from`（动态 EQ）或一个比较键（`equals`/`notEquals`/`gt`/`gte`/`lt`/`lte` + 标量）。缺来源 `intent-rule-leaf-source-missing` 拒绝；**绝不**静默成 `EQ null`。
+- 动作节点的条件分「定位数据」与「执行门」两类，**别混**（详见下「规则图的触发条件」）。
+- **跨模型写（`targetObjectCode`≠规则模型）平台支持、可运行时生效**（2026-09-28 真机复核）。两个前提：① 承载它的规则必须真的触发——`Create` 规则在提交时触发；`Update` 规则只在 `data.update` 触发，**submit 不执行它**（放进 `Update` 是典型静默空转，lint 警告 `rule-graph-cross-model-update-trigger-inert`；也可绑定流程事件如 `end`）。② 目标行必须已提交——目标查询不匹配 DRAFT 行，`data.save` 未 submit 的行不回写。
+- 关联字段：`type: WORK_SHEET` + `relativeCode: <目标模型>` + `options.displayField`，与 `field.create` 行形状一致。（键名是 `relativeCode`，wire 键 `relativeSchemaCode`，别混。）
+- 节点显示名用 activity 级的 `name`（`participant.name` 只作参与者说明，平台不认作节点名；`{type: Originator, name: 部门负责人}` 会被工具提升为节点名）。
+- **字段级数据规则**（`models[].datarules[]`，`dataRuleType` 1校验/2计算/3拼接/4必填/5只读）——注意是 `dataRuleType`（不是 `type`）：
+  ```yaml
+  datarules:
+    - { propertyCode: order_note, dataRuleType: 4, options: { requiredFormula: '{amount} 大于 {"valueType":"custom","value":5000}' }, name: 金额超5000说明必填 }
+  ```
+  ⚠️ **type 3/4/5 不驱动门户表单控件**（真机复核）：平台存成 bizdatarule，只镜像进控件 `historyOpt`，运行时门户读的是控件 `options`。门户条件（如「金额>5000 时必填」）必须写在 `fields[].options`（`requiredFormula`/`readonlyCondition`/`shortTextStitch`）；写进 `datarules[]` 设计器可见但门户不拦（validate/plan 给 `datarule-not-portal-facing` 警告）。datarule 只用于服务端引擎（校验/计算）。
+
+- 规则排在字段发布之后（编译器按能力排序：先建全部模型/字段，再跑规则）。
+- `rule.save` 只写草稿；`enabled` 由 `rule.enable` 保证（publish+启用）——readback 用 `enabled` 和**语义图摘要**（忽略画布几何）判等价。
+
+## 表单与视图
+
+- 新字段加入已有表单：`form.publish --args '{...,"rebuild":true}'` 一步（重建脚手架+强制提拔）；或分步 `form.draft --rebuild` → `form.publish`。
+- rebuild 会保留已识别的关系映射、显示和布局 options；Sheet201 columns 按最新子表字段刷新。
+- **配置列表视图用 `listview.configure`（省略 `code` 即平台自动生成的默认视图 code=schemaCode），不要先 `listview.create`——那会多出一个视图。** 只有确实要第二个视图才 create；两者职责分开。
+- 数值控件：`scale` 是小数位数（0=整数,1=1位,2=2位…）；「金额两位小数」用 `scale:2`。列表列 displayFormat 由 scale 推导。
+- **列表列只放业务字段**：平台 `listview.create` 会预置系统列（`name/creater/createdTime/sequenceNo`）和一条 `createdTime` 默认筛选；intent 的 `fieldCodes` 是权威集合，编译器用 `replaceColumns:true + hideDefaultSystemFields:true + conditions:[]` 清掉预置项。要展示某系统列/筛选就显式点名。
+- 筛选条件默认显示：`conditions[].visible` 不传也应为 true。
+- 配置默认视图后即可用 `data.list`；否则部分 8.6.26 读面业务列可能为 null，单行用 `data.load` 核对。
+- 读回视图用 `listview.get`（默认回列/排序/条件/动作紧凑清单）与 `listview.list`。
+
+## 流程字段权限
+
+新增字段后，必须重新检查每个参与节点的 `propertyPermissions`：
+
+- 填写节点：需求要求的字段可编辑，必要字段必填。
+- 审批节点：通常 `visible:true, editable:false, required:false`。
+- 不需要展示的字段明确 `visible:false`。
+
+**怎么配**（没有单独的权限工具，别把「找不到入口」当不支持→假阻塞）：`workflow.get_draft --full` 读节点正文，改目标
+`ParticipantActivity.propertyPermissions[]`（`{propertyCode, visible, editable, required, summary, subPropertyPermissions}`），
+用 `workflow.update` 原样回写，再 `workflow.publish`。**要生效必须 `summary:true`**（只有它进运行时 `activitySummaries`；
+否则 `form/load` 的 `formPermission.dataPermissions` 回退默认，读不到你的 `editable:false`）；子表列用 `subPropertyPermissions`。
+验收用 `npm run test:live-permission` + **非管理员参与者**（管理员会被后端强制 `e:true` 掩盖）。
+
+声明式流程（intent）的 `workflow.template` 用 **`activities` + `routes`**（不是 `nodes`/`edges`）：活动 `{id, type: START|END|PARTICIPANT|…, participant?}`，路由 `{preNode, postNode}` 必须指向已声明活动 code；`workflow.update` 只从 `activities` 读节点，写 `nodes` 会在 apply 时 `rules[0] references an unknown activity`（validate 会提前拦）。
+
+示例：
+
+```text
+开始 → 填写申请单 → 部门审批 → 财务审批 → 结束
+```
+
+如果环境里存在测试节点，先确认保留还是删除，不要静默覆盖。
+
+## 业务规则
+
+**先选对机制，别一律上规则图**（三者代价差很大）：
+
+| 需求形态 | 用哪个 | 入口 |
+| --- | --- | --- |
+| 条件必填 / 条件只读 / 恒只读（表单交互层） | 字段 `options` | `field.update --example form-conditional-required` / `form-conditional-readonly` / `form-always-readonly` |
+| 服务端字段级校验 / 计算 / 拼接 / 显示（type 1..5） | 数据规则 | `datarule.create`（字段级引擎） |
+| 数据事件自动化（创建/更新时改字段、调服务、发起流程） | 规则图 | 本节 `rule.save`（`--example standard-business-rule-graph`） |
+
+「超过某值必填 / 等于某值只读」= **字段 options**，**不要**建规则图、也**不要**用 `datarule.create`
+（实测：`datarule` type3/4/5 不会让门户表单控件变必填/只读，且符号式经 `historyOpt` 镜像会让表单渲染崩溃；
+平台的 bizdatarule 会被镜像进表单控件 `historyOpt`，而设计器/运行时读的是控件 `options`）。
+
+### 条件式（必填/只读/显示）怎么写
+
+- **恒必填**：`requiredFormula: "true"`（字面量）；**条件必填**：`requiredFormula: "{触发字段} 操作符 {\"valueType\":...,\"value\":...}"`。
+- 操作符用**中文**（设计器产出）：等于/不等于/大于/小于/大于等于/小于等于/包含/包含全部/等于任意一个/为空/不为空；也接受符号 `== != > >= <= Contains IsEmpty`。为空/不为空**不带值**。
+- 写完后 `field.publish` → `configure_form`（同步进控件）→ **门户打开表单改触发字段的值**，断言目标控件变 `required` / `disabled`（存储回读不算验证）。
+- 恒只读：`readonlyFormula: true`。
+
+### 规则图的触发条件（关键）
+
+规则支持**触发条件**，不要用「两条无条件规则」表达互斥结果：
+
+- **节点级条件有两大类，别混**（各节点类型都可能有，完整字段/样例见 `describe rule.save --full` 的 RULE_NODE_TEMPLATES）：
+  - **定位要操作哪些数据**（`filterCondition`：叶 `targetSchemaDataItem`+`ruleConditionType`）：UPDATE=改哪条（空=整表）、DELETE=删哪条、CREATE=存在符合则不新增+`findMainData`、QUERY=`targetConditionGroups`、**ASSIGN=在输入数据源匹配要取值的行（不是执行门！）**。⚠️ 非唯一字段（金额等）会命中**多条**；改「当前/关联那一条」用唯一键（`id` 或 `from`）。`actions.filter` 表达这类（同模型省略→默认 `id=id`；跨模型省略 fail-closed）。
+  - **执行门 / 满足条件触发**（`dataCondition`，BIZ_ACTION 用 `execConditionGroups`）：**与定位两码事**——决定「要不要执行」，不决定「改哪条」。compact `actions.when` 表达 UPDATE 执行门（叶 `currentSchemaDataItem`+`ruleDataConditionType`）；其它节点用 `nodeGraph`。**条件改自身**：`when: [{field: amount, gt: 10000}]` + 省略 `filter`（默认 `id=id`）——别把条件写进 `filter`，那会改掉所有符合的行（bench66 多行互覆）。
+  - 子表定位 `filterSubCondition`；子表触发范围 `childTriggerConditionType∈ADD/MODIFY/DELETE`。
+- **触发时机**：数据事件（`Create`/`Update`/`Delete`）**只分发到平台预置 code 行**；流程相关用预置 `Available`（流程生效）/`Cancel`（流程作废），或流程事件绑定 `workflow.bindRule` 的 `end`/`cancel`/`start`/`activate`。
+- **预置规则身份不可改**：`Create`/`Update`/`Delete`/`Load`/`GetList`/`Available`/`Cancel` 名称由平台维护（`Create`=数据新增）；传 `name` 不生效（仅自定义规则名称可改），可改的是节点名 `nodeName`。
+- **流程事件只绑自定义规则**：`workflow.bindRule` 的 `ruleCodes` 只能给自定义 code——设计器的事件规则选择器不提供预置触发行（绑 `Create` 到 `end` 非法，工具 fail closed）。要「审批通过后执行某逻辑」：新建自定义规则承载动作节点再绑 `end`。
+- **审批通过/驳回回写**：通过绑 `end`（或 `Available`）、驳回绑 `cancel`（或 `Cancel`）——**不要**把两条各自 FIXED 赋值的规则都绑到 `endEventHandler`（两条都会执行、后者覆盖前者；工具会在 `bizActions.length>1` 时回读 `advisory` 提醒）。真实生产只在 `endEventHandler` 绑**一条**多分支规则图。
+
+规则图需要显式：
+
+- `ruleCode`、名称、触发方式
+- 每个节点 `nodeName`
+- `nodeType`、路由、目标模型
+- 主表/子表 `findMainData`
+- 每个映射的 source/target 字段：**新增/更新节点的字段映射 = `dataActions`**（每目标字段一条叶：`{targetDataItem, ruleValueType:"DYNAMIC"/"FIXED", value:""/字面量, ruleActionType:"EQUALS", currentDataItemValue:"<来源字段>"}`）。**`execFormMapping` 只是展示开关，不是映射来源**——只写 `execFormMapping:true` 不写 `dataActions`，「主表字段值设置」是空的、新增行业务字段全 null（工具对 `execFormMapping:true` 缺 `dataActions` fail closed `rule-graph-create-mapping-missing`）。**写跨表节点前先 `rule.get` 读一条真实同型规则（如 `purchase_request`/`Create`）当基线**，不要从模板推断。
+
+流程结束后新增目标表单，配置发布后要真实跑完流程，再读目标表单每个字段（`data.load`，不是 `data.list`——后者只投影列表列）；只看到规则 `ENABLED` 不等于映射成功。
+
+## 业务集成
+
+优先复用现存 service/method，不做无必要的部署：
+
+```bash
+omc call service.get --env local --args '{"serviceCode":"omc_demo_restful"}'
+```
+
+- **新写一个接口 ≠ 新建一个服务**。同一个服务下可以挂多个方法：新服务用 `service.register`（`serviceCode` 已存在会 `duplicate-service` 拒绝），**往已有服务加方法用 `method.create`**（服务不存在 → 拒绝并提示先用 `service.register`；方法已存在 → 拒绝并提示改用 `method.update`）。不要为加一个方法而删服务重建（会连带丢掉服务的其它方法与规则绑定）。
+
+BIZ_ACTION：
+
+- 先读方法输入/输出参数面。
+- `codeType: 1` 的 PROPERTY 输入：`bizCode` 是源字段 code，`propertyName` 是显示名，`serviceMethodParameterCode` 必须命中方法参数。
+- **常量入参用 `codeType: 0`(CONST)**（如固定请求头 `X-LowCode-Corpid`）：值可放 `bizCode`，也可放 `value`（工具会自动移入 `bizCode`）。平台 CONST **只读 `bizCode`**——`value`/`expressionValue` 原样存着的话，运行时取到的是字面 `null`。
+- 参数面每参数必带 `bizPropertyType`（参数类型），否则业务规则按类型匹配字段会失败、映射不到（缺失即拒绝）；`externParameterType`/`description` 工具补齐。**返回值参数默认不必填（`required:false`），入参按需必填**——返回值声明为必填会经规则 designer 的 `required` 镜像强制每条输出映射也必填，是绑定摩擦的常见来源。
+- `rule.save` 自动补 `serviceName`/`serviceMethodName`/节点 `nodeCategory:"actionNode"`/映射元素 `index`（弹窗异步加载，稍候再判空）。
+- 配规则后读回 methodMapping，再用按钮或流程实际触发一次。
+- 服务、方法、参数不确定时拒绝猜，先读证据。
+
+## 按钮与在线 JS
+
+- 直接执行规则：`useLocation: ROW` + `operateType: WITH_OUT_VIEW`。
+- `WITH_VIEW` 是打开表单。
+- FLOW 按钮需要 workflowCode；CLI 会补安全的 actionConfig。
+- **在线 JS 分两条**：本 CLI 只做**发布与回读**——用 `onlinejs.compose` 把已定稿的 `source` 组合进平台 skeleton 的 `customScript` 再 publish，回读 `publishedHtmlJson`+SHA-256。**脚本内容的编写/增量合并不在本 CLI**：若当前项目自带在线 JS 编写规范（例如其 `.cpdocs`/技能或项目文档），遵循它；否则向用户/设计者索取已定稿的 `source`。不要在 omc 侧手写或臆造 JS 逻辑。
+
+## 运行验收与清理
+
+运行测试前在草稿里列出：
+
+- 测试输入值
+- 预计生成的记录/调用
+- 每个字段的验收值
+- 清理哪些测试数据，保留哪些配置
+
+推荐顺序：
+
+```text
+配置读回 → CLI 运行触发 → workitem/data/service 读回 → 比较字段 → 清理测试数据
+```
+
+浏览器不是常规验收步骤；只有用户报告 UI 回归时才做专项诊断。