lixi
1441f0148f
CI / flutter-gates (push) Successful in 2m30s
- MediaUploader：选图→压缩（80→60 降质阶梯，10 MiB 超限拒绝）→createUpload →预签名 PUT 直传（进度回调）→confirm→ready assetId 交付；并发槽位 2、 顺序即 position、单图失败不拖垮整批；凭据过期预检与存储侧 403 各自动 换新凭据一次；失败重试复用压缩产物、从 createUpload 全新开始 - 孤儿防护：未 confirm 的 assetId 只以管线局部变量存在，快照 assetId 与 ready 态断言绑定，buildAttachRequests 非全员 ready 即抛 StateError - 线路修正：media 两步上传端点由 user 服务（:8082 MediaController）提供, T3-12 误挂 community 客户端（:8084 无 media 路由），补 mediaApi 分端口 直连，compose 真链路实测证实 - UploadProgressOverlay 四态进度层（05 号规范 §3.3）；直传层本地 HttpServer 三线路测试（200/403/断连）；compose 冒烟测试 （PATBOND_MEDIA_SMOKE=1 启用，默认跳过） - 新依赖：image_picker、flutter_image_compress（03 号评估选型） - flutter test 379 全绿（基线 347，+32）、analyze 0、format 无 diff Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
472 lines
15 KiB
Dart
472 lines
15 KiB
Dart
import 'dart:async';
|
||
|
||
import 'package:flutter/foundation.dart';
|
||
import 'package:patbond_flutter/core/network/api_exception.dart';
|
||
import 'package:patbond_flutter/features/community/community_models.dart';
|
||
import 'package:patbond_flutter/features/community/community_repository.dart';
|
||
import 'package:patbond_flutter/features/community/media_compression.dart';
|
||
import 'package:patbond_flutter/features/community/media_direct_upload.dart';
|
||
import 'package:patbond_flutter/features/community/media_picking.dart';
|
||
|
||
/// 单张图的上传阶段（05 号规范 §3.3 四视觉态的底层状态模型）。
|
||
///
|
||
/// 生命周期：queued → compressing → uploading(progress) → confirming
|
||
/// → ready | failed(retryable?)。ready 是唯一可交付态——**assetId 只在
|
||
/// ready 态对外可见**（孤儿防护：未 confirm 的 asset 不得被引用）。
|
||
enum MediaItemPhase {
|
||
queued,
|
||
compressing,
|
||
uploading,
|
||
confirming,
|
||
ready,
|
||
failed,
|
||
}
|
||
|
||
/// 单张图的不可变状态快照（UI 消费；内部任务状态见 _UploadTask）。
|
||
@immutable
|
||
class MediaUploadItem {
|
||
const MediaUploadItem({
|
||
required this.localId,
|
||
required this.phase,
|
||
required this.previewBytes,
|
||
this.progress = 0,
|
||
this.assetId,
|
||
this.errorMessage,
|
||
this.retryable = false,
|
||
}) : assert(
|
||
(assetId != null) == (phase == MediaItemPhase.ready),
|
||
'assetId 与 ready 态严格绑定（孤儿防护）',
|
||
);
|
||
|
||
/// 本地稳定标识（重试/删除寻址用，与服务端无关）。
|
||
final int localId;
|
||
|
||
final MediaItemPhase phase;
|
||
|
||
/// 缩略预览字节（原图，UI 直接 Image.memory 渲染）。
|
||
final Uint8List previewBytes;
|
||
|
||
/// 直传进度 0..1（uploading 有意义；confirming 视作 1.0）。
|
||
final double progress;
|
||
|
||
/// ready 态的可引用 asset 标识；其余态恒为 null（构造期断言兜底）。
|
||
final String? assetId;
|
||
|
||
/// failed 态的用户可读原因。
|
||
final String? errorMessage;
|
||
|
||
/// failed 态是否可重试（false = 终态，如压缩后仍超限）。
|
||
final bool retryable;
|
||
|
||
bool get isReady => phase == MediaItemPhase.ready;
|
||
bool get isFailed => phase == MediaItemPhase.failed;
|
||
bool get isBusy => !isReady && !isFailed;
|
||
}
|
||
|
||
/// 内部任务：可变状态 + 生命周期旗标（cancelled 后一切在途结果作废）。
|
||
class _UploadTask {
|
||
_UploadTask({required this.localId, required this.source});
|
||
|
||
final int localId;
|
||
final PickedMediaImage source;
|
||
|
||
MediaItemPhase phase = MediaItemPhase.queued;
|
||
double progress = 0;
|
||
String? errorMessage;
|
||
bool retryable = false;
|
||
bool cancelled = false;
|
||
|
||
/// 压缩产物缓存（重试跳过重压缩）。
|
||
CompressedMediaImage? compressed;
|
||
|
||
/// confirm 成功前的服务端 assetId 只以管线局部变量存在，**不落任务
|
||
/// 状态、不出现在 [MediaUploadItem] 快照**——孤儿防护的结构保证;
|
||
/// confirm 通过后才写入 [readyAssetId]。
|
||
String? readyAssetId;
|
||
|
||
MediaUploadItem snapshot() => MediaUploadItem(
|
||
localId: localId,
|
||
phase: phase,
|
||
previewBytes: source.bytes,
|
||
progress: progress,
|
||
assetId: readyAssetId,
|
||
errorMessage: errorMessage,
|
||
retryable: retryable,
|
||
);
|
||
}
|
||
|
||
/// 媒体上传编排器（T3-13，03 号评估 §4.3 冻结接口的定稿实现）。
|
||
///
|
||
/// 职责：选图 → 压缩（降质阶梯 80→60，仍超 10 MiB 拒绝为终态失败）→
|
||
/// createUpload → 预签名 PUT 直传（进度回调；Content-Type 按
|
||
/// requiredHeaders 原样携带）→ confirm → ready assetId 交付。
|
||
///
|
||
/// 语义要点：
|
||
/// - **顺序保持**：items 顺序 = 加入顺序 = position 语义；并发上传的
|
||
/// 完成先后不影响顺序（[buildAttachRequests] 按当前列表序发号）。
|
||
/// - **单飞槽位**：至多 [maxConcurrentUploads] 张同时占用网络管线，
|
||
/// 单图失败不拖垮整批。
|
||
/// - **凭据过期**：PUT 前过期预检、存储侧 403 各触发一次自动
|
||
/// re-createUpload（换新 assetId 新凭据）；再失败交给手动重试。
|
||
/// - **失败重试**：retry 复用压缩产物、从 createUpload 全新开始
|
||
/// （统一覆盖「对象未上传保持 uploading」与「内容不符置 failed 终态」
|
||
/// 两种服务端分支——旧 asset 弃引用，由服务端超时清理兜底）。
|
||
/// - **孤儿防护**：未 confirm 的 assetId 只以管线局部变量存在;
|
||
/// 对外可见的 [MediaUploadItem.assetId] 与 ready 态严格绑定（断言），
|
||
/// [buildAttachRequests] 仅在全员 ready 时可用。
|
||
/// - 预签名凭据只存内存、用完即弃，不持久化（既有纪律）。
|
||
class MediaUploader extends ChangeNotifier {
|
||
MediaUploader({
|
||
required this._repository,
|
||
MediaImagePicker? picker,
|
||
MediaImageCompressor? compressor,
|
||
MediaDirectUploadClient? directUpload,
|
||
this.maxImages = 9,
|
||
this.maxConcurrentUploads = 2,
|
||
this.maxByteSize = 10 * 1024 * 1024,
|
||
DateTime Function()? now,
|
||
}) : _picker = picker ?? SystemMediaImagePicker(),
|
||
_compressor = compressor ?? const NativeMediaImageCompressor(),
|
||
_directUpload = directUpload ?? DioMediaDirectUploadClient(),
|
||
_now = now ?? DateTime.now,
|
||
_slots = maxConcurrentUploads;
|
||
|
||
final CommunityRepository _repository;
|
||
final MediaImagePicker _picker;
|
||
final MediaImageCompressor _compressor;
|
||
final MediaDirectUploadClient _directUpload;
|
||
final DateTime Function() _now;
|
||
|
||
/// 九宫格上限（05 号规范 §3.2）。
|
||
final int maxImages;
|
||
|
||
final int maxConcurrentUploads;
|
||
|
||
/// 与服务端 byteSize 上限一致（10 MiB，13 号报告偏差 #7）。
|
||
final int maxByteSize;
|
||
|
||
/// 凭据过期预检安全边距：距 expiresAt 不足此值即视为过期，直接换新。
|
||
static const credentialsSafetyMargin = Duration(seconds: 30);
|
||
|
||
/// 压缩降质阶梯（80 常规 → 60 兜底；仍超限即终态拒绝）。
|
||
static const qualityLadder = [80, 60];
|
||
|
||
final List<_UploadTask> _tasks = [];
|
||
int _nextLocalId = 1;
|
||
bool _picking = false;
|
||
|
||
int _slots;
|
||
final List<Completer<void>> _slotWaiters = [];
|
||
|
||
// ---- 对外状态 ----
|
||
|
||
/// 选择器是否拉起中（uploader 级 picking 态）。
|
||
bool get isPicking => _picking;
|
||
|
||
List<MediaUploadItem> get items =>
|
||
List.unmodifiable(_tasks.map((task) => task.snapshot()));
|
||
|
||
bool get isEmpty => _tasks.isEmpty;
|
||
int get remainingSlots => maxImages - _tasks.length;
|
||
int get readyCount =>
|
||
_tasks.where((t) => t.phase == MediaItemPhase.ready).length;
|
||
bool get allReady => _tasks.isNotEmpty && readyCount == _tasks.length;
|
||
bool get hasFailure => _tasks.any((t) => t.phase == MediaItemPhase.failed);
|
||
bool get hasBusyItem => _picking || _tasks.any((t) => t.snapshot().isBusy);
|
||
|
||
/// 页级汇总进度（05 号规范 §3.3 线性进度条）：各图等权。
|
||
double get overallProgress {
|
||
if (_tasks.isEmpty) return 0;
|
||
var sum = 0.0;
|
||
for (final task in _tasks) {
|
||
sum += switch (task.phase) {
|
||
MediaItemPhase.ready => 1.0,
|
||
MediaItemPhase.uploading => task.progress,
|
||
MediaItemPhase.confirming => 1.0,
|
||
_ => 0.0,
|
||
};
|
||
}
|
||
return sum / _tasks.length;
|
||
}
|
||
|
||
/// 交付口（T3-17 发布页组 CreatePostRequest.media 用）：
|
||
/// 仅全员 ready 时可用——**任何非 ready 项在场即抛 [StateError]**，
|
||
/// 从类型上杜绝未 confirm asset 被引用。position 按当前列表序 0..n-1。
|
||
List<PostMediaAttachRequest> buildAttachRequests({int coverIndex = 0}) {
|
||
if (!allReady) {
|
||
throw StateError('存在未就绪的上传项，不得引用（孤儿防护）');
|
||
}
|
||
return [
|
||
for (final (index, task) in _tasks.indexed)
|
||
PostMediaAttachRequest(
|
||
assetId: task.readyAssetId!,
|
||
position: index,
|
||
isCover: index == coverIndex,
|
||
),
|
||
];
|
||
}
|
||
|
||
// ---- 操作 ----
|
||
|
||
/// 拉起系统选择器并把所选图片加入上传管线（剩余槽位自动截断）。
|
||
Future<void> pickAndAdd() async {
|
||
if (_picking || remainingSlots <= 0) return;
|
||
_picking = true;
|
||
notifyListeners();
|
||
try {
|
||
final images = await _picker.pickImages(limit: remainingSlots);
|
||
_picking = false;
|
||
addImages(images);
|
||
} catch (_) {
|
||
_picking = false;
|
||
notifyListeners();
|
||
}
|
||
}
|
||
|
||
/// 直接加入图片（选择器旁路，测试与分享外链场景用）。
|
||
void addImages(List<PickedMediaImage> images) {
|
||
for (final image in images.take(remainingSlots)) {
|
||
final task = _UploadTask(localId: _nextLocalId++, source: image);
|
||
_tasks.add(task);
|
||
unawaited(_run(task));
|
||
}
|
||
notifyListeners();
|
||
}
|
||
|
||
/// 重试一张可重试失败图：复用压缩产物，从 createUpload 全新开始。
|
||
void retry(int localId) {
|
||
final task = _taskOrNull(localId);
|
||
if (task == null ||
|
||
task.phase != MediaItemPhase.failed ||
|
||
!task.retryable) {
|
||
return;
|
||
}
|
||
task.errorMessage = null;
|
||
task.retryable = false;
|
||
task.progress = 0;
|
||
task.phase = MediaItemPhase.queued;
|
||
notifyListeners();
|
||
unawaited(_run(task));
|
||
}
|
||
|
||
/// 移除一张图（任意态可移除）；在途请求结果一律作废，未 confirm 的
|
||
/// 服务端 asset 弃引用（服务端超时清理兜底）。
|
||
void remove(int localId) {
|
||
final task = _taskOrNull(localId);
|
||
if (task == null) return;
|
||
task.cancelled = true;
|
||
_tasks.remove(task);
|
||
notifyListeners();
|
||
}
|
||
|
||
/// 清空全部（发布成功/离开页面时调用）。
|
||
void reset() {
|
||
for (final task in _tasks) {
|
||
task.cancelled = true;
|
||
}
|
||
_tasks.clear();
|
||
_picking = false;
|
||
notifyListeners();
|
||
}
|
||
|
||
_UploadTask? _taskOrNull(int localId) {
|
||
for (final task in _tasks) {
|
||
if (task.localId == localId) return task;
|
||
}
|
||
return null;
|
||
}
|
||
|
||
// ---- 管线 ----
|
||
|
||
Future<void> _run(_UploadTask task) async {
|
||
await _acquireSlot();
|
||
try {
|
||
if (task.cancelled) return;
|
||
final compressed = await _compress(task);
|
||
if (compressed == null || task.cancelled) return;
|
||
await _uploadAndConfirm(task, compressed);
|
||
} finally {
|
||
_releaseSlot();
|
||
}
|
||
}
|
||
|
||
/// 压缩（降质阶梯）；超限终态失败返回 null。
|
||
Future<CompressedMediaImage?> _compress(_UploadTask task) async {
|
||
final cached = task.compressed;
|
||
if (cached != null) return cached;
|
||
_transition(task, MediaItemPhase.compressing);
|
||
try {
|
||
for (final quality in qualityLadder) {
|
||
final result = await _compressor.compress(
|
||
task.source,
|
||
quality: quality,
|
||
);
|
||
if (task.cancelled) return null;
|
||
if (result.byteSize <= maxByteSize) {
|
||
task.compressed = result;
|
||
return result;
|
||
}
|
||
}
|
||
} catch (_) {
|
||
_fail(task, message: '图片处理失败', retryable: true);
|
||
return null;
|
||
}
|
||
_fail(task, message: '图片过大，压缩后仍超过 10 MB', retryable: false);
|
||
return null;
|
||
}
|
||
|
||
Future<void> _uploadAndConfirm(
|
||
_UploadTask task,
|
||
CompressedMediaImage compressed,
|
||
) async {
|
||
// createUpload：登记 mime/byteSize，取预签名 PUT 凭据（内存态，不持久化）。
|
||
MediaUploadCredentials credentials;
|
||
try {
|
||
credentials = await _createUpload(compressed);
|
||
} on Exception catch (error) {
|
||
if (!task.cancelled) _failFromApi(task, error);
|
||
return;
|
||
}
|
||
if (task.cancelled) return;
|
||
|
||
// 直传 PUT：过期预检与存储侧 403 各允许一次自动换新凭据。
|
||
_transition(task, MediaItemPhase.uploading);
|
||
var renewed = false;
|
||
while (true) {
|
||
if (_credentialsExpired(credentials)) {
|
||
if (renewed) {
|
||
_fail(task, message: '上传凭据已过期', retryable: true);
|
||
return;
|
||
}
|
||
renewed = true;
|
||
try {
|
||
credentials = await _createUpload(compressed);
|
||
} on Exception catch (error) {
|
||
if (!task.cancelled) _failFromApi(task, error);
|
||
return;
|
||
}
|
||
if (task.cancelled) return;
|
||
// 回到循环顶复检新凭据（服务端时钟异常仍过期即失败，不无限重取）。
|
||
continue;
|
||
}
|
||
try {
|
||
await _directUpload.put(
|
||
url: credentials.uploadUrl,
|
||
headers: credentials.requiredHeaders,
|
||
bytes: compressed.bytes,
|
||
onProgress: (sent, total) {
|
||
if (task.cancelled || total <= 0) return;
|
||
task.progress = sent / total;
|
||
notifyListeners();
|
||
},
|
||
);
|
||
break;
|
||
} on MediaDirectUploadException catch (error) {
|
||
if (task.cancelled) return;
|
||
if (error.isCredentialRejected && !renewed) {
|
||
renewed = true;
|
||
try {
|
||
credentials = await _createUpload(compressed);
|
||
} on Exception catch (creationError) {
|
||
_failFromApi(task, creationError);
|
||
return;
|
||
}
|
||
if (task.cancelled) return;
|
||
task.progress = 0;
|
||
notifyListeners();
|
||
continue;
|
||
}
|
||
_fail(
|
||
task,
|
||
message: error.statusCode == null ? '网络中断，上传失败' : '上传被存储服务拒绝',
|
||
retryable: true,
|
||
);
|
||
return;
|
||
}
|
||
}
|
||
if (task.cancelled) return;
|
||
|
||
// confirm：42205 对象未上传保持 uploading / 内容不符置 failed 终态,
|
||
// 客户端统一按「可重试 + 重试换新 asset」处理，两分支都正确收敛。
|
||
_transition(task, MediaItemPhase.confirming);
|
||
final MediaAsset asset;
|
||
try {
|
||
asset = await _repository.completeMediaUpload(credentials.assetId);
|
||
} on Exception catch (error) {
|
||
if (!task.cancelled) _failFromApi(task, error);
|
||
return;
|
||
}
|
||
if (task.cancelled) return;
|
||
if (asset.status != MediaAssetStatus.ready) {
|
||
_fail(task, message: '上传确认未通过', retryable: true);
|
||
return;
|
||
}
|
||
task.readyAssetId = asset.id;
|
||
task.progress = 1;
|
||
_transition(task, MediaItemPhase.ready);
|
||
}
|
||
|
||
Future<MediaUploadCredentials> _createUpload(
|
||
CompressedMediaImage compressed,
|
||
) {
|
||
return _repository.createMediaUpload(
|
||
CreateMediaUploadRequest(
|
||
kind: MediaKind.image,
|
||
purpose: MediaPurpose.postImage,
|
||
mimeType: compressed.mimeType,
|
||
byteSize: compressed.byteSize,
|
||
),
|
||
);
|
||
}
|
||
|
||
bool _credentialsExpired(MediaUploadCredentials credentials) =>
|
||
!_now().add(credentialsSafetyMargin).isBefore(credentials.expiresAt);
|
||
|
||
void _failFromApi(_UploadTask task, Exception error) {
|
||
// 参数被服务端拒绝（40000：mime/byteSize 白名单外）重试无意义，终态。
|
||
final retryable =
|
||
error is! ApiBusinessException || error.code != ApiCodes.paramError;
|
||
_fail(
|
||
task,
|
||
message: error is ApiBusinessException ? error.message : '网络异常，请重试',
|
||
retryable: retryable,
|
||
);
|
||
}
|
||
|
||
void _fail(
|
||
_UploadTask task, {
|
||
required String message,
|
||
required bool retryable,
|
||
}) {
|
||
if (task.cancelled) return;
|
||
task.phase = MediaItemPhase.failed;
|
||
task.errorMessage = message;
|
||
task.retryable = retryable;
|
||
notifyListeners();
|
||
}
|
||
|
||
void _transition(_UploadTask task, MediaItemPhase phase) {
|
||
if (task.cancelled) return;
|
||
task.phase = phase;
|
||
notifyListeners();
|
||
}
|
||
|
||
Future<void> _acquireSlot() {
|
||
if (_slots > 0) {
|
||
_slots--;
|
||
return Future.value();
|
||
}
|
||
final waiter = Completer<void>();
|
||
_slotWaiters.add(waiter);
|
||
return waiter.future;
|
||
}
|
||
|
||
void _releaseSlot() {
|
||
if (_slotWaiters.isNotEmpty) {
|
||
_slotWaiters.removeAt(0).complete();
|
||
} else {
|
||
_slots++;
|
||
}
|
||
}
|
||
}
|