影响: - `docs/TDC-TDS-CONTRACT.md` 由「P4 的输入清单」改写为「已落地契约」: 只走 internal 通道、6 个固定出向头、10 个对外端点 → 出向 TDS 端点映射、 降级三档、7 条刻意分歧、真 TDS 实测记录。 - `README.md` / `CLAUDE.md` 补上 10 个出向端点、两个环境变量、TDS 通道小节与踩坑行。 改动: - 契约文档重写:新增「返回风格两套」「身份解析两套口径」「降级三档」三节, 补录本仓 10 个端点与 TDS 侧 11 条原始返回的实测表。 - README:后端 API 表增 7 行、环境变量表增 `SSW_TDS_BASE_URL` / `SSW_TDS_INTERNAL_TOKEN`(令牌值只指向 `src/config.rs`,不入文档)。 - CLAUDE.md:目录树、红线、API 表、关键实现细节 13–14、TDS 出向通道小节、 踩坑表 6 行、范围外声明同步。 - 计划文件:修正「12 条用例」为实际的 4 条用例(219 = 207 + 8 + 4), 并记录实施后与上游的三处差异(空体可选、connectorId 取值宽松、query 传参)。 - 工作日志追加 P4 小节:4 个 commit、5 个变异自证表、真 TDS 实跑结果、3 个遗留项。 设计: - 不改 `static/`:上游 SPA 的 serviceCatalog / billing 两个 api 对象要的正是 这 10 个路径,后端补齐即可 ⇒ 前端一个字不动。 - 遗留 R10(`GET /api/ssw/tdc/Identity` 泄漏 `secretKey`,上游是 `@JsonIgnore`) 与 R11(13 个文件的 rustfmt 漂移)本轮不修,超出 P4 范围,已登记。 Co-Authored-By: Claude Code <[email protected]>
213 lines
14 KiB
Markdown
213 lines
14 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 三档降级)。
|