From 10037c3266e991ffe90fa26ff813972edf84a320 Mon Sep 17 00:00:00 2001
From: yaosutu <770858045@qq.com>
Date: Tue, 30 Jun 2026 16:30:33 +0800
Subject: [PATCH] =?UTF-8?q?docs(changelog):=20A2=20=E8=AE=A2=E5=8D=95?=
 =?UTF-8?q?=E5=AE=9E=E9=85=8D=E5=B1=82=E5=90=88=E5=B9=B6=E8=BF=9B=E8=A1=8C?=
 =?UTF-8?q?=E7=A8=8B=E8=8A=82=E7=82=B9=20=E2=80=94=20=E8=A1=8C=E7=A8=8B?=
 =?UTF-8?q?=E8=8A=82=E7=82=B9=E7=BB=93=E7=AE=97=E5=85=A5=E5=8F=82+?=
 =?UTF-8?q?=E7=AD=BE=E5=8D=95=E5=87=BA=E5=8F=82+=E5=88=A0=E6=99=AF?=
 =?UTF-8?q?=E7=82=B9=E9=A4=90=E6=8E=A5=E5=8F=A3=20(#4628)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

管理后台 changelog：行程节点接口加 7 结算入参 / 签单出参加 type=SERVICE+景点出单+房型真名 / 删 6 个景点餐配置接口改走行程节点。epic #4628 五期 PR #4630/#4633/#4640/#4651/#4656。
---
 ...��程结算入参+签单出参+删景点餐接口-修改接口-管理后台.md | 168 ++++++++++++++++++
 1 file changed, 168 insertions(+)
 create mode 100644 changelogs-v2/2026-06/52_4628_订单实配层合并进行程节点A2_行程结算入参+签单出参+删景点餐接口-修改接口-管理后台.md

diff --git a/changelogs-v2/2026-06/52_4628_订单实配层合并进行程节点A2_行程结算入参+签单出参+删景点餐接口-修改接口-管理后台.md b/changelogs-v2/2026-06/52_4628_订单实配层合并进行程节点A2_行程结算入参+签单出参+删景点餐接口-修改接口-管理后台.md
new file mode 100644
index 0000000..50f8b53
--- /dev/null
+++ b/changelogs-v2/2026-06/52_4628_订单实配层合并进行程节点A2_行程结算入参+签单出参+删景点餐接口-修改接口-管理后台.md
@@ -0,0 +1,168 @@
+# 订单实配层合并进行程节点（A2 epic）—— 行程节点结算入参 + 签单出参变化 + 删景点/餐配置接口
+
+> 变更类型：**修改接口**（含删除接口）｜ 端类型：**管理后台**
+> epic：[#4628](https://git.1814.love:8443/wx/HL/issues/4628)（5 期 PR：#4630 / #4633 / #4640 / #4651 / #4656）
+> 背景：景点/活动/餐的「实配层」（order_scenic/meal/activity_assignment 三表）合并进行程节点 order_itinerary_node 单表，三表已退役。本文汇总对前端有契约影响的 3 处变化。
+
+---
+
+## ① 接口背景
+
+原模型下，行程景点/餐/活动有两套数据：行程节点（叙事展示）+ 独立实配表（结算/门票）。实配表是「空孤岛」（创单不物化、只靠运维手动配），导致**签单景点不出单、退款门票算不准**。A2 把结算维度合并进 order_itinerary_node 单表，行程与结算同源。对前端的契约影响集中在 3 处：行程节点编辑接口入参、打印签单出参、景点/餐配置接口删除。
+
+---
+
+## ② 变更清单
+
+1. **行程节点新增/编辑接口加结算入参**（POST/PUT 行程节点）：新增 included / sellPrice / originalPrice / supplierName / supplierPhone / coverUrl / remark 7 个可选入参 —— 自费门票/活动在此标记。
+2. **打印签单出参变化**（GET sign-voucher）：①新增 `type="SERVICE"` 服务/接送预订通知单；②景点 entry 由「恒空」变为「正常出单」；③酒店房型 `items[].name` 由可能显示「其他房型」变为显示真实房型名。
+3. **删除 6 个景点/餐配置接口**（已 404）：原独立实配表的景点/餐配置接口退役，改走行程节点编辑接口。
+
+---
+
+## ③ 变更一：行程节点新增/编辑接口加结算入参
+
+| 项 | 值 |
+|---|---|
+| 方法/路径 | `POST /v3/admin/order/{id}/itinerary/nodes`（新增节点）/ `PUT /v3/admin/order/{id}/itinerary/nodes/{nodeId}`（编辑节点） |
+| 鉴权 | 管理后台登录态 |
+
+**新增入参（均可选，节点类型为 SCENIC/ACTIVITY/SERVICE/TRANSPORT 时生效）**
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `included` | Boolean | 否 | 套餐已含=true（退款不计可退）；自费/加收=false。**自费项 included=false 时 sellPrice 必填**（否则报错 583064） |
+| `sellPrice` | BigDecimal(字符串) | 否 | 客户成交单价（自费项必填）。退款/签单按此口径 |
+| `originalPrice` | BigDecimal(字符串) | 否 | 票面原价（展示用） |
+| `supplierName` | string | 否 | 供应商名 |
+| `supplierPhone` | string | 否 | 供应商电话 |
+| `coverUrl` | string | 否 | 封面图 URL |
+| `remark` | string | 否 | 备注 |
+
+> 创单物化的景点/活动默认 `included=true`（套餐已含）。前端配自费门票/活动 = 编辑该节点传 `included=false` + `sellPrice`。
+
+**错误码**
+
+| code | 说明 |
+|---|---|
+| 583064 | 自费节点（included=false）未填 sellPrice |
+
+---
+
+## ④ 变更二：打印签单出参变化
+
+接口：`GET /v3/admin/order/{id}/sign-voucher`（出参结构详见 changelog #4549 那份；本次为**取值/类型语义变化**）
+
+**1. 新增 `type="SERVICE"` 服务/接送预订通知单**
+
+`entries[].type` 原有 `HOTEL` / `SCENIC`，**新增 `SERVICE`**（行程中 SERVICE/TRANSPORT 节点，如接送机）。title=「服务/接送预订通知单」，supplierName=服务供应商，items[].name=服务名。
+
+**2. 景点 entry 由空变有**
+
+原景点恒不出单（实配空），现在行程中的景点节点**正常生成 `type="SCENIC"` 通知单**。前端原若对「无景点」做特殊处理，现在会正常收到景点条目。
+
+**3. 房型显示真名**
+
+酒店 `items[].name` 原可能显示「其他房型」（脏字典码兜底），现改走资源房型主数据，**显示真实房型名**（如「大床房」「精品标间」）。前端无需改，仅展示值变准。
+
+> 枚举更新：`entries[].type` 取值集 `{HOTEL, SCENIC}` → `{HOTEL, SCENIC, SERVICE}`。
+
+---
+
+## ⑤ 变更三：删除 6 个景点/餐配置接口（已 404）
+
+以下 6 个接口**已删除，调用返回 404**：
+
+| 方法 | 旧路径 | 替代 |
+|---|---|---|
+| POST | `/v3/admin/order/{id}/scenic` | 改走 `POST /v3/admin/order/{id}/itinerary/nodes`（nodeType=SCENIC） |
+| PUT | `/v3/admin/order/{id}/scenic/{scenicAssignmentId}` | 改走 `PUT /v3/admin/order/{id}/itinerary/nodes/{nodeId}` |
+| DELETE | `/v3/admin/order/{id}/scenic/{scenicAssignmentId}` | 改走行程节点删除 `DELETE .../itinerary/nodes/{nodeId}` |
+| POST | `/v3/admin/order/{id}/meal` | 改走行程节点新增（nodeType=RESTAURANT） |
+| PUT | `/v3/admin/order/{id}/meal/{mealAssignmentId}` | 改走行程节点编辑 |
+| DELETE | `/v3/admin/order/{id}/meal/{mealAssignmentId}` | 改走行程节点删除 |
+
+> 景点/餐的配置统一走行程节点接口（含变更四的结算入参）。前端若还在调上述旧路径，会收到 404，请迁移。
+
+---
+
+## ⑥ 数据字典
+
+- `entries[].type`：HOTEL（酒店预订通知单）/ SCENIC（景点门票预订通知单）/ **SERVICE（服务/接送预订通知单，新增）**。
+- `included`：true（套餐已含）/ false（自费加收）。
+
+---
+
+## ⑦ 错误码
+
+| code | 说明 | 场景 |
+|---|---|---|
+| 583064 | 自费节点未填成交价 | 行程节点 included=false 但 sellPrice 为空 |
+
+---
+
+## ⑧ 示例
+
+**配自费景点（编辑行程节点）**
+
+```
+PUT /v3/admin/order/2071526.../itinerary/nodes/3009...
+{ "included": false, "sellPrice": "120.00", "supplierName": "草原供应商" }
+```
+
+**签单出参（新增 SERVICE entry 片段）**
+
+```json
+{ "type": "SERVICE", "title": "服务/接送预订通知单",
+  "supplierName": "海拉尔接机", "items": [{ "name": "海拉尔接机" }] }
+```
+
+**调已删景点接口（404）**
+
+```
+POST /v3/admin/order/{id}/scenic  →  404 接口不存在
+```
+
+---
+
+## ⑨ 业务边界
+
+- 创单物化的景点/活动默认套餐已含（included=true），退款不逐项退；自费项需前端显式标 included=false + sellPrice。
+- 签单景点/服务条目来自行程节点（创单即有），不再依赖运维手动配置。
+- 餐（RESTAURANT 节点）仅展示，不纳入退款。
+
+---
+
+## ⑩ 修改前后对比
+
+| 维度 | 改前 | 改后 |
+|---|---|---|
+| 行程节点接口 | 无结算入参 | 加 7 个结算入参（included/sellPrice 等） |
+| 签单 type | HOTEL / SCENIC | + SERVICE |
+| 签单景点 | 恒不出单 | 正常出单 |
+| 签单房型 | 可能「其他房型」 | 真实房型名 |
+| 景点/餐配置 | 独立 6 接口 | 删除，改走行程节点接口 |
+
+---
+
+## ⑪ 影响评估 / 回滚
+
+- **前端必改**：① 配景点/餐若用旧 6 接口 → 迁行程节点接口；② 签单 type 枚举处理加 SERVICE 分支；③ 配自费门票走行程节点 included=false + sellPrice。
+- 签单房型/景点出单为展示增强，前端无需改。
+- 后端：三表已 DROP，回滚需后端版本回退 + 恢复表（不可逆迁移，慎重）。
+
+---
+
+## ⑫ 注意事项
+
+- 自费节点 included=false 必带 sellPrice，否则 583064。
+- 签单服务/接送供应商电话为内网明文（与酒店联系人电话同口径）。
+- 旧景点/餐接口已 404，无兼容期。
+
+---
+
+## ⑬ 关联 / 联系人
+
+- epic：[#4628](https://git.1814.love:8443/wx/HL/issues/4628)
+- PR：[#4630](https://git.1814.love:8443/wx/HL/pulls/4630) / [#4633](https://git.1814.love:8443/wx/HL/pulls/4633) / [#4640](https://git.1814.love:8443/wx/HL/pulls/4640) / [#4651](https://git.1814.love:8443/wx/HL/pulls/4651) / [#4656](https://git.1814.love:8443/wx/HL/pulls/4656)
+- 负责人：腰苏图（后端）