新增：媒体上传客户端——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>

lib/app/app.dart

@@ -152,7 +152,9 @@ class _AppState extends State<App> {
     return ApiPetsRepository(api: api);
   }
 
-  /// community 服务分端口直连（:8084），token 刷新单飞经共享 [TokenRefresher]。
+  /// community 服务分端口直连（:8084）；media 两步上传端点由 user 服务
+  /// （:8082 MediaController）提供，单独建 mediaApi 直连。token 刷新
+  /// 单飞经共享 [TokenRefresher]。
   CommunityRepository _buildCommunityRepository() {
     final dio = buildPatbondDio(
       session: sessionManager,
@@ -163,7 +165,16 @@ class _AppState extends State<App> {
       session: sessionManager,
       refresher: _ensureRefresher(),
     );
-    return ApiCommunityRepository(api: api);
+    final mediaDio = buildPatbondDio(
+      session: sessionManager,
+      baseUrl: patbondUserApiBaseUrl,
+    );
+    final mediaApi = ApiClient(
+      dio: mediaDio,
+      session: sessionManager,
+      refresher: _ensureRefresher(),
+    );
+    return ApiCommunityRepository(api: api, mediaApi: mediaApi);
   }
 
   AnalyticsPageName? _resolveRootPage() {

lib/core/widgets/upload_progress_overlay.dart

@@ -0,0 +1,143 @@
+import 'package:flutter/material.dart';
+import 'package:patbond_flutter/core/theme/app_theme.dart';
+import 'package:patbond_flutter/features/community/media_uploader.dart';
+
+/// 上传进度覆盖层（设计规范 05 号 §3.3）：叠加在编辑态九宫格单格上,
+/// 四视觉态映射 [MediaItemPhase]：
+///
+/// | 视觉态 | 阶段 | 形态 |
+/// | --- | --- | --- |
+/// | 排队 | queued / compressing | ink 40% scrim + 「等待中」白字胶囊 |
+/// | 上传中 | uploading / confirming | scrim + 白色环形进度 36 + 百分比胶囊 |
+/// | 成功 | ready | scrim 150ms 淡出，无残留角标 |
+/// | 失败 | failed | error 12% scrim + errorDark 图标 + 底部「重试」通栏 |
+///
+/// 失败态整格点按重试（[onRetry]，仅可重试失败传入）；组件本身不含
+/// 图片，由九宫格把它叠在缩略图上（Stack）。
+class UploadProgressOverlay extends StatelessWidget {
+  const UploadProgressOverlay({
+    required this.phase,
+    this.progress = 0,
+    this.onRetry,
+    super.key,
+  });
+
+  final MediaItemPhase phase;
+
+  /// 直传进度 0..1（uploading 态显示；confirming 定格 100%）。
+  final double progress;
+
+  /// 失败态整格点按回调；null 即失败不可重试（终态，只展示不响应）。
+  final VoidCallback? onRetry;
+
+  @override
+  Widget build(BuildContext context) {
+    return switch (phase) {
+      MediaItemPhase.queued || MediaItemPhase.compressing => _Scrim(
+        child: Center(child: _pill(const Text('等待中', style: _pillTextSm))),
+      ),
+      MediaItemPhase.uploading || MediaItemPhase.confirming => _Scrim(
+        child: Column(
+          mainAxisAlignment: MainAxisAlignment.center,
+          children: [
+            SizedBox(
+              width: 36,
+              height: 36,
+              child: CircularProgressIndicator(
+                value: phase == MediaItemPhase.confirming ? 1.0 : progress,
+                color: Colors.white,
+                backgroundColor: Colors.white24,
+                strokeWidth: 3,
+              ),
+            ),
+            const SizedBox(height: 8),
+            _pill(
+              Text(
+                '${((phase == MediaItemPhase.confirming ? 1.0 : progress) * 100).round()}%',
+                style: _pillTextXs,
+              ),
+            ),
+          ],
+        ),
+      ),
+      // 成功：scrim 150ms 淡出后不留任何角标。
+      MediaItemPhase.ready => const IgnorePointer(
+        child: AnimatedOpacity(
+          opacity: 0,
+          duration: Duration(milliseconds: 150),
+          child: _Scrim(child: SizedBox.expand()),
+        ),
+      ),
+      MediaItemPhase.failed => GestureDetector(
+        onTap: onRetry,
+        child: Container(
+          color: AppColors.error.withAlpha(31),
+          child: Column(
+            children: [
+              const Expanded(
+                child: Center(
+                  child: Icon(
+                    Icons.error_outline,
+                    size: 24,
+                    color: AppColors.errorDark,
+                  ),
+                ),
+              ),
+              if (onRetry != null)
+                Container(
+                  width: double.infinity,
+                  color: AppColors.errorDark,
+                  padding: const EdgeInsets.symmetric(vertical: 4),
+                  child: const Text(
+                    '重试',
+                    textAlign: TextAlign.center,
+                    style: TextStyle(
+                      color: Colors.white,
+                      fontSize: 11,
+                      fontWeight: FontWeight.w700,
+                    ),
+                  ),
+                ),
+            ],
+          ),
+        ),
+      ),
+    };
+  }
+
+  static const _pillTextSm = TextStyle(
+    color: Colors.white,
+    fontSize: 12,
+    fontWeight: FontWeight.w600,
+  );
+
+  static const _pillTextXs = TextStyle(
+    color: Colors.white,
+    fontSize: 11,
+    fontWeight: FontWeight.w700,
+  );
+
+  /// 白字衬 ink 80% 胶囊底（对 40% scrim 上的合成底色对比度兜底，§3.3）。
+  Widget _pill(Widget child) {
+    return Container(
+      padding: const EdgeInsets.symmetric(horizontal: 8, vertical: 2),
+      decoration: BoxDecoration(
+        color: AppColors.ink.withAlpha(204),
+        borderRadius: const BorderRadius.all(Radius.circular(AppRadius.pill)),
+      ),
+      child: child,
+    );
+  }
+}
+
+/// ink 40% 全格 scrim。
+class _Scrim extends StatelessWidget {
+  const _Scrim({required this.child});
+
+  final Widget child;
+
+  @override
+  Widget build(BuildContext context) {
+    return Container(color: AppColors.ink.withAlpha(102), child: child);
+  }
+}

lib/features/community/community_repository.dart

@@ -62,10 +62,21 @@ abstract class CommunityRepository {
 /// `Idempotency-Key`（1~128 字符；每次逻辑提交换新键；token 刷新后的
 /// 自动重放沿用同一个键——键在本层每次调用生成一次，重放走同一 headers）。
 /// 点赞/收藏/关注为 PUT/DELETE 语义幂等，无需幂等键。
+///
+/// 端口线路：community 域端点走 community 服务客户端；media 两步上传
+/// 端点由 **user 服务**提供（13 号报告 §2，MediaController 在
+/// patbond-user），经 [mediaApi] 直连——T3-13 真链路实测修正,
+/// 未提供时回落主客户端（既有测试桩场景）。
 class ApiCommunityRepository implements CommunityRepository {
-  ApiCommunityRepository({required this._api, this._uuid = const Uuid()});
+  ApiCommunityRepository({
+    required ApiClient api,
+    ApiClient? mediaApi,
+    this._uuid = const Uuid(),
+  }) : _api = api,
+       _mediaApi = mediaApi ?? api;
 
   final ApiClient _api;
+  final ApiClient _mediaApi;
   final Uuid _uuid;
 
   Future<Object?> _request(
@@ -74,9 +85,10 @@ class ApiCommunityRepository implements CommunityRepository {
     Object? body,
     Map<String, Object?>? query,
     bool idempotent = false,
+    bool media = false,
   }) async {
     try {
-      return await _api.request(
+      return await (media ? _mediaApi : _api).request(
         path,
         method: method,
         body: body,
@@ -101,6 +113,7 @@ class ApiCommunityRepository implements CommunityRepository {
       '/api/v1/media/uploads',
       method: 'POST',
       body: request.toJson(),
+      media: true,
     );
     return MediaUploadCredentials.fromJson(_asMap(data));
   }
@@ -111,6 +124,7 @@ class ApiCommunityRepository implements CommunityRepository {
     final data = await _request(
       '/api/v1/media/uploads/$assetId/complete',
       method: 'POST',
+      media: true,
     );
     return MediaAsset.fromJson(_asMap(data));
   }

lib/features/community/media_compression.dart

@@ -0,0 +1,53 @@
+import 'dart:typed_data';
+
+import 'package:flutter_image_compress/flutter_image_compress.dart';
+import 'package:patbond_flutter/features/community/media_picking.dart';
+
+/// 压缩产物（直传本体）。mimeType 与直传 PUT 的 Content-Type、
+/// createUpload 登记值三处必须一致（Content-Type 已签进预签名签名）。
+class CompressedMediaImage {
+  const CompressedMediaImage({required this.bytes, required this.mimeType});
+
+  final Uint8List bytes;
+  final String mimeType;
+
+  int get byteSize => bytes.length;
+}
+
+/// 压缩抽象：quality 由 MediaUploader 的降质阶梯驱动（80 → 60），
+/// 单测注入假实现控制产物大小。
+abstract class MediaImageCompressor {
+  Future<CompressedMediaImage> compress(
+    PickedMediaImage source, {
+    required int quality,
+  });
+}
+
+/// 基于 flutter_image_compress 的原生压缩实现（03 号评估 §4.1 选型）。
+///
+/// 策略（03 号 §4.1 + 13 号报告偏差 #6）：长边 ≤2048 重采样、统一转码
+/// JPEG（服务端 mime 白名单不收 HEIC，客户端统一出 jpeg）；
+/// autoCorrectionAngle 矫正方向后不保留 EXIF——顺带剥离 GPS 定位隐私，
+/// **不要开 keepExif**。
+class NativeMediaImageCompressor implements MediaImageCompressor {
+  const NativeMediaImageCompressor({this.maxLongEdge = 2048});
+
+  final int maxLongEdge;
+
+  @override
+  Future<CompressedMediaImage> compress(
+    PickedMediaImage source, {
+    required int quality,
+  }) async {
+    final bytes = await FlutterImageCompress.compressWithList(
+      source.bytes,
+      minWidth: maxLongEdge,
+      minHeight: maxLongEdge,
+      quality: quality,
+      format: CompressFormat.jpeg,
+      autoCorrectionAngle: true,
+      keepExif: false,
+    );
+    return CompressedMediaImage(bytes: bytes, mimeType: 'image/jpeg');
+  }
+}

lib/features/community/media_direct_upload.dart

@@ -0,0 +1,82 @@
+import 'dart:typed_data';
+
+import 'package:dio/dio.dart';
+
+/// 预签名直传失败。
+///
+/// - [statusCode] 为 null 表示网络层失败（断连/超时），可原凭据重试；
+/// - 403 为存储侧拒绝签名（凭据过期/被改动），须重新 createUpload 换新凭据；
+/// - 其余状态码按可重试处理（重试走完整重传）。
+class MediaDirectUploadException implements Exception {
+  const MediaDirectUploadException({this.statusCode, required this.message});
+
+  final int? statusCode;
+  final String message;
+
+  /// 存储侧拒绝了凭据（签名过期/不符），重试前必须换新凭据。
+  bool get isCredentialRejected => statusCode == 403;
+
+  @override
+  String toString() => 'MediaDirectUploadException($statusCode): $message';
+}
+
+/// 预签名 PUT 直传抽象（两步上传第二步的传输层）。
+///
+/// 不走业务信封、不带 Bearer 鉴权——鉴权就是 URL 里的签名本身;
+/// [headers] 即 createUpload 返回的 requiredHeaders，必须原样携带
+/// （Content-Type 已签进签名，改动即 403）。
+abstract class MediaDirectUploadClient {
+  Future<void> put({
+    required String url,
+    required Map<String, String> headers,
+    required Uint8List bytes,
+    void Function(int sent, int total)? onProgress,
+  });
+}
+
+/// 基于裸 Dio 的实现：独立实例，无 AuthInterceptor（预签名 URL 携带
+/// Authorization 头会破坏 SigV4 校验），sendTimeout 按 10 MiB 弱网上限放宽。
+class DioMediaDirectUploadClient implements MediaDirectUploadClient {
+  DioMediaDirectUploadClient({Dio? dio})
+    : _dio =
+          dio ??
+          Dio(
+            BaseOptions(
+              connectTimeout: const Duration(seconds: 5),
+              sendTimeout: const Duration(seconds: 120),
+              receiveTimeout: const Duration(seconds: 30),
+              validateStatus: (_) => true,
+            ),
+          );
+
+  final Dio _dio;
+
+  @override
+  Future<void> put({
+    required String url,
+    required Map<String, String> headers,
+    required Uint8List bytes,
+    void Function(int sent, int total)? onProgress,
+  }) async {
+    final Response<Object?> response;
+    try {
+      response = await _dio.put<Object?>(
+        url,
+        data: Stream<Uint8List>.value(bytes),
+        options: Options(
+          headers: {...headers, Headers.contentLengthHeader: bytes.length},
+        ),
+        onSendProgress: onProgress,
+      );
+    } on DioException catch (error) {
+      throw MediaDirectUploadException(message: '直传网络失败：${error.type.name}');
+    }
+    final status = response.statusCode ?? 0;
+    if (status < 200 || status >= 300) {
+      throw MediaDirectUploadException(
+        statusCode: status,
+        message: '存储侧拒绝直传：HTTP $status',
+      );
+    }
+  }
+}

lib/features/community/media_picking.dart

@@ -0,0 +1,48 @@
+import 'dart:typed_data';
+
+import 'package:image_picker/image_picker.dart';
+
+/// 待上传的一张原始图（选择器产物，压缩前形态）。
+///
+/// 只持有内存字节：不落磁盘副本、不携带原始文件路径，配合压缩层剥离
+/// EXIF（含 GPS）的隐私纪律（03 号评估 §4.1）。
+class PickedMediaImage {
+  const PickedMediaImage({required this.bytes, this.name});
+
+  /// 原始字节（供压缩层消费与格内缩略预览）。
+  final Uint8List bytes;
+
+  /// 原始文件名（仅诊断用途，不参与上传——objectKey 由服务端生成）。
+  final String? name;
+}
+
+/// 图片选择抽象：MediaUploader 只依赖本接口，单测注入假实现，
+/// widget 测试无需平台通道。
+abstract class MediaImagePicker {
+  /// 拉起系统选择器，最多返回 [limit] 张；用户取消返回空列表。
+  Future<List<PickedMediaImage>> pickImages({required int limit});
+}
+
+/// 基于 image_picker 的系统选择器实现（03 号评估 §4.1 选型：官方维护、
+/// pickMultiImage 多选，M3 不引入重型相册组件）。
+class SystemMediaImagePicker implements MediaImagePicker {
+  SystemMediaImagePicker({ImagePicker? picker})
+    : _picker = picker ?? ImagePicker();
+
+  final ImagePicker _picker;
+
+  @override
+  Future<List<PickedMediaImage>> pickImages({required int limit}) async {
+    // 仅剩一个空位时用单选（pickMultiImage 的 limit 在部分平台要求 ≥2）。
+    final files = limit <= 1
+        ? [?await _picker.pickImage(source: ImageSource.gallery)]
+        : await _picker.pickMultiImage(limit: limit);
+    final images = <PickedMediaImage>[];
+    for (final file in files.take(limit)) {
+      images.add(
+        PickedMediaImage(bytes: await file.readAsBytes(), name: file.name),
+      );
+    }
+    return images;
+  }
+}

lib/features/community/media_uploader.dart

@@ -0,0 +1,471 @@
+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++;
+    }
+  }
+}