a698734df5
- 将“域名筛选”统一更新为“站点筛选”或“多站点管理” - 更新管理后台API文档，明确支持通过siteId参数筛选数据 - 在站点隔离配置文档中新增管理后台API使用说明 - 更新数据统计文档，将按域名分类改为按站点分类 - 修正相关API参数说明，从domain参数改为siteId参数
232 lines
6.5 KiB
Markdown
232 lines
6.5 KiB
Markdown
# 统计数据
|
||
|
||
统计数据接口用于获取评论统计、站点列表等数据看板相关信息。
|
||
|
||
所有接口都需要在请求头中携带 Bearer Token。
|
||
|
||
```http
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
## 1.1 获取评论统计数据（数据看板）
|
||
|
||
```
|
||
GET /admin/stats/comments
|
||
```
|
||
|
||
用于管理后台「数据看板」展示评论整体统计、按站点统计以及最近 30 天评论趋势。
|
||
|
||
- 方法：`GET`
|
||
- 路径：`/admin/stats/comments`
|
||
- 鉴权：需要（Bearer Token）
|
||
|
||
**查询参数**
|
||
|
||
| 名称 | 位置 | 类型 | 必填 | 说明 |
|
||
| -------- | ----- | ------ | ---- | ------------------------------- |
|
||
| `siteId` | query | string | 否 | 按站点 ID 筛选评论数据，如 `blog`、`docs` |
|
||
|
||
说明：
|
||
|
||
- 当提供 `siteId` 参数且不为 `default` 时，仅返回该站点下的评论统计数据
|
||
|
||
**成功响应**
|
||
|
||
- 状态码：`200`
|
||
|
||
```json
|
||
{
|
||
"summary": {
|
||
"total": 123,
|
||
"approved": 100,
|
||
"pending": 20,
|
||
"rejected": 3
|
||
},
|
||
"domains": [
|
||
{
|
||
"domain": "example.com",
|
||
"total": 80,
|
||
"approved": 70,
|
||
"pending": 8,
|
||
"rejected": 2
|
||
},
|
||
{
|
||
"domain": "blog.example.com",
|
||
"total": 30,
|
||
"approved": 20,
|
||
"pending": 9,
|
||
"rejected": 1
|
||
}
|
||
],
|
||
"last7Days": [
|
||
{
|
||
"date": "2026-01-15",
|
||
"total": 10
|
||
},
|
||
{
|
||
"date": "2026-01-16",
|
||
"total": 12
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
| -------------------- | ------------------- | ------------------------------------- |
|
||
| `summary` | object | 评论整体汇总统计 |
|
||
| `summary.total` | number | 评论总数 |
|
||
| `summary.approved` | number | 已通过评论数 |
|
||
| `summary.pending` | number | 待审核评论数 |
|
||
| `summary.rejected` | number | 已拒绝评论数 |
|
||
| `domains` | Array\<DomainStat\> | 按站点聚合的评论统计列表 |
|
||
| `domains[].domain` | string | 站点 ID（如 `blog`、`docs` 或 `default`） |
|
||
| `domains[].total` | number | 该站点下评论总数 |
|
||
| `domains[].approved` | number | 该站点下已通过评论数 |
|
||
| `domains[].pending` | number | 该站点下待审核评论数 |
|
||
| `domains[].rejected` | number | 该站点下已拒绝评论数 |
|
||
| `last7Days` | Array\<DailyStat\> | 最近 30 天的每日评论数（按自然日聚合） |
|
||
| `last7Days[].date` | string (YYYY-MM-DD) | 日期，UTC 时间格式化后的自然日 |
|
||
| `last7Days[].total` | number | 当日评论总数 |
|
||
|
||
**错误响应**
|
||
|
||
- 状态码：`500`
|
||
|
||
```json
|
||
{
|
||
"message": "获取统计数据失败"
|
||
}
|
||
```
|
||
|
||
## 1.2 获取点赞统计数据（点赞排行榜）
|
||
|
||
```
|
||
GET /admin/likes/stats
|
||
```
|
||
|
||
用于管理后台展示按点赞数排序的页面列表，例如「点赞排行榜」。
|
||
|
||
- 方法：`GET`
|
||
- 路径：`/admin/likes/stats`
|
||
- 鉴权：需要（Bearer Token）
|
||
|
||
**查询参数**
|
||
|
||
| 名称 | 位置 | 类型 | 必填 | 说明 |
|
||
| -------- | ----- | ------ | ---- | ------------------------------- |
|
||
| `siteId` | query | string | 否 | 按站点 ID 筛选点赞数据，如 `blog`、`docs` |
|
||
|
||
说明：
|
||
|
||
- 当提供 `siteId` 参数且不为 `default` 时，仅返回该站点下的点赞统计数据
|
||
- 默认返回点赞数最多的前 50 条记录
|
||
|
||
**成功响应**
|
||
|
||
- 状态码：`200`
|
||
|
||
```json
|
||
{
|
||
"items": [
|
||
{
|
||
"pageSlug": "https://example.com/blog/hello-world",
|
||
"pageTitle": "Hello World",
|
||
"pageUrl": "https://example.com/blog/hello-world",
|
||
"likes": 12
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
| ------------ | ------ | ---------------------------- |
|
||
| `pageSlug` | string | 页面唯一标识符 |
|
||
| `pageTitle` | string \| null | 页面标题 |
|
||
| `pageUrl` | string \| null | 页面 URL |
|
||
| `likes` | number | 当前页面累计点赞数 |
|
||
|
||
**错误响应**
|
||
|
||
- 状态码：`500`
|
||
|
||
```json
|
||
{
|
||
"message": "获取点赞统计失败"
|
||
}
|
||
```
|
||
|
||
## 1.4 获取点赞记录列表
|
||
|
||
```
|
||
GET /admin/likes/list
|
||
```
|
||
|
||
用于管理后台查看单条点赞记录列表，支持按页面、用户以及时间范围筛选。
|
||
|
||
- 方法：`GET`
|
||
- 路径：`/admin/likes/list`
|
||
- 鉴权：需要（Bearer Token）
|
||
|
||
**查询参数**
|
||
|
||
| 名称 | 位置 | 类型 | 必填 | 说明 |
|
||
| ----------- | ----- | ------- | ---- | --------------------------------------------------- |
|
||
| `page` | query | integer | 否 | 页码，默认 `1` |
|
||
| `page_slug` | query | string | 否 | 按页面标识筛选点赞记录 |
|
||
| `user_id` | query | string | 否 | 按用户标识筛选点赞记录，对应前端的 `X-CWD-Like-User` |
|
||
| `start` | query | number | 否 | 起始时间（毫秒时间戳），大于等于该时间的记录 |
|
||
| `end` | query | number | 否 | 结束时间（毫秒时间戳），小于等于该时间的记录 |
|
||
|
||
说明：
|
||
|
||
- 当前实现中每页固定大小为 `20`；
|
||
- 既可以使用 `page_slug` / `user_id`，也可以同时使用两者进行组合筛选。
|
||
|
||
**成功响应**
|
||
|
||
- 状态码：`200`
|
||
|
||
```json
|
||
{
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"pageSlug": "https://example.com/blog/hello-world",
|
||
"userId": "550e8400-e29b-41d4-a716-446655440000",
|
||
"createdAt": 1737593600000
|
||
}
|
||
],
|
||
"pagination": {
|
||
"page": 1,
|
||
"limit": 20,
|
||
"total": 3
|
||
}
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
| -------------------- | ------ | ---------------------------- |
|
||
| `data[].id` | number | 点赞记录 ID |
|
||
| `data[].pageSlug` | string | 页面唯一标识符 |
|
||
| `data[].userId` | string | 用户标识（来自 `X-CWD-Like-User` 或 IP） |
|
||
| `data[].createdAt` | number | 点赞时间戳（毫秒） |
|
||
| `pagination.page` | number | 当前页码 |
|
||
| `pagination.limit` | number | 每页数量（固定为 20） |
|
||
| `pagination.total` | number | 总页数 |
|
||
|
||
**错误响应**
|
||
|
||
- 状态码：`500`
|
||
|
||
```json
|
||
{
|
||
"message": "获取点赞记录失败"
|
||
}
|
||
```
|