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 目录不入库。
This commit is contained in:
2026-10-14 01:07:46 +08:00
parent d94d4e1ed5
commit 41d1a4d5a9
10 changed files with 145 additions and 17 deletions
+11 -1
View File
@@ -29,6 +29,7 @@
| 账单解析预览 | 展示命中的规则名与建议分类/标签 |
| 账单确认导入 | 规则建议分类优先于面板默认分类;标签与默认标签合并去重 |
| 新建/编辑记录 | 不自动应用,但可借助 AI 推荐 |
| 规则管理页「应用」 | 手动把规则应用到命中的历史账单(先预览确认;分类覆盖、标签追加) |
## 列表查询与分页
@@ -36,6 +37,14 @@
- `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` 提供两个入口:规则管理页(生成 + 创建)与收支记录页批量操作(生成 + 可选应用到账单)。
@@ -43,7 +52,8 @@
- 生成建议(`suggest`,`POST /api/ai/rule/suggest`):依据用户勾选的记录生成规则建议;规则管理页限定**已打标签记录**,收支记录页为**任意勾选账单**。输入字段为记录的类型、备注、交易渠道、已有分类与标签(不含金额与原始账单数据),并按「类型 + 备注 + 渠道 + 标签」组合去重。
- 创建规则(`apply`,`POST /api/ai/rule/apply`):输出规则经 `RuleService.create` 落库,必要时新建分类/标签,规则默认启用。
- 应用到交易(`applyToTransactions`,`POST /api/ai/rule/apply-transactions`):**纯本地匹配、不调用大模型**,按规则的类型/关键词/金额条件匹配指定交易,命中则聚合分类与标签,委托 `AiSuggestionService.apply` 落库(覆盖分类、追加标签,必要时新建)。
- **去重**:以「类型 + 归一化关键词 + 分类 + 排序标签集合」为签名;与已有规则或同批已创建规则重复时跳过(`apply` 返回实际创建数),建议阶段则标记 `duplicate` 供前端禁止勾选。
- 去重校验(`checkDuplicates`,`POST /api/ai/rule/check-duplicates`):**纯本地、不调用大模型**,复用同一签名逻辑,对**编辑后的规则**逐条返回是否重复(与已有规则签名一致或批内先前规则重复),入参 DTO `AiRuleDuplicateCheckRequest`(复用 `AiRuleApplyRequest.Item`)。前端规则弹窗编辑任一字段后防抖(约 300ms)调用它刷新 `duplicate` 标记。
- **去重签名**:以「类型 + 归一化关键词 + 分类 + 排序标签集合」为签名;与已有规则或同批已创建规则重复时跳过(`apply` 返回实际创建数),建议阶段与编辑重算阶段则标记 `duplicate`;前端重复项默认不勾选且禁止勾选,编辑后重算时「重复→不重复」自动勾选、「不重复→重复」自动取消并禁用。
## 校验