489d30e084
- 将主项目及各子模块的版本号从0.0.18更新至0.1.1-beta - 在API文档中将查询参数`domain`统一替换为`siteId`以明确筛选依据 - 为评论统计和点赞统计接口添加`siteId`筛选参数说明
172 lines
5.3 KiB
Markdown
172 lines
5.3 KiB
Markdown
# 访问统计
|
||
|
||
访问统计接口用于获取页面访问数据、浏览趋势等信息。
|
||
|
||
所有接口都需要在请求头中携带 Bearer Token。
|
||
|
||
```http
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
## 1.1 获取访问统计概览
|
||
|
||
```
|
||
GET /admin/analytics/overview
|
||
```
|
||
|
||
用于管理后台「访问统计」页面展示整体访问数据，包括总 PV、总页面数、今日/昨日/本周/上周/本月/上月访问量以及最近 30 天的访问趋势。
|
||
|
||
- 方法：`GET`
|
||
- 路径：`/admin/analytics/overview`
|
||
- 鉴权：需要（Bearer Token）
|
||
|
||
**查询参数**
|
||
|
||
| 名称 | 位置 | 类型 | 必填 | 说明 |
|
||
| -------- | ----- | ------ | ---- | ------------------------------------------ |
|
||
| `siteId` | query | string | 否 | 按站点 ID 筛选访问数据，如 `blog`、`docs` |
|
||
|
||
**成功响应**
|
||
|
||
- 状态码：`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）
|
||
|
||
**查询参数**
|
||
|
||
| 名称 | 位置 | 类型 | 必填 | 说明 |
|
||
| -------- | ----- | ------ | ---- | ------------------------------------------ |
|
||
| `siteId` | query | string | 否 | 按站点 ID 筛选访问数据，如 `blog`、`docs` |
|
||
| `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": "获取页面访问统计失败"
|
||
}
|
||
```
|