Files
tdc-rs/docs/contract.md
T
adminandClaude Opus 4.8 d4a22e18b0 refactor(b1b-c12): 手写日历算法换 chrono —— 时间口径写进 contract.md
影响:仓里不再有第二套日期换算实现;对外行为零变化
(239 条测试全绿、冒烟断言数仍 75、边界与实体自检全绿)。

改动:
- src/tdc/service/account.rs:删手写 civil_from_days(天元纪日换算)与手拼
  now_iso(),一律 chrono(Utc::now().format("%Y-%m-%d %H:%M:%S"))
  ⇒ 输出值与原来逐字相同;单测换成 now_iso_is_utc_and_parsable
    (形状可解析 + 与 Utc::now() 差 ≤ 5 秒 ⇒ 有人改成 Local::now() 会红)
- src/tdc/util/code.rs / src/tdc/service/crud.rs:补口径注释(业务编码与
  DB 审计列 = 服务器本地时区,与上游 LocalDateTime.now()/now() 同口径)
- docs/contract.md(新):时间口径对照表(含 file:line 引用)
- docs/decisions.md(新):决策日志 D1–D16 摘要 + 补记 D17 + 新增 D18
- CLAUDE.md / .workbuddy/memory/2026-10-26.md 同步

设计:spec 的「口径统一为 UTC」没有全仓执行(记 D18)—— 全仓 UTC 会让业务
编码的日期段在上游的 8 小时错位窗口里差一天 ⇒ 造出新的对上游偏差,且违反
B1b「行为零变化」;落地口径 = 账号库自有审计字段用 UTC(无上游对照物),
业务编码与 DB 审计列用服务器本地时区(有上游对照物)。

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
2026-10-26 22:38:24 +08:00

3.0 KiB
Raw Blame History

对外契约(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 同口径),并同步更新本节。