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]>
This commit is contained in:
1 parent
fbee7ae860
commit
d4a22e18b0
7 files changed
+126
-36
No files matched your search
@@ -0,0 +1,35 @@
|
||||
# 对外契约(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 同口径),并同步更新本节。
|
||||
@@ -0,0 +1,33 @@
|
||||
# 决策记录(decisions)
|
||||
|
||||
> 🔴 本文件是**为什么这么定**的唯一去处:每条 = 编号 / 决策 / 取值 / 来源。
|
||||
> 规格原文见 `docs/superpowers/specs/2026-10-26-tdc-rs-mvc-align-v3-design.md` §12(D1–D16 的全文在那边)。
|
||||
> 与 `docs/contract.md`(对外形状)/ `docs/known-limitations.md`(已知偏差)配套读。
|
||||
|
||||
| # | 决策 | 取值 | 来源 |
|
||||
|---|---|---|---|
|
||||
| D1 | 前端 | 继续用上游 Vue SPA(不做面 B) | 用户拍板 |
|
||||
| D2 | 业务边界 | 与上游一致,**分批**,本批只做底座 | 用户拍板 |
|
||||
| D3 | 业务包 MVC | 对位上游包结构 + **保留通用引擎** | 用户拍板 |
|
||||
| D4 | 库 | 单库 | 用户拍板 |
|
||||
| D5 | 账号层 | 一步切 `base_user`(官方双 md5) | 用户拍板 |
|
||||
| D6 | 权限 | **按上游**(角色码 + 管理员位,删 18 键) | 用户拍板 |
|
||||
| D7 | 面 B / `perm-smoke-jnpf.sh` | **不做** | 由 D1 推导 |
|
||||
| D8 | 存量 `accounts.json` 账号 | **不导入**(D5 推导;文件保留不删) | 由 D5 推导 |
|
||||
| D9 | `tdsReadOnly` | 判据在、种子不种(照抄上游不一致) | spec §4.1 |
|
||||
| D10 | 借技能的工程化外壳,不借契约层 | 分层 / 尺子 / 文档 / 手册可借;契约层一律不借(面 A·面 B · 600/602 信封 · `base_module` 菜单 · 复合主键) | 2026-10-26 对标技能 `ssw-jnpf-lite-rust` |
|
||||
| D11 | 权限宽严**维持追平上游 = 显式敞开 + 显式记账** | **不**收紧为 fail-closed(会造出与上游不一致的新偏差) | spec §5.2 / §5.4 |
|
||||
| D12 | 技能化本批不做 | 阻塞在分发形态(`static/` 定位依赖 `current_exe()` 向上找)⇒ 先做文档层(B5) | spec §0.4 / §11.3 |
|
||||
| D13 | B1 拆成 B1a(尺子先行)+ B1b(搬家 + 边界收敛) | `cargo test` 不覆盖 HTTP 层 ⇒ 无尺子不搬家;B1a 先锁基线断言数 N,B1b 后必须 == N | spec §2.4 / §8 |
|
||||
| D14 | `codec.rs` 归**业务层** `tdc/util/code.rs` | 它是业务编码生成器(`PRO`/`RES`/`API`/`DS`),不是序列化 codec;`ids.rs` 留平台层 | spec §2.1 |
|
||||
| D15 | `tdc_identity` **双读写路径显式承认 + 收口 + 记账** | 不硬收进引擎(上游无「通用引擎」概念)⇒ 领域 SQL 收进 `src/tdc/service/identity.rs`、只 SELECT 明确列、记进 `docs/known-limitations.md` L1 | spec §2.3.1 C10 / S8 |
|
||||
| D16 | numeric 列输出 JSON **数字**(不是 JSON 字符串) | 上游 `ProductEntity.java:88` 的 `BigDecimal` 只带 `@TableField`(无 `@JsonSerialize`)⇒ Jackson 默认 ⇒ 数字 | 2026-10-26 B1a 复核上游取证链 |
|
||||
| **D17** | **鉴权白名单按**实际**清单剪 9 条**(不是 spec 预估的 7 条) | 上游 `gateway.white-url` 里 P2P 是 **5** 条(不是 4)⇒ 实际死路径 9 条 ⇒ 本仓照抄**实际**清单,账本逐条记明 | 2026-10-26 B1b C5(清单见 `src/tdc/support/public_paths.rs`) |
|
||||
| **D18** | **时间口径 = 两套,各自绑定上游对照物** | C12 的「口径统一为 **UTC**」若**全仓**执行 ⇒ 业务编码与 DB 审计列从服务器本地时区变 UTC ⇒ ①违反 B1b「行为零变化」②**产生新的对上游偏差**(上游 `TdcCodeUtil` 用 `LocalDateTime.now()`、审计列用 MySQL `now()`,都是服务器本地;跨零点的 8 小时里编码日期段直接差一天)⇒ **不做全仓 UTC**。落地口径:**① 仓里不再手写日历算法,一律 `chrono`;② 账号库自有审计字段 = UTC**(本仓自有格式、无上游对照物;替换实现时**保持**原值 ⇒ 零行为变化);**③ 业务编码与 DB 审计列 = 服务器本地时区**(有上游对照物 ⇒ 必须同口径)。对照表写在 `docs/contract.md` §时间口径 | 2026-10-26 B1b C12(复核上游 `TdcCodeUtil.java`) |
|
||||
|
||||
---
|
||||
|
||||
## 补记说明
|
||||
|
||||
- **D1–D16** 的完整措辞(含来源链)在 v3 spec §12;本表只留一行摘要,方便日常查。
|
||||
- **D17 / D18** 是 v3 spec 落点(`06f5a79`)之后、执行中追加的决策 ⇒ 只住本文件。
|
||||
Reference in new issue
Block a user