# 早鸟优惠: 每个方案可配「适用人群」(成人/儿童/小童/幼童)

> **服务**: hl-order-service-v2 (8084)
> **PR**: #3162 #3169
> **Issue**: #3161 #3166
> **日期**: 2026-05-28
> **影响范围**: 管理端「早鸟方案」编辑页 —— 新增「适用人群」多选;早鸟人数口径变更

---

## ⚠️ 关键变化

- 早鸟方案新增「适用人群」配置(成人 ADULT / 儿童 CHILD / 小童 YOUNG_CHILD / 幼童 BABY)。
- 该配置决定**哪几类出行人计入本方案的早鸟人数**(用于阶梯人数匹配 minPeople/maxPeople)**以及享受每人立减**。
- **默认排除幼童(BABY)**:不填 / 留空时后端默认 `成人+儿童+小童`,存量方案迁移后也是这个默认。
- 不同方案可配不同人群(A 方案只算成人、B 方案算成人+儿童+小童 …),互不影响。
- **前端需在「早鸟方案」新增/编辑表单加一个「适用人群」多选框**(取值用 `traveler_type` 字典:成人/儿童/小童/幼童),不传 = 后端按默认处理。

---

## 一、背景

此前早鸟人数是「全员计入」,后调整为「幼童不参与早鸟」(全局写死)。现进一步升级:**由每个方案自行配置适用人群**,满足不同早鸟活动覆盖不同人群的需要。后端为纯人数口径变更,无金额/字段类型破坏性改动。

---

## 二、变更接口清单

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|------|------|------|----------|------|
| 1 | 新增早鸟方案 | POST | `/admin/order/early-bird` | 请求体新增字段 | `applicableTravelerTypes` |
| 2 | 修改早鸟方案 | PUT | `/admin/order/early-bird/{planId}` | 请求体新增字段 | 同上 |
| 3 | 早鸟方案详情 | GET | `/admin/order/early-bird/{planId}` | 响应新增字段 | 回显 codes + 中文文案 |
| 4 | 早鸟方案列表 | GET | `/admin/order/early-bird` (或 `/list`) | 响应新增字段 | 同上,每条 |

---

## 三、接口详情

### 1/2. 新增 / 修改早鸟方案 `POST|PUT /admin/order/early-bird[/{planId}]`

**VO**: `EarlyBirdPlanSaveReqVO`

#### 入参(仅列新增字段,其余字段不变)

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| applicableTravelerTypes | Body | `string[]` | 否 | 每项 ∈ `ADULT/CHILD/YOUNG_CHILD/BABY` | 适用人群。**空 / 不传 → 默认 `["ADULT","CHILD","YOUNG_CHILD"]`(排除幼童)**。含非法值返回错误码 `585009` |

请求示例:

```json
{
  "planName": "暑期早鸟",
  "discountType": "AMOUNT_PER_PERSON",
  "discountAmount": 100,
  "minPeople": 2,
  "maxPeople": 10,
  "startDate": "2026-06-01",
  "endDate": "2026-08-31",
  "productIds": [123, 456],
  "applicableTravelerTypes": ["ADULT", "CHILD", "YOUNG_CHILD"]
}
```

### 3/4. 早鸟方案详情 / 列表 `GET /admin/order/early-bird[/{planId}]`

**VO**: `EarlyBirdPlanVO`(新增 2 字段)

| 字段 | 类型 | 说明 |
|------|------|------|
| applicableTravelerTypes | `string[]` | 适用人群 code 列表(如 `["ADULT","CHILD","YOUNG_CHILD"]`)。后端保证非空(存量/历史方案回显默认值) |
| applicableTravelerTypesText | `string` | 适用人群中文文案,`/` 分隔(如 `成人/儿童/小童`),可直接展示 |

---

## 四、前端改动建议

1. 「早鸟方案」新增/编辑弹窗加一个「适用人群」多选(checkbox / multi-select),选项取 `traveler_type` 字典(成人 ADULT / 儿童 CHILD / 小童 YOUNG_CHILD / 幼童 BABY)。
2. 默认勾选 `成人 / 儿童 / 小童`(对齐后端默认,排除幼童);允许全不选时不传该字段(后端按默认)。
3. 列表/详情可直接展示 `applicableTravelerTypesText`。
4. 旧前端不传该字段时行为不变(后端默认排除幼童),可分批升级,无强制。

---

## 五、测试服验证(已通过)

经网关 `api.test.1814.love:9443` + 真 admin token 实测:
- 含幼童 `[ADULT,CHILD,YOUNG_CHILD,BABY]` 创建 + 回读持久化 + 文案「成人/儿童/小童/幼童」✓
- 空列表 → 默认 `[ADULT,CHILD,YOUNG_CHILD]` + 「成人/儿童/小童」✓
- 仅 `[ADULT]` → 「成人」✓
- 非法值 `[FOO]` → 错误码 `585009` ✓
