新增：宠物头像接线——铅笔角标接上传、列表与详情展示真实头像（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(