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