docs: 更新API文档结构并完善功能说明
- 重构API文档侧边栏，将公开API拆分为子分类（评论、点赞、配置、身份验证、访问统计） - 新增详细的公开API接口文档，包括评论管理、点赞功能、配置获取、身份验证和访问统计 - 完善数据统计功能文档，增加概览数据、访问明细和数据分析说明 - 更新功能设置文档，补充图片预览和个性化设置说明 - 修正管理员登录文档中的错误描述和格式问题
This commit is contained in:
anghunk
@@ -28,7 +28,16 @@ export const apiSidebar = [
|
||||
text: 'API 文档',
|
||||
items: [
|
||||
{ text: '概览', link: '/api/overview' },
|
||||
{ text: '公开 API', link: '/api/public' },
|
||||
{
|
||||
text: '公开 API',
|
||||
items: [
|
||||
{ text: '评论接口', link: '/api/public/comments' },
|
||||
{ text: '点赞接口', link: '/api/public/like' },
|
||||
{ text: '配置接口', link: '/api/public/config' },
|
||||
{ text: '身份验证', link: '/api/public/auth' },
|
||||
{ text: '访问统计', link: '/api/public/analytics' },
|
||||
],
|
||||
},
|
||||
{
|
||||
text: '管理员 API',
|
||||
items: [
|
||||
@@ -41,7 +50,7 @@ export const apiSidebar = [
|
||||
{ text: 'Telegram 通知', link: '/api/admin/telegram-notify' },
|
||||
{ text: '统计数据', link: '/api/admin/stats' },
|
||||
{ text: '访问统计', link: '/api/admin/analytics' },
|
||||
{ text: '点赞开关', link: '/api/admin/feature-settings' },
|
||||
{ text: '功能设置', link: '/api/admin/feature-settings' },
|
||||
],
|
||||
},
|
||||
],
|
||||
|
||||
@@ -14,7 +14,7 @@ Authorization: Bearer <token>
|
||||
GET /admin/analytics/overview
|
||||
```
|
||||
|
||||
用于管理后台「访问统计」页面展示整体访问数据，包括总 PV、总页面数以及最近 30 天的访问趋势。
|
||||
用于管理后台「访问统计」页面展示整体访问数据，包括总 PV、总页面数、今日/昨日/本周/上周/本月/上月访问量以及最近 30 天的访问趋势。
|
||||
|
||||
- 方法：`GET`
|
||||
- 路径：`/admin/analytics/overview`
|
||||
@@ -34,6 +34,12 @@ GET /admin/analytics/overview
|
||||
{
|
||||
"totalPv": 1000,
|
||||
"totalPages": 50,
|
||||
"todayPv": 100,
|
||||
"yesterdayPv": 80,
|
||||
"weekPv": 500,
|
||||
"lastWeekPv": 400,
|
||||
"monthPv": 800,
|
||||
"lastMonthPv": 650,
|
||||
"last30Days": [
|
||||
{
|
||||
"date": "2026-01-15",
|
||||
@@ -53,10 +59,23 @@ GET /admin/analytics/overview
|
||||
| -------------- | ------------------- | ------------------------------------- |
|
||||
| `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`
|
||||
|
||||
@@ -69,7 +69,7 @@ POST /admin/login
|
||||
|
||||
| 参数 | 值 | 说明 |
|
||||
|------|-----|------|
|
||||
| 最大失败次数 | 5 次 | 超过次数后封禁 IP |
|
||||
| 最大失败次数 | 5.次 | 超过次数后封禁 IP |
|
||||
| 封禁时间 | 30 分钟 | IP 被封禁后需等待此时间 |
|
||||
| 计数有效期 | 10 分钟 | 失败计数在此时间后自动重置 |
|
||||
|
||||
@@ -80,7 +80,7 @@ POST /admin/login
|
||||
4. 登录成功后会清除失败计数
|
||||
5. 所有状态存储在 Cloudflare KV 中，基于 IP 地址区分
|
||||
|
||||
- 登录失败（用户名或密码错误）：
|
||||
- 登录失败（用户名或密码无效）：
|
||||
- 状态码：`401`
|
||||
|
||||
```json
|
||||
@@ -92,7 +92,7 @@ POST /admin/login
|
||||
|
||||
`failedAttempts` 字段表示当前失败次数（1-4），前端可用于提示用户剩余尝试次数。
|
||||
|
||||
- 登录失败次数过多导致 IP 被封禁：
|
||||
- IP 已被封禁：
|
||||
- 状态码：`403`
|
||||
|
||||
```json
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# 功能设置相关
|
||||
|
||||
管理点赞功能开关的接口。
|
||||
管理各项功能开关的接口，包括点赞功能、图片灯箱预览、评论占位符、域名可见性等。
|
||||
|
||||
## 获取功能设置
|
||||
|
||||
@@ -21,16 +21,22 @@ GET /admin/settings/feature
|
||||
```json
|
||||
{
|
||||
"enableCommentLike": true,
|
||||
"enableArticleLike": true
|
||||
"enableArticleLike": true,
|
||||
"enableImageLightbox": true,
|
||||
"commentPlaceholder": "发表你的看法...",
|
||||
"visibleDomains": ["example.com", "blog.example.com"]
|
||||
}
|
||||
```
|
||||
|
||||
字段说明：
|
||||
|
||||
| 字段名 | 类型 | 说明 |
|
||||
| ------------------ | ------- | ---------------------- |
|
||||
| `enableCommentLike` | boolean | 是否启用评论点赞功能 |
|
||||
| `enableArticleLike` | boolean | 是否启用文章点赞功能 |
|
||||
| 字段名 | 类型 | 说明 |
|
||||
| -------------------- | ------ | ---------------------- |
|
||||
| `enableCommentLike` | boolean | 是否启用评论点赞功能 |
|
||||
| `enableArticleLike` | boolean | 是否启用文章点赞功能 |
|
||||
| `enableImageLightbox` | boolean | 是否启用评论图片灯箱预览功能 |
|
||||
| `commentPlaceholder` | string \| null | 评论输入框的占位符文本 |
|
||||
| `visibleDomains` | string[] | 允许显示评论组件的域名列表 |
|
||||
|
||||
## 更新功能设置
|
||||
|
||||
@@ -56,16 +62,28 @@ PUT /admin/settings/feature
|
||||
```json
|
||||
{
|
||||
"enableCommentLike": true,
|
||||
"enableArticleLike": true
|
||||
"enableArticleLike": true,
|
||||
"enableImageLightbox": true,
|
||||
"commentPlaceholder": "发表你的看法...",
|
||||
"visibleDomains": ["example.com", "blog.example.com"]
|
||||
}
|
||||
```
|
||||
|
||||
字段说明：
|
||||
|
||||
| 字段名 | 类型 | 必填 | 说明 |
|
||||
| ------------------ | ------- | ---- | ---------------------- |
|
||||
| `enableCommentLike` | boolean | 否 | 是否启用评论点赞功能 |
|
||||
| `enableArticleLike` | boolean | 否 | 是否启用文章点赞功能 |
|
||||
| 字段名 | 类型 | 必填 | 说明 |
|
||||
| -------------------- | ------- | ---- | ---------------------- |
|
||||
| `enableCommentLike` | boolean | 否 | 是否启用评论点赞功能 |
|
||||
| `enableArticleLike` | boolean | 否 | 是否启用文章点赞功能 |
|
||||
| `enableImageLightbox` | boolean | 否 | 是否启用评论图片灯箱预览功能 |
|
||||
| `commentPlaceholder` | string | 否 | 评论输入框的占位符文本 |
|
||||
| `visibleDomains` | string[] | 否 | 允许显示评论组件的域名列表 |
|
||||
|
||||
**说明**：
|
||||
|
||||
- `enableImageLightbox`：启用后，评论内容中的图片可以点击放大预览
|
||||
- `commentPlaceholder`：自定义评论输入框的占位符文本，留空则使用默认文本
|
||||
- `visibleDomains`：设置后，只有在此列表中的域名可以正常显示评论组件，其他域名将被隐藏。留空或为 `null` 表示不限制域名。
|
||||
|
||||
**成功响应**
|
||||
|
||||
|
||||
@@ -585,22 +585,28 @@ GET /api/config/comments
|
||||
"avatar": "https://gravatar.com/avatar",
|
||||
"adminEnabled": true,
|
||||
"allowedDomains": [],
|
||||
"requireReview": false
|
||||
"requireReview": false,
|
||||
"enableCommentLike": true,
|
||||
"enableArticleLike": true,
|
||||
"enableImageLightbox": true,
|
||||
"commentPlaceholder": "发表你的看法..."
|
||||
}
|
||||
```
|
||||
|
||||
字段说明：
|
||||
|
||||
| 字段名 | 类型 | 说明 |
|
||||
| ------------------ | ------- | -------------------------------------------------------------------- |
|
||||
| `adminEmail` | string | 博主邮箱地址，用于在前端展示"博主"标识，并触发管理员身份验证流程 |
|
||||
| `adminBadge` | string | 博主标识文字，例如 `"博主"` |
|
||||
| `avatarPrefix` | string | 头像地址前缀，如 Gravatar 或 Cravatar 镜像地址 |
|
||||
| `adminEnabled` | boolean | 是否启用博主标识相关展示（关闭时不显示徽标，但仍可作为管理员邮箱） |
|
||||
| `allowedDomains` | Array\<string\> | 允许调用组件的域名列表，留空则不限制 |
|
||||
| `requireReview` | boolean | 是否开启新评论先审核再显示（true 表示新评论默认为待审核） |
|
||||
| `enableCommentLike` | boolean | 是否启用评论点赞功能（默认 true） |
|
||||
| `enableArticleLike` | boolean | 是否启用文章点赞功能（默认 true） |
|
||||
| 字段名 | 类型 | 说明 |
|
||||
| -------------------- | ------ | -------------------------------------------------------------------- |
|
||||
| `adminEmail` | string | 博主邮箱地址，用于在前端展示"博主"标识，并触发管理员身份验证流程 |
|
||||
| `adminBadge` | string | 博主标识文字，例如 `"博主"` |
|
||||
| `avatarPrefix` | string | 头像地址前缀，如 Gravatar 或 Cravatar 镜像地址 |
|
||||
| `adminEnabled` | boolean | 是否启用博主标识相关展示（关闭时不显示徽标，但仍可作为管理员邮箱） |
|
||||
| `allowedDomains` | Array\<string\> | 允许调用组件的域名列表，留空则不限制 |
|
||||
| `requireReview` | boolean | 是否开启新评论先审核再显示（true 表示新评论默认为待审核） |
|
||||
| `enableCommentLike` | boolean | 是否启用评论点赞功能（默认 true） |
|
||||
| `enableArticleLike` | boolean | 是否启用文章点赞功能（默认 true） |
|
||||
| `enableImageLightbox` | boolean | 是否启用评论图片灯箱预览功能（默认 false） |
|
||||
| `commentPlaceholder` | string \| null | 评论输入框的占位符文本，留空则使用默认值 |
|
||||
|
||||
**错误响应**
|
||||
|
||||
|
||||
3
docs/api/public/analytics.md
Normal file
3
docs/api/public/analytics.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# 访问统计
|
||||
|
||||
页面访问统计接口，用于记录和分析页面访问数据。
|
||||
67
docs/api/public/analytics/track-visit.md
Normal file
67
docs/api/public/analytics/track-visit.md
Normal file
@@ -0,0 +1,67 @@
|
||||
# 记录页面访问
|
||||
|
||||
```
|
||||
POST /api/analytics/visit
|
||||
```
|
||||
|
||||
前端组件在加载时调用此接口，记录页面访问数据，用于后台访问统计分析。
|
||||
|
||||
- 方法：`POST`
|
||||
- 路径：`/api/analytics/visit`
|
||||
- 鉴权：不需要
|
||||
|
||||
**请求头**
|
||||
|
||||
| 名称 | 必填 | 示例 |
|
||||
| -------------- | ---- | ------------------ |
|
||||
| `Content-Type` | 是 | `application/json` |
|
||||
|
||||
**请求体**
|
||||
|
||||
```json
|
||||
{
|
||||
"postSlug": "https://example.com/blog/hello-world",
|
||||
"postTitle": "博客标题",
|
||||
"postUrl": "https://example.com/blog/hello-world"
|
||||
}
|
||||
```
|
||||
|
||||
字段说明：
|
||||
|
||||
| 字段名 | 类型 | 必填 | 说明 |
|
||||
| ----------- | ------ | ---- | -------------------------------------------------------------------- |
|
||||
| `postSlug` | string | 是 | 文章唯一标识符，`window.location.origin + window.location.pathname` |
|
||||
| `postTitle` | string | 否 | 文章标题，用于后台展示页面名称 |
|
||||
| `postUrl` | string | 否 | 文章 URL，用于后台展示页面链接和域名统计 |
|
||||
|
||||
**成功响应**
|
||||
|
||||
- 状态码：`200`
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true
|
||||
}
|
||||
```
|
||||
|
||||
**错误响应**
|
||||
|
||||
- 缺少 `postSlug`：
|
||||
|
||||
- 状态码：`400`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "postSlug is required"
|
||||
}
|
||||
```
|
||||
|
||||
- 服务器内部错误：
|
||||
|
||||
- 状态码：`500`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "记录访问数据失败"
|
||||
! }
|
||||
```
|
||||
3
docs/api/public/auth.md
Normal file
3
docs/api/public/auth.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# 身份验证
|
||||
|
||||
管理员评论密钥验证接口，用于博主发布评论时的身份验证。
|
||||
75
docs/api/public/auth/verify-admin.md
Normal file
75
docs/api/public/auth/verify-admin.md
Normal file
@@ -0,0 +1,75 @@
|
||||
# 验证管理员密钥
|
||||
|
||||
```
|
||||
POST /api/verify-admin
|
||||
```
|
||||
|
||||
验证前台管理员评论所需的密钥，用于博主发布评论时的身份验证。
|
||||
|
||||
- 方法：`!POST`
|
||||
- 路径：`/api/verify-admin`
|
||||
- 鉴权：不需要
|
||||
|
||||
**请求头**
|
||||
|
||||
| 名称 | 必填 | 示例 |
|
||||
| -------------- | ---- | ------------------ |
|
||||
| `Content-Type` | 是 | `application/json` |
|
||||
|
||||
**请求体**
|
||||
|
||||
```json
|
||||
{
|
||||
"adminToken": "your-admin-key"
|
||||
}
|
||||
```
|
||||
|
||||
字段说明：
|
||||
|
||||
| 字段名 | 类型 | 必填 | 说明 |
|
||||
| ----------- | ------ | ---- | -------------- |
|
||||
| `adminToken` | string | 是 | 管理员评论密钥 |
|
||||
|
||||
**风控说明**
|
||||
|
||||
- 本地密钥存活时间 72 小时
|
||||
- 同一 IP 连续验证失败 3 次后，该 IP 将被锁定 30 分钟
|
||||
- 失败次数记录有效期为 1 小时
|
||||
|
||||
**成功响应**
|
||||
|
||||
- 状态码：`200`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "验证通过"
|
||||
}
|
||||
```
|
||||
|
||||
或未设置密钥时：
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "未设置管理员密钥"
|
||||
}
|
||||
```
|
||||
|
||||
**错误响应**
|
||||
|
||||
- 密钥错误：
|
||||
- 状态码：`401`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "密钥错误"
|
||||
}
|
||||
```
|
||||
|
||||
- 验证失败次数过多：
|
||||
- 状态码：`403`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "验证失败次数过多，请 30 分钟后再试"
|
||||
}
|
||||
```
|
||||
3
docs/api/public/comments.md
Normal file
3
docs/api/public/comments.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# 评论接口
|
||||
|
||||
评论相关的公开接口，包括获取评论列表、提交评论、评论点赞等。
|
||||
96
docs/api/public/comments/get-comments.md
Normal file
96
docs/api/public/comments/get-comments.md
Normal file
@@ -0,0 +1,96 @@
|
||||
# 获取评论列表
|
||||
|
||||
```
|
||||
GET /api/comments
|
||||
```
|
||||
|
||||
获取指定文章的评论列表，支持分页和嵌套结构。
|
||||
|
||||
- 方法：`GET`
|
||||
- 路径：`/api/comments`
|
||||
- 鉴权：不需要
|
||||
|
||||
**查询参数**
|
||||
|
||||
| 名称 | 位置 | 类型 | 必填 | 说明 |
|
||||
| ----------- | ----- | ------- | ---- | -------------------------------------------------------------------------------------------- |
|
||||
| `post_slug` | query | string | 是 | 使用 `window.location.origin + window`location.pathname`，获取带域名的链接，否则后台无法识别 |
|
||||
| `page` | query | integer | 否 | 页码，默认 `1` |
|
||||
| `limit` | query | integer | 否 | 每页数量，默认 `20`，最大 `50` |
|
||||
| `nested` | query | string | 否 | 是否返回嵌套结构，默认 `'true'` |
|
||||
|
||||
**成功响应**
|
||||
|
||||
- 状态码：`200`
|
||||
|
||||
```json
|
||||
{
|
||||
"data": [
|
||||
{
|
||||
"id": 1,
|
||||
"author": "张三",
|
||||
"email": "zhangsan@example.com",
|
||||
"url": "https://example.com",
|
||||
"contentText": "很棒的文章！",
|
||||
"contentHtml": "很棒的文章！",
|
||||
"pubDate": "2026-01-13T10:00:00Z",
|
||||
"postSlug": "/blog/hello-world",
|
||||
"avatar": "https://gravatar.com/avatar/...",
|
||||
"priority": 2,
|
||||
"likes": 5,
|
||||
"replies": [
|
||||
{
|
||||
"id": 2,
|
||||
"author": "李四",
|
||||
"email": "lisi@example.com",
|
||||
"url": null,
|
||||
"contentText": "同感！",
|
||||
"contentHtml": "同感！",
|
||||
"pubDate": "2026-01-13T11:00:00Z",
|
||||
"postSlug": "/blog/hello-world",
|
||||
"avatar": "https://gravatar.com/avatar/...",
|
||||
"parentId": 1,
|
||||
"replyToAuthor": "张三",
|
||||
"priority": 1,
|
||||
"likes": 2
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"pagination": {
|
||||
"page": 1,
|
||||
"limit": 20,
|
||||
"total": 1,
|
||||
"totalCount": 2
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- 当 `nested=true`（默认）时，接口返回的是"根评论列表"，每条根评论包含其 `replies`。
|
||||
- 当 `nested=false` 时，接口返回扁平列表，所有评论都在 `data` 中，`replies` 为空。
|
||||
- `priority` 字段：评论的置顶权重，数值越大排序越靠前。
|
||||
- `likes` 字段：评论的点赞数，默认为 0。
|
||||
|
||||
**错误响应**
|
||||
|
||||
- 缺少 `post_slug`：
|
||||
|
||||
- 状态码：`400`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "post_slug is required"
|
||||
}
|
||||
```
|
||||
|
||||
- 服务器内部错误：
|
||||
|
||||
- 状态码：`500`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "错误信息"
|
||||
}
|
||||
```
|
||||
119
docs/api/public/comments/like-comment.md
Normal file
119
docs/api/public/comments/like-comment.md
Normal file
@@ -0,0 +1,119 @@
|
||||
# 评论点赞
|
||||
|
||||
## 点赞评论
|
||||
|
||||
```
|
||||
POST /api/comments/like
|
||||
```
|
||||
|
||||
对指定评论进行点赞操作。
|
||||
|
||||
- 方法：`POST`
|
||||
- 路径：`/api/comments/like`
|
||||
- 鉴权：不需要
|
||||
|
||||
**请求头**
|
||||
|
||||
| 名称 | 必填 | 示例 |
|
||||
| -------------- | ---- | ------------------ |
|
||||
| `Content-Type` | 是 | `application/json` |
|
||||
|
||||
**请求体**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 123
|
||||
}
|
||||
```
|
||||
|
||||
字段说明：
|
||||
|
||||
| 字段名 | 类型 | 必填 | 说明 |
|
||||
| ------ | ------ | ---- | ---------- |
|
||||
| `id` | number | 是 | 评论 ID |
|
||||
|
||||
**成功响应**
|
||||
|
||||
- 状态码：`200`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "点赞成功",
|
||||
"likes": 5
|
||||
}
|
||||
```
|
||||
|
||||
字段说明：
|
||||
|
||||
| 字段名 | 类型 | 说明 |
|
||||
| ------- | ------ | -------------- |
|
||||
| `likes` | number | 更新后的点赞数 |
|
||||
|
||||
**错误响应**
|
||||
|
||||
- 状态码：`400`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "评论不存在"
|
||||
}
|
||||
```
|
||||
|
||||
## 取消点赞评论
|
||||
|
||||
```
|
||||
DELETE /api/comments/like
|
||||
```
|
||||
|
||||
取消对指定评论的点赞。
|
||||
|
||||
- 方法：`DELETE`
|
||||
- 路径：`/api/comments/like`
|
||||
- 鉴权：不需要
|
||||
|
||||
**请求头**
|
||||
|
||||
| 名称 | 必填 | 示例 |
|
||||
| -------------- | ---- | ------------------ |
|
||||
| `Content-Type` | 是 | `application/json` |
|
||||
|
||||
**请求体**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 123
|
||||
}
|
||||
```
|
||||
|
||||
字段说明：
|
||||
|
||||
| 字段名 | 类型 | 必填 | 说明 |
|
||||
| ------ | ------ | ---- | ---------- |
|
||||
| `id` | number | 是 | 评论 ID |
|
||||
|
||||
**成功响应**
|
||||
|
||||
- 状态码：`200`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "取消点赞成功",
|
||||
"likes": 4
|
||||
}
|
||||
```
|
||||
|
||||
字段说明：
|
||||
|
||||
| 字段名 | 类型 | 说明 |
|
||||
| ------- | ------ | -------------- |
|
||||
| `likes` | number | 更新后的点赞数 |
|
||||
|
||||
**错误响应**
|
||||
|
||||
- 状态码：`400`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "评论不存在"
|
||||
}
|
||||
```
|
||||
194
docs/api/public/comments/post-comment.md
Normal file
194
docs/api/public/comments/post-comment.md
Normal file
@@ -0,0 +1,194 @@
|
||||
# 提交评论
|
||||
|
||||
```
|
||||
POST /api/comments
|
||||
```
|
||||
|
||||
提交新评论或回复。
|
||||
|
||||
- 方法：`POST`
|
||||
- 路径：`/api/comments`
|
||||
- 鉴权：不需要
|
||||
|
||||
**请求头**
|
||||
|
||||
| 名称 | 必填 | 示例 |
|
||||
| -------------- | ---- | ---------------------------- |
|
||||
| `Content-Type` | 是 | `application/json` |
|
||||
|
||||
**请求体（Request Body）**
|
||||
|
||||
```json
|
||||
{
|
||||
"post_slug": "https://example.com/blog/hello-world",
|
||||
"post_title": "博客标题，可选",
|
||||
"post_url": "https://example.com/blog/hello-world",
|
||||
"name": "张三",
|
||||
"email": "zhangsan@example.com",
|
||||
"url": "https://zhangsan.me",
|
||||
"content": "很棒的文章！",
|
||||
"parent_id": 1,
|
||||
"adminToken": "your-admin-key"
|
||||
}
|
||||
```
|
||||
|
||||
字段说明：
|
||||
|
||||
| 字段名 | 类型 | 必填 | 说明 |
|
||||
| ------------ | ------ | ---- | ------------------------------------------------------------------------------------------------------------- |
|
||||
| `post_slug` | string | 是 | 文章唯一标识符，应与前端组件初始化时的 `postSlug` 值一致，`window.location.origin + window.location.pathname` |
|
||||
| `post_title` | string | 否 | 文章标题，用于邮件通知内容 |
|
||||
| `post_url` | string | 否 | 文章 URL，用于邮件通知中的跳转链接 |
|
||||
| `name` | string | 是 | 评论者昵称 |
|
||||
| `email` | string | 是 | 评论者邮箱，需为合法邮箱格式 |
|
||||
| `url` | string | 否 | 评论者个人主页或站点地址 |
|
||||
| `content` | string | 是 | 评论内容，内部会过滤 `<script>...</script>` 片段 |
|
||||
| `parent_id` | number | 否 | 父评论 ID，用于回复功能；缺省或 `null` 表示根评论 |
|
||||
| `adminToken` | string | 否 | 管理员评论密钥，博主发布评论时需要先通过 `/api/verify-admin` 验证密钥后将密钥传入此字段，评论将直接通过且不受审核设置影响 |
|
||||
|
||||
**成功响应**
|
||||
|
||||
- 状态码：`200`
|
||||
|
||||
评论直接通过时：
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "评论已提交",
|
||||
"status": "approved"
|
||||
}
|
||||
```
|
||||
|
||||
评论进入待审核状态时（开启"先审核再显示"且非管理员评论）：
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "已提交评论，待管理员审核后显示",
|
||||
"status": "pending"
|
||||
}
|
||||
```
|
||||
|
||||
**错误响应**
|
||||
|
||||
- 请求体缺失或字段类型错误：
|
||||
|
||||
- 状态码：`400`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "无效的请求体"
|
||||
}
|
||||
```
|
||||
|
||||
- 缺少必填字段：
|
||||
|
||||
- `post_slug` 为空：
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "post_slug 必填"
|
||||
}
|
||||
```
|
||||
|
||||
- `content` 为空：
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "评论内容不能为空"
|
||||
}
|
||||
```
|
||||
|
||||
- `author` 为空：
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "昵称不能为空"
|
||||
}
|
||||
```
|
||||
|
||||
- `email` 为空或格式不正确：
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "邮箱不能为空"
|
||||
}
|
||||
```
|
||||
|
||||
或
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "邮箱格式不正确"
|
||||
}
|
||||
```
|
||||
|
||||
- IP 或邮箱被限制：
|
||||
|
||||
- IP 被限制：
|
||||
- 状态码：`403`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "当前 IP 已被限制评论，请联系站长进行处理"
|
||||
}
|
||||
```
|
||||
|
||||
- 邮箱被限制：
|
||||
- 状态码：`403`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "当前邮箱已被限制评论，请联系站长进行处理"
|
||||
}
|
||||
```
|
||||
|
||||
- 管理员评论验证失败：
|
||||
|
||||
- 未输入密钥：
|
||||
- 状态码：`401`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "请输入管理员密钥",
|
||||
"requireAuth": true
|
||||
}
|
||||
```
|
||||
|
||||
- 密钥错误：
|
||||
- 状态码：`401`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "密钥错误"
|
||||
}
|
||||
```
|
||||
|
||||
- 验证失败次数过多：
|
||||
- 状态码：`403`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "验证失败次数过多，请 30 分钟后再试"
|
||||
}
|
||||
```
|
||||
|
||||
- 评论频率限制：
|
||||
|
||||
- 状态码：`429`
|
||||
- 逻辑：同一 IP 最近一条评论时间在 10 秒内，则拒绝此次请求。
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "评论频繁，等 10s 后再试"
|
||||
}
|
||||
```
|
||||
|
||||
- 服务器内部错误：
|
||||
|
||||
- 状态码：`500`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Internal Server Error"
|
||||
}
|
||||
```
|
||||
3
docs/api/public/config.md
Normal file
3
docs/api/public/config.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# 配置接口
|
||||
|
||||
获取评论相关的公开配置，用于前端组件读取博主邮箱、徽标等信息。
|
||||
55
docs/api/public/config/get-config.md
Normal file
55
docs/api/public/config/get-config.md
Normal file
@@ -0,0 +1,55 @@
|
||||
# 获取配置
|
||||
|
||||
```
|
||||
GET /api/config/comments
|
||||
```
|
||||
|
||||
获取评论相关的公开配置，用于前端组件读取博主邮箱、徽标等信息。
|
||||
|
||||
- 方法：`GET`
|
||||
- 路径：`/api/config/comments`
|
||||
- 鉴权：不需要
|
||||
|
||||
**成功响应**
|
||||
|
||||
- 状态码：`200`
|
||||
|
||||
```json
|
||||
{
|
||||
"adminEmail": "admin@example.com",
|
||||
"adminBadge": "博主",
|
||||
"avatar": "https://gravatar.com/avatar",
|
||||
"adminEnabled": true,
|
||||
"allowedDomains": [],
|
||||
"requireReview": false,
|
||||
"enableCommentLike": true,
|
||||
"enableArticleLike": true,
|
||||
"enableImageLightbox": true,
|
||||
"commentPlaceholder": "发表你的看法..."
|
||||
}
|
||||
```
|
||||
|
||||
字段说明：
|
||||
|
||||
| 字段名 | 类型 | 说明 |
|
||||
| -------------------- | ------ | -------------------------------------------------------------------- |
|
||||
| `adminEmail` | string | 博主邮箱地址，用于在前端展示"博主"标识，并触发管理员身份验证流程 |
|
||||
| `adminBadge` | string | 博主标识文字，例如 `"博主"` |
|
||||
| `avatarPrefix` | string | 头像地址前缀，如 Gravatar 或 Cravatar 需像地址 |
|
||||
| `adminEnabled` | boolean | 是否启用博主标识相关展示（关闭时不显示徽标，但仍可作为管理员邮箱） |
|
||||
| `allowedDomains` | Array\<string\> | 允许调用组件的域名列表，留空则不限制 |
|
||||
| `requireReview` | boolean | 是否开启新评论先审核再显示（true 表示新评论默认为待审核） |
|
||||
| `enableCommentLike` | boolean | 是否启用评论点赞功能（默认 true） |
|
||||
| `enableArticleLike` | boolean | 是否启用文章点赞功能（默认 true） |
|
||||
| `enableImageLightbox` | boolean | 是否启用评论图片灯箱预览功能（默认 false） |
|
||||
| `commentPlaceholder` | string \| null | 评论输入框的占位符文本，留空则使用默认值 |
|
||||
|
||||
**错误响应**
|
||||
|
||||
- 状态!码：`500`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "加载评论配置失败"
|
||||
}
|
||||
```
|
||||
3
docs/api/public/like.md
Normal file
3
docs/api/public/like.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# 点赞接口
|
||||
|
||||
文章和评论点赞相关的公开接口。
|
||||
67
docs/api/public/like/get-like-status.md
Normal file
67
docs/api/public/like/get-like-status.md
Normal file
@@ -0,0 +1,67 @@
|
||||
# 获取点赞状态
|
||||
|
||||
```
|
||||
GET /api/like
|
||||
```
|
||||
|
||||
获取当前页面的点赞状态和总点赞数，一般由前端组件在页面加载时自动调用。
|
||||
|
||||
- 方法：`GET`
|
||||
- 路径：`/api/like`
|
||||
- 鉴权：不需要
|
||||
|
||||
**查询参数**
|
||||
|
||||
| 名称 | 位置 | 类型 | 必填 | 说明 |
|
||||
| ----------- | ----- | ------ | ---- | --------------------------------------------------- |
|
||||
| `post_slug` | query | string | 是 | 页面唯一标识符，`window.location.origin + window.location.pathname` |
|
||||
|
||||
**请求头（可选）**
|
||||
|
||||
| 名称 | 必填 | 示例 | 说明 |
|
||||
| ----------------- | ---- | ----------------------------- | ------------------------------ |
|
||||
| `X-CWD-Like-User` | 否 | `550e8400-e29b-41d4-a716...` | 前端生成的匿名用户标识，用于区分不同用户 |
|
||||
|
||||
未显式传入 `X-CWD-Like-User` 时，服务端会尝试使用 `cf-connecting-ip` 作为用户标识，找不到时退回到 `anonymous`。
|
||||
|
||||
**成功响应**
|
||||
|
||||
- 状态码：`200`
|
||||
|
||||
```json
|
||||
{
|
||||
"liked": false,
|
||||
"alreadyLiked": false,
|
||||
"totalLikes": 12
|
||||
}
|
||||
```
|
||||
|
||||
字段说明：
|
||||
|
||||
| 字段名 | 类型 | 说明 |
|
||||
| ------------- | ------- | ---------------------------------------- |
|
||||
| `liked` | boolean | 当前用户是否已点赞 |
|
||||
| `alreadyLiked` | boolean | 预留字段，当前实现始终为 `false` |
|
||||
| `totalLikes` | number | 当前页面的总点赞数 |
|
||||
|
||||
**错误响应**
|
||||
|
||||
- 缺少 `post_slug`：
|
||||
|
||||
- 状态码：`400`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "post_slug is required"
|
||||
}
|
||||
```
|
||||
|
||||
- 服务器内部错误：
|
||||
|
||||
- 状态码：`500`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "获取点赞状态失败"
|
||||
}
|
||||
```
|
||||
75
docs/api/public/like/post-like.md
Normal file
75
docs/api/public/like/post-like.md
Normal file
@@ -0,0 +1,75 @@
|
||||
# 点赞文章
|
||||
|
||||
```
|
||||
POST /api/like
|
||||
```
|
||||
|
||||
对当前页面执行点赞操作，同一用户对同一页面只会计入一次点赞。
|
||||
|
||||
- 方法：`POST`
|
||||
- 路径：`/api/like`
|
||||
- 鉴权：不需要
|
||||
|
||||
**请求头**
|
||||
|
||||
| 名称 | 必填 | 示例 | 说明 |
|
||||
| ----------------- | ---- | ----------------------------- | ------------------------------ |
|
||||
| `ContentC-Type` | 是 | `application/json` | |
|
||||
| `X-CWD-Like-User` | 否 | `550e8400-e29b-41d4-a716...` | 前端生成的匿名用户标识，用于区分不同用户 |
|
||||
|
||||
**请求体**
|
||||
|
||||
```json
|
||||
{
|
||||
"postSlug": "https://example.com/blog/hello-world",
|
||||
"postTitle": "博客标题，可选",
|
||||
"postUrl": "https://example.com/blog/hello-world"
|
||||
}
|
||||
```
|
||||
|
||||
字段说明：
|
||||
|
||||
| 字段名 | 类型 | 必填 | 说明 |
|
||||
| ----------- | ------ | ---- | -------------------------------------------------------------------- |
|
||||
| `postSlug` | string | 是 | 页面唯一标识符，应与评论接口中的 `post_slug` 一致 |
|
||||
| `postTitle` | string | 否 | 页面标题，用于点赞统计中显示 |
|
||||
| `postUrl` | string | 否 | 页面 URL，用于点赞统计中跳转 |
|
||||
|
||||
**成功响应**
|
||||
|
||||
- 状态码：`200`
|
||||
|
||||
```json
|
||||
{
|
||||
"liked": true,
|
||||
"alreadyLiked": false,
|
||||
"totalLikes": 13
|
||||
}
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- 第一次点赞：`liked=true`，`alreadyLiked=false`，`totalLikes` 增加 1；
|
||||
- 重复点赞：服务器不会重复插入记录，`alreadyLiked=true`，`totalLikes` 不会继续增加。
|
||||
|
||||
**错误响应**
|
||||
|
||||
- 缺少 `postSlug`：
|
||||
|
||||
- 状态码：`400`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "postSlug is required"
|
||||
}
|
||||
```
|
||||
|
||||
- 服务器内部错误：
|
||||
|
||||
- 状态码：`500`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "点赞失败"
|
||||
}
|
||||
```
|
||||
@@ -14,8 +14,30 @@ CWD 内置提供评论数据分析和访客数据分析功能。
|
||||
|
||||
访客数据分析功能包含：
|
||||
|
||||
- 总访客数统计
|
||||
- 日/周/月访客数统计
|
||||
### 概览数据
|
||||
|
||||
- 总访问量（PV）统计
|
||||
- 总页面数统计
|
||||
- 今日访问量
|
||||
- 昨日访问量
|
||||
- 本周访问量
|
||||
- 上周访问量（用于同比对比）
|
||||
- 本月访问量
|
||||
- 上月访问量（用于同比对比）
|
||||
- 最近 30 天访客数据可视化图表
|
||||
|
||||
### 访问明细
|
||||
|
||||
- 页面访问明细，支持按 PV 排序或查看最新访问记录
|
||||
- 点赞页面访问记录
|
||||
|
||||
### 数据分析
|
||||
|
||||
- 同比趋势：对比本周与上周、本月与上月的访问量变化
|
||||
- 趋势图表：通过可视化图表直观展示访问数据的变化趋势
|
||||
|
||||
## 域名筛选
|
||||
|
||||
管理后台顶部导航栏提供了全局域名下拉选择器，用于在多域名站点之间切换数据视图。
|
||||
|
||||
在数据看板页面，所有数据统计都会根据选中的域名进行筛选，确保您能准确查看每个站点的数据情况。
|
||||
|
||||
@@ -1,11 +1,38 @@
|
||||
# 功能开关
|
||||
|
||||
### 点赞开关
|
||||
在 `网站设置` > `功能开关` 中，您可以控制各项功能的开启状态和个性化配置。
|
||||
|
||||
在 `网站设置` > `功能开关` 中，您可以控制文章点赞和评论点赞功能的开启状态。
|
||||
## 点赞功能
|
||||
|
||||
### 评论点赞
|
||||
|
||||
控制是否启用评论点赞功能。开启后，用户可以对评论进行点赞操作。
|
||||
|
||||
功能默认开启，可根据需要关闭。
|
||||
|
||||
### 文章点赞
|
||||
|
||||
控制是否启用文章点赞功能。开启后，每篇文章底部会显示点赞按钮，用户可以对文章进行点赞。
|
||||
|
||||
功能默认开启，可根据需要关闭。
|
||||
|
||||
## 图片预览
|
||||
|
||||
### 图片灯箱预览
|
||||
|
||||
控制是否启用评论内容中图片的灯箱预览功能。开启后，评论中的图片可以点击放大查看，再次点击关闭。
|
||||
|
||||
功能默认关闭，可根据需要开启。
|
||||
|
||||
## 个性化设置
|
||||
|
||||
### 评论框提示文案 (Placeholder)
|
||||
|
||||
自定义评论输入框的提示文字，支持换行。留空则使用默认值。
|
||||
自定义评论输入框的提示文字，让用户更清楚地知道应该输入什么内容。
|
||||
|
||||
- 支持换行
|
||||
- 留空则使用默认值："发表你的看法..."
|
||||
|
||||
示例：
|
||||
- "请留下您的评论，与大家分享您的看法..."
|
||||
- "欢迎留言，谢谢！"
|
||||
|
||||
Reference in New Issue
Block a user