- 协议版本收敛为单一常量 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
369 lines
25 KiB
Markdown
369 lines
25 KiB
Markdown
# 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`。
|
||
|