MVP 增补：书库列表分页/截断提示与目录查询列选择（#5 后续优化） #24

New Issue

2026-09-11T11:03:38+08:00

ila commented

2026-09-11 11:03:38 +08:00

基本信息

类型：重构
所属 Epic：暂不归属（#16 的四阶段为 #2～#15）
所属 MVP / 版本：#16 之后的补齐项
阶段：后续优化

依赖与并行

前置工单：#5（已实现待验收）
是否允许与前置工单并行：是
原因：只影响书库列表与目录查询的读取方式，不改动 #5 的导入、任务与阅读契约。

子项目影响

仅影响的子项目 / 交付单元：共享后端（server）与学习端（learner）
是否跨子项目：是
是否修改共享接口或契约：书库列表若加入分页或截断字段，会修改 GET /api/v1/books 的响应；唯一事实来源为架构与业务规则 Wiki
各子项目需要执行的验证：后端 MySQL 集成测试、学习端单测与构建

原始需求

来源：Gitea #5 审核意见（2026-09-11 评论 7667 的两条“后续优化建议”）
提出时间：2026-09-11
关键原话或脱敏摘要：“只返回最新 200 本，无分页/总数/截断提示；超过上限后旧书无法从书库列表访问”“目录查询载入每章 original_text；目录应只读取所需列，降低长书开销”

要解决什么

书库列表当前最多返回最近更新的 200 本（server/app/lexgo/library.go 的 ListBooks）。超过上限后，旧书在学习端不可见，也没有任何提示，用户会以为数据丢失。
书籍目录接口 GET /api/v1/books/:id 通过 Find(&chapters) 载入整行，包含 MEDIUMTEXT 的 original_text。章节多或正文长时会带来明显的内存与 IO 开销，而目录只需要序号、标题、状态与字符数。

期望结果：列表要么可分页访问全部书籍，要么明确告知已截断；目录查询不再加载正文。

做什么 / 不做什么

做：为书库列表设计分页或“是否截断 + 总数”的响应字段，并在学习端给出对应入口或提示；把目录查询改为只选择目录所需列。
不做：不改动 #5 的导入契约、任务状态机、原文保真与归属规则；不引入全文检索或缓存层；不调整每账号容量策略（属于另一议题）。

已确认方案

待方案确认后填写。候选方向（择一，需用户确认）：

A：GET /api/v1/books 增加 page/limit（或游标）与 total，学习端分页加载。
B：保持单页返回，但增加 truncated（布尔）与 total，学习端明确提示“仅显示最近 200 本”。

目录列选择为独立的小改动，可与上项一起实施；不变更响应字段集合，只减少读取列。

预计修改文件：

server/app/lexgo/library.go（ListBooks、BookDetail）
server/app/lexgo/library_test.go（新增列表边界与列选择相关用例）
learner/src/stores/library.ts、learner/src/views/LibraryView.vue（分页或截断提示）
架构与代码地图、业务规则、本地开发与验证 Wiki

需求变化记录

日期	变化内容	原因	用户确认
2026-09-11	由 #5 审核意见转为独立工单	不属于 #5 必须整改范围 R1～R4	是

设计与原型门禁

修改类型：非 UI + 小范围 UI（提示或分页入口）
所需设计证据：文字设计（接口与状态说明）即可；列表分页属常规列表交互，沿用现有书库布局
可编辑设计源、线上原型链接和访问检查：无
审核版本、revision、复制版本或确认日期及识别方式：无
本地 HTML 导出：未要求
状态：无
确认人、确认时间和覆盖范围：待方案确认
无需 UI 原型或无需任何原型的原因：属既有列表的常规能力补齐，不存在交互不确定性；原型 v1 未包含 200 本以上场景

文档影响

不影响长期文档，原因：
更新项目档案或本地开发与验证
更新架构与代码地图
更新业务规则与术语
更新常见修改或故障排查
更新其他 Wiki 页面：

交付文档影响

无交付文档影响，原因：面向内部维护者，不改变部署、安装或对外支持方式

任务记录与可选快照

单次任务事实来源：当前 Gitea 工单正文与评论
默认不创建任务快照
用户明确要求专项快照；用途和范围：
项目专用规则要求任务快照；规则入口：

验收标准

书库列表在超过当前上限时要么可继续访问更早的书籍，要么明确提示已截断并给出总数；两种行为都要有测试。
书籍目录接口不再加载章节正文；用真实 MySQL 集成测试确认目录仍返回序号、标题、状态、字符数与 jobId。
学习端在对应场景下行为正确（分页/提示），并通过单测与构建。
不改动 #5 的导入、任务、原文保真与归属契约，原有用例保持通过。

验证方式

python scripts/server.py test-integration
npx --yes pnpm@9.15.1 --dir learner test:unit --run
npx --yes pnpm@9.15.1 --dir learner build

风险和回退

风险：分页会改变 GET /api/v1/books 的响应形状，需要同步学习端；截断提示方案则只新增字段，风险更低。列选择改动需确认目录仍能正确显示字符数与失败原因。回退：恢复列表查询的原有行为并回滚学习端改动，数据库结构不变。

## 基本信息 - 类型：重构 - 所属 Epic：暂不归属（#16 的四阶段为 #2～#15） - 所属 MVP / 版本：#16 之后的补齐项 - 阶段：后续优化 ## 依赖与并行 - 前置工单：#5（已实现待验收） - 是否允许与前置工单并行：是 - 原因：只影响书库列表与目录查询的读取方式，不改动 #5 的导入、任务与阅读契约。 ## 子项目影响 - 仅影响的子项目 / 交付单元：共享后端（server）与学习端（learner） - 是否跨子项目：是 - 是否修改共享接口或契约：书库列表若加入分页或截断字段，会修改 `GET /api/v1/books` 的响应；唯一事实来源为架构与业务规则 Wiki - 各子项目需要执行的验证：后端 MySQL 集成测试、学习端单测与构建 ## 原始需求 - 来源：Gitea #5 审核意见（2026-09-11 评论 7667 的两条“后续优化建议”） - 提出时间：2026-09-11 - 关键原话或脱敏摘要：“只返回最新 200 本，无分页/总数/截断提示；超过上限后旧书无法从书库列表访问”“目录查询载入每章 original_text；目录应只读取所需列，降低长书开销” ## 要解决什么 1. 书库列表当前最多返回最近更新的 200 本（`server/app/lexgo/library.go` 的 `ListBooks`）。超过上限后，旧书在学习端不可见，也没有任何提示，用户会以为数据丢失。 2. 书籍目录接口 `GET /api/v1/books/:id` 通过 `Find(&chapters)` 载入整行，包含 MEDIUMTEXT 的 `original_text`。章节多或正文长时会带来明显的内存与 IO 开销，而目录只需要序号、标题、状态与字符数。期望结果：列表要么可分页访问全部书籍，要么明确告知已截断；目录查询不再加载正文。 ## 做什么 / 不做什么 - 做：为书库列表设计分页或“是否截断 + 总数”的响应字段，并在学习端给出对应入口或提示；把目录查询改为只选择目录所需列。 - 不做：不改动 #5 的导入契约、任务状态机、原文保真与归属规则；不引入全文检索或缓存层；不调整每账号容量策略（属于另一议题）。 ## 已确认方案待方案确认后填写。候选方向（择一，需用户确认）： - A：`GET /api/v1/books` 增加 `page`/`limit`（或游标）与 `total`，学习端分页加载。 - B：保持单页返回，但增加 `truncated`（布尔）与 `total`，学习端明确提示“仅显示最近 200 本”。目录列选择为独立的小改动，可与上项一起实施；不变更响应字段集合，只减少读取列。预计修改文件： - `server/app/lexgo/library.go`（`ListBooks`、`BookDetail`） - `server/app/lexgo/library_test.go`（新增列表边界与列选择相关用例） - `learner/src/stores/library.ts`、`learner/src/views/LibraryView.vue`（分页或截断提示） - 架构与代码地图、业务规则、本地开发与验证 Wiki ## 需求变化记录 | 日期 | 变化内容 | 原因 | 用户确认 | |---|---|---|---| | 2026-09-11 | 由 #5 审核意见转为独立工单 | 不属于 #5 必须整改范围 R1～R4 | 是 | ## 设计与原型门禁 - 修改类型：非 UI + 小范围 UI（提示或分页入口） - 所需设计证据：文字设计（接口与状态说明）即可；列表分页属常规列表交互，沿用现有书库布局 - 可编辑设计源、线上原型链接和访问检查：无 - 审核版本、revision、复制版本或确认日期及识别方式：无 - 本地 HTML 导出：未要求 - 状态：无 - 确认人、确认时间和覆盖范围：待方案确认 - 无需 UI 原型或无需任何原型的原因：属既有列表的常规能力补齐，不存在交互不确定性；原型 v1 未包含 200 本以上场景 ## 文档影响 - [ ] 不影响长期文档，原因： - [ ] 更新项目档案或本地开发与验证 - [x] 更新架构与代码地图 - [x] 更新业务规则与术语 - [ ] 更新常见修改或故障排查 - [ ] 更新其他 Wiki 页面： ## 交付文档影响 - [x] 无交付文档影响，原因：面向内部维护者，不改变部署、安装或对外支持方式 ## 任务记录与可选快照 - 单次任务事实来源：当前 Gitea 工单正文与评论 - [x] 默认不创建任务快照 - [ ] 用户明确要求专项快照；用途和范围： - [ ] 项目专用规则要求任务快照；规则入口： ## 验收标准 - [ ] 书库列表在超过当前上限时要么可继续访问更早的书籍，要么明确提示已截断并给出总数；两种行为都要有测试。 - [ ] 书籍目录接口不再加载章节正文；用真实 MySQL 集成测试确认目录仍返回序号、标题、状态、字符数与 jobId。 - [ ] 学习端在对应场景下行为正确（分页/提示），并通过单测与构建。 - [ ] 不改动 #5 的导入、任务、原文保真与归属契约，原有用例保持通过。 ## 验证方式 ```powershell python scripts/server.py test-integration npx --yes pnpm@9.15.1 --dir learner test:unit --run npx --yes pnpm@9.15.1 --dir learner build ``` ## 风险和回退风险：分页会改变 `GET /api/v1/books` 的响应形状，需要同步学习端；截断提示方案则只新增字段，风险更低。列选择改动需确认目录仍能正确显示字符数与失败原因。回退：恢复列表查询的原有行为并回滚学习端改动，数据库结构不变。

ila referenced this issue

2026-09-11 11:04:17 +08:00

MVP 粘贴英语文本，处理后进入本人章节阅读 #5

ila referenced this issue

2026-09-11 11:22:52 +08:00

MVP 粘贴英语文本，处理后进入本人章节阅读 #5

ila referenced this issue

2026-09-11 11:27:24 +08:00

MVP 粘贴英语文本，处理后进入本人章节阅读 #5

ila referenced this issue

2026-09-11 20:30:07 +08:00

MVP 保存个人词义与状态，并在其他章节同步显示 #7