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

14 KiB
Raw Blame History

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