sync events done

ATTENTION.md

@@ -0,0 +1,81 @@
+# ClickHouse使用注意事项
+
+## 数据插入最佳实践
+
+### 1. 利用ClickHouse的默认值机制
+
+在向ClickHouse插入数据时，对于有默认值的字段（如`event_id`、`timestamp`、`date`、`hour`等），可以不用显式提供这些值，让ClickHouse自动生成。这样可以：
+- 简化代码
+- 避免格式错误
+- 确保数据一致性
+
+示例：
+
+```typescript
+// 推荐做法：不指定有默认值的字段
+await clickhouse.insert({
+  table: 'events',
+  values: [{
+    // event_id, timestamp, date, hour 自动由ClickHouse生成
+    user_id: 'test-user-123',
+    influencer_id: 'influencer-456',
+    // 其他必要字段...
+  }],
+  format: 'JSONEachRow'
+});
+```
+
+### 2. 避免JSON格式问题
+
+使用`JSONEachRow`格式时，可能会遇到时间戳等特殊格式字段的解析错误：
+
+```
+Cannot parse input: expected '"' before: '.749Z","date":"2025-03-12",...
+```
+
+解决方法：
+- 让ClickHouse使用默认值自动生成时间相关字段
+- 如必须手动指定，确保格式严格符合ClickHouse要求
+
+### 3. 使用正确的方法
+
+ClickHouse客户端库(@clickhouse/client)提供了多种插入数据的方法：
+
+- **insert方法**：最适合结构化数据
+  ```typescript
+  await clickhouse.insert({
+    table: 'table_name',
+    values: [{ field1: value1, field2: value2 }],
+    format: 'JSONEachRow'
+  });
+  ```
+
+- **query方法**：适合原始SQL语句
+  ```typescript
+  await clickhouse.query({
+    query: `INSERT INTO table_name (field1, field2) VALUES (?, ?)`,
+    values: [[value1, value2]]
+  });
+  ```
+
+### 4. Enum类型字段
+
+对于Enum类型字段（如`event_type`、`funnel_stage`等），插入时使用定义的枚举字符串值，ClickHouse会自动转换为内部数字表示：
+
+```typescript
+// 正确：使用枚举字符串值
+event_type: 'comment',
+funnel_stage: 'consideration',
+```
+
+## 常见错误处理
+
+1. **JSON格式错误**：通常与时间戳和日期字段有关，尽可能使用ClickHouse默认值
+2. **枚举值错误**：确保使用表定义中的精确枚举字符串
+3. **数据类型不匹配**：检查每个字段的类型是否与表定义匹配
+
+## 性能考虑
+
+1. 批量插入比单条插入更高效
+2. 对于大批量数据，考虑使用流式插入
+3. 高频小数据量插入，考虑使用异步插入方法