diff --git a/docs/api/admin.md b/docs/api/admin.md index f3750f6..77e9ab4 100644 --- a/docs/api/admin.md +++ b/docs/api/admin.md @@ -50,3 +50,8 @@ Token 通过登录接口获取，有效期为 24 小时。 - **获取访问统计概览** `GET /admin/analytics/overview` - 用于管理后台「访问统计」页面展示整体访问数据 - **获取页面访问统计** `GET /admin/analytics/pages` - 用于管理后台「访问统计」页面展示各个页面的访问明细 + +### 点赞管理相关 + +- **获取点赞记录列表** `GET /admin/likes/list` - 获取各页面的点赞记录列表，支持按页面或用户筛选 +- **获取点赞统计** `GET /admin/likes/stats` - 获取点赞 Top 页面列表，用于后台展示点赞排行榜 diff --git a/docs/api/admin/stats.md b/docs/api/admin/stats.md index e674409..c837584 100644 --- a/docs/api/admin/stats.md +++ b/docs/api/admin/stats.md @@ -136,3 +136,124 @@ GET /admin/stats/domains "message": "获取域名列表失败" } ``` + +## 1.3 获取点赞统计数据（点赞排行榜） + +``` +GET /admin/likes/stats +``` + +用于管理后台展示按点赞数排序的页面列表，例如「点赞排行榜」。 + +- 方法：`GET` +- 路径：`/admin/likes/stats` +- 鉴权：需要（Bearer Token） + +当前实现不接收查询参数，默认返回点赞数最多的前 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": "获取点赞记录失败" +} +``` diff --git a/docs/api/public.md b/docs/api/public.md index 3868451..a108a9f 100644 --- a/docs/api/public.md +++ b/docs/api/public.md @@ -295,6 +295,150 @@ POST /api/comments } ``` +### 1.3 获取点赞状态 + +``` +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": "获取点赞状态失败" + } + ``` + +### 1.4 点赞当前页面 + +``` +POST /api/like +``` + +对当前页面执行点赞操作，同一用户对同一页面只会计入一次点赞。 + +- 方法：`POST` +- 路径：`/api/like` +- 鉴权：不需要 + +**请求头** + +| 名称 | 必填 | 示例 | 说明 | +| ----------------- | ---- | ----------------------------- | ------------------------------ | +| `Content-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": "点赞失败" + } + ``` + ## 2. 配置相关 ### 2.1 获取评论相关的公开配置 diff --git a/docs/guide/frontend-config.md b/docs/guide/frontend-config.md index a10c456..eb1de24 100644 --- a/docs/guide/frontend-config.md +++ b/docs/guide/frontend-config.md @@ -20,12 +20,13 @@ ### 参数说明 -| 参数 | 类型 | 必填 | 默认值 | 说明 | -| ------------ | ----------------------- | ---- | --------- | ------------------------- | -| `el` | `string \| HTMLElement` | 是 | - | 挂载元素选择器或 DOM 元素 | -| `apiBaseUrl` | `string` | 是 | - | API 基础地址 | -| `theme` | `'light' \| 'dark'` | 否 | `'light'` | 主题模式 | -| `pageSize` | `number` | 否 | `20` | 每页显示评论数 | +| 参数 | 类型 | 必填 | 默认值 | 说明 | +| -------------- | ----------------------- | ---- | --------- | ------------------------------------------ | +| `el` | `string \| HTMLElement` | 是 | - | 挂载元素选择器或 DOM 元素 | +| `apiBaseUrl` | `string` | 是 | - | API 基础地址 | +| `theme` | `'light' \| 'dark'` | 否 | `'light'` | 主题模式 | +| `pageSize` | `number` | 否 | `20` | 每页显示评论数 | +| `customCssUrl` | `string` | 否 | - | 自定义样式表 URL，追加到 Shadow DOM 底部 | 头像前缀、博主邮箱和标识等信息由后端接口 `/api/config/comments` 提供，无需在前端进行配置。 @@ -50,6 +51,11 @@ ```javascript // 动态切换主题 comments.updateConfig({ theme: 'dark' }); + +// 配置自定义样式（会以 形式注入到 Shadow DOM 底部） +comments.updateConfig({ + customCssUrl: 'https://your-cdn.example.com/cwd-custom.css', +}); ``` ## 其他框架示例