xiaoshu-app/docs/qa/lesson-study-batches-2026-10-13

多词本课堂记录修复与真实数据验收（2026-10-13）

已完成本地实现、后端发布和小黄指定课次恢复。前端未发布，由项目负责人发布学生／老师端和管理后台构建。

根因与现在的行为

原 stu_record_update_v2 以预约＋开课记录定位并替换 xxqs。七／八／九年级是同一个开课下的三个单元，所以后两次保存覆盖了前面的成果。结束页只读取当前开课，且新课未生成复习日期。

现在按课堂批次保存，确认掌握情况后在事务中合并成一条 DailyStudyRecord。同一词库 GeneralID 去重，重复轮次保留来源；新版本确认可以更新状态，旧版本及被较新轮次覆盖的迟到请求不能覆盖新状态。草稿不计入正式词数，存在草稿时不能结课。旧客户端采用保守合并，已有词不被删除。

老师确认页仅显示英文，提供「保存并继续选词」「保存并结束课程」。每轮有服务器确认累计数，预约详情和结课反馈显示各词本／单元及最终累计数；学习历史详情和学习报告同时显示各单元去重后的来源拆分。刷新可恢复服务器草稿与本机勾选；保存失败不跳走、不清草稿。恢复草稿使用批次实际词本记录词汇进度。

结课使用与批次保存相同的数据库锁，冻结课堂汇总，按北京时间结课日期的第 1、2、3、5、7、9、11、14、17、21 天生成 10 次复习，每次引用同一份完整词表。重复结课不重复扣课时或产生复习任务。无词课堂不产生空复习。

课堂 AI 阅读在缓存查询和模型调用前，由服务端根据学员、记录 ID、版本读取完整词表。缓存包含来源版本和阅读配置；旧版本请求在模型调用前被拒绝。历史文章保留，不自动重生成；独立手动选词入口沿用原用途。

已发布后端

• 线上 migration_status.version：2026-10-13-lesson-batches-v8。
• 4 个网关：xiaoshu.app.gateway、xiaoshu.admin.gateway、xiaoshu.ops.gateway、xiaoshu.ops.gateway.v3。
• 新增 LessonStudyBatch、LessonStudyCommand，以及课堂汇总字段和唯一索引。
• 3 个数据库函数：xs_lesson_study_save、xs_lesson_study_rebuild、xs_lesson_complete。
• 线上源码与本地最终源码逐一相等核验，见 backend-verification.json。旧系统直连接口同步函数未修改。
• 发布前备份在本机权限受限目录 /Users/mac/.local/state/xiaoshu/cloud-releases/2026-10-13-lesson-batches-v8/，包括原云函数、SQL 函数、Schema 和定向恢复前后数据。凭据及原始客户快照未提交 Git。
• scripts/migrate-lesson-study.mjs 默认只输出计划；--apply 需要现有超级管理员会话、环境凭据和私有备份目录。迁移与同步／课时操作互斥，临时执行函数用完即删。

指定历史课次恢复

预约 839154386019743（钱老师 69／小黄 110），原学习记录 ID 666765721179035 保留：

来源	恢复词数	掌握状态
七年级	9	待老师补标
八年级	5	待老师补标
九年级	3	保留已掌握
合计	17	已掌握 3，待确认 14

按用户明确确认的词表恢复，排除 how、quite a few。生成 10 次复习：10 月 14、15、16、18、20、22、24、27、30 日及 11 月 3 日。

恢复脚本重跑前后完全一致；余额、四类扣费流水、课时预留、预约、已有复习工资记录均不变。上课记录除词表及更新时间外字段不变，未重新结课。线上学习报告为一条 17 词记录，复习和 AI 来源均指向这条完整记录。见 recovery-api-verification.json。

老师可在预约详情的恢复批次中点击「补充掌握情况」。该入口只补标已核实恢复词，不得改词、覆盖已确认状态或产生财务动作；新课仍须逐轮全部确认后才计入成果。

验证结果

验证	结果
服务端测试	180 通过；最终来源细化后的相关 13 项再次通过
学生／老师端测试	214 通过
管理后台测试	261 通过
双端生产构建	通过；保留原有样式预算和 CommonJS 提示
云函数语法／入口检查	11 个定义通过；119 个调用无缺失 action
原场景	同一开课的三个单元 9→14→17，唯一汇总
跨词本	三个独立课程、重复词、重新标记、旧请求冲突测试通过
浏览器	375／812 宽度无横向溢出；英文确认、失败保留、同键重试、累计 17 通过
真实隔离链路	67 项通过：开课、保存、并发结课、报告、评价、修改反馈、课时和对账等
AI 外部调用	实际课堂 17 词来源成功生成文章；未保存文章或覆盖客户历史文章
清理	隔离账号 0、测试／迁移临时函数 0

真实 AI 首次检查已成功；首轮验收随后遇到旧脚本仍期望报告为「1 词」的断言，修正为 17 后完整链路重跑通过。重跑未再次调用收费生成服务。模型请求词表另由适配器测试检查 17 词全部进入请求体。相关证据见 online-smoke.txt、ai-live-check.txt、browser-result.json 和截图。

浏览器为本机 Chrome 隔离数据验证，真实链路为隔离账号调用已发布后端；本次未声称微信真机验收或前端已上线。

前端发布与复验

1. 使用本次修复代码执行 npm run build，分别发布 dist/xiaoshu-mobile、dist/xiaoshu-admin 中对应站点产物，沿用既有发布配置。
2. 老师刷新页面重新进入预约，分三轮确认学习后应看到累计 9、14、17；结课前核对最终 17。
3. 学生学习历史和报告应只有一条课堂记录；10 次复习应各含完整词表；从记录进入 AI 阅读会使用汇总来源。
4. 本次后端和定向历史修复已执行，无需发布前端时再次恢复历史数据。保留既有文章；用户主动生成新文章时才调用 AI。