Files
tdc-rs/docs/TDC-TDS-CONTRACT.md
admin 4b32b40bd6 feat(tds): 同步 ssw-tdc 最新 internal 契约并完成真 TDS 联调验证
- 协议版本收敛为单一常量 3.2,移除联调期自创的 env 覆盖
- 按真源同步 5 项契约:Dispute 下线、Billing/List 增 side、internalCatalog 6 过滤字段、新增 ServiceCatalog/Detail、出向方法收敛
- 修正 /api/** 未命中非 GET 请求被静态兜底判成 405 的偏差,恢复 404 契约
- 新增上游用例跨进程验证脚本与 4 份联调文档;部署级凭据只从环境变量读取
- 全量测试 308 passed;132 端点契约一致;真 TDS 21 条用例 19 PASS / 1 FAIL / 1 INFO
2026-11-05 17:53:15 +08:00

369 lines
25 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.
# TDC ↔ TDS 跨方契约
> 🔴 **现状(P4 已落地)**:本仓**有** TDS 出向通道,**只走 internal 通道**
> (≡ 上游 `TdsReportClient.internalHeaders()` / `internal*` / `*Billing`)。
> 旧版的 `/api/ssw/tdc/tds/*` 代理网关**已下线**(请求该路径 ⇒ **404**)。
>
> **本轮范围**:照抄上游新版 TDC 的 `ServiceCatalogController` + `BillingController`
> (10 个端点),出向打到真 TDS 的 `*/Internal/*` 与 `BillingLedger/*` 端点。
> 上游还有一条 login/`ensureToken` 通道(JNPF 登录换 token)⇒ **本轮不做**。
>
> **上游真源**(只读):
> - `ssw-tdc-controller/.../ServiceCatalogController.java`、`.../BillingController.java`
> - `ssw-tdc-biz/.../client/TdsReportClient.java`
> - `ssw-tds-controller/.../{Catalog,TradeOrder,BillingLedger,Space}Controller.java`
---
## 1. 通道:只走 internal
| 通道 | 上游入口 | 本仓 | 说明 |
|---|---|---|---|
| **internal** | `TdsReportClient`(`X-Internal-Token` + 固定头) | ✅ **本轮实现** | TDS `white-url` 放行的内部端点 |
| login / `ensureToken` | `TdsReportClient.ensureToken`(JNPF 登录换 token) | ❌ 不做 | 本轮不需要 |
| ~~Bridge/\*\*~~ | 旧 `HttpTdcTdsClient` 代理(`App-Code: tdc`) | ❌ **已下线** | 旧代理随 Task 10 撤除 ⇒ 404 |
**为什么 internal**:`App-Code: sswflow`(internal 通道的值)**≠** `App-Code: tdc`(Bridge 通道的值)。
上游新版 TDC 的服务目录 / 账单两页走的是 internal 通道 ⇒ 本仓照抄。
---
## 2. 出向请求头(**正好 6 个**,逐字照抄上游 `internalHeaders()`)
| 头 | 值 | 说明 |
|---|---|---|
| `Content-Type` | `application/json` | |
| `App-Code` | `sswflow` | 🔴 **不是** `tdc`(那是 Bridge 通道) |
| `Jnpf-Origin` | `pc` | |
| `Vue-Version` | `3` | |
| `X-Internal-Token` | `SSW_TDS_INTERNAL_TOKEN` | 有默认值(本地单机模式不出向时无所谓) |
| `X-Protocol-Version` | `1.0` | 与上游 `InternalTokenSupport.PROTOCOL_VERSION` 一致 |
- 🔴 **绝不**带 `Authorization` / `Cookie` ⇒ 本地会话令牌不外泄。
- 🔴 超时照抄上游 `restTemplate()`:**连接 3s / 读取 5s**(快速失败,别拖垮本地业务)。
- 🔴 `reqwest` 客户端必须 `.no_proxy()` ⇒ 本机 `HTTP_PROXY` / 系统代理会把 loopback 的 TDS 劫持成 502。
---
## 3. 本仓对外 10 个端点 → 出向 TDS 端点
> 路径与 HTTP 方法**逐字对齐上游前端**(上游 SPA 的 `W = "/api/ssw/tdc"`,
> `static/assets/tdc-*.js` 里 `serviceCatalog` / `billing` 两个 api 对象就是这 10 个调用)。
| 本仓端点 | 方法 | 出向 TDS 路径 | 方法 | 体 | 返回形状 |
|---|---|---|---|---|---|
| `/api/ssw/tdc/ServiceCatalog` | GET | `/api/ssw/tds/Catalog/Internal/Catalog` | POST | `{spaceId, keyword}` | 解包型 ⇒ `data`(`{list,total}`) |
| `/api/ssw/tdc/ServiceCatalog/Buy` | POST | `/api/ssw/tds/TradeOrder/Internal/Apply` | POST | 透传(补 `buyerConnectorId`) | 解包型 ⇒ `data` |
| `/api/ssw/tdc/ServiceCatalog/BuyBatch` | POST | `/api/ssw/tds/TradeOrder/Internal/ApplyBatch` | POST | 透传(补 `buyerConnectorId`) | 解包型 ⇒ `data` |
| `/api/ssw/tdc/Billing/List` | GET | `/api/ssw/tds/BillingLedger/Internal/List` | POST | `{connectorId[, keyword]}` | 整包型 ⇒ `data` |
| `/api/ssw/tdc/Billing/{id}/Dispute` | PUT | `/api/ssw/tds/BillingLedger/{id}/Dispute` | PUT | `{}` | 整包型 ⇒ `msg` + 账本 id |
| `/api/ssw/tdc/Billing/{id}/Confirm` | PUT | `/api/ssw/tds/BillingLedger/{id}/Confirm?connectorId=` | PUT | `{}` | 整包型 ⇒ `msg` + 账本 id |
| `/api/ssw/tdc/Billing/{id}/Settle` | PUT | `/api/ssw/tds/BillingLedger/{id}/Settle?connectorId=` | PUT | `{}` | 整包型 ⇒ `msg` + 账本 id |
| `/api/ssw/tdc/Billing/{id}/Receipt` | PUT | `/api/ssw/tds/BillingLedger/{id}/Receipt` | **POST** | `{receiptNo, remark}`(只挑这两个键) | 整包型 ⇒ `msg` + 账本 id |
| `/api/ssw/tdc/Billing/{id}/Voucher` | GET | `/api/ssw/tds/BillingLedger/{id}/Voucher` | GET | — | 整包型 ⇒ `data`(须是对象) |
| `/api/ssw/tdc/Billing/LocalCompare?contractId=` | GET | **不出向** | — | — | 本地表 `tdc_api_consume_log` |
- 🔴 **对外 PUT / 出向 POST**(`Receipt`):上游 TDC 控制器对外是 `PUT`,TDS 侧是 `POST` ⇒ 两边都要对。
- 🔴 **出向 URL 只由固定路径模板拼出**:路径段(账本 id)过白名单
(ASCII 字母/数字/下划线/短横线,1..=64)⇒ 用户输入绝不直接进 URL 路径。
- 🔴 `connectorId` 走**查询串**(不是头)⇒ 必须 URL 编码。
### 3.1 两种返回风格(照抄上游,别混)
| 风格 | 上游方法 | 语义 |
|---|---|---|
| **解包型** | `internalCatalog` / `internalApply` / `internalApplyBatch` | `code==200` ⇒ 取 `data`;否则 `Err(msg)` |
| **整包型** | `listBillingForConnector` / `dispute` / `confirm` / `settle` / `receipt` / `voucher` | 原样返回 `{code,msg,data}`,由上层判 `code` |
⚠️ 整包型的**成功**里 `data` 是**字符串**(账本 id),不是对象 —— 写测试/解析时别想当然。
### 3.2 身份解析:两套口径(照抄上游)
| 端点 | 口径 | 规则 |
|---|---|---|
| `Billing/List` / `Dispute` / `Receipt` / `Voucher` / `LocalCompare` | **宽松**(上游 `resolveConnectorId`) | 显式 `connectorId` 优先;为空取本端固定身份 |
| `Billing/{id}/Confirm` / `Settle` | **严格**(上游 `resolveOwnConnectorIdStrict`) | 只认本端身份;显式 id 与本端**不一致** ⇒ 拒 |
- **本端固定身份** = `tdc_identity` 里 `f_default_mark` 优先的那一行
(`f_tds_space_id` ⇒ 空间;`f_tds_connector_id` ⇒ 连接器)。
- **越权自检**(上游 `ownsLedger`):动作类端点先 `BillingLedger/Internal/List`(**不带 keyword**),
在 `data.list` 里找 id 匹配 ⇒ 不匹配 ⇒ 拒。**任何异常 ⇒ false(fail-closed)**。
⚠️ 这条自检本身**会发一次出向请求**(`List`)—— 断言「越权时不出向」时只能断言
**动作端点没被调用**,不能断言「一条出向都没有」。
---
## 4. 降级语义(三档,**都不许变成 HTTP 500 / panic**)
| 情形 | 表现 | 文案来源 |
|---|---|---|
| **NOOP**(未配 `SSW_TDS_BASE_URL`) | 本地单机模式,**不发任何网络请求** | 「未配置 TDS 地址(本地单机模式)」 |
| **不可达**(超时 / 网络错 / 响应不是 JSON) | 业务失败(HTTP 200 + `code:400`) | 上游原话「TDS …不可达」 |
| **TDS 业务失败**(HTTP 200 但 `code != 200`) | 业务失败(HTTP 200 + `code:400`) | TDS 的 `msg` 原文 |
- 🔴 **TDS 业务错误走 HTTP 200** ⇒ 判定成败**必须看 body 的 `code`**(只看 HTTP 状态会把失败误判成成功)。
- 🔴 本仓对外也是 **HTTP 200 + `{code,msg,data}`**(业务失败 = `code:400`,`data:null`)。
---
## 5. 已登记的刻意分歧(照抄上游时**故意**不同的地方)
| # | 分歧 | 上游 | 本仓 | 理由 |
|---|---|---|---|---|
| D1 | 宽松身份口径 | 既有端点(List/Dispute/Receipt/Voucher/LocalCompare)就是宽松的 | **照抄**(未加固) | 用户明确「照抄上游,不创新」 |
| D2 | 异常包装 | 抛异常 | `Result<T, String>` | Rust 侧表达;**语义逐条对齐** |
| D3 | `msg` 缺失时的文案 | `String.valueOf(res.get("msg"))` ⇒ 字面量 `"null"` | 空串兜底 | 上游那个 `"null"` 是 bug,前端会显示一个 "null" |
| D4 | 数字型 `connectorId` | 硬转 `(String)` ⇒ `ClassCastException`(500) | 宽松取文本,**不 500** | 上游自己注了这一点(2026-09-19 审查 P2-7) |
| D5 | 空请求体 | 上游 `@RequestBody` 必填 ⇒ 报错 | 动作类端点**接受空体**(当空对象) | 上游这几个端点体可空;`ServiceCatalog/Buy` 也是空体当空对象 |
| D6 | 分页 | 上游 standalone 分支不翻页 | `currentPage`/`pageSize` **忽略** | 上游 `internalCatalog` 无分页参数 |
| D7 | `Content-Type` 校验 | 上游 415 | 本仓不校验 ⇒ 报「请求体格式有误」 | 与本仓其它端点一致(`JsonBody` 口径) |
---
## 6. 实测记录(真 TDS,2026-10-25)
**环境**:TDS = `http://127.0.0.1:30041`(库 `tds2`,`java` PID 56575,**不重启**);
本仓连接器 = `:30410`(`SSW_TDS_BASE_URL=http://127.0.0.1:30041`)。
身份绑定:空间 `PORTAL-DEMO-SPACE`(门户演示空间)。
### 6.1 本仓 10 个端点(对外形状)
| # | 调用 | 本仓返回 |
|---|---|---|
| 1 | `GET /api/ssw/tdc/ServiceCatalog?keyword=` | `{"code":200,"msg":null,"data":{"list":[],"total":0}}` |
| 2 | `POST /api/ssw/tdc/ServiceCatalog/Buy` 体 `{"productId":"P-1"}` | `{"code":400,"msg":"数据产品不存在: null","data":null}` |
| 3 | `POST /api/ssw/tdc/ServiceCatalog/BuyBatch` 体 `{"productIds":["P-1","P-2"]}` | `{"code":400,"msg":"业务用途必填(平台运营据此审核)","data":null}` |
| 4 | `GET /api/ssw/tdc/Billing/List` | `{"code":200,"msg":null,"data":{"list":[]}}` |
| 5 | `PUT /api/ssw/tdc/Billing/{不存在的id}/Dispute` | `{"code":400,"msg":"非本方账单,无权发起异议","data":null}` |
| 6 | `PUT /api/ssw/tdc/Billing/{不存在的id}/Confirm` | `{"code":400,"msg":"非本方账单,无权确认","data":null}` |
| 7 | `PUT /api/ssw/tdc/Billing/{不存在的id}/Settle` | `{"code":400,"msg":"非本方账单,无权结算","data":null}` |
| 8 | `PUT /api/ssw/tdc/Billing/{不存在的id}/Receipt` | `{"code":400,"msg":"非本方账单,无权上传结算回执","data":null}` |
| 9 | `GET /api/ssw/tdc/Billing/{不存在的id}/Voucher` | `{"code":400,"msg":"非本方账单,无权下载对账凭证","data":null}` |
| 10 | `GET /api/ssw/tdc/Billing/LocalCompare?contractId=C-1` | `{"code":200,"msg":null,"data":{"contractId":"C-1","local":[]}}` |
> 全部 **HTTP 200**(业务失败也是 200)⇒ 判成败必须读 body 的 `code`。
> 5–9 是**本仓的越权闸门**先拒的(`ownsLedger` 查不到该账本)⇒ **动作请求根本没发出去**。
### 6.2 TDS 侧**原始**返回(直打 TDS,绕开本仓闸门)
| # | TDS 调用 | TDS 原始返回 |
|---|---|---|
| T1 | `GET /api/ssw/tds/Space/Internal/List` | `{"code":200,"msg":"Success","data":[{"id":"PORTAL-DEMO-SPACE",…,"name":"门户演示空间",…}]}` |
| T2 | `POST /api/ssw/tds/Catalog/Internal/Catalog` 体 `{"spaceId":"PORTAL-DEMO-SPACE","keyword":null}` | `{"code":200,"msg":"Success","data":{"list":[],"total":0}}` |
| T3 | `POST /api/ssw/tds/TradeOrder/Internal/Apply` 体 `{}` | `{"code":400,"msg":"数据产品不存在: null"}` |
| T4 | `POST /api/ssw/tds/TradeOrder/Internal/ApplyBatch` 体 `{}` | `{"code":400,"msg":"多方批次下单需至少勾选 2 个提供方资源(单标请走 /Internal/Apply)"}` |
| T5 | `POST /api/ssw/tds/BillingLedger/Internal/List` 体 `{"connectorId":"854250096668180741"}` | `{"code":200,"msg":"Success","data":{"list":[]}}` |
| T6 | `PUT /api/ssw/tds/BillingLedger/{不存在的id}/Dispute` | `{"code":400,"msg":"台账不存在"}` |
| T7 | `PUT /api/ssw/tds/BillingLedger/{不存在的id}/Confirm?connectorId=…` | `{"code":400,"msg":"台账不存在"}` |
| T8 | `PUT /api/ssw/tds/BillingLedger/{不存在的id}/Settle?connectorId=…` | `{"code":400,"msg":"台账不存在"}` |
| T9 | `POST /api/ssw/tds/BillingLedger/{不存在的id}/Receipt` | `{"code":400,"msg":"台账不存在"}` |
| T10 | `GET /api/ssw/tds/BillingLedger/{不存在的id}/Voucher` | `{"code":400,"msg":"台账不存在"}` |
| T11 | `GET /api/ssw/tds/Space/Internal/List`(**不带令牌**,对照组) | `{"code":400,"msg":"缺少有效凭证(需登录或内部凭证)"}` |
- T11 说明 **`X-Internal-Token` 真的生效**(缺了就 400)。
- ⚠️ **调试 TDS 里没有本连接器的账本行** ⇒ 5 个动作端点的**成功路径**无法对着真 TDS 走通
(TDS 侧只会回「台账不存在」)。成功路径由 `tests/tds_biz.rs` 的**假 TDS** 覆盖。
- T3/T4 的拒因**逐字**来自 TDS(`数据产品不存在: null` 里的 `null` 是 TDS 自己拼的,
本仓**原样透传**,没替它美化)。
### 6.3 浏览器级验收(上游控制台两个 TDS 页)
| 页面 | 页面发出的后端调用 | 结果 |
|---|---|---|
| `/tdc/service-catalog` | `GET /api/ssw/tdc/ServiceCatalog?currentPage=1&pageSize=20` | ✅ **200**(R3 时代是 404),页面渲染出表格壳 |
| `/tdc/billing` | `GET /api/ssw/tdc/Billing/List?currentPage=1&pageSize=10` | ✅ **200**(R3 时代是 404),页面渲染出账期/产品/合约编号/… 列 |
两页都是「No data」—— 演示 TDS 里没有产品 / 账本 ⇒ **不是**本仓的锅。
---
## 7. 旧 Bridge 通道(**历史,已下线**)
> 留档以便追溯,**本仓不再实现**。
| 文件 | 作用 |
|---|---|
| `TdcTdsClient.java` | 抽象接口 |
| `HttpTdcTdsClient.java` | HTTP 实现(配 `ssw.tds.base-url` 时生效) |
| `NoopTdcTdsClient.java` | 降级实现(未配 base-url) |
| `TdcTdsClientConfig.java` | 装配(base-url / internal-token 注入) |
旧契约清单(**全部 404**):
```
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
```
旧代理时代的实测(2026-10-23,**已失效**,仅供追溯):
| 调用 | 结果 |
|---|---|
| `Bridge/Contract/855041382379688261` | `contractCode: CT-CRT-yxkcm`,状态 `01` |
| `Bridge/Connector/854250096668180741` | 「TEE 连接器_05496131」,`orgName: 吉利汽车`,`ONLINE` |
| `Bridge/DataProduct/855039616187633989` | 「测评目录产品-iws2k」,`DRAFT` |
旧代理的「失败即降级、绝不拖垮本地 TDC 业务」原则**已被 internal 通道继承**
(见 §4 三档降级)。
### 6.4 契约 stub 联调实测(2026-11-05,跨进程真 HTTP 对端)
**背景**:真 TDS(`ssw/trusted-space/ssw-tds`)在本机无法独立启动(RocketMQ name-server
`192.168.10.6:30094`、MinIO `192.168.0.207:9000` 均不可达)。改用**契约忠实 TDS stub**
(`tds-stub/server-internal.js`,零依赖 Node,监听 `127.0.0.1:30100`)做跨进程联调:
stub 逐请求打印「方法/路径/查询串/六固定头/体长度」,可直接核对 tdc-rs 出向是否逐字照抄
上游 `internalHeaders()`。证据见 `tds-stub/integration-evidence.log`。
**环境**:tdc-rs `:30410`(`SSW_TDS_BASE_URL=http://127.0.0.1:30100`、`SSW_TDS_INTERNAL_TOKEN=ssw-internal-token-e2e`);
本端身份 `LOCAL-CONNECTOR`(`f_tds_space_id=PORTAL-DEMO-SPACE`、`f_tds_connector_id=854250096668180741`,
经 `PUT /api/ssw/tdc/Identity/{id}` 写入,使越权自检可过)。
**出向契约核对(10 端点全部对齐)**:
| 本仓端点 | 出向 TDS | 实测出向(stub 日志) | 结果 |
|---|---|---|---|
| ServiceCatalog GET | Catalog/Internal/Catalog (POST) | `POST /api/ssw/tds/Catalog/Internal/Catalog` bodyLen=46 | ✅ 解包型 `data`→`{list,total}` |
| ServiceCatalog/Buy POST | TradeOrder/Internal/Apply (POST) | `POST /api/ssw/tds/TradeOrder/Internal/Apply` | ✅ |
| ServiceCatalog/BuyBatch POST | TradeOrder/Internal/ApplyBatch (POST) | `POST /api/ssw/tds/TradeOrder/Internal/ApplyBatch` | ✅ |
| Billing/List GET | BillingLedger/Internal/List (POST) | `POST /api/ssw/tds/BillingLedger/Internal/List` | ✅ 整包型 `data` 原样返回 |
| Billing/{id}/Dispute PUT | BillingLedger/{id}/Dispute (PUT) | 先 `List`(自检) 再 `PUT .../Dispute` | ✅ |
| Billing/{id}/Confirm PUT | …/Confirm?connectorId= (PUT) | `PUT .../Confirm?connectorId=854250096668180741` | ✅ 查串非头 |
| Billing/{id}/Settle PUT | …/Settle?connectorId= (PUT) | `PUT .../Settle?connectorId=854250096668180741` | ✅ |
| Billing/{id}/Receipt PUT | …/Receipt (POST) | 对外 PUT、出向 `POST .../Receipt` bodyLen=31 | ✅ 分歧 D-对外PUT/出向POST 对齐 |
| Billing/{id}/Voucher GET | …/Voucher (GET) | `GET .../Voucher` | ✅ |
| Billing/LocalCompare GET | **不出向** | 日志无新增 | ✅ 本地表 |
> 所有出向均带 6 固定头(`app-code=sswflow`/`jnpf-origin=pc`/`vue-version=3`/`x-protocol-version=1.0`/
> `X-Internal-Token`(stub 校验通过)/`Content-Type:application/json`)⇒ 与 §2 逐字一致。
**越权自检(fail-closed)**:`Billing/{id}/Dispute|Confirm|Settle|Receipt|Voucher` 对非本方账本
(如 `NOPE-LEDGER`)→ 「非本方账单,无权…」;stub 日志仅见 `BillingLedger/Internal/List`
(`owns_ledger` 自检),**动作请求未发出** ⇒ 与 §3.2 一致。
**三档降级(均 HTTP 200 + `code:400`,绝不 500/panic)**:
| 档 | 触发 | 本仓返回 |
|---|---|---|
| NOOP | 未配 `SSW_TDS_BASE_URL`(启动日志 `TDS mode: NOOP`) | `{"code":400,"msg":"未配置 TDS 地址(本地单机模式)"}`,无出向 |
| 不可达 | `SSW_TDS_BASE_URL` 指向死端口 30199 | `{"code":400,"msg":"TDS 账单查询不可达"}`,无出向 |
| 业务失败 | TDS 回 HTTP 200 + `code≠200` | 透传 TDS `msg`(如 `{"code":400,"msg":"多方批次下单需至少勾选 2 个提供方资源…"}`) |
**结论**:tdc-rs P4 出向通道与真 TDS(`ssw/trusted-space/ssw-tds` 控制器逐字确认)契约**完全对齐**,
无分歧;6 固定头、token、解包/整包、越权自检、三档降级均符合 `docs/TDC-TDS-CONTRACT.md` 与上游代码。
---
## §6.5 真实测试 TDS 部署联调(`192.168.1.50:33000`)
对端:**运营平台(TDS) `http://192.168.1.50:33000/`**(门户账号由部署方提供,标题「尚数网可信数据空间」)。
非 stub,是真部署,用来做真·跨进程联调。
### 发现 1:协议版本错位(🔴 阻塞,已修)
- 真 TDS 实际为**协议 `3.2`**(`ssw-tds/.../InternalTokenSupport.PROTOCOL_VERSION = "3.2"`)。
- 版本闸门语义(与上游逐字一致):**主版本必须相等,次版本向后兼容**;未声明⇒放行+WARN;声明了但不兼容⇒**fail-closed 401**。
- tdc-rs 此前硬编码 `X-Protocol-Version: "1.0"`(`platform/protocol.rs` 常量)⇒ 对真 TDS 直接 401:
`{"code":401,"msg":"跨端协议版本不兼容(对端 1.0,本端 3.2),请升级对端"}`。
- 根因:tdc-rs(ssw-tdc 的 Rust 重实现)**落后两个主版本**未同步;上游 Java `ssw-tdc` 应同为 `3.2`。
**修复(严格 1:1 对齐 ssw-tdc)**:将 `platform/protocol.rs` 的单一常量 `PROTOCOL_VERSION` 升到 `"3.2"`,
其同时驱动**入向闸门**与**出向 `X-Protocol-Version` 头**(≡ 上游 `InternalTokenSupport.PROTOCOL_VERSION` 一处定义两处复用)。
**移除**原联调期临时加的 `SSW_TDS_PROTOCOL_VERSION` 环境变量与 `tds_protocol_version` 字段——ssw-tdc 真源无此 env,
tdc-rs 不引入自创逻辑。改动:`platform/protocol.rs`(`PROTOCOL_VERSION="3.2"`)、`tdc/client/tds.rs`
(`internal_headers` 直接引用该常量、删 `protocol_version` 字段与构造参数)、`tdc/state.rs`、`platform/config.rs`(删字段/env)、测试同步。
验证:以该常量启动后,真 TDS 版本闸门放行,回 `{"code":400,"msg":"缺少有效内部凭证"}`(token 错,证明版本已对上)。
### 发现 2:内部令牌为部署私有值(✅ 已由部署方提供,联调跑通)
- 令牌校验:`InternalTokenSupport.isInternal(req, internalToken)` 逐字比对 `X-Internal-Token` 与
配置的 `internal-token`(默认 `ssw-internal-token-e2e`,来源 `SSW_INTERNAL_TOKEN` 环境变量)。
- 真 TDS 用**非默认**令牌:默认 `ssw-internal-token-e2e` 及十余个常见测试值全部回
`缺少有效内部凭证`;仓库 `application.yml`、部署目录均无明文 ⇒ 部署方设定的私有值。
- 部署方已提供该值,写入 `SSW_TDS_INTERNAL_TOKEN` 后所有 internal 端点放行。
### 联调结果(2026-11-05;真源钉在 ssw-tdc `3d247df`)
健康检查:`{"protocolVersion":"3.2","tdsMode":"HTTP","tdsBaseUrl":"http://192.168.1.50:33000"}`。
| 端点 | 真 TDS 结果 |
|---|---|
| `GET /ServiceCatalog` | `code:200`,701 个真实产品 |
| `POST /ServiceCatalog/Buy` | 见发现 3;修正字段后 `code:200`,订单 `DD202611050011` |
| `POST /ServiceCatalog/BuyBatch` | `productIds` 被识别,回业务校验「需至少勾选 2 个提供方资源」 |
| `GET /Billing/List` | `code:200`(部署侧列表为空) |
| `GET /Billing/LocalCompare?contractId=...` | `code:200`,`{contractId, local:[]}` |
| `GET /Billing/{id}/Voucher`(真实账本) | `code:200`,完整 `{ledger, metrics}` |
| 5 个账本动作 `ownsLedger` 自检 | 非本方账本全部 fail-closed 拒绝,拒因文案各自正确 |
| 出向 6 固定头 + `X-Protocol-Version: 3.2` | 全部放行(与 `3d247df TdsReportClient.internalHeaders():2569` 逐字一致) |
### 发现 3:Buy 字段名漂移(🔴 两仓契约问题,已交 ssw-tdc 项目组)
目录返回的产品**没有 `usageId` 字段**(只有 `id` 主键 / `productId` 业务编码);ssw-tdc standalone
Buy 原样透传 body;ssw-tds `TradeOrderServiceImpl.buy` 只取 `usageId` 且 `getById` 按主键查。
实测 `productId` / `id` 任一值 ⇒ `数据产品不存在: null`;只有
`{"usageId":"<产品主键>","buyerConnectorId":"<已注册连接器>"}` 才能下单成功。
详见 `docs/SSW-TDC-TDS-INTEGRATION-FINDINGS.md`(含完整字段组合实测表与修复建议)。
### 发现 4:真源版本差距(tdc-rs 已同步闭环)
钉住 `3d247df` 后发现 tdc-rs 曾保留已下线的 `/Billing/{id}/Dispute`、缺 `side` 参数、
`internalCatalog` 过滤字段不全;现已逐项按真源同步,并从建仓基线 `c568cc7` 回溯到
最新 main `2d331e9` 核对契约层。详见 `docs/TDC-RS-ALIGNMENT-GAP.md`。
### 复跑命令
```bash
# 启动(协议版本由 platform/protocol.rs 单一常量 3.2 驱动,无 env 覆盖)
PORT=30410 TDC_DATA_DIR=<project>/data \
SSW_INTERNAL_TOKEN=ssw-internal-token-e2e \
SSW_TDS_BASE_URL=http://192.168.1.50:33000 \
SSW_TDS_INTERNAL_TOKEN=<部署方令牌> \
./target/debug/tdc-connector
# 调用:本机 HTTP_PROXY 会劫持 loopback/内网 ⇒ 一律 --noproxy '*'
curl -s --noproxy '*' -H 'X-Internal-Token: ssw-internal-token-e2e' \
-H 'X-Protocol-Version: 3.2' http://127.0.0.1:30410/api/ssw/tdc/ServiceCatalog
```
### 上游更新同步后的复验(2026-11-05 17:00)
按用户要求回溯 **tdc-rs 建仓基线 `c568cc7`(2026-10-23,`PROTOCOL_VERSION=1.0`)→
ssw-tdc 最新 main `2d331e9`(15:55)**,共 188 提交 / 472 文件;协议版本期间连升 7 次到 `3.2`。
`3d247df..2d331e9` 的 8 个提交只动沙箱/前端,**契约层与 .50 部署版本等价**。
已严格照抄同步 5 项契约变更(详见 `docs/TDC-RS-ALIGNMENT-GAP.md`):
Dispute 下线、`side`、`internalCatalog` 6 过滤字段、新增 `catalogDetail` + `/Detail/{productCode}`、协议 3.2。
复验矩阵(服务 `127.0.0.1:30410`,health = `protocolVersion:3.2 / tdsMode:HTTP`):
| 请求 | 真 TDS 结果 | 说明 |
|---|---|---|
| `GET /ServiceCatalog` | `200`,701 条 | 通道正常 |
| `GET /ServiceCatalog?keyword=E2E-DNP-b3r3b-a7ty` | `200`,**1 条** | 新增过滤字段真实生效 |
| `?keyword=NOT-EXIST-XYZ` / 6 参数组合 | `0` 条 / `{"list":[],"total":0}` | 对端确实按字段过滤 |
| `GET /ServiceCatalog/Detail/E2E-DNP-b3r3b-a7ty` | `200` 完整详情 | **新增端点打通** |
| `Detail/887690246907504709`(主键) | `400 产品不存在或不在本空间目录` | TDS 按 productCode 查 |
| `Detail/...?spaceId=BOGUS` | `200` 正确详情 | spaceId 只取本端身份,不信任入参 |
| `Detail/%2e%2e` | `400 产品编码非法: ..` | 路径段白名单生效 |
| `GET /Billing/List?side=PROVIDER` | `200` 真实账本 | side 生效 |
| `?side=CONSUMER` / `?side=BOGUS` | 空 / `400 side 只接受 PROVIDER / CONSUMER` | 对端校验该字段 |
| `PUT /Billing/FAKE/Dispute` | `404 接口不存在`(17:35 修复 405 偏差后) | **已下线**(不再是业务端点) |
| `POST /Buy {"productId":...}` | `400 数据产品不存在: null` | 两仓漂移仍在(见发现 3) |
| `POST /Buy {"usageId":"<主键>","buyerConnectorId":"<已注册>"}` | `200` 生成订单 | 链路通 |
| `POST /BuyBatch` | `400 需至少勾选 2 个提供方资源` | 业务校验正常 |
| `GET /Billing/{真实账本}/Voucher` | `200 {ledger, metrics}` | 只读出向正常 |
| `PUT /Billing/FAKE/Confirm` | `400 无法确定连接器身份…` | 严格口径 + 本地身份未注册 |
本地验证(17:35 复跑):`cargo test` 全量 **308 passed / 0 failed / 1 ignored**;
`check-contract.sh` **132 条端点 ↔ 实际注册路由完全一致**(删 Dispute −1 / 加 Detail +1,总数不变)。
**上游用例跨进程验证(17:35)**:`python3 scripts/verify-upstream-cases.py --with-write`
⇒ 21 条,**19 PASS / 1 FAIL / 1 INFO**。唯一 FAIL 是上游 `contacter` ↔ `buyerContact`
字段漂移(tdc-rs 按真源透传,不自创映射);U05「下线端点 ⇒ 404」已由 405 修为 404 并转 PASS。
详见 `docs/UPSTREAM-CASES-VERIFICATION.md`。