# 飞书多维表格自动AI对话 API接口文档

本文档描述了飞书多维表格自动AI对话功能的REST API接口。

## 基本信息

- 基础URL: `/api/feishu/`
- 认证方式: JWT Token (需要在请求头中添加 `Authorization: Bearer <token>`)
- 请求方式: POST/GET
- 返回格式: JSON

## 注意事项

1. 请确保使用正确的URL路径：完整路径为 `/api/feishu/process-table/` 而非 `/api/v1/feishu/process-table/`
2. 飞书授权令牌有效期较短，为了避免授权问题，请在请求中提供正确的 `app_id` 和 `app_secret` 参数:
   ```json
   {
     "table_id": "your_table_id",
     "view_id": "your_view_id",
     "app_id": "cli_a5c97daacb9e500d",
     "app_secret": "fdVeOCLXmuIHZVmSV0VbJh9wd0Kq1o5y"
   }
   ```
3. 查看运行日志中的错误信息，根据错误代码进行故障排除

## 接口列表

### 1. 处理飞书表格数据

从飞书多维表格读取数据，处理重复邮箱，可选择性地进行自动对话。

- **URL**: `/api/feishu/process-table/`
- **方法**: `POST`
- **权限**: 仅限组长角色
- **请求参数**:

| 参数名 | 类型 | 必需 | 描述 |
|--------|------|------|------|
| table_id | string | 是 | 表格ID |
| view_id | string | 是 | 视图ID |
| app_token | string | 否 | 飞书应用TOKEN |
| access_token | string | 否 | 用户访问令牌 |
| goal_template | string | 否 | 目标内容模板 |
| auto_chat | boolean | 否 | 是否自动执行AI对话 |
| turns | integer | 否 | 自动对话轮次 |

- **请求示例**:

```json
{
  "table_id": "tbl3oikG3F8YYtVA",
  "view_id": "vewSOIsmxc",
  "app_id": "cli_a5c97daacb9e500d",
  "app_secret": "fdVeOCLXmuIHZVmSV0VbJh9wd0Kq1o5y",
  "goal_template": "与达人{handle}(邮箱:{email})建立联系，最终目标是达成合作。",
  "auto_chat": true,
  "turns": 5
}
```

- **成功响应**:

```json
{
  "status": "success",
  "records_count": 100,
  "duplicate_emails_count": 5,
  "processing_results": {
    "total": 5,
    "success": 4,
    "failure": 1,
    "details": [
      {
        "email": "example1@gmail.com",
        "handle": "example1",
        "status": "success"
      },
      // ...其他处理结果
    ]
  },
  "chat_results": [
    {
      "email": "example1@gmail.com",
      "result": {
        "status": "success",
        "turns_completed": 5,
        "goal_achieved": true,
        "summary_status": "success",
        "conversation_id": "feishu_ai_12345"
      }
    }
    // ...其他自动对话结果
  ]
}
```

### 2. 执行自动对话

为指定邮箱的达人执行自动对话，支持真实邮件发送和接收。

- **URL**: `/api/feishu/auto-chat/`
- **方法**: `POST`
- **权限**: 仅限组长角色
- **请求参数**:

| 参数名 | 类型 | 必需 | 描述 |
|--------|------|------|------|
| email | string | 是 | 达人邮箱 |
| force_send | boolean | 否 | 是否强制发送新邮件(即使没有新回复) |
| subject | string | 否 | 邮件主题(仅当force_send=true时使用) |
| content | string | 否 | 邮件内容(仅当force_send=true时使用) |

- **请求示例 (自动回复)**:

```json
{
  "email": "example@gmail.com"
}
```

- **请求示例 (强制发送)**:

```json
{
  "email": "example@gmail.com",
  "force_send": true,
  "subject": "关于合作细节的讨论",
  "content": "您好，\n\n针对您提出的问题，我们可以提供以下方案...\n\n期待您的回复。\n\n祝好，\n运营团队"
}
```

- **成功响应**:

```json
{
  "status": "success",
  "email_sent": true,
  "turns_completed": 1,
  "goal_achieved": false,
  "summary_status": "not_needed",
  "conversation_id": "feishu_ai_12345"
}
```

- **待回复响应** (没有检测到新的达人回复):

```json
{
  "status": "success",
  "message": "没有新的达人回复，不需要回复",
  "turns_completed": 0,
  "goal_achieved": false,
  "email_sent": false,
  "conversation_id": "feishu_ai_12345"
}
```

### 3. 设置用户总目标

设置针对特定达人的对话总目标。

- **URL**: `/api/feishu/user-goal/`
- **方法**: `POST`
- **权限**: 仅限组长角色
- **请求参数**:

| 参数名 | 类型 | 必需 | 描述 |
|--------|------|------|------|
| email | string | 是 | 达人邮箱 |
| goal | string | 是 | 目标内容 |

- **请求示例**:

```json
{
  "email": "example@gmail.com",
  "goal": "与达人建立联系并了解其账号情况，评估合作潜力，处理合作需求，最终目标是达成合作并签约。"
}
```

- **成功响应**:

```json
{
  "status": "success",
  "action": "create",
  "goal": {
    "id": "12345",
    "content": "与达人建立联系并了解其账号情况，评估合作潜力，处理合作需求，最终目标是达成合作并签约。",
    "created_at": "2024-01-01 12:00:00",
    "updated_at": "2024-01-01 12:00:00"
  }
}
```

### 4. 获取用户总目标

获取当前用户的总目标设置。

- **URL**: `/api/feishu/user-goal/`
- **方法**: `GET`
- **权限**: 仅限组长角色
- **请求参数**: 无

- **成功响应**:

```json
{
  "status": "success",
  "action": "retrieve",
  "goal": {
    "id": "12345",
    "content": "与达人建立联系并了解其账号情况，评估合作潜力，处理合作需求，最终目标是达成合作并签约。",
    "created_at": "2024-01-01 12:00:00",
    "updated_at": "2024-01-01 12:00:00"
  }
}
```

### 5. 检查目标完成状态

检查与特定达人的对话是否已达成目标。

- **URL**: `/api/feishu/check-goal/`
- **方法**: `GET`
- **权限**: 仅限组长角色
- **请求参数**:

| 参数名 | 类型 | 必需 | 描述 |
|--------|------|------|------|
| email | string | 是 | 达人邮箱 |

- **请求示例**:

```
GET /api/feishu/check-goal/?email=example@gmail.com
```

- **成功响应**:

```json
{
  "status": "success",
  "email": "example@gmail.com",
  "goal_achieved": true,
  "last_message_time": "2024-01-01 12:00:00",
  "last_message": "好的，我们已经确认了合作细节。期待与您的成功合作！[目标已达成]",
  "summary": "本次对话主要讨论了合作条款和细节。达成了产品发布时间、价格区间、佣金比例等共识。双方已同意合作，下一步将签署正式合同。"
}
```

## 错误响应

所有接口在出错时会返回统一格式的错误信息：

```json
{
  "error": "错误描述信息"
}
```

常见HTTP状态码：

- 400: 请求参数错误
- 403: 权限不足
- 404: 资源不存在
- 500: 服务器内部错误

## 使用示例

### 使用curl命令

```bash
# 获取授权令牌
TOKEN=$(curl -s -X POST http://yourserver.com/api/auth/login/ -d '{"username":"admin","password":"yourpassword"}' -H "Content-Type: application/json" | jq -r '.token')

# 处理飞书表格数据
curl -X POST http://yourserver.com/api/feishu/process-table/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "table_id":"tbl3oikG3F8YYtVA",
    "view_id":"vewSOIsmxc",
    "app_id":"cli_a5c97daacb9e500d",
    "app_secret":"fdVeOCLXmuIHZVmSV0VbJh9wd0Kq1o5y",
    "auto_chat":true
  }'

# 检查目标完成状态
curl -X GET "http://yourserver.com/api/feishu/check-goal/?email=example@gmail.com" \
  -H "Authorization: Bearer $TOKEN"
```

### 使用JavaScript

```javascript
// 获取授权令牌
async function getToken() {
  const response = await fetch('http://yourserver.com/api/auth/login/', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      username: 'admin',
      password: 'yourpassword'
    }),
  });
  const data = await response.json();
  return data.token;
}

// 处理飞书表格数据
async function processFeishuTable() {
  const token = await getToken();
  const response = await fetch('http://yourserver.com/api/feishu/process-table/', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      table_id: 'tbl3oikG3F8YYtVA',
      view_id: 'vewSOIsmxc',
      app_id: 'cli_a5c97daacb9e500d',
      app_secret: 'fdVeOCLXmuIHZVmSV0VbJh9wd0Kq1o5y',
      auto_chat: true
    }),
  });
  const data = await response.json();
  console.log(data);
}

processFeishuTable();
``` 