feat(client): Flutter 逐屏还原 + iPad ≥900 断点 (tsk_gpPXi-icyeOE)

对照 design/ui_kits mobile+tablet 原型逐屏补齐 Flutter 客户端:

- l10n 资源层(strings_zh/en,单显)+ Riverpod 状态层(连接状态机/免费额度/
  节点选择/语言/主题),UI 与数据解耦,mock 数据接 API 不动 UI。
- 连接键严格三态(off 虚线轨道环 / connecting 旋转弧 / on 满环+计时+光晕),
  状态来自 connectionProvider,点击只派发事件——禁止乐观显示。
- 节点页置顶「智能选择」推荐卡(clay 渐变 zap + 推荐胶囊,默认选中);
  免费额度卡(剩余分钟+进度条 ≤3 分钟切 warning + 看广告解锁变绿)。
- Tab 左右滑动切换(手势竞技场仲裁,子页滚动不误触发,200ms 方向感知滑入)。
- iPad/宽屏 ≥900 LayoutBuilder 切侧栏分栏(导航行高 ≥48,连接页双栏/节点双列网格),
  复用同一批原子组件,不 fork 页面。
- 语义 token 零硬编码;文案全部走 l10n;套餐数字对齐 §7;无支付表单/emoji 国旗。
- CI 红线词扫描扩展到 client/lib;新增 Flutter analyze+test CI 任务。
- 测试:连接状态机/额度/节点单测、连接键三态与卡片组件测试、
  golden(连接键三态/推荐卡/额度卡 × 明暗)。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

client/test/golden/components_golden_test.dart

@@ -0,0 +1,87 @@
+// components_golden_test.dart — 关键组件 golden(明/暗两主题)
+//
+// 覆盖:连接键三态、智能选择推荐卡、免费额度卡。
+// 首次生成基准图:`flutter test --update-goldens test/golden`。
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:pangolin_vpn/l10n/strings_zh.dart';
+import 'package:pangolin_vpn/state/connection_provider.dart';
+import 'package:pangolin_vpn/state/quota_provider.dart';
+import 'package:pangolin_vpn/widgets/connect_button.dart';
+import 'package:pangolin_vpn/widgets/quota_card.dart';
+import 'package:pangolin_vpn/widgets/smart_select_card.dart';
+
+import '../helpers/harness.dart';
+
+void main() {
+  setUpAll(disableGoogleFontsFetching);
+  const t = StringsZh();
+
+  Future<void> goldenOf(
+    WidgetTester tester,
+    Widget child,
+    Finder finder,
+    String name, {
+    bool dark = false,
+    Duration settle = Duration.zero,
+  }) async {
+    await tester.pumpWidget(wrapThemed(child, dark: dark));
+    if (settle == Duration.zero) {
+      await tester.pump();
+    } else {
+      await tester.pump(settle); // 固定帧,确保连接中旋转角确定
+    }
+    await expectLater(finder, matchesGoldenFile('goldens/$name.png'));
+  }
+
+  ConnectButton btn(VpnPhase phase, {Duration elapsed = Duration.zero}) => ConnectButton(
+        phase: phase,
+        elapsed: elapsed,
+        offLabel: t.connectNow,
+        secureLabel: t.secure,
+        onTap: () {},
+      );
+
+  for (final dark in [false, true]) {
+    final suffix = dark ? 'dark' : 'light';
+
+    testWidgets('连接键 off · $suffix', (tester) async {
+      await goldenOf(tester, btn(VpnPhase.off), find.byType(ConnectButton), 'connect_off_$suffix', dark: dark);
+    });
+
+    testWidgets('连接键 connecting · $suffix', (tester) async {
+      await goldenOf(tester, btn(VpnPhase.connecting), find.byType(ConnectButton), 'connect_connecting_$suffix',
+          dark: dark, settle: const Duration(milliseconds: 700));
+    });
+
+    testWidgets('连接键 on · $suffix', (tester) async {
+      await goldenOf(tester, btn(VpnPhase.on, elapsed: const Duration(seconds: 5)), find.byType(ConnectButton),
+          'connect_on_$suffix', dark: dark);
+    });
+
+    testWidgets('推荐卡 · $suffix', (tester) async {
+      await goldenOf(tester, SmartSelectCard(t: t, selected: true, onTap: () {}), find.byType(SmartSelectCard),
+          'smart_card_$suffix', dark: dark);
+    });
+
+    testWidgets('额度卡(低额度警示)· $suffix', (tester) async {
+      await goldenOf(
+        tester,
+        QuotaCard(quota: const FreeQuotaState(remainingMinutes: 2), t: t, onWatchAd: () {}),
+        find.byType(QuotaCard),
+        'quota_low_$suffix',
+        dark: dark,
+      );
+    });
+
+    testWidgets('额度卡(已解锁)· $suffix', (tester) async {
+      await goldenOf(
+        tester,
+        QuotaCard(quota: const FreeQuotaState(adUnlocked: true), t: t, onWatchAd: () {}),
+        find.byType(QuotaCard),
+        'quota_unlocked_$suffix',
+        dark: dark,
+      );
+    });
+  }
+}

client/test/helpers/harness.dart

@@ -0,0 +1,33 @@
+// harness.dart — 测试公共脚手架
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:google_fonts/google_fonts.dart';
+import 'package:pangolin_vpn/pangolin_theme.dart';
+
+/// 测试环境禁用 google_fonts 运行时网络拉取(离线确定化)。
+void disableGoogleFontsFetching() {
+  GoogleFonts.config.allowRuntimeFetching = false;
+}
+
+/// 用穿山甲明/暗主题包裹被测组件,并固定宽度便于 golden 对照。
+Widget wrapThemed(
+  Widget child, {
+  bool dark = false,
+  double width = 360,
+  List<Override> overrides = const [],
+}) {
+  return ProviderScope(
+    overrides: overrides,
+    child: MaterialApp(
+      debugShowCheckedModeBanner: false,
+      theme: PangolinTheme.light,
+      darkTheme: PangolinTheme.dark,
+      themeMode: dark ? ThemeMode.dark : ThemeMode.light,
+      home: Scaffold(
+        body: Center(
+          child: SizedBox(width: width, child: child),
+        ),
+      ),
+    ),
+  );
+}

client/test/unit/connection_controller_test.dart

@@ -0,0 +1,71 @@
+// connection_controller_test.dart — 连接状态机:严格三态、禁乐观显示
+import 'package:flutter_test/flutter_test.dart';
+import 'package:pangolin_vpn/state/connection_provider.dart';
+
+void main() {
+  // 注入极短握手时长,用真实计时器走完状态流转。
+  ConnectionController make() => ConnectionController(handshake: const Duration(milliseconds: 20));
+
+  test('初始为 off', () {
+    final ctl = make();
+    expect(ctl.state.phase, VpnPhase.off);
+    ctl.dispose();
+  });
+
+  test('connect: off → connecting → on', () async {
+    final ctl = make();
+    ctl.connect();
+    expect(ctl.state.phase, VpnPhase.connecting);
+    await Future<void>.delayed(const Duration(milliseconds: 60));
+    expect(ctl.state.phase, VpnPhase.on);
+    ctl.dispose();
+  });
+
+  test('握手中再次 toggle 被忽略(禁止乐观回退)', () async {
+    final ctl = make();
+    ctl.toggle(); // off → connecting
+    expect(ctl.state.phase, VpnPhase.connecting);
+    ctl.toggle(); // connecting 中点击 → 仍 connecting
+    expect(ctl.state.phase, VpnPhase.connecting);
+    await Future<void>.delayed(const Duration(milliseconds: 60));
+    expect(ctl.state.phase, VpnPhase.on);
+    ctl.dispose();
+  });
+
+  test('on 态 toggle → off', () async {
+    final ctl = make();
+    ctl.connect();
+    await Future<void>.delayed(const Duration(milliseconds: 60));
+    expect(ctl.state.phase, VpnPhase.on);
+    ctl.toggle();
+    expect(ctl.state.phase, VpnPhase.off);
+    ctl.dispose();
+  });
+
+  test('已连接时切换节点 → 重连(回到 connecting)', () async {
+    final ctl = make();
+    ctl.connect();
+    await Future<void>.delayed(const Duration(milliseconds: 60));
+    expect(ctl.state.phase, VpnPhase.on);
+    ctl.onNodeChanged();
+    expect(ctl.state.phase, VpnPhase.connecting);
+    ctl.dispose();
+  });
+
+  test('on 态计时累加', () async {
+    final ctl = make();
+    ctl.connect();
+    await Future<void>.delayed(const Duration(milliseconds: 60));
+    expect(ctl.state.elapsed, Duration.zero);
+    await Future<void>.delayed(const Duration(milliseconds: 1100));
+    expect(ctl.state.elapsed.inSeconds, greaterThanOrEqualTo(1));
+    ctl.dispose();
+  });
+
+  test('off 态切换节点不会自动连接', () {
+    final ctl = make();
+    ctl.onNodeChanged();
+    expect(ctl.state.phase, VpnPhase.off);
+    ctl.dispose();
+  });
+}

client/test/unit/nodes_provider_test.dart

@@ -0,0 +1,40 @@
+// nodes_provider_test.dart — 节点选择 / 智能选择派生
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:pangolin_vpn/l10n/app_text.dart';
+import 'package:pangolin_vpn/models/node.dart';
+import 'package:pangolin_vpn/state/nodes_provider.dart';
+
+void main() {
+  test('默认智能选择(AUTO)', () {
+    final c = ProviderContainer();
+    addTearDown(c.dispose);
+    expect(c.read(selectedNodeCodeProvider), kSmartNodeCode);
+    expect(c.read(isSmartSelectProvider), true);
+  });
+
+  test('智能选择取延迟最小节点', () {
+    final c = ProviderContainer();
+    addTearDown(c.dispose);
+    final node = c.read(effectiveNodeProvider);
+    final minPing = kDemoNodes.map((n) => n.ping).reduce((a, b) => a < b ? a : b);
+    expect(node.ping, minPing);
+  });
+
+  test('选中具体节点后生效节点随之改变', () {
+    final c = ProviderContainer();
+    addTearDown(c.dispose);
+    c.read(selectedNodeCodeProvider.notifier).state = 'JP';
+    expect(c.read(isSmartSelectProvider), false);
+    expect(c.read(effectiveNodeProvider).code, 'JP');
+  });
+
+  test('localizedSub 不串语言:无标签用拉丁地名', () {
+    const tw = Node(code: 'TW', nameZh: '台湾 台北', nameEn: 'Taipei', ping: 28);
+    expect(tw.localizedSub(AppLang.zh), 'Taipei');
+    expect(tw.localizedSub(AppLang.en), 'Taipei');
+    const hk = Node(code: 'HK', nameZh: '香港 · 流媒体', nameEn: 'Hong Kong', ping: 18, tag: NodeTag.streaming);
+    expect(hk.localizedSub(AppLang.zh), '流媒体优化');
+    expect(hk.localizedSub(AppLang.en), 'Streaming');
+  });
+}

client/test/unit/quota_controller_test.dart

@@ -0,0 +1,36 @@
+// quota_controller_test.dart — 免费额度状态机
+import 'package:flutter_test/flutter_test.dart';
+import 'package:pangolin_vpn/state/quota_provider.dart';
+
+void main() {
+  test('默认值:10 分钟总额 / 6 分钟剩余 / 未解锁', () {
+    final ctl = QuotaController();
+    expect(ctl.state.totalMinutes, 10);
+    expect(ctl.state.remainingMinutes, 6);
+    expect(ctl.state.adUnlocked, false);
+  });
+
+  test('progress = 剩余/总额', () {
+    final ctl = QuotaController(const FreeQuotaState(totalMinutes: 10, remainingMinutes: 5));
+    expect(ctl.state.progress, closeTo(0.5, 1e-9));
+  });
+
+  test('isLow:剩余 ≤3 分钟为真', () {
+    expect(const FreeQuotaState(remainingMinutes: 3).isLow, true);
+    expect(const FreeQuotaState(remainingMinutes: 4).isLow, false);
+  });
+
+  test('watchAd 解锁今日使用', () {
+    final ctl = QuotaController();
+    expect(ctl.state.adUnlocked, false);
+    ctl.watchAd();
+    expect(ctl.state.adUnlocked, true);
+  });
+
+  test('reset 回到未解锁初始态', () {
+    final ctl = QuotaController()..watchAd();
+    ctl.reset();
+    expect(ctl.state.adUnlocked, false);
+    expect(ctl.state.remainingMinutes, 6);
+  });
+}

client/test/widget/cards_test.dart

@@ -0,0 +1,55 @@
+// cards_test.dart — 额度卡 / 智能选择推荐卡 行为
+import 'package:flutter_test/flutter_test.dart';
+import 'package:pangolin_vpn/l10n/strings_zh.dart';
+import 'package:pangolin_vpn/state/quota_provider.dart';
+import 'package:pangolin_vpn/widgets/pangolin_icons.dart';
+import 'package:pangolin_vpn/widgets/quota_card.dart';
+import 'package:pangolin_vpn/widgets/smart_select_card.dart';
+
+import '../helpers/harness.dart';
+
+void main() {
+  setUpAll(disableGoogleFontsFetching);
+  const t = StringsZh();
+
+  testWidgets('额度卡:未解锁显示看广告按钮,点击回调', (tester) async {
+    var watched = 0;
+    await tester.pumpWidget(wrapThemed(
+      QuotaCard(quota: const FreeQuotaState(), t: t, onWatchAd: () => watched++),
+    ));
+    await tester.pump();
+    expect(find.text(t.watchAd), findsOneWidget);
+    await tester.tap(find.text(t.watchAd));
+    expect(watched, 1);
+  });
+
+  testWidgets('额度卡:已解锁显示已解锁文案', (tester) async {
+    await tester.pumpWidget(wrapThemed(
+      QuotaCard(quota: const FreeQuotaState(adUnlocked: true), t: t, onWatchAd: () {}),
+    ));
+    await tester.pump();
+    expect(find.text(t.adUnlocked), findsOneWidget);
+    expect(find.byIcon(PangolinIcons.checkCircle), findsOneWidget);
+  });
+
+  testWidgets('推荐卡:展示推荐胶囊与文案,选中显示对勾', (tester) async {
+    await tester.pumpWidget(wrapThemed(
+      SmartSelectCard(t: t, selected: true, onTap: () {}),
+    ));
+    await tester.pump();
+    expect(find.text(t.smartSelect), findsOneWidget);
+    expect(find.text(t.recommended), findsOneWidget);
+    expect(find.text(t.smartSub), findsOneWidget);
+    expect(find.byIcon(PangolinIcons.check), findsOneWidget);
+  });
+
+  testWidgets('推荐卡:点击回调', (tester) async {
+    var picked = 0;
+    await tester.pumpWidget(wrapThemed(
+      SmartSelectCard(t: t, selected: false, onTap: () => picked++),
+    ));
+    await tester.pump();
+    await tester.tap(find.text(t.smartSelect));
+    expect(picked, 1);
+  });
+}

client/test/widget/connect_button_test.dart

@@ -0,0 +1,51 @@
+// connect_button_test.dart — 连接键三态展示与回调
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:pangolin_vpn/state/connection_provider.dart';
+import 'package:pangolin_vpn/widgets/connect_button.dart';
+import 'package:pangolin_vpn/widgets/pangolin_icons.dart';
+
+import '../helpers/harness.dart';
+
+void main() {
+  setUpAll(disableGoogleFontsFetching);
+
+  Widget button(VpnPhase phase, {Duration elapsed = Duration.zero, VoidCallback? onTap}) => wrapThemed(
+        ConnectButton(
+          phase: phase,
+          elapsed: elapsed,
+          offLabel: '点击连接',
+          secureLabel: '已加密',
+          onTap: onTap ?? () {},
+        ),
+      );
+
+  testWidgets('off 态:power 图标 + 点击连接', (tester) async {
+    await tester.pumpWidget(button(VpnPhase.off));
+    await tester.pump();
+    expect(find.byIcon(PangolinIcons.power), findsOneWidget);
+    expect(find.text('点击连接'), findsOneWidget);
+  });
+
+  testWidgets('connecting 态:loader 图标', (tester) async {
+    await tester.pumpWidget(button(VpnPhase.connecting));
+    await tester.pump(const Duration(milliseconds: 100));
+    expect(find.byIcon(PangolinIcons.loader), findsOneWidget);
+  });
+
+  testWidgets('on 态:盾勾 + 计时 + 已加密', (tester) async {
+    await tester.pumpWidget(button(VpnPhase.on, elapsed: const Duration(seconds: 5)));
+    await tester.pump();
+    expect(find.byIcon(PangolinIcons.shieldCheck), findsOneWidget);
+    expect(find.text('00:00:05'), findsOneWidget);
+    expect(find.text('已加密'), findsOneWidget);
+  });
+
+  testWidgets('点击触发回调', (tester) async {
+    var tapped = 0;
+    await tester.pumpWidget(button(VpnPhase.off, onTap: () => tapped++));
+    await tester.pump();
+    await tester.tap(find.byType(ConnectButton));
+    expect(tapped, 1);
+  });
+}