docs: 新增早鸟优惠计划管理 CRUD 接口 changelog（管理后台，PR #4076）

2026-06-20 10:16:55 +08:00 · 2026-06-20 10:16:55 +08:00 · 43d69d38d1
--- a/changelogs-v2/2026-06/20_4076_早鸟优惠计划管理CRUD接口-新增接口-管理后台.md
+++ b/changelogs-v2/2026-06/20_4076_早鸟优惠计划管理CRUD接口-新增接口-管理后台.md
@ -0,0 +1,339 @@
+# 早鸟优惠计划管理 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 |