docs: 补记范围相关导图与 prod 升级方案
- 待办:复习总览改为「上次编辑的导图」,任务页相关导图不再区分草稿/已结束 - 新增笔记:总览按所选标签列出保存过的导图 - 新增提案:prod 只保留学习记录后原地升级
This commit is contained in:
@@ -0,0 +1,62 @@
|
||||
# Agent Note: 复习总览按所选标签列出相关保存导图
|
||||
|
||||
Status: implemented
|
||||
|
||||
## Problem
|
||||
|
||||
复习总览(`/review`)的「选择复习范围」原来只服务于开始一次新的自由回忆:选完标签点「选择这个范围」就跳走,页面上看不到「这个范围我以前画过什么」,用户只能从「上次编辑的导图」或「最近回忆」里逐条翻。
|
||||
|
||||
11-20 删掉的「已有标签导图」读的是 `review_tag_mind_maps`,那张表没有写入链路,只能看不能改,已确认不复用。当前保存的图实际在 `review_recalls.document_json`,打开即进入编辑。
|
||||
|
||||
同时维护者定了一条硬约束:系统中所有列表分页都必须由后端 SQL 完成,不能在 Java 或前端拿到全量后再分页。学习页「相关导图」是前端每页 100 条拉回 `review_recalls` 再按标签交集过滤,最多 1000 条,这条实现不能直接搬到总览。
|
||||
|
||||
## Decision
|
||||
|
||||
**页面**
|
||||
|
||||
- 复习总览的顺序:上次编辑的导图 → 选择范围 → **相关导图** → 待归类 → 最近回忆。相关导图只在选中 1–10 个标签时出现;选标签即时查询(300ms 防抖),并集/交集切换不重查(匹配只看标签)。
|
||||
- 判定:导图范围与所选标签至少有一个相同即列出;命中标签多的排前面,同分按更新时间从新到旧,id 兜底。行内是 compact 版本:标题 + 「更新 时间」 + 「命中标签」,不重复范围/并集/交集与用时;点击进入 `/review/recalls/:num` 编辑。≥769 用紧凑单行,≤768 保持两行并把动作收成行尾箭头;5 行在 1280 下 321px,不高于范围卡 332px。
|
||||
- 每页 5 / 10 / 20 张可选,默认 5;分页条只保留 `prev, pager, next`,每页条数是页面内的中文 `el-select`,不依赖 Element Plus 全局 locale。当前页 `--green-700` + 600 字重;≤768 的 prev/next/页码点击区 44×44、条数选择 44 高。改标签或改条数回到第 1 页,加载时禁用。
|
||||
- 状态:超过 10 个标签只提示不发请求;加载(延迟 200ms)、空(「所选标签下还没有导图,换一组标签试试。」)、失败重试各一行文案;标题下不写自述句。
|
||||
- 最近回忆首屏从 3 条改为 5 条:`GET /review/recalls` 增加可选 `excludeRecallNum`,由 SQL 排除顶部那张;前端直接请求 `pageSize=5`,不再 fetch 6 条再 filter + slice。弹窗仍按 20 条/页、不传排除参数;弹窗总数单独用 `dialogTotal`,不覆盖首屏 `total`。
|
||||
|
||||
**接口与数据**
|
||||
|
||||
- 新表 `review_recall_scope_tags`:一条回忆 × 一个归一化标签一行,唯一键 `(recall_num, normalized_tag)`,匹配索引 `(created_by, normalized_tag, recall_num, deleted)`。
|
||||
- 写入:`ReviewRecallStore.insert` 在回忆创建同一事务里按 `scope.normalizedTags()` 插入;`delete` / `deleteUnreadable` 一并删除。历史回忆用 Java Flyway 迁移 `V20261122_3__backfill_recall_scope_tags` 从 `document_json` 回填,缺 `normalizedTags` 时用 `tags` 归一化兜底,跳过 TASK、已删除与不可解析文档,`ON DUPLICATE KEY UPDATE` 可重复执行。
|
||||
- 接口:`GET /review/recalls/related`,重复 `tags`(1–10 个,单个 ≤255)、`pageNum`、`pageSize`(1–100),返回 `{ current, size, total, records: [{ recall: RecallSummary, matchedTags }] }`。
|
||||
- SQL:在 `review_recalls r` 上用 `EXISTS` 命中候选(避免 join 放大行数),select 列表用相关子查询算 `matched_tag_count`,`ORDER BY matched_tag_count DESC, last_modified_time DESC, id DESC`;`LIMIT/OFFSET` 由 MyBatis-Plus 分页拦截器生成,count 单独一条 `COUNT(*)`,Java 不 `subList`。自定义 SQL 显式写 `deleted = 0`,子查询写 `t.created_by = r.created_by`,租户条件仍由拦截器追加。
|
||||
- 命中判定用归一化名(trim + 小写),回给前端的 `matchedTags` 用范围里保存的原样写法;只有历史文档只剩 `normalizedTags` 时才回退归一化名。
|
||||
- `related` 的查询与装配拆到 `RecallRelatedQuery`:`ReviewRecallService` 已经贴着 Checkstyle 的 400 行文件上限,直接塞进去会超限;`ReviewRecallService.related` 仍是 controller 的唯一入口并持有事务。
|
||||
|
||||
**文档**
|
||||
|
||||
- `lpt-docs/docs/concepts/review-overview.md`:把「总览不单列图列表」改成「选中范围后列出相关导图,按命中标签数排序、可翻页,不是全库图列表」。
|
||||
- `mind-map.md`:按碎片标签查看相关图从「只发生在学习页」改为「学习页 + 复习总览范围块」。
|
||||
- `review-scope.md`:补一句查看已有导图不创建回忆、不开始计时、不改写图的范围。
|
||||
- `README.md`:复习范围行补索引表标识;保存的导图行补总览按标签交集列出。
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
- **前端过滤现有回忆列表(学习页做法)**:不用改库、不用新接口,实现最快。但维护者要求所有分页在 SQL 里完成;这条路必须先把全量标签回忆拉回再分页,数据量大时还要截断到 1000 条,正好违反约束。放弃。
|
||||
- **扩展 `GET /review/recalls`,加 relatedTags 参数**:少一个端点。但现有列表的 `tags + combineMode` 是精确范围键查询,改成「交集 + 命中数排序」会改变同一个接口的语义和响应形状,所有调用方都要跟着理解两种模式。新开 `/related` 保持旧列表契约不变。放弃。
|
||||
- **直接对 `document_json` 用 MySQL JSON 函数**:不用新表。但 `document_json` 是 LONGTEXT,没有索引,每次都要全表解析;测试跑 H2,`JSON_TABLE` 等函数不可用;违反「SQL 里分页」的性能前提。放弃。
|
||||
- **复用 `review_tag_mind_maps`**:表已经在,有 `tag_names`。但它是 AI 从碎片生成的旧图,没有写入链路,11-20 已判定为死入口;相关导图要打开的是用户自己画的自由回忆。放弃。
|
||||
- **在 `review_recalls` 加一列分隔符拼接的 scope_tags**:少一张表。但按标签计数只能用 N 个 `LIKE`,无法走索引,标签名还要选不可能出现的分隔符;同样要回填。放弃。
|
||||
- **启动时用 ApplicationRunner 回填**:不用 Flyway。但一次性数据迁移应当有版本、顺序和失败记录;仓库已有 `V20261115_2`、`V20261115_5` 两个 Java 迁移先例,沿用即可。放弃。
|
||||
- **最近回忆继续取 6 条再剔除顶部那张**:不改列表接口。虽然它不是分页,但会留下唯一一处前端截取;维护者的约束是「所有分页在 SQL 里」,加 `excludeRecallNum` 后首屏也完全由 SQL 决定。放弃。
|
||||
|
||||
## Consequences
|
||||
|
||||
- 索引表与回忆创建路径必须同步:以后新增任何绕开 `ReviewRecallStore.insert` 的写入,相关导图就会漏图。本次用集成测试锁住唯一创建路径。
|
||||
- 回填解析的是历史 `document_json`,版本变化或不可读文档会被跳过;上线后要核对「TAG 回忆数」与「索引里的 distinct recall_num」一致,不等时按运行时 `deleteUnreadable` 处理后重查。
|
||||
- 标签改名不会改写历史范围和索引,选中新标签查不到旧图;这是现有「范围保留当时名称」的语义,不自动回填。
|
||||
- 顶部「上次编辑的导图」如果命中当前标签,会和相关列表同时出现;顶部是继续入口,列表是范围查询结果,接受重复。
|
||||
- 查询靠 `(created_by, normalized_tag, recall_num)` 索引;候选集是「带任一选中标签的回忆」,个人数据量下没问题,量级上来再改预聚合。分页 count 与页查询各一次,均在 SQL 里完成。
|
||||
- 前端不再有任何 `slice` / `filter` 取页,但也把正确性押在后端 SQL 上:`/related` 未上线前,选标签后这块会走失败态并给「重试读取」,不会静默空着。
|
||||
- 首屏多一次补查请求(`excludeRecallNum` 变化时),换来顶部那张不会被列两遍;弹窗与首屏各用各的总数,避免 20 条/页口径污染首屏 5 条。
|
||||
- 每页条数用页面内中文下拉,不改 `main.ts` 的 Element Plus 全局 locale;如果以后要统一 EP 内部文案,再单独做。
|
||||
- 学习页「相关导图」仍走前端过滤,暂不迁移到 `/related`;两套实现会暂时并存。
|
||||
- 旧 `review_tag_mind_maps` 仍留在库里,前端没有入口;这次不恢复它。
|
||||
- 验证:后端 `./mvnw validate` 0 违规、`./mvnw test` 620 个用例全绿;前端 5 个目标 spec 46 例、`e2e/review.spec.ts` 10 例、`type-check`、`lint`(0 error)、`lint:ui`、`build` 全绿。全量 `npm test` 仍有 15 例既有失败(6 个未触碰文件,VTU/Vue 双实例下 `wrapper.emitted()` 失效),与本次无关。
|
||||
- UI 评审:第一轮 6/10;第二轮指出 ≤768 每行多出孤立动作行(P1),把动作收成行尾箭头后第三轮 8.5/10、无阻断。剩余 P2(条数走数据角色、顶部轻页码、空态按钮)作为后续。最终 1280 区块 321px / 范围卡 332px,360 区块约 493px / 范围卡 369px,主操作仍在 360 首屏;加载态仍是单行文案、无骨架,200% 缩放与深色模式未验证。
|
||||
Reference in New Issue
Block a user