OPC/lexgo
2
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 粘贴英语文本、章节处理与本人阅读 (#5)

Browse Source 
schema v3 新增 lexgo_books、lexgo_chapters、lexgo_ingest_jobs；一次粘贴生成一个章节，
原文按收到的字符串逐字保存；处理任务具备持久状态机、启动恢复与 requestId 幂等。
新增书籍/章节/任务 API 一律按认证身份过滤归属，他人编号返回 404，后台任务不使用
客户端用户编号；学习端补齐粘贴导入、书库、章节状态与失败重试、原文阅读与章节切换。

测试：MySQL 集成测试覆盖导入→处理中→就绪→阅读完整路径、失败重试、幂等、越权与
Unicode 原文保真；学习端 Vitest 31 项、Playwright 3 项与构建通过；lexgo_dev 已显式
迁移到 v3，迁移前后既有数据指纹不变。

文档：Wiki 先写后回读（架构、业务规则、本地验证、需求总览、Home），导出核心镜像。
This commit is contained in:
ila
2026-09-11 00:36:23 +08:00
parent ed5da31888
commit a55708cd37
25 changed files with 3442 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/02-architecture-and-code-map.md
+37 -2
View File
@@ -2,8 +2,8 @@
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Architecture-and-Code-Map
wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Architecture-and-Code-Map.-
wiki_revision: 5bc7ccf33d1cc1cc28598c90e27a2ab6af4146bd
synchronized_at: 2026-09-10T14:33:23Z
wiki_revision: fa7d3d66e6e68164ee97a23dc20a737fcaba7a11
synchronized_at: 2026-09-10T16:35:18Z
<!-- gitea-wiki-mirror:end -->
# 架构与代码地图
@@ -175,3 +175,38 @@ WordNet 使用 ZIP 内原始 index/data/exception 文件，不使用 SysDict 或
- [resources/js/components/Review/ReviewHotkeyInformationDialog.vue](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/resources/js/components/Review/ReviewHotkeyInformationDialog.vue)
上游 LICENSE 为 GPL v3，本单只核对并描述行为，没有移植源码。#1 评论 7497 的四项对照登记由本节补充；原型 v1 的保存/关闭主要流程保持，不更改其历史验收记录，不声称已经在 Quant-UX 新建修订版。范围调整与原生手柄作为可运行小样验证，若真机结果导致主要流程变化，应先更新关键原型状态并由用户确认。
## 粘贴导入、章节与阅读（#5，schema v3）
#5 实现了目标路径一的第一段可运行链路：粘贴英语文本 → 持久导入任务 → 固定分章 → 处理中/就绪 → 本人阅读原文。Go 单进程同时承担 API 与后台任务。本单不接入 Python NLP，token、lemma 与词典索引仍待 #6，路线未决边界见业务规则页。
| 路径 | 职责 |
|---|---|
| server/app/lexgo/database.go | schema v3 显式迁移：lexgo_books、lexgo_chapters、lexgo_ingest_jobs；按版本累加语句，版本行只在全部语句成功后推进 |
| server/app/lexgo/library.go | 粘贴校验与固定分章、书籍/章节/任务写入、本人归属查询、重试与请求幂等 |
| server/app/lexgo/ingest.go | 任务声明 claim、处理完成、固定失败原因、启动恢复 |
| server/app/lexgo/router.go | 新增书籍/章节/任务路由；粘贴请求使用独立的 4 MiB 体积上限 |
| server/cmd/lexgo/main.go | serve 启动时恢复遗留任务，并按秒轮询处理待处理任务 |
| learner/src/stores/library.ts、views/ImportView.vue、BookView.vue、ReaderView.vue | 粘贴导入、书库与章节状态、失败重试、原文阅读 |
任务状态为 pending → processing → ready/failed，章节与任务共用同一套状态词。声明与完成分属两个事务：声明一经提交，即使进程随即退出，也只会留下可被启动恢复重新入队的 processing 记录。
### 粘贴导入 API v1（#5）
| 方法与路径 | 行为和权限 |
|---|---|
| POST /api/v1/books | {requestId,title,text,language?}；创建书籍＋首个章节＋导入任务；重复 requestId 返回首次结果（HTTP 200，duplicate=true） |
| POST /api/v1/books/:id/chapters | 向本人书籍追加一个章节 |
| GET /api/v1/books | 本人书库与章节状态计数；拒绝查询参数，避免用参数替换认证身份 |
| GET /api/v1/books/:id | 本人书籍与章节列表，含 jobId 与可读失败原因 |
| GET /api/v1/chapters/:id | 本人章节详情；仅 ready 时返回 originalText，并附带前后章节编号 |
| GET /api/v1/jobs/:id | 本人任务状态、尝试次数与失败原因 |
| POST /api/v1/jobs/:id/retry | 仅失败任务可重试；复用同一章节，不新建章节 |
所有接口按认证身份过滤 owner_id；他人书籍、章节或任务编号统一返回 404，管理员角色也不能解除学习数据的本人归属过滤。后台任务只使用任务行内的 owner_id，不接受客户端用户编号；请求体含未知字段（例如 ownerId）直接返回 400。
### schema v3
lexgo_books(owner_id, title, language)、lexgo_chapters(book_id, owner_id, ordinal, title, original_text MEDIUMTEXT, char_count, content_sha256, status, error_reason) 与 lexgo_ingest_jobs(owner_id, book_id, chapter_id, request_key, content_sha256, status, attempts, error_reason, finished_at)。owner_id 在章节与任务上冗余存放，使任何查询都能直接按认证身份过滤而不依赖连接；UNIQUE(book_id, ordinal) 与 UNIQUE(owner_id, request_key) 分别阻止重复章节与重复提交。启动检查要求版本 3，服务不自动迁移。
并发重复提交：请求命中 request_key 唯一键冲突后，用加锁读读取已提交结果，因为该请求事务的快照早于并发提交；因此两个并发相同提交只会产生一个章节，另一个得到 duplicate=true 的首次结果。
docs/03-business-rules-and-glossary.md
+17 -2
View File
@@ -2,8 +2,8 @@
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Business-Rules-and-Glossary
wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Business-Rules-and-Glossary.-
wiki_revision: 227c6cb92d30490f0f1f4b1b9f29cdbed8559ee4
synchronized_at: 2026-09-10T14:33:25Z
wiki_revision: ff2abb673fe97e7eaa6934f76180ffdde701da8d
synchronized_at: 2026-09-10T16:35:18Z
<!-- gitea-wiki-mirror:end -->
# 业务规则与术语
@@ -112,3 +112,18 @@ POST /lookup 接收 {surface,lemma?}。查词键单独 casefold/NFC/弯撇号转
桌面鼠标/手机长按使用原生 Selection；正文中键盘 ←/→ 选相邻词，Shift+←/→ 从锚点扩缩连续范围，起点/终点按钮可用 Tab/Enter。Esc 或关闭清除选区及未保存编辑，保留滚动和键盘阅读位置；切换章节清除选区，当前页面内分别记住章节滚动位置。纯标点的新选区清除旧面板，防止操作上一个词。个人释义必须显式保存，状态变化也随保存提交；本小样仅写内存。
手机方案保留浏览器原生长按、选择手柄和滚动，面板最多占底部 42dvh，正文有底部阅读余量；键盘定位用滚动边距避开面板。未获得真实手机结果，不能判定手柄、系统菜单、虚拟键盘或触摸滚动冲突已经解决。
## #5 粘贴分章、任务与阅读规则 v1
用户于 2026-09-10 确认两项边界（工单 #5 评论 7644）：本单按 Go 处理、不接入 Python；一次粘贴等于一个章节。
- 固定分章规则：一次粘贴产生一个章节，不按空行或长度自动再分。新建书籍时书籍标题与首章标题同为提交的标题；追加时标题即新章节标题。分章规则变化属于需求变化，必须重新确认。
- 长度与校验：标题去首尾空白后 1～120 个字符；正文必须含至少一个非空白字符；正文上限 100000 Unicode code point，超出返回 400；语言当前只接受 en。
- 原文保真：正文按收到的字符串原样保存与返回，不做 NFC、大小写、换行或空白归一化；页面使用 white-space: pre-wrap 展示，制表符、连续空格与空行保持可见。处理完成前不返回原文。
- 归属：书籍、章节与任务都记录认证账号的 owner_id；他人编号返回 404；管理员角色不解除学习数据的本人归属；后台任务只使用任务行的 owner，不信任客户端用户编号。
- 任务状态：pending、processing、ready、failed，章节与任务共用同一词表。失败时返回固定原因码加可读中文提示，错误字段不保存正文。
- 固定失败原因：unsupported_language、too_long、empty_text、content_changed。前三种只能由其他写入路径产生（例如语言调整或后续编辑功能）；content_changed 表示章节内容在处理前被改动，属于过期任务，必须重新提交，或恢复为提交时的内容后重试。
- 幂等：客户端 requestId 与账号构成唯一键。同一 requestId 配同标题同正文的重复提交返回首次结果，不新建章节；同一 requestId 配不同标题或正文返回 409；并发重复提交同样只产生一个章节。重试复用原章节，只增加尝试次数。
- 恢复：声明与完成分属两个事务。进程在声明后退出时，重启把 processing 的章节与任务放回 pending 并保留尝试次数，不产生重复章节。
- 未决边界：Go＋Python NLP 与全 Go 路线尚未确认。本单只做 Go 校验、分章与发布，不产生 token、lemma 或词典索引；正式接入前必须由用户确认路线，再定义生产 token 契约。
- 已知限制：本单未设置每账号书籍数量或总容量配额，只限制单次正文与请求体大小；删除书籍/章节属 #10，导入失败不会自动重试，只在启动时恢复被中断的 processing 任务。
docs/04-local-development-and-verification.md
+38 -2
View File
@@ -2,8 +2,8 @@
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Local-Development-and-Verification
wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Local-Development-and-Verification.-
wiki_revision: 694facbb7a861182122c9f6c69d28c58b005cb1a
synchronized_at: 2026-09-10T14:52:22Z
wiki_revision: b8741ac70a524bb79741183f592f19c1206cd71b
synchronized_at: 2026-09-10T16:35:18Z
<!-- gitea-wiki-mirror:end -->
# 本地开发与验证
@@ -246,3 +246,39 @@ node --test spikes/english/view.test.mjs
#4 用户验收记录：2026-09-10T22:51:52+08:00 用户确认“#4通过验收”（评论 7636）。未补充手机型号/浏览器/操作记录，未重跑测试，未自动合并 PR。后续正式移动端集成应补真机回归。
## #5 粘贴导入与章节阅读（schema v3）
升级步骤（本机，仓库根执行）：停止 lexgo-api → `python scripts/server.py build` → `python scripts/server.py migrate` → 启动 lexgo-api。lexgo_dev 已从 v2 升到 v3，新增 lexgo_books、lexgo_chapters、lexgo_ingest_jobs；迁移前后 sys_user 4、lexgo_spaces 4、lexgo_sessions 3、lexgo_login_logs 23、lexgo_operation_logs 1 完全一致。托管实例重启后 /healthz 返回 200，两端首页仍为 200，lexgo-admin 与 lexgo-learner 的 PID 未变化。
回退：停止 API，把 lexgo_schema 中 id=1 的版本从 3 改回 2，并恢复上一二进制；三张新表保留不删除，旧程序不读写它们。重新升级时显式 migrate 重新执行 IF NOT EXISTS 语句即可；集成测试覆盖 v2→v3 的既有数据保留与 v2 标记下的重复迁移。未在开发库演练回退。
学习端入口：http://127.0.0.1:5173 → 登录 → 我的书库 → 粘贴文本导入 → 章节就绪后进入阅读。
测试命令与结果（仓库根执行；本单使用专用库 lexgo_test_issue5，不借用其他测试库）：
| 命令 | 本次结果 |
|---|---|
| `python scripts/server.py test-integration`（LEXGO_TEST_DB_NAME=lexgo_test_issue5） | 全部通过：18 个顶层用例，其中 #5 新增 8 个（7 个书库/章节/任务/阅读 + 1 个 v2→v3 数据保留），另含 12 个子用例；既有 10 个用例保持通过 |
| `npx --yes pnpm@9.15.1 --dir learner test:unit --run` | 3 个文件 31 项通过（session 9、library 16、reading 6） |
| `npx --yes pnpm@9.15.1 --dir learner build` | vue-tsc 类型检查与 vite 构建通过，退出码 0 |
| `npx --yes pnpm@9.15.1 --dir learner test:e2e` | 3 项通过（既有 auth 2 项 + 新增 reading 1 项，均为虚构 API 响应） |
### 真实 API + MySQL 实测（2026-09-10，lexgo_dev）
使用本单新建的虚构账号 issue5_a、issue5_b，口令只保存在忽略的 .local/issue5-accounts.json；未改动 admin、dev、learner_a、learner_b。脚本 .local/verify-issue5-api.ps1 只在本机运行，不输出口令。
- 粘贴：HTTP 201，章节与任务均为 pending，charCount 99。
- 处理：实测状态序列 pending → ready，约 1132 ms（后台任务每秒轮询）；job attempts=1。
- 阅读：originalText 与提交正文逐字符相等，CRLF、制表符、弯引号、破折号、省略号、é 加组合重音、emoji、行尾空格与空行全部保留；sha256 前缀 ce7357ea22a3。
- 幂等：同一 requestId 重复提交 HTTP 200、duplicate=true、章节与任务编号不变；同一 requestId 换正文 HTTP 409；书库仍为 1 本。
- 隔离：issue5_b 读取 issue5_a 的书籍、章节、任务以及追加、重试全部 404；请求体带 ownerId 与查询参数 ownerId 均 400；issue5_b 书库为空。
- 追加与阅读导航：新章节 ordinal=2，处理后就绪，前后章节编号互相指向。
- 校验：空标题、纯空白正文、非 en 语言、缺少 requestId、超过 100000 code point 分别返回 400 与可读中文提示。
- 遗留 fixture：lexgo_dev 中 issue5_a 名下 1 本虚构书、2 个就绪章节（bookId=1，章节 1、2）。
浏览器实测：真实学习端 + 真实 API + 真实 MySQL 联测（临时 Playwright 用例，运行后删除）：issue5_a 登录 → 书库显示既有虚构书与“导入内容”入口 → 导入页粘贴含空行、制表符、行尾空格与 emoji 的正文 → 书库页由“处理中”变为“已就绪” → 阅读页 article.reader-text 的 textContent 与粘贴正文逐字符相等、computed white-space 为 pre-wrap → “下一章”切换到第二章且正文精确相等 → 390×844 视口下横向溢出 0 px。同一轮还运行了 3 项虚构 API 的既有 e2e，共 4 项通过。
截图保存在本机 .local/evidence/（library.png、book-after-paste.png、reader-desktop.png、reader-mobile-390.png）并作为工单附件上传，便于人工目视复核；本次会话模型不能读取图片，截图未经 Agent 目视检查，功能断言来自上面的程序化检查。
未验证：处理失败到重试的用户界面路径只由集成测试覆盖（无法通过 API 主动制造处理失败）；真实手机浏览器长按、手柄、滚动与虚拟键盘仍属 #4 缺口，本次只用桌面浏览器窄屏检查，不能当作真机结果；Python NLP 未接入，token、lemma 与词典仍为 #3 小样范围；生产并发、容量、备份恢复与部署不在本单范围。
docs/09-product-requirements-overview.md
+8 -2
View File
@@ -2,8 +2,8 @@
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Product-Requirements-Overview
wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Product-Requirements-Overview.-
wiki_revision: db82eeb1d509b8d3c4a2204143cfb0e829b6b083
synchronized_at: 2026-09-10T12:43:32Z
wiki_revision: 125df697d3d45dee098616d25970bb65a96727cd
synchronized_at: 2026-09-10T16:35:19Z
<!-- gitea-wiki-mirror:end -->
# 产品需求总览
@@ -223,3 +223,9 @@ Anki（U20）、YouTube/Jellyfin 远程字幕（U07/A08）、全量旧实例迁
## 试用前管理能力增补
用户于 2026-09-10 验收 #2，并批准新增 #18 登录日志与操作审计：两个管理员列表、查询筛选分页、必要字段记录、权限及 90 天保留清理。沿用现有 go-admin 管理布局，无需独立高保真原型。已通过用户验收，纳入 #16“邀请用户试用前完成”；不替代 #3 英语分词和 #4 阅读选择验证，也不引入其他 go-admin 默认模块。
## 实施进度增补（#5）
2026-09-10：#5“粘贴英语文本，处理后进入本人章节阅读”已实现并待用户验收，覆盖 F01 基础（书库与章节）、F02（粘贴导入）、F04 基础（处理状态与失败重试）与 F05 原文（可读原文与章节切换）。本节取代此前“阅读、导入尚未实现”的表述：粘贴导入与原文阅读已实现；点词查词、词典、个人词语状态、复习与统计仍未实现（#6～#15）。schema 升级为 v3，新增 lexgo_books、lexgo_chapters、lexgo_ingest_jobs。
范围边界不变：本单按 Go 处理，不接入 Python NLP，因此不产生 token、lemma 或词典索引；Go＋Python NLP 与全 Go 路线仍未确认，正式接入前必须由用户确认。真机手机详细证据仍缺失（#4 缺口保持）。
docs/README.md
+4 -2
View File
@@ -2,8 +2,8 @@
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Home
wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Home
wiki_revision: a645b99632c70734b493ed030ad6d4d2acfd13be
synchronized_at: 2026-09-10T14:52:14Z
wiki_revision: 5b936b75caeec89cd54f7147c842f0b66f901307
synchronized_at: 2026-09-10T16:35:18Z
<!-- gitea-wiki-mirror:end -->
# LexGo 文档入口
@@ -63,3 +63,5 @@ Quant-UX 原型 v1 已通过用户验收。[桌面预览](https://qux.ilapage.cn
#4 阅读选择小样已实现桌面鼠标/键盘、范围调整与原文位置验证，入口 http://127.0.0.1:5184/；固定版本 LinguaCafe 四项源码对照已记录。用户已验收并关闭 #4；真实手机详细测试证据仍缺失，详见本地验证页。#21 仍待实施。
#5 粘贴导入与章节阅读已实现，待用户验收：schema v3 新增 books/chapters/ingest_jobs，学习端具备粘贴导入、书库、处理状态与原文阅读；查词、词典与复习仍未实现。本单按 Go 处理，Go＋Python NLP 与全 Go 路线仍未决，正式接入前须用户确认。