Files
lpt-meta/OPTIMIZATION_BACKLOG.md
T

605 lines
58 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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. 协作约定
- 完成一项后:勾选对应条目并追加一行「完成于 <仓库> <commit>」;若条目语义已被改动,直接重写条目,不要追加开发日志。
- 涉及概念/设计语义的改动(如会话生命周期、有效时间定义):必须同步更新 `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 内容归属与待归类 | 待实施 | 设计已确认 | 实现级取舍:碎片表如何承载归属、报告字段拆分、归类交互落点 |
| | 报告-01 报告与碎片不可修订 | P1 | 待设计 | 与归属-01 同批改报告结构;修订与删除的边界(软删除、历史报告标记) |
| 标记与元信息 | 标记-01 统一标记存储 | P1 | 待决策 | 可挂对象;标记名受控方式;标记值类型;按标记检索;标记名治理与可见性 |
| 复习 | 复习-01 复习回路补全 | 待确认 | 待决策(6 项) | Feed 是否含报告;反馈动作形态;覆盖率口径;待归类呈现;遗漏项语义;排序可配置性 |
| | 复习-02 Feed 只读无反馈动作 | P1 | 依赖复习-01 | 反馈动作形态(复习-01 第 2 项) |
| | 复习-03 Feed 随机取样 | P3 | 已完成 | — |
| | 复习-04 覆盖率查询拉全量 | P3 | 依赖复习-01 | 覆盖率口径(复习-01 第 3 项) |
| | 复习-05 Feed 返回全文 | P3 | 依赖复习-01 | 条目单位与摘要口径(复习-01 第 1 项) |
| | 复习-06 学习引导 | P1 | 已确认待实施 | 依赖 AI-02 / AI-03,以及标记-01 的存储设计 |
| | 复习-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 | 待决策 | 删除 / 保留并在 `lpt-docs` 说明定位 |
| 学习录音 | 录音-01 采集后端接口与 OBS 后端 | P1 | 已实现·已暂停 | 先定采集方案:OBS / 自研原生 |
| | 录音-02 控制通道与会话绑定 | P1 | 已暂停 | 轮询 lpt-be / 直连本机端口(建议轮询) |
| | 录音-03 音频落盘与对象存储 | P1 | 已暂停 | 对象存储选型(MinIO / 云对象存储) |
| | 录音-04 转写链路(provider 可配置) | P2 | 已暂停 | AI-02 / AI-03 |
| | 录音-05 录制可见性与隐私边界 | P1 | 已暂停 | 指示形态、他人语音口径 |
| | 录音-06 浏览器侧接入 | P1 | 已暂停 | 油猴脚本 / 直接进 lpt-fe |
> **学习录音模块已整体暂停**(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)遗忘检测只在「重新进入学习页面」这一条路径上执行
- [x] 已完成
- **完成于** `lpt-be` `d8c8b76`
- **涉及仓库**:`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 分钟」
- [x] 已完成
- **完成于** `lpt-be` `d8c8b76`
- **涉及仓库**:`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)结束会话不幂等,会产生重复学习报告
- [x] 已完成
- **完成于** `lpt-be` `d8c8b76`
- **涉及仓库**:`lpt-be`
- **依据**:`StudySessionsEntity.endedStudySession()` 在 `state = ENDED` 时只 `log.warn` 并原样返回;`StudySessionsServiceImpl.endedStudySession()` 随后无条件 `studyReportsMapper.insert(...)`。
- **影响**:重复点击、网络重试即可写入多条报告 → 复习 Feed 重复项、标准导图重复节点、统计重复计数。
- **建议**:`state != ENDED` 才允许写报告,否则幂等返回;接口层可加幂等键。
- **验收**:对同一 `sessionNum` 连续调用两次结束接口,第二次不新增报告(断言报告条数)。
### 会话-04(原 LPT-05)缺少服务端兜底:悬挂会话与超长会话无人收敛
- [x] 已完成
- **完成于** `lpt-be` `db55218`
- **涉及仓库**:`lpt-be`
- **已实施**:
1. 硬兜底阈值 2 小时:进行中且最后一段超过该时长时强制收敛为暂停,按遗忘规则(会话-决策02)截断到 `last_start_time + 25 分钟`,并落 `auto_converged` 标记供前端提示「疑似忘记结束」。
2. 收敛方式采用**并用**:惰性收敛挂在「活跃会话」与「任务未结束会话」两个读取入口;定时扫描(默认 10 分钟)兜底,保证用户不回来时统计也会收敛、悬挂会话不再阻塞新任务。
3. 四类阈值(25 分钟番茄钟、50 分钟遗忘判定、2 小时硬兜底、10 分钟有效时间下限)统一收到 `lpt.study-time.*` 配置,实体入口由统一的时间口径对象承载;非法组合(兜底阈值小于遗忘阈值等)在启动时直接失败。
- **实现约束**:收敛写入一律使用「状态仍为 ONGOING」的条件更新,惰性收敛与定时扫描并发时只结算一次;定时扫描跨租户扫描(系统级后台任务,无登录态),但不影响读取路径的租户隔离。
- **测试环境**:定时任务用 `lpt.study-time.scan-enabled: false` 在测试配置里关闭,避免调度任务与用例自造的悬挂会话互相干扰(落库集成测试直接调用扫描方法)。
- **验收**:制造一个 3 小时前的 ONGOING 会话,在不访问该任务页面的前提下,惰性/定时收敛后状态为 PAUSED 且有效时间已按 会话-决策02 截断;正常进行中的会话不受影响。✅ 已用落库集成测试覆盖(惰性、定时、不会误伤正常会话、不跨租户、重复扫描不重复结算)
---
## 5. P1 会挡路的功能缺口与待补能力
### 会话-05(原 LPT-07)活跃会话拦截没有出路,会永久堵住新任务
- [x] 已完成
- **完成于** `lpt-fe` `25fbc67`(+ `lpt-docs` `804d53a`)
- **涉及仓库**:`lpt-fe`(+ `lpt-be` 需提供结束/放弃能力)
- **已实施**:拦截入口补两个新出口:「结束它并开始新任务」(复用 `ended` 接口,旧会话会生成一份未填写总结的报告)与「放弃该会话」(复用 `abort`,仅限未产生学习残片的会话,后端拒绝时原样转达原因);两者成功后继续开始当前任务,一次交互内解除阻塞。另对 会话-04 自动收敛过的会话在弹窗与任务页给出「疑似乎忘记结束」提示。
- **依据(修正)**:守卫实际位于 `StartTask.vue` 的 `loadTaskSession()`(清单原文写的是 `Study.vue` 的 `startTask()`,与实际代码不符,已按实际位置改);原行为只有「前往继续 / 取消」,取消后只弹一条提示,用户无处可去。
- **影响**:一个搁置数月的暂停会话会阻止开始任何新任务(所有任务入口都撞同一个守卫),用户必须先找回那个任务手动结束。
- **验收**:存在陈旧活跃会话时,用户可在一次交互内开始新任务。✅ 已用交互式集成测试覆盖五个出口分支(前往继续 / 结束并开始 / 放弃 / 放弃失败 / 取消)
### 报告-01(原 LPT-08)学习报告与知识碎片不可修订
> **已确认的决策(2026-10-09,维护者)**
>
> 1. **修订范围**:知识碎片与学习报告**都可编辑、都可删除**。删除一律走软删除(`deleted`),Feed / 统计 / 导图取材按未删除过滤。
> - 取舍:接受了「报告可被改写,因此不再是不可变的原样事实」,换取记录成本下降。这与 §3 支点「学习报告是会话产出的真实记录」存在张力,属于维护者的有意取舍。
> - 连带口径:**碎片删除不连带删报告**(碎片是原料,报告是收敛)。
> - 导图处理:删改后给受影响任务置「待更新」标记,AI 重建**由用户手动触发**,不自动重建(避免一次删除触发大范围 AI 调用)。
> 2. **删除报告不连带删碎片**:报告与碎片在库里是并列关系(都挂在会话上),碎片是独立原料。删除报告时弹窗明示「本次学习的 N 条碎片会保留」。
> - 关键理由:归属-01 之后碎片有独立的内容归属,可能已被归类到**其他任务**;连带删除会删掉已经归属到别处的内容。
> - 删除后:报告 `deleted=1`;碎片不变;受影响任务置「待更新」;统计里报告数 -1、碎片数不变。
> 3. **删除学习任务时**:碎片**保留**并把内容归属置空(进入待归类),其余(会话、报告、标准导图、回忆记录、应用场景)**随任务一并软删除**。
> - 与决策 1、2 一致:碎片是原料,不因归属消失而消失;删任务撤销的是「这次学习的时间记录与收敛结果」,不是知识本身。
> - 弹窗必须分别列出「即将删除」与「即将保留(N 条碎片进入待归类)」,避免用户以为删干净了。
> - 顺带修复:当前 `deleteTask` 只软删任务行、不级联任何东西,而前端弹窗却写着「关联的会话/报告/应用场景将被一并删除」——文案与实现不一致。
- [ ] 未完成
- **涉及仓库**:`lpt-be`(+ `lpt-fe`)
- **依据**:端点清单——`StudyReportFragments` 只有 `POST` / `PUT /{id}` / `GET`;`StudyReports` 只有创建与查询,**没有 PUT、没有 DELETE**;碎片也没有 DELETE。
- **影响**:写错不能改,也不能删除,只能改数据库。
- **理由**:知识碎片是学习报告、复习 Feed、标准导图的共同原料,记录成本上升会直接降低记录率,连锁削弱整个复习闭环。
- **建议**:报告支持编辑与删除;碎片支持删除;删除需考虑对标准导图、回忆记录、统计的影响(软删除 + 标记重建导图)。
- **验收**:报告/碎片可编辑与删除;删除后 Feed 与统计不再包含该条。
### 复习-02(原 LPT-09)复习 Feed 只读,没有反馈动作
- [ ] 未完成
- **涉及仓库**:`lpt-be`(+ `lpt-fe`)
- **依据**:Feed 仅提供列表/详情/回忆对比;`ReviewServiceImpl.reviewNeedWeight()` 的智能权重只有两个信号——时间衰减(`createdTime`)与任务最近一次回忆覆盖率。
- **影响**:无法表达「这条其实很熟」与「这条完全没印象」;权重长期只有两个偏置,也没有「已复习」状态,同一批内容会反复出现。
- **建议**:加轻量动作(稍后再看 / 已掌握),把「上次复习时间」变成第三个权重信号;保持既有「无压力、偶遇式」设计,不引入强制清单。
- **依赖**:动作形态需先确认 复习-01(§11)中的反馈动作取舍。
- **验收**:用户反馈动作可落库并在下一次 Feed 排序中生效。
### 导出-01(原 LPT-10)无数据导出
- [x] 已完成
- **完成于** `lpt-be` `faaaa13`、`lpt-fe` `87e4cea`
- **涉及仓库**:`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-be` + `lpt-fe` + `lpt-ai`(概念文档已写入 `lpt-docs`)
- **依据**:复习只有接触(Feed)与结构提取(回忆对比),概念边界上的误解(例如把“参数量”当成能决定磁盘占用)不会被覆盖率捕捉。
- **已定**:开放式问题引导(例:“1B 参数量的 LLM 模型,会占用多少磁盘空间?”),无标准答案、不判分;AI 在对话中纠正回答里隐含的边界问题;对话不设轮数上限;产出是知识碎片,由用户确认后记录;复用碎片全链路(归属、待归类、导图取材、Feed 回收);碎片默认归属“被引导概念所属的学习任务”,并带「来自学习引导」标记(仅标记,不做特殊处理);记录上下文为复习行为;耗时计入复习-07;不进入学习报告;入口为 Feed 卡片与导图节点;不提供降级形态,AI 不可用时该功能整体不可用。
- **前置条件**:依赖 AI-02 / AI-03(多轮对话不能建在当前同步阻塞的链路上);「来自学习引导」标记的存储依赖标记-01。
- **验收**:一次学习引导结束后,用户确认可生成一条归属正确、带来源标记的碎片,并随导图增量更新出现;不确认则不产生任何数据;AI 不可用时入口不可用,且不影响复习其他部分。
### 复习-07 复习耗时统计
- [x] 已完成
- **完成于** `lpt-be` `3b33cd8`、`67c8711`,`lpt-fe` `21af81f`
- **涉及仓库**:`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 分钟
- [x] 已完成
- **完成于** `lpt-be` `cf380c5`、`lpt-fe` `e52682c`(+ `lpt-docs` `39efbb6`)
- **涉及仓库**:`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 串行且无重试
- [x] 已完成
- **涉及仓库**:`lpt-ai`(+ `lpt-be` 超时策略)
- **完成于** `lpt-ai` `bf56c2b`
- **依据**:`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` 类,测试覆盖并发、重试、复用与清理。
- **不得改动的契约**:`/ai/tasks` 必须固定返回 201(Java 端 `AiServiceClient` 把非 201 视为提交失败),复用信息放在响应体的 `reused` / `status` 字段。
- **验收**:并发 N 个任务时耗时不再线性增长;可重试错误不产生失败结论。✅ 已用假 LLM 服务端到端验证:4 个任务× 300 ms 共用 431 ms(串行需 1200 ms+);前两次 429 后仍为 `done`;相同请求只调用 LLM 1 次。
- **遗留**:`lpt-ai` 的部署(`lpt-infra` configmap)未设队列相关环境变量,目前走默认值;需要调优时再补。
### AI-04(原 LPT-14)防并发锁是 JVM 内存锁
- [x] 已完成
- **完成于** `lpt-be` `cf380c5`
- **涉及仓库**:`lpt-be`
- **已实施**:删除 `StandardMindMapServiceImpl` 里的 `ConcurrentHashMap<String, AtomicBoolean> generatingTasks`,改为基于 `ai_tasks` 的进行中判定:同一用户 + 同一类型 + 同一目标已有 `PENDING`/`RUNNING` 任务时复用该任务,因此不存在「多副本锁失效」。执行侧再用「状态仍为 PENDING」的条件更新抢占,多副本并发也不会重复执行。
- **对外语义已明确**:提交接口返回的是**任务状态**(`AiTaskResponse`),不再是可能为 null 的实体;前端据此展示「正在生成」。
- **验收**:多副本场景下同一任务不会并发生成;生成中重复请求返回明确的进行中状态。✅ 单测覆盖「同一目标重复提交返回同一任务标识」,集成测试覆盖重复提交复用
---
## 7. P3 检索与数据增长
### 数据-01(原 LPT-15)业务主表缺索引,而每条查询都被追加租户条件
- [x] 已完成
- **完成于** `lpt-be` `e506c4d`(补了 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()`
- [x] 已完成
- **完成于** `lpt-be` `251a468`
- **涉及仓库**:`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-be`
- **依据**:`ReviewServiceImpl.latestRecallRatioByTask()` 按 `taskNum in (...)` 查询全部记录(含体积较大的 `compare_result` JSON)后只在内存里取每条任务的第一条。
- **影响**:数据传输量与内存占用随复习次数线性增长。
- **建议**:改为分组取最新(子查询/`MAX(created_time)`),或把最近覆盖率冗余到任务表/导图表。
- **验收**:该查询返回行数等于任务数而非回忆记录数。
### 数据-02(原 LPT-18)统计聚合在内存中完成且无时间范围
- [ ] 未完成
- **涉及仓库**:`lpt-be`
- **依据**:`ReviewServiceImpl.fillReviewTaskStats()` 加载**所有任务的全部会话**到内存再聚合,无时间窗、无分页。
- **影响**:使用越久越慢,且会随会话数增长而内存膨胀。
- **建议**:下推为 SQL 聚合(含今日/本周条件),必要时物化统计表。
- **验收**:统计接口加载的会话行数与任务数同阶,不随历史会话数线性增长。
### 复习-05(原 LPT-19)Feed 返回全文
- [ ] 未完成
- **涉及仓库**:`lpt-be` + `lpt-fe`
- **依据**:`ReviewFeedItem.content` 直接返回报告/碎片全文,`getReviewFeed(100, "smart")` 一次最多 100 条;前端只展示前几十个字(详情页才需要全文)。
- **建议**:Feed 返回摘要字段(含长度标记),详情接口按需拉全文。
- **验收**:Feed 响应体积显著下降且展示行为不变。
### 数据-03(原 LPT-20)编号生成有撞号风险且无唯一约束
- [x] 已完成
- **完成于** `lpt-be` `3cc3be1`
- **涉及仓库**:`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`。
- **当前决策(2026-10-09,维护者)**:**暂缓**。项目处于开发阶段,认为该风险可接受;不同环境使用不同密码会给开发带来不必要的精力消耗。
- 重新评估的前提:进入对外发布/多人协作阶段,或 `lpt-secrets` 的值与仓库中的值相同(后者意味着公开在 Git 里的就是生产口令)。
- 若重新开工,建议顺序:**先轮换凭证**(使历史值作废)→ 再改配置占位符 → 「清 Git 历史」收益很低,可只做整洁性处理(改写历史会让所有已有克隆失效,且已外流的副本不受影响)。
### 安全-02(原 LPT-22)Actuator 端点鉴权边界未固定
- [x] 已完成
- **完成于** `lpt-be` `251a468`
- **已实施**:把暴露清单显式固定为 `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 与滥用)
- [x] 已完成
- **完成于** `lpt-ai` `f091fe6`、`1c31682`,`lpt-be` `251a468`、`bad7d6b`,`lpt-infra` `9160dd1`
- **已实施**:
1. **抓取四层校验**(`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。
2. **入站令牌(可选)**:`LPT_AI_TOKEN` 设置后 `/ai/*` 与 `/admin` 都要求携带(header `x-api-token` 或 query `token`);`lpt-be` 侧由 `lpt.ai-service.token` 提供。部署清单用 `secretKeyRef.optional: true` 引用 `lpt-secrets/lpt-ai-token`,**没设这个 key 也能启动**(此时不校验)。
3. **限流**:`/ai/tasks` 按来源限流(默认 30 次/分钟,`LPT_AI_RATE_LIMIT`)。
4. **请求体上限**:`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
- [x] 已完成
- **完成于** `lpt-be` `af13bd5`
- **涉及仓库**:`lpt-be`
- **依据**:`application.yml` 中 `mybatis-plus.configuration.log-impl: org.apache.ibatis.logging.stdout.StdOutImpl`(注释里保留了 `Slf4jImpl` 备选)。
- **影响**:生产日志包含全部 SQL 与参数(含学习内容),噪音大且不利于排查。
- **建议**:改为 `Slf4jImpl` 并按环境分级,生产默认不打印参数。
- **验收**:生产环境不再输出逐条 SQL。
### 运维-01(原 LPT-25)备份只在集群内同一 PVC
- [ ] 未完成
- **涉及仓库**:`lpt-infra`
- **依据**:`mysql-backup-cronjob.yaml` 每日 `mysqldump --all-databases` 写入同一集群的 `mysql-backup` PVC,保留 14 天,且 dev 与 prod 混在同一 dump。
- **影响**:集群级故障即全丢;无法按环境恢复。
- **建议**:增加异地/对象存储副本,按库分文件,并定期做恢复演练。
- **验收**:可在集群外取得可恢复的备份,并完成一次演练记录。
### 清理-01(原 LPT-26)死代码与死表清理
- [ ] 未完成
- **涉及仓库**:`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. 建议推进顺序(按模块)
同一模块内的条目触碰同一批表结构、口径或配置,建议一个模块一次性改完,避免出现双口径并存的中间态。
1. **学习会话生命周期**:会话-01/02/03 已完成;会话-04 + 会话-05 已完成(收敛方式取「惰性 + 定时并用」,出口取「结束并开始新任务 + 放弃」)。本模块已收口。
2. **内容归属与报告**:归属-01 与报告-01 合并一次改完碎片表与报告结构(碎片归属、报告四段结构、导图待更新标记、检索口径);标记-01(统一标记存储)随同定下,学习引导的来源标记依赖它。
3. **复习**:先落复习-01 的六项结论(口径与内容边界),复习-07(复习耗时)已独立完成;再做复习-02 / 复习-03 / 复习-04 / 复习-05;复习-06(学习引导)依赖 AI-02 / AI-03 与标记-01,排在 AI 链路之后。
4. **AI 链路**:AI-01 / AI-02 / AI-03 / AI-04 均已完成。本模块已收口。
5. **数据与检索 + 导出**:数据-01 / 数据-02 / 数据-03 / 导出-01 均已完成。本模块已收口。
6. **安全与运维清理**:安全-02 / 安全-03 / 安全-04 已完成;安全-01 由维护者决定暂缓(见条目内「当前决策」);剩运维-01(需外部存储目标)与清理-01(需确认是否删除)。
7. **学习录音(已暂停)**:模块整体挂起,重启前先定 §12「路线分叉」(依赖 OBS / 自研原生)。
---
## 10. 已确认的设计变更(待实施)
### 归属-01(原 DC-01)内容归属与待归类
- **文档**:`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)复习回路补全
- **文档**:`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 只做语义匹配与归属建议。
- **待确认**:
1. Feed 是否包含学习报告(文档取向:不含)。
2. 反馈动作形态:只读 /“已掌握 + 稍后再看”/ 仅“稍后再看”(关联 复习-02)。
3. 覆盖率口径:最近一次 / 最近若干次加权。
4. 待归类内容的呈现:总览独立分类 / Feed 混排打标;归类是否需在卡片上一键完成。
5. 遗漏项语义:快照 + 回看原文 / 跨次累计集合。
6. 排序信号是否对用户可配置(掌握度与时间效应的强度)。
- **关联实现**:复习-02(反馈动作)、复习-03(Feed 随机取样)、复习-04(覆盖率查询)、复习-05(Feed 摘要)。
### 标记-01 统一标记存储
- **文档**:`lpt-docs/docs/concepts/marker.md`(新增,含 5 个待决问题)
- **背景**:来源标记、用户标签等弱信息分散在各功能里考虑,缺少统一存放位置;每新增一种标记就要改一次功能表结构。
- **已定**:标记统一存放,至少包含对象类型与标识、标记名与值、种类(系统标记 / 用户标签)、建立者与时间;标记不是状态——会话状态、报告可否修订、导图是否待更新这类流程判断留在主体上;学习引导产出的碎片带「来自学习引导」系统标记。
- **待确认**:
1. 标记可挂在哪些对象上(碎片 / 报告 / 任务 / 会话)。
2. 标记名的受控方式(系统标记固定词表、用户标签自由输入;是否允许在系统标记上叠加)。
3. 标记值的类型(布尔开关 / 枚举 / 自由文本)。
4. 是否需要按标记检索的入口,以及需要哪些索引。
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 后端
- [x] 已实现并实测通过(模块已暂停,代码在分支)
- **涉及仓库**:`lpt-companion`,分支 `feature/study-recording`,HEAD `8d0969d`
- **完成于** `feature/study-recording` `8d0969d`;`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):
1. 端到端可采到系统混音:OBS 日志 `pulse-input: Started recording from 'alsa_output...analog-stereo.monitor' (default)`,与非默认输出设备无关。
2. 采到的是**其他应用**的声音:用 `pw-cat`(非浏览器)播放 440 Hz,录出的音轨 FFT 主频精确为 440 Hz,峰值 9873。
3. 配置隔离成功:独立 `CreateProfile` / `CreateSceneCollection` / `CreateScene` / `CreateInput`,不影响用户已有配置。
4. 采集路径:OBS 录 Simple+mkv(320×240@5fps、200 kbps),抽出 Opus/Ogg 后删视频。中间文件约 112 MB/小时,最终音频约 18 MB/小时。
- **实现要点(踩坑记录均已写入 `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`。
- **验收**:学习会话中可一键开始/结束录音,并看到状态与转写结果。
## 附录 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` → 200
- `GET https://lpt.cat-shark.xyz/api/actuator/info` → 200
- `GET https://lpt.cat-shark.xyz/api/actuator/env` → 401
- `GET 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`。