# 飞书数据同步工具

这个工具提供了与飞书多维表格进行数据同步的功能，支持双向同步：从飞书导入数据到数据库，以及从数据库导出数据到飞书。同时支持将达人数据同步到外部知识库。

## 功能特点

- 从飞书多维表格导入数据到数据库
- 从Excel文件更新数据库记录
- 从数据库导出数据到飞书多维表格
- 从特定数据库模型导入数据到飞书
- 从自定义SQL查询导入数据到飞书
- 将达人信息同步到外部知识库
- 支持Gmail和飞书达人信息的统一管理
- 支持自定义字段映射
- 支持记录过滤和数量限制

## 使用方法

### 显示帮助信息

```bash
python feishu.py help
```

### 从飞书导入数据到数据库

```bash
python feishu.py sync_from_feishu
```

### 从Excel文件更新数据库记录

```bash
python feishu.py update_from_excel <excel文件路径>
```

### 从数据库导出数据到飞书多维表格

```bash
python feishu.py export_to_feishu [--handle 关键字] [--limit 数量]
```

例如，导出Handle包含"tiktok"的前10条记录：

```bash
python feishu.py export_to_feishu --handle tiktok --limit 10
```

### 从特定数据库模型导入数据到飞书

```bash
python feishu.py import_from_db <模型名称> [--filters 字段1=值1,字段2=值2,...] [--limit 数量]
```

支持的模型：
- Data：数据模型
- KnowledgeBase：知识库模型
- FeishuCreator：飞书创作者模型

例如，导入技术部的管理员数据：

```bash
python feishu.py import_from_db Data --filters type=admin,department=技术部 --limit 50
```

### 从自定义SQL查询导入数据到飞书

```bash
python feishu.py custom_import <sql_file>
```

SQL文件格式示例：

```sql
-- 查询语句
SELECT id, name, type FROM your_table WHERE condition;

-- FIELD_MAPPING:
{
    "id": "飞书ID字段",
    "name": "飞书名称字段",
    "type": "飞书类型字段"
}
```

### 将达人信息同步到知识库

```bash
python feishu.py sync_to_kb --id <creator_id> | --handle <handle> | --email <email>
```

例如，同步特定达人信息到知识库：

```bash
python feishu.py sync_to_kb --handle tiktok_user123
```

## 示例

在`examples`目录中提供了几个示例文件：

- `custom_query.sql`：自定义SQL查询示例，包含字段映射
- `creator_kb_query.sql`：查询达人信息并检查知识库映射的SQL示例
- `sample_data_template.txt`：Excel导入模板说明

## REST API接口

除了命令行工具外，还提供了以下REST API接口：

### 1. 飞书数据同步API

```
POST /api/feishu/sync
```

参数：
- `sync_type` (可选)：同步类型，默认为"all"
- `handle` (可选)：指定特定的达人Handle
- `create_kb` (可选)：是否创建知识库，默认为false

### 2. 达人信息同步到知识库API

```
POST /api/feishu/to_kb
```

参数：
- `creator_id`、`handle`或`email`：至少提供一个参数用于识别达人

### 3. 检查达人知识库API

```
POST /api/feishu/check_kb
```

参数：
- `creator_id`、`handle`或`email`：至少提供一个参数用于识别达人

## 与Gmail集成

本工具支持与Gmail系统集成，实现达人信息的统一管理：

1. 当通过飞书同步达人信息到知识库时，会检查该达人是否已有Gmail映射
2. 如果该达人邮箱已有Gmail映射，则使用现有知识库
3. 如果没有映射，则创建新的知识库并建立映射关系
4. 知识库文档采用追加模式，保留历史记录

## 配置

飞书API配置位于代码中，包括：

- APP_TOKEN：飞书应用的AppToken
- TABLE_ID：飞书多维表格的TableID
- USER_ACCESS_TOKEN：用户访问令牌

如需修改这些配置，请编辑相应的函数中的变量。

## 注意事项

1. 确保已安装所需的依赖：`lark_oapi`, `pandas`, `django`等
2. 在执行数据库操作前，确保数据库连接已正确配置
3. 自定义SQL查询应避免执行修改数据的操作(INSERT, UPDATE, DELETE等)
4. 导入大量数据时，可能需要分批处理，使用`--limit`参数控制数量
5. 创建知识库需要管理员权限，确保有可用的管理员账号

## 常见问题

### Q: 导入数据时出现字段不匹配错误？

A: 确保字段名称与飞书多维表格中的字段名称完全匹配，或使用字段映射功能。

### Q: 如何添加新的数据模型支持？

A: 在`import_from_database_to_feishu`函数中添加新的模型映射，并按照现有模式实现字段映射逻辑。

### Q: 如何处理Gmail和飞书同一个达人的数据合并？

A: 系统会自动检查达人邮箱，如果在Gmail中已有映射，会使用同一个知识库，避免重复创建。