feat(analytics): 添加访问统计功能
实现页面访问统计功能，包括： 1. 前端组件挂载时上报访问数据 2. 后端接口记录访问信息并存储 3. 管理后台新增访问统计视图 4. 相关API文档和设计说明更新
This commit is contained in:
anghunk
@@ -1,16 +1,18 @@
|
||||
# 公开 API
|
||||
|
||||
无需认证即可访问的公开接口，包括评论获取、评论提交以及评论设置获取。
|
||||
无需认证即可访问的公开接口，包括评论获取、评论提交、配置获取和身份验证。
|
||||
|
||||
包含路径、方法、参数、请求体和响应示例。
|
||||
|
||||
## 获取指定文章的评论列表
|
||||
## 1. 评论相关
|
||||
|
||||
### 1.1 获取指定文章的评论列表
|
||||
|
||||
```
|
||||
GET /api/comments
|
||||
```
|
||||
|
||||
获取指定文章的评论列表。
|
||||
获取指定文章的评论列表，支持分页和嵌套结构。
|
||||
|
||||
- 方法：`GET`
|
||||
- 路径：`/api/comments`
|
||||
@@ -42,6 +44,7 @@ GET /api/comments
|
||||
"pubDate": "2026-01-13T10:00:00Z",
|
||||
"postSlug": "/blog/hello-world",
|
||||
"avatar": "https://gravatar.com/avatar/...",
|
||||
"priority": 2,
|
||||
"replies": [
|
||||
{
|
||||
"id": 2,
|
||||
@@ -54,7 +57,8 @@ GET /api/comments
|
||||
"postSlug": "/blog/hello-world",
|
||||
"avatar": "https://gravatar.com/avatar/...",
|
||||
"parentId": 1,
|
||||
"replyToAuthor": "张三"
|
||||
"replyToAuthor": "张三",
|
||||
"priority": 1
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -70,8 +74,9 @@ GET /api/comments
|
||||
|
||||
说明：
|
||||
|
||||
- 当 `nested=true`（默认）时，接口返回的是“根评论列表”，每条根评论包含其 `replies`。
|
||||
- 当 `nested=true`（默认）时，接口返回的是"根评论列表"，每条根评论包含其 `replies`。
|
||||
- 当 `nested=false` 时，接口返回扁平列表，所有评论都在 `data` 中，`replies` 为空。
|
||||
- `priority` 字段：评论的置顶权重，数值越大排序越靠前。
|
||||
|
||||
**错误响应**
|
||||
|
||||
@@ -95,7 +100,7 @@ GET /api/comments
|
||||
}
|
||||
```
|
||||
|
||||
## 提交新评论或回复
|
||||
### 1.2 提交新评论或回复
|
||||
|
||||
```
|
||||
POST /api/comments
|
||||
@@ -124,11 +129,12 @@ POST /api/comments
|
||||
"email": "zhangsan@example.com",
|
||||
"url": "https://zhangsan.me",
|
||||
"content": "很棒的文章！",
|
||||
"parent_id": 1
|
||||
"parent_id": 1,
|
||||
"adminToken": "your-admin-key"
|
||||
}
|
||||
```
|
||||
|
||||
**字段说明**
|
||||
字段说明：
|
||||
|
||||
| 字段名 | 类型 | 必填 | 说明 |
|
||||
| ------------ | ------ | ---- | ------------------------------------------------------------------------------------------------------------- |
|
||||
@@ -140,20 +146,31 @@ POST /api/comments
|
||||
| `url` | string | 否 | 评论者个人主页或站点地址 |
|
||||
| `content` | string | 是 | 评论内容，内部会过滤 `<script>...</script>` 片段 |
|
||||
| `parent_id` | number | 否 | 父评论 ID，用于回复功能；缺省或 `null` 表示根评论 |
|
||||
| `adminToken` | string | 否 | 管理员评论密钥，博主发布评论时需要先通过 `/api/verify-admin` 验证密钥后将密钥传入此字段，评论将直接通过且不受审核设置影响 |
|
||||
|
||||
**成功响应**
|
||||
|
||||
- 状态码：`200`
|
||||
|
||||
评论直接通过时：
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Comment submitted. Awaiting moderation."
|
||||
"message": "评论已提交",
|
||||
"status": "approved"
|
||||
}
|
||||
```
|
||||
|
||||
当前实现中评论会直接以 `approved` 状态写入数据库，后续如引入人工审核可在实现中调整为“待审核”状态。
|
||||
评论进入待审核状态时（开启"先审核再显示"且非管理员评论）：
|
||||
|
||||
**错误响应**与限流
|
||||
```json
|
||||
{
|
||||
"message": "已提交评论，待管理员审核后显示",
|
||||
"status": "pending"
|
||||
}
|
||||
```
|
||||
|
||||
**错误响应**
|
||||
|
||||
- 请求体缺失或字段类型错误：
|
||||
|
||||
@@ -165,7 +182,7 @@ POST /api/comments
|
||||
}
|
||||
```
|
||||
|
||||
- 缺少必填字段示例：
|
||||
- 缺少必填字段：
|
||||
|
||||
- `post_slug` 为空：
|
||||
|
||||
@@ -207,6 +224,56 @@ POST /api/comments
|
||||
}
|
||||
```
|
||||
|
||||
- IP 或邮箱被限制：
|
||||
|
||||
- IP 被限制：
|
||||
- 状态码：`403`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "当前 IP 已被限制评论，请联系站长进行处理"
|
||||
}
|
||||
```
|
||||
|
||||
- 邮箱被限制：
|
||||
- 状态码：`403`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "当前邮箱已被限制评论，请联系站长进行处理"
|
||||
}
|
||||
```
|
||||
|
||||
- 管理员评论验证失败：
|
||||
|
||||
- 未输入密钥：
|
||||
- 状态码：`401`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "请输入管理员密钥",
|
||||
"requireAuth": true
|
||||
}
|
||||
```
|
||||
|
||||
- 密钥错误：
|
||||
- 状态码：`401`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "密钥错误"
|
||||
}
|
||||
```
|
||||
|
||||
- 验证失败次数过多：
|
||||
- 状态码：`403`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "验证失败次数过多，请30分钟后再试"
|
||||
}
|
||||
```
|
||||
|
||||
- 评论频率限制：
|
||||
|
||||
- 状态码：`429`
|
||||
@@ -214,7 +281,7 @@ POST /api/comments
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "评论频繁，等 10s 后再试"
|
||||
"message": "评论频繁，等10s后再试"
|
||||
}
|
||||
```
|
||||
|
||||
@@ -228,7 +295,9 @@ POST /api/comments
|
||||
}
|
||||
```
|
||||
|
||||
## 获取评论相关的公开配置
|
||||
## 2. 配置相关
|
||||
|
||||
### 2.1 获取评论相关的公开配置
|
||||
|
||||
```
|
||||
GET /api/config/comments
|
||||
@@ -248,7 +317,7 @@ GET /api/config/comments
|
||||
{
|
||||
"adminEmail": "admin@example.com",
|
||||
"adminBadge": "博主",
|
||||
"avatarPrefix": "https://gravatar.com/avatar",
|
||||
"avatar": "https://gravatar.com/avatar",
|
||||
"adminEnabled": true,
|
||||
"allowedDomains": [],
|
||||
"requireReview": false
|
||||
@@ -259,7 +328,7 @@ GET /api/config/comments
|
||||
|
||||
| 字段名 | 类型 | 说明 |
|
||||
| -------------- | ------- | -------------------------------------------------------------------- |
|
||||
| `adminEmail` | string | 博主邮箱地址，用于在前端展示“博主”标识，并触发管理员身份验证流程 |
|
||||
| `adminEmail` | string | 博主邮箱地址，用于在前端展示"博主"标识，并触发管理员身份验证流程 |
|
||||
| `adminBadge` | string | 博主标识文字，例如 `"博主"` |
|
||||
| `avatarPrefix` | string | 头像地址前缀，如 Gravatar 或 Cravatar 镜像地址 |
|
||||
| `adminEnabled` | boolean | 是否启用博主标识相关展示（关闭时不显示徽标，但仍可作为管理员邮箱） |
|
||||
@@ -275,3 +344,80 @@ GET /api/config/comments
|
||||
"message": "加载评论配置失败"
|
||||
}
|
||||
```
|
||||
|
||||
## 3. 身份验证相关
|
||||
|
||||
### 3.1 验证管理员密钥
|
||||
|
||||
```
|
||||
POST /api/verify-admin
|
||||
```
|
||||
|
||||
验证前台管理员评论所需的密钥，用于博主发布评论时的身份验证。
|
||||
|
||||
- 方法：`POST`
|
||||
- 路径：`/api/verify-admin`
|
||||
- 鉴权：不需要
|
||||
|
||||
**请求头**
|
||||
|
||||
| 名称 | 必填 | 示例 |
|
||||
| -------------- | ---- | ------------------ |
|
||||
| `Content-Type` | 是 | `application/json` |
|
||||
|
||||
**请求体**
|
||||
|
||||
```json
|
||||
{
|
||||
"adminToken": "your-admin-key"
|
||||
}
|
||||
```
|
||||
|
||||
字段说明：
|
||||
|
||||
| 字段名 | 类型 | 必填 | 说明 |
|
||||
| ----------- | ------ | ---- | -------------- |
|
||||
| `adminToken` | string | 是 | 管理员评论密钥 |
|
||||
|
||||
**风控说明**
|
||||
|
||||
- 同一 IP 连续验证失败 3 次后，该 IP 将被锁定 30 分钟
|
||||
- 失败次数记录有效期为 1 小时
|
||||
|
||||
**成功响应**
|
||||
|
||||
- 状态码：`200`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "验证通过"
|
||||
}
|
||||
```
|
||||
|
||||
或未设置密钥时：
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "未设置管理员密钥"
|
||||
}
|
||||
```
|
||||
|
||||
**错误响应**
|
||||
|
||||
- 寽钥错误：
|
||||
- 状态码：`401`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "密钥错误"
|
||||
}
|
||||
```
|
||||
|
||||
- 验证失败次数过多：
|
||||
- 状态码：`403`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "验证失败次数过多，请30分钟后再试"
|
||||
}
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user