@steedos-labs/plugin-workflow 3.0.39 → 3.0.40

package/main/default/routes/api_workflow_ai_form_design.router.js

@@ -75,6 +75,7 @@ router.post('/am/ai/form-design', async function auth(req, res, next) {
   - "org" — 组织（选择单个部门）
   - "orgMulti" — 组织（多选，选择多个部门）
   - "reference" — 对象选择（选择指定对象的记录，支持多选，可展示记录的多个字段）
+  - "richtext" — 富文本（支持格式化文本、颜色、链接等）
 - required: 布尔值，是否必填
 - colspan: 数字，字段占几列，取值范围 1~tableColumns。默认 1（占一列），设为 tableColumns 则独占一行。section 和 table 始终等于 tableColumns
 - description: 字符串，字段说明/提示文字，支持 HTML
@@ -168,6 +169,19 @@ router.post('/am/ai/form-design', async function auth(req, res, next) {
   - pickerMultiple: 布尔值，是否允许多选，默认 false
   - lookupFilters: 字符串，OData 过滤表达式，如 "status eq 'active'"
   - lookupDisplayFields: 数组，关联数据后额外展示的字段，格式 [{ "field": "字段API名", "label": "显示标签" }]
+  - lookupFillRules: 数组，填充规则，选择关联记录后将源字段值自动填充到表单其他字段。格式 [{ "sourceField": "关联对象的字段API名", "targetField": "当前表单中的目标字段name" }]
+    - 示例：选择合同后自动填充合同金额到表单的金额字段：lookupFillRules: [{ "sourceField": "amount", "targetField": "contract_amount" }]
+
+- member 类型（成员单选）填充规则：
+  - pickerFillRules: 数组，选择人员后将人员字段值自动填充到表单其他字段。源对象为 space_users。格式 [{ "sourceField": "源字段API名", "targetField": "当前表单中的目标字段name" }]
+  - sourceField 支持点号表示法，可访问关联对象的子属性。成员的 organization 字段引用了 organizations 对象，因此可以使用 "organization.xxx" 访问部门属性
+  - 可用的 organization 子属性示例：organization.name（部门名称）、organization.fullname（部门全称）等
+  - 示例：选择成员后自动填充其所属部门名称到文本字段：
+    pickerFillRules: [{ "sourceField": "organization.name", "targetField": "dept_name" }, { "sourceField": "name", "targetField": "user_name" }]
+
+- org 类型（部门单选）填充规则：
+  - pickerFillRules: 数组，选择部门后将部门字段值自动填充到表单其他字段。源对象为 organizations。格式同 member 的 pickerFillRules
+  - 示例：选择部门后自动填充部门全称到文本字段：pickerFillRules: [{ "sourceField": "fullname", "targetField": "org_fullname" }]
 
 - reference 类型（对象选择）：
   - reference_to: 字符串，关联对象的 API 名称，如 "contracts"、"accounts"
@@ -193,16 +207,22 @@ router.post('/am/ai/form-design', async function auth(req, res, next) {
 ## 事件脚本
 
 events 对象包含三个可选的 JavaScript 脚本：
-- onInit: 表单初始化时执行。可用参数：form (表单实例), fields (字段数据)
+- onInit: 表单初始化时执行。可用参数：form (表单实例), fields (字段数据), currentStep (当前审批步骤对象)
   - form.setFieldValue(fieldName, value) — 设置字段值
   - form.getFieldValue(fieldName) — 获取字段值
   - form.setFieldOptions(fieldName, options) — 设置下拉选项
   - form.setFieldHidden(fieldName, hidden) — 显隐字段
   - form.setFieldRequired(fieldName, required) — 设为必填
-- onValueChange: 字段值变化时执行。可用参数：field (变化的字段), value (新值), oldValue (旧值), form (表单实例), values (所有字段值)
-- onSubmit: 表单提交前执行。可用参数：form (表单实例), values (提交数据)。返回 false 可阻止提交
+  - form.currentStep — 当前审批步骤对象，包含 name(步骤名)、step_type(步骤类型: start/submit/sign/counterSign/condition)、_id 等属性
+- onValueChange: 字段值变化时执行。可用参数：field (变化的字段), value (新值), oldValue (旧值), form (表单实例), values (所有字段值), currentStep (当前审批步骤对象)
+- onSubmit: 表单提交前执行。可用参数：form (表单实例), values (提交数据), currentStep (当前审批步骤对象)。返回 false 可阻止提交
+
+所有脚本支持 async/await。
+⚠️ 脚本内容直接写代码体，参数（form、field、value 等）由运行时自动注入，**禁止用 function(...){} 包裹**。
+正确："if (field.name === 'x') { ... }"
+错误："function(field, value, oldValue, form, values) { ... }"
 
-所有脚本支持 async/await，示例：
+示例：
 \`\`\`javascript
 // onValueChange 示例
 if (field.name === 'quantity' || field.name === 'unit_price') {
@@ -227,14 +247,16 @@ if (field.name === 'quantity' || field.name === 'unit_price') {
 新版表单已**不再支持** instance_template（审批单模板）、form_script（表单脚本）、flow_events（流程事件），这些是旧版的遗留功能。当用户提供这些数据时，你需要：
 
 1. **分析其中的业务逻辑**，理解它们实现了什么功能
-2. **将业务逻辑迁移到新版机制中**：
-   - 字段显隐控制 → 转为字段的 visibilityRules
-   - 动态必填控制 → 转为字段的 requiredRules
-   - 字段值自动计算 → 转为 formula 类型字段，或写入 events.onValueChange
+2. **⭐ 声明式字段配置优先，脚本兜底**。迁移旧版脚本时，按以下优先级选择实现方式——能用字段属性声明式解决的，绝不写事件脚本：
+   - 数值范围校验（如金额上限/下限）→ number 字段的 **min / max** 属性（而非 onSubmit 脚本校验）
+   - 字段显隐控制 → 字段的 **visibilityRules**（而非 onValueChange 中 form.setFieldHidden()）
+   - 动态必填控制 → 字段的 **requiredRules**（而非 onValueChange 中 form.setFieldRequired()）
+   - 字段值自动计算 → **formula** 类型字段（而非 onValueChange 中 form.setFieldValue()），仅当公式语法无法表达时才退化到 onValueChange
+   - 跨对象属性引用（如旧公式 {applicant.organization.name}）→ 成员字段的 **pickerFillRules**，sourceField 使用点号表示法如 "organization.name"，targetField 指向目标文本字段
+   - 字段选项设置 → 字段的 **options** 属性（静态选项），仅动态/异步加载选项时才用 events.onInit / events.onValueChange 中 form.setFieldOptions()
    - 初始化赋值/选项加载 → 写入 events.onInit
-   - 值联动/级联逻辑 → 写入 events.onValueChange
-   - 提交前校验 → 写入 events.onSubmit
-   - 字段选项设置 → 转为字段的 options 属性，或通过 events.onInit / events.onValueChange 中 form.setFieldOptions() 设置
+   - 值联动/级联逻辑（无法用 formula 表达时）→ 写入 events.onValueChange
+   - 提交前复杂校验（无法用 min/max/required 等表达时）→ 写入 events.onSubmit
 3. **instance_template 仍可用于推断字段 label、colspan（列宽）和 rowspan（行高）**
 4. **不要在输出中返回** instance_template、form_script、flow_events 字段
 
@@ -313,8 +335,54 @@ if (field.name === 'quantity' || field.name === 'unit_price') {
 - 新版事件脚本使用 form.getFieldValue() / form.setFieldValue() / form.setFieldOptions() / form.setFieldHidden() / form.setFieldRequired() 等 API
 
 ### 流程事件 (flow_events)
-- 旧版流程级别的事件脚本
-- 分析其中的业务逻辑，合并迁移到新版的 events 中
+- 旧版流程级别的事件脚本，通常绑定在 jQuery 事件上（如 \`instance-before-submit\`、\`instance-before-save\` 等）
+- 分析其中的业务逻辑，**优先用字段声明式配置实现，无法声明式表达时才写入 events 脚本**
+- 常见迁移模式：
+  - \`instance-before-submit\` 中的数值范围校验（如 \`money >= 5000000\` 则阻止提交）→ **直接设置 number 字段的 max 属性**，如 \`"max": 4999999.99\`，无需写 onSubmit 脚本
+  - \`instance-before-submit\` 中的必填校验 → 设置字段 \`required: true\` 或 \`requiredRules\`
+  - \`instance-before-submit\` 中的复杂跨字段校验（如"结束日期必须大于开始日期"且无法用单字段属性表达）→ 写入 events.onSubmit，用 \`form.getFieldValue()\` 获取值，返回 \`false\` 阻止提交
+  - \`instance-before-save\` 中的自动赋值 → 写入 events.onInit 或 events.onValueChange
+  - \`WorkflowManager.getInstance().state\` 等实例状态判断 → 新版 onSubmit 仅在提交时触发，草稿保存不触发，通常可省略状态判断
+  - \`e.preventDefault()\` + \`toastr.error(msg)\` → 新版用 \`form.showError(msg); return false;\` 替代
+- 注意：旧版脚本中的字段引用（如 \`formValues['中文字段名']\`）需替换为新版英文字段 name
+- 注意：旧版脚本是 JavaScript 语法，其中被注释掉的代码（// 单行注释 或 /* */ 块注释）属于废弃逻辑，不需要识别和迁移，直接忽略即可
+- 迁移示例：
+  旧版 flow_events：
+  \`\`\`javascript
+  var money = parseFloat(formValues['申请增加额度']);
+  if (money >= 5000000) { e.preventDefault(); toastr.error('金额不能超过500万'); }
+  \`\`\`
+  新版迁移方式：**不写脚本**，直接在字段上配置：
+  \`\`\`json
+  { "name": "apply_increase_amount", "type": "number", "max": 4999999.99, "precision": 2 }
+  \`\`\`
+
+### 旧版 HTML 字段类型迁移
+- 旧版表单中存在 type 为 \"html\" 的字段，这是旧版的 HTML 编辑器字段，允许用户输入和编辑 HTML 格式的富文本内容
+- 新版表单中 **不再支持 \"html\" 类型**，已被 **\"richtext\"（富文本）** 类型完全替代
+- **迁移规则**：当遇到 type 为 \"html\" 的字段时，必须将其 type 改为 \"richtext\"，其余属性（name、label、required、colspan、defaultValue 等）保持不变
+- richtext 类型支持格式化文本、颜色、链接等富文本编辑功能，功能上完全覆盖旧版 html 类型
+- 迁移示例：
+  旧版字段：{ "name": "content", "label": "内容", "type": "html" }
+  新版字段：{ "name": "content", "label": "内容", "type": "richtext" }
+- migrationLog 记录格式："字段 <name>: type 从 html 转换为 richtext"
+
+### 旧公式字段跨对象引用迁移
+- 旧版表单中，公式字段可能通过 \`{applicant.organization.name}\`、\`{applicant.name}\` 等语法引用成员的关联属性。这种跨对象引用在新版中不再通过公式实现，而是通过**成员字段的 pickerFillRules（填充规则）**来替代。
+- 迁移方式：
+  1. 将引用跨对象属性的公式字段改为**普通文本字段**（type: "text"）作为目标字段
+  2. 在成员字段（type: "member"）上配置 **pickerFillRules**，使用点号表示法的 sourceField（如 "organization.name"），targetField 指向该文本字段
+  3. 如果 targetField 字段应为只读展示（即旧版是纯展示的公式字段），设置 readonly: true
+- 迁移示例：
+  旧版公式字段：\`{applicant.organization.name}\` 用于显示申请人所属部门名称
+  新版迁移方式：
+  1. 创建文本字段 { "name": "dept_name", "label": "所属部门", "type": "text", "readonly": true }
+  2. 在成员字段上配置 pickerFillRules: [{ "sourceField": "organization.name", "targetField": "dept_name" }]
+- 常见映射：
+  - \`{applicant.organization.name}\` → sourceField: "organization.name"
+  - \`{applicant.organization.fullname}\` → sourceField: "organization.fullname"
+  - \`{applicant.name}\` → sourceField: "name"
+  - \`{applicant.mobile}\` → sourceField: "mobile"
 
 ## 输出格式
 返回一个 JSON 对象，格式如下（不要有任何其他文字、解释、markdown 标记）：
@@ -325,8 +393,32 @@ if (field.name === 'quantity' || field.name === 'unit_price') {
     "onInit": "脚本代码或空字符串",
     "onValueChange": "脚本代码或空字符串",
     "onSubmit": "脚本代码或空字符串"
-  }
-}`;
+  },
+  "migrationLog": ["迁移记录，仅升级场景需要"]
+}
+
+### migrationLog（迁移记录）
+当用户提供了 flow_events、form_script、instance_template 中包含业务逻辑（如校验、赋值、显隐控制等脚本代码）时，必须在 migrationLog 数组中为每条被迁移的逻辑记录一条说明，格式：
+  "<来源>: <原逻辑简述> → <迁移到的具体位置>"
+
+迁移目标可以是以下任意一种：
+- 字段属性：如 "字段 apply_increase_amount 的 max:4999999.99"
+- 字段规则：如 "字段 remark 的 visibilityRules"、"字段 attachment_desc 的 requiredRules"
+- formula 字段：如 "新增 formula 字段 total_amount"
+- 事件脚本：如 "events.onSubmit"、"events.onValueChange"
+- 已省略（含原因）：如 "已省略（旧版 state=='draft' 判断，新版 onSubmit 仅提交时触发，无需判断）"
+
+示例：
+"migrationLog": [
+  "flow_events: 申请增加额度>=500万阻止提交 → 字段 apply_increase_amount 的 max:4999999.99",
+  "flow_events: ins.state!='draft' 状态判断 → 已省略（新版 onSubmit 仅提交时触发）",
+  "form_script: 根据类型字段显隐备注 → 字段 remark 的 visibilityRules",
+  "form_script: 选择部门后级联加载人员选项 → events.onValueChange",
+  "instance_template: {applicant.organization.name} 跨对象引用 → 成员字段 applicant 的 pickerFillRules (organization.name → dept_name)"
+]
+
+⚠️ 如果 flow_events 或 form_script 不为空但 migrationLog 为空数组，视为错误。每条旧版逻辑都必须有对应的迁移记录，不允许静默丢弃。
+如果没有提供 flow_events、form_script，或它们为空，则 migrationLog 可省略或为空数组。`;
 
     // Build current fields description
     const fieldsJson = JSON.stringify(fields || [], null, 2);
@@ -439,7 +531,7 @@ ${userRequest}
       'text', 'textarea', 'number', 'date', 'datetime', 'time',
       'select', 'multiSelect', 'checkbox', 'radio', 'file', 'image',
       'lookup', 'section', 'table', 'grid', 'formula',
-      'member', 'memberMulti', 'org', 'orgMulti', 'reference'
+      'member', 'memberMulti', 'org', 'orgMulti', 'reference', 'richtext'
     ];
     const jsIdentifierRe = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
     function sanitizeName(name) {
@@ -458,6 +550,8 @@ ${userRequest}
         if (field.type === 'groupPicker') field.type = field.pickerMultiple ? 'orgMulti' : 'org';
         // Backward compat: map legacy select + pickerMultiple to multiSelect
         if (field.type === 'select' && field.pickerMultiple) field.type = 'multiSelect';
+        // Backward compat: map legacy html type to richtext
+        if (field.type === 'html') field.type = 'richtext';
         if (field.type && !validTypes.includes(field.type)) {
           field.type = 'text'; // fallback to text for unknown types
         }
@@ -481,6 +575,8 @@ ${userRequest}
             if (child.type === 'userPicker') child.type = child.pickerMultiple ? 'memberMulti' : 'member';
             if (child.type === 'groupPicker') child.type = child.pickerMultiple ? 'orgMulti' : 'org';
             if (child.type === 'select' && child.pickerMultiple) child.type = 'multiSelect';
+            // Backward compat: map legacy html type to richtext
+            if (child.type === 'html') child.type = 'richtext';
             if (child.type && !validTypes.includes(child.type)) {
               child.type = 'text';
             }
@@ -512,6 +608,10 @@ ${userRequest}
         onSubmit: result.events.onSubmit || '',
       },
     };
+    // Pass through migrationLog if present (for upgrade audit trail)
+    if (Array.isArray(result.migrationLog) && result.migrationLog.length > 0) {
+      responseData.migrationLog = result.migrationLog;
+    }
     return res.json(responseData);
 
   } catch (error) {

package/main/default/routes/api_workflow_ai_form_design_stream.router.js

@@ -302,7 +302,7 @@ router.post('/am/ai/form-design-stream', async function auth(req, res, next) {
       'text', 'textarea', 'number', 'date', 'datetime', 'time',
       'select', 'multiSelect', 'checkbox', 'radio', 'file', 'image',
       'lookup', 'section', 'table', 'grid', 'formula',
-      'member', 'memberMulti', 'org', 'orgMulti', 'reference'
+      'member', 'memberMulti', 'org', 'orgMulti', 'reference', 'richtext'
     ];
     const jsIdentifierRe = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
     function sanitizeName(name) {
@@ -321,6 +321,8 @@ router.post('/am/ai/form-design-stream', async function auth(req, res, next) {
         if (field.type === 'groupPicker') field.type = field.pickerMultiple ? 'orgMulti' : 'org';
         // Backward compat: map legacy select + pickerMultiple to multiSelect
         if (field.type === 'select' && field.pickerMultiple) field.type = 'multiSelect';
+        // Backward compat: map legacy html type to richtext
+        if (field.type === 'html') field.type = 'richtext';
         if (field.type && !validTypes.includes(field.type)) {
           field.type = 'text';
         }
@@ -342,6 +344,8 @@ router.post('/am/ai/form-design-stream', async function auth(req, res, next) {
             if (child.type === 'userPicker') child.type = child.pickerMultiple ? 'memberMulti' : 'member';
             if (child.type === 'groupPicker') child.type = child.pickerMultiple ? 'orgMulti' : 'org';
             if (child.type === 'select' && child.pickerMultiple) child.type = 'multiSelect';
+            // Backward compat: map legacy html type to richtext
+            if (child.type === 'html') child.type = 'richtext';
             if (child.type && !validTypes.includes(child.type)) {
               child.type = 'text';
             }
@@ -370,6 +374,10 @@ router.post('/am/ai/form-design-stream', async function auth(req, res, next) {
         onSubmit: result.events.onSubmit || '',
       },
     };
+    // Pass through migrationLog if present (for upgrade audit trail)
+    if (Array.isArray(result.migrationLog) && result.migrationLog.length > 0) {
+      responseData.migrationLog = result.migrationLog;
+    }
 
     const fieldCount = (responseData.fields || []).length;
     sendEvent('progress', { stage: 'complete', message: `转换完成！共 ${fieldCount} 个字段` });
@@ -429,6 +437,7 @@ function buildSystemPrompt() {
   - "org" — 组织（选择单个部门）
   - "orgMulti" — 组织（多选，选择多个部门）
   - "reference" — 对象选择（选择指定对象的记录，支持多选，可展示记录的多个字段）
+  - "richtext" — 富文本（支持格式化文本、颜色、链接等）
 - required: 布尔值，是否必填
 - colspan: 数字，字段占几列，取值范围 1~tableColumns。默认 1（占一列），设为 tableColumns 则独占一行。section 和 table 始终等于 tableColumns
 - description: 字符串，字段说明/提示文字，支持 HTML
@@ -522,6 +531,19 @@ function buildSystemPrompt() {
   - pickerMultiple: 布尔值，是否允许多选，默认 false
   - lookupFilters: 字符串，OData 过滤表达式，如 "status eq 'active'"
   - lookupDisplayFields: 数组，关联数据后额外展示的字段，格式 [{ "field": "字段API名", "label": "显示标签" }]
+  - lookupFillRules: 数组，填充规则，选择关联记录后将源字段值自动填充到表单其他字段。格式 [{ "sourceField": "关联对象的字段API名", "targetField": "当前表单中的目标字段name" }]
+    - 示例：选择合同后自动填充合同金额到表单的金额字段：lookupFillRules: [{ "sourceField": "amount", "targetField": "contract_amount" }]
+
+- member 类型（成员单选）填充规则：
+  - pickerFillRules: 数组，选择人员后将人员字段值自动填充到表单其他字段。源对象为 space_users。格式 [{ "sourceField": "源字段API名", "targetField": "当前表单中的目标字段name" }]
+  - sourceField 支持点号表示法，可访问关联对象的子属性。成员的 organization 字段引用了 organizations 对象，因此可以使用 "organization.xxx" 访问部门属性
+  - 可用的 organization 子属性示例：organization.name（部门名称）、organization.fullname（部门全称）等
+  - 示例：选择成员后自动填充其所属部门名称到文本字段：
+    pickerFillRules: [{ "sourceField": "organization.name", "targetField": "dept_name" }, { "sourceField": "name", "targetField": "user_name" }]
+
+- org 类型（部门单选）填充规则：
+  - pickerFillRules: 数组，选择部门后将部门字段值自动填充到表单其他字段。源对象为 organizations。格式同 member 的 pickerFillRules
+  - 示例：选择部门后自动填充部门全称到文本字段：pickerFillRules: [{ "sourceField": "fullname", "targetField": "org_fullname" }]
 
 - reference 类型（对象选择）：
   - reference_to: 字符串，关联对象的 API 名称，如 "contracts"、"accounts"
@@ -547,16 +569,22 @@ function buildSystemPrompt() {
 ## 事件脚本
 
 events 对象包含三个可选的 JavaScript 脚本：
-- onInit: 表单初始化时执行。可用参数：form (表单实例), fields (字段数据)
+- onInit: 表单初始化时执行。可用参数：form (表单实例), fields (字段数据), currentStep (当前审批步骤对象)
   - form.setFieldValue(fieldName, value) — 设置字段值
   - form.getFieldValue(fieldName) — 获取字段值
   - form.setFieldOptions(fieldName, options) — 设置下拉选项
   - form.setFieldHidden(fieldName, hidden) — 显隐字段
   - form.setFieldRequired(fieldName, required) — 设为必填
-- onValueChange: 字段值变化时执行。可用参数：field (变化的字段), value (新值), oldValue (旧值), form (表单实例), values (所有字段值)
-- onSubmit: 表单提交前执行。可用参数：form (表单实例), values (提交数据)。返回 false 可阻止提交
+  - form.currentStep — 当前审批步骤对象，包含 name(步骤名)、step_type(步骤类型: start/submit/sign/counterSign/condition)、_id 等属性
+- onValueChange: 字段值变化时执行。可用参数：field (变化的字段), value (新值), oldValue (旧值), form (表单实例), values (所有字段值), currentStep (当前审批步骤对象)
+- onSubmit: 表单提交前执行。可用参数：form (表单实例), values (提交数据), currentStep (当前审批步骤对象)。返回 false 可阻止提交
 
-所有脚本支持 async/await，示例：
+所有脚本支持 async/await。
+⚠️ 脚本内容直接写代码体，参数（form、field、value 等）由运行时自动注入，**禁止用 function(...){} 包裹**。
+正确："if (field.name === 'x') { ... }"
+错误："function(field, value, oldValue, form, values) { ... }"
+
+示例：
 \`\`\`javascript
 // onValueChange 示例
 if (field.name === 'quantity' || field.name === 'unit_price') {
@@ -581,14 +609,16 @@ if (field.name === 'quantity' || field.name === 'unit_price') {
 新版表单已**不再支持** instance_template（审批单模板）、form_script（表单脚本）、flow_events（流程事件），这些是旧版的遗留功能。当用户提供这些数据时，你需要：
 
 1. **分析其中的业务逻辑**，理解它们实现了什么功能
-2. **将业务逻辑迁移到新版机制中**：
-   - 字段显隐控制 → 转为字段的 visibilityRules
-   - 动态必填控制 → 转为字段的 requiredRules
-   - 字段值自动计算 → 转为 formula 类型字段，或写入 events.onValueChange
+2. **⭐ 声明式字段配置优先，脚本兜底**。迁移旧版脚本时，按以下优先级选择实现方式——能用字段属性声明式解决的，绝不写事件脚本：
+   - 数值范围校验（如金额上限/下限）→ number 字段的 **min / max** 属性（而非 onSubmit 脚本校验）
+   - 字段显隐控制 → 字段的 **visibilityRules**（而非 onValueChange 中 form.setFieldHidden()）
+   - 动态必填控制 → 字段的 **requiredRules**（而非 onValueChange 中 form.setFieldRequired()）
+   - 字段值自动计算 → **formula** 类型字段（而非 onValueChange 中 form.setFieldValue()），仅当公式语法无法表达时才退化到 onValueChange
+   - 跨对象属性引用（如旧公式 {applicant.organization.name}）→ 成员字段的 **pickerFillRules**，sourceField 使用点号表示法如 "organization.name"，targetField 指向目标文本字段
+   - 字段选项设置 → 字段的 **options** 属性（静态选项），仅动态/异步加载选项时才用 events.onInit / events.onValueChange 中 form.setFieldOptions()
    - 初始化赋值/选项加载 → 写入 events.onInit
-   - 值联动/级联逻辑 → 写入 events.onValueChange
-   - 提交前校验 → 写入 events.onSubmit
-   - 字段选项设置 → 转为字段的 options 属性，或通过 events.onInit / events.onValueChange 中 form.setFieldOptions() 设置
+   - 值联动/级联逻辑（无法用 formula 表达时）→ 写入 events.onValueChange
+   - 提交前复杂校验（无法用 min/max/required 等表达时）→ 写入 events.onSubmit
 3. **instance_template 仍可用于推断字段 label、colspan（列宽）和 rowspan（行高）**
 4. **不要在输出中返回** instance_template、form_script、flow_events 字段
 
@@ -667,9 +697,53 @@ if (field.name === 'quantity' || field.name === 'unit_price') {
 - 新版事件脚本使用 form.getFieldValue() / form.setFieldValue() / form.setFieldOptions() / form.setFieldHidden() / form.setFieldRequired() 等 API
 
 ### 流程事件 (flow_events)
-- 旧版流程级别的事件脚本
-- 分析其中的业务逻辑，合并迁移到新版的 events 中
-
+- 旧版流程级别的事件脚本，通常绑定在 jQuery 事件上（如 \`instance-before-submit\`、\`instance-before-save\` 等）
+- 分析其中的业务逻辑，**优先用字段声明式配置实现，无法声明式表达时才写入 events 脚本**
+- 常见迁移模式：
+  - \`instance-before-submit\` 中的数值范围校验（如 \`money >= 5000000\` 则阻止提交）→ **直接设置 number 字段的 max 属性**，如 \`"max": 4999999.99\`，无需写 onSubmit 脚本
+  - \`instance-before-submit\` 中的必填校验 → 设置字段 \`required: true\` 或 \`requiredRules\`
+  - \`instance-before-submit\` 中的复杂跨字段校验（如"结束日期必须大于开始日期"且无法用单字段属性表达）→ 写入 events.onSubmit，用 \`form.getFieldValue()\` 获取值，返回 \`false\` 阻止提交
+  - \`instance-before-save\` 中的自动赋值 → 写入 events.onInit 或 events.onValueChange
+  - \`WorkflowManager.getInstance().state\` 等实例状态判断 → 新版 onSubmit 仅在提交时触发，草稿保存不触发，通常可省略状态判断
+  - \`e.preventDefault()\` + \`toastr.error(msg)\` → 新版用 \`form.showError(msg); return false;\` 替代
+- 注意：旧版脚本中的字段引用（如 \`formValues['中文字段名']\`）需替换为新版英文字段 name
+- 注意：旧版脚本是 JavaScript 语法，其中被注释掉的代码（// 单行注释 或 /* */ 块注释）属于废弃逻辑，不需要识别和迁移，直接忽略即可
+- 迁移示例：
+  旧版 flow_events：
+  \`\`\`javascript
+  var money = parseFloat(formValues['申请增加额度']);
+  if (money >= 5000000) { e.preventDefault(); toastr.error('金额不能超过500万'); }
+  \`\`\`
+  新版迁移方式：**不写脚本**，直接在字段上配置：
+  \`\`\`json
+  { "name": "apply_increase_amount", "type": "number", "max": 4999999.99, "precision": 2 }
+  \`\`\`
+### 旧版 HTML 字段类型迁移
+- 旧版表单中存在 type 为 \"html\" 的字段，这是旧版的 HTML 编辑器字段，允许用户输入和编辑 HTML 格式的富文本内容
+- 新版表单中 **不再支持 \"html\" 类型**，已被 **\"richtext\"（富文本）** 类型完全替代
+- **迁移规则**：当遇到 type 为 \"html\" 的字段时，必须将其 type 改为 \"richtext\"，其余属性（name、label、required、colspan、defaultValue 等）保持不变
+- richtext 类型支持格式化文本、颜色、链接等富文本编辑功能，功能上完全覆盖旧版 html 类型
+- 迁移示例：
+  旧版字段：{ "name": "content", "label": "内容", "type": "html" }
+  新版字段：{ "name": "content", "label": "内容", "type": "richtext" }
+- migrationLog 记录格式："字段 <name>: type 从 html 转换为 richtext"
+
+### 旧公式字段跨对象引用迁移
+- 旧版表单中，公式字段可能通过 \`{applicant.organization.name}\`、\`{applicant.name}\` 等语法引用成员的关联属性。这种跨对象引用在新版中不再通过公式实现，而是通过**成员字段的 pickerFillRules（填充规则）**来替代。
+- 迁移方式：
+  1. 将引用跨对象属性的公式字段改为**普通文本字段**（type: "text"）作为目标字段
+  2. 在成员字段（type: "member"）上配置 **pickerFillRules**，使用点号表示法的 sourceField（如 "organization.name"），targetField 指向该文本字段
+  3. 如果 targetField 字段应为只读展示（即旧版是纯展示的公式字段），设置 readonly: true
+- 迁移示例：
+  旧版公式字段：\`{applicant.organization.name}\` 用于显示申请人所属部门名称
+  新版迁移方式：
+  1. 创建文本字段 { "name": "dept_name", "label": "所属部门", "type": "text", "readonly": true }
+  2. 在成员字段上配置 pickerFillRules: [{ "sourceField": "organization.name", "targetField": "dept_name" }]
+- 常见映射：
+  - \`{applicant.organization.name}\` → sourceField: "organization.name"
+  - \`{applicant.organization.fullname}\` → sourceField: "organization.fullname"
+  - \`{applicant.name}\` → sourceField: "name"
+  - \`{applicant.mobile}\` → sourceField: "mobile"
 ## 输出格式
 返回一个 JSON 对象，格式如下（不要有任何其他文字、解释、markdown 标记）：
 {
@@ -679,8 +753,32 @@ if (field.name === 'quantity' || field.name === 'unit_price') {
     "onInit": "脚本代码或空字符串",
     "onValueChange": "脚本代码或空字符串",
     "onSubmit": "脚本代码或空字符串"
-  }
-}`;
+  },
+  "migrationLog": ["迁移记录，仅升级场景需要"]
+}
+
+### migrationLog（迁移记录）
+当用户提供了 flow_events、form_script、instance_template 中包含业务逻辑（如校验、赋值、显隐控制等脚本代码）时，必须在 migrationLog 数组中为每条被迁移的逻辑记录一条说明，格式：
+  "<来源>: <原逻辑简述> → <迁移到的具体位置>"
+
+迁移目标可以是以下任意一种：
+- 字段属性：如 "字段 apply_increase_amount 的 max:4999999.99"
+- 字段规则：如 "字段 remark 的 visibilityRules"、"字段 attachment_desc 的 requiredRules"
+- formula 字段：如 "新增 formula 字段 total_amount"
+- 事件脚本：如 "events.onSubmit"、"events.onValueChange"
+- 已省略（含原因）：如 "已省略（旧版 state=='draft' 判断，新版 onSubmit 仅提交时触发，无需判断）"
+
+示例：
+"migrationLog": [
+  "flow_events: 申请增加额度>=500万阻止提交 → 字段 apply_increase_amount 的 max:4999999.99",
+  "flow_events: ins.state!='draft' 状态判断 → 已省略（新版 onSubmit 仅提交时触发）",
+  "form_script: 根据类型字段显隐备注 → 字段 remark 的 visibilityRules",
+  "form_script: 选择部门后级联加载人员选项 → events.onValueChange",
+  "instance_template: {applicant.organization.name} 跨对象引用 → 成员字段 applicant 的 pickerFillRules (organization.name → dept_name)"
+]
+
+⚠️ 如果 flow_events 或 form_script 不为空但 migrationLog 为空数组，视为错误。每条旧版逻辑都必须有对应的迁移记录，不允许静默丢弃。
+如果没有提供 flow_events、form_script，或它们为空，则 migrationLog 可省略或为空数组。`;
 }
 
 exports.default = router;

package/main/default/routes/api_workflow_box_filter.router.js

@@ -14,10 +14,10 @@ router.get('/api/workflow/v2/:box/filter', requireAuthentication, async function
     const userSession = req.user;
     const { userId, is_space_admin, spaceId } = userSession;
     // TODO 按应用分类显示
-    const { app, flowId } = req.query;
+    const { app, flowId, additionalFilters } = req.query;
     const { box } = req.params;
     const filter = await objectql.getSteedosSchema().broker.call("instance.getBoxFilters", {
-        box, appId: app, flowId, userId, is_space_admin, spaceId
+        box, appId: app, flowId, additionalFilters, userId, is_space_admin, spaceId
     })
     return res.send({
         filter

package/main/default/services/flows.service.js

@@ -144,37 +144,33 @@ module.exports = {
           }
         } else {
           var categories = await this.getSpaceCategories(categoriesIds, userSession);
+          const allFilters = [
+            ["category", "in", _.map(categories, '_id')],
+            ["state", "=", "enabled"],
+          ];
+          if (action === "new") allFilters.push(["forbid_initiate_instance", "!=", true]);
+          if (keywordsFilter) allFilters.push(keywordsFilter);
+          const allFlows = await objectql.getObject("flows").find({
+            filters: allFilters,
+            fields: ['_id', 'name', 'sort_no', 'category', 'perms'],
+          });
+          const flowsByCategory = _.groupBy(allFlows, 'category');
           for (const category of categories) {
-            const filters = [
-              ["category", "=", category._id],
-              ["state", "=", "enabled"],
-            ];
-            if(action === "new"){
-              filters.push(["forbid_initiate_instance", "!=", true]);
-            }
-            if (keywordsFilter) {
-              filters.push(keywordsFilter)
-            }
-            // console.log(`filters`, filters)
-            const categoryFlows = await objectql.getObject("flows").find({
-              filters: filters,
-              fields: ['_id', 'name', 'sort_no', 'category', 'perms'],
-              sort: "sort_no desc,name",
-            });
+            const catFlows = flowsByCategory[category._id] || [];
             category.flows = [];
-            for (const flow of categoryFlows) {
-              if(allData){
+            for (const flow of catFlows) {
+              if (allData) {
+                category.flows.push(flow);
+              } else if (this.canAdd(flow, userSession)) {
                 category.flows.push(flow);
-              }else{
-                if (this.canAdd(flow, userSession)) {
+              } else if (action === 'query') {
+                if (is_space_admin || this.canMonitor(flow, userSession) || this.canAdmin(flow, userSession)) {
                   category.flows.push(flow);
-                } else if (action == 'query') {
-                  if (is_space_admin || this.canMonitor(flow, userSession) || this.canAdmin(flow, userSession)) {
-                    category.flows.push(flow);
-                  }
                 }
               }
             }
+            // Sort per-category in memory to avoid MongoDB large-dataset sort RAM limit
+            category.flows = _.orderBy(category.flows, ['sort_no', 'name'], ['desc', 'asc']);
           }
           data = categories;
         }

package/main/default/services/instance.service.js

@@ -134,8 +134,7 @@ module.exports = {
     },
     getBoxFilters: {
         async handler(ctx){
-            const { appId, box, flowId, userId, is_space_admin, spaceId } = ctx.params;
-            const categoriesIds = await this.getAppCategoriesIds(appId);
+            const { appId, box, flowId, userId, is_space_admin, spaceId, additionalFilters } = ctx.params;
             const filter = [];
             switch (box) {
                 case 'inbox':
@@ -182,8 +181,11 @@ module.exports = {
                     break;
             }
 
-            if(categoriesIds && categoriesIds.length > 0){
-                filter.push(['category', 'in', categoriesIds])
+            if(!additionalFilters || additionalFilters.indexOf('category') < 0){
+                const categoriesIds = await this.getAppCategoriesIds(appId);
+                if(categoriesIds && categoriesIds.length > 0){
+                    filter.push(['category', 'in', categoriesIds])
+                }
             }
 
             return filter;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steedos-labs/plugin-workflow",
-  "version": "3.0.39",
+  "version": "3.0.40",
   "main": "package.service.js",
   "license": "MIT",
   "files": [

package/package.service.js

@@ -51,6 +51,20 @@ module.exports = {
 				}
 			}
 		},
+		getUser: {
+			rest: {
+				method: 'GET',
+				fullPath: '/api/workflow/getCurrentUser'
+			},
+			async handler(ctx) {
+				try {
+					return ctx.meta.user;
+				} catch (error) {
+					console.error(error);
+					return false;
+				}
+			}
+		},
 		send_badge_to_user: {
 			params: {
 				send_from: { type: 'string', optional: false },