EmDash 内容日期时间规范化：UTC ISO 存储、时区换算与夏令时安全迁移实战

• CMS
• 后端
• 前端
• 插件系统

导读

EmDash 是一个基于 Astro 的全栈 TypeScript CMS，其内容模型中的datetime字段此前允许站点写入各种带时区偏移或不带偏移的日期时间格式，导致按时间排序、区间查询和修订记录对比结果不可预期。本篇文章围绕 changeset calm-datetimes-normalize.md 所描述的能力展开：从"所有内容日期时间统一以带固定毫秒的 UTC ISO 字符串存储"这一核心约定讲起，完整梳理管理后台按站点时区换算、API/MCP/CLI 强制显式偏移的写入约束、以及迁移如何以分批、可审计、遇夏令时边界即停的安全方式把存量数据规整为规范形态。读完本文，你将掌握 EmDash 中日期时间字段的完整存储契约、各写入入口的归一化行为，以及升级时迁移工具的报告格式与人工介入条件。

为什么内容日期时间需要统一规范化

在真实的 CMS 场景中，同一个datetime字段的值可能来自多个入口，历史上也积累了多种写法：

• 带时区偏移的 ISO 字符串，如2026-08-22T01:00:00+09:00；
• 不带偏移的"本地时间"，如2026-01-15T09:30；
• 纯日期，如2026-08-22；
• 历史遗留的 JSON 引号包裹值，如"2026-08-21T16:00:00.000Z"。

这些写法语义并不等价：2026-01-15T09:30在纽约和东京代表不同的绝对时刻。当内容库中混存多种写法时，SQL 层面的字符串排序会得到错误的先后顺序，区间查询（"本周发布"）也会漏掉或误纳记录；修订快照对比时，同一时刻的不同写法还会被误判为内容发生了变化。

changeset 给出的解决方案是一条明确且可执行的存储契约：

将每个内容日期时间存储为带固定毫秒的 UTC ISO 字符串（如2026-08-21T16:00:00.000Z）。管理后台通过站点配置的时区换算日期时间字段，而 API、MCP 与 CLI 的写入现在要求Z或显式 UTC 偏移。

这条契约在 datetime-normalization.ts 中得到完整实现：任何被接受的值最终都通过toISOString()折叠为YYYY-MM-DDTHH:mm:ss.sssZ形态，从而让排序、区间查询与修订对比拥有确定性的比较基础。

三种值类别：canonical、offset 与 naive

归一化过程先把输入值分成三类，定义在 datetime-normalization.ts 的DatetimeNormalizationKind中：

类型层面由NormalizedDatetime承载：{ value: string; kind: DatetimeNormalizationKind }。其中kind是迁移审计的关键输入——只有canonical的值被视为无需处理，其余两类都计入noncanonicalCount（见 datetime-storage.ts）。

归一化器的判定规则与错误码

normalizeDatetime(value, timezone)的处理顺序如下（对应 datetime-normalization.ts）：

1. Date实例：直接toISOString()；若为Invalid Date抛invalid。
2. 非字符串：抛invalid。
3. JSON 引号包裹值：尝试JSON.parse解开历史遗留的"..."形式后递归归一化。
4. naive 形态：命中NAIVE_DATETIME_PATTERN（支持YYYY-MM-DD、YYYY-MM-DDTHH:mm、秒、1~3 位小数秒）时走站点时区解析。
5. 显式偏移：必须命中(?:Z|[+-]\d{2}:?\d{2})$且通过z.iso.datetime({ offset: true })校验，否则抛invalid；合法值最终统一为toISOString()，并依据是否与输入逐字相同区分canonical与offset。

解析失败时抛出DatetimeNormalizationError，其code枚举（datetime-normalization.ts）是迁移审计与用户提示的共同依据：

对 API、MCP 与 CLI 写入的强制约束

changeset 明确要求"API、MCP 和 CLI 的写入现在需要Z或显式 UTC 偏移"，对应normalizeExplicitDatetime()（datetime-normalization.ts）：它以"UTC"为站点时区调用通用归一化，一旦结果kind === "naive"立即抛offset_required，从而拒绝无偏移的写入。这一函数被内容仓库在持久化时直接调用（见 content.ts），因此任何通过 API、MCP 或 CLI 提交的无偏移日期时间都会被挡在数据库之外。

管理后台：站点时区驱动的输入输出换算

管理后台的日期时间字段使用<input type="datetime-local">，该输入框本身不含时区概念。为避免使用浏览器本地时区造成"作者在纽约看到的编辑结果与站点东京时区不一致"，后台统一改用站点配置的时区做往返换算，实现位于 datetime-local.ts：

• toDatetimeLocalInputValue(value, timezone)：把存储的 UTC ISO 时刻格式化为站点时区的YYYY-MM-DDTHH:mm供输入框显示；对历史 naive 值则尽量截取其原有本地表示；
• fromDatetimeLocalInputValue(value, timezone)：把用户输入的YYYY-MM-DDTHH:mm解析回站点时区的绝对时刻，再转成 UTC ISO 存储。

值得注意的实现细节（datetime-local.ts）：解析时通过Intl.DateTimeFormat以 6 小时为步长在本地时刻前后 ±48 小时采样时区偏移，然后用候选偏移反推 UTC 时刻、再验证其站点本地表示与输入一致。若候选不唯一或为空，说明该本地时间在站点时区中"出现两次"或"不存在"，直接抛出错误——这与核心归一化器对ambiguous/nonexistent的处理完全同构，确保后台 UI 与后端契约行为一致。

站点时区本身来自options表中的site:timezone配置，读取逻辑见 datetime-storage.ts：未配置或解析失败时默认"UTC"。该配置同时作用于后台编辑与迁移扫描，是整套机制唯一的时区事实来源。

迁移前扫描：报告非规范值并停止于夏令时边界

迁移的第一步是只读预检（preflight），对应scanDatetimeStorage()/normalizeDatetimeStorage()（datetime-storage.ts）。扫描范围包括：

1. 系统日期时间列：created_at、updated_at、published_at、scheduled_at、deleted_at（datetime-storage.ts）；
2. 内容字段：每个集合（ec_<slug>表）中类型为datetime的字段，以及repeater字段内校验信息标记为 datetime 的子字段（datetime-storage.ts）；
3. 修订快照：revisions表中每行的dataJSON，按相同字段描述符归一化（datetime-storage.ts）。

扫描以id > cursor ORDER BY id LIMIT 50的键集分页游标逐批推进（批次大小常量DATETIME_MIGRATION_BATCH_SIZE = 50，见 datetime-storage.ts），避免一次性载入全表。每一处非规范值都会被记录到样本中：

• 普通非规范值记入noncanonicalCount（进一步细分为naiveCount）；
• ambiguous/nonexistent这类需要人来拍板的值记入manualReviewCount；
• 解析/序列化意外错误记入inspectionErrorCount；
• 诊断样本最多保留 50 条（MAX_DIAGNOSTIC_SAMPLES），样本内优先保留需人工审查与错误条目（datetime-storage.ts）。

formatDatetimeStorageReport()（datetime-storage.ts）把结果整理为可读报告，首行形如：

123 noncanonical values (12 naive) using America/New_York

随后逐行列出样本位置（如ec_posts/42.published_at: ...、revisions/9001.data.starts_at (posts/42): ...）与消息，超出样本上限时给出N additional findings omitted。

夏令时边界即停的安全策略

changeset 特别强调：

如果某个值落在重复或跳过的夏令时时段，迁移会在写入之前停止，并报告需要显式偏移的内容行或修订。

对应逻辑在normalizeDatetimeStorage()（datetime-storage.ts）中：预检完成后，若manualReviewCount > 0或inspectionErrorCount > 0，立即抛出异常，不做任何写入。因为2026-11-01T01:30（纽约回拨）与2026-03-08T02:30（纽约前拨）这类时刻在站点时区中根本无法唯一确定（datetime-normalization.test.ts 的it.each用例直接验证了这两个场景），只有内容作者才能为这些值指定正确的偏移。迁移宁可停下，也不猜测。

迁移写入：分批更新与修订快照重写

预检通过且存在非规范值时，迁移才进入写入阶段：

1. 预检：只读扫描，输出报告到 stderr；
2. 写入扫描：以相同游标逐批读取，对每行应用归一化；列变更按DATETIME_UPDATE_COLUMN_BATCH_SIZE = 24（(50-1)/2，见 datetime-storage.ts）再次分片，每条 UPDATE 带id与"变更前的列值"双重谓词（datetime-storage.ts），避免并发写入时覆盖新数据；PostgreSQL 上 repeater 的 JSON 列使用CAST(... AS JSON)并对比CAST(... AS JSONB)保证语义比较；
3. 修订快照重写：仅当data未被并发修改（WHERE data = 原值）时才写回（datetime-storage.ts）；
4. 复检：再次只读扫描，若仍存在任何非规范值或错误，抛出异常，保证迁移要么收敛到 canonical 状态、要么报告失败。

该流程被注册为数据库迁移 079_datetime_normalization.ts：up即执行normalizeDatetimeStorage()，down为空并注释说明"UTC 归一化刻意不可逆，因为原始写法没有携带额外数据"——也就是说，升级前应确保有数据库备份。

与修订对比、排序查询的联动

统一为 UTC ISO 后，内容仓库对datetime字段的持久化一律先经过ContentDatetimeNormalizer（content-datetime.ts）：它从_emdash_fields与_emdash_collections读取集合的 datetime 字段描述符（含 repeater 子字段），结合site:timezone构建上下文，然后调用normalizeContentDatetimes()对顶层字段与 repeater 行内子字段统一归一化；任何DatetimeNormalizationError都会被转换为EmDashValidationError暴露给调用方（content-datetime.ts），保证写入路径的报错信息一致、可读。

normalizeContentDatetimes()的实现（datetime-normalization.ts）还体现了两个工程细节：

• 只处理声明的字段：普通字符串字段即使长得像日期（例如标题里的2026-01-15T09:30）也原样保留（datetime-normalization.test.ts 明确断言了这一点）；
• 不可变更新与计数：仅在发生变更时浅拷贝，并累计changedCount与naiveCount，供审计与报告使用。

这一契约同时惠及修订对比：修订快照中的数据在写入时已统一为规范形态，后续对比不再被"同一时刻、两种写法"这类假差异干扰；排序与区间查询则在统一字符串上获得确定性的字典序/区间语义。

升级到该行为的操作清单

1. 确认站点时区：在后台设置中确认site:timezone正确（默认UTC）。该值同时决定后台输入框换算与迁移时 naive 值的解析基准。
2. 执行迁移：运行包含迁移 079_datetime_normalization.ts 的emdash migrate类命令（具体命令以当前版本 CLI 为准）。迁移会先输出预检报告。
3. 处理人工审查项：若报告出现N require manual review，说明存在落在夏令时边界（重复或跳过时段）的值，迁移已停止写入；需为报告列出的内容行或修订补充显式偏移后再重跑。
4. 核对收敛结果：迁移结束时会复检，确保全库达到 canonical 状态；down不可逆，升级前请备份数据库。
5. 约束外部写入方：API、MCP、CLI 现在要求Z或显式 UTC 偏移；脚本与集成方应改用normalizeExplicitDatetime的语义（拒绝 naive 值），或先经站点时区换算再提交。

小结

EmDash 的日期时间规范化不是一次性的数据清理，而是一套贯穿存储、编辑、写入与迁移的完整契约：存储层统一为带固定毫秒的 UTC ISO 字符串（datetime-normalization.ts）；管理后台以站点时区往返换算（datetime-local.ts）；API/MCP/CLI 强制显式偏移；迁移工具以 50 行分批扫描、变更前值双重谓词防覆盖、夏令时边界即停并在写入后复检（datetime-storage.ts）。对内容作者而言，站点时区下无法唯一确定的时刻永远需要人工介入；对开发者而言，这套规则保证了排序、区间查询与修订对比在升级后拥有一致的比较基础。

• CMS
• 后端
• 前端
• 插件系统