hl-api-changelog/changelogs-v2/2026-07/91_5202_调整订单行程节点时间-修改接口-前端待处理-管理后台.md

调整订单行程节点时间回显与修改（修改接口）

日期：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

快照出参

{
  "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

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

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

清空示例：

{
  "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，前端按空态展示。
• 本次不改订单金额、节点价格、数量、顺序和资源绑定逻辑。