留言管理系统设计文档

概述

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

核心功能

1. 留言列表管理

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

2. 留言回复功能

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

3. 留言状态管理

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

4. 留言删除功能

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

5. 页面跳转功能

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

权限控制

访问权限

• 仅超级管理员可访问：留言管理功能需要超级管理员权限
• 路由级别权限控制：通过 requireAuth: [ROLE_SUPER_ADMIN] 配置
• 后端接口权限控制：所有留言管理接口都需要超级管理员权限验证

操作权限

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

数据库设计

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

mail（留言表）

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

主要字段：

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

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

业务流程

1. 查看留言列表

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

2. 回复留言

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

3. 修改留言状态

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

4. 删除留言

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

5. 查看来源页面

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

API 接口

1. 获取留言列表

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

请求参数：

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

响应数据：

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

2. 回复留言

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

请求参数：

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

响应数据：

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

3. 更新留言状态

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

请求参数：

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

响应数据：

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

4. 删除留言

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

请求参数：

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

响应数据：

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

主要涉及文件列表

前端文件

• 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/controllers/mails.mts - 留言相关控制器
• src/models/Mail.mts - 留言数据模型

类型定义文件

• typings/mail.d.ts - 留言类型定义

技术实现要点

1. 类型安全

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

2. 用户体验优化

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

3. 安全性

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

4. 代码规范

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

注意事项

1. 邮件发送：回复留言时会自动发送邮件通知用户，需要确保邮件服务配置正确
2. 软删除：删除留言是软删除，只是将状态设置为 deleted，不会真正删除数据
3. 状态管理：状态只能修改为 todo 或 done，不能直接修改为 deleted（需要通过删除操作）
4. 页面链接验证：查看来源页面时会验证链接是否以 http 开头，确保链接有效