feat(client): 免费版连接倒计时 + 到点切断 + 灰按钮 + 看广告加时(#21 前端)

四端共享 Dart 实现,配合 #21 后端账户级卡控:

- me.dart: 加 quota_cap_min(当日总额度 = daily + 看广告 bonus,进度条分母)。
- quota_provider: total 取 quotaCapMin;isExhausted;markExhausted(倒计时归零本地置耗尽
  + 登录态拉 me 校准);watchAd() async 调 /ads/unlock(占位 ad_token=uuid)→ 刷新 me,返回 granted。
- connection_provider: 连接时锁定 _freeRemainingSec(会员 null 不倒计时);复用 elapsed 计时器
  每 tick 算 freeCountdown,归零 → _onFreeQuotaExhausted(主动切断不报节点异常 + markExhausted);
  倒计时用墙上时钟(后台漏跳回前台补上、准时切);连接遇后端 QUOTA_EXHAUSTED 兜底置耗尽。
- connect_button: enabled/onDisabledTap —— 额度耗尽 off 态灰化(锁图标),点击弹加时。
- quota_card: 三态(连接倒计时 mm:ss / 未连接剩余分钟 / 耗尽今日已用完);移动「看广告加时」、桌面「升级会员」。
- ad_reward_dialog(新): 移动端占位广告(播放中→3s→加时→奖励);桌面版硬 10 分钟提示去移动端/升级。
- l10n(zh/en): 倒计时/已用完/看广告加时/占位广告/桌面升级 双语。
- 测试: quota isExhausted/markExhausted;连接倒计时归零自动切断+置耗尽(注入时钟);
  额度卡三态 widget;/me 契约含 quota_cap_min;golden 更新(Linux 权威基线 quota_low/exhausted)。
- 文档: docs/free-quota-ad.html + 登记 docs/index.html。

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

client/test/contract/api_contract_test.dart

@@ -20,6 +20,7 @@ const _frozenMeKeys = <String>{
   'devices_used',
   'devices_max',
   'quota_today_min',
+  'quota_cap_min',
   'data_today_gb',
   'weekly_gb',
   'totp_enabled',
@@ -37,6 +38,7 @@ Map<String, dynamic> _meSample() => {
       'devices_used': 2,
       'devices_max': 5,
       'quota_today_min': null, // pro/team 不限 → null
+      'quota_cap_min': null, // pro/team 不限 → null
       'data_today_gb': 1.5,
       'weekly_gb': [0.1, 0.2, 0.0, 1.0, 2.0, 0.5, 1.5],
       'totp_enabled': true,

client/test/golden/components_golden_test.dart

@@ -76,12 +76,12 @@ void main() {
       );
     });
 
-    testWidgets('额度卡(已解锁)· $suffix', (tester) async {
+    testWidgets('额度卡(已耗尽)· $suffix', (tester) async {
       await goldenOf(
         tester,
-        QuotaCard(quota: const FreeQuotaState(adUnlocked: true), t: t, onWatchAd: () {}),
+        QuotaCard(quota: const FreeQuotaState(remainingMinutes: 0), t: t, onWatchAd: () {}),
         find.byType(QuotaCard),
-        'quota_unlocked_$suffix',
+        'quota_exhausted_$suffix',
         dark: dark,
       );
     });

client/test/unit/connection_watchdog_test.dart

@@ -13,6 +13,7 @@ import 'package:pangolin_vpn/models/node.dart';
 import 'package:pangolin_vpn/services/connect_api.dart';
 import 'package:pangolin_vpn/state/connection_provider.dart';
 import 'package:pangolin_vpn/state/nodes_provider.dart';
+import 'package:pangolin_vpn/state/quota_provider.dart';
 
 // 可控假桥:能手动推 VpnStatus,无内部计时器(避免 pending timer)。
 class _FakeBridge implements VpnBridge {
@@ -279,4 +280,36 @@ void main() {
     bridge.emit(VpnStatus.off); // 收尾:停看门狗/计时器
     await tester.pump();
   });
+
+  // 免费版 10 分钟卡控:连接期倒计时,墙上时钟越过额度即自动切断 + 本地置耗尽(#21)。
+  testWidgets('免费额度倒计时归零 → 自动切断 + 置耗尽', (tester) async {
+    final bridge = _FakeBridge();
+    var fake = DateTime(2026, 7, 1, 12);
+    final c = makeContainer(bridge, now: () => fake); // 未登录默认免费,剩余 10 分钟
+    addTearDown(bridge.dispose);
+    addTearDown(c.dispose);
+    await tester.pumpWidget(UncontrolledProviderScope(container: c, child: const SizedBox()));
+    c.read(nodesProvider);
+    await tester.pump();
+
+    // 免费默认剩余 10 分钟 → toggle 触发 _connect 锁定 600s 倒计时(fake api 抛错不影响锁定)。
+    expect(c.read(quotaProvider).remainingMinutes, 10);
+    c.read(connectionProvider.notifier).toggle();
+    await tester.pump();
+    bridge.emit(VpnStatus.on); // _startElapsed:_connectedAt = fake(T0)
+    await tester.pump();
+    await tester.pump();
+    expect(c.read(connectionProvider).phase, VpnPhase.on);
+    expect(c.read(connectionProvider).freeCountdown, isNotNull, reason: '连接期应有倒计时');
+
+    // 快进墙上时钟越过 10 分钟 → 下一个 1s tick 触发 _refreshElapsed → 切断。
+    fake = fake.add(const Duration(seconds: 601));
+    await tester.pump(const Duration(seconds: 1));
+    await tester.pump();
+    await tester.pump();
+
+    expect(c.read(connectionProvider).phase, VpnPhase.off, reason: '额度用完应自动切断');
+    expect(c.read(connectionProvider).error, t.quotaExhaustedNotice, reason: '应给「已用完」提示');
+    expect(c.read(quotaProvider).isExhausted, true, reason: '切断后本地置耗尽 → 按钮灰化');
+  });
 }

client/test/unit/quota_controller_test.dart

@@ -41,24 +41,29 @@ void main() {
       expect(const FreeQuotaState(remainingMinutes: 3).isLow, true);
       expect(const FreeQuotaState(remainingMinutes: 4).isLow, false);
     });
+    test('isExhausted:剩余 ≤0 为真', () {
+      expect(const FreeQuotaState(remainingMinutes: 0).isExhausted, true);
+      expect(const FreeQuotaState(remainingMinutes: 1).isExhausted, false);
+    });
   });
 
-  // 未登录默认态:总额 10 / 剩余 10 / 未解锁;watchAd 本地置位。
+  // 未登录默认态:总额 10 / 剩余 10 / 未耗尽。
   group('quotaProvider', () {
-    test('默认 10/10 未解锁', () {
+    test('默认 10/10 未耗尽', () {
       final c = _container();
       addTearDown(c.dispose);
       final q = c.read(quotaProvider);
       expect(q.totalMinutes, 10);
       expect(q.remainingMinutes, 10);
-      expect(q.adUnlocked, false);
+      expect(q.isExhausted, false);
     });
 
-    test('watchAd 解锁今日使用', () {
+    test('markExhausted 本地立即置剩余 0', () {
       final c = _container();
       addTearDown(c.dispose);
-      c.read(quotaProvider.notifier).watchAd();
-      expect(c.read(quotaProvider).adUnlocked, true);
+      c.read(quotaProvider.notifier).markExhausted();
+      expect(c.read(quotaProvider).remainingMinutes, 0);
+      expect(c.read(quotaProvider).isExhausted, true);
     });
   });
 }

client/test/widget/cards_test.dart

@@ -12,24 +12,32 @@ void main() {
   setUpAll(disableGoogleFontsFetching);
   const t = StringsZh();
 
-  testWidgets('额度卡:未解锁显示看广告按钮,点击回调', (tester) async {
+  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(find.text(t.watchAdMore), findsOneWidget);
+    await tester.tap(find.text(t.watchAdMore));
     expect(watched, 1);
   });
 
-  testWidgets('额度卡:已解锁显示已解锁文案', (tester) async {
+  testWidgets('额度卡(耗尽):显示今日已用完 + 看广告加时', (tester) async {
     await tester.pumpWidget(wrapThemed(
-      QuotaCard(quota: const FreeQuotaState(adUnlocked: true), t: t, onWatchAd: () {}),
+      QuotaCard(quota: const FreeQuotaState(remainingMinutes: 0), t: t, onWatchAd: () {}),
     ));
     await tester.pump();
-    expect(find.text(t.adUnlocked), findsOneWidget);
-    expect(find.byIcon(PangolinIcons.checkCircle), findsOneWidget);
+    expect(find.text(t.quotaUsedUp), findsOneWidget);
+    expect(find.text(t.watchAdMore), findsOneWidget);
+  });
+
+  testWidgets('额度卡(桌面·有余额):不显示加时按钮', (tester) async {
+    await tester.pumpWidget(wrapThemed(
+      QuotaCard(quota: const FreeQuotaState(), t: t, isDesktop: true, onWatchAd: () {}),
+    ));
+    await tester.pump();
+    expect(find.text(t.watchAdMore), findsNothing);
   });
 
   testWidgets('推荐卡:展示推荐胶囊与文案,选中显示对勾', (tester) async {