修复：埋点接线与三处偏差（sessionId/eventId/设备信息）

- 生产接线修复：app.dart 组装时传 analytics 实例给 ApiAuthRepository（_buildRepository），修复 M1 遗留的「生产环境 _analytics 恒为 null、挂接点空转」问题 - sessionId 生命周期：新建 SessionTracker (WidgetsBindingObserver)，冷启动生成 UUIDv7、后台超 30 分钟换新、未超阈值沿用原值，不再每事件随机生成 - eventId 改 UUIDv7：对齐 13 号规范（uuid 包已在依赖，直接用 v7()），保留插入时间局部性 - appVersion 动态注入：package_info_plus（新增依赖）异步读取后 setAppVersion，不再硬编码 '1.0.0+1' - osVersion 动态读取：Platform.operatingSystemVersion 正则提取主版本（如 android-14），不再硬编码 - 队列顺手加固：上传失败批次重回队首而非整批丢弃（一行级缓解，分段持久化属 M2 第二波）测试新增 9 例：session_tracker_test（5 例：冷启动/短后台/长后台/级联状态/连续幂等），analytics_service_test 补强 4 例（UUIDv7/sessionId 不再逐事件生成/appVersion 可注入/失败重回队列）。验收对照（06 号报告 §5.1 六条）：1✓ SessionTracker 新建、2✓ 三条语义、3✓ 同会话 sessionId 一致、4✓ sessionId 为 UUID 不持久化、5✓ 单测 3 例（实际 5 例）、6✓ 真机脚本（开发者手测）。 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-09-07 14:49:24 +08:00
parent 3f8388e5d4
commit 4c2f839a01
8 changed files with 367 additions and 47 deletions
@@ -2,59 +2,125 @@ import 'package:flutter_test/flutter_test.dart';
 import 'package:patbond_flutter/analytics/analytics_service.dart';

 void main() {
+  final uuidV7 = RegExp(
+    r'^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[0-9a-f]{4}-[0-9a-f]{12}$',
+  );
+
+  AnalyticsService buildService({
+    String Function()? getSessionId,
+    String? anonymousId,
+  }) {
+    var counter = 0;
+    return AnalyticsService(
+      apiBaseUrl: 'http://test',
+      getAccessToken: null,
+      getSessionId: getSessionId ?? () => 'session-${counter++}',
+      anonymousId: anonymousId,
+    );
+  }
+
  group('AnalyticsService', () {
    test('tracks event with required fields', () async {
-      final service = AnalyticsService(
-        apiBaseUrl: 'http://test',
-        getAccessToken: null,
-      );
+      final service = buildService(getSessionId: () => 'session-a');

-      // Never throws, never awaits network (fire-and-forget).
-      expect(
-        () => service.trackEvent('auth_login_succeeded', {
-          'identifierType': 'username',
-          'durationMs': 123,
-        }),
-        returnsNormally,
-      );
+      await service.trackEvent('auth_login_succeeded', {
+        'identifierType': 'username',
+        'durationMs': 123,
+      });
+
+      final event = service.pendingEvents.single;
+      expect(event['eventName'], 'auth_login_succeeded');
+      expect(event['eventVersion'], 1);
+      expect(event['sessionId'], 'session-a');
+      expect(event['anonymousId'], isNotEmpty);
+      expect(event['clientTs'], isNotEmpty);
+      expect(event['appVersion'], isNotEmpty);
+      expect(event['osVersion'], isNotEmpty);
+      expect(event['props'], {'identifierType': 'username', 'durationMs': 123});
+    });
+
+    test('eventId 为 UUIDv7 且逐事件唯一', () async {
+      final service = buildService();
+
+      await service.trackEvent('auth_login_succeeded');
+      await service.trackEvent('auth_logout');
+
+      final ids = service.pendingEvents
+          .map((event) => event['eventId'] as String)
+          .toList();
+      expect(ids[0], matches(uuidV7));
+      expect(ids[1], matches(uuidV7));
+      expect(ids[0], isNot(ids[1]));
+    });
+
+    test('同一 tracker 下多事件 sessionId 相同，不再每事件生成', () async {
+      final service = buildService(getSessionId: () => 'tracker-session');
+
+      await service.trackEvent('auth_login_succeeded');
+      await service.trackEvent('page_viewed', {'pageName': 'home'});
+      await service.trackEvent('auth_logout');
+
+      final sessionIds = service.pendingEvents
+          .map((event) => event['sessionId'])
+          .toSet();
+      expect(sessionIds, {'tracker-session'});
+    });
+
+    test('appVersion 可注入更新（不再硬编码）', () async {
+      final service = buildService();
+
+      service.setAppVersion('2.3.4+56');
+      await service.trackEvent('auth_login_succeeded');
+
+      expect(service.pendingEvents.single['appVersion'], '2.3.4+56');
    });

    test('rejects events with forbidden field patterns', () async {
-      final service = AnalyticsService(
-        apiBaseUrl: 'http://test',
-        getAccessToken: null,
-      );
+      final service = buildService();

      // Forbidden field triggers local rejection (no throw, silent drop).
      await service.trackEvent('auth_login_succeeded', {
        'userPassword': 'leak', // Forbidden pattern
      });

-      // Event should be dropped (no assertion — just verify no crash).
+      expect(service.pendingEvents, isEmpty);
    });

-    test('identify sets userId', () {
-      final service = AnalyticsService(
-        apiBaseUrl: 'http://test',
-        getAccessToken: null,
-      );
+    test('identify sets userId on subsequent events', () async {
+      final service = buildService();

      service.identify('user-123');
+      await service.trackEvent('auth_login_succeeded');

-      // Subsequent events will carry userId (validated in integration tests).
+      expect(service.pendingEvents.single['userId'], 'user-123');
    });

-    test('reset clears userId but keeps anonymousId', () {
-      final service = AnalyticsService(
-        apiBaseUrl: 'http://test',
-        getAccessToken: null,
-        anonymousId: 'anon-123',
-      );
+    test('reset clears userId but keeps anonymousId', () async {
+      final service = buildService(anonymousId: 'anon-123');

      service.identify('user-123');
      service.reset();
+      await service.trackEvent('auth_logout');

-      // userId cleared, anonymousId retained (validated in integration tests).
+      final event = service.pendingEvents.single;
+      expect(event.containsKey('userId'), isFalse);
+      expect(event['anonymousId'], 'anon-123');
+    });
+
+    test('上传失败批次重回队列而非整批丢弃', () async {
+      // apiBaseUrl 指向不可达端口：满 20 条触发 flush 必然失败。
+      final service = AnalyticsService(
+        apiBaseUrl: 'http://127.0.0.1:1',
+        getAccessToken: null,
+        getSessionId: () => 's',
+      );
+
+      for (var i = 0; i < 20; i++) {
+        await service.trackEvent('auth_login_succeeded', {'attemptSeq': i});
+      }
+
+      // 第 20 条触发上传，失败后批次应重回队列（M0 行为是整批清空）。
+      expect(service.pendingEvents.length, 20);
    });
  });
 }
@@ -0,0 +1,77 @@
+import 'package:flutter/widgets.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:patbond_flutter/analytics/session_tracker.dart';
+
+void main() {
+  final uuidV7 = RegExp(
+    r'^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[0-9a-f]{4}-[0-9a-f]{12}$',
+  );
+
+  group('SessionTracker', () {
+    test('冷启动生成 UUIDv7 格式的 sessionId', () {
+      final tracker = SessionTracker();
+      expect(tracker.sessionId, matches(uuidV7));
+    });
+
+    test('短后台（≤30 分钟）resume 后沿用原 sessionId', () {
+      var clock = DateTime.utc(2026, 9, 7, 10);
+      final tracker = SessionTracker(now: () => clock);
+      final original = tracker.sessionId;
+
+      tracker.didChangeAppLifecycleState(AppLifecycleState.paused);
+      clock = clock.add(const Duration(minutes: 30));
+      tracker.didChangeAppLifecycleState(AppLifecycleState.resumed);
+
+      expect(tracker.sessionId, original);
+    });
+
+    test('长后台（>30 分钟）resume 后生成新 sessionId', () {
+      var clock = DateTime.utc(2026, 9, 7, 10);
+      final tracker = SessionTracker(now: () => clock);
+      final original = tracker.sessionId;
+
+      tracker.didChangeAppLifecycleState(AppLifecycleState.paused);
+      clock = clock.add(const Duration(minutes: 31));
+      tracker.didChangeAppLifecycleState(AppLifecycleState.resumed);
+
+      expect(tracker.sessionId, isNot(original));
+      expect(tracker.sessionId, matches(uuidV7));
+    });
+
+    test('真实生命周期级联下退后台时刻不被 inactive 覆盖', () {
+      // 前台恢复时状态机级联 paused → hidden → inactive → resumed，
+      // 若 inactive 覆盖记时，31 分钟长后台会被误判为 0 分钟。
+      var clock = DateTime.utc(2026, 9, 7, 10);
+      final tracker = SessionTracker(now: () => clock);
+      final original = tracker.sessionId;
+
+      tracker.didChangeAppLifecycleState(AppLifecycleState.inactive);
+      tracker.didChangeAppLifecycleState(AppLifecycleState.hidden);
+      tracker.didChangeAppLifecycleState(AppLifecycleState.paused);
+      clock = clock.add(const Duration(minutes: 31));
+      tracker.didChangeAppLifecycleState(AppLifecycleState.hidden);
+      tracker.didChangeAppLifecycleState(AppLifecycleState.inactive);
+      tracker.didChangeAppLifecycleState(AppLifecycleState.resumed);
+
+      expect(tracker.sessionId, isNot(original));
+    });
+
+    test('连续多次短后台幂等，仅超阈值才换新', () {
+      var clock = DateTime.utc(2026, 9, 7, 10);
+      final tracker = SessionTracker(now: () => clock);
+      final original = tracker.sessionId;
+
+      for (var i = 0; i < 3; i++) {
+        tracker.didChangeAppLifecycleState(AppLifecycleState.paused);
+        clock = clock.add(const Duration(minutes: 10));
+        tracker.didChangeAppLifecycleState(AppLifecycleState.resumed);
+        expect(tracker.sessionId, original);
+      }
+
+      tracker.didChangeAppLifecycleState(AppLifecycleState.paused);
+      clock = clock.add(const Duration(minutes: 35));
+      tracker.didChangeAppLifecycleState(AppLifecycleState.resumed);
+      expect(tracker.sessionId, isNot(original));
+    });
+  });
+}