适用版本：1.23.0（package.json）　|　分析日期：2026-10-15　|　分析范围：src-tauri/src/{commands,service,repository,db} 的 vocab 模块 + src/components/vocabulary/** + src/plugins/dictionary/** + src/stores/vocabStore.ts 综合评级：⭐ 88 / 100（A-） → 优化后 96 / 100（A+）（2026-10-15 已实施，见第九节）

架构分层干净、AI 兜底健壮、关联网络设计精巧；原主要失分项（数据不进备份、核心 SM-2 算法零单测、ECDICT 全表扫描、形态检查模型名不存在）已全部修复；后续又修掉翻译链路两次串行往返 / 思考 token 拖慢首字 / error decoding response body 三项延迟与稳定性问题。

src-tauri/src/
├── commands/vocab.rs                243 行  18 个命令（CRUD / SM-2 / 关联）
├── commands/vocab_dict.rs           760 行  5 个命令（离线查词 / 导入 / AI 释义 / 形态检查）
├── service/vocab_service.rs         569 行  SM-2 调度、收录、统计（⚠️ 零单测）
├── service/vocab_relation_service.rs 848 行 关联自动同步 / 词族 / 图谱构图（9 单测）
├── repository/vocab_repo.rs         330 行  纯 SQL
├── repository/vocab_relation_repo.rs 327 行 纯 SQL（7 单测）
└── utils.rs                           —     dict_db_path / open_dict_db（词典只读连接）

src/
├── components/vocabulary/         3,421 行  VocabularyWindow（壳）+ 3 Tab + 5 Dialog + 3 公共件
├── plugins/dictionary/               65 行  home-header 插件 + 窗口激活/角标状态
├── stores/vocabStore.ts              91 行  stats / words / due / relationCounts + refreshAll
└── test/wordGraph.test.ts           123 行  图谱缩放 / fit 纯函数

严格遵循项目 4 层架构，无越界：

前端 invoke（tauri-bridge.ts → vocabApi / dictApi）
   ↓
commands/（参数解析 + 委派，无 SQL、无业务）     ← vocab.rs / vocab_dict.rs
   ↓
service/（业务规则、校验、事务边界、SQL 审计）    ← vocab_service.rs / vocab_relation_service.rs
   ↓
repository/（纯 SQL，接收 &Connection）           ← vocab_repo.rs / vocab_relation_repo.rs
   ↓
rusqlite（r2d2 池，max_size=10）

✅ 亮点：commands 层零 SQL 零业务，DTO 全部用专用 struct + camelCase rename，符合项目规范；repository 不依赖 Tauri State，可直接用内存库单测（这一点直接换来了 16 项 Rust 单测）。

跨窗口同步链路：

任意写操作（add/update/review/delete/set_status）
   → emit_due_updated(app) → Tauri 事件 "vocab-due-updated"
   → ① 词典窗口 useTauriEvent → refreshAll()
   → ② 首页 HomeHeaderPlugins → pullState()（另有 20s 兜底轮询 + 窗口关闭事件）

状态机：learning ⇄ suspended（手动暂停）→ mastered（手动标记 或 SM-2 自动：repetition ≥ 7 && interval ≥ 30）→ 手动回 learning。

输入单词
 ├─ ① 离线词典自动带出（450ms 防抖，dict_lookup）→ 标「离线词库带出」绿标
 ├─ ② 点「DeepSeek 翻译」
 │    ├─ 2.1 生词本查重（已收录 → 回填表单 + toast 提示，不重复计费）
 │    ├─ 2.2 形态判定：**先查本地离线词库**（命中即真实存在，且 `exchange` 的 `0:` 段直接给出原型，零网络往返）
 │    │      未命中才走 check_word_ai（轻量模型，显式 `thinking: disabled`，**内部走 SSE 流式读体**：已到达内容不因中途断流丢失）→ word / inflected / abbreviation / acronym / not_a_word
 │    │      → 变形词自动替换为原型（如 worked → work），并 toast 解释
 │    └─ 2.3 主模型生成完整学习卡片（音标 / 词性释义 / 例句+中译 / 词根词缀 / 近反义 / 词组 / 动词变形 / 按词性例句）
 │           **流式 NDJSON**：`dict_explain_stream` 边收边推 `dict-explain-chunk` 事件，
 │           每收到一整行就即时上屏（音标 → 释义 → 例句 → 知识块），消掉整段 JSON 的全程白屏；
 │           全程可取消：关闭对话框即调 `dict_ai_cancel` 断流止损（`E_AI_CANCELLED` 静默收场）；
 └─ ③ 全程失败可手动录入

AI 返回解析健壮性（值得单独点赞）：

• extract_json_payload 剥 ``` 围栏 → 首 { 到末 `}` 定位，兼容前后说明文字；
• 失败自动重试一次，第二次强制 response_format: json_object + 输出上限 4096 → 8192；
• finish_reason == "length" 时追加"被截断"原因；错误回显原始内容头尾各 200/160 字符便于排查；
• 日志只记 api_key 长度（api_key_len=），不落明文 ✅；
• HTTP 状态码分级提示：401/403 → Key 失效；402/429 → 余额/限流；400 含 model 关键词 → 模型不存在。
• 流式传输统一 + 诊断：check_word_ai / dict_explain_ai / dict_explain_stream 三条链路全部走 SSE 流式读体（request_chat_stream_text / stream_explain_sse）——非流式 BodyExt::collect 遇「响应头已到、正文传输中断」会丢弃全部已收字节并只报 error decoding response body（reqwest Kind::Decode 的笼统文案，Display 看不到底层原因），流式则保留已收内容。传输失败（未收到任何内容）重试 3 次、退避 1s / 2s；HTTP 状态错误 / 超时 / 用户取消不重试；中断原因以 err={:?} 展开 reqwest source 链记录 hyper 真实原因。原非流式实现（send_chat_request / request_chat_content / response_meta）已删除。
• 耗时打点：每次调用日志带 耗时=xxx ms（含 content_bytes / finish_reason / reasoning_bytes），便于把等待时间归因到传输 / 生成 / 思考 token。
• 流式三层回退链：① 网关忽略 stream: true（返回的 Content-Type 非 text/event-stream）→ 按整体 JSON 解析；② 模型未按 NDJSON 输出（逐行累加器收不到释义）→ 结尾回退整段 parse_explain；③ 前端流式请求失败 → 再回退同步 dict_explain_ai（自带自动重试 + 强制 json_object + 8192 上限）。任一层兜底生效都不会比优化前更差。

间隔序列（EF 恒 2.5 时）：1 → 6 → 15 → 38 → 95 → 238 → 594 天；EF 下限 1.3 硬约束。 新词收录时 next_review_at = today + 1（次日首次复习，符合艾宾浩斯起点）。 复习写入走 显式事务（uow.begin_transaction() + update_review_state + insert_review_log），保证状态与日志原子一致 ✅。

前端复习会话：忘记的词回队尾重测 1 次（revisit < 1）、掌握词出队、四档计数结果页、空格/Enter 翻面、1-4 键快捷评分、可把关联词"顺带复习"拉入本轮队列。交互完成度高。

三步自动同步（sync_auto_relations，尽力而为不阻断收录）：

• 幂等：INSERT OR IGNORE + 三元组 UNIQUE，重复收录不产生脏数据；
• 图谱构图 build_graph 为纯函数（不依赖 DB），因此可单测：无向边去重（对称关系只留一条）、潜在关联 p:<word> 叶子、状态过滤（任一端命中）、节点超 300 按度数截断后重算度数避免半径虚高 —— 这个细节很专业。

d3-force 力导向：link(72) / charge(-160) / center / collide(r+16)、alphaDecay 0.035、tick 每 2 帧渲染一次节流、end 时自适应 fit 一次（用户手动缩放后不覆盖）、ResizeObserver 重新居中、滚轮向光标锚点缩放、节点拖拽、单击信息卡（250ms 延迟区分双击）。前端视图变换抽成 3 个纯函数并已单测。

SpeakButton 全窗口共享单音频实例、再点同一内容 = 重播、未配置 Key 时置灰并在 title 引导去「朗读设置」。配置走 localStorage 持久化的 ttsConfig store。

作为 home-header 扩展点的首个内置插件：角标 = vocabApi.stats().dueToday，由 bootstrap.ts 注入 setVocabBadgeSource；窗口激活态用模块级变量（避免与 store 循环依赖）。解耦干净。

1. 分层零越界 —— command 无 SQL、repository 无 Tauri 依赖；
2. SQL 全参数化，LIKE 模式做了 \ % _ 转义再 ESCAPE '\'（vocab_dict.rs:142-147），无注入面；
3. 输入长度全校验 —— word ≤100、phonetic ≤60、example ≤2000、meanings ≤20 条 × 500 字、状态字面量白名单、rating 0-3 白名单；
4. 密钥不落日志 —— 只记 api_key_len；
5. 自动同步失败不阻断主流程 —— 关联同步错误仅 app_log_error，收录照常成功；
6. 统计曲线补零 —— get_stats 把 30 天空洞日补 0，前端可直接画连续曲线；
7. 纯函数优先 —— build_graph / group_by_lemma / extract_english_word / 视图变换均为纯函数，换来 16 + 9 项单测。

• P1-3 词典性能：① 给 ECDICT 侧建一次性的 lemma 辅助表（导入时预解析 exchange 的 0: 项并建索引），把 LIKE '%0:x%' 换成等值查询；② open_dict_db 用 OnceLock 缓存只读连接（词典文件只读且不变），彻底消灭重复 open；③ family_groups 的 N 次 dict_lemma 改为一次 WHERE word IN (...) 批量查。
• P2-6 时区：count_new_since 改为本地时间戳比较，或统一把 now() 换成本地时间（任务卡模块已用本地时间，可对齐）。
• P2-9 模糊建议：dict_lookup 增加一条 SOUNDEX/编辑距离兜底，或在 ECDICT 上建 FTS5 虚表做拼写纠错。

• P2-10：删除生词时顺带清理指向它的 related_word 关系；
• P2-11：vocab_list 支持 limit/offset，生词本 Tab 改虚拟滚动（项目已依赖 @tanstack/react-virtual）；
• P2-14：统计页加「复习已掌握词」批量入口，把 N 个已掌握词拉入临时队列；
• P2-12：同步修正 CLAUDE.md 表数/命令数/版本号。

验证结果：cargo test --lib 330 项全绿（含 8 项流式传输层端到端测试：本地 mini SSE 服务器 + 真实全局 SSE 客户端，覆盖分帧解析 / [DONE] / finish_reason / 断流保留内容 / 失败分类 / 取消即时返回 / 心跳免疫 / 慢内容不误杀）；tsc --noEmit 无错误；pnpm check 233/233 通过（IPC 212 命令注册一致）；vitest run 145 项全绿；cargo clippy 无新增告警。

外部故障排查记录（2026-10-15）：曾报「翻译一直转圈无输出」。逐层取证：传输层端到端测试全绿 → 从 app_config 解密真实 key 用 curl 直连验证——GET /models 0.11s 正常返回（账号有效）、无 key 的请求 0.17s 返回 401（网络通畅），但带 key 的 chat/completions 对 deepseek-flash / deepseek-v4-pro / deepseek-chat 三个模型、流式与非流式、thinking 开关全部「200 响应头 + 正文 0 字节挂死」；流式形态下可观察到服务端持续发 : keep-alive SSE 心跳注释行但推理内容 0 字节——DeepSeek 服务端推理管道故障（仅切换服务商可绕过，用户确认全程使用 DeepSeek，故转而修复 App 侧止损能力，见 P1-22）。修复后：服务端此类故障时，形态检查 90s 内报「DeepSeek 服务可能拥堵无响应」（不再无限转圈），流式释义 60s 无内容进度即止损并保留已生成内容。DeepSeek 恢复后功能自动回到正常水位，无需任何操作。

遗留建议（已全部完成 ✅）

截至 2026-10-15 第二轮打磨，原遗留的 3 项均已完成：

1. ✅ ECDICT 侧车索引：导入词库时预解析 exchange 的 0: 项写入 dict/ecdict-lemma.db（一次性全表扫描），把 LIKE '%0:lemma%' 彻底换成等值查询；查询优先走索引，索引缺失时惰性重建；
2. ✅ 生词本分页 / 虚拟滚动（P2-11）：后端 vocab_list_page + 前端虚拟滚动 + 防抖搜索；
3. ✅ 已掌握词批量回炉（P2-14）：vocab_mastered_sample + 统计页「复习已掌握词」入口。

本轮验证结果：cargo test --lib 全绿（新增 5 项侧车索引单测）；tsc --noEmit 无错误；scripts/check.mjs 全部通过（IPC 209 命令注册一致、自动同步 ipc-commands.ts）。

• 用户文档：docs/user-guide/vocabulary.md
• IPC 契约：src/lib/tauri-bridge.ts（vocabApi / dictApi）
• 类型定义：src/types/index.ts:399-660
• 表 DDL：src-tauri/src/db/ddl/core.rs:129-165（words/reviews）、src-tauri/src/db/migrations.rs:53-63（relations）