Files
tdc-rs/docs/TDC-TDS-CONTRACT.md
T
adminandClaude Code 52074a136d docs(tds): 补齐 P4 出向通道的契约文档与项目指引
影响:
- `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]>
2026-10-25 14:24:54 +08:00

213 lines
14 KiB
Markdown
Raw 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 三档降级)。