docs: 添加点赞功能相关API文档

- 在admin.md中添加点赞管理相关接口说明 - 在frontend-config.md中新增customCssUrl配置项 - 新增admin/stats.md详细描述点赞统计和记录接口 - 在public.md中添加获取点赞状态和点赞操作接口
2026-01-22 18:05:18 +08:00
parent fc99d334db
commit 26e1ab5c61
4 changed files with 282 additions and 6 deletions
--- 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 页面列表，用于后台展示点赞排行榜
--- 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": "获取点赞记录失败"
+}
+```
--- 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 获取评论相关的公开配置
--- 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' });
+
+// 配置自定义样式（会以 <link> 形式注入到 Shadow DOM 底部）
+comments.updateConfig({
+	customCssUrl: 'https://your-cdn.example.com/cwd-custom.css',
+});
 ```

 ## 其他框架示例