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/lib/state/quota_provider.dart

@@ -1,30 +1,32 @@
 // quota_provider.dart — 免费版每日额度状态(Riverpod)
 //
-// 设计约定(design/CLAUDE.md §7 / §2):免费额度权威在服务端。
-// 总额度取自 plans 的 free.daily_minutes,今日剩余取自 me.quota_today_min
-// (后端已算好 = 上限 − 今日已用)。adUnlocked 为本地会话态(看广告需 ad SDK,
-// 尚未接入,保留本地乐观置位)。
+// 设计约定(design/CLAUDE.md §7 / §2):免费额度权威在服务端,且**全账户共享**
+// (非每设备)。总额度取自 me.quota_cap_min(= 套餐每日上限 + 看广告累加分钟),
+// 今日剩余取自 me.quota_today_min(后端已算好 = 额度 − 今日已用)。
+//
+// 看广告加时(累加式):watchAd() 调 /v1/ads/unlock,服务端校验后 +N 分钟并回传最新
+// 剩余,客户端随即刷新 me 让额度权威同步。占位广告 SDK 阶段用客户端生成的 ad_token,
+// 服务端 DevVerifier 放行(nonce 仍防重放)。
 import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:uuid/uuid.dart';
 
+import '../services/device_identity.dart';
 import 'account_providers.dart';
+import 'auth_provider.dart';
 
 /// 免费额度快照。
 class FreeQuotaState {
   const FreeQuotaState({
     this.totalMinutes = 10,
     this.remainingMinutes = 10,
-    this.adUnlocked = false,
   });
 
-  /// 每日总额度(分钟)。§7:免费版每日 10 分钟。
+  /// 今日总额度(分钟)= 套餐每日上限 + 看广告累加。§7:免费版基础每日 10 分钟。
   final int totalMinutes;
 
-  /// 今日剩余分钟(展示值,权威以服务端为准)。
+  /// 今日剩余分钟(权威以服务端为准;连接期倒计时由连接状态机本地推算)。
   final int remainingMinutes;
 
-  /// 今日是否已观看激励视频解锁。
-  final bool adUnlocked;
-
   /// 进度(0–1),用于进度条宽度。
   double get progress =>
       totalMinutes == 0 ? 0 : (remainingMinutes / totalMinutes).clamp(0.0, 1.0);
@@ -32,11 +34,12 @@ class FreeQuotaState {
   /// 是否进入低额度警示(≤3 分钟切 warning 色)。
   bool get isLow => remainingMinutes <= 3;
 
-  FreeQuotaState copyWith({int? totalMinutes, int? remainingMinutes, bool? adUnlocked}) =>
-      FreeQuotaState(
+  /// 今日额度是否已耗尽(剩余 0):连接按钮据此灰化,点击弹广告/升级。
+  bool get isExhausted => remainingMinutes <= 0;
+
+  FreeQuotaState copyWith({int? totalMinutes, int? remainingMinutes}) => FreeQuotaState(
         totalMinutes: totalMinutes ?? this.totalMinutes,
         remainingMinutes: remainingMinutes ?? this.remainingMinutes,
-        adUnlocked: adUnlocked ?? this.adUnlocked,
       );
 }
 
@@ -53,18 +56,43 @@ class QuotaController extends StateNotifier<FreeQuotaState> {
   void _sync() {
     final me = _ref.read(meProvider).valueOrNull;
     final plans = _ref.read(plansProvider).valueOrNull;
-    var total = 10; // §7 默认免费 10 分钟,plans 就绪后以其为准
+    var base = 10; // §7 默认免费基础 10 分钟,plans 就绪后以其为准
     if (plans != null) {
       for (final p in plans) {
-        if (p.code == 'free' && p.dailyMinutes != null) total = p.dailyMinutes!;
+        if (p.code == 'free' && p.dailyMinutes != null) base = p.dailyMinutes!;
       }
     }
+    // 总额度优先取服务端 quota_cap_min(含看广告加时);缺省回退基础额度。
+    final total = me?.quotaCapMin ?? base;
     final remaining = (me?.quotaTodayMin ?? total).clamp(0, total);
-    state = state.copyWith(totalMinutes: total, remainingMinutes: remaining);
+    state = FreeQuotaState(totalMinutes: total, remainingMinutes: remaining);
   }
 
-  /// 观看激励视频后解锁今日使用(本地乐观;真实 ad 校验待 ad SDK 接入)。
-  void watchAd() => state = state.copyWith(adUnlocked: true);
+  /// 连接期倒计时归零 → 本地立即置耗尽(按钮随即灰化);登录态下再拉 me 让服务端权威同步。
+  void markExhausted() {
+    state = state.copyWith(remainingMinutes: 0);
+    if (_ref.read(authProvider).isLoggedIn) {
+      _ref.read(meProvider.notifier).refresh();
+    }
+  }
+
+  /// 看广告加时:调 /v1/ads/unlock 累加分钟,成功后刷新 me 拿最新额度。
+  /// 返回本次加时分钟(null = 失败)。占位阶段用客户端生成的 ad_token。
+  Future<int?> watchAd() async {
+    try {
+      final deviceId = await _ref.read(deviceIdentityProvider).deviceId();
+      final res = await _ref.read(accountApiProvider).adUnlock(
+            deviceId: deviceId,
+            adToken: const Uuid().v4(), // 占位 ad_token(DevVerifier 放行)
+          );
+      // 乐观置位剩余,再拉 me 校准(账户共享,以服务端为准)。
+      state = state.copyWith(remainingMinutes: res.minutesRemaining);
+      await _ref.read(meProvider.notifier).refresh();
+      return res.grantedMinutes;
+    } catch (_) {
+      return null;
+    }
+  }
 }
 
 final quotaProvider = StateNotifierProvider<QuotaController, FreeQuotaState>(