feiniao-site-node/docs/FRONTEND_API_GUIDE.md

联系我们 API 接口文档

基本信息

• 开发环境: http://localhost:3000
• 生产环境: https://api.feiniao.com (待配置)
• Content-Type: application/json

1. 提交联系表单

接口信息

• URL: /contact/submit
• 方法: POST
• 描述: 用户提交联系我们表单，系统会保存到数据库并自动发送邮件通知

请求参数

{
  "name": "张三",           // 必填：联系人姓名
  "email": "user@example.com", // 必填：联系人邮箱
  "phone": "13800138000",    // 可选：联系电话
  "company": "某某科技公司",   // 可选：公司名称
  "subject": "产品咨询",      // 必填：留言主题
  "message": "我想了解产品详情" // 必填：留言内容
}

成功响应 (201)

{
  "success": true,
  "message": {
    "id": 1,
    "message": "感谢您的留言，我们已收到并会在24小时内回复"
  },
  "data": "留言提交成功，我们会尽快回复您"
}

错误响应 (400)

{
  "success": false,
  "message": "参数验证失败",
  "error": [
    "联系人姓名不能为空",
    "邮箱格式不正确"
  ]
}

2. 获取联系记录列表 (管理员用)

接口信息

• URL: /contact/list
• 方法: GET
• 描述: 获取联系我们留言列表，支持分页和状态筛选

请求参数 (Query)

GET /contact/list?page=1&limit=10&status=0

• page: 页码 (默认: 1)
• limit: 每页数量 (默认: 10)
• status: 处理状态 (0-未处理, 1-已处理)

成功响应 (200)

{
  "success": true,
  "message": {
    "contacts": [
      {
        "id": 1,
        "name": "张三",
        "email": "user@example.com",
        "phone": "13800138000",
        "company": "某某科技公司",
        "subject": "产品咨询",
        "message": "我想了解产品详情",
        "status": 0,
        "isEmailSent": true,
        "createdAt": "2025-09-19T09:27:05.000Z",
        "updatedAt": "2025-09-19T09:27:06.000Z"
      }
    ],
    "pagination": {
      "total": 25,
      "page": 1,
      "limit": 10,
      "totalPages": 3
    }
  },
  "data": "获取成功"
}

3. 获取联系详情

接口信息

• URL: /contact/detail/:id
• 方法: GET
• 描述: 根据ID获取具体的联系记录详情

请求示例

GET /contact/detail/1

成功响应 (200)

{
  "success": true,
  "message": "获取成功",
  "data": {
    "id": 1,
    "name": "张三",
    "email": "user@example.com",
    "phone": "13800138000",
    "company": "某某科技公司",
    "subject": "产品咨询",
    "message": "我想了解产品详情",
    "status": 0,
    "isEmailSent": true,
    "createdAt": "2025-09-19T09:27:05.000Z",
    "updatedAt": "2025-09-19T09:27:06.000Z"
  }
}

4. 更新处理状态

接口信息

• URL: /contact/update/:id/status
• 方法: PUT
• 描述: 更新联系记录的处理状态

请求示例

PUT /contact/update/1/status
{
  "status": 1  // 0-未处理, 1-已处理
}

成功响应 (200)

{
  "success": true,
  "message": "状态更新成功",
  "data": {
    "id": 1,
    "status": 1,
    // ... 其他字段
  }
}

5. 删除联系记录

接口信息

• URL: /contact/delete/:id
• 方法: DELETE
• 描述: 根据ID删除联系记录

请求示例

DELETE /contact/delete/1

成功响应 (200)

{
  "success": true,
  "message": "删除成功",
  "data": null
}

前端集成示例

JavaScript/Fetch 示例

// 提交联系表单
async function submitContact(formData) {
  try {
    const response = await fetch('http://localhost:3000/contact/submit', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(formData)
    });
    
    const result = await response.json();
    
    if (result.success) {
      console.log('提交成功:', result.message);
      // 显示成功消息给用户
    } else {
      console.error('提交失败:', result.error);
      // 显示错误消息给用户
    }
  } catch (error) {
    console.error('网络错误:', error);
  }
}

// 使用示例
const contactData = {
  name: '张三',
  email: 'zhangsan@example.com',
  phone: '13800138000',
  company: '某某科技公司',
  subject: '产品咨询',
  message: '我想了解一下你们的产品价格和功能特点。'
};

submitContact(contactData);

React 示例

import { useState } from 'react';

function ContactForm() {
  const [formData, setFormData] = useState({
    name: '',
    email: '',
    phone: '',
    company: '',
    subject: '',
    message: ''
  });
  const [loading, setLoading] = useState(false);
  const [message, setMessage] = useState('');

  const handleSubmit = async (e) => {
    e.preventDefault();
    setLoading(true);
    
    try {
      const response = await fetch('http://localhost:3000/contact/submit', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(formData)
      });
      
      const result = await response.json();
      
      if (result.success) {
        setMessage('留言提交成功，我们会尽快回复您！');
        setFormData({ name: '', email: '', phone: '', company: '', subject: '', message: '' });
      } else {
        setMessage('提交失败：' + (result.error?.join(', ') || result.message));
      }
    } catch (error) {
      setMessage('网络错误，请稍后重试');
    } finally {
      setLoading(false);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      {/* 表单字段 */}
      <input
        type="text"
        placeholder="姓名 *"
        value={formData.name}
        onChange={(e) => setFormData({...formData, name: e.target.value})}
        required
      />
      <input
        type="email"
        placeholder="邮箱 *"
        value={formData.email}
        onChange={(e) => setFormData({...formData, email: e.target.value})}
        required
      />
      {/* 其他字段... */}
      
      <button type="submit" disabled={loading}>
        {loading ? '提交中...' : '提交留言'}
      </button>
      
      {message && <p>{message}</p>}
    </form>
  );
}

注意事项

1. 必填字段: name, email, subject, message
2. 邮箱格式: 必须是有效的邮箱格式
3. 自动邮件: 提交成功后会自动发送通知邮件给管理员和自动回复给用户
4. 状态码: 成功201，客户端错误400，服务器错误500
5. CORS: 如果前后端不同域，需要配置CORS

错误处理

• 400: 参数验证失败，检查必填字段和格式
• 404: 记录不存在（查询/更新/删除时）
• 500: 服务器内部错误，联系后端开发人员