119 lines
4.7 KiB
Dart
119 lines
4.7 KiB
Dart
|
/// 本地上传任务状态机（P3 计划 Task 5）：纯迁移表，无 drift 依赖。
|
|||
|
|
///
|
|||
|
|
/// 状态取值与合法迁移对齐技术实施方案 §5.5 与 P3 计划 Task 5/6：
|
|||
|
|
/// - 准备：preparing → queued（入队）/ preparationFailed（准备失败，可回
|
|||
|
|
/// preparing 重试）；
|
|||
|
|
/// - 传输主干：queued → uploading → uploadedConfirming → completed；
|
|||
|
|
/// - 网络等待与重试：waitingNetwork / retryableFailed 可回 queued（重新
|
|||
|
|
/// 出队）或直接 uploading（续传/重试）；
|
|||
|
|
/// - 终态：completed / cancelled，不接受任何后续迁移（completed 的源文件
|
|||
|
|
/// 仅按保留策略清理，见 task_store.dart 的 cleanupCandidates 硬守护）。
|
|||
|
|
///
|
|||
|
|
/// 取消语义（方案 §5.5）：未开始（preparing/preparationFailed/queued/
|
|||
|
|
/// waitingNetwork/retryableFailed）→ cancelled 为确定语义；uploading 进行中
|
|||
|
|
/// → cancelled 为"尽力"（写入标记，实际中断由引擎在下一个检查点兑现）。
|
|||
|
|
library;
|
|||
|
|
|
|||
|
|
/// 上传任务状态（drift 表 `upload_tasks.state` 的取值）。
|
|||
|
|
///
|
|||
|
|
/// 注意与服务端会话状态（UploadSessionState：pending/confirmed/...）区分：
|
|||
|
|
/// 本枚举是客户端本地任务生命周期，二者在 uploadedConfirming 阶段交汇。
|
|||
|
|
enum UploadTaskState {
|
|||
|
|
/// 准备中：选图/拍摄后复制源文件到受管目录、空间检查（Task 6）。
|
|||
|
|
preparing('preparing'),
|
|||
|
|
|
|||
|
|
/// 准备失败（独立状态，可重试回 preparing）：复制失败/磁盘不足等。
|
|||
|
|
preparationFailed('preparation_failed'),
|
|||
|
|
|
|||
|
|
/// 已入队，等待传输引擎出队。
|
|||
|
|
queued('queued'),
|
|||
|
|
|
|||
|
|
/// 传输中：POST /uploads → presign PUT → complete 的任一环节。
|
|||
|
|
uploading('uploading'),
|
|||
|
|
|
|||
|
|
/// 字节已传完，等待/重试完成核验（POST complete）。
|
|||
|
|
uploadedConfirming('uploaded_confirming'),
|
|||
|
|
|
|||
|
|
/// 终态：核验通过，服务端已受理（cleanup 仅针对此态与 cancelled）。
|
|||
|
|
completed('completed'),
|
|||
|
|
|
|||
|
|
/// 网络不可达，指数退避等待恢复（nextRetryAt 记录下次尝试时间）。
|
|||
|
|
waitingNetwork('waiting_network'),
|
|||
|
|
|
|||
|
|
/// 可重试失败（服务端 5xx/超时等），按退避策略回 queued 重试。
|
|||
|
|
retryableFailed('retryable_failed'),
|
|||
|
|
|
|||
|
|
/// 终态：用户取消（uploading 态下为尽力取消）。
|
|||
|
|
cancelled('cancelled');
|
|||
|
|
|
|||
|
|
const UploadTaskState(this.wire);
|
|||
|
|
|
|||
|
|
/// 落库（drift state 列）取值。
|
|||
|
|
final String wire;
|
|||
|
|
|
|||
|
|
/// 解析落库取值；未知值 fail-fast（与 models.dart 的枚举解析约定一致）。
|
|||
|
|
static UploadTaskState fromWire(String value) => values.firstWhere(
|
|||
|
|
(v) => v.wire == value,
|
|||
|
|
orElse: () => throw FormatException('未知 UploadTaskState: $value'),
|
|||
|
|
);
|
|||
|
|
|
|||
|
|
/// 是否终态（不接受任何后续迁移）。
|
|||
|
|
bool get isTerminal => this == completed || this == cancelled;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/// 合法迁移表（键=当前状态，值=可直接迁入的目标集合）。
|
|||
|
|
const Map<UploadTaskState, Set<UploadTaskState>> kUploadTaskTransitions = {
|
|||
|
|
UploadTaskState.preparing: {
|
|||
|
|
UploadTaskState.queued,
|
|||
|
|
UploadTaskState.preparationFailed,
|
|||
|
|
UploadTaskState.cancelled,
|
|||
|
|
},
|
|||
|
|
UploadTaskState.preparationFailed: {
|
|||
|
|
UploadTaskState.preparing,
|
|||
|
|
UploadTaskState.cancelled,
|
|||
|
|
},
|
|||
|
|
UploadTaskState.queued: {
|
|||
|
|
UploadTaskState.uploading,
|
|||
|
|
UploadTaskState.waitingNetwork,
|
|||
|
|
UploadTaskState.cancelled,
|
|||
|
|
},
|
|||
|
|
UploadTaskState.uploading: {
|
|||
|
|
UploadTaskState.uploadedConfirming,
|
|||
|
|
UploadTaskState.waitingNetwork,
|
|||
|
|
UploadTaskState.retryableFailed,
|
|||
|
|
// 尽力取消：见库级文档（进行中取消由引擎在检查点兑现）。
|
|||
|
|
UploadTaskState.cancelled,
|
|||
|
|
},
|
|||
|
|
UploadTaskState.uploadedConfirming: {
|
|||
|
|
UploadTaskState.completed,
|
|||
|
|
UploadTaskState.retryableFailed,
|
|||
|
|
UploadTaskState.waitingNetwork,
|
|||
|
|
},
|
|||
|
|
UploadTaskState.waitingNetwork: {
|
|||
|
|
UploadTaskState.queued,
|
|||
|
|
// 网络恢复直接续传（重试）。
|
|||
|
|
UploadTaskState.uploading,
|
|||
|
|
UploadTaskState.cancelled,
|
|||
|
|
},
|
|||
|
|
UploadTaskState.retryableFailed: {
|
|||
|
|
UploadTaskState.queued,
|
|||
|
|
UploadTaskState.cancelled,
|
|||
|
|
},
|
|||
|
|
// 终态：无出边（completed 的清理走 cleanedAt 标记，不是状态迁移）。
|
|||
|
|
UploadTaskState.completed: {},
|
|||
|
|
UploadTaskState.cancelled: {},
|
|||
|
|
};
|
|||
|
|
|
|||
|
|
/// `from → to` 是否合法迁移（自迁移一律非法，状态未变无需写库）。
|
|||
|
|
bool canTransition(UploadTaskState from, UploadTaskState to) =>
|
|||
|
|
kUploadTaskTransitions[from]!.contains(to);
|
|||
|
|
|
|||
|
|
/// 断言 `from → to` 合法，否则抛 [StateError]（携带合法目标集，便于排障）。
|
|||
|
|
void assertTransition(UploadTaskState from, UploadTaskState to) {
|
|||
|
|
if (!canTransition(from, to)) {
|
|||
|
|
final legal = kUploadTaskTransitions[from]!;
|
|||
|
|
final hint = legal.isEmpty ? '（终态，无合法后继）' : '，合法目标：$legal';
|
|||
|
|
throw StateError('非法上传任务状态迁移：$from → $to$hint');
|
|||
|
|
}
|
|||
|
|
}
|