cal.diy 飞书日历（Lark Calendar）集成全解析：OAuth 令牌机制、事件订阅与日历服务实现

• 后端
• 前端
• 企业应用

本文以 cal.diy（Cal.com 开源调度基础设施）仓库中飞书日历（Lark Calendar）应用的官方描述文档为骨架，结合其完整源码实现，深入讲解这一日历集成在仓库中的工作原理。Lark Calendar 是飞书（Lark）官方提供的时间管理与日程安排服务，用户可在移动端和网页端创建、编辑事件，并选择事件类型与时间；任何拥有飞书账户的用户都可以使用。读完本文，你将掌握：该集成在仓库中的完整目录结构与注册方式、四个核心配置密钥的作用、OAuth 授权与令牌刷新全链路、app_ticket轮询机制、四类事件订阅的处理逻辑，以及日历增删改查与忙碌时间查询的底层调用。

集成概览：一个标准的 OAuth 日历应用

飞书日历集成的官方描述位于 DESCRIPTION.md，其文字说明虽然简短，但仓库中的实现代码完整地支撑了"时间管理 + 日程创建/编辑"这一核心能力：

Lark Calendar is a time management and scheduling service developed by Lark. Allows users to create and edit events, with options available for type and time. Available to anyone that has a Lark account on both mobile and web versions.

在应用注册层面，_metadata.ts将该应用声明为：

• type / slug：lark_calendar/lark-calendar，是仓库中约上百个 App Store 集成之一；
• variant：calendar，归类到categories: ["calendar"]；
• isOAuth：true，走标准的 OAuth 授权码流程；
• installed：true，默认随应用商店注册表安装；
• publisher：Lark，logo 为 icon.svg。

应用目录结构清晰分层，api/放置 Next.js API 路由（授权入口、回调、事件订阅），lib/放置核心服务（令牌管理、日历服务、机器人消息），types/集中定义飞书 API 的响应与请求类型。

上图为飞书日历的典型界面：左侧为飞书办公套件导航（消息、日历、文档、邮箱、会议等），主区域为周视图日程，右侧为新建日程的编辑窗口（可设置日程名称、时间、参与人、会议室与描述）。该图与 DESCRIPTION.md 中 frontmatter 引用的静态资源列表（1.png–4.png）一致，直观展示了"创建与编辑事件、选择类型与时间"的产品形态。

前置条件与四个核心配置密钥

飞书应用接入需要先在飞书开放平台创建企业自建应用并获取密钥。集成通过getAppKeysFromSlug("lark-calendar")从数据库App表中按 slug 读取应用密钥（见 _utils/getAppKeysFromSlug.ts），zod.ts中的appKeysSchema定义了四个必填密钥：

其中app_ticket不会在初始化时配置，而是由事件订阅接口在运行时接收并持久化（详见下文"事件订阅"一节）。common.ts统一声明飞书开放平台域名LARK_HOST = "open.larksuite.com"，并提供两个通用工具：isExpired（判断令牌是否过期）与handleLarkError（统一校验飞书响应：code !== 0即抛错，并记录响应头X-Tt-Logid便于排查）。

OAuth 授权流程：从跳转到凭据落库

授权入口（GET/api/integrations/larkcalendar/add）

api/add.ts是授权链路的起点：读取app_id、app_secret后，构造飞书网页授权地址：

const params = { app_id, redirect_uri: `${WEBAPP_URL}/api/integrations/larkcalendar/callback`, state, // encodeOAuthState(req)，用于回调后安全跳回原页面 }; const url = `https://${LARK_HOST}/open-apis/authen/v1/index?${query}`;

值得注意的是，它在跳转前会主动调用POST /open-apis/auth/v3/app_ticket/resend，注释明确写着 "trigger app_ticket_immediately"——即在授权开始时就触发飞书推送一次app_ticket，确保后续令牌换发不阻塞。

回调处理（GET/api/integrations/larkcalendar/callback）

api/callback.ts完成"授权码 → 用户令牌 → 落库 → 绑定主日历"四步：

1. 换取用户令牌：携带app_access_token调用POST /open-apis/authen/v1/access_token（grant_type: authorization_code），失败（非 200 或code !== 0）则携带错误信息重定向回/apps/installed?error=...；
2. 构造凭据：将access_token、refresh_token及各自过期时间（expires_in、refresh_expires_in，以秒为单位换算为 Unix 时间戳）存入LarkAuthCredentials；
3. 单用户单凭据策略：源码注释解释了关键设计——飞书同一时刻仅允许一对refresh_token/access_token生效，新令牌会使旧令牌失效；而Credential表中userId + type并不唯一，因此先findFirst查询，存在则update、不存在则create，始终保证每个用户只有一条lark_calendar凭据；
4. 绑定主日历：调用GET /open-apis/calendar/v4/calendars/primary获取用户主日历，成功则将calendar_id写入SelectedCalendar（integration 为lark_calendar），此后该日历即可用于忙碌查询与事件写入。

回调最终通过getSafeRedirectUrl(state?.returnTo)安全跳转，兜底为应用已安装页。

令牌生命周期：app_ticket → app_access_token → 用户令牌刷新

飞书开放平台采用三层令牌体系，lib/AppAccessToken.ts是其中的关键实现：

1. app_ticket 的获取与轮询

源码注释总结了 app_ticket 的五个事实：有效期仅 1 小时；无法通过 API 主动查询；只能由飞书每小时的app_ticket事件推送；可以触发重发；触发后需要轮询数据库等待新票据写入。因此getAppTicket()在发现无有效票据时，先调用重发接口，再用makePoolingPromise(getAppTicketFromKeys, 24, 5 * 1000)轮询：最多尝试 24 次、每次间隔 5 秒（即最长约 2 分钟），等待事件订阅接口把新app_ticket写入App.keys。

2. app_access_token 的缓存与失效处理

getAppAccessToken()优先复用未过期的缓存（app_access_token+expire_date均存于App.keys）；过期则携带app_id、app_secret、app_ticket调用POST /open-apis/auth/v3/app_access_token换新并回写。源码对错误码10012（app_ticket 失效）做了专门处理：清空库中的app_ticket并抛错提示重试，避免用过期票据反复请求。

3. 用户令牌的惰性刷新与凭据同步

lib/CalendarService.ts中的larkAuth采用惰性刷新：getToken()仅在expiry_date过期时才调用refreshAccessToken。刷新时先检查refresh_token与refresh_expires_date，若刷新令牌也已过期，则直接删除该 Credential 并抛错（用户需重新授权）；有效时以app_access_token为 Bearer 调用POST /open-apis/authen/v1/refresh_access_token（grant_type: refresh_token），并通过refreshOAuthTokens支持可选的凭据同步端点（CALCOM_CREDENTIAL_SYNC_ENDPOINT），随后将新令牌对写回数据库。

事件订阅 API：四类飞书事件的统一入口

api/events.ts是POST /api/integrations/larkcalendar/callback之外的事件接收端点，同一路由按事件类型分发，并统一使用 zod 校验请求体：

1. URL 验证（type === "url_verification"）：校验token与open_verification_token一致后，原样返回challenge，完成飞书事件订阅的首次握手；
2. app_ticket 事件（event.type === "app_ticket"）：校验 token 后将新票据写入App.keys.app_ticket，与 AppAccessToken.ts 的轮询逻辑闭环；
3. 消息接收事件（header.event_type === "im.message.receive_v1"）：用户在群聊中 @ 机器人时触发，解析tenant_key与发送者open_id，调用sendPostMsg发送欢迎消息；
4. 单聊创建事件（event.type === "p2p_chat_create"）：用户首次与机器人发起单聊时触发，同样发送欢迎消息。

后三类事件都返回{ code: 0, msg: "success" }以确认接收。这三个分支分别对应飞书文档中的"应用票据事件、消息接收事件、机器人事件"三类订阅场景，代码中以注释形式保留了官方文档链接出处。

日历服务：事件 CRUD、忙碌查询与日历列表

lib/CalendarService.ts通过工厂函数BuildCalendarService(credential)导出实例（避免内部类型泄漏到.d.ts），实现Calendar接口，覆盖调度引擎所需的全部日历能力：

• createEvent / updateEvent / deleteEvent：分别调用飞书calendar/v4/calendars/{calendarId}/events/create_event、.../patch_event（PATCH）与DELETE .../events/{uid}。目标日历来自event.destinationCalendar中匹配当前凭据的externalId；创建事件后还会调用attendees/create_attendees批量添加参与者（need_notification: false），若添加失败则回滚删除已创建的事件，保证一致性；
• getAvailability：调用calendar/v4/freebusy/batch_get批量查询忙碌时间。仅统计selectedCalendars中属于lark_calendar的日历；若未选择任何日历则退化为查询全部可写日历；请求体包含time_min、time_max与calendar_ids，返回的freebusy_list被规约为BufferedBusyTime[]；
• listCalendars：列出可用的集成日历，过滤规则相当严谨——只保留type为primary或shared、permissions !== "private"、且role为owner或writer的日历（即有写入权限的日历），再补充主日历信息，最终映射为统一的IntegrationCalendar（externalId、name、primary等）；
• 事件字段翻译：translateEvent把 Cal.com 的CalendarServiceEvent映射为飞书LarkEvent——标题、描述、起止时间（转为秒级时间戳并携带组织者时区）、attendee_ability: "none"、free_busy_status: "busy"、默认 5 分钟提醒，并通过getLocation合成视频会议/附加信息生成location.name；translateAttendees将参会者与团队成员（排除凭据本人）转为third_party类型的外部参与者。

机器人欢迎消息：开箱即用的引导文案

lib/BotService.ts实现了面向飞书机器人的租户级消息能力：getTenantAccessTokenByTenantKey以app_access_token换取指定租户的tenant_access_token，sendPostMsg再以该令牌调用im/v1/messages（receive_id_type=open_id）发送富文本post消息。默认文案是一份完整的引导：介绍 cal.diy 是开源调度基础设施、访问网站注册账号、在 Apps 中安装飞书日历并登录、创建事件类型并分享预约链接，同时附上帮助台入口——新用户与机器人建立会话后即可获得全套指引。

注册表与类型定义的落点

飞书日历集成在仓库中通过自动生成的注册表文件挂载进应用商店体系：

• apps.metadata.generated.ts 与 apps.keys-schemas.generated.ts：将larkcalendar的元数据与密钥/数据校验 schema 注册进统一清单；
• apps.server.generated.ts：将./larkcalendar/api注册为服务端 API 模块；
• calendar.services.generated.ts：将./larkcalendar/lib/CalendarService注册到日历服务工厂，供调度引擎按集成类型实例化。

此外，types/LarkCalendar.ts 集中定义了飞书侧的数据契约，包括LarkAuthCredentials（令牌对）、LarkEvent（事件载荷）、LarkEventAttendee、FreeBusyResp、ListCalendarsResp（含permissions、role、type等枚举）与RefreshTokenResp等，是理解上述各服务返回值类型的直接参考。

小结

通过将简短的官方描述与仓库源码相互印证可以看到，飞书日历集成远不止"创建和编辑事件"这一句话——它是一套完整的 OAuth 日历接入实现：四密钥配置驱动、授权码换取用户令牌、单用户单凭据策略、app_ticket轮询换取应用令牌、三层令牌的缓存与惰性刷新、四类事件订阅分发、严格的日历过滤规则与事件字段翻译，以及事件创建失败时的回滚保障。对于需要在 cal.diy 中接入其他飞书式（票据推送 + 多级令牌）开放平台的开发者而言，larkcalendar 目录内的api/、lib/、types/分层与_utils/通用工具（getAppKeysFromSlug、refreshOAuthTokens）构成了一份可复用的完整范本。

• 后端
• 前端
• 企业应用