opencals-build-booking-site

构建 Opencals 预约店面

你正在帮助某人基于 Opencals 托管预约 API 搭建一个真正可预约的店面。你不会构建预约引擎——可用时段计算、时区和重复预约问题都由 API 处理。你的工作在前端：从模板开始，连接到他们的店铺，重新设计样式，然后部署。

如需准确的 SDK 方法名称和参数格式，请使用配套的 opencals-storefront-api 技能——它是有关可用时段、购物车、预约、结账、折扣、自助服务、访客/参与者、自定义时长和速率限制的权威资料。本技能介绍的是围绕它展开的构建工作流。

何时使用此技能

当用户想要预约、约会或日程安排网站时，或者想要“Opencals 店面”时，使用此技能；当用户向你提供业务描述和灵感素材（截图、竞品网站），并要求制作预约网站时，也使用此技能。如果他们需要可自托管的预约引擎或数据驻留能力，那么此工具不适合——请告知他们这一点，并推荐 Cal.com 或 Easy!Appointments。

主要流程：创意 + 灵感 → 上线网站

1. 了解业务。 他们出售的是人的时间（发型师、临床医生、教练），还是物品（球场、房间、泳道、设备），或两者兼有？是否有团体活动？多个地点？在线服务/配送？这些因素决定模板和建模方式。
2. 选择最合适的模板（见下文）。先匹配预约形式，再考虑外观——重新设计样式成本低，重新架构成本高。
3. 搭建脚手架 → 配置 → 接入 → 重塑品牌 → 部署（见下方工作流）。
4. 将灵感中的设计元素融入模板的设计令牌/组件；保留已接入的预约流程。

如果目标是在现有网站中添加预约，而不是构建新网站，同样适用该 SDK 和 API——使用 opencals-storefront-api 技能，并将预约流程嵌入他们的应用（或 iframe/小组件），而不是搭建新模板。

前置条件（先询问这些信息）

1. 业务类型 — 选择最接近的起始模板：
   • template-haar — 美发沙龙（服务 + 作品集，温暖／编辑风格）
   • template-frisor — 理发店（深色、编辑风格）
   • template-clarity — 诊所（平静、温暖；以需求为先的 Care Finder、单页预约编辑器，支持按次就诊填写信息并上传照片、诊所就诊或视频就诊、家庭护理记录；无密码登录）
   • template-volt（又称 padel template）— 多俱乐部板网球和壁球网络（深色／技术风格）：混合了可预约资源（多个俱乐部的球场，可通过实时场馆地图或网格查看）和由员工带领的课程（教练），并提供团队与装备结账以及比赛门票确认。任何出租可互换单元的场所都适合从这里开始——球场、球道、房间、工位、设备等，尤其适合同时提供课程或教学的场所。参见下文“资源预约业务”。
   • template-noir（NOIR Drive）— 豪华汽车租赁（黑色、电影感、动画丰富）：按天预订车辆，支持日期范围日历、送车与取车地点选择、按天计费的附加项目、交车时收取押金，以及由员工提供的司机套餐。任何按整天出租物品的业务都适合从这里开始——汽车、船只、设备等。参见下文“按天预订的租赁”。
   • template-bali-villas（Bali Villa Rentals，演示品牌 Lumbung Sidemen）— 别墅租赁（温暖、静谧、稻田摄影风格）：按晚预订别墅，入住时间为 15:00，退房时间为 11:00；日历显示实时可订情况和换房日期，并支持填写宾客人数与抵达信息、添加按次住宿计费的附加项目，以及通过账户更改日期或取消预订。别墅、小木屋、家庭旅馆或客房都适合从这里开始。参见下文“按晚住宿”。
   • template-fluently（Fluently）— 语言学校（多彩、活泼、3D 吉祥物）：小班课程带有等级变体并实时显示“剩余席位”，提供私人 1:1 课程、免费试课、教师员工、校区，以及带有加入按钮的在线课堂。任何学校或课程业务都适合从这里开始——语言、音乐、编程、辅导、艺术等。参见下文“学校和课程”。
   • template-reformer（Tensile）— 位于柏林的 Reformer 普拉提工作室（技术感、温暖；混凝土色、墨色和弹簧色）：每周课程表覆盖三间工作室及线上课程，每节课都注明教练并显示剩余床位；已满课程显示“下一个有空位的课程”；课程详情页可跳转至结账；提供 1:1 和双人私人课程、指定日期的工作坊、免责协议问题、入门和非高峰时段折扣，以及通过账户更改／取消预约和加入候补。普拉提、瑜伽、芭蕾把杆、有氧动感单车或任何提供课程表的工作室都适合从这里开始。参见下文“健身和普拉提工作室”。
2. Opencals 私有店铺密钥（spk_...）— 在 Opencals 控制面板中获取（Users → your user → API Keys）。模板会从服务端调用 API，因此密钥会保密，每位访客也会获得独立的速率限制。如果对方还没有密钥，请引导他们在部署前创建店铺和私有店铺密钥（网站可以在没有密钥的情况下构建，但不会返回实时数据）。
3. Node.js 20+ 和 Vercel 账户（免费套餐即可）用于部署。

工作流

1. 基于最接近的模板搭建

npx create-next-app -e https://github.com/letsopencals/template-haar my-booking-site
cd my-booking-site
npm install

根据需要，将仓库替换为 template-frisor、template-clarity、template-volt、template-noir、template-bali-villas、template-fluently 或 template-reformer。这些都是完整应用——服务目录、实时可用情况、购物车、结账、Stripe 支付和客户账户均已连接就绪。不要重新构建这些功能。

2. 配置环境

将 .env.example 复制为 .env.local 并填写：

OPENCALS_API_KEY=spk_your_key_here          # Required — the private storefront key
AUTH_SECRET=<random string>                 # Required — session encryption
# OPENCALS_API_URL=https://api.opencals.com # Optional — defaults to this
# NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_...  # Optional — for payments

使用 openssl rand -base64 32 生成 AUTH_SECRET。

3. 理解 SDK 的接线方式（不要另起炉灶）

SDK 通过 lib/opencals.ts 中的副作用导入进行一次初始化，每个 API 路由都会在文件顶部导入该模块。服务采用基于类的形式（ProductService、CartService、AppointmentService、CheckoutService、AuthService、SelfService 等）。构建层面的概览请参阅 references/booking-flow.md，准确的调用形式请参阅 opencals-storefront-api 技能——请使用其中的内容，不要自行编造方法名。

4. 重新打造品牌并自定义

主要是设计方面，而非接线：在 app/globals.css 中设置颜色／字体令牌，在 lib/site-config.ts 中设置文案和业务详情；服务／员工／地点通过 API 从商店获取。请参阅 references/customizing.md。

5. 在本地验证

npm run dev

确认服务已加载、可用性返回了时段，并且测试预约已完成。API 路由会通过 handleApiError 显示实际错误——请阅读错误，不要吞掉它们。

6. 部署到 Vercel

npx vercel

在 Vercel 项目设置中添加相同的环境变量，然后运行 npx vercel --prod。免费套餐足以用于上线；用户只需为预约向 Opencals 付费。

资源预约业务（球场、球道、房间、设备）

有些场所预约的是物品，通常有许多可互换的单元，有时还会提供由员工带领的课程。padel/volt 模板是一个完整示例。请根据实际情况为每种资源建模冲突规则——不要强行把所有内容都归入“员工”。自定义时长使用 allowCustomDuration，而不是时长变体产品。完整详情、三规则决策表、多俱乐部建模以及按俱乐部制定的可用性策略，请参阅 references/resource-booking.md（API 调用形式请参阅 opencals-storefront-api 技能中的 custom-duration.md／availability.md）。

按天预订的租赁（汽车、船只、设备、别墅）

多日租赁不使用时段。每个单元都是一个无员工的产品，基础时长为 1 天（duration: 86400、allowCustomDuration、maxDuration），并使用连续的 24/7 时间表（或不设时间表）。界面读取合并后的可用性时间范围（getCurrentAvailabilitiesMerged，不带 duration），在客户端检查取车到还车的时间是否位于同一范围内，并按商店时区预订从取车日 00:00 到还车日 00:00 的时段，再转换为 UTC。交接时间窗口和航班号通过预约的 customAttributes 传递；押金通过必选复选框确认，并在交接时收取。template-noir 是一个完整示例；完整模式请参阅 references/rentals-multi-day.md。

过夜住宿（别墅、小木屋、民宿、房间）

采用与按天租赁相同的模式，另外还需设置包含 fixedStartTime（入住时间，例如 15:00）和 fixedEndTime（退房时间，例如 11:00）的 fixedTimes。时段从入住日期的 fixedStartTime 开始，到退房日期的 fixedEndTime 结束，使用时间表时区，再转换为 UTC；请根据产品自身的固定时间在服务端构建。API 会对此进行强制校验：客户预约和改期不符合要求时会返回 400（商家预约不受此限制），并按 ceil(booked / base) 计价，因此 N 晚 = N × 价格。退房日可以是下一次入住日。最少入住晚数设在站点内容中，住客人数、到达时间和航班号放在 customAttributes 中。template-bali-villas 是一个完整示例；完整模式请参阅 references/rentals-multi-day.md §11。

学校和课程（语言、音乐、编程、辅导）

无需特殊引擎功能：科目是集合，课程是产品，其变体为级别（小组课，maxAttendees > 1）或时长（私教课，1 个名额）；$0 的 1 个名额产品可用作免费试听，教师是分配到各课程的员工。课程形式（线上还是线下小组课）根据课程的地点类型推导，因此无需依赖 slug。实时“剩余名额”来自时段可用性。Online 地点的 link 是教室 URL，会随已预约的预约记录中的地点一同返回，可用于提供“加入课程”按钮。template-fluently 是一个完整示例；完整模式请参阅 references/classes-and-lessons.md。

健身与普拉提工作室（核心床、瑜伽、芭蕾塑形、动感单车）

采用相同的课程模式，但再细分一层：每个课程 × 工作室 × 教练对应一个变体（flow-mitte-lena），每个变体都有自己的每周日程，工作室是唯一地点，教练是唯一员工，maxAttendees 等于房间内的床位数。房间和床位布局属于模板内容。可用性 API 会在时段满员后将其移除，因此课程表会学习每个系列的每周模式，并将缺失的一周显示为已满，附上“下一个有空位的课程”链接；日期固定的工作坊满员后则直接消失。私教课（1 对 1 和双人课）各占一个席位，并按工作室共享产品池；双人课是一次预订，带有 people: "2" 自定义属性。template-reformer 是完整示例；完整模式请参阅 references/classes-and-lessons.md §6。

资源

• Opencals — 主站
• 文档和 API 参考
• npm 上的 @opencals/storefront-sdk
• Dashboard — 创建商店，管理 storefront API 密钥

注意事项

• 切勿在前端硬编码服务、价格或可用性——这些信息来自 API。
• 切勿臆造 SDK 方法名称。请使用 opencals-storefront-api 技能或模板现有的 app/api/ 路由。
• 前端采用 MIT 许可证：可以从 UI 中移除所有 Opencals 品牌标识。API 本身不是开源的，也不属于你交付的内容。