时区是预约功能的坟场：vibe 项目的日历预约实战

引子：看起来最简单的功能，坑最深

每个做过预约功能的开发者，动手前都觉得这是个"三天搞定"的需求：选个日期、挑个时间段、存进数据库、发个提醒。动手后才发现，这玩意儿是时间、并发、分布式系统三座大山交汇的地方。

先看三个经典翻车现场。翻车一：美国夏令时切换那天（3 月第二个周日凌晨 2 点直接跳到 3 点），你的系统里凭空多出了一批"2:30 的预约"——那个时间点在那一天根本不存在，两个用户被安排进了同一个"不存在"的时间段。翻车二：你的用户在北京约了和纽约客户的会，页面上显示的是北京时间，邮件提醒里写的是纽约时间，客户准时出现时，你的用户还在吃午饭——显示层和通知层用了两套时区逻辑。翻车三：用户设了"每周三上午 10 点"的重复预约，跨年之后全乱了——你的重复规则实现把 12 月 30 日（周三）之后直接跳到了 1 月 6 日，看似没错，但那年 1 月 1 日是周五，真正的"每周三"应该是 1 月 7 日……你的 RRULE 解析器在闰周边界上翻了车。

这三个翻车的共同根因：把时间当成了字符串，把时区当成了展示问题。时间是预约系统的核心领域模型，时区是它最锋利的边角。这篇指南把预约功能拆成五块硬骨头：路线选择、时区工程、可用性引擎、履约闭环、测试清单，啃完你就能交付一个经得起夏令时考验的预约系统。

路线选择：Cal.com 还是全自建？

动手写代码之前，先回答一个战略问题：你要不要自己造这个轮子？预约赛道有个成熟的开源答案——Cal.com（MIT 协议，可自托管、可嵌入）。先看决策表：

• 选 Cal.com 自托管 / 嵌入：如果你的预约需求是"标准形态"——1 对 1 会议、多人排班、付费预约——直接用它。一台 2C4G 的 VPS 就能跑，嵌入方式有 iframe 和 API 两种。代价是定制天花板：它的 UI 和数据模型是为"会议预约"设计的，你要做的是"带复杂业务规则的预约"（比如医疗分诊、带资源锁定的场地预约），改起来比重写还痛苦。
• 选全自建：当预约是你的核心差异化（比如预约逻辑本身就是你的产品）、或者你需要把预约深度嵌入现有业务流（预约→支付→核销→评价一条链），自建。代价是你要亲手踩完本文后面所有的坑——这篇指南就是为这条路准备的。

一个经验法则：如果你的预约需求用三句话能讲完，用 Cal.com；如果讲了五分钟还没讲完，自建。最惨的是中间态——用 Cal.com 改到一半发现改不动，又推倒自建，两份工都白打了。

另外注意授权与成本：Cal.com 自托管免费，但你要自己管升级、备份和可用性；它的 Cloud 版按用户收费，团队小的时候反而比自建便宜。别为了"省钱"自托管一个你没时间运维的服务——运维成本是自建报价单里最容易被漏掉的一行。

时区工程：永远存 UTC，显示时再转

这是全文最重要的一节，也是翻车率最高的一节。先看数据流图：

图 1：时区工程数据流。铁律：永远存 UTC，显示时转本地；浮动时间与绝对时间走不同模型。

铁律一：存储层只认 UTC

数据库里存什么？永远存 UTC 时间戳。Postgres 用 timestamptz，MySQL 用 DATETIME 存 UTC（MySQL 的 TIMESTAMP 有隐式转换的坑，vibe 项目建议统一用 DATETIME 存 UTC 并在应用层约定）。绝不存"2026-10-20 10:00"这种裸本地时间——没有时区信息的时间字符串是定时炸弹，它在你做跨时区查询、做夏令时计算、做数据迁移的每一个环节都会炸。

但只存 UTC 还不够。预约还有第二个维度：事件发生的时区。比如用户在纽约约了"每周三 10 点（纽约时间）"，存 UTC 是 2026-10-21T14:00:00Z，同时要存 event_timezone = 'America/New_York'。为什么？因为夏令时切换后，"每周三 10 点（纽约时间）"对应的 UTC 会变（EDT 是 UTC-4，EST 是 UTC-5）。只存 UTC，你的重复预约在 11 月第一个周日之后会整体漂移一小时——这是预约系统最经典的慢刀子 bug，用户要过半年才发现。

-- 预约表：UTC 时间 + 事件时区，双列缺一不可
CREATE TABLE bookings (
  id            UUID PRIMARY KEY,
  starts_at     TIMESTAMPTZ NOT NULL,  -- UTC，排序/冲突检测都用它
  ends_at       TIMESTAMPTZ NOT NULL,
  event_tz      TEXT NOT NULL,         -- IANA 时区，如 America/New_York
  rrule         TEXT,                  -- 重复规则（见下节）
  status        TEXT NOT NULL DEFAULT 'pending',
  created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

铁律二：IANA 时区库，不要自己算偏移

时区不是"UTC+8"这种固定偏移——时区是规则，偏移是结果。北京是固定 UTC+8 没错，但纽约在一年里会在 UTC-4 和 UTC-5 之间横跳，历史上还改过切换日期。用 IANA 时区库（tzdata），所有语言都有成熟实现：Python 的 zoneinfo、Node 的 luxon / date-fns-tz、Go 的 time.LoadLocation。自己写"夏令时判断函数"是自杀行为——tzdata 每年更新好几次，各国政府说改就改。

前端有个配套坑：new Date() 用的是用户设备的本地时区，而你的业务时区可能是另一个。正确姿势是：前端只负责采集"本地时间 + IANA 时区名"，转换全部在服务端做。把 Intl.DateTimeFormat().resolvedOptions().timeZone 拿到的时区名传给后端，别传偏移量——偏移量在 DST 边界是错的。

铁律三：分清"浮动时间"和"绝对时间"

这是时区工程里最被低估的一课。绝对时间（会议、预约、航班）锚定在时间线上的一个点，随观察者时区改变显示；浮动时间（生日、节假日、"每天早上 8 点吃药"）锚定在"当地 wall clock"上，不做时区转换。

预约系统里 99% 是绝对时间，但有两个例外最容易错：一是"营业时间"（"周一到周五 9:00-18:00"）——这是浮动时间，要按商家所在时区的 wall clock 存（存"09:00"字符串 + 商家时区），不能转成 UTC 存，否则夏令时一切换，商家的营业时间就漂了。二是生日/纪念日提醒——存 date 类型，别存 timestamptz，否则跨时区用户会在"昨天"收到生日提醒。

夏令时边界测试清单

夏令时切换日是预约功能的期末考试。上线前，先在测试环境造出这几天的完整数据：

• 跳变日（spring forward）：2026 年美国是 3 月 8 日，凌晨 2:00→3:00，"2:30"不存在。测试：用户试图约 2:30，系统必须拒绝或明确提示，不能静默存成 3:30。
• 回拨日（fall back）：2026 年美国是 11 月 1 日，凌晨 2:00 出现两次（EDT 1:30 和 EST 1:30 是两个不同的 UTC 时刻）。测试：约"11 月 1 日 1:30"必须让用户明确选"夏令时的 1:30 还是标准时的 1:30"，含糊过去就是超卖。
• 跨切换日的重复预约："每周三 10 点（纽约时间）"横跨 11 月 1 日，切换后的实例必须还是当地 10 点，而不是 UTC 不变导致漂成 9 点。

记住：夏令时 bug 的特点是"半年后才爆发"。3 月写的代码，11 月才炸，中间你早就忘了这段逻辑。所以测试数据必须"穿越"到切换日去造，不能只测"下周三"。

可用性引擎：把"能不能约"算对

时区解决"时间是什么"，可用性引擎解决"哪个时间能约"。它由四块组成：营业时间建模、缓冲时间、重复规则、冲突检测。

营业时间建模

营业时间是"浮动时间"（见上节），按商家时区的 wall clock 建模。推荐的数据结构：按星期几存时间段数组，特殊日期（节假日、临时休息）用覆盖表。

// 营业时间：周维度模板 + 日期维度覆盖
{
  "timezone": "Asia/Shanghai",
  "weekly": {
    "1": [["09:00","12:00"],["13:30","18:00"]],  // 周一
    "2": [["09:00","12:00"],["13:30","18:00"]],
    ...
    "0": []                                      // 周日休息
  },
  "overrides": {
    "2026-10-25": [],                            // 临时休息：覆盖为空
    "2026-10-01": [["10:00","16:00"]]            // 节假日缩短营业
  }
}

关键设计：overrides 永远优先于 weekly 模板，查询某天可用性时先查覆盖表。这个结构简单到可以用 JSONB 存，vibe 项目别急着建一堆关系表。

缓冲时间：前后各留 15 分钟

缓冲时间（buffer）是预约系统里最容易被"优化"掉、又最不该被优化掉的东西。10:00-10:30 的预约，如果 10:30-11:00 又约了一个，服务提供者连喝水的时间都没有。实现上，缓冲时间要参与冲突检测：一个预约的"占用区间"是 [starts_at - buffer_before, ends_at + buffer_after]，而不是 [starts_at, ends_at]。

给个判断标准：如果你的冲突检测没考虑缓冲时间，你的系统在第一天就会超卖——只不过超卖的是"人的精力"而不是"座位"，更难发现，伤害更大。

重复规则 RRULE：别自己发明轮子

重复预约（"每周三 10 点""每月 1 号"）用 RRULE（RFC 5545）表达，这是日历领域的事实标准，Google Calendar、Apple Calendar 都认它。Python 有 dateutil.rrule，JS 有 rrule.js，别自己写"每周几"的解析器——你处理不了"每月的第三个周五"这种规则。

RRULE 有两个实战要点。第一，展开（expansion）要有边界：查询"未来 3 个月有哪些实例"，在内存里展开 RRULE 再过滤，别试图在 SQL 里解析 RRULE。第二，单个实例的改期/取消用 RECURRENCE-ID 语义：不要改整条规则，而是为那个实例建一条"例外记录"（这一天改到几点 / 这一天取消），查询时把例外叠加上去。这是 Google Calendar 的做法，也是唯一经得起考验的做法。

冲突检测算法（含可直接用的代码）

冲突检测是预约系统的心脏，逻辑却出奇地简单：两个区间重叠 ⟺ A.start < B.end 且 B.start < A.end。记住这个充要条件，能排除 90% 的手写 bug（很多人写成"包含"判断，漏掉"部分重叠"的情况）。

-- 新预约 [p_start, p_end) 是否与已有 confirmed 冲突（含缓冲）
-- 区间重叠充要条件：existing.starts_at < p_end AND existing.ends_at > p_start
SELECT COUNT(*) > 0 AS has_conflict
FROM bookings
WHERE resource_id = $1
  AND status = 'confirmed'
  AND starts_at < $3   -- $3 = p_end + buffer_after
  AND ends_at   > $2;  -- $2 = p_start - buffer_before

但 SQL 只是"检测"，真正的坑在并发：两个用户同时看到"10:00 可约"，同时提交，检测都通过了，结果超卖。解法是检测 + 插入必须在同一个事务里，并对资源加行锁（SELECT ... FOR UPDATE 锁资源行，或用唯一约束做幂等）。vibe 项目最常见的翻车就是"检测和写入之间隔了一次网络往返"——把这两步包进一个事务，超卖就消失了。

预约状态机也值得一张图——它定义了"一个预约一生的所有合法路径"：

图 2：预约状态机。状态转换必须写进事务：确认与锁档期原子提交，否则超卖。

状态机的实战价值在于它逼你回答所有"然后呢"：待确认超时未处理怎么办（自动取消还是自动确认？）？已确认的预约用户没出现怎么办（标记爽约，扣信用分）？已取消的档期什么时候释放（立即）？每个箭头都对应一段代码，没有箭头的转换就是 bug 的温床。

履约闭环：约上了只是开始

很多 vibe 项目的预约功能做到"能下单"就停了，结果爽约率 40%，商家骂声一片。预约的价值不在"约上"，在"履约"。

确认与提醒：邮件 + 短信双通道

提醒策略的黄金组合：T-24h 邮件 + T-2h 短信。邮件负责"详细信息"（时间、地点、改期链接），短信负责"别忘了"（短、醒目）。为什么是双通道？邮件的打开率撑死 30%，短信 90%+，但短信贵——24 小时前用便宜的邮件，2 小时前用贵的短信，成本和效果的最优解。

提醒时间有个时区细节："提前 24 小时"按绝对时间算（UTC 减 24h），但"发送内容里的时间"按用户本地时区显示。混淆这两者，就会出现"提醒说会议在 10 点，用户理解成自己时区的 10 点，实际是对方时区的 10 点"的惨案。定时任务（cron / 延迟队列）扫描"未来 24h 内未提醒的已确认预约"，用 UTC 比较，雷打不动。

改期 / 取消政策：写进代码，而不是写进客服话术

政策必须代码化：提前多久可免费取消（比如 24h）、改期次数上限、爽约几次进黑名单。示例规则——"开始前 24h 内取消收 50% 取消费；开始前 2h 内取消视为爽约"。这些规则写进配置表，客服只负责执行，不负责解释。政策模糊的预约系统，客服就是人肉状态机，累死还总被投诉双标。

爽约处理：信用体系的起点

爽约（no-show）不处理，守约的用户就是在为爽约者买单。轻量方案：爽约 1 次警告、2 次 30 天内只能约"次日达"档（降低商家损失）、3 次冻结预约权限。数据记在用户画像里，风控层也能用上——一个在 A 商家总爽约的用户，在 B 商家大概率也一样。

Google Calendar 双向同步：能避就避，避不开就这么做

双向同步是预约功能里著名的"看起来很美"：你要处理 Google 侧的变更推送（webhook）、冲突消解（两边同时改了怎么办）、删除语义（Google 删了算取消还是算隐藏）。实战建议：第一版只做单向同步（你的系统 → Google Calendar），用 Google Calendar API 创建事件、把事件 ID 存下来；用户改期时更新对应事件。双向同步等你有专职后端再碰——它的复杂度是一个独立项目，不是"一个功能"。

测试清单：12 个必测用例

最后是上线前的 12 个必测用例。建议写成自动化测试，而不是手动点一遍——时区 bug 的可怕之处在于"半年后才爆发"，手动测试保证不了回归。

• 跨天：预约 23:30-00:30，结束日期必须落在第二天，账单/统计按"开始日期"归属，别按结束日期。
• 跨月：1 月 31 日的"每月 1 次"重复，下个月是 2 月 28 日（不是 3 月 3 日），RRULE 库默认行为要验证。
• 夏令时跳变日：2026-03-08（美）2:30 的预约必须被拒绝或明确提示，不能静默存成 3:30。
• 夏令时回拨日：2026-11-01（美）1:30 出现两次，必须让用户二选一，不能含糊。
• 跨切换日的重复预约："每周三 10 点（纽约）"横跨 11 月 1 日，切换后仍是当地 10 点。
• 闰年 2 月 29 日："每年 2 月 29 日"的重复在平年怎么处理（2 月 28 日还是跳过）？产品要定，代码要实现，测试要覆盖。
• 跨年重复："每周三"横跨 12 月 31 日，年周边界（ISO 周）别算错。
• 并发超卖：两个请求同时约同一档期，必须只有一个成功。用并发测试打 50 个并行请求验证。
• 缓冲时间参与冲突：10:00-10:30（后缓冲 15 分钟）与 10:30-11:00 必须判冲突。
• 改期到已占用档期：改期本质是"取消 + 新约"，新约必须重新走冲突检测，不能跳过。
• 取消后档期立即释放：取消的事务提交后，同一档期必须可被再次预约，无缓存残留。
• 提醒时区正确性：给跨时区用户发提醒，邮件里的"会议时间"按收件人时区显示，用固定用例断言字符串。

一句话总结：预约功能的质量 = 时区正确性 × 并发安全性 × 履约闭环，三项里任何一项是零，总分就是零。时区用 UTC + IANA + 双列存储打底，冲突检测用"重叠充要条件 + 事务行锁"封顶，提醒用 T-24h/T-2h 双通道收尾——这三板斧抡圆了，你的预约系统就能活过第一个夏令时。