系统业务时区与常规设置¶
系统设置中的「常规设置」提供全局 IANA 时区、12/24 小时制和日期格式。默认
Asia/Shanghai、24 小时制、YYYY-MM-DD。这些设置由管理员发布，对所有用户生效。
中国大陆等无夏令时地区无需季节切换；有夏令时的地区按事件日期的时区规则处理。
配置与传播¶
runtime_configuration 的 general 文档是权威来源。管理员通过现有
GET/POST /api/config/runtime/general 读取和发布，提交 expectedRevision 防止覆盖
并发修改，发布保存版本历史并写审计。GET /api/system/preferences 为所有已认证
用户提供格式设置及 revision；GET /api/system/timezones 提供时区名、当前偏移和
本年季节调整信息。无写权限的用户不能发布配置。
服务端启动时验证配置；无效持久化配置会阻止启动，避免悄悄使用另一时区。 实例每 5 秒检查数据库版本，客户端在恢复焦点、恢复可见及每 30 秒检查配置。 前端首次加载失败时提示重试，不在错误时区下打开业务页面。后台刷新失败保留最近 一次有效配置，服务端记录错误。
时间契约¶
- 数据库连接使用 UTC。
TIMESTAMPTZ和 Unix 秒/毫秒字段继续表示绝对时刻，切换 设置不改写这些值。现有字段的秒/毫秒单位不变。 - 业务日期、图表、邮件和控制台可读时间采用系统时区；结构化日志保留绝对时间。
- 日期输入标注系统时区。不存在的当地时间被拒绝，重复时间必须选择 UTC 偏移。
- 超时、重试、租约、会话有效期和「最近 24 小时」按实际经过时间计算。
- 自然日/周/月用日历边界计算；跨夏令时的自然日可为 23 或 25 小时。
- 定时发送遇到重复时间采用首次出现；遇到时钟跳跃顺延到下一个有效分钟。
- 时区数据库来自
chrono-tz；浏览器使用其 Intl 时区数据，选择列表会过滤浏览器 不支持的名称。更新时区规则时需更新依赖和浏览器。
报告与历史数据¶
启动数据库初始化会执行可重复运行的 migrate_system_time.sql：
- 报告保存生成时的 timezone、settings_revision 和 UTC 周期边界；生成中、归档、 修订、导出和重发邮件均保留该报告自己的日历规则。
- 更改时区会在同一事务内重置未来报告调度起点；从下一完整周期开始，不补发之前 的历史。调度发布检查配置版本，旧版本无法发布。已排队的报告按旧快照完成。
- 新的 IP 发现事实保留
first_observed_atUTC 时间，按查询时区归日。 - 旧事实只有上海
day_start时，由已启用的分析快照 worker 自动加入可重试回填 队列。也可使用现有--rebuild-analytics-snapshots命令重建。 - 在其他时区查询未回填的旧事实，接口返回明确的
analytics_timezone_backfill_required；不能准确恢复的原始数据不会被伪造为新日期。 原始观测已删除时，保留旧事实，但该历史范围无法转换。
验证¶
后端执行 cargo fmt --check、cargo clippy --all-targets、cargo test。
报告和统计集成测试使用独立测试库，设置 REPORT_TEST_DATABASE_URL 或
ANALYTICS_TEST_DATABASE_URL，通过 --ignored 显式运行。
前端执行 pnpm test:time、pnpm build，并检查设置加载失败、保存冲突、不同浏览器
时区、夏令时缺口及重复时间、移动端布局。