weaver-e10-builder 1.1.6 → 1.1.8

package/skill-docs/references/form/guide-form-layout-planning.md

@@ -0,0 +1,68 @@
+# EB 表单布局规划
+
+本指南用于从需求文档识别 FLOW/EXCEL 布局，并将布局要求完整写入 plan 和 `fields.json`。表单创建顺序见 [新建 EBuilder 表单](guide-create-form.md)。
+
+## 确认布局类型
+
+- `FLOW`：流式布局。
+- `EXCEL`：表格式布局。
+- 使用 `form create --layout FLOW|EXCEL` 在创建时指定。
+- 需求未明确且选择会改变最终布局时，建表前向用户确认。
+
+## 识别布局样表
+
+识别发生在读取需求文档之后、编写 `plan.md` 之前。先整理字段定义，再扫描布局章节和表格。
+
+出现以下特征时，将表格作为布局样表：
+
+- 上下文说明“表格式布局”“Excel 样式”或“按照如下布局”；
+- 单元格包含 `[字段名]`，或呈现标签与字段控件交替结构；
+- 存在表单标题、分组标题、合并单元格、有意义的空白位置；
+- 表格表达字段摆放位置，而不是重复列出字段名称、类型和说明。
+
+逐行识别表单标题、分组标题、字段标签、字段控件、空白占位、同排字段、合并和跨列关系，以及必填、只读、独占一行等显示属性。优先使用 `e10-cli docx read` 生成的 Markdown 表格；合并区域不清晰时查看原 DOCX 中对应表格结构。
+
+## 写入 Plan
+
+识别结果分别写入同一表单的两个部分：
+
+1. “字段定义”：保存字段类型和可以直接创建的属性。
+2. “表单布局蓝图”：逐行保存标题、分组、字段同排关系、顺序、空白占位、跨列信息和原文说明。
+
+```markdown
+##### 表单布局蓝图
+
+| 行 | 区域/分组 | 左侧 | 右侧 | 布局说明 |
+|---|---|---|---|---|
+| 1 | 标题 | 项目信息表 | — | 合并整行 |
+| 2 | 基本信息 | 项目名称 | 项目编号 | 同排两列 |
+| 3 | 基本信息 | 项目简介 | — | 独占整行 |
+```
+
+轻量核对原样表中的每个字段，确保同时出现在字段定义和布局蓝图中，并保留同排关系和分组顺序。
+
+## 转换为 fields.json
+
+- 数组顺序表示字段展示顺序。
+- `group` 表示需求明确的分组。
+- `singleRow:true` 表示独占一行。
+- `required:true`、`readOnly:true`、`hidden:true` 表示显示属性。
+
+```json
+[
+  {"componentKey":"Text","fieldName":"项目名称","group":"基本信息","required":true},
+  {"componentKey":"Text","fieldName":"项目编号","group":"基本信息","readOnly":true},
+  {"componentKey":"TextArea","fieldName":"项目简介","group":"基本信息","singleRow":true}
+]
+```
+
+只有需求明确要求分组时才设置 `group`；需求未要求时保持不分组。
+
+## 创建与局部调整
+
+```bash
+e10-cli form create <appId> "<表单名>" --fields @fields.json --layout EXCEL
+e10-cli form layout read <objId> <appId>
+```
+
+创建后需要调整局部位置或显示属性时，使用 `form layout` 下的移动、只读和必填设置命令；具体参数通过 `form layout --help` 查询。

package/skill-docs/references/form/guide-form-serial-mark.md

@@ -0,0 +1,47 @@
+# EB 表单复杂编号
+
+复杂编号用于在文本字段上配置固定内容、日期、流水号、表单字段、系统字段和代字组合。
+
+## 设置编号
+
+```bash
+e10-cli form serial-mark set <objId> <appId> <字段ID> --segments @segments.json
+```
+
+数组顺序就是编号拼接顺序：
+
+```json
+[
+  {"type":"field","fieldId":"<项目类型字段ID>","shortName":{"研发":"YF","实施":"SS"}},
+  {"type":"fixed","value":"-"},
+  {"type":"year","format":"four","alone":true},
+  {"type":"fixed","value":"-"},
+  {"type":"serial","digits":4,"zero":true}
+]
+```
+
+## 编号段
+
+| `type` | 含义 | 常用属性 |
+|---|---|---|
+| `fixed` | 固定文本 | `value` |
+| `year` | 年份 | `format:four|two`、`alone` |
+| `serial` | 流水号 | `digits`、`zero`、`alone` |
+| `field` | 表单字段值 | `fieldId`、`shortName`、`alone` |
+| `system` | 系统字段 | `systemField:creator|creator-dept`、`alone` |
+| `date` | 日期 | `format:yyyy|yyyyMM|yyyyMMdd`、`source` |
+
+`alone:true` 用于按该段分别计数；`shortName` 用于将选项值映射为代字。
+
+## 增量调整、查询和清除
+
+```bash
+e10-cli form serial-mark add-segment <objId> <appId> <字段ID> --type field --field-id <取值字段ID> --position 0
+e10-cli form serial-mark short-name list <objId> <appId> <选择字段ID>
+e10-cli form serial-mark short-name set <objId> <appId> <选择字段ID> --map '{"研发":"YF","实施":"SS"}'
+e10-cli form serial-mark read <objId> <appId>
+e10-cli form serial-mark fields <objId> <appId>
+e10-cli form serial-mark clear <objId> <appId> <字段ID>
+```
+
+配置复杂编号后，目标字段由平台自动生成编号并按只读方式使用。

package/skill-docs/references/form/guide-form-view.md

@@ -83,6 +83,13 @@ e10-cli --json form list-view <objId> <appId>
 
 `--pc-only` 只用于已确认本次验收为 PC 的场景。未指定时，命令必须取得真实 MOBILE 配置，禁止用 PC 配置推导移动端。
 
+`create` / `ensure` 同样支持 `--terminal pc|mobile`（缺省 `pc`）：决定显示列写进哪一端，另一端原样保留。只给某一端配显示列时用 `--terminal`，两端都要就分两次执行。
+
+```bash
+# 只给移动端补显示列，PC 端配置不动
+e10-cli --json form table-view create <objId> <appId> "移动端表格" --terminal mobile
+```
+
 服务器通过必须同时满足：
 
 - 创建后按返回 `listId` 找到同名列表。
@@ -113,7 +120,19 @@ e10-cli --json form table-view style <objId> <appId> <listId> <style>
 
 可编辑表格内部还有数据态 `8` 和只读态 `9`；用户要求“改成可编辑表格”时必须使用编辑态 `11`，不得把只读态 `9` 当成完成。
 
-命令先确认 `listId` 属于目标 `objId`，分别读取完整 PC/MOBILE 配置，只修改 PC 顶层 `mode`，保存后重新读取 PC 配置。移动端配置必须原样保留；读取不到时，只有明确 `--pc-only` 才允许继续。
+命令先确认 `listId` 属于目标 `objId`，读取目标终端的完整配置后只修改其顶层 `mode`，保存后重新读取该终端配置核对。
+
+PC 与移动端是**两个独立槽位**（保存接口的 `config` 落 PC、`mConfig` 落移动端），`--terminal` 决定改哪一端，缺省 `pc`：
+
+- `--terminal pc`：只改 PC，移动端配置原样回传；
+- `--terminal mobile`：只改移动端，PC 配置原样回传。
+
+末尾会回显实际落点与另一端状态（`终端: 移动端（另一端配置保持原样）`）。另一端配置读取不到时，只有明确 `--pc-only` 才允许继续；`--terminal mobile` 与 `--pc-only` 互斥，同时传会直接报错——不要用 `--pc-only` 去改移动端。
+
+```bash
+# 只把移动端改成网格列表式，PC 展示样式保持不动
+e10-cli --json form table-view style <objId> <appId> <listId> grid --terminal mobile
+```
 
 前端验收：重新进入“基础设置 → 展示样式”仍显示“可编辑表格”，并且列表进入可编辑状态。
 
@@ -126,7 +145,7 @@ e10-cli --json form table-view search-style <objId> <appId> <listId> advanced
 
 显示方式固定为 `advanced → commonSearchType="0"`、`filter → commonSearchType="1"`，不得直接猜内部值。
 
-命令先确认 `listId` 属于目标表单，完整保留 PC 其他配置和真实 MOBILE 配置，保存后重新读取目标属性。前端验收：“常用搜索 → 基础信息 → 显示方式”能正常打开，且刷新后仍为目标方式；若配置页异常，接口回读成功也不能验收。
+命令先确认 `listId` 属于目标表单，完整保留目标终端的其他配置，保存后重新读取目标属性；`--terminal` 同上（`pc` 只改 PC、`mobile` 只改移动端，另一端原样回传）。前端验收：“常用搜索 → 基础信息 → 显示方式”能正常打开，且刷新后仍为目标方式；若配置页异常，接口回读成功也不能验收。
 
 ## 常用搜索字段
 
@@ -143,7 +162,7 @@ e10-cli --json form table-view search-field configure \
   --condition like
 ```
 
-命令必须从当前数据源接口取得完整字段模型，按前端最终保存结构生成搜索项：字段 `id` 与独立的 18 位 `filterId` 不得混用，字段自身 `multiSelect` 原样保留，搜索默认配置单独写入 `listFilterDefaultSets`。保存时完整保留 PC 其他配置和真实 MOBILE 配置，再独立回读字段及条件关系。
+命令必须从当前数据源接口取得完整字段模型，按前端最终保存结构生成搜索项：字段 `id` 与独立的 18 位 `filterId` 不得混用，字段自身 `multiSelect` 原样保留，搜索默认配置单独写入 `listFilterDefaultSets`。保存时完整保留目标终端的其他配置，再独立回读字段及条件关系；`--terminal` 同上（`pc` 只改 PC、`mobile` 只改移动端，另一端原样回传）。
 
 具体配置固定映射：
 

package/skill-docs/references/form/ref-form-fields.md

@@ -0,0 +1,147 @@
+# 表单字段定义参考
+
+本参考用于编写 EB 表单的 `fields.json`。标准创建顺序见 [新建 EBuilder 表单](guide-create-form.md)。
+
+## 通用结构
+
+```json
+{"componentKey":"Text","fieldName":"项目名称","required":true,"readOnly":false,"hidden":false,"singleRow":true,"group":"基本信息"}
+```
+
+| 属性 | 说明 |
+|---|---|
+| `componentKey` | 字段类型 |
+| `fieldName` | 字段中文名称 |
+| `required` / `readOnly` / `hidden` | 必填、只读、隐藏 |
+| `singleRow` | 独占一行 |
+| `group` | 需求指定的字段分组 |
+| `multiple` | 支持多选的类型设置为多选 |
+| `defaultValue` | 默认值；人员、部门和日期写 `true` 表示动态当前值 |
+
+## 支持的字段类型
+
+| `componentKey` | 用途 | 常用专属属性 |
+|---|---|---|
+| `Text` | 单行文本 | `maxLen`，缺省 100 |
+| `TextArea` | 多行文本 | `maxLen`，缺省 4000 |
+| `Email` / `Phone` / `Mobile` / `IDCard` | 邮箱、电话、手机、身份证 | `maxLen` |
+| `Number` | 数字 | `precision`、`percent`、`delimiter`、`capital` |
+| `Money` | 金额 | `precision`、`delimiter`、`capital` |
+| `Date` / `DateTime` | 日期、日期时间 | `format`、`minField`、`maxField` |
+| `DateRange` | 日期区间 | `format`、`startPlaceholder`、`endPlaceholder` |
+| `Time` | 时间 | 格式 `HH:mm:ss` |
+| `Select` / `RadioBox` / `CheckBox` | 选项字段 | `fieldOptions`、`optionTemplate`、`multiple` |
+| `Employee` / `Department` | 人员、部门 | `multiple`、`defaultValue` |
+| `FileComponent` | 附件 | 通用显示属性 |
+| `EInvoice` | 电子发票 | 通用显示属性 |
+| `AudioRecord` / `VideoRecord` | 语音、视频 | 通用显示属性 |
+| `DetailTable` | 明细表 | `formFields`、二级明细属性 |
+| `EBuilder` | 关联 EB 表单 | `sformId`、`dataTitle`、`displayColumns`、`multiple` |
+| `Flow` | 关联流程数据 | `sformId` 指向流程绑定的表单 objId |
+| `Browser` / `RelateBrowser` | 通用关联浏览 | `browserType`、`browserFormSource`、`multiple` |
+| `Project` / `Task` / `Document` / `Agenda` | 项目、任务、文档、日程 | `multiple` |
+| `FormData` | 原生关联表单数据 | `multiple` |
+| `Customer` / `Clue` / `Contact` / `Chance` | CRM 关联 | `multiple` |
+| `Product` / `Activity` / `Quote` / `Competitor` | CRM 业务关联 | `multiple` |
+| `Performance` / `Report` / `Attend` | 绩效、汇报、考勤 | 类型专属配置 |
+| `RelateODoc` / `RelateTag` | 公文、标签 | `multiple`、类型专属配置 |
+| `DrivingRecord` | 行车记录 | `defaultRows` |
+
+人员相关业务字段使用 `Employee`，附件字段使用 `FileComponent`。
+
+## 文本、数字和日期
+
+```json
+{"componentKey":"Text","fieldName":"项目编号","maxLen":500},
+{"componentKey":"TextArea","fieldName":"项目简介","maxLen":4000,"singleRow":true},
+{"componentKey":"Number","fieldName":"成本占比","precision":2,"percent":true},
+{"componentKey":"Money","fieldName":"合同金额","precision":2,"delimiter":true,"capital":true},
+{"componentKey":"Date","fieldName":"计划结束日期","minField":"计划开始日期"},
+{"componentKey":"DateRange","fieldName":"合同有效期","format":"yyyy-MM-dd"}
+```
+
+- `Number` 缺省精度为 0；`Money` 缺省精度为 2。
+- 百分比字段以百分数显示，比例公式需要得到 0–100 的数值。
+- `minField` 表示本字段最早不得早于目标字段；`maxField` 表示最晚不得晚于目标字段。
+- 日期字段需要当前日期默认值时写 `"defaultValue":true`。
+- 字段本身包含起止含义时优先使用 `DateRange`。
+
+## 选项、默认值与多选
+
+```json
+{"componentKey":"Select","fieldName":"状态","fieldOptions":[{"name":"启用"},{"name":"停用"}]},
+{"componentKey":"Employee","fieldName":"项目成员","multiple":true}
+```
+
+`valueKey` 可省略，由 CLI 生成；手工指定时使用数字字符串。共享选项可使用：
+
+```json
+{"componentKey":"Select","fieldName":"优先级","optionTemplate":"优先级模板"}
+```
+
+`fieldOptions` 与 `optionTemplate` 选择其中一种。不写 `multiple` 或写 `false` 表示单选（`isSingle:true`）；写 `true` 表示多选（`isSingle:false`）。多选 Select 由 CLI 转为 `SelectMultiple`。
+
+## EBuilder 与字段带出
+
+```json
+{"componentKey":"EBuilder","fieldName":"关联客户","sformId":"<目标表单objId>","dataTitle":"客户名称","displayColumns":["客户名称","客户类型"]}
+```
+
+`displayColumns` 未指定时，CLI 选择目标表单的业务字段作为浏览显示列。需要从关联记录带出值时，在目标字段写：
+
+```json
+{"componentKey":"Text","fieldName":"联系人","relateFrom":{"ebuilderField":"关联客户","sourceFieldId":"<目标字段fieldId>"}}
+```
+
+`sourceFieldId` 使用目标表单字段的数字 ID。
+
+## 原生关联类型码表
+
+| 关联对象 | `fields.json componentKey` | 平台组件 |
+|---|---|---|
+| 项目 | `Project` | `Mainline` |
+| 任务 | `Task` | `Task` |
+| 文档 | `Document` | `Document` |
+| 日程 | `Agenda` | `AgendaComponent` |
+| 表单数据 | `FormData` | `FormComponent` |
+| 客户、线索、联系人、商机 | `Customer` / `Clue` / `Contact` / `Chance` | 对应 CRM Component |
+| 产品、市场活动、报价、竞争对手 | `Product` / `Activity` / `Quote` / `Competitor` | 对应业务 Component |
+| 绩效、工作汇报、考勤 | `Performance` / `Report` / `Attend` | 对应业务 Component |
+| 通用浏览 | `Browser` / `RelateBrowser` | `RelateBrowser` |
+| 公文、标签 | `RelateODoc` / `RelateTag` | 同名平台组件 |
+| 行车记录 | `DrivingRecord` | `DrivingRecord` |
+
+已明确的专属参数包括考勤 `attendDateType`、行车记录 `defaultRows`、标签 `range`。参数值按实际需求或接口返回配置。
+
+## 通用关联浏览
+
+| 浏览对象 | `browserType` | 其他参数 |
+|---|---|---|
+| 工作流 | `workflow` | 缺省类型 |
+| 人事合同 | `hrcontract` | — |
+| 表单 | `form` | `browserFormSource:business|ebuilder` |
+| 角色 | `role` | — |
+| 档案 | `archive` | — |
+
+```json
+{"componentKey":"Browser","fieldName":"关联业务表单","browserType":"form","browserFormSource":"business"},
+{"componentKey":"Browser","fieldName":"关联EB表单","browserType":"form","browserFormSource":"ebuilder"}
+```
+
+## 明细表与公式
+
+```json
+{"componentKey":"DetailTable","fieldName":"订单明细","formFields":[
+  {"componentKey":"Text","fieldName":"商品名称"},
+  {"componentKey":"Number","fieldName":"数量"},
+  {"componentKey":"Number","fieldName":"单价","precision":2}
+]}
+```
+
+二级明细使用 `enableSubDetail`、`defaultExpandRow` 和 `subDetailConfig`。明细子字段支持常用属性、选项、日期限制和公式。
+
+```json
+{"componentKey":"Number","fieldName":"合计金额","formula":"SUM({付款明细.付款金额})"}
+```
+
+公式对象还可以包含 `expression`、`returnType` 和 `name`。完整表达式规则见 [字段公式函数参考](guide-form-formula-functions.md)。

package/skill-docs/references/hrm/guide-matrix.md

@@ -15,7 +15,7 @@
 | `e10-cli matrix config-edit <id>` | 编辑配置。`--condition` `--value` 或 `--config` 一次性提交 |
 | `e10-cli matrix enable <id>` | 启用矩阵 |
 | `e10-cli matrix disable <id>` | 停用矩阵 |
-| `e10-cli matrix delete <ids...>` | 删除矩阵 |
+| `e10-cli matrix delete <ids...>` | 删除矩阵。**矩阵里有数据行时平台会拒绝删除**（报"存在不能删除的矩阵"且不指出是哪个）——先 `matrix data delete <id> <rowIds...>` 清空数据行再删；批量删除时只要有**一条**不可删，整批都失败 |
 
 ### 矩阵数据维护
 
@@ -32,13 +32,13 @@
 ## 典型工作流
 
 ```bash
-# 1. 创建矩阵
+# 1. 创建矩阵（新建即启用；分权租户的所属机构自动取当前机构）
 e10-cli matrix create "审批人映射表" --type 2 --desc "部门→审批人"
 
 # 2. 查 ID
 e10-cli matrix list --name "审批人"
 
-# 3. 配字段（条件=部门，值=审批人）—— 注意：首次配置可能需在 UI 操作
+# 3. 配字段（条件=部门，值=审批人）—— 直接可用，不需要先开设计器
 e10-cli matrix config-edit <matrixId> \
   --condition '[{"type":"department","name":"所属部门"}]' \
   --value '[{"type":"resource","name":"审批人","singleType":1}]'
@@ -61,6 +61,57 @@ e10-cli workflow set-operator <wf> <nodeId> --type matrix \
 
 ---
 
+## 系统矩阵 vs 自定义矩阵
+
+`matrix list --json` 每条记录带三个标记位，决定这个矩阵能改什么：
+
+| 字段 | 取值 | 含义 |
+|---|---|---|
+| `type` | `0` / `1` / `2` | `0`=分部矩阵、`1`=部门矩阵、`2`=自定义矩阵 |
+| `sysType` | `1` / `0` | `1`=系统矩阵（平台内置的组织维度矩阵），`0`=非系统 |
+| `syncType` | `1` / `0` | `1`=数据行随系统组织同步，`0`=手工维护 |
+
+- **系统矩阵**（`sysType=1`，即 type 0/1 的分部/部门矩阵）：条件列由平台内置的组织维度决定（分部 / 部门），建好后不自行增删条件列；`syncType=1` 时数据行随系统组织同步，不需要 `matrix data save` 手工填（典型：`部门矩阵` —— 条件列=部门、值列为空、描述"同步系统部门信息"）。
+- **自定义矩阵**（`sysType=0`，`type=2`）：条件列与值列都自由配置，数据行手工维护，可带 `belongOrgId` 归属机构。
+
+> 两者**在流程里的用法完全一样**（都是 `workflow set-operator --type matrix`），差别只在"条件列从哪来 / 数据谁来填"。
+
+**所属机构与分权**：矩阵强制校验"所属机构"，而落到哪个字段由**分权状态**决定——分权开启时平台读 `belong_org_id`（归属机构），关闭时读 `targetId`。CLI 建矩阵前会自动查 `check-detach` 判断并选对字段，分权租户还会直接用返回的当前机构兜底，所以 `matrix create` 通常不用手写机构；只有"非分权租户"或"归属机构与目标机构必须不同"时才需要 `--org-id` / `--target-id`。
+
+**列表的状态过滤**：`matrix list` 走管理端点 `matrix2/list`，能看到**停用的矩阵**并显示真实状态；`--name`（模糊）、`--enable-status`、`--org-id` 都是服务端过滤。
+
+## 完整配置：条件列 → 人员列 → 数据映射 → 运行时读回
+
+```bash
+# ① 建矩阵（自定义矩阵。系统矩阵是平台内置的，用 matrix list 找现成的）
+#    新建即为「启用」状态，不需要再 enable；要停用才跑 matrix disable
+#    所属机构：分权租户自动取当前机构，非分权租户用 --org-id 显式指定（不加会有"所属机构不能为空"）
+e10-cli matrix create "部门审批人" --type 2 --desc "部门→审批人"
+
+# ② 配列：条件列 + 值列。值列 type=resource 就是"人员列"；singleType 0=多选 1=单选
+e10-cli matrix config-edit <matrixId> \
+  --condition '[{"type":"department","name":"所属部门"}]' \
+  --value '[{"type":"resource","name":"审批人","singleType":1}]'
+
+# ③ 取各列 configId（数据映射的键就是它），再填数据行
+e10-cli matrix config <matrixId>            # → conditionConfigList[].id / valueConfigList[].id
+e10-cli matrix data save <matrixId> --rows @rows.json
+e10-cli matrix data list <matrixId>         # 回读数据行
+
+# ④ 启用并挂到流程节点
+e10-cli matrix enable <matrixId>
+e10-cli workflow set-operator <wf> <nodeId> --type matrix \
+  --matrix-id <matrixId> --value-config-id <值列configId> \
+  --matrix-rule "<条件列configId>:1:1:1"
+
+# ⑤ 运行时读回：确认条件列/值列是否就是流程实际在读的那一组
+e10-cli matrix config <matrixId>
+```
+
+> **矩阵类型不用手填**：`--type matrix` 的 `sourceType` / 条件列中文名由 CLI 自动读 `GET /api/bs/hrm/matrix2/config?id=<matrixId>` 解析——`conditionConfigList[].type` 是 `department` 即部门矩阵、`subcompany` 即分部矩阵。条件列不在目标矩阵里时会直接报错并列出可选列，不会静默挂错。
+>
+> 排查"取不到人"时按这个顺序看：`matrix config`（列对不对）→ `matrix data list`（行有没有）→ 流程节点的矩阵规则是否引用了正确的 `条件configId`。
+
 ## 字段类型枚举
 
 | 中文 | API 值 |

package/skill-docs/references/workflow/guide-workflow-action.md

@@ -49,6 +49,8 @@ e10-cli workflow save-action @action.json
 
 跨表单动作流的**生成**统一走 `e10-cli actionflow generate`：写一份语义 plan（`event` + `actions`），CLI 编译、preflight、保存并启用、正式回读，返回设计器链接。组件参数、映射、条件的权威是 `e10-cli actionflow component-describe <type>`，参考 `actionflows/references/components/` 下对应组件 md。下面是平台机制要点，写 plan 时按此组织。
 
+除 e-builder/流程数据动作外，动作流还支持 HTTP/HTTPS 接口调用、DML 数仓 SQL/存储过程、自定义事件、内置 MQ 监听/发送、消息、文档、人员、会议和日程等组件。HTTP 必须先按“连接器 → 连接信息 → 接口 → 接口详情”读取当前环境对象；请求参数通过接口详情真实 `table`/`paramKey` 配置 `inputParams`，不要猜测或重建 `request.tables`。DML 的数据源连接必须先用 `e10-cli actionflow datasource-list` 查询，SQL 占位符与 `fieldSet` 必须一致；详细约束分别见 `actionflows/references/components/http/Http.md` 和 `actionflows/references/components/database/DMLExecute.md`。
+
 已有动作流的局部变更不要重新生成新应用；先用 `read-design --out` 保存正式设计，再按 `actionflows/SKILL.md` 的 `update` 计划格式提交显式 `operations`。更新器会自动备份原设计并保留未声明内容，不能按名称选择目标，也不会在保存/回读失败时自动回滚或删除目标。更新计划中的节点 ID 必须来自这次正式回读；保存新版时平台可能重分配动作/出口节点 ID，CLI 会按新版版本列表定位新场景并按动作树结构回读校验，不能把新 ID 变化误判为失败。更新时触发器 `event` 必须保持原样，不能修改触发类型、触发表单、触发时机或其他触发器参数；如果需求要变更触发器，必须改为新建动作流，CLI 会在检查/保存前明确拒绝。正常更新通过后调用 `saveDesign` 时固定使用 `saveNewVersion:true`，保存为该动作流的新版本。
 
 ### 平台机制要点

package/skill-docs/references/workflow/guide-workflow-condition.md

@@ -6,6 +6,8 @@
 
 **一行命令搞定**，自动校验字段类型、自动生成 API payload、自动绑定到连线：
 
+命令中的 `<sourceId>` 是要绑定条件的**连线 ID（linkId）**，`<nodeId>` 是该连线的**来源节点 ID（srcNodeId）**，不是目标节点 ID。可先执行 `workflow nodes <wf> --json` 或 `workflow link-list <wf>`，从同一条连线中取得这两个值。
+
 > **AND / OR 规则写在「同一次调用」里**：要组合多条规则，一次 `add` 传多个 `--rule` + `--relation AND|OR`，例如
 > `--rule "form:金额:大于:1000" --rule "system:流程标题:包含:合同" --relation AND`。
 >
@@ -109,7 +111,9 @@ e10-cli workflow condition add <wf> <sourceId> <nodeId> "超标" \
 
 ### 明细字段条件
 
-末尾必带量词 `:任一`(任一行满足) / `:所有`(所有行满足)：
+末尾量词 `:任一`(任一行满足，**缺省**) / `:所有`(所有行满足)：
+
+> **量词只对明细字段生效**：它决定"明细任一行 / 所有行"的语义，只有左字段属于明细表时才会写入配置。**写在主表字段上会被忽略且不报错**——主表字段直接省略量词。明细字段省略量词时按"任一行"处理。
 
 ```bash
 # 明细任一行金额>1万
@@ -125,14 +129,30 @@ e10-cli workflow condition add <wf> <sourceId> <nodeId> "明细发票日期" \
   --rule "form:发票日期:小于:field:报销日期:任一"
 ```
 
+明细量与主表条件组合（同一次调用内，多条 `--rule` 默认 AND）：
+
+```bash
+# 所属部门=财务部 AND 明细任一行金额>1万
+e10-cli workflow condition add <wf> <sourceId> <nodeId> "财务部大额明细" \
+  --rule "form:所属部门:等于:财务部" \
+  --rule "form:明细金额:大于:10000:任一"
+
+# 明细所有行数量都在 1~100 AND （发起时间≥报销日期）
+e10-cli workflow condition add <wf> <sourceId> <nodeId> "明细数量且时间" \
+  --rule "form:明细数量:范围:1:100:所有" \
+  --rule "system:发起时间:大于等于:field:报销日期"
+```
+
+> 需要"明细任一行满足 A **或** 任一行满足 B"时，用 `|` 把两条明细规则串在同一条 `--rule` 里（见下方 OR 分组），两条各带各的量词。
+
 ### OR 分组：用 `|` 分隔子规则
 
 同一条 `--rule` 内用 `|` 分隔表示 OR 关系：
 
 ```bash
-# 报销类型∈{差旅费,住宿费} OR 发票编号以FP开头
-e10-cli workflow condition add <wf> <sourceId> <nodeId> "差旅住宿或FP发票" \
-  --rule "form:报销类型:属于:差旅费,住宿费:任一|form:发票编号:包含:FP:任一"
+# 报销类型∈{差旅费,住宿费} OR 发票编号含 FP（两个都是主表字段，不带量词）
+e10-cli workflow condition add <wf> <sourceId> <nodeId> "差旅住宿或含FP发票" \
+  --rule "form:报销类型:属于:差旅费,住宿费|form:发票编号:包含:FP"
 
 # 报销金额>10000 OR 紧急程度=紧急
 e10-cli workflow condition add <wf> <sourceId> <nodeId> "大额或紧急" \
@@ -147,14 +167,36 @@ e10-cli workflow condition add <wf> <sourceId> <nodeId> "大额或紧急" \
 ```bash
 # 报销初审→财务部专项复核：
 # AND条件：所属部门=财务部, 报销金额5k~10k, 发起时间≥报销日期,
-# OR条件(明细)：报销类型∈{差旅费,住宿费} OR 发票编号以FP开头
+# OR条件：报销类型∈{差旅费,住宿费} OR 发票编号含 FP
 e10-cli workflow condition add <wf> <sourceId> <nodeId> "财务部复核" \
   --rule "form:所属部门:等于:财务部" \
   --rule "form:报销金额:范围:5000:10000" \
   --rule "system:发起时间:大于等于:field:报销日期" \
-  --rule "form:报销类型:属于:差旅费,住宿费:任一|form:发票编号:包含:FP:任一"
+  --rule "form:报销类型:属于:差旅费,住宿费|form:发票编号:包含:FP"
 ```
 
+### 平台边界：不支持"前缀匹配"
+
+出口条件**没有「以…开头 / 开头包含」运算符**。文本字段可用的比较符就是：等于、不等于、包含、不包含、为空、不为空——其中 **「包含」是全串包含**，`FP` 出现在编号任意位置都算命中，不限定开头。
+
+写前缀操作会被当场拒绝，不会静默存错：
+
+```bash
+e10-cli workflow condition add <wf> <sourceId> <nodeId> "FP发票" --rule "form:发票编号:开头包含:FP"
+# ❌ 字段 "发票编号" (类型=String) 不支持操作 "开头包含"，可选: 等于, 不等于, 包含, 不包含, 为空, 不为空
+```
+
+要表达"编号以 FP 开头"，按下列顺序选，**不要**把「包含」当「开头」用：
+
+1. **编号规则本身前缀唯一**——同前缀不会出现在其他类别里，直接用「包含」，语义等价；
+2. **取值有限**——用「属于」逐项枚举，如 `属于:FP001,FP002,FP003`；
+3. **确实要严格前缀语义**——不在出口条件解决：改用节点提交校验（`workflow node validate`）或表单/编号规则层约束；
+4. **都不行**——走平台需求，不要在方案里承诺出口条件支持前缀。
+
+> **判据以协议为准**：可用关系符的唯一权威来源是 `POST /api/workflow/pathdef/rule/condition/getRuleDesignCondition` 的当次响应（`otherItems` / `browserCompareOptions`），历史编码矩阵只作参考。协议里没有的语义，**直接判定不支持，不要用相近编码替代**——这条是平台接口文档的明确要求（"关系符不含目标语义 → 不生成该叶子，不用相近编码替代"）。
+>
+> 同理，`结尾包含`、正则匹配在这个域也不存在。
+
 ## 添加分支条件（原始 JSON，完整控制）
 
 需要 4 步操作：

package/skill-docs/references/workflow/guide-workflow-odoc.md

@@ -0,0 +1,76 @@
+# 公文流程指南
+
+## 定位
+
+公文流程是原生工作流程的特殊类型，由 `bridgeService=odoc` 标识。固定/自由通过 `--is-free 0|1` 设置。需求明确出现公文流程、公文审批、收文、发文、公文设置或正文设置时读取本指南；基础节点、出口、操作者、条件和布局规则同时读取 [流程表单指南](guide-workflow.md)。
+
+## 创建
+
+### 随流程自建原生流程表单
+
+```bash
+e10-cli workflow create-workflow "公文审批流程" --odoc --layout FLOW
+```
+
+自建模式沿用原生工作流程路径，提交 `relateForm=0`、`formId=0` 和 `bridgeService=odoc`。表格式布局使用 `--layout EXCEL`。
+
+### 绑定已有原生流程表单
+
+```bash
+e10-cli workflow create-workflow "公文审批流程" --odoc --form-id <formId>
+```
+
+绑定模式提交 `relateForm=1`、`formId=<已有原生流程表单ID>` 和 `bridgeService=odoc`。后续字段与布局继续使用 `wf-form` 和原生流程表单 `formId`。
+
+团队流程默认使用当前创建者机构；多机构场景再显式传 `--sub-company <机构ID>`。其他通用参数如 `--workflow-type`、`--desc`、`--is-free` 与普通原生工作流程一致。
+
+## 创建结果与后续配置
+
+命令返回 `workflowId` 和 `formId`，JSON 结果以 `flowKind:"odoc"`、`bridgeService:"odoc"` 标识公文流程。创建后的列表回读同样带 `bridgeService=odoc`，并核对返回记录的 `bridgeService`。
+
+取得 `workflowId` 后，节点、出口、操作者、出口条件、会签、退回、超时、消息、编号和动作流继续使用通用 `workflow` 命令。
+
+## 公文专属配置
+
+### 查询
+
+```bash
+e10-cli workflow odoc list [--name <关键词>] [--sub-company <机构ID>]
+e10-cli workflow odoc read <workflowId>
+```
+
+`list` 使用 `bridgeService=odoc` 查询公文流程；`read` 返回流程名称、绑定表单 `formId` 和公文设置摘要。
+
+### 读取与保存公文设置
+
+```bash
+e10-cli workflow odoc setting get <workflowId>
+e10-cli workflow odoc setting set <workflowId> --config @odoc-setting.json
+```
+
+`setting set` 读取当前配置、合并指定内容、保存并回读。配置 JSON 可直接使用平台字段，也可按 `basic`、`text`、`files`、`nodes`、`signature`、`archive`、`ai` 分组；`number` 映射为 `odocNumber`，`attachmentArea` 映射为 `odocAttachArea`。
+
+常用配置也可直接使用参数：
+
+```bash
+e10-cli workflow odoc setting set <workflowId> \
+  --official-type 1 \
+  --request-title-field "公文标题" \
+  --upload-word 1 --upload-pdf 1 --upload-ofd 1 \
+  --text-in-form 1 --column-position 1 \
+  --attach-area 1 --archive-node "归档"
+```
+
+字段参数支持字段名称或字段 ID，节点参数支持节点名称或节点 ID。平台开关值使用 `0` 和 `1`。
+
+### 配置结构
+
+- 基础正文：`officialType`、`requestTitleField`、`flowDocField`、`documentTitleField`、`defaultCat`、`flowDocCatField`、`docPropSettings`。
+- 正文展示：`openTextDefaultNode`、`editTextNode`、`previewDefault`、`isTextInForm`、`columnPosition`、`textColumnSize`。
+- 文件与签章：`uploadWORD`、`uploadPDF`、`uploadOFD`、`signGroupMould`、`signNodeList`、`openSignatureSeal`。
+- 公文编号：`odocNumber`。
+- 附件区域：`odocAttachArea`，包含启用状态、打开节点、展示位置及正文/附件比例。
+- 归档：`archivesForm`、`archivesNodeOpen`、`archivesNode`、`archivesAuth` 和字段映射设置。
+- AI 与格式：`openAiAbstract`、`openAiFormat`、`defaultFormatTemplate`、`showAiAssistant`、`showOfficialDoc`。
+
+保存请求携带完整公文设置，其中字段选择值为字段 ID、节点选择值为节点 ID，`signNodeList` 保存节点及其启用、必填状态。