xiaoshu-app/docs/features/student-teacher-teaching-release-2026-09-10.md

学生端、老师端教学接通与优化交付

日期：2026-09-10（北京时间）。本次源代码范围为 xiaoshu-mobile、移动端云网关、教学事务迁移与验收脚本。后台前端仅执行回归检查。

已实现

模块	最终行为
会话与提交	第一方教学、反馈、测评、单元和收入接口统一携带 Parse 会话；401 清理会话并回登录页。读请求允许有限重试，普通写请求不自动重试。重要教学写入携带稳定请求键，失败重试复用键。
预约状态	新库 CommonModel 取消标记传递到列表、日历和详情；默认排除取消预约，历史明确标注，前后端均阻止开课。未重新改写历史预约。
完课闭环	老师结束并提交反馈后，学生可查看、评价，老师再确认。评价先保存再更新状态；状态确认由数据库锁定预约、校验操作者和前置状态，重复请求不倒退状态。
课时账户	显示 30 分钟课时、60 分钟课时、体验课时、陪练时长的余额、预留、可用数量及对应分页流水。工资独立显示；混用课时的充值、提现、转赠、商城入口停用。
列表与统计	抗遗忘、收入、预约、销课、学习历史和学员列表接服务端分页；日历和总量由后台聚合。主要学员、日期切换请求取消或序号保护，写入成功清理概览缓存。加载更多失败不跳过该页。
学习上下文	保留学生、预约、bindingId 和返回入口；单元记录归属学生。学习草稿按账号、学生、预约/开课隔离，账号变更清理草稿；学习写入键随当前草稿保留。
可靠保存	单词进度、学习记录双表、测评、单元、阅读创建使用数据库教学命令事务；失败回滚，重复请求返回已有结果。关键保存失败显示错误，提交中防连点。
阅读	复用文章要求完整规范化词表及级别、类型、主题匹配；重新生成跳过复用。老师带读写入所选学生，服务端固定学生和操作者，禁止跨学生改归属。历史文章按 ID 打开，PDF 按需加载。
新库报表	学习报表读取预约、学习记录、完课反馈和抗遗忘汇总，替换旧报表链接。
辅助入口	短信、支付、提现、实名认证、排行榜、旧游戏等未接通能力明确停用或提示；动态页面配置中的接口纳入能力检查，避免把错误伪装成空列表。
UI 与拆分	课时账户、报表、停用说明复用卡片、页面留白和错误状态；提取学习草稿模块。大型学习组件尚有后续拆分空间，未宣称已消除全部样式预算警告。

数据库与部署

• 新增 MobileTeachingCommand 和 xs_mobile_teaching_write，主键为帐套、学习对象作用域、带操作者前缀的请求键，序列化同一学习对象的教学写入。
• 新增 xs_mobile_confirm_appointment，承接 20/30 两个完课确认状态；验证学生/老师身份、前置状态、取消标记，不修改课时或工资快照。
• 阅读记录增加 operatorId、learnerLegacyId、sourceStudyId 字段。
• 已在目标服务器执行迁移，并更新 xiaoshu/app/gateway，函数 ID D3F5Zj8saa；能力版本 2026-09-mobile-teaching-v1。原接口路径保留。
• 课时扣减沿用现有课时业务事务，完课反馈在后续幂等事务中保存；两者并非一个跨表总事务。反馈失败可重试，已成功扣减不会重复扣费。
• 没有批量开放待确认课程、补发历史抗遗忘工资、调整已锁定工资或重做历史预约清理。

本次验证

检查	结果与边界
移动端自动测试	103 项通过，含路由集成、会话、草稿隔离、阅读完整词表匹配和重新生成。
后台自动测试	192 项通过。
教学事务、开课课时、抗遗忘测试	38 项通过，含并发幂等、写入回滚、确认状态权限和防倒退。
云函数与能力检查	11 个定义通过；扫描 114 个请求动作，未发现漏适配动作（实现集合与明确停用集合不互斥）。
构建	移动端、后台构建成功；仍有现存样式体积与 PDF 依赖 CommonJS 优化警告。
线上隔离教学写入	学习并发保存、学习记录双表、单元、测评、阅读、越权拒绝、四类账户读取通过。
线上隔离完课流程	老师带读→学生查看文章→老师完课→学生查看反馈与新报表→学生评价→老师最终确认通过；取消预约拒绝开课，重复完课只扣一次课时。
线上课时事务	重试、充值/完课并发、争抢最后一节课、退款/预留并发、四类余额与流水、事务审计通过。
线上抗遗忘计薪	首次完成仅 1 元，重复完成、改写到另一月份不增薪且不改首次月份。使用数据库回滚验收，没有留下测试工资。
测试清理	隔离用户、业务记录、临时函数清理；此前测试命令凭据按本次隔离账号精确清理，未清理真实用户记录。

真实账号仅做只读对账：抽查老师抗遗忘任务 573 条（29 页），学生 220 条（11 页），完整遍历后数量及唯一数量均与服务端总量一致。默认预约列表不再包含已取消预约。抽查学生四类余额为 0、9、0、9，预留为 0，与后台一致。待确认开课 1,298 条保持原状。

核对材料保存在忽略目录 tmp/mobile-teaching-verification/：read-audit.json 为只读证据，pending-enrollments.json 为待确认开课清单（记录、学生、课程 ID、分类与状态）。这些业务数据不提交 Git；证据不足的课程继续待确认，不自动开放。

待发布与待验收

1. 前端线上发布：本机无公网前端站点部署凭据，本次只生成构建产物并按此前要求尝试推送。后端部署成功不表示公网学生端/老师端已更新。
2. Git 推送：远端 git.fmode.cn 返回 HTTP 502。本地提交保留，远端恢复后运行 git push origin main；不能把本次本地提交称为已推送。
3. 真实设备体验：真实手机音频播放、浏览器返回体验和弱网交互尚待人工设备验收；自动化与接口验收不能替代这些体验。
4. 实际 AI 生成：未消耗真实模型执行生成/重新生成；本次验证了匹配逻辑、学生归属与阅读存取，模型输出质量、费用和耗时待验收。
5. 辅助功能：短信登录、外部支付/提现/实名认证、排行榜和旧游戏依然未完整接通，已明确停用。它们不是本次宣称上线的功能。
6. 体积优化：后续按单词学习、练习、复习日历继续拆分学习组件并抽取共享样式；当前功能修复没有消除所有既有构建警告。

可复跑命令

需要线上权限的脚本从环境读取 XIAOSHU_MASTER_KEY，不得写入仓库。迁移只改结构和函数，不执行历史补发。隔离写入脚本会临时创建测试账号并在 finally 清理，不应把它当纯只读脚本运行。

npm run test:mobile:ci
npm run test:admin:ci
node --test scripts/tests/mobile-teaching.test.mjs scripts/tests/member-enrollment.test.mjs scripts/tests/member-enrollment-gateway.test.mjs scripts/tests/review-rewards.test.mjs
npm run cloud:validate
npm run app:actions:audit
npm run build:mobile
npm run build:admin
node scripts/migrate-mobile-teaching.mjs --apply
node scripts/deploy-admin-functions.mjs --only=xiaoshu/app/gateway
node scripts/audit-mobile-teaching-readonly.mjs
node scripts/smoke-mobile-teaching-writes.mjs
node scripts/smoke-mobile-teaching-flow.mjs