wx/hl-api-changelog

派生 0

yaosutu 60350ddecf 推 changelog：订单财务明细查询（优惠/增项清单）接口说明 — #4205 变更预览历史数据源用法

2026-06-22 14:58:50 +08:00

14 KiB

原始文件 Blame 文件历史

订单财务明细查询（优惠/增项清单）— 接口说明 + 变更预览历史数据源用法

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

1. 接口背景

订单增减项弹窗（POST /v3/admin/order/{orderId}/adjustment）需要在打开时先展示该订单的历史增减项明细与合计，让定制师在看到存量数据的前提下再填写本次变更金额。

本接口 GET /v3/admin/order/{orderId}/discount-surcharge/list 承担这一历史数据源角色：

打开弹窗 → 前端调本接口（includeReversed=false）→ 渲染历史明细列表 + 合计
定制师填入本次金额 → 前端用 summary.activeDiscountTotal / activeSurchargeTotal + 本次 amount 实时推算新综合价/应收尾款（本地计算，不调接口）
定制师确认提交 → 调 POST /adjustment → 响应 discountAmountAfter / surchargeAmountAfter 即最新合计，直接刷新 UI，不必重查本接口

与 22_4205_订单增减项改造-新增接口-管理后台.md（写入端 /adjustment）配套阅读，两份合起来构成完整的增减项弹窗对接说明。

2. 变更清单

#	变更类型	接口 / 字段	说明
1	✨ 新增字段	discounts[].itemCode	优惠字典编码（来自 order_discount_item 字典）
2	✨ 新增字段	discounts[].itemName	优惠字典中文名（如：老客户回馈、临时优惠）
3	✨ 新增字段	surcharges[].itemCode	增项字典编码（来自 order_surcharge_item 字典）
4	✨ 新增字段	surcharges[].itemName	增项字典中文名（如：加项景点、用车费用）
5	📝 接口说明	GET /v3/admin/order/{orderId}/discount-surcharge/list	补充变更预览场景下的标准调用方式

本文件重点说明列表查询接口的字段含义与调用场景。写入端（POST /adjustment）见同目录另一份 changelog。

3. 接口详情

项	值
方法	GET
路径	/v3/admin/order/{orderId}/discount-surcharge/list
接口名	查询订单优惠+附加费清单
认证	Bearer JWT（管理后台 token）
幂等性	只读，天然幂等
限流	无特殊限流
Content-Type	无请求体

4. 接口入参

4.1 路径参数

参数	类型	必填	说明
orderId	Long	是	订单 ID（雪花 ID，前端以字符串传输防精度丢失）

4.2 Query 参数

参数	类型	必填	默认值	说明
includeReversed	Boolean	否	true	false=仅返 ACTIVE 有效项；true=含 REVERSED/REVERSAL 历史撤销行。变更预览弹窗固定传 false
category	String	否	ALL	暂未启用，固定传 ALL 或直接不传

5. 出参字段

5.1 顶层结构

字段	类型	说明
orderId	Long	订单 ID
discounts	DiscountVO[]	历史优惠/减项列表（按 created_at 升序）
surcharges	SurchargeVO[]	历史增项/附加费列表（按 created_at 升序）
summary	SummaryVO	聚合统计

5.2 discounts[] 字段（DiscountVO）

字段	类型	说明
id	String	主键（雪花 ID，JSON 序列化为字符串）
discountType	String	优惠类型，固定值 MANUAL
itemCode	String	优惠字典编码（如 LOYAL_CUSTOMER），来自 order_discount_item；存量历史行可能为 null
itemName	String	优惠字典中文名（如老客户回馈）；存量历史行可能为 null，用 discountName 兜底
discountName	String	优惠描述文本
discountAmount	String	金额（元，BigDecimal 序列化为字符串，正数）
sourceType	String	来源类型：MANUAL=手动录入
sourceRefId	Long	来源关联 ID，MANUAL 时为 null
status	String	行状态（ACTIVE / REVERSED / REVERSAL），见 6.1 节
reverseRefId	Long	指向被撤销的原行 ID，仅 REVERSAL 行有值，ACTIVE 时 null
operatorId	Long	操作人 ID
operatorName	String	操作人姓名快照（写入时取，历史不变）
createdAt	String	写入时间（ISO-8601，如 2026-05-10T16:08:32）

5.3 surcharges[] 字段（SurchargeVO）

字段	类型	说明
id	String	主键（字符串序列化）
itemCode	String	增项字典编码（如 EXTRA_ATTRACTION），来自 order_surcharge_item；存量历史行可能为 null
itemName	String	增项字典中文名（如加项景点）；存量历史行可能为 null，用 surchargeName 兜底
surchargeName	String	增项描述文本
surchargeAmount	String	金额（元，String 序列化，正数）
sourceType	String	来源类型：MANUAL=手动 / ITINERARY_EDIT=行程编辑联动
sourceRefId	Long	来源关联 ID（MANUAL 时 null，ITINERARY_EDIT 时为行程编辑记录 ID）
status	String	行状态（ACTIVE / REVERSED / REVERSAL）
reverseRefId	Long	指向被撤销的原行 ID，仅 REVERSAL 行有值
operatorId	Long	操作人 ID
operatorName	String	操作人姓名快照
createdAt	String	写入时间（ISO-8601）

5.4 summary 字段（SummaryVO）

字段	类型	说明
activeDiscountTotal	String	当前生效优惠合计（仅 ACTIVE 行 SUM，String）
activeSurchargeTotal	String	当前生效增项合计（仅 ACTIVE 行 SUM，String）
discountAmountMirror	String	order_main.discount_amount 的镜像值，与 activeDiscountTotal 正常相等，双校验用
surchargeAmountMirror	String	order_main.surcharge_amount 的镜像值

变更预览推算公式（前端本地计算，不调接口）：

新优惠合计 = activeDiscountTotal + 本次 discountAmount（减项为正数）
新增项合计 = activeSurchargeTotal + 本次 surchargeAmount
新综合价   = orderAmount - 新优惠合计 + 新增项合计
应收尾款   = 新综合价 - 已收款（前端自有字段）

必须用 BigNumber / Decimal.js 运算，禁止 JS 原生浮点。

6. 枚举 / 数据字典

6.1 status 枚举（discounts[].status / surcharges[].status）

值	含义	前端渲染建议
ACTIVE	当前有效	正常渲染
REVERSED	已被撤销（原行被抹除）	仅 includeReversed=true 时返回；渲染删除线
REVERSAL	反向冲销行（撤销动作本身）	仅 includeReversed=true 时返回；灰显或隐藏

变更预览弹窗传 includeReversed=false，后端不返 REVERSED/REVERSAL 行，前端无需再过滤。

6.2 sourceType 枚举

值	来源场景
MANUAL	定制师在订单增减项弹窗手动录入
ITINERARY_EDIT	行程编辑模块联动产生的费用增减

6.3 order_discount_item 字典（减项选项）

通过 GET /admin/dict/data/order_discount_item 动态获取；以下为发版参考值。

dictValue（itemCode）	dictLabel（itemName）
LOYAL_CUSTOMER	老客户回馈
PROMO_CODE	优惠码减免
GROUP_DISCOUNT	团体优惠
HOLIDAY_PROMO	节假日促销
REFERRAL	推荐奖励
COMPLAINT_COMP	投诉补偿
MANUAL_ADJUST	临时调价
OTHER_DISCOUNT	其他优惠

6.4 order_surcharge_item 字典（增项选项）

dictValue（itemCode）	dictLabel（itemName）
EXTRA_ATTRACTION	加项景点
VEHICLE_FEE	用车费用
ACCOMMODATION	住宿升级
CATERING	餐饮加项
SERVICE_UPGRADE	服务升级
OTHER_SURCHARGE	其他增项

7. 错误码

错误码	HTTP 状态	含义	前端处理建议
200	200	正常（discounts/surcharges 为空数组也返 200）	渲染空列表
587001	404	订单不存在	关闭弹窗并 toast 订单不存在

8. 示例

8.1 典型成功（弹窗打开，includeReversed=false）

请求：

GET /v3/admin/order/1234567890001/discount-surcharge/list?includeReversed=false
Authorization: Bearer <admin-token>

响应：

{
  "code": 200,
  "data": {
    "orderId": 1234567890001,
    "discounts": [
      {
        "id": "8800001234567",
        "discountType": "MANUAL",
        "itemCode": "LOYAL_CUSTOMER",
        "itemName": "老客户回馈",
        "discountName": "老客户回馈减免 200",
        "discountAmount": "200.00",
        "sourceType": "MANUAL",
        "sourceRefId": null,
        "status": "ACTIVE",
        "reverseRefId": null,
        "operatorId": 30001,
        "operatorName": "李定制师",
        "createdAt": "2026-05-10T16:08:32"
      }
    ],
    "surcharges": [
      {
        "id": "8800009876543",
        "itemCode": "EXTRA_ATTRACTION",
        "itemName": "加项景点",
        "surchargeName": "加项景点：羊卓雍措一日游",
        "surchargeAmount": "240.00",
        "sourceType": "MANUAL",
        "sourceRefId": null,
        "status": "ACTIVE",
        "reverseRefId": null,
        "operatorId": 30001,
        "operatorName": "李定制师",
        "createdAt": "2026-05-10T16:12:10"
      }
    ],
    "summary": {
      "activeDiscountTotal": "200.00",
      "activeSurchargeTotal": "240.00",
      "discountAmountMirror": "200.00",
      "surchargeAmountMirror": "240.00"
    }
  }
}

本次新增减项 100 元时，弹窗变更预览本地推算：

新优惠合计 = 200.00 + 100.00 = 300.00
新增项合计 = 240.00（本次无增项）
新综合价   = orderAmount - 300.00 + 240.00

8.2 边界情况（无历史增减项）

请求：

GET /v3/admin/order/9999999999001/discount-surcharge/list?includeReversed=false

响应：

{
  "code": 200,
  "data": {
    "orderId": 9999999999001,
    "discounts": [],
    "surcharges": [],
    "summary": {
      "activeDiscountTotal": "0.00",
      "activeSurchargeTotal": "0.00",
      "discountAmountMirror": "0.00",
      "surchargeAmountMirror": "0.00"
    }
  }
}

空数组时渲染「暂无历史增减项」；summary 全零，变更预览公式仍正确。

8.3 业务失败（订单不存在）

请求：

GET /v3/admin/order/0000000000001/discount-surcharge/list

响应：

{
  "code": 587001,
  "msg": "订单不存在"
}

9. 业务边界

适用场景

订单增减项弹窗打开时，拉历史明细和合计用于变更预览（传 includeReversed=false）
订单详情页财务明细 Tab 展示完整流水（传 includeReversed=true）

不适用场景

本接口只读；录入新增减项必须调 POST /v3/admin/order/{orderId}/adjustment
不适合用作提交后刷新数据源；POST /adjustment 响应已携带 discountAmountAfter/surchargeAmountAfter，直接用

特殊边界

discountAmountMirror / surchargeAmountMirror 是 order_main 持久列快照；极端并发下与 activeTotal 可能短暂不一致，以 Mirror 值为账面权威
includeReversed=true 时，REVERSED 与 REVERSAL 两种行都返回，前端可按 status 差异渲染（删除线 / 灰色）

10. 修改前后对比

字段级对比

字段	改前	改后	影响
discounts[].itemCode	不存在	新增 String	前端可渲染字典标签 chip
discounts[].itemName	不存在	新增 String	前端直接展示中文名，无需自行查字典
surcharges[].itemCode	不存在	新增 String	同上
surcharges[].itemName	不存在	新增 String	同上

行为级对比

维度	改前	改后
discountName/surchargeName	纯自由文本	由字典 itemName 生成，标准化
变更预览历史合计	无此字段，弹窗无法预算	summary.activeDiscountTotal/activeSurchargeTotal 支撑弹窗实时推算

11. 影响评估 / 回滚

兼容性

discounts[] / surcharges[] 新增 itemCode / itemName 为纯增量字段，不影响已渲染旧字段
存量历史记录 itemCode/itemName 为 null，前端用 discountName/surchargeName 兜底

前端同步上线

变更预览弹窗对接：打开时调本接口（includeReversed=false），拿 summary 用于预览推算
现有财务明细渲染：按需接入 itemCode/itemName，新旧字段共存，可渐进迁移

回滚方案

后端回滚后 itemCode/itemName 不返回，前端渲染降级为 discountName/surchargeName，无破坏
无 DDL 变更，回滚零风险

12. 注意事项

金额全部 String：discountAmount、surchargeAmount、summary 四个合计字段均为字符串。前端必须用 BigNumber/Decimal.js 运算，禁止 JS 原生浮点。
includeReversed 必须显式传 false：变更预览弹窗调用时必须明确传 includeReversed=false，后端默认值为 true，不传则返回撤销历史行，导致合计计算错误。
提交后不必重查本接口：POST /adjustment 成功响应直接携带 discountAmountAfter / surchargeAmountAfter 最新合计，前端用这两个字段刷新 UI，无需再调 list。
itemCode/itemName 存量行为 null：早于本次改造写入的记录 itemCode/itemName 为 null，前端渲染时以 discountName/surchargeName 兜底。
变更预览推算是前端本地计算：不需要向后端预查，直接用 summary + 本次输入金额在前端推算，减少往返。

13. 关联 / 联系人

项	值
Issue	#4205 订单增减项改造
PR（写入端 /adjustment）	#4207 订单增减项改造
配套 changelog（写入端）	changelogs-v2/2026-06/22_4205_订单增减项改造-新增接口-管理后台.md
后端负责人	腰苏图（yaosutu）
Gitea 仓库	https://git.1814.love:8443/wx/HL

14 KiB 原始文件 Blame 文件历史 Unescape Escape