> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superun.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 飛書通訊錄

> 在 superun 中接入飛書通訊錄、部門、組織架構和成員查詢能力。

# 飛書通訊錄

飛書通訊錄能力用於讀取企業成員、部門層級和組織結構。它適合做成員選擇器、部門篩選、權限範圍、人員資訊同步和身份映射。

***

## 適合什麼場景

* 在產品中展示部門樹或組織架構。
* 按部門篩選成員、分配任務或發起審批。
* 根據飛書用戶身份匹配產品內用戶。
* 自動同步員工姓名、頭像、電子郵件、職位等基礎資訊。

***

## 接入前需要準備

| 準備項    | 說明                                                                       |
| ------ | ------------------------------------------------------------------------ |
| 飛書基礎插件 | 先啟用 [飛書插件](/zh-Hant/superun/integrations/feishu)，並填寫 App ID 和 App Secret |
| 通訊錄權限  | 在飛書開放平台開通部門和成員讀取相關權限                                                     |
| 數據權限範圍 | 在飛書管理後台設定應用可讀取的成員或部門範圍                                                   |
| 版本發佈   | 權限變更後，需要建立新版本並發佈                                                         |

<Warning>
  通訊錄接口可能因為「應用可用範圍」或「數據權限範圍」過小而返回空數據。權限已開通但查不到成員時，優先檢查飛書後台的數據範圍配置。
</Warning>

***

## 飛書後台需要開通的權限

進入飛書開放平台 → 找到你的企業自建應用 →「權限管理」，按業務需要申請下面的 **tenant 類型** 權限。

| 權限 key                             | 權限名稱      | 類型     | 用途                          |
| ---------------------------------- | --------- | ------ | --------------------------- |
| `contact:contact.base:readonly`    | 獲取通訊錄基本資訊 | tenant | 通訊錄基礎讀取能力，通常作為通訊錄接口基礎權限     |
| `contact:department.base:readonly` | 獲取部門基本資訊  | tenant | 查詢部門列表、部門層級和組織結構            |
| `contact:user.base:readonly`       | 獲取用戶基本資訊  | tenant | 查詢成員基礎資訊，例如姓名、頭像、open\_id 等 |
| `contact:user.email:readonly`      | 獲取用戶電子郵件  | tenant | 可選，需要讀取成員電子郵件時開通            |
| `contact:user.phone:readonly`      | 獲取用戶手機號   | tenant | 可選，需要讀取成員手機號時開通             |

推薦使用飛書權限管理中的「批量導入」：

```json theme={null}
{
  "scopes": {
    "tenant": [
      "contact:contact.base:readonly",
      "contact:department.base:readonly",
      "contact:user.base:readonly",
      "contact:user.email:readonly",
      "contact:user.phone:readonly"
    ],
    "user": []
  }
}
```

如果不需要電子郵件或手機號，可以先不申請 `contact:user.email:readonly` 和 `contact:user.phone:readonly`。後續業務確實要展示這些欄位時，再補權限並發佈新版本。

***

## 如何在 superun 中啟用

<Steps>
  <Step title="啟用飛書基礎插件">
    確認飛書應用憑證已在 superun 中配置完成。
  </Step>

  <Step title="開通通訊錄權限和數據範圍">
    在飛書開放平台申請通訊錄權限，並在飛書管理後台配置應用可讀取的成員或部門範圍。
  </Step>

  <Step title="啟用飛書通訊錄">
    在「研發」→「技能庫」點擊「飛書通訊錄」，說明產品中需要使用成員或部門數據的地方。
  </Step>

  <Step title="補充欄位需求">
    告訴 superun 需要讀取哪些成員欄位，例如姓名、頭像、電子郵件、手機號、職位或部門。
  </Step>

  <Step title="測試查詢結果">
    發佈飛書應用版本後，在產品中測試部門樹、成員列表和人員詳情是否符合預期。
  </Step>
</Steps>

***

## 常見問題

<AccordionGroup>
  <Accordion title="為什麼接口調用成功但成員列表為空？">
    常見原因是飛書後台沒有把應用的數據權限範圍設定到目標成員或部門。需要管理員在飛書管理後台調整應用可見範圍。
  </Accordion>

  <Accordion title="讀取電子郵件或手機號需要額外配置嗎？">
    通常需要額外開通對應欄位的讀取權限。建議只申請業務確實需要的欄位。
  </Accordion>
</AccordionGroup>