314 行
12 KiB
Markdown
314 行
12 KiB
Markdown
# 订单增减项改造 — 新增统一端点 + 出参增 itemCode/itemName
|
||
|
||
- **日期**: 2026-06-22
|
||
- **端类型**: 管理后台
|
||
- **服务**: hl-order-service-v3（端口 8086）
|
||
- **接口路径前缀**: /v3/admin/order
|
||
- **PR**: [#4207](https://git.1814.love:8443/wx/HL/pulls/4207)
|
||
- **Issue**: [#4205](https://git.1814.love:8443/wx/HL/issues/4205)
|
||
- **Commit**: [3a3577aa9](https://git.1814.love:8443/wx/HL/commit/3a3577aa9de39857d66c3e1811420ce175956f0a)
|
||
- **后端负责人**: 腰苏图（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. 关联 / 联系人
|
||
|
||
- **Issue**: https://git.1814.love:8443/wx/HL/issues/4205
|
||
- **PR**: https://git.1814.love:8443/wx/HL/pulls/4207
|
||
- **Commit**: https://git.1814.love:8443/wx/HL/commit/3a3577aa9de39857d66c3e1811420ce175956f0a
|
||
- **后端负责人**: 腰苏图（yaosutu）
|