# 访问统计

访问统计接口用于获取页面访问数据、浏览趋势等信息。

所有接口都需要在请求头中携带 Bearer Token。

```http
Authorization: Bearer <token>
```

## 1.1 获取访问统计概览

```
GET /admin/analytics/overview
```

用于管理后台「访问统计」页面展示整体访问数据，包括总 PV、总页面数、今日/昨日/本周/上周/本月/上月访问量以及最近 30 天的访问趋势。

- 方法：`GET`
- 路径：`/admin/analytics/overview`
- 鉴权：需要（Bearer Token）

**查询参数**

| 名称     | 位置  | 类型   | 必填 | 说明                                       |
| -------- | ----- | ------ | ---- | ------------------------------------------ |
| `domain` | query | string | 否   | 按域名筛选访问数据，传入域名，如 `example.com` |

**成功响应**

- 状态码：`200`

```json
{
  "totalPv": 1000,
  "totalPages": 50,
  "todayPv": 100,
  "yesterdayPv": 80,
  "weekPv": 500,
  "lastWeekPv": 400,
  "monthPv": 800,
  "lastMonthPv": 650,
  "last30Days": [
    {
      "date": "2026-01-15",
      "total": 20
    },
    {
      "date": "2026-01-16",
      "total": 25
    }
  ]
}
```

字段说明：

| 字段名         | 类型                | 说明                                  |
| -------------- | ------------------- | ------------------------------------- |
| `totalPv`      | number              | 总访问量（PV）                        |
| `totalPages`   | number              | 总页面数                              |
| `todayPv`      | number              | 今日访问量                            |
| `yesterdayPv`  | number              | 昨日访问量                            |
| `weekPv`       | number              | 本周访问量                            |
| `lastWeekPv`   | number              | 上周访问量（用于同比对比）              |
| `monthPv`      | number              | 本月访问量                            |
| `lastMonthPv`  | number              | 上月访问量（用于同比对比）              |
| `last30Days`   | Array\<DailyStat\>  | 最近 30 天的每日访问数（按自然日聚合） |
| `last30Days[].date`   | string (YYYY-MM-DD) | 日期，UTC 时间格式化后的自然日        |
| `last30Days[].total`  | number              | 当日访问总数                          |

**说明**：

- `weekPv`：本周（从周一到当天）的总访问量
- `lastWeekPv`：上周（上周一到上周日）的总访问量，用于与本周进行同比对比
- `monthPv`：本月（从本月1号到当天）的总访问量
- `lastMonthPv`：上月（上月1号到上月最后一天）的总访问量，用于与本月进行进行同比对比

**错误响应**

- 状态码：`500`

```json
{
  "message": "获取访问统计概览失败"
}
```

## 1.2 获取页面访问统计

```
GET /admin/analytics/pages
```

用于管理后台「访问统计」页面展示各个页面的访问明细，支持按 PV 排序或最新访问排序。

- 方法：`GET`
- 路径：`/admin/analytics/pages`
- 鉴权：需要（Bearer Token）

**查询参数**

| 名称     | 位置  | 类型   | 必填 | 说明                                       |
| -------- | ----- | ------ | ---- | ------------------------------------------ |
| `domain` | query | string | 否   | 按域名筛选访问数据，传入域名，如 `example.com` |
| `order`  | query | string | 否   | 排序方式，`pv`（按访问量排序，默认）或 `latest`（最新访问） |

说明：

- 当前实现中固定返回前 20 条数据
- `order=pv`：按访问量降序排序，访问量相同时按最后访问时间降序排序
- `order=latest`：按最后访问时间降序排序，访问时间相同时按访问量降序排序

**成功响应**

- 状态码：`200`

```json
{
  "items": [
    {
      "postSlug": "https://example.com/blog/hello-world",
      "postTitle": "Hello World",
      "postUrl": "https://example.com/blog/hello-world",
      "pv": 100,
      "lastVisitAt": 1737593600000
    }
  ],
  "itemsByPv": [
    {
      "postSlug": "https://example.com/blog/hello-world",
      "postTitle": "Hello World",
      "postUrl": "https://example.com/blog/hello-world",
      "pv": 100,
      "lastVisitAt": 1737593600000
    }
  ],
  "itemsByLatest": [
    {
      "postSlug": "https://example.com/blog/hello-world",
      "postTitle": "Hello World",
      "postUrl": "https://example.com/blog/hello-world",
      "pv": 100,
      "lastVisitAt": 1737593600000
    }
  ]
}
```

字段说明：

| 字段名              | 类型   | 说明                                      |
| ------------------- | ------ | ----------------------------------------- |
| `items`             | Array  | 根据 `order` 参数返回的主列表            |
| `itemsByPv`         | Array  | 按 `order=pv` 规则排序后的前 20 条数据   |
| `itemsByLatest`     | Array  | 按 `order=latest` 规则排序后的前 20 条数据 |
| `postSlug`          | string | 文章唯一标识符                           |
| `postTitle`         | string \| null | 文章标题                    |
| `postUrl`           | string \| null | 文章 URL                   |
| `pv`                | number | 访问量（PV）                             |
| `lastVisitAt`       | number \| null | 最后访问时间戳（毫秒）      |

**错误响应**

- 状态码：`500`

```json
{
  "message": "获取页面访问统计失败"
}
```