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

128 lines
8.3 KiB
Markdown
Raw Permalink 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.
# 上游验收用例 · 跨进程验证报告
> 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. 怎么跑
```bash
# 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 数值上),否则自动化测试会出现「实现正确但用例判红」
或「实现漏校验但用例放行」。