From acc49a4d5c12ab76321a9d7b8a473fc91b5c39c6 Mon Sep 17 00:00:00 2001 From: cat-shark Date: Sat, 10 Oct 2026 13:42:56 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=95=B4=E7=90=86=E5=AD=A6=E4=B9=A0?= =?UTF-8?q?=E9=97=AD=E7=8E=AF=E6=94=B9=E5=8A=A8=E6=B8=85=E5=8D=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- OPTIMIZATION_BACKLOG.md | 95 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 95 insertions(+) diff --git a/OPTIMIZATION_BACKLOG.md b/OPTIMIZATION_BACKLOG.md index a933fb3..2a1d70f 100644 --- a/OPTIMIZATION_BACKLOG.md +++ b/OPTIMIZATION_BACKLOG.md @@ -66,6 +66,12 @@ | | 录音-04 转写链路(provider 可配置) | P2 | 已暂停 | 前置 AI-02 / AI-03 已完成;仍待采集方案 | | | 录音-05 录制可见性与隐私边界 | P1 | 已暂停 | 指示形态、他人语音口径 | | | 录音-06 浏览器侧接入 | P1 | 已暂停 | 油猴脚本 / 直接进 lpt-fe | +| 学习闭环重构 | 闭环-01 操作入口归位 | P1 | 待决策 | 复习模块内的操作落点与交互形态 | +| | 闭环-02 任务名自动成为标签 | P1 | 待决策 | 是否进系统标记词表;任务改名/删除如何联动 | +| | 闭环-03 标签管理与搜索选择 | P1 | 依赖 闭环-02 | 标签体系口径(任务名标签与自由标签的关系) | +| | 闭环-04 按标签复习生成导图 | P1 | 依赖 闭环-02/03 | 与按任务复习并存还是替代 | +| | 闭环-05 任务执行页展示并编辑导图 | P1 | 可直接实施 | 编辑粒度、并发覆盖口径 | +| | 闭环-06 记录应用过程中犯的错误 | P2 | 待决策 | 数据模型、与导图/残片的关系、如何复习 | > **学习录音模块已整体暂停**(2026‑10‑08):录音-01 的实现已完成并实测通过,但采到系统音频的两条路线(依赖 OBS / 自研原生)还没定,其余条目全部挂起。详见 §12。 @@ -700,6 +706,95 @@ - **待确认**:油猴脚本还是直接进 `lpt-fe`。 - **验收**:学习会话中可一键开始/结束录音,并看到状态与转写结果。 +## 13. 学习闭环重构(新需求,2026‑10‑10) + +> **状态:待决策,确认前不要实施。** 本节把维护者 2026‑10‑10 提出的产品方向整理成可执行条目。概念级设计(为什么这样学、概念如何组织)仍归 `lpt-docs`,本节只放**待办、依据与验收标准**。 +> +> **共同背景(为什么做)**:学习过程中「定义」这类内容其实不多,残片产生量有限、且往往集中出现;真正消耗时间的是「如何正确识别这些概念」与「概念的实际应用」(大部分发生在做题过程中)。现有实现把残片级操作铺在首页,聚合维度又只有「任务」一个,撑不起「按概念 / 按应用场景」的学习闭环。 +> +> **现状坐标(接手时先看这里)** +> - **首页** = `/welcome` → `lpt-fe/src/components/Welcome.vue`:落地页(`Login.vue:44` 登录后跳这里),实际承担的是**复习 Feed 滚动条**(`getReviewFeed(100, "smart")`),并在残片卡片上直接挂了写操作。 +> - **复习模块** = `/review` → `lpt-fe/src/components/Review.vue`:任务维度总览(任务卡片 + 统计、待归类内容、标签管理弹窗、导出/排序偏好),任务卡片主操作是「回忆复习」。 +> - **任务执行页** = `/start-task/:taskNum` → `lpt-fe/src/components/StartTask.vue`。 +> - **基础导图** = 表 `review_standard_mind_maps`,端点 `GET/PUT /review/standard-mind-map/{taskNum}`、`POST /review/standard-mind-map/{taskNum}/find-node`(均在 `ReviewController`);前端 `lpt-fe/src/api/standardMindMap.ts` + `components/MindMapViewer.vue`(已支持 `:editable`)。 +> - **残片标签** = 表 `markers`,端点 `GET|POST /markers`、`POST /markers/batch`、`DELETE /markers/{id}`、`PUT /markers/rename`、`GET /markers/filter`、`GET /markers/tags`;系统词表 `SystemMarkerEnum` 目前只有 `FROM_GUIDANCE("来源", "学习引导")`。 + +--- + +### 闭环-01 操作入口归位:首页只暴露残片内容 + +- [ ] 未完成 +- **涉及仓库**:`lpt-fe`(`components/Welcome.vue`、`components/Review.vue`) +- **依据**:`Welcome.vue` 的残片卡片当前直接挂了 `MarkerChips`(`Welcome.vue:497`,打标签/筛选)与三个动作按钮「已掌握 / 稍后再看 / 学习引导」(`Welcome.vue:504-525`);另有 `color-legend` 图例(`Welcome.vue:465`,文案「学习残片」+ 一段 tooltip 解释)。首页因此同时承担了「暴露内容」与「执行操作」两件事。 +- **建议**: + 1. 首页滚动条只保留**只读展示**:残片正文、来源任务、时间等;移除打标签、反馈(已掌握/稍后再看)、学习引导等写操作控件。 + 2. 移除 `color-legend` 图例及其 `el-tooltip` 说明(「学习碎片」图例即此处)。 + 3. 上述操作改在复习模块完成。落点需先定:复习 Feed 就地操作,还是进 `ReviewDetail.vue` 详情后操作。 +- **待确认**:首页是否保留「点击残片跳到复习详情」的纯导航(建议保留,纯导航不算写操作);复习模块现有两条路径(`Review.vue` 任务卡片 + `ReviewDetail.vue` 详情),是否需要新增按残片粒度的操作面板。 +- **验收**:首页不出现任何打标签/反馈/引导控件与图例;同样的操作在复习模块内可完成;`lpt-fe/src/__tests__/components/Welcome.spec.ts` 相关断言同步更新,`npm run type-check` 与 `npm test` 全绿。 + +### 闭环-02 任务名自动成为标签(把「任务」降级成一种标签) + +- [ ] 未完成 +- **涉及仓库**:`lpt-be`(残片产生路径)+ `lpt-fe`(标签展示与修改) +- **依据**:任务名目前只是 `tasks.task_name`,没进标签体系;而 `markers` 已支持自由标签(`MarkerKindEnum` 的 TAG)与系统标记两套语义(见 §5 标记-01)。回忆复习里导图取材已改为「归属该任务的残片」(§5 归属-01),聚合维度实际被任务锁死。 +- **建议**:残片落库时自动打一条「任务名标签」,用户可改可删;实现上优先复用 `markers` 的自由标签,不再造第二套标签存储。 +- **待确认**: + - 任务名标签当**系统标记**(只读词表 + 带值)还是**自由标签**(可改名删除)?走系统标记语义更严谨,但要给 `SystemMarkerEnum` 加一个「归属任务」类型,且用户改不了名。 + - 任务改名时旧标签是否跟随更新(建议不追溯,历史按当时名字保留)。 + - 删任务时标签如何处理(现有语义:删任务后残片进「待归类」)。 +- **验收**:新建残片后自动带上任务名标签;用户可修改或删除;同一任务名的残片能用该标签一次筛出。 + +### 闭环-03 标签管理与打标签时搜索选择 + +- [ ] 未完成 +- **涉及仓库**:`lpt-fe`(`components/MarkerChips.vue`、`Review.vue` 的标签管理弹窗)+ 可能需要 `lpt-be` 补接口 +- **依据**:`MarkerChips.vue` 的打标签入口是普通 `el-input`(`placeholder="标签名"`,`MarkerChips.vue:87`),**没有候选也没有搜索**,只能靠记忆手输;标签管理目前只有 `Review.vue:509` 的弹窗 + `PUT /markers/rename`、`GET /markers/tags`(用量统计),没有「提前新建/批量整理」的入口。 +- **建议**: + 1. 标签管理支持提前增删改:新建空标签、改名、删除、看用量。 + 2. 打标签改为可搜索选择:输入即过滤已有标签(含自动的任务名标签),同时允许输入新标签。 + 3. 「提前存在的标签」目前无处可放(`markers` 的每一行都挂在一个对象上)。这是本条的**实现前提**,见下。 +- **待确认**:标签字典放哪里——在 `markers` 里造「无对象」行,还是新增 `user_tags` 字典表(建议后者,语义干净);删除字典标签时是否连带删除已打在残片上的标记(建议:字典删除只影响候选,不动已打标记);大小写与去重口径。 +- **验收**:可在标签管理里提前建好标签;打标签时能搜到并选中;删除字典标签不破坏已有标记。 + +### 闭环-04 按标签做回忆复习并生成导图 + +- [ ] 未完成 +- **涉及仓库**:`lpt-be`(导图存储与取材口径、回忆对比入口)+ `lpt-fe`(`Review.vue` / `ReviewRecall.vue`)+ `lpt-ai`(提示词入参) +- **依据**:回忆复习目前是任务维度——`Review.vue` 任务卡片主操作进 `/review/recall/:taskNum`(`ReviewRecall.vue`),基础导图也按 `taskNum` 存取。想要「按概念复习」,现在没有任何入口。 +- **建议**:复习模块增加「按标签复习」:选一个或多个标签 → 聚合带这些标签的残片 → 生成/更新一张导图 → 走既有回忆对比链路。 +- **待确认**: + - 与按任务复习**并存还是替代**(建议先并存,避免一次性推翻既有数据模型)。 + - 按标签生成的导图存哪里:`review_standard_mind_maps` 现在以 `taskNum` 为键,需要引入「标签导图」的存储口径(新表 / 表加维度列)。**这是本条主要改造点。** + - 多标签取**并集还是交集**;导图与标签组合的缓存键如何定义,以及标签集合变化后何时重算。 +- **验收**:选定标签后可生成导图并完成一次回忆对比,记录落库可追溯;不影响既有按任务复习。 + +### 闭环-05 任务执行页展示并编辑该任务的基础导图 + +- [ ] 未完成 +- **涉及仓库**:`lpt-fe`(`components/StartTask.vue`) +- **依据**:后端**已有** `GET/PUT /review/standard-mind-map/{taskNum}` 与 `POST .../find-node`;前端 `api/standardMindMap.ts` 已封装 `getStandardMindMap` / `updateStandardMindMap` / `findNode`,`MindMapViewer.vue` 已支持 `:editable="true"`。但这套只在 `ReviewRecall.vue`(`/review/recall/:taskNum`)用过,`StartTask.vue`(任务执行页)完全没有导图。**所以这条基本是前端接线,不需要后端改造。** +- **建议**:任务执行页增加该任务基础导图的展示 + 就地编辑(复用 `MindMapViewer` 与既有 PUT),让「应用知识时发现定义有缺陷」能立刻改导图。 +- **待确认**:编辑粒度(只改节点文案,还是允许增删节点/调层级——取决于 `MindMapViewer` 现有编辑能力);两个入口同时编辑时的**互相覆盖**(`PUT` 是整体覆盖 `outline`),建议引入版本号或最后写入时间校验。 +- **验收**:任务执行页能看到当前任务的基础导图;改动后能在复习页看到同一份;编辑冲突有明确行为且不会静默丢改动。 + +### 闭环-06 记录应用过程中犯的错误 + +- [ ] 未完成 +- **涉及仓库**:待定(新能力,至少要碰 `lpt-be` + `lpt-fe`,可能也要 `lpt-docs` 先定概念) +- **依据**:维护者观察——学习时间主要花在「识别概念」与「实际应用(做题)」上,而现在的残片体系只适合记录「刚学到的内容」,**没有地方记录「用错了 / 做错了」**。这类信息才是查缺补漏的直接线索,且天然发生在做题时(不在学习页面)。 +- **建议(待定,仅作讨论起点)**:新增一种「错误记录」条目,至少包含:题目/场景、我当时的错误做法、正确的做法或正确答案、关联的概念或导图节点;支持从题目直接记录(不要求先回到学习页);可在复习模块按概念/标签聚合回看。 +- **待确认**: + - 是新增独立实体,还是复用残片体系加一个「类型/标记」维度(如系统标记 `错题`)?后者改动小,但残片与「错误」的语义差别较大。 + - 是否必须关联到导图节点/概念(关联才能做「概念→错误」的复习,价值最高,但录入成本也高)。 + - 复习方式:「错误」是进现有复习 Feed 一起排序,还是单独一个回看列表。 + - 是否需要 AI 参与(如把错误总结成「这个概念的高频误区」)。 +- **验收**:待本条决策定稿后补。**在数据模型定下来之前不要动手实现。** + +--- + + + ## 附录 A 核对方式(可复现) - 代码核对:阅读 `lpt-be` 的 `service/impl/*`、`entity/*`、`controller/*`、`config/*`、`resources/application*.yml`、`resources/db/migration/*`;`lpt-fe/src` 的 `utils/request.ts`、`components/*`、`api/*`;`lpt-ai/src` 全部;`lpt-infra` 的 `dev/`、`prod/`、`traefik/`。