# 早鸟优惠计划管理 CRUD 接口（管理后台）

- **端类型**：管理后台
- **变更类型**：新增接口
- **日期**：2026-06-20
- **PR**：[#4076](https://git.1814.love:8443/wx/HL/pulls/4076)
- **负责人**：yst（腰苏图）

---

## 接口背景

早鸟优惠（Early Bird Discount）是订单 v3 新增的优惠机制，允许管理员为指定产品配置日期区间 x 人数区间 x 折扣方式三维优惠计划。下单时系统自动匹配最优方案并应用优惠。

本次（PR #4076）新增管理后台侧 CRUD 6 个接口，供管理员对早鸟计划进行增删改查、启停操作。

---

## 变更清单

| # | 方法 | 路径 | 说明 |
|---|------|------|------|
| 1 | GET | /v3/admin/order/early-bird/list | 早鸟计划分页列表 |
| 2 | GET | /v3/admin/order/early-bird/{planId} | 早鸟计划详情 |
| 3 | POST | /v3/admin/order/early-bird | 创建早鸟计划 |
| 4 | PUT | /v3/admin/order/early-bird/{planId} | 修改早鸟计划（不影响已下单订单） |
| 5 | DELETE | /v3/admin/order/early-bird/{planId} | 删除早鸟计划 |
| 6 | PUT | /v3/admin/order/early-bird/{planId}/toggle | 启用 / 禁用早鸟计划 |

全部为新增接口，无前版存量接口被替换。
---

## 接口详情

| 项目 | 说明 |
|------|------|
| **认证** | 需要管理后台 JWT Token（Authorization: Bearer token） |
| **Base URL** | /v3/admin/order/early-bird |
| **幂等性** | POST 创建非幂等（同参数可重复创建多个计划）；PUT 修改按 planId 幂等覆盖 |
| **限流** | 无独立限流规则，走全局网关限流 |
| **内容类型** | 请求体 Content-Type: application/json；GET 请求均为 Query 参数 |

---

## 接口入参

### 4.1 GET /v3/admin/order/early-bird/list — 分页列表

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| pageNo | Integer | 是 | 页码，从 1 开始 |
| pageSize | Integer | 是 | 每页条数，建议 10 / 20 |

### 4.2 GET /v3/admin/order/early-bird/{planId} — 详情

路径参数 planId（Long）：早鸟计划 ID。

### 4.3 POST /v3/admin/order/early-bird — 创建

请求体（EarlyBirdPlanSaveReqVO）：

| 字段 | 类型 | 必填 | 校验规则 | 说明 |
|------|------|------|----------|------|
| planName | String | 是 | NotBlank | 计划名称 |
| remark | String | 否 | 无 | 优惠描述 |
| discountType | String | 否 | 枚举三选一 | 折扣方式，默认 AMOUNT_TOTAL（见枚举节） |
| discountAmount | BigDecimal | 条件必填 | AMOUNT_PER_PERSON 或 AMOUNT_TOTAL 时必填 | 优惠金额（元） |
| discountPercent | BigDecimal | 条件必填 | PERCENT 时必填，值区间 (0, 100) 开区间 | 折扣率，80=8折（非立减百分比） |
| priority | Integer | 否 | >=0，默认 0 | 优先级，同区间多命中时大者优先 |
| minPeople | Integer | 是 | >=1 | 最低适用人数（含） |
| maxPeople | Integer | 否 | >=1 且 >=minPeople | 最高适用人数（含），不填=不限 |
| startDate | LocalDate | 是 | yyyy-MM-dd | 生效开始日期 |
| endDate | LocalDate | 是 | yyyy-MM-dd，需 >=startDate | 生效结束日期 |
| productIds | List<Long> | 否 | 无 | 关联产品 ID 列表，空=不限产品 |
| applicableTravelerTypes | List<String> | 否 | 枚举值见下 | 适用人群 code 列表，空=后端自动填充成人+儿童+小童（排婴儿） |

### 4.4 PUT /v3/admin/order/early-bird/{planId} — 修改

路径参数 planId（Long）。请求体与 4.3 完全一致，全字段覆盖更新。修改不影响已下单订单中已匹配的早鸟优惠。

### 4.5 DELETE /v3/admin/order/early-bird/{planId} — 删除

路径参数 planId（Long）。无请求体。

### 4.6 PUT /v3/admin/order/early-bird/{planId}/toggle — 启用 / 禁用

| 参数 | 类型 | 位置 | 说明 |
|------|------|------|------|
| planId | Long | Path | 早鸟计划 ID |
| enabled | Boolean | Query | true=启用；false=禁用 |

禁用后该计划不再参与下单时自动匹配。
---

## 出参字段

所有接口返回 Result<T> 包装，成功 code=200。列表接口返回 Result<PageResult<EarlyBirdPlanVO>>，创建/详情返回 Result<EarlyBirdPlanVO>，修改/删除/toggle 返回 Result<Void>。

### EarlyBirdPlanVO 字段表

| 字段 | 类型 | 说明 |
|------|------|------|
| planId | Long（字符串序列化） | 计划 ID，雪花 ID，前端用字符串接收防精度丢失 |
| planName | String | 计划名称 |
| remark | String | 优惠描述，可为 null |
| discountType | String | 折扣方式枚举 code |
| discountAmount | BigDecimal | 优惠金额，PERCENT 类型时为 null |
| discountPercent | BigDecimal | 折扣率（0~100），非 PERCENT 时为 null；80=8折 |
| priority | Integer | 优先级 |
| minPeople | Integer | 最低适用人数（含） |
| maxPeople | Integer | 最高适用人数（含），null=不限 |
| peopleRangeText | String | 后端拼好的人数区间文案，如 3-5 人 / 3 人及以上 |
| discountText | String | 后端拼好的折扣说明，如 每人立减 100 元 / 整单立减 500 元 / 8 折优惠 |
| startDate | LocalDate（yyyy-MM-dd） | 生效开始日期 |
| endDate | LocalDate（yyyy-MM-dd） | 生效结束日期 |
| enabled | Boolean | 是否启用 |
| applicableTravelerTypes | List<String> | 适用人群 code 列表；配置为空时后端回填 [ADULT, CHILD, YOUNG_CHILD] |
| applicableTravelerTypesText | String | 后端拼好的适用人群文案，如 成人/儿童/小童 |
| productIds | List<Long> | 关联产品 ID 列表，空=不限产品 |
| productNames | List<String> | 关联产品名称，下标与 productIds 对齐；产品已删除时填 产品[ID]已删除 |
| products | List<{productId:Long, name:String}> | 关联产品结构化列表 |
| createTime | LocalDateTime | 创建时间 |
| updateTime | LocalDateTime | 最后更新时间 |

---

## 枚举 / 数据字典

### discountType — 折扣方式

| code | 中文 | 计算说明 |
|------|------|----------|
| AMOUNT_PER_PERSON | 每人立减 | 优惠金额 = discountAmount x 计费人数 |
| AMOUNT_TOTAL | 整单立减（默认） | 优惠金额 = discountAmount |
| PERCENT | 按比例打折 | 优惠金额 = 总价 x (100 - discountPercent) / 100 |

discountPercent 语义：值为折扣率，80 表示 8折，不是打 8 折的优惠百分比。立减额 = 总价 x (100 - 80) / 100 = 总价 x 0.2。

### applicableTravelerTypes — 适用人群

| code | 中文 | 人数匹配规则 |
|------|------|------------|
| ADULT | 成人 | 计入人数 |
| CHILD | 儿童 | 计入人数 |
| YOUNG_CHILD | 小童 | 计入人数 |
| BABY | 婴儿 | 默认不计入人数，需显式配置才计入 |

人数匹配口径：命中方案的 applicableTravelerTypes 中包含哪几类，就统计哪几类的人数判断是否满足 minPeople/maxPeople 区间。默认配置排除婴儿。

---

## 错误码

早鸟模块错误码段位：581600 – 581699

| 错误码 | 说明 | 触发场景 |
|--------|------|----------|
| 581600 | 早鸟计划不存在 | planId 查不到对应记录 |
| 581601 | 早鸟计划已禁用 | 对已禁用计划执行不允许操作 |
| 581602 | 当前日期不在有效期内 | 当前日期早于 startDate 或晚于 endDate |
| 581603 | 人数不满足最低人数要求（{0}） | 计费人数 < minPeople，{0} 为最低人数阈值 |
| 581604 | 人数超过最高人数限制（{0}） | 计费人数 > maxPeople，{0} 为最高人数阈值 |
| 581605 | PERCENT 时折扣率不能为空 | discountType=PERCENT 但 discountPercent 未传 |
| 581606 | {0} 类型时优惠金额不能为空 | 立减类型但 discountAmount 未传，{0} 为类型名 |
| 581607 | 最高人数不能小于最低人数 | maxPeople < minPeople |
| 581608 | 结束日期不能早于开始日期 | endDate < startDate |
| 581609 | 适用人群包含非法取值：{0} | applicableTravelerTypes 有不在枚举范围的 code |
| 581610 | 产品已存在生效时间与人数区间重叠的早鸟计划，不能重复创建或启用 | 同产品同时间段同人数区间已有启用计划 |
---

## 示例

### 8.1 典型成功 — 创建早鸟计划（整单立减）

POST /v3/admin/order/early-bird，Content-Type: application/json

请求体：

    {
      "planName": "暑期早鸟立减300",
      "remark": "7月出发整单立减300元",
      "discountType": "AMOUNT_TOTAL",
      "discountAmount": 300,
      "priority": 10,
      "minPeople": 2,
      "maxPeople": 6,
      "startDate": "2026-07-01",
      "endDate": "2026-07-31",
      "productIds": [1900000000001, 1900000000002],
      "applicableTravelerTypes": ["ADULT", "CHILD", "YOUNG_CHILD"]
    }

响应：

    {
      "code": 200,
      "msg": "success",
      "data": {
        "planId": "1920000000001234",
        "planName": "暑期早鸟立减300",
        "remark": "7月出发整单立减300元",
        "discountType": "AMOUNT_TOTAL",
        "discountAmount": 300.00,
        "discountPercent": null,
        "priority": 10,
        "minPeople": 2,
        "maxPeople": 6,
        "peopleRangeText": "2-6 人",
        "discountText": "整单立减 300 元",
        "startDate": "2026-07-01",
        "endDate": "2026-07-31",
        "enabled": true,
        "applicableTravelerTypes": ["ADULT", "CHILD", "YOUNG_CHILD"],
        "applicableTravelerTypesText": "成人/儿童/小童",
        "productIds": [1900000000001, 1900000000002],
        "productNames": ["云南大理亲子7日游", "丽江雪山5日徒步"],
        "products": [
          {"productId": 1900000000001, "name": "云南大理亲子7日游"},
          {"productId": 1900000000002, "name": "丽江雪山5日徒步"}
        ],
        "createTime": "2026-06-20T10:00:00",
        "updateTime": "2026-06-20T10:00:00"
      }
    }

### 8.2 边界情况 — 折扣率类计划（不限人数、不限产品）

maxPeople 不传=不限；productIds 不传=不限产品；applicableTravelerTypes 不传=后端回填默认值。

请求体：

    {
      "planName": "年底全产品9折",
      "discountType": "PERCENT",
      "discountPercent": 90,
      "minPeople": 1,
      "startDate": "2026-12-01",
      "endDate": "2026-12-31"
    }

响应：

    {
      "code": 200,
      "msg": "success",
      "data": {
        "planId": "1920000000001235",
        "planName": "年底全产品9折",
        "remark": null,
        "discountType": "PERCENT",
        "discountAmount": null,
        "discountPercent": 90.00,
        "priority": 0,
        "minPeople": 1,
        "maxPeople": null,
        "peopleRangeText": "1 人及以上",
        "discountText": "9 折优惠",
        "startDate": "2026-12-01",
        "endDate": "2026-12-31",
        "enabled": true,
        "applicableTravelerTypes": ["ADULT", "CHILD", "YOUNG_CHILD"],
        "applicableTravelerTypesText": "成人/儿童/小童",
        "productIds": [],
        "productNames": [],
        "products": [],
        "createTime": "2026-06-20T11:00:00",
        "updateTime": "2026-06-20T11:00:00"
      }
    }

### 8.3 业务失败 — 产品时间区间人数区间重叠（581610）

该产品+时间段+人数区间已有另一启用计划。请求体：

    {
      "planName": "冲突测试计划",
      "discountType": "AMOUNT_TOTAL",
      "discountAmount": 100,
      "minPeople": 2,
      "maxPeople": 5,
      "startDate": "2026-07-01",
      "endDate": "2026-07-15",
      "productIds": [1900000000001]
    }

响应：

    {
      "code": 581610,
      "msg": "产品已存在生效时间与人数区间重叠的早鸟计划，不能重复创建或启用",
      "data": null
    }
---

## 业务边界

**适用场景**：管理员新建/修改/删除早鸟优惠配置；对已有计划快速启停；查询当前所有早鸟计划状态。

**不适用场景**：小程序用户侧查看早鸟优惠（走 internal Feign 接口）；下单时自动匹配优惠（订单服务内部逻辑，前端无需干预）；修改不追溯已下单订单中已应用的优惠金额。

**特殊边界**：

- 同一产品在同一时间段+人数区间内只允许存在一个启用状态的计划（581610）；禁用状态不参与冲突检测
- discountPercent=80 表示 8折，不是优惠 80%；前端展示需转换为 X折格式
- planId 为雪花 ID，JSON 已序列化为字符串，前端用字符串类型接收
- applicableTravelerTypes 传空或不传，后端自动填充默认值 [ADULT, CHILD, YOUNG_CHILD] 并持久化

---

## 修改前后对比

新增接口，无前版对比。

---

## 影响评估 / 回滚

新增接口，不影响存量功能，无需回滚策略。如需下线，在网关层屏蔽 /v3/admin/order/early-bird 前缀即可。

---

## 注意事项

1. discountPercent 语义陷阱：80=8折，不是立减 80%。前端展示请转换为 X折，勿直接显示 80%。
2. planId 雪花 ID 序列化：响应中已序列化为字符串；调用修改/删除/toggle 时路径参数直接传字符串即可。
3. applicableTravelerTypes 回填：创建时不传或传空，后端自动填充默认值并持久化；详情/列表返回实际存储值（不再是空数组）。
4. toggle 启用触发重叠校验（581610）：将已禁用计划重新启用时，若同时间+人数区间已有其他启用计划，会拒绝启用。
5. PUT 修改是全字段覆盖，不支持 PATCH 语义，未传的选填字段会被重置为 null/默认值。
6. productNames/products 降级：关联产品已删除时，productNames 对应位置返回 产品[ID]已删除，前端按需降级处理。

---

## 关联 / 联系人

| 项目 | 内容 |
|------|------|
| PR | [#4076 早鸟优惠管理后台 CRUD](https://git.1814.love:8443/wx/HL/pulls/4076) |
| 后端负责人 | yst（腰苏图） |
| 变更服务 | hl-order-service-v3 |