- R2 并发同键作答：取得词条行锁后加锁复查答案键，stale 插入遇到唯一键冲突转为返回 已记录结果，不再返回 500；新增两个 goroutine 同键提交的集成用例 - R3 排期：只有新建或状态/等级实际变化才移动 due_at，编辑释义与例句保留原排期， 逾期词条不会被挤出当天队列 - R3 附带发现：保存未提及等级时保留已获得的等级，阅读器面板不再把 4 级词重置为 1 级 - R1 契约：作答响应 result 只取 applied/stale，另加 duplicate 标记，重放返回首次结果； 客户端按首次结果计数，本轮只解决卡片而没有新计分时显示完成页而不是空队列 - R4/R5：stale 与重放分别给出角色为 status 的提示，answerId 作用域注释与实现一致 - Wiki 更新 Business-Rules-and-Glossary、Architecture-and-Code-Map、 Local-Development-and-Verification 并同步镜像
This commit is contained in:
@@ -2,8 +2,8 @@
|
||||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||||
wiki_page: Architecture-and-Code-Map
|
||||
wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Architecture-and-Code-Map.-
|
||||
wiki_revision: 0d6fb43a2662e263fc6f2fb5426b9a8fafaa4868
|
||||
synchronized_at: 2026-09-11T12:54:05Z
|
||||
wiki_revision: 8add5553222f7f5235c0b3fe45a0ad46d37bbd46
|
||||
synchronized_at: 2026-09-11T14:44:50Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# 架构与代码地图
|
||||
@@ -267,7 +267,7 @@ schema v6 新增 `lexgo_term_reviews`（每个个人词条一行排期：`due_at
|
||||
| 接口 | 权限与输入/输出 |
|
||||
|---|---|
|
||||
| GET /api/v1/reviews/queue | 本人＋当前语言；仅 `新词`/`学习中` 且 `due_at ≤ now`，按 `due_at, id` 排序、最多 50 条；返回 `{items, total}`，`total` 是全部到期数；不接受查询参数 |
|
||||
| POST /api/v1/reviews/:termId/answers | `{answerId, grade: correct\|wrong\|again, expectedDueAt}`；应用成功 201，重放或过期 200；返回 `result`(applied/duplicate/stale)、前后状态/等级/到期时间、`requeued` 与词条新状态 |
|
||||
| POST /api/v1/reviews/:termId/answers | `{answerId, grade: correct\|wrong\|again, expectedDueAt}`；应用成功 201，重放或过期 200；返回首次结果 `result`(applied/stale) 与 `duplicate` 标记、前后状态/等级/到期时间、`requeued` 与词条新状态；加锁后再次读取答案键，所以并发的同键提交也返回记录而不是报错 |
|
||||
|
||||
学习端新增 `/review` 路由与书库、阅读器顶栏的「到期复习」入口；`stores/review.ts` 维护队列、本轮计数、评分与重学，`ReviewCard.vue`/`ReviewView.vue` 呈现正面（词＋挖空例句）、答案面（个人释义＋例句＋三个评分按钮）、完成页与空队列页。一次评分对应一个 `answerId`，失败重试复用同一个；换词后重新生成。切换账号或退出登录会清空队列、计数与当前卡片。
|
||||
|
||||
|
||||
@@ -2,8 +2,8 @@
|
||||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||||
wiki_page: Business-Rules-and-Glossary
|
||||
wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Business-Rules-and-Glossary.-
|
||||
wiki_revision: e59184a923910cee9283771154349397e7063fbd
|
||||
synchronized_at: 2026-09-11T12:54:06Z
|
||||
wiki_revision: 1d90013d883de9339865694e0bb0026f9edd3acc
|
||||
synchronized_at: 2026-09-11T14:44:50Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# 业务规则与术语
|
||||
@@ -181,13 +181,13 @@ exact优先；未命中再按WordNet异常表/词尾规则查候选，词性顺
|
||||
|---|---|---|---|---|---|---|---|
|
||||
| 下次复习 | 1 天 | 2 天 | 4 天 | 7 天 | 15 天 | 30 天 | 60 天 |
|
||||
|
||||
**入队范围**：只有状态 `新词` 或 `学习中` 且 `due_at ≤ now` 的词条进入队列；`已知` 与 `忽略` 不入队。新保存的词立即到期（`due_at` = 保存时刻），保存后就能复习；手动把词条改为「学习中 level N」时下次复习为 `now + 间隔[N]`，避免刚标等级就被当成到期。已在队列中的词条被改成 `已知`/`忽略` 后再次作答会被拒绝（409），排队信息由服务端裁决而不是前端过滤。
|
||||
**入队范围**：只有状态 `新词` 或 `学习中` 且 `due_at ≤ now` 的词条进入队列；`已知` 与 `忽略` 不入队。新保存的词立即到期（`due_at` = 保存时刻），保存后就能复习；手动把词条改为「学习中 level N」时下次复习为 `now + 间隔[N]`，避免刚标等级就被当成到期。只有新建词条或状态/等级实际变化才移动复习时间：只修改释义、例句或原词形时保留原有排期，否则编辑文本会把逾期词条挤出当天队列。保存未提及等级时保留已获得的等级，只有进入 `学习中` 才从 1 开始，因此阅读器面板的保存不会把等级重置为 1。已在队列中的词条被改成 `已知`/`忽略` 后再次作答会被拒绝（409），排队信息由服务端裁决而不是前端过滤。
|
||||
|
||||
**三个评分动作**：`correct` 认识/答对 → 等级 +1（封顶 7）、按新等级排期、离开本轮；`wrong` 不认识/答错 → `学习中` 降一级（最低 1）、`新词` 保持 `新词`、`due_at = now` 立即回到本轮；`again` 再学一次 → 等级与状态不变、`due_at = now` 立即回到本轮。计数上 `correct_count` 只统计 `correct`，`wrong_count` 统计 `wrong` 与 `again`，`review_count` 统计全部已应用作答。词条的原文、个人释义与例句不因复习改变。
|
||||
|
||||
**时区与到期边界**：`due_at` 以 UTC 绝对时刻存储，到期判定是 `due_at ≤ now`，不引入本地日边界。理由：MVP 没有用户时区设置（属 X 系列边界），绝对时刻在多账号自托管下语义一致、没有夏令时陷阱；代价是复习时刻会随首次作答时间漂移，例如 22:00 答对的 1 天间隔词条要到次日 22:00 才到期。原型界面的「到期复习 N / M」指当前到期队列的位置与本轮卡片数，不是自然日统计。
|
||||
|
||||
**幂等与并发**：客户端每次作答生成一个 `answerId`，服务端以 `UNIQUE(owner_id, answer_id)` 去重。同一个 `answerId` 再次提交返回首次结果（`result=duplicate`）且不改变等级、间隔和次数；同一词条在别处已经被推进（提交回传的 `expectedDueAt` 与服务端当前 `due_at` 不一致）时记为 `result=stale`，同样不改变任何状态。因此网络重发、双击、双标签页作答都只记账一次。每次尝试都会落一条 `lexgo_review_answers`（含 `result`），这是「只记账一次」的证据，也供 #13 统计使用。
|
||||
**幂等与并发**：客户端每次作答生成一个 `answerId`，服务端以 `UNIQUE(owner_id, answer_id)` 去重。同一个 `answerId` 再次提交返回首次结果并把 `duplicate` 标记为 true（`result` 仍是首次的 `applied` 或 `stale`），不改变等级、间隔和次数，因此客户端重试可以按首次结果计数；同一词条在别处已经被推进（提交回传的 `expectedDueAt` 与服务端当前 `due_at` 不一致）时记为 `result=stale`，同样不改变任何状态。因此网络重发、双击、双标签页作答都只记账一次。每次尝试都会落一条 `lexgo_review_answers`（含 `result`），这是「只记账一次」的证据，也供 #13 统计使用。
|
||||
|
||||
**归属与错误**：词条归属由服务端按会话裁决，`owner` 不接受客户端输入；他人词条与不存在的词条统一 404，未登录 401，未知评分/缺少 `expectedDueAt`/未知字段 400，词条已变成 `已知`/`忽略` 409。复习接口不写审计日志：答题属于私人学习内容。
|
||||
|
||||
|
||||
@@ -2,8 +2,8 @@
|
||||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||||
wiki_page: Local-Development-and-Verification
|
||||
wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Local-Development-and-Verification.-
|
||||
wiki_revision: e01464ad570bbd037e813985d78b137462bca241
|
||||
synchronized_at: 2026-09-11T12:54:06Z
|
||||
wiki_revision: 1192d23a8198e981961adfc6066f0b3bc3b84058
|
||||
synchronized_at: 2026-09-11T14:44:50Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# 本地开发与验证
|
||||
@@ -362,3 +362,21 @@ node --test spikes/english/view.test.mjs
|
||||
运维记录：本次只有 lexgo-api（新二进制）与 lexgo-learner 被重启；学习端常驻 Vite 在长时间运行后一度对 `/src/style.css` 返回空样式表，导致 E2E 观察到 `white-space: normal`，重启后恢复，未改动代码或配置。其余实例保持 Running。
|
||||
|
||||
未验证：真实手机触屏详细证据与完整备份恢复演练仍属既有缺口（#14/#15）；本单只用桌面浏览器窄屏检查，不当作真机结果。并发只覆盖到「双标签页同一词条」这一层，没有做多用户压测。
|
||||
|
||||
## #8 审核整改（R1～R3，2026-09-11）
|
||||
|
||||
独立审核（Claude Code）只读审阅提交 `0328505`／`ec5ec2d`，指出三处影响验收标准第 2、3 条的问题。三点均先在 `lexgo_test_issue8` 写复现用例观察到失败，再修复并转绿。
|
||||
|
||||
| 问题 | 现象与根因 | 修复 | 回归用例 |
|
||||
|---|---|---|---|
|
||||
| R2 并发同键返回 500 | 两个同时到达、带同一 `answerId` 的请求都在加锁前查不到记录；后者进入 stale 分支插入相同 `answer_key`，触发唯一键冲突返回 500 | 取得词条行锁后再用加锁读复查一次答案键，命中直接返回首次结果；stale 插入遇到 1062 也转为返回记录 | `TestMySQLReviewConcurrentReplayOfOneAnswer`（两个 goroutine 同键提交，两个都 2xx、`review_count = 1`、只有一条答案记录） |
|
||||
| R3 编辑文本会重排复习 | `saveTerm` 无条件调用 `syncTermReview`，编辑释义/例句也会把 `due_at` 重算，逾期词条被挤出当天队列 | 保存前加锁读取旧行，只有新建或状态/等级实际变化才移动 `due_at`；缺行时补建排期行 | `TestMySQLReviewEditKeepsSchedule`（逾期 3 级词只改释义：`due_at` 与队列不变；改等级则重排） |
|
||||
| R3 附带发现：面板保存把等级重置为 1 | 阅读器面板只提交状态不提交等级，`termLevel` 对缺省等级一律返回 1，于是 4 级词改一个错字会掉到 1 级 | 保存未提及等级时保留已获得的等级；只有进入 `学习中` 才从 1 开始 | `TestMySQLReviewPanelSaveKeepsLevel`（4 级词面板式保存后仍为 4 级，且排期不变；退出再进入学习中则从 1 开始） |
|
||||
|
||||
**答案契约随之明确**：作答响应 `result` 只取 `applied`/`stale`，另加 `duplicate` 布尔标记。重放返回首次结果并把 `duplicate` 置真，客户端因此可以按首次结果计数：网络把响应丢掉后点「重试提交」拿到 `duplicate=true` 的 `applied`，本轮计数正常增加，完成页不会退化成「今天没有到期词条」。已应用的作答返回 201，重放与 stale 返回 200（R1）。
|
||||
|
||||
**提示与注释（R4、R5）**：卡片因 `stale` 离开时页面显示 `role="status"` 提示「该词已在其他页面复习，本次未计分。」，重放且首次为 stale 时显示「该词已按上一次的评分记录，未重复计分。」；本轮只解决卡片而没有新计分时，完成页显示「本轮没有新的计分：N 个词条已在其他页面复习。」。`answerId` 的作用域注释改为「每张卡片一个，失败重试复用」，与 `answerIdFor` 的实现一致。
|
||||
|
||||
**流程记录（R6）**：评论 7769 的方案写的是在 `lexgo_terms` 上增加列，实际实现改为独立表 `lexgo_term_reviews`（加法迁移可重试、不对既有表做 ALTER）。该变更在实施评论 7776 与 Wiki 中说明了原因，但没有按「数据结构变化先更新工单」的要求在实施前追加变更评论；本页与上文契约按实际实现记录，方案评论中的「新增列均有默认值」以独立表为准。
|
||||
|
||||
整改后重跑：Go 单元与集成测试（专用库 `lexgo_test_issue8`）44 个顶层用例全部通过、0 跳过；学习端 73 项单测、类型检查、构建与 5 项 E2E 通过；管理端 31 项与 lint 通过；治理 56 项与严格检查通过；真实 API＋MySQL 42 项检查通过（新增 4 项针对 R3 与重放契约）；真实浏览器复核面板保存与复习闭环通过。截图 `.local/evidence/issue8-fixed-summary.png`。
|
||||
|
||||
Reference in New Issue
Block a user