从 ssw-mvp/boot/ssw-tdc(Spring Boot/JNPF,37 Controller)剥离重底座的本地优先实现: - axum 单进程承担控制面/数据面/静态托管/TDC→TDS HTTP 契约网关 - pglite-rs 0.2 内嵌原生 PostgreSQL(进程内,非浏览器 WASM),19 张 tdc_* 表 - 静态 HTML + 原生 JS 控制台:schema 自省驱动 CRUD + 按表生命周期动作 - 红线:TDC↔TDS 只走 HTTP 契约,未配 SSW_TDS_BASE_URL 时 Noop 降级 - AGENTS.md 记录架构红线、命令速查与踩坑清单;docs/ 记录跨方契约细节
3.7 KiB
TDC ↔ TDS 跨方契约参考
本仓库 /api/ssw/tdc/tds/* 代理网关所还原的原始契约,真源在
~/Desktop/workspace/ssw-mvp/boot/ssw-tdc/ssw-tdc-controller/src/main/java/ssw/tdc/client/。
原 Java 侧结构
| 文件 | 作用 |
|---|---|
TdcTdsClient.java |
抽象接口 |
HttpTdcTdsClient.java |
HTTP 实现(配 ssw.tds.base-url 时生效) |
NoopTdcTdsClient.java |
降级实现(未配 base-url) |
TdcTdsClientConfig.java |
装配(base-url / internal-token 注入) |
核心原则:所有调用失败即降级(catch 后返回空/默认值),绝不拖垮本地 TDC 业务。
契约清单(原注释逐条抄录)
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
请求头:非空时带 X-Internal-Token(对应 JNPF AuthFilter 的 exclude-url 内部免鉴权端点)。
真实 TDS 侧的额外约束(实测)
-
Bridge/**需App-Code: tdcTdsBridgeInternalController的白名单只放行App-Code=tdc;缺该头直接返回App-Code invalid。X-Internal-Token仅在tds.internal-secret非空时才校验(当前配置为空 = 免 token)。 → 本仓库代理对Bridge/**统一注入App-Code: tdc,并丢弃客户端自带的该头以防伪造/重复。 -
业务错误走 HTTP 200 + body
code例如AuthFilter未放行时返回{"code":600,"msg":"登录过期"},HTTP 状态仍是 200。 → 判定成败必须同时看body.code == 200,只看 HTTP 状态会把失败误判为成功。 -
无
POST /api/ssw/tds/Connector/Register真实ConnectorController只有/{id}/Audit|Heartbeat|Offline|Cancel|PullSession|BusinessDetail; 连接器由运营方在 CRUD 侧建档。 → 本仓库register端点在真 TDS 上返回registerStatus: UNSUPPORTED_BY_TDS,不伪造成功; Noop 模式(未配 base-url)才本地置APPROVED。 -
NodeReportPOST /api/ssw/tds/NodeReport可直连(200);GET /NodeReport/Categories需登录态。 → 本仓库 heartbeat 在配 base-url 时一并上报NodeReport,失败仅告警不影响本地。
代理行为约定(src/main.rs → tds_proxy)
| 行为 | 实现 |
|---|---|
| 路径映射 | /api/ssw/tdc/tds/{rest} → {base}/api/ssw/tds/{rest}(query 透传) |
| 逐跳头剥离 | host / content-length / connection / transfer-encoding / upgrade / keep-alive / te / trailer |
| 内部令牌 | SSW_TDS_TOKEN 非空时注入 X-Internal-Token |
| App-Code | rest 以 Bridge 开头时注入 App-Code: tdc(覆盖客户端自带值) |
| 上游不可达 | 返回 502 {"error":"tds unreachable"} |
| 未配 base-url | 返回 501 NOOP mode(对应原 NoopTdcTdsClient) |
| 响应回传 | 透传上游状态码与 Content-Type,body 原样字节回传 |
实测验证记录(真实 TDS,2026-10-23)
| 调用 | 结果 |
|---|---|
Bridge/Contract/855041382379688261 |
contractCode: CT-CRT-yxkcm,状态 01 |
Bridge/Connector/854250096668180741 |
「TEE 连接器_05496131」,orgName: 吉利汽车,ONLINE |
Bridge/DataProduct/855039616187633989 |
「测评目录产品-iws2k」,DRAFT |
经本仓库连接器代理调用返回完全相同的数据,与 tds 库一致。