<!-- mipuyun-api-doc: ancillary-product -->
# AncillaryProduct（辅营产品）

## 数据结构总览

辅营产品采用三级嵌套结构：

```
AncillaryGroup（分组层）
  └─ AncillaryCategory（类别层）
       └─ BaggageOption（选项层）
```

---

## AncillaryGroup（分组层）

按 **航程方向 + 运价家族** 分组的最外层容器。

| 字段名 | 类型 | 示例值 | 说明 |
|--------|------|--------|------|
| currency | String | "CAD" | 售价币种（ISO 4217） |
| fareFamilyType | String | "BASIC" | 运价家族类型，如 `BASIC`、`SMART`、`PROMO` |
| journeyDirection | String | "outbound" | 航程方向：`outbound`（去程）/ `inbound`（回程） |
| categoryList | Array\<AncillaryCategory\> | - | 辅营类别列表 |

---

## AncillaryCategory（类别层）

按行李类别分组，携带定价模式和购买限制。

| 字段名 | 类型 | 示例值 | 说明 |
|--------|------|--------|------|
| categoryCode | String | "StandardCheckedBaggage" | 类别代码，见下方 categoryCode 说明 |
| maxPieces | String | "5" | 该类别最多可购买件数 |
| pricingMode | String | "STEP" | 定价模式：`FLAT` / `STEP` / `TIERED`，见下方说明 |
| categoryDetail | Array\<BaggageOption\> | - | 该类别下的选项列表 |

### categoryCode 说明

| categoryCode | 说明 |
|--------------|------|
| CabinBaggageOverheadLocker | 手提行李（头顶行李架） |
| CabinBaggageUnderSeat | 手提行李（座椅下） |
| StandardCheckedBaggage | 托运行李 |

### pricingMode 说明

| pricingMode | 说明 |
|-------------|------|
| FLAT | 固定单价，每件为独立产品，pieceNo 固定为 1 |
| STEP | 逐件定价，pieceNo 表示第 N 件，同 pieceNo 可有多个重量选项 |
| TIERED | 按总重量档位选择，不计件，pieceNo 固定为 1 |

---

## BaggageOption（选项层）

具体的行李规格和价格。

| 字段名 | 类型 | 示例值 | 说明 |
|--------|------|--------|------|
| pieceNo | Integer | 1 | 第 N 件。STEP 模式下为序号（1, 2, 3...），FLAT/TIERED 模式下为 1 |
| weight | BigDecimal | 23 | 行李额重量（KG） |
| size | String | "55x40x23cm" | 尺寸限制，空字符串表示无特殊限制 |
| price | BigDecimal | 64.00 | 该选项/该件价格 |
| maxPieces | Integer | 1 | 该选项可购买数量 |

---

## 响应示例

### STEP 模式示例

```json
{
  "currency": "CAD",
  "fareFamilyType": "BASIC",
  "journeyDirection": "outbound",
  "categoryList": [
    {
      "categoryCode": "StandardCheckedBaggage",
      "maxPieces": "5",
      "pricingMode": "STEP",
      "categoryDetail": [
        { "pieceNo": 1, "weight": 10, "size": "", "price": 39.00, "maxPieces": 1 },
        { "pieceNo": 1, "weight": 23, "size": "", "price": 64.00, "maxPieces": 1 },
        { "pieceNo": 2, "weight": 23, "size": "", "price": 64.00, "maxPieces": 1 },
        { "pieceNo": 3, "weight": 23, "size": "", "price": 99.00, "maxPieces": 1 }
      ]
    }
  ]
}
```

> **STEP 模式解读**：第 1 件可选 10kg（$39）或 23kg（$64），第 2 件 23kg（$64），第 3 件 23kg（$99）。

### TIERED 模式示例

```json
{
  "currency": "CNY",
  "fareFamilyType": "ECONOMY",
  "journeyDirection": "outbound",
  "categoryList": [
    {
      "categoryCode": "StandardCheckedBaggage",
      "maxPieces": "1",
      "pricingMode": "TIERED",
      "categoryDetail": [
        { "pieceNo": 1, "weight": 20, "size": "", "price": 300.00, "maxPieces": 1 },
        { "pieceNo": 1, "weight": 25, "size": "", "price": 500.00, "maxPieces": 1 },
        { "pieceNo": 1, "weight": 30, "size": "", "price": 800.00, "maxPieces": 1 }
      ]
    }
  ]
}
```

> **TIERED 模式解读**：按重量档位互斥选择，20kg（¥300）、25kg（¥500）或 30kg（¥800），只能选一个。