recording-upload-handoff

1. 实验目标与工程要点

这个 Android host 样板专门拆“录制结束 → 上传任务接手”这一瞬间，验证三个最关键的交接动作：

• 录音文件结束写入后，先冻结会话状态，再交给上传任务
• 上传层拿到的是稳定文件路径和会话 ID，而不是 UI 里的临时状态
• 上传失败时，本地文件不能立刻删；只有服务端确认 uploaded 后才允许回收

---

2. 深入原理与生活浅显比喻

2.1 生活浅显比喻

它像接力赛的交棒区：

• 录音阶段是第一棒，负责把音频安全跑完
• 上传阶段是第二棒，负责把文件送到服务端
• 交棒时必须把棒真正递稳，不能边跑边扔

如果交棒区设计不好，常见事故不是“第二棒慢一点”，而是“棒直接掉地上”。

2.2 底层原理分析

录音结束时最容易犯的错是：

1. 直接删本地文件
2. 只在页面 state 里记上传状态
3. 没有 uploadSessionId / fileFingerprint

更稳的做法是：

• 先把会话状态从 recording 切到 waitingUpload
• 生成稳定的 uploadSessionId
• 把文件路径、文件大小、重试次数、清理条件交给上传层
• 上传层完成后再把状态推进到 uploaded / failed

2.3 方案对比矩阵

方案	通俗比喻	底层原理	保证特性	吞吐性能	运行开销	适用场景
录音页直接上传	运动员自己拿两棒一起跑	UI 线程同时管理录音与上传	开发快	高	低	Demo
显式 handoff	规范交棒区	session + file meta + upload worker 分层	状态稳定、失败可恢复	中	中	会议录音、采访录音
录完即删本地文件	交棒前先把棒丢了	没有失败恢复文件	极弱	高	低	不推荐

---

3. Android / 移动端实战场景与误配事故

3.1 实战场景

• 录音 App：前台录音，结束后交 WorkManager / 上传任务补传
• 会议纪要：录音结束立刻排队上传，页面可退出

3.2 常见误配与事故注意事项

• 录音页销毁后上传状态全丢
• 上传失败时文件已删除，无法补传
• 重复点击“完成录音”生成多份上传任务

3.3 排障思路

重点看四个字段有没有落稳：

1. recordingSessionId
2. uploadSessionId
3. localFilePath
4. cleanupEligible

---

4. 实验源码与运行验证

关键源码

• Activity：RecordingUploadHandoffActivity.kt
• 布局：activity_recording_upload_handoff.xml

关键参数 / 开关

• simulateUploadFailure：模拟第一次上传失败
• cleanupEligible：只有上传成功后才变为 true

运行方式

cd labs/android/host
./gradlew installDebug

打开 Android Host，进入 录音结束到上传交接。

预期控制台运行输出

recording -> waitingUpload
handoff uploadSessionId=upload-demo-001 file=meeting.m4a
upload failed, keep local file for retry
retry success, cleanupEligible=true

---

5. 对应知识库文档

• 理论主文档：录音转写：录制进行中 + 断点上传 + 会话同步 + 推送回流