---
frontend_status: "implemented"
frontend_owner: "hl-ui-codex"
frontend_ref: "mmg/hl-ui@b619849eb3c71f2e466dec4539f577213c060db0"
updated_at: "2026-07-25T03:25:59.312Z"
---
# 调整订单行程节点时间回显与修改（修改接口）

> 日期：2026-07-24
> 工单：#5202
> 服务：`hl-order-service-v3`
> 前端状态：待处理（`D:/work2/hl-ui` 本次未修改）

## 结论

产品行程节点的两类时间在下单时均已固化到订单行程节点：

- `startTime`：精确开始时间，格式 `HH:mm`。
- `timePeriod`：时间说明，值来自 `itinerary_time_period` 字典，例如 `MORNING`。

本次补齐“调整订单 → 行程”中的完整读写契约：

- 快照逐节点返回 `startTime`、`timePeriod`。
- 调整提交可只修改时间，不要求同时改价或改数量。
- 新增节点也可携带两类时间。
- 两字段可分别存在，不强制互斥。
- 旧订单或未设置时间的节点返回 `null`。

## 涉及接口

| 方法 | 路径 | 变化 |
|---|---|---|
| GET | `/v3/admin/order/{orderId}/adjustment/snapshot` | `data.itinerary.days[].nodes[]` 补齐 `timePeriod`，保留已有 `startTime` |
| POST | `/v3/admin/order/{orderId}/adjustment/submit` | `updates.itinerary.days[].nodes[]` 支持提交 `startTime`、`timePeriod` |

## 快照出参

```json
{
  "data": {
    "itinerary": {
      "days": [
        {
          "id": "8001",
          "dayNumber": 2,
          "nodes": [
            {
              "id": "9001",
              "title": "呼和诺尔草原旅游区",
              "startTime": "05:05",
              "timePeriod": null
            },
            {
              "id": "9002",
              "title": "额尔古纳湿地漂流",
              "startTime": null,
              "timePeriod": "EARLY_MORNING"
            }
          ]
        }
      ]
    }
  }
}
```

`timePeriod` 返回字典值，展示文字请使用现有 `itinerary_time_period` 字典翻译，不要在页面硬编码中文。

## 提交语义

节点时间沿用 patch 语义：

| 入参状态 | 含义 |
|---|---|
| 字段省略或传 `null` | 不修改该字段 |
| `startTime: "09:05"` | 设置精确开始时间 |
| `timePeriod: "MORNING"` | 设置时间说明 |
| `startTime: ""` | 清空精确开始时间，后端落库为 `NULL` |
| `timePeriod: ""` | 清空时间说明，后端落库为 `NULL` |

仅修改时间时的请求示例：

```json
{
  "updates": {
    "itinerary": {
      "days": [
        {
          "id": "8001",
          "dayNumber": 2,
          "nodes": [
            {
              "id": "9001",
              "startTime": "06:30"
            },
            {
              "id": "9002",
              "timePeriod": "AFTERNOON"
            }
          ]
        }
      ]
    }
  }
}
```

清空示例：

```json
{
  "id": "9001",
  "startTime": "",
  "timePeriod": ""
}
```

非空 `startTime` 必须是 24 小时制 `HH:mm`，例如 `09:05`；`9:05`、`24:00` 均不合法。

## 管理后台处理清单

当前 `FunItemAdjustModal.vue` 已从快照读取 `startTime`，但尚未渲染、参与 diff 或写入提交体；`timePeriod` 还未映射。需补：

- 节点草稿与基线同时保存 `startTime`、`timePeriod`。
- 节点行增加精确时间选择器和 `itinerary_time_period` 字典下拉，并回显现有值。
- `funItemsChanged` 与节点 diff 同时比较两字段；只有时间变化也要生成节点 patch。
- `buildItineraryDays()` 对变化字段按需提交，未变化字段省略。
- 用户清空后，提交体将该字段从前端 `null` 转为 `""`；不要直接传 `null`，否则后端按“不修改”处理。
- 保留两字段可同时设置的能力，不在前端强制互斥。

## 兼容性

- 新增出参字段兼容旧调用方。
- `startTime` 原字段保持不变。
- 未设置时间的历史数据返回 `null`，前端按空态展示。
- 本次不改订单金额、节点价格、数量、顺序和资源绑定逻辑。