影响: - `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]>
14 KiB
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.javassw-tdc-biz/.../client/TdsReportClient.javassw-tds-controller/.../{Catalog,TradeOrder,BillingLedger,Space}Controller.java
1. 通道:只走 internal
| 通道 | 上游入口 | 本仓 | 说明 |
|---|---|---|---|
| internal | TdsReportClient(X-Internal-Token + 固定头) |
✅ 本轮实现 | TDS white-url 放行的内部端点 |
login / ensureToken |
TdsReportClient.ensureToken(JNPF 登录换 token) |
❌ 不做 | 本轮不需要 |
旧 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 三档降级)。