hl-api-changelog/changelogs-v2/2026-06/52_4628_订单实配层合并进行程节点A2_行程结算入参+签单出参+删景点餐接口-修改接口-管理后台.md

订单实配层合并进行程节点（A2 epic）—— 行程节点结算入参 + 签单出参变化 + 删景点/餐配置接口

变更类型：修改接口（含删除接口）｜ 端类型：管理后台 epic：#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 片段）

{ "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
• PR：#4630 / #4633 / #4640 / #4651 / #4656
• 负责人：腰苏图（后端）