front/.cursor/skills/oms-auto-trigger-formula/SKILL.md

---
name: oms-auto-trigger-formula
description: >-
  Writes OMS auto-trigger (自动触发) Chinese formulas for /channel/autoTrigger.
  Use when the user asks for 触发条件, 自动触发公式, 拦截/警告/问题件规则,
  oversize/国家/客户/销售产品条件, 字段非空/为空/不能为null 必填校验,
  or formula verification sample data.
---

# OMS 自动触发公式编写

为 `/channel/autoTrigger` 生成可直接粘贴的**中文公式**（后端 `ChineseFormulaEvaluator`）。

源码权威：

- 前端字段/算子：`src/views/channel/autoTrigger/formulaMeta.ts`
- 后端解析：`Oms.Application/.../ChineseFormulaEvaluator.cs`、`AutoTriggerFormulaMeta.cs`

## 产出格式

回复必须包含：

1. **时机**：`下单` | `入库` | `出库`（无「预报」；旧「预报」=「下单」）
2. **操作**：`拦截` | `警告` | `问题件`
3. **公式**：单行可执行表达式（无解释性注释夹在公式内）
4. **一句话说明**：命中条件是什么
5. （可选）**验证样例**：国家/尺寸/客户等，方便弹窗「验证触发条件」

```text
时机：下单
操作：拦截
公式：(单件最大长度()>60||单件最大宽度()>46)&&国家包含('GB')
说明：英国且超尺寸时拦截
验证样例：国家 GB，长 70，宽 40，高 40
```

## 语法硬规则（必遵守）

| 规则 | 正确 | 错误 |
|------|------|------|
| 字段名必须是注册过的**中文 label** | `国家包含('GB')` | `ConsigneeCountry=='GB'` |
| 字符串字段用 `字段包含('值')` | `客户包含('阿里')` | `客户()=='阿里'` |
| 数值/聚合用 `字段()` 再比较 | `实重()>5`、`单件最大长度()>60` | `实重>5`、`长度包含('60')` |
| 布尔用 `字段()==1` / `==0` | `是否偏远()==1` | `是否偏远()==true` |
| **非空 / 不能为 null** | `国家有值()` 或 `国家包含('')` | `国家!=null`、`国家()==null`、`国家!=''` |
| **为空 / 未填** | `收件人邮编为空()` 或 `!收件人邮编有值()` | `邮编==null`、`邮编包含(null)` |
| 字符串字面量单引号 | `'GB'`；内部单引号翻倍 `''` | `"GB"` |
| 逻辑运算 | `&&` `\|\|` `!` | `and` `or` `not` / 中文「且」 |
| 比较运算 | `==` `!=` `>` `>=` `<` `<=` | `=` `<>` |
| 算术 | `+ - * /` 与 `()` | — |
| 空公式 | 空串视为恒真（勿故意输出空） | — |
| 长度 | ≤ 10000 | — |

`包含` 语义：字段字符串 **Contains** 参数（子串匹配，非全等）。多选可用 `\|\|`：

```text
国家包含('GB')||国家包含('UK')
```

排除产品：

```text
!销售产品包含('EX_ASP_HKDHL_YD')
```

### 空值 / 必填（不能为 null）

求值器**没有** `null` 字面量；禁止写 `字段==null` / `字段()!=null`。

| 意图 | 推荐写法 | 等价写法 |
|------|----------|----------|
| 字段有值（非 null、字符串非空白） | `国家有值()` | `国家包含('')` |
| 字段为空（null 或空白） | `国家为空()` | `!国家有值()` |
| 拦截「缺某字段」 | `收件人电话为空()` | `!收件人电话有值()` |
| 拦截「某字段必须填」再叠加条件 | `国家有值()&&国家包含('GB')` | — |

语义说明：

- **字符串 / 日期**：`有值` = 非 null 且非空白；`为空` = null 或空白。
- **数值 / 布尔**：`有值` = 底层值非 null（`0` / `false` 仍算有值）；`为空` = null。
- 件重尺若业务上「0 也算未填」，用 `单件最大长度()<=0` 等比较，**不要**只靠 `有值()`（因为 0 仍有值）。
- `字段()` 把 null 当成 `0`，**不能**用 `字段()==0` 区分「未填」与「真是 0」。

## 写公式工作流

1. 从用户描述抽出：时机、操作、条件（国家/客户/产品/尺寸/重量/状态、**必填/不能为空**等）。
2. 映射到**中文字段**（见下方常用表；完整目录见 [field-catalog.md](field-catalog.md)）。
3. 按字段类型选：`包含('值')` / `字段()` / **`有值()` / `为空()`**。
4. 用户说「不能为空 / 必填 / 未填拦截」→ 用 `字段为空()`（缺了就命中）或前置 `字段有值()&&…`。
5. 用 `&&` / `||` / `!` / `()` 组合；复杂条件先括号。
6. 对照 [examples.md](examples.md) 自检语法。
7. 输出「时机 + 操作 + 公式 + 说明」；需要时给验证样例。

不确定字段名时：优先读 `formulaMeta.ts` 的 `ORDER_TABLE_FIELDS` / `VIRTUAL_FORMULA_FIELDS`，或后端 `AutoTriggerFormulaMeta`。**禁止编造未注册中文名**。

## 常用字段速查

### 聚合（下单尺寸最常用）

| 中文 | 用法 |
|------|------|
| 单件最大长度 / 宽度 / 高度 | `单件最大长度()>60` |
| 单件长宽高之和 | `单件长宽高之和()>150` |

### 订单 / 客户

| 中文 | 类型 | 典型 |
|------|------|------|
| 国家 | string | `国家包含('GB')`（二字码） |
| 收件国家名称 | string | `收件国家名称包含('英国')` |
| 销售产品 | string | `销售产品包含('EX_')` |
| 收货渠道 | string | `收货渠道包含('DHL')` |
| 客户 | string | `客户包含('阿里国际站')` |
| 客户组 | string | `客户组包含('VIP')` |
| 货物属性 | string | `货物属性包含('sensitive')` |
| 申报总金额 | number | `申报总金额()>1000` |
| 是否偏远 / 是否COD / 是否拦截 | boolean | `是否偏远()==1` |
| 实重 / 计费重 / 长度/宽度/高度 | number | `实重()>20`（件重尺；下单前优先用聚合字段） |

### 收件人（选填 / 必填场景）

`收件人邮编包含('9')`、`收件人省州包含('CA')`、`收件人城市包含('London')`

必填拦截示例：`收件人手机为空()||收件人电话为空()`、`收件人邮编为空()`（手机=`收件人手机`，固话=`收件人电话`）

完整字段见 [field-catalog.md](field-catalog.md)。

## 时机与操作注意

- **下单 + 拦截**：建单前阻断（含草稿保存尝试）。
- **下单 + 警告/问题件**：预报成功后触发；纯草稿保存不触发。
- **入库/出库**：作业创建**之后**触发；「拦截」只打标，不回滚入库/出库。
- **问题件**：需能匹配问题模板，否则可能静默跳过。

## 自检清单

- [ ] 每个字段都是注册中文名
- [ ] 字符串用 `包含('…')`，数字用 `字段() 比较`
- [ ] 必填/非空用 `有值()` 或 `包含('')`，为空用 `为空()`；无 `null` 字面量
- [ ] 括号匹配；`&&`/`||` 优先级按需加括号
- [ ] 国家一般用二字码 `国家包含('XX')`
- [ ] 排除条件用 `!字段包含('…')`
- [ ] 公式可单行粘贴进触发条件编辑器

## 更多

- 完整字段目录：[field-catalog.md](field-catalog.md)
- 场景示例：[examples.md](examples.md)