43 lines
3.5 KiB
Markdown
43 lines
3.5 KiB
Markdown
# 提示词：TMS V2 对接
|
||
|
||
你只做主账进程内的 TMS 网关与字典投影。智能体通过主账「查价」API 间接触达 TMS。签名、投影、错误分类代码必须有**详细中文注释**（1002/1003/技术失败如何区分）。见 `05`。
|
||
|
||
## 认证
|
||
|
||
1. `client_credentials` 取 `accessToken`（Basic clientId:clientSecret）。
|
||
2. 查询/详情/模板字段：`Authorization: Bearer`。
|
||
3. 空运锁舱/释放：额外 HMAC 签名头，正文原字节参与签名。
|
||
4. 生产明文见 `03`，**新系统直接复用现网 TMS 信息**（同机并行，不再另开测试 TMS）：`TMS_V2_BASE_URL=http://113.106.62.254:3100/sangoe-boot`；ClientId/Secret/SignatureSecret 均为 `WVRELUFpQWdlbnQk`。`YTD_TMS_V2_ENABLED=true`。字典同步 Token 也用 `03` 现网值。凭证放新系统自己的 `.env`，不要改 `C:\yutongda\secure\` 给现网 Java 用的那份。
|
||
|
||
**不要**把密钥写进代码或前端。旧字段 `tmsServiceToken`/`tmsSignatureKey` 不要在 V2 再使用。
|
||
|
||
## 查询请求
|
||
|
||
主账按 TMS V2 `/quote/v2/query` 把空运查价参数带全再出站。智能体必须参数齐全才建单、才出询价卡片。
|
||
|
||
空运出站必带：`requestId`（UUID）、`workOrderNo`（WOYYYYMMDDNNNN）、`transportMode=AIR`、`segments[0]` 的 origin/originCode/destination/destinationCode/cargoName、`quantity`（整数）、`weightKg`/`volumeCbm`（大于 0 的数字）、`packageType`。`quoteDate`（yyyy-MM-dd）仅在销售说了报价日期时带上。缺必带项：补问，不出卡片，不出站。
|
||
|
||
- 海运、陆运：销售未说报价日期则填当天，不补问该字段
|
||
- 空运：销售未说报价日期则不传 `quoteDate`，不填当天。TMS 一次返回各航班日期舱位后由销售点选，选定舱位的航班日期再写回工单报价日期
|
||
- 口语单位在出站前去掉；机场名能对应三字码则带上，销售已写三字码则原样带
|
||
- 空运 `packageType` 必须是 TMS 字典码：1=全部（现网航线常无价）、2=托盘/散货/卡板、3=纸箱/木箱。销售卡片仍写原文；禁止把托盘编成 1
|
||
- 空运增值服务：工单字段 `added_services`。有内容才在 `segments[0].addedServices` 传多项原词（顿号、中英文逗号都拆开，空格不拆）。没填不传该字段，不挡查价。TMS 有报价就回报价，没有就回暂无报价。
|
||
|
||
## 响应
|
||
|
||
规范化 envelope：`code`、`tmsData`、`tmsRequestId`。销售侧只分两路业务结果：
|
||
|
||
- code 1 且有价 → 返回报价
|
||
- 1002 / 无 quoteFound / TMS 说缺项 → **暂无报价**
|
||
- HTTP 5xx/超时/熔断 → 技术失败（不是「暂无报价」）
|
||
|
||
锁舱/释放：空运群内由航线 @ BOT 触发，主账 HMAC 出站 `/air/cabin/lock`、`/air/cabin/release`（入参以 TMS 文档为准；日期用工单报价日期填 `flightDate`）。**测服打开真实出站**；验收期间现网锁舱必须先停，禁止两套同时抢舱。正式现网切流前不要让现网和新系统同时 lock。单测用 stub，禁止单测打真实 TMS。
|
||
|
||
## 观测
|
||
|
||
每次出站记录：耗时、HTTP 状态、业务码、请求摘要（无密钥）、响应摘要。连续失败熔断。字典版本号写入工单 `tmsMappingVersion`。
|
||
|
||
## 测试
|
||
|
||
用 WireMock/本地 stub：token 成功、query 1/1002/1003、签名错误、超时、lock/release 成功与 2006/2009。禁止单测打真实 TMS。联调查价可以打现网 TMS（同一 Client）。测服联调 lock/release 只打测试工单，且现网锁舱已停。不要做 Redis「TMS 测试开关」。无价和技术失败看真实 query 响应或 stub。
|