fix(voice): restore failed transcription recovery

docs/incidents/2026-07-22-miniprogram-voice-retry.md

@@ -3,7 +3,7 @@
 ## 状态
 
 - 记录日期：2026-07-22
-- 当前状态：待处理
+- 当前状态：已修复，待部署验证
 - 影响范围：小程序反馈生成页的语音转录重试流程
 - 相关会话：`7dc4f0dd-bd32-4d4b-b90a-c36ae83c2ca7`
 
@@ -73,6 +73,10 @@ POST /api/v1/feedback-lessons/{lesson_id}/finish
 
 页面没有独立、明确的“重试转录”主操作，也没有显示将要重试的失败片段数量。
 
+### 原生弹窗确认文案超限
+
+语音记录弹窗把 `confirmText` 设置为“重试失败项”，共 5 个字符。项目使用的微信小程序 API 类型定义明确限制 `showModal.confirmText` 最多 4 个字符，因此该弹窗可能直接调用失败；原实现也没有设置 `fail` 回调，界面上不会留下可观察错误。
+
 ### 生成失败后没有刷新会话
 
 `generateFeedback` 捕获 API 错误后只显示短暂 Toast，没有重新调用 `loadActiveSession`，也没有把错误信息和 `X-Request-Id` 保存到页面的持久错误区域。
@@ -83,7 +87,7 @@ POST /api/v1/feedback-lessons/{lesson_id}/finish
 
 API 当前只有通用 HTTP 请求日志。重试请求未到达服务端时，没有前端操作日志；请求到达服务端后，也缺少 `transcription_retry_requested` 等业务事件日志。
 
-## 待实现方案
+## 实现方案
 
 1. 当 `failedSegmentCount > 0` 时，主操作优先显示“重试转录”，并直接调用失败片段重试流程。
 2. 禁止在存在失败片段时调用生成接口。
@@ -92,6 +96,16 @@ API 当前只有通用 HTTP 请求日志。重试请求未到达服务端时，
 5. API 为重试受理、生成拒绝和转录失败增加包含会话 ID、课堂 ID、片段 ID、尝试次数和错误分类的结构化业务日志。
 6. 对“未识别到清晰语音”提供更准确的用户提示，说明可能是录音过短、静音或环境噪声，并允许放弃该失败片段或重新录制。
 
+## 实施结果
+
+- 主操作按 `failed -> processing -> generate -> save` 排序；存在失败片段时显示“重试转录（数量）”，不会调用生成接口。
+- 原生弹窗确认文案缩短为“重试转录”，符合最多 4 个字符的约束。
+- 重试开始后立即锁定操作并显示处理中状态；请求结束后无论成功或失败都刷新活动会话并恢复轮询。
+- 生成请求结束后始终刷新活动会话；API 错误消息和 `X-Request-Id` 保存在页面错误区域，可复制查询。
+- 页面增加失败原因说明和“放弃并重新录制”；后端删除失败片段时会重算课堂状态，空课堂会一并删除。
+- API 增加 `transcription_retry_requested`、`feedback_generation_rejected` 和 `failed_transcription_discarded` 业务日志；转录 worker 将无清晰语音分类为 `no_clear_speech`。
+- 前端自动化测试覆盖失败优先级、重试状态流转、无清晰语音提示和 API 失败后的会话刷新；后端测试覆盖错误分类和 OpenAPI 路由完整性。
+
 ## 验收标准
 
 - 存在失败片段时，主按钮不再显示“生成反馈”。