diff --git a/.workbuddy/memory/2026-10-26.md b/.workbuddy/memory/2026-10-26.md index eab536d..bd145b3 100644 --- a/.workbuddy/memory/2026-10-26.md +++ b/.workbuddy/memory/2026-10-26.md @@ -124,7 +124,8 @@ cargo test → exit 0(全绿) | C8 | 配置分家:平台 `Config` 削掉 5 个业务字段,业务配置进 `tdc::config::TdcConfig` | `1797aa0` | | C9 | 状态分家:平台 `AppState` 只留配置/db/锁/会话,业务态进 `tdc::state::TdcState`(Deref + FromRef) | `49e5fce` | | C10 | `tdc_identity` 领域 SQL 收进 `tdc::service::identity`(控制器不再自己拼);只 SELECT 明确列 | `3076bda` | -| C11 | `constant_time_eq` 上收到 `src/platform/compare.rs`(两份实现合一) | 本次提交 | +| C11 | `constant_time_eq` 上收到 `src/platform/compare.rs`(两份实现合一) | `fbee7ae` | +| C12 | 删手写日历算法(`civil_from_days` / `now_iso`),一律 `chrono`;时间口径写进 `docs/contract.md` | 本次提交 | **关键决定** @@ -152,6 +153,21 @@ cargo test → exit 0(全绿) 业务侧用 `pub use` 复用 ⇒ `identity::constant_time_eq` / `account::constant_time_eq` 两个旧路径都还在,调用方零改动,但**实现只有一份**。 +**C12 的做法(口径分两套,不是随手写的)**: + +- 删掉 `src/tdc/service/account.rs` 里手写的天元纪日换算(`civil_from_days`) + 与手拼的 `now_iso()` ⇒ 一律 `chrono`(`Utc::now().format("%Y-%m-%d %H:%M:%S")`,**值与原来逐字相同** ⇒ 零行为变化)。 +- 🔴 **spec 的「口径统一为 UTC」没有全仓执行**(记 **D18**): + 上游 `TdcCodeUtil` 用 `LocalDateTime.now()`、审计列用 MySQL `now()` ⇒ 都是**服务器本地时区**; + 全仓改 UTC 会让业务编码的日期段在上游的 8 小时错位窗口里**直接差一天** ⇒ **产生新的对上游偏差**, + 且违反 B1b「行为零变化」。 + ⇒ 落地口径:**账号库自有审计字段 = UTC**(本仓自有格式、无上游对照物);**业务编码 + DB 审计列 = 服务器本地时区**。 + 对照表写进 **`docs/contract.md` §时间口径**(新建,B5 继续补齐其余章节)。 +- 单测 `civil_from_days_matches_known_dates` 换成 `now_iso_is_utc_and_parsable` + (形状可解析 + 与 `Utc::now()` 差 ≤ 5 秒 ⇒ 有人改成 `Local::now()` 会红)。 +- 顺带新建 **`docs/decisions.md`**(决策日志):D1–D16 摘要 + **补记 D17**(白名单剪 9 条) + + **D18**(时间口径);v3 spec §12 全文仍是 D1–D16 的出处。 + **C9 的技术选型**:业务层 `TdcState` **deref 到** `platform::state::AppState`(⇒ `state.db` 等字段访问零改动) + `impl FromRef for AppState`(⇒ axum 里 `State` 可用,平台端点不必认识业务类型)。 🔴 `FromRef` 在 **`axum::extract::FromRef`**(`axum::core::extract::FromRef` 不存在)。 @@ -178,7 +194,7 @@ CP1 只查「表名前缀 / 端点前缀」,查不出模块引用 ⇒ 必须 ## 当前状态 - 分支 `feat/mvc-align-v3`;**回退点 = `06f5a79`**(v3 spec 落点)。 -- B1b 已完成 **C1–C11**;下一条 = **C12**(`civil_from_days`/`now_iso` 换 `chrono`,口径 **UTC**)。 +- B1b 已完成 **C1–C12**(C12 的口径决定记 **D18**);下一批 = **B2**(schema 追平:`base_user` / `base_role` / `base_role_relation`)。 - B1b 验收:`cargo test` 全绿 + `smoke.sh` 断言数 **== 75** + `check-boundary.sh` 全绿 (**7 条 B1b 账本条目已清空**)+ `check-entity.sh` 全绿 + 浏览器验收重跑(**未重跑** ⇒ B5 前补)。 - ⚠️ **B2 前必须先停掉占着 `data/tdc.pg` 的旧开发服**(pglite 每数据目录只允许一个进程)。 diff --git a/CLAUDE.md b/CLAUDE.md index a54b0d4..fac8e93 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -66,7 +66,7 @@ tdc-rs/ │ # + **三把尺子**:smoke.sh(HTTP 契约)/ check-boundary.sh(边界静态) │ # / check-entity.sh(实体静态)+ boundary-ledger.txt / upstream-json-ignore.tsv ├── tests/ # 集成测试(account_api / api_smoke / auth_flow / crud_engine / permission_gate / spa_fallback / bootstrap_fail / tds_biz) -├── docs/ # 补充文档(DDL-GUARD.md / TDC-TDS-CONTRACT.md / CONSOLE-ACCEPTANCE.md / known-limitations.md) +├── docs/ # 补充文档(DDL-GUARD.md / TDC-TDS-CONTRACT.md / CONSOLE-ACCEPTANCE.md / contract.md / known-limitations.md) │ # + superpowers/(v3 spec / 执行提示词 / 上游差异表) ├── tds-stub/server.js # TDS 契约桩(零依赖,仅供端到端调试) └── data/ # 运行期数据(tdc.pg/ + accounts.json,已 gitignore) @@ -281,6 +281,11 @@ bash scripts/check-entity.sh # ③ 实体静态(加实体的接触点完 19. **常量时间比较只有一份实现**(C11):实现住在 `src/platform/compare.rs`; 业务侧(`tdc::service::identity` / `tdc::service::account`)用 `pub use crate::platform::compare::constant_time_eq;` 复用 ⇒ **不许再抄一份**。 +20. **时间口径分两套,不是随手写的**(C12):仓里**不再手写日历算法**,一律 `chrono`; + - **服务器本地时区**(`chrono::Local`):业务编码(`tdc/util/code.rs`)与 DB 审计列(SQL `now()`) + ⇒ **必须**与上游 Java `LocalDateTime.now()` / MySQL `now()` 同口径(否则编码日期段差一天); + - **UTC**(`chrono::Utc`):账号库自己的审计字段(`tdc/service/account.rs::now_iso`)——本仓自有格式,无上游对照物。 + 🔴 完整对照表 + 「别把 Local 写成 UTC / 别把 UTC 写成 Local」见 **`docs/contract.md` §时间口径**。 ## 数据模型 diff --git a/docs/contract.md b/docs/contract.md new file mode 100644 index 0000000..aa9c57d --- /dev/null +++ b/docs/contract.md @@ -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 同口径),并同步更新本节。 diff --git a/docs/decisions.md b/docs/decisions.md new file mode 100644 index 0000000..405442f --- /dev/null +++ b/docs/decisions.md @@ -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`)之后、执行中追加的决策 ⇒ 只住本文件。 diff --git a/src/tdc/service/account.rs b/src/tdc/service/account.rs index 6db2443..d7e7e7c 100644 --- a/src/tdc/service/account.rs +++ b/src/tdc/service/account.rs @@ -8,8 +8,8 @@ use std::path::{Path, PathBuf}; use std::sync::Mutex; -use std::time::{SystemTime, UNIX_EPOCH}; +use chrono::Utc; use serde::{Deserialize, Serialize}; use crate::platform::cipher::md5_hex; @@ -278,36 +278,17 @@ impl AccountStore { } /// 当前 UTC 时间(`YYYY-MM-DD HH:MM:SS`)。 +/// +/// 🔴 **口径 = UTC**(v3 spec §2.3.1 C12):本仓**不再手写日历算法**, +/// 一律用 `chrono` ⇒ 换库/换时区不会漂。 +/// ⚠️ 别顺手改成 `chrono::Local`(`Local::now()` 是本机时区 ⇒ 值会变)。 +/// +/// 📌 全仓两套时间口径(详见 `docs/contract.md` §时间口径): +/// - **UTC**:账号库自己的审计字段(本函数)—— 本仓自有格式,无上游对照; +/// - **服务器本地时区**:业务编码(`tdc/util/code.rs`)与 DB 审计列(SQL `now()`) +/// —— **必须**与上游 Java `LocalDateTime.now()` / MySQL `now()` 同口径。 pub fn now_iso() -> String { - let secs = SystemTime::now() - .duration_since(UNIX_EPOCH) - .map(|d| d.as_secs() as i64) - .unwrap_or(0); - let days = secs.div_euclid(86_400); - let rem = secs.rem_euclid(86_400); - let (y, m, d) = civil_from_days(days); - format!( - "{y:04}-{m:02}-{d:02} {:02}:{:02}:{:02}", - rem / 3600, - (rem % 3600) / 60, - rem % 60 - ) -} - -/// 天元纪日 → 公历年月日(Hinnant 算法,闰年规则完整)。 -fn civil_from_days(z: i64) -> (i64, u32, u32) { - let z = z + 719_468; - // 🔴 `if/else` 表达式必须**加括号**再参与运算 —— 否则 `let era = if … {} / 146_097;` - // 的解析含义依赖 Rust 对「块表达式后接运算符」的贪婪规则,脆弱且易被误读。 - let era = (if z >= 0 { z } else { z - 146_096 }) / 146_097; - let doe = (z - era * 146_097) as u64; - let yoe = (doe - doe / 1460 + doe / 36_524 - doe / 146_096) / 365; - let y = yoe as i64 + era * 400; - let doy = doe - (365 * yoe + yoe / 4 - yoe / 100); - let mp = (5 * doy + 2) / 153; - let d = (doy - (153 * mp + 2) / 5 + 1) as u32; - let m = if mp < 10 { mp + 3 } else { mp - 9 } as u32; - (if m <= 2 { y + 1 } else { y }, m, d) + Utc::now().format("%Y-%m-%d %H:%M:%S").to_string() } #[cfg(test)] @@ -433,9 +414,21 @@ mod tests { assert!(!store.bootstrap_admin_uses_default_password()); } + /// 🔴 手写日历算法已删(C12)⇒ 改测「格式 + 口径」两件事: + /// ① 形状必须是 `YYYY-MM-DD HH:MM:SS`(能被 `NaiveDateTime` 解析); + /// ② **口径是 UTC**(与 `Utc::now()` 相差在几秒内)—— + /// 一旦有人图省事改成 `Local::now()`,本用例在非 UTC 时区下立刻红。 #[test] - fn civil_from_days_matches_known_dates() { - assert_eq!(civil_from_days(0), (1970, 1, 1)); - assert_eq!(civil_from_days(20_750), (2026, 10, 24)); + fn now_iso_is_utc_and_parsable() { + let s = now_iso(); + let parsed = chrono::NaiveDateTime::parse_from_str(&s, "%Y-%m-%d %H:%M:%S") + .unwrap_or_else(|e| panic!("now_iso 形状不对: {:?} ({})", s, e)); + let drift = (Utc::now().naive_utc() - parsed).num_seconds().abs(); + assert!( + drift <= 5, + "now_iso 应是 UTC 口径: {} (与 Utc::now() 差 {} 秒)", + s, + drift + ); } } diff --git a/src/tdc/service/crud.rs b/src/tdc/service/crud.rs index 027a760..4cb7fcc 100644 --- a/src/tdc/service/crud.rs +++ b/src/tdc/service/crud.rs @@ -430,6 +430,9 @@ pub async fn create( }; let op = operator(state, principal); let id = next_id(); + // 🔴 时间口径 = **服务器本地时区**(与上游 Java `LocalDateTime.now()` 同口径)。 + // 这里的 `now` 只用于**业务编码**(`f_interface_code` / `f_resource_code` …); + // DB 审计列走 SQL `now()`(同为本机时区)。对照见 `docs/contract.md` §时间口径。 let now = Local::now(); let mut cols: Vec = vec!["f_id".to_string()]; diff --git a/src/tdc/util/code.rs b/src/tdc/util/code.rs index e8f4c40..3113473 100644 --- a/src/tdc/util/code.rs +++ b/src/tdc/util/code.rs @@ -10,6 +10,11 @@ //! //! 上游真源:`boot/ssw-tdc/ssw-tdc-biz/.../util/TdcCodeUtil.java`、 //! `boot/ssw-common/ssw-common-biz/.../util/BizCodeUtil.java`(2026-10-24 逐字核对)。 +//! +//! 🔴 **时间口径 = 服务器本地时区**(`chrono::Local`,**不是 UTC**): +//! 上游用 `LocalDateTime.now()`(Java,服务器本地)⇒ 本仓必须同口径, +//! 否则同一时刻生成的编码会与上游差一个时区偏移(日期段在跨零点的 8 小时里直接变一天)。 +//! 全仓两套口径的对照见 `docs/contract.md` §时间口径。 use chrono::{DateTime, Local}; use rand::Rng;