# 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` |
| **系统标识** | `SDK-TEST-FLUTTER` |
| **系统名称** | Flutter SDK测试 |
| **认证方式** | 无需认证 |
| **协议** | HTTP（生产建议 HTTPS） |

---

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

### 2.1 修复参数命名问题

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

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

**修改位置**: 第 59 行

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

---

### 2.2 更新 Example App 配置

#### [MODIFY] `example/lib/main.dart`

**修改位置**: 第 10-17 行

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

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

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

---

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

#### [MODIFY] `example/lib/main.dart`

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

```dart
  // 绑定生命周期监听，后台时自动 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

```bash
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 事件上报

```http
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",
      "Url": "https://example.com/demo",
      "ButtonId": "demo_btn_01"
    },
    "customTags": {"tenantId": "t1", "feature": "demo"}
  }
]
```

### 4.2 获取配置

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

**响应示例**:
```json
{
  "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 按照以上方案执行修改。**