Files

T

rosercode 41d1a4d5a9 docs: 补充管理页批量操作说明并同步规则/AI 规则文档

为规则、分类、标签管理页新增的「批量操作模式」与多选删除补充使用与开发文档，同时补上此前已完成但未同步的 AI 规则建议可编辑、编辑后实时重算去重等文档，并登记批量模式截图脚本。

变更内容：
- guide/categories-tags.md：补充分类与标签的批量删除说明，并回填 tags-batch.png、categories-batch.png 配图。
- guide/rules.md：批量删除与应用匹配账单改为需先进入「批量操作」模式（默认不显示勾选框）。
- dev/api.md：新增 DELETE /api/tag/batch、/api/category/batch，并补齐规则命中账单预览/一键应用、AI 规则去重校验等接口。
- dev/data-model.md：说明标签删除清理交易标签与规则标签关联、分类删除保留逻辑引用（账单显示未分类）。
- dev/rule-engine.md、dev/ai.md、dev/preferences.md、guide/ai.md、guide/transactions.md：同步 AI 规则建议可编辑、编辑后实时重算去重、应用开关默认开启并持久化等说明。
- scripts/ts/capture-elements.ts：新增 captureBatchModes()（标签/分类批量模式截图）并纳入 main()。

说明：
- 截图经测试环境（前端 5174 / 后端 8081，虚构数据）生成，已上传 OSS，正文以 OSS 长期地址引用；public/screenshots 目录不入库。

2026-10-14 01:07:46 +08:00

5.5 KiB

Raw Blame History

规则引擎

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

数据模型

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

匹配逻辑

RuleServiceImpl.matchBatch 的核心流程：

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

应用位置

场景	行为
账单解析预览	展示命中的规则名与建议分类/标签
账单确认导入	规则建议分类优先于面板默认分类；标签与默认标签合并去重
新建/编辑记录	不自动应用，但可借助 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 白名单、金额下限不大于上限、目标分类归属当前用户且类型一致。保存规则标签时采用全量替换。

5.5 KiB Raw Blame History Unescape Escape