LinguaCafe 功能需求提取
调研日期：2026-09-10。用途：作为 LexGo 使用 Go 复刻 LinguaCafe 的需求基线。
1. 调研基线与可信边界
目标仓库：simjanos-dev/LinguaCafe。本次实际读取 main 的提交 c1ea298ce40c65b9dd33e9b26fd2e52fae66f2c8，提交时间为 2025-03-19T21:17:36+01:00，消息为 add: update notes。日期代表本次获取的提交，不代表已经核实所有分支或镜像版本。
方法：阅读仓库手册、路由、管理页面、业务服务、模型、Python 文本处理器和依赖清单，并参考官方 Wiki。本次没有启动原版进行端到端测试；“已确认”表示有文档或代码证据，不表示所有外部集成在今天仍可运行。
原仓库只读参考副本：D:/opc_project/linguacafe-reference。本目录只保存需求和分析，不包含复刻实现。
证据索引（以下源码链接均固定到本次提交）：
| 编号 | 来源 | 用途 |
|---|---|---|
| S1 | README | 定位、语言清单、声明与资源归属 |
| S2 | 使用手册 | 导入、阅读、词汇、复习、主题与目标 |
| S3 | 安装和配置手册 | 多用户限制、语言、词典、Anki、备份 |
| S4 | Web 路由 | 页面/API 和管理员权限边界 |
| S5 | 管理页面 | 管理区真实菜单 |
| S6 | 文本处理器 | 分词、EPUB、字幕、网页、语言模型接口 |
| S7 | 词汇服务 | CSV 格式、状态编码、短语与检索 |
| S8 | 复习查询、单词调度、复习界面 | 到期筛选、等级、重学、练习模式 |
| S9 | 导入服务、后台任务 | 文本处理任务与章节生成 |
| S10 | Compose | 部署组件、备份计划 |
| S11 | 管理员中间件 | 服务端 is_admin 校验 |
关键冲突：并非完全没有多用户或管理端
S1 仍写着每台服务器仅支持一个用户；S3 明确描述已增加多用户支持及其限制。S4、S5、S11 也存在用户管理、管理员判断和管理页面，S8 查询按用户隔离。
因此，本报告将其归纳为：有多用户基础和管理区，但多用户支持尚不完整，不能按成熟多租户平台理解。 不能只依据 README 判定“只有单用户”，也不能因为有用户表就推定完整隔离已通过验证。
2. 产品定位与主要流程
LinguaCafe 是自托管的外语阅读和词汇学习工具。核心闭环是：导入感兴趣的材料 → 选择适合难度的章节 → 阅读时查询并保存词语 → 在上下文中复习 → 查看学习进展。
“书籍”是内容集合，可以是小说，也可以是新闻、播客文本或字幕集合；“章节”是可阅读、可处理、可统计的内容单位。它不是以课程售卖、直播教学或考试为中心的 LMS。
角色有普通学习者和实例管理员；个人部署时，同一个账号可以同时承担两种职责。原版未证实教师、组织管理员、付费会员等角色。
典型流程：
- 管理员完成账号、目标语言、语言模型和词典配置。
- 学习者选择语言，导入内容到新书或已有书，等待章节处理。
- 根据新词、已知词和学习中词汇数量选择章节。
- 阅读时点词、划选短语，保存释义、读音或例句并调整学习状态。
- 完成章节，更新阅读统计；按设置批量将新词标为已知。
- 按全库、书籍或章节范围复习，或仅练习而不改变复习数据。
- 查看每日目标、日历和累计统计，必要时导出词汇或发送 Anki。
3. 用户端功能清单
优先级是 LexGo 的实施建议，并非上游优先级。P0 为首个可用闭环；P1 为主要功能补齐；P2 为专项语言或外部集成补齐。完整复刻需要覆盖 P0～P2。
| ID | 模块 | 原版需求/行为 | 建议优先级 | 证据 |
|---|---|---|---|---|
| U01 | 身份与偏好 | 登录、修改密码、选择学习语言、个人设置；具有用户管理基础 | P0 | S3、S4 |
| U02 | 内容库 | 创建、修改、删除书籍和章节，管理封面，进入章节阅读/编辑 | P0 | S2、S4 |
| U03 | 难度提示 | 书籍和章节展示独立词、已知词、高亮词、新词等数量 | P0 | S2 |
| U04 | 文本导入 | 粘贴文本、上传文本文件；新建书籍或追加章节 | P0 | S2、S9 |
| U05 | 电子书导入 | 导入 EPUB 并分章；不能由“ebook”推定支持 PDF、MOBI | P1 | S2、S6 |
| U06 | 网页导入 | 输入 URL 提取正文，编辑后入库；有语言/网站适用限制 | P1 | S2、S6 |
| U07 | 字幕导入 | 字幕文件、YouTube 字幕、Jellyfin 外部字幕；保留字幕时间信息的处理路径 | 文件 P1，远程 P2 | S2、S6、S9 |
| U08 | 导入设置 | Simple/Detailed 处理选项与章节长度设置；手册默认 3000、上限 15000 字符 | P0 | S2 |
| U09 | 后台处理 | 章节异步处理，处理状态更新，失败章节重试入口 | P0 | S4、S9 |
| U10 | 阅读器 | 按词语状态高亮文本、切换章节、选择词语、快捷键操作 | P0 | S2 |
| U11 | 词语浮层 | 侧栏、弹窗、移动端底部面板、鼠标悬停四种查询呈现 | 主查询 P0，完整形态 P1 | S2 |
| U12 | 词汇保存 | 保存/修改释义、读音、学习等级、例句；可以标记已知或忽略 | P0 | S2、S4 |
| U13 | 短语 | 连续选择多个词创建短语，保存释义与等级，并在文本中识别 | P0 | S2、S7 |
| U14 | 词典查询 | 导入词典查词；有 lemma 时可用于查词；普通面板可部分匹配，悬停以精确匹配为主 | P0 | S2 |
| U15 | 在线翻译 | DeepL、LibreTranslate、MyMemory、自定义 API 的配置和查询路径 | P1 | S3、S4 |
| U16 | 完成阅读 | 更新阅读数据，可将章节新词批量置为已知；允许关闭自动置已知 | P0 | S2 |
| U17 | 复习 | SRS、全库/书/章节筛选、单词和短语、答对/答错、重学处理 | P0 | S2、S8 |
| U18 | 练习模式 | 不改变复习数据地练习词汇 | P1 | S2、S8 |
| U19 | 词汇库 | 搜索、筛选、排序、编辑词和短语，CSV 导入/导出 | 查询编辑 P0，CSV P1 | S4、S7 |
| U20 | Anki | 经 AnkiConnect 添加卡片；可配置相关连接与卡片字段 | P2 | S3、S4 |
| U21 | 学习目标 | 每日阅读、标记词语、复习目标；日历进展、累计统计及日历数据修改 | P0 | S2、S4 |
| U22 | 朗读 | 阅读/复习页面使用浏览器 SpeechSynthesis，可按语言选择声音 | P1 | S2 |
| U23 | 汉字与读音 | 日语汉字、部首信息；日语/中文机器读音可供显示和人工修正 | P2 | S2、S4、S6 |
| U24 | 外观 | 浅色、深色、电子墨水屏主题，自定义颜色和字体 | 基础主题 P0，完整定制 P1 | S2 |
| U25 | 移动访问 | 响应式布局与 PWA 添加到主屏；手册声明屏幕宽度至少 340px | 响应式 P0，PWA P1 | S2 |
| U26 | 数据维护 | 删除本人某语言学习数据；帮助、更新说明、资源归属入口 | P1 | S4 |
3.1 词语状态与复习规则不能简化成普通生词本
原版 CSV 和内部编码映射如下（S7）：
| 业务状态 | CSV 表达 | 原版内部 stage |
|---|---|---|
| 新词 | new |
2 |
| 忽略 | ignored |
1 |
| 已知 | learned |
0 |
| 学习等级 1～7 | 1～7 |
-1～-7 |
等级越接近 0 越接近学会。忽略词不算学会的词。原版把状态和等级合并编码；Go 可以改成显式状态加等级，但 CSV 和迁移层必须保留正确映射。
S8 表明：正常复习选取学习状态、到期或重学词条；练习模式不要求到期。答对可能清除重学标记或向 0 前进，答错可能退级并进入重学。单词模型按当前等级配置的候选间隔，选择已有复习数量较少的日期；这不是简单的固定间隔表，也不能直接称为 FSRS。
要逐项对齐原版时，还需覆盖短语调度与单词调度的差异、同日重学、时区、重复提交及边界等级。以上是已提取的规则概要，不是完整状态机测试结果。
3.2 词典及语言数据
词典数据与用户保存释义是不同概念：前者是可复用查询资源，后者是个人学习记录。悬停结果还区分个人释义、字典结果和在线翻译。读音或词形还原可能出错，需要保留原词、来源和人工修正能力。（S2、S3）
S1 列出 27 种语言：中文、克罗地亚语、捷克语、丹麦语、荷兰语、英语、芬兰语、法语、德语、希腊语、意大利语、日语、韩语、拉丁语、马其顿语、挪威语、波兰语、葡萄牙语、罗马尼亚语、俄语、斯洛文尼亚语、西班牙语、瑞典语、泰语、土耳其语、乌克兰语、威尔士语。
“支持一种语言”不代表该语言同时具有高质量分词、lemma、词性、性别标注、读音、离线词典和所有翻译服务。S3 的支持矩阵应转换为可配置的能力字段；首期只承诺经过验收的语言组合。
3.3 CSV 互通
原版词汇导入字段按顺序为 Word、Translation、Lemma、Reading、Lemma reading、Level；至少提供 Word。支持跳过首行、仅更新已存在词条，并报告创建、更新、拒绝数量。缺少某列与显式空值语义不同：未提供字段保留旧值，提供空值可能清空旧值。（S3、S7）
Go 版兼容导入必须测试这些差异；词汇 CSV 不包含全部书籍、设置和复习历史，不能作为完整备份格式。
4. 管理端功能清单
S5 的真实菜单为 Dashboard、Users、Languages、Dictionaries、Fonts、API、Reviews。管理区已存在，应复刻其职责。
| ID | 模块 | 已确认的职责 | 建议优先级 | 证据 |
|---|---|---|---|---|
| A01 | 管理员访问 | 服务端管理员权限检查，受限管理页面/API | P0 | S4、S11 |
| A02 | 用户管理 | 创建/查看/更新用户；手册说明用户删除仍缺失 | P0 | S3、S4、S5 |
| A03 | 语言管理 | 安装、查看语言模型；原版手册说明卸载是整体卸载已安装语言 | P0 | S3、S4 |
| A04 | 词典管理 | 支持的词典导入、CSV 测试/导入、编辑/删除、条目数量查询 | 基础 P0，格式补齐 P1 | S4 |
| A05 | 翻译 API | DeepL/LibreTranslate/MyMemory/自定义 API 配置；有 DeepL 用量查询 | P1 | S3、S4 |
| A06 | 字体管理 | 上传、编辑、删除字体；指定字体适用语言 | P1 | S2、S4 |
| A07 | 复习设置 | 配置复习等级对应间隔等参数 | P0 | S2、S5、S8 |
| A08 | 集成设置 | Anki、Jellyfin 等连接配置 | P2 | S3、S5 |
| A09 | 系统设置 | 全局设置读写及管理概览 | P0 | S4、S5 |
| A10 | 备份 | 创建数据库备份、计划备份；完整恢复还依赖文件数据 | P0 | S3、S4、S10 |
不应把业务词典与后台框架的“数据字典”混为一谈。前者处理大量语言词条、释义、词形和来源；后者通常只是性别、状态等枚举选项。
5. 非功能要求与已知限制
原版可观察约束
- 自托管：存在 Web、MySQL、Redis、Python 文本服务等组件。（S10）
- 长文本性能：手册提示过长章节拖慢阅读器；短语新增会涉及已导入文本索引，内容量大时可能变慢。（S2）
- 多用户限制：Anki 请求经服务器发送，不适合多个用户各自桌面；用户删除缺失；同一浏览器的部分显示设置在账号间共用。（S3）
- 设置分层：阅读和复习显示设置部分位于浏览器；用户设置页的数据位于服务端。（S2）
- PWA 支持仅证实安装/全屏形态，不能据此承诺离线学习、断网同步或原生 App。（S2）
- 外部资源依赖：模型安装需要联网；网页/字幕抓取和在线翻译需单独验证当前可用性。（S3、S6）
- 数据保护：数据库备份与文件备份要结合；自动数据库备份并不等于完整实例备份。（S3、S10）
LexGo 建议新增的质量要求（不是声称原版已具备）
| ID | 要求 | 可验收标准 |
|---|---|---|
| N01 | 用户隔离 | 用户 B 无法以书籍、词汇、任务或文件 ID 访问/修改用户 A 数据 |
| N02 | 重试幂等 | 重复执行同一导入任务不增加重复章节；重复提交同次复习不重复计数 |
| N03 | 可恢复任务 | Worker 重启后任务能恢复或重试，并有可读失败原因 |
| N04 | 文本完整性 | 分词/渲染后原文空白、标点、Unicode 字符可还原，词语点击位置正确 |
| N05 | 本地核心可用 | 安装完资源后，不依赖在线翻译也能阅读、保存词汇与复习 |
| N06 | 完整备份恢复 | 在空白实例恢复数据库、文件和资源清单后，内容与学习状态相符 |
| N07 | 移动与键盘操作 | 至少覆盖 360px、平板、桌面；键盘可完成查词和复习，不仅靠颜色表达状态 |
| N08 | 性能目标 | 固定 4 核/8GB 测试机、单库 100 万词条、20 并发下，离线查词 API p95 目标 <300ms；须实测后定版 |
N08 是拟定目标，不是基准测试结果；不包含公网延迟、外部翻译时间和冷启动模型加载。
6. 不能归入“原版已支持”的扩展
多租户组织、课程商城、会员收费、教师班级、社交排行榜、AI 对话、自动生成课程、PDF OCR、视频转写、云端高质量 TTS、原生移动 App、完整离线同步、FSRS 算法、通用用户删除与审计后台，均不能根据本次证据直接认定为现成功能。
这些可以另立扩展需求；特别是用户删除、操作审计、个人 Anki 连接与浏览器设置隔离，适合在多用户版中补齐。
7. 建议首版范围与验收场景
首版建议：普通用户/管理员、英语先行、文本导入、章节处理、阅读查词、单词/短语状态、基础复习、统计、基础词典管理、备份。中文/日语通过独立语言验收后加入；英语先行是可调整假设。
| 场景 | 通过条件 |
|---|---|
| 全流程 | 安装词典 → 导入一段文本 → 阅读查词 → 保存短语 → 完成阅读 → 到期复习 → 统计更新可完成 |
| 状态一致 | 同一用户同语言同词在不同章节状态一致；忽略与已知统计分开 |
| 完成阅读 | 开关关闭时只更新阅读行为，不批量改变新词；重复请求无重复副作用 |
| 多用户 | A 保存的释义、学习状态和书籍不会进入 B 的查询或复习列表 |
| 后台权限 | 普通用户直接请求管理员 API 得到拒绝，隐藏菜单不是唯一防线 |
| 失败恢复 | 模拟文本处理失败，页面展示错误；重试后章节只生成一份 |
| 复习 | 固定时间测试到期、未到期、重学、答对/答错；练习不改变调度状态 |
| 字符与短语 | 中文、日文、重音字符、emoji、换行与重叠短语不造成错位或原文丢失 |
| 备份 | 恢复后书籍数量、抽样词汇状态、用户设置与文件校验一致 |
需求提取已完成；具体范围取舍和框架方案见 Go 复刻与框架选型分析。