# 上游测试用例移植台账(UPSTREAM-TEST-PARITY) > 🔴 **本文件回答一个问题**:上游 TDC / TDS / ssw-common 里**有哪些测试用例**,我们在 tdc-rs 上**搬了哪些、没搬哪些、为什么**。 > > **机器可复算的版本**在 `scripts/upstream-test-ledger.tsv`(台账 · 唯一真源); > **自检**在 `scripts/check-upstream-tests.sh`(第五把尺子)。 > 本文件是**人读版**(背景 + 逐类说明 + 复跑命令)。 --- ## 1. 为什么要做这件事 上游的测试用例**没有统一入口**: | 上游形态 | 谁跑 | 本仓对位 | |---|---|---| | `*Test.java`(带 `@Test`) | Maven **surefire**(`mvn test`) | `cargo test`(集成测试) | | `*SelfTest.java`(纯 `main`) | **surefire 不跑** ⇒ 上游自己靠 `tools/run-java-selftests.sh` 人工跑(退出码 0 = 过、**4 = UNVERIFIED ≠ 过**) | `cargo test`(`tests/upstream_*.rs`) | ⇒ 「上游有哪些用例、我们搬没搬」这件事**光靠肉眼看仓库是答不出来的** ⇒ 必须有一份 **可复算的清单 + 一把对账的尺子**,否则上游新增一个类而我们没看见 ⇒ **静默漂移**。 **普查结果**:上游 TDC + TDS + ssw-common 共 **15 个测试类**(6 个 JUnit + 9 个 SelfTest) ⇒ 本仓 **3 个已移植**(29 条对位用例)、**12 个判定为超范围**(逐条记理由 ⇒ `docs/known-limitations.md` L8)。 --- ## 2. 逐类台账 ### 2.1 已移植(3 类 · 29 条对位用例) | 上游类 | 仓库 | 形态 | 上游断言 | 本仓对位 | |---|---|---|---|---| | `ssw.common.guard.ProdGuardSelfTest` | ssw-common | SelfTest | 10 | `tests/upstream_guard_parity.rs`(**12** 条) | | `ssw.tds.controller.SswProdRuntimeGuardSelfTest` | TDS | SelfTest | 12 | `tests/upstream_guard_parity.rs`(**7** 条 / 10 条中可搬的部分) | | `ssw.tdc.client.ProviderInvokeTimeoutsSelfTest` | TDC | SelfTest | 11 | `tests/upstream_tds_timeout_parity.rs`(**10** 条) | > 本仓 12 + 7 + 10 = **29 条**对位用例,全部落在 `cargo test` 里(离线、秒级、无外部依赖)。 #### ① `ProdGuardSelfTest` ⇒ 生产档弱密钥守卫 **上游真源**:`boot/ssw-common/ssw-common-biz/src/test/java/ssw/common/guard/ProdGuardSelfTest.java` (判据本体 `.../src/main/java/ssw/common/guard/ProdGuard.java`) 上游 `ProdGuard.violations(map)` 的**六条判据**(缺一条即空检查 ⇒ 逐条照抄): | # | 判据 | 本仓落点 | 对位用例 | |---|---|---|---| | ① | 键**不在** map 里 ⇒ **跳过**(不判本应用没有的键) | `src/platform/guard.rs:137` | `prod_guard_absent_key_is_not_falsely_blocked` | | ② | 值为 null / 空白 ⇒ 违规 | `:147` | `prod_guard_blank_value_is_named` / `runtime_guard_prod_with_null_token_violates_without_panic` | | ③ | 值**精确等于**已知弱值 ⇒ 违规 | `:152` | `prod_guard_exact_weak_value_is_blocked` / `prod_guard_default_weak_values_are_still_blocked` | | ④ | 值**含**已知弱值 ⇒ 违规(**反绕过**) | `:158` | `prod_guard_default_value_with_suffix_is_blocked` | | ⑤ | 值命中**弱标记词** ⇒ 违规 | `:166` | `prod_guard_weak_marker_word_is_blocked` / `prod_guard_weak_marker_is_whole_word_only` | | ⑥ | 长度 < 12 ⇒ 违规 | `:174` | `prod_guard_min_len_is_enforced` / `prod_guard_too_short_value_is_blocked` | | — | **强值必放行**(防"守卫恒红") | — | `prod_guard_strong_values_are_all_allowed` | | — | 报错**点名**违规键 | `src/platform/guard.rs:188` | `prod_guard_violation_message_names_the_key` | | — | 协议共享值**不受管**(上游 chg_0020) | `src/platform/guard.rs:29` | `prod_guard_cipher_key_is_not_guarded` | **🔴 键名映射**(上游一个令牌两个方向通用 ⇒ 本仓拆成两个 ⇒ **两个都受管**): | 上游 `GUARDED` 键 | 本仓 | 说明 | |---|---|---| | `ssw.internal-token` | `SSW_INTERNAL_TOKEN` | 入向(`X-Internal-Token` 闸门) | | `tds-report.password` | `SSW_TDS_INTERNAL_TOKEN` | 出向(对端 internal 通道) | | `ssw.dataset.pepper` / `oauth.login.jwtSecretKey` / `tdc-delivery.password` / `spring.datasource.password` | — | 本仓**无对应配置项** ⇒ 判据①跳过 | | ~~`security.security-key`~~ | — | 上游 chg_0020 **已移出**(协议共享值,必须发给浏览器)⇒ 本仓 `CIPHER_KEY` **同样不受管** | **🔴 判据④ 存在的理由**:只比精确值时,把默认值后面加一个字符(`ssw-internal-token-e2e1`) 就能绕过守卫 ⇒ 那是"改了但没真改" ⇒ 上游专门有这条,本仓照抄。 #### ② `SswProdRuntimeGuardSelfTest` ⇒ 生产档运行时闸门 **上游真源**:`boot/ssw-tds/ssw-tds-controller/src/test/java/ssw/tds/controller/SswProdRuntimeGuardSelfTest.java` 上游 `SswProdRuntimeGuard.evaluate(prod, codeDev, testEnv, token)` 是**纯函数** ⇒ 本仓的对位物同样是纯函数 (`Config::check_secret_guard()` + `Config::guard_values()`,不读进程全局 env)。 | 上游条 | 断言 | 本仓对位 | |---|---|---| | ① | 非 prod ⇒ 一律不违规 | `runtime_guard_non_prod_never_violates` | | ② | prod + 门户验证码通道的 codeDev | 🚫 **超范围**(本仓无门户验证码通道) | | ③ | prod + 令牌为空 ⇒ 违规并点名 | `runtime_guard_prod_with_empty_token_violates` | | ④ | prod + 令牌为 null ⇒ 违规、不抛异常 | `runtime_guard_prod_with_null_token_violates_without_panic` | | ⑤ | prod + 仓库默认弱值 ⇒ 违规 | `runtime_guard_prod_with_default_token_violates` | | ⑥ | prod + 全强值 ⇒ 放行 | `runtime_guard_prod_with_strong_token_passes` | | ⑦ | **判别性**(只翻 prod 一位 ⇒ 结论必须翻转) | `runtime_guard_is_discriminable_on_the_prod_switch` | | ⑧ | 未声明测试环境 ⇒ 不放行 | 🚫 **超范围**(门户验证码通道) | | ⑨ | 已声明测试环境 ⇒ 只放行验证码、**不放行**内部令牌 | 🚫 **超范围**(门户验证码通道) | | ⑩ | **任何部署档位都解锁不了弱令牌** | `runtime_guard_no_deployment_flag_unlocks_a_weak_token` | > ②⑧⑨ 三条都属**门户验证码通道**(`ssw.portal.code-dev`)⇒ 本仓**没有该通道** > ⇒ 记 `OUT-OF-SCOPE-PART`(见 `docs/known-limitations.md` L8)。 > ⑩ 在本仓以**更强的形式**成立:连"单机模式"这种部署档位都解锁不了弱令牌。 #### ③ `ProviderInvokeTimeoutsSelfTest` ⇒ 出向超时的两跳判据 **上游真源**:`boot/ssw-tdc/ssw-tdc-biz/src/test/java/ssw/tdc/client/ProviderInvokeTimeoutsSelfTest.java` | 跳 | 上游判据 | 本仓对位 | 手法差异 | |---|---|---|---| | ① | 注入的超时值**真的落进 socket 工厂**(反射读 `SimpleClientHttpRequestFactory`)+ 判别性 | `hop1_injected_timeout_actually_reaches_the_socket_layer` / `hop1_changing_the_injected_value_changes_the_client` | 🔴 **行为级替代反射**:Rust 的 `reqwest::Client` **不暴露**超时 getter ⇒ 改用「短超时 ⇒ 超时错 / 长超时 ⇒ 成功」(同一个延迟 TCP 服务器)⇒ 结论**等价且更强**(真跑 socket 层,不是读字段) | | ② | **只有** cause 链里有 `SocketTimeoutException` 才改写文案;`ConnectException` / `UnknownHostException` / 无 cause ⇒ **不改写**;多层包装仍须命中;cause 链**有界**(`depth < 16`) | `hop2_read_timeout_is_rewritten_and_names_current_values` / `hop2_connect_timeout_is_rewritten` / `hop2_connection_refused_is_not_rewritten` / `hop2_dns_failure_is_not_rewritten` / `hop2_no_cause_is_not_rewritten` / `hop2_multilevel_wrapped_cause_is_still_detected` / `hop2_cause_chain_walk_is_bounded` / `hop2_end_to_end_connection_refused_stays_unreachable` | 照抄(`src/tdc/client/tds.rs:74` 的 `cause_chain_has_timeout` + `:112` 的 `timeout_text_or_null`) | > 🔴 判据②的**反例**(连接被拒 / DNS 失败 **不得**说成"超时")在本仓是**实机**验证的: > `hop2_end_to_end_connection_refused_stays_unreachable` 真打一个没人监听的端口 ⇒ 文案必须是「TDS 不可达」。 ### 2.2 判定为超范围(12 类) 逐条理由在 `scripts/upstream-test-ledger.tsv` 的 `reason` 列,汇总见 `docs/known-limitations.md` **L8**。 分类: | 类别 | 类 | 为什么超范围 | |---|---|---| | 隐私计算执行面 | `ExecNfsSupportTest` / `NaxPodSupportTest` / `NaxExecRenderTest` / `K8sSandboxClientRenderTest` | 依赖 **Nax 引擎 + K8s 拓扑**(NFS 通道 / Pod 模板渲染)⇒ 本仓明确不做(`CLAUDE.md`「明确不在本仓库范围」) | | P2P 传输 | `P2pTransferTimeoutsSelfTest` | 判据对象是 **P2P 出向客户端** ⇒ 本仓无 P2P 通道;**机制**本身已由 `ProviderInvokeTimeoutsSelfTest` 那条覆盖 | | MaxKey SSO | `MaxkeyRegisterPrecheckSelfTest` / `MaxkeyAppRegistrarLogicSelfTest` / `MaxkeyMgtClientLiveSelfTest` | 本仓**不实现 MaxKey SSO**(`/Auth/SsoConfig` 恒 `enabled:false`,见 L2);第三条还是**实机**打真 MaxKey | | CA 签发 | `CertSignerStrictSelfTest` | 软 PKI / CA 签发由上游 **scard 安全平面**承担 ⇒ 本仓不做 | | 守门告警表 | `GuardAlertTypeSelfTest` | 告警表在 **TDS 侧** ⇒ 本仓无对应表 | | IP 白名单 | `IpWhitelistUtilTest` | 本仓**没有**该功能(入向只认内部令牌 + 会话令牌) | | LLM 客户端 | `SswLLMClientTest` | 本仓**没有** LLM 客户端 | --- ## 3. 怎么复跑 ```bash # ① 对位用例(29 条,秒级、离线) cargo test --test upstream_guard_parity --test upstream_tds_timeout_parity # ② 第五把尺子:台账自检 + 与上游普查对账 bash scripts/check-upstream-tests.sh # ③ 只看台账不判红(排障) bash scripts/check-upstream-tests.sh --report # ④ 重新普查上游测试类(上游克隆不在场 ⇒ 自动跳过该侧校验,不判红) python3 scripts/upstream-test-census.py python3 scripts/upstream-test-census.py --check # ⑤ 上游克隆路径可覆盖 UPSTREAM_TDC_CLONE=/tmp/sswtdc-probe UPSTREAM_TDS_CLONE=/tmp/sswtds-probe \ bash scripts/check-upstream-tests.sh ``` 🔴 **上游克隆不在场不判红**(只跳过「上游有、台账无」与「上游文件存在」两项)—— 台账里登记的类**仍然**按台账校验(PORTED 行必须真有对位用例)。 --- ## 4. 台账格式(`scripts/upstream-test-ledger.tsv`,制表符分隔) | 列 | 含义 | |---|---| | 1 `upstream_class` | 上游全限定类名 | | 2 `upstream_repo` | `TDC` / `TDS` / `COMMON`(ssw-common 两侧都有 ⇒ 记 `COMMON`) | | 3 `upstream_file` | 相对**克隆根目录**的路径 | | 4 `kind` | `JUNIT`(surefire 跑) / `SELFTEST`(纯 main,**surefire 不跑**) | | 5 `assertions` | 上游断言条数(`-` = 未逐条计数) | | 6 `tdc_counterpart` | 本仓对位:`文件::fn1+fn2+…`(`-` = 无对位) | | 7 `status` | `PORTED` / `OUT-OF-SCOPE` | | 8 `reason` | 搬法说明 / 不搬的理由(**必填**) | **尺子管的四件事**: 1. 每行 8 列、`status` 合法、`reason` 非空; 2. `PORTED` 行的对位文件**存在**、登记的用例函数**真在**那个文件里; 3. `OUT-OF-SCOPE` 行的对位必须为空(`-`); 4. **文件级集合相等**:台账登记的用例集合 == 对位文件里实际存在的移植用例集合(防少登记 / 多登记)。 🔴 第 4 条靠**前缀约定**识别"移植用例":`upstream_` / `hop1_` / `hop2_` / `runtime_guard_` / `prod_guard_` ⇒ 辅助函数(`spawn_delayed_server` 之类)不会被误计。 --- ## 5. 相关文档 | 文档 | 讲什么 | |---|---| | `docs/decisions.md` **D22 / D23** | 守卫语义升级为上游六条判据;出向超时外置到 env + cause 链分类 | | `docs/known-limitations.md` **L8** | 12 个超范围的上游测试类 + 3 条门户验证码相关的未搬断言 | | `docs/TDC-TDS-CONTRACT.md` | 出向通道的降级三档(超时归入「不可达」那一档的**细分**) |