# 联系记录接口文档

## 1. 查询联系记录列表

### 接口信息
- **URL**: `/api/contacts`
- **方法**: `GET`
- **认证**: 需要登录（Header 携带 Authorization）

### 请求参数

| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| page | integer | 否 | 页码，默认 1 | 1 |
| page_size | integer | 否 | 每页数量，默认 10 | 20 |
| search | string | 否 | 搜索关键词（姓名/岗位/联系方式） | 张三 |
| reply_status | string | 否 | 回复状态筛选 | 已回复 |
| wechat_exchanged | boolean | 否 | 是否交换微信 | true |
| start_date | string | 否 | 开始日期（YYYY-MM-DD） | 2024-01-01 |
| end_date | string | 否 | 结束日期（YYYY-MM-DD） | 2024-12-31 |

### 请求示例

```bash
# 基础查询
GET /api/contacts?page=1&page_size=20

# 关键词搜索
GET /api/contacts?search=张三

# 按回复状态筛选
GET /api/contacts?reply_status=已回复

# 按时间范围筛选
GET /api/contacts?start_date=2024-01-01&end_date=2024-12-31

# 组合筛选
GET /api/contacts?search=产品经理&reply_status=已回复&wechat_exchanged=true&start_date=2024-01-01&end_date=2024-12-31
```

### 响应示例

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "total": 150,
    "page": 1,
    "page_size": 20,
    "results": [
      {
        "id": 1,
        "name": "张三",
        "position": "产品经理",
        "contact": "13800138000",
        "reply_status": "已回复",
        "wechat_exchanged": true,
        "account_id": 1,
        "worker_id": "worker-001",
        "notes": "沟通顺畅，有意向",
        "contacted_at": "2024-03-01T10:30:00",
        "created_at": "2024-03-01T10:00:00"
      },
      {
        "id": 2,
        "name": "李四",
        "position": "前端工程师",
        "contact": "wechat:lisi123",
        "reply_status": "未回复",
        "wechat_exchanged": false,
        "account_id": 2,
        "worker_id": "worker-002",
        "notes": "",
        "contacted_at": "2024-03-02T14:20:00",
        "created_at": "2024-03-02T14:00:00"
      }
    ]
  }
}
```

---

## 2. 导出联系记录为 Excel

### 接口信息
- **URL**: `/api/contacts/export`
- **方法**: `GET`
- **认证**: 需要登录（Header 携带 Authorization）
- **响应类型**: `application/json`（返回下载链接）

### 请求参数

| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| search | string | 否 | 搜索关键词（姓名/岗位/联系方式） | 张三 |
| reply_status | string | 否 | 回复状态筛选 | 已回复 |
| wechat_exchanged | boolean | 否 | 是否交换微信 | true |
| start_date | string | 否 | 开始日期（YYYY-MM-DD） | 2024-01-01 |
| end_date | string | 否 | 结束日期（YYYY-MM-DD） | 2024-12-31 |

### 请求示例

```bash
# 导出所有联系记录
GET /api/contacts/export

# 导出指定时间段的记录
GET /api/contacts/export?start_date=2024-01-01&end_date=2024-12-31

# 导出已回复且交换微信的记录
GET /api/contacts/export?reply_status=已回复&wechat_exchanged=true

# 导出组合筛选结果
GET /api/contacts/export?search=产品经理&start_date=2024-01-01&end_date=2024-03-31&reply_status=已回复
```

### 响应示例

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "download_url": "http://127.0.0.1:8000/media/exports/contacts_export_20240304_153045_a1b2c3d4.xlsx",
    "filename": "contacts_export_20240304_153045_a1b2c3d4.xlsx",
    "total_records": 150,
    "generated_at": "2024-03-04 15:30:45"
  }
}
```

### 响应字段说明

| 字段名 | 类型 | 说明 |
|--------|------|------|
| download_url | string | 文件下载链接（完整 URL） |
| filename | string | 生成的文件名 |
| total_records | integer | 导出的记录总数 |
| generated_at | string | 文件生成时间 |

### Excel 文件格式

**表头**（蓝色背景，白色粗体文字）:

| 列名 | 说明 | 示例 |
|------|------|------|
| ID | 记录 ID | 1 |
| 姓名 | 联系人姓名 | 张三 |
| 岗位 | 应聘岗位 | 产品经理 |
| 联系方式 | 电话或微信 | 13800138000 |
| 回复状态 | 回复状态 | 已回复 |
| 是否交换微信 | 是/否 | 是 |
| Worker ID | Worker 标识 | worker-001 |
| 备注 | 备注信息 | 沟通顺畅，有意向 |
| 联系时间 | 联系时间 | 2024-03-01 10:30:00 |
| 创建时间 | 创建时间 | 2024-03-01 10:00:00 |

### 前端调用示例

```javascript
// 使用 axios
const exportContacts = async (params) => {
  try {
    const response = await axios.get('/api/contacts/export', {
      params: params,
      headers: {
        'Authorization': `Bearer ${token}`
      }
    });
    
    if (response.data.code === 200) {
      const { download_url, filename, total_records } = response.data.data;
      
      // 方式1：直接打开下载链接
      window.open(download_url, '_blank');
      
      // 方式2：使用 a 标签下载
      const link = document.createElement('a');
      link.href = download_url;
      link.download = filename;
      document.body.appendChild(link);
      link.click();
      document.body.removeChild(link);
      
      // 提示用户
      console.log(`成功导出 ${total_records} 条记录`);
    }
  } catch (error) {
    console.error('导出失败:', error);
  }
};

// 调用示例
exportContacts({
  start_date: '2024-01-01',
  end_date: '2024-12-31',
  reply_status: '已回复'
});
```

```javascript
// 使用 fetch
const exportContacts = async (params) => {
  const queryString = new URLSearchParams(params).toString();
  
  try {
    const response = await fetch(`/api/contacts/export?${queryString}`, {
      headers: {
        'Authorization': `Bearer ${token}`
      }
    });
    
    const result = await response.json();
    
    if (result.code === 200) {
      const { download_url, filename, total_records } = result.data;
      
      // 直接下载文件
      const link = document.createElement('a');
      link.href = download_url;
      link.download = filename;
      link.click();
      
      alert(`成功导出 ${total_records} 条记录`);
    }
  } catch (error) {
    console.error('导出失败:', error);
  }
};
```

```vue
<!-- Vue 3 组件示例 -->
<template>
  <button @click="handleExport" :loading="exporting">
    导出 Excel
  </button>
</template>

<script setup>
import { ref } from 'vue';
import axios from 'axios';

const exporting = ref(false);

const handleExport = async () => {
  exporting.value = true;
  
  try {
    const response = await axios.get('/api/contacts/export', {
      params: {
        start_date: '2024-01-01',
        end_date: '2024-12-31'
      }
    });
    
    if (response.data.code === 200) {
      const { download_url, total_records } = response.data.data;
      
      // 下载文件
      window.open(download_url, '_blank');
      
      // 显示成功提示
      ElMessage.success(`成功导出 ${total_records} 条记录`);
    }
  } catch (error) {
    ElMessage.error('导出失败，请重试');
  } finally {
    exporting.value = false;
  }
};
</script>
```

---

## 错误码说明

| 错误码 | 说明 |
|--------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未登录或 token 无效 |
| 500 | 服务器内部错误 |

## 注意事项

1. **时间筛选**：
   - `start_date` 从当天 00:00:00 开始
   - `end_date` 到当天 23:59:59 结束
   - 时间筛选基于 `created_at` 字段（创建时间）

2. **搜索功能**：
   - `search` 参数支持模糊匹配
   - 同时搜索姓名、岗位、联系方式三个字段

3. **导出机制**：
   - 导出接口返回下载链接，不直接返回文件流
   - 文件保存在服务器 `media/exports/` 目录
   - 文件名格式：`contacts_export_{时间戳}_{随机ID}.xlsx`
   - 导出接口不分页，会导出所有符合条件的记录
   - 建议在导出大量数据时添加时间范围限制

4. **文件管理**：
   - 导出的文件会保存在服务器上
   - 建议定期清理过期的导出文件
   - 可以通过定时任务删除超过一定时间的文件

5. **认证要求**：
   - 所有接口都需要在 Header 中携带 `Authorization` token
   - token 格式：`Bearer <token>`

6. **下载链接**：
   - 返回的 `download_url` 是可直接访问的完整下载 URL
   - 前端可直接 `window.open(download_url)` 或 `a.href = download_url` 下载