- 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]>
83 lines
4.5 KiB
Markdown
83 lines
4.5 KiB
Markdown
# 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 落地出向客户端时,**重新做一遍**这组实测并更新本表。
|