Table of Contents
LexGo 文档入口
第一次阅读
- 项目档案：已确认使用轻量模式、MySQL 8 和本地 go-admin 管理端；学习端采用 Vue 3 + TypeScript + Vite 独立工程；其余技术候选与范围状态。
- 需求总览、工作量估算：首版闭环与后续范围。
- 架构与代码地图、业务规则。
- 开发工作流、本地开发与验证。
五分钟开始
项目已有账号与独立空间工程基础代码，尚未实现阅读学习业务。当前原型已通过用户验收，已拆 MVP 实施工单并安排技术验证。数据库已确定 MySQL 8，管理端已确定采用指定本地 go-admin/go-admin-ui；不把候选技术建议当作已实现能力。
命令从仓库根目录执行：python dev_scripts/harness.py sync --verify 同步线上页面并校验结构，预期退出码 0；python -m unittest discover -s tests -v 验证治理工具，预期全部通过。产品启动命令尚不存在。
简单修改从哪里开始
先看常见修改和故障排查。轻量局部改动做最小验证；新功能和数据/权限变化建单。长期规则先改 Wiki，再导出镜像。
事实来源
Wiki 保存长期规则，工单保存单次实施与验收，Git 保存源码和镜像。当前工程基础已通过验收，已有调研不等于运行验收。数据库选择以用户确认的 MySQL 8 为准，历史 PostgreSQL 建议不再适用。
原有四份调研资料作为证据页面保留：需求提取、Go 分析、另一份需求提取、另一份 Go 分析。其正文为既有调研记录，不将整份建议视为已批准方案。
初始化记录与流程、接入指南、交付文档指南。不默认创建任务快照。
当前 MVP 讨论入口
已确认定位：支持多账号、数据独立的自托管学习工具，先邀请少量用户使用。需求总览已记录 F01～F12 纳入 MVP，X01～X14 暂不纳入；其他研究功能未获批准。
当前设计阶段
F01～F12 已获用户确认，X 系列暂不纳入。Quant-UX 桌面与手机原型 v1 已通过用户验收；进入四阶段实施准备。默认学习语言为英语，原型文章为虚构样例。
原型制作进度与证据见原型工单 #1。
Quant-UX 原型 v1 已通过用户验收。桌面预览、手机预览。工程基础 #2 已于 2026-09-10 通过用户验收：两端用户名登录、管理员创建/启停/重置学习账号、可撤销会话和本人英语空空间。阅读、导入、词典和复习尚未实现。代码在 feat/2-account-foundation 分支。
当前实施入口
四阶段实施总览 #16。14 张单元工单，预计 52～84 人日；实际产品实现未开始。学习端与管理端均使用账号（用户名）＋密码登录，不要求邮箱。详见需求总览和工作量表。
当前管理端交付
#2 已验收并关闭（记录 7576）。新增 #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 完成章节与个人基础进度已于 2026-09-15 通过用户验收：阅读页正文下方提供显式的「标记本章已读」，只记录已读、不批量改变词语状态；重复标记返回同一条记录、不重复计数。书籍页章节列表显示「已读」，新的「进度」页面显示已读章节（只统计可阅读章节，形如「3 / 8 章（可阅读）」）、待复习、已知词、学习中、新词、忽略与已保存词条数，并按书显示已读进度；待复习与到期复习队列使用同一规则与同一时钟。正文被改成新版本后该章会回到未读（记录保留），重新标记即更新同一条记录；删除章节时记录随之消失。本次新增 schema v7（一张新表），需要显式迁移；开发库迁移前后各表计数一致。真实 API＋MySQL 37 项检查与浏览器页面数字对照数据库直查全部一致；PR #33 已 fast-forward-only 合入 main。
#14 桌面与手机体验、主题与键盘操作已于 2026-09-15 通过用户验收：新增「显示」设置（浅色/深色/跟随系统，正文标准/大/特大），偏好按账号保存在本机，切换账号不会串；阅读位置按账号与章节保留，正文换成新版本后不再套用旧位置；复习页支持空格显示答案、1/2/3 评分，输入框内不会误触快捷键，所有可交互元素有可见焦点环。手机端用 390×844 触摸视口验证八个界面无横向溢出、都能返回、触摸滑动滚动而不误开释义面板，深色与特大字号刷新后保持。本次没有数据库与接口变化；PR #34 已 fast-forward-only 合入 main。真实手机的长按选择与手感仍需人工确认。
#15 自托管试用交付已于 2026-09-15 通过用户验收：备份、恢复与校验同时提供纯二进制子命令（lexgo backup|restore|verify，部署机只需要二进制与 MySQL 客户端）与 Python 工具通道（交叉验证与开发便利），两条通道的 dump 与 manifest 格式一致、可互相恢复；新增运维工具（scripts/ops.py：依赖检查、建空库、备份、恢复、校验、两账号闭环演练；scripts/bench.py：写明规模的人造数据集性能测量）、新的 Wiki 部署与运维页，以及一次完整的本机演练——空库安装（建库 → 迁移 → 首次 bootstrap 建管理员 → 管理员建两个虚构演练账号 → 走通粘贴/阅读/查词/保存/复习/完成章节/进度）、备份 lexgo_dev、恢复到空实例并用第二个 API 实例完成两账号闭环与越权校验，恢复后逐表行数与内容校验和都和源库一致、源库未被改动。备份含全部用户数据（数据库）与环境配置（单独保管凭据），恢复默认只写空库、覆盖需要显式确认与 --force、拒绝写入系统库。性能在 20 章/2000 词条/8000 条作答的人造数据集上实测并记录环境，只作观察不给承诺。两条通道已在本机交叉验证（19 项）；纯二进制安装另有 9 项演练、完整恢复演练 27 项、附件版恢复演练 22 项。真实回滚（升级后切回旧二进制）、HTTPS、多机与定时备份仍未验证，已写入部署页的已知限制。PR #35 已 fast-forward-only 合入 main。
#21 书籍音频与封面附件已于 2026-09-15 通过用户验收：每本书可以上传一张封面（JPG/PNG/WebP，≤2 MiB，≤4096×4096）和一段 MP3（≤20 MiB）；书库卡片显示封面，书籍页新增「音频与封面」区块可上传、替换、移除，阅读页在正文上方显示常驻播放器（播放/暂停、拖动进度、0.75–1.5 倍速），不自动播放、不与文本同步。播放位置按账号与书籍保存，替换或移除音频会重置位置；附件与进度按账号隔离，读取需要会话并支持 HTTP Range。附件存于 MySQL，因此 #15 的备份恢复天然覆盖：2026-09-15 的恢复演练验证了恢复后附件按字节相同地返回且 Range 仍可用。真实浏览器是否解码播放（媒体元素在测试中被桩替换）以及真机听感仍需人工确认。
#37 章节级音频与章节插图已于 2026-09-16 通过用户验收：每章可以上传一段 MP3（≤20 MiB）与一张插图（JPG/PNG/WebP，≤2 MiB、≤4096×4096），封面仍按书；阅读页在正文上方显示本章插图的缩略图、点击后在弹窗里查看原图（书籍页章节列表不显示章节图片），播放器只在本章有音频时出现且不与文本同步，播放位置按「账号＋章节」保存并在切换章节时上报；书籍页的封面压成一行紧凑控件（预览＋上传/替换/移除），书名右侧显示书级作者，「编辑书籍」可改书名与作者，章节列表每行只有一个「编辑」，点开后在同一对话框里编辑标题、作者、正文与本章插图、音频（标题/作者/正文点保存后生效，文件选中后立即上传；阅读页在标题下显示作者）。类型按文件内容判定，读取需会话并支持 HTTP Range 与 ETag；附件存于数据库，包含在 #15 的备份恢复范围内（第三次恢复演练已验证按字节恢复）。schema 已升到 v11（v9 章级附件、v10 章节作者、v11 书籍作者，均需显式迁移），书级音频接口已下线，其实测试期数据在迁移中清空；PR #38 已 fast-forward-only 合入 main。真机听感与浏览器真实解码播放仍需人工确认；书库卡片暂不显示书级作者、章节作者不继承书级作者（两项经确认未实现，如需另开工单）。
#37 章节级音频与章节插图已于 2026-09-15 实施完成，待用户验收：每章可以上传一段 MP3（≤20 MiB）与一张插图（JPG/PNG/WebP，≤2 MiB、≤4096×4096），封面仍按书；阅读页在正文上方显示本章插图的缩略图、点击后在弹窗里查看原图（书籍页章节列表不显示章节图片），播放器只在本章有音频时出现且不与文本同步，播放位置按「账号＋章节」保存并在切换章节时上报；书籍页章节列表显示插图缩略图与「附件」入口，附件编辑与正文编辑分开。类型按文件内容判定，读取需会话并支持 HTTP Range 与 ETag；附件存于数据库，包含在 #15 的备份恢复范围内（第三次恢复演练已验证按字节恢复）。schema v9 需显式迁移，书级音频接口已下线，其实测试期数据在迁移中清空。真机听感与浏览器真实解码播放仍需人工确认。
#37 章节级音频与章节插图已于 2026-09-15 实施完成，待用户验收：每章可以上传一段 MP3（≤20 MiB）与一张插图（JPG/PNG/WebP，≤2 MiB、≤4096×4096），封面仍按书；阅读页在正文上方显示本章插图的缩略图、点击后在弹窗里查看原图（书籍页章节列表不显示章节图片），播放器只在本章有音频时出现且不与文本同步，播放位置按「账号＋章节」保存并在切换章节时上报；书籍页章节列表每行只有一个「编辑」，点开后在同一对话框里编辑标题、正文与本章插图、音频（标题与正文点保存后生效，文件选中后立即上传）。类型按文件内容判定，读取需会话并支持 HTTP Range 与 ETag；附件存于数据库，包含在 #15 的备份恢复范围内（第三次恢复演练已验证按字节恢复）。schema v9 需显式迁移，书级音频接口已下线，其实测试期数据在迁移中清空。真机听感与浏览器真实解码播放仍需人工确认。
#37 章节级音频与章节插图已于 2026-09-15 实施完成，待用户验收：每章可以上传一段 MP3（≤20 MiB）与一张插图（JPG/PNG/WebP，≤2 MiB、≤4096×4096），封面仍按书；阅读页在正文上方显示本章插图的缩略图、点击后在弹窗里查看原图（书籍页章节列表不显示章节图片），播放器只在本章有音频时出现且不与文本同步，播放位置按「账号＋章节」保存并在切换章节时上报；书籍页章节列表每行只有一个「编辑」，点开后在同一对话框里编辑标题、作者、正文与本章插图、音频（标题/作者/正文点保存后生效，文件选中后立即上传；阅读页在标题下显示作者）。类型按文件内容判定，读取需会话并支持 HTTP Range 与 ETag；附件存于数据库，包含在 #15 的备份恢复范围内（第三次恢复演练已验证按字节恢复）。schema v9 需显式迁移，书级音频接口已下线，其实测试期数据在迁移中清空。真机听感与浏览器真实解码播放仍需人工确认。
#37 章节级音频与章节插图已于 2026-09-15 实施完成，待用户验收：每章可以上传一段 MP3（≤20 MiB）与一张插图（JPG/PNG/WebP，≤2 MiB、≤4096×4096），封面仍按书；阅读页在正文上方显示本章插图的缩略图、点击后在弹窗里查看原图（书籍页章节列表不显示章节图片），播放器只在本章有音频时出现且不与文本同步，播放位置按「账号＋章节」保存并在切换章节时上报；书籍页的封面压成一行紧凑控件（预览＋上传/替换/移除），书名右侧显示书级作者，「编辑书籍」可改书名与作者，章节列表每行只有一个「编辑」，点开后在同一对话框里编辑标题、作者、正文与本章插图、音频（标题/作者/正文点保存后生效，文件选中后立即上传；阅读页在标题下显示作者）。类型按文件内容判定，读取需会话并支持 HTTP Range 与 ETag；附件存于数据库，包含在 #15 的备份恢复范围内（第三次恢复演练已验证按字节恢复）。schema v9 需显式迁移，书级音频接口已下线，其实测试期数据在迁移中清空。真机听感与浏览器真实解码播放仍需人工确认。
#40 英汉词典与规范音标已于 2026-09-16 实现并进入待验收：新增第二本英语词典——ECDICT 常用子集（约 8.2 万条中文释义，3.0 MB）与 CMUdict 转写的 IPA 音标。音标分三层来源：能由 CMUdict 音素按固定映射转写的用真 IPA（35,799 条），否则保留 ECDICT 记法仅做字符级规范化并标注来源（30,580 条），两者都不可靠就不显示（16,342 条，例如 grok）；含 ^ 等丢失首音的记法整条丢弃，不做猜测。schema 升到 v12（放开 lexgo_dictionaries 单行 CHECK、增加 provider 列，两步都带条件守卫、可重放），英英与英汉词典可分别启停，查词时中文释义在前、英英释义随后，屈折形经 WordNet lemma 解析后也能看到中文释义但不会复制词目音标。归档由 scripts/dict_prepare.py 从 sha256 pin 的三个源显式准备（运行时不联网，产物不入库，仓库只保存 pin 与两份许可证），整包存进 MySQL 因而包含在 #15 的备份范围内。测试：Go 96 项、学习端 159 单测与 26 项 e2e（含 390×844 触摸视口）、管理端 32 项、真实 API 28 项检查；PR #41 已合入 main，并由用户于 2026-09-16 验收通过。发音音频、整句翻译与汉英方向不在本单范围。
#42 登录有效期已于 2026-09-16 由 8 小时改为 30 天（学习端与管理端共用同一登录接口，一处生效）：有效期提取为具名常量 SessionLifetime，仍然是绝对有效期、不做滑动续期，撤销规则不变（退出只撤销当前会话，改密码/停用/重置撤销该账号全部会话，服务端只存 SHA-256 摘要）。代价是令牌泄露后的可用窗口放大约 90 倍；设备/会话列表与"退出其他设备"未包含在本单，如需另开工单。无数据库结构变化，旧会话按各自到期时间自然过渡；测试：Go 92 项（新增 1 项锁定 30 天与摘要存储，并把过期断言改为按常量计算）；PR #43 已合入 main，并由用户于 2026-09-16 验收通过。