Files
tdc-rs/docs/TDC-TDS-CONTRACT.md
T
xstudio 885b108fe0 init: TDC 连接器 Rust MVP(pglite-rs 内嵌 + 静态 HTML 控制台)
从 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/ 记录跨方契约细节
2026-10-24 10:31:06 +08:00

73 lines
3.7 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 跨方契约参考
本仓库 `/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 侧的额外约束(实测)
1. **`Bridge/**` 需 `App-Code: tdc`**
`TdsBridgeInternalController` 的白名单只放行 `App-Code=tdc`;缺该头直接返回 `App-Code invalid`。
`X-Internal-Token` 仅在 `tds.internal-secret` 非空时才校验(当前配置为空 = 免 token)。
→ 本仓库代理对 `Bridge/**` **统一注入** `App-Code: tdc`,并丢弃客户端自带的该头以防伪造/重复。
2. **业务错误走 HTTP 200 + body `code`**
例如 `AuthFilter` 未放行时返回 `{"code":600,"msg":"登录过期"}`,HTTP 状态仍是 200。
→ 判定成败必须同时看 `body.code == 200`,只看 HTTP 状态会把失败误判为成功。
3. **无 `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`。
4. **`NodeReport`**
`POST /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` 库一致。