Files
tdc-rs/docs/UPSTREAM-CASES-VERIFICATION.md
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.3 KiB
Raw Permalink Blame History

上游验收用例 · 跨进程验证报告

2026-11-05 | tdc-rs(Rust)↔ 测试环境 TDS http://192.168.1.50:33000 真源:ssw-tdc 3d247df(.50 部署对应)/ 最新 main 2d331e9;ssw-tds 0b37733

1. 用例从哪来

两仓没有可直接执行的 HTTP E2E 脚本(docs/e2e/cases/TC-DOM4-*.mjs 在集成仓,不在本仓), 验收用例以人读 Given/When/Then 写在 OpenSpec 变更里:

仓 用例文件 挑用的条目
ssw-tdc openspec/changes/chg_0017_drop-demand-in-portal/testcases.md 「必须带内部凭证」
ssw-tdc chg_0020_batch3-identity-domain/testcases.md C5 connectorId 传播
ssw-tdc chg_0022_batch4b_delivery_billing/testcases.md C5 账单无异议(要求 404)
ssw-tds chg_0032_batch4-trade-domain/testcases.md C4 超长联系人拒 / C5 用途非空
ssw-tds chg_0033_batch4b_delivery_billing/testcases.md C3 账单字段 / C4 异议与修正端点下线
ssw-tds chg_0034_crypto-compliance/testcases.md C18 协议版本兼容窗口
ssw-tds chg_0036_batch5-portal-record-domain/testcases.md C1 详情字段 / C2 门户边界

补充:tdc-rs 自带的 scripts/upstream-test-ledger.tsv 是上游 Java 单测的移植台账 (静态尺子,只管「搬没搬」),不是跨进程验收用例,与本报告不冲突。

2. 怎么跑

# TDS internal token 是部署级私有值,只从环境变量读、不入库;未设置时脚本直接退出并提示
export TDS_INTERNAL_TOKEN='<部署方令牌>'
# 只读用例(无副作用)
python3 scripts/verify-upstream-cases.py
# 完整(含下单类,会真出订单)
python3 scripts/verify-upstream-cases.py --with-write

脚本内临时启动 tdc-connector(默认 127.0.0.1:30412),跑完无论成功失败都回收进程, 不留后台服务;显式禁用代理(本机 HTTP_PROXY 会劫持 loopback/内网)。 结构化结果写 /tmp/upstream_cases_result.json。 测试数据动态取(目录第一个产品的 id / productId、账本列表),不硬编码。

总计 21 条:PASS 19 / FAIL 1 / INFO 1。(2026-11-05 17:35 修复 404 口径后复跑;首轮为 18/2/1)

3. 用例与结果

# 上游来源 期望 实际 判定
U01 tdc chg_0017 不带 X-Internal-Token ⇒ 401 401 内部接口凭证无效 PASS
U02 tds C18 声明 3.1(同 major)⇒ 放行 200 code=200 真实目录 PASS
U03 tds C18 声明 2.0(跨 major)⇒ 拒 401 跨端协议版本不兼容(对端 2.0,本端 3.2) PASS
U04 tds C18(tdc-rs 入向面) 声明 1.0 ⇒ 拒 401 跨端协议版本不兼容 PASS
U05 tdc C5 PUT /Billing/{id}/Dispute ⇒ 404 404 接口不存在(17:35 复跑) PASS
U06 tds C4 TDS PUT .../Dispute ⇒ 404/未注册 HTTP 200 + code 600 Login expired PASS*
U07 tds C4 TDS POST .../Correction ⇒ 404/未注册 HTTP 200 + code 600 Login expired PASS*
U08 tds C5 前置 目录返回真实产品 702 个产品,含 id/productId PASS
U09 上游最新 internalCatalog keyword 精确过滤 命中 1 条 PASS
U10 tds C1 GET /Detail/{productCode} ⇒ 200 200 完整详情 PASS
U11 tds C2 详情不含 classifyLevel 未出现 PASS
U12 tdc 段白名单 %2e%2e 非法段被拒 code 400 产品编码非法: .. PASS
U13 上游 side 枚举 side=BOGUS ⇒ 400 400 side 只接受 PROVIDER / CONSUMER PASS
U14 tds C3 side=PROVIDER 返回本方账本 30 条账本 PASS
U15 tds C3 账期 YYYY-MM / 两位状态码 / 金额两位小数 账期 2026-11✓、状态 01✓、金额 0.0(数值,非展示串) INFO
U16 ssw-tdc ownsLedger 非本方账本 fail-closed code 400(身份解析阶段即拒,未出向) PASS
U17 本次 findings 对照 透传 productId ⇒ 数据产品不存在: null 复现 PASS
U18 tds C5 usageId=主键 + purpose ⇒ 200 出单 200 出单 PASS
U19 tds C4 contacter > 10 字符 ⇒ 下单被拒 code 200 直接出单 FAIL
U20 tdc C5 自动补 buyerConnectorId 400 买方连接器不存在(本端身份未在 .50 注册) PASS
U21 tds C4 复核 buyerContact > 10 字符 ⇒ 拒 400 联系人不得超过 10 个字符(contacter C..10) PASS

* U06/U07 按「端点不可用」判定:TDS 源码里 Dispute/Correction 路由确实已删, 未注册路径被登录闸门拦成 HTTP 200 + code 600。语义等价但状态码不是用例写的 404, 见 §4.3。

4. 偏差项分析

4.1 U19(新发现 · 高价值):internal 通道联系人字段名漂移

  • ssw-tds TradeOrderEntity:66-68 把属性 buyerContact 用 @JsonProperty("contacter") 暴露给对外 API;
  • 但 internal 下单走 TradeOrderServiceImpl.buy(Map body, true),L155 直接 order.setBuyerContact(str(body.get("buyerContact"))) —— 只认 buyerContact,不认 contacter;
  • 于是上游用例 chg_0032/C4(按对外字段写 contacter 超 10 字符)经连接器 internal 通道下发时 校验完全不触发,超长联系人静默出单;改传 buyerContact 才被 L159-160 拦下(U21)。

这与已登记的 Buy productId ↔ usageId 漂移是同一类根因: 实体对外 JSON 名与 internal Map 键名没有统一映射,两侧各写各的。 建议项目组一并收敛(统一键名,或在 internal 入口做一次显式字段归一)。

4.2 U05:端点下线的状态码口径(tdc-rs 侧已修复,转 PASS)

chg_0022/C5 与 chg_0033/C4 都要求下线端点返回 404。首轮 tdc-rs 返回 405 + code:405 方法不被允许。根因不在 axum 路由层:platform::fallback::spa_fallback 把请求先交给静态服务,而静态服务对齐 ServeDir,对非 GET/HEAD 一律先回 405 + Allow, 截胡了本仓既有契约「/api/** 未命中 ⇒ 404 JSON」。

已把 /api 命名空间判定前置到静态服务之前(非 /api 路径的非 GET 仍保持 405 + Allow), 并补 tests/spa_fallback.rs 精确 404 断言、收紧 tests/tds_biz.rs 的 /Dispute 断言。 17:35 真进程复跑:HTTP 404 {"code":404,"msg":"接口不存在","success":false} ⇒ U05 PASS。

剩余口径差只在 .50 TDS 侧(U06/U07 返回 HTTP 200 + code 600,见 §4.3), 建议项目组用例把「端点不可用」判成 404 / 405 / 业务码 600 之一,或由平台侧 让未注册 internal 路径直接 404。

4.3 U06/U07:用例期望与 .50 部署口径

未注册 internal 路径在 .50 返回 HTTP 200 + code 600 Login expired,不是 404。 这是平台鉴权过滤器的表现,非 tdc-rs 问题;但用例若只判 HTTP 状态码会误判。 建议用例改为判「端点不可用」(404/405,或业务码 600)。

4.4 U15:展示层 vs API 数值

C3 的「金额两位小数」是页面展示要求;internal 账本 API 返回 JSON 数值 0.0。 账期 ^\d{4}-\d{2}$、状态码 01` 两位码均已实测符合。此项记为 INFO,不是缺陷。

4.5 环境限制(非代码问题)

本端 f_tds_connector_id 未在 .50 TDS 注册 ⇒ 自动补的 buyerConnectorId 报 「买方连接器不存在」,Confirm/Settle 的严格身份口径也在解析阶段被拒(U16、U20)。 用例里凡需已注册身份的,均显式传 878443108591731461。

5. 结论

  • tdc-rs 与真 TDS 的 3.2 internal 通道全线可用:鉴权闸门、版本兼容窗口、目录/详情/过滤、 账本查询与 side 枚举、越权 fail-closed、下单链路均按上游行为落地。
  • 19/21 通过;U05(下线端点状态码)已由 tdc-rs 修复并复验转 PASS。 唯一 FAIL 是 U19 上游 internal 字段漂移;按「严格按真源、不自创映射」的约束 不在 tdc-rs 侧修,已并入给项目组的 findings 请其裁定。
  • 上游用例仍有 3 处口径需要收敛(contacter 字段名、下线端点的 404 断言在 .50 上不成立、 金额展示格式套到 API 数值上),否则自动化测试会出现「实现正确但用例判红」 或「实现漏校验但用例放行」。