# 对外契约(contract) > 🔴 本文件记录 **tdc-rs 对外可观测的契约**:口径、形状、边界。 > 与 `docs/decisions.md`(为什么这么定)/ `docs/known-limitations.md`(已知偏差)配套读。 > > **当前状态**:v3 改造批次 B1b 进行中,本文件先落地「时间口径」一节(C12 要求); > 其余章节在 B5 补齐。 --- ## 时间口径 仓里有**两套**时间口径,**不是随手写的**——各对应上游的一个具体行为: | 面 | 口径 | 代码位置 | 上游对照 | 为什么是它 | |---|---|---|---|---| | 业务编码(`PRO-` / `RES-` / `API-` / `DS-` 的日期与时刻段) | **服务器本地时区** | `src/tdc/util/code.rs:37`(`day_prefix`)、`src/tdc/util/code.rs:58`(`format_code`)⇒ `Local::now()` | `TdcCodeUtil.dayPrefix` / `TdcCodeUtil.format` 用 `LocalDateTime.now()`(Java,服务器本地) | 编码里的 `yyyyMMdd-HHmmss` 要与上游**同一天同刻**;差一个时区偏移时,跨零点的 8 小时里日期段会直接变成前一天 | | DB 审计列(`f_creator_time` / `f_modify_time` / `f_delete_time` …) | **服务器本地时区** | `src/tdc/service/crud.rs:520`、`:524`、`:530`、`:624`、`:688` ⇒ SQL `now()` | JNPF `BaseEntity` 自动填充用 `new Date()`(服务器本地) | 审计列的时间戳要与上游同一量纲,便于两边的日志按时间轴对齐 | | 账号库自己的审计字段(`creator_time`) | **UTC** | `src/tdc/service/account.rs:290`(`now_iso`)⇒ `chrono::Utc::now()` | 上游 j7 的 `base_user` 走 MySQL 填充,**本仓这一格没有上游对照物**(账号层原是本机 JSON 文件) | 本仓自有格式 ⇒ 选**与时区无关**的 UTC,避免换机器/换时区后同一条记录的时间戳含义漂移 | 🔴 **收敛后的规矩**(v3 spec §2.3.1 C12): 1. **仓里不再手写日历算法** —— 一律用 `chrono`(已依赖 `chrono 0.4`,`features = ["clock"]`)。 此前 `account.rs` 自己实现了一套天元纪日 → 公历的换算(`civil_from_days`)⇒ 重复造轮子, 且与 `code.rs` 的时区口径不一致(一个 UTC 一个本地)⇒ 手工算法与它的推论一起删除。 2. **口径写在代码注释里**(不是只在文档里):谁想改时区,必须先改那处的注释 ⇒ 评审时看得见。 3. ⚠️ **别把 UTC 写成 Local**:账号层的 `now_iso` 用 `chrono::Utc::now()`; 换成 `Local::now()` 在非 UTC 时区下会**静默改值**(`src/tdc/service/account.rs` 的单测 `now_iso_is_utc_and_parsable` 会红)。 4. ⚠️ **别把 Local 写成 UTC**:业务编码与 DB 审计列必须留在**服务器本地时区**, 否则同一时刻生成的编码与上游对不上(见上表第一行)。 📌 **B4 之后的注意**:账号层从本机 JSON 文件迁到 `base_user` 表后, `f_creator_time` 这一格会从「UTC(本仓自有格式)」变成「DB `now()`(服务器本地时区)」—— 那时**以表为准**(与上游 j7 同口径),并同步更新本节。