wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态

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

浏览代码
这个提交包含在：
yaosutu 2026-06-22 14:58:39 +08:00
父节点 70f9e64dcb
当前提交 60350ddecf
共有 1 个文件被更改，包括 387 次插入 和 0 次删除
显示统计 下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件

387
changelogs-v2/2026-06/22_4205_订单财务明细查询-接口说明-管理后台.md 普通文件
查看文件

@ -0,0 +1,387 @@
# 订单财务明细查询（优惠/增项清单）— 接口说明 + 变更预览历史数据源用法
- **日期**: 2026-06-22
- **端类型**: 管理后台
- **服务**: hl-order-service-v3（端口 8086）
- **接口路径前缀**: /v3/admin/order
- **Issue**: [#4205](https://git.1814.love:8443/wx/HL/issues/4205)
- **PR**: [#4207](https://git.1814.love:8443/wx/HL/pulls/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>
```
响应：
```json
{
"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
```
响应：
```json
{
"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
```
响应：
```json
{
"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. 注意事项
1. **金额全部 String**：discountAmount、surchargeAmount、summary 四个合计字段均为字符串。前端必须用 BigNumber/Decimal.js 运算，禁止 JS 原生浮点。
2. **includeReversed 必须显式传 false**：变更预览弹窗调用时必须明确传 includeReversed=false，后端默认值为 true，不传则返回撤销历史行，导致合计计算错误。
3. **提交后不必重查本接口**：POST /adjustment 成功响应直接携带 discountAmountAfter / surchargeAmountAfter 最新合计，前端用这两个字段刷新 UI，无需再调 list。
4. **itemCode/itemName 存量行为 null**：早于本次改造写入的记录 itemCode/itemName 为 null，前端渲染时以 discountName/surchargeName 兜底。
5. **变更预览推算是前端本地计算**：不需要向后端预查，直接用 summary + 本次输入金额在前端推算，减少往返。
---
## 13. 关联 / 联系人
| 项 | 值 |
|---|---|
| Issue | [#4205 订单增减项改造](https://git.1814.love:8443/wx/HL/issues/4205) |
| PR（写入端 /adjustment） | [#4207 订单增减项改造](https://git.1814.love:8443/wx/HL/pulls/4207) |
| 配套 changelog（写入端） | changelogs-v2/2026-06/22_4205_订单增减项改造-新增接口-管理后台.md |
| 后端负责人 | 腰苏图（yaosutu） |
| Gitea 仓库 | https://git.1814.love:8443/wx/HL |