> ## 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 中接入飞书通讯录、部门、组织架构和成员查询能力。

# 飞书通讯录

飞书通讯录能力用于读取企业成员、部门层级和组织结构。它适合做成员选择器、部门筛选、权限范围、人员信息同步和身份映射。

***

## 适合什么场景

* 在产品中展示部门树或组织架构。
* 按部门筛选成员、分配任务或发起审批。
* 根据飞书用户身份匹配产品内用户。
* 自动同步员工姓名、头像、邮箱、职位等基础信息。

***

## 接入前需要准备

| 准备项    | 说明                                                               |
| ------ | ---------------------------------------------------------------- |
| 飞书基础插件 | 先启用 [飞书插件](/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>