doc_ai_backed/frontend-sdk/API_EXAMPLES.md

# 数据埋点 API 调用示例

## 基础信息

- **接口路径**: `/doc_ai/v1/analytics/track`
- **请求方法**: `POST`
- **Content-Type**: `application/json`
- **认证**: 可选（Bearer Token）

## 1. 基础埋点事件（最小参数）

```bash
curl -X POST http://localhost:8080/doc_ai/v1/analytics/track \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 12345,
    "event_name": "button_click"
  }'
```

## 2. 完整埋点事件（包含所有字段）

```bash
curl -X POST http://localhost:8080/doc_ai/v1/analytics/track \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "user_id": 12345,
    "event_name": "formula_recognition_start",
    "properties": {
      "file_name": "math_formula.png",
      "file_size": 102400,
      "file_type": "image/png",
      "upload_method": "drag_drop"
    },
    "device_info": {
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
      "screen_width": 1920,
      "screen_height": 1080,
      "language": "zh-CN",
      "timezone": "Asia/Shanghai",
      "platform": "MacIntel"
    },
    "meta_data": {
      "task_id": "task_123456",
      "timestamp": 1706342400000
    }
  }'
```

## 3. 页面浏览事件

```bash
curl -X POST http://localhost:8080/doc_ai/v1/analytics/track \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 12345,
    "event_name": "page_view",
    "properties": {
      "page_url": "https://example.com/home",
      "page_title": "首页",
      "page_name": "home",
      "referrer": "https://example.com/login"
    },
    "device_info": {
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
      "screen_width": 1920,
      "screen_height": 1080
    }
  }'
```

## 4. 任务相关事件

```bash
curl -X POST http://localhost:8080/doc_ai/v1/analytics/track \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "user_id": 12345,
    "event_name": "task_create",
    "properties": {
      "task_type": "formula_recognition",
      "file_name": "equation.png",
      "file_size": 204800
    },
    "meta_data": {
      "task_id": "task_789012"
    }
  }'
```

## 5. 任务完成事件

```bash
curl -X POST http://localhost:8080/doc_ai/v1/analytics/track \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 12345,
    "event_name": "task_complete",
    "properties": {
      "duration_seconds": 5.2,
      "success": true,
      "result_type": "latex"
    },
    "meta_data": {
      "task_id": "task_789012"
    }
  }'
```

## 6. 表单提交事件

```bash
curl -X POST http://localhost:8080/doc_ai/v1/analytics/track \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 12345,
    "event_name": "form_submit",
    "properties": {
      "form_name": "user_registration",
      "form_fields": ["email", "password", "phone"],
      "success": true,
      "validation_errors": 0
    }
  }'
```

## 7. 文件上传事件

```bash
curl -X POST http://localhost:8080/doc_ai/v1/analytics/track \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 12345,
    "event_name": "file_upload",
    "properties": {
      "file_name": "document.pdf",
      "file_size": 5242880,
      "file_type": "application/pdf",
      "upload_source": "drag_drop",
      "upload_duration_ms": 1200
    }
  }'
```

## 8. 错误追踪事件

```bash
curl -X POST http://localhost:8080/doc_ai/v1/analytics/track \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 12345,
    "event_name": "error_occurred",
    "properties": {
      "error_type": "network_error",
      "error_message": "Failed to fetch data",
      "error_code": "NET_001",
      "page_url": "https://example.com/tasks",
      "user_action": "click_submit_button"
    }
  }'
```

## 9. 使用环境变量（推荐）

```bash
# 设置环境变量
export API_BASE_URL="http://localhost:8080"
export JWT_TOKEN="YOUR_JWT_TOKEN"
export USER_ID=12345

# 调用接口
curl -X POST ${API_BASE_URL}/doc_ai/v1/analytics/track \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${JWT_TOKEN}" \
  -d "{
    \"user_id\": ${USER_ID},
    \"event_name\": \"button_click\",
    \"properties\": {
      \"button_name\": \"submit\",
      \"button_position\": \"bottom\"
    }
  }"
```

## 10. 使用 JSON 文件

创建 `event.json` 文件：
```json
{
  "user_id": 12345,
  "event_name": "custom_event",
  "properties": {
    "action": "click",
    "element": "button",
    "value": "submit"
  },
  "device_info": {
    "user_agent": "Mozilla/5.0",
    "screen_width": 1920,
    "screen_height": 1080
  },
  "meta_data": {
    "task_id": "task_123"
  }
}
```

然后执行：
```bash
curl -X POST http://localhost:8080/doc_ai/v1/analytics/track \
  -H "Content-Type: application/json" \
  -d @event.json
```

## 11. 批量埋点接口

```bash
curl -X POST http://localhost:8080/doc_ai/v1/analytics/track/batch \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "events": [
      {
        "user_id": 12345,
        "event_name": "page_view",
        "properties": {
          "page_name": "home"
        }
      },
      {
        "user_id": 12345,
        "event_name": "button_click",
        "properties": {
          "button_name": "start"
        }
      }
    ]
  }'
```

## 响应示例

### 成功响应
```json
{
  "code": 200,
  "message": "success",
  "data": null
}
```

### 错误响应
```json
{
  "code": 400,
  "message": "invalid request",
  "data": null
}
```

## 注意事项

1. **user_id** 和 **event_name** 是必填字段
2. **properties**、**device_info**、**meta_data** 都是可选字段，类型为 JSON 对象
3. 如果提供了 Authorization header，token 中的 user_id 会被设置到上下文中，但请求体中的 user_id 仍然需要提供
4. 建议在生产环境中始终使用 HTTPS
5. 批量接口最多支持 100 个事件

## 测试命令（本地开发）

```bash
# 最简单的测试
curl -X POST http://localhost:8080/doc_ai/v1/analytics/track \
  -H "Content-Type: application/json" \
  -d '{"user_id": 1, "event_name": "test_event"}'

# 查看响应详情
curl -X POST http://localhost:8080/doc_ai/v1/analytics/track \
  -H "Content-Type: application/json" \
  -d '{"user_id": 1, "event_name": "test_event"}' \
  -v
```