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

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

> **基础参考**: 先查阅 [字段 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": {
        "客户名称": "字节跳动",
        "负责人": [{"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": "fld001",
      "field_name": "任务名称",
      "type": 1,
      "ui_type": "Text",
      "property": {}
    },
    {
      "field_id": "fld002",
      "field_name": "负责人",
      "type": 11,
      "ui_type": "User",
      "property": {
        "multiple": true
      }
    },
    {
      "field_id": "fld003",
      "field_name": "截止日期",
      "type": 5,
      "ui_type": "DateTime",
      "property": {
        "date_formatter": "yyyy-MM-dd HH:mm"
      }
    },
    {
      "field_id": "fld004",
      "field_name": "状态",
      "type": 3,
      "ui_type": "SingleSelect",
      "property": {
        "options": [
          {"id": "optXXX", "name": "进行中", "color": 0},
          {"id": "optYYY", "name": "已完成", "color": 10}
        ]
      }
    }
  ]
}
```

**关键信息**:
- `type`: 字段基础类型（1=文本, 2=数字, 3=单选...）
- `ui_type`: UI 展示类型（区分进度、货币、评分等）
- `property`: 字段配置（单选的 options、日期的 formatter 等）

---

## 场景 2: 批量导入客户数据

**工具**: `feishu_bitable_app_table_record`

```json
{
  "action": "batch_create",
  "app_token": "S404b...",
  "table_id": "tblXXXXXXXX",
  "records": [
    {
      "fields": {
        "客户名称": "字节跳动",
        "负责人": [{"id": "ou_8240099442cf5da49f04f4bf8f8abcef"}],
        "签约日期": 1674206443000,
        "状态": "进行中",
        "金额": 1000000,
        "标签": ["重要客户", "战略合作"],
        "联系电话": "17899870000",
        "官网": {
          "text": "字节跳动官网",
          "link": "https://www.bytedance.com"
        }
      }
    },
    {
      "fields": {
        "客户名称": "飞书",
        "负责人": [{"id": "ou_xxx"}],
        "签约日期": 1675416243000,
        "状态": "已完成",
        "金额": 500000,
        "标签": ["核心产品"],
        "联系电话": "13800138000"
      }
    }
  ]
}
```

**字段值格式说明**:
- **文本**: 字符串 `"客户名称"`
- **人员**: 对象数组 `[{"id": "ou_xxx"}]`（只能传 id）
- **日期**: 毫秒时间戳 `1674206443000`
- **单选**: 字符串 `"进行中"`
- **多选**: 字符串数组 `["重要客户", "战略合作"]`
- **数字**: 数字 `1000000`
- **电话**: 字符串 `"17899870000"`
- **超链接**: 对象 `{"text": "显示文本", "link": "URL"}`

**返回示例**:
```json
{
  "records": [
    {
      "record_id": "rec001",
      "fields": {...}
    },
    {
      "record_id": "rec002",
      "fields": {...}
    }
  ]
}
```

**限制**:
- 单次最多 500 条记录
- 超过需分批调用

---

## 场景 2.5: 创建表并插入数据（含空行处理）

**问题**: `app.create` 创建的默认表中会自带空记录（空行），直接插入数据会导致数据污染。

**正确流程**: 见场景 0 的模式 B

**核心步骤**:
1. 创建 App → 获取 `app_token` 和 `default_table_id`
2. 查看默认表记录 (`list` action)
3. 删除空行 (`batch_delete` action)
4. 批量插入数据 (`batch_create` action)

**错误示例**（跳过步骤 2-3）:
```
表格最终状态：
| 客户名称 | 负责人 | 状态 |
|---------|--------|------|
|         |        |      | ← 空行（原有）
| 字节跳动 | 张三   | 进行中 | ← 新插入
| 飞书    | 李四   | 已完成 | ← 新插入
```

**正确示例**（执行步骤 2-3）:
```
表格最终状态：
| 客户名称 | 负责人 | 状态 |
|---------|--------|------|
| 字节跳动 | 张三   | 进行中 |
| 飞书    | 李四   | 已完成 |
```

---

## 场景 3: 筛选查询（高级筛选）

**工具**: `feishu_bitable_app_table_record`

```json
{
  "action": "list",
  "app_token": "S404b...",
  "table_id": "tblXXXXXXXX",
  "filter": {
    "conjunction": "and",
    "conditions": [
      {
        "field_name": "状态",
        "operator": "is",
        "value": ["进行中"]
      },
      {
        "field_name": "截止日期",
        "operator": "isLess",
        "value": ["ExactDate", "1740441600000"]
      },
      {
        "field_name": "优先级",
        "operator": "isGreater",
        "value": ["3"]
      }
    ]
  },
  "sort": [
    {
      "field_name": "截止日期",
      "desc": false
    },
    {
      "field_name": "优先级",
      "desc": true
    }
  ],
  "field_names": ["任务名称", "负责人", "截止日期", "状态"],
  "page_size": 100
}
```

**参数说明**:

### filter 结构
- `conjunction`: 条件组合方式（`"and"` 或 `"or"`）
- `conditions`: 条件数组

### operator 类型（10 种）

| operator | 含义 | 支持字段 | value 格式 |
|----------|------|----------|-----------|
| `is` | 等于 | 所有 | `["值"]` |
| `isNot` | 不等于 | 除日期外 | `["值"]` |
| `contains` | 包含 | 除日期外 | `["值1", "值2"]` |
| `doesNotContain` | 不包含 | 除日期外 | `["值1"]` |
| `isEmpty` | 为空 | 所有 | `[]` |
| `isNotEmpty` | 不为空 | 所有 | `[]` |
| `isGreater` | 大于 | 数字、日期 | `["值"]` |
| `isGreaterEqual` | 大于等于 | 数字 | `["值"]` |
| `isLess` | 小于 | 数字、日期 | `["值"]` |
| `isLessEqual` | 小于等于 | 数字 | `["值"]` |

### 日期字段特殊值

```json
// 具体日期
{"operator": "is", "value": ["ExactDate", "1702449755000"]}

// 相对日期
{"operator": "is", "value": ["Today"]}      // 今天
{"operator": "is", "value": ["Tomorrow"]}   // 明天
{"operator": "is", "value": ["Yesterday"]}  // 昨天
{"operator": "is", "value": ["CurrentWeek"]} // 本周
{"operator": "is", "value": ["LastWeek"]}   // 上周
{"operator": "is", "value": ["TheLastWeek"]} // 过去七天
{"operator": "is", "value": ["TheNextWeek"]} // 未来七天
```

### sort 结构
- `field_name`: 排序字段
- `desc`: `true` 降序，`false` 升序
- 支持多字段排序（按数组顺序）

---

## 场景 4: 更新单条记录

**工具**: `feishu_bitable_app_table_record`

```json
{
  "action": "update",
  "app_token": "S404b...",
  "table_id": "tblXXXXXXXX",
  "record_id": "recusyQbB0fVL5",
  "fields": {
    "状态": "已完成",
    "完成时间": 1674206443000,
    "备注": "客户已签约"
  }
}
```

**说明**:
- 只传需要更新的字段
- 不传的字段保持不变
- 支持部分字段更新

**批量更新**（最多 500 条）:

```json
{
  "action": "batch_update",
  "app_token": "S404b...",
  "table_id": "tblXXXXXXXX",
  "records": [
    {
      "record_id": "rec001",
      "fields": {
        "状态": "已完成"
      }
    },
    {
      "record_id": "rec002",
      "fields": {
        "状态": "已完成"
      }
    }
  ]
}
```

---

## 场景 5: 创建带选项的单选字段

**工具**: `feishu_bitable_app_table_field`

```json
{
  "action": "create",
  "app_token": "S404b...",
  "table_id": "tblXXXXXXXX",
  "field_name": "优先级",
  "type": 3,
  "property": {
    "options": [
      {"name": "高", "color": 0},
      {"name": "中", "color": 1},
      {"name": "低", "color": 2}
    ]
  }
}
```

**颜色编号**（color 范围 0-54）:
- 0: 红色
- 1: 橙色
- 10: 绿色
- 20: 蓝色

**多选字段**（type=4）格式相同:

```json
{
  "action": "create",
  "app_token": "S404b...",
  "table_id": "tblXXXXXXXX",
  "field_name": "标签",
  "type": 4,
  "property": {
    "options": [
      {"name": "重要", "color": 0},
      {"name": "紧急", "color": 1},
      {"name": "长期", "color": 10}
    ]
  }
}
```

**注意**:
- 创建时**不能**指定选项 ID（`id` 字段），系统自动生成
- 选项总数不超过 20,000

---

## 场景 6: 创建复杂字段（进度、货币、评分）

### 进度字段 (type=2, ui_type="Progress")

```json
{
  "action": "create",
  "app_token": "S404b...",
  "table_id": "tblXXXXXXXX",
  "field_name": "完成进度",
  "type": 2,
  "ui_type": "Progress",
  "property": {
    "min": 0,
    "max": 100,
    "range_customize": true
  }
}
```

**写入值**: `0.75` 表示 75%

---

### 货币字段 (type=2, ui_type="Currency")

```json
{
  "action": "create",
  "app_token": "S404b...",
  "table_id": "tblXXXXXXXX",
  "field_name": "预算",
  "type": 2,
  "ui_type": "Currency",
  "property": {
    "currency_code": "CNY",
    "formatter": "0,000.00"
  }
}
```

**currency_code 可选值**:
- `"CNY"`: 人民币 (¥)
- `"USD"`: 美元 ($)
- `"EUR"`: 欧元 (€)
- `"JPY"`: 日元 (¥)

**写入值**: `5000.50`（普通数字）

---

### 评分字段 (type=2, ui_type="Rating")

```json
{
  "action": "create",
  "app_token": "S404b...",
  "table_id": "tblXXXXXXXX",
  "field_name": "客户满意度",
  "type": 2,
  "ui_type": "Rating",
  "property": {
    "min": 1,
    "max": 5,
    "rating": {
      "symbol": "star"
    }
  }
}
```

**symbol 可选值**:
- `"star"`: ⭐ 星星
- `"heart"`: ❤️ 爱心
- `"fire"`: 🔥 火焰
- `"thumbsup"`: 👍 赞

**写入值**: `4`（整数）

---

## 场景 7: 处理附件字段

### 步骤 1: 上传附件到多维表格

**工具**: `feishu_drive_media`（上传素材接口）

```json
{
  "action": "upload",
  "file_path": "/path/to/file.pdf",
  "parent_type": "bitable_image",
  "parent_node": "S404b..."  // app_token
}
```

**返回**:
```json
{
  "file_token": "DRiFbwaKsoZaLax4WKZbEGCccoe"
}
```

---

### 步骤 2: 创建附件字段（可选）

```json
{
  "action": "create",
  "app_token": "S404b...",
  "table_id": "tblXXXXXXXX",
  "field_name": "合同文件",
  "type": 17
}
```

---

### 步骤 3: 写入附件记录

```json
{
  "action": "create",
  "app_token": "S404b...",
  "table_id": "tblXXXXXXXX",
  "fields": {
    "客户名称": "字节跳动",
    "合同文件": [
      {"file_token": "DRiFbwaKsoZaLax4WKZbEGCccoe"},
      {"file_token": "BZk3bL1Enoy4pzxaPL9bNeKqcLe"}
    ]
  }
}
```

**限制**:
- 单个单元格附件数不超过 100
- 必须先上传到当前多维表格，不能用外部 file_token

---

## 场景 8: 双向关联字段

### 步骤 1: 创建双向关联字段

**在"任务表"中创建关联到"项目表"的字段**:

```json
{
  "action": "create",
  "app_token": "S404b...",
  "table_id": "tbl_task",
  "field_name": "所属项目",
  "type": 21,
  "property": {
    "table_id": "tbl_project",
    "back_field_name": "关联的任务",
    "multiple": true
  }
}
```

**结果**:
- 在"任务表"中创建字段"所属项目"
- 在"项目表"中**自动创建**字段"关联的任务"

---

### 步骤 2: 写入关联记录

```json
{
  "action": "create",
  "app_token": "S404b...",
  "table_id": "tbl_task",
  "fields": {
    "任务名称": "开发新功能",
    "所属项目": {
      "link_record_ids": ["rec_project_001"]
    }
  }
}
```

**级联更新**:
- 在"任务表"中设置"所属项目"为 `rec_project_001`
- "项目表"的 `rec_project_001` 记录的"关联的任务"字段会**自动添加**当前任务的 record_id

---

### 单向关联 (type=18)

**区别**: 只影响当前表，不会自动更新对方表

```json
{
  "action": "create",
  "app_token": "S404b...",
  "table_id": "tbl_task",
  "field_name": "参考任务",
  "type": 18,
  "property": {
    "table_id": "tbl_task",  // 可以关联自己
    "multiple": true
  }
}
```

---

## 🔗 参考链接

- [字段 Property 配置详解](field-properties.md)
- [记录值数据结构详解](record-values.md)
- [飞书开放平台 - 多维表格文档](https://open.feishu.cn/document/server-docs/docs/bitable-v1/bitable-overview)