# 数据分析活动接口说明

## 接口概述
`/api/activities` 端点提供了访问和导出分析事件数据的功能，可用于查询短链接的点击和访问记录。

## 请求方式
- HTTP 方法: **GET**
- URL: `/api/activities`

## 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| slug | string | 否* | 短链接标识符 |
| domain | string | 否* | 短链接域名 |
| format | string | 否 | 响应格式，可选值: `csv`（纯文本显示）；不传则默认返回JSON |
| startTime | string | 否* | 起始时间，ISO格式 |
| endTime | string | 否* | 结束时间，ISO格式 |
| page | number | 否 | 当前页码，默认为1 |
| pageSize | number | 否 | 每页记录数，默认为50 |

_*注：必须提供 (slug和domain) 或 (startTime和endTime) 中的至少一组过滤条件_

## 响应格式

### JSON格式（默认）

```json
{
  "success": true,
  "data": [
    {
      "id": "事件ID",
      "type": "事件类型",
      "time": "事件时间",
      "visitor": {
        "id": "访问者ID",
        "ipAddress": "IP地址",
        "userAgent": "浏览器用户代理",
        "referrer": "来源页面"
      },
      "device": {
        "type": "设备类型",
        "browser": "浏览器",
        "os": "操作系统"
      },
      "location": {
        "country": "国家",
        "city": "城市"
      },
      "link": {
        "id": "链接ID",
        "slug": "短链标识",
        "originalUrl": "原始链接",
        "label": "链接标签",
        "tags": ["标签1", "标签2"]
      },
      "utm": {
        "source": "来源",
        "medium": "媒介",
        "campaign": "活动",
        "term": "关键词",
        "content": "内容"
      }
    }
  ],
  "meta": {
    "total": 总记录数,
    "page": 当前页码,
    "pageSize": 每页记录数
  }
}
```

### CSV格式

当使用 `format=csv` 参数时，接口将返回以下列的CSV纯文本：

```
time,activity,campaign,clientId,originPath
2023-01-01 12:34:56,click,spring_sale,abc123,https://example.com/path?utm_campaign=spring_sale
```

列说明：
- `time`: 事件发生时间
- `activity`: 事件类型（如点击、访问等）
- `campaign`: 营销活动标识（从URL中的utm_campaign提取）
- `clientId`: 访问者标识的前半部分
- `originPath`: 原始请求路径或引荐URL

## 使用示例

### 基本查询（JSON）
```
GET /api/activities?slug=0326recap10&domain=example.com
```

### 导出CSV
```
GET /api/activities?slug=0326recap10&format=csv
```

### 按日期范围过滤
```
GET /api/activities?startTime=2023-03-01T00:00:00Z&endTime=2023-03-31T23:59:59Z
```

### 分页
```
GET /api/activities?slug=0326recap10&page=2&pageSize=100
```

## 错误响应

当请求参数不正确或服务器发生错误时，返回以下格式：

```json
{
  "success": false,
  "error": "错误描述信息"
}
```

常见错误代码：
- 400: 参数错误，例如缺少必要的过滤条件
- 500: 服务器内部错误