新增：埋点分段持久化队列（13 号规范 §3.3，M2 第二波）

- AnalyticsEventStore：shared_preferences 分段存储（每段 ≤20 条、总上限 500 超限丢最旧整段）、冷启动恢复、损坏段/损坏索引容错、 droppedCount 丢弃诊断计数 - AnalyticsService 接入持久化队列：上传拿到终态（202/4xx）才删段实现 at-least-once；冲刷按段拼批 ≤50 条循环上传（契约单批上限）；取批即封段，冲刷在途新事件写入新开放段不丢 - app.dart 冷启动 restore() 恢复离线积压并冲刷（13 号 §3.4 触发点） - 保留第一波语义：flushNow()、4xx 毒丸丢弃、满 20 条冲刷触发 - 新增 13 个单测（恢复/上限淘汰/损坏容错/202 清段/flushNow 协同/ 分批上传），全套 64 测试全绿 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-09-07 17:04:16 +08:00
parent 1afec6aad1
commit 33b993ca0c
5 changed files with 577 additions and 28 deletions
@@ -0,0 +1,159 @@
+import 'dart:convert';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:patbond_flutter/analytics/analytics_event_store.dart';
+import 'package:shared_preferences/shared_preferences.dart';
+
+Map<String, dynamic> event(int seq) => {
+  'eventId': 'id-$seq',
+  'eventName': 'auth_login_succeeded',
+  'seq': seq,
+};
+
+void main() {
+  group('AnalyticsEventStore', () {
+    test('事件持久化后新实例冷启动可恢复（顺序保持旧 → 新）', () async {
+      SharedPreferences.setMockInitialValues({});
+      final store = AnalyticsEventStore();
+      await store.restore();
+      for (var i = 0; i < 45; i++) {
+        await store.add(event(i));
+      }
+
+      final reborn = AnalyticsEventStore();
+      await reborn.restore();
+
+      expect(reborn.length, 45);
+      expect(reborn.events.first['seq'], 0);
+      expect(reborn.events.last['seq'], 44);
+      // 45 条按容量 20 分段应为 3 段
+      final prefs = await SharedPreferences.getInstance();
+      final index =
+          jsonDecode(prefs.getString(AnalyticsEventStore.segIndexKey)!) as List;
+      expect(index.length, 3);
+    });
+
+    test('超过 500 条总上限时丢最旧整段', () async {
+      SharedPreferences.setMockInitialValues({});
+      final store = AnalyticsEventStore();
+      await store.restore();
+      for (var i = 0; i < 520; i++) {
+        await store.add(event(i));
+      }
+
+      // 第 501 条触发淘汰最旧一段（20 条），此后回落到上限内
+      expect(store.length, 500);
+      expect(store.events.first['seq'], 20);
+      expect(store.events.last['seq'], 519);
+      expect(store.droppedCount, 20);
+    });
+
+    test('损坏段丢弃不崩溃，其余段正常恢复且索引被清理', () async {
+      SharedPreferences.setMockInitialValues({
+        AnalyticsEventStore.segIndexKey: jsonEncode(['bad', 'good']),
+        '${AnalyticsEventStore.segKeyPrefix}bad': '{not-valid-json[[',
+        '${AnalyticsEventStore.segKeyPrefix}good': jsonEncode([event(7)]),
+      });
+
+      final store = AnalyticsEventStore();
+      await store.restore();
+
+      expect(store.length, 1);
+      expect(store.events.single['seq'], 7);
+      expect(store.droppedCount, 1);
+      final prefs = await SharedPreferences.getInstance();
+      expect(prefs.getString('${AnalyticsEventStore.segKeyPrefix}bad'), isNull);
+      expect(jsonDecode(prefs.getString(AnalyticsEventStore.segIndexKey)!), [
+        'good',
+      ]);
+    });
+
+    test('段索引本身损坏时清扫孤儿段、从空队列重建', () async {
+      SharedPreferences.setMockInitialValues({
+        AnalyticsEventStore.segIndexKey: 'garbage-not-json',
+        '${AnalyticsEventStore.segKeyPrefix}orphan': jsonEncode([event(1)]),
+      });
+
+      final store = AnalyticsEventStore();
+      await store.restore();
+
+      expect(store.length, 0);
+      final prefs = await SharedPreferences.getInstance();
+      expect(
+        prefs.getString('${AnalyticsEventStore.segKeyPrefix}orphan'),
+        isNull,
+      );
+      // 可继续正常写入
+      await store.add(event(2));
+      expect(store.length, 1);
+    });
+
+    test('takeBatch 封段：在途批次不受新事件影响，删段后新事件保留', () async {
+      SharedPreferences.setMockInitialValues({});
+      final store = AnalyticsEventStore();
+      await store.restore();
+      for (var i = 0; i < 5; i++) {
+        await store.add(event(i));
+      }
+
+      final batch = store.takeBatch(50);
+      // 模拟上传在途期间进入的新事件
+      await store.add(event(99));
+
+      expect(batch.events.length, 5);
+      await store.removeSegments(batch.segmentIds);
+      expect(store.length, 1);
+      expect(store.events.single['seq'], 99);
+    });
+
+    test('takeBatch 按段拼批不超过单批上限', () async {
+      SharedPreferences.setMockInitialValues({});
+      final store = AnalyticsEventStore();
+      await store.restore();
+      for (var i = 0; i < 60; i++) {
+        await store.add(event(i));
+      }
+
+      // 段容量 20、单批上限 50 → 每批最多 2 整段（40 条）
+      final first = store.takeBatch(50);
+      expect(first.events.length, 40);
+      await store.removeSegments(first.segmentIds);
+      final second = store.takeBatch(50);
+      expect(second.events.length, 20);
+    });
+
+    test('上传成功删段后 shared_preferences 无残留', () async {
+      SharedPreferences.setMockInitialValues({});
+      final store = AnalyticsEventStore();
+      await store.restore();
+      for (var i = 0; i < 20; i++) {
+        await store.add(event(i));
+      }
+
+      final batch = store.takeBatch(50);
+      await store.removeSegments(batch.segmentIds);
+
+      expect(store.length, 0);
+      final prefs = await SharedPreferences.getInstance();
+      expect(
+        prefs.getKeys().where(
+          (key) => key.startsWith(AnalyticsEventStore.segKeyPrefix),
+        ),
+        isEmpty,
+      );
+      expect(
+        jsonDecode(prefs.getString(AnalyticsEventStore.segIndexKey)!),
+        isEmpty,
+      );
+    });
+
+    test('未调用 restore（持久化不可用）时降级为纯内存队列', () async {
+      final store = AnalyticsEventStore();
+      await store.add(event(1));
+      expect(store.length, 1);
+      final batch = store.takeBatch(50);
+      await store.removeSegments(batch.segmentIds);
+      expect(store.length, 0);
+    });
+  });
+}
@@ -0,0 +1,141 @@
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:patbond_flutter/analytics/analytics_event_store.dart';
+import 'package:patbond_flutter/analytics/analytics_service.dart';
+import 'package:shared_preferences/shared_preferences.dart';
+
+/// 服务级持久化队列联动测试（13 号规范 §3.3/§3.4）：
+/// 本地 HttpServer 模拟 /api/v1/events 的 202 / 400 响应。
+void main() {
+  Future<(HttpServer, List<int>)> startServer(int statusCode) async {
+    final server = await HttpServer.bind(InternetAddress.loopbackIPv4, 0);
+    final batchSizes = <int>[];
+    server.listen((request) async {
+      final body =
+          jsonDecode(await utf8.decoder.bind(request).join())
+              as Map<String, dynamic>;
+      batchSizes.add((body['events'] as List).length);
+      request.response.statusCode = statusCode;
+      await request.response.close();
+    });
+    return (server, batchSizes);
+  }
+
+  AnalyticsService buildService(String apiBaseUrl, AnalyticsEventStore store) {
+    return AnalyticsService(
+      apiBaseUrl: apiBaseUrl,
+      getAccessToken: null,
+      getSessionId: () => 'session-x',
+      store: store,
+    );
+  }
+
+  group('AnalyticsService 持久化队列', () {
+    test('满 20 条冲刷、202 受理后清空持久化段', () async {
+      SharedPreferences.setMockInitialValues({});
+      final (server, batchSizes) = await startServer(202);
+      addTearDown(() => server.close(force: true));
+      final store = AnalyticsEventStore();
+      await store.restore();
+      final service = buildService('http://127.0.0.1:${server.port}', store);
+
+      for (var i = 0; i < 20; i++) {
+        await service.trackEvent('auth_login_succeeded', {'attemptSeq': i});
+      }
+
+      expect(batchSizes, [20]);
+      expect(service.pendingEvents, isEmpty);
+      final prefs = await SharedPreferences.getInstance();
+      expect(
+        prefs.getKeys().where(
+          (key) => key.startsWith(AnalyticsEventStore.segKeyPrefix),
+        ),
+        isEmpty,
+      );
+    });
+
+    test('flushNow 冲刷不满 20 条的持久化队列', () async {
+      SharedPreferences.setMockInitialValues({});
+      final (server, batchSizes) = await startServer(202);
+      addTearDown(() => server.close(force: true));
+      final store = AnalyticsEventStore();
+      await store.restore();
+      final service = buildService('http://127.0.0.1:${server.port}', store);
+
+      await service.trackEvent('auth_login_succeeded');
+      await service.trackEvent('auth_logout');
+      await service.flushNow();
+
+      expect(batchSizes, [2]);
+      expect(service.pendingEvents, isEmpty);
+      expect(store.length, 0);
+    });
+
+    test('上传失败事件持久化，冷启动恢复后自动重传', () async {
+      SharedPreferences.setMockInitialValues({});
+      // 第一个进程：端口不可达，20 条触发冲刷失败，事件留在持久化队列
+      final storeA = AnalyticsEventStore();
+      await storeA.restore();
+      final serviceA = buildService('http://127.0.0.1:1', storeA);
+      for (var i = 0; i < 20; i++) {
+        await serviceA.trackEvent('auth_login_succeeded', {'attemptSeq': i});
+      }
+      expect(serviceA.pendingEvents.length, 20);
+
+      // 模拟冷启动：新实例 restore 恢复并冲刷到可用服务端
+      final (server, batchSizes) = await startServer(202);
+      addTearDown(() => server.close(force: true));
+      final storeB = AnalyticsEventStore();
+      final serviceB = buildService('http://127.0.0.1:${server.port}', storeB);
+      await serviceB.restore();
+
+      expect(batchSizes, [20]);
+      expect(serviceB.pendingEvents, isEmpty);
+    });
+
+    test('4xx 永久拒绝直接删段丢弃（毒丸防护），计入丢弃诊断数', () async {
+      SharedPreferences.setMockInitialValues({});
+      final (server, batchSizes) = await startServer(400);
+      addTearDown(() => server.close(force: true));
+      final store = AnalyticsEventStore();
+      await store.restore();
+      final service = buildService('http://127.0.0.1:${server.port}', store);
+
+      for (var i = 0; i < 20; i++) {
+        await service.trackEvent('auth_login_succeeded', {'attemptSeq': i});
+      }
+
+      expect(batchSizes, [20]);
+      expect(service.pendingEvents, isEmpty);
+      expect(store.droppedCount, 20);
+      final prefs = await SharedPreferences.getInstance();
+      expect(
+        prefs.getKeys().where(
+          (key) => key.startsWith(AnalyticsEventStore.segKeyPrefix),
+        ),
+        isEmpty,
+      );
+    });
+
+    test('积压超过单批上限时按 50 条分批循环上传', () async {
+      SharedPreferences.setMockInitialValues({});
+      final (server, batchSizes) = await startServer(202);
+      addTearDown(() => server.close(force: true));
+      final store = AnalyticsEventStore();
+      await store.restore();
+      // 直接预置 60 条积压（绕过 trackEvent 的满 20 冲刷触发）
+      for (var i = 0; i < 60; i++) {
+        await store.add({'eventId': 'id-$i', 'eventName': 'page_viewed'});
+      }
+      final service = buildService('http://127.0.0.1:${server.port}', store);
+
+      await service.flushNow();
+
+      // 段容量 20、单批上限 50 → 40 + 20 两批
+      expect(batchSizes, [40, 20]);
+      expect(service.pendingEvents, isEmpty);
+    });
+  });
+}