|
|
# 查价系统 · 宿主 postMessage 对接说明
|
|
|
|
|
|
**版本**：1.1
|
|
|
**更新日期**：2026-07-24
|
|
|
**适用对象**：在 iframe 中嵌入查价页的宿主系统（如 ShipRo / 元子侧适配方）
|
|
|
**嵌入页**：`/embed-demo`（须先按 `嵌入对接文档.md` 完成 API Key 直登）
|
|
|
|
|
|
> 原则：**由查价系统定义「要填什么 / 查完回什么」**；宿主按本协议发 `postMessage` 预填、收结果。字段与程序内部询价结构对齐，宿主无需再猜哪些字段可用。
|
|
|
|
|
|
---
|
|
|
|
|
|
## 0. ShipRo 联调要点（v1.1）
|
|
|
|
|
|
### 0.1 URL 直进 MotherShip 登录后表单（方案 A）
|
|
|
|
|
|
```text
|
|
|
https://if.dev.51track.vip/embed-demo?login_type=api_key&api_key=<Key>&embed=1&module=MS_LOGGED_IN
|
|
|
```
|
|
|
|
|
|
等价：`entry=ms_logged_in`
|
|
|
|
|
|
登录成功后**跳过** MotherShip/Flock 卡片与「免账号/登录后」点选，直接进入「创建新货件」。须该客户已绑定 MotherShip 官网账密，否则停在账密面板。
|
|
|
|
|
|
### 0.2 fill 可晚到 / 可重复 / 先缓存再灌表（方案 B）
|
|
|
|
|
|
- 收到 `chajia:fill` **立刻缓存** `payload.form`（不要求当前已在表单页）。
|
|
|
- 切入 `module` 后，表单挂载时写入 UI；用户在表单页再点「填入数据」会**再次**灌表（`seq` 递增）。
|
|
|
- 先回 `chajia:fill-ack`（`ok: true`，缓存确认）；表单真正写入后再回一次 ack（`ui_applied: true`）。
|
|
|
- **不依赖**宿主必须先等 `chajia:ready`（ready 仍会发，便于时序；晚到 fill 同样有效）。
|
|
|
|
|
|
### 0.3 `MS_LOGGED_IN` 地址可只传整段文本
|
|
|
|
|
|
宿主可不传 `place_id` / `mothership_option_id`。查价页把 `formatted_address` 或 `street` 写入提货/送货**搜索框**；用户须点选联想确认后才能「继续」。`cargo_lines` 写入货物行（inch/lb）；空数组不改货物。
|
|
|
|
|
|
---
|
|
|
|
|
|
## 1. 总览
|
|
|
|
|
|
```text
|
|
|
宿主页面
|
|
|
└─ iframe → .../embed-demo?...&embed=1[&module=MS_LOGGED_IN]
|
|
|
├─ iframe → 宿主：chajia:ready / chajia:fill-ack / chajia:quote-result / chajia:error
|
|
|
└─ 宿主 → iframe：chajia:select-module / chajia:fill / chajia:ping
|
|
|
```
|
|
|
|
|
|
| 方向 | 类型 | 作用 |
|
|
|
|------|------|------|
|
|
|
| iframe→宿主 | `chajia:ready` | 会话就绪（可开始发 fill；非强制前置） |
|
|
|
| 宿主→iframe | `chajia:select-module` | 切入四模块之一 |
|
|
|
| 宿主→iframe | `chajia:fill` | 按模块写入/缓存表单字段（**必带 module**，可重复） |
|
|
|
| 宿主→iframe | `chajia:scroll-quotes` | 请求 iframe 滚到「选择承运商」区（私卡出报价后） |
|
|
|
| iframe→宿主 | `chajia:fill-ack` | 已缓存；表单写入后再带 `ui_applied` |
|
|
|
| iframe→宿主 | `chajia:quote-result` | 查价结束（成功/失败/过期）；**及** MS 侧栏点选承运商时再次推送（带 `selected`） |
|
|
|
| iframe→宿主 | `chajia:quote-save` | 用户点「保存本次询价记录」（可选；写快照） |
|
|
|
| iframe→宿主 | `chajia:scroll-top` | 进入二级详情等：请求宿主把查价 iframe 区域滚到视口顶部 |
|
|
|
| iframe→宿主 | `chajia:error` | 协议层错误（缺 module 等） |
|
|
|
| iframe→宿主 | `chajia:module-changed` | 用户或宿主切换了模块 |
|
|
|
|
|
|
信封统一格式：
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"source": "chajia",
|
|
|
"version": 1,
|
|
|
"type": "chajia:fill",
|
|
|
"request_id": "宿主生成的 UUID，可选，用于配对",
|
|
|
"module": "MS_LOGGED_IN",
|
|
|
"payload": {}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
- **必须**校验 `source === "chajia"` 且 `version === 1`，忽略其它来源。
|
|
|
- `targetOrigin`：生产建议写成查价域名；联调可用 `*`。
|
|
|
- 仅当页面在 **iframe** 中时，查价页才会向 `parent` 回传。
|
|
|
|
|
|
---
|
|
|
|
|
|
## 2. 模块 ID（必须区分）
|
|
|
|
|
|
与 OpenAPI 路线一致，**四选一、互斥**：
|
|
|
|
|
|
| module | 含义 | 门户表现 |
|
|
|
|--------|------|----------|
|
|
|
| `MS_GUEST` | MotherShip 免账号 | MotherShip → 免账号 |
|
|
|
| `MS_LOGGED_IN` | MotherShip 登录后 | MotherShip → 登录后（须已绑官网账密） |
|
|
|
| `FLOCK_GUEST` | Flock 免账号 | Flock → 免账号 |
|
|
|
| `FLOCK_LOGGED_IN` | Flock 登录后 | Flock → 登录后（须已绑官网账密） |
|
|
|
|
|
|
`chajia:fill` **必须**带 `module`。不同模块的 `payload.form` 字段不同，不可混用。
|
|
|
|
|
|
---
|
|
|
|
|
|
## 3. 宿主 → iframe：预填（按模块）
|
|
|
|
|
|
### 3.1 通用写法
|
|
|
|
|
|
```js
|
|
|
iframe.contentWindow.postMessage(
|
|
|
{
|
|
|
source: "chajia",
|
|
|
version: 1,
|
|
|
type: "chajia:fill",
|
|
|
request_id: crypto.randomUUID(),
|
|
|
module: "MS_LOGGED_IN",
|
|
|
payload: {
|
|
|
select_module: true,
|
|
|
form: { /* 见 3.3 */ }
|
|
|
},
|
|
|
},
|
|
|
"https://if.dev.51track.vip",
|
|
|
);
|
|
|
```
|
|
|
|
|
|
也可把 `form` 直接作为 `payload`（无 `select_module` 包装）。
|
|
|
|
|
|
### 3.2 `MS_GUEST`
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"pickup": { "street": "1234 Warehouse Blvd", "city": "Los Angeles", "state": "CA" },
|
|
|
"delivery": { "street": "5678 Distribution Dr", "city": "Dallas", "state": "TX" },
|
|
|
"weight": { "value": 500, "unit": "lb" },
|
|
|
"dimensions": { "length": 48, "width": 40, "height": 48, "unit": "in" },
|
|
|
"pallet_count": 2,
|
|
|
"cargo_type": "general_freight"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### 3.3 `MS_LOGGED_IN`（ShipRo 现网：整段文本 + cargo_lines）
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"pickup_address": {
|
|
|
"street": "整段发货地址原文",
|
|
|
"formatted_address": "整段发货地址原文"
|
|
|
},
|
|
|
"delivery_address": {
|
|
|
"street": "整段目的地址原文",
|
|
|
"formatted_address": "整段目的地址原文"
|
|
|
},
|
|
|
"cargo_lines": [
|
|
|
{
|
|
|
"cargo_type": "pallet",
|
|
|
"quantity": 1,
|
|
|
"weight_lb": 100,
|
|
|
"length_in": 48,
|
|
|
"width_in": 40,
|
|
|
"height_in": 48
|
|
|
}
|
|
|
]
|
|
|
}
|
|
|
```
|
|
|
|
|
|
| 字段 | 说明 |
|
|
|
|------|------|
|
|
|
| 地址 | `formatted_address` 或 `street` → 搜索框；可不传 place_id（用户点选联想） |
|
|
|
| cargo_lines | inch/lb；**空数组不改**货物 |
|
|
|
| ready_* / accessorials | 可选；不传用页默认 |
|
|
|
|
|
|
### 3.4 仅切模块
|
|
|
|
|
|
```json
|
|
|
{ "source": "chajia", "version": 1, "type": "chajia:select-module", "module": "MS_LOGGED_IN" }
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 4. 查价结果
|
|
|
|
|
|
`chajia:quote-result` → `payload.quotes[].carrier` / `final_total`；失败读 `error_message`。
|
|
|
宿主若需明确区分“官网原价”和“客户加价后展示价”，可直接读：
|
|
|
|
|
|
- `base_total_before_markup`：未加价原价
|
|
|
- `customer_markup_amount`：该客户加价金额
|
|
|
- `customer_final_total`：该客户最终展示价（等同当前 `final_total`）
|
|
|
- `is_customer_markup_applied`：是否已叠加客户加价
|
|
|
- `pricing_mode = "customer_final"`：宿主可直接按客户最终价展示
|
|
|
|
|
|
### 4.1 侧栏点选承运商即时同步（宿主锁价）
|
|
|
|
|
|
MotherShip 登录后侧栏（`MS_LOGGED_IN`）：
|
|
|
|
|
|
1. 用户点选任意承运商卡片、默认选中出价、或切换保障导致生效费率变化时
|
|
|
2. iframe 再次发出 **`chajia:quote-result`**（**不依赖**绿色「保存本次询价记录」）
|
|
|
3. `payload.quotes[]` 中当前生效那条 **`selected: true`**，其余 `false`
|
|
|
4. 宿主取 `selected === true` 的档（无则兜底首条）即可锁定承运商与 `final_total` / `customer_final_total`
|
|
|
5. 绿色「保存」仍可选发 `chajia:quote-save`（`action: "save"` + 同样 `selected`），仅用于写快照；私卡询价跳转**不必**等保存
|
|
|
|
|
|
触发时机代码入口：`onSelectQuote` → `notifyHostQuoteSelection` → `reportQuoteResult`。
|
|
|
|
|
|
### 4.2 出报价后视野定位（需求3）
|
|
|
|
|
|
1. **查价页**：报价列表出现后自动 `scrollIntoView` 到侧栏「选择承运商」（`#ms-choose-carrier`）；「已选」角标与承运商名同一行，不遮挡标题
|
|
|
2. **宿主**：收到 `quote-result` 后左侧滚到「当前选中报价」，并可向 iframe 发：
|
|
|
|
|
|
```json
|
|
|
{ "source": "chajia", "version": 1, "type": "chajia:scroll-quotes" }
|
|
|
```
|
|
|
|
|
|
iframe 收到后再次滚承运商区。需查价页与 cc-client **一起部署** 才完整。
|
|
|
|
|
|
### 4.3 「继续」进入二级后置顶
|
|
|
|
|
|
用户在一级点「继续」进入提货/送货详情时：
|
|
|
|
|
|
1. **查价页**：iframe 内 `scrollTo(0)` + 根节点 `scrollIntoView`
|
|
|
2. **同时**向宿主发：
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"source": "chajia",
|
|
|
"version": 1,
|
|
|
"type": "chajia:scroll-top",
|
|
|
"module": "MS_LOGGED_IN",
|
|
|
"payload": { "reason": "logged-in-details" }
|
|
|
}
|
|
|
```
|
|
|
|
|
|
3. **宿主**：收到后将私卡询价弹窗/iframe 容器滚到视口顶部
|
|
|
|
|
|
需查价页与 cc-client 一并更新。
|
|
|
|
|
|
---
|
|
|
|
|
|
## 5. 联调顺序（ShipRo）
|
|
|
|
|
|
1. iframe：`...&embed=1&module=MS_LOGGED_IN`
|
|
|
2. 进「创建新货件」后点「填入数据」→ `chajia:fill`
|
|
|
3. 收 `fill-ack`（缓存）→ 再收 `ui_applied` ack
|
|
|
4. 用户点选地址联想 → 继续 → `chajia:quote-result`（出票）
|
|
|
5. 用户在侧栏点选承运商 → 再收 `chajia:quote-result`（带 `selected`）→ 宿主锁价后可「确认询价并新建集装箱」
|
|
|
|
|
|
亦可打开后立即 fill（先缓存，表单挂载后灌入）。
|
|
|
|
|
|
| 能力 | 状态 |
|
|
|
|------|------|
|
|
|
| URL `module` / `entry` 直进 | 已实现 |
|
|
|
| fill 缓存 + 可重复 + 晚到灌表 | 已实现 |
|
|
|
| MS_LOGGED_IN 搜索框 + cargo_lines | 已实现 |
|
|
|
| MS_GUEST 预填 / quote-result | 已实现 |
|
|
|
| 侧栏点选承运商 → quote-result + selected | 已实现 |
|
|
|
| 出报价后自动滚到「选择承运商」/ scroll-quotes | 已实现 |
|
|
|
| 「继续」进二级 → scroll-top 置顶 | 已实现 |
|
|
|
|
|
|
---
|
|
|
|
|
|
## 6. 文档关系
|
|
|
|
|
|
| 文档 | 用途 |
|
|
|
|------|------|
|
|
|
| `嵌入对接文档.md` | iframe URL、API Key、`module` |
|
|
|
| 本文 | postMessage |
|
|
|
| `api对接文档.md` | OpenAPI |
|
|
|
|
|
|
代码：`lib/embed/host-bridge.ts`、`parseEmbedEntryModule`（`lib/embed/sso-params.ts`）、`map-quotes-selection.ts`、`mothership-logged-in-quote-sidebar` / `embedded-quote-widget`。
|
