sync & read me

app/api/events/track/readme.md

@@ -0,0 +1,175 @@
+
+# 事件跟踪接口说明
+
+## 概述
+该接口用于跟踪用户交互事件并将数据存储到 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兼容的格式