patbond-doc/docs/development/iterations/iteration-2/10-flutter-analytics-repair.md

M2 第一波 Flutter 埋点修复报告

角色：Frontend Developer (Flutter)
日期：2026-09-07
依据：03 号技术评估、06 号埋点与实验规划、13 号埋点落地工程规范
仓库：patbond-flutter @ dev 分支，基线 34 测试全绿
任务：修复 M1 遗留的两个高优先埋点项（sessionId 生命周期、page_viewed 路由埋点），确保 M2 新事件的会话与版本维度可用

---

0. 执行摘要

改动范围：15 文件（6 新增 + 9 修改），766 行插入 / 49 行删除
测试数变化：34 → 51（+17 新增：session_tracker 5 + analytics_service 补强 4 + route_observer 8）
质量门禁：flutter analyze 0 问题，dart format 0 变更，51 测试全绿
提交：2 个逻辑提交（4c2f839 接线修复 + SessionTracker + 三处偏差；6fef0db page_viewed 路由埋点），已推送 origin/dev

核心修复：

1. 生产接线修复（03 §1.4 #4）：app.dart 组装时传 analytics 实例给 ApiAuthRepository，修复 M1 遗留的「生产环境 _analytics 恒为 null、登录纵切埋点空转」问题
2. sessionId 生命周期（06 §5.1 + 13 §3.1）：新建 SessionTracker (WidgetsBindingObserver)，冷启动/后台超 30 分钟换新 UUIDv7 sessionId，不再每事件随机生成
3. 三处偏差修复（06 §0.1）：eventId 改 UUIDv7、appVersion 改 package_info_plus 动态读取、osVersion 改 Platform.operatingSystemVersion 正则提取
4. page_viewed 路由埋点（06 §5.2 + 03 §3.2）：AnalyticsRouteObserver 集中式捕获 didPush/didReplace/didPop，pageName 枚举化，referrer 链跨机制连贯，三类非路由曝光手动补点

---

1. 改动清单（按施工顺序）

1.1 SessionTracker（新建 lib/analytics/session_tracker.dart）

职责：管理 sessionId 生命周期，WidgetsBindingObserver 监听 app 生命周期状态。

语义三条（13 §4.0 + 06 §5.1）：

1. 冷启动生成新 sessionId（构造时 Uuid().v7()）
2. AppLifecycleState.paused → resumed 间隔 > 30 分钟：生成新 sessionId
3. 间隔 ≤ 30 分钟：沿用原 sessionId

实现要点：

• 只在首次离开 resumed 状态时记录 _leftForegroundAt（level 级联 inactive/hidden/paused 不覆盖，否则间隔永趋近零）
• sessionId 纯内存存储，不落 shared_preferences（03 §3.1 决策：冷启动本来就换新，持久化无增量价值）
• 构造参数化 timeout（默认 30 分钟）与时钟注入（测试免真实等待）

单测 5 例（test/analytics/session_tracker_test.dart，验收标准第 5 条）：

1. 冷启动生成 UUIDv7 格式
2. 短后台（≤30 分钟）沿用原值
3. 长后台（>30 分钟）换新
4. 真实级联状态下退后台时刻不被 inactive 覆盖
5. 连续多次短后台幂等，仅超阈值才换新

1.2 AnalyticsService 三处偏差修复（修改 lib/analytics/analytics_service.dart）

改动点：

#	偏差（06 §0.1）	修复	验收证据
1	eventId 为 UUID v4	改为 Uuid().v7()（uuid 包已在依赖，直接用）	单测断言 UUIDv7 正则 + 逐事件唯一
2	sessionId 每事件生成	构造参数 getSessionId，从 SessionTracker 注入	单测：同 tracker 下多事件 sessionId 相同
3	appVersion/osVersion 硬编码	appVersion 构造默认 'unknown'、异步 setAppVersion()；osVersion 从 Platform.operatingSystemVersion 正则提取主版本	单测：setAppVersion 后事件携带注入值

顺手加固（03 §1.4 #1 的一行级缓解）：上传失败批次重回队首而非整批丢弃（M0 行为），上限 500 条超限丢最旧。真正的 shared_preferences 分段持久化队列属 M2 第二波（03 §3.2 注意）。

单测补强 4 例（test/analytics/analytics_service_test.dart）：

1. eventId 为 UUIDv7 且逐事件唯一
2. 同一 tracker 下多事件 sessionId 相同，不再每事件生成
3. appVersion 可注入更新（不再硬编码）
4. 上传失败批次重回队列而非整批丢弃

1.3 生产接线修复（修改 lib/app/app.dart）

问题根源（03 §1.4 #4）：_buildRepository() 构造 ApiAuthRepository 时未传 analytics 实例，生产构建里 _analytics 恒为 null，登录/注册/退出纵切的 5 处挂接点空转。

修复：

1. app.dart 的 _AppState.initState() 实例化 AnalyticsService（传入 getSessionId: () => _sessionTracker.sessionId）
2. _buildRepository() 构造 ApiAuthRepository 时传 analytics: _analytics
3. 异步初始化 appVersion（PackageInfo.fromPlatform() 后 _analytics.setAppVersion()）
4. SessionTracker 注册/注销为 WidgetsBinding observer

auth_repository.dart 签名调整：构造器接收 AnalyticsService? analytics（沿用既有 this._analytics 私有命名参数风格）。

新增依赖：pubspec.yaml 加 package_info_plus: ^8.1.2（flutter pub add 自动选最新兼容版）。

1.4 page_viewed 路由埋点（新增 4 文件）

架构（03 §3.2 集中式 NavigatorObserver 方案）：

文件	职责
analytics_page_name.dart	pageName 编译期枚举（06 §5.2 字典 v2 + 03 Tab 映射），禁止自由字符串
page_view_tracker.dart	上报单一出口：维护 referrer 链、去重、reportTab 记录主壳当前 Tab
analytics_route_observer.dart	NavigatorObserver 派生：didPush/didReplace/didPop，字典外路由不上报
app.dart	组装：routeObserver 挂 MaterialApp.navigatorObservers，resolveRootPage 回栈到无名根路由时解析当前页

pageName 枚举（AnalyticsPageName）：

• 字典 v2 初始集合（06 §5.2）：login / register / home / profile / pet_list / pet_detail / pet_form / record_form / record_detail
• 客户端现存页/Tab 补充（03 §3.2）：create / pet_archive / services / post_detail
• M2 健康档案页面族尚未落地，pet_list 等先留枚举定义不接线

三类非路由曝光手动补点（03 §3.2）：

1. 主壳 Tab 切换（IndexedStack 无路由事件）：MainShellPage.selectTab() 内 pageViewTracker.reportTab()，initState 补初始 Tab
2. 认证状态机切页（根部 AnimatedSwitcher 无路由事件）：app.dart 的 sessionManager.addListener(_reportAuthStateChange)
3. 回栈到无名根路由（observer 的 didPop 无 previousRoute.name）：resolveRootPage 回调按认证状态 + 主壳当前 Tab 返回页面

既有 push 挂路由名（03 §3.2 清单 4）：

• login_page.dart：Navigator.push(fadePageRoute(..., settings: RouteSettings(name: AnalyticsPageName.register.pageName)))
• main_shell_page.dart：openPost() 的 MaterialPageRoute 挂 post_detail
• fade_route.dart：签名扩展可选 RouteSettings? settings 参数

单测 8 例（test/analytics/analytics_route_observer_test.dart，验收标准第 5 条）：

1. push 路由报 page_viewed
2. push 两页 referrer 链正确，pop 返回补报前一页（didPopNext）
3. pop 回无名根路由经 resolveRootPage 补报
4. 未在枚举的路由名不上报
5. dialog 不上报（PopupRoute 不是 PageRoute）
6. PageViewTracker：连续相同页面去重（Tab 重复点选）
7. referrer 链跨机制连贯（首页无 referrer）
8. reportTab 记录当前 Tab

---

2. 对照验收标准自证

2.1 sessionId 生命周期（06 §5.1 六条）

#	验收标准	自证
1	新建 lib/analytics/session_tracker.dart，注册为 WidgetsBindingObserver；AnalyticsService 从它读 sessionId	✓ session_tracker.dart 新建，app.dart 注册 observer，AnalyticsService 构造接收 getSessionId 注入
2	语义三条：冷启动生成新；paused→resumed 超 30 分钟生成新；≤30 分钟沿用	✓ 构造时生成、didChangeAppLifecycleState 判定间隔
3	同一前台会话内所有事件 sessionId 完全一致	✓ 单测「同一 tracker 下多事件 sessionId 相同」通过
4	sessionId 为 UUID，不落任何持久化存储	✓ Uuid().v7() 生成，纯内存字段 _sessionId
5	单元测试 ≥3 例：冷启动/短后台/长后台	✓ session_tracker_test.dart 5 例（冷启动/短≤30min/长>30min/级联状态/连续幂等）
6	真机手测脚本	交付 QA/开发者手测（登录→退后台 5min→回前台操作→退后台 35min→回前台，库内应恰好 2 个 sessionId）

2.2 page_viewed 路由埋点（06 §5.2 六条）

#	验收标准	自证
1	RouteObserver 注册进 MaterialApp.navigatorObservers，didPush/didPopNext 触发 page_viewed	✓ AnalyticsRouteObserver 注册，didPush/didReplace/didPop 实现
2	pageName 是编译期枚举，v2 初始集合 9 个 + 客户端现存 4 个；带参数路由归一化	✓ AnalyticsPageName 枚举 13 个值，fromRouteName 映射，路由名取自枚举 pageName 字段
3	referrer = 前一页 pageName，栈底/冷启动首页为 null	✓ PageViewTracker 维护 _lastPageName，首次报告无 referrer；单测「referrer 链跨机制连贯」通过
4	不在字典枚举内的路由不上报	✓ AnalyticsPageName.fromRouteName 返回 null 时 observer 不调 track；单测「未在枚举的路由名不上报」通过
5	单测/widget 测试：push 两页断言两条事件且 referrer 链正确；pop 返回断言 didPopNext 补报	✓ analytics_route_observer_test.dart：「push 两页 referrer 链正确，pop 返回补报前一页」通过
6	M1 存量四页与 M2 新页一次性挂全	✓ login/register 由 RouteSettings 挂；home/create/pet_archive/services/profile 由 Tab 补点；post_detail 由 openPost 挂；M2 健康档案页面族枚举已预留、待功能落地接线

---

3. 测试数变化与覆盖

基线：34 测试全绿（第一迭代收官记录）
收官：51 测试全绿（+17 新增）

新增分布：

• test/analytics/session_tracker_test.dart：5 例（冷启动/短后台/长后台/级联状态/连续幂等）
• test/analytics/analytics_service_test.dart 补强：4 例（UUIDv7/sessionId 不再逐事件生成/appVersion 可注入/失败重回队列）
• test/analytics/analytics_route_observer_test.dart：8 例（push/pop/referrer 链/根路由 resolveRootPage/枚举外不报/dialog 不报/Tab 去重/reportTab）

既有测试回归：34 测试 0 失败，登录/注册/主壳冒烟测试、auth_repository 单测、widget 组件测试均不受影响（analytics 注入为可选参数，测试继续传 null/FakeAuthRepository）。

---

4. 新增依赖说明

依赖	版本	用途	引入理由
package_info_plus	^8.1.2	读取 app 版本号（version + buildNumber）	替代硬编码 appVersion，使版本维度指标可用（M2 起按版本切片看回归，06 §0.1 偏差 3）

uuid ^4.6.0 已在既有依赖（M1 用于 Idempotency-Key 与 anonymousId），直接用其 v7() 方法。Platform 来自 dart:io 标准库，无需新增依赖。

---

5. 遗留与下一波

5.1 本波完成项（06 §7.2 三处客户端小修）

1. ✅ sessionId 生命周期（P0，会话维度指标前置）
2. ✅ eventId 改 UUIDv7（顺手修，保留插入局部性）
3. ✅ appVersion/osVersion 动态读取（版本维度可用）
4. ✅ page_viewed 路由埋点（M2 新增高频事件，漏斗前置）
5. ✅ 生产接线修复（M1 遗留，本波一并关闭）

5.2 未闭环项（排入 M2 第二波或后续迭代）

1. shared_preferences 分段持久化队列（13 §3.3 原规范）：本波仅顺手加固失败重回队列（一行级），真正的 500 条分段、20 条/段、溢出淘汰最旧段排 M2 第二波（03 §3.2 注意、06 §7.2 工单拆分 1）
2. 主壳 Tab/认证切页的 page_viewed 单测：widget_test.dart 主壳冒烟测试未断言 page_viewed 事件（本波集成测试成本高，Tab 切换逻辑已由 PageViewTracker 单测覆盖去重语义）
3. 健康档案页面族 RouteSettings 接线：pageName 枚举已预留 pet_list/pet_detail/pet_form/record_form/record_detail，待 M2 健康档案功能落地时挂接（06 §5.2 验收 6 注明「M2 新页待功能落地接线」）
4. 真机手测脚本执行：sessionId 生命周期的 30 分钟后台判定需真机/模拟器验证（06 §5.1 验收 6），交付 QA 或开发者手测

---

6. 质量门禁通过记录

$ flutter analyze
No issues found! (ran in 0.9s)

$ dart format --set-exit-if-changed lib test
Formatted 46 files (0 changed) in 0.21 seconds.

$ flutter test
00:03 +51: All tests passed!

代码行数：+766 插入 / -49 删除，净增 717 行（含注释与测试）
文件数：6 新增（session_tracker + page_name + route_observer + page_view_tracker + 2 测试文件）+ 9 修改

---

7. 提交记录

仓库：patbond-flutter @ dev 分支
基线：3f8388e fix: 清零 flutter analyze 问题并修复隐私红线正则缺陷（CI 门禁）
提交：

4c2f839 修复：埋点接线与三处偏差（sessionId/eventId/设备信息）
  - 生产接线修复：app.dart 传 analytics 给 ApiAuthRepository
  - sessionId 生命周期：SessionTracker (WidgetsBindingObserver)
  - eventId 改 UUIDv7；appVersion 动态注入；osVersion 动态读取
  - 队列顺手加固：失败批次重回队列
  - 新增依赖 package_info_plus
  - 测试 +9 例（session_tracker 5 + analytics_service 补强 4）

6fef0db 新增：page_viewed 集中式路由埋点（NavigatorObserver）
  - AnalyticsRouteObserver 页面零侵入
  - AnalyticsPageName 枚举编译期锁死
  - PageViewTracker 维护 referrer 链与去重
  - 三类非路由曝光手动补点（Tab/认证/根路由）
  - 测试 +8 例（analytics_route_observer_test）

已推送：origin/dev（施工过程中曾误将全部改动合并进单提交 f501a95 并推送，随即以同内容的上述两个拆分提交 --force-with-lease 替换，内容零差异）。

---

8. 施工过程记录（debug trail）

1. 通读三份规范（06/03/13）与仓库现状，核对既有 34 测试基线
2. 发现 package_info_plus 未在依赖，flutter pub add package_info_plus 新增
3. 新建 SessionTracker（WidgetsBindingObserver），注意级联状态处理（首次离开 resumed 才记时）
4. 修改 AnalyticsService 三处偏差（eventId v7 / sessionId 注入 / appVersion 可变 / osVersion 动态）
5. 修改 app.dart 接线（实例化 analytics + tracker，传给 repository，注册 observer，认证切换监听）
6. 新建 page_viewed 四件套（枚举/tracker/observer/接线），主壳 Tab 补点，login_page/fade_route 挂路由名
7. 编写 session_tracker_test（5 例）+ analytics_service_test 补强（4 例）+ analytics_route_observer_test（8 例）
8. flutter test 第一轮编译错误：测试 lambda 签名不匹配（(name, props) 改 (name, [props])）
9. flutter analyze 第一轮警告：page_view_tracker 的 map literal 空安全操作符误用，改为命令式条件插入
10. 全绿后 dart format 确认无格式变更，提交代码（1 个合并提交），推送 origin/dev

---

Frontend Developer · 2026-09-07
基线测试 34 全绿 → 收官 51 全绿（+17），flutter analyze 0 问题，已推送。