# 【修改接口·管理后台】v3 行程 day/node 写操作真实化

> **更新时间**: 2026-05-19
> **端类型**: 管理后台
> **关联**: HL Issue [#2598](https://git.1814.love:8443/wx/HL/issues/2598) / PR [#2613](https://git.1814.love:8443/wx/HL/pulls/2613)
> **背景**: hl-order-service-v3 行程模块写接口从 Mock 替换为真实落库，7 个接口行为语义从假数据回显变为真实 DB 读写 + 审计日志。路径/方法/参数结构/响应结构全部不变。

---

## 1. 接口背景

行程编辑页（管理后台）包含天（Day）和节点（Node）两层叙事结构：

- **天（Day）**：对应行程中的第 N 天，含标题、封面、描述、餐饮安排、集合解散地等叙事字段。
- **节点（Node）**：每天下的具体活动节点，含节点类型（景点/餐厅/活动/服务/自定义）、时间、资源关联等。

之前 6 个写接口均为 Mock（返回硬编码 ID 或入参原样回显），不落库。本期（PR #2613）全部替换为真实 DB 操作，同时新增编辑历史分页接口（F7）。

**前端调用方式不变**——所有接口路径、方法、入参结构、出参结构与之前约定完全一致，变化的是后端行为从假数据变为真数据落库 + 审计。

---

## 2. 变更清单

| # | 方法 | 路径 | 变更类型 | 说明 |
|---|------|------|----------|------|
| F1 | POST | `/v3/admin/order/{orderId}/itinerary/days` | 行为变更 | Mock→真实：dayNumber/dayDate 后端派生，真实落库 + 写 edit_log |
| F2 | PUT  | `/v3/admin/order/{orderId}/itinerary/days/{dayId}` | 行为变更 | Mock→真实：更新叙事字段，dayNumber/dayDate 不可改 |
| F3 | DELETE | `/v3/admin/order/{orderId}/itinerary/days/{dayId}` | 行为变更 | Mock→真实：级联软删 nodes + activity/custom_assignment |
| F4 | POST | `/v3/admin/order/{orderId}/itinerary/nodes` | 行为变更 | Mock→真实：ACTIVITY/CUSTOM 同事务 INSERT 实配，sortOrder 派生 |
| F5 | PUT  | `/v3/admin/order/{orderId}/itinerary/nodes/{nodeId}` | 行为变更 | Mock→真实：仅叙事字段，实配不动 |
| F6 | DELETE | `/v3/admin/order/{orderId}/itinerary/nodes/{nodeId}` | 行为变更 | Mock→真实：软删节点，实配不动（下一期补） |
| F7 | GET  | `/v3/admin/order/{orderId}/itinerary/edit-log/page` | 行为变更 | Mock→真实：6 字段筛选分页，真实查 order_itinerary_edit_log |

**破坏兼容？** 无。入参字段、出参字段名/类型全部不变。

---

## 3. 接口详情

所有接口：
- **服务**: hl-order-service-v3（端口 8086，通过 Gateway :8080 路由）
- **认证**: JWT Bearer Token，Header `Authorization: Bearer {token}`，无效 token 返回 `code=401`
- **限流**: Gateway 全局限流，无接口级特殊限流
- **幂等性**: 写接口非幂等（每次调用均落库 + 写 edit_log）；建议前端防重提交（按钮 loading 态）

### F1 新增天
- **方法 + 路径**: `POST /v3/admin/order/{orderId}/itinerary/days`
- **描述**: 为指定订单新增一个行程天，dayNumber 由后端 MAX+1 派生

### F2 修改天
- **方法 + 路径**: `PUT /v3/admin/order/{orderId}/itinerary/days/{dayId}`
- **描述**: 修改指定行程天的叙事字段，dayNumber/dayDate 不可改

### F3 删除天
- **方法 + 路径**: `DELETE /v3/admin/order/{orderId}/itinerary/days/{dayId}`
- **描述**: 软删指定行程天，级联软删该天下所有节点及 activity/custom 实配

### F4 新增节点
- **方法 + 路径**: `POST /v3/admin/order/{orderId}/itinerary/nodes`
- **描述**: 在指定天下新增节点，sortOrder 由后端 MAX+1 派生；ACTIVITY/CUSTOM 类型需带 assignmentPayload

### F5 修改节点
- **方法 + 路径**: `PUT /v3/admin/order/{orderId}/itinerary/nodes/{nodeId}`
- **描述**: 修改节点叙事字段，不修改实配数据（下一期）

### F6 删除节点
- **方法 + 路径**: `DELETE /v3/admin/order/{orderId}/itinerary/nodes/{nodeId}`
- **描述**: 软删指定节点，不级联删除实配（与 deleteDay 的级联行为不同）

### F7 编辑历史分页
- **方法 + 路径**: `GET /v3/admin/order/{orderId}/itinerary/edit-log/page`
- **描述**: 分页查询订单行程编辑历史，支持 6 字段筛选

---

## 4. 接口入参

### 4.1 路径参数（所有接口）

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| orderId | Long（String） | 是 | 订单 ID，雪花 ID 以字符串形式传递 |

F2 / F3 额外：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| dayId | Long（String） | 是 | 天 ID |

F5 / F6 额外：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| nodeId | Long（String） | 是 | 节点 ID |

### 4.2 请求体字段

#### F1 新增天 / F2 修改天（请求体相同，均为 ItineraryDayUpsertReqVO）

所有字段均为非必填：

| 字段 | 类型 | 校验 | 说明 |
|------|------|------|------|
| dayTitle | String | 长度 ≤128 | 当天标题 |
| quoteText | String | 长度 ≤256 | 金句/小诗 |
| coverImageUrl | String | 长度 ≤512 | 封面图 OSS URL |
| description | String | 长度 ≤4096 | 当日描述（支持富文本） |
| breakfast | String | 枚举见第 6 节 | 早餐安排 |
| lunch | String | 枚举见第 6 节 | 午餐安排 |
| dinner | String | 枚举见第 6 节 | 晚餐安排 |
| diningRemark | String | 长度 ≤256 | 餐饮备注 |
| gatherPlace | Object | — | 集合地点（POI 对象，字段见下） |
| dismissalPlace | Object | — | 解散地点 |
| dailyMileage | Integer | 值 ≥0 | 当日里程（km） |
| dailyDuration | Integer | 值 ≥0 | 行驶时长（分钟） |
| mileageManualOverride | Boolean | — | 是否手动覆盖里程 |
| photoUrls | List\<String\> | — | 图集 URL 列表 |
| editReason | String | 长度 ≤256 | 修改原因（写入 edit_log） |

注意（F2 修改天）: dayNumber 和 dayDate 后端管理，传了也不生效。

gatherPlace / dismissalPlace POI 对象结构（字段均可选）：

```json
{name:国家会展中心,address:上海市青浦区崧泽大道,longitude:121.2987,latitude:31.1598}
```

当前响应中 gatherPlace/dismissalPlace 以 JSON 字符串形式返回（非 Object），下一期统一处理。

#### F3 删除天 / F6 删除节点（请求体）

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| editReason | String | 否 | 删除原因（写入 edit_log） |

#### F4 新增节点 / F5 修改节点（请求体 ItineraryNodeUpsertReqVO）

| 字段 | 类型 | 必填 | 校验 | 说明 |
|------|------|------|------|------|
| nodeName | String | 是（F4/F5）| @NotBlank，长度 ≤128 | 节点名称 |
| dayId | Long（String） | 是（F4）| — | 所属天 ID，F5 修改时无需传 |
| nodeType | String | 是（F4） | 枚举见第 6 节 | 节点类型；F5 修改时不可改 |
| resourceType | String | 否 | 枚举见第 6 节 | 关联资源类型 |
| resourceId | Long（String） | 否 | — | 资源 ID；ACTIVITY 类型时后端校验 DB NOT NULL |
| startTime | String | 否 | HH:mm 格式 | 开始时间，如 "09:00" |
| timePeriod | String | 否 | — | 时段标签，如 "上午" |
| durationMinutes | Integer | 否 | 值 ≥0 | 持续时长（分钟） |
| description | String | 否 | 长度 ≤2000 | 节点描述 |
| images | List\<String\> | 否 | — | 图集 URL 列表 |
| emojiIcon | String | 否 | 长度 ≤8 | Emoji 图标 |
| assignmentPayload | Object | nodeType=ACTIVITY/CUSTOM 时必填 | 见下 | 实配载荷（新增节点时使用） |
| editReason | String | 否 | 长度 ≤256 | 修改原因（写入 edit_log） |

assignmentPayload 对象结构（NodeAssignmentPayload）：

| 字段 | 类型 | 必填 | 校验 | 说明 |
|------|------|------|------|------|
| unitPrice | BigDecimal | 是 | 值 ≥0 | 单价 |
| qty | Integer | 是 | 值 ≥1 | 数量 |
| costPrice | BigDecimal | 否 | — | 成本价 |
| supplierName | String | 否 | 长度 ≤128 | 供应商名称 |
| supplierContact | String | 否 | 长度 ≤64 | 供应商联系人 |
| supplierPhone | String | 否 | 长度 ≤32 | 供应商电话 |

totalAmount = unitPrice x qty，后端自动计算，不接受前端传入。

#### F7 编辑历史分页（Query 参数）

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| pageNo | Integer | 是 | 页码，从 1 开始 |
| pageSize | Integer | 是 | 每页条数，建议 10-20 |
| editType | String | 否 | 枚举见第 6 节，单值筛选 |
| targetDay | Integer | 否 | 筛选指定天号（如 1、2、3） |
| operatorId | Long | 否 | 筛选指定操作人 ID |
| operatedFrom | String | 否 | 开始时间，**必须 ISO 格式** `2026-05-19T00:00:00` |
| operatedTo | String | 否 | 结束时间，**必须 ISO 格式** `2026-05-19T23:59:59` |

注意：operatedFrom/operatedTo 必须使用 ISO 格式（含 T），空格格式（2026-05-19 00:00:00）会返回 400。

---

## 5. 出参字段

所有接口统一包装：

```json
{"code":200,"msg":"success","data":{}}
```

### F1/F2/F3 响应体（ItineraryDayRespVO）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | String | 天 ID（Long 序列化为 String，防 JS 精度丢失） |
| orderId | String | 订单 ID |
| dayNumber | Integer | 第几天（后端派生，从 1 开始） |
| dayDate | String | 当日日期，格式 yyyy-MM-dd |
| dayTitle | String | 标题 |
| quoteText | String | 金句 |
| coverImageUrl | String | 封面图 URL |
| description | String | 描述 |
| breakfast | String | 早餐枚举值 |
| lunch | String | 午餐枚举值 |
| dinner | String | 晚餐枚举值 |
| diningRemark | String | 餐饮备注 |
| gatherPlace | String | 集合地点（当前为 JSON 字符串，非 Object） |
| dismissalPlace | String | 解散地点（同上） |
| dailyMileage | Integer | 当日里程 |
| dailyDuration | Integer | 行驶时长（分钟） |
| mileageManualOverride | Boolean | 是否手动覆盖里程 |
| photoUrls | List<String> | 图集 |
| editLogId | String | 本次操作产生的 edit_log ID（Long→String） |
| createTime | String | 创建时间 |
| updateTime | String | 更新时间 |

### F4/F5/F6 响应体（ItineraryNodeRespVO）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | String | 节点 ID（Long→String） |
| orderId | String | 订单 ID |
| dayId | String | 所属天 ID（Long→String） |
| nodeType | String | 节点类型枚举值 |
| sortOrder | Integer | 排序权重（后端派生，0-based max+1） |
| resourceType | String | 资源类型 |
| resourceId | String | 资源 ID（Long→String） |
| resourceName | String | 资源名称（Feign 反查，SERVICE/CUSTOM/无 resourceId 时为 null） |
| nodeName | String | 节点名称 |
| startTime | String | 开始时间（HH:mm） |
| timePeriod | String | 时段标签 |
| durationMinutes | Integer | 持续时长 |
| description | String | 描述 |
| images | List<String> | 图集 |
| emojiIcon | String | Emoji |
| refType | String | 实配关联类型（枚举见第 6 节） |
| refId | String | 实配 ID（Long→String，无实配时 null） |
| assignment | Object | 实配数据（F4 ACTIVITY/CUSTOM 时有值，F5/F6 当前返回 null） |
| editLogId | String | 本次操作产生的 edit_log ID（Long→String） |
| createTime | String | 创建时间 |
| updateTime | String | 更新时间 |

assignment 对象（仅 F4 ACTIVITY/CUSTOM 时非 null）：

| 字段 | 类型 | 说明 |
|------|------|------|
| id | String | 实配 ID |
| unitPrice | BigDecimal | 单价 |
| qty | Integer | 数量 |
| totalAmount | BigDecimal | 总额（后端派生） |
| costPrice | BigDecimal | 成本价 |
| supplierName | String | 供应商 |
| status | String | 实配状态，新增时为 PLANNED |

### F7 响应体（分页）

```json
{code:200,data:{records:[],total:9,page:1,pageSize:10}}
```

EditLogVO 字段：

| 字段 | 类型 | 说明 |
|------|------|------|
| id | String | edit_log ID（Long→String） |
| orderId | String | 订单 ID |
| editType | String | 操作类型枚举值（见第 6 节） |
| targetDay | Integer | 操作涉及的天号 |
| beforeSnapshot | String | 操作前快照（JSON 字符串） |
| afterSnapshot | String | 操作后快照（JSON 字符串） |
| amountDelta | BigDecimal | 金额变化（叙事层固定为 0） |
| editReason | String | 操作原因 |
| scope | String | 固定为 ITINERARY |
| operatorId | String | 操作人 ID（Long→String） |
| operatorName | String | 操作人姓名 |
| operatedAt | String | 操作时间（ISO 格式） |
| adjustmentId | String | 关联调整单 ID（暂未支持，固定 null） |

---

## 6. 枚举 / 数据字典

### 餐饮枚举（breakfast / lunch / dinner）

| 值 | 含义 |
|----|------|
| HOTEL | 酒店/旅馆餐 |
| CAMP | 营地餐 |
| SPECIAL | 特色餐 |
| SELF | 自理 |

### 节点类型（nodeType）

| 值 | 含义 |
|----|------|
| SCENIC | 景点游览 |
| RESTAURANT | 用餐 |
| ACTIVITY | 活动体验 |
| SERVICE | 服务项 |
| CUSTOM | 自定义 |

### 资源类型（resourceType）

| 值 | 含义 |
|----|------|
| SCENIC_SPOT | 景点 |
| RESTAURANT | 餐厅 |
| ACTIVITY | 活动 |

### 实配关联类型（refType）

| 值 | 含义 |
|----|------|
| NONE | 无实配 |
| SCENIC_ASSIGNMENT | 关联景点实配 |
| MEAL_ASSIGNMENT | 关联餐饮实配 |
| ACTIVITY_ASSIGNMENT | 关联活动实配 |
| CUSTOM_ASSIGNMENT | 关联自定义实配 |
| STAFF_ASSIGNMENT | 关联员工实配 |

### edit_log 操作类型（editType）

| 值 | 含义 |
|----|------|
| ADD_DAY | 新增天 |
| EDIT_DAY | 修改天 |
| REMOVE_DAY | 删除天 |
| ADD_NODE | 新增节点（本期新增枚举） |
| EDIT_NODE | 修改节点（本期新增枚举） |
| REMOVE_NODE | 删除节点（本期新增枚举） |

---

## 7. 错误码

| 错误码 | 含义 | 触发场景 |
|--------|------|----------|
| 583001 | ORDER_NOT_FOUND 订单不存在 | orderId 无对应记录 |
| 583050 | DAY_NOT_FOUND 行程天不存在或已删除 | dayId 不属于该订单，或已软删 |
| 583051 | NODE_NOT_FOUND 节点不存在或已删除 | nodeId 不属于该订单，或已软删 |
| 583052 | ASSIGNMENT_PAYLOAD_REQUIRED 实配载荷必填 | nodeType=ACTIVITY/CUSTOM 但未传 assignmentPayload |
| 583053 | INVALID_NODE_TYPE 节点类型非法 | nodeType 传了非枚举值 |
| 583022 | RESOURCE_NOT_FOUND 资源不存在 | resourceId 对应资源在 resource-service 查不到 |
| 401 | 未认证 / Token 无效 | 无 Authorization Header 或 Token 过期 |

---

## 8. 示例

### 8.1 典型成功 — 新增一天 + 新增节点

**Step 1：新增天**

```bash
curl -X POST "http://localhost:8080/v3/admin/order/844477867747184641/itinerary/days" \n  -H "Authorization: Bearer {token}" \n  -H "Content-Type: application/json" \n  -d '{"dayTitle":"第一天·布达拉宫","description":"抵达拉萨，参观布达拉宫","breakfast":"HOTEL","lunch":"SPECIAL","dinner":"SELF","editReason":"初次添加行程天"}'
```

响应：

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "844800000000001001",
    "orderId": "844477867747184641",
    "dayNumber": 1,
    "dayDate": "2026-06-01",
    "dayTitle": "第一天·布达拉宫",
    "breakfast": "HOTEL",
    "lunch": "SPECIAL",
    "dinner": "SELF",
    "gatherPlace": null,
    "editLogId": "844900000000000001",
    "createTime": "2026-05-19T15:30:00"
  }
}
```

说明：第一次新增天，dayNumber=1；dayDate 根据订单出发日自动计算。

**Step 2：新增景点节点**

```bash
curl -X POST "http://localhost:8080/v3/admin/order/844477867747184641/itinerary/nodes" \n  -H "Authorization: Bearer {token}" \n  -H "Content-Type: application/json" \n  -d '{"dayId":"844800000000001001","nodeType":"SCENIC","nodeName":"布达拉宫","resourceType":"SCENIC_SPOT","resourceId":"700000000000001","startTime":"10:00","durationMinutes":180}'
```

响应：

```json
{
  "code": 200,
  "data": {
    "id": "844800000000002001",
    "dayId": "844800000000001001",
    "nodeType": "SCENIC",
    "sortOrder": 0,
    "resourceName": "布达拉宫",
    "nodeName": "布达拉宫",
    "startTime": "10:00",
    "durationMinutes": 180,
    "refType": "NONE",
    "refId": null,
    "assignment": null,
    "editLogId": "844900000000000002"
  }
}
```

说明：该天第一个节点，sortOrder=0；resourceName 由后端 Feign 反查。

### 8.2 边界情况 — 新增 ACTIVITY 节点（带实配载荷）

```bash
curl -X POST "http://localhost:8080/v3/admin/order/844477867747184641/itinerary/nodes" \n  -H "Authorization: Bearer {token}" \n  -H "Content-Type: application/json" \n  -d '{"dayId":"844800000000001001","nodeType":"ACTIVITY","nodeName":"骑马体验","resourceType":"ACTIVITY","resourceId":"710000000000002","startTime":"14:00","durationMinutes":60,"assignmentPayload":{"unitPrice":200.00,"qty":4,"costPrice":150.00,"supplierName":"高原牧场体验馆","supplierContact":"王师傅","supplierPhone":"18800001234"}}'
```

响应（节点 + 活动实配同事务写入）：

```json
{
  "code": 200,
  "data": {
    "id": "844800000000002002",
    "dayId": "844800000000001001",
    "nodeType": "ACTIVITY",
    "sortOrder": 1,
    "resourceName": "高原骑马体验",
    "nodeName": "骑马体验",
    "refType": "ACTIVITY_ASSIGNMENT",
    "refId": "860000000000000001",
    "assignment": {"id":"860000000000000001","unitPrice":200.00,"qty":4,"totalAmount":800.00,"costPrice":150.00,"supplierName":"高原牧场体验馆","status":"PLANNED"},
    "editLogId": "844900000000000003"
  }
}
```

边界说明：第 2 个节点，sortOrder=1；totalAmount=200x4=800，后端派生；resourceName 由 Feign 反查不依赖前端传入。

### 8.3 业务失败 — ACTIVITY 节点未传 assignmentPayload

```bash
curl -X POST "http://localhost:8080/v3/admin/order/844477867747184641/itinerary/nodes" \n  -H "Authorization: Bearer {token}" \n  -H "Content-Type: application/json" \n  -d '{"dayId":"844800000000001001","nodeType":"ACTIVITY","nodeName":"骑马体验"}'
```

响应：

```json
{"code":583052,"msg":"nodeType=ACTIVITY/CUSTOM 必须传 assignmentPayload","data":null}
```

---

## 9. 业务边界

### 适用场景

- 管理后台行程编辑页的新增天/删除天/编辑天/新增节点/修改节点/删除节点操作
- 编辑历史面板查看审计日志

### 不适用场景

- 整体行程保存（batchSave，POST /itinerary/save）——该接口仍为 Mock，下一期处理
- 小程序端行程查看（MpItineraryService.getMpItinerary）——只读接口，不涉及本期写操作
- staff/scenic/meal 类节点的实配写入——下一期

### 特殊边界

| 场景 | 行为 |
|------|------|
| dayNumber 派生 | 后端 MAX(day_number)+1，同订单第一次加天时 dayNumber=1；前端不传不接收 |
| dayDate 派生 | 订单出发日+(dayNumber-1) 天自动计算；F2 修改天不可改 dayNumber，因此 dayDate 也不变 |
| sortOrder 派生 | addNode 时 MAX(sort_order)+1，该天首个节点 sortOrder=0；前端不传 |
| resourceName 派生 | nodeType=SCENIC_SPOT/RESTAURANT/ACTIVITY 且有 resourceId 时 Feign 反查；nodeType=SERVICE/CUSTOM 或 resourceId=null 时跳过返回 null |
| deleteDay 级联范围 | 软删该天所有节点 + 节点关联的 activity_assignment / custom_assignment；scenic_assignment / meal_assignment 暂不级联（留 TODO） |
| deleteNode 不级联 | 单独删节点不删实配（与 deleteDay 的级联不同），下一期补 |
| F5 editNode 实配不动 | 修改节点叙事字段时不同步修改 activity/custom_assignment，响应 assignment=null |
| 并发 addDay 防护 | 两人同时 addDay 触发 uk_order_day 唯一索引冲突时，后端 catch DuplicateKeyException 重试一次，仍失败返回业务错误码（不出 500） |
| 跨订单防护 | dayId/nodeId 校验 order_id 是否匹配，他人订单数据传进来返回 DAY_NOT_FOUND / NODE_NOT_FOUND |
| 已删除天再删 | 返回 DAY_NOT_FOUND（583050），不重复软删 |

---

## 10. 修改前后对比

### 字段级对比（入参/出参结构不变）

| 维度 | 修改前（Mock） | 修改后（真实） |
|------|--------|--------|
| F1 addDay 返回 id | 硬编码 7700000000008 | 真实雪花 ID，String 类型 |
| F2 editDay 返回数据 | 原 dayId 原样回显 | 真实更新后 DB 记录，含 updateTime |
| F3 deleteDay 返回 | 伪 deleted: true | 返回删除前的 day 完整数据 + editLogId |
| F4 addNode 返回 id | 硬编码 7800000000088 | 真实雪花 ID，refType/refId 真实回填 |
| F5 editNode / F6 deleteNode | 入参原样回显 | 真实 DB 操作后记录 |
| F7 edit-log/page | 固定返回 3 条假 log | 真实查询 order_itinerary_edit_log |
| edit_log 是否存在 | 否（Mock 不写 DB） | 是，每次写操作同事务 1 行 |

### 行为级对比

| 操作 | 修改前 | 修改后 |
|------|--------|--------|
| 新增天两次 | 两次都返回同一 Mock ID | dayNumber 正确派生为 1、2 |
| 页面刷新后数据是否保留 | 否（Mock 不落库） | 是（真实落库） |
| 删除天后节点是否消失 | 否 | 是（级联软删） |
| 编辑历史能否查到 | 否 | 是（每个写操作写 edit_log） |

---

## 11. 影响评估 / 回滚

### 对前端的影响

- 接口路径/方法/入参结构/出参字段名完全不变，前端代码无需修改
- 行为变化：之前 Mock 数据刷新会丢失，现在真实落库；如果前端有基于 Mock 行为的临时兼容代码（如前端本地缓存假 ID 后续补偿），需检查是否有 workaround 要清理

### 前端需要验证的点

1. id / dayId / nodeId / editLogId / refId / operatorId 等所有 Long ID 字段均已序列化为 String，验证 JS 端是否正确处理（不要 parseInt）
2. editNode（F5）响应 assignment=null，如需展示实配数据需另调 /itinerary/full 接口
3. gatherPlace / dismissalPlace 当前响应为 JSON 字符串，需 JSON.parse() 后渲染（下一期后端统一改为 Object 返回）
4. F7 edit-log/page 日期筛选必须 ISO 格式：2026-05-19T00:00:00，空格格式会 400

### 破坏性兼容

无破坏性兼容。

### 回滚方案

如需回滚，通过 Gitea 创建 revert PR，将 dev-v3 回到 PR #2613 合入前的状态。回滚不影响已落库的 order_itinerary_day / order_itinerary_node / order_itinerary_edit_log 数据（软删数据保留，不清库）。

---

## 12. 注意事项

1. **adjustmentId 暂未支持**：EditLogVO.adjustmentId 字段保留但 DDL 无对应列，固定返回 null，下一期 adjustment 流程接入时补齐。

2. **gatherPlace / dismissalPlace 返回 JSON 字符串**：当前接口返回的是 JSON 字符串而非 Object，前端需 JSON.parse() 后再使用。下一期统一改为 Object 返回。

3. **batchSave 仍为 Mock**：POST /v3/admin/order/{orderId}/itinerary/save 整体保存接口本期未真实化，仍返回 Mock 数据。

4. **staff/scenic/meal 实配 CRUD 仍 Mock**：nodeType=SERVICE/CUSTOM 的节点写入已真实，但 staff、scenic、meal 类型相关实配的增删改仍 Mock，下一期补齐。

5. **F5 editNode 不同步实配**：修改节点叙事字段时不修改关联实配，响应 assignment=null。如需实配数据调 /v3/admin/order/{orderId}/itinerary/full。

6. **deleteNode 不级联实配**：单独删节点（F6）不删关联的 activity/custom_assignment，与 deleteDay（F3）的级联行为不同，下一期补齐。

7. **resource-service 可用性**：nodeType=SCENIC/RESTAURANT/ACTIVITY 且传了 resourceId 时，后端会 Feign 调 resource-service 反查资源名。若 resource-service 不可用，返回 RESOURCE_NOT_FOUND（583022），写操作事务回滚。可通过不传 resourceId 规避（resourceName 会为 null）。

8. **Long ID 全为 String**：所有 Long 类型 ID 均序列化为 String（防 JS 精度丢失），前端赋值时不要做 parseInt。

---

## 13. 关联 / 联系人

- **Issue**: [#2598 v3 行程 day/node 写操作真实化](https://git.1814.love:8443/wx/HL/issues/2598)
- **PR**: [#2613](https://git.1814.love:8443/wx/HL/pulls/2613)
- **Commits（dev-v3 rebase 后）**:
  - [12adf586](https://git.1814.love:8443/wx/HL/commit/12adf5861530f5af429d85aa38db9f801fd1d192) feat: Task 1-15 全量完成
  - [38c93408](https://git.1814.love:8443/wx/HL/commit/38c93408c2ca80784cd31cc1e6ee92b724814c9a) fix: Phase 4 QA BUG+WARN 修复
  - [d96c6575](https://git.1814.love:8443/wx/HL/commit/d96c657589838301739a47ab816bec2bbab9b042) fix: Phase 5 reviewer 必修项修复
- **后端负责人**: @yaosutu