From 45f5dc4a06002e482d43e316d4292e391f9d9b60 Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Fri, 24 Jul 2026 10:28:43 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E4=BA=A4=E6=8E=A5=E8=B0=83=E6=95=B4?=
 =?UTF-8?q?=E8=AE=A2=E5=8D=95=E8=8A=82=E7=82=B9=E6=97=B6=E9=97=B4=E5=A5=91?=
 =?UTF-8?q?=E7=BA=A6=20(#5202)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...�•è¡Œç¨‹èŠ‚点时间-修改接å�£-å‰�端待处ç�†-管ç�†å�Žå�°.md | 130 ++++++++++++++++++
 1 file changed, 130 insertions(+)
 create mode 100644 changelogs-v2/2026-07/91_5202_调整订�行程节点时间-修改接�-�端待处�-管���.md

diff --git a/changelogs-v2/2026-07/91_5202_调整订�行程节点时间-修改接�-�端待处�-管���.md b/changelogs-v2/2026-07/91_5202_调整订�行程节点时间-修改接�-�端待处�-管���.md
new file mode 100644
index 0000000..0ddd755
--- /dev/null
+++ b/changelogs-v2/2026-07/91_5202_调整订�行程节点时间-修改接�-�端待处�-管���.md
@@ -0,0 +1,130 @@
+# 调整订�行程节点时间回显与修改（修改接�）
+
+> 日期：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`，�端按空�展示。
+- 本次�改订�金��节点价格�数��顺�和资�绑定逻辑。