# 规则引擎

规则引擎用于在账单导入与新建记录时，按条件自动应用分类与标签。

## 数据模型

- `t_rule`：`name`、`enabled`、`sort_order`（优先级，越小越优先）、`type`（限定收支类型，可空）、`keyword`（关键词）、`min_amount` / `max_amount`（金额区间）、`category_id`（目标分类）。
- `t_rule_tag`：规则与标签的多对多关联。

## 匹配逻辑

`RuleServiceImpl.matchBatch` 的核心流程：

1. 一次性加载当前用户**已启用**的规则，按 `sort_order`、`id` 升序排序；预加载规则标签与引用分类。
2. 拼接匹配文本 = `交易对方 + 商品名称 + 备注`，统一转小写。
3. 逐条判断是否命中：
   - **类型**：规则指定了 type 且与记录类型不一致则跳过。
   - **关键词**：包含匹配（忽略大小写）。
   - **金额区间**：`min_amount ≤ amount ≤ max_amount`（含边界，任一为空表示不限制）。
4. 命中后：
   - **分类**：取首个命中且与记录类型一致的规则分类。
   - **标签**：取所有命中规则标签的并集（去重）。
5. 返回结果与入参一一对应。

## 应用位置

| 场景 | 行为 |
|---|---|
| 账单解析预览 | 展示命中的规则名与建议分类/标签 |
| 账单确认导入 | 规则建议分类优先于面板默认分类；标签与默认标签合并去重 |
| 新建/编辑记录 | 不自动应用，但可借助 AI 推荐 |
| 规则管理页「应用」 | 手动把规则应用到命中的历史账单（先预览确认；分类覆盖、标签追加） |

## 列表查询与分页

- `GET /api/rule/list`：返回当前用户全部规则（按优先级排序），供内部复用。
- `GET /api/rule/page`：分页查询，支持 `keyword`（匹配规则名称或关键词）、`enabled`、`type` 筛选，返回 `PageResult<RuleVO>`。
- `DELETE /api/rule/batch`：批量删除（body `{ ids }`）；先按 `userId` 过滤归属，清理规则-标签关联后删除，返回实际删除数。

## 一键应用到匹配账单

规则默认只在导入时生效，不会改写历史账单；`RuleService.previewApply` / `applyToMatchedTransactions` 支持把规则手动应用到**历史账单**（前端规则管理页的行内「应用」/ 勾选后的「应用匹配账单」）：

- `POST /api/rule/apply-preview`（`previewApply`）：校验规则归属后加载当前用户**全部交易**，按规则条件（类型 + 关键词 + 金额区间；关键词匹配备注、忽略大小写）逐条匹配；**分类**取所选规则中优先级最高（`sort_order` 最小）且类型一致者，**标签**取所有命中规则标签的并集。返回命中明细 `RuleMatchedTransactionVO`（含当前分类/标签与目标分类/标签）与统计 `RuleApplyPreviewVO`（命中数、将改分类数、将加标签数、是否截断）。明细最多 500 条（`PREVIEW_MAX_ROWS`），超出置 `truncated`，统计仍按全部命中计算。
- `POST /api/rule/apply`（`applyToMatchedTransactions`）：复用同一匹配逻辑，**分类覆盖写入**（仅类型一致时）、**标签仅追加缺失项**（不删除已有标签），返回 `RuleApplyResultVO`（命中/变更/新增标签数），幂等。
- 入参 DTO `RuleApplyRequest`（`ruleIds`，非空）；均为**纯本地匹配**，不调用大模型；**不限规则是否启用**（停用规则也可手动应用）。

## AI 生成规则

`AiRuleServiceImpl` 提供两个入口：规则管理页（生成 + 创建）与收支记录页批量操作（生成 + 可选应用到账单）。

- 生成建议（`suggest`，`POST /api/ai/rule/suggest`）：依据用户勾选的记录生成规则建议；规则管理页限定**已打标签记录**，收支记录页为**任意勾选账单**。输入字段为记录的类型、备注、交易渠道、已有分类与标签（不含金额与原始账单数据），并按「类型 + 备注 + 渠道 + 标签」组合去重。
- 创建规则（`apply`，`POST /api/ai/rule/apply`）：输出规则经 `RuleService.create` 落库，必要时新建分类/标签，规则默认启用。
- 应用到交易（`applyToTransactions`，`POST /api/ai/rule/apply-transactions`）：**纯本地匹配、不调用大模型**，按规则的类型/关键词/金额条件匹配指定交易，命中则聚合分类与标签，委托 `AiSuggestionService.apply` 落库（覆盖分类、追加标签，必要时新建）。
- 去重校验（`checkDuplicates`，`POST /api/ai/rule/check-duplicates`）：**纯本地、不调用大模型**，复用同一签名逻辑，对**编辑后的规则**逐条返回是否重复（与已有规则签名一致或批内先前规则重复），入参 DTO `AiRuleDuplicateCheckRequest`（复用 `AiRuleApplyRequest.Item`）。前端规则弹窗编辑任一字段后防抖（约 300ms）调用它刷新 `duplicate` 标记。
- **去重签名**：以「类型 + 归一化关键词 + 分类 + 排序标签集合」为签名；与已有规则或同批已创建规则重复时跳过（`apply` 返回实际创建数），建议阶段与编辑重算阶段则标记 `duplicate`；前端重复项默认不勾选且禁止勾选，编辑后重算时「重复→不重复」自动勾选、「不重复→重复」自动取消并禁用。

## 校验

`RuleServiceImpl.validate` 会校验：`type` 白名单、金额下限不大于上限、目标分类归属当前用户且类型一致。保存规则标签时采用全量替换。

## 相关文档

- [规则管理（使用说明）](/guide/rules)
- [账单解析](/dev/bill-parsing)