新增：媒体上传客户端——MediaUploader 编排状态机 + 预签名直传 + 进度组件，修正 media 端点误挂 community 服务（T3-13）

- 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>

test/features/community/community_repository_test.dart

@@ -14,6 +14,7 @@ import '../../helpers/community_test_helpers.dart';
 void main() {
   late SessionManager session;
   late FakeHttpAdapter adapter;
+  late FakeHttpAdapter mediaAdapter;
   late ApiCommunityRepository repository;
 
   Future<void> setUpWith(
@@ -28,39 +29,58 @@ void main() {
     adapter = FakeHttpAdapter(handler);
     dio.httpClientAdapter = adapter;
     final refresher = TokenRefresher(dio: dio, session: session);
+    // media 两步上传端点由 user 服务提供（13 号报告 §2），走独立客户端;
+    // 两 adapter 分开记录以断言线路不串。
+    final mediaDio = buildPatbondDio(
+      session: session,
+      baseUrl: 'http://user.local',
+    );
+    mediaAdapter = FakeHttpAdapter(handler);
+    mediaDio.httpClientAdapter = mediaAdapter;
     repository = ApiCommunityRepository(
       api: ApiClient(dio: dio, session: session, refresher: refresher),
+      mediaApi: ApiClient(
+        dio: mediaDio,
+        session: session,
+        refresher: refresher,
+      ),
     );
   }
 
   group('请求线路（路径 / 方法 / 鉴权 / 参数）', () {
-    test('createMediaUpload：POST /api/v1/media/uploads，携带 Bearer', () async {
-      await setUpWith(
-        (options) async =>
-            jsonResponse(201, okEnvelope(sampleUploadCredentialsJson())),
-      );
+    test(
+      'createMediaUpload：POST /api/v1/media/uploads 走 user 服务客户端，携带 Bearer',
+      () async {
+        await setUpWith(
+          (options) async =>
+              jsonResponse(201, okEnvelope(sampleUploadCredentialsJson())),
+        );
 
-      final credentials = await repository.createMediaUpload(
-        const CreateMediaUploadRequest(
-          kind: MediaKind.image,
-          purpose: MediaPurpose.postImage,
-          mimeType: 'image/jpeg',
-          byteSize: 204800,
-        ),
-      );
+        final credentials = await repository.createMediaUpload(
+          const CreateMediaUploadRequest(
+            kind: MediaKind.image,
+            purpose: MediaPurpose.postImage,
+            mimeType: 'image/jpeg',
+            byteSize: 204800,
+          ),
+        );
 
-      final request = adapter.requests.single;
-      expect(request.path, '/api/v1/media/uploads');
-      expect(request.method, 'POST');
-      expect(request.headers['Authorization'], 'Bearer community-access');
-      expect(request.data, {
-        'kind': 'image',
-        'purpose': 'post_image',
-        'mimeType': 'image/jpeg',
-        'byteSize': 204800,
-      });
-      expect(credentials.uploadUrl, contains('X-Amz-Signature'));
-    });
+        // 线路：media 端点不打 community 客户端。
+        expect(adapter.requests, isEmpty);
+        final request = mediaAdapter.requests.single;
+        expect(request.baseUrl, 'http://user.local');
+        expect(request.path, '/api/v1/media/uploads');
+        expect(request.method, 'POST');
+        expect(request.headers['Authorization'], 'Bearer community-access');
+        expect(request.data, {
+          'kind': 'image',
+          'purpose': 'post_image',
+          'mimeType': 'image/jpeg',
+          'byteSize': 204800,
+        });
+        expect(credentials.uploadUrl, contains('X-Amz-Signature'));
+      },
+    );
 
     test('completeMediaUpload：POST /complete 无请求体（服务端幂等）', () async {
       await setUpWith(
@@ -70,7 +90,8 @@ void main() {
 
       final asset = await repository.completeMediaUpload('a-1');
 
-      final request = adapter.requests.single;
+      expect(adapter.requests, isEmpty);
+      final request = mediaAdapter.requests.single;
       expect(request.path, '/api/v1/media/uploads/a-1/complete');
       expect(request.method, 'POST');
       expect(asset.status, MediaAssetStatus.ready);

test/features/community/media_direct_upload_test.dart

@@ -0,0 +1,112 @@
+import 'dart:io';
+import 'dart:typed_data';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:patbond_flutter/features/community/media_direct_upload.dart';
+
+/// 预签名直传客户端（T3-13）：本地 HttpServer 模拟 MinIO
+/// （埋点队列测试先例）——200 成功、403 签名过期、传输中断三线路。
+void main() {
+  Future<HttpServer> startServer(
+    Future<void> Function(HttpRequest request) handler,
+  ) async {
+    final server = await HttpServer.bind(InternetAddress.loopbackIPv4, 0);
+    server.listen((request) async => handler(request));
+    return server;
+  }
+
+  test('200：PUT 本体逐字节到达，requiredHeaders 原样携带，无鉴权头泄漏', () async {
+    late Map<String, String?> seenHeaders;
+    late List<int> seenBody;
+    late String seenMethod;
+    final server = await startServer((request) async {
+      seenMethod = request.method;
+      seenHeaders = {
+        'content-type': request.headers.value('content-type'),
+        'authorization': request.headers.value('authorization'),
+        'x-device-id': request.headers.value('x-device-id'),
+      };
+      seenBody = await request.fold<List<int>>(
+        [],
+        (all, chunk) => all..addAll(chunk),
+      );
+      request.response.statusCode = 200;
+      await request.response.close();
+    });
+    addTearDown(() => server.close(force: true));
+
+    final bytes = Uint8List.fromList(List.generate(4096, (i) => i % 251));
+    final progress = <(int, int)>[];
+    await DioMediaDirectUploadClient().put(
+      url:
+          'http://127.0.0.1:${server.port}/patbond-media/post_image/a-1?X-Amz-Signature=sig',
+      headers: const {'Content-Type': 'image/jpeg'},
+      bytes: bytes,
+      onProgress: (sent, total) => progress.add((sent, total)),
+    );
+
+    expect(seenMethod, 'PUT');
+    expect(seenBody, bytes);
+    // Content-Type 已签进签名，必须原样携带。
+    expect(seenHeaders['content-type'], 'image/jpeg');
+    // 裸客户端：预签名 URL 即鉴权，业务侧 Bearer/设备头不得外漏给存储。
+    expect(seenHeaders['authorization'], isNull);
+    expect(seenHeaders['x-device-id'], isNull);
+    expect(progress.last.$1, progress.last.$2);
+    expect(progress.last.$2, bytes.length);
+  });
+
+  test('403（签名过期/被改动）→ isCredentialRejected 异常', () async {
+    final server = await startServer((request) async {
+      await request.drain<void>();
+      request.response.statusCode = 403;
+      await request.response.close();
+    });
+    addTearDown(() => server.close(force: true));
+
+    await expectLater(
+      DioMediaDirectUploadClient().put(
+        url: 'http://127.0.0.1:${server.port}/patbond-media/a-1',
+        headers: const {'Content-Type': 'image/jpeg'},
+        bytes: Uint8List(16),
+      ),
+      throwsA(
+        isA<MediaDirectUploadException>()
+            .having((e) => e.statusCode, 'statusCode', 403)
+            .having(
+              (e) => e.isCredentialRejected,
+              'isCredentialRejected',
+              true,
+            ),
+      ),
+    );
+  });
+
+  test('传输中断（服务端半途断连）→ 网络型异常（statusCode null，可重试）', () async {
+    final server = await startServer((request) async {
+      // 读取少量字节后直接断开 socket，不回任何响应。
+      await request.take(1).drain<void>();
+      final socket = await request.response.detachSocket(writeHeaders: false);
+      await socket.close();
+      socket.destroy();
+    });
+    addTearDown(() => server.close(force: true));
+
+    await expectLater(
+      DioMediaDirectUploadClient().put(
+        url: 'http://127.0.0.1:${server.port}/patbond-media/a-1',
+        headers: const {'Content-Type': 'image/jpeg'},
+        bytes: Uint8List.fromList(List.filled(1 << 20, 7)),
+      ),
+      throwsA(
+        isA<MediaDirectUploadException>()
+            .having((e) => e.statusCode, 'statusCode', isNull)
+            .having(
+              (e) => e.isCredentialRejected,
+              'isCredentialRejected',
+              false,
+            ),
+      ),
+    );
+  });
+}

test/features/community/media_uploader_test.dart

@@ -0,0 +1,470 @@
+import 'dart:async';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:patbond_flutter/core/network/api_exception.dart';
+import 'package:patbond_flutter/features/community/community_exceptions.dart';
+import 'package:patbond_flutter/features/community/community_models.dart';
+import 'package:patbond_flutter/features/community/media_direct_upload.dart';
+import 'package:patbond_flutter/features/community/media_uploader.dart';
+
+import '../../helpers/community_test_helpers.dart';
+import '../../helpers/media_test_helpers.dart';
+
+/// MediaUploader 状态机全路径（T3-13）：
+/// 选图→压缩→createUpload→直传→confirm→ready 编排、并发顺序保持、
+/// 弱网失败语义（凭据过期重取 / 403 换凭据 / 42205 重试）与孤儿防护。
+void main() {
+  late FakeCommunityRepository repository;
+  late FakeMediaImagePicker picker;
+  late FakeMediaCompressor compressor;
+  late FakeDirectUploadClient direct;
+  int uploadSeq = 0;
+
+  MediaUploader build({
+    int maxConcurrentUploads = 2,
+    int maxByteSize = 10 * 1024 * 1024,
+    DateTime Function()? now,
+  }) {
+    return MediaUploader(
+      repository: repository,
+      picker: picker,
+      compressor: compressor,
+      directUpload: direct,
+      maxConcurrentUploads: maxConcurrentUploads,
+      maxByteSize: maxByteSize,
+      now: now,
+    );
+  }
+
+  setUp(() {
+    repository = FakeCommunityRepository();
+    picker = FakeMediaImagePicker([]);
+    compressor = FakeMediaCompressor();
+    direct = FakeDirectUploadClient();
+    uploadSeq = 0;
+    // 默认脚本：凭据按序发号，confirm 返回同 id 的 ready asset。
+    repository.onCreateMediaUpload = (request) async =>
+        credentials(assetId: 'a-${++uploadSeq}');
+    repository.onCompleteMediaUpload = (assetId) async =>
+        readyAsset(assetId: assetId);
+  });
+
+  group('happy path', () {
+    test('单图全程：阶段序列 + 进度 + ready assetId 交付', () async {
+      direct.manual = true;
+      final uploader = build();
+      final phases = <MediaItemPhase>[];
+      uploader.addListener(() {
+        if (uploader.items.isNotEmpty) phases.add(uploader.items.single.phase);
+      });
+
+      uploader.addImages([pickedImage()]);
+      await pumpEventQueue();
+
+      final call = direct.calls.single;
+      expect(uploader.items.single.phase, MediaItemPhase.uploading);
+      call.emitProgress(512, 1024);
+      expect(uploader.items.single.progress, 0.5);
+      // 上传中 assetId 不可见（孤儿防护）。
+      expect(uploader.items.single.assetId, isNull);
+
+      call.succeed();
+      await pumpEventQueue();
+
+      final item = uploader.items.single;
+      expect(item.phase, MediaItemPhase.ready);
+      expect(item.assetId, 'a-1');
+      expect(item.progress, 1);
+      expect(uploader.allReady, isTrue);
+      expect(phases.first, MediaItemPhase.queued);
+      expect(
+        phases,
+        containsAllInOrder([
+          MediaItemPhase.queued,
+          MediaItemPhase.compressing,
+          MediaItemPhase.uploading,
+          MediaItemPhase.confirming,
+          MediaItemPhase.ready,
+        ]),
+      );
+      expect(repository.calls, ['createUpload:image/jpeg:64', 'complete:a-1']);
+    });
+
+    test('直传按凭据原样携带 requiredHeaders 与压缩产物字节', () async {
+      final uploader = build();
+      uploader.addImages([pickedImage(seed: 7, size: 128)]);
+      await pumpEventQueue();
+
+      final call = direct.calls.single;
+      expect(call.headers, {'Content-Type': 'image/jpeg'});
+      expect(call.url, contains('X-Amz-Signature'));
+      expect(call.bytes.length, 128);
+      // 登记 byteSize 与直传本体一致。
+      expect(repository.calls.first, 'createUpload:image/jpeg:128');
+    });
+
+    test('压缩降质阶梯：80 超限降 60，登记与直传用 60 档产物', () async {
+      compressor.sizePerQuality = {80: 11 * 1024 * 1024, 60: 9 * 1024 * 1024};
+      final uploader = build();
+      uploader.addImages([pickedImage()]);
+      await pumpEventQueue();
+
+      expect(compressor.qualities, [80, 60]);
+      expect(uploader.items.single.phase, MediaItemPhase.ready);
+      expect(direct.calls.single.bytes.length, 9 * 1024 * 1024);
+    });
+  });
+
+  group('多图并发与顺序保持', () {
+    test('并发上限 2：第三张等槽位；完成乱序不影响 position 语义', () async {
+      direct.manual = true;
+      final uploader = build();
+      uploader.addImages([
+        pickedImage(seed: 1),
+        pickedImage(seed: 2),
+        pickedImage(seed: 3),
+      ]);
+      await pumpEventQueue();
+
+      // 只有前两张进入直传，第三张排队等槽位。
+      expect(direct.calls, hasLength(2));
+      expect(uploader.items[2].phase, MediaItemPhase.queued);
+
+      // 第二张先完成（乱序），释放槽位后第三张才发起。
+      direct.calls[1].succeed();
+      await pumpEventQueue();
+      expect(direct.calls, hasLength(3));
+      direct.calls[0].succeed();
+      direct.calls[2].succeed();
+      await pumpEventQueue();
+
+      expect(uploader.allReady, isTrue);
+      final attach = uploader.buildAttachRequests();
+      // position 按加入序 0..2，与完成先后无关；isCover 恰好首图。
+      expect(attach.map((a) => a.position), [0, 1, 2]);
+      expect(attach.map((a) => a.isCover), [true, false, false]);
+      // 完成序：第 2 张先确认（a-2），仍归位 index 1。
+      expect(attach[1].assetId, 'a-2');
+      expect(attach[0].assetId, 'a-1');
+      expect(attach[2].assetId, 'a-3');
+    });
+
+    test('单图失败不拖垮整批：另一张照常 ready', () async {
+      direct.manual = true;
+      final uploader = build();
+      uploader.addImages([pickedImage(seed: 1), pickedImage(seed: 2)]);
+      await pumpEventQueue();
+
+      direct.calls[0].fail(const MediaDirectUploadException(message: '断连'));
+      direct.calls[1].succeed();
+      await pumpEventQueue();
+
+      expect(uploader.items[0].phase, MediaItemPhase.failed);
+      expect(uploader.items[0].retryable, isTrue);
+      expect(uploader.items[1].phase, MediaItemPhase.ready);
+      expect(uploader.hasFailure, isTrue);
+      expect(uploader.allReady, isFalse);
+    });
+  });
+
+  group('弱网 / 失败语义', () {
+    test('直传网络中断 → failed 可重试；retry 复用压缩产物、换新 asset', () async {
+      direct.scriptedOutcomes.add(
+        const MediaDirectUploadException(message: '断连'),
+      );
+      final uploader = build();
+      uploader.addImages([pickedImage()]);
+      await pumpEventQueue();
+      expect(uploader.items.single.phase, MediaItemPhase.failed);
+      expect(uploader.items.single.retryable, isTrue);
+
+      uploader.retry(uploader.items.single.localId);
+      await pumpEventQueue();
+
+      final item = uploader.items.single;
+      expect(item.phase, MediaItemPhase.ready);
+      // 重试从 createUpload 全新开始（a-2），旧 a-1 弃引用。
+      expect(item.assetId, 'a-2');
+      // 压缩只做一次（产物缓存）。
+      expect(compressor.qualities, [80]);
+      expect(repository.calls, [
+        'createUpload:image/jpeg:64',
+        'createUpload:image/jpeg:64',
+        'complete:a-2',
+      ]);
+    });
+
+    test('凭据过期预检：PUT 前重新 createUpload 换新凭据', () async {
+      final clock = DateTime.utc(2026, 9, 9, 12);
+      var issued = 0;
+      repository.onCreateMediaUpload = (request) async {
+        issued++;
+        return credentials(
+          assetId: 'a-$issued',
+          // 首张凭据已进入 30 秒安全边距，第二张充足。
+          expiresAt: issued == 1
+              ? clock.add(const Duration(seconds: 10))
+              : clock.add(const Duration(minutes: 10)),
+        );
+      };
+      final uploader = build(now: () => clock);
+      uploader.addImages([pickedImage()]);
+      await pumpEventQueue();
+
+      expect(issued, 2);
+      expect(direct.calls.single.url, contains('/a-2?'));
+      expect(uploader.items.single.assetId, 'a-2');
+    });
+
+    test('换新凭据仍过期 → failed 可重试，不再无限重取', () async {
+      final clock = DateTime.utc(2026, 9, 9, 12);
+      repository.onCreateMediaUpload = (request) async =>
+          credentials(expiresAt: clock);
+      final uploader = build(now: () => clock);
+      uploader.addImages([pickedImage()]);
+      await pumpEventQueue();
+
+      expect(uploader.items.single.phase, MediaItemPhase.failed);
+      expect(uploader.items.single.retryable, isTrue);
+      expect(direct.calls, isEmpty);
+    });
+
+    test('存储侧 403（签名过期）→ 自动换新凭据重传一次后 ready', () async {
+      direct.scriptedOutcomes.add(
+        const MediaDirectUploadException(statusCode: 403, message: '签名过期'),
+      );
+      final uploader = build();
+      uploader.addImages([pickedImage()]);
+      await pumpEventQueue();
+
+      expect(direct.calls, hasLength(2));
+      expect(uploader.items.single.phase, MediaItemPhase.ready);
+      expect(uploader.items.single.assetId, 'a-2');
+      expect(repository.calls.last, 'complete:a-2');
+    });
+
+    test('换新凭据后仍 403 → failed 可重试，不无限自动重传', () async {
+      direct.scriptedOutcomes.addAll([
+        const MediaDirectUploadException(statusCode: 403, message: '签名过期'),
+        const MediaDirectUploadException(statusCode: 403, message: '签名过期'),
+      ]);
+      final uploader = build();
+      uploader.addImages([pickedImage()]);
+      await pumpEventQueue();
+
+      expect(direct.calls, hasLength(2));
+      expect(uploader.items.single.phase, MediaItemPhase.failed);
+      expect(uploader.items.single.retryable, isTrue);
+    });
+
+    test('confirm 42205（对象未上传/内容不符）→ failed 可重试，重试换新 asset', () async {
+      var confirms = 0;
+      repository.onCompleteMediaUpload = (assetId) async {
+        if (++confirms == 1) {
+          throw const MediaUploadStateException(message: '上传未完成');
+        }
+        return readyAsset(assetId: assetId);
+      };
+      final uploader = build();
+      uploader.addImages([pickedImage()]);
+      await pumpEventQueue();
+      expect(uploader.items.single.phase, MediaItemPhase.failed);
+      expect(uploader.items.single.retryable, isTrue);
+      expect(uploader.items.single.assetId, isNull);
+
+      uploader.retry(uploader.items.single.localId);
+      await pumpEventQueue();
+      expect(uploader.items.single.phase, MediaItemPhase.ready);
+      expect(uploader.items.single.assetId, 'a-2');
+    });
+
+    test('confirm 返回非 ready 状态（防御）→ failed 可重试', () async {
+      repository.onCompleteMediaUpload = (assetId) async =>
+          MediaAsset.fromJson({
+            ...readyAssetJson(assetId: assetId),
+            'status': 'uploading',
+            'url': null,
+            'readyAt': null,
+          });
+      final uploader = build();
+      uploader.addImages([pickedImage()]);
+      await pumpEventQueue();
+
+      expect(uploader.items.single.phase, MediaItemPhase.failed);
+      expect(uploader.items.single.retryable, isTrue);
+    });
+
+    test('createUpload 40000（参数拒绝）→ failed 终态不可重试', () async {
+      repository.onCreateMediaUpload = (request) async {
+        throw const ApiBusinessException(code: 40000, message: 'mime 不允许');
+      };
+      final uploader = build();
+      uploader.addImages([pickedImage()]);
+      await pumpEventQueue();
+
+      final item = uploader.items.single;
+      expect(item.phase, MediaItemPhase.failed);
+      expect(item.retryable, isFalse);
+      uploader.retry(item.localId);
+      await pumpEventQueue();
+      // 终态失败 retry 为 no-op。
+      expect(repository.calls, hasLength(1));
+    });
+
+    test('压缩阶梯到底仍超限 → failed 终态，未发起任何网络调用', () async {
+      compressor.sizePerQuality = {80: 12 * 1024 * 1024, 60: 11 * 1024 * 1024};
+      final uploader = build();
+      uploader.addImages([pickedImage()]);
+      await pumpEventQueue();
+
+      final item = uploader.items.single;
+      expect(item.phase, MediaItemPhase.failed);
+      expect(item.retryable, isFalse);
+      expect(repository.calls, isEmpty);
+      expect(direct.calls, isEmpty);
+    });
+
+    test('压缩异常 → failed 可重试', () async {
+      compressor.error = Exception('原生编解码失败');
+      final uploader = build();
+      uploader.addImages([pickedImage()]);
+      await pumpEventQueue();
+
+      expect(uploader.items.single.phase, MediaItemPhase.failed);
+      expect(uploader.items.single.retryable, isTrue);
+    });
+  });
+
+  group('孤儿防护（未 confirm 的 asset 不得被引用）', () {
+    test('非全员 ready 时 buildAttachRequests 抛 StateError', () async {
+      direct.manual = true;
+      final uploader = build();
+      expect(uploader.buildAttachRequests, throwsStateError);
+
+      uploader.addImages([pickedImage(seed: 1), pickedImage(seed: 2)]);
+      await pumpEventQueue();
+      // 在途（uploading）。
+      expect(uploader.buildAttachRequests, throwsStateError);
+
+      direct.calls[0].succeed();
+      direct.calls[1].fail(const MediaDirectUploadException(message: '断连'));
+      await pumpEventQueue();
+      // 一 ready 一 failed：失败项在场仍禁止引用。
+      expect(uploader.readyCount, 1);
+      expect(uploader.buildAttachRequests, throwsStateError);
+    });
+
+    test('全生命周期快照 assetId 仅 ready 态非空', () async {
+      direct.manual = true;
+      final uploader = build();
+      final observed = <MediaItemPhase, String?>{};
+      uploader.addListener(() {
+        for (final item in uploader.items) {
+          observed[item.phase] = item.assetId;
+        }
+      });
+      uploader.addImages([pickedImage()]);
+      await pumpEventQueue();
+      direct.calls.single.succeed();
+      await pumpEventQueue();
+
+      expect(observed[MediaItemPhase.ready], 'a-1');
+      for (final MapEntry(:key, :value) in observed.entries) {
+        if (key != MediaItemPhase.ready) expect(value, isNull);
+      }
+    });
+
+    test('直传在途 remove → 结果作废，不发 confirm', () async {
+      direct.manual = true;
+      final uploader = build();
+      uploader.addImages([pickedImage()]);
+      await pumpEventQueue();
+
+      uploader.remove(uploader.items.single.localId);
+      expect(uploader.isEmpty, isTrue);
+
+      direct.calls.single.succeed();
+      await pumpEventQueue();
+      // 已移除的图完成直传也不确认（asset 留给服务端超时清理）。
+      expect(repository.calls.where((c) => c.startsWith('complete')), isEmpty);
+    });
+
+    test('reset 后在途 confirm 结果作废', () async {
+      direct.manual = true;
+      final uploader = build();
+      uploader.addImages([pickedImage()]);
+      await pumpEventQueue();
+      uploader.reset();
+      direct.calls.single.succeed();
+      await pumpEventQueue();
+
+      expect(uploader.isEmpty, isTrue);
+      expect(repository.calls.where((c) => c.startsWith('complete')), isEmpty);
+    });
+  });
+
+  group('选图与容量', () {
+    test('pickAndAdd：picking 态、limit=剩余槽位、产物入列', () async {
+      picker.results.addAll([pickedImage(seed: 1), pickedImage(seed: 2)]);
+      picker.gate = Completer<void>();
+      final uploader = build();
+
+      final picking = uploader.pickAndAdd();
+      expect(uploader.isPicking, isTrue);
+      picker.gate!.complete();
+      await picking;
+      await pumpEventQueue();
+
+      expect(uploader.isPicking, isFalse);
+      expect(picker.limits, [9]);
+      expect(uploader.items, hasLength(2));
+      expect(uploader.allReady, isTrue);
+    });
+
+    test('用户取消选择（空结果）→ 恢复空闲，无副作用', () async {
+      final uploader = build();
+      await uploader.pickAndAdd();
+      await pumpEventQueue();
+      expect(uploader.isPicking, isFalse);
+      expect(uploader.isEmpty, isTrue);
+      expect(repository.calls, isEmpty);
+    });
+
+    test('满 9 张后 pickAndAdd no-op；addImages 超量截断', () async {
+      final uploader = build();
+      uploader.addImages(List.generate(11, (i) => pickedImage(seed: i)));
+      await pumpEventQueue();
+
+      expect(uploader.items, hasLength(9));
+      expect(uploader.remainingSlots, 0);
+      await uploader.pickAndAdd();
+      expect(picker.limits, isEmpty);
+    });
+
+    test('overallProgress 汇总：ready 计 1、uploading 计进度', () async {
+      direct.manual = true;
+      final uploader = build();
+      uploader.addImages([pickedImage(seed: 1), pickedImage(seed: 2)]);
+      await pumpEventQueue();
+
+      direct.calls[0].succeed();
+      await pumpEventQueue();
+      direct.calls[1].emitProgress(1, 2);
+      expect(uploader.overallProgress, closeTo(0.75, 0.001));
+    });
+  });
+}
+
+Map<String, dynamic> readyAssetJson({required String assetId}) => {
+  'id': assetId,
+  'kind': 'image',
+  'purpose': 'post_image',
+  'mimeType': 'image/jpeg',
+  'byteSize': 1024,
+  'widthPx': 1080,
+  'heightPx': 810,
+  'status': 'ready',
+  'url': 'http://minio.local/p.jpg?X-Amz-Signature=sig',
+  'readyAt': '2026-09-09T00:00:00.000Z',
+  'createdAt': '2026-09-09T00:00:00.000Z',
+};

test/helpers/community_test_helpers.dart

@@ -141,6 +141,9 @@ class FakeCommunityRepository implements CommunityRepository {
   Future<LikeState> Function(String postId, bool target)? onLikeToggle;
   Future<BookmarkState> Function(String postId, bool target)? onBookmarkToggle;
   Future<Post> Function(String postId)? onGetPost;
+  Future<MediaUploadCredentials> Function(CreateMediaUploadRequest request)?
+  onCreateMediaUpload;
+  Future<MediaAsset> Function(String assetId)? onCompleteMediaUpload;
 
   @override
   Future<CursorPage<FeedCard>> getFeed({int? limit, String? cursor}) {
@@ -181,11 +184,16 @@ class FakeCommunityRepository implements CommunityRepository {
   @override
   Future<MediaUploadCredentials> createMediaUpload(
     CreateMediaUploadRequest request,
-  ) => throw UnimplementedError();
+  ) {
+    calls.add('createUpload:${request.mimeType}:${request.byteSize}');
+    return onCreateMediaUpload!(request);
+  }
 
   @override
-  Future<MediaAsset> completeMediaUpload(String assetId) =>
-      throw UnimplementedError();
+  Future<MediaAsset> completeMediaUpload(String assetId) {
+    calls.add('complete:$assetId');
+    return onCompleteMediaUpload!(assetId);
+  }
 
   @override
   Future<Post> createPost(CreatePostRequest request) =>

test/helpers/media_test_helpers.dart

@@ -0,0 +1,138 @@
+import 'dart:async';
+import 'dart:typed_data';
+
+import 'package:patbond_flutter/features/community/community_models.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';
+
+/// media 上传链路测试件（T3-13）：假选择器/压缩器/直传客户端,
+/// 全部支持 Completer 控时序（helpers 既有先例）。
+
+PickedMediaImage pickedImage({int seed = 1, int size = 64}) => PickedMediaImage(
+  bytes: Uint8List.fromList(List.filled(size, seed)),
+  name: 'img-$seed.jpg',
+);
+
+MediaUploadCredentials credentials({
+  String assetId = 'a-1',
+  DateTime? expiresAt,
+}) => MediaUploadCredentials(
+  assetId: assetId,
+  uploadUrl:
+      'http://minio.local/patbond-media/post_image/$assetId?X-Amz-Signature=sig',
+  method: 'PUT',
+  requiredHeaders: const {'Content-Type': 'image/jpeg'},
+  expiresAt: expiresAt ?? DateTime.now().add(const Duration(minutes: 10)),
+);
+
+MediaAsset readyAsset({String assetId = 'a-1'}) => MediaAsset(
+  id: assetId,
+  kind: MediaKind.image,
+  purpose: 'post_image',
+  mimeType: 'image/jpeg',
+  byteSize: 1024,
+  widthPx: 1080,
+  heightPx: 810,
+  status: MediaAssetStatus.ready,
+  url: 'http://minio.local/p.jpg?X-Amz-Signature=sig',
+  readyAt: DateTime.utc(2026, 9, 9),
+  createdAt: DateTime.utc(2026, 9, 9),
+);
+
+class FakeMediaImagePicker implements MediaImagePicker {
+  FakeMediaImagePicker(this.results);
+
+  final List<PickedMediaImage> results;
+  final List<int> limits = [];
+
+  /// 非 null 时 pickImages 挂起等待（picking 态观测用）。
+  Completer<void>? gate;
+
+  @override
+  Future<List<PickedMediaImage>> pickImages({required int limit}) async {
+    limits.add(limit);
+    await gate?.future;
+    return results.take(limit).toList();
+  }
+}
+
+/// 假压缩器：默认原样透传出 image/jpeg；[sizePerQuality] 指定各降质档
+/// 的产物大小（超限阶梯测试用）。
+class FakeMediaCompressor implements MediaImageCompressor {
+  final List<int> qualities = [];
+  Map<int, int>? sizePerQuality;
+  Exception? error;
+
+  @override
+  Future<CompressedMediaImage> compress(
+    PickedMediaImage source, {
+    required int quality,
+  }) async {
+    qualities.add(quality);
+    if (error != null) throw error!;
+    final size = sizePerQuality?[quality];
+    return CompressedMediaImage(
+      bytes: size == null
+          ? source.bytes
+          : Uint8List.fromList(List.filled(size, 0)),
+      mimeType: 'image/jpeg',
+    );
+  }
+}
+
+/// 一次直传调用的观测句柄（进度回调驱动 + 结局手动控制）。
+class DirectUploadCall {
+  DirectUploadCall({
+    required this.url,
+    required this.headers,
+    required this.bytes,
+    required this.onProgress,
+  });
+
+  final String url;
+  final Map<String, String> headers;
+  final Uint8List bytes;
+  final void Function(int sent, int total)? onProgress;
+  final Completer<void> completer = Completer<void>();
+
+  void emitProgress(int sent, int total) => onProgress?.call(sent, total);
+  void succeed() => completer.complete();
+  void fail(MediaDirectUploadException error) => completer.completeError(error);
+}
+
+class FakeDirectUploadClient implements MediaDirectUploadClient {
+  final List<DirectUploadCall> calls = [];
+
+  /// 非 null 时每次 put 自动以该结果收尾（null = 自动成功）；
+  /// 设为 manual 后由测试经 [calls] 手动驱动。
+  bool manual = false;
+  final List<MediaDirectUploadException?> scriptedOutcomes = [];
+
+  @override
+  Future<void> put({
+    required String url,
+    required Map<String, String> headers,
+    required Uint8List bytes,
+    void Function(int sent, int total)? onProgress,
+  }) {
+    final call = DirectUploadCall(
+      url: url,
+      headers: headers,
+      bytes: bytes,
+      onProgress: onProgress,
+    );
+    calls.add(call);
+    if (!manual) {
+      final outcome = scriptedOutcomes.isEmpty
+          ? null
+          : scriptedOutcomes.removeAt(0);
+      if (outcome == null) {
+        call.succeed();
+      } else {
+        call.fail(outcome);
+      }
+    }
+    return call.completer.future;
+  }
+}

test/smoke/media_upload_smoke_test.dart

@@ -0,0 +1,146 @@
+import 'dart:async';
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:dio/dio.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:patbond_flutter/core/network/api_client.dart';
+import 'package:patbond_flutter/core/network/token_refresher.dart';
+import 'package:patbond_flutter/features/auth/auth_models.dart';
+import 'package:patbond_flutter/features/auth/session_manager.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_picking.dart';
+import 'package:patbond_flutter/features/community/media_uploader.dart';
+import 'package:uuid/uuid.dart';
+
+import '../helpers/auth_test_helpers.dart';
+
+/// T3-13 compose 真链路冒烟（默认跳过，不计入常规测试套件）：
+///
+/// ```bash
+/// # 先起后端六容器（patbond-api 仓库根）：
+/// #   ./deploy/init-secrets.sh
+/// #   JAVA_HOME=<JDK17> ./mvnw -DskipTests package && docker compose up -d --build
+/// PATBOND_MEDIA_SMOKE=1 flutter test test/smoke/media_upload_smoke_test.dart
+/// ```
+///
+/// 驱动**真实 MediaUploader** 走完整链路：注册取 token → createUpload
+/// （user :8082）→ 预签名 PUT 直传 MinIO（:9000）→ confirm → ready
+/// assetId → 引用发帖（community :8084）→ 预签名 GET 取回字节一致。
+/// 压缩层用透传实现（flutter test VM 无原生编解码通道），其余全为生产实现。
+void main() {
+  final enabled = Platform.environment['PATBOND_MEDIA_SMOKE'] == '1';
+  final env = Platform.environment;
+  final authBase = env['PATBOND_SMOKE_AUTH_BASE'] ?? 'http://127.0.0.1:8081';
+  final userBase = env['PATBOND_SMOKE_USER_BASE'] ?? 'http://127.0.0.1:8082';
+  final communityBase =
+      env['PATBOND_SMOKE_COMMUNITY_BASE'] ?? 'http://127.0.0.1:8084';
+
+  // 1x1 PNG（67 字节，合法图片本体；mime 声明与直传 Content-Type 一致）。
+  final pngBytes = base64Decode(
+    'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8'
+    'z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==',
+  );
+
+  test(
+    '选图→压缩→createUpload→直传→confirm→ready→引用发帖→GET 回读',
+    () async {
+      // ---- 注册测试账号（一次性，随机凭据，不落任何持久化）----
+      final dio = Dio(BaseOptions(validateStatus: (_) => true));
+      final seed = DateTime.now().millisecondsSinceEpoch;
+      final register = await dio.post<Map<String, dynamic>>(
+        '$authBase/api/v1/auth/register',
+        data: {
+          'username': 'smoke$seed',
+          'phone': '+86139${(seed % 100000000).toString().padLeft(8, '0')}',
+          'password': 'Smoke1234!$seed',
+        },
+        options: Options(
+          headers: {
+            'Idempotency-Key': const Uuid().v4(),
+            'X-Device-Id': const Uuid().v4(),
+          },
+        ),
+      );
+      expect(register.data?['code'], 0, reason: '注册失败：${register.data}');
+
+      final session = SessionManager(store: InMemoryTokenStore());
+      await session.updateTokens(
+        AuthTokens.fromJson(register.data!['data'] as Map<String, dynamic>),
+      );
+      final refresher = TokenRefresher(
+        dio: buildPatbondDio(session: session, baseUrl: authBase),
+        session: session,
+      );
+      final repository = ApiCommunityRepository(
+        api: ApiClient(
+          dio: buildPatbondDio(session: session, baseUrl: communityBase),
+          session: session,
+          refresher: refresher,
+        ),
+        mediaApi: ApiClient(
+          dio: buildPatbondDio(session: session, baseUrl: userBase),
+          session: session,
+          refresher: refresher,
+        ),
+      );
+
+      // ---- 真实 MediaUploader 全链路 ----
+      final uploader = MediaUploader(
+        repository: repository,
+        compressor: _PassthroughPngCompressor(),
+      );
+      final done = Completer<void>();
+      uploader.addListener(() {
+        if (done.isCompleted) return;
+        if (uploader.allReady) done.complete();
+        if (uploader.hasFailure) {
+          done.completeError(
+            StateError('上传失败：${uploader.items.single.errorMessage}'),
+          );
+        }
+      });
+      uploader.addImages([
+        PickedMediaImage(bytes: pngBytes, name: 'smoke.png'),
+      ]);
+      await done.future.timeout(const Duration(seconds: 60));
+
+      final item = uploader.items.single;
+      expect(item.phase, MediaItemPhase.ready);
+      expect(item.assetId, isNotEmpty);
+
+      // ---- ready assetId 引用发帖（孤儿防护出口）+ 预签名 GET 回读 ----
+      final post = await repository.createPost(
+        CreatePostRequest(
+          content: 'T3-13 媒体上传冒烟 $seed',
+          status: PostStatus.published,
+          media: uploader.buildAttachRequests(),
+        ),
+      );
+      expect(post.media.single.assetId, item.assetId);
+      final fetched = await dio.get<List<int>>(
+        post.media.single.url,
+        options: Options(responseType: ResponseType.bytes),
+      );
+      expect(fetched.statusCode, 200);
+      expect(fetched.data, pngBytes, reason: '预签名 GET 回读字节应与上传一致');
+
+      // 收尾：删除冒烟帖（asset 服务端软删语义随帖处理）。
+      await repository.deletePost(post.id);
+    },
+    skip: enabled ? false : '需 compose 后端在位，PATBOND_MEDIA_SMOKE=1 时执行',
+    timeout: const Timeout(Duration(minutes: 3)),
+  );
+}
+
+/// 透传压缩器：原样输出字节并声明 image/png（仅冒烟用——测试 VM 无
+/// flutter_image_compress 平台通道；生产走 NativeMediaImageCompressor）。
+class _PassthroughPngCompressor implements MediaImageCompressor {
+  @override
+  Future<CompressedMediaImage> compress(
+    PickedMediaImage source, {
+    required int quality,
+  }) async => CompressedMediaImage(bytes: source.bytes, mimeType: 'image/png');
+}

test/widgets/upload_progress_overlay_test.dart

@@ -0,0 +1,90 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:patbond_flutter/core/theme/app_theme.dart';
+import 'package:patbond_flutter/core/widgets/upload_progress_overlay.dart';
+import 'package:patbond_flutter/features/community/media_uploader.dart';
+
+/// UploadProgressOverlay（05 号规范 §3.3）：排队 / 上传中 / 失败三态
+/// 形态与失败整格点按重试。
+void main() {
+  Widget host(Widget overlay) => MaterialApp(
+    home: Scaffold(body: SizedBox(width: 100, height: 100, child: overlay)),
+  );
+
+  testWidgets('排队态：scrim + 「等待中」胶囊', (tester) async {
+    await tester.pumpWidget(
+      host(const UploadProgressOverlay(phase: MediaItemPhase.queued)),
+    );
+
+    expect(find.text('等待中'), findsOneWidget);
+    expect(find.byType(CircularProgressIndicator), findsNothing);
+  });
+
+  testWidgets('上传中态：环形进度带 value + 百分比胶囊', (tester) async {
+    await tester.pumpWidget(
+      host(
+        const UploadProgressOverlay(
+          phase: MediaItemPhase.uploading,
+          progress: 0.4,
+        ),
+      ),
+    );
+
+    final indicator = tester.widget<CircularProgressIndicator>(
+      find.byType(CircularProgressIndicator),
+    );
+    expect(indicator.value, 0.4);
+    expect(find.text('40%'), findsOneWidget);
+  });
+
+  testWidgets('confirming 定格 100%', (tester) async {
+    await tester.pumpWidget(
+      host(
+        const UploadProgressOverlay(
+          phase: MediaItemPhase.confirming,
+          progress: 0.4,
+        ),
+      ),
+    );
+
+    expect(find.text('100%'), findsOneWidget);
+  });
+
+  testWidgets('失败态：errorDark 图标 + 重试通栏，整格点按触发 onRetry', (tester) async {
+    var retried = 0;
+    await tester.pumpWidget(
+      host(
+        UploadProgressOverlay(
+          phase: MediaItemPhase.failed,
+          onRetry: () => retried++,
+        ),
+      ),
+    );
+
+    final icon = tester.widget<Icon>(find.byIcon(Icons.error_outline));
+    expect(icon.color, AppColors.errorDark);
+    expect(find.text('重试'), findsOneWidget);
+    // 整格（含图标区）点按即重试。
+    await tester.tap(find.byIcon(Icons.error_outline));
+    expect(retried, 1);
+  });
+
+  testWidgets('失败终态（onRetry null）：不显示重试通栏', (tester) async {
+    await tester.pumpWidget(
+      host(const UploadProgressOverlay(phase: MediaItemPhase.failed)),
+    );
+
+    expect(find.text('重试'), findsNothing);
+  });
+
+  testWidgets('成功态：150ms 淡出且不拦截点击、无残留文案', (tester) async {
+    await tester.pumpWidget(
+      host(const UploadProgressOverlay(phase: MediaItemPhase.ready)),
+    );
+    await tester.pumpAndSettle();
+
+    expect(find.text('等待中'), findsNothing);
+    expect(find.text('重试'), findsNothing);
+    expect(find.byType(IgnorePointer), findsWidgets);
+  });
+}