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

14 KiB
Raw Blame History

决策记录(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 依赖)
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。
  • D18 是本轮唯一一处「与执行提示词冲突」:提示词要求「口径统一为 UTC」,v3 spec §2.3.1 C12 也写了 UTC, 但全仓 UTC 会引入对上游的新偏差(上游用服务器本地时区)⇒ 按「spec 与提示词冲突时 spec 优先」的规则, v3 spec 赢,但 spec 的「全仓 UTC」与它自己的「B1b 行为零变化」原则冲突 ⇒ 采纳两套口径并显式记账。 这是本轮需要拍板人知晓的偏离点(最终报告里也会单列)。