docs: 待办补命名收敛清单

This commit is contained in:
cat-shark
2026-11-20 09:36:54 +08:00
parent bd6717dc8d
commit 0b12d9a800
+53
View File
@@ -74,6 +74,11 @@
| | 闭环-04 按标签复习生成导图 | P1 | 已完成 | — | | | 闭环-04 按标签复习生成导图 | P1 | 已完成 | — |
| | 闭环-05 任务执行页展示并编辑导图 | P1 | 已完成 | — | | | 闭环-05 任务执行页展示并编辑导图 | P1 | 已完成 | — |
| | 闭环-06 记录应用过程中犯的错误 | P2 | 只出设计 | 实现前仍需定:归属关系、入口关系、删除口径 | | | 闭环-06 记录应用过程中犯的错误 | P2 | 只出设计 | 实现前仍需定:归属关系、入口关系、删除口径 |
| 命名与术语 | 命名-01 知识碎片标识收敛 | P4 | 待决策 | 库表 `study_report_fragments` 是否改名(见条目) |
| | 命名-02 AI 任务类型三套写法 | P3 | 可直接实施 | — |
| | 命名-03 时间字段后缀统一 | P3 | 可直接实施 | — |
| | 命名-04 实体类名复数后缀 | P4 | 可直接实施 | — |
| | 命名-05 复习类概念的 `Review` 前缀 | P4 | 待决策 | 是否接受改名后与既有库表/接口不一致的过渡期 |
> **学习录音模块已整体暂停**(2026‑10‑08):录音-01 的实现已完成并实测通过,但采到系统音频的两条路线(依赖 OBS / 自研原生)还没定,其余条目全部挂起。详见 §12。 > **学习录音模块已整体暂停**(2026‑10‑08):录音-01 的实现已完成并实测通过,但采到系统音频的两条路线(依赖 OBS / 自研原生)还没定,其余条目全部挂起。详见 §12。
@@ -866,7 +871,55 @@
--- ---
## 14. 命名收敛(术语表对齐)
> **本节不是功能缺陷清单**,不影响行为、数据与性能,优先级整体排在功能条目之后。口径来源:`lpt-docs/docs/concepts/README.md` 的「英文名与命名契约」与「代码现状」;规则本身见 meta `.agents/roles/business-terminology.md`。
>
> **共同前提**:存量偏差已登记在术语表,**新代码已经开始按英文名派生**;本节只处理「存量怎么追」,不处理「新代码叫什么」。
### 命名-01 知识碎片标识收敛
- [ ] 未完成(**库表改名部分待决策**)
- **涉及仓库**:`lpt-be`、`lpt-fe`
- **依据**:概念已从「学习报告残片」改为「知识碎片」,英文名定为 `KnowledgeFragment`;代码仍是 `study_report_fragments` / `StudyReportFragmentsEntity` / `ReportFragment` / `Fragment`,共四套写法指向同一概念。
- **建议**:分两步,先做零风险的一半。
1. 前端 `ReportFragment` / `FragmentGroup` / `FragmentContextType` 与后端 DTO(`ReportFragment`、`StudyReportFragment`)统一到 `KnowledgeFragment`;不动库表、不动接口路径。
2. 库表与实体改名(`knowledge_fragments` / `KnowledgeFragmentEntity`)作为**单独迁移**评估;它会带出索引名、Mapper XML、历史导出与 `review_recall_records` 的内嵌字段。
- **验收**:第 1 步——`rg -i "reportfragment" lpt-fe/src lpt-be/src/main/java` 无命中;全量测试全绿。第 2 步按迁移规范另开条目后验收。
### 命名-02 AI 任务类型三套写法
- [ ] 未完成
- **涉及仓库**:`lpt-be`、`lpt-fe`、`lpt-ai`
- **依据**:同一个 AI 任务在三端有三个名字:`lpt-be`/`lpt-fe` 用 `RECALL_HINT` / `RECALL_CHECK` / `MIND_MAP` / `REPORT_DRAFT` / `TAG_MIND_MAP`,`lpt-ai` 用 `recall-hint` / `recall-check` / `generate-mind-map` / `aggregate-report` / `guidance`。后者是历史名(`report` 已改称「学习报告」、`guidance` 已改称「学习引导」)。
- **建议**:以术语表英文名为准建一张**固定的类型映射表**(放在契约所在的那一侧,两个仓库都引用同一张表的口径),新类型不允许单端起名;存量 `aggregate-report` / `generate-mind-map` 保留在 `lpt-ai` 作为入站别名,不要再扩散。
- **验收**:`lpt-ai` 收到的每个任务类型都能在映射表里查到;新增任务类型时两端同时登记。
### 命名-03 时间字段后缀统一
- [ ] 未完成
- **涉及仓库**:`lpt-be`、`lpt-fe`(接口字段)
- **依据**:三个概念的英文名已定为 `EffectiveTime` / `ActiveDuration` / `ActualTime`,但实际后缀混用:`study_sessions.effectiveTime`、`study_sessions.actualTime`、`review_recalls.activeDurationMs`、回忆侧 `actualDurationMs`;前端又统一去掉了 `Ms`(`activeDuration` / `actualDuration`)。同一份时间概念在会话侧叫 `Time`、在回忆侧叫 `Duration`。
- **建议**:按概念分而不是按端分——「秒数型耗时」统一用术语表的英文名,不再用 `Time` / `Duration` 后缀区分语义;回忆侧的 `actualDuration` 归到 `ActualTime`。改字段名时接口向后兼容一版(新旧字段同时返回)。
- **验收**:术语表「代码现状」表里时间类三行的偏差列清空;旧字段名仅作为兼容别名出现,并有删除条目。
### 命名-04 实体类名复数后缀
- [ ] 未完成
- **涉及仓库**:`lpt-be`
- **依据**:派生规则是 `<英文名>Entity`,实际有四个实体多了复数 `s`:`StudySessionsEntity`、`StudyExpectationsEntity`、`StudyReportsEntity`、`StudyReportFragmentsEntity`;同一仓库里 `TaskEntity`、`MarkerEntity` 又是单数。
- **建议**:纯类名重构,无库表变动;一次性改完,不建过渡类。
- **验收**:`rg "sEntity\b" lpt-be/src/main/java` 无命中;`./mvnw -o test` 全绿。
### 命名-05 复习类概念的 `Review` 前缀
- [ ] 未完成(**待决策**)
- **涉及仓库**:`lpt-be`、`lpt-fe`
- **依据**:术语表的英文名里有的带 `Review`(`ReviewScope`、`ReviewReference`、`ReviewFeed`、`ReviewOverview`),有的不带(`FreeRecall`、`RecallGapCheck`、`RecallHint`、`RecallDraft`、`LearningGuidance`);代码里同样混杂:`review_recalls` / `ReviewRecallEntity` / `RecallDetail`、`HintItem` / `RECALL_HINT`、`ScopeSnapshot`、`ReferenceSummary`、`GuidanceSession`。规律无人定过。
- **建议**:前缀规则二选一并写进术语表:①库表带领域前缀、代码类型不带;②一律带。选①意味着前端类型要改名,选②意味着库表要改名。**在定下之前不要局部改**,否则会多出第五种写法。
- **验收**:术语表里写明前缀规则,且「代码现状」表不再有前缀偏差行。
---
## 附录 A 核对方式(可复现) ## 附录 A 核对方式(可复现)