feat: 回忆去掉结束状态,新增按标签查相关导图

- 删除 status/endedAt 与结束接口,回忆只能继续编辑,用时继续累计
- 新增 review_recall_scope_tags 索引表与回填迁移,按标签交集查询保存导图
- 新增 GET /review/recalls/related,分页在 SQL 完成;列表支持 excludeRecallNum
- 范围匹配不到知识碎片时拒绝开始回忆(SCOPE_EMPTY)
This commit is contained in:
2026-11-22 21:41:31 +08:00
parent cf3fa6418b
commit cf7518c320
23 changed files with 944 additions and 125 deletions
@@ -34,6 +34,8 @@ AI 执行期间可以暂存一份提交输入,以便重启接手和结果引
本篇维护当前内容存储、范围匹配、写入保护、临时 AI 输入和删除迁移。[前端工作区决策](../../../../../lpt-fe/.agents/notes/implemented/feature/2026-11-16-current-recall-workspace.md)维护入口与交互,[AI 协议决策](../../../../../lpt-ai/.agents/notes/implemented/architecture/2026-11-16-recall-strict-protocol.md)维护严格输出和调用预算。三篇部分相关,分别保留;[租户隔离](2026-05-27-tenant-line-row-isolation.md)和[计费规则](2026-10-10-ai-usage-accounting-rules.md)继续维护各自决定。
[2026-11-22 的决定](2026-11-22-recall-map-without-status.md)取代了本篇的两条内容:新建回忆不再自动带入同范围已结束导图,回忆记录也不再区分进行中/已结束(`status`、`endedAt` 与结束接口均已删除);其余当前内容存储规则仍以本篇为准。
## Alternatives considered
- 只隐藏编号和历史入口:可以复用已有异步绑定,改动面较小;但后端仍保存编辑过程,与只保留当前内容的业务要求冲突,因此删除整个内容版本模型。
@@ -50,7 +52,7 @@ AI 执行期间可以暂存一份提交输入,以便重启接手和结果引
## Verification
- `ReviewRecallServiceIntegrationTest` 校验多次覆盖后先前正文不再落盘、同范围自动带入、范围差异、租户隔离、资料分页,以及 AI 终态清除临时输入。
- `ReviewRecallServiceIntegrationTest` 校验多次覆盖后先前正文不再落盘、同范围新建仍空白、范围差异、租户隔离、资料分页,以及 AI 终态清除临时输入。
- `ReviewRecallControllerIntegrationTest` 校验无版本 DTO、原文读取与旧请求拒绝;`RecallAiResultValidatorTest` 校验引用是否确实来自本次输入。异步结果不能覆盖后续编辑由服务集成测试验证。
- `RecallStorageMigrationTest` 验证重建存储并删除旧记录、保留任务标准导图和标签导图。迁移在 H2 的 MySQL 模式执行;`MigrationIndexKeyLengthTest` 额外复算 InnoDB 索引键长度,不能替代真实 MySQL 的 DDL 验证。
- 使用 JDK 17 运行 `./mvnw clean test`。
@@ -0,0 +1,66 @@
# Agent Note: 自由回忆去掉状态与自动带入,任意历史记录都能继续编辑
Status: implemented
## Problem
自由回忆曾把一条记录分成「进行中(ACTIVE)」与「已结束(ENDED)」两种状态:`status` 既落库成列、又进 `RecallDetail`,
还带一个 `endedAt` 字段和 `POST /review/recalls/{num}/end` 端点。只有 `ENDED` 的记录才会被「同范围自动带入」选中,
只有 `ACTIVE` 的记录才允许恢复(`resume`)和保存草稿(`PUT /draft`)。
这套状态带来的是纯粹的摩擦,没有对应的业务收益:
- **用户视角没有「结束」这个动作。** 想再改昨天的回忆,记录已经是 `ENDED`,只能开始新的一次;
而新记录又把上次的导图整棵复制过来,于是旧记录变成一份再也碰不到的副本。
- **自动带入把两条记录耦合成一条链。** 复制只发生在「同范围最近一条已结束」记录上,用户看到的新空白图取决于
是谁先点了结束,行为难以解释;资料、提示与耗时却按本次重新开始,复制过来的节点算不上同一次回忆。
- **状态是第四个写入保护维度。** 编辑者(`editorId`)与写令牌(`writeToken`)已经解决多页面覆盖,
`status` 只是再多一条会在恢复与保存之间产生「已经结束,只能回看」这种前后矛盾的拒绝。
## Decision
自由回忆不再有状态,任意历史记录都能继续编辑:
- 新建回忆永远从空白根节点开始,不再查询「同范围最近已完成导图」;`previousExpression` / `carryContent` 删除。
- `RecallDetail`(含列表 `RecallSummary`)不再有 `status` 与 `endedAt`;`EndRequest` 与 `POST /review/recalls/{num}/end` 删除;
列表接口不再接受 `status` 查询参数。
- 任意记录都能 `POST /resume` 接管编辑:恢复只重置计时编辑段并轮换 `writeToken`;`PUT /draft` 继续可用,
有效时间与实际用时继续累计到同一条记录。
- `ReviewRecallStore.guard` 只校验 `editorId` + `writeToken`,`setEntity` 不再写 `status`;`ReviewRecallEntity` 去掉该字段。
- `V20261122_1__drop_recall_status.sql` 先删含 `status` 的索引 `idx_recall_user_scope_status`,再 `DROP COLUMN status`,
最后按去掉 `status` 的列顺序重建 `idx_recall_user_scope (created_by, scope_type, scope_key, deleted, last_modified_time, id)`。
旧 `document_json` 里的 `detail.status` / `detail.endedAt` 由 `RecallJson.readStored` 的「忽略未知字段」自然丢弃,
不做回填 JSON 的迁移。
- 主动查漏的输入不变:仍是当前 `expression` + 本次 `reference.units`,历史导图从不发送给 AI。
## Alternatives considered
- **保留 `status` 但允许 `ENDED` 记录继续编辑。** 改动最小,`resume` 里去掉一条校验即可;但 `status` 与 `endedAt`
会继续出现在 API 契约和数据库里,用户和前端要一直维护一个不再影响行为的字段,等于把废弃字段当契约留着。
- **把 `status` 换成「已完成/未完成」的展示派生值(例如「最后修改时间早于 N 天」)。** 可以让列表看起来有分组;
但这是前端可以自己算的展示口径,落到后端只是把同一条状态的维护成本换了个名字,且没有任何写入规则依赖它。
- **保留自动带入但改成「带入最近一条同范围记录」。** 能让用户接着上次的图;但复制来的节点与本次资料、本次提示不对应,
且用户无法选择不复制(新回忆只能是复制品),因此直接取消带入,需要接着写时打开原记录继续编辑即可。
## Consequences
收益是契约与数据库各少一列、少一个端点、少一次「同范围历史查询」,恢复与保存不再互相否定;展示与写入规则只剩
`editorId` / `writeToken` 一层,与既有的多页面覆盖语义一致。
代价是:
- **删除列不可逆。** 代码回退到带 `status` 的版本会因缺列直接报错,必须与迁移同批回退或补一次新增列的回填。
- **旧记录的含义变宽。** 以前 `ENDED` 表示「不再修改」,现在任何记录都能被接手;拿到最新写令牌的页面可以覆盖,这是既有语义。
- **列表索引重建。** `idx_recall_user_scope` 的列顺序只服务「按范围过滤 + 最近修改排序」,不能再按 `status` 过滤;
未指定范围时列表仍走 `idx_recall_list (created_by, deleted, last_modified_time, id)`。
## Verification
- `ReviewRecallServiceIntegrationTest`:`creatingRecallAlwaysStartsFromAnEmptyRootEvenWithHistoryInScope` 覆盖同范围有历史导图时新建仍空白;
`anyHistoricalRecallResumesAndKeepsAccumulatingOnTheSameRecord` 覆盖任意记录多次恢复 + 草稿后 `activeDurationMs` / `actualDurationMs`
在同一条记录上继续累计;其余用例去掉了结束动作与状态断言。
- `ReviewRecallControllerIntegrationTest`:详情断言不含 `status` / `endedAt`,`anyHistoricalRecallResumesAgainAndKeepsEditing`
覆盖同一篇记录连续恢复与恢复后保存草稿;旧的未知字段(`carryFrom`)与过期写令牌仍按 400 拒绝。
- `RecallStorageMigrationTest` 断言迁移后 `review_recalls` 不再有 `status` 列;`MigrationIndexKeyLengthTest` 解析全部迁移文件,
会复算重建后的 `idx_recall_user_scope` 键长(564 字节,上限 3072)。
- 使用 JDK 17 运行 `./mvnw test`(611 个测试)。
@@ -0,0 +1,36 @@
# Agent Note: 空范围不能创建、恢复或保存回忆
Status: implemented
## Problem
自由回忆的范围只校验「所选标签在某个碎片上存在」,没有校验「本次范围实际匹配到至少一条碎片」。多标签交集没有同时命中的碎片时,`ReferenceSnapshot` 是 `EMPTY`,但记录仍被创建、仍能进入导图编辑,随后提示和查漏每次都以 `NO_REFERENCE` 失败。用户看到的是一个能画图、却不能使用任何资料辅助的回忆。
线上记录 `RECALL-814013dd-2ce5-4346-af3f-3b8d887bbbce` 就是这种情况:标签 `A` 与「【体验测试】数据库事务学习(2026-11-15)」各命中 2 条碎片,交集为 0,`detail.reference` 为 `EMPTY`。
## Decision
- `ReviewRecallService.create` 在取得 `ReferenceSnapshot` 后检查 `RecallReferenceLoader.knowledgeSources(reference.sources())`;为空时抛 `SCOPE_EMPTY`,不写记录。
- `resume` 与 `draft` 在加载文档后调用同一个 `requireKnowledge` 检查;空范围记录不能接管编辑,也不能继续保存。
- `get`、`list`、删除保持可读/可删:历史里的空范围记录仍能出现在回忆列表并删除,只是不能继续编辑。
- `SCOPE_EMPTY` 是业务错误码,前端据此显示「重新选择范围」,不把空范围伪装成网络失败。
## Alternatives considered
- **只在下一步(提示/查漏)禁用按钮**:改动最小,但用户已经进入导图、画了内容,才发现这个范围没有任何资料;这不是「不进入编辑」,只是把失败推迟。放弃。
- **自动把交集改成并集**:能让范围立刻有碎片,但会静默改变用户选择的复习范围,也无法解释历史快照。放弃。
- **允许进入但只读展示**:用户仍会看到一张不能继续编辑的导图,和「进入导图编辑页面」的边界不清楚;不如直接停在范围选择。放弃。
- **删除历史空范围记录**:等于替用户清理数据,且可能连带删除用户已画的内容;保留历史、禁止编辑即可。放弃。
## Consequences
- 空范围不能再产生新的回忆记录;已存在的空范围记录留在历史中,打开时由前端显示范围错误与「重新选择范围」,后端也拒绝恢复/保存。
- 用户要使用提示或查漏,必须先调整标签或组合方式,使范围至少命中一条知识碎片。
- 新增 `SCOPE_EMPTY` 业务码;没有数据库迁移,也没有改写既有 `document_json`。
- 匹配到碎片但碎片正文为空的情况仍然允许进入(有碎片,只是资料没有可用文本),由提示/查漏的禁用态处理。
## Verification
- `ReviewRecallServiceIntegrationTest.zeroMatchingFragmentsCannotCreateResumeOrDraft`:交集 0 时创建抛 `SCOPE_EMPTY`;把已有记录的快照改为空后,`resume` 与 `draft` 都抛 `SCOPE_EMPTY`。
- 既有创建、恢复、计时累计、资料分页与 AI 终态测试继续通过。
- `./mvnw test` 全绿(新增用例后 612 个测试)。