85 KiB
LPT 实现优化清单
面向接手实现的代理。每条都是功能性问题(数据正确性、能力缺失、性能、安全),不含外观类改进。 §3 列出已确认的设计决策:它们是有意为之的行为,不要当作缺陷修改。
0. 基线信息
| 项目 | 核对基线 |
|---|---|
| 生成时间 | 2026-09-14 |
| 代码基线 | lpt-be c961157 / lpt-fe e66bdb7 / lpt-ai 200f088 / lpt-infra 0a23075 / lpt-docs 9cb9c75 |
| 核对方式 | 通读上述仓库源码 + 对线上 prod/dev 做只读探测(见附录 A) |
| 复核时间 | 2026-10-08 |
| 复核基线 | lpt-be 04d1f40 / lpt-fe 99a1b16 / lpt-ai bf56c2b / lpt-infra 34f2380 / lpt-docs a16cb4c |
| 复核结论 | 会话-01/02/03 已修(lpt-be d8c8b76);会话-04 仍无 @Scheduled;AI-03 已修(见条目)。基础设施变更:时区固定、LLM 切换为 DeepSeek(不影响本清单条目) |
若某仓库 HEAD 已明显晚于上表,先确认问题是否已被修复,再动手。
1. 协作约定
- 完成一项后:勾选对应条目并追加一行「完成于 <仓库> 」;若条目语义已被改动,直接重写条目,不要追加开发日志。
- 涉及概念/设计语义的改动(如会话生命周期、有效时间定义):必须同步更新
lpt-docs的概念或设计文档;lpt-docs只写概念与设计,不写实现过程。 - 本文档不记载开发过程,只保留「待办 + 依据 + 验收标准」。禁止写入任何密钥、密码、Token 明文。
- 条目粒度按「一个代理能独立完成并自测」切分,跨仓库条目已标注涉及仓库。
- §3「设计决策」不是待办:改动前必须先与维护者确认,禁止当成缺陷直接「修复」。若某项决策需要调整,先在 §3 改写该条,再开对应实现条目。
- 编号规则:条目编号以中文领域前缀开头,形如
复习-02,前缀必须让人一眼看出改动落在哪块(会话、复习、报告、归属、导出、AI、数据、安全、运维、清理);设计决策用会话-决策01这种形式。编号不复用,旧编号作为别名保留在条目首次出现处(如复习-02(原 LPT-09))。
2. 改动计划总览(按模块)
按模块给设计和决策。状态 含义:可直接实施(方案已定,不需维护者再拍板)/待决策(结论落地前不要开工)/依赖其他条目。
| 模块 | 条目 | 优先级 | 状态 | 需要先定什么 |
|---|---|---|---|---|
| 学习会话生命周期 | 会话-01 遗忘检测路径不统一 | P0 | 已完成 | — |
会话-02 isOverTime() 误报超时 |
P0 | 已完成 | — | |
| 会话-03 结束会话不幂等 | P0 | 已完成 | — | |
| 会话-04 悬挂会话无收敛 | P0 | 已完成 | — | |
| 会话-05 活跃会话拦截无出路 | P1 | 已完成 | — | |
| 内容归属与报告 | 归属-01 内容归属与待归类 | P1 | 已完成 | — |
| 报告-01 报告与碎片不可修订 | P1 | 已完成 | — | |
| 标记与元信息 | 标记-01 统一标记存储 | P1 | 已完成 | — |
| 复习 | 复习-01 复习回路补全 | P1 | 已完成 | — |
| 复习-02 Feed 只读无反馈动作 | P1 | 已完成 | — | |
| 复习-03 Feed 随机取样 | P3 | 已完成 | — | |
| 复习-04 覆盖率查询拉全量 | P3 | 已完成 | — | |
| 复习-05 Feed 返回全文 | P3 | 已完成 | — | |
| 复习-06 学习引导 | P1 | 已完成 | — | |
| 复习-07 复习耗时统计 | P2 | 已完成 | — | |
| AI 链路 | AI-01 事务内同步等 AI | P2 | 已完成 | — |
| AI-02 全链路同步阻塞 | P2 | 已完成 | — | |
| AI-03 单 worker 串行无重试 | P2 | 已完成 | — | |
| AI-04 防并发锁是 JVM 内存锁 | P2 | 已完成 | — | |
| 数据与检索 | 数据-01 业务主表缺索引 | P3 | 已完成 | — |
| 数据-02 统计聚合在内存 | P3 | 已完成 | — | |
| 数据-03 编号撞号风险 | P3 | 已完成 | — | |
| 导出 | 导出-01 无数据导出 | P1 | 已完成 | — |
| 安全 | 安全-01 数据库凭证明文 | P4 | 已暂缓(维护者决定) | 重新评估前提见条目内「当前决策」 |
| 安全-02 Actuator 鉴权边界 | P4 | 已完成 | — | |
| 安全-03 AI 入站无防护 | P4 | 已完成 | — | |
| 安全-04 生产打印全部 SQL | P4 | 已完成 | — | |
| 运维与清理 | 运维-01 备份只在同一 PVC | P4 | 已暂缓(维护者决定) | 恢复前提见条目内「维护者决定」 |
| 清理-01 死代码与死表 | P4 | 已完成 | — | |
| 学习录音 | 录音-01 采集后端接口与 OBS 后端 | P1 | 已实现·已暂停 | 先定采集方案:OBS / 自研原生 |
| 录音-02 控制通道与会话绑定 | P1 | 已暂停 | 轮询 lpt-be / 直连本机端口(建议轮询) | |
| 录音-03 音频落盘与对象存储 | P1 | 已暂停 | 对象存储选型(MinIO / 云对象存储) | |
| 录音-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。
已确认的设计决策(不是待办):会话-决策01 少于 10 分钟不计入总时长;会话-决策02 遗忘判定阈值 50 分钟;录音-决策01 录音由本机伴随程序负责;录音-决策02 只采系统输出不采麦克风。
3. 已确认的设计决策(不是待办,不要当缺陷改)
会话-决策01(原 D-01)少于 10 分钟的有效学习时间不计入总学习时间
- 依据:
StudySessionsEntity.endedStudySession():effectiveTime < 10 * 60 → setEffectiveTime(0); setEffectivenessRatio(0);常量MIN_EFFECTIVE_TIME_SECONDS。 - 决策:25 分钟的番茄钟已经足够碎片化,更短的碎片视为噪声,刻意不记录。
- 注意:这与
lpt-docs/design/principles.md中「量化,但不评判」存在张力,但已由维护者确认为有意取舍。除非维护者主动改变口径,否则不要改成「保留真实值 + 打标记」。 - 来源:原 LPT-02 条目,2026-09-14 由维护者澄清后重新归类。
会话-决策02(原 D-02)遗忘判定阈值为 50 分钟(2 × WORK_DURATION)
- 依据:
StudySessionsEntity.isOverTime():minutes >= WORK_DURATION * 2;触发时按lastStartTime + 25 分钟截断有效时间。 - 决策:25~50 分钟区间默认用户仍在屏幕前(番茄钟已提醒但可能正在收尾),不做截断;超过 50 分钟才判定为「忘了点暂停/结束」。
- 注意:不要把这个阈值改成等于番茄钟长度(25 分钟);阈值存在的意义是区分「在学」与「忘了关」。真正要修的是执行路径不统一,见 会话-01。
录音-决策01 录音由运行在本机的伴随程序负责,浏览器不采集也不传输音频
- 依据:浏览器无法在 Linux/macOS 采集系统音频(Chrome/Edge 仅在 Windows/ChromeOS 共享整个屏幕时可采系统声,Linux/macOS 只能采标签页音频,Firefox/Safari 不支持音频捕获);Chromium
media/audio/pulse/audio_manager_pulse.cc明确排除 monitor(loopback)设备。此外公网页面直连本机端口在 Chrome 142+ 受 Local Network Access 权限约束(Chrome 152 实测:公网页面向127.0.0.1的 fetch 被拒,navigator.permissions.query({name:'local-network-access'})返回prompt)。 - 决策:采集、编码、上传全部由运行在用户本机的伴随程序完成;网页只负责发起、结束与展示。网页关闭或崩溃不影响录音。
- 注意:不要把「浏览器直接采系统声」当作可用的退化路径,也不要默认用「本地端口直连」做控制通道(取舍见 录音-02)。
录音-决策02 只采系统输出,不采麦克风
- 依据:录音要回答的是「用户听到了什么」,而不是「房间里发生了什么」。
- 决策:只采系统混音,不采麦克风,也不用麦克风作为兜底来源。
- 注意:这条同时收敛隐私范围与转写噪音,不要为提高「完整性」而混入麦克风。
录音-决策03 采集层只用 OBS,不自研原生采集(已暂停,待重评)
2026‑10‑08:本决策已回退为「待重评」。录音-01 实现完成后暴露了两个与决策依据相冲的事实:① OBS 无法直接录出纯音频(详见 §12),必须再引入 ffmpeg 抽音轨;② OBS 安装体积与跨平台配置差异成本高于先前估计。重启本模块前重新拍板,参见 §12「路线分叉」。
- 依据(当时):OBS 三平台都原生支持系统音频采集(Windows WASAPI loopback、Linux PulseAudio/PipeWire monitor、macOS 13+ ScreenCaptureKit),官方发布覆盖 Windows x64/arm64、macOS Apple/Intel、Ubuntu
.deb;自研需分别实现三套原生采集(尤其 macOS SCK),成本远高于引入 OBS。 - 决策(暂停):采集层只做 OBS 后端,不保留原生后端的分支;OBS 的发布与升级由用户自行负责。
- 注意:不要因为「不想让用户装 OBS」而临时增加虚拟声卡方案(Linux
module-remap-source+ 常驻 watcher),该路线已实测可行但被本决策取代。
4. P0 数据正确性
会话-01(原 LPT-01)遗忘检测只在「重新进入学习页面」这一条路径上执行
- 已完成
- 完成于
lpt-bed8c8b76 - 涉及仓库:
lpt-be(可选lpt-fe心跳) - 前提:系统已具备遗忘检测(见 会话-决策02),问题不在于缺少机制,而在于它只挂在一条路径上。
- 依据:
pausedStudySession(lastStartTime.plusMinutes(WORK_DURATION))只在StudySessionsServiceImpl.startOrContinueStudySession()中出现(全仓唯一)。而pauseStudySession()与StudySessionsEntity.endedStudySession()(内部pausedStudySession(now))都是直接effective += now - lastStartTime,没有遗忘检测。 - 影响:页面不刷新、停留在前台时,pause / ended 两条路径依然可达。典型场景:番茄钟响起后用户离开,3 小时后回到同一个页面点「休息」(
StartTask.vue的restTimer()→stopTimer()→ pause 接口),这 3 小时被全额计入有效学习时间。是否被截断取决于用户有没有刷新过页面。 - 理由:这恰好落在 会话-决策02 想覆盖的「忘了点暂停/结束」场景里,属于检测点遗漏,会让同一行为产生两种统计结果,直接损害时间数据的可信度。
- 建议:抽出统一的结算时间函数(如
resolveSettlementTime(session):now - lastStartTime > 50min时返回lastStartTime + 25min,否则返回now),在 pause / ended / 定时收敛三条路径共用;番茄钟长度与两类阈值统一配置化。 - 验收:构造「ONGOING 且
last_start_time为 3 小时前」的会话,分别调用 pause 与 ended 接口,断言effective_time被截断到 25 分钟;StudySessionsEntityTest同步补用例。
会话-02(原 LPT-03)isOverTime() 误报「超时 25 分钟」
- 已完成
- 完成于
lpt-bed8c8b76 - 涉及仓库:
lpt-be - 依据:
StudySessionsEntity.isOverTime()只比较last_start_time与当前时间,不看end_time与session_state。startOrContinueStudySession()用同一判定既驱动截断又驱动systemMessage。 - 影响:已暂停很久的会话(时间早已在暂停时正确入账),每次回到页面都会弹「上段学习任务已经超时 25 分钟,将仅计算为 25 分钟的有效学习时间」。
- 建议:拆分「是否需要截断」与「是否需要提示」两个判定,并纳入
end_time/state。 - 验收:对
state=PAUSED且end_time已存在的会话,接口不返回systemMessage。
会话-03(原 LPT-04)结束会话不幂等,会产生重复学习报告
- 已完成
- 完成于
lpt-bed8c8b76 - 涉及仓库:
lpt-be - 依据:
StudySessionsEntity.endedStudySession()在state = ENDED时只log.warn并原样返回;StudySessionsServiceImpl.endedStudySession()随后无条件studyReportsMapper.insert(...)。 - 影响:重复点击、网络重试即可写入多条报告 → 复习 Feed 重复项、标准导图重复节点、统计重复计数。
- 建议:
state != ENDED才允许写报告,否则幂等返回;接口层可加幂等键。 - 验收:对同一
sessionNum连续调用两次结束接口,第二次不新增报告(断言报告条数)。
会话-04(原 LPT-05)缺少服务端兜底:悬挂会话与超长会话无人收敛
- 已完成
- 完成于
lpt-bedb55218 - 涉及仓库:
lpt-be - 已实施:
- 硬兜底阈值 2 小时:进行中且最后一段超过该时长时强制收敛为暂停,按遗忘规则(会话-决策02)截断到
last_start_time + 25 分钟,并落auto_converged标记供前端提示「疑似忘记结束」。 - 收敛方式采用并用:惰性收敛挂在「活跃会话」与「任务未结束会话」两个读取入口;定时扫描(默认 10 分钟)兜底,保证用户不回来时统计也会收敛、悬挂会话不再阻塞新任务。
- 四类阈值(25 分钟番茄钟、50 分钟遗忘判定、2 小时硬兜底、10 分钟有效时间下限)统一收到
lpt.study-time.*配置,实体入口由统一的时间口径对象承载;非法组合(兜底阈值小于遗忘阈值等)在启动时直接失败。
- 硬兜底阈值 2 小时:进行中且最后一段超过该时长时强制收敛为暂停,按遗忘规则(会话-决策02)截断到
- 实现约束:收敛写入一律使用「状态仍为 ONGOING」的条件更新,惰性收敛与定时扫描并发时只结算一次;定时扫描跨租户扫描(系统级后台任务,无登录态),但不影响读取路径的租户隔离。
- 测试环境:定时任务用
lpt.study-time.scan-enabled: false在测试配置里关闭,避免调度任务与用例自造的悬挂会话互相干扰(落库集成测试直接调用扫描方法)。 - 验收:制造一个 3 小时前的 ONGOING 会话,在不访问该任务页面的前提下,惰性/定时收敛后状态为 PAUSED 且有效时间已按 会话-决策02 截断;正常进行中的会话不受影响。✅ 已用落库集成测试覆盖(惰性、定时、不会误伤正常会话、不跨租户、重复扫描不重复结算)
5. P1 会挡路的功能缺口与待补能力
会话-05(原 LPT-07)活跃会话拦截没有出路,会永久堵住新任务
- 已完成
- 完成于
lpt-fe25fbc67(+lpt-docs804d53a) - 涉及仓库:
lpt-fe(+lpt-be需提供结束/放弃能力) - 已实施:拦截入口补两个新出口:「结束它并开始新任务」(复用
ended接口,旧会话会生成一份未填写总结的报告)与「放弃该会话」(复用abort,仅限未产生学习残片的会话,后端拒绝时原样转达原因);两者成功后继续开始当前任务,一次交互内解除阻塞。另对 会话-04 自动收敛过的会话在弹窗与任务页给出「疑似乎忘记结束」提示。 - 依据(修正):守卫实际位于
StartTask.vue的loadTaskSession()(清单原文写的是Study.vue的startTask(),与实际代码不符,已按实际位置改);原行为只有「前往继续 / 取消」,取消后只弹一条提示,用户无处可去。 - 影响:一个搁置数月的暂停会话会阻止开始任何新任务(所有任务入口都撞同一个守卫),用户必须先找回那个任务手动结束。
- 验收:存在陈旧活跃会话时,用户可在一次交互内开始新任务。✅ 已用交互式集成测试覆盖五个出口分支(前往继续 / 结束并开始 / 放弃 / 放弃失败 / 取消)
报告-01(原 LPT-08)学习报告与知识碎片不可修订
- 已完成
- 完成于
lpt-bec74f73a(+lpt-fe18a2580) - 已实施:碎片与报告都支持编辑与删除(软删除);新增
PUT /report-fragments/{id}/ownership、DELETE /report-fragments/{id}、PUT|DELETE /review/report/{id}、GET /review/report/{id}/structured;报告改为结构化三段(session_summary/expectation_verdict/free_summary,原content直接改名,不做老数据兼容),「按归属分组的碎片」查看时实时聚合;删除报告不连带删碎片,弹窗明示碎片保留。
已确认的决策(2026-10-09,维护者)
- 修订范围:知识碎片与学习报告都可编辑、都可删除。删除一律走软删除(
deleted),Feed / 统计 / 导图取材按未删除过滤。
- 取舍:接受了「报告可被改写,因此不再是不可变的原样事实」,换取记录成本下降。这与 §3 支点「学习报告是会话产出的真实记录」存在张力,属于维护者的有意取舍。
- 连带口径:碎片删除不连带删报告(碎片是原料,报告是收敛)。
- 导图处理:删改后给受影响任务置「待更新」标记,AI 重建由用户手动触发,不自动重建(避免一次删除触发大范围 AI 调用)。
- 删除报告不连带删碎片:报告与碎片在库里是并列关系(都挂在会话上),碎片是独立原料。删除报告时弹窗明示「本次学习的 N 条碎片会保留」。
- 关键理由:归属-01 之后碎片有独立的内容归属,可能已被归类到其他任务;连带删除会删掉已经归属到别处的内容。
- 删除后:报告
deleted=1;碎片不变;受影响任务置「待更新」;统计里报告数 -1、碎片数不变。- 删除学习任务时:碎片保留并把内容归属置空(进入待归类),其余(会话、报告、标准导图、回忆记录、应用场景)随任务一并软删除。
- 与决策 1、2 一致:碎片是原料,不因归属消失而消失;删任务撤销的是「这次学习的时间记录与收敛结果」,不是知识本身。
- 弹窗必须分别列出「即将删除」与「即将保留(N 条碎片进入待归类)」,避免用户以为删干净了。
- 顺带修复:当前
deleteTask只软删任务行、不级联任何东西,而前端弹窗却写着「关联的会话/报告/应用场景将被一并删除」——文案与实现不一致。
- 未完成
- 涉及仓库:
lpt-be(+lpt-fe) - 依据:端点清单——
StudyReportFragments只有POST/PUT /{id}/GET;StudyReports只有创建与查询,没有 PUT、没有 DELETE;碎片也没有 DELETE。 - 影响:写错不能改,也不能删除,只能改数据库。
- 理由:知识碎片是学习报告、复习 Feed、标准导图的共同原料,记录成本上升会直接降低记录率,连锁削弱整个复习闭环。
- 建议:报告支持编辑与删除;碎片支持删除;删除需考虑对标准导图、回忆记录、统计的影响(软删除 + 标记重建导图)。
- 验收:报告/碎片可编辑与删除;删除后 Feed 与统计不再包含该条。
复习-02(原 LPT-09)复习 Feed 只读,没有反馈动作
-
已完成
-
完成于
lpt-be63824b2(+lpt-fe232fdb8) -
已实施:碎片新增
mastered/revisit/last_reviewed_time;PUT /review/feed/{fragmentId}/feedback标记或取消两个动作,POST /review/feed/{fragmentId}/touched记录「接触」;智能排序的第三个信号取「最近接触时间」,「稍后再看」×1.6,「已掌握」×0.3(不归零,保留文档要求的随机性)。 -
刻意的取舍:Feed 响应里
mastered/revisit用@JsonIgnore隐藏,前端只跟踪本次浏览内的点击状态。这样前端无法把反馈做成徽标或计数——一旦展示成状态,复习就会滑回清单模式。 -
未完成
-
涉及仓库:
lpt-be(+lpt-fe) -
依据:Feed 仅提供列表/详情/回忆对比;
ReviewServiceImpl.reviewNeedWeight()的智能权重只有两个信号——时间衰减(createdTime)与任务最近一次回忆覆盖率。 -
影响:无法表达「这条其实很熟」与「这条完全没印象」;权重长期只有两个偏置,也没有「已复习」状态,同一批内容会反复出现。
-
建议:加轻量动作(稍后再看 / 已掌握),把「上次复习时间」变成第三个权重信号;保持既有「无压力、偶遇式」设计,不引入强制清单。
-
依赖:动作形态需先确认 复习-01(§11)中的反馈动作取舍。
-
验收:用户反馈动作可落库并在下一次 Feed 排序中生效。
导出-01(原 LPT-10)无数据导出
- 已完成
- 完成于
lpt-befaaaa13、lpt-fe87e4cea - 涉及仓库:
lpt-be(+lpt-fe) - 已实施:两个只读接口
GET /export/task/{taskNum}与GET /export/range?startDate&endDate,均支持format=markdown|json(默认 markdown);内容随统一响应体返回(ExportResult{fileName, contentType, content}),前端落成文件下载,不引入新的响应约定。两种格式共用同一个导出模型,保证内容一致。 - 范围口径:按时间范围导出时,报告与碎片先按时间倒序合并再按内容归属分组,保证同一任务下两种内容交错时顺序仍然正确;起止日期均为闭区间,省略即不限制(默认方案)。
- 附带效果:导出内容包含任务维度的统计,顺带覆盖了 复习-07 新增的复习耗时。
- 理由:
lpt-docs明确系统定位是「辅助学习的工具」,工具型系统应保证数据可携带;同时可缓解备份粒度过粗的问题(见 运维-01)。 - 验收:导出内容可独立阅读,包含报告/碎片原文与时间信息。✅ 单测覆盖两种格式、范围分组顺序、空范围、非法格式/起止日期倒置;前端集成测试覆盖导出弹窗主流程与未选时间段的拦截
复习-06 学习引导
- 已完成
- 完成于
lpt-aifb3c6f9、lpt-beb51a621(+lpt-fe232fdb8) - 已实施:新增复习行为实体
review_guidance_conversations(记录上下文与复习耗时都挂在它身上);GUIDANCEAI 任务类型按轮提交,AI 回复写回会话轮次作为下一轮上下文;入口为 Feed 卡片与导图节点;用户确认后产出的碎片记录上下文为这次复习行为、默认内容归属为被引导概念所属任务、并带FROM_GUIDANCE系统标记;放弃不产生任何数据。 - 涉及仓库:
lpt-be+lpt-fe+lpt-ai(概念文档已写入lpt-docs) - 依据:复习只有接触(Feed)与结构提取(回忆对比),概念边界上的误解(例如把“参数量”当成能决定磁盘占用)不会被覆盖率捕捉。
- 已定:开放式问题引导(例:“1B 参数量的 LLM 模型,会占用多少磁盘空间?”),无标准答案、不判分;AI 在对话中纠正回答里隐含的边界问题;对话不设轮数上限;产出是知识碎片,由用户确认后记录;复用碎片全链路(归属、待归类、导图取材、Feed 回收);碎片默认归属“被引导概念所属的学习任务”,并带「来自学习引导」标记(仅标记,不做特殊处理);记录上下文为复习行为;耗时计入复习-07;不进入学习报告;入口为 Feed 卡片与导图节点;不提供降级形态,AI 不可用时该功能整体不可用。
- 前置条件:依赖 AI-02 / AI-03(多轮对话不能建在当前同步阻塞的链路上);「来自学习引导」标记的存储依赖标记-01。
- 验收:一次学习引导结束后,用户确认可生成一条归属正确、带来源标记的碎片,并随导图增量更新出现;不确认则不产生任何数据;AI 不可用时入口不可用,且不影响复习其他部分。
复习-07 复习耗时统计
- 已完成
- 完成于
lpt-be3b33cd8、67c8711,lpt-fe21af81f - 涉及仓库:
lpt-be+lpt-fe - 已实施:回忆记录落
review_duration_seconds,recall接口接收前端计时并由服务端统一结算,复习总览按任务聚合后与学习时长并列。 - 遗留:学习引导尚未实现(复习-06),其耗时复用同一个
review_duration_seconds字段,不需要再改表结构。 - 依据:复习总览目前只展示来自会话的“累计有效学习时长”(
ReviewTaskStats.effectiveTime),复习行为本身没有任何计时,投入不可见。 - 已定口径:只对回忆对比与学习引导计时,滚动浏览不计时;超过 5 分钟无交互则截断到上一次交互时间(复习没有暂停动作);命名“复习耗时”,不叫有效复习时间、不套用 10 分钟最小阈值;复习总览按任务与学习时长并列展示;不做跨任务汇总大数字、不设目标、不参与复习排序。
- 建议:把复习行为作为时间记录的主体(回忆对比已有记录实体,学习引导新增),耗时写在该行为上;前端补空闲检测并上报交互时间。
- 验收:完成一次回忆对比后,复习总览该任务行出现复习耗时且与学习时长分列;页面挂机超过 5 分钟不再继续累计。
6. P2 AI 链路(收益成本比最高)
AI-01(原 LPT-11)recallCompare 在事务中同步等待 AI,长事务占用数据库连接
- 未完成
- 涉及仓库:
lpt-be - 依据:
StandardMindMapServiceImpl.recallCompare()标注@Transactional,内部同步调用AiServiceClient.compareRecall()(轮询上限lpt.ai-service.timeout-seconds: 600)。Hikari 连接池未显式配置,为默认 10。 - 影响:并发几个回忆对比即可耗尽连接池,导致全站请求阻塞。这是建议最先修的一条:把 AI 调用移出事务即可,改动小、风险低。
- 建议:先做纯读的对比计算(事务外),再开短事务写入回忆记录;或引入任务表 + 异步回写(与 AI-02 一起做)。
- 验收:AI 调用期间不持有数据库连接(可通过连接池监控或长事务日志证明)。
AI-02(原 LPT-12)AI 全链路同步阻塞,用户需干等最长 10 分钟
- 已完成
- 完成于
lpt-becf380c5、lpt-fee52682c(+lpt-docs39efbb6) - 涉及仓库:
lpt-be+lpt-fe+lpt-ai - 已实施:新增
ai_tasks表与统一 AI 任务接口(POST /ai/tasks、GET /ai/tasks/{taskNum}、GET /ai/tasks/latest):- 提交秒级返回任务标识,结果写在
result_payload,按标识可重复获取; - 三类能力(回忆对比、标准导图生成、报告草稿)全部改为任务;
- 读取接口不再产生副作用:
GET /review/standard-mind-map/{taskNum}不再自动生成(缺失时返回 null),GET /study-sessions/{sessionNum}/report-draft已删除; - 执行器在
ai-task-*线程池里执行,提交后立即投递,@Scheduled兜底扫描接手投递失败与进程重启;卡在 RUNNING 超过阈值的任务会被回收重试。
- 提交秒级返回任务标识,结果写在
- 顺带修掉的一个真实缺陷:后台执行线程没有 Web 上下文,而租户拦截器与公共字段自动填充都取
StpUtil,会直接抛NotWebContextException。已引入TenantContext让后台线程显式声明执行身份(以任务所属用户执行),请求线程行为不变。 - 遗留:
lpt-ai侧无需改动(AI-03 已提供任务队列);lpt-be的AiServiceClient仍是「提交到 lpt-ai 后轮询」的同步封装,但已被调用在执行线程内,不再阻塞请求。 - 依据:
lpt-fe/src/utils/request.ts的timeout: 600000;lpt-be的AiServiceClient.submitAndWait()内部轮询最长 600s;GET /study-sessions/{sessionNum}/report-draft这类 GET 也会触发 10 分钟阻塞并计费。 - 验收:提交 AI 任务后接口在秒级返回任务标识;任务结果可重复获取,无需重试即可拿到。✅ 落库集成测试覆盖:提交不在请求线程里调 AI、按标识重复查询结果一致、失败任务可查到原因、任务受租户隔离
AI-03(原 LPT-13)lpt-ai 单 worker 串行且无重试
- 已完成
- 涉及仓库:
lpt-ai(+lpt-be超时策略) - 完成于
lpt-aibf56c2b - 依据:
task-queue.ts只有一个processing标志顺序处理;失败直接置failed,无退避重试;任务记录TTL_MS = 1 小时。 - 影响:N 个并发请求时第 N 个需等待 N × LLM 耗时,超过
lpt-be的 600s 超时后表现为「AI 实际成功、客户端已超时」,结果既不落库也不告知,用户重复点击导致重复计费。LLM 的 429/5xx 抖动被当成永久失败。 - 已实施:
- Worker 池:并发度
LPT_AI_CONCURRENCY(默认 2),队列改为基于 id 的 FIFO。 - 退避重试:新增
llm/retry.ts,仅重试 408/429/5xx 与超时;4xx 客户端错误与「API Key 未配置」不重试;服务端Retry-After优先于自算退避。为此让LlmError保留上游真实状态码(原先一律记为 502,无法区分 429 与 400)。 - 幂等与结果复用:以
type + params的稳定哈希为幂等键(支持显式idempotencyKey);进行中的相同请求合并为同一任务,已完成结果在LPT_AI_RESULT_CACHE_MS窗口内复用;失败任务不复用,保留用户重试机会;请求体force: true可强制重新生成。 - 队列改为可注入依赖的
TaskQueue类,测试覆盖并发、重试、复用与清理。
- Worker 池:并发度
- 不得改动的契约:
/ai/tasks必须固定返回 201(Java 端AiServiceClient把非 201 视为提交失败),复用信息放在响应体的reused/status字段。 - 验收:并发 N 个任务时耗时不再线性增长;可重试错误不产生失败结论。✅ 已用假 LLM 服务端到端验证:4 个任务× 300 ms 共用 431 ms(串行需 1200 ms+);前两次 429 后仍为
done;相同请求只调用 LLM 1 次。 - 遗留:
lpt-ai的部署(lpt-infraconfigmap)未设队列相关环境变量,目前走默认值;需要调优时再补。
AI-04(原 LPT-14)防并发锁是 JVM 内存锁
- 已完成
- 完成于
lpt-becf380c5 - 涉及仓库:
lpt-be - 已实施:删除
StandardMindMapServiceImpl里的ConcurrentHashMap<String, AtomicBoolean> generatingTasks,改为基于ai_tasks的进行中判定:同一用户 + 同一类型 + 同一目标已有PENDING/RUNNING任务时复用该任务,因此不存在「多副本锁失效」。执行侧再用「状态仍为 PENDING」的条件更新抢占,多副本并发也不会重复执行。 - 对外语义已明确:提交接口返回的是任务状态(
AiTaskResponse),不再是可能为 null 的实体;前端据此展示「正在生成」。 - 验收:多副本场景下同一任务不会并发生成;生成中重复请求返回明确的进行中状态。✅ 单测覆盖「同一目标重复提交返回同一任务标识」,集成测试覆盖重复提交复用
7. P3 检索与数据增长
数据-01(原 LPT-15)业务主表缺索引,而每条查询都被追加租户条件
- 已完成
- 完成于
lpt-bee506c4d(补了 created_by 打头的复合索引;EXPLAIN 需在 MySQL 上核对) - 涉及仓库:
lpt-be - 依据:
V20250629_1__LPT_dataBase_init.sql中study_sessions/study_reports/study_report_fragments/tasks均只有主键;MybatisPlusConfig的租户拦截器给每条 SELECT/UPDATE/DELETE 追加created_by = ?;全仓仅少数 review 表有索引。 - 影响:所有高频查询(Feed、统计、按会话取碎片/报告)都是全表扫描 + 过滤,随使用量线性劣化。
- 建议:按实际查询补复合索引,例如
(created_by, task_num, session_state)、(created_by, session_num, created_time)、(created_by, created_time)、(created_by, task_num, calculated_priority)。 - 验收:
EXPLAIN显示关键查询走索引而非全表扫描。
复习-03(原 LPT-16)Feed 使用 ORDER BY RAND()
- 已完成
- 完成于
lpt-be251a468 - 涉及仓库:
lpt-be - 已实施:采样方式改为「随机起点 + 顺序取窗口」:先用
MIN(id)/MAX(id)(StudyReportFragmentsMapper.selectIdRange)取主键区间,在区间内随机选起点,再按id ASC取够数量;不足时从头回绕补齐,并按主键去重。random与smart两种模式共用该方法,全仓已无ORDER BY RAND()。- 起点后的
id >= ? ORDER BY id LIMIT n走主键索引,不再有全表随机排序。 - 取舍:删除造成的 id 空洞会让靠后的内容被略微偏重。对「偶遇式」的 Feed 可以接受,换来的是稳定的访问路径;若将来需要严格均匀,可改为预生成候选池。
- 起点后的
- 验收:Feed 接口不产生全表随机排序(
EXPLAIN可验证)。✅ 落库集成测试覆盖取满数量、页内不重复、确实随机(40 轮取样去重后远多于单页容量)、起点落在末尾时的回绕补齐
复习-04(原 LPT-17)取「每任务最近一次回忆覆盖率」时拉取全部回忆记录
- 已完成
- 完成于
lpt-be3dda263 - 已实施:新增
ReviewRecallRecordMapper.selectLatestRatioByTask,用「按任务取最大 id」的 JOIN 在 SQL 侧定位每个任务的最新记录,只返回task_num+recall_ratio两列,不再读取compare_result大字段。 - 涉及仓库:
lpt-be - 依据:
ReviewServiceImpl.latestRecallRatioByTask()按taskNum in (...)查询全部记录(含体积较大的compare_resultJSON)后只在内存里取每条任务的第一条。 - 影响:数据传输量与内存占用随复习次数线性增长。
- 建议:改为分组取最新(子查询/
MAX(created_time)),或把最近覆盖率冗余到任务表/导图表。 - 验收:该查询返回行数等于任务数而非回忆记录数。
数据-02(原 LPT-18)统计聚合在内存中完成且无时间范围
- 未完成
- 涉及仓库:
lpt-be - 依据:
ReviewServiceImpl.fillReviewTaskStats()加载所有任务的全部会话到内存再聚合,无时间窗、无分页。 - 影响:使用越久越慢,且会随会话数增长而内存膨胀。
- 建议:下推为 SQL 聚合(含今日/本周条件),必要时物化统计表。
- 验收:统计接口加载的会话行数与任务数同阶,不随历史会话数线性增长。
复习-05(原 LPT-19)Feed 返回全文
- 已完成
- 完成于
lpt-bedbeafba - 已实施:Feed 条目只返回 ≤200 字的摘要(换行压成空格),另加
contentLength(原文总长度)与contentTruncated;全文继续由详情接口按需拉取。前端本来就只在 120 字处截断,因此展示行为不变。 - 涉及仓库:
lpt-be+lpt-fe - 依据:
ReviewFeedItem.content直接返回报告/碎片全文,getReviewFeed(100, "smart")一次最多 100 条;前端只展示前几十个字(详情页才需要全文)。 - 建议:Feed 返回摘要字段(含长度标记),详情接口按需拉全文。
- 验收:Feed 响应体积显著下降且展示行为不变。
数据-03(原 LPT-20)编号生成有撞号风险且无唯一约束
- 已完成
- 完成于
lpt-be3cc3be1 - 涉及仓库:
lpt-be - 已实施:编码后缀由「6 位毫秒片段」改为「6 位毫秒片段 + 6 位随机数」(
SecureRandom),保留PREFIX-yyyyMMdd-<12位>的可读形态,不破坏已有编号与前端引用;同时补上唯一约束(created_by, task_num)与(created_by, session_num)(迁移V20261009_3),作为最终防线。 - 证据:此风险不是推测——为 复习-07 写落库集成测试时,同毫秒两次
generateNum真的产出了完全相同的task_num,导致两个任务的数据被并到同一条聚合。 - 注意:唯一约束迁移在历史数据已有重复编号时会直接失败——这是有意为之,需要人工确认后再处理,而不是静默跳过约束。
- 验收:并发创建 N 个任务/会话无重复编号,数据库层有唯一约束保护。✅ 单测覆盖 300 次连续生成无重复
8. P4 安全与运维
安全-01(原 LPT-21)数据库凭证明文入库
- 未完成(维护者决定暂缓,见下方「当前决策」)
- 涉及仓库:
lpt-be+lpt-infra - 依据:
application-prod.yml、application-dev.yml、application-local.yml均包含明文数据库账号密码(三个环境同一份)。lpt-infra已通过lpt-secrets注入SPRING_DATASOURCE_PASSWORD覆盖,但配置文件仍在 Git 历史中。 - 建议:轮换凭证 → 配置文件只保留占位符/环境变量引用 → 清理历史(或至少视为已泄露处理)。
- 验收:仓库中不再出现明文凭证;本地开发通过环境变量或本地未跟踪配置提供。
- 注意:不要把任何密码值复制进本文档。
- 2026-10-09 核查补充(供重新评估时使用,均不含凭证值本身):
- 三个环境的 username 与 password 完全相同,且 username 是
root(即三环境共用一个 root 账号,爆炸半径为「全库 + 全环境」)。 application-local.yml指向一个公网 MySQL,实测该端口 TCP 可达;这一份没有 k8s env 覆盖(本地开发无集群),是「活的」可能性最高的一份。application-prod.yml/application-dev.yml的值在集群内被lpt-secrets覆盖,可能只是死值;需用一条kubectl get secret核实是否与文件值相同。lpt-infra把 MySQL 暴露为NodePort(dev 30306 / prod 30307),这条与「凭证是否泄露」无关,是独立的暴露面。lpt-infra全仓无NetworkPolicy。
- 三个环境的 username 与 password 完全相同,且 username 是
- 当前决策(2026-10-09,维护者):暂缓。项目处于开发阶段,认为该风险可接受;不同环境使用不同密码会给开发带来不必要的精力消耗。
- 重新评估的前提:进入对外发布/多人协作阶段,或
lpt-secrets的值与仓库中的值相同(后者意味着公开在 Git 里的就是生产口令)。 - 若重新开工,建议顺序:先轮换凭证(使历史值作废)→ 再改配置占位符 → 「清 Git 历史」收益很低,可只做整洁性处理(改写历史会让所有已有克隆失效,且已外流的副本不受影响)。
- 重新评估的前提:进入对外发布/多人协作阶段,或
安全-02(原 LPT-22)Actuator 端点鉴权边界未固定
- 已完成
- 完成于
lpt-be251a468 - 已实施:把暴露清单显式固定为
health,info,并写明「/actuator/**不受SaInterceptor约束,这里是唯一的口子,临时排查请用 local profile 覆盖而不是改这里」。 - 方案取舍:清单给的两个选项里选了「显式固定白名单」,因为集群内没有任何
NetworkPolicy(已核实),「独立端口 + 网络策略」当前没有可依赖的基础设施。 - 涉及仓库:
lpt-be - 依据:线上只读探测确认
/api/actuator/health、/api/actuator/info未登录返回 200,而/api/actuator/env与业务接口返回 401(已注册的 actuator 端点不受SaInterceptor约束)。 - 影响:当前探针正常,但一旦放开 metrics/prometheus 等端点,会连带公开。
- 建议:显式固定暴露白名单,或把管理端点放到独立端口并加网络策略。
- 验收:未鉴权可访问的端点清单与预期完全一致。
安全-03(原 LPT-23)lpt-ai 缺少入站防护(SSRF 与滥用)
- 已完成
- 完成于
lpt-aif091fe6、1c31682,lpt-be251a468、bad7d6b,lpt-infra9160dd1 - 已实施:
- 抓取四层校验(
utils/ssrf-guard.ts):协议白名单 → 端口白名单(默认只允许 80/443,避免被用来探测内网 Redis/MySQL)→ DNS 解析后逐个校验每一个解析结果(防解析到内网与 DNS rebinding)→ 重定向逐跳重新校验(防「首跳合法、次跳内网」);响应体截断到 512 KiB 且只接受网页类型。 覆盖 IPv4 私网/回环/链路本地(含云元数据 169.254.169.254)/CGNAT/组播/保留段,以及 IPv6 回环、ULA、链路本地、组播,并识别 IPv4-mapped 与 NAT64 里内嵌的 IPv4。 - 入站令牌(可选):
LPT_AI_TOKEN设置后/ai/*与/admin都要求携带(headerx-api-token或 querytoken);lpt-be侧由lpt.ai-service.token提供。部署清单用secretKeyRef.optional: true引用lpt-secrets/lpt-ai-token,没设这个 key 也能启动(此时不校验)。 - 限流:
/ai/tasks按来源限流(默认 30 次/分钟,LPT_AI_RATE_LIMIT)。 - 请求体上限:
LPT_AI_BODY_LIMIT_BYTES,默认 256 KiB。
- 抓取四层校验(
- 两条实现取舍(与维护者确认过):
- 令牌默认不启用:维护者明确表示开发阶段不想为额外凭据付出精力。因此实现为「一条环境变量即可收紧」,并保证未启用时启动告警 + Pod 正常启动。
- 不做日志脱敏:
admin/store.ts已按条数限制保留(MAX_ENTRIES=200),而按内容脱敏会削弱/admin面板的排查能力;本项不在验收标准内,留待后续隐私专项。
- 顺带发现:
POST /fetch-title全工作区零调用(lpt-fe走的是lpt-be的/utils/fetch-title,用 Java 侧TitleFetcher)。保留是为满足本条目验收;如需精简可连同抓取工具一并删除,列入 清理-01 候选。 - 验收:
/fetch-title无法访问内网与元数据地址;未授权请求无法提交 AI 任务。✅ 已用单测覆盖内网/回环/元数据/IPv4-mapped/NAT64/端口/协议/域名解析到回环等绕过路径,以及令牌校验的放行与拒绝分支
安全-04(原 LPT-24)生产环境打印全部 SQL
- 已完成
- 完成于
lpt-beaf13bd5 - 涉及仓库:
lpt-be - 依据:
application.yml中mybatis-plus.configuration.log-impl: org.apache.ibatis.logging.stdout.StdOutImpl(注释里保留了Slf4jImpl备选)。 - 影响:生产日志包含全部 SQL 与参数(含学习内容),噪音大且不利于排查。
- 建议:改为
Slf4jImpl并按环境分级,生产默认不打印参数。 - 验收:生产环境不再输出逐条 SQL。
运维-01(原 LPT-25)备份只在集群内同一 PVC
维护者决定:暂不做(2026-10-09)。
- 现状:每日
mysqldump --all-databases写入同集群的mysql-backupPVC,保留 14 天,dev 与 prod 混在同一个 dump 里。- 恢复前提:需要维护者提供异地/对象存储目标(S3/MinIO 兼容存储的端点与凭据,或一台可 SSH 的常开主机及其保留策略)。
- 若重新开工,建议顺序:先把现有备份做可靠(按库分文件、备份后校验非空且可读、失败可见)→ 再做一次真实的恢复演练(当前从未验证过备份可恢复)→ 最后接异地副本。
- 未做的风险已明确:集群级故障即全丢,这一点维护者已知悉并接受。
- 未完成
- 涉及仓库:
lpt-infra - 依据:
mysql-backup-cronjob.yaml每日mysqldump --all-databases写入同一集群的mysql-backupPVC,保留 14 天,且 dev 与 prod 混在同一 dump。 - 影响:集群级故障即全丢;无法按环境恢复。
- 建议:增加异地/对象存储副本,按库分文件,并定期做恢复演练。
- 验收:可在集群外取得可恢复的备份,并完成一次演练记录。
清理-01(原 LPT-26)死代码与死表清理
已确认的决策(2026-10-09,维护者):删代码,两张表先保留并在
lpt-docs记录定位。
- 删除(7 个文件):
TestController及其单测、TestTableService/TestTableServiceImpl/TestTableServiceImplTest/TestTableMapper/TestTableEntity。- 保留并记录:
test_table、review_mind_maps(后者已被review_standard_mind_maps取代,零代码引用)。- 保留表的理由:删表不可逆,且无法连接线上库核实是否还有数据(
review_mind_maps曾支持 xmind 上传解析,可能存有导入过的导图);两张表几乎不占空间,代价只是不够整洁。- 接受的代价:失去「手动触发四种业务异常」的入口。
GlobalExceptionHandlerTest覆盖的是 handler 层逻辑(直接调用,不经 Spring),本条目不再提供端到端手工验证手段。- 现状修正:清单原依据提到「
lpt-fe/src/api/review.ts仍导出/review/mind-map/*」——已核实前端这部分已经清理干净,无需处理。
- 未完成
- 涉及仓库:
lpt-be+lpt-fe - 依据:
TestController(/test/{id})与test_table仍在生产代码中;review_mind_maps表自V20260620_1创建后无任何代码引用也未 drop;lpt-fe/src/api/review.ts仍导出/review/mind-map/*(含 xmind 上传解析)相关调用,而后端已无对应端点。 - ���议:确认无外部调用后删除端点/表/前端死代码;若保留,需在
lpt-docs说明定位。 - 验收:前后端不再存在无实现的接口调用;数据库无孤儿表。
9. 建议推进顺序(按模块)
同一模块内的条目触碰同一批表结构、口径或配置,建议一个模块一次性改完,避免出现双口径并存的中间态。
- 学习会话生命周期:会话-01/02/03 已完成;会话-04 + 会话-05 已完成(收敛方式取「惰性 + 定时并用」,出口取「结束并开始新任务 + 放弃」)。本模块已收口。
- 内容归属与报告:归属-01 + 报告-01 + 标记-01 均已一次改完(碎片表拆分归属、报告结构化、导图待更新标记、检索口径),学习引导的来源标记随之落地。本模块已收口。
- 复习:复习-01 六项结论已落;复习-02 / 复习-03 / 复习-04 / 复习-05 / 复习-06 / 复习-07 均已完成。本模块已收口。
- AI 链路:AI-01 / AI-02 / AI-03 / AI-04 均已完成。本模块已收口。
- 数据与检索 + 导出:数据-01 / 数据-02 / 数据-03 / 导出-01 均已完成。本模块已收口。
- 安全与运维清理:安全-02 / 安全-03 / 安全-04 已完成;安全-01 与运维-01 由维护者决定暂缓(见条目内记录);清理-01 已完成。
- 学习录音(已暂停):模块整体挂起,重启前先定 §12「路线分叉」(依赖 OBS / 自研原生)。
10. 已确认的设计变更(待实施)
归属-01(原 DC-01)内容归属与待归类
已确认的决策(2026-10-09,维护者)
- 报告里的「按归属分组的碎片」采用实时聚合,不做快照。
- 报告表只存三段文本(会话摘要、预期达成判断、自由总结);「按归属分组的碎片」在查看时按碎片的当前内容归属聚合,不落库。展示顺序按
learning-report.md:会话摘要 → 预期达成判断 → 按归属分组的碎片 → 自由总结(分组排在自由总结之前)。- 理由:与标准导图的取材口径一致(都按当前归属),避免出现「报告说属于甲、导图放在乙」的双口径——而这正是本条目要消灭的东西;同时表结构最简单,不需要碎片改归属时的同步逻辑。
- 代价:删除碎片会让历史报告的分组段变短。这与决策 1「碎片可删」是同一个取舍,已接受。
- 推论:「旁支碎片」不需要额外字段——它就是「归属不等于本会话所属任务」的那部分碎片,同样是派生结果。
- 不做老数据兼容(维护者):现有报告的
content列直接改名为free_summary,老数据顺势落进「自由总结」,新代码不读旧语义、不维护双渲染路径。摘要与达成判断两段对老报告留空(本来就不存在)。
- 维护者的后续计划:之后自行把老数据的碎片与导图迁移进新系统,报告不在迁移范围内。
- 迁移进来的历史碎片必须带上原会话:记录上下文保持
NOT NULL的硬约束,不做放宽。
- 维护者准备的迁移数据需按「任务 → 会话 → 碎片」顺序提供:老任务(归属目标)、老会话(
session_num/task_num/start_time)、老碎片(正文 + 所属会话)。- 代价:迁移脚本比「只迁碎片」麻烦一层,换来的是老碎片仍能回答「当时在学什么的时候记的」,且时间统计能接回时间轴。
- 已排除的替代方案:造一个「历史导入」虚拟会话兜底(会让一条虚拟会话被当成真实学习、需在统计里特判);放宽
session_num为可空(会放弃 lpt-docs 的「记录上下文不可为空」约束)。- 待归类内容两处都要出现:复习总览里一个独立区块(回答「还欠多少」),复习 Feed 卡片上加「待归类」标记并就地归类(归类到已有任务,或升格为新任务)。这是个可选项,不做成待办清单。
- 理由:
lpt-docs要求「待归类内容必须被看见,否则归类无从发生」;而复习的日常入口常常是 Feed 而不是总览,两处缺一都会漏。- 已排除:只放总览(归类时机与注意到的时机错开);只在 Feed 打标(永远不知道积压多少);独立「待归类」页面(会变成待办清单,且与总览职责重叠)。
归属-01 已完成(2026-10-09)。 完成于
lpt-bec74f73a(+lpt-fe18a2580、lpt-docs8c55b86)。归属-01 决策完毕(2026-10-09),可以开工。 实现要点汇总:碎片表拆
context_type+context_num(不可空、不可变)与内容归属字段(可空、可变、单一);报告表content→free_summary并新增session_summary/expectation_verdict,分组段实时聚合不落库;删任务时碎片归属置空进待归类、其余软删;待归类在总览独立区块与 Feed 卡片两个入口呈现并支持就地归类/升格为任务。
- 文档:
lpt-docs/docs/concepts/knowledge-ownership.md(设计已确认,见文末结论)、lpt-docs/docs/concepts/learning-report.md(结构化报告形态)、lpt-docs/docs/design/system-structure.md(设计总纲) - 背景:学习 A 内容时顺手记下的旁支知识(例:学 AI 时记下“1B = one billion”)目前会被算作 A 的知识,进 A 的导图与回忆对比基准。根因是把「记录地点」当成了「内容归属」。
- 变更内容:拆分记录上下文(不可变、不可为空;取值是学习会话或复习行为)与内容归属(可变、单一、可为空);时间按行为统计(学习会话→学习时间,复习行为→复习耗时)、内容按归属聚合;新增待归类视图;归类动作挂在复习 Feed 里;AI 只给归属建议;待归类内容可升格为学习任务;学习报告改为结构化(会话摘要、预期达成判断、按归属分组的碎片、自由总结,旁支碎片留在本次报告单独标注)。
- 影响范围:碎片表结构、学习报告结构(字段、AI 草稿生成与降级拼接、前端展示、历史自由文本报告兼容)、标准导图取材、按任务的复习与检索(
StandardMindMapServiceImpl.doGenerate()、ReviewServiceImpl.getTaskReview()、getTaskFragments()/getTaskReports())。学习会话的时间与状态机不受影响。 - 前置条件:已满足—— 2026-09-19 维护者确认:碎片不可脱离学习会话;报告改为结构化并保留自由总结;归属保持单一,跨领域关联由标签承担。结论原文见
knowledge-ownership.md「已确认的结论」。 - 实施要求:一次替换干净,禁止出现“导图按归属、检索仍按会话”的双口径并存;归属变更后需标记导图待更新。
11. 待确认的设计缺口(确认前不要实施)
复习-01(原 DC-02)复习回路补全
已确认的决策(2026-10-09,维护者)
以下 4 项无需决策——文档与实现已经收敛到同一口径,直接按此执行:
项 结论 文档依据 实现依据 1 Feed 不含学习报告 review-feed.md:「Feed 的条目单位是知识碎片。学习报告不以条目形式出现在 Feed 中」getReviewFeed/getSmartFeed均调用mergeAndConvert(List.of(), fragments),报告列表恒为空3 覆盖率口径 = 最近一次(不做加权) recall-review.md:「为复习排序提供任务级掌握度:最近一条记录的覆盖率」;review-loop.md同ReviewServiceImpl.latestRecallRatioByTask()取created_time降序的第一条4 待归类内容两处都出现(总览独立区块 + Feed 混排打标、就地归类) review-loop.md:「待归类内容在复习总览中可见,在 Feed 中可归类」待实现;口径见归属-01 决策 4 5 遗漏项 = 本次对比的快照,不做跨次累计 recall-review.md:「遗漏项是本次对比的快照,不是跨次累计的待办集合」对比结果写在单条回忆记录的 compare_result里,不跨记录聚合需要决策的第 2 项(已定):
- Feed 反馈动作:提供「已掌握」与「稍后再看」两个轻量动作,另外把「上次复习时间」作为第三个权重信号(原只有时间衰减与任务级覆盖率两个)。
- 两个动作只调整出现概率,不产生状态展示、不计总数、不做待复习列表:
已掌握降低概率但不归零(保留文档要求的随机性——「每条内容都有机会出现」),稍后再看提高概率。- 展开查看 / 进入回忆对比会刷新「上次复习时间」,本身不产生额外数据。
- 不落进标记表:文档明确「标记不是状态」,因此反馈状态落在碎片自身的字段上。
- 已排除:只做「稍后再看」(无法低成本表达「这条我熟」,重复出现只能等时间衰减);只做「已掌握」(缺少正向「再巩固」入口,且回忆对比是任务级的);不做反馈(重复出现的痛点原样保留)。
需要决策的第 6 项(已定):
- 排序信号强度用三档预设,不做精确权重。 档次为「时间为主(默认)/均衡/掌握度为主」,前端可切换。
- 现状落差:文档写「信号强度可配置」,但实现里系数写死(
0.3 + ageDays/90*0.7与1.0 - ratio*0.7),本项即为填补这个落差。- 理由:现有公式是「时间因子 × 掌握度因子」两个乘数而非加权和,给百分比是假精度;两个信号本身抽象,调完也未必知道是哪一项起作用;三档已覆盖真实意图(「怎么老给我看旧内容」与「怎么总给我看熟的」)。
- 已排除:与任务优先级一致的前端百分比权重弹窗(假精度 + 需重构公式 + 为低频设置多写一套持久化与校验);只做后端配置项(等于不可用,不会为看 Feed 效果去改 yaml 重启);写死并改文档(放弃一个已经留好的口子)。
复习-01 决策完毕(2026-10-09)。 连带解锁:复习-02(反馈动作)、复习-04(覆盖率查询依赖口径)、复习-05(Feed 摘要口径)、复习-06(学习引导,前置 AI-02/03 与标记-01 均已满足)。
- 文档:
- 文档:
lpt-docs/docs/design/review-loop.md(立场、内容来源、两个层级、排序、归类、反馈、AI 边界)、lpt-docs/docs/concepts/review-overview.md(新增)、recall-review.md(回忆记录、覆盖率、复习起点、遗漏项)、review-feed.md、lpt-docs/docs/design/principles.md、module-boundaries.md。 - 背景:复习此前只有零散描述(Feed、导图、回忆对比各自成文),缺少系统级口径:复习内容的完整来源、任务级与条目级两层入口、覆盖率与掌握度的定义、遗漏项的语义、反馈动作、归类动作落点、AI 边界都未定;文档写的是“Feed 展示碎片和学习报告”,实现只返回碎片。
- 本次补全(已按以下取向写入文档):复习只做“低阻力反复出现 + 主动提取”,不做到期调度、打卡、评分;Feed 条目单位是碎片,报告从任务记录进入;覆盖率按任务聚合成掌握度,作为排序信号之一;遗漏项是每次对比的快照,不做跨次累计待办;归类动作落在复习里;AI 只做语义匹配与归属建议。
- 待确认:
- Feed 是否包含学习报告(文档取向:不含)。
- 反馈动作形态:只读 /“已掌握 + 稍后再看”/ 仅“稍后再看”(关联 复习-02)。
- 覆盖率口径:最近一次 / 最近若干次加权。
- 待归类内容的呈现:总览独立分类 / Feed 混排打标;归类是否需在卡片上一键完成。
- 遗漏项语义:快照 + 回看原文 / 跨次累计集合。
- 排序信号是否对用户可配置(掌握度与时间效应的强度)。
- 关联实现:复习-02(反馈动作)、复习-03(Feed 随机取样)、复习-04(覆盖率查询)、复习-05(Feed 摘要)。
标记-01 统一标记存储
已确认的决策(2026-10-09,维护者)
- 可挂对象:知识碎片 + 学习任务。对象用「类型 + 标识」引用(
object_type∈ {FRAGMENT,TASK})。
- 报告不挂:它是会话的派生结果,且「按归属分组的碎片」本身就是一个分组维度,再加标记会出现两套「分组」语义。
- 会话不挂:时间轴对象,状态/是否收敛这类流程性信息按文档要求留在主体上。
- 表格是通用的,以后要加对象类型只需加枚举值与校验。
- 标记名受控方式:两类彻底分开。
- 系统标记:标记名与值来自代码里的固定词表(枚举),由系统写入,用户只读、不可删改。理由:「找出所有来自 X 的碎片」这类检索的可靠性依赖于它没被改过。
- 用户标签:标记名自由输入,可增删改。
- 同一对象上两类共存、互不覆盖,用「种类」字段区分展示(系统标记灰底只读,标签可删)。
- 已排除:允许用户修改系统标记(系统检索不可靠);标签也走预置词表(与「用户自由建立的分类」冲突);不区分两类(复习-06 的「来源标记」失去落点)。
- 标记值的存法:名副其实。系统标记用「标记名 + 标记值」成对存储(
来源 = 学习引导);用户标签只有标记名,marker_value留空(标签名本身就是全部信息,不做「英语 = 英语」这种冗余)。
- 已排除:让标签也带值(输入成本上升、语义与「内容归属」及碎片正文混淆、检索要区分「有名」与「名+值都匹配」);扁平命名不带值(丢失「按来源聚合」的维度,且与文档定义的「标记名与标记值」不一致);类型化值 BOOLEAN/ENUM/TEXT(目前只有两个真实需求,属于过度设计,且三列互斥存储会让读写校验变重)。
- 检索入口:支持单一标签筛选,点标签即筛选(碎片列表 / 复习 Feed / 任务列表)。不做多标签 AND/OR 组合、不做跨对象统一搜索页。
- 关键理由:
knowledge-ownership.md规定标签「只影响检索,不影响聚合与统计」,且标记不能表达第二归属、不能参与流程判断——检索是标记唯一的作用,不做检索入口等于让标签失去意义。- 已排除:只展示不检索(标签变成纯装饰);多标签组合 + 跨对象搜索(要查询构建器与动态 SQL,而标签体系规模未知、组合筛选未必用得上);独立标记页(与列表内筛选职责重叠)。
- 治理与可见性:全可见 + 标签可改名 + 可删除。
- 系统标记对用户可见(灰底只读标签)。理由:学习引导产出的碎片默认归属被引导概念所属任务,用户看到「来源=学习引导」才能理解它为何归在那里;且复习-06 的验收就是「带来源标记」,隐藏它等于它不存在。
- 用户标签可重命名(一次更新影响所有带该标签的对象)、可删除(从所有对象移除)。不做「废弃而非删除」那套状态机。
- 改名安全性依据:文档明确「标记不参与聚合口径,也不改变内容归属」,因此批量改名不存在数据口径风险——这正是它与「改内容归属」的关键区别。
- 已排除:系统标记对用户隐藏(用户无法解释学习引导碎片为何归在那里、调试时看不到系统写了什么);只能删不能改名(改名退化为「删旧建新 + 逐条重打」,而批量改名本身无数据风险);可废弃(多一套状态转换与检索判断,而标签不参与聚合、保留历史标记的收益很小)。
标记-01 已完成(2026-10-09)。 完成于
lpt-bec6258fa(+lpt-fe232fdb8)。标记-01 决策完毕(2026-10-09),可以开工。 实现要点:一张通用标记表(
object_type∈ {FRAGMENT,TASK} +object_num+kind∈ {SYSTEM,USER} +marker_name+ 可空marker_value+ 建立者/时间);系统标记走代码枚举词表且用户只读;索引两条(按标记找对象、按对象列标记);前端提供点标签即筛选的单一筛选入口。
- 文档:
lpt-docs/docs/concepts/marker.md(新增,含 5 个待决问题) - 背景:来源标记、用户标签等弱信息分散在各功能里考虑,缺少统一存放位置;每新增一种标记就要改一次功能表结构。
- 已定:标记统一存放,至少包含对象类型与标识、标记名与值、种类(系统标记 / 用户标签)、建立者与时间;标记不是状态——会话状态、报告可否修订、导图是否待更新这类流程判断留在主体上;学习引导产出的碎片带「来自学习引导」系统标记。
- 待确认:
- 标记可挂在哪些对象上(碎片 / 报告 / 任务 / 会话)。
- 标记名的受控方式(系统标记固定词表、用户标签自由输入;是否允许在系统标记上叠加)。
- 标记值的类型(布尔开关 / 枚举 / 自由文本)。
- 是否需要按标记检索的入口,以及需要哪些索引。
- 标记名的治理(重命名、废弃)与对用户的可见性。
- 关联实现:复习-06(来源标记)、归属-01(用户标签)。
12. 新增能力:学习录音(已暂停)
模块状态:已暂停(2026‑10‑08)。录音-01 的实现已完成并实测通过,但「依赖 OBS」与「自研原生采集」两条路线的取舍未定,其余条目已挂起。重启前先读完本节末尾的「路线分叉」。
目标:学习会话期间采集设备上全部播放声音(含蓝牙耳机等全部输出设备),转写为文本,作为学习报告与知识碎片的上下文原料。概念与边界见
lpt-docs的docs/concepts/study-recording.md。
采集架构(已确认):采集由运行在用户本机的伴随程序负责,音频直传后端;浏览器不采集音频、不传输音频,只发起与展示。
采集后端(待重评):当前实现走 OBS,但 录音-决策03 已回退为待重评,见下方「路线分叉」。
代码位置:lpt-companion(本地独立仓库,已加入 meta 的 .gitignore,远端待建)。
| 分支 | 内容 |
|---|---|
main |
仓库脚手架 + AGENTS.md(含待定方案、约束与实测坑位总结) |
feature/study-recording |
第一版实现(OBS 后端 + 抽音轨),HEAD 8d0969d |
已实现并实测的部分:obs-websocket 协议客户端与认证、独立 profile / 场景集合 / 场景 / 系统音频源的幂等准备、平台音频源映射、录制控制、用 ffmpeg 抽音轨并删中间视频,共 85 个单测。
平台能力核对(2026-10-07 本机实测 + 源码核对):
| 平台 | 系统音频来源 | 证据 |
|---|---|---|
| Windows | WASAPI loopback | OBS 桌面音频标准能力(本机无法验证) |
| Linux | 默认 sink 的 monitor | 本机实测:pw-record --target=<sink>.monitor 采集成功(峰值 32768 / RMS 27959);浏览器经 module-remap-source 走 getUserMedia 亦成功,且能录到非浏览器客户端的播放声 |
| macOS 13+ | ScreenCaptureKit | OBS 源码 plugins/mac-capture/mac-sck-audio-capture.m;plugin-main.c 中 coreaudio_output_capture_info 已标 OBS_SOURCE_DEPRECATED,改用 sck_audio_capture_info(本机无法验证) |
已排除的路线:
- 浏览器直接采集系统声:仅 Windows/ChromeOS 在共享整个屏幕时支持;Chromium 明确排除 monitor 设备。
- 把 monitor 包装成普通输入源再由浏览器采集:本机验证可行(
module-remap-source),但需要常驻 watcher 跟随默认输出设备,且网页关闭即中断,已被伴随程序方案取代。 - 公网页面直连本机端口做控制:Chrome 142+ 起受 Local Network Access 权限约束(实测见 录音-决策01)。
- 用配置让 OBS 只录音频:
RecFormat2=ogg会让容器变成 ogg,但 OBS 仍用libfdk_aac写入,容器与编码器不匹配 → 产出 0 字节文件;RecAudioEncoder设成aac/opus/ffmpeg_opus均未改变实际编码器。
路线分叉(重启本模块前必须先定)
| 依赖 OBS(当前实现) | 自研原生采集 | |
|---|---|---|
| 原理 | 经 obs-websocket 驱动 OBS 录出「视频+音频」,再用 ffmpeg 抽出音轨并丢弃视频 | 直接读操作系统混音端点,写出纯音频 |
| 实测状态 | Linux ✅ 已验证;Win / macOS 未验证 | Linux ✅ 已验证(pw-record,20 行);Win / macOS 未实现 |
| 额外依赖 | OBS + ffmpeg | 无 |
| 体积 | 35 MB(发行版包)~2.5 GB(flatpak) | 几 MB |
| 中间产物 | 会写出较大的视频文件再删(已压到 112 MB/小时) | 无 |
| 主要成本 | 三平台配置差异与 OBS 版本漂移 | 需自写三套原生采集(macOS SCK 最难) |
伴随程序必须运行在声音实际播放的那台机器上,所以「多端」的含义是:每台用于学习的设备都要装一份并各自配对;换了播放设备(例如改用手机听)该设备就必须有自己的采集能力。
录音-01 采集后端接口与 OBS 后端
- 已实现并实测通过(模块已暂停,代码在分支)
- 涉及仓库:
lpt-companion,分支feature/study-recording,HEAD8d0969d - 完成于
feature/study-recording8d0969d;main仅保留脚手架与说明 - 依据:OBS 32.2.2 提供 Windows x64/arm64、macOS Apple/Intel、Ubuntu 24.04/26.04 发布;obs-websocket 5.x 自 OBS 28 内置。
- 已实测验证(Linux / PipeWire / OBS 32.2.2 / obs-websocket 5.7.4):
- 端到端可采到系统混音:OBS 日志
pulse-input: Started recording from 'alsa_output...analog-stereo.monitor' (default),与非默认输出设备无关。 - 采到的是其他应用的声音:用
pw-cat(非浏览器)播放 440 Hz,录出的音轨 FFT 主频精确为 440 Hz,峰值 9873。 - 配置隔离成功:独立
CreateProfile/CreateSceneCollection/CreateScene/CreateInput,不影响用户已有配置。 - 采集路径:OBS 录 Simple+mkv(320×240@5fps、200 kbps),抽出 Opus/Ogg 后删视频。中间文件约 112 MB/小时,最终音频约 18 MB/小时。
- 端到端可采到系统混音:OBS 日志
- 实现要点(踩坑记录均已写入
lpt-companion/AGENTS.md):--profile/--collection首次运行会被忽略,改用 obs-websocket 的CreateProfile;空场景集合必须先CreateScene;输出模式/容器/画布变更必须重启 OBS(prepare()用restartRequired告知);以 kill 结束 OBS 会留下 sentinel 导致卡在安全模式对话框;flatpak 版配置路径与启动方式不同。 - OBS 侧的已知限制:无法通过配置让 OBS 只录音频(
RecFormat2=ogg会因编码器不匹配产出 0 字节文件),故改走「录标准容器 + 用 ffmpeg 抽音轨」。 - 新增外部依赖:抽音轨需要
ffmpeg(配置项media.ffmpegPath);分发时需考虑自带或引导安装。 - 验收:在未手动操作 OBS 界面的前提下,能从零建立独立配置并录出可播放的音频文件;用户已有的 OBS 配置不被改动。✅ 已验证
录音-02 控制通道与会话绑定
- 未完成
- 涉及仓库:
lpt-be+ 伴随程序 - 依据:Chrome 142+ 的 Local Network Access 权限使「网页直连本机端口」需要用户授权一次,且网页关闭会中断控制(实测见 录音-决策01)。
- 建议(待确认):轮询式控制通道——网页只写
lpt-be标记开始/结束,伴随程序带设备 token 轮询lpt-be取任务,音频由伴随程序直传lpt-be。备选:直连127.0.0.1换取即时起停,代价是 LNA 授权与网页生命周期耦合。 - 验收:网页发起后伴随程序在轮询周期内开始录音;关闭网页不影响录音继续与上传;未配对的设备无法拉取任务。
录音-03 音频落盘与对象存储
- 未完成
- 涉及仓库:
lpt-be+lpt-infra - 依据:
lpt-be现有 45 个端点全为 JSON,无任何文件上传能力(MultipartFile零命中);lpt-infra仅有 mysql 10Gi 与 lpt-logs 5Gi PVC,无对象存储。实测码率:Opus 32 kbps ≈ 14.8 MB/小时(未限码率时 58 MB/小时)。 - 建议:录音元数据入业务库(会话、起止、时长、对象键、状态),音频本体入 S3/MinIO 兼容对象存储;分片上传并支持断点续传;长期保留。与 运维-01(备份异地)同源,建议一并规划。
- 验收:一段会话录音可通过元数据定位并取回;上传中断后可续传;容量按 15 MB/小时可控增长。
录音-04 转写链路(provider 可配置)
- 未完成
- 涉及仓库:
lpt-ai+lpt-be - 依据:
lpt-ai目前只有 SiliconFlow OpenAI 兼容 chat(Qwen/Qwen2.5-32B-Instruct),无任何 ASR 能力;AiServiceClient为同步轮询(见 AI-01 / AI-02)。 - 建议:provider 在配置中切换
online(SiliconFlow 转写接口)/local(whisper.cpp)/off(只存音频),默认off。 - 依赖:AI-02 / AI-03。长音频转写若走同步链路,等于复制 AI-01 / AI-02 的问题。
- 验收:切换配置即可改变转写来源;
off时全链路不因缺少转写而失败。
录音-05 录制可见性与隐私边界
- 未完成
- 涉及仓库:
lpt-companion+lpt-fe(或油猴脚本) +lpt-docs - 依据:录音采集的是系统混音,可能包含他人语音(线上会议、通话);采集范围由系统决定,用户无法逐条挑选;OBS 自身窗口可能被最小化到托盘,不足以充当「正在录音」的指示。
- 建议:除了网页侧展示状态,伴随程序还要有常驻的本地可见指示,并提供一键停止;开始前明确说明采集范围与长期保留策略;未配对或未授权时不得开始录音。
- 待确认:本地指示形态(托盘图标变化 / 常驻悬浮提示);他人语音的产品口径;会话暂停期间是否继续录音。
- 验收:录制中存在不易忽略的可见指示;任意时刻可一键停止;停止后不再产生新分片。
录音-06 浏览器侧接入
- 未完成
- 涉及仓库:
lpt-fe(或独立油猴脚本) - 依据:浏览器侧只需发起、结束与展示状态,不接触音频。
- 建议:优先直接接入
lpt-fe(类型安全、随应用版本发布);若仍使用油猴脚本,脚本只调用lpt-be接口,不持有音频。 - 待确认:油猴脚本还是直接进
lpt-fe。 - 验收:学习会话中可一键开始/结束录音,并看到状态与转写结果。
13. 学习闭环重构(新需求,2026‑10‑10)
状态:口径已定(2026‑10‑10 维护者确认),可以实施。 本节把维护者 2026‑10‑10 提出的产品方向整理成可执行条目。概念级设计(为什么这样学、概念如何组织)仍归
lpt-docs,本节只放待办、依据与验收标准;本轮决策已同步写入lpt-docs(标记、标准思维导图、回忆对比、复习 Feed、复习回路、模块边界)。共同背景(为什么做):学习过程中「定义」这类内容其实不多,残片产生量有限、且往往集中出现;真正消耗时间的是「如何正确识别这些概念」与「概念的实际应用」(大部分发生在做题过程中)。现有实现把残片级操作铺在首页,聚合维度又只有「任务」一个,撑不起「按概念 / 按应用场景」的学习闭环。
现状坐标(接手时先看这里)
- 首页 =
/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-fe33b1c8a - 涉及仓库:
lpt-fe(components/Welcome.vue、components/ReviewDetail.vue、components/Review.vue) - 依据:
Welcome.vue的残片卡片当前直接挂了MarkerChips(Welcome.vue:497,打标签/筛选)与三个动作按钮「已掌握 / 稍后再看 / 学习引导」(Welcome.vue:504-525);另有color-legend图例(Welcome.vue:465,文案「学习残片」+ 一段 tooltip 解释)。首页因此同时承担了「暴露内容」与「执行操作」两件事。 - 建议:
- 首页滚动条只保留只读展示:残片正文、来源任务、时间等;移除打标签、反馈(已掌握/稍后再看)、学习引导等写操作控件。
- 移除
color-legend图例及其el-tooltip说明(「学习碎片」图例即此处)。 - 上述操作改在复习模块完成。落点需先定:复习 Feed 就地操作,还是进
ReviewDetail.vue详情后操作。
- 已定口径(2026‑10‑10):
- 首页保留「点击残片跳到复习详情」的纯导航;打标签、反馈(已掌握/稍后再看)、学习引导集中到
ReviewDetail.vue详情页,不为残片新增独立的操作面板。 - 归类仍留在 Feed 卡片(与 §10 归属-01 一致:归类只是一次选择,复习是成本最低的时机),本次不迁移。
- 首页保留「点击残片跳到复习详情」的纯导航;打标签、反馈(已掌握/稍后再看)、学习引导集中到
- 已实施:
Welcome.vue只保留只读展示与导航(删掉MarkerChips、三个动作按钮、color-legend图例与标记筛选条,回想卡片新增「查看详情」入口),归类仍留在 Feed 卡片;ReviewDetail.vue新增碎片操作区(MarkerChips打标签/删标签、已掌握/稍后再看、学习引导);点碎片标签跳/review?markerName=xxx并在Review.vue挂载时应用该筛选。 - 验收:首页不出现任何打标签/反馈/引导控件与图例;同样的操作在复习模块内可完成。✅
Welcome.spec.ts改为只读断言(控件/图例不存在、getMarkersBatch不被调用、可进详情),新增ReviewDetail.spec.ts(4 例:标记增删、标签跳转筛选、反馈回显、学习引导)与Review.spec.ts(2 例:带/不带markerName);npm run type-check与全量npm test(39 文件 / 245 用例)全绿
闭环-02 任务名自动成为标签(把「任务」降级成一种标签)
- 未完成
- 涉及仓库:
lpt-be(残片产生路径)+lpt-fe(标签展示与修改) - 依据:任务名目前只是
tasks.task_name,没进标签体系;而markers已支持自由标签(MarkerKindEnum的 TAG)与系统标记两套语义(见 §5 标记-01)。回忆复习里导图取材已改为「归属该任务的残片」(§5 归属-01),聚合维度实际被任务锁死。 - 建议:残片落库时自动打一条「任务名标签」,用户可改可删;实现上优先复用
markers的自由标签,不再造第二套标签存储。 - 已定口径(2026‑10‑10):
- 任务名标签走自由标签(
MarkerKindEnum的 TAG),可改名、可删除;不给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(用量统计),没有「提前新建/批量整理」的入口。 - 建议:
- 标签管理支持提前增删改:新建空标签、改名、删除、看用量。
- 打标签改为可搜索选择:输入即过滤已有标签(含自动的任务名标签),同时允许输入新标签。
- 「提前存在的标签」目前无处可放(
markers的每一行都挂在一个对象上)。这是本条的实现前提,见下。
- 已定口径(2026‑10‑10):
- 标签字典新增
user_tags表,不为「无对象标签」在markers里造行。 - 字典只做候选:改名与删除不影响任何对象上已打好的标记。
- 去重口径:名字按 trim + 大小写不敏感判重,展示保留用户输入的原样。
- 标签字典新增
- 验收:可在标签管理里提前建好标签;打标签时能搜到并选中;删除字典标签不破坏已有标记。
闭环-04 按标签做回忆复习并生成导图
- 未完成
- 涉及仓库:
lpt-be(导图存储与取材口径、回忆对比入口)+lpt-fe(Review.vue/ReviewRecall.vue)+lpt-ai(提示词入参) - 依据:回忆复习目前是任务维度——
Review.vue任务卡片主操作进/review/recall/:taskNum(ReviewRecall.vue),基础导图也按taskNum存取。想要「按概念复习」,现在没有任何入口。 - 建议:复习模块增加「按标签复习」:选一个或多个标签 → 聚合带这些标签的残片 → 生成/更新一张导图 → 走既有回忆对比链路。
- 已定口径(2026‑10‑10):
- 与按任务复习并存,不替换既有
/review/recall/:taskNum。 - 标签导图新增独立表(以规范化标签集合为键),不改
review_standard_mind_maps的 task_num 唯一键。 - 多标签由用户在界面上选并集/交集(默认并集);缓存键把标签集合(排序后)与模式一起纳入。
- 重算手动触发:素材变化只置「待更新」,与报告-01 的导图重建口径一致。
- 按标签复习写回忆记录:
review_recall_records.task_num改为可空,并加范围列(任务/标签 + 标签集合),复习耗时与覆盖率统计一并可用。
- 与按任务复习并存,不替换既有
- 验收:选定标签后可生成导图并完成一次回忆对比,记录落库可追溯;不影响既有按任务复习。
闭环-05 任务执行页展示并编辑该任务的基础导图
- 已完成
- 完成于
lpt-fedfa9b1d - 涉及仓库:
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),让「应用知识时发现定义有缺陷」能立刻改导图。 - 已定口径(2026‑10‑10):
- 编辑粒度与回忆页一致:复用
MindMapViewer的全量编辑(Tab 加子节点 / Enter 加同级 / 双击改文字 / 拖拽 / 右键菜单),保存走toOutline()+ 整体PUT。 - 并发覆盖:保持整体 PUT 覆盖,暂不加乐观锁(两个入口同时编辑会「后写覆盖先写」,风险已知悉;需要时另开条目补版本校验)。
- 编辑粒度与回忆页一致:复用
- 已实施:
StartTask.vue新增「基础导图」卡片,复用getStandardMindMap/updateStandardMindMap与MindMapViewer;任务加载时并行拉取导图(失败不阻塞学习主流程),无导图时以「新建导图」入口给一个以任务名命名的根节点,保存即新建;needsUpdate提示与复习页同义(重建仍只在复习页手动触发)。 - 验收:任务执行页能看到当前任务的基础导图;改动后能在复习页看到同一份(同一份数据,两处共用 PUT);编辑冲突按已定口径为「后写覆盖」。✅ 单测覆盖「拉取后渲成树 + 编辑后整体 PUT 保存」「无导图时以任务名作根节点新建」;
npm run type-check与全量npm test(37 文件 / 241 用例)全绿
闭环-06 记录应用过程中犯的错误(本次只出设计)
- 未完成(已定:本次只出设计,不动代码)
- 涉及仓库:设计落
lpt-docs(概念文档error-record.md);实现阶段才碰lpt-be+lpt-fe - 依据:维护者观察——学习时间主要花在「识别概念」与「实际应用(做题)」上,而现在的残片体系只适合记录「刚学到的内容」,没有地方记录「用错了 / 做错了」。这类信息才是查缺补漏的直接线索,且天然发生在做题时(不在学习页面)。
- 已定设计(2026‑10‑10,维护者确认):详见
lpt-docs/docs/concepts/error-record.md。要点:新增独立实体(不复用残片 + 系统标记);概念/导图节点关联可选;入口允许从题目直接记录;复习方式是单独的错误回看列表(按概念/标签聚合),不进现有 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/。 - 线上只读探测(仅 GET,未做任何写操作):
GET https://lpt.cat-shark.xyz/api/actuator/health→ 200GET https://lpt.cat-shark.xyz/api/actuator/info→ 200GET https://lpt.cat-shark.xyz/api/actuator/env→ 401GET https://lpt.cat-shark.xyz/api/review/feed(未登录)→ 401
- 结构性核对命令示例:
rg -n "@Scheduled" lpt-be/src、rg -n "ORDER BY RAND" lpt-be/src、rg -n "unique" lpt-be/src/main/resources/db/migration。