Feishu Bitable

# 飞书多维表格使用场景完整示例

本文档提供多维表格操作的完整场景示例，包括参数说明和注意事项。

> **基础参考**: 先查阅 [字段 Property 配置详解](field-properties.md) 和 [记录值数据结构详解](record-values.md)

---

## 📋 目录

1. [场景 0: 创建数据表（两种模式对比）](#场景-0-创建数据表两种模式对比)
2. [场景 1: 查字段类型（必做第一步）](#场景-1-查字段类型必做第一步)
3. [场景 2: 批量导入客户数据](#场景-2-批量导入客户数据)
4. [场景 2.5: 创建表并插入数据（含空行处理）](#场景-25-创建表并插入数据含空行处理)
5. [场景 3: 筛选查询（高级筛选）](#场景-3-筛选查询高级筛选)
6. [场景 4: 更新单条记录](#场景-4-更新单条记录)
7. [场景 5: 创建带选项的单选字段](#场景-5-创建带选项的单选字段)
8. [场景 6: 创建复杂字段（进度、货币、评分）](#场景-6-创建复杂字段进度货币评分)
9. [场景 7: 处理附件字段](#场景-7-处理附件字段)
10. [场景 8: 双向关联字段](#场景-8-双向关联字段)

---

## 场景 0: 创建数据表（两种模式对比）

### 模式 A：一次性定义所有字段

**适用场景**：字段类型、配置都已明确，需要快速创建表结构。

**优势**：一次 API 调用，原子性操作。

**工具**: `feishu_bitable_app_table`

```json
{
  "action": "create",
  "app_token": "S404b...",
  "table": {
    "name": "客户管理表",
    "default_view_name": "所有客户",
    "fields": [
      {
        "field_name": "客户名称",
        "type": 1
      },
      {
        "field_name": "负责人",
        "type": 11,
        "property": {
          "multiple": false
        }
      },
      {
        "field_name": "签约日期",
        "type": 5,
        "property": {
          "date_formatter": "yyyy-MM-dd"
        }
      },
      {
        "field_name": "状态",
        "type": 3,
        "property": {
          "options": [
            {"name": "进行中", "color": 0},
            {"name": "已完成", "color": 10}
          ]
        }
      },
      {
        "field_name": "金额",
        "type": 2,
        "ui_type": "Currency",
        "property": {
          "currency_code": "CNY",
          "formatter": "0.00"
        }
      }
    ]
  }
}
```

**返回示例**:
```json
{
  "table_id": "tblXXXXXXXX",
  "name": "客户管理表",
  "default_view_id": "vewXXXXXXXX"
}
```

---

### 模式 B：使用默认表 + 逐步修改字段

**适用场景**：探索式建表，需要边建边调整，或复杂字段配置需要分步确认。

**优势**：
- `app.create` 自带默认表和默认字段，可在此基础上调整
- 复杂字段（单选 options、URL 格式等）分步确认，减少出错
- 踩坑后容易回退（比如 URL 字段改为文本字段）

**完整流程**：

#### 步骤 1: 创建 App（工具: `feishu_bitable_app`）

```json
{
  "action": "create",
  "name": "客户管理系统",
  "folder_token": "fldXXXXXXXX"
}
```

**返回**: 包含 `app_token` 和默认表的 `default_table_id`

---

#### 步骤 2: 查看默认字段（工具: `feishu_bitable_app_table_field`）

```json
{
  "action": "list",
  "app_token": "S404b...",
  "table_id": "tblXXXXXXXX"
}
```

**返回示例**:
```json
{
  "fields": [
    {
      "field_id": "fld001",
      "field_name": "文本",
      "type": 1,
      "ui_type": "Text"
    },
    {
      "field_id": "fld002",
      "field_name": "数字",
      "type": 2,
      "ui_type": "Number"
    }
  ]
}
```

---

#### 步骤 3: 修改默认字段名称（工具: `feishu_bitable_app_table_field`）

```json
{
  "action": "update",
  "app_token": "S404b...",
  "table_id": "tblXXXXXXXX",
  "field_id": "fld001",
  "field_name": "客户名称"
}
```

---

#### 步骤 4: 补充缺失字段（工具: `feishu_bitable_app_table_field`）

```json
{
  "action": "create",
  "app_token": "S404b...",
  "table_id": "tblXXXXXXXX",
  "field_name": "负责人",
  "type": 11,
  "property": {
    "multiple": false
  }
}
```

---

#### 步骤 5: 查看空记录（工具: `feishu_bitable_app_table_record`）

```json
{
  "action": "list",
  "app_token": "S404b...",
  "table_id": "tblXXXXXXXX"
}
```

**返回**: 可能包含空记录 `[{"record_id": "recxxx", "fields": {}}, ...]`

---

#### 步骤 6: 删除空行（工具: `feishu_bitable_app_table_record`）

```json
{
  "action": "batch_delete",
  "app_token": "S404b...",
  "table_id": "tblXXXXXXXX",
  "records": ["recxxx", "recyyy"]
}
```

---

#### 步骤 7: 批量插入数据（工具: `feishu_bitable_app_table_record`）

```json
{
  "action": "batch_create",
  "app_token": "S404b...",
  "table_id": "tblXXXXXXXX",
  "records": [
    {
      "fields": {
        "客户名称": "Bytedance",
        "负责人": [{"id": "ou_xxx"}],
        "状态": "进行中"
      }
    }
  ]
}
```

---

**⚠️ 模式 B 的关键注意事项**:
- 默认表中通常已有空记录，**必须先删除**，否则会有数据污染
- 步骤 5-6 是必需的，不能跳过
- 适合不确定字段配置的探索式场景

---

## 场景 1: 查字段类型（必做第一步）

**为什么必做**: 不同字段类型的值格式完全不同，必须先查询再写入。

**工具**: `feishu_bitable_app_table_field`

```json
{
  "action": "list",
  "app_token": "S404b...",
  "table_id": "tblXXXXXXXX"
}
```

**返回示例**:
```json
{
  "fields": [
    {
      "field_id":