Files
tdc-rs/docs/known-limitations.md
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

370 lines
22 KiB
Markdown
Raw Permalink 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.
# 已知限制(Known Limitations)
> 本文件记录**本仓与上游的已知差距**,以及**刻意保留的取舍**。
> 每条都带 `file:line` 引用,便于随时核对是否已过时。
> 决策背景见 [`decisions.md`](decisions.md),对外契约见 [`contract.md`](contract.md)。
---
## L1 · `tdc_identity` 有**两条读写路径**(显式承认 + 已收口)
**现象**:`tdc_identity` 这一张表同时被两条路径读写 ——
| 路径 | 位置 | 用途 |
|---|---|---|
| **领域路径** | `src/tdc/service/identity.rs:99`、`:105`、`:148`、`:217`、`:241`、`:333`、`:403`、`:460`、`:511` | 引导身份、登录校验、当前身份、可用空间、能力集、TDS 绑定 |
| **引擎路径** | `src/tdc/service/crud.rs:248`、`:287`、`:317`、`:341`、`:721`、`:739` | 通用 CRUD 引擎对**任意**实体表(含 `tdc_identity`)的列表/详情/写入 |
**为什么保留两条**:上游**没有「通用 CRUD 引擎」这个概念**(每个实体一个 Controller + JNPF 底座),
硬把领域 SQL 收进引擎会**失真**(引擎是**实体无关**的,列清单/隐藏字段/冻结列都要靠 spec 驱动)。
⇒ 决策:**显式承认 + 收口 + 记账**(v3 spec §2.3.1 C10 / 决策 D15)。
**已经收口的部分**:
- 领域 SQL **全部集中在 `src/tdc/service/identity.rs` 一个文件** ——
控制器层不再自己拼 `tdc_identity` 的 SQL
(原先 `src/tdc/controller/tds_biz.rs` 里的 `tdc_identity` 查询已移入
`src/tdc/service/identity.rs:511` 的 `local_tds_binding`)。
- 领域查询**只 SELECT 明确列**,永不 `SELECT *`
⇒ 密钥列(`f_secret_key`)不会被整行拖进内存。
**仍存在的风险**:两条路径的**隐藏字段 / 冻结列 / 权限语义**可能漂移 ——
例如引擎路径的出参走 `spec.hidden_fields` 删键(`src/tdc/mapper.rs`),
而领域路径靠**手写 SELECT 列表**控制可见列。
新增 `tdc_identity` 字段时,**两条路径都要看一眼**。
**复现/核对方式**:
```bash
# 领域路径的 SQL 全在这一个文件里
grep -n "SELECT\|INSERT INTO" src/tdc/service/identity.rs
# 引擎路径的 SELECT *(实体无关,按表结构展开)
grep -n "SELECT \*" src/tdc/service/crud.rs
```
---
## L2 · 上游 `base_user` 的 `f_maxkey_user_id` 列**没建**
**现象**:本仓的 `base_user`(`schema/migrate.sql` 末段,账号层三表)**没有**
`f_maxkey_user_id` 这一列,而上游 j7 的 `base_user`(最新态)有。
**上游怎么来的**:上游迁移 `boot/db/j7/V1.0.3__base_user_maxkey_user_id.sql` 追加的 ——
它是 **MaxKey SSO 的「认亲键」**:SSO 首次按手机号认亲后,把 MaxKey 的稳定标识
(`/sign/api/oauth/v20/me` 返回的 `userId`)写进本地那一行,以后一律用它。
**为什么不建**:本仓**不实现 MaxKey SSO**(`/api/ssw/tdc/Auth/SsoConfig` 恒 `enabled:false`,
见 `src/tdc/service/identity.rs:431`)⇒ 这一列没有写入方,也没有读取方 ⇒ 建了就是死列。
同源的取舍:上游 j7 的其余 120 张 `base_*`(`base_module` / `base_authorize` / `base_organize` …)
也**一律不建**(上游 `ssw.jnpf-permission.enabled=false` ⇒ 菜单授权行是死的;v3 spec §3.1)。
**补建的触发条件**:将来若要接 MaxKey SSO ⇒ ① 加这一列 + 唯一索引
(`uk_base_user_maxkey_user_id … WHERE f_maxkey_user_id IS NOT NULL AND <> ''`)
② 改 `schema/migrate.sql` ⇒ **必须清空 `data/` 重建**(见 `CLAUDE.md` 的坑位表)。
**核对方式**:
```bash
# 本仓建了哪些列
grep -n "f_maxkey_user_id" schema/migrate.sql || echo "(没建,符合预期)"
# 上游那一列的出处
grep -n "f_maxkey_user_id" /tmp/sswtdc-probe/boot/db/j7/V1.0.3__base_user_maxkey_user_id.sql
```
---
## L3 · `tdc_demo_car_insurance` **不参与任何聚合**(它没有父表)
**现象**:v3 spec §6.2 的 B3 清单列了 7 张「上游无独立控制器、走父实体聚合」的子表,
本仓已覆盖其中 **6 张**(字段说明 / 脱敏规则 / 接口参数 / 接口字段 / 交付参与方 / 交付待发队列),
**唯独 `tdc_demo_car_insurance` 挂不了**。
**为什么**:那张表**没有任何父外键** —— 列只有 `f_policy_no` / `f_vehicle_type` / `f_age` /
`f_claim_amount` / `f_drive_score` / `f_risk_level` / `f_region`(+ 系统列),
它在上游是 `SandboxSessionServiceImpl` 的**「读不到就喂演示数据」降级数据源**
(上游 `SandboxSessionServiceImpl:333` 的注释原文:`FALLBACK → 演示表(tdc_demo_car_insurance)`),
**不是任何实体的子表**。而 Sandbox / Nax 隐私计算属本仓**明确排除**的范围
(见 `CLAUDE.md`「明确不在本仓库范围」)⇒ 本仓既没有它的消费者,也没有它的父。
**为什么不硬挂**:挂到任意父实体上都是**编造关系** ⇒ 会让「聚合详情字段齐全」变成一句假话。
**核对方式**:
```bash
# 这张表没有父外键(列里没有 *_id 指向别的表)
grep -n "CREATE TABLE public.tdc_demo_car_insurance" -A 20 schema/migrate.sql
# 没有任何实体声明它当子表(注册表自检里有一条单测钉住这点)
grep -n "tdc_demo_car_insurance" src/tdc/entity/*.rs # 期望:无输出
```
**若将来要覆盖**:前提是本仓接上 Sandbox / Nax 侧的会话实体 ⇒
那时它才有一个可挂的父(本仓的 `tdc_sandbox_exec_run` 是**执行记录**,不是会话主体)⇒
需要**先建模会话实体**,再按 `ChildTable` 声明挂载。
---
## L4 · 实体级写权限**没有隔离**(**显式敞开 + 显式记账**)
**现象**:**除管理员端点外,任何登录用户(连接器身份会话 / 本地账号会话)可写全部 18 个实体**
—— 建、改、删都只要求「有登录态或内部令牌」。
**为什么**:D6 / D11 定的口径。旧的「实体 → 权限键」那一层
(`entity::PERMISSION_KEYS` 18 条 + `identity::capabilities()` + `crud::require_write_permission()`)
**从来就没在管**:
- 能力集**解析不出** ⇒ **fail-open**(本地单机模式没有能力集)⇒ 绝大多数情况下**直接放行**;
- 能解析出时,`*` / `all` 也会放行;
- ⇒ 这一层的实际效果 ≈「登录即可写」。
留着它有两个害处:① 让人**以为**有实体级隔离;② 制造「本地能用、部署后就锁死」的假象
(部署后能力集能解析出来 ⇒ 行为与本地**不一致**)。
**所以**:B4 把整条链路**删掉**,写操作统一走 `platform::auth::require_menu_permission`
(= 内部令牌 **或** 有登录态)⇒ **与上游 `TdcCrudController.requireMenuPermission()` 完全同构**
(上游 `permissionGuard == null` 时也只校验这两样)。
**这不是「放权」**:上游本仓同款;本仓**没有**比上游更宽。
**仍然在的隔离**(别误读):
| 面 | 还在吗 | 位置 |
|---|---|---|
| 实体**只读/只写分档**(`no_create` / `no_update` / `no_delete`) | ✅ **在** | `src/tdc/entity/mod.rs`(`TableSpec`) |
| **管理员端点**(`/api/permission/Users*` 6 个) | ✅ **在**(`f_is_administrator=1`,fail-closed) | `src/tdc/controller/account.rs`(`require_admin`) |
| **内部令牌**通道 | ✅ **在** | `src/platform/auth.rs` |
| 实体级**按角色**的读写隔离 | ❌ **没有**(上游也没有) | — |
**🔴 部署退出门槛(D11 的兑现处)**:账号发放**只给受信人**。
默认引导口令是公开已知的 `admin` ⇒ 上线前必须改(`TDC_STRICT_SECRETS=1` 会在
「管理员仍在用默认口令」时**拒绝启动**;改口令走 `/api/permission/Users/{id}/Actions/ResetPassword`)。
**受限于「任何登录用户可写全部实体」这条,本机部署只要有一个普通账号被拿到 ⇒ 等于全量可写。**
**核对方式**:
```bash
# 权限键表已不存在
grep -rn "PERMISSION_KEYS" src/ | grep -v "^src/.*://" # 期望:无输出
# 写路径只剩登录态闸门
grep -n "require_menu_permission\|require_write_permission" src/tdc/service/crud.rs
# 管理员位判据
grep -n "f_is_administrator" src/tdc/service/account.rs
```
---
## L5 · 上游的**动作端点**未实现(**分期的正常状态**)
**现象**:上游 18 个 `extends TdcCrudController` 的控制器里,除了 CRUD-6 基线
(列表 / `All` / 详情 / 新增 / 修改 / 删除)与 2 条只读聚合体(`Resource/{id}/Detail` ·
`Dataset/{id}/Detail`,本仓 B3 已实现)之外,还有 **109 条**动作端点 ——
本仓**一条都没实现**。
> 🔴 **数字口径**:`scripts/upstream-action-census.py`(只读上游克隆)——
> 18 个控制器**自声明** 122 条 method-level 映射,扣掉 11 条重复声明的 CRUD-6 基线
> 与 2 条已实现的聚合体 ⇒ **109 条未实现**(形态 A 26 + 形态 B 83)。
> **不是**「144」那个数 —— 144 是 `grep -rhoE` 对**全部 31 个控制器**(含非 CRUD 的
> `Auth` / `Billing` / `ServiceCatalog` / `Gateway` / `Portal` …)的去重计数,口径不同。
**上游那 109 条长什么样**(按域分组,括号里是端点数;★ 标的是**形态 A** ⇒ 见 L7):
| 域 | 上游端点 | 依赖 | 能否在本仓实现 |
|---|---|---|---|
| **产品上下架 / 审核** | `Product/{id}/OnShelf` · `OffShelf` · `Audit` · `AuditReject` · `Enable` · `Offline` · `PublishToTds` · `PublishNewVersion` · `PublishCallback` · `UploadCover` · `Product/{id}/Cover` · `Product/Catalog`★ · `Product/Internal/ForceOffline`(13) | 上下架状态机 + 出向 TDS 发布 | ⚠️ 可做,但要**先定状态机**(本仓无 `f_status` 动作语义) |
| **资源挂载 / 脱敏 / 加密** | `Resource/{id}/Mount` · `MountData` · `Disable` · `Enable` · `Classify` · `MarkCipher` · `Cipher/Query` · `Sync` · `Resource/{id}/Fields` · `MaskRules` · `Sample` · `Resource/Sample/{productId}` · `Resource/Enabled`★ · `Resource/Search`★(14) | 加密标记 + 分类 + 同步 | ⚠️ 部分可做(`Classify`/`Mount` 是纯 DB 写) |
| **合约协商 / 签署** | `Contract/Proposal`★ · `CreateByProposal`★ · `MultiParty/CreateByConnector` · `InitiateTask`★ · `Initiables`★ · `MyOrders`★ · `UsageMetrics`★ · `Contract/{id}/Change` · `ChangeCancel` · `Initiate` · `Negotiate` · `NegotiateRespond` · `Negotiation/Status` · `Negotiation/Summary` · `Negotiations` · `Parties` · `Resign` · `Terminate` · `Effective` · `Sync` · `LocalSign`★ · `ConnectorSign`★(22) | 合约状态机 + 多方交互 | ❌ 复杂(是本仓**最大的一块**) |
| **交付执行** | `DeliveryTask/{id}/DataSetDeliver` · `Destroy` · `Cancel` · `Finish` · `ReDeliver` · `RequestClose` · `Event` · `Exec/Start` · `Exec/Status` · `Result/Artifact` · `Result/Artifact/Proxy` · `Result/Download` · `Result/Pull` · `Result/Summary` · `Dev/Open` · `Dev/Submit` · `Dev/AuditResult` · `Dev/Artifact` · `DeliveryLog/ByTask/{taskId}` · `DeliveryTask/CountRunning`★ · `DestroyScan`★ · `EngineSelfCheck`★ · `Internal/VoidAlgorithm` · `EngineJobs/Dispatch`(24) | **Nax 隐私计算引擎** + scard 安全平面 | ❌ **本地不可行**(见 `CLAUDE.md` §明确不在范围) |
| **身份注册 / 心跳** | `Identity/{id}/Register` · `RegisterCallback` · `Heartbeat` · `Default` · `RotateSecret` · `Identity/Default`★ · `AutoProvision`★ · `Internal/Deregister`(8) | 私钥签名 + 平台侧注册流程 | ⚠️ 部分可做(`Default`/`RotateSecret` 是纯 DB 写) |
| **订单 / 凭据 / 策略 / 数据源 / 接口 / 通知 / 审计** | `Order/{id}/Approve` · `ConfirmPayment` · `Reject` · `Sign` · `Order/{id}/Delivery` · `Credential/Verify`★ · `Credential/{id}/Revoke` · `Policy/Check`★ · `Policy/GateCheck`★ · `Policy/{id}/Enable` · `Datasource/{id}/Enable` · `Disable` · `Sync` · `Test` · `Datasource/Enabled`★ · `Datasource/Types`★ · `DataInterface/{id}/Enable` · `Disable` · `Copy` · `Preview` · `DataInterface/Import`★ · `DataInterface/{id}/Export` · `Notification/{id}/Read` · `Notification/UnreadCount`★ · `AuditLog/Verify`★ · `AuditLog/ReportNow`★(26) | 纯业务状态机(部分) | ⚠️ **多数可做**(纯 DB 写 + 简单校验) |
| **策略模板 / 数据集** | `PolicyTemplate/Options`★ · `Dataset/{id}/Sample`(2) | 下拉项 / 样本预览 | ⚠️ 可做(`Options` 是纯 SELECT) |
| **只读聚合体**(**已实现**,不在 109 内) | `Resource/{id}/Detail` · `Dataset/{id}/Detail`(2) | — | ✅ **已实现**(B3) |
**为什么不一次做完**:109 条动作端点里,**约 1/4 依赖本仓明确排除的引擎**
(Nax / Sandbox / scard)⇒ 硬做会造出一堆「点了没反应」的死按钮;
剩下的 80 条是**状态机**,需要**逐域定状态与副作用**(尤其合约协商 22 条),
一次性糊出来必然与上游行为对不上 ⇒ 与 v3 spec §2「分批」的原则冲突。
**本仓现在做了什么**:把 CRUD-6 基线 + 2 条只读聚合体 + 10 个 TDS 出向端点
(共 **132** 条,`docs/contract.md` 是唯一真源)**做齐做对**,
动作端点**留到后续批次**。
**核对方式**:
```bash
# 本仓的端点全表(132 条)
bash scripts/check-contract.sh
# 上游那 109 条动作端点(脚本统计,只读上游快照;口径见本节开头的说明)
python3 scripts/upstream-action-census.py
# 本仓**没有**的路径 ⇒ 404 是预期行为(★ 形态 A 除外,见 L7)
grep -rn "OnShelf\|OffShelf\|Negotiate\|Exec/Start" src/ # 期望:无输出
```
---
## L6 · **分发形态缺陷**:`static/` 靠 `current_exe()` 向上找(D12 · 本批不修)
**现象**:本仓的静态前端目录靠**从可执行文件向上找**来定位:
```rust
// src/main.rs:43
fn resolve_project_dir() -> PathBuf { … 向上找含 static/index.html 的目录 … }
```
⇒ **二进制必须与 `static/` 保持「向上可及」的相对关系**。
**三个具体的坏处**:
| 场景 | 症状 |
|---|---|
| `cargo install` 装的二进制 | `~/.cargo/bin/tdc-connector` 向上找不到 `static/` ⇒ **前端 404**(后端 API 仍可用) |
| 打成单文件分发 | 同上(`static/` 根本不在旁边) |
| 二进制被**软链**调用 | `current_exe()` 在 Linux/macOS 上返回**真实路径**(多数平台已解引用)⇒ 软链目录里的 `static/` 看不见 |
**为什么本批不修**(D12):真正的修法有两种,都**不是本批能顺手做的** ——
① 把 `static/` **打进二进制**(`include_dir!` 或 `rust-embed`)⇒ 二进制体积 +2 MB,
且要处理「版本不匹配时前端与后端对不上」;② 把 `static/` 做成**可配置的外部资源目录**
(环境变量 / 配置文件)⇒ 改配置面 + 改启动装配。
**D12 的原话**:技能化本批不做,**阻塞在分发形态** ⇒ 技能化与分发形态**一起单独立项**。
**当前的规避办法**:
```bash
# 办法 1:就地跑(仓库根目录)
PORT=30000 ./target/debug/tdc-connector # ✅ static/ 就在旁边
# 办法 2:把 static/ 拷到二进制的上一级
cp -R static/ ../ # 下一个目录有 static/ 即可
```
**核对方式**:
```bash
grep -n "resolve_project_dir" src/main.rs
# 起服务后确认前端在
curl -s --noproxy '*' -o /dev/null -w '%{http_code}\n' http://127.0.0.1:30000/ # 期望 200
```
**将来立项时要定的**:
1. 静态资源是**打进二进制**还是**外部目录**?
2. 若外部 ⇒ 配置面放哪(环境变量 / 同目录 `tdc-connector.toml` / 首个 CLI 参数)?
3. 版本不匹配怎么防(前端 `index.html` 的 build id vs 后端 `protocolVersion`)?
4. 与技能化(`SKILL.md` + 三处软链 + 「仓根即技能」)**一起**设计 ——
否则技能装到 `~/.agents/skills/` 后 `static/` 又定位不到了。
---
## L7 · **单段尾**的动作端点**不会 404**(被通用详情路由吞掉)
**现象**:L5 那 109 条动作端点里,有 **26 条**(★)的路径形状是
`/{Entity}/{action}`(**恰好一个尾段**)—— 比如 `PolicyTemplate/Options`、
`Datasource/Types`、`Resource/Enabled`、`Product/Catalog`。
本仓的通用 CRUD 引擎给**每个**实体都注册了详情路由:
```rust
// src/tdc/controller/crud.rs:65-93
.route(&format!("{}/{{id}}", s.path),
get(/* detail */).put(/* update */).delete(/* delete */))
```
⇒ `GET /api/ssw/tdc/PolicyTemplate/Options` **先被这条路由匹配上**
(`{id}` = 字面量 `"Options"`)⇒ 请求**根本走不到 404** ⇒ 进详情处理器 ⇒
按 `f_id = 'Options'` 查库 ⇒ 查不到 ⇒ 返回业务失败。
**实测行为**(26 条逐条打,**零偏差**):
| 方法 | 条数 | 实测响应 |
|---|---|---|
| `GET` | 13 | **HTTP 200** + `{"code":400,"msg":"记录不存在或已删除","data":null}` |
| `POST` | 13 | **HTTP 405** + `{"code":405,"msg":"方法不被允许"}`(`{id}` 上没注册 POST) |
⇒ 🔴 **只判 HTTP 状态码会把这 26 条误判成「成功」或「方法错」** ——
这正是 `CLAUDE.md` 那条红线「**业务错误必须读 body 的 `code`**」的现实案例。
⇒ 剩下 **83 条**(≥2 尾段,如 `Contract/{id}/Negotiate`)才是**真 404**。
**上游前端的实际观感**(B5 浏览器验收实测):
| 页面 | 上游前端调的端点 | 本仓返回 | 观感 |
|---|---|---|---|
| `/tdc/products` | `GET PolicyTemplate/Options` | 200 + `code:400` | 下拉框**空**(不是报错页) |
| `/tdc/products` | `GET Resource/Enabled` | 200 + `code:400` | 同上 |
| `/tdc/datasources` | `GET Datasource/Types` | 200 + `code:400` | 同上 |
| `/tdc/delivery` | `GET DeliveryTask/EngineSelfCheck` | 200 + `code:400` | 引擎自检块**空** |
⇒ 页面**不崩**,只是**下拉项为空** ⇒ 从浏览器上看不出「端点没实现」,
只能从网络面板里看到那个 `code:400`。**这比 404 更难被发现** ⇒ 记账在此。
**为什么不修**(本批不修的理由):
- 「让这 26 条真 404」需要把通用详情路由从 `/{Entity}/{id}` 改成**先判字面量动作名**
⇒ 违反 v3 spec C3「引擎必须**实体无关**(零 `match api_name`)」——
除非引入一张「保留字 = 动作名」的**全局**表(不是实体专属),复杂度与收益不匹配。
- 「把这 26 条真实现」属 L5 的**后续批次**(动作端点分批实现)。
**核对方式**:
```bash
# 26 条形态 A 的清单
python3 scripts/upstream-action-census.py | sed -n '/形态 A 明细/,$p'
# 实测其中一条(注意:HTTP 是 200,业务码才是失败)
curl -s --noproxy '*' -H "X-Internal-Token: $SSW_INTERNAL_TOKEN" \
http://127.0.0.1:30000/api/ssw/tdc/PolicyTemplate/Options
# ⇒ {"code":400,"msg":"记录不存在或已删除","data":null}
```
---
## L8 · 上游 **15 个测试类**里只搬了 **3 个**(12 个超范围 + 3 条门户断言)
**现象**:上游 TDC + TDS + ssw-common 共 **15 个测试类**(6 个 JUnit + 9 个 SelfTest),
本仓只移植了 **3 个**(29 条对位用例)⇒ **12 个类**判定为超范围,
另有 **3 条**断言(`SswProdRuntimeGuardSelfTest` 的 ②⑧⑨)超范围。
**逐类台账**(机器可复算的版本在 `scripts/upstream-test-ledger.tsv`,人读版在
[`UPSTREAM-TEST-PARITY.md`](UPSTREAM-TEST-PARITY.md)):
| 上游类 | 形态 | 超范围的理由 |
|---|---|---|
| `ssw.tdc.support.ExecNfsSupportTest` | JUNIT | 执行侧 **NFS 通道** ⇒ 依赖 Nax 隐私计算引擎 |
| `ssw.tdc.engine.NaxPodSupportTest` | JUNIT | **Nax 引擎 + K8s 拓扑**(NodePort 派生 / 探针 / 投递物) |
| `ssw.tdc.client.NaxExecRenderTest` | JUNIT | Nax 执行 **Pod 模板渲染契约**(依赖 K8s) |
| `ssw.tdc.client.K8sSandboxClientRenderTest` | JUNIT | 沙箱执行 **Pod 模板渲染契约**(依赖 K8s) |
| `ssw.tdc.service.impl.P2pTransferTimeoutsSelfTest` | SELFTEST | 判据对象是 **P2P 传输客户端** ⇒ 本仓无 P2P 出向通道(**机制**已由 `ProviderInvokeTimeoutsSelfTest` 覆盖) |
| `ssw.tds.support.MaxkeyRegisterPrecheckSelfTest` | SELFTEST | **MaxKey SSO** 应用注册预检 ⇒ 本仓不实现 MaxKey SSO(见 L2) |
| `ssw.tds.service.MaxkeyAppRegistrarLogicSelfTest` | SELFTEST | MaxKey 应用登记**编排判据** ⇒ 同上 |
| `ssw.tds.client.MaxkeyMgtClientLiveSelfTest` | SELFTEST | **实机**打真 MaxKey(登录→建应用→授权→回读→退租)⇒ 本仓无 MaxKey 侧 |
| `ssw.tds.crypto.CertSignerStrictSelfTest` | SELFTEST | **CA 签发严格模式** ⇒ 软 PKI 由上游 scard 安全平面承担,本仓不做 |
| `ssw.tds.service.GuardAlertTypeSelfTest` | SELFTEST | **守门告警类型名长度不变式**(`GUARD_` + 原因 ≤ 列宽)⇒ 该告警表在 TDS 侧,本仓无对应表 |
| `ssw.common.util.IpWhitelistUtilTest` | JUNIT | **IP 白名单**(CIDR / 全放 / 归一 / 畸形 fail-closed)⇒ 本仓**没有**该功能(入向只认内部令牌 + 会话令牌) |
| `ssw.common.util.SswLLMClientTest` | JUNIT | **LLM 客户端**(代理 URL 解析 / OpenAI / Anthropic 后缀 / 业务错误 JSON)⇒ 本仓**没有** LLM 客户端 |
| `ssw.tds.controller.SswProdRuntimeGuardSelfTest` ②⑧⑨ | SELFTEST | 三条都属**门户验证码通道**(`ssw.portal.code-dev`)⇒ 本仓无该通道 |
**为什么不硬搬**:
- 前 4 条属**隐私计算执行面**(Nax 引擎 + K8s)⇒ 本仓明确不做(`CLAUDE.md`「明确不在本仓库范围」)⇒
**没有判据对象**可搬(不是"懒得搬",是"没有那个东西")。
- MaxKey / CA 签发 / IP 白名单 / LLM 客户端 ⇒ 本仓**没有对应功能** ⇒ 搬过来只能是**假绿**。
- P2P 那条**机制**(超时落进 socket 层 + cause 链分类)已由 `ProviderInvokeTimeoutsSelfTest` 的对位用例覆盖 ⇒
只缺**判据对象**。
**🔴 风险与兜底**:
- **风险**:上游改了判据而本仓没跟上 ⇒ **静默漂移**。
- **兜底**:`scripts/check-upstream-tests.sh`(第五把尺子)+ `scripts/upstream-test-census.py`
⇒ 上游**新增**一个测试类而台账没登记 ⇒ **红**;台账登记的对位用例被删/改名 ⇒ **红**。
⇒ 漂移**有闸门**,不靠"记得看"。
- **🔴 局限**:尺子只管「台账 ⇄ 代码」和「台账 ⇄ 上游测试类集合」,
**管不了**「上游某个类内部的断言变了」⇒ 那是**人工**要做的(见 `UPSTREAM-TEST-PARITY.md` 的逐条对照表)。
**核对方式**:
```bash
bash scripts/check-upstream-tests.sh # 台账自检 + 上游普查对账
python3 scripts/upstream-test-census.py # 重新普查上游测试类
```