b450b512a2
- 添加 mipu-api 作为 git submodule (Claude Code Skill) - 迁移 API 文档源文件到 docs/ 目录统一维护 - 添加 Gitea Actions 工作流：tag推送自动打包docs并发布Release - Skill 运行时自动从 mipu-open Release 下载最新文档 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
175 lines
9.1 KiB
Markdown
175 lines
9.1 KiB
Markdown
<!-- mipuyun-api-doc: ancillary -->
|
||
# Ancillary
|
||
|
||
# Ancillary 实体定义
|
||
|
||
## 重要约定
|
||
|
||
| **字段名** | **数据类型** | **示例值** | **说明** |
|
||
|------------------| --- | --- |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||
| journeyDirection | String | outbound | **行程方向**：- outbound: 去程- inbound: 回程<br>**用途**：区分往返行程的去程和回程方向 |
|
||
| categoryCode | String | StandardCheckedBaggage | 值举例：<BR> - 托运行李：StandardCheckedBaggage <BR> - 随身行李：CabinBaggageOverheadLocker <BR> - 选座产品：Seat |
|
||
| productCode | String | SCI_BAG_20KG | 值举例：<BR> - 托运行李：SCI_BAG_20KG <BR> - 随身行李：CBOL_BAG_15KG <BR> - 选座产品：SEAT_16A |
|
||
| price | Number | 21.22 | 预计采购价格，选填 |
|
||
| currency | String | USD | 预计采购价对应的货币，选填 |
|
||
| baggage | Object | {"piece":0,"weight":20,"size":"","allWeight":true} | 行李附加信息：仅当行李类产品时非空，描述行李的重量、件数等属性 |
|
||
| ├─ piece | Integer | 1 | 行李最多件数：1：最多限一件2：最多限两件 |
|
||
| ├─ weight | Integer | 20 | 行李总重量限制：单位为公斤（KG），允许的行李总总量。20表示为：20KG |
|
||
| ├─ size | String | "" | 行李尺寸限制：格式为 "长*宽*高"（如 "56*36***23cm"），空字符串表示无特殊尺寸限制（需遵循航司通用规则） |
|
||
| seat | Object | {"segmentIndex":1,"row":"12","column":"A"} | 座位附加信息：仅当`categoryCode=Seat`（座位类产品）时非空，描述座位的位置信息 |
|
||
| ├─ segmentIndex | Integer | 1 | **航段序号**：从 1 开始，在整个行程中连续编号<br>• 单程（OW）：去程从 1 开始<br>• 往返（RT）：去程从 1 开始，**回程 = 去程航段数 + 1**<br>**示例**：<br>- 单程直飞：segmentIndex=1<br>- 单程2段转机：segmentIndex=1, 2<br>- 往返直飞：去程 segmentIndex=1，回程 segmentIndex=2<br>- 往返2段转机：去程 segmentIndex=1,2，回程 segmentIndex=3,4 |
|
||
| ├─ row | String | "12" | 座位行号：标识座位所在的行（如 "12" 表示第12排） |
|
||
| ├─ column | String | "A" | 座位列号：标识座位所在的列（如 "A"、"B"、"C" 等） |
|
||
|
||
# 二、行李与选座的行程处理规则
|
||
|
||
## 1. segmentIndex 的计算规则
|
||
|
||
**重要**：seat 对象中的 `segmentIndex` 在整个行程中**连续编号**，不是每个方向重新从 1 开始。
|
||
|
||
**计算规则：**
|
||
- **单程（OW）**：去程从 1 开始连续编号
|
||
- 直飞：segmentIndex = 1
|
||
- 2段转机：segmentIndex = 1, 2
|
||
- 3段转机：segmentIndex = 1, 2, 3
|
||
|
||
- **往返（RT）**：去程从 1 开始，回程紧接去程的编号
|
||
- 往返直飞：去程 segmentIndex = 1，回程 segmentIndex = 2
|
||
- 去程2段+回程1段：去程 segmentIndex = 1, 2，回程 segmentIndex = 3
|
||
- 去程2段+回程2段：去程 segmentIndex = 1, 2，回程 segmentIndex = 3, 4
|
||
|
||
**计算公式：**
|
||
- 去程第 N 段：segmentIndex = N
|
||
- 回程第 M 段：segmentIndex = 去程航段数 + M
|
||
|
||
## 2. 往返行程的区分
|
||
|
||
往返行程通过 `journeyDirection` 字段来区分：
|
||
- **outbound**：去程
|
||
- **inbound**：回程
|
||
|
||
对于选座产品（`categoryCode=Seat`），每个座位通过 `segmentIndex` 标识其对应的航段。
|
||
|
||
## 3. 行李产品的特殊规则
|
||
|
||
### 转机行程的行李规格要求
|
||
|
||
在单向的转机行程中（即同一个 `journeyDirection` 下有多个航段），行李规格（重量、件数）**必须保持一致**。
|
||
|
||
### 规则说明
|
||
|
||
- 如果去程有3个航段（BOM→SGN→SYD→MEL），整个去程购买的行李规格必须相同
|
||
- 例如：不能第1段购买20KG，第2段购买25KG
|
||
- 必须所有航段都购买20KG，或都购买25KG
|
||
|
||
### 为什么需要相同规格？
|
||
|
||
- 转机时行李会自动转运到下一航段，不需要重新托运
|
||
- 航司系统要求整个行程使用相同的行李规格，以确保行李正常转运
|
||
|
||
### 往返行程的行李
|
||
|
||
- 去程和回程（不同的 `journeyDirection`）可以购买不同规格的行李
|
||
- 例如：去程购买20KG，回程购买25KG是允许的
|
||
|
||
## 4. 选座产品的特殊规则
|
||
|
||
### 每个航段独立选座
|
||
|
||
与行李不同，选座是**每个航段独立进行的**。
|
||
|
||
### 规则说明
|
||
|
||
- 每个航段都需要单独选择座位（通过 seat 对象中的 segmentIndex 区分）
|
||
- 即使是转机行程，不同航段可以选择不同的座位
|
||
- 例如：第1段选 12A，第2段选 15F
|
||
|
||
### 为什么需要独立选座？
|
||
|
||
- 每个航段的航班座位图不同
|
||
- 机型、座位布局可能不同
|
||
- 乘客可能希望在不同航段选择不同位置（如去程靠窗，回程靠过道）
|
||
|
||
### 选座对象中的字段
|
||
|
||
- `segmentIndex`：标识选座对应的航段（seat 专用字段）
|
||
- `row`：座位行号（如 "12"）
|
||
- `column`：座位列号（如 "A"、"F"）
|
||
|
||
**示例 - 转机行程选座：**
|
||
|
||
往返直飞（去程1段+回程1段）：
|
||
```json
|
||
// 去程座位
|
||
{
|
||
"categoryCode": "Seat",
|
||
"productCode": "SEAT_12A",
|
||
"journeyDirection": "outbound",
|
||
"seat": {
|
||
"segmentIndex": 1,
|
||
"row": "12",
|
||
"column": "A"
|
||
}
|
||
}
|
||
// 回程座位
|
||
{
|
||
"categoryCode": "Seat",
|
||
"productCode": "SEAT_8F",
|
||
"journeyDirection": "inbound",
|
||
"seat": {
|
||
"segmentIndex": 2,
|
||
"row": "8",
|
||
"column": "F"
|
||
}
|
||
}
|
||
```
|
||
|
||
往返转机（去程2段+回程2段）：
|
||
```json
|
||
// 去程第1段座位
|
||
{
|
||
"categoryCode": "Seat",
|
||
"productCode": "SEAT_12A",
|
||
"journeyDirection": "outbound",
|
||
"seat": {
|
||
"segmentIndex": 1,
|
||
"row": "12",
|
||
"column": "A"
|
||
}
|
||
}
|
||
// 去程第2段座位
|
||
{
|
||
"categoryCode": "Seat",
|
||
"productCode": "SEAT_15F",
|
||
"journeyDirection": "outbound",
|
||
"seat": {
|
||
"segmentIndex": 2,
|
||
"row": "15",
|
||
"column": "F"
|
||
}
|
||
}
|
||
// 回程第1段座位（segmentIndex = 去程航段数 + 1 = 3）
|
||
{
|
||
"categoryCode": "Seat",
|
||
"productCode": "SEAT_8A",
|
||
"journeyDirection": "inbound",
|
||
"seat": {
|
||
"segmentIndex": 3,
|
||
"row": "8",
|
||
"column": "A"
|
||
}
|
||
}
|
||
// 回程第2段座位（segmentIndex = 去程航段数 + 2 = 4）
|
||
{
|
||
"categoryCode": "Seat",
|
||
"productCode": "SEAT_10F",
|
||
"journeyDirection": "inbound",
|
||
"seat": {
|
||
"segmentIndex": 4,
|
||
"row": "10",
|
||
"column": "F"
|
||
}
|
||
}
|
||
```
|
||
|