yx_tracking_flutter/4.Example App 集成实施方案.md

Example App 集成实施方案

Example App Integration Implementation Plan

目标 (Goal): 使 example app 能够完整运行并对接真实后端
执行者 (Executor): Codex
日期 (Date): 2026-01-28
执行记录 (Execution): 已执行（参数名修复、Example 配置更新、生命周期监听接入、HTTP 放行）

---

一、后端配置信息 | Backend Configuration

项目	值
API 基础地址	http://192.168.2.7:18828/api/ExternalEventlogs
系统标识	SDK-TEST-FLUTTER
系统名称	Flutter SDK测试
认证方式	无需认证
协议	HTTP（生产建议 HTTPS）

---

二、需要修改的文件 | Files to Modify

2.1 修复参数命名问题

[MODIFY] lib/src/config/config_manager.dart

问题: SDK 使用 system_code，但后端期望 systemCode

修改位置: 第 59 行

- queryParameters: <String, dynamic>{'system_code': config.systemCode},
+ queryParameters: <String, dynamic>{'systemCode': config.systemCode},

---

2.2 更新 Example App 配置

[MODIFY] example/lib/main.dart

修改位置: 第 10-17 行

  await Analytics.init(
    const AnalyticsConfig(
-     systemCode: 'DEMO_APP',
-     endpointBaseUrl: 'https://example.com/api/ExternalEventlogs',
+     systemCode: 'SDK-TEST-FLUTTER',
+     endpointBaseUrl: 'http://192.168.2.7:18828/api/ExternalEventlogs',
      clientType: 3,
      enableDebug: true,
      batchSize: 5,
      flushInterval: 30,
      allowInsecureHttp: true,
    ),
  );

修改位置: 第 161-164 行（更新说明文字）

- const Text(
-   '说明：Demo 使用 example.com 作为占位地址，'
-   '实际联调时请替换为真实 HTTPS 域名。',
- ),
+ const Text(
+   '说明：已对接 SDK-TEST-FLUTTER 系统，'
+   '点击 Track 按钮记录事件，点击 Flush 上报。',
+ ),

---

2.3 添加生命周期监听（可选优化）

[MODIFY] example/lib/main.dart

修改位置: 第 18 行之后添加

  // 绑定生命周期监听，后台时自动 flush
  Analytics.bindLifecycleObserver();

---

### 2.4 放行 HTTP（开发/测试环境）

#### [MODIFY] `lib/src/config/analytics_config.dart`

**说明**: 为联调环境允许 HTTP，新增 `allowInsecureHttp` 配置项。

```diff
 const AnalyticsConfig({
   ...
   this.allowInsecureHttp = false,
 });

 // validate()
 if (scheme == 'http' && allowInsecureHttp) {
   // 允许开发/测试环境使用 HTTP
 }

---

## 三、验证步骤 | Verification Steps

### 3.1 运行测试

```bash
cd /Volumes/Workspace/SourceCode/yuanxuan/yx_tracking_flutter
flutter test

3.2 运行 Example App

cd /Volumes/Workspace/SourceCode/yuanxuan/yx_tracking_flutter/example
flutter run -d macos  # 或 chrome / android / ios

3.3 功能验证清单

• 启动 App 无报错
• 点击 "Track Demo Event"，缓存数量 +1
• 点击 "Flush Now"，事件成功上报（HTTP 200）
• 点击 "Refresh Config"，从后端拉取配置成功
• 在管理后台查看上报的事件数据

---

四、API 接口参考 | API Reference

4.1 事件上报

POST /api/ExternalEventlogs/AddEventListLog
Content-Type: application/json

[
  {
    "system_code": "SDK-TEST-FLUTTER",
    "eventType": "DEMO_BUTTON_CLICK",
    "userInfo": null,
    "clientType": 3,
    "clientTimestamp": 1706000000000,
    "timestamp": "2026-01-28T12:00:00.000Z",
    "deviceInfo": {
      "os": "macOS 14.0",
      "model": "MacBook Pro",
      "screenResolution": "1920x1080"
    },
    "eventParams": {"page": "demo"},
    "customTags": {"tenantId": "t1", "feature": "demo"}
  }
]

4.2 获取配置

GET /api/ExternalEventlogs/GetSystemAllDimInfo?systemCode=SDK-TEST-FLUTTER

响应示例:

{
  "systemInfo": {
    "system_code": "SDK-TEST-FLUTTER",
    "system_name": "Flutter SDK测试"
  },
  "systemEventTypes": [
    {"event_code": "DEMO_BUTTON_CLICK", "event_name": "Demo按钮点击"}
  ],
  "systemCustonTas": [
    {"tag_name": "tenantId", "tag_type": "string"}
  ]
}

---

五、数据模型对齐 | Data Model Alignment

后端字段 (EventlogAddDto)	SDK 字段 (Event)	状态
system_code	systemCode	✅
eventType	eventType	✅
userInfo	userInfo	✅
clientType (1=Android, 2=iOS, 3=Flutter)	clientType	✅ 使用 3
clientTimestamp (int64 毫秒)	clientTimestamp	✅
timestamp (ISO8601)	timestamp	✅
deviceInfo	deviceInfo	✅
eventParams	eventParams	✅
customTags	customTags	✅

---

六、注意事项 | Notes

1. 网络环境: 确保开发机器可访问 192.168.2.7:18828
2. 事件类型: 如需校验事件类型，需在管理后台配置 DEMO_BUTTON_CLICK
3. 自定义标签: 如需校验标签，需在管理后台配置 tenantId、feature
4. HTTP 仅限联调: 生产环境请务必使用 HTTPS，并关闭 allowInsecureHttp

---

请 Codex 按照以上方案执行修改。