feat(early-bird): 每方案可配适用人群(成人/儿童/小童/幼童) — 前端早鸟方案编辑加多选 (PR #3162/#3169, Closes #3161/#3166)

changelogs/2026-05/28_feat_early_bird_per_plan_applicable_traveler_types.md

@@ -0,0 +1,92 @@
+# 早鸟优惠: 每个方案可配「适用人群」(成人/儿童/小童/幼童)
+
+> **服务**: 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` ✓