weaver-e10-builder 1.0.10-beta → 1.0.12-beta

package/skill-docs/actionflows/references/condition_rules.md

@@ -0,0 +1,97 @@
+# 条件业务规则
+
+仅在需求包含条件、筛选或 if/else 时读取本文件。
+
+- 用户没有说明条件成立或不成立后要做什么时，不擅自补写更新、删除、通知或其他业务动作。
+- 条件的业务含义存在多个合理解释时，向用户确认比较含义与各结果分支的预期动作。
+- 条件字段、操作符、值形态的**权威规范（前端 ConditionSet 源码逆向）**见下方「二、ESB filterInput / ConditionSet 右值规范」，来源：工作区 `condition-generator-skill/`（SKILL.md 第 6 章 + references/）。
+
+---
+
+## 一、筛选条件（filterCondition）plan 写法
+
+- 单条件：`{"field": {"id": "<目标字段id>", "label": "<字段名>"}, "operator": "<操作符>", "right": {...}}`。`right` 是唯一对外计划字段；不要使用历史别名 `value`。
+- 条件组（且/或）：`{"relationship": "and|or", "conditions": [ <条件1>, <条件2>, ... ]}`（编译器支持嵌套）。不接受平台输出 DTO 的 `datas` 或 `1/0`。
+- `right` 值形态（type）：
+  - `context`：`{"type":"context","paramKey":"<真实paramKey>","label":"<显示名>"}` —— 引用上游上下文（esbAssign.wId 自动指向当前节点）
+  - `native` + `mode: "currentTime"|"currentDate"|"now"|"today"`：**当前时间/当前日期**。编译器自动改写为系统参数 `{time}`/`{date}`（见下节 6），`conditions.value` 非空、`type:""`，设计器点开筛选器右值区能正常回显，不会出现「右值未配置」（真机验证 2026-08-18）
+  - `fixed`：普通固定值；字符串为 `{...}` 系统变量时自动识别为 system
+  - `system`：系统参数 token，如 `{userid}`/`{date}`/`{time}`（由动作流编译器内置 system_params 处理）
+- 操作符：`eq/neq/gt/lt/gte/lte/contains/uncontains/empty/nempty`（`empty/nempty` 无右值）
+- 日期字段用系统值：直接 `right.value = "{date}"` 或 `{time}`（ESB 体系），无需 `{today}`（那是通用 ConditionSet 的占位符写法，ESB 编译器会归一为 system）
+
+## 分支条件（`Condition`）
+
+分支条件和 `filterCondition` 共用 AND/OR 业务语义，但保存协议不同，不能互相复制 DTO。
+
+- 计划用 `condition: { relationship: "and|or", conditions: [...] }`；叶子为 `{left, operator, right}`。
+- `left` 只能是当前上游组件的实时字段；`operator` 由字段类型限制，未知或不兼容时编译失败。
+- `right` 只用 `fixed`、`system`、`context`，或 `formula` 完整回读对象。`context` 必须写真实 `paramKey`，由运行时生成 FormulaBean；禁止把字段名作为固定值。
+- 保存采用 ESB `source=8`：预暂存注册来源节点 → `getConditionSet` → `saveCondition` → 以保存响应回填真实持久化 ID → 最终暂存。新建后 `getExpressionBean` 可能只返回分组骨架，不能覆盖完整 `childrens` 叶子树；`mapBaseId`、`conditionId`、`mapId` 和所有 Long ID 都保持字符串，新建条件不传本地 `conditionId`。
+
+## 二、ESB filterInput / ConditionSet 右值规范（源自 condition-generator-skill）
+
+ESB 动作流的 `filterInput`（TimeBatchTrigger/DateTrigger/数据动作筛选）与通用 ConditionSet 筛选器**结构同源**（`isNewFilter/isParent/datas/relationship/key` + 叶子 `conditions{func,type,value,text}`）。生成条件时遵循以下规范：
+
+### 1. 叶子条件结构
+
+```json
+{
+  "id": "<字段id>", "fieldName": "<字段英文名>",
+  "conditions": { "func": "lt", "type": "", "value": "{time}", "text": "当前时间" }
+}
+```
+
+`fieldType/text/objId/compType` 等元信息由编译器按真实字段补全（`buildFilterInput`），**plan 里不写**。
+
+### 2. 值类型 `conditions.type` 枚举
+
+| type | 含义 | 适用 |
+|---|---|---|
+| `""` | 手动输入 / 选选项 / **系统值** | 文本/数值直接输入、选择框选选项、**日期选系统占位符** |
+| `"custom"` | 专用选择器 / 选择框手动输入 | 人员/部门/级联/地区/Select 手动输入；**日期 range 模式推荐**（渲染日期选择器） |
+| `"custombyhander"` | 手动输入（浏览器类组件） | 人员/部门/关联字段/文档/附件 |
+| `"formField"` | 引用本表/关联表字段值 | 所有类型（value 含 `compareFormField`，必须含 `objId`+`name` 否则回显空白） |
+| `"varField"` | 引用系统/流程变量 | 所有类型（value 含 `compareVarField`，`id` 必须是真实变量 id 否则回显空白） |
+| `"filterVal"` | 引用其他筛选组件搜索值 | 文本/数值/日期 |
+
+### 3. 系统日期占位符（通用 ConditionSet 写法，type 为 `""`）
+
+| 占位符 | 含义 |
+|---|---|
+| `{today}` | 当前日期 |
+| `{yesterday}` / `{tomorrow}` | 昨天 / 明天 |
+| `{currweek}` / `{lastweek}` / `{nextweek}` | 本周 / 上周 / 下周 |
+| `{currmonth}` / `{lastmonth}` / `{nextmonth}` | 本月 / 上月 / 下月 |
+| `{currseason}` / `{lastseason}` / `{nextseason}` | 本季 / 上季 / 下季 |
+| `{curryear}` / `{lastyear}` / `{nextyear}` | 本年 / 去年 / 明年 |
+
+自定义日期占位符（type `"custom"`，后端 `handleValue` 识别）：`{year}`（本年区间）、`{year}-{month}`（当月区间）、`{date:±N}`（今天±N 天）。
+
+> **ESB 差异**：ESB 动作流的系统值 token 由编译器内置 system_params 处理（`{date}`=当前日期、`{time}`=当前时刻、`{userid}` 等）；通用 ConditionSet 的 `{today}` 等占位符在 ESB filterInput 中由编译器归一（native `currentTime/currentDate/now/today` → `{time}`/`{date}`），生成时两者皆可，编译器兜底。
+
+### 4. func 操作符
+
+| func | 含义 | 适用 |
+|---|---|---|
+| `eq`/`neq` | 等于/不等于 | 所有 |
+| `gt`/`lt`/`gte`/`lte` | 大于/小于/大于等于/小于等于 | 数值、日期 |
+| `range` | 区间（value 为 `[起始,结束]`） | 数值、日期 |
+| `contains`/`uncontains` | 包含/不包含 | 文本 |
+| `empty`/`nempty` | 为空/不为空（无右值） | 所有 |
+
+### 5. 字段类型 × 值类型速查
+
+- 文本（String/Text/TextArea）：type `""`、`formField`、`varField`、`filterVal`；无 `custombyhander`
+- 数值（Number/NumberComponent）：type `""`（含 range）、`formField`、`varField`、`filterVal`；**无 `custombyhander`**
+- 日期（Date/DateComponent/DateInterval）：type `""`（手动输入/系统日期）、`"custom"`（手动输入，range 推荐）、`"customDate"`（仅宿主注入回调时可用，**默认不用**）、`formField`、`varField`、`filterVal`
+- 选择框（Select/RadioBox/CheckBox）：type `""`（选选项，value 逗号分隔）、`"custom"`（手动输入）、`formField`、`varField`
+- 人员（Employee）/部门（Department）：type `""`（系统选项）、`"custom"`（选人/选部门）、`"custombyhander"`、`formField`、`varField`
+
+### 6. 「当前时间」筛选的正确表达（真机验证 2026-08-18）
+
+ESB TimeBatchTrigger/DateTrigger 等定时器的 `filterCondition` 用「字段 < 当前时间」时：
+
+- plan 写：`{"field": {"id": "<日期字段id>", "label": "<字段名>"}, "operator": "lt", "right": {"type": "native", "mode": "currentTime", "label": "当前时间"}}`
+- 编译器把 `native currentTime/now/current_time` 改写为系统参数 `{time}`（`currentDate/today/current_date` → `{date}`），落到 system 路径
+- 读回后 `conditions = {"func":"lt","text":"当前时间","value":"{time}","type":"","isEsb":false}` —— value 非空，设计器点开筛选器右值区正常回显「当前时间」，**不会空**（此前直接透传 `type:"currentTime"` + `value:""` 导致点进去右值区空白，外部摘要正常）