Files
tdc-rs/docs/TDC-TDS-CONTRACT.md
T
adminandClaude Code 4a5b7ecb2b docs: 补齐鉴权/权限键说明 + 目录树同步 + DDL 守卫踩坑记录
- README: 新增「鉴权三道门」表与「写操作的权限键」说明块;「已实现范围」
  补 JNPF 兼容登录 + 本地账号管理一条;目录树同步到当前模块拆分
  (src/lib.rs、src/{account,auth,cipher,…}、src/domain、src/routes 全量、
  tests/、data/accounts.json)。
- docs/DDL-GUARD.md: 新增。记录 DDL 不可下载这条红线的四轮踩坑(路径级
  Unicode 大写折叠 1536/1536、内容级 Range 同偏移比对、fail-closed)、
  已知边界与回归测试入口。
- docs/TDC-TDS-CONTRACT.md: 加现状横幅 —— 旧代理网关已随 Task 10 下线
  (请求 /api/ssw/tdc/tds/* 现为 404),SSW_TDS_BASE_URL 仅用于健康检查
  回显与单机模式判定;本文改为 P4 出向客户端的输入契约。

Co-Authored-By: Claude Code <[email protected]>
2026-10-25 11:28:34 +08:00

83 lines
4.5 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 跨方契约参考
> 🔴 **现状(P0+P1)**:本仓**没有** TDS 出向通道。
> 旧版的 `/api/ssw/tdc/tds/*` 代理网关**已随 Task 10 下线**(现在请求该路径 ⇒ **404**)。
> `SSW_TDS_BASE_URL` 目前只用于**健康检查回显**与「本地单机模式」的判定,不产生任何出向请求。
>
> **本文现在的角色 = P4(TDS 出向客户端)的输入契约**,不是本仓现状的描述。
> 出向客户端落地时,本文列的路径/请求头/错误口径**逐条照抄**即可。
## 原 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`,失败仅告警不影响本地。
## 代理行为约定(**旧代理已下线**;下表是 P4 重做时的行为约定)
| 行为 | 约定 |
|---|---|
| 路径映射 | `/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 原样字节回传 |
> ⚠️ 「未配 base-url ⇒ 501 NOOP」「失败即降级、绝不拖垮本地 TDC 业务」是**原 Java 侧的核心原则**
> (`TdcTdsClient` → `NoopTdcTdsClient`),P4 重做时必须保留。
## 实测验证记录(真实 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` 库一致。
> ⚠️ 这份记录是**旧代理时代**(2026-10-23)留下的,**旧代理现已下线**。
> P4 落地出向客户端时,**重新做一遍**这组实测并更新本表。