docs(changelog): 打印行程单费用块收敛（Issue #4696，PR #4697）

顶层删 orderAmount/payableTotal/outstandingBalance 移入 feeDetail；feeDetail 补优惠/附加费/已付；报价分价改可空(feeDetail 恒返回)。破坏性，管理后台前端须同步。
2026-07-01 15:10:00 +08:00 · 2026-07-01 15:10:00 +08:00 · 0e32011617
--- a/changelogs-v2/2026-07/04_4696_打印行程单费用块收敛-修改接口-管理后台.md
+++ b/changelogs-v2/2026-07/04_4696_打印行程单费用块收敛-修改接口-管理后台.md
@ -0,0 +1,203 @@
+# 打印行程单费用块收敛（订单金额并入 feeDetail + 补优惠/加费/已付）
+
+**接口路径**：GET /v3/admin/order/{id}/print-itinerary
+**服务**：hl-order-service-v3
+**PR**：[#4697](https://git.1814.love:8443/wx/HL/pulls/4697) ｜ **Issue**：[#4696](https://git.1814.love:8443/wx/HL/issues/4696) ｜ **前序**：[#4692](https://git.1814.love:8443/wx/HL/pulls/4692)（二次调整）/ [#4683](https://git.1814.love:8443/wx/HL/pulls/4683) / [#4650](https://git.1814.love:8443/wx/HL/pulls/4650) ｜ **合并至**：dev-v3
+**变更类型**：修改接口（含破坏性变更）
+
+---
+
+## 1. 接口背景
+
+打印行程单接口第三轮调整：费用字段此前散在两处（顶层 orderAmount/payableTotal/outstandingBalance + feeDetail 报价分价），且缺优惠/附加费/已付。本次把**费用相关全部收进 feeDetail**，并补齐字段。**只改出参，入参不变，零 DDL，无新依赖。**
+
+feeDetail 重构为两部分：
+- **订单财务**（本地数据，恒返回，不受 product-v2 报价 Feign 影响）
+- **报价分价明细**（product-v2 报价，Feign 失败时仅这部分置 null，feeDetail 本身仍返回）
+
+---
+
+## 2. 变更清单
+
+| 类型 | 字段路径 | 变更说明 |
+|------|----------|----------|
+| 删除字段 | `orderAmount`（顶层） | 移入 feeDetail |
+| 删除字段 | `payableTotal`（顶层） | 移入 feeDetail |
+| 删除字段 | `outstandingBalance`（顶层） | 移入 feeDetail |
+| 新增字段 | `feeDetail.orderAmount` | 订单总额（冻结原售价，不含优惠/加费） |
+| 新增字段 | `feeDetail.discountAmount` | 优惠金额（SUM(order_discount) 镜像） |
+| 新增字段 | `feeDetail.surchargeAmount` | 附加费用（SUM(order_surcharge) 镜像） |
+| 新增字段 | `feeDetail.payableTotal` | 订单应收总额（= 原价 − 优惠 + 加费） |
+| 新增字段 | `feeDetail.paidAmount` | 已付金额 |
+| 新增字段 | `feeDetail.outstandingBalance` | 应收尾款（= 应收 − 已付 + 已退） |
+| 行为变更 | `feeDetail`（整体） | 由「Feign 失败整块 null」改为「恒返回」，仅报价分价（items/singleRoomSurcharge/grandTotal）可能 null |
+
+> `orderNo`（订单号）保留在顶层（订单标识，非金额）。`feeDetail.onsiteBalance`（代收）不变。
+
+---
+
+## 3. 接口详情
+
+- 方法：GET ｜ 路径：`/v3/admin/order/{id}/print-itinerary` ｜ 鉴权：管理后台 JWT
+- 响应：`Result<PrintItineraryRespVO>`
+
+---
+
+## 4. 入参
+
+| 位置 | 字段 | 类型 | 必填 | 说明 |
+|------|------|------|:---:|------|
+| Path | `id` | String | 是 | 订单 ID |
+
+本次入参无变化。
+
+---
+
+## 5. 出参
+
+### 5.1 顶层（删除字段）
+
+| 字段 | 变更 |
+|------|------|
+| ~~`orderAmount`~~ / ~~`payableTotal`~~ / ~~`outstandingBalance`~~ | 删除，移入 feeDetail |
+
+> 其余顶层字段（agencyName / orderNo / teamNo / productName / departDate / returnDate / paxSummary / 人员 / consultantName）不变。
+
+### 5.2 feeDetail（03 费用明细，重构后全平铺）
+
+| 字段 | 类型 | 说明 | 降级 |
+|------|------|------|------|
+| `orderAmount` | BigDecimal(String) | 订单总额（冻结原售价，不含优惠/加费） | 恒返回 |
+| `discountAmount` | BigDecimal(String) | 优惠金额（order_main 镜像；无则 0/null） | 恒返回 |
+| `surchargeAmount` | BigDecimal(String) | 附加费用（order_main 镜像；无则 0/null） | 恒返回 |
+| `payableTotal` | BigDecimal(String) | 订单应收总额（= 原价 − 优惠 + 加费；取消单为 0） | 恒返回 |
+| `paidAmount` | BigDecimal(String) | 已付金额 | 恒返回 |
+| `outstandingBalance` | BigDecimal(String) | 应收尾款（= 应收 − 已付 + 已退） | 恒返回 |
+| `onsiteBalance` | BigDecimal(String) | 代收款（现场实收尾款；null=未录入） | 恒返回 |
+| `items` | List\<FeeLineItemVO\> | 报价行项（成人/儿童/幼童/婴儿包价） | **product-v2 Feign 失败为 null** |
+| `singleRoomSurcharge` | BigDecimal(String) | 单房差（报价维度） | **Feign 失败为 null** |
+| `grandTotal` | BigDecimal(String) | 报价合计（product-v2 实时报价，非订单冻结额） | **Feign 失败为 null** |
+
+`FeeLineItemVO`：`name` / `unitPrice` / `qty` / `subtotal`（小计取报价权威值，含早鸟折扣口径）。
+
+---
+
+## 6. 枚举 / 数据字典
+
+本次无枚举变更。金额均为字符串（防 JS 精度丢失）。
+
+---
+
+## 7. 错误码
+
+无新增错误码。product-v2 报价 Feign 失败走降级（报价分价置 null），不抛业务错误。
+
+---
+
+## 8. 示例
+
+### 8.1 典型成功
+
+```json
+{
+  "code": 200,
+  "data": {
+    "agencyName": "内蒙古呼籁国际旅行社有限公司",
+    "orderNo": "HL20260701001",
+    "teamNo": "26-0554",
+    "productName": "游牧的森林-短途版",
+    "departDate": "2026-07-01",
+    "returnDate": "2026-07-04",
+    "paxSummary": "2大2小",
+    "feeDetail": {
+      "orderAmount": "18000.00",
+      "discountAmount": "2000.00",
+      "surchargeAmount": "500.00",
+      "payableTotal": "16500.00",
+      "paidAmount": "10000.00",
+      "outstandingBalance": "6500.00",
+      "onsiteBalance": "3540.00",
+      "items": [
+        {"name": "成人包价", "unitPrice": "3380.00", "qty": 2, "subtotal": "6760.00"},
+        {"name": "儿童包价", "unitPrice": "1980.00", "qty": 1, "subtotal": "1980.00"}
+      ],
+      "singleRoomSurcharge": "0",
+      "grandTotal": "16500.00"
+    }
+  },
+  "success": true
+}
+```
+（其余区块 transports/customerOverview/hotels/emergencyContacts/days/notices/refundNotes/handoverChecklist/collectReceipt/remark 结构不变，此处省略。）
+
+### 8.2 边界（product-v2 报价 Feign 失败）
+
+```json
+{
+  "feeDetail": {
+    "orderAmount": "18000.00",
+    "discountAmount": "2000.00",
+    "surchargeAmount": "500.00",
+    "payableTotal": "16500.00",
+    "paidAmount": "10000.00",
+    "outstandingBalance": "6500.00",
+    "onsiteBalance": "3540.00",
+    "items": null,
+    "singleRoomSurcharge": null,
+    "grandTotal": null
+  }
+}
+```
+> feeDetail 本身仍返回，只有报价分价三项为 null。前端展示订单财务照常，报价明细区显示"暂无"。
+
+### 8.3 异常
+
+订单未录代收款：`onsiteBalance` 为 null；`outstandingBalance` 仍按应收派生返回。
+
+---
+
+## 9. 业务边界
+
+- feeDetail 订单财务字段取自订单本地数据，恒返回，不随 product-v2 报价 Feign 降级。
+- `grandTotal`（报价合计）是 product-v2 实时报价，与 `orderAmount`（下单冻结原价）语义不同，产品改价后可能不一致。
+- 勾稽：`payableTotal = orderAmount − discountAmount + surchargeAmount`；`outstandingBalance = payableTotal − paidAmount + refundedAmount`。
+
+---
+
+## 10. 修改前后对比
+
+| 位置 | 修改前 | 修改后 |
+|------|--------|--------|
+| 顶层 | `orderAmount` / `payableTotal` / `outstandingBalance` | 删除（移入 feeDetail） |
+| feeDetail | `{items, singleRoomSurcharge, grandTotal, onsiteBalance}` | `{orderAmount, discountAmount, surchargeAmount, payableTotal, paidAmount, outstandingBalance, onsiteBalance, items, singleRoomSurcharge, grandTotal}` |
+| 降级 | product-v2 Feign 失败 → 整个 `feeDetail` = null | Feign 失败 → 仅 `items`/`singleRoomSurcharge`/`grandTotal` = null，feeDetail 恒返回 |
+
+---
+
+## 11. 影响评估 / 回滚
+
+**破坏性变更**（前端必须同步）：
+1. 顶层不再有 `orderAmount`/`payableTotal`/`outstandingBalance` → 改从 `feeDetail` 取。
+2. `feeDetail` 报价分价（items/singleRoomSurcharge/grandTotal）改为可空 → 前端判空展示（原判整个 feeDetail 是否 null 的逻辑要改成判这三项）。
+
+**新增可选接入**：feeDetail 的 discountAmount / surchargeAmount / paidAmount。
+
+**回滚**：接口层回退到 PR #4692 版本。零 DDL，无数据迁移。
+
+---
+
+## 12. 注意事项
+
+- 所有金额为字符串（防 JS 精度丢失）。
+- feeDetail 一定非 null；判"报价是否取到"改判 `feeDetail.items == null`。
+- `grandTotal`（报价合计）≠ `orderAmount`（订单冻结额），展示订单总价请用 orderAmount / payableTotal。
+
+---
+
+## 13. 关联 / 联系人
+
+- Issue：[#4696](https://git.1814.love:8443/wx/HL/issues/4696)
+- PR：[#4697](https://git.1814.love:8443/wx/HL/pulls/4697)
+- 前序：[#4692](https://git.1814.love:8443/wx/HL/pulls/4692) / [#4683](https://git.1814.love:8443/wx/HL/pulls/4683) / [#4650](https://git.1814.love:8443/wx/HL/pulls/4650)
+- 设计文档：API-SPEC §12.6（四件套 v6.2.3）
+- 负责人：腰苏图（yst）