学习追踪系统

Appearance

联系请求管理 API ​

概述 ​

联系请求管理模块提供了用户联系管理员的功能，包括申请提交、状态管理和筛选功能。支持多种申请类型，具备防垃圾信息机制和频率限制。

功能特性 ​

  • 📝 申请提交 - 用户可提交联系管理员申请
  • 🔍 状态管理 - 支持待处理、已查看、已解决三种状态
  • 🛡️ 安全防护 - 垃圾信息检测、频率限制、验证码验证
  • 📊 统计分析 - 实时统计各状态申请数量
  • 🔄 实时筛选 - 支持按状态和申请类型筛选
  • 📄 分页显示 - 支持分页浏览申请列表

API 接口 ​

1. 提交联系申请 ​

接口地址: POST /api/contact/submit

功能描述: 用户提交联系管理员申请

请求参数:

参数名类型必填说明
namestring是申请人姓名（2-50字符）
emailstring是邮箱地址
phonestring否手机号码（中国格式）
subjectstring是申请类型
messagestring是详细说明（1-1000字符）
captchastring是验证码（4位字符）

申请类型 (subject):

  • account_registration - 申请注册账户
  • password_reset - 密码重置申请
  • technical_support - 技术支持
  • feature_request - 功能建议
  • other - 其他问题

请求示例:

json
{
  "name": "张三",
  "email": "zhangsan@example.com",
  "phone": "13800138000",
  "subject": "account_registration",
  "message": "希望申请注册账户，用于学习追踪",
  "captcha": "A1B2"
}

响应示例:

json
{
  "success": true,
  "message": "申请已提交，管理员将在24小时内回复您",
  "requestId": 123
}

错误响应:

json
{
  "success": false,
  "message": "输入验证失败：姓名长度必须在2-50个字符之间；请输入有效的邮箱地址",
  "errors": [
    {
      "field": "name",
      "msg": "姓名长度必须在2-50个字符之间"
    }
  ]
}

2. 获取联系请求列表 ​

接口地址: GET /api/admin/contact-requests

功能描述: 管理员获取联系请求列表（需要管理员权限）

请求参数:

参数名类型必填默认值说明
pagenumber否1页码
limitnumber否10每页数量
statusstring否all状态筛选
subjectstring否all申请类型筛选

状态筛选 (status):

  • all - 全部状态
  • pending - 待处理
  • reviewed - 已查看
  • resolved - 已解决

申请类型筛选 (subject):

  • all - 全部类型
  • account_registration - 申请注册账户
  • password_reset - 密码重置申请
  • technical_support - 技术支持
  • feature_request - 功能建议
  • other - 其他问题

请求示例:

GET /api/admin/contact-requests?page=1&limit=20&status=pending&subject=account_registration

响应示例:

json
{
  "success": true,
  "data": {
    "requests": [
      {
        "id": 1,
        "name": "张三",
        "email": "zhangsan@example.com",
        "phone": "13800138000",
        "subject": "account_registration",
        "message": "希望申请注册账户，用于学习追踪",
        "status": "pending",
        "admin_note": null,
        "ip_address": "192.168.1.100",
        "user_agent": "Mozilla/5.0...",
        "created_at": "2025-09-09T14:56:14.000Z",
        "updated_at": "2025-09-09T14:56:14.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 5,
      "pages": 1
    },
    "stats": {
      "pending": 3,
      "reviewed": 1,
      "resolved": 1,
      "total": 5
    }
  }
}

3. 更新联系请求状态 ​

接口地址: PUT /api/admin/contact-requests/:id/status

功能描述: 管理员更新联系请求状态（需要管理员权限）

路径参数:

  • id - 联系请求ID

请求参数:

参数名类型必填说明
statusstring是新状态
adminNotestring否管理员备注

状态值 (status):

  • pending - 待处理
  • reviewed - 已查看
  • resolved - 已解决

请求示例:

json
{
  "status": "reviewed",
  "adminNote": "已查看申请，正在处理中"
}

响应示例:

json
{
  "success": true,
  "message": "状态更新成功",
  "data": {
    "id": 1,
    "name": "张三",
    "email": "zhangsan@example.com",
    "status": "reviewed",
    "admin_note": "已查看申请，正在处理中",
    "updated_at": "2025-09-09T15:30:00.000Z"
  }
}

4. 删除联系请求 ​

接口地址: DELETE /api/admin/contact-requests/:id

功能描述: 管理员删除联系请求（需要管理员权限）

路径参数:

  • id - 联系请求ID

响应示例:

json
{
  "success": true,
  "message": "联系请求已删除"
}

安全机制 ​

1. 频率限制 ​

  • 每小时最多5次申请提交
  • 基于IP地址和邮箱地址限制

2. 垃圾信息检测 ​

自动检测并拒绝包含以下关键词的申请：

  • 广告、推广、营销相关词汇
  • 违法、诈骗、传销相关词汇
  • 色情、暴力、政治相关词汇

3. 输入验证 ​

  • 姓名：2-50个字符
  • 邮箱：有效邮箱格式
  • 手机：中国手机号格式（可选）
  • 申请类型：预定义类型之一
  • 详细说明：1-1000个字符
  • 验证码：4位字母数字组合

4. 重复提交检测 ​

  • 同一邮箱1小时内只能提交一次申请
  • 基于邮箱地址和创建时间判断

状态流转 ​

待处理 (pending) → 已查看 (reviewed) → 已解决 (resolved)
  • 待处理: 新提交的申请
  • 已查看: 管理员已查看但未处理完成
  • 已解决: 申请已处理完成

错误码说明 ​

错误码说明
400请求参数错误
401未授权访问
403权限不足
404资源不存在
429请求过于频繁
500服务器内部错误

使用示例 ​

JavaScript 前端调用示例 ​

javascript
// 提交联系申请
async function submitContactRequest(formData) {
  try {
    const response = await fetch('/api/contact/submit', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(formData)
    });
    
    const result = await response.json();
    
    if (result.success) {
      alert('申请提交成功！');
    } else {
      alert('提交失败：' + result.message);
    }
  } catch (error) {
    console.error('提交申请时出错：', error);
  }
}

// 获取联系请求列表
async function loadContactRequests(page = 1, status = 'all', subject = 'all') {
  try {
    const response = await fetch(
      `/api/admin/contact-requests?page=${page}&status=${status}&subject=${subject}`
    );
    
    const result = await response.json();
    
    if (result.success) {
      return result.data;
    } else {
      throw new Error(result.message);
    }
  } catch (error) {
    console.error('获取联系请求列表时出错：', error);
    throw error;
  }
}

// 更新申请状态
async function updateRequestStatus(requestId, status, adminNote = '') {
  try {
    const response = await fetch(`/api/admin/contact-requests/${requestId}/status`, {
      method: 'PUT',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ status, adminNote })
    });
    
    const result = await response.json();
    
    if (result.success) {
      alert('状态更新成功！');
    } else {
      alert('更新失败：' + result.message);
    }
  } catch (error) {
    console.error('更新状态时出错：', error);
  }
}

注意事项 ​

  1. 权限要求: 管理接口需要管理员权限
  2. 频率限制: 用户提交申请有频率限制，避免滥用
  3. 数据安全: 所有输入都经过验证和清理
  4. 日志记录: 重要操作会记录安全日志
  5. 状态管理: 申请状态只能按顺序流转，不能回退

更新日志 ​

  • 2025-09-09: 初始版本发布
    • 实现联系申请提交功能
    • 实现管理员状态管理功能
    • 实现实时筛选和分页功能
    • 添加安全防护机制

Released under the MIT License.

Copyright © 2024-present Study Tracker Team