wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态
hl-api-changelog/changelogs-v2/2026-06/22_4205_订单增减项改造-新增接口-管理后台.md
yaosutu 0e9a44568f feat: 订单增减项改造 changelog（Issue #4205，PR #4207） 
新增统一端点 POST /v3/admin/order/{orderId}/adjustment + 字典化项目名 + 出参增 itemCode/itemName
2026-06-22 12:40:39 +08:00

12 KiB
原始文件 Blame 文件历史

订单增减项改造 — 新增统一端点 + 出参增 itemCode/itemName

  • 日期: 2026-06-22
  • 端类型: 管理后台
  • 服务: hl-order-service-v3（端口 8086）
  • 接口路径前缀: /v3/admin/order
  • PR: #4207
  • Issue: #4205
  • Commit: 3a3577aa9
  • 后端负责人: 腰苏图（yaosutu）

1. 接口背景

订单详情页原「添加优惠」按鈕，升级为「订单增减项」：既能加优惠（减项）又能加费用（增项）。改造前项目名是自由文本输入；改造后改为数据字典选项，前端渲染 chip 单选。

本次变更要点：

  • 新增 统一端点 POST /v3/admin/order/{orderId}/adjustment，direction 字段区分减项/增项，前端只维护一套提交逻辑
  • 新建 两个数据字典 type（order_discount_item / order_surcharge_item），前端动态拉取渲染
  • 增强 优惠/附加费清单接口出参，discounts[]/surcharges[] 各新增 itemCode + itemName 字段
  • 旧端点 POST /v3/admin/order/{orderId}/discounts 和 /surcharges 已标为 @Deprecated，前端改调 /adjustment；撤销端点不变

2. 变更清单

# 变更类型 接口 / 字段 影响
1 ✨ 新增接口 POST /v3/admin/order/{orderId}/adjustment 统一增减项写入，替代旧两端点
2 ✨ 新增字典 order_discount_item（8 项） 减项/优惠选项，前端动态拉取
3 ✨ 新增字典 order_surcharge_item（6 项） 增项/费用选项，前端动态拉取
4 ✨ 出参新增字段 discounts[].itemCode / discounts[].itemName 优惠/附加费清单接口
5 ✨ 出参新增字段 surcharges[].itemCode / surcharges[].itemName 同上
6 🔧 旧端点废弃 POST /v3/admin/order/{orderId}/discounts @Deprecated，Swagger 隐藏，前端不再调用
7 🔧 旧端点废弃 POST /v3/admin/order/{orderId}/surcharges @Deprecated，Swagger 隐藏，前端不再调用

3. 接口详情

3.1 新增统一增减项端点

项 值
方法 POST
路径 /v3/admin/order/{orderId}/adjustment
接口名 订单增减项（统一端点，按 direction 分流）
认证 Bearer JWT（管理后台 token）
幂等性 有（@Idempotent，同用户同订单重复提交返回首次结果）
并发锁 有（@Lock4j，同订单并发请求串行执行）
Content-Type application/json

3.2 字典查询接口（走 user-service，路径与现有字典接口相同）

方法 路径 说明
GET /admin/dict/data/order_discount_item 获取减项选项列表
GET /admin/dict/data/order_surcharge_item 获取增项选项列表

返回格式示例：

前端渲染 chip 单选，提交时传 value（即 itemCode）。

4. 接口入参

4.1 路径参数

参数 类型 必填 说明
orderId Long 是 订单 ID

4.2 请求体字段（OrderAdjustmentReqVO）

字段 类型 必填 说明 示例
direction String 是 增减方向：REDUCE=减项/优惠，ADD=增项/附加费 "REDUCE"
itemCode String 是 项目代码：REDUCE 时取 order_discount_item 的 value，ADD 时取 order_surcharge_item 的 value "OLD_CUSTOMER"
amount String 是 金额（元），必须 > 0，传字符串防 JS 精度丢失 "200.00"
remark String 否 备注，最多 500 字 "春节活动老客户优惠"

5. 出参字段

5.1 统一端点出参

direction=REDUCE 时返回优惠记录（OrderDiscountRespVO），direction=ADD 时返回附加费记录（OrderSurchargeRespVO）。

direction=REDUCE 出参（优惠记录）

字段 类型 说明 示例
id String 优惠记录主键 "8800001234567"
orderId String 订单 ID "12345678901234"
discountType String 优惠类型（统一端点写入时存 itemCode 值） "OLD_CUSTOMER"
itemCode String 新增 优惠项目 itemCode（字典 order_discount_item value） "OLD_CUSTOMER"
itemName String 新增 优惠项目中文名（字典 label 快照） "老客户回访"
discountName String 优惠描述（与 itemName 相同，为字典中文名快照） "老客户回访"
discountAmount String 优惠金额（元） "200.00"
sourceType String 来源类型（统一端点固定 MANUAL） "MANUAL"
sourceRefId String/null 来源关联 ID null
status String 记录状态（写入后固定 ACTIVE） "ACTIVE"
operatorId String 操作人 ID（JWT 派生） "30001"
operatorName String 操作人姓名快照 "李定制师"
createdAt String 写入时间（ISO 8601） "2026-06-22T16:08:32"
orderDiscountAmountAfter String 写入后订单优惠总额镜像（本订单所有 ACTIVE 优惠合计） "200.00"

direction=ADD 出参（附加费记录）

字段 类型 说明 示例
id String 附加费记录主键 "8800009876543"
orderId String 订单 ID "12345678901234"
itemCode String 新增 增项项目 itemCode（字典 order_surcharge_item value） "ROOM_UPGRADE"
itemName String 新增 增项项目中文名（字典 label 快照） "升级房型"
surchargeName String 附加费描述（与 itemName 相同） "升级房型"
surchargeAmount String 附加费金额（元） "300.00"
sourceType String 来源类型（统一端点固定 MANUAL） "MANUAL"
sourceRefId String/null 来源关联 ID null
status String 记录状态（写入后固定 ACTIVE） "ACTIVE"
operatorId String 操作人 ID "30001"
operatorName String 操作人姓名快照 "李定制师"
createdAt String 写入时间（ISO 8601） "2026-06-22T16:12:00"
orderSurchargeAmountAfter String 写入后订单附加费总额镜像（本订单所有 ACTIVE 附加费合计） "300.00"

5.2 优惠/附加费清单接口新增字段

接口：GET /v3/admin/order/{orderId}/discounts-surcharges（路径不变）

discounts[] 新增字段

字段 类型 说明 历史数据
itemCode String/null 优惠项目 itemCode null（早鸟、行程编辑等历史写入行）
itemName String/null 优惠项目中文名 null（历史行兼容）

surcharges[] 新增字段

字段 类型 说明 历史数据
itemCode String/null 增项项目 itemCode null（历史行兼容）
itemName String/null 增项项目中文名 null（历史行兼容）

历史行（早鸟自动写入、行程编辑产生的记录）itemCode/itemName 返回 null，前端渲染时降级显示 discountName/surchargeName 字段。

6. 枚举 / 数据字典

6.1 AdjustmentDirection 枚举（入参 direction 字段）

值 含义 落库位置
REDUCE 减项/优惠，订单总额减少 order_discount 表
ADD 增项/附加费，订单总额增加 order_surcharge 表

6.2 order_discount_item 字典（dictType=order_discount_item）

减项/优惠选项，前端调 GET /admin/dict/data/order_discount_item 动态渲染。

value（itemCode，提交时传此值） label（展示中文） sort
OLD_CUSTOMER 老客户回访 1
DISTRIBUTION 分销返点 2
PEER_PRICE 同行价 3
FAMILY_PRICE 亲友价 4
COMPLAINT_COMP 投诉补偿 5
FESTIVAL 生日节日 6
GROUPON 团购优惠 7
OTHER 其他 8

6.3 order_surcharge_item 字典（dictType=order_surcharge_item）

增项/费用选项，前端调 GET /admin/dict/data/order_surcharge_item 动态渲染。

value（itemCode，提交时传此值） label（展示中文） sort
ROOM_UPGRADE 升级房型 1
ADD_ENTERTAINMENT 加购娱乐项目 2
ADD_VEHICLE 增加用车 3
EXTRA_PERSON 超员补位 4
ADD_ITINERARY 行程加点 5
OTHER 其他 6

7. 错误码

错误码 含义 触发场景
200 成功 —
581306 ADJUSTMENT_ITEM_INVALID：itemCode 不在对应字典范围内 direction=REDUCE 时 itemCode 不在 order_discount_item；direction=ADD 时 itemCode 不在 order_surcharge_item；或字典服务不可用
400 参数校验失败 direction/itemCode 为空，amount 为空或 ≤ 0，remark 超 500 字
404（内部业务码） 订单不存在 orderId 无对应订单

字典服务（user-service）不可用时，后端降级返回空选项集，任何 itemCode 均触发 581306 拒绝（保守策略）。

8. 示例

8.1 典型成功——减项（老客户优惠 200 元）

请求：

响应：

8.2 典型成功——增项（升级房型 300 元）

请求：

响应：

8.3 业务失败——itemCode 不合法（错误码 581306）

请求：

响应：

"VIP" 是旧端点历史枚举值，不在 order_discount_item 字典，统一端点拒绝。

9. 业务边界

适用：

  • 订单处于任何状态均可操作（无订单状态限制）
  • 一笔订单可叠加多条优惠/附加费记录，每条独立成行

不适用：

  • 旧端点（/discounts、/surcharges）已废弃，前端不应再调用

特殊边界：

  • 减项/增项金额均无上限校验，业务人员自行把握
  • 历史行（早鸟写入、行程编辑产生）itemCode/itemName 返回 null，前端渲染时降级显示 discountName/surchargeName
  • 同一请求遭并发时（@Lock4j），后到的排队等待，不会重复写入

10. 修改前后对比

10.1 写入端点

场景 改造前 改造后
加优惠 POST /{orderId}/discounts，discountName 自由文本 POST /{orderId}/adjustment，direction=REDUCE + itemCode 字典选项
加附加费 POST /{orderId}/surcharges，surchargeName 自由文本 POST /{orderId}/adjustment，direction=ADD + itemCode 字典选项

10.2 出参字段变化（清单接口）

位置 改造前 改造后
discounts[n] 无 itemCode / itemName 字段 新增 itemCode、itemName（统一端点写入时有值，历史行 null）
surcharges[n] 无 itemCode / itemName 字段 新增 itemCode、itemName（同上）

10.3 项目名来源变化

改造前 改造后
discountName/surchargeName 由用户自由输入文本 由 itemCode 查字典 label 后端回填，存入 discountName/surchargeName 快照列

11. 影响评估 / 回滚

前端需同步操作：

  1. 订单增减项弹窗的原因/项目 chips 改为动态调字典接口渲染（/admin/dict/data/order_discount_item 和 order_surcharge_item），不再硬编码
  2. 提交时调 /adjustment，传 direction + itemCode + amount + remark
  3. 清单接口（discounts/surcharges 列表）新增 itemCode/itemName 字段，建议优先显示 itemName，null 时降级显示 discountName/surchargeName

破坏兼容性：旧端点仍保留可调（非破坏性），但 Swagger 已隐藏，前端代码应切换。

上线顺序建议：user-service 须先于或同时于 order-v3 部署（字典须先存在）；建议先上线后端，再上线前端。

回滚方案：

  • 后端：重新部署旧版 hl-order-service-v3 + hl-user-service（旧端点仍在）
  • 前端：切回调旧两端点即可

12. 注意事项

  1. user-service 先行：order-v3 /adjustment 端点运行时调 user-service 拉字典，若字典不存在，任何 itemCode 均触发 581306 拒绝。两服务须同批或 user-service 先上。
  2. itemCode 大小写敏感：传 "OLD_CUSTOMER" 不能传 "old_customer"。
  3. amount 传字符串：防 JS 数值精度丢失，传 "200.00" 而非数字 200.00。
  4. 字典 value 不可随意修改：value 已写入历史快照字段，运营改 value 会导致历史数据 itemCode 无法回查中文名（itemName 返回 null，discountName 仍有值可降级）。
  5. 多条叠加：多次调 /adjustment 每次写一条新记录，清单接口可见全部明细，镜像值为当前全部 ACTIVE 之和。

13. 关联 / 联系人