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

时间与时区规范

本页定义 AgileLabs Framework 项目在存储、传输、输入和展示四个环节中的正式时间规则。

适用场景

  • API 入参与出参中的时间字段。
  • 审计字段、版本字段、日志时间和任务调度时间。
  • 用户本地时间展示与跨时区业务。

必须遵守

  • 存储层时间优先使用 UTC 语义，审计字段默认采用 DateTimeOffset.UtcNow。
  • 前后端传输时间统一使用 Unix timestamp，精度固定为毫秒 ms。
  • 禁止把 ISO 时间字符串作为默认接口格式。
  • 前端展示时间前必须转换为浏览器本地时间。
  • 前端输入本地时间后，发送到远端前必须转换为 UTC 时间戳。
  • 不把服务器本地时区当作用户时区，不混用展示时间和并发版本字段。

推荐做法

  • 传输层统一用时间戳，展示层统一由前端或项目级 resolver 按用户时区转换。
  • 审计时间、展示时间、调度时间和版本字段分别命名，不复用一个字段承担多种语义。
  • 当项目需要复杂的用户时区决策时，在 WorkContext 或项目级 resolver 上扩展，而不是把逻辑散落在页面与控制器中。
  • 维护旧接口时先文档化当前语义，再安排收敛。

运作机制

  • 时间问题要拆成四层看：存储语义、传输语义、输入语义、展示语义。四层不区分清楚，项目很容易出现“看上去没错，跨时区后全错”的问题。
  • 框架和现有案例已经体现了 UTC 存储、项目级 resolver 和时间戳序列化转换的组合方式。
  • 统一使用毫秒时间戳，是为了降低浏览器端和前端生态中的换算成本，并减少字符串时区解析歧义。

常见问题

  • “为什么不直接用 ISO 时间字符串？” 因为字符串解析、时区偏移和前端运行环境差异容易产生歧义。默认协议统一用毫秒时间戳更稳定。
  • “用户输入的是本地时间，为什么发送时还要转 UTC？” 因为远端保存和跨端传输需要统一语义，本地输入只是交互形式，不是存储和传输格式。
  • “版本字段 ts 能不能直接展示给用户？” 不能。版本字段服务于并发控制，不等于业务展示时间。

相关检查

示例项目对照