Cal.diy App Store 集成模式全解析：生成文件、静态 Map 导入与日历缓存扩展规范

Cal.diy 的 App Store（应用商店）是一个高度插件化的集成体系：日历、视频会议、支付、CRM、分析等各类集成以独立目录形式存在于 packages/app-store 下，再由 app-store-cli 批量生成统一的注册清单。本文以 agents/rules/patterns-app-store.md 这份开发规范为主线，结合 生成器源码 与 App Store 运行时入口 的实际实现，讲解其"生成文件（generated files）— 静态 Map 导入 — 日历缓存扩展"三层模式的原理与约束。读完本文，你将能理解：哪些文件可以直接手改、哪些必须改动生成器、lazyImport 参数如何决定静态/动态导入，以及如何按既定模式为 Office365 等 provider 扩展日历缓存能力。

一、规范总览：三条不可逾越的集成铁律

该规则文件在仓库中承担"约定优先"的定位（front-matter 中声明 impact: MEDIUM），其约束对象是所有涉及 App Store 集成的改动。全文可归结为三条核心约定：

1. *.generated.ts 是机器产物，禁止手工修改；结构性改动应落在 app-store-cli 的生成代码上。
2. 浏览器端组件尽量走静态 Map 导入而非动态导入，以获得更好的运行时性能；服务端服务文件按类型选择默认导出或具名导出。
3. 日历缓存等跨模块能力有固定的代码落位约定：provider 特有的缓存逻辑应放进对应 provider 目录，而不是散落在共享缓存层。

下文将逐条展开，并用源码佐证每一条规则背后的真实机制。

二、Generated Files：由 app-store-cli 生成的注册清单

在 packages/app-store 目录下可以看到一批 *.generated.ts / *.generated.tsx 文件，它们不是手写代码，而是 app-store-cli 的输出物，例如：

• packages/app-store/calendar.services.generated.ts
• packages/app-store/crm.apps.generated.ts
• packages/app-store/analytics.services.generated.ts
• packages/app-store/payment.services.generated.ts
• packages/app-store/video.adapters.generated.ts
• packages/app-store/apps.server.generated.ts（API handlers）
• packages/app-store/apps.browser.generated.tsx（浏览器端组件）
• packages/app-store/apps.metadata.generated.ts / bookerApps.metadata.generated.ts
• packages/app-store/apps.schemas.generated.ts / apps.keys-schemas.generated.ts
• packages/app-store/redirect-apps.generated.ts

打开任意一个生成文件，头部都带有醒目的警示横幅，例如 calendar.services.generated.ts：

/**
   This file is autogenerated using the command `yarn app-store:build --watch`.
   Don't modify this file manually.
**/

这正是规则第一条的出处：如果你发现某类集成"没有被导入"或"多了一个应用"，正确做法是修复生成器，而不是往这些文件里追加一行 import。 因为生成文件会在下一次 build / watch 时被整体覆盖，任何手改都会丢失。

从 build.ts 可以看出，生成器在写完文件后还会调用 biome format --write 统一格式化，然后打印 Generated ... 日志，所有文件由 filesToGenerate 一张清单决定，新增一类生成文件的入口也在这里。

触发方式与监听行为

根目录 package.json 暴露了三个相关脚本：

yarn app-store:build   # 执行 yarn turbo build --filter=@calcom/app-store-cli
yarn app-store:watch   # 执行 yarn app-store-cli watch
yarn app-store         # 执行 yarn app-store-cli cli（交互式创建/管理应用）

生成器本身支持命令行参数 --watch：非 watch 模式调用 generateFiles() 一次生成全部清单；watch 模式则用 chokidar 监听整个 packages/app-store 目录，并在三种事件下（通过 debounce 防抖后）重新生成（见 build.ts 末尾）：

• addDir：新增应用目录（目录名满足 getAppName 的校验，即以合法应用名命名且不以 _ 开头）；
• change：config.json 被修改（如元数据、分类、externalLink 等变化）；
• unlinkDir：应用目录被删除。

开发者在本地调试新应用时执行 yarn app-store:watch 即可获得"改动即重新生成"的反馈闭环。

目录扫描规则

生成器只认应用目录，判定逻辑在 getAppName 中：目录名不能以 _ 开头、不能是 ee、不能含路径分隔符。扫描时，顶层应用与 ee/、templates/ 下的子应用都会被收录（见 build.ts），而 _utils、_components 这类共享内部目录则被有意跳过。每收集一个应用，还会优先读取其 config.json 并用 AppMetaSchema 做结构校验；老应用没有 config.json 时则回退读取 _metadata.ts 的 metadata 导出（见 forEachAppDir）。

三、Import 模式：静态 Map 导入的取舍与 lazyImport

规则中提到的"从动态导入迁移到静态 Map 导入"，其核心实现集中在生成器最关键的工厂函数 getExportedObject()（见 build.ts）。它负责：扫描应用目录 → 确认要导入的文件存在 → 生成 import 语句 → 拼装一个以 app 为 key 的导出 Map。

function getExportedObject(
  objectName: string,
  {
    lazyImport = false,
    importConfig,
    entryObjectKeyGetter = (app) => app.name,
  }: {
    lazyImport?: boolean;
    importConfig: ImportConfig;
    entryObjectKeyGetter?: (arg: App, importName?: string) => string;
  },
  filter?: (arg: App) => boolean
)

三个核心参数决定了生成结果的性质：

参数	作用	影响
objectName	导出 Map 的变量名	决定生成文件里 export const xxxMap = {...} 的名字
lazyImport	是否使用动态导入	false（默认）= 顶部静态 import；true = 运行时动态 import
importConfig	指定要导入的文件与导出名	单对象为唯一选择；二元数组为主选 + 回退（如 config.json 缺失时改用 _metadata.ts）

lazyImport = false：静态导入（服务端优先）

对于不需要按需加载的服务端数据（如元数据、zod schema），生成的是顶层静态 import + 同步 Map：

• 具名导出：import { metadata as zoomvideo_zod } from ".../zod"；
• 默认导出：import xxx_default from ".../config.json"。

appStoreMetadata、appDataSchemas、appKeysSchemas 均走此路径（见 build.ts）。静态导入让所有引用在模块加载期即完成解析，配合打包器的 tree-shaking 更利于性能，这正是规则强调"静态优于动态"的原因。

lazyImport = true：动态导入（浏览器组件）

而浏览器组件若全部静态打包，会让首屏 bundle 膨胀。因此组件类 Map（InstallAppButtonMap、AppSettingsComponentsMap、EventTypeAddonMap、EventTypeSettingsMap）都传入了 lazyImport: true（见 build.ts）。此时 getExportedObject 会进一步区分文件类型（见 build.ts）：

if (chosenConfig.fileToBeImported.endsWith(".tsx")) {
  output.push(`"${key}": dynamic(() => import("${getModulePath(...)}")),`);
} else {
  output.push(`"${key}": import("${getModulePath(...)}"),`);
}

• .tsx 组件文件 → 包一层 next/dynamic，交给 Next.js 做代码分割与懒加载；
• .ts 服务文件 → 使用原生 import() 返回 Promise。

产物可见 apps.browser.generated.tsx：

import dynamic from "next/dynamic";
export const InstallAppButtonMap = {
  exchange2013calendar: dynamic(() => import("./exchange2013calendar/components/InstallAppButton")),
  exchange2016calendar: dynamic(() => import("./exchange2016calendar/components/InstallAppButton")),
  ...
};

也就是说：getExportedObject() 的 lazyImport 参数是"动态还是静态"的唯一开关，而文件扩展名 .tsx/.ts 又进一步决定动态导入是否交由 next/dynamic 处理。

服务类 Map 的动态化与 E2E 特殊处理

CalendarServiceMap、AnalyticsServiceMap、VideoApiAdapterMap 等服务 Map 同样使用 lazyImport: true 的 import() 形式，但它们在 build.ts 中还有一段特殊改写：当环境变量 NEXT_PUBLIC_IS_E2E === '1' 时，导出为空对象 {}，从而在端到端测试中隔离真实第三方调用。例如 calendar.services.generated.ts 实际生成的是条件导出：

export const CalendarServiceMap =
  process.env.NEXT_PUBLIC_IS_E2E === "1"
    ? {}
    : {
        applecalendar: import("./applecalendar/lib/CalendarService"),
        googlecalendar: import("./googlecalendar/lib/CalendarService"),
        office365calendar: import("./office365calendar/lib/CalendarService"),
        ...
      };

按分类过滤与特殊 key

getExportedObject 还接受第 4 个可选参数 filter，配合文件存在性做双重过滤：

• isCalendarApp / isCrmApp：按 config.json 的 categories 是否包含 "calendar" / "crm" 决定是否进入 CalendarServiceMap / CrmServiceMap；
• isBookerApp：仅当元数据含 appData.location（如视频会议类）或 appData.tag（如 GA4、GTM 等标签管理类）时，才进入 bookerApps.metadata.generated.ts（见 build.ts）；
• Analytics / Payment / Video 等服务则直接用"该 app 目录下是否存在 lib/AnalyticsService.ts 等文件"作为过滤条件（见 build.ts）。

另外，Map 的 key 默认取应用目录名，但 schema 类 Map 使用 getAppId() 特例：stripepayment 目录对外暴露的 key 是 stripe（见 build.ts 与注释中关于 eventType 按 appId 查表的说明）。若你集成一个历史遗留目录名与 appId 不一致的 provider，就需要留意这类 key 转换逻辑。

四、生成文件的类型矩阵：改 build.ts 时必须覆盖的场景

规则特别强调"修改 build.ts 时需确保正确处理所有类型"。结合上一节，getExportedObject() 面对的输入可归纳为一个二维矩阵：

生成文件类型	示例	导入导出形态
常规服务文件	calendar.services.generated.ts、crm.apps.generated.ts、payment.services.generated.ts	需默认导出（importName: "default"），按需支持 E2E 条件置空
元数据 / schema	apps.metadata.generated.ts、apps.schemas.generated.ts	具名导出 + 多来源回退（config.json 默认导出 → _metadata.ts 具名导出）
浏览器组件文件	apps.browser.generated.tsx	必须走动态导入并交由 Next.js next/dynamic 处理
API handlers	apps.server.generated.ts	api/index.ts 入口，动态 import

新增一个分类或调整导入策略时，改动的最小集是：filesToGenerate 清单 + 若干 getExportedObject 调用。校验改动是否完整，可以观察生成的 *.generated.ts 是否同时满足：默认导入应用得以静态/动态正确生成、浏览器组件没有退化成同步加载、服务 Map 仍保留 E2E 条件分支。

五、Calendar Cache 模式：provider 特有代码放对位置

规则的最后一段指向日历缓存（calendar cache）体系。本仓库中与其对应的基础设施可以串联出完整的证据链：

1. 功能开关定义：calendar-cache 与 calendar-cache-serve 是 flags/config.ts 中声明的布尔型功能标志，说明该能力是可灰度开关的团队级特性。
2. 数据层消费：SelectedCalendarRepository 在查询"下一批需要 watch/unwatch 的日历"时，以 featureId: "calendar-cache" 且 enabled: true 作为组织级过滤条件，并结合 googleChannelExpiration、重试次数（watchAttempts / unwatchAttempts）等字段维护订阅通道的生命周期——这表明日历缓存是"拉取缓存 + 订阅推送"两态结合的实现。
3. 数据库迁移痕迹：packages/prisma/migrations 中从早期 add_calendar_cache 到 add_calendar_cache_serve、delegation_credential_calendar_cache 再到 add_holiday_cache 等一系列迁移，记录了该体系随版本演进逐步成形的过程。

在这样一套多 provider 共享的缓存系统里，规则给出的落位约定是：共享逻辑留在公共的 calendar-cache 模块，而 provider 特有的实现（例如针对 Outlook / Office365 的过期策略、分页拉取与增量同步差异）必须下沉到对应 provider 目录。office365calendar 就是一个很好的参照物——packages/app-store/office365calendar 下完整地聚集了该 provider 的元数据（_metadata.ts）、API 路由（api/）、实现（lib/，含 CalendarService.ts、getOfficeAppKeys.ts）与 schema（zod.ts），并且正是经由上一节提到的 CalendarServiceMap 统一注册。

对集成开发者而言，这条约定的实践意义是：

• 新增缓存 provider 时，先判断改动是"影响所有 provider 的公共行为"还是"只属于某个 provider"，前者改公共缓存层，后者写进 provider 目录；
• 不要把 Office365 特有的请求参数、错误重试或令牌刷新逻辑泄漏到共享层，以免破坏 Google Calendar 等其他 provider 的既有行为；
• 代码审查时以此检查依赖方向：provider 目录可以引用共享层，共享层不应反向依赖某个 provider。

六、实战工作流小结

综合上文，在 Cal.diy 中做一次"新增或调整 App Store 集成"时，推荐按下面的顺序自查：

1. 创建应用骨架：通过 yarn app-store 交互式 CLI（或复制现有模板）在 packages/app-store 下建立目录，确保目录名合法、提供 config.json（或旧式 _metadata.ts）；
2. 按类型补充文件：服务集成提供 lib/CalendarService.ts 等默认导出实现；UI 集成提供 components/InstallAppButton.tsx、components/AppSettingsInterface.tsx 等组件；
3. 启动 watch 生成：执行 yarn app-store:watch，确认 *.generated.ts 中自动出现你的应用条目，且 import 形态符合预期（服务走 import()、组件走 dynamic()）；
4. 绝不手改生成文件：若注册结果不正确，回到 packages/app-store-cli/src/build.ts 调整 getExportedObject 的调用或 filesToGenerate 清单，重新生成并比对 diff；
5. 涉及日历缓存时：把 provider 特有逻辑放进 provider 目录，并确认 calendar-cache 功能开关、repository 层订阅管理能与既有 provider 兼容。

这套"生成器统一登记 + 运行时按需解析 + provider 目录自治"的架构，既保证了成百个集成的注册一致性，又为浏览器端性能与 E2E 隔离留出了明确开关，是理解整个 Cal.diy 插件体系最值得先读的一课。