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>
122 lines
3.7 KiB
Markdown
122 lines
3.7 KiB
Markdown
<!-- 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），只能选一个。
|