新增：宠物头像接线——铅笔角标接上传、列表与详情展示真实头像（T3.5-09）

- `Pet.avatarUrl` 入模型；列表卡与详情头像改用真实预签名 URL（无图仍回退
  爪印占位——服务端对非 ready 的 asset 直接给 null，客户端只有一种占位）。
- 详情页铅笔角标自此有功能：接 `MediaUploader`（purpose=pet_avatar）；已有
  头像时先给「更换 / 移除」二选一，移除即三态显式 null。
- 权限按 **WRITE 档**呈现（ADR-022 D3.5-3：owner + caregiver 可改头像，
  viewer 无入口），与资料编辑的 MANAGE 档刻意不同。因此纯头像 PATCH 只发
  `version` + `avatarAssetId`，**不夹带任何资料字段**——夹带会让服务端按更严
  的一半定档，caregiver 立刻 403。
- `UpdatePetRequest.avatarAssetId` 是该 schema 唯一的三态字段，其余字段保持
  M2 两态语义（它们的 CHECK 约束本就不允许空值，「清空」无意义）。
- 40902 冲突后重取档案让用户自行决定重来，不静默重放（头像是用户可见的
  覆盖操作，不该自动生效两次）。

测试 588 → 597（+9）。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

lib/core/widgets/pet_avatar.dart

@@ -28,9 +28,12 @@ enum PetAvatarSize {
 /// 头像实现。圆形裁切 + 3px `surface` 白描边 + 轻投影（正典
 /// `.patbond-avatar` 规格），可选右下编辑徽标与品牌渐变环。
 ///
-/// M2 首版不做头像上传（ADR-010 / D2-1 裁决），[url] 为 null 时渲染
-/// 本地占位形态（`surfaceTint` 底 + `Icons.pets`）；有图时经
-/// [RemoteImage] 加载（loading / 失败兜底由其内置）。
+/// M2 首版不做头像上传（ADR-010 / D2-1 裁决）；T3.5-09 起 [url] 由服务端
+/// `Pet.avatarUrl`（预签名 GET）驱动，[url] 为 null 时仍渲染本地占位形态
+/// （`surfaceTint` 底 + `Icons.pets`）——签一个必然 404 的 URL 比返回 null
+/// 更糟，故服务端对非 ready 的 asset 直接给 null，客户端只有一种占位逻辑。
+/// 有图时经 [RemoteImage] 加载（缓存 key 已剥签名参数；loading / 失败兜底
+/// 由其内置）。
 class PetAvatar extends StatelessWidget {
   const PetAvatar({
     required this.size,
@@ -45,7 +48,7 @@ class PetAvatar extends StatelessWidget {
 
   final PetAvatarSize size;
 
-  /// 头像图 URL；null 为本地占位形态（M2 默认）。
+  /// 头像图 URL；null 为本地占位形态（无头像 / asset 非 ready / 存储未配置）。
   final String? url;
 
   /// 可点击时整体 [InkWell] 圆形 ripple。

lib/features/pets/pet_detail_page.dart

@@ -2,10 +2,12 @@ import 'package:flutter/material.dart';
 import 'package:patbond_flutter/core/navigation/fade_route.dart';
 import 'package:patbond_flutter/core/network/api_exception.dart';
 import 'package:patbond_flutter/core/theme/app_theme.dart';
+import 'package:patbond_flutter/core/widgets/avatar_upload_sheet.dart';
 import 'package:patbond_flutter/core/widgets/empty_state_illustration.dart';
 import 'package:patbond_flutter/core/widgets/inline_error_banner.dart';
 import 'package:patbond_flutter/core/widgets/pet_avatar.dart';
 import 'package:patbond_flutter/core/widgets/record_type_dot.dart';
+import 'package:patbond_flutter/features/community/community_models.dart';
 import 'package:patbond_flutter/features/pets/care_reminders_page.dart';
 import 'package:patbond_flutter/features/pets/health_events_page.dart';
 import 'package:patbond_flutter/features/pets/health_record_analytics.dart';
@@ -43,6 +45,7 @@ class PetDetailPage extends StatefulWidget {
     super.key,
     this.analytics,
     this.healthAnalytics,
+    this.avatarUploaderBuilder,
   });
 
   final PetsController controller;
@@ -50,6 +53,10 @@ class PetDetailPage extends StatefulWidget {
   final PetAnalytics? analytics;
   final HealthRecordAnalytics? healthAnalytics;
 
+  /// 头像上传编排器构造口（T3.5-09）；null 即本次构建未装配上传能力，
+  /// 隐藏头像编辑入口（生产装配恒注入，见 `app.dart`）。
+  final AvatarUploaderBuilder? avatarUploaderBuilder;
+
   @override
   State<PetDetailPage> createState() => _PetDetailPageState();
 }
@@ -186,6 +193,109 @@ class _PetDetailPageState extends State<PetDetailPage> {
   /// 记录写入权限档 WRITE（owner + caregiver）；viewer 隐藏录入入口。
   bool get _canWriteRecords => _pet?.myRole != PetRole.viewer;
 
+  /// 头像写入权限档 **WRITE**（ADR-022 决策 D3.5-3：头像属日常照护信息，
+  /// 与体重/疫苗同档，owner + caregiver 均可改；viewer 只读）。
+  ///
+  /// 注意这与 [_canEdit]（MANAGE，仅 owner）**刻意不同**：服务端按「本次
+  /// 请求触及了哪些字段」定档——只带 avatarAssetId 走 WRITE，碰任一资料
+  /// 字段即 MANAGE。故这里只发纯头像 PATCH，不夹带任何资料字段。
+  bool get _canEditAvatar =>
+      _phase == _DetailPhase.ready &&
+      _pet?.myRole != PetRole.viewer &&
+      widget.avatarUploaderBuilder != null;
+
+  /// 头像入口：已有头像时先给「更换 / 移除」二选一，没有则直接拉起上传。
+  Future<void> _onAvatarTap() async {
+    final pet = _pet;
+    if (pet == null || !_canEditAvatar) return;
+    if (pet.avatarUrl == null) {
+      await _uploadAvatar();
+      return;
+    }
+    final action = await showModalBottomSheet<String>(
+      context: context,
+      showDragHandle: true,
+      builder: (context) => SafeArea(
+        child: Column(
+          mainAxisSize: MainAxisSize.min,
+          children: [
+            ListTile(
+              leading: const Icon(Icons.photo_camera_outlined),
+              title: const Text('更换头像'),
+              onTap: () => Navigator.pop(context, 'replace'),
+            ),
+            ListTile(
+              leading: const Icon(
+                Icons.delete_outline,
+                color: AppColors.errorDark,
+              ),
+              title: const Text(
+                '移除头像',
+                style: TextStyle(color: AppColors.errorDark),
+              ),
+              onTap: () => Navigator.pop(context, 'clear'),
+            ),
+          ],
+        ),
+      ),
+    );
+    if (!mounted || action == null) return;
+    if (action == 'replace') {
+      await _uploadAvatar();
+    } else {
+      // 三态「显式 null」= 清除头像（缺省是「不改」，两者在 JSON 上不同）。
+      await _patchAvatar(const PatchField<String>.clear(), '已移除头像');
+    }
+  }
+
+  Future<void> _uploadAvatar() async {
+    final builder = widget.avatarUploaderBuilder;
+    if (builder == null) return;
+    final assetId = await showAvatarUploadSheet(
+      context,
+      builder: builder,
+      // 用途即引用侧的类型检查：帖图或用户头像挂到宠物上会被答 404/40405。
+      purpose: MediaPurpose.petAvatar,
+    );
+    if (assetId == null || !mounted) return;
+    await _patchAvatar(PatchField<String>.value(assetId), '头像已更新');
+  }
+
+  /// 纯头像 PATCH：请求体只有 `version` + `avatarAssetId`，**不带任何资料
+  /// 字段**——夹带资料字段会把权限档从 WRITE 抬到 MANAGE，caregiver 立刻
+  /// 403（服务端刻意按更严的一半判，堵「夹带改名」）。
+  Future<void> _patchAvatar(PatchField<String> intent, String okMessage) async {
+    final pet = _pet;
+    if (pet == null) return;
+    try {
+      final updated = await widget.controller.updatePet(
+        pet.id,
+        UpdatePetRequest(version: pet.version, avatarAssetId: intent),
+      );
+      if (!mounted) return;
+      setState(() {
+        _pet = updated;
+        _phase = _DetailPhase.ready;
+      });
+      ScaffoldMessenger.of(
+        context,
+      ).showSnackBar(SnackBar(content: Text(okMessage)));
+    } on PetVersionConflictException catch (error) {
+      // 40902：他人已改过这行。重取档案拿新 version，让用户自行决定是否重来
+      // （不静默重放——头像是用户可见的覆盖操作，不该自动生效两次）。
+      if (!mounted) return;
+      ScaffoldMessenger.of(
+        context,
+      ).showSnackBar(SnackBar(content: Text(petAvatarSaveErrorMessage(error))));
+      await _load();
+    } on ApiException catch (error) {
+      if (!mounted) return;
+      ScaffoldMessenger.of(
+        context,
+      ).showSnackBar(SnackBar(content: Text(petAvatarSaveErrorMessage(error))));
+    }
+  }
+
   Future<void> _openWeights(Pet pet) async {
     await Navigator.of(context).push(
       // 列表页页名不在字典 v2 枚举内（06 §5.2 验收 4：字典外不上报），
@@ -306,11 +416,14 @@ class _PetDetailPageState extends State<PetDetailPage> {
       children: [
         Column(
           children: [
+            // T3.5-09：头像展示真实预签名 URL（无图回退爪印占位）；铅笔角标
+            // 自此有功能——接 MediaUploader 上传 pet_avatar，WRITE 档可见。
             PetAvatar(
               size: PetAvatarSize.xl,
-              showEditBadge: _canEdit,
-              onTap: _canEdit ? _openEdit : null,
-              semanticLabel: _canEdit ? '编辑宠物资料' : null,
+              url: pet.avatarUrl,
+              showEditBadge: _canEditAvatar,
+              onTap: _canEditAvatar ? _onAvatarTap : null,
+              semanticLabel: _canEditAvatar ? '更换宠物头像' : null,
             ),
             const SizedBox(height: 12),
             Text(pet.name, style: Theme.of(context).textTheme.headlineSmall),

lib/features/pets/pet_display.dart

@@ -54,3 +54,21 @@ String petLoadErrorMessage(ApiException? error) => switch (error) {
   ApiRateLimitException _ => '请求过于频繁，请稍后再试',
   _ => '加载失败，请稍后重试',
 };
+
+/// 宠物头像写入失败的文案（T3.5-09）。按契约 v1.4.0 为
+/// `PATCH /pets/{petId}` 新增的两格分层：
+///
+/// - 404/40405：asset 不存在 / 非本人 / 已删 / **用途不符**（帖图或用户头像
+///   当宠物头像）→ 引导重新上传，而不是「宠物不存在」（40401 才是那个）。
+/// - 422/42203：本人的 `pet_avatar` asset 仍在 uploading/failed → 可重试。
+/// - 403/40300：viewer 改头像（入口本已按 myRole 隐藏，此处兜底防越权构造）。
+/// - 409/40902：版本冲突 → 由调用方重取档案后重试。
+String petAvatarSaveErrorMessage(ApiException? error) => switch (error) {
+  ApiBusinessException(code: ApiCodes.mediaNotFound) => '头像已失效，请重新上传',
+  ApiBusinessException(code: ApiCodes.mediaNotReady) => '头像还没上传完，请稍后重试',
+  ApiBusinessException(code: ApiCodes.petAccessDenied) => '你没有修改该宠物头像的权限',
+  ApiBusinessException(code: ApiCodes.versionConflict) => '档案已被更新，请重新操作',
+  ApiNetworkException _ => '网络异常，请检查网络后重试',
+  ApiRateLimitException _ => '请求过于频繁，请稍后再试',
+  _ => '头像保存失败，请稍后重试',
+};

lib/features/pets/pet_models.dart

@@ -1,8 +1,11 @@
-/// pets 域响应 / 请求模型（接口契约冻结稿 openapi.yaml v1.2.0，
+/// pets 域响应 / 请求模型（接口契约冻结稿 openapi.yaml v1.4.0，
 /// 字段名与后端逐字一致；枚举取值严格校验，未知值抛 [FormatException]
 /// 以便契约漂移在测试期暴露而非静默吞掉）。
 library;
 
+import 'package:patbond_flutter/core/models/patch_field.dart';
+
+export 'package:patbond_flutter/core/models/patch_field.dart';
 export 'package:patbond_flutter/core/models/cursor_page.dart';
 
 /// 物种（创建即定，不可修改）。
@@ -143,6 +146,7 @@ class Pet {
     required this.microchipNo,
     required this.sterilizedOn,
     required this.status,
+    required this.avatarUrl,
     required this.myRole,
     required this.createdAt,
     required this.updatedAt,
@@ -164,6 +168,9 @@ class Pet {
       microchipNo: json['microchipNo'] as String?,
       sterilizedOn: _dateOrNull(json['sterilizedOn']),
       status: PetStatus.fromJson(json['status'] as String),
+      // 契约 v1.4.0 新增：时效性预签名 GET URL，每次响应现签；
+      // 不得持久化、过期即重取。响应**不含 avatarAssetId**（只写不读）。
+      avatarUrl: json['avatarUrl'] as String?,
       myRole: PetRole.fromJson(json['myRole'] as String),
       createdAt: DateTime.parse(json['createdAt'] as String),
       updatedAt: DateTime.parse(json['updatedAt'] as String),
@@ -184,6 +191,11 @@ class Pet {
   final String? microchipNo;
   final DateTime? sterilizedOn;
   final PetStatus status;
+
+  /// 头像预签名 GET URL；无头像 / asset 非 ready / 对象存储未配置均为 null。
+  /// 「有头像」等价于本字段非 null（契约不外露 assetId）。
+  final String? avatarUrl;
+
   final PetRole myRole;
   final DateTime createdAt;
   final DateTime updatedAt;
@@ -230,8 +242,17 @@ class CreatePetRequest {
   };
 }
 
-/// 更新宠物请求（部分更新：缺席字段不变；不支持清空回 null；
-/// 品种对整体替换；species 不可改；version 乐观锁必填）。
+/// 更新宠物请求（部分更新：缺席字段不变；品种对整体替换；species 不可改；
+/// version 乐观锁必填）。
+///
+/// **两态与三态并存**：除 [avatarAssetId] 外的字段沿 M2 两态语义（缺省或
+/// null 皆为「不改」，不支持清空回 null——它们的 CHECK 约束本就不允许空值）；
+/// [avatarAssetId] 是本 schema **唯一的三态字段**（契约 v1.4.0），因为
+/// 「删掉我设的那张头像」是一等公民操作，两态根本无法表达。
+///
+/// **权限随本次触及的字段变档**（ADR-022 + 服务端 `requiredLevel`）：
+/// 只带 [avatarAssetId] 走 WRITE（owner + caregiver 均可）；碰任一资料字段
+/// 即 MANAGE（仅 owner）；混合请求取更严的一半（防「夹带改名」）。
 class UpdatePetRequest {
   const UpdatePetRequest({
     required this.version,
@@ -245,6 +266,7 @@ class UpdatePetRequest {
     this.microchipNo,
     this.sterilizedOn,
     this.status,
+    this.avatarAssetId = const PatchField<String>.absent(),
   });
 
   final int version;
@@ -259,19 +281,26 @@ class UpdatePetRequest {
   final DateTime? sterilizedOn;
   final PetStatus? status;
 
-  Map<String, Object?> toJson() => {
-    'version': version,
-    if (name != null) 'name': name,
-    if (breedId != null) 'breedId': breedId,
-    if (customBreedName != null) 'customBreedName': customBreedName,
-    if (sex != null) 'sex': sex!.name,
-    if (birthDate != null) 'birthDate': dateToJson(birthDate!),
-    if (birthDateEstimated != null) 'birthDateEstimated': birthDateEstimated,
-    if (personality != null) 'personality': personality,
-    if (microchipNo != null) 'microchipNo': microchipNo,
-    if (sterilizedOn != null) 'sterilizedOn': dateToJson(sterilizedOn!),
-    if (status != null) 'status': status!.name,
-  };
+  /// 宠物头像 asset（两步上传产物，`purpose` 须为 `pet_avatar`）。三态。
+  final PatchField<String> avatarAssetId;
+
+  Map<String, Object?> toJson() {
+    final json = <String, Object?>{
+      'version': version,
+      if (name != null) 'name': name,
+      if (breedId != null) 'breedId': breedId,
+      if (customBreedName != null) 'customBreedName': customBreedName,
+      if (sex != null) 'sex': sex!.name,
+      if (birthDate != null) 'birthDate': dateToJson(birthDate!),
+      if (birthDateEstimated != null) 'birthDateEstimated': birthDateEstimated,
+      if (personality != null) 'personality': personality,
+      if (microchipNo != null) 'microchipNo': microchipNo,
+      if (sterilizedOn != null) 'sterilizedOn': dateToJson(sterilizedOn!),
+      if (status != null) 'status': status!.name,
+    };
+    avatarAssetId.writeTo(json, 'avatarAssetId');
+    return json;
+  }
 }
 
 /// 品种目录项（只读字典）。

lib/features/pets/pets_page.dart

@@ -2,6 +2,7 @@ import 'package:flutter/material.dart';
 import 'package:patbond_flutter/analytics/analytics_page_name.dart';
 import 'package:patbond_flutter/core/navigation/fade_route.dart';
 import 'package:patbond_flutter/core/theme/app_theme.dart';
+import 'package:patbond_flutter/core/widgets/avatar_upload_sheet.dart';
 import 'package:patbond_flutter/core/widgets/empty_state_illustration.dart';
 import 'package:patbond_flutter/core/widgets/inline_error_banner.dart';
 import 'package:patbond_flutter/core/widgets/pet_avatar.dart';
@@ -25,6 +26,7 @@ class PetsPage extends StatefulWidget {
     super.key,
     this.analytics,
     this.healthAnalytics,
+    this.avatarUploaderBuilder,
   });
 
   final PetsController controller;
@@ -33,6 +35,9 @@ class PetsPage extends StatefulWidget {
   /// health_record 域埋点（T2-13，记录页面族透传）。
   final HealthRecordAnalytics? healthAnalytics;
 
+  /// 头像上传编排器构造口（T3.5-09，透传详情页）。
+  final AvatarUploaderBuilder? avatarUploaderBuilder;
+
   @override
   State<PetsPage> createState() => _PetsPageState();
 }
@@ -75,6 +80,7 @@ class _PetsPageState extends State<PetsPage> {
           petId: pet.id,
           analytics: widget.analytics,
           healthAnalytics: widget.healthAnalytics,
+          avatarUploaderBuilder: widget.avatarUploaderBuilder,
         ),
         settings: RouteSettings(name: AnalyticsPageName.petDetail.pageName),
       ),
@@ -189,7 +195,8 @@ class _PetCard extends StatelessWidget {
           padding: const EdgeInsets.all(14),
           child: Row(
             children: [
-              const PetAvatar(size: PetAvatarSize.lg),
+              // T3.5-09：列表卡展示真实头像（预签名 URL，无图回退爪印占位）。
+              PetAvatar(size: PetAvatarSize.lg, url: pet.avatarUrl),
               const SizedBox(width: 12),
               Expanded(
                 child: Column(

test/features/pets/pet_avatar_wiring_test.dart

@@ -0,0 +1,323 @@
+import 'dart:async';
+
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:patbond_flutter/core/network/api_exception.dart';
+import 'package:patbond_flutter/core/theme/app_theme.dart';
+import 'package:patbond_flutter/core/widgets/pet_avatar.dart';
+import 'package:patbond_flutter/features/community/community_models.dart';
+import 'package:patbond_flutter/features/community/media_uploader.dart';
+import 'package:patbond_flutter/features/pets/pet_detail_page.dart';
+import 'package:patbond_flutter/features/pets/pet_display.dart';
+import 'package:patbond_flutter/features/pets/pet_exceptions.dart';
+import 'package:patbond_flutter/features/pets/pet_models.dart';
+import 'package:patbond_flutter/features/pets/pets_controller.dart';
+import 'package:patbond_flutter/features/pets/pets_page.dart';
+
+import '../../helpers/community_test_helpers.dart';
+import '../../helpers/media_test_helpers.dart';
+import '../../helpers/pet_test_helpers.dart';
+
+/// T3.5-09 宠物头像接线。
+///
+/// 两条不变量在这里守住：
+/// 1. **权限按 WRITE 档呈现**（owner + caregiver 有入口，viewer 没有），与
+///    资料编辑（MANAGE，仅 owner）不同档。
+/// 2. **纯头像 PATCH 不夹带资料字段**——夹带会把服务端定档抬到 MANAGE，
+///    caregiver 立刻 403。
+void main() {
+  const signedAvatar =
+      'https://minio.local/patbond-media/pet_avatar/2026/09/a-1'
+      '?X-Amz-Signature=sig';
+
+  late FakePetsRepository pets;
+  late PetsController controller;
+  late FakeCommunityRepository community;
+  late FakeMediaImagePicker picker;
+  late FakeMediaCompressor compressor;
+  late FakeDirectUploadClient direct;
+
+  setUp(() {
+    pets = FakePetsRepository();
+    controller = PetsController(repository: pets);
+    community = FakeCommunityRepository();
+    picker = FakeMediaImagePicker([decodablePickedImage()]);
+    compressor = FakeMediaCompressor();
+    direct = FakeDirectUploadClient();
+    community.onCreateMediaUpload = (_) async => credentials();
+    community.onCompleteMediaUpload = (assetId) async =>
+        readyAsset(assetId: assetId);
+  });
+
+  MediaUploader buildUploader(MediaPurpose purpose) => MediaUploader(
+    repository: community,
+    purpose: purpose,
+    picker: picker,
+    compressor: compressor,
+    directUpload: direct,
+    maxImages: 1,
+    maxConcurrentUploads: 1,
+  );
+
+  Future<void> pumpDetail(
+    WidgetTester tester, {
+    bool withUploader = true,
+  }) async {
+    tester.view.physicalSize = const Size(700, 2400);
+    tester.view.devicePixelRatio = 1.0;
+    addTearDown(tester.view.reset);
+    await tester.pumpWidget(
+      MaterialApp(
+        theme: buildAppTheme(),
+        home: const Scaffold(body: Text('列表基底')),
+      ),
+    );
+    final navigator = tester.state<NavigatorState>(find.byType(Navigator));
+    unawaited(
+      navigator.push(
+        MaterialPageRoute<void>(
+          builder: (_) => PetDetailPage(
+            controller: controller,
+            petId: 'p-1',
+            avatarUploaderBuilder: withUploader ? buildUploader : null,
+          ),
+        ),
+      ),
+    );
+    await tester.pump();
+  }
+
+  group('契约字段', () {
+    test('Pet.avatarUrl 解析（无头像为 null；不外露 avatarAssetId）', () {
+      expect(buildPet('p-1').avatarUrl, isNull);
+      expect(
+        buildPet('p-1', overrides: {'avatarUrl': signedAvatar}).avatarUrl,
+        signedAvatar,
+      );
+    });
+
+    test('UpdatePetRequest：只带头像时载荷仅 version + avatarAssetId', () {
+      const request = UpdatePetRequest(
+        version: 3,
+        avatarAssetId: PatchField<String>.value('a-1'),
+      );
+      expect(request.toJson(), {'version': 3, 'avatarAssetId': 'a-1'});
+    });
+
+    test('UpdatePetRequest：清除头像为显式 null；缺省则键不出现', () {
+      expect(
+        const UpdatePetRequest(
+          version: 3,
+          avatarAssetId: PatchField<String>.clear(),
+        ).toJson(),
+        {'version': 3, 'avatarAssetId': null},
+      );
+      final absent = const UpdatePetRequest(version: 3, name: '豆豆').toJson();
+      expect(absent, {'version': 3, 'name': '豆豆'});
+      expect(
+        absent.containsKey('avatarAssetId'),
+        isFalse,
+        reason: '改名请求不该顺手把头像清掉',
+      );
+    });
+
+    test('头像写入失败文案分层（40405 / 42203 与 40401 区分开）', () {
+      expect(
+        petAvatarSaveErrorMessage(
+          const ApiBusinessException(
+            code: ApiCodes.mediaNotFound,
+            message: 'x',
+          ),
+        ),
+        '头像已失效，请重新上传',
+      );
+      expect(
+        petAvatarSaveErrorMessage(
+          const ApiBusinessException(
+            code: ApiCodes.mediaNotReady,
+            message: 'x',
+          ),
+        ),
+        '头像还没上传完，请稍后重试',
+      );
+      expect(
+        petAvatarSaveErrorMessage(
+          const ApiBusinessException(
+            code: ApiCodes.petAccessDenied,
+            message: 'x',
+          ),
+        ),
+        '你没有修改该宠物头像的权限',
+      );
+    });
+  });
+
+  group('权限呈现（WRITE 档）', () {
+    testWidgets('owner：头像可点 + 铅笔角标', (tester) async {
+      pets.getPetHandler = (_) async => buildPet('p-1');
+      await pumpDetail(tester);
+      await tester.pumpAndSettle();
+
+      final avatar = tester.widget<PetAvatar>(find.byType(PetAvatar));
+      expect(avatar.showEditBadge, isTrue);
+      expect(avatar.onTap, isNotNull);
+      expect(avatar.semanticLabel, '更换宠物头像');
+    });
+
+    testWidgets('caregiver：头像入口在（WRITE 档），但资料编辑入口不在（MANAGE 档）', (tester) async {
+      pets.getPetHandler = (_) async =>
+          buildPet('p-1', overrides: {'myRole': 'caregiver'});
+      await pumpDetail(tester);
+      await tester.pumpAndSettle();
+
+      final avatar = tester.widget<PetAvatar>(find.byType(PetAvatar));
+      expect(avatar.showEditBadge, isTrue, reason: 'ADR-022：头像属 WRITE 档');
+      expect(avatar.onTap, isNotNull);
+      expect(find.text('编辑资料'), findsNothing, reason: '改档案仍是 MANAGE 档');
+    });
+
+    testWidgets('viewer：头像不可点、无角标', (tester) async {
+      pets.getPetHandler = (_) async =>
+          buildPet('p-1', overrides: {'myRole': 'viewer'});
+      await pumpDetail(tester);
+      await tester.pumpAndSettle();
+
+      final avatar = tester.widget<PetAvatar>(find.byType(PetAvatar));
+      expect(avatar.showEditBadge, isFalse);
+      expect(avatar.onTap, isNull);
+    });
+
+    testWidgets('未装配上传能力：owner 也不渲染头像入口', (tester) async {
+      pets.getPetHandler = (_) async => buildPet('p-1');
+      await pumpDetail(tester, withUploader: false);
+      await tester.pumpAndSettle();
+
+      final avatar = tester.widget<PetAvatar>(find.byType(PetAvatar));
+      expect(avatar.showEditBadge, isFalse);
+      expect(avatar.onTap, isNull);
+    });
+  });
+
+  group('上传与清除', () {
+    testWidgets('无头像 → 点头像直接上传 → PATCH 只带 version + avatarAssetId', (
+      tester,
+    ) async {
+      pets.getPetHandler = (_) async => buildPet('p-1', version: 3);
+      UpdatePetRequest? captured;
+      pets.updatePetHandler = (petId, request) async {
+        captured = request;
+        return buildPet(
+          'p-1',
+          version: 4,
+          overrides: {'avatarUrl': signedAvatar},
+        );
+      };
+      await pumpDetail(tester);
+      await tester.pumpAndSettle();
+
+      await tester.tap(find.byType(PetAvatar));
+      await tester.pumpAndSettle();
+      await tester.tap(find.text('使用这张'));
+      await tester.pumpAndSettle();
+
+      expect(community.lastMediaUploadRequest!.purpose, MediaPurpose.petAvatar);
+      expect(captured!.toJson(), {'version': 3, 'avatarAssetId': 'a-1'});
+      expect(find.text('头像已更新'), findsOneWidget);
+      // 详情页头像随即换成服务端回显的现签 URL。
+      expect(
+        tester.widget<PetAvatar>(find.byType(PetAvatar)).url,
+        signedAvatar,
+      );
+    });
+
+    testWidgets('已有头像 → 点头像给「更换 / 移除」；移除发显式 null', (tester) async {
+      pets.getPetHandler = (_) async =>
+          buildPet('p-1', version: 5, overrides: {'avatarUrl': signedAvatar});
+      UpdatePetRequest? captured;
+      pets.updatePetHandler = (petId, request) async {
+        captured = request;
+        return buildPet('p-1', version: 6);
+      };
+      await pumpDetail(tester);
+      await tester.pumpAndSettle();
+
+      await tester.tap(find.byType(PetAvatar));
+      await tester.pumpAndSettle();
+      expect(find.text('更换头像'), findsOneWidget);
+      expect(find.text('移除头像'), findsOneWidget);
+
+      await tester.tap(find.text('移除头像'));
+      await tester.pumpAndSettle();
+
+      final payload = captured!.toJson();
+      expect(payload.containsKey('avatarAssetId'), isTrue);
+      expect(payload['avatarAssetId'], isNull);
+      expect(payload['version'], 5);
+      expect(payload.keys.length, 2, reason: '不得夹带任何资料字段（否则抬到 MANAGE 档）');
+      expect(find.text('已移除头像'), findsOneWidget);
+      expect(tester.widget<PetAvatar>(find.byType(PetAvatar)).url, isNull);
+    });
+
+    testWidgets('40902 版本冲突：提示 + 自动重取档案（不静默重放）', (tester) async {
+      var getCalls = 0;
+      pets.getPetHandler = (_) async {
+        getCalls += 1;
+        return buildPet('p-1', version: getCalls == 1 ? 3 : 9);
+      };
+      pets.updatePetHandler = (petId, request) async =>
+          throw const PetVersionConflictException(message: 'stale');
+      await pumpDetail(tester);
+      await tester.pumpAndSettle();
+
+      await tester.tap(find.byType(PetAvatar));
+      await tester.pumpAndSettle();
+      await tester.tap(find.text('使用这张'));
+      await tester.pumpAndSettle();
+
+      expect(find.text('档案已被更新，请重新操作'), findsOneWidget);
+      expect(getCalls, 2, reason: '冲突后重取档案拿新 version');
+    });
+
+    testWidgets('42203 头像未就绪：SnackBar 提示，不改动头像', (tester) async {
+      pets.getPetHandler = (_) async => buildPet('p-1', version: 3);
+      pets.updatePetHandler = (petId, request) async =>
+          throw const ApiBusinessException(
+            code: ApiCodes.mediaNotReady,
+            message: 'uploading',
+          );
+      await pumpDetail(tester);
+      await tester.pumpAndSettle();
+
+      await tester.tap(find.byType(PetAvatar));
+      await tester.pumpAndSettle();
+      await tester.tap(find.text('使用这张'));
+      await tester.pumpAndSettle();
+
+      expect(find.text('头像还没上传完，请稍后重试'), findsOneWidget);
+      expect(tester.widget<PetAvatar>(find.byType(PetAvatar)).url, isNull);
+    });
+  });
+
+  group('列表展示', () {
+    testWidgets('列表卡展示真实头像；无头像回退占位', (tester) async {
+      pets.listPetsHandler = () async => [
+        buildPet('p-1', name: '豆豆', overrides: {'avatarUrl': signedAvatar}),
+        buildPet('p-2', name: '花花'),
+      ];
+      await tester.pumpWidget(
+        MaterialApp(
+          theme: buildAppTheme(),
+          home: Scaffold(body: PetsPage(controller: controller)),
+        ),
+      );
+      await tester.pumpAndSettle();
+
+      final avatars = tester
+          .widgetList<PetAvatar>(find.byType(PetAvatar))
+          .toList();
+      expect(avatars.length, 2);
+      expect(avatars[0].url, signedAvatar);
+      expect(avatars[1].url, isNull, reason: '无头像回退爪印占位（不显示破图）');
+    });
+  });
+}

test/helpers/pet_test_helpers.dart

@@ -1,4 +1,4 @@
-/// pets 域测试样本（契约 openapi.yaml v1.2.0 各 schema 全字段 JSON）
+/// pets 域测试样本（契约 openapi.yaml v1.4.0 各 schema 全字段 JSON）
 /// 与共享假仓库。
 library;
 
@@ -27,6 +27,7 @@ Map<String, dynamic> samplePetJson({
   'microchipNo': null,
   'sterilizedOn': null,
   'status': 'active',
+  'avatarUrl': null,
   'myRole': 'owner',
   'createdAt': '2026-09-01T10:00:00+08:00',
   'updatedAt': '2026-09-02T10:00:00+08:00',