yx_tracking_flutter/3.Flutter todo list.md

一、准备阶段

A. 项目初始化

• 创建 Flutter package 工程（当前包名：yx_tracking_flutter）
• 配置 pubspec.yaml（已添加 sqflite、path_provider、dio、path）
• 配置 SDK 最低支持 Flutter / Dart 版本（Flutter >=3.22.0，Dart >=3.3.0 <4.0.0）
• 建立基础目录结构（入口为 lib/yx_tracking_flutter.dart，lib/src/* 已建立）
• 约定统一代码风格（使用 flutter_lints）

---

二、Phase 1 开发任务（可用性 + 稳定性）

1. 基础模型与配置

• 实现 AnalyticsConfig（含 HTTPS 与参数校验）
• 实现 UserInfo
• 实现 DeviceInfo
• 实现 Event & StoredEvent（含 payload 序列化/反序列化）
• 实现 TimeUtil（时间戳 & ISO8601 格式化）
• 实现 Logger（debug/info/warn/error，debug 开关控制）
• 实现 DeviceUtil（采集 os/model/screenResolution 的最小实现）

2. 存储层（EventStorage + Sqflite）

• 抽象接口 EventStorage（含 init/insert/fetchBatch/delete/count/trim/updateRetryCount/dispose）
• 实现 SqfliteEventStorage（建表、索引、CRUD、trim、retryCount 更新）
• 封装事件反序列化（Event.fromPayload / Event.fromJson）
• 稳定性修补：fetchBatch 会删除解析失败的坏数据，避免队列被卡死

3. 网络层（ApiClient）

• 封装 HttpClient（基于 Dio，支持超时与自定义 headers）
• 实现 ApiClient.sendBatch（调用 /AddEventListLog）
• 状态码与异常模型（ApiException 区分可重试/不可重试）

4. 核心逻辑（AnalyticsCore + Scheduler）

• 实现 Scheduler（Timer.periodic + start/stop）
• 实现 AnalyticsCore.init（校验配置、采集设备、初始化存储/网络、启动调度）
• 实现 track 主流程（构造事件、入库、trim、达到 batchSize 触发 flush）
• 实现 flush（互斥、防并发、批量发送、重试与退避）
• 稳定性增强（重试退避、异常兜底、坏数据清理）
• Phase 2 已接入（ConfigManager、Validator、配置周期刷新、release 校验标记）\n- 实现 IsolateEventStorage（默认启用，后台 Isolate 执行 IO）\n- 实现生命周期监听（bindLifecycleObserver，后台/销毁时自动 flush）

5. Facade 对外接口（company_analytics.dart）

• 暴露 Analytics Facade（入口文件：lib/yx_tracking_flutter.dart）
• 已提供 init/track/setUser/setDeviceInfo/flush/setDebug/dispose
• 调试 API：cachedEventCount/cachedRecentEvents/refreshConfig/reportMetricsNow
• addInterceptor(...) 已实现（Phase 3）

6. Phase 1 测试任务

• 基础单测已存在（配置校验、事件序列化/反序列化）
• EventStorage 行为测试已覆盖（trim、fetchRecent、retryCount 更新等契约测试）
• AnalyticsCore.track/flush 成功与失败重试路径测试已覆盖
• 已完成 mock 集成测试与压力测试（断网恢复补发、track 1 万次稳定性）

---

三、Phase 2 开发任务（配置化 + 校验 + 调试）

1. 配置模型 & 持久化

• 定义 SystemInfo / EventDefinition / TagDefinition / SystemDimInfo
• 使用 sqflite 同库缓存配置（表：config_cache）
• 已实现 saveSystemDimInfo / loadSystemDimInfo

2. ConfigManager

• 已实现 ConfigManager（持有 currentConfig、支持缓存加载与拉取）
• 已接入 GET /GetSystemAllDimInfo?system_code=...
• 已在 AnalyticsCore.init 中异步拉取（失败不影响埋点）
• 周期刷新已补齐（定时器按 refreshInterval 拉取）
• Example 联调支持 HTTP（新增 allowInsecureHttp 配置）

3. Validator（事件校验）

• 已实现 Validator（依赖 ConfigManager，输出 ValidationResult）
• 已在 AnalyticsCore.track 中接入校验并打印 errors/warnings
• Release 模式已补充校验标记（写入 _sdk_invalid_event/_sdk_missing_tags/_sdk_type_error_fields）
• “严重 error 阻断发送”的策略开关已实现（blockOnValidationError）

4. 调试增强

• Logger 已具备 debug/info/warn/error 级别与 debug 开关
• 关键路径日志已接入（init/track/flush/validator/config）
• 已提供 Demo 调试界面（example/）
• Demo 已支持：缓存条数、最近事件摘要、Track Demo Event、Flush Now、Refresh Config

5. Phase 2 测试任务

• 配置拉取测试已覆盖（正确/错误 JSON、刷新跳过、缓存保持）
• 校验行为测试已覆盖（未知事件、缺失必填、类型不匹配）
• “配置失败不影响发送”的降级路径已覆盖（无配置仍可 track/flush）

---

四、Phase 3 开发任务（监控 + 策略 + 插件）

1. 自监控埋点

• 已在 AnalyticsCore 中增加统计字段（sent/failed/retry/dropped、平均延迟、窗口时间）
• 已在 flush 成功 / 失败 / 删除 / 丢弃等位置更新计数
• 已实现指标上报（定时器 + 内部事件 SDK_METRICS_SEND / SDK_METRICS_QUEUE）
• 已提供调试入口：Analytics.reportMetricsNow()

2. 策略控制（采样与开关）

• 已在 SystemDimInfo 中增加策略字段（SdkStrategy / EventStrategy）
• 已在 ConfigManager 中解析并缓存策略
• 已在 AnalyticsCore.track 入口接入策略（全局开关 / 事件开关 / 采样率）

3. 插件（拦截器）机制

• 已定义接口 AnalyticsInterceptor（beforeSend / afterSend）
• 已在 AnalyticsCore 中维护拦截器列表并实现 addInterceptor(...)
• 已在 flush 前调用 beforeSend（支持返回 null 拦截事件）
• 已在 flush 后调用 afterSend（成功/失败均回调）
• 已做异常隔离（拦截器异常不会影响主流程）
• 已内置 CommonTagsInterceptor（自动追加 _sdk_version/_platform）

4. Phase 3 测试任务

• 自监控事件测试已覆盖（reportMetricsNow 生成 SDK_METRICS_* 事件）
• 策略测试已覆盖（全局关闭、事件关闭、采样率）
• 拦截器测试已覆盖（追加 tag、拦截事件、异常隔离、afterSend 回调）

---

五、交付物与文档清单

• SDK 源码（Flutter package）
• 单元测试代码（关键路径已覆盖；覆盖率统计报告需单独产出）
• 集成 Demo App（示例项目，含 Debug 页面）
• 文档：README（使用说明 + 调试/拦截器/指标能力）
• 文档：设计说明（2.Flutter 埋点 SDK 设计方案（独立 Dart 实现）.md）