diff --git a/docs/.vitepress/configs/sidebar.js b/docs/.vitepress/configs/sidebar.js index a9b5c4c..b5c09a5 100644 --- a/docs/.vitepress/configs/sidebar.js +++ b/docs/.vitepress/configs/sidebar.js @@ -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' }, ], }, ], diff --git a/docs/api/admin/analytics.md b/docs/api/admin/analytics.md index e4a308d..2c9dc84 100644 --- a/docs/api/admin/analytics.md +++ b/docs/api/admin/analytics.md @@ -14,7 +14,7 @@ Authorization: Bearer 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\ | 最近 30 天的每日访问数（按自然日聚合） | | `last30Days[].date` | string (YYYY-MM-DD) | 日期，UTC 时间格式化后的自然日 | | `last30Days[].total` | number | 当日访问总数 | +**说明**： + +- `weekPv`：本周（从周一到当天）的总访问量 +- `lastWeekPv`：上周（上周一到上周日）的总访问量，用于与本周进行同比对比 +- `monthPv`：本月（从本月1号到当天）的总访问量 +- `lastMonthPv`：上月（上月1号到上月最后一天）的总访问量，用于与本月进行进行同比对比 + **错误响应** - 状态码：`500` diff --git a/docs/api/admin/auth.md b/docs/api/admin/auth.md index f58c150..5d76fed 100644 --- a/docs/api/admin/auth.md +++ b/docs/api/admin/auth.md @@ -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 diff --git a/docs/api/admin/feature-settings.md b/docs/api/admin/feature-settings.md index 3c4a524..0696841 100644 --- a/docs/api/admin/feature-settings.md +++ b/docs/api/admin/feature-settings.md @@ -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` 表示不限制域名。 **成功响应** diff --git a/docs/api/public.md b/docs/api/public.md index 0f0a0c4..ffa5657 100644 --- a/docs/api/public.md +++ b/docs/api/public.md @@ -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\ | 允许调用组件的域名列表，留空则不限制 | -| `requireReview` | boolean | 是否开启新评论先审核再显示（true 表示新评论默认为待审核） | -| `enableCommentLike` | boolean | 是否启用评论点赞功能（默认 true） | -| `enableArticleLike` | boolean | 是否启用文章点赞功能（默认 true） | +| 字段名 | 类型 | 说明 | +| -------------------- | ------ | -------------------------------------------------------------------- | +| `adminEmail` | string | 博主邮箱地址，用于在前端展示"博主"标识，并触发管理员身份验证流程 | +| `adminBadge` | string | 博主标识文字，例如 `"博主"` | +| `avatarPrefix` | string | 头像地址前缀，如 Gravatar 或 Cravatar 镜像地址 | +| `adminEnabled` | boolean | 是否启用博主标识相关展示（关闭时不显示徽标，但仍可作为管理员邮箱） | +| `allowedDomains` | Array\ | 允许调用组件的域名列表，留空则不限制 | +| `requireReview` | boolean | 是否开启新评论先审核再显示（true 表示新评论默认为待审核） | +| `enableCommentLike` | boolean | 是否启用评论点赞功能（默认 true） | +| `enableArticleLike` | boolean | 是否启用文章点赞功能（默认 true） | +| `enableImageLightbox` | boolean | 是否启用评论图片灯箱预览功能（默认 false） | +| `commentPlaceholder` | string \| null | 评论输入框的占位符文本，留空则使用默认值 | **错误响应** diff --git a/docs/api/public/analytics.md b/docs/api/public/analytics.md new file mode 100644 index 0000000..6f6298c --- /dev/null +++ b/docs/api/public/analytics.md @@ -0,0 +1,3 @@ +# 访问统计 + +页面访问统计接口，用于记录和分析页面访问数据。 diff --git a/docs/api/public/analytics/track-visit.md b/docs/api/public/analytics/track-visit.md new file mode 100644 index 0000000..ed5e53a --- /dev/null +++ b/docs/api/public/analytics/track-visit.md @@ -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": "记录访问数据失败" +! } + ``` diff --git a/docs/api/public/auth.md b/docs/api/public/auth.md new file mode 100644 index 0000000..2eb3552 --- /dev/null +++ b/docs/api/public/auth.md @@ -0,0 +1,3 @@ +# 身份验证 + +管理员评论密钥验证接口，用于博主发布评论时的身份验证。 diff --git a/docs/api/public/auth/verify-admin.md b/docs/api/public/auth/verify-admin.md new file mode 100644 index 0000000..0f5a784 --- /dev/null +++ b/docs/api/public/auth/verify-admin.md @@ -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 分钟后再试" + } + ``` diff --git a/docs/api/public/comments.md b/docs/api/public/comments.md new file mode 100644 index 0000000..823d996 --- /dev/null +++ b/docs/api/public/comments.md @@ -0,0 +1,3 @@ +# 评论接口 + +评论相关的公开接口，包括获取评论列表、提交评论、评论点赞等。 diff --git a/docs/api/public/comments/get-comments.md b/docs/api/public/comments/get-comments.md new file mode 100644 index 0000000..8b350bd --- /dev/null +++ b/docs/api/public/comments/get-comments.md @@ -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": "错误信息" + } + ``` diff --git a/docs/api/public/comments/like-comment.md b/docs/api/public/comments/like-comment.md new file mode 100644 index 0000000..f899887 --- /dev/null +++ b/docs/api/public/comments/like-comment.md @@ -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": "评论不存在" +} +``` diff --git a/docs/api/public/comments/post-comment.md b/docs/api/public/comments/post-comment.md new file mode 100644 index 0000000..c3ab213 --- /dev/null +++ b/docs/api/public/comments/post-comment.md @@ -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 | 是 | 评论内容，内部会过滤 `` 片段 | +| `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" + } + ``` diff --git a/docs/api/public/config.md b/docs/api/public/config.md new file mode 100644 index 0000000..7de6a3f --- /dev/null +++ b/docs/api/public/config.md @@ -0,0 +1,3 @@ +# 配置接口 + +获取评论相关的公开配置，用于前端组件读取博主邮箱、徽标等信息。 diff --git a/docs/api/public/config/get-config.md b/docs/api/public/config/get-config.md new file mode 100644 index 0000000..d39925a --- /dev/null +++ b/docs/api/public/config/get-config.md @@ -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\ | 允许调用组件的域名列表，留空则不限制 | +| `requireReview` | boolean | 是否开启新评论先审核再显示（true 表示新评论默认为待审核） | +| `enableCommentLike` | boolean | 是否启用评论点赞功能（默认 true） | +| `enableArticleLike` | boolean | 是否启用文章点赞功能（默认 true） | +| `enableImageLightbox` | boolean | 是否启用评论图片灯箱预览功能（默认 false） | +| `commentPlaceholder` | string \| null | 评论输入框的占位符文本，留空则使用默认值 | + +**错误响应** + +- 状态!码：`500` + +```json +{ + "message": "加载评论配置失败" +} +``` diff --git a/docs/api/public/like.md b/docs/api/public/like.md new file mode 100644 index 0000000..e6d089e --- /dev/null +++ b/docs/api/public/like.md @@ -0,0 +1,3 @@ +# 点赞接口 + +文章和评论点赞相关的公开接口。 diff --git a/docs/api/public/like/get-like-status.md b/docs/api/public/like/get-like-status.md new file mode 100644 index 0000000..9bfce38 --- /dev/null +++ b/docs/api/public/like/get-like-status.md @@ -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": "获取点赞状态失败" + } + ``` diff --git a/docs/api/public/like/post-like.md b/docs/api/public/like/post-like.md new file mode 100644 index 0000000..b46b0ec --- /dev/null +++ b/docs/api/public/like/post-like.md @@ -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": "点赞失败" + } + ``` diff --git a/docs/function/data-statistics.md b/docs/function/data-statistics.md index 269aa3c..c07c9e2 100644 --- a/docs/function/data-statistics.md +++ b/docs/function/data-statistics.md @@ -14,8 +14,30 @@ CWD 内置提供评论数据分析和访客数据分析功能。 访客数据分析功能包含： -- 总访客数统计 -- 日/周/月访客数统计 +### 概览数据 + +- 总访问量（PV）统计 +- 总页面数统计 +- 今日访问量 +- 昨日访问量 +- 本周访问量 +- 上周访问量（用于同比对比） +- 本月访问量 +- 上月访问量（用于同比对比） - 最近 30 天访客数据可视化图表 + +### 访问明细 + - 页面访问明细，支持按 PV 排序或查看最新访问记录 - 点赞页面访问记录 + +### 数据分析 + +- 同比趋势：对比本周与上周、本月与上月的访问量变化 +- 趋势图表：通过可视化图表直观展示访问数据的变化趋势 + +## 域名筛选 + +管理后台顶部导航栏提供了全局域名下拉选择器，用于在多域名站点之间切换数据视图。 + +在数据看板页面，所有数据统计都会根据选中的域名进行筛选，确保您能准确查看每个站点的数据情况。 diff --git a/docs/function/feature-settings.md b/docs/function/feature-settings.md index 76cb6de..131e21e 100644 --- a/docs/function/feature-settings.md +++ b/docs/function/feature-settings.md @@ -1,11 +1,38 @@ # 功能开关 -### 点赞开关 +在 `网站设置` > `功能开关` 中，您可以控制各项功能的开启状态和个性化配置。 -在 `网站设置` > `功能开关` 中，您可以控制文章点赞和评论点赞功能的开启状态。 +## 点赞功能 + +### 评论点赞 + +控制是否启用评论点赞功能。开启后，用户可以对评论进行点赞操作。 功能默认开启，可根据需要关闭。 +### 文章点赞 + +控制是否启用文章点赞功能。开启后，每篇文章底部会显示点赞按钮，用户可以对文章进行点赞。 + +功能默认开启，可根据需要关闭。 + +## 图片预览 + +### 图片灯箱预览 + +控制是否启用评论内容中图片的灯箱预览功能。开启后，评论中的图片可以点击放大查看，再次点击关闭。 + +功能默认关闭，可根据需要开启。 + +## 个性化设置 + ### 评论框提示文案 (Placeholder) -自定义评论输入框的提示文字，支持换行。留空则使用默认值。 \ No newline at end of file +自定义评论输入框的提示文字，让用户更清楚地知道应该输入什么内容。 + +- 支持换行 +- 留空则使用默认值："发表你的看法..." + +示例： +- "请留下您的评论，与大家分享您的看法..." +- "欢迎留言，谢谢！"