后端前端企业应用【免费下载链接】cal.diyScheduling infrastructure for absolutely everyone.项目地址https://gitcode.com/GitHub_Trending/ca/cal.diy点击查看免费下载本文以 cal.diyCal.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 / sluglark_calendar/lark-calendar是仓库中约上百个 App Store 集成之一variantcalendar归类到categories: [calendar]isOAuthtrue走标准的 OAuth 授权码流程installedtrue默认随应用商店注册表安装publisherLarklogo 为 icon.svg。应用目录结构清晰分层api/放置 Next.js API 路由授权入口、回调、事件订阅lib/放置核心服务令牌管理、日历服务、机器人消息types/集中定义飞书 API 的响应与请求类型。上图为飞书日历的典型界面左侧为飞书办公套件导航消息、日历、文档、邮箱、会议等主区域为周视图日程右侧为新建日程的编辑窗口可设置日程名称、时间、参与人、会议室与描述。该图与 DESCRIPTION.md 中 frontmatter 引用的静态资源列表1.png–4.png一致直观展示了创建与编辑事件、选择类型与时间的产品形态。前置条件与四个核心配置密钥飞书应用接入需要先在飞书开放平台创建企业自建应用并获取密钥。集成通过getAppKeysFromSlug(lark-calendar)从数据库App表中按 slug 读取应用密钥见 _utils/getAppKeysFromSlug.tszod.ts中的appKeysSchema定义了四个必填密钥密钥用途app_id飞书应用的唯一标识用于 OAuth 授权跳转与各类令牌接口app_secret应用密钥用于请求app_ticket、app_access_token等open_verification_token注意 zod 校验字段名为open_verfication_token事件订阅的验签令牌用于 URL 验证与事件推送校验运行期动态写入app_ticket由飞书每小时推送的票据是换取app_access_token的前提其中app_ticket不会在初始化时配置而是由事件订阅接口在运行时接收并持久化详见下文事件订阅一节。common.ts统一声明飞书开放平台域名LARK_HOST open.larksuite.com并提供两个通用工具isExpired判断令牌是否过期与handleLarkError统一校验飞书响应code ! 0即抛错并记录响应头X-Tt-Logid便于排查。OAuth 授权流程从跳转到凭据落库授权入口GET/api/integrations/larkcalendar/addapi/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/callbackapi/callback.ts完成授权码 → 用户令牌 → 落库 → 绑定主日历四步换取用户令牌携带app_access_token调用POST /open-apis/authen/v1/access_tokengrant_type: authorization_code失败非 200 或code ! 0则携带错误信息重定向回/apps/installed?error...构造凭据将access_token、refresh_token及各自过期时间expires_in、refresh_expires_in以秒为单位换算为 Unix 时间戳存入LarkAuthCredentials单用户单凭据策略源码注释解释了关键设计——飞书同一时刻仅允许一对refresh_token/access_token生效新令牌会使旧令牌失效而Credential表中userId type并不唯一因此先findFirst查询存在则update、不存在则create始终保证每个用户只有一条lark_calendar凭据绑定主日历调用GET /open-apis/calendar/v4/calendars/primary获取用户主日历成功则将calendar_id写入SelectedCalendarintegration 为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_tokenexpire_date均存于App.keys过期则携带app_id、app_secret、app_ticket调用POST /open-apis/auth/v3/app_access_token换新并回写。源码对错误码10012app_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_tokengrant_type: refresh_token并通过refreshOAuthTokens支持可选的凭据同步端点CALCOM_CREDENTIAL_SYNC_ENDPOINT随后将新令牌对写回数据库。事件订阅 API四类飞书事件的统一入口api/events.ts是POST /api/integrations/larkcalendar/callback之外的事件接收端点同一路由按事件类型分发并统一使用 zod 校验请求体URL 验证type url_verification校验token与open_verification_token一致后原样返回challenge完成飞书事件订阅的首次握手app_ticket 事件event.type app_ticket校验 token 后将新票据写入App.keys.app_ticket与 AppAccessToken.ts 的轮询逻辑闭环消息接收事件header.event_type im.message.receive_v1用户在群聊中 机器人时触发解析tenant_key与发送者open_id调用sendPostMsg发送欢迎消息单聊创建事件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_eventPATCH与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的日历即有写入权限的日历再补充主日历信息最终映射为统一的IntegrationCalendarexternalId、name、primary等事件字段翻译translateEvent把 Cal.com 的CalendarServiceEvent映射为飞书LarkEvent——标题、描述、起止时间转为秒级时间戳并携带组织者时区、attendee_ability: none、free_busy_status: busy、默认 5 分钟提醒并通过getLocation合成视频会议/附加信息生成location.nametranslateAttendees将参会者与团队成员排除凭据本人转为third_party类型的外部参与者。机器人欢迎消息开箱即用的引导文案lib/BotService.ts实现了面向飞书机器人的租户级消息能力getTenantAccessTokenByTenantKey以app_access_token换取指定租户的tenant_access_tokensendPostMsg再以该令牌调用im/v1/messagesreceive_id_typeopen_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构成了一份可复用的完整范本。赞分享后端前端企业应用【免费下载链接】cal.diyScheduling infrastructure for absolutely everyone.项目地址https://gitcode.com/GitHub_Trending/ca/cal.diy点击查看免费下载相关推荐Cal.com 飞书日历集成解析Feishu Calendar 应用的授权、令牌与日程同步实现Cal.com 飞书日历集成解析Feishu Calendar 应用的授权、令牌与日程同步实现 飞书日历Feishu Calendar是飞书Lark/F后端前端企业应用Lark/飞书 CLI 日历日程更新实战lark-cli calendar update 全参数详解与源码级剖析Lark/飞书 CLI 日历日程更新实战 lark cli calendar update 全参数详解与源码级剖析 本文是 Lark/飞书官方 CLI 工具CLIAI 技能lark-cli calendar transfer飞书日历日程组织者转让命令的完整实战指南lark cli calendar transfer飞书日历日程组织者转让命令的完整实战指南 本文以 Lark/飞书官方 CLI 工具仓库 lark clCLIAI 技能创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考