# 事件跟踪接口说明

## 概述
该接口用于跟踪用户交互事件并将数据存储到 ClickHouse 数据库中。支持记录各种类型的事件，并可包含与链接、用户、团队、项目等相关的详细信息。

## 接口信息
- **URL**: `/api/events/track`
- **方法**: `POST`
- **Content-Type**: `application/json`

## 请求参数

### 必填字段
| 参数 | 类型 | 描述 |
|------|------|------|
| `event_type` | string | 事件类型，如 'click', 'view', 'conversion' |

### 核心事件字段
| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `event_id` | string | 否 | 事件唯一标识符，不提供时自动生成UUID |
| `event_time` | string/Date | 否 | 事件发生时间，格式为ISO日期字符串，默认为当前时间 |
| `event_attributes` | object/string | 否 | 事件相关的其他属性，可以是JSON对象或JSON字符串 |

### 链接信息
| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `link_id` | string | 否 | 短链接的唯一ID |
| `link_slug` | string | 否 | 短链接的slug部分 |
| `link_label` | string | 否 | 短链接的显示名称 |
| `link_title` | string | 否 | 短链接的标题 |
| `link_original_url` | string | 否 | 原始目标URL |
| `link_attributes` | object/string | 否 | 链接相关的额外属性 |
| `link_created_at` | string/Date | 否 | 链接创建时间 |
| `link_expires_at` | string/Date | 否 | 链接过期时间 |
| `link_tags` | array/string | 否 | 链接标签，可以是数组或JSON字符串 |

### 用户信息
| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `user_id` | string | 否 | 用户ID |
| `user_name` | string | 否 | 用户名称 |
| `user_email` | string | 否 | 用户邮箱 |
| `user_attributes` | object/string | 否 | 用户相关的其他属性 |

### 团队和项目信息
| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `team_id` | string | 否 | 团队ID |
| `team_name` | string | 否 | 团队名称 |
| `team_attributes` | object/string | 否 | 团队相关的其他属性 |
| `project_id` | string | 否 | 项目ID |
| `project_name` | string | 否 | 项目名称 |
| `project_attributes` | object/string | 否 | 项目相关的其他属性 |

### 二维码信息
| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `qr_code_id` | string | 否 | 二维码ID |
| `qr_code_name` | string | 否 | 二维码名称 |
| `qr_code_attributes` | object/string | 否 | 二维码相关的其他属性 |

### 访问者信息
| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `visitor_id` | string | 否 | 访问者唯一标识符，不提供时自动生成 |
| `session_id` | string | 否 | 会话ID，不提供时自动生成 |
| `ip_address` | string | 否 | 访问者IP地址，默认从请求头获取 |
| `country` | string | 否 | 访问者所在国家 |
| `city` | string | 否 | 访问者所在城市 |
| `device_type` | string | 否 | 设备类型 (如 desktop, mobile, tablet) |
| `browser` | string | 否 | 浏览器名称 |
| `os` | string | 否 | 操作系统 |
| `user_agent` | string | 否 | 用户代理字符串，默认从请求头获取 |

### 引荐来源信息
| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `referrer` | string | 否 | 引荐URL，默认从请求头获取 |
| `utm_source` | string | 否 | UTM来源参数 |
| `utm_medium` | string | 否 | UTM媒介参数 |
| `utm_campaign` | string | 否 | UTM活动参数 |
| `utm_term` | string | 否 | UTM术语参数 |
| `utm_content` | string | 否 | UTM内容参数 |

### 交互信息
| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `time_spent_sec` | number | 否 | 用户在页面上停留的时间（秒），默认0 |
| `is_bounce` | boolean | 否 | 是否是跳出（只访问一个页面），默认true |
| `is_qr_scan` | boolean | 否 | 是否来自二维码扫描，默认false |
| `conversion_type` | string | 否 | 转化类型 |
| `conversion_value` | number | 否 | 转化价值，默认0 |

## 响应格式

### 成功响应 (201 Created)
```json
{
  "success": true,
  "message": "Event tracked successfully",
  "event_id": "uuid-of-tracked-event"
}
```

### 错误响应

#### 缺少必填字段 (400 Bad Request)
```json
{
  "error": "Missing required field: event_type"
}
```

#### 服务器错误 (500 Internal Server Error)
```json
{
  "error": "Failed to track event",
  "details": "具体错误信息"
}
```

## 使用示例

### 基本事件跟踪请求
```javascript
fetch('/api/events/track', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    event_type: 'click',
    link_id: 'abc123',
    link_slug: 'promo-summer',
    link_original_url: 'https://example.com/summer-promotion'
  })
})
```

### 详细事件跟踪请求
```javascript
fetch('/api/events/track', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    event_type: 'conversion',
    link_id: 'abc123',
    link_slug: 'promo-summer',
    link_original_url: 'https://example.com/summer-promotion',
    event_attributes: {
      page: '/checkout',
      product_id: 'xyz789'
    },
    user_id: 'user123',
    team_id: 'team456',
    project_id: 'proj789',
    visitor_id: 'vis987',
    is_bounce: false,
    time_spent_sec: 120,
    conversion_type: 'purchase',
    conversion_value: 99.99,
    utm_source: 'email',
    utm_campaign: 'summer_sale'
  })
})
```

## 注意事项
- 所有对象类型的字段（如 `event_attributes`）可以作为对象或预先格式化的JSON字符串传递
- 如果不提供 `event_id`、`visitor_id` 或 `session_id`，系统将自动生成
- 时间戳字段接受ISO格式的日期字符串，并会被转换为ClickHouse兼容的格式