docs: 添加点赞功能相关API文档
- 在admin.md中添加点赞管理相关接口说明 - 在frontend-config.md中新增customCssUrl配置项 - 新增admin/stats.md详细描述点赞统计和记录接口 - 在public.md中添加获取点赞状态和点赞操作接口
This commit is contained in:
anghunk
@@ -50,3 +50,8 @@ Token 通过登录接口获取，有效期为 24 小时。
|
|||||||
|
|
||||||
- **获取访问统计概览** `GET /admin/analytics/overview` - 用于管理后台「访问统计」页面展示整体访问数据
|
- **获取访问统计概览** `GET /admin/analytics/overview` - 用于管理后台「访问统计」页面展示整体访问数据
|
||||||
- **获取页面访问统计** `GET /admin/analytics/pages` - 用于管理后台「访问统计」页面展示各个页面的访问明细
|
- **获取页面访问统计** `GET /admin/analytics/pages` - 用于管理后台「访问统计」页面展示各个页面的访问明细
|
||||||
|
|
||||||
|
### 点赞管理相关
|
||||||
|
|
||||||
|
- **获取点赞记录列表** `GET /admin/likes/list` - 获取各页面的点赞记录列表，支持按页面或用户筛选
|
||||||
|
- **获取点赞统计** `GET /admin/likes/stats` - 获取点赞 Top 页面列表，用于后台展示点赞排行榜
|
||||||
|
|||||||
@@ -136,3 +136,124 @@ GET /admin/stats/domains
|
|||||||
"message": "获取域名列表失败"
|
"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": "获取点赞记录失败"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|||||||
@@ -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. 配置相关
|
||||||
|
|
||||||
### 2.1 获取评论相关的公开配置
|
### 2.1 获取评论相关的公开配置
|
||||||
|
|||||||
@@ -20,12 +20,13 @@
|
|||||||
|
|
||||||
### 参数说明
|
### 参数说明
|
||||||
|
|
||||||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||||||
| ------------ | ----------------------- | ---- | --------- | ------------------------- |
|
| -------------- | ----------------------- | ---- | --------- | ------------------------------------------ |
|
||||||
| `el` | `string \| HTMLElement` | 是 | - | 挂载元素选择器或 DOM 元素 |
|
| `el` | `string \| HTMLElement` | 是 | - | 挂载元素选择器或 DOM 元素 |
|
||||||
| `apiBaseUrl` | `string` | 是 | - | API 基础地址 |
|
| `apiBaseUrl` | `string` | 是 | - | API 基础地址 |
|
||||||
| `theme` | `'light' \| 'dark'` | 否 | `'light'` | 主题模式 |
|
| `theme` | `'light' \| 'dark'` | 否 | `'light'` | 主题模式 |
|
||||||
| `pageSize` | `number` | 否 | `20` | 每页显示评论数 |
|
| `pageSize` | `number` | 否 | `20` | 每页显示评论数 |
|
||||||
|
| `customCssUrl` | `string` | 否 | - | 自定义样式表 URL，追加到 Shadow DOM 底部 |
|
||||||
|
|
||||||
头像前缀、博主邮箱和标识等信息由后端接口 `/api/config/comments` 提供，无需在前端进行配置。
|
头像前缀、博主邮箱和标识等信息由后端接口 `/api/config/comments` 提供，无需在前端进行配置。
|
||||||
|
|
||||||
@@ -50,6 +51,11 @@
|
|||||||
```javascript
|
```javascript
|
||||||
// 动态切换主题
|
// 动态切换主题
|
||||||
comments.updateConfig({ theme: 'dark' });
|
comments.updateConfig({ theme: 'dark' });
|
||||||
|
|
||||||
|
// 配置自定义样式（会以 <link> 形式注入到 Shadow DOM 底部）
|
||||||
|
comments.updateConfig({
|
||||||
|
customCssUrl: 'https://your-cdn.example.com/cwd-custom.css',
|
||||||
|
});
|
||||||
```
|
```
|
||||||
|
|
||||||
## 其他框架示例
|
## 其他框架示例
|
||||||
|
|||||||
Reference in New Issue
Block a user