重构：宠物列表/详情/编辑页接入真实数据（T2-12，四态齐备）

- 档案 Tab 替换为真实宠物列表（05 号规范 P1）：PetsController 四态
  驱动（loading/empty/error+重试/ready），空态插画 + 建档 CTA，
  下拉刷新，虚线添加卡；页面一律走 T2-11 数据层、不直连 ApiClient
- 新增 PetDetailPage（P2 档案信息部分）：内存副本首屏 + getPet 刷新，
  40401 防枚举 → 不存在态返回列表并刷新；仅 owner 显示编辑入口
  （40300 语义）；体重/疫苗/时间线区块留待 T2-13/14 接摘要与记录接口
- 新增 PetFormPage（建档/编辑）：品种目录接口 + 自定义品种互斥
  （目录失败回落自定义 + 重试）、性别契约必填、生日+估算、芯片号；
  失焦+提交双校验、错误三层模型沿用登录纵切
- 40902 版本冲突：明确提示 + 自动拉取最新 version 重提路径（有测试）；
  40903 芯片号冲突字段级报错（有测试）
- 埋点挂接：pet_create_started（表单首次输入、每次进入一次）/
  succeeded / failed 三事件接线；建宠表单路由名 pet_form、详情页
  pet_detail 进入既有 RouteObserver 采集；档案 Tab 页名 pet_archive
  改报 pet_list（字典 v2）；编辑表单不带路由名（漏斗到达段不掺编辑）
- app.dart 装配：pet 服务 ApiClient（:8083）共享 TokenRefresher；
  登出 reset 控制器防跨账号泄漏；PetsController.loadBreeds 按物种缓存
- AppState 清理：pets 页原 demo 消费方移除，vaccines 及其模型/持久化
  删除；pet demo 仅存首页问候/创作页/主壳头像（后续工单收敛）
- 头像按 ADR-010 本地占位，不做上传
- 测试 145 → 177 全绿（列表/详情/表单四态与冲突路径 widget 测试、
  控制器 loadBreeds/reset、展示纯函数）；analyze 0；format 无 diff

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

test/features/pets/pet_detail_page_test.dart

@@ -0,0 +1,179 @@
+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/features/pets/pet_detail_page.dart';
+import 'package:patbond_flutter/features/pets/pet_exceptions.dart';
+import 'package:patbond_flutter/features/pets/pet_form_page.dart';
+import 'package:patbond_flutter/features/pets/pet_models.dart';
+import 'package:patbond_flutter/features/pets/pets_controller.dart';
+
+import '../../helpers/pet_test_helpers.dart';
+
+void main() {
+  late FakePetsRepository repository;
+  late PetsController controller;
+
+  setUp(() {
+    repository = FakePetsRepository();
+    controller = PetsController(repository: repository);
+  });
+
+  Future<void> pumpDetail(WidgetTester tester, {String petId = 'p-1'}) async {
+    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: petId),
+        ),
+      ),
+    );
+    await tester.pump();
+  }
+
+  testWidgets('ready：档案字段齐备，owner 可见编辑入口', (tester) async {
+    repository.getPetHandler = (petId) async => buildPet(
+      'p-1',
+      overrides: {
+        'microchipNo': '985112000000001',
+        'personality': '活泼',
+        'sterilizedOn': '2025-06-01',
+      },
+    );
+
+    await pumpDetail(tester);
+    await tester.pumpAndSettle();
+
+    expect(find.text('豆豆'), findsOneWidget);
+    expect(find.text('基本资料'), findsOneWidget);
+    expect(find.text('柴犬'), findsOneWidget);
+    expect(find.text('男孩'), findsOneWidget);
+    expect(find.text('2024-03-15'), findsOneWidget);
+    expect(find.text('985112000000001'), findsOneWidget);
+    expect(find.text('活泼'), findsOneWidget);
+    expect(find.text('2025-06-01'), findsOneWidget);
+    expect(find.byIcon(Icons.edit_outlined), findsWidgets);
+    expect(find.text('编辑资料'), findsOneWidget);
+  });
+
+  testWidgets('生日估算标记与未填写字段兜底', (tester) async {
+    repository.getPetHandler = (petId) async =>
+        buildPet('p-1', overrides: {'birthDateEstimated': true});
+
+    await pumpDetail(tester);
+    await tester.pumpAndSettle();
+
+    expect(find.text('2024-03-15（估算）'), findsOneWidget);
+    // 芯片号 / 性格 / 绝育日期未填。
+    expect(find.text('未填写'), findsNWidgets(3));
+  });
+
+  testWidgets('四态 · loading：无内存副本时居中转圈', (tester) async {
+    final completer = Completer<Pet>();
+    repository.getPetHandler = (petId) => completer.future;
+
+    await pumpDetail(tester);
+    await tester.pump();
+
+    expect(find.byType(CircularProgressIndicator), findsOneWidget);
+
+    completer.complete(buildPet('p-1'));
+    await tester.pumpAndSettle();
+    expect(find.text('豆豆'), findsOneWidget);
+  });
+
+  testWidgets('四态 · error/retry：无副本加载失败给横幅与重试', (tester) async {
+    var calls = 0;
+    repository.getPetHandler = (petId) async {
+      calls++;
+      if (calls == 1) throw const ApiNetworkException('断网');
+      return buildPet('p-1');
+    };
+
+    await pumpDetail(tester);
+    await tester.pumpAndSettle();
+
+    expect(find.text('网络异常，请检查网络后重试'), findsOneWidget);
+
+    await tester.tap(find.text('重试'));
+    await tester.pumpAndSettle();
+
+    expect(find.text('豆豆'), findsOneWidget);
+  });
+
+  testWidgets('四态 · notFound（40401）：提示不存在，返回列表并触发刷新', (tester) async {
+    repository.getPetHandler = (petId) async =>
+        throw const PetNotFoundException(message: '不存在');
+    var listCalls = 0;
+    repository.listPetsHandler = () async {
+      listCalls++;
+      return const [];
+    };
+
+    await pumpDetail(tester);
+    await tester.pumpAndSettle();
+
+    expect(find.text('宠物不存在或已被删除'), findsOneWidget);
+
+    await tester.tap(find.text('返回列表'));
+    await tester.pumpAndSettle();
+
+    expect(find.byType(PetDetailPage), findsNothing);
+    expect(find.text('列表基底'), findsOneWidget);
+    expect(listCalls, 1);
+  });
+
+  testWidgets('有内存副本时先渲染副本；后台刷新失败降级 SnackBar', (tester) async {
+    repository.listPetsHandler = () async => [buildPet('p-1')];
+    await controller.refresh();
+    final completer = Completer<Pet>();
+    repository.getPetHandler = (petId) => completer.future;
+
+    await pumpDetail(tester);
+    await tester.pump();
+
+    // 副本即时渲染，无整页 loading。
+    expect(find.text('豆豆'), findsOneWidget);
+    expect(find.byType(CircularProgressIndicator), findsNothing);
+
+    completer.completeError(const ApiNetworkException('断网'));
+    await tester.pumpAndSettle();
+
+    expect(find.text('豆豆'), findsOneWidget);
+    expect(find.text('网络异常，请检查网络后重试'), findsOneWidget);
+  });
+
+  testWidgets('viewer 角色隐藏全部编辑入口（40300 语义）', (tester) async {
+    repository.getPetHandler = (petId) async =>
+        buildPet('p-1', overrides: {'myRole': 'viewer'});
+
+    await pumpDetail(tester);
+    await tester.pumpAndSettle();
+
+    expect(find.byIcon(Icons.edit_outlined), findsNothing);
+    expect(find.text('编辑资料'), findsNothing);
+    expect(find.byIcon(Icons.edit), findsNothing);
+  });
+
+  testWidgets('owner 点编辑 → 进入编辑表单并预填', (tester) async {
+    repository.getPetHandler = (petId) async => buildPet('p-1');
+
+    await pumpDetail(tester);
+    await tester.pumpAndSettle();
+
+    await tester.tap(find.text('编辑资料'));
+    await tester.pumpAndSettle();
+
+    expect(find.byType(PetFormPage), findsOneWidget);
+    expect(find.text('编辑宠物资料'), findsOneWidget);
+    expect(find.text('豆豆'), findsOneWidget);
+  });
+}

test/features/pets/pet_display_test.dart

@@ -0,0 +1,58 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:patbond_flutter/core/network/api_exception.dart';
+import 'package:patbond_flutter/features/pets/pet_display.dart';
+import 'package:patbond_flutter/features/pets/pet_models.dart';
+
+import '../../helpers/pet_test_helpers.dart';
+
+void main() {
+  test('petAgeLabel：岁 / 月 / 未满月 / 未知边界', () {
+    final now = DateTime(2026, 9, 8);
+    expect(petAgeLabel(DateTime(2024, 3, 15), now: now), '2 岁');
+    expect(petAgeLabel(DateTime(2025, 9, 9), now: now), '11 个月');
+    expect(petAgeLabel(DateTime(2026, 3, 1), now: now), '6 个月');
+    expect(petAgeLabel(DateTime(2026, 9, 1), now: now), '未满月');
+    expect(petAgeLabel(null, now: now), '年龄未知');
+    expect(petAgeLabel(DateTime(2027), now: now), '年龄未知');
+  });
+
+  test('petMetaLine：品种 · 性别 · 年龄；自定义品种回退', () {
+    final now = DateTime(2026, 9, 8);
+    expect(petMetaLine(buildPet('p-1'), now: now), '柴犬 · 男孩 · 2 岁');
+
+    final custom = buildPet(
+      'p-2',
+      overrides: {
+        'breedId': null,
+        'breedDisplayName': null,
+        'customBreedName': '狸花',
+        'sex': 'unknown',
+        'birthDate': null,
+      },
+    );
+    expect(petMetaLine(custom, now: now), '狸花 · 性别未知 · 年龄未知');
+  });
+
+  test('petLoadErrorMessage：网络 / 限流 / 其他三档文案', () {
+    expect(
+      petLoadErrorMessage(const ApiNetworkException('x')),
+      '网络异常，请检查网络后重试',
+    );
+    expect(petLoadErrorMessage(const ApiRateLimitException()), '请求过于频繁，请稍后再试');
+    expect(
+      petLoadErrorMessage(
+        const ApiBusinessException(code: 40000, message: 'x'),
+      ),
+      '加载失败，请稍后重试',
+    );
+    expect(petLoadErrorMessage(null), '加载失败，请稍后重试');
+  });
+
+  test('物种 / 性别 / 状态标签', () {
+    expect(petSpeciesLabel(PetSpecies.dog), '狗狗');
+    expect(petSpeciesLabel(PetSpecies.cat), '猫咪');
+    expect(petSexLabel(PetSex.female), '女孩');
+    expect(petStatusLabel(PetStatus.archived), '已归档');
+    expect(petStatusLabel(PetStatus.lost), '走失中');
+  });
+}

test/features/pets/pet_form_page_test.dart

@@ -0,0 +1,345 @@
+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/features/pets/pet_analytics.dart';
+import 'package:patbond_flutter/features/pets/pet_exceptions.dart';
+import 'package:patbond_flutter/features/pets/pet_form_page.dart';
+import 'package:patbond_flutter/features/pets/pet_models.dart';
+import 'package:patbond_flutter/features/pets/pets_controller.dart';
+
+import '../../helpers/pet_test_helpers.dart';
+
+void main() {
+  late FakePetsRepository repository;
+  late PetsController controller;
+  late List<(String, Map<String, dynamic>?)> events;
+  late PetAnalytics analytics;
+
+  setUp(() {
+    repository = FakePetsRepository();
+    controller = PetsController(repository: repository);
+    events = [];
+    analytics = PetAnalytics(
+      (name, [props]) async => events.add((name, props)),
+    );
+  });
+
+  List<Map<String, dynamic>?> eventsOf(String name) => [
+    for (final e in events)
+      if (e.$1 == name) e.$2,
+  ];
+
+  Future<void> pumpForm(WidgetTester tester, Widget form) async {
+    tester.view.physicalSize = const Size(700, 2000);
+    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: (_) => form)));
+    await tester.pumpAndSettle();
+  }
+
+  Future<void> pumpCreate(
+    WidgetTester tester, {
+    PetCreateEntryPoint entryPoint = PetCreateEntryPoint.profileEmptyState,
+  }) {
+    return pumpForm(
+      tester,
+      PetFormPage.create(
+        controller: controller,
+        analytics: analytics,
+        entryPoint: entryPoint,
+      ),
+    );
+  }
+
+  Future<void> selectBreed(WidgetTester tester, String label) async {
+    await tester.tap(find.byType(DropdownButtonFormField<String>));
+    await tester.pumpAndSettle();
+    await tester.tap(find.text(label).last);
+    await tester.pumpAndSettle();
+  }
+
+  group('创建模式', () {
+    testWidgets('提交空表单：昵称/性别/品种三处校验拦截 + failed(validation_error)', (
+      tester,
+    ) async {
+      await pumpCreate(tester);
+
+      await tester.tap(find.text('保存档案'));
+      await tester.pumpAndSettle();
+
+      expect(find.text('请输入宠物昵称'), findsOneWidget);
+      expect(find.text('请选择性别'), findsOneWidget);
+      expect(find.text('请选择品种'), findsOneWidget);
+
+      final failed = eventsOf('pet_create_failed');
+      expect(failed, hasLength(1));
+      expect(failed.single!['failureReason'], 'validation_error');
+      expect(failed.single!['attemptSeq'], 1);
+    });
+
+    testWidgets('首次输入触发 pet_create_started（每次进入仅一次）', (tester) async {
+      await pumpCreate(tester);
+
+      expect(eventsOf('pet_create_started'), isEmpty);
+
+      await tester.enterText(find.widgetWithText(TextFormField, '宠物昵称'), '咪');
+      await tester.tap(find.text('女孩'));
+      await tester.pumpAndSettle();
+
+      final started = eventsOf('pet_create_started');
+      expect(started, hasLength(1));
+      expect(started.single!['entryPoint'], 'profile_empty_state');
+    });
+
+    testWidgets('目录品种建档成功：请求对齐契约、页面回列表、succeeded 三属性', (tester) async {
+      CreatePetRequest? captured;
+      repository.createPetHandler = (request) async {
+        captured = request;
+        return buildPet('p-new', name: '咪咪');
+      };
+
+      await pumpCreate(tester);
+      await tester.enterText(find.widgetWithText(TextFormField, '宠物昵称'), '咪咪');
+      await tester.tap(find.text('女孩'));
+      await tester.pumpAndSettle();
+      await selectBreed(tester, '柴犬');
+      await tester.enterText(
+        find.widgetWithText(TextFormField, '芯片号（可选）'),
+        '985112000000001',
+      );
+
+      await tester.tap(find.text('保存档案'));
+      await tester.pumpAndSettle();
+
+      expect(captured!.toJson(), {
+        'name': '咪咪',
+        'species': 'dog',
+        'sex': 'female',
+        'breedId': 'b-1',
+        'microchipNo': '985112000000001',
+      });
+      expect(find.text('列表基底'), findsOneWidget);
+      expect(controller.pets.single.id, 'p-new');
+
+      final succeeded = eventsOf('pet_create_succeeded');
+      expect(succeeded, hasLength(1));
+      expect(succeeded.single!['species'], 'dog');
+      expect(succeeded.single!['petIndex'], 1);
+      expect(succeeded.single!['durationMs'], isA<int>());
+    });
+
+    testWidgets('自定义品种与目录互斥：只发送 customBreedName', (tester) async {
+      CreatePetRequest? captured;
+      repository.createPetHandler = (request) async {
+        captured = request;
+        return buildPet('p-new');
+      };
+
+      await pumpCreate(tester);
+      await tester.enterText(find.widgetWithText(TextFormField, '宠物昵称'), '大黄');
+      await tester.tap(find.text('男孩'));
+      await tester.pumpAndSettle();
+      await selectBreed(tester, '自定义品种…');
+
+      expect(find.text('品种名称'), findsOneWidget);
+      await tester.enterText(
+        find.widgetWithText(TextFormField, '品种名称'),
+        '中华田园犬',
+      );
+
+      await tester.tap(find.text('保存档案'));
+      await tester.pumpAndSettle();
+
+      expect(captured!.toJson()['customBreedName'], '中华田园犬');
+      expect(captured!.toJson().containsKey('breedId'), isFalse);
+    });
+
+    testWidgets('40903 芯片号冲突：字段级报错 + failed 带 errorCode/httpStatus', (
+      tester,
+    ) async {
+      repository.createPetHandler = (request) async =>
+          throw const MicrochipTakenException(message: '已登记');
+
+      await pumpCreate(tester);
+      await tester.enterText(find.widgetWithText(TextFormField, '宠物昵称'), '咪咪');
+      await tester.tap(find.text('女孩'));
+      await tester.pumpAndSettle();
+      await selectBreed(tester, '柴犬');
+
+      await tester.tap(find.text('保存档案'));
+      await tester.pumpAndSettle();
+
+      expect(find.text('该芯片号已被登记，请核对后重试'), findsOneWidget);
+      expect(find.byType(PetFormPage), findsOneWidget);
+
+      final failed = eventsOf('pet_create_failed');
+      expect(failed.single!['errorCode'], 40903);
+      expect(failed.single!['httpStatus'], 409);
+      expect(failed.single!['failureReason'], 'validation_error');
+    });
+
+    testWidgets('网络异常：SnackBar + 重试动作 + failed(network_error)', (tester) async {
+      repository.createPetHandler = (request) async =>
+          throw const ApiNetworkException('断网');
+
+      await pumpCreate(tester);
+      await tester.enterText(find.widgetWithText(TextFormField, '宠物昵称'), '咪咪');
+      await tester.tap(find.text('未知'));
+      await tester.pumpAndSettle();
+      await selectBreed(tester, '柴犬');
+
+      await tester.tap(find.text('保存档案'));
+      await tester.pumpAndSettle();
+
+      expect(find.text('网络异常，请检查网络后重试'), findsOneWidget);
+      expect(find.text('重试'), findsOneWidget);
+      expect(
+        eventsOf('pet_create_failed').single!['failureReason'],
+        'network_error',
+      );
+    });
+
+    testWidgets('品种目录加载失败：回落自定义输入，重试后目录恢复', (tester) async {
+      var calls = 0;
+      repository.listBreedsHandler = (species) async {
+        calls++;
+        if (calls == 1) throw const ApiNetworkException('断网');
+        return [Breed.fromJson(sampleBreedJson())];
+      };
+
+      await pumpCreate(tester);
+
+      expect(find.text('品种目录加载失败，可先填写自定义品种'), findsOneWidget);
+      expect(find.text('品种名称'), findsOneWidget);
+
+      await tester.tap(find.text('重试'));
+      await tester.pumpAndSettle();
+
+      expect(find.byType(DropdownButtonFormField<String>), findsOneWidget);
+      expect(find.text('品种目录加载失败，可先填写自定义品种'), findsNothing);
+    });
+
+    testWidgets('昵称失焦校验：空值即时 errorText，输入即清除', (tester) async {
+      await pumpCreate(tester);
+
+      await tester.tap(find.widgetWithText(TextFormField, '宠物昵称'));
+      await tester.pump();
+      // 焦点移到芯片号 → 昵称失焦触发校验。
+      await tester.tap(find.widgetWithText(TextFormField, '芯片号（可选）'));
+      await tester.pumpAndSettle();
+
+      expect(find.text('请输入宠物昵称'), findsOneWidget);
+
+      await tester.enterText(find.widgetWithText(TextFormField, '宠物昵称'), '豆');
+      await tester.pumpAndSettle();
+      expect(find.text('请输入宠物昵称'), findsNothing);
+    });
+  });
+
+  group('编辑模式', () {
+    testWidgets('预填 + 物种锁定 + 差量提交（只发送改动字段与 version）', (tester) async {
+      UpdatePetRequest? captured;
+      repository.updatePetHandler = (petId, request) async {
+        captured = request;
+        return buildPet('p-1', name: '豆豆二世', version: 4);
+      };
+
+      await pumpForm(
+        tester,
+        PetFormPage.edit(
+          controller: controller,
+          pet: buildPet('p-1', version: 3),
+          analytics: analytics,
+        ),
+      );
+
+      // 物种锁定为静态文案，无可选分段控件。
+      expect(find.text('物种（创建后不可修改）'), findsOneWidget);
+      expect(find.byType(SegmentedButton<PetSpecies>), findsNothing);
+      expect(find.text('编辑宠物资料'), findsOneWidget);
+
+      await tester.enterText(
+        find.widgetWithText(TextFormField, '宠物昵称'),
+        '豆豆二世',
+      );
+      await tester.tap(find.text('保存修改'));
+      await tester.pumpAndSettle();
+
+      expect(captured!.toJson(), {'version': 3, 'name': '豆豆二世'});
+      expect(find.text('列表基底'), findsOneWidget);
+      // 编辑不产生 pet_create_* 事件（06 §1.4）。
+      expect(events, isEmpty);
+    });
+
+    testWidgets('40902 版本冲突：明确提示 + 自动取新 version，重提成功', (tester) async {
+      var updateCalls = 0;
+      final versions = <int>[];
+      repository.updatePetHandler = (petId, request) async {
+        updateCalls++;
+        versions.add(request.version);
+        if (updateCalls == 1) {
+          throw const PetVersionConflictException(message: '版本过期');
+        }
+        return buildPet('p-1', name: '豆豆二世', version: 5);
+      };
+      repository.getPetHandler = (petId) async => buildPet('p-1', version: 4);
+
+      await pumpForm(
+        tester,
+        PetFormPage.edit(
+          controller: controller,
+          pet: buildPet('p-1', version: 3),
+        ),
+      );
+      await tester.enterText(
+        find.widgetWithText(TextFormField, '宠物昵称'),
+        '豆豆二世',
+      );
+
+      await tester.tap(find.text('保存修改'));
+      await tester.pumpAndSettle();
+
+      // 明确的用户提示 + 刷新路径（已拉取最新版本）。
+      expect(find.text('资料已在其他设备被修改，已获取最新版本，请核对后重新保存'), findsOneWidget);
+      expect(find.byType(PetFormPage), findsOneWidget);
+
+      await tester.tap(find.text('保存修改'));
+      await tester.pumpAndSettle();
+
+      expect(versions, [3, 4]);
+      expect(find.text('列表基底'), findsOneWidget);
+    });
+
+    testWidgets('无任何变更：不发 PATCH 直接返回', (tester) async {
+      var updateCalls = 0;
+      repository.updatePetHandler = (petId, request) async {
+        updateCalls++;
+        return buildPet('p-1');
+      };
+
+      await pumpForm(
+        tester,
+        PetFormPage.edit(
+          controller: controller,
+          pet: buildPet('p-1', version: 3),
+        ),
+      );
+
+      await tester.tap(find.text('保存修改'));
+      await tester.pumpAndSettle();
+
+      expect(updateCalls, 0);
+      expect(find.text('列表基底'), findsOneWidget);
+    });
+  });
+}

test/features/pets/pets_controller_test.dart

@@ -3,40 +3,9 @@ import 'package:patbond_flutter/core/network/api_exception.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_repository.dart';
 
 import '../../helpers/pet_test_helpers.dart';
 
-/// 假仓库：各方法可注入行为，未注入的方法抛 UnimplementedError。
-class FakePetsRepository implements PetsRepository {
-  Future<List<Pet>> Function()? listPetsHandler;
-  Future<Pet> Function(CreatePetRequest)? createPetHandler;
-  Future<Pet> Function(String)? getPetHandler;
-  Future<Pet> Function(String, UpdatePetRequest)? updatePetHandler;
-
-  @override
-  Future<List<Pet>> listPets() =>
-      listPetsHandler?.call() ?? Future.value(const []);
-
-  @override
-  Future<Pet> createPet(CreatePetRequest request) => createPetHandler!(request);
-
-  @override
-  Future<Pet> getPet(String petId) => getPetHandler!(petId);
-
-  @override
-  Future<Pet> updatePet(String petId, UpdatePetRequest request) =>
-      updatePetHandler!(petId, request);
-
-  @override
-  dynamic noSuchMethod(Invocation invocation) =>
-      throw UnimplementedError('${invocation.memberName}');
-}
-
-Pet pet(String id, {String name = '豆豆', int version = 1}) => Pet.fromJson(
-  samplePetJson(overrides: {'id': id, 'name': name, 'version': version}),
-);
-
 void main() {
   late FakePetsRepository repository;
   late PetsController controller;
@@ -53,7 +22,7 @@ void main() {
   });
 
   test('refresh 成功：loading → ready，列表就位', () async {
-    repository.listPetsHandler = () async => [pet('p-1'), pet('p-2')];
+    repository.listPetsHandler = () async => [buildPet('p-1'), buildPet('p-2')];
     final phases = <PetsLoadPhase>[];
     controller.addListener(() => phases.add(controller.phase));
 
@@ -83,7 +52,7 @@ void main() {
     expect(controller.phase, PetsLoadPhase.error);
     expect(controller.lastError, isA<ApiNetworkException>());
 
-    repository.listPetsHandler = () async => [pet('p-1')];
+    repository.listPetsHandler = () async => [buildPet('p-1')];
     await controller.refresh();
 
     expect(controller.phase, PetsLoadPhase.ready);
@@ -92,9 +61,10 @@ void main() {
   });
 
   test('createPet：成功后插入列表头', () async {
-    repository.listPetsHandler = () async => [pet('p-1')];
+    repository.listPetsHandler = () async => [buildPet('p-1')];
     await controller.refresh();
-    repository.createPetHandler = (request) async => pet('p-2', name: '咪咪');
+    repository.createPetHandler = (request) async =>
+        buildPet('p-2', name: '咪咪');
 
     final created = await controller.createPet(
       const CreatePetRequest(
@@ -110,7 +80,7 @@ void main() {
   });
 
   test('createPet 失败（40903）：类型化异常外抛，列表不变', () async {
-    repository.listPetsHandler = () async => [pet('p-1')];
+    repository.listPetsHandler = () async => [buildPet('p-1')];
     await controller.refresh();
     repository.createPetHandler = (request) async =>
         throw const MicrochipTakenException(message: '芯片号已被登记');
@@ -130,10 +100,10 @@ void main() {
   });
 
   test('updatePet：成功后同步列表内存副本', () async {
-    repository.listPetsHandler = () async => [pet('p-1', version: 1)];
+    repository.listPetsHandler = () async => [buildPet('p-1', version: 1)];
     await controller.refresh();
     repository.updatePetHandler = (petId, request) async =>
-        pet('p-1', name: '豆豆二世', version: 2);
+        buildPet('p-1', name: '豆豆二世', version: 2);
 
     await controller.updatePet(
       'p-1',
@@ -155,13 +125,66 @@ void main() {
   });
 
   test('getPet：详情结果回写列表副本', () async {
-    repository.listPetsHandler = () async => [pet('p-1', version: 1)];
+    repository.listPetsHandler = () async => [buildPet('p-1', version: 1)];
     await controller.refresh();
-    repository.getPetHandler = (petId) async => pet('p-1', version: 5);
+    repository.getPetHandler = (petId) async => buildPet('p-1', version: 5);
 
     final detail = await controller.getPet('p-1');
 
     expect(detail.version, 5);
     expect(controller.pets.single.version, 5);
   });
+
+  test('loadBreeds：按物种缓存，仓库只打一次', () async {
+    var calls = 0;
+    repository.listBreedsHandler = (species) async {
+      calls++;
+      return [Breed.fromJson(sampleBreedJson())];
+    };
+
+    final first = await controller.loadBreeds(PetSpecies.dog);
+    final second = await controller.loadBreeds(PetSpecies.dog);
+
+    expect(first.single.displayName, '柴犬');
+    expect(identical(first, second), isTrue);
+    expect(calls, 1);
+
+    await controller.loadBreeds(PetSpecies.cat);
+    expect(calls, 2);
+  });
+
+  test('loadBreeds 失败：异常外抛且不缓存，重试可恢复', () async {
+    var calls = 0;
+    repository.listBreedsHandler = (species) async {
+      calls++;
+      if (calls == 1) throw const ApiNetworkException('断网');
+      return [Breed.fromJson(sampleBreedJson())];
+    };
+
+    await expectLater(
+      controller.loadBreeds(PetSpecies.dog),
+      throwsA(isA<ApiNetworkException>()),
+    );
+    final breeds = await controller.loadBreeds(PetSpecies.dog);
+    expect(breeds, hasLength(1));
+  });
+
+  test('reset：登出清空回 initial（含品种缓存）', () async {
+    repository.listPetsHandler = () async => [buildPet('p-1')];
+    var breedCalls = 0;
+    repository.listBreedsHandler = (species) async {
+      breedCalls++;
+      return [Breed.fromJson(sampleBreedJson())];
+    };
+    await controller.refresh();
+    await controller.loadBreeds(PetSpecies.dog);
+
+    controller.reset();
+
+    expect(controller.phase, PetsLoadPhase.initial);
+    expect(controller.pets, isEmpty);
+    expect(controller.lastError, isNull);
+    await controller.loadBreeds(PetSpecies.dog);
+    expect(breedCalls, 2);
+  });
 }

test/features/pets/pets_page_test.dart

@@ -0,0 +1,147 @@
+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/empty_state_illustration.dart';
+import 'package:patbond_flutter/features/pets/pet_detail_page.dart';
+import 'package:patbond_flutter/features/pets/pet_form_page.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/pet_test_helpers.dart';
+
+class _RecordingNavObserver extends NavigatorObserver {
+  final pushedNames = <String?>[];
+
+  @override
+  void didPush(Route<dynamic> route, Route<dynamic>? previousRoute) {
+    pushedNames.add(route.settings.name);
+  }
+}
+
+void main() {
+  late FakePetsRepository repository;
+  late PetsController controller;
+  late _RecordingNavObserver observer;
+
+  setUp(() {
+    repository = FakePetsRepository();
+    controller = PetsController(repository: repository);
+    observer = _RecordingNavObserver();
+  });
+
+  Future<void> pumpPage(WidgetTester tester) {
+    return tester.pumpWidget(
+      MaterialApp(
+        theme: buildAppTheme(),
+        navigatorObservers: [observer],
+        home: Scaffold(body: PetsPage(controller: controller)),
+      ),
+    );
+  }
+
+  testWidgets('四态 · loading：拉取期间居中转圈', (tester) async {
+    final completer = Completer<List<Pet>>();
+    repository.listPetsHandler = () => completer.future;
+
+    await pumpPage(tester);
+    await tester.pump();
+
+    expect(find.byType(CircularProgressIndicator), findsOneWidget);
+
+    completer.complete(const []);
+    await tester.pumpAndSettle();
+    expect(find.byType(CircularProgressIndicator), findsNothing);
+  });
+
+  testWidgets('四态 · empty：空态插画 + 建档 CTA 打开 pet_form 表单页', (tester) async {
+    await pumpPage(tester);
+    await tester.pumpAndSettle();
+
+    expect(find.byType(EmptyStateIllustration), findsOneWidget);
+    expect(find.text('还没有宠物档案'), findsOneWidget);
+
+    await tester.tap(find.text('添加宠物'));
+    await tester.pumpAndSettle();
+
+    expect(find.byType(PetFormPage), findsOneWidget);
+    // page_viewed(pet_form) 接线依据：路由名进入既有 RouteObserver 采集。
+    expect(observer.pushedNames.last, 'pet_form');
+  });
+
+  testWidgets('四态 · error/retry：横幅 + 重试按钮，重试后恢复列表', (tester) async {
+    var calls = 0;
+    repository.listPetsHandler = () async {
+      calls++;
+      if (calls == 1) throw const ApiNetworkException('断网');
+      return [buildPet('p-1')];
+    };
+
+    await pumpPage(tester);
+    await tester.pumpAndSettle();
+
+    expect(find.text('网络异常，请检查网络后重试'), findsOneWidget);
+    expect(find.text('重试'), findsOneWidget);
+
+    await tester.tap(find.text('重试'));
+    await tester.pumpAndSettle();
+
+    expect(find.text('豆豆'), findsOneWidget);
+  });
+
+  testWidgets('四态 · ready：列表卡渲染名字与元信息，含添加入口', (tester) async {
+    repository.listPetsHandler = () async => [
+      buildPet('p-1'),
+      buildPet(
+        'p-2',
+        name: '咪咪',
+        overrides: {
+          'species': 'cat',
+          'sex': 'female',
+          'breedId': null,
+          'breedDisplayName': null,
+          'customBreedName': '狸花',
+        },
+      ),
+    ];
+
+    await pumpPage(tester);
+    await tester.pumpAndSettle();
+
+    expect(find.text('我的宠物'), findsOneWidget);
+    expect(find.text('豆豆'), findsOneWidget);
+    expect(find.text('咪咪'), findsOneWidget);
+    expect(find.textContaining('柴犬 · 男孩'), findsOneWidget);
+    expect(find.textContaining('狸花 · 女孩'), findsOneWidget);
+    expect(find.text('＋ 添加宠物'), findsOneWidget);
+    expect(find.text('添加'), findsOneWidget);
+  });
+
+  testWidgets('点宠物卡 → 以 pet_detail 路由名进入详情页', (tester) async {
+    repository.listPetsHandler = () async => [buildPet('p-1')];
+    repository.getPetHandler = (petId) async => buildPet('p-1');
+
+    await pumpPage(tester);
+    await tester.pumpAndSettle();
+
+    await tester.tap(find.text('豆豆'));
+    await tester.pumpAndSettle();
+
+    expect(find.byType(PetDetailPage), findsOneWidget);
+    expect(observer.pushedNames.last, 'pet_detail');
+  });
+
+  testWidgets('非 active 宠物显示状态标签（走失中）', (tester) async {
+    repository.listPetsHandler = () async => [
+      buildPet('p-1', overrides: {'status': 'lost'}),
+    ];
+
+    await pumpPage(tester);
+    await tester.pumpAndSettle();
+
+    expect(find.text('走失中'), findsOneWidget);
+  });
+}

test/helpers/pet_test_helpers.dart

@@ -1,6 +1,10 @@
-/// pets 域测试样本（契约 openapi.yaml v1.2.0 各 schema 全字段 JSON）。
+/// pets 域测试样本（契约 openapi.yaml v1.2.0 各 schema 全字段 JSON）
+/// 与共享假仓库。
 library;
 
+import 'package:patbond_flutter/features/pets/pet_models.dart';
+import 'package:patbond_flutter/features/pets/pets_repository.dart';
+
 Map<String, Object?> okListEnvelope(List<Object?> data) => {
   'code': 0,
   'message': 'ok',
@@ -105,3 +109,55 @@ Map<String, dynamic> samplePetSummaryJson() => {
     'amountCents': 12850,
   },
 };
+
+Map<String, dynamic> sampleBreedJson({
+  String id = 'b-1',
+  String species = 'dog',
+  String code = 'shiba',
+  String displayName = '柴犬',
+}) => {'id': id, 'species': species, 'code': code, 'displayName': displayName};
+
+/// 快速构造 Pet（widget/controller 测试共用）。
+Pet buildPet(
+  String id, {
+  String name = '豆豆',
+  int version = 1,
+  Map<String, Object?> overrides = const {},
+}) => Pet.fromJson(
+  samplePetJson(
+    overrides: {'id': id, 'name': name, 'version': version, ...overrides},
+  ),
+);
+
+/// 假仓库：各方法可注入行为；listPets 默认空列表，其余未注入的方法抛
+/// UnimplementedError（22 号报告 §7：widget 测试注入假仓库的共享实现）。
+class FakePetsRepository implements PetsRepository {
+  Future<List<Pet>> Function()? listPetsHandler;
+  Future<Pet> Function(CreatePetRequest)? createPetHandler;
+  Future<Pet> Function(String)? getPetHandler;
+  Future<Pet> Function(String, UpdatePetRequest)? updatePetHandler;
+  Future<List<Breed>> Function(PetSpecies?)? listBreedsHandler;
+
+  @override
+  Future<List<Pet>> listPets() =>
+      listPetsHandler?.call() ?? Future.value(const []);
+
+  @override
+  Future<Pet> createPet(CreatePetRequest request) => createPetHandler!(request);
+
+  @override
+  Future<Pet> getPet(String petId) => getPetHandler!(petId);
+
+  @override
+  Future<Pet> updatePet(String petId, UpdatePetRequest request) =>
+      updatePetHandler!(petId, request);
+
+  @override
+  Future<List<Breed>> listBreeds({PetSpecies? species}) =>
+      listBreedsHandler?.call(species) ??
+      Future.value([Breed.fromJson(sampleBreedJson())]);
+
+  @override
+  dynamic noSuchMethod(Invocation invocation) =>
+      throw UnimplementedError('${invocation.memberName}');
+}

test/widget_test.dart

@@ -4,6 +4,7 @@ import 'package:patbond_flutter/features/auth/session_manager.dart';
 import 'package:shared_preferences/shared_preferences.dart';
 
 import 'helpers/auth_test_helpers.dart';
+import 'helpers/pet_test_helpers.dart';
 
 void main() {
   testWidgets('Patbond renders the main navigation', (tester) async {
@@ -12,7 +13,11 @@ void main() {
       ..markAuthenticated();
 
     await tester.pumpWidget(
-      App(sessionManager: session, authRepository: FakeAuthRepository()),
+      App(
+        sessionManager: session,
+        authRepository: FakeAuthRepository(),
+        petsRepository: FakePetsRepository(),
+      ),
     );
     await tester.pumpAndSettle();