0b28c9fa4c
- 重构API文档侧边栏，将公开API拆分为子分类（评论、点赞、配置、身份验证、访问统计） - 新增详细的公开API接口文档，包括评论管理、点赞功能、配置获取、身份验证和访问统计 - 完善数据统计功能文档，增加概览数据、访问明细和数据分析说明 - 更新功能设置文档，补充图片预览和个性化设置说明 - 修正管理员登录文档中的错误描述和格式问题
158 lines
4.7 KiB
Markdown
158 lines
4.7 KiB
Markdown
# 访问统计
|
||
|
||
访问统计接口用于获取页面访问数据、浏览趋势等信息。
|
||
|
||
所有接口都需要在请求头中携带 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
|
||
},
|
||
{
|
||
"postSlug": "https://example.com/about",
|
||
"postTitle": "关于我",
|
||
"postUrl": "https://example.com/about",
|
||
"pv": 50,
|
||
"lastVisitAt": 1737593500000
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
| ------------- | ------ | -------------------------- |
|
||
| `postSlug` | string | 文章唯一标识符 |
|
||
| `postTitle` | string \| null | 文章标题 |
|
||
| `postUrl` | string \| null | 文章 URL |
|
||
| `pv` | number | 访问量（PV） |
|
||
| `lastVisitAt` | number \| null | 最后访问时间戳（毫秒） |
|
||
|
||
**错误响应**
|
||
|
||
- 状态码：`500`
|
||
|
||
```json
|
||
{
|
||
"message": "获取页面访问统计失败"
|
||
}
|
||
```
|