# 订单实配层合并进行程节点（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)
- 负责人：腰苏图（后端）