OPC/lexgo
2
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
feat/13-progress
lexgo/docs/02-architecture-and-code-map.md
T
ila a9952b3516 feat: 完成章节并查看个人基础进度 (#13) 
- schema v7 新增 lexgo_chapter_progress（chapter_id 主键、read_sha256 内容版本门控、
  外键级联到章节/书籍/账号），仍然只用可重放的 CREATE TABLE IF NOT EXISTS
- POST /api/v1/chapters/:id/complete：只记已读、不改词语状态；只有 ready 章节可标记；
  重复调用返回同一行并带 duplicate，不移动已读时间也不重复计数；正文新版本后该章
  回到未读但保留记录，重新标记更新同一行
- GET /api/v1/progress：已读/可阅读章节、已知/学习中/新词/忽略、已保存词条、待复习
  与每本书的已读进度；到期数量与复习队列共用 dueTermsQuery 与同一时钟
- ChapterSummary 增加 readAt，书籍列表、阅读器与编辑响应都会解析
- 学习端新增 /progress 页面与导航、stores/progress.ts，阅读器新增显式「标记本章已读」
  区块，书籍页显示已读标记
- Wiki 记录 Architecture、Business-Rules、Local-Development 与需求更新
2026-09-15 12:31:53 +08:00

359 lines
40 KiB
Markdown
Raw Permalink 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.
<!-- gitea-wiki-mirror:start -->
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: 9bc2de753de2249c586306cdc27b566052941da2
synchronized_at: 2026-09-15T04:31:24Z
<!-- gitea-wiki-mirror:end -->
# 架构与代码地图
## 项目定位
Go 承担业务与后台任务，浏览器提供阅读学习界面，NLP 保留独立边界是现有分析的建议。用户区与管理区共享身份服务，但功能权限与个人数据所有权分别校验。
## 代码地图
| 现有位置 | 内容 | 能证明什么 |
|---|---|---|
| `docs/01-LinguaCafe需求提取.md`、`docs/linguacafe-requirements.md` | 两份需求研究 | 参考需求与上游证据索引 |
| `docs/02-Go复刻与框架选型分析.md`、`docs/linguacafe-go-analysis.md` | 两份设计建议 | 候选方案，含未解决差异 |
| `docs/` 核心页面 | Gitea Wiki 的单向镜像 | 仅文档与治理准备，不是产品实现 |
| `dev_scripts/harness.py`、`dev_scripts/wiki_docs.py` | 原样复制的 DevHarness 工具 | 治理工具入口，无业务 API |
| `tests/` | 上游治理工具与文档结构测试 | 不验证阅读、NLP 或 SRS |
工程入口与已实现模块见下方 #2/#18；学习领域拟定职责：identity（身份）、library（书库）、ingestion（导入）、lexicon（全局词典）、vocabulary（个人词语）、review（复习）、progress（统计）、administration（管理）。底座固定后再决定具体目录。
## 两条主要执行路径
目标路径一：上传文本 → 创建有所有者的导入任务 → 提取/分词/索引 → 章节就绪 → 阅读器按 token 展示原文和用户词语状态。
目标路径二：阅读保存词语或短语 → 写入个人学习状态与例句 → 查询到期词条 → 服务端计算作答后的状态 → 写入幂等事件 → 更新统计。
## 不可破坏的边界
- 词典资源与个人释义分离，共享缓存不能混入个人记录。
- Go/Python/JavaScript 的偏移契约必须统一；原文与内容版本必须保留。
- API 与 Worker 复用业务规则；NLP 通过明确契约调用，不泄露模型内部对象到前端。
- 任务至少可重试而不重复产出；学习事件不重复计数。
- 共享 API/NLP/状态契约在批准后的主题 Wiki 中建立唯一来源，字段和版本尚未定案；不能以本页概要直接生成冻结接口。
## 管理端选型落地边界
管理端采用用户指定的 `D:/github_project/goadmin`，前后端固定 commit 见项目档案。后端现有入口为源仓库 main.go，业务分布于 app/cmd/common；管理前端入口为 go-admin-ui/src/main.js，页面位于 src/views，路由/API 封装位于 src/router、src/api。这些是外部参考仓库路径，尚未复制或运行于 LexGo。
当前 #2 已固定首批 LexGo 目录和身份衔接契约；通用管理能力可复用，用户与语言的数据所有权检查由业务层实现。既有分析中 gin-vue-admin 的推荐已被本次用户决策替代。
## 学习端与管理端的目标架构
以下是目标结构；账号、管理端与学习空空间已由 #2 实现。英语 NLP 已完成 #3 独立验证，尚未接入业务 API。
```mermaid
flowchart TD
L[学习端 Vue 3 / TypeScript / Vite] --> API[共享 Go API：基于 go-admin 扩展]
A[管理端 go-admin-ui] --> API
API --> B[独立学习业务模块]
B --> DB[(MySQL 8)]
B --> W[后台任务：具体选型待验证]
W --> N[NLP：Python 小样已验证，生产集成待实施]
```
| 交付部分 | 建设方式 | 复用与自建边界 |
|---|---|---|
| 学习端 | create-vue 新建独立 SPA 工程 | 复用 Vue Router、Pinia、Element Plus；定制书库、阅读器、划词与复习组件 |
| 管理端 | 指定本地 go-admin-ui 二次开发 | 沿用现有 Vue CLI/Vuex 工程，按 LexGo 需要适配管理页面 |
| 共享后端 | 指定 go-admin 后端扩展为模块化单体 | 复用适配后的身份、权限与管理能力；新增 library、vocabulary、review、progress 等业务模块 |
两个前端分别构建，共用账号体系、API 与数据库。角色权限和数据所有权分别校验，隐藏路由不能替代服务端授权。共享业务规则由后端维护；两端不各实现一套词汇或复习状态规则。
部署方向为同域名 `/app` 学习端、`/admin` 管理端、共享 API，首期不拆业务微服务。这些前缀是部署建议，具体网关、静态资源 base、路由回退和登录方式在接口/部署设计中验证后固定。学习端独立工程不要求单独部署后端。
先按浏览器响应式界面设计电脑与手机使用；PWA 保留为后续候选，完整离线同步不在本次技术确认中。最终页面和 MVP 范围将在后续需求讨论中确定。
## go-admin 模块参考与原型边界（2026-09-10）
以下来自已记录固定版本的本地源码检查，尚未执行配套构建。
| LexGo 内容 | 参考来源 | 复用边界与设计证据 |
|---|---|---|
| 账号、角色、菜单和 API 权限 | 后端 app/admin 的 sys_user/sys_role 路由、API、service/DTO/model；前端 src/views/admin/sys-user、sys-role | 两端用户名＋密码登录；账号页面沿用表格/弹窗，字段说明即可；学习接口另加强制用户归属 |
| 语言资源列表、配置 | SysConfig、SysDict 与管理前端对应列表/表单 | 复用表单模式；SysDict 是系统枚举，不能作为自然语言词典；简单配置不另画全套原型 |
| 文本处理状态 | app/jobs 的 SysJob 状态操作可参考 | 原版是 cron 任务管理，不能作为可靠文本队列的证据；新任务需明确持久状态、恢复和幂等 |
| 学习领域 API 与表 | router/apis/service/dto/models、版本迁移机制 | 沿用结构，独立设计词条身份、归属、原文位置与复习事务；后端无需 UI 原型 |
| 阅读、查词、短语、复习 | 已验收 Quant-UX v1 与运行划词小样 | 使用定制学习组件，主要交互改变时补关键原型；真实触摸/连续选择必须运行验证 |
源码检查发现 common/actions/permission.go 允许关闭 EnableDP，且 DataScope 默认分支不添加过滤；该机制用于管理数据范围，不能单独保证私人学习数据隔离。学习接口必须强制按认证用户归属查询，不允许客户端指定用户替代认证身份。
仅当管理流程引入多步安装、处理中/失败重试等明显交互不确定性时，补关键状态原型。通常的列表、编辑、删除确认沿用 go-admin 表格、表单和弹窗，记录字段、权限、异常和验收即可。
## 已实现工程入口（#2）
| 路径 | 职责 |
|---|---|
| server/cmd/lexgo/main.go | 配置连接、migrate/bootstrap/serve 命令；默认只监听 127.0.0.1:8000 |
| server/app/admin/models、server/common/models | 按 upstream.json 原样选用的 go-admin 模型和约定 |
| server/app/lexgo/database.go | MySQL 8 显式版本迁移、所有权标记、启动检查 |
| server/app/lexgo/service.go | 用户名校验、账号创建、bcrypt、随机会话摘要和撤销 |
| server/app/lexgo/router.go | JSON 请求、角色和归属授权、API 路由和安全错误响应 |
| server/app/lexgo/*_test.go | 真实 MySQL 隔离、撤销、并发创建、迁移拒绝/恢复、bootstrap 验证 |
| admin/src/views、admin/src/session.mjs | 基于 go-admin-ui 的账号页面与管理端会话 |
| learner/src/views、learner/src/stores/session.ts | 独立学习端登录与私人空空间、会话及迟到响应隔离 |
| scripts/server.py | 安全读取本机 .env.local，传入子进程；不输出秘密 |
### 账号 API v1
请求使用 JSON；受保护接口使用 Authorization: Bearer。成功结构 {code:200,data:...}，创建账号 HTTP 201；失败使用实际 HTTP 400/401/403/404/409/429/500 和 {code:状态码,msg:必要提示}。响应 Cache-Control:no-store。
| 方法与路径 | 行为和权限 |
|---|---|
| POST /api/v1/login | username/password，返回 token、expiresAt、user；不要求邮箱 |
| GET /api/v1/me | 当前登录者 id/username/role/disabled |
| POST /api/v1/logout | 撤销当前会话 |
| GET /api/v1/space | 当前用户英语空间；拒绝查询参数指定用户 |
| GET /api/v1/spaces/:id | 仅本人的空间可读，他人编号返回 404 |
| GET /api/v1/accounts | 管理员查看账号列表；只输出必要字段 |
| POST /api/v1/accounts | 管理员创建 learner；拒绝客户端 role 等未知字段 |
| PATCH /api/v1/accounts/:id | 管理员启停或重置 learner 密码；不能修改自己或其他管理员 |
| GET /healthz | 检查数据库连接，仅返回健康状态 |
schema v1：sys_user 保留选用 go-admin 模型字段，唯一小写用户名；lexgo_spaces 以 owner_id 为主键；lexgo_sessions 保存 token_hash/owner_id/expires_at；lexgo_schema 记录版本与产品所有权。服务启动不自动迁移。迁移仅接受空库或合法已有 LexGo marker，拒绝空 marker、其他产品、负版本与未来版本；版本 0 可重试部分迁移，版本 1 幂等。
凭据字段只存在本地环境和必要数据库哈希中。后台账号密码更新使用表/字段更新，避免上游 BeforeUpdate hook 对已有哈希再次加密。账号行再会话行的锁顺序用于串行化撤销与请求；API 在事务提交后才返回成功。
## 登录与操作审计（#18）
server/app/lexgo/audit.go 定义两类白名单字段日志、筛选分页、失败记录和过期清理；router.go 在登录/账号操作边界接入。登录成功时会话与日志同一事务；账号操作成功时业务写入与日志同一事务；失败时先回滚业务，再以独立、有 3 秒超时的事务写失败记录。日志写入失败返回通用 500，不输出数据库原始错误或凭据。
database.go 显式迁移至 v2，两张新增表均以 created_at/id 建立排序清理索引，账号字段建查询索引，无业务表级联删除。cmd/lexgo/main.go 的服务进程在启动和每小时执行审计清理，每次最多运行一分钟、每批删除 1000 条，仅影响过期审计记录。
admin/src/views/AuditLogs.vue 通过 kind 复用登录/操作列表；audit-logs.mjs 负责筛选编码和请求序号，session.mjs 继续进行管理员及会话 generation 校验。切换页面/账号清空日志，普通翻页保留总数，防止分页组件跳回第一页。菜单与标题按当前路由显示。
## 英语分词与本地词典验证（#3，已验收）
`spikes/english/` 是独立可运行验证小样，不是学习端生产功能。推荐后续采用 Python 3.12.12、spaCy 3.8.7、en_core_web_sm 3.8.0（保留 tok2vec/tagger/attribute_ruler/lemmatizer，停用 parser/ner）和 NLTK 3.9.2 读取 WordNet 3.0。Go 继续管理用户、权限、任务和持久数据，后续通过显式契约调用 NLP；本单未新增 Go API、MySQL 表或常驻部署实例。
| 文件 | 作用 |
|---|---|
| engine.py | 原文分词、lemma、三个位置单位、直接/lemma 查词；只读本地资源 |
| app.py、index.html、app.mjs、view.mjs、style.css | loopback 临时 HTTP 小样、输入/阅读/查词结果；单进程串行，输入不落盘 |
| resources.json、setup_resources.py、requirements.lock | 固定版本、来源和 SHA256；显式联网准备，运行期无自动下载 |
| test_engine.py、test_app.py、view.test.mjs | 真实模型离线验证、HTTP 边界与浏览器偏移/迟到响应测试 |
| benchmark.py、benchmark-result.json | 虚构语料的候选对照、长文/查询实测及环境样本 |
WordNet 使用 ZIP 内原始 index/data/exception 文件，不使用 SysDict 或新增业务库。NLTK 默认 synsets 会隐式词形还原，本小样直接读取其固定版本索引以区分 exact 和显式 lemma；禁用依赖全局 corpus 的 OMW 跨版本映射，只接受 WordNet 3.0。升级 NLTK 或词典时必须重跑契约测试。
候选比较：正则分词＋WordNet 默认名词 morphology 依赖少、速度快，但不具备上下文判断，缩写和词性歧义处理弱；纯 Go 规则同样需要自行维护这些语言规则。本次 spaCy 在 12 个明确样例中答对 11 个，基线 6 个，因此推荐保留独立 Python NLP 边界。样例量不足以证明总体准确率；不宣称部署或正式阅读功能已完成。
## #4 阅读选择小样与 LinguaCafe 对照
小样位于 spikes/selection：serve.py 只提供白名单静态文件，app.mjs 负责 DOM 原生选择/键盘/面板状态，range.mjs 负责原文范围和匹配，fixtures.mjs 提供两章虚构文本。保存仅在内存 Map，刷新清空，不接入账号、MySQL、正式词典、复习或 #21 附件。使用 Intl.Segmenter 的词与字形边界验证 UI，不能替代 #3 的 spaCy 结果；正式阅读器必须以章节原文、内容版本与 NLP tokens 为共同基准。
参考版本固定 LinguaCafe c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8。本次实际读取以下源码；未启动 LinguaCafe、未亲测其浏览器或手机行为。下表“参考行为”是源码证据；LexGo 方案是独立实现与取舍，不应标为上游已经验证的体验。
| 项目 | 参考行为与来源 | LexGo 采用及保留差异 |
|---|---|---|
| 阅读器 | TextBlockGroup.vue L56–100 用词/短语 stage、selected、hover 等状态；InteractiveTextStyling.scss L20–126 由主题决定颜色。TextReaderChapterList.vue L15–43 展示章节统计及已处理章节阅读入口；TextReader.vue L195–214 提供阅读完成后的书库/下一章 | 保留正文上下文、词语状态与选中区分、章节切换；小样以两章和学习中/已认识/忽略验证，章节统计及已读持久化仍属后续功能。侧栏/底部面板为 LexGo 布局，不宣称复制上游排版 |
| 查词面板 | VocabularyBox.vue L124–169、374–404 区分 Translation 与字典搜索，新短语需 Save phrase；TextBlockGroup.vue L1351–1380 失选时自动保存单词/已有短语。VocabularySearchBox.vue L149–179 及保存 catch 未证明完整错误反馈 | 沿用 v1 的词典释义/我的释义、明确保存、关闭继续阅读。LexGo 关闭不自动保存；保存后可见反馈，无词典/无结果仍可手填。小样用固定虚构释义与故障状态，不把它当成真实词典/网络重试验证 |
| 短语与键盘 | TextBlockGroup.vue L399–599 自定义鼠标范围；L374–457 为手机 500ms 长按及后续触摸移动，选区开始后阻止默认滚动；L1071–1202 的 Shift+方向键跳高亮词，而非扩展范围，Esc 失选 | LexGo 采用原生鼠标拖选、手机长按/系统手柄，不拦截 touchmove；起止端点按钮可调整。←/→ 相邻词，Shift+←/→ 扩缩范围，Esc 取消。原型的预设短语按钮被真实正文选区替代，属于 #4 明确要求的验证；手机手柄是否与底部面板冲突仍待真机 |
| 复习 | Review.vue L270–345、559–692 为 Reveal→I was correct/Again，正确移除卡、Again 保留并随机抽剩余卡，最后一张正确完成；ReviewHotkeyInformationDialog.vue L14–24 提供快捷键。练习模式不写状态 | 已验收 v1 保留中文显答、答对/答错、再学与完成，单词/短语分别有状态。上游随机下一卡、阶段降级和快捷键不是本单已实现行为；#8 再明确调度、重学和幂等，#4 不新增复习引擎 |
源码链接：
- [resources/js/components/Text/TextBlockGroup.vue](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/resources/js/components/Text/TextBlockGroup.vue)
- [resources/sass/Text/InteractiveTextStyling.scss](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/resources/sass/Text/InteractiveTextStyling.scss)
- [resources/js/components/TextReader/TextReaderChapterList.vue](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/resources/js/components/TextReader/TextReaderChapterList.vue)
- [resources/js/components/TextReader/TextReader.vue](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/resources/js/components/TextReader/TextReader.vue)
- [resources/js/components/Text/VocabularyBox.vue](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/resources/js/components/Text/VocabularyBox.vue)
- [resources/js/components/Text/VocabularySearchBox.vue](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/resources/js/components/Text/VocabularySearchBox.vue)
- [resources/js/components/TextReader/TextReaderHotkeyInformationDialog.vue](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/resources/js/components/TextReader/TextReaderHotkeyInformationDialog.vue)
- [resources/js/components/Review/Review.vue](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/resources/js/components/Review/Review.vue)
- [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 的首次结果。
## #5 审核整改（R1～R4，2026-09-11）
提交见工单 #5 的整改评论；本条记录实现与验证方式。
- 追加契约（R1）：学习端把新建与追加拆成两个请求类型，追加不发送 language；后端保持严格解码，并新增回归测试断言“追加带 language 返回 400、不带则 201”，学习端单测断言追加请求体只有 requestId/title/text。
- 运行期任务恢复（R2）：`server/app/lexgo/ingest.go` 的恢复逻辑合并为一处——启动恢复使用阈值 0，运行期每轮清扫使用 15 秒阈值并把超过 5 次尝试的任务置为 failed（原因码 attempts_exhausted）；`cmd/lexgo/main.go` 的 worker 每秒先清扫再处理，日志分别说明“已重新入队”与“本批未完成、等待下一次清扫”，不再声称已完成实际跳过的重试。
- 离页作废在途请求（R3）：`closeBook`/`closeChapter` 推进请求序号并清理 loading；`ImportView` 记录是否已卸载，卸载后的成功响应不再触发跳转。
- 重试自愈（R4）：`retryChapter` 先把重试返回的章节状态应用到列表与阅读器并重新安排轮询，再做静默刷新。
验证：Go 全量用例 20 项通过（新增运行期恢复与尝试上限两项）；学习端单测 38 项通过，其中 7 项在整改前的代码上复现失败；真实联调确认追加路径可用、被中断的任务在运行中被自动恢复（约 0.5 秒，无需重启）、重试在首次刷新失败后仍自动显示最终结果。
## 全 Go 正式架构决定（2026-09-11，#6）
用户已明确选择全 Go：正式英语分词、原文位置映射、本地词典解析和词形候选查询由 Go 后端完成，不运行 Python NLP 服务。此前“Python 建议/全 Go 未决”仅为历史决策记录，由本决定覆盖；spikes/english 保留历史验证，不接入产品。#6 按该方向实施，当前方案见工单最新启动评论；WordNet 3.0 仍为首个资源（英语释义），词形规则候选不等同于 spaCy 上下文消歧，原文及个人学习状态不按候选合并。
## #6 全 Go 词典与阅读器（2026-09-11，已验收并合入 main）
`server/app/lexgo/wordnet.go` 负责固定 WordNet ZIP 校验/内存解析、Unicode 分词及词形候选；`dictionary.go` 负责资源与章节查词 API；`database.go` schema v4 新增单槽共享资源表 lexgo_dictionaries（元数据、enabled、SHA、ZIP LONGBLOB），已有学习数据不改写。每个 Router 按 SHA 缓存一个不可变词典，查询先读资源元数据，缓存未命中才读取 ZIP；进程重启从数据库恢复，不需要 Python NLP 或额外资源目录。
| 接口 | 权限与输入/输出 |
|---|---|
| GET /api/v1/dictionaries | 管理员；items + supported，状态 ready/disabled/unavailable，不返回 archive 或本机路径 |
| POST /api/v1/dictionaries/import | 管理员；multipart name/language/version/source/format/file；返回 resource + duplicate；格式/来源/版本固定 |
| PATCH /api/v1/dictionaries/:id | 管理员；{enabled:boolean}；返回 resource |
| GET /api/v1/chapters/:id/tokens | 本人 ready 章节；{textSha256,tokens:[{text,start,end,startUtf16,endUtf16,kind}]} |
| POST /api/v1/lookup | {chapterId,start,end}，cp半开范围；本人ready完整单词；返回 status/query/matchedForm/candidates/entries/resource |
管理端 `Dictionaries.vue` + `dictionaries.mjs` + session multipart 方法，复用 go-admin 导航/表单与身份失效保护。学习端 `useReaderLookup.ts` 校验原文片段/SHA/所有位置，`ReaderTokens.vue` 渲染可聚焦单词，`LookupPanel.vue` 展示释义及临时个人草稿。桌面侧栏，手机固定底部45dvh面板；关闭恢复焦点，仅无后续手动滚动时恢复自动调整前位置。旧响应在换词/换章/退出/离页后失效。
参考：[WordNet 数据格式](https://wordnet.princeton.edu/documentation/wndb5wn)、[词形规则](https://wordnet.princeton.edu/documentation/morphy7wn)。#3 仅历史实验，#6 不调用其实验服务。
## #7 个人词条与阅读器状态（2026-09-11，已验收并合入 main）
schema v5 新增 lexgo_terms：一个学习者对一个词形一条记录。身份键为 `(owner_id, language, term)`，`term` 是 Go 侧 `normalizeWord` 的结果（NFC、小写、弯撇号转直撇号），列使用 `utf8mb4_bin`，避免折叠 `resume`/`résumé`；`original_form` 保存最近一次保存的原词形供显示。`definition`/`examples` 是学习者自己的文本，例句按行存储；共享词典仍只在 `lexgo_dictionaries`，两者不混存。`status` 与 `level` 由数据库检查约束守住：只有 `learning` 允许 1～7，其他状态必须为 0。
| 接口 | 权限与输入/输出 |
|---|---|
| POST /api/v1/terms | 本人；`{chapterId,start,end,definition,examples[],status,level?}`；服务端按 #6 同一套 token 范围反推词形，`owner`/`language`/`term` 一律不接受客户端输入；唯一键 upsert，重复保存更新同一行；首次 201、更新 200，返回 `{term,created}` |
| GET /api/v1/terms/:id | 本人；他人编号与不存在编号统一 404，不泄露存在性 |
| GET /api/v1/chapters/:id/tokens | 在原响应上为 word 片段增加可选 `term:{id,status,level}`；服务端按本章词形分批（每批 500）查本人词条，其他章节保存的同形词同样命中 |
`server/app/lexgo/terms.go` 负责身份、状态/等级边界、文本上限、upsert 与章节点词状态；`database.go` 提供 v5；`dictionary.go` 的 tokens 与 lookup 共用 `wordAtRange`，保存与查询必须落在同一个完整单词范围上，所以客户端无法命名自己没有读到的词。个人词条不写审计日志。
学习端 `useReaderLookup.ts` 在原有查询状态上增加个人释义、例句、状态、已保存编号、预填与保存；打开已保存词先读 `GET /terms/:id`，读取失败时禁用保存，避免用空表单覆盖原内容。`LookupPanel.vue` 提供状态单选、释义与例句输入、保存与简短反馈；`ReaderTokens.vue` 按状态高亮 `is-new`/`is-learning`/`is-known`/`is-ignored`。换词、换章、离页、退出或切换账号都会清空表单、状态与高亮。管理端无改动。
## #8 复习调度与答题（2026-09-11，已验收并合入 main）
schema v6 新增 `lexgo_term_reviews`（每个个人词条一行排期：`due_at`、`review_count`、`correct_count`、`wrong_count`、`last_reviewed_at`）与 `lexgo_review_answers`（每次作答一条：`answer_key`、评分、状态/等级/间隔前后值、`result`、`requeued`、时间）。两条语句都是 `CREATE TABLE IF NOT EXISTS` 加 `INSERT IGNORE ... SELECT`，所以迁移是可重试的加法迁移；旧二进制回到 v5 仍可继续写 `lexgo_terms`，不需要改动个人词条表本身。既有已保存词汇在迁移中按 `due_at = created_at` 进入队列。
`server/app/lexgo/review.go` 负责间隔表、队列、评分转换、幂等与并发；`terms.go` 的保存路径通过 `syncTermReview` 维护排期行（`新词` 立即到期，显式 `学习中 level N` 排 `now + 间隔[N]`），计数在状态或等级变化时保留。
| 接口 | 权限与输入/输出 |
|---|---|
| GET /api/v1/reviews/queue | 本人＋当前语言；仅 `新词`/`学习中` 且 `due_at ≤ now`，按 `due_at, id` 排序、最多 50 条；返回 `{items, total}`，`total` 是全部到期数；不接受查询参数 |
| POST /api/v1/reviews/:termId/answers | `{answerId, grade: correct\|wrong\|again, expectedDueAt}`；应用成功 201，重放或过期 200；返回首次结果 `result`(applied/stale) 与 `duplicate` 标记、前后状态/等级/到期时间、`requeued` 与词条新状态；加锁后再次读取答案键，所以并发的同键提交也返回记录而不是报错 |
学习端新增 `/review` 路由与书库、阅读器顶栏的「到期复习」入口；`stores/review.ts` 维护队列、本轮计数、评分与重学，`ReviewCard.vue`/`ReviewView.vue` 呈现正面（词＋挖空例句）、答案面（个人释义＋例句＋三个评分按钮）、完成页与空队列页。一次评分对应一个 `answerId`，失败重试复用同一个；换词后重新生成。切换账号或退出登录会清空队列、计数与当前卡片。
参考：[LinguaCafe Review.vue](https://github.com/simjanos-dev/LinguaCafe/blob/c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8/resources/js/components/Review/Review.vue)。上游的随机抽卡、阶段降级与快捷键不属于本单；#8 只实现本项目的固定间隔、固定顺序与幂等作答。
## #9 TXT 上传导入（2026-09-11，已验收并合入 main）
`server/app/lexgo/upload.go` 负责把上传的 TXT 解码后交给与粘贴相同的核心：解码、multipart 解析与两条路由，schema 无变化（沿用 #5 的 `lexgo_books`/`lexgo_chapters`/`lexgo_ingest_jobs`）。文件只在内存中存在，不写临时文件，客户端文件名不参与任何路径也不入库。
| 接口 | 权限与输入/输出 |
|---|---|
| POST /api/v1/books/upload | 本人；multipart：`requestId`、`title`、`language`（可省略，省略即英语）、`file`；新建书籍与首章 |
| POST /api/v1/books/:id/chapters/upload | 本人且本人书籍；multipart：`requestId`、`title`、`file`；追加一章；不接受 `language` |
字段白名单之外的字段、重复字段、缺失 `file`、非 multipart 请求都返回 400；201 新建、200 重复、409 同编号换内容、404 他人书籍、401 未登录、429 已有文件正在上传（单槽并发门）。响应体与粘贴路径同为 `PasteResult`，所以学习端复用同一套跳转与轮询逻辑。
解码规则见业务规则页；实现上 `decodeTextUpload` 先按 UTF-16 BOM 识别并给出针对性提示，再剥离可选 UTF-8 BOM，然后用 `utf8.Valid` 整体校验，最后交给 `validatePaste`（非空、≤100000 码点）。因此上传与粘贴共享同一分章与任务规则：一次提交一章，`requestId` + 内容 SHA 幂等，worker 只发布已落库的原文。
学习端 `ImportView.vue` 增加「粘贴文本 / TXT 文件」来源切换（沿用已验收 v1 的切换与状态行），`stores/library.ts` 增加 `upload()` 与 `fileProblem`/`fileSizeLabel`，`session.request` 支持 `FormData`（multipart 请求不再被 JSON 化，边界由浏览器提供）。客户端预检只提前反馈，服务端结论为最终结论。
## #10 编辑与删除书籍章节（2026-09-11，已验收并合入 main）
`server/app/lexgo/edit.go` 提供改名、编辑与删除；`ingest.go` 增加版本门控。**schema 无变化**：`chapters.content_sha256` 与 `jobs.content_sha256` 就是版本键，新增的 `superseded` 复用现有 `error_reason` 列。
| 接口 | 权限与输入/输出 |
|---|---|
| PATCH /api/v1/books/:id | 本人；`{title}`；返回 `{book}` |
| GET /api/v1/chapters/:id/source | 本人任意状态；返回 `{source:{id,bookId,ordinal,title,text,status,contentSha256,charCount}}`，供编辑使用；不接受查询参数 |
| PATCH /api/v1/chapters/:id | 本人；`{title?,text?}`；返回 `{chapter,job,versionChanged}`；正文变化才新建任务 |
| DELETE /api/v1/books/:id | 本人；返回 `{deleted:{bookId,chapters}}`；FC 级联删除章节与任务 |
| DELETE /api/v1/chapters/:id | 本人；返回 `{deleted:{chapterId,bookId,remaining}}`；删除后重排序号 |
**版本门控**（本单修掉的缺陷）：任务只在 `job.content_sha256 == chapter.content_sha256` 时才能影响章节。认领任务时用 JOIN 只取版本匹配的行，并先把过期版本任务一次性标为 `failed/superseded`；发布前再比对一次，不匹配就只把任务标为 `superseded` 并**完全不触碰章节**；恢复扫描同样先作废过期版本任务、只重排版本匹配的中断任务；重试接口拒绝版本不匹配的任务（409）。删除期间在途任务找不到章节时视为无事可做（级联已删除其任务行）。
`unprocessableReason` 保留一条内容一致性检查：存储的正文重新计算出的 SHA 必须等于该章节存储的 SHA，用于兜住绕过 API 的直接写入（`content_changed`），与版本门控互不重复。
学习端 `BookView.vue` 增加书名编辑对话框、章节编辑对话框（标题 + 正文，正文来自 source 接口）与两处确认弹窗（`ElMessageBox`），章节行增加「编辑」入口；`LibraryView.vue` 在书库被删后显示「书籍已删除 · 已保存的生词和短语仍保留在生词本。」；`stores/library.ts` 增加 `renameBook`、`updateChapter`、`loadChapterSource`、`deleteBook`、`deleteChapter`。正文编辑通过浏览器 textarea 输入，因此该章的行尾统一为 LF（粘贴与 TXT 导入仍保留原始 CRLF）。
## #11 短语选择、保存与复习（2026-09-11，已验收并合入 main）
短语与单词共用一张表和一套复习机制：`lexgo_terms` 的 `term` 列存身份键，**单词键不含空格、短语键以空格分隔**，所以「词或短语」不需要额外列，也不需要第二套排期/队列/作答逻辑。`kind` 与词数由身份键在服务端派生（`termKind`/`termWordCount`），视图与队列项随响应返回。
`server/app/lexgo/phrase.go`：
| 部分 | 职责 |
|---|---|
| `phraseWords` | 从本人 ready 章节的 token 里取完全落在选区内的词；**切进单词的范围直接 400**，不静默丢弃；2～12 个词 |
| `phraseKey` / `phraseSource` | 身份键＝按顺序的规范化词形以单个空格连接；显示片段＝选区原文（内部标点与换行保留） |
| `phraseMatches` | 跨章节匹配：按首词分组后顺序比对词形，候选按 (起点, 长度降序, id) 排序并取**最左最长**的互不重叠集合 |
| `phrasesForChapter` | 按 `term LIKE '% %'` 取本人短语并匹配，供 tokens 响应使用 |
| `SavePhrase` | 由服务端推导身份后走与单词相同的 `saveTerm` upsert；`kind` 冲突返回 409 |
| 接口 | 说明 |
|---|---|
| POST /api/v1/phrases | `{chapterId,start,end,definition,examples[],status,level?}`；本人 ready 章节；服务端推导词序列与身份，不接受客户端身份；首次 201、重复 200 |
| GET /api/v1/terms/:id | 复用；响应增加 `kind` 与 `wordCount` |
| GET /api/v1/chapters/:id/tokens | 响应增加 `phrases:[{id,status,wordCount,startToken,endToken}]` |
| GET /api/v1/reviews/queue | 队列项增加 `kind` 与 `wordCount`；短语与单词同一队列、同一作答接口 |
学习端：`composables/readerRange.ts` 是纯函数层（整词对齐、内部保留、端点按词调整、命中优先级、区间换算），`composables/useTextSelection.ts` 监听 `selectionchange`（100ms 去抖）与 document 的 `pointerup` 读取浏览器原生选区并映射为 token 索引，**不拦截 touchmove、不 preventDefault**；`ReaderTokens.vue` 为每个 token 输出 `data-token-index` 与短语区间样式；`ReaderView.vue` 负责把选区变成短语、shift 点击扩展、以及面板端点调整；`LookupPanel.vue` 增加短语标题与四个端点按钮；复习卡用 `maskedPrompt` 把整段短语挖成一个空。已保存短语点击优先打开短语面板，单词数据不受影响。
## #12 词汇库：搜索、筛选与编辑（2026-09-11，已验收并合入 main）
`server/app/lexgo/vocabulary.go` 提供只读列表与按 id 编辑，**不改 schema**（沿用 #11 的「身份键派生 kind/词数」）。
| 接口 | 权限与输入/输出 |
|---|---|
| GET /api/v1/terms | 本人＋当前语言；`query`、`status`、`kind`、`page`、`limit`；返回 `{items,total,page,limit}`；默认 `page=1`、`limit=20`，上限 100；排序 `updated_at DESC, id DESC` |
| PATCH /api/v1/terms/:id | 本人；`{definition?,examples?,status?,level?}`；返回 `{term}`；身份字段不接受输入 |
参数校验沿用审计列表的既有约定：查询键白名单、重复键与未知键 400、`page ≥ 1`、`limit ≤ 100`、枚举值非法 400。搜索同时匹配规范化身份键、显示原文与个人释义；因为 `term` 使用 `utf8mb4_bin`，查询会先转小写再比较；`%`、`_`、`\` 经 `escapeLike` 转义后作为字面值，避免 `%` 命中全部。`kind` 通过键是否含空格判断（`term NOT LIKE '% %'` / `term LIKE '% %'`）。
编辑复用同一套领域规则：`termContent` 校验释义与例句上限、`termLevel` 校验状态与等级边界（只有 `learning` 带 1～7 级），只有状态或等级变化才调用 `syncTermReview` 重排（`reschedule=false` 时只补建缺失的排期行），因此**只改文本不动排期**、历史作答记录与计数保留。
学习端 `stores/vocabulary.ts` 保存列表状态与筛选（打开/关闭编辑对话框、从阅读器返回都不会丢），`views/VocabView.vue` 提供搜索框与显式搜索按钮、状态与类型筛选、分页、空态与「没有匹配的词条 + 清除搜索与筛选」，并把筛选与页码同步到 `/vocab?...`（`router.replace`）。释义/例句/状态/等级四个字段抽成 `components/TermFormFields.vue`，与阅读器面板共用；等级选择器只在词汇库编辑对话框中出现（阅读器面板仍只有四个状态）。
## #13 章节完成与个人基础进度（2026-09-15）
schema v7 新增 `lexgo_chapter_progress`：一章一行（`chapter_id` 主键），带 `owner_id`、`book_id`、`language`、`read_sha256`（标记时该章 `content_sha256` 的快照）、`read_at` 与时间戳，外键级联到章节、书籍与账号。仍然只加新表，不用 `ALTER TABLE ADD COLUMN`，保持每个版本 DDL 可重放。
| 接口 | 权限与输入/输出 |
|---|---|
| POST /api/v1/chapters/:id/complete | 本人；只有 `ready` 章节可标记，否则 409；重复调用返回同一行并带 `duplicate`；返回 `{progress:{chapterId,bookId,read,readAt,duplicate}}` |
| GET /api/v1/progress | 本人当前语言；返回 `{readChapters,totalChapters,knownTerms,learningTerms,newTerms,ignoredTerms,savedTerms,dueNow,books[]}` |
`server/app/lexgo/progress.go` 集中实现：`CompleteChapter`（事务内锁定章节，缺行则插入，内容相同则原样返回，内容不同则把同一行推进到新版本）、`readAtByChapter`（批量取章节的已读时间，只认可「标记快照＝当前内容」且章节 `ready`）、`LearnerProgressFor`（阅读分母与分子都只算 `ready` 章节，词条按四种状态分组，`dueNow` 复用 `dueTermsQuery`）。`review.go` 抽出 `dueTermsQuery`，到期复习队列和进度页共用同一谓词与同一服务端时钟，避免两处漂移。`ChapterSummary` 增加 `readAt` 字段，`BookDetail`、`ChapterDetail` 与章节编辑响应都会解析它，所以列表、阅读器和编辑后的状态一致。
学习端新增 `/progress` 页面与导航「进度」（`stores/progress.ts`、`views/ProgressView.vue`）：已读章节、待复习、已知词、学习中、新词、忽略六张卡片，加每本书的已读进度与进入书籍的链接、已保存词条总数、刷新与失败重试、无书时的引导。阅读器正文下方新增显式的「标记本章已读」区块（`ReaderView.vue`，`data-testid="mark-read"`），显示已读时间与重复标记提示；书籍页章节列表对已读章节显示「已读」标记（`BookView.vue`）。`stores/library.ts` 增加 `markChapterRead`，只把 `readAt` 写回章节列表与打开中的阅读器，不动其他字段。
Reference in New Issue View Git Blame Copy Permalink