> ## 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 可以根據你的業務需求，幫助產品建立、查詢、更新或同步飛書日程。

***

## 適合什麼場景

* 在產品中建立會議後，同步生成飛書日程。
* 查詢成員可用時間，輔助安排會議或預約。
* 將報名、面試、拜訪等業務節點同步到日曆。
* 在產品頁面展示用戶的飛書日程或會議安排。

***

## 接入前需要準備

| 準備項    | 說明                                                       |
| ------ | -------------------------------------------------------- |
| 飛書基礎插件 | 先啟用 [飛書插件](/zh-Hant/superun/integrations/feishu)，並完成飛書登入 |
| 日曆權限   | 在飛書開放平台同時開通日曆讀取和寫入相關權限                                   |
| 用戶重新授權 | 如果用戶之前只授權過登入，需要重新同意日曆權限                                  |
| 版本發佈   | 權限變更後，需要建立新版本並發佈                                         |

<Warning>
  飛書日曆通常需要同時具備「讀取」和「寫入」兩類權限。只開通寫入權限時，查詢主日曆或讀取日程可能仍會失敗。
</Warning>

***

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

進入飛書開放平台 → 找到你的企業自建應用 →「權限管理」，申請下面兩條 **user 類型** 權限。日程能力建議兩條同時開通。

| 權限 key                       | 權限名稱    | 類型   | 用途                         |
| ---------------------------- | ------- | ---- | -------------------------- |
| `calendar:calendar:readonly` | 讀取日曆與日程 | user | 查詢主日曆、讀取日程列表、讀取日程詳情、檢查日程數據 |
| `calendar:calendar`          | 寫入日曆與日程 | user | 建立、編輯、刪除日程，處理參會人和會議相關寫入    |

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

```json theme={null}
{
  "scopes": {
    "tenant": [],
    "user": ["calendar:calendar:readonly", "calendar:calendar"]
  }
}
```

<Warning>
  `calendar:calendar` 雖然名字裡沒有 `write`，但在當前接入中不能替代讀取權限。需要查詢日程、查詢主日曆或做「先讀後寫」的流程時，必須同時申請 `calendar:calendar:readonly`。
</Warning>

權限申請後還需要完成「建立版本 → 提交審批 → 發佈」。沒有發佈新版本時，用戶重新授權頁面不會展示新增的日曆權限。

***

## 如何在 superun 中啟用

<Steps>
  <Step title="確認飛書登入已接入">
    日程能力依賴飛書登入授權。建議先讓目標用戶至少完成一次飛書登入。
  </Step>

  <Step title="在飛書後台開通日曆權限">
    同時申請日曆讀取和寫入權限，並發佈飛書應用新版本。
  </Step>

  <Step title="啟用飛書日程">
    在「研發」→「技能庫」點擊「飛書日程」，描述你希望接入的日程場景。
  </Step>

  <Step title="補充業務規則">
    說明什麼時候建立日程、參與人來自哪裡、是否需要會議室、提醒時間和同步方向。
  </Step>

  <Step title="完成授權測試">
    按提示在飛書授權頁同意新增日曆權限，然後在產品中測試建立或查詢日程。
  </Step>
</Steps>

***

## 常見問題

<AccordionGroup>
  <Accordion title="為什麼已經能飛書登入，但日程接口還是提示權限不足？">
    登入預設只會申請基礎身份權限。日程屬於額外能力，需要在飛書後台開通日曆權限，並讓用戶重新授權。
  </Accordion>

  <Accordion title="可以只做建立日程，不讀取日程嗎？">
    可以按業務簡化功能，但實際實現中通常仍需要讀取主日曆、校驗日程或同步結果，因此建議一次性開通讀取和寫入權限。
  </Accordion>

  <Accordion title="為什麼飛書後台已經申請權限，授權頁還是沒有新增權限？">
    通常是應用新版本還沒有發佈。權限申請通過後，需要進入「版本管理與發佈」建立並發佈新版本。
  </Accordion>
</AccordionGroup>