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

36 lines
3.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 对外契约(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 同口径),并同步更新本节。