# TDC ↔ TDS 跨方契约参考 本仓库 `/api/ssw/tdc/tds/*` 代理网关所还原的原始契约,真源在 `~/Desktop/workspace/ssw-mvp/boot/ssw-tdc/ssw-tdc-controller/src/main/java/ssw/tdc/client/`。 ## 原 Java 侧结构 | 文件 | 作用 | |---|---| | `TdcTdsClient.java` | 抽象接口 | | `HttpTdcTdsClient.java` | HTTP 实现(配 `ssw.tds.base-url` 时生效) | | `NoopTdcTdsClient.java` | 降级实现(未配 base-url) | | `TdcTdsClientConfig.java` | 装配(base-url / internal-token 注入) | **核心原则**:所有调用**失败即降级**(catch 后返回空/默认值),绝不拖垮本地 TDC 业务。 ## 契约清单(原注释逐条抄录) ``` GET /api/ssw/tds/Bridge/Contract/{id} -> 合约概览 Map GET /api/ssw/tds/Bridge/Connector/{id} -> 连接器概览 Map GET /api/ssw/tds/Bridge/DataProduct/{id} -> 数据产品概览 Map POST /api/ssw/tds/Bridge/AuditChain body: {bizIds:[..]} -> 审计哈希链 Map POST /api/ssw/tds/Bridge/ChainEvidence body: {bizIds:[..]} -> 链上存证 Map POST /api/ssw/tds/Bridge/AuditRecord body: {bizIds:[..]} -> 审计记录 Map POST /api/ssw/tds/Bridge/AuditTrail body: 留痕 JSON -> void ``` 请求头:非空时带 `X-Internal-Token`(对应 JNPF `AuthFilter` 的 exclude-url 内部免鉴权端点)。 ## 真实 TDS 侧的额外约束(实测) 1. **`Bridge/**` 需 `App-Code: tdc`** `TdsBridgeInternalController` 的白名单只放行 `App-Code=tdc`;缺该头直接返回 `App-Code invalid`。 `X-Internal-Token` 仅在 `tds.internal-secret` 非空时才校验(当前配置为空 = 免 token)。 → 本仓库代理对 `Bridge/**` **统一注入** `App-Code: tdc`,并丢弃客户端自带的该头以防伪造/重复。 2. **业务错误走 HTTP 200 + body `code`** 例如 `AuthFilter` 未放行时返回 `{"code":600,"msg":"登录过期"}`,HTTP 状态仍是 200。 → 判定成败必须同时看 `body.code == 200`,只看 HTTP 状态会把失败误判为成功。 3. **无 `POST /api/ssw/tds/Connector/Register`** 真实 `ConnectorController` 只有 `/{id}/Audit|Heartbeat|Offline|Cancel|PullSession|BusinessDetail`; 连接器由运营方在 CRUD 侧建档。 → 本仓库 `register` 端点在真 TDS 上返回 `registerStatus: UNSUPPORTED_BY_TDS`,**不伪造成功**; Noop 模式(未配 base-url)才本地置 `APPROVED`。 4. **`NodeReport`** `POST /api/ssw/tds/NodeReport` 可直连(200);`GET /NodeReport/Categories` 需登录态。 → 本仓库 heartbeat 在配 base-url 时一并上报 `NodeReport`,失败仅告警不影响本地。 ## 代理行为约定(`src/main.rs` → `tds_proxy`) | 行为 | 实现 | |---|---| | 路径映射 | `/api/ssw/tdc/tds/{rest}` → `{base}/api/ssw/tds/{rest}`(query 透传) | | 逐跳头剥离 | `host` / `content-length` / `connection` / `transfer-encoding` / `upgrade` / `keep-alive` / `te` / `trailer` | | 内部令牌 | `SSW_TDS_TOKEN` 非空时注入 `X-Internal-Token` | | App-Code | `rest` 以 `Bridge` 开头时注入 `App-Code: tdc`(覆盖客户端自带值) | | 上游不可达 | 返回 502 `{"error":"tds unreachable"}` | | 未配 base-url | 返回 501 `NOOP mode`(对应原 `NoopTdcTdsClient`) | | 响应回传 | 透传上游状态码与 `Content-Type`,body 原样字节回传 | ## 实测验证记录(真实 TDS,2026-10-23) | 调用 | 结果 | |---|---| | `Bridge/Contract/855041382379688261` | `contractCode: CT-CRT-yxkcm`,状态 `01` | | `Bridge/Connector/854250096668180741` | 「TEE 连接器_05496131」,`orgName: 吉利汽车`,`ONLINE` | | `Bridge/DataProduct/855039616187633989` | 「测评目录产品-iws2k」,`DRAFT` | 经本仓库连接器代理调用返回**完全相同**的数据,与 `tds` 库一致。