Appearance
recording-sync-state-machine
1. 实验目标与工程要点
这个 Flutter host 样板把录音转写案例里的页面层状态收敛成一条可观察状态机：
recording：录音进行中waitingUpload：录音结束，等待交接上传uploading：客户端 / 宿主正在上传transcribing：服务端异步转写中synced：结果已回流failed：当前尝试失败，但还可重试或补拉
它验证的重点是：Flutter 最适合统一业务状态与用户反馈，而不是直接承担后台长链路执行。
2. 深入原理与生活浅显比喻
2.1 生活浅显比喻
把它想成物流看板：
- 录音页像仓库前台，只负责展示“已收件、待发车、运输中、已签收”
- 真正开车送货的是宿主上传任务和服务端转写任务
- 前台看板可以很清楚，但不能代替车队与仓库系统本身
2.2 底层原理分析
这个页面要解决两个最容易混掉的边界：
- 页面状态 ≠ 后台授权：Flutter 可以知道当前是
uploading，但是否真能在后台继续上传，仍由宿主平台决定。 - 推送到达 ≠ 会话已收敛：推送只是加速器，最终还是要以前台补拉或会话刷新把状态收口到
synced。
2.3 方案对比矩阵
| 方案 | 通俗比喻 | 底层原理 | 保证特性 | 吞吐性能 | 运行开销 | 适用场景 |
|---|---|---|---|---|---|---|
| 页面只放 loading | 大厅只挂“处理中”灯牌 | 单布尔值状态 | 最弱 | 高 | 低 | Demo |
| 显式会话状态机 | 物流每一站都单独亮灯 | 阶段状态枚举 + 日志 | 可观察、易排障 | 中 | 中 | 录音转写、上传回流 |
| 页面直接做后台执行 | 前台自己去开运输车 | 业务状态与后台执行耦合 | 脆弱 | 中 | 高 | 不推荐 |
3. Android / 移动端实战场景与误配事故
3.1 实战场景
- 会议录音页
- 即时语音笔记页
- 上传后等待 AI 结构化结果回流的详情页
3.2 常见误配与事故注意事项
- 只用一个
isLoading，导致用户根本不知道卡在上传还是转写 - 推送丢失后一直停在 transcribing，没有前台补拉入口
- 页面销毁后把服务端任务也当成“结束了”
3.3 排障思路
先问：
- 失败发生在
uploading还是transcribing？ - 推送丢失时有没有前台补拉入口？
- 重新进会话页时状态能不能根据服务端结果恢复？
4. 实验源码与运行验证
关键源码
关键参数 / 开关
上传时有网：关闭后第一次上传会进入failed转写完成时推送到达：关闭后需要手动点“前台补拉”才能收敛为synced
运行方式
bash
cd labs/flutter/host
flutter pub get
flutter run启动后在首页进入 录音回流状态机。
预期控制台运行输出
text
[recording] 前台录音会话已开始
[waitingUpload] 录音结束，等待宿主把文件交给上传层
[uploading] 第 1 次尝试上传音频分片
[transcribing] 服务端已接管任务，客户端只保留会话状态
[synced] 前台补拉成功，录音纪要已回流到当前会话