Files
tdc-rs/docs/TDC-RS-ALIGNMENT-GAP.md
T
admin 4b32b40bd6 feat(tds): 同步 ssw-tdc 最新 internal 契约并完成真 TDS 联调验证
- 协议版本收敛为单一常量 3.2,移除联调期自创的 env 覆盖
- 按真源同步 5 项契约:Dispute 下线、Billing/List 增 side、internalCatalog 6 过滤字段、新增 ServiceCatalog/Detail、出向方法收敛
- 修正 /api/** 未命中非 GET 请求被静态兜底判成 405 的偏差,恢复 404 契约
- 新增上游用例跨进程验证脚本与 4 份联调文档;部署级凭据只从环境变量读取
- 全量测试 308 passed;132 端点契约一致;真 TDS 21 条用例 19 PASS / 1 FAIL / 1 INFO
2026-11-05 17:53:15 +08:00

8.9 KiB
Raw Blame History

tdc-rs 上游同步记录与剩余差距

性质:tdc-rs 自身记录,不是 ssw-tdc 项目组的动作项。 给项目组的问题见 SSW-TDC-TDS-INTEGRATION-FINDINGS.md。 同步目标(最新真源):ssw-tdc origin/main = 2d331e92855a5203ce9632dd3881754848344ba9(2026-11-05 15:55)。 部署对应版本:3d247df(.50 TDS 部署所用,14:13);已确认 3d247df..2d331e9 的 8 个提交 只动 K8s 沙箱 / 隐私计算 / 两个 Vue 文件,未碰契约层 ⇒ 两者契约等价,同步到最新 main 即可对齐 .50。 建仓基线:c568cc7(2026-10-23 16:18,tdc-rs 10-24 建仓前最后一个上游提交, 当时的 /tmp/sswtdc-probe 快照;PROTOCOL_VERSION = "1.0")。 核对/同步时间:2026-11-05 17:35,真 TDS 192.168.1.50:33000 复验并跑完 21 条上游用例后。

0. 基线 → 最新:上游这半个月改了什么

c568cc7..2d331e9 共 188 个提交、472 个文件改动,批次 chg_0018 ~ chg_0026, 新增 DB 迁移 V2.95.0 ~ V2.104.0 共 13 个。改动集中在前端/沙箱/交付域; 与 tdc-rs 已实现范围(standalone 目录·购买·账单 10 个端点)相关的契约变更只有下面 5 项。

协议版本演进(根因)

InternalTokenSupport.PROTOCOL_VERSION 在两仓各硬编码一份,期间连升 7 次:

提交 批次 版本
基线 c568cc7 — 1.0
a716a7b batch2 数据域 1.0 → 2.0
81cbb19 batch3c 标识码 2.0 → 2.1
41739b4 batch4a 订单六态 2.1 → 2.2
898fced batch4b 交付五态 + 账单异议下线 2.2 → 2.3
41ba4dd 签约期策略冲突 2.3 → 3.0
ac55760 发布载荷 3.0 → 3.1
c4812cf D03 协商增强 3.1 → 3.2

tdc-rs 一直停在 1.0 ⇒ 真 TDS 版本闸门直接 401。已按上游单一常量语义升到 3.2, 移除联调期自创的 SSW_TDS_PROTOCOL_VERSION env(真源无此配置)。

出向端点集合(基线 67 条 → 最新 70 条)

新增 Catalog/Detail/、Contract/Internal/Get/、Contract/Internal/Refuse、 DeliveryTask/Internal/ExecFact(s)、SampleAccess、Internal/PortalAsset; 删除 Contract/Internal/Change、ChangeCancel、Resign、DeliveryTask/Internal/Ready、 disputeBilling。除 Catalog/Detail 外全部落在 tdc-rs 未实现的 40+ 端点范围,见 §5。

1. ✅ 已同步:/Billing/{id}/Dispute 下线

上游批4b(chg_0022 乙案,2026-10-29 定稿)删除路由与 disputeBilling。 已改:tds_biz.rs 删路由 + billing_dispute handler;tds.rs 删 dispute_billing; docs/contract.md 端点表删该行;tests/tds_biz.rs 改用 Voucher 验证越权自检, 并新增「/Dispute 已下线、不得出向」断言。 真 TDS 复验:PUT /Billing/FAKE/Dispute → HTTP 404 {"code":404,"msg":"接口不存在","success":false} ✅

注:刚删路由时曾回 405,根因不在 axum 路由层,而是 platform::static_files::serve 对非 GET 请求一律先回 405 + Allow,截胡了 /api/** 未命中本该返回的 404。 已把 /api 判定前置到静态服务之前,详见 §7。

2. ✅ 已同步:Billing/List 的 side 参数

上游 BillingController.list(connectorId, keyword, side) + listBillingForConnector(cid, keyword, side)(2026-11-04 供方中心 R1)。 已改:入向 query 读 side;出向 body 非空白才带;ownsLedger 保持 side=None(两侧都返)。 真 TDS 复验:side=PROVIDER → 200 真实账本;CONSUMER → 空; side=BOGUS → 400 side 只接受 PROVIDER / CONSUMER,收到: BOGUS (证明字段被对端真实解析,非静默忽略)✅

3. ✅ 已同步:internalCatalog 过滤字段

上游改为 internalCatalog(spaceId, Map filters),控制器 putIfPresent 收 keyword / industry / productType / dataSource / safeLevel / priceMode(2026-11-04)。 已改:service_catalog_list 读 6 键(param() 已 trim + 过滤空白 ≡ putIfPresent); internal_catalog 接受 Option<&Map>,只放非空白值,取消「keyword 恒带键」旧行为。 真 TDS 复验:无参数 → 全量 701 条;keyword=E2E-DNP-b3r3b-a7ty → 1 条; keyword=NOT-EXIST-XYZ → 0 条;6 参数组合 → {"list":[],"total":0} ✅

4. ✅ 已同步(新增):ServiceCatalog/Detail/{productCode}

上游 2026-11-03 数据集语义批新增:入向 GET /Detail/{productCode} → 出向 GET /api/ssw/tds/Catalog/Detail/{code}?spaceId=<本端身份>。 🔴 上游明确 spaceId 只能从本端身份解析,不得接受浏览器指定。 已改:tds.rs 增 catalog_detail(段白名单 + URL 编码、解包型); tds_biz.rs 增 handler + 路由;docs/contract.md 端点表增行;tests/tds_biz.rs 增断言。 端点数:删 Dispute −1、加 Detail +1 ⇒ 仍 10 条 / 总 132 条,check-contract.sh 全绿。 真 TDS 复验:业务编码 E2E-DNP-b3r3b-a7ty → 200 完整详情;主键 → 400「产品不存在或不在本空间目录」 (证明 TDS 按 productCode 查);带 ?spaceId=BOGUS 仍返回正确详情(不信任入参); %2e%2e → 400「产品编码非法: ..」✅

5. 🟢 环境限制(非代码缺陷,仍在)

本地 tdc_identity.f_tds_connector_id 未在 .50 TDS 注册 ⇒ 自动带出的 buyerConnectorId 报「买方连接器不存在」;Confirm / Settle 的严格身份口径因此被拒。 显式传已注册 878443108591731461 后:Buy usageId=产品主键 → 200 生成订单 ✅ 动作:联调时显式传 buyerConnectorId / connectorId,或写本端身份绑定。不改代码。

6. ⚪ 范围决策(需产品确认,仍在)

2d331e9 的 TdsReportClient 有 70 条出向端点(合同 / 交付任务 / 审计 / 主体 / 链证 / 大文件 / 沙箱…), tdc-rs 只实现 10 条(目录·购买·账单)。当前定位是 standalone 子集, 是否扩到全量属范围决策而非 bug,需明确后再排期。

已确认对齐(无需动作)

  • PROTOCOL_VERSION = "3.2":单一常量同时驱动入向闸门与出向头,无 env 覆盖。
  • internalHeaders() 6 个头与 TdsReportClient:2569 逐字一致。
  • internalApply / internalApplyBatch / billingAction / receiptBilling / voucherBilling 路径、方法、体形状在基线→最新期间未变,tdc-rs 无需改。
  • Buy 的 productId 原样透传与上游逐字一致(两仓 productId vs usageId 漂移是 上游对端问题,见项目组 findings 文档,tdc-rs 不自创映射)。
  • 越权自检 ownsLedger、三档降级(NOOP / 不可达 / 业务失败)行为一致。

验证记录(2026-11-05 17:35 复跑)

项 结果
cargo build ✅
cargo test(全量,17 个测试二进制) ✅ 308 passed / 0 failed / 1 ignored
bash scripts/check-contract.sh ✅ 端点表 132 条 ↔ 实际注册路由完全一致
真 TDS 端到端复验 ✅ 见 §1~§4 逐项
verify-upstream-cases.py --with-write ✅ 21 条:19 PASS / 1 FAIL / 1 INFO(唯一 FAIL 为上游字段漂移)

上游用例跨进程验证(2026-11-05 17:35 复跑)

python3 scripts/verify-upstream-cases.py --with-write:21 条上游验收用例 (来源与逐条结果见 docs/UPSTREAM-CASES-VERIFICATION.md) ⇒ 19 PASS / 1 FAIL / 1 INFO(首轮 17:25 为 18/2/1)。 唯一 FAIL 是 U19 = 上游 contacter ↔ buyerContact 字段漂移 (项目组 findings §5ter 发现 5),tdc-rs 按真源原样透传,不自创映射。

✅ 已闭环:U05 下线端点的 404 口径

首轮 U05 期望 404、实得 405。定位到 platform::fallback::spa_fallback:请求先交给 static_files::serve,后者对齐 ServeDir 语义,对非 GET/HEAD 一律先回 405 + Allow ⇒ 把模块首行契约「/api/** 未命中 ⇒ 404 JSON」截胡了。 不是 axum 路由层的 method-not-allowed 回退。

已改:src/platform/fallback.rs 把 /api 命名空间判定前置于静态服务 (与 fallback_response / ddl_guard 同一层 percent-decode 口径);非 /api 路径的 非 GET 仍回 405 + Allow(RFC 9110),未被过度改写。 已补:tests/spa_fallback.rs::api_unmatched_non_get_returns_404_json (PUT/POST/DELETE/PATCH 精确 404 信封 + HEAD 状态码 + 反向锁定 SPA 深链仍 405); tests/tds_biz.rs 的 /Dispute 断言从 assert_ne!(OK) 收紧为 assert_eq!(404)。 复验:真进程 PUT /api/ssw/tdc/Billing/NOT-REAL/Dispute → HTTP 404 {"code":404,"msg":"接口不存在","success":false},U05 PASS ✅

这是修正「本仓既有 404 契约没在非 GET 上落实」,不是为用例自创业务逻辑。

另:chg_0033/C3 的「金额两位小数」是展示层要求,internal API 返数值 0.0, 已按 INFO 记录,不是缺陷。