From d5a7a15344dfdd75fe3b5c4c991a5a512aa295da Mon Sep 17 00:00:00 2001 From: anghunk Date: Wed, 21 Jan 2026 21:56:57 +0800 Subject: [PATCH] =?UTF-8?q?feat(analytics):=20=E6=B7=BB=E5=8A=A0=E8=AE=BF?= =?UTF-8?q?=E9=97=AE=E7=BB=9F=E8=AE=A1=E5=8A=9F=E8=83=BD?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 实现页面访问统计功能，包括： 1. 前端组件挂载时上报访问数据 2. 后端接口记录访问信息并存储 3. 管理后台新增访问统计视图 4. 相关API文档和设计说明更新 --- cwd-admin/src/api/admin.ts | 25 + cwd-admin/src/router/index.ts | 6 + cwd-admin/src/views/AnalyticsVisitView.vue | 266 ++++++++ cwd-admin/src/views/LayoutView.vue | 12 + cwd-admin/widget/src/core/CWDComments.js | 4 + cwd-admin/widget/src/core/api.js | 20 +- cwd-api/src/api/admin/visitAnalytics.ts | 78 +++ cwd-api/src/api/public/trackVisit.ts | 69 ++ cwd-api/src/index.ts | 5 + docs/api/admin.md | 715 +++++++++++++++------ docs/api/public.md | 178 ++++- docs/function/admin-panel.md | 64 ++ 12 files changed, 1241 insertions(+), 201 deletions(-) create mode 100644 cwd-admin/src/views/AnalyticsVisitView.vue create mode 100644 cwd-api/src/api/admin/visitAnalytics.ts create mode 100644 cwd-api/src/api/public/trackVisit.ts diff --git a/cwd-admin/src/api/admin.ts b/cwd-admin/src/api/admin.ts index 247844e..86b8234 100644 --- a/cwd-admin/src/api/admin.ts +++ b/cwd-admin/src/api/admin.ts @@ -83,6 +83,23 @@ export type CommentStatsResponse = { }[]; }; +export type VisitOverviewResponse = { + totalPv: number; + totalPages: number; +}; + +export type VisitPageItem = { + postSlug: string; + postTitle: string | null; + postUrl: string | null; + pv: number; + lastVisitAt: string | null; +}; + +export type VisitPagesResponse = { + items: VisitPageItem[]; +}; + export async function loginAdmin(name: string, password: string): Promise { const res = await post('/admin/login', { name, password }); const key = res.data.key; @@ -212,3 +229,11 @@ export function importComments(data: any[]): Promise<{ message: string }> { export function fetchCommentStats(): Promise { return get('/admin/stats/comments'); } + +export function fetchVisitOverview(): Promise { + return get('/admin/analytics/overview'); +} + +export function fetchVisitPages(): Promise { + return get('/admin/analytics/pages'); +} diff --git a/cwd-admin/src/router/index.ts b/cwd-admin/src/router/index.ts index 52dc22e..155a8d1 100644 --- a/cwd-admin/src/router/index.ts +++ b/cwd-admin/src/router/index.ts @@ -5,6 +5,7 @@ import CommentsView from '../views/CommentsView.vue'; import SettingsView from '../views/SettingsView.vue'; import DataView from '../views/DataView.vue'; import StatsView from '../views/StatsView.vue'; +import AnalyticsVisitView from '../views/AnalyticsVisitView.vue'; const routes: RouteRecordRaw[] = [ { @@ -30,6 +31,11 @@ const routes: RouteRecordRaw[] = [ name: 'stats', component: StatsView }, + { + path: 'analytics', + name: 'analytics', + component: AnalyticsVisitView + }, { path: 'settings', name: 'settings', diff --git a/cwd-admin/src/views/AnalyticsVisitView.vue b/cwd-admin/src/views/AnalyticsVisitView.vue new file mode 100644 index 0000000..fb7178c --- /dev/null +++ b/cwd-admin/src/views/AnalyticsVisitView.vue @@ -0,0 +1,266 @@ + + + + + + diff --git a/cwd-admin/src/views/LayoutView.vue b/cwd-admin/src/views/LayoutView.vue index 7e87697..0b63bd4 100644 --- a/cwd-admin/src/views/LayoutView.vue +++ b/cwd-admin/src/views/LayoutView.vue @@ -75,6 +75,13 @@ > 数据看板 +
  • + 访问统计 +
  • +) => { + try { + await c.env.CWD_DB.prepare( + 'CREATE TABLE IF NOT EXISTS page_stats (id INTEGER PRIMARY KEY AUTOINCREMENT, post_slug TEXT UNIQUE NOT NULL, post_title TEXT, post_url TEXT, pv INTEGER NOT NULL DEFAULT 0, last_visit_at TEXT, created_at TEXT NOT NULL, updated_at TEXT NOT NULL)' + ).run(); + + const row = await c.env.CWD_DB.prepare( + 'SELECT COUNT(*) as totalPages, COALESCE(SUM(pv), 0) as totalPv FROM page_stats' + ).first<{ + totalPages: number | null; + totalPv: number | null; + }>(); + + const data: VisitOverview = { + totalPv: row?.totalPv || 0, + totalPages: row?.totalPages || 0 + }; + + return c.json(data); + } catch (e: any) { + return c.json( + { message: e.message || '获取访问统计概览失败' }, + 500 + ); + } +}; + +export const getVisitPages = async (c: Context<{ Bindings: Bindings }>) => { + try { + await c.env.CWD_DB.prepare( + 'CREATE TABLE IF NOT EXISTS page_stats (id INTEGER PRIMARY KEY AUTOINCREMENT, post_slug TEXT UNIQUE NOT NULL, post_title TEXT, post_url TEXT, pv INTEGER NOT NULL DEFAULT 0, last_visit_at TEXT, created_at TEXT NOT NULL, updated_at TEXT NOT NULL)' + ).run(); + + const { results } = await c.env.CWD_DB.prepare( + 'SELECT post_slug, post_title, post_url, pv, last_visit_at FROM page_stats ORDER BY pv DESC, last_visit_at DESC' + ).all<{ + post_slug: string; + post_title: string | null; + post_url: string | null; + pv: number; + last_visit_at: string | null; + }>(); + + const items: VisitPageItem[] = results.map((row) => ({ + postSlug: row.post_slug, + postTitle: row.post_title, + postUrl: row.post_url, + pv: row.pv || 0, + lastVisitAt: row.last_visit_at + })); + + return c.json({ items }); + } catch (e: any) { + return c.json( + { message: e.message || '获取页面访问统计失败' }, + 500 + ); + } +}; + diff --git a/cwd-api/src/api/public/trackVisit.ts b/cwd-api/src/api/public/trackVisit.ts new file mode 100644 index 0000000..066887c --- /dev/null +++ b/cwd-api/src/api/public/trackVisit.ts @@ -0,0 +1,69 @@ +import type { Context } from 'hono'; +import type { Bindings } from '../../bindings'; + +type TrackVisitBody = { + postSlug?: string; + postTitle?: string; + postUrl?: string; +}; + +export const trackVisit = async (c: Context<{ Bindings: Bindings }>) => { + try { + const body = (await c.req.json().catch(() => ({}))) as TrackVisitBody; + + const rawPostSlug = typeof body.postSlug === 'string' ? body.postSlug.trim() : ''; + const rawPostTitle = typeof body.postTitle === 'string' ? body.postTitle.trim() : ''; + const rawPostUrl = typeof body.postUrl === 'string' ? body.postUrl.trim() : ''; + + if (!rawPostSlug) { + return c.json({ message: 'postSlug is required' }, 400); + } + + await c.env.CWD_DB.prepare( + 'CREATE TABLE IF NOT EXISTS page_stats (id INTEGER PRIMARY KEY AUTOINCREMENT, post_slug TEXT UNIQUE NOT NULL, post_title TEXT, post_url TEXT, pv INTEGER NOT NULL DEFAULT 0, last_visit_at TEXT, created_at TEXT NOT NULL, updated_at TEXT NOT NULL)' + ).run(); + + const now = new Date().toISOString(); + + const existing = await c.env.CWD_DB.prepare( + 'SELECT id, pv FROM page_stats WHERE post_slug = ?' + ) + .bind(rawPostSlug) + .first<{ id: number; pv: number }>(); + + if (!existing) { + await c.env.CWD_DB.prepare( + 'INSERT INTO page_stats (post_slug, post_title, post_url, pv, last_visit_at, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?)' + ) + .bind( + rawPostSlug, + rawPostTitle || null, + rawPostUrl || null, + 1, + now, + now, + now + ) + .run(); + } else { + const newPv = (existing.pv || 0) + 1; + await c.env.CWD_DB.prepare( + 'UPDATE page_stats SET post_title = ?, post_url = ?, pv = ?, last_visit_at = ?, updated_at = ? WHERE id = ?' + ) + .bind( + rawPostTitle || null, + rawPostUrl || null, + newPv, + now, + now, + existing.id + ) + .run(); + } + + return c.json({ success: true }); + } catch (e: any) { + return c.json({ message: e.message || '记录访问数据失败' }, 500); + } +}; + diff --git a/cwd-api/src/index.ts b/cwd-api/src/index.ts index da393e1..adaa615 100644 --- a/cwd-api/src/index.ts +++ b/cwd-api/src/index.ts @@ -23,6 +23,8 @@ import { getAdminEmail } from './api/admin/getAdminEmail'; import { setAdminEmail } from './api/admin/setAdminEmail'; import { testEmail } from './api/admin/testEmail'; import { getStats } from './api/admin/getStats'; +import { trackVisit } from './api/public/trackVisit'; +import { getVisitOverview, getVisitPages } from './api/admin/visitAnalytics'; const app = new Hono<{ Bindings: Bindings }>(); const VERSION = `v${packageJson.version}`; @@ -214,6 +216,7 @@ app.get('/', (c) => { app.get('/api/comments', getComments); app.post('/api/comments', postComment); app.post('/api/verify-admin', verifyAdminKey); +app.post('/api/analytics/visit', trackVisit); app.get('/api/config/comments', async (c) => { try { const settings = await loadCommentSettings(c.env); @@ -240,6 +243,8 @@ app.post('/admin/comments/import', importComments); app.put('/admin/comments/status', updateStatus); app.put('/admin/comments/update', updateComment); app.get('/admin/stats/comments', getStats); +app.get('/admin/analytics/overview', getVisitOverview); +app.get('/admin/analytics/pages', getVisitPages); app.get('/admin/settings/email', getAdminEmail); app.put('/admin/settings/email', setAdminEmail); app.get('/admin/settings/email-notify', async (c) => { diff --git a/docs/api/admin.md b/docs/api/admin.md index 5695574..ef23c4c 100644 --- a/docs/api/admin.md +++ b/docs/api/admin.md @@ -10,7 +10,9 @@ Authorization: Bearer Token 通过登录接口获取，有效期为 24 小时。 -## 管理员登录 +## 1. 身份认证相关 + +### 1.1 管理员登录 ``` POST /admin/login @@ -93,7 +95,9 @@ POST /admin/login } ``` -## 获取评论列表 +## 2. 评论管理相关 + +### 2.1 获取评论列表 ``` GET /admin/comments/list @@ -135,6 +139,7 @@ GET /admin/comments/list "contentText": "很棒的文章！", "contentHtml": "很棒的文章！", "status": "approved", + "priority": 2, "ua": "Mozilla/5.0 ...", "avatar": "https://gravatar.com/avatar/..." } @@ -158,7 +163,7 @@ GET /admin/comments/list } ``` -## 更新评论状态 +### 2.2 更新评论状态 ``` PUT /admin/comments/status @@ -166,6 +171,8 @@ PUT /admin/comments/status 更新评论状态（例如通过 / 拒绝）。 +**注意**：此接口仅用于更新评论状态，如需修改评论内容、置顶权重等，请使用 `/admin/comments/update` 接口。 + - 方法：`PUT` - 路径：`/admin/comments/status` - 鉴权：需要（Bearer Token） @@ -212,7 +219,106 @@ PUT /admin/comments/status } ``` -## 删除指定评论 +### 2.3 更新评论内容 + +``` +PUT /admin/comments/update +``` + +更新评论的详细信息，包括昵称、邮箱、网址、评论地址、内容、状态和置顶权重等。 + +- 方法：`PUT` +- 路径：`/admin/comments/update` +- 鉴权：需要（Bearer Token） + +**请求头** + +| 名称 | 必填 | 示例 | +| -------------- | ---- | ------------------ | +| `Content-Type` | 是 | `application/json` | + +**请求体** + +```json +{ + "id": 1, + "name": "张三", + "email": "zhangsan@example.com", + "url": "https://zhangsan.me", + "postSlug": "https://example.com/blog/hello-world", + "contentText": "更新后的评论内容", + "status": "approved", + "priority": 2 +} +``` + +字段说明： + +| 字段名 | 类型 | 必填 | 说明 | +| ----------- | ------ | ---- | -------------------------------------- | +| `id` | number | 是 | 评论 ID | +| `name` | string | 是 | 评论者昵称 | +| `email` | string | 是 | 评论者邮箱 | +| `url` | string | 否 | 评论者个人主页或站点地址 | +| `postSlug` | string | 否 | 评论地址（文章 URL），不传则保持原值 | +| `contentText` | string | 是 | 评论内容（纯文本） | +| `status` | string | 否 | 评论状态，可选 `approved`、`pending`、`rejected` | +| `priority` | number | 否 | 置顶权重，默认为 1，数值越大越靠前 | + +**置顶权重说明**： + +- `1`：不置顶（默认值） +- `2` 或更高：数值越大，该评论在列表中排序越靠前 +- 公开 API 获取评论时，会按照 `priority DESC` 进行排序 + +**成功响应** + +- 状态码：`200` + +```json +{ + "message": "Comment updated, id: 1." +} +``` + +**错误响应** + +- ID 无效： + - 状态码：`400` 或 `404` + + ```json + { + "message": "Missing or invalid id" + } + ``` + + 或 + + ```json + { + "message": "Comment not found" + } + ``` + +- 必填字段为空： + - 状态码：`400` + + ```json + { + "message": "昵称不能为空" + } + ``` + +- 更新失败： + - 状态码：`500` + + ```json + { + "message": "Update failed" + } + ``` + +### 2.4 删除指定评论 ``` DELETE /admin/comments/delete @@ -260,7 +366,142 @@ DELETE /admin/comments/delete } ``` -## 导出所有评论数据 +### 2.5 将指定 IP 加入评论黑名单 + +``` +POST /admin/comments/block-ip +``` + +通过接口将指定 IP 地址加入评论黑名单，后续该 IP 提交评论将被拒绝。 + +- 方法：`POST` +- 路径：`/admin/comments/block-ip` +- 鉴权：需要（Bearer Token） + +**请求头** + +| 名称 | 必填 | 示例 | +| -------------- | ---- | ------------------ | +| `Content-Type` | 是 | `application/json` | + +**请求体** + +```json +{ + "ip": "1.1.1.1" +} +``` + +字段说明： + +| 字段名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------------------------------------------ | +| `ip` | string | 是 | 要加入黑名单的 IP 地址，多个 IP 用逗号或换行分隔 | + +**成功响应** + +- 状态码：`200` + +```json +{ + "message": "已加入 IP 黑名单" +} +``` + +**错误响应** + +- IP 为空： + - 状态码：`400` + + ```json + { + "message": "IP 地址不能为空" + } + ``` + +- 内部错误： + - 状态码：`500` + + ```json + { + "message": "操作失败" + } + ``` + +### 2.6 将指定邮箱加入评论黑名单 + +``` +POST /admin/comments/block-email +``` + +通过接口将指定邮箱地址加入评论黑名单，后续该邮箱提交评论将被拒绝。 + +- 方法：`POST` +- 路径：`/admin/comments/block-email` +- 鉴权：需要（Bearer Token） + +**请求头** + +| 名称 | 必填 | 示例 | +| -------------- | ---- | ------------------ | +| `Content-Type` | 是 | `application/json` | + +**请求体** + +```json +{ + "email": "spam@example.com" +} +``` + +字段说明： + +| 字段名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | ------------------------------------------------ | +| `email` | string | 是 | 要加入黑名单的邮箱地址，多个邮箱用逗号或换行分隔 | + +**成功响应** + +- 状态码：`200` + +```json +{ + "message": "已加入邮箱黑名单" +} +``` + +**错误响应** + +- 邮箱为空： + - 状态码：`400` + + ```json + { + "message": "邮箱不能为空" + } + ``` + +- 邮箱格式不正确： + - 状态码：`400` + + ```json + { + "message": "邮箱格式不正确" + } + ``` + +- 内部错误： + - 状态码：`500` + + ```json + { + "message": "操作失败" + } + ``` + +## 3. 评论数据导入导出 + +### 3.1 导出所有评论数据 ``` GET /admin/comments/export @@ -309,7 +550,7 @@ GET /admin/comments/export } ``` -## 导入评论数据 +### 3.2 导入评论数据 ``` POST /admin/comments/import @@ -377,95 +618,9 @@ POST /admin/comments/import } ``` -## 获取当前通知邮箱配置 +## 4. 评论设置相关 -``` -GET /admin/settings/email -``` - -获取当前通知邮箱配置。 - -- 方法：`GET` -- 路径：`/admin/settings/email` -- 鉴权：需要（Bearer Token） - -**成功响应** - -- 状态码：`200` - -```json -{ - "email": "admin@example.com" -} -``` - -**错误响应** - -- 状态码：`500` - -```json -{ - "message": "错误信息" -} -``` - -## 设置通知邮箱 - -``` -PUT /admin/settings/email -``` - -设置通知邮箱，用于接收新评论提醒。 - -- 方法：`PUT` -- 路径：`/admin/settings/email` -- 鉴权：需要（Bearer Token） - -**请求头** - -| 名称 | 必填 | 示例 | -| -------------- | ---- | ------------------ | -| `Content-Type` | 是 | `application/json` | - -**请求体** - -```json -{ - "email": "admin@example.com" -} -``` - -**成功响应** - -- 状态码：`200` - -```json -{ - "message": "保存成功" -} -``` - -**错误响应** - -- 邮箱格式不正确： - - 状态码：`400` - - ```json - { - "message": "邮箱格式不正确" - } - ``` - -- 服务器错误： - - 状态码：`500` - - ```json - { - "message": "错误信息" - } - ``` - -## 获取评论配置 +### 4.1 获取评论配置 ``` GET /admin/settings/comments @@ -500,13 +655,13 @@ GET /admin/settings/comments | 字段名 | 类型 | 说明 | | ---------------- | --------------- | --------------------------------------------------------- | -| `adminEmail` | string | 博主邮箱地址，用于显示“博主”标识以及管理员身份验证 | +| `adminEmail` | string | 博主邮箱地址，用于显示"博主"标识以及管理员身份验证 | | `adminBadge` | string | 博主标识文字，例如 `"博主"` | | `avatarPrefix` | string | 头像地址前缀，如 Gravatar 或 Cravatar 镜像地址 | | `adminEnabled` | boolean | 是否启用博主标识相关展示 | | `allowedDomains` | Array\ | 允许调用组件的域名列表，留空则不限制 | | `adminKey` | string\|null | 管理员评论密钥（明文），仅通过管理后台接口返回 | -| `adminKeySet` | boolean | 是否已经设置过管理员评论密钥 | +| `adminKeySet` | boolean | 是否已经设置过管理员管理员评论密钥 | | `requireReview` | boolean | 是否开启新评论先审核再显示（true 表示新评论默认为待审核） | | `blockedIps` | Array\ | IP 黑名单列表，匹配到的 IP 提交评论将被拒绝 | | `blockedEmails` | Array\ | 邮箱黑名单列表，匹配到的邮箱提交评论将被拒绝 | @@ -521,7 +676,7 @@ GET /admin/settings/comments } ``` -## 更新评论配置 +### 4.2 更新评论配置 ``` PUT /admin/settings/comments @@ -599,16 +754,51 @@ PUT /admin/settings/comments } ``` -## 将指定 IP 加入评论黑名单 +### 4.3 获取通知邮箱配置（已废弃） ``` -POST /admin/comments/block-ip +GET /admin/settings/email ``` -通过接口将指定 IP 地址加入评论黑名单，后续该 IP 提交评论将被拒绝。 +获取当前通知邮箱配置。 -- 方法：`POST` -- 路径：`/admin/comments/block-ip` +> [!NOTE] +> 此接口已被 `/admin/settings/email-notify` 替代，建议使用新接口获取完整的邮件通知配置。 + +- 方法：`GET` +- 路径：`/admin/settings/email` +- 鉴权：需要（Bearer Token） + +**成功响应** + +- 状态码：`200` + +```json +{ + "email": "admin@example.com" +} +``` + +**错误响应** + +- 状态码：`500` + +```json +{ + "message": "错误信息" +} +``` + +### 4.4 设置通知邮箱（已废弃） + +``` +PUT /admin/settings/email +``` + +设置通知邮箱，用于接收新评论提醒。 + +- 方法：`PUT` +- 路径：`/admin/settings/email` - 鉴权：需要（Bearer Token） **请求头** @@ -621,99 +811,22 @@ POST /admin/comments/block-ip ```json { - "ip": "1.1.1.1" + "email": "admin@example.com" } ``` -字段说明： - -| 字段名 | 类型 | 必填 | 说明 | -| ------ | ------ | ---- | ------------------------------------------------ | -| `ip` | string | 是 | 要加入黑名单的 IP 地址，多个 IP 用逗号或换行分隔 | - **成功响应** - 状态码：`200` ```json { - "message": "已加入 IP 黑名单" + "message": "保存成功" } ``` **错误响应** -- IP 为空： - - 状态码：`400` - - ```json - { - "message": "IP 地址不能为空" - } - ``` - -- 内部错误： - - 状态码：`500` - - ```json - { - "message": "操作失败" - } - ``` - -## 将指定邮箱加入评论黑名单 - -``` -POST /admin/comments/block-email -``` - -通过接口将指定邮箱地址加入评论黑名单，后续该邮箱提交评论将被拒绝。 - -- 方法：`POST` -- 路径：`/admin/comments/block-email` -- 鉴权：需要（Bearer Token） - -**请求头** - -| 名称 | 必填 | 示例 | -| -------------- | ---- | ------------------ | -| `Content-Type` | 是 | `application/json` | - -**请求体** - -```json -{ - "email": "spam@example.com" -} -``` - -字段说明： - -| 字段名 | 类型 | 必填 | 说明 | -| ------- | ------ | ---- | ------------------------------------------------ | -| `email` | string | 是 | 要加入黑名单的邮箱地址，多个邮箱用逗号或换行分隔 | - -**成功响应** - -- 状态码：`200` - -```json -{ - "message": "已加入邮箱黑名单" -} -``` - -**错误响应** - -- 邮箱为空： - - 状态码：`400` - - ```json - { - "message": "邮箱不能为空" - } - ``` - - 邮箱格式不正确： - 状态码：`400` @@ -723,16 +836,250 @@ POST /admin/comments/block-email } ``` -- 内部错误： +- 服务器错误： - 状态码：`500` ```json { - "message": "操作失败" + "message": "错误信息" } ``` -## 获取评论统计数据（数据看板） +## 5. 邮件通知配置相关 + +### 5.1 获取邮件通知配置 + +``` +GET /admin/settings/email-notify +``` + +获取邮件通知配置，包括 SMTP 配置和邮件模板。 + +- 方法：`GET` +- 路径：`/admin/settings/email-notify` +- 鉴权：需要（Bearer Token） + +**成功响应** + +- 状态码：`200` + +```json +{ + "globalEnabled": true, + "smtp": { + "host": "smtp.qq.com", + "port": 465, + "user": "noreply@qq.com", + "pass": "", + "secure": true + }, + "templates": { + "reply": "回复评论的邮件模板 HTML", + "admin": "新评论通知的邮件模板 HTML" + } +} +``` + +字段说明： + +| 字段名 | 类型 | 说明 | +| -------------- | ------- | ------------------------------------------------------------ | +| `globalEnabled` | boolean | 是否全局启用邮件通知 | +| `smtp.host` | string | SMTP 服务器地址，默认 `smtp.qq.com` | +| `smtp.port` | number | SMTP 服务器端口，默认 `465` | +| `smtp.user` | string | SMTP 用户名（发件邮箱） | +| `smtp.pass` | string | SMTP 密码（脱敏显示，不返回完整密码） | +| `smtp.secure` | boolean | 是否使用 SSL/TLS，默认 `true` | +| `templates.reply` | string | 回复评论时的邮件模板，支持变量占位符 | +| `templates.admin` | string | 新评论通知的邮件模板，支持变量占位符 | + +**邮件模板变量** + +回复评论模板（`templates.reply`）支持的变量： + +| 变量名 | 说明 | +| ----------------- | ------------ | +| `${toEmail}` | 收件人邮箱 | +| `${toName}` | 收件人昵称 | +| `${postTitle}` | 文章标题 | +| `${parentComment}` | 被回复的评论内容 | +| `${replyAuthor}` | 回复者昵称 | +| `${replyContent}` | 回复内容 | +| `${postUrl}` | 文章链接 | + +新评论通知模板（`templates.admin`）支持的变量： + +| 变量名 | 说明 | +| ----------------- | ------------ | +| `${postTitle}` | 文章标题 | +| `${postUrl}` | 文章链接 | +| `${commentAuthor}` | 评论者昵称 | +| `${commentContent}` | 评论内容 | + +**错误响应** + +- 状态码：`500` + +```json +{ + "message": "错误信息" +} +``` + +### 5.2 更新邮件通知配置 + +``` +PUT /admin/settings/email-notify +``` + +更新邮件通知配置，包括 SMTP 配置和邮件模板。 + +- 方法：`PUT` +- 路径：`/admin/settings/email-notify` +- 鉴权：需要（Bearer Token） + +**请求头** + +| 名称 | 必填 | 示例 | +| -------------- | ---- | ------------------ | +| `Content-Type` | 是 | `application/json` | + +**请求体** + +```json +{ + "globalEnabled": true, + "smtp": { + "host": "smtp.qq.com", + "port": 465, + "user": "noreply@qq.com", + "pass": "your_password", + "secure": true + }, + "templates": { + "reply": "
    ...
    ", + "admin": "
    ...
    " + } +} +``` + +字段说明： + +| 字段名 | 类型 | 必填 | 说明 | +| -------------- | ------- | ---- | ------------------------------------------------------------ | +| `globalEnabled` | boolean | 否 | 是否全局启用邮件通知 | +| `smtp` | object | 否 | SMTP 配置对象 | +| `smtp.host` | string | 否 | SMTP 服务器地址 | +| `smtp.port` | number | 否 | SMTP 服务器端口 | +| `smtp.user` | string | 否 | SMTP 用户名（发件邮箱） | +| `smtp.pass` | string | 否 | SMTP 密码 | +| `smtp.secure` | boolean | 否 | 是否使用 SSL/TLS | +| `templates` | object | 否 | 邮件模板对象 | +| `templates.reply` | string | 否 | 回复评论的邮件模板 HTML | +| `templates.admin` | string | 否 | 新评论通知的邮件模板 HTML | + +**成功响应** + +- 状态码：`200` + +```json +{ + "message": "保存成功" +} +``` + +**错误响应** + +- 状态码：`500` + +```json +{ + "message": "保存失败" +} +``` + +### 5.3 测试邮件发送 + +``` +POST /admin/settings/email-test +``` + +测试邮件通知配置是否正确，发送一封测试邮件到指定邮箱。 + +- 方法：`POST` +- 路径：`/admin/settings/email-test` +- 鉴权：需要（Bearer Token） + +**请求头** + +| 名称 | 必填 | 示例 | +| -------------- | ---- | ------------------ | +| `Content-Type` | 是 | `application/json` | + +**请求体** + +```json +{ + "toEmail": "test@example.com", + "smtp": { + "host": "smtp.qq.com", + "port": 465, + "user": "noreply@qq.com", + "pass": "your_password", + "secure": true + } +} +``` + +字段说明： + +| 字段名 | 类型 | 必填 | 说明 | +| ----------- | ------ | ---- | ------------------------------------ | +| `toEmail` | string | 是 | 接收测试邮件的邮箱地址 | +| `smtp` | object | 是 | SMTP 配置对象（与更新配置接口相同） | + +**成功响应** + +- 状态码：`200` + +```json +{ + "message": "邮件发送成功" +} +``` + +**错误响应** + +- 接收邮箱无效： + - 状态码：`400` + + ```json + { + "message": "请输入有效的接收邮箱" + } + ``` + +- SMTP 配置不完整： + - 状态码：`400` + + ```json + { + "message": "SMTP 配置不完整" + } + ``` + +- 邮件发送失败： + - 状态码：`500` + + ```json + { + "message": "邮件发送失败: 具体错误信息" + } + ``` + +## 6. 统计数据相关 + +### 6.1 获取评论统计数据（数据看板） ``` GET /admin/stats/comments diff --git a/docs/api/public.md b/docs/api/public.md index e9cec90..34405a4 100644 --- a/docs/api/public.md +++ b/docs/api/public.md @@ -1,16 +1,18 @@ # 公开 API -无需认证即可访问的公开接口，包括评论获取、评论提交以及评论设置获取。 +无需认证即可访问的公开接口，包括评论获取、评论提交、配置获取和身份验证。 包含路径、方法、参数、请求体和响应示例。 -## 获取指定文章的评论列表 +## 1. 评论相关 + +### 1.1 获取指定文章的评论列表 ``` GET /api/comments ``` -获取指定文章的评论列表。 +获取指定文章的评论列表，支持分页和嵌套结构。 - 方法：`GET` - 路径：`/api/comments` @@ -42,6 +44,7 @@ GET /api/comments "pubDate": "2026-01-13T10:00:00Z", "postSlug": "/blog/hello-world", "avatar": "https://gravatar.com/avatar/...", + "priority": 2, "replies": [ { "id": 2, @@ -54,7 +57,8 @@ GET /api/comments "postSlug": "/blog/hello-world", "avatar": "https://gravatar.com/avatar/...", "parentId": 1, - "replyToAuthor": "张三" + "replyToAuthor": "张三", + "priority": 1 } ] } @@ -70,8 +74,9 @@ GET /api/comments 说明： -- 当 `nested=true`（默认）时，接口返回的是“根评论列表”，每条根评论包含其 `replies`。 +- 当 `nested=true`（默认）时，接口返回的是"根评论列表"，每条根评论包含其 `replies`。 - 当 `nested=false` 时，接口返回扁平列表，所有评论都在 `data` 中，`replies` 为空。 +- `priority` 字段：评论的置顶权重，数值越大排序越靠前。 **错误响应** @@ -95,7 +100,7 @@ GET /api/comments } ``` -## 提交新评论或回复 +### 1.2 提交新评论或回复 ``` POST /api/comments @@ -124,11 +129,12 @@ POST /api/comments "email": "zhangsan@example.com", "url": "https://zhangsan.me", "content": "很棒的文章！", - "parent_id": 1 + "parent_id": 1, + "adminToken": "your-admin-key" } ``` -**字段说明** +字段说明： | 字段名 | 类型 | 必填 | 说明 | | ------------ | ------ | ---- | ------------------------------------------------------------------------------------------------------------- | @@ -140,20 +146,31 @@ POST /api/comments | `url` | string | 否 | 评论者个人主页或站点地址 | | `content` | string | 是 | 评论内容，内部会过滤 `` 片段 | | `parent_id` | number | 否 | 父评论 ID，用于回复功能；缺省或 `null` 表示根评论 | +| `adminToken` | string | 否 | 管理员评论密钥，博主发布评论时需要先通过 `/api/verify-admin` 验证密钥后将密钥传入此字段，评论将直接通过且不受审核设置影响 | **成功响应** - 状态码：`200` +评论直接通过时： + ```json { - "message": "Comment submitted. Awaiting moderation." + "message": "评论已提交", + "status": "approved" } ``` -当前实现中评论会直接以 `approved` 状态写入数据库，后续如引入人工审核可在实现中调整为“待审核”状态。 +评论进入待审核状态时（开启"先审核再显示"且非管理员评论）： -**错误响应**与限流 +```json +{ + "message": "已提交评论，待管理员审核后显示", + "status": "pending" +} +``` + +**错误响应** - 请求体缺失或字段类型错误： @@ -165,7 +182,7 @@ POST /api/comments } ``` -- 缺少必填字段示例： +- 缺少必填字段： - `post_slug` 为空： @@ -207,6 +224,56 @@ POST /api/comments } ``` +- IP 或邮箱被限制： + + - IP 被限制： + - 状态码：`403` + + ```json + { + "message": "当前 IP 已被限制评论，请联系站长进行处理" + } + ``` + + - 邮箱被限制： + - 状态码：`403` + + ```json + { + "message": "当前邮箱已被限制评论，请联系站长进行处理" + } + ``` + +- 管理员评论验证失败： + + - 未输入密钥： + - 状态码：`401` + + ```json + { + "message": "请输入管理员密钥", + "requireAuth": true + } + ``` + + - 密钥错误： + - 状态码：`401` + + ```json + { + "message": "密钥错误" + } + ``` + + - 验证失败次数过多： + - 状态码：`403` + + ```json + { + "message": "验证失败次数过多，请30分钟后再试" + } + ``` + - 评论频率限制： - 状态码：`429` @@ -214,7 +281,7 @@ POST /api/comments ```json { - "message": "评论频繁，等 10s 后再试" + "message": "评论频繁，等10s后再试" } ``` @@ -228,7 +295,9 @@ POST /api/comments } ``` -## 获取评论相关的公开配置 +## 2. 配置相关 + +### 2.1 获取评论相关的公开配置 ``` GET /api/config/comments @@ -248,7 +317,7 @@ GET /api/config/comments { "adminEmail": "admin@example.com", "adminBadge": "博主", - "avatarPrefix": "https://gravatar.com/avatar", + "avatar": "https://gravatar.com/avatar", "adminEnabled": true, "allowedDomains": [], "requireReview": false @@ -259,7 +328,7 @@ GET /api/config/comments | 字段名 | 类型 | 说明 | | -------------- | ------- | -------------------------------------------------------------------- | -| `adminEmail` | string | 博主邮箱地址，用于在前端展示“博主”标识，并触发管理员身份验证流程 | +| `adminEmail` | string | 博主邮箱地址，用于在前端展示"博主"标识，并触发管理员身份验证流程 | | `adminBadge` | string | 博主标识文字，例如 `"博主"` | | `avatarPrefix` | string | 头像地址前缀，如 Gravatar 或 Cravatar 镜像地址 | | `adminEnabled` | boolean | 是否启用博主标识相关展示（关闭时不显示徽标，但仍可作为管理员邮箱） | @@ -275,3 +344,80 @@ GET /api/config/comments "message": "加载评论配置失败" } ``` + +## 3. 身份验证相关 + +### 3.1 验证管理员密钥 + +``` +POST /api/verify-admin +``` + +验证前台管理员评论所需的密钥，用于博主发布评论时的身份验证。 + +- 方法：`POST` +- 路径：`/api/verify-admin` +- 鉴权：不需要 + +**请求头** + +| 名称 | 必填 | 示例 | +| -------------- | ---- | ------------------ | +| `Content-Type` | 是 | `application/json` | + +**请求体** + +```json +{ + "adminToken": "your-admin-key" +} +``` + +字段说明： + +| 字段名 | 类型 | 必填 | 说明 | +| ----------- | ------ | ---- | -------------- | +| `adminToken` | string | 是 | 管理员评论密钥 | + +**风控说明** + +- 同一 IP 连续验证失败 3 次后，该 IP 将被锁定 30 分钟 +- 失败次数记录有效期为 1 小时 + +**成功响应** + +- 状态码：`200` + +```json +{ + "message": "验证通过" +} +``` + +或未设置密钥时： + +```json +{ + "message": "未设置管理员密钥" +} +``` + +**错误响应** + +- 寽钥错误： + - 状态码：`401` + + ```json + { + "message": "密钥错误" + } + ``` + +- 验证失败次数过多： + - 状态码：`403` + + ```json + { + "message": "验证失败次数过多，请30分钟后再试" + } + ``` diff --git a/docs/function/admin-panel.md b/docs/function/admin-panel.md index 4ed280a..aba8103 100644 --- a/docs/function/admin-panel.md +++ b/docs/function/admin-panel.md @@ -18,6 +18,70 @@ 开启是否显示博主标签，配置博主邮箱和标签文字，即可在评论中显示博主标签；关闭为不显示。 +### 管理员评论密钥 + +设置管理员评论密钥后，博主在前台发布评论时需要输入此密钥进行身份验证，评论将被直接通过，不受"先审核再显示"设置的影响。 + +**注意**： +- 同一 IP 连续验证失败 3 次后，该 IP 将被锁定 30 分钟 +- 失败次数记录有效期为 1 小时 + +### 评论置顶 + +在评论管理页面，点击"编辑"按钮可修改评论的置顶权重： + +- `1`：不置顶（默认值） +- `2` 或更高：数值越大，该评论在列表中排序越靠前 + +置顶后的评论会在前台评论列表中优先显示。 + +### 邮件通知配置 + +在设置页面可以配置邮件通知功能，包括： + +#### 全局开关 + +控制是否启用邮件通知功能。 + +#### SMTP 配置 + +| 字段 | 说明 | 示例 | +| ------- | -------------------------------- | ----------------- | +| 主机 | SMTP 服务器地址 | `smtp.qq.com` | +| 端口 | SMTP 服务器端口 | `465` | +| 用户名 | 发件邮箱 | `noreply@qq.com` | +| 密码 | 邮箱密码或授权码 | `your_password` | +| 安全连接 | 是否使用 SSL/TLS | `true` | + +#### 邮件模板 + +支持自定义 HTML 邮件模板，包含以下变量： + +**回复评论模板变量**： + +| 变量名 | 说明 | +| ----------------- | ------------ | +| `${toEmail}` | 收件人邮箱 | +| `${toName}` | 收件人昵称 | +| `${postTitle}` | 文章标题 | +| `${parentComment}` | 被回复的评论内容 | +| `${replyAuthor}` | 回复者昵称 | +| `${replyContent}` | 回复内容 | +| `${postUrl}` | 文章链接 | + +**新评论通知模板变量**： + +| 变量名 | 说明 | +| ----------------- | ------------ | +| `${postTitle}` | 文章标题 | +| `${postUrl}` | 文章链接 | +| `${commentAuthor}` | 评论者昵称 | +| `${commentContent}` | 评论内容 | + +#### 测试邮件 + +配置完成后，可以使用"测试邮件"功能发送一封测试邮件到指定邮箱，验证配置是否正确。 + ## 使用官方管理后台 使用官方提供的管理后台（最新版本）https://cwd.zishu.me