# 联系我们 API 接口文档

## 基本信息

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

## 1. 提交联系表单

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

### 请求参数

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

### 成功响应 (201)

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

### 错误响应 (400)

```json
{
  "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)

```json
{
  "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)

```json
{
  "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`
- **描述**: 更新联系记录的处理状态

### 请求示例

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

### 成功响应 (200)

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

## 5. 删除联系记录

### 接口信息
- **URL**: `/contact/delete/:id`
- **方法**: `DELETE`
- **描述**: 根据ID删除联系记录

### 请求示例

```
DELETE /contact/delete/1
```

### 成功响应 (200)

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

## 前端集成示例

### JavaScript/Fetch 示例

```javascript
// 提交联系表单
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 示例

```jsx
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**: 服务器内部错误，联系后端开发人员