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

4.5 KiB
Raw Blame History

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 落地出向客户端时,重新做一遍这组实测并更新本表。