agilelabs-fx-docs main framework-standards/checks/time-and-timezone.md

时间与时区检查

本页用于检查项目在时间存储、时间传输、前端输入和前端展示四个环节是否遵循统一规则。

检查目标

  • 判断时间语义是否在存储、传输、输入和展示四层保持一致。
  • 判断是否存在时区漂移、时间字符串混用或字段语义混淆。
  • 判断项目级时间 resolver 是否建立在统一规则之上。

必查项

  • 存储层是否保持 UTC 语义。
  • API 是否统一传输毫秒 Unix timestamp。
  • 前端展示前是否转换为浏览器本地时间。
  • 前端输入本地时间后是否转换为 UTC 时间戳再发送。
  • 审计时间、展示时间和并发版本字段是否分开设计。

判定标准

  • 四层语义清晰、字段职责明确,判定为合规。
  • 若接口混用时间戳和 ISO 字符串,判定为不合规。
  • 若前端直接展示服务端 UTC 值而不做本地化处理,判定为不合规。
  • 若版本字段被当成展示时间使用,判定为语义错误。

常见不合规信号

  • 同一模块有的接口返回时间戳,有的接口返回字符串时间。
  • 代码里直接用服务器本地时间替代用户时区。
  • 页面把用户输入的本地时间原样提交给后端。
  • ts 这类并发字段被前端当成业务时间展示。

规则依据

示例项目对照