# 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` | 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 三档降级)。