Files
lpt-be/.agents/notes/implemented/architecture/2026-11-16-current-recall-storage.md
T
cat-shark 27ddf8be5a docs: 规则与技能迁入 .agents/,并接入决策笔记
- roles/ 与 skills/ 迁移到 .agents/ 下,AGENTS.md 引用同步
- 收录 8 篇决策笔记到 .agents/notes/
- .rgignore 排除 archived 历史快照
2026-11-18 15:01:05 +08:00

57 lines
6.6 KiB
Markdown

# Agent Note: 自由回忆只保存当前导图与本次资料
Status: implemented
## Problem
自由回忆需要持续保存当前输入、提供本次资料,并允许下次接着最后的导图回忆。为每次自动保存维护内容历史,会把编辑、恢复、原文查看和 AI 请求都绑定到版本模型。业务只要求每次回忆的最终内容;不兼容的回忆数据允许一次性删除。
## Decision
每次回忆的 `RecallDocument` 只保存当前 `detail.expression` 和单一 `reference` 来源集合。自动保存覆盖当前导图,不保存中间导图、表达历史、资料历史或对应的版本字段。不同回忆仍是独立记录,各自保留最后保存的导图;“只保留当前内容”不表示整个账号只能有一条回忆记录。
本次资料在创建回忆时取一次,来源不可访问时原地清除正文及依赖它的 AI 结果。下一次创建回忆重新取材。DTO 名称 `ReferenceSnapshot` 只表示本次唯一来源集合,不包含版本号、历史列表或切换入口;普通查询和保存不会生成另一份资料。
`writeToken` 是覆盖写入保护:成功写入替换当前随机令牌,不维护递增内容编号或旧令牌列表。草稿只保留最近一次写入的请求编号与摘要,响应丢失时允许同一请求重试。其他业务收据只保存标识和摘要,不保存历史正文。
创建回忆时,服务端按当前用户、规范化标签集合及并集/交集方式选择最近已结束记录。标签顺序、空格或大小写不构成不同范围,组合方式不同则范围不同。新回忆复制最后导图的文字、节点标识及结构,清空此前帮助标记;资料、提示请求和累计耗时从本次重新建立。没有可用记录时初始化空白根节点。未完成草稿通过恢复接口编辑。
资料目录由 `GET /review/recalls/{num}/references` 分页返回标题与摘要,正文由同一路径下的 `/sources/{sourceId}` 获取。详情只返回资料汇总,避免每次草稿上传都携带全量正文。资料接口不接受版本参数。
AI 执行期间可以暂存一份提交输入,以便重启接手和结果引用校验;终态成功写回后清除 `params_json`,不能据此建立可回看的编辑过程。成功结果保留提示/查漏内容及必要请求信息,不替换当前导图。已显示帮助或原文的事实单独保留,供 AI 区分资料与已知帮助;这些事实不带表达版本或中间导图。具体输出与重试规则归属[AI 协议决策](../../../../../lpt-ai/.agents/notes/implemented/architecture/2026-11-16-recall-strict-protocol.md)。
## 删除范围与同步升级
`V20261116_1__replace_recall_storage.sql` 删除 `review_recall_records`,重建自由回忆的当前记录、请求、收据与所有者锁表,清除 `RECALL_COMPARE`、`TAG_RECALL_COMPARE`、`RECALL_HINT` 和 `RECALL_CHECK` 的既存任务。迁移不回填不兼容的表达历史与资料历史,已执行的历史 Flyway 脚本保持不变。
任务标准导图 `review_standard_mind_maps` 与标签导图 `review_tag_mind_maps` 保留,`StartTask` 的生成和编辑能力保留。被移除的是依赖旧对比记录表的查询、写入、统计和浏览链路,不能重新从旧任务类型写入该表。
表达式与提示结果增加字段后,旧版 `document_json` 不做读取兼容:`V20261118_1__clear_incompatible_recall_data.sql` 清空既有回忆、回忆请求/收据与回忆 AI 任务;运行中遇到无法解析的残留行直接逻辑删除并返回 `STORED_DATA_INVALID`,不保留、不隐藏。旧格式 AI 结果读取失败时按“旧版本格式,请重新请求”展示,不再冒充核验失败。
前端、后端与 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)继续维护各自决定。
## Alternatives considered
- 只隐藏编号和历史入口:可以复用已有异步绑定,改动面较小;但后端仍保存编辑过程,与只保留当前内容的业务要求冲突,因此删除整个内容版本模型。
- 把不兼容回忆回填为当前结构:能保留个人历史;但需要维护旧格式转换与历史引用,业务已允许删除这些数据,因此使用一次性清理迁移。
- 无写入保护地覆盖当前图:实现更短,也没有内容版本;但两个页面可能静默覆盖彼此输入,因此使用单个随机写入令牌与请求幂等控制。
## Consequences
覆盖保存把正文存储限制在每次回忆的一份当前内容,写入保护继续防止多页面静默覆盖。代价是无法恢复某一步编辑,也不能在本次回忆里刷新或切换资料历史;写入令牌与幂等摘要只能解决请求冲突,不能提供内容回滚。
删除迁移会清除既存对比记录和不兼容的自由回忆记录。保留任务标准导图和标签导图不意味着保留依赖这些图的旧回忆对比记录。代码回退不能还原已删除内容,发布时需要明确接受这个数据结果。
若业务以后确实需要编辑回滚、回忆内更新资料或长期保留请求输入,必须重新评估存储与清理规则;不得以恢复编号字段或长期保留 `params_json` 的方式隐式引入历史。
## Verification
- `ReviewRecallServiceIntegrationTest` 校验多次覆盖后先前正文不再落盘、同范围自动带入、范围差异、租户隔离、资料分页,以及 AI 终态清除临时输入。
- `ReviewRecallControllerIntegrationTest` 校验无版本 DTO、原文读取与旧请求拒绝;`RecallAiResultValidatorTest` 校验引用是否确实来自本次输入。异步结果不能覆盖后续编辑由服务集成测试验证。
- `RecallStorageMigrationTest` 验证重建存储并删除旧记录、保留任务标准导图和标签导图。迁移在 H2 的 MySQL 模式执行;`MigrationIndexKeyLengthTest` 额外复算 InnoDB 索引键长度,不能替代真实 MySQL 的 DDL 验证。
- 使用 JDK 17 运行 `./mvnw clean test`。