# yx_tracking_flutter

企业级 Flutter 埋点 SDK（Flutter 运行环境使用，非纯 Dart 运行时），对齐后端接口：

- `GET /api/ExternalEventlogs/GetSystemAllDimInfo`
- `POST /api/ExternalEventlogs/AddEventListLog`
- `POST /api/ExternalEventlogs/AddEventLog`（可选降级）

当前已覆盖 Phase 1 / Phase 2 / Phase 3 的核心能力：初始化、持久化队列、批量上报、配置下发、校验、策略控制、拦截器与 SDK 自监控指标。

## 功能特性

- 统一事件模型，自动补齐公共字段（systemCode、deviceInfo、时间戳等）
- 本地持久化队列（sqflite），默认运行在独立 Isolate 中，避免阻塞 UI（需 Flutter 环境）
- 应用生命周期监听（进入后台/销毁时自动 flush）
- 批量上报 + 重试退避 + 队列上限裁剪
- 配置下发（`GetSystemAllDimInfo`）与本地缓存
- 事件校验（Debug 详细日志，Release 自动标记 `_sdk_*`）
- 动态策略（全局开关、事件级开关、采样率）
- 拦截器机制（beforeSend / afterSend，异常隔离）
- SDK 自监控指标（发送成功/失败/重试/丢弃、队列长度、平均延迟）

## 快速开始

在你的 App 初始化阶段调用：

```dart
import 'package:yx_tracking_flutter/yx_tracking_flutter.dart';

Future<void> bootstrapAnalytics() async {
  await Analytics.init(
    const AnalyticsConfig(
      systemCode: 'OA_APP',
      endpointBaseUrl: 'https://your-host',
      clientType: 3,
      enableDebug: true,
    ),
  );
  
  // 注册生命周期监听（推荐）
  Analytics.bindLifecycleObserver();
}
```

上报事件：

```dart
await Analytics.track(
  'PAGE_VIEW',
  eventParams: const <String, dynamic>{
    'Page': 'home',
    'Url': 'https://example.com/home',
    'ButtonId': 'page_view',
  },
  customTags: const <String, dynamic>{'tenantId': 't1'},
);
```

手动触发发送：

```dart
await Analytics.flush(force: true);
```

## 关键配置项（AnalyticsConfig）

除了文档中的 Phase 1 配置项，还新增了以下能力配置：
- `endpointBaseUrl`：仅填写基础 host（如 `https://your-host`），SDK 会自动拼接 `/api/ExternalEventlogs/*` 路径
- `useIsolateStorage`: 是否使用 Isolate 进行存储操作（默认 `true`，强烈建议在 Flutter 环境开启）
- `allowInsecureHttp`：是否允许使用 HTTP（默认 `false`，仅用于开发/测试环境）
- `enableMetrics`：是否启用 SDK 自监控指标（默认 `true`）
- `metricsReportInterval`：指标上报周期（默认 10 分钟）
- `blockOnValidationError`：Debug 下遇到校验 error 是否阻断发送（默认 `false`）

所有配置项详见：`lib/src/config/analytics_config.dart`

## 调试与运维能力

调试 API：

```dart
final count = await Analytics.cachedEventCount();
final recent = await Analytics.cachedRecentEvents(limit: 20);
await Analytics.refreshConfig(force: true);
await Analytics.reportMetricsNow();
```

## 拦截器（Phase 3）

```dart
class TenantInterceptor extends AnalyticsInterceptor {
  @override
  Future<Event?> beforeSend(Event event) async {
    final tags = Map<String, dynamic>.from(event.customTags ?? const {});
    tags['tenantId'] = 't1';
    return event.copyWith(customTags: tags);
  }
}

void setupInterceptors() {
  Analytics.addInterceptor(TenantInterceptor());
}
```

SDK 内置 `CommonTagsInterceptor`，会自动追加：

- `_sdk_version`
- `_platform`

## 运行示例 Demo

仓库已包含最小调试 Demo：

```bash
cd example
flutter run
```

Demo 提供：缓存条数、最近事件摘要、Track Demo Event、Flush Now、Refresh Config。

## 测试与校验

已通过以下本地校验：

- 根目录：`flutter analyze` / `flutter test`
- example：`flutter analyze` / `flutter test`

## 参考文档

- 设计方案：`2.Flutter 埋点 SDK 设计方案（独立 Dart 实现）.md`
- 实施清单：`3.Flutter todo list.md`