Files
tdc-rs/docs/decisions.md
T
adminandClaude Code 1a0fdbf879 feat(upstream-parity): 移植上游测试用例 —— 29 条对位用例 + 第五把尺子
**影响**
- 生产档弱密钥守卫从「只比默认值」升级为上游 `ProdGuard` 的**六条判据**(纯函数),
  弱令牌用「默认值加后缀」绕过、弱标记词、长度下限三类都拦得住;`CIPHER_KEY`(协议共享值)**不受管**。
- 出向 TDS 超时**外置到 env**(`SSW_TDS_CONNECT_TIMEOUT_MS` / `SSW_TDS_READ_TIMEOUT_MS`),
  且**只有 cause 链里真有超时**才改写文案 ⇒ 连接被拒 / DNS 失败不再被误报成「超时」(排查方向不被带偏)。
- 上游 15 个测试类全部**登记在册**:3 个已移植(29 条对位用例)、12 个判定超范围(逐条记理由)。
- 新增第五把尺子 `scripts/check-upstream-tests.sh`:台账 ⇄ 代码 ⇄ 上游测试类集合三向对账,
  上游新增测试类而台账没登记 ⇒ **红**(不靠"记得看"防漂移)。
- 回归网:`cargo test` 246 → **278**(+32),其余四把尺子与引用自检**全绿**。

**改动**
- `src/platform/guard.rs`(新):上游 `ProdGuard.violations` 的纯函数移植(弱值清单 / 弱标记词整体词匹配 / `MIN_LEN=12` / 逐条点名)。
- `src/platform/config.rs`:`check_secret_guard` 改走守卫判据;新增 `guard_values`(只放本部署真有的键)
  与出向超时两项配置(非法值回落默认,不让连接器起不来)。
- `src/tdc/client/tds.rs`:新增 `cause_chain_has_timeout` / `timeout_text_or_null`(cause 链遍历**有界** `depth<16`),
  `TdsClient::with_timeouts` 接受超时。
- `tests/upstream_guard_parity.rs`(新 · 19 条)+ `tests/upstream_tds_timeout_parity.rs`(新 · 10 条)。
- `scripts/upstream-test-ledger.tsv`(台账真源)+ `scripts/upstream-test-census.py`(上游测试类普查/对账)
  + `scripts/check-upstream-tests.sh`(第五把尺子)。
- 文档:`docs/UPSTREAM-TEST-PARITY.md`(新)+ `docs/known-limitations.md` L8 + `docs/decisions.md` D22/D23
  + `CLAUDE.md` 同步(尺子表 / 目录树 / 命令速查 / 实现细节 22–23 / 坑位表)。

**设计**
- 上游 hop 1 的「反射读 socket 工厂」**抄不了**(`reqwest::Client` 不暴露超时 getter)⇒ 改用**行为级**判别
  (同一延迟 TCP 服务器:短超时⇒超时错、长超时⇒成功)⇒ 结论等价且更强(真跑 socket 层)。
- 上游 `*SelfTest.java` **surefire 不跑**(无统一入口)⇒ 判据落成 `cargo test` 常规用例(纯函数 ⇒ 可离线断言)。
- 超范围判定原则:**本仓没有对应功能 ⇒ 不搬**(硬搬只会是假绿);「机制」已覆盖的(P2P 那条)按机制记账。

Co-Authored-By: Claude Code <[email protected]>
2026-10-27 09:04:08 +08:00

64 lines
14 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.
# 决策记录(decisions)
> 🔴 本文件是**为什么这么定**的唯一去处:每条 = 编号 / 决策 / 取值 / 代码落点 / 来源。
> 规格原文见 `docs/superpowers/specs/2026-10-26-tdc-rs-mvc-align-v3-design.md` §12(D1–D16 的全文在那边)。
> 与 `docs/contract.md`(对外形状)/ `docs/known-limitations.md`(已知偏差)配套读。
>
> **「代码落点」列给的是本仓里实现该决策的 `文件:行号`** ⇒ 抽查任意一条都能直接跳过去核对。
---
## 索引(按批次)
| 批次 | 决策 |
|---|---|
| B0(拍板) | D1–D12 |
| B1b(搬家) | D13 / D14 / D17 / D18 |
| B3(子表) | D19 |
| B4(账号层) | D15 / D16 / D20 / D21 |
| B5(文档层) | D10 / D12 的兑现 |
| 上游对齐(测试移植) | D22 / D23 |
---
## 决策表
| # | 决策 | 取值 | 代码落点 | 来源 |
|---|---|---|---|---|
| D1 | 前端 | 继续用上游 Vue SPA(不做面 B) | `static/`(构建产物)· `src/platform/fallback.rs:120`(`spa_fallback` 托管) | 用户拍板 |
| D2 | 业务边界 | 与上游一致,**分批**,本批只做底座 | `src/tdc/`(18 实体 + 10 TDS 端点) | 用户拍板 |
| D3 | 业务包 MVC | 对位上游包结构 + **保留通用引擎** | `src/tdc/{entity,mapper,service,controller,client}/` · `src/platform/` | 用户拍板 |
| D4 | 库 | 单库 | `src/platform/db.rs`(pglite 单 backend)+ `src/platform/state.rs`(`process_db_lock`) | 用户拍板 |
| D5 | 账号层 | 一步切 `base_user`(官方双 md5) | `src/tdc/service/account.rs:124`(`official_password_hash`)· `schema/migrate.sql`(`base_user`) | 用户拍板 |
| D6 | 权限 | **按上游**(角色码 + 管理员位,删 18 键) | `src/tdc/service/account.rs:289`(`is_administrator`)· `src/tdc/service/account.rs:320`(`role_codes`) | 用户拍板 |
| D7 | 面 B / `perm-smoke-jnpf.sh` | **不做** | (无实现) | 由 D1 推导 |
| D8 | 存量 `accounts.json` 账号 | **不导入**(D5 推导;文件保留不删) | `src/main.rs:148`(`data/accounts.json` 保留但**不读**) | 由 D5 推导 |
| D9 | `tdsReadOnly` | 判据在、种子不种(照抄上游不一致) | `src/tdc/service/account.rs:53`(`ROLE_CODES` 判据含它)· `:56`(`SEED_ROLES` 种子**不含**它) | spec §4.1 |
| D10 | 借技能的工程化外壳,不借契约层 | 分层 / 尺子 / 文档 / 手册可借;契约层一律不借(面 A·面 B · 600/602 信封 · `base_module` 菜单 · 复合主键) | 本仓形状 = `src/platform/envelope.rs:27`(**HTTP 200 + `{code,msg,data}`**)⇒ 无 600/602 鉴权信封 | 2026-10-26 对标技能 `ssw-jnpf-lite-rust` |
| D11 | 权限宽严**维持追平上游 = 显式敞开 + 显式记账** | **不**收紧为 fail-closed(会造出与上游不一致的新偏差) | `src/platform/auth.rs:243`(`require_menu_permission` = 内部令牌 **或** 有登录态) | spec §5.2 / §5.4 |
| D12 | 技能化本批不做 | 阻塞在分发形态(`static/` 定位依赖 `current_exe()` 向上找)⇒ 先做文档层(B5) | `src/main.rs:43`(`resolve_project_dir` 从可执行文件向上找 `static/index.html`) | spec §0.4 / §11.3 |
| D13 | B1 拆成 B1a(尺子先行)+ B1b(搬家 + 边界收敛) | `cargo test` 不覆盖 HTTP 层 ⇒ 无尺子不搬家;B1a 先锁基线断言数 N,B1b 后必须 == N | `scripts/smoke.sh`(N=75 ⇒ B4 后 N=80) | spec §2.4 / §8 |
| D14 | `codec.rs` 归**业务层** `tdc/util/code.rs` | 它是业务编码生成器(`PRO`/`RES`/`API`/`DS`),不是序列化 codec;`ids.rs` 留平台层 | `src/tdc/util/code.rs:37`(`day_prefix`)· `:58`(`format_code`)· `src/platform/ids.rs:119`(`next_id`) | spec §2.1 |
| D15 | `tdc_identity` **双读写路径显式承认 + 收口 + 记账** | 不硬收进引擎(上游无「通用引擎」概念)⇒ 领域 SQL 收进 `src/tdc/service/identity.rs`、只 SELECT 明确列、记进 `docs/known-limitations.md` L1 | `src/tdc/service/identity.rs`(领域路径)· `src/tdc/service/crud.rs:207`(引擎路径) | spec §2.3.1 C10 / S8 |
| D16 | numeric 列输出 JSON **数字**(不是 JSON 字符串) | 上游 `ProductEntity.java:88` 的 `BigDecimal` 只带 `@TableField`(无 `@JsonSerialize`)⇒ Jackson 默认 ⇒ 数字 | `src/tdc/mapper.rs`(`row_to_json_spec` 不做字符串化)· `src/tdc/entity/product.rs` | 2026-10-26 B1a 复核上游取证链 |
| **D17** | **鉴权白名单按**实际**清单剪 9 条**(不是 spec 预估的 7 条) | 上游 `gateway.white-url` 里 P2P 是 **5** 条(不是 4)⇒ 实际死路径 9 条 ⇒ 本仓照抄**实际**清单,账本逐条记明 | `src/tdc/support/public_paths.rs:51`(`all_public_paths`) | 2026-10-26 B1b C5 |
| **D18** | **时间口径 = 两套,各自绑定上游对照物** | C12 的「口径统一为 **UTC**」若**全仓**执行 ⇒ 业务编码与 DB 审计列从服务器本地时区变 UTC ⇒ ①违反 B1b「行为零变化」②**产生新的对上游偏差**(上游 `TdcCodeUtil` 用 `LocalDateTime.now()`、审计列用 MySQL `now()`,都是服务器本地;跨零点的 8 小时里编码日期段直接差一天)⇒ **不做全仓 UTC**。落地口径:**① 仓里不再手写日历算法,一律 `chrono`;② 账号库自有审计字段 = UTC**(本仓自有格式、无上游对照物;替换实现时**保持**原值 ⇒ 零行为变化);**③ 业务编码与 DB 审计列 = 服务器本地时区**(有上游对照物 ⇒ 必须同口径)。对照表写在 `docs/contract.md` §时间口径 | ① `src/tdc/util/code.rs:38`(`day_prefix_at(prefix, Local::now())` = **服务器本地**)· ② `src/tdc/service/account.rs:257` 起的账号审计列 = UTC | 2026-10-26 B1b C12(复核上游 `TdcCodeUtil.java`) |
| **D19** | **子表挂载面逐父子不同**(`Aggregate` / `Detail` / `List` 三面) | 上游口径**不是**「子表都挂详情」:`Resource`/`Dataset` 的子表只在 `/Detail` 聚合体(普通详情**不带**);`DataInterface` 的子表只在普通详情(上游覆写了基类详情,且**没有** `/Detail` 路由);`DeliveryTask` 的参与方挂详情**与**列表(`decorate` 批量挂)。⇒ 子表声明从 `(key, table)` 二元组升级为 `ChildTable` 结构(外键列 / 父行取值列 / 排序列 / 存活谓词 / 挂载面),引擎仍**零 `match api_name`**(只认列名)。**`outbox` 是本仓扩展**(上游不挂,但 `local_task_id` = 任务 `f_id` ⇒ 货真价实的子表);**`tdc_demo_car_insurance` 挂不了**(无父外键 ⇒ 记为已知限制 L3) | `src/tdc/entity/mod.rs:60`(`ChildMount`)· `:74`(`ChildTable`)· `:164`(`children_on`)· `src/tdc/entity/resource.rs:34`(Resource 挂 Aggregate 面)· `src/tdc/entity/delivery_task.rs` | 2026-10-26 B3(复核上游 `ResourceServiceImpl#withChildren` / `DataInterfaceController#detail` / `DeliveryTaskController#decorate`) |
| **D20** | **账号层切 `base_user` + 官方双 md5 公式 + 删掉 18 键假权限层** | ① **载体**:`data/accounts.json` → `base_user` 表(JSON 文件**保留不删**,但后端**不再读取** ⇒ 存量账号**不导入**,D8);② **口令**:入库用官方公式 `f_password = md5(lower(md5(明文)) + lower(f_secretkey))`,`f_secretkey` **每账号随机**(UUID v4 大写),**改密不换 secretkey**(与官方一致);③ **引导**:`base_user` 无存活行时种一个管理员(`f_is_administrator=1`),**幂等**;`base_role` 逐字照抄上游 `V1.0.1__connector_seed.sql` 的三行(`tdcProvider`/`tdcConsumer`/`user`),管理员绑 `user` 角色;④ **管理员判据** = `f_is_administrator=1`,**查询异常 ⇒ false(fail-closed)**;⑤ **删掉 18 条实体→权限键**(`entity::PERMISSION_KEYS` + `identity::capabilities()` + `crud::require_write_permission()`)—— 那层「解析不出 ⇒ fail-open」**从来就没在管**,留着只是**看起来在管** ⇒ 拆掉并**显式记账**(L4);⑥ **不收紧为 fail-closed**(D11)⇒ 写操作改用上游同款 `require_menu_permission()`(内部令牌 **或** 有登录态) | ① `src/tdc/service/account.rs:621`(`bootstrap_account_layer`)· `src/main.rs:148`(JSON 不再读);② `src/tdc/service/account.rs:124`(`official_password_hash`)· `:137`(`new_j7_id`)· `:576`(`reset_password` **不换** secretkey);③ `src/tdc/service/account.rs:56`(`SEED_ROLES`)· `src/tdc/constant.rs:21`(默认口令);④ `src/tdc/service/account.rs:289`(`is_administrator` fail-closed);⑤ `src/tdc/service/crud.rs:515/662/763`(三个写路径)· `src/platform/auth.rs:243`;⑥ `src/tdc/controller/account.rs:149`(`require_admin`) | 2026-10-26 B4(复核上游 `PasswordTokenGranter.java:186` / `AuthController#me:207` / `TdcCrudController.java:133`) |
| **D21** | **角色码暴露在 `/Auth/Me` 的 `roles` 键 + 保留 `require_menu_permission` 登录态闸门** | ① 上游 `AuthController#me:207` 有 `data.put("roles", roles)` ⇒ 本仓 `me_payload` 加 `roles` 键(**出参新增一个键**,形状其余不变);角色码判据**逐字照抄**上游 SQL(`IN ('tdcProvider','tdcConsumer','tdsReadOnly')`)⇒ **只对账号会话算**(上游只有门户登录这一路算角色),身份会话返回**空数组**;② 写操作的门禁换成 `platform::auth::require_menu_permission`(**已在 list/all/detail/aggregate_detail 用着**)⇒ 四个读写面**同一个闸门**,与上游 `requireMenuPermission()` **同构**;③ D9 的悬空码照抄 ⇒ 引导管理员绑 `user` 角色 ⇒ 它的 `roles` **是空数组**(上游同口径,**不是 bug**) | ① `src/tdc/service/identity.rs:360`(`me_payload(…, roles)` 出 `roles` 键)· `:311`(`me`)· `src/tdc/service/account.rs:320`(`role_codes` **逐字**上游 SQL);② `src/tdc/service/crud.rs:207/276/461/822`(四个读面)· `:515/662/763`(三个写面)—— **七个面同一个闸门**;③ `src/tdc/service/account.rs:56`(`SEED_ROLES`) | 2026-10-26 B4 |
| **D22** | **生产档弱密钥守卫升级为上游 `ProdGuard` 的六条判据**(本仓原来只有「默认口令即不安全」这一条) | ① **判据纯函数化**:上游把判据抽成 `ProdGuard.violations(map)`(纯函数,不读 Spring)⇒ 本仓落成 `platform::guard::guard_violations(map)`,不读进程全局 env ⇒ 可离线逐组断言;② **六条判据缺一不可**:①键不在 map⇒跳过 ②值为 null/空白⇒违规 ③值精确等于弱值⇒违规 ④值**含**弱值⇒违规(**反绕过**:默认值加个后缀也拦住)⑤值命中弱标记词⇒违规 ⑥长度<12⇒违规;③ 与 ④ **分开报错**(照抄上游);③ **双令牌都受管**(上游一个 `ssw.internal-token` 双向通用 ⇒ 本仓拆成入向 `SSW_INTERNAL_TOKEN` / 出向 `SSW_TDS_INTERNAL_TOKEN` ⇒ 两个都受管;出向令牌**仅在配了 `SSW_TDS_BASE_URL` 时**才进守卫 ⇒ 本地单机模式不会被误停);④ **`CIPHER_KEY` 不受管**(上游 chg_0020 已把 `security.security-key` 移出受管清单 —— 那是**协议共享值**,必须发给浏览器 ⇒ 本仓的 `CIPHER_KEY` 同款裁定,否则"保持默认同值"这种正常部署会被判红);⑤ **弱标记词按整体词匹配**(上游正则 `(?i)(^|[\-_.])(…)([\-_.]|$)` ⇒ 手写等价实现,不引 regex 依赖) | `src/platform/guard.rs:134`(`guard_violations`)· `:101`(`has_weak_marker`)· `:188`(`violation_message`)· `:46`(`WEAK_VALUES`)· `:77`(`GUARDED`)· `src/platform/config.rs:247`(`check_secret_guard`)· `:261`(`guard_values`) | 2026-10-27(复核上游 `ProdGuard.java:119` / `ProdGuardSelfTest.java`) |
| **D23** | **出向 TDS 超时外置到 env + 照抄上游的 cause 链超时分类** | ① **超时值外置**:`SSW_TDS_CONNECT_TIMEOUT_MS`(默认 3000)/ `SSW_TDS_READ_TIMEOUT_MS`(默认 5000)⇒ 上游把超时当**可配项**(不同对端网络条件不同),本仓原来**写死在代码里**;② **cause 链分类**(照抄上游 `ProviderInvokeTimeoutsSelfTest` 第 2 跳):**只有** cause 链里存在超时(`reqwest::Error::is_timeout()` 或 `io::ErrorKind::TimedOut`)才把文案改写成「调用 TDS 超时(当前 connect=…ms / read=…ms,可用 … 调大)」;**连接被拒 / DNS 失败 / 无 cause ⇒ 不改写**(仍是「TDS 不可达」)——🔴 **把连接被拒说成"超时"会把排查引向错误方向**(改超时没用,要改网络/证书);③ **cause 链有界**(`depth < 16`,照抄上游)⇒ 多层包装仍能命中,但环状链不死循环;④ **不引 regex**:弱值/弱标记词判据手写(见 D22) | `src/tdc/client/tds.rs:74`(`cause_chain_has_timeout`)· `:112`(`timeout_text_or_null`)· `:29`(`MAX_CAUSE_DEPTH=16`)· `:171`(`with_timeouts`)· `src/platform/config.rs:130`(`timeout_ms_from`)· `:189`(读 env) | 2026-10-27(复核上游 `ProviderInvokeTimeoutsSelfTest.java`) |
---
## 补记说明
- **D1–D16** 的完整措辞(含来源链)在 v3 spec §12;本表只留一行摘要,方便日常查。
- **D17–D21** 是 v3 spec 落点(`06f5a79`)之后、执行中追加的决策 ⇒ 只住本文件。
- **D22–D23** 是「上游测试用例移植」批次追加的决策(守卫语义升级 / 出向超时外置)⇒ 只住本文件;
对应的上游真源与逐条对照见 [`UPSTREAM-TEST-PARITY.md`](UPSTREAM-TEST-PARITY.md)。
- **D18 是本轮唯一一处「与执行提示词冲突」**:提示词要求「口径统一为 UTC」,v3 spec §2.3.1 C12 也写了 UTC,
但**全仓 UTC 会引入对上游的新偏差**(上游用服务器本地时区)⇒ 按「spec 与提示词冲突时 spec 优先」的规则,
**v3 spec 赢**,但 spec 的「全仓 UTC」与它自己的「B1b 行为零变化」原则冲突 ⇒ 采纳**两套口径**并显式记账。
**这是本轮需要拍板人知晓的偏离点**(最终报告里也会单列)。