lexgo/docs/linguacafe-requirements.md

generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: LinguaCafe-Requirements-Alternative wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/LinguaCafe-Requirements-Alternative.- wiki_revision: 55fdebd66e3c1ece8c7dae81ca8639f5a8be5388 synchronized_at: 2026-09-10T06:27:50Z

LinguaCafe 需求提取

调研日期：2026-09-10。目标项目：LexGo（Go 复刻方案）。本文提取上游需求，不代表已实现或已完成运行验收。

1. 基线与证据

本次实际拉取并静态检查了 LinguaCafe 的 main 分支，固定提交为 c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8，提交日期为 2025-03-19。调研日期不等于源码发布日期；本文不宣称这是某个最新稳定发行版。检查范围包含仓库手册、路由、管理页面、业务服务、依赖清单及 Python 文本处理代码，没有启动原版容器进行端到端验证。

证据索引均指向这个固定提交：

编号	来源	用途
S1	README	产品定位、语言范围、部署限制
S2	Usage and features	阅读、复习、词汇和界面行为
S3	Setup	多用户限制、语言、词典、集成和备份
S4	Web 路由	可访问功能及管理权限分组
S5	管理页面	管理端实际导航
S6	Python 处理器	分词、EPUB、字幕、网页导入
S7	ReviewService	用户隔离、到期词筛选及练习模式
S8	FAQ	删除来源后的词汇保留
S9	导入校验	章节长度接口约束

下文“已有”表示手册明确描述或源码存在实现入口，不保证所有第三方服务今天仍可用。“建议”表示 Go 版的产品或工程选择。优先级是本次建议：P0 为首个可用版本，P1 为主要功能对齐，P2 为后续完整度补齐。

2. 产品目标与核心流程

LinguaCafe 是自托管的外语阅读和词汇学习工具。用户导入自己想读的材料，在上下文中查词、保存释义和短语，再通过复习巩固；书籍生词统计帮助判断阅读难度。[S1][S2]

主流程：选择语言 → 导入材料 → 生成书籍和章节 → 文本处理 → 阅读与查词 → 保存单词/短语 → 到期复习 → 查看每日目标和累计进度。

“书籍”是内容容器，可装文章、字幕、播客文字稿等，并不限于出版物。现有证据不支持把自动语音识别、PDF OCR、付费课程、社交社区列为原版必备功能。[S2][S6]

3. 多用户现状：必须保留的资料冲突

README 写着每台服务器仅支持一个用户；同一提交的 Setup 手册却明确写着已经新增多用户支持，并列出未完成事项。源码存在用户管理页面、is_admin 权限检查，复习查询也按 user_id 过滤。[S1][S3][S4][S5][S7]

因此，本次结论是：原版已有多用户和管理员基础，但多用户体验及集成尚不完整。既不能称为完全没有多用户，也不能称为成熟多租户系统。

手册明确的限制包括：用户删除尚未完成；Anki 经服务器连接，不适合多个用户各自使用桌面 Anki；部分浏览器本地设置在同设备不同用户之间共享。管理员 API 页面也提示多用户部署时可能需要禁用 Jellyfin。[S3；API 设置源码]

4. 用户端功能需求

ID	模块	提取的需求与关键行为	证据	建议阶段
U01	账号	登录、退出、修改密码；可选择学习语言	S4	P0
U02	语言隔离	切换语言后显示对应阅读内容、词汇及学习数据	S3、S7	P0
U03	内容库	创建、编辑、删除书籍和章节，支持向已有书籍添加章节	S2、S4	P0
U04	难度统计	书籍与章节显示唯一词、已知词、高亮词及新词统计	S2	P0
U05	文本导入	粘贴文本、上传文本文件，导入前可编辑内容	S2	P0
U06	电子书导入	解析 EPUB 并生成章节；不能将“电子书”泛化为任意格式	S2、S6	P1
U07	网页导入	输入网址提取正文、编辑后导入；受语言和网页结构限制	S2、S6	P1
U08	字幕导入	上传字幕文件，或者读取 YouTube 字幕、Jellyfin 外部字幕	S2、S6	文件 P1，在线集成 P2
U09	文本处理	支持 Simple/Detailed 模式、按长度切章；详细模式按语言提供词元、读音、语法信息	S2、S3、S6	基础 P0，逐语言增强 P1
U10	处理状态	章节异步处理，提供状态更新及失败重试入口	S4；app/Jobs/ProcessChapter.php	P0
U11	阅读器	按词汇状态高亮；点词查词，鼠标连续选择创建短语，支持快捷键	S2	P0
U12	查词界面	桌面侧栏、弹窗、移动端底部抽屉、悬停简版；不同界面查询策略有差别	S2	点击与移动端 P0，悬停 P1
U13	释义保存	保存或编辑单词/短语释义、读音、学习等级及例句；支持手工释义	S2、S4	P0
U14	词汇状态	New、Learning、Known、Ignored；学习等级展示为 1—7，Known 为 0；Ignored 不计已学词	S2	P0
U15	章节完成	完成阅读时更新阅读统计；可配置是否把章节内新词批量标为已知	S2	P0
U16	词汇检索	按文字、等级、书籍、章节、释义、单词/短语过滤；编辑与 CSV 导入导出	S4	搜索编辑 P0，CSV P1
U17	SRS	类 Leitner 的间隔复习；范围可为全部、一本书或一章	S2、S7	P0
U18	练习模式	不按正常到期队列限制练习，且不改变正常复习数据	S2、S7	P1
U19	目标与统计	每日阅读、标记、复习目标，日历及累计统计，可编辑目标和完成记录	S2、S4	P1
U20	Anki	通过 AnkiConnect 添加卡片；已有词条可更新释义、读音和例句，受网络及单用户式配置限制	S3、S4、API 设置源码	P2
U21	TTS	阅读器与复习页使用浏览器 SpeechSynthesis，按语言选语音，可用性取决于浏览器	S2	P1
U22	日语扩展	汉字查询、详情、部首等信息；部分能力依赖导入 JMDict 相关数据	S2、S3、S4	P2，日语优先时提前
U23	外观	浅色、深色、墨水屏主题；颜色、字体和阅读/复习显示可调整	S2	基础主题 P0，其余 P1
U24	多设备	手机、平板和桌面布局，手册目标最小宽度 340px；支持添加到主屏幕的 PWA 体验	S2	响应式 P0，PWA P1
U25	数据保留	删除导入来源不应顺带清除已经积累的词汇	S8	P0
U26	帮助	用户手册、更新记录、资源署名页面	S4	P1

阅读和复习语义

界面中的学习等级不能直接当作数据库编码。手册写 1—7，而 ReviewService 用 stage < 0 筛选学习词。Go 版需要建立明确的状态映射，迁移前核对全部编码、下次复习时间和 relearning 行为，不能简单复制正整数等级。[S2][S7]

原版提到“完成章节”操作难以撤销。因此 Go 版建议将阅读完成事件与批量改词状态分开记录，防止重试重复计数；是否提供撤销属于增强需求。

普通查词优先使用可用的 lemma，并展示词典结果；悬停查词更精简，偏向精确匹配。自动生成的中文、日文读音可能错误，应保留原文、机器读音和人工修订的区别。[S2]

5. 管理端功能需求

管理端不是推测：原版页面明确包含 Dashboard、Users、Languages、Dictionaries、Fonts、API、Reviews 七个入口，后端路由也有 admin 中间件保护。[S4][S5]

ID	模块	已有需求	建议阶段
A01	管理权限	管理员才能访问系统级设置和管理 API	P0
A02	用户管理	查看、创建、编辑用户；用户删除不能标为原版已完成	P0，删除为增强
A03	语言管理	查看已安装语言、下载并安装模型；上游手册描述的卸载粒度较粗	P0
A04	本地词典	导入官方支持的词典数据、自定义 CSV，查看记录数，编辑和删除词典配置	P0
A05	在线词典	DeepL、MyMemory、LibreTranslate、自定义 API 配置；支持查询及相关用量信息	适配一个 P1，其余 P2
A06	字体管理	上传、编辑、删除字体，配置适用语言	P1
A07	集成设置	管理翻译接口、AnkiConnect、Jellyfin 的地址、开关及凭据	P1—P2
A08	复习设置	配置 SRS 规则和复习间隔	P0
A09	备份	管理页面触发备份；部署支持定时数据库备份和保留策略	P1

此表证据为 S3—S5。Go 版建议新增任务失败详情、重试、运行健康信息和操作审计；这些不应描述为上游已具备完整运维平台。

6. 语言与导入边界

上游列出的 27 种语言：中文、克罗地亚语、捷克语、丹麦语、荷兰语、英语、芬兰语、法语、德语、希腊语、意大利语、日语、韩语、拉丁语、马其顿语、挪威语、波兰语、葡萄牙语、罗马尼亚语、俄语、斯洛文尼亚语、西班牙语、瑞典语、泰语、土耳其语、乌克兰语、威尔士语。[S1][S3]

支持语言不等于每种语言都具有同等分词、lemma、性别标注、词典和翻译能力。上游手册限定中文为普通话和简体字；Go 版如增加繁体应列为扩展。第三方翻译的今日语言覆盖与配额不直接沿用旧手册。[S3]

另一个资料冲突：手册称默认每章 3000 字符、最高 15000；导入请求校验允许 200—20000。Go 版建议先用默认 3000、统一上限 15000，前后端共用契约；此值为设计建议，不是对原版实际 UI 上限的运行结论。[S2][S9]

已核实电子书解析针对 EPUB；PDF、MOBI、扫描件 OCR 没有在本次检查中得到支持证据。字幕功能已核实，但完整扩展名清单仍需按上游解析依赖及测试样本验证，不承诺任意字幕格式。[S6]

7. Go 版质量要求与验收建议

以下是复刻工程的建议性验收标准，不是上游性能承诺。

ID	验收场景	通过条件
Q01	阅读闭环	导入文本后可打开章节，查词、保存释义、改等级、进入到期复习
Q02	数据隔离	A 用户不能通过替换书籍、章节、词汇、任务或附件 ID 访问 B 用户数据；后台权限由服务端检查
Q03	语言隔离	同形字符串在不同语言的学习状态互不影响
Q04	Unicode	中文、日文、组合字符和 emoji 的高亮、选词、短语边界不发生错位
Q05	复习确定性	固定时间与输入时，调度输出可重现；Known/Ignored 不进入正常队列，练习不改调度
Q06	幂等	重试导入、重复提交复习、重复点击章节完成不产生重复内容或统计
Q07	保留词汇	删除书籍后已积累的词汇仍可检索；来源缺失时例句显示有明确策略
Q08	失败处理	模型未安装、词典为空、外部服务超时和损坏 EPUB 均显示可理解的失败原因
Q09	移动交互	340px 宽度下可阅读、打开查词及保存；触摸选择与页面滚动不冲突
Q10	备份恢复	新实例恢复数据库和文件后，能登录、读书、查词和复习；备份不能只验证文件存在
Q11	导入安全	富文本清理、压缩包大小和路径检查、URL 抓取的内网访问限制、凭据脱敏
Q12	性能	以默认章节、15k 字符章节、大词典和多人并发建立基准；先测 p95 延迟及内存，再设发布阈值

8. 首版范围与后续范围

首版建议至少支持英语，使用单个管理员账号跑通核心闭环，但数据结构从第一天保留 user_id；若首版开放多个账号，Q02 必须先通过。英语先行只是降低变量的默认建议，尚未由用户指定；面向日语用户时应优先建设日语分词与词典能力。

P0：账号、语言选择、文本导入、章节处理、阅读高亮、查词、单词和短语、基础 SRS、最小管理区。

P1：EPUB/字幕文件/网页导入、CSV、目标日历、TTS、字体、PWA、备份恢复、更多语言与词典。

P2：YouTube、Jellyfin、Anki 的完整接入、汉字部首等专门功能，以及更完整的多用户运营管理。

用户删除、配额、公共书库、多租户、计费、AI 讲解、云端 TTS、离线同步、FSRS 均应明确列为扩展；P0 完成不能称为完整复刻。

对应技术分析见 Go 复刻与框架选型。