140 lines
6.6 KiB
Markdown
140 lines
6.6 KiB
Markdown
## 一、准备阶段
|
||
|
||
### A. 项目初始化
|
||
|
||
- [x] 创建 Flutter package 工程（当前包名：`yx_tracking_flutter`）
|
||
- [x] 配置 `pubspec.yaml`（已添加 `sqflite`、`path_provider`、`dio`、`path`）
|
||
- [x] 配置 SDK 最低支持 Flutter / Dart 版本（Flutter `>=3.22.0`，Dart `>=3.3.0 <4.0.0`）
|
||
- [x] 建立基础目录结构（入口为 `lib/yx_tracking_flutter.dart`，`lib/src/*` 已建立）
|
||
- [x] 约定统一代码风格（使用 `flutter_lints`）
|
||
|
||
------
|
||
|
||
## 二、Phase 1 开发任务（可用性 + 稳定性）
|
||
|
||
### 1. 基础模型与配置
|
||
|
||
- [x] 实现 `AnalyticsConfig`（含 HTTPS 与参数校验）
|
||
- [x] 实现 `UserInfo`
|
||
- [x] 实现 `DeviceInfo`
|
||
- [x] 实现 `Event` & `StoredEvent`（含 payload 序列化/反序列化）
|
||
- [x] 实现 `TimeUtil`（时间戳 & ISO8601 格式化）
|
||
- [x] 实现 `Logger`（debug/info/warn/error，debug 开关控制）
|
||
- [x] 实现 `DeviceUtil`（采集 os/model/screenResolution 的最小实现）
|
||
|
||
### 2. 存储层（EventStorage + Sqflite）
|
||
|
||
- [x] 抽象接口 `EventStorage`（含 init/insert/fetchBatch/delete/count/trim/updateRetryCount/dispose）
|
||
- [x] 实现 `SqfliteEventStorage`（建表、索引、CRUD、trim、retryCount 更新）
|
||
- [x] 封装事件反序列化（`Event.fromPayload` / `Event.fromJson`）
|
||
- [x] 稳定性修补：`fetchBatch` 会删除解析失败的坏数据，避免队列被卡死
|
||
|
||
### 3. 网络层（ApiClient）
|
||
|
||
- [x] 封装 `HttpClient`（基于 Dio，支持超时与自定义 headers）
|
||
- [x] 实现 `ApiClient.sendBatch`（调用 `/AddEventListLog`）
|
||
- [x] 状态码与异常模型（`ApiException` 区分可重试/不可重试）
|
||
|
||
### 4. 核心逻辑（AnalyticsCore + Scheduler）
|
||
|
||
- [x] 实现 `Scheduler`（`Timer.periodic` + start/stop）
|
||
- [x] 实现 `AnalyticsCore.init`（校验配置、采集设备、初始化存储/网络、启动调度）
|
||
- [x] 实现 `track` 主流程（构造事件、入库、trim、达到 batchSize 触发 flush）
|
||
- [x] 实现 `flush`（互斥、防并发、批量发送、重试与退避）
|
||
- [x] 稳定性增强（重试退避、异常兜底、坏数据清理）
|
||
- [x] Phase 2 已接入（ConfigManager、Validator、配置周期刷新、release 校验标记）\n- [x] 实现 `IsolateEventStorage`（默认启用，后台 Isolate 执行 IO）\n- [x] 实现生命周期监听（`bindLifecycleObserver`，后台/销毁时自动 flush）
|
||
|
||
### 5. Facade 对外接口（company_analytics.dart）
|
||
|
||
- [x] 暴露 `Analytics` Facade（入口文件：`lib/yx_tracking_flutter.dart`）
|
||
- [x] 已提供 `init/track/setUser/setDeviceInfo/flush/setDebug/dispose`
|
||
- [x] 调试 API：`cachedEventCount/cachedRecentEvents/refreshConfig/reportMetricsNow`
|
||
- [x] `addInterceptor(...)` 已实现（Phase 3）
|
||
|
||
### 6. Phase 1 测试任务
|
||
|
||
- [x] 基础单测已存在（配置校验、事件序列化/反序列化）
|
||
- [x] `EventStorage` 行为测试已覆盖（trim、fetchRecent、retryCount 更新等契约测试）
|
||
- [x] `AnalyticsCore.track/flush` 成功与失败重试路径测试已覆盖
|
||
- [x] 已完成 mock 集成测试与压力测试（断网恢复补发、track 1 万次稳定性）
|
||
|
||
------
|
||
|
||
## 三、Phase 2 开发任务（配置化 + 校验 + 调试）
|
||
|
||
### 1. 配置模型 & 持久化
|
||
|
||
- [x] 定义 `SystemInfo / EventDefinition / TagDefinition / SystemDimInfo`
|
||
- [x] 使用 sqflite 同库缓存配置（表：`config_cache`）
|
||
- [x] 已实现 `saveSystemDimInfo / loadSystemDimInfo`
|
||
|
||
### 2. ConfigManager
|
||
|
||
- [x] 已实现 `ConfigManager`（持有 `currentConfig`、支持缓存加载与拉取）
|
||
- [x] 已接入 `GET /GetSystemAllDimInfo?system_code=...`
|
||
- [x] 已在 `AnalyticsCore.init` 中异步拉取（失败不影响埋点）
|
||
- [x] 周期刷新已补齐（定时器按 refreshInterval 拉取）
|
||
- [x] Example 联调支持 HTTP（新增 allowInsecureHttp 配置）
|
||
|
||
### 3. Validator（事件校验）
|
||
|
||
- [x] 已实现 `Validator`（依赖 `ConfigManager`，输出 `ValidationResult`）
|
||
- [x] 已在 `AnalyticsCore.track` 中接入校验并打印 errors/warnings
|
||
- [x] Release 模式已补充校验标记（写入 `_sdk_invalid_event/_sdk_missing_tags/_sdk_type_error_fields`）
|
||
- [x] “严重 error 阻断发送”的策略开关已实现（`blockOnValidationError`）
|
||
|
||
### 4. 调试增强
|
||
|
||
- [x] `Logger` 已具备 debug/info/warn/error 级别与 debug 开关
|
||
- [x] 关键路径日志已接入（init/track/flush/validator/config）
|
||
- [x] 已提供 Demo 调试界面（`example/`）
|
||
- [x] Demo 已支持：缓存条数、最近事件摘要、Track Demo Event、Flush Now、Refresh Config
|
||
|
||
### 5. Phase 2 测试任务
|
||
|
||
- [x] 配置拉取测试已覆盖（正确/错误 JSON、刷新跳过、缓存保持）
|
||
- [x] 校验行为测试已覆盖（未知事件、缺失必填、类型不匹配）
|
||
- [x] “配置失败不影响发送”的降级路径已覆盖（无配置仍可 track/flush）
|
||
|
||
------
|
||
|
||
## 四、Phase 3 开发任务（监控 + 策略 + 插件）
|
||
|
||
### 1. 自监控埋点
|
||
|
||
- [x] 已在 `AnalyticsCore` 中增加统计字段（sent/failed/retry/dropped、平均延迟、窗口时间）
|
||
- [x] 已在 flush 成功 / 失败 / 删除 / 丢弃等位置更新计数
|
||
- [x] 已实现指标上报（定时器 + 内部事件 `SDK_METRICS_SEND / SDK_METRICS_QUEUE`）
|
||
- [x] 已提供调试入口：`Analytics.reportMetricsNow()`
|
||
|
||
### 2. 策略控制（采样与开关）
|
||
|
||
- [x] 已在 `SystemDimInfo` 中增加策略字段（`SdkStrategy / EventStrategy`）
|
||
- [x] 已在 `ConfigManager` 中解析并缓存策略
|
||
- [x] 已在 `AnalyticsCore.track` 入口接入策略（全局开关 / 事件开关 / 采样率）
|
||
|
||
### 3. 插件（拦截器）机制
|
||
|
||
- [x] 已定义接口 `AnalyticsInterceptor`（`beforeSend / afterSend`）
|
||
- [x] 已在 `AnalyticsCore` 中维护拦截器列表并实现 `addInterceptor(...)`
|
||
- [x] 已在 flush 前调用 `beforeSend`（支持返回 null 拦截事件）
|
||
- [x] 已在 flush 后调用 `afterSend`（成功/失败均回调）
|
||
- [x] 已做异常隔离（拦截器异常不会影响主流程）
|
||
- [x] 已内置 `CommonTagsInterceptor`（自动追加 `_sdk_version/_platform`）
|
||
|
||
### 4. Phase 3 测试任务
|
||
|
||
- [x] 自监控事件测试已覆盖（`reportMetricsNow` 生成 `SDK_METRICS_*` 事件）
|
||
- [x] 策略测试已覆盖（全局关闭、事件关闭、采样率）
|
||
- [x] 拦截器测试已覆盖（追加 tag、拦截事件、异常隔离、afterSend 回调）
|
||
|
||
------
|
||
|
||
## 五、交付物与文档清单
|
||
|
||
- [x] SDK 源码（Flutter package）
|
||
- [x] 单元测试代码（关键路径已覆盖；覆盖率统计报告需单独产出）
|
||
- [x] 集成 Demo App（示例项目，含 Debug 页面）
|
||
- [x] 文档：README（使用说明 + 调试/拦截器/指标能力）
|
||
- [x] 文档：设计说明（`2.Flutter 埋点 SDK 设计方案（独立 Dart 实现）.md`）
|