ila
a9952b3516
- 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 与需求更新
87 lines
11 KiB
Markdown
87 lines
11 KiB
Markdown
<!-- gitea-wiki-mirror:start -->
|
||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||
wiki_page: Home
|
||
wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Home
|
||
wiki_revision: 9ee88d82494e22e689086b053770c4f4620d3657
|
||
synchronized_at: 2026-09-15T04:31:22Z
|
||
<!-- gitea-wiki-mirror:end -->
|
||
|
||
# LexGo 文档入口
|
||
|
||
## 第一次阅读
|
||
|
||
1. [项目档案](https://git.ilapage.cn/OPC/lexgo/wiki/Project-Profile.-)：已确认使用轻量模式、MySQL 8 和本地 go-admin 管理端；学习端采用 Vue 3 + TypeScript + Vite 独立工程；其余技术候选与范围状态。
|
||
2. [需求总览](https://git.ilapage.cn/OPC/lexgo/wiki/Product-Requirements-Overview.-)、[工作量估算](https://git.ilapage.cn/OPC/lexgo/wiki/Workload-Estimate.-)：首版闭环与后续范围。
|
||
3. [架构与代码地图](https://git.ilapage.cn/OPC/lexgo/wiki/Architecture-and-Code-Map.-)、[业务规则](https://git.ilapage.cn/OPC/lexgo/wiki/Business-Rules-and-Glossary.-)。
|
||
4. [开发工作流](https://git.ilapage.cn/OPC/lexgo/wiki/Development-Workflow.-)、[本地开发与验证](https://git.ilapage.cn/OPC/lexgo/wiki/Local-Development-and-Verification.-)。
|
||
|
||
## 五分钟开始
|
||
|
||
项目已有账号与独立空间工程基础代码，尚未实现阅读学习业务。当前原型已通过用户验收，已拆 MVP 实施工单并安排技术验证。数据库已确定 MySQL 8，管理端已确定采用指定本地 go-admin/go-admin-ui；不把候选技术建议当作已实现能力。
|
||
|
||
命令从仓库根目录执行：`python dev_scripts/harness.py sync --verify` 同步线上页面并校验结构，预期退出码 0；`python -m unittest discover -s tests -v` 验证治理工具，预期全部通过。产品启动命令尚不存在。
|
||
|
||
## 简单修改从哪里开始
|
||
|
||
先看[常见修改](https://git.ilapage.cn/OPC/lexgo/wiki/Common-Changes.-)和[故障排查](https://git.ilapage.cn/OPC/lexgo/wiki/Troubleshooting)。轻量局部改动做最小验证；新功能和数据/权限变化建单。长期规则先改 Wiki，再导出镜像。
|
||
|
||
## 事实来源
|
||
|
||
Wiki 保存长期规则，工单保存单次实施与验收，Git 保存源码和镜像。当前工程基础已通过验收，已有调研不等于运行验收。数据库选择以用户确认的 MySQL 8 为准，历史 PostgreSQL 建议不再适用。
|
||
|
||
原有四份调研资料作为证据页面保留：[需求提取](https://git.ilapage.cn/OPC/lexgo/wiki/LinguaCafe-Requirements.-)、[Go 分析](https://git.ilapage.cn/OPC/lexgo/wiki/Go-Architecture-Analysis.-)、[另一份需求提取](https://git.ilapage.cn/OPC/lexgo/wiki/LinguaCafe-Requirements-Alternative.-)、[另一份 Go 分析](https://git.ilapage.cn/OPC/lexgo/wiki/Go-Analysis-Alternative.-)。其正文为既有调研记录，不将整份建议视为已批准方案。
|
||
|
||
[初始化记录与流程](https://git.ilapage.cn/OPC/lexgo/wiki/New-Project-Documentation-Setup.-)、[接入指南](https://git.ilapage.cn/OPC/lexgo/wiki/Existing-Project-Adoption-Guide.-)、[交付文档指南](https://git.ilapage.cn/OPC/lexgo/wiki/Delivery-Documentation-Guide.-)。不默认创建任务快照。
|
||
|
||
## 当前 MVP 讨论入口
|
||
|
||
已确认定位：支持多账号、数据独立的自托管学习工具，先邀请少量用户使用。[需求总览](https://git.ilapage.cn/OPC/lexgo/wiki/Product-Requirements-Overview.-)已记录 F01～F12 纳入 MVP，X01～X14 暂不纳入；其他研究功能未获批准。
|
||
|
||
## 当前设计阶段
|
||
|
||
F01～F12 已获用户确认，X 系列暂不纳入。Quant-UX 桌面与手机原型 v1 已通过用户验收；进入四阶段实施准备。默认学习语言为英语，原型文章为虚构样例。
|
||
|
||
原型制作进度与证据见[原型工单 #1](https://git.ilapage.cn/OPC/lexgo/issues/1)。
|
||
|
||
Quant-UX 原型 v1 已通过用户验收。[桌面预览](https://qux.ilapage.cn/#/simulate.html?h=a2aa10as5WpKpxe9fjDXETLqmigWeGWqsSjGmNmERlfgTpjXambHTDwagN8C&s=true&log=false)、[手机预览](https://qux.ilapage.cn/#/simulate.html?h=a2aa10aFDLzpVy0xPE70ftx5adTPyjWy5bj6nhPk2kDkJEwtIf1GiZjqx1n6&s=true&log=false)。工程基础 #2 已于 2026-09-10 通过用户验收：两端用户名登录、管理员创建/启停/重置学习账号、可撤销会话和本人英语空空间。阅读、导入、词典和复习尚未实现。代码在 feat/2-account-foundation 分支。
|
||
|
||
|
||
## 当前实施入口
|
||
|
||
[四阶段实施总览 #16](https://git.ilapage.cn/OPC/lexgo/issues/16)。14 张单元工单，预计 52～84 人日；实际产品实现未开始。学习端与管理端均使用账号（用户名）＋密码登录，不要求邮箱。详见需求总览和工作量表。
|
||
|
||
|
||
## 当前管理端交付
|
||
|
||
#2 已验收并关闭（记录 7576）。新增 [#18 登录日志与操作审计](https://git.ilapage.cn/OPC/lexgo/issues/18)，已通过用户验收，列入 #16 的试用前准备。管理端提供登录日志、操作日志查询，默认保留 90 天；数据库为显式迁移后的 schema v2。代码分支 feat/18-audit-logs，基于已验收的 feat/2-account-foundation；#17 尚未合并，因此新 PR 以该基础分支为目标，保持差异只含 #18。
|
||
|
||
|
||
日志审计 #18 于 2026-09-10T20:40:04+08:00 获用户验收并关闭；#16 已更新完成索引。该验收时 #3/#4 尚未开始。
|
||
|
||
|
||
英语分词/原文定位/本地词典 #3 独立可运行小样已通过用户验收并关闭。代码与复现命令位于 spikes/english；临时入口 http://127.0.0.1:5183/。推荐 Python spaCy 英语模型与 WordNet 3.0 的离线组合；尚未接入正式学习端。
|
||
|
||
|
||
#4 阅读选择小样已实现桌面鼠标/键盘、范围调整与原文位置验证，入口 http://127.0.0.1:5184/；固定版本 LinguaCafe 四项源码对照已记录。用户已验收并关闭 #4；真实手机详细测试证据仍缺失，详见本地验证页。#21 仍待实施。
|
||
|
||
#5 粘贴导入与章节阅读已实现，待用户验收：schema v3 新增 books/chapters/ingest_jobs，学习端具备粘贴导入、书库、处理状态与原文阅读；查词、词典与复习仍未实现。本单按 Go 处理，Go＋Python NLP 与全 Go 路线仍未决，正式接入前须用户确认。
|
||
|
||
|
||
## 当前进度（2026-09-11）
|
||
|
||
#5已验收，#17/#19/#20/#22/#23按依赖顺序合入main。#6已按用户确认的全Go方向实现英语词典与阅读点词，2026-09-11通过用户验收，PR #25已合入main；原文/账户隔离保留。正式NLP不使用Python服务。管理端“英语词典”导入指定WordNet3.0，学习端打开本人章节即可查词。个人释义与学习状态已实现持久化（#7，待用户验收）。详见#6工单、架构和本地开发页面。
|
||
|
||
#7 个人词条已实现并于 2026-09-11 通过用户验收（schema v5 新增 lexgo_terms）：阅读器可保存释义、例句与状态，同一词形在本人其他章节显示一致高亮，两个账号数据独立；保存幂等，跨账号与篡改身份均被拒绝；PR #26 已 fast-forward-only 合入 main。
|
||
|
||
#8 单词到期复习已于 2026-09-11 通过用户验收（schema v6 新增 lexgo_term_reviews 与 lexgo_review_answers）：固定间隔表（1/2/4/7/15/30/60 天）、答对升级、答错或再学立即回队、已知与忽略不入队；重复提交、网络重发与双标签页都只记账一次，到期判定用 UTC 绝对时刻而不引入本地日边界。学习端新增「到期复习」入口，卡片正面显示词与挖空例句、答案面显示个人释义，并有完成页与空队列页。独立审核指出的并发同键 500、编辑文本重排复习与面板保存重置等级三项已整改并复测；PR #27 已 fast-forward-only 合入 main。第 3 阶段「首条学习闭环」#5～#8 全部验收。
|
||
|
||
#9 TXT 文件导入已于 2026-09-13 通过用户验收：导入页新增「粘贴文本 / TXT 文件」来源切换，只接受 UTF-8（允许可选 BOM）且不替换损坏字符，UTF-16 与其他编码会被明确拒绝；文件只在内存中解码、不写临时文件，客户端文件名不参与任何路径也不入库；上传与粘贴共用同一分章、任务与幂等规则，重复上传同一文件只产生一章。本次没有数据库结构变化；PR #28 已 fast-forward-only 合入 main。
|
||
|
||
#10 编辑与删除书籍章节已于 2026-09-14 通过用户验收：可改书名、改章节标题、编辑章节正文并按新版本重新处理，也可用确认弹窗删除章节或整本书。编辑正文产生明确版本，旧处理结果会被标为 superseded 而不覆盖新版本；删除在事务内完成并重排剩余章节序号，已保存的个人词条、复习排期与作答记录一律保留。本次没有数据库结构变化；旧处理结果不会覆盖新版本，PR #29 已 fast-forward-only 合入 main。
|
||
|
||
#11 短语选择、保存与复习已于 2026-09-14 通过用户验收：在正文中连续选择一个范围（桌面原生拖选、手机系统手柄、面板端点按钮与 Shift 点击调整），保存个人释义与状态；短语与单词共用同一张表、同一到期队列与同一套幂等作答，因此同一短语在不同章节只存一条记录并在出现的每处高亮，复习卡片把整段短语挖成一个空。短语与单词重叠时短语高亮覆盖、单词数据不变；编辑正文后短语不再出现时不报错，词条与复习排期保留。本次没有数据库结构变化；用户确认 kind 与词数由身份键派生，PR #30 已 fast-forward-only 合入 main。
|
||
|
||
#12 词汇库的搜索、筛选与编辑已于 2026-09-15 通过用户验收：生词本分页列出本人保存的词语与短语，可按关键词（匹配词形、原文或个人释义，大小写不敏感）与状态/类型筛选，并可编辑释义、例句、状态与 1～7 学习等级。编辑沿用与阅读器相同的领域规则：身份不可改、只有状态或等级变化才重排复习时间、历史作答记录保留；筛选与页码写入 URL，刷新或返回列表都保留。原型的「来自某章节」不实现，因为词条按身份存储、不引用章节。本次没有数据库结构变化；PR #31 已 fast-forward-only 合入 main。
|
||
|
||
#13 完成章节与个人基础进度已实现，待用户验收：阅读页正文下方提供显式的「标记本章已读」，只记录已读、不批量改变词语状态；重复标记返回同一条记录、不重复计数。书籍页章节列表显示「已读」，新的「进度」页面显示已读章节（只统计可阅读章节，形如「3 / 8 章（可阅读）」）、待复习、已知词、学习中、新词、忽略与已保存词条数，并按书显示已读进度；待复习与到期复习队列使用同一规则与同一时钟。正文被改成新版本后该章会回到未读（记录保留），重新标记即更新同一条记录；删除章节时记录随之消失。本次新增 schema v7（一张新表），需要显式迁移；开发库迁移前后各表计数一致。真实 API＋MySQL 37 项检查与浏览器页面数字对照数据库直查全部一致。
|