峰云CMS建站系统

外观

留言管理系统设计文档 ​

概述 ​

留言管理系统是后台管理系统的核心模块之一，专为超级管理员设计，提供用户留言查看、回复、状态管理等功能。系统采用 Vue3 + Element Plus + TypeScript 技术栈开发，确保类型安全和良好的用户体验。

核心功能 ​

1. Dashboard 入口 ​

  • 在管理后台仪表盘中显示留言管理入口卡片
  • 实时显示待处理留言数量
  • 点击卡片可直接跳转到留言管理页面
  • 卡片样式与其他功能模块保持一致

2. 留言列表管理 ​

  • 留言列表展示（分页）
  • 按关键词搜索（搜索留言内容）
  • 按状态筛选（全部、待处理、已完成、已删除）
  • 留言信息展示（ID、用户称呼、邮箱、留言内容、来源页面、回复内容、状态、创建时间）

3. 留言回复功能 ​

  • 查看留言详情（用户称呼、邮箱、留言内容）
  • 回复留言（支持多行文本，最大2000字符）
  • 回复后自动发送邮件通知用户
  • 回复内容保存到数据库

3. 留言状态管理 ​

  • 查看留言当前状态
  • 修改留言状态（todo-待处理、done-已完成）
  • 状态修改前确认提示
  • 状态修改后自动刷新列表

4. 留言删除功能 ​

  • 软删除留言（将状态设置为 deleted）
  • 删除前确认提示
  • 删除后自动刷新列表

5. 页面跳转功能 ​

  • 查看留言来源页面（如果存在有效链接）
  • 新窗口打开页面链接

6. 公开留言表单 ​

  • 在网站底部（footer）提供留言表单
  • 用户无需登录即可提交留言
  • 自动记录留言来源页面信息（页面标题和URL）
  • 表单验证（称呼、邮箱格式、留言内容）
  • 提交成功后显示提示信息并清空表单

权限控制 ​

访问权限 ​

  • 仅超级管理员可访问：留言管理功能需要超级管理员权限
  • 路由级别权限控制：通过 requireAuth: [ROLE_SUPER_ADMIN] 配置
  • 后端接口权限控制：所有留言管理接口都需要超级管理员权限验证
  • 公开留言接口：创建留言接口（/api/mails/create-mail）为公开接口，无需认证

操作权限 ​

  • 留言回复：仅超级管理员可回复留言
  • 状态修改：仅超级管理员可修改留言状态
  • 留言删除：仅超级管理员可删除留言

数据库设计 ​

留言管理系统主要使用以下数据表：

mail（留言表） ​

存储用户留言的基本信息。

主要字段：

  • id: 主键，自增
  • name: 用户称呼（varchar(255)，非空）
  • email: 用户邮箱（varchar(255)，非空）
  • message: 用户发送的信息（text，非空）
  • page_title: 来源页面标题（varchar(255)，默认为空）
  • page_url: 来源页面URL（varchar(500)，默认为空）
  • reply: 回复内容（text，可为空）
  • status: 邮件处理状态（enum: todo-待处理, done-已完成, deleted-已删除，默认 todo）
  • created_at: 创建时间
  • updated_at: 更新时间

详细字段说明请参考 数据库设计文档。

业务流程 ​

1. 从 Dashboard 进入留言管理 ​

1. 超级管理员登录后台管理系统
2. 进入管理后台仪表盘
3. 查看"留言管理"卡片，显示待处理留言数量
4. 点击"留言管理"卡片
5. 系统跳转到留言管理页面

2. 查看留言列表 ​

1. 超级管理员登录后台管理系统
2. 点击"留言管理"或从仪表盘进入
3. 系统显示留言列表（分页，默认每页20条）
4. 可输入关键词进行搜索（搜索留言内容）
5. 可选择状态进行筛选（全部、待处理、已完成、已删除）
6. 系统返回匹配的留言列表

3. 回复留言 ​

1. 在留言列表中点击"回复"按钮
2. 弹出回复对话框
3. 显示留言详情（用户称呼、邮箱、留言内容）
4. 输入回复内容（必填，最大2000字符）
5. 点击"确认回复"
6. 系统验证回复内容（不能为空，不能超过2000字符）
7. 发送邮件通知用户
8. 保存回复内容到数据库
9. 刷新留言列表

4. 修改留言状态 ​

1. 在留言列表的状态列中选择新状态
2. 弹出确认对话框
3. 确认修改
4. 系统更新留言状态
5. 刷新留言列表

5. 删除留言 ​

1. 在留言列表中点击"删除"按钮
2. 弹出确认对话框
3. 确认删除
4. 系统将留言状态设置为 deleted（软删除）
5. 刷新留言列表

6. 查看来源页面 ​

1. 在留言列表中点击"查看页面"按钮
2. 系统验证页面链接是否有效（必须以 http 开头）
3. 在新窗口打开页面链接

7. 用户提交留言 ​

1. 用户在网站任意页面滚动到底部
2. 看到留言表单板块（视觉上独立的紫色渐变背景）
3. 填写称呼、邮箱、留言内容
4. 点击"提交留言"按钮
5. 系统验证表单数据（称呼不能为空、邮箱格式、留言内容不能为空）
6. 自动获取当前页面标题和URL
7. 提交到服务器创建留言记录
8. 显示成功提示信息
9. 清空表单

API 接口 ​

1. 获取留言列表 ​

接口路径： GET /api/mails/mails

请求参数：

typescript
{
  pageNo?: number;      // 页码，默认1
  pageSize?: number;    // 每页数量，默认10
  keyword?: string;     // 关键词（搜索留言内容）
  status?: string;       // 状态筛选（"" | "todo" | "done" | "deleted"）
}

响应数据：

typescript
{
  list: Mail[];         // 留言列表
  total: number;        // 总记录数
  pageNum: number;      // 当前页码
  pageSize: number;      // 每页数量
}

2. 回复留言 ​

接口路径： POST /api/mails/reply-mail

请求参数：

typescript
{
  id: number; // 留言ID
  reply: string; // 回复内容
}

响应数据：

typescript
{
  code: 200;
  message: "Reply successfully";
  data: null;
}

3. 更新留言状态 ​

接口路径： POST /api/mails/update-mail-status

请求参数：

typescript
{
  id: number; // 留言ID
  status: "todo" | "done"; // 新状态
}

响应数据：

typescript
{
  code: 200;
  message: "Update successfully";
  data: null;
}

4. 删除留言 ​

接口路径： POST /api/mails/delete-mail

请求参数：

typescript
{
  id: string; // 留言ID（字符串类型）
}

响应数据：

typescript
{
  code: 200;
  message: "Deleted successfully";
  data: null;
}

5. 创建留言（公开接口） ​

接口路径： POST /api/mails/create-mail

权限要求： 无需认证，公开接口

请求参数：

typescript
{
  name: string;           // 用户称呼（必填，1-255字符）
  email: string;          // 用户邮箱（必填，邮箱格式，最大255字符）
  message: string;        // 留言内容（必填）
  page_title?: string;    // 来源页面标题（可选，自动获取）
  page_url?: string;      // 来源页面URL（可选，自动获取）
}

响应数据：

typescript
{
  code: 200;
  message: "留言提交成功";
  data: {
    id: number; // 留言ID
    message: string; // 成功提示信息
  }
}

主要涉及文件列表 ​

前端文件 ​

  • apps/admin/src/views/DashboardView/DashboardView.vue - 仪表盘页面（包含留言管理入口）
  • apps/admin/src/views/MailsView/MailsView.vue - 留言管理主页面
  • apps/admin/src/components/MailReplyDialog/MailReplyDialog.vue - 回复留言对话框组件
  • apps/admin/src/api/mails.ts - 留言相关 API 接口
  • apps/admin/src/router/index.ts - 路由配置（添加留言管理路由）

后端文件 ​

  • src/routes/mails.mts - 留言相关路由
  • src/routes/admin.mts - 管理后台路由（包含 dashboard 接口）
  • src/controllers/mails.mts - 留言相关控制器
  • src/controllers/admin.mts - 管理后台控制器（包含 dashboard 数据获取）
  • src/services/mail.mts - 留言服务层（包含获取待处理留言数）
  • src/models/Mail.mts - 留言数据模型

前端公开页面文件 ​

  • views/_parts/footer.ejs - 底部组件（包含留言表单）
  • public/js/mail-form.mjs - 留言表单提交处理脚本

类型定义文件 ​

  • typings/mail.d.ts - 留言类型定义
  • typings/admin.d.ts - 管理后台类型定义（包含 dashboard 返回数据类型）

技术实现要点 ​

1. 类型安全 ​

  • 所有 API 接口都有完整的 TypeScript 类型定义
  • 使用 zod 进行请求参数验证
  • 前后端类型保持一致

2. 用户体验优化 ​

  • 分页加载，支持每页数量自定义
  • 搜索和筛选功能，快速定位目标留言
  • 状态修改和删除操作都有确认提示
  • 回复内容有字符限制和字数统计
  • 操作成功后自动刷新列表

3. 安全性 ​

  • 所有接口都需要超级管理员权限验证
  • 输入内容进行验证和过滤
  • 邮件发送使用事务保证数据一致性

4. 代码规范 ​

  • 使用 Composition API 和 <script setup lang="ts">
  • 组件拆分合理（回复对话框独立组件）
  • 代码结构清晰，易于维护

注意事项 ​

  1. 邮件发送：回复留言时会自动发送邮件通知用户，需要确保邮件服务配置正确
  2. 软删除：删除留言是软删除，只是将状态设置为 deleted，不会真正删除数据
  3. 状态管理：状态只能修改为 todo 或 done，不能直接修改为 deleted（需要通过删除操作）
  4. 页面链接验证：查看来源页面时会验证链接是否以 http 开头，确保链接有效
  5. 公开留言接口：创建留言接口为公开接口，不需要认证，但需要进行输入验证和防刷保护
  6. 页面信息自动获取：如果前端未提供 page_title 和 page_url，后端会尝试从请求头中获取 referer 信息
  7. 留言表单样式：留言表单使用独立的视觉设计（紫色渐变背景），位于网站底部，在所有使用 footer 组件的页面都会显示

中小微企业级建站程序。十年Web开发经验提炼而成，基于Vue3+Node.js，功能强大，支持多种业务场景。

Copyright © 2023-2025 峰云CMS建站系统 版权所有。保留一切权利。
浙ICP备18053953号-13