diff --git a/changelogs-v2/2026-07/25_5244_派单详情分别返回接送说明与通用备注-修改接口-管理后台.md b/changelogs-v2/2026-07/25_5244_派单详情分别返回接送说明与通用备注-修改接口-管理后台.md new file mode 100644 index 0000000..cb03881 --- /dev/null +++ b/changelogs-v2/2026-07/25_5244_派单详情分别返回接送说明与通用备注-修改接口-管理后台.md @@ -0,0 +1,139 @@ +--- +schema: "hl-changelog/v2" +ticket: "5244" +title: "派单详情分别返回接送说明与通用备注" +consumer: "admin" +change_type: "修改接口" +backend_status: "deployed" +gateway_status: "verified" +frontend_status: "pending" +frontend_owner: "" +frontend_ref: "" +target_release: "" +verified_at: "" +status_note: "后端 PR #5246 已合并并部署;前端需在派单 Step1 大交通卡片分别渲染两个字段。" +updated_at: "2026-07-25" +base: "dev-v3" +generated: "2026-07-25T09:05:18+08:00" +--- + +# 车务派单详情:分别返回接送说明与通用备注 + +> **服务**: `hl-order-service-v3`、`hl-fleet-service` +> +> **工单**: [wx/HL#5244](https://git.1814.love:8443/wx/HL/issues/5244) +> +> **后端 PR**: [wx/HL#5246](https://git.1814.love:8443/wx/HL/pulls/5246) +> +> **影响范围**: 车务管理 → 派车看板 → 派单弹窗 Step1 → 大交通 + +## 业务口径 + +`pickupRemark` 与 `remark` 是两个独立字段,不得合并、互相覆盖或只取其中一个: + +- `pickupRemark`:接机/送机说明;ARRIVAL 展示为“接机说明”,DEPARTURE 展示为“送机说明”。 +- `remark`:大交通通用备注,展示为“备注”。 +- 整团 `arrive/depart` 与分批 `batches[]` 使用同一字段口径。 +- 任一字段为 `null` 或空白时,只隐藏该字段对应的展示行,不影响另一字段。 + +## 变更接口 + +### 管理后台 + +```http +GET /admin/fleet/board/orders/:orderId +``` + +`data.transport.arrive`、`data.transport.depart` 与 `data.transport.batches[]` 均包含: + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `pickupRemark` | `String/null` | 否 | 接机/送机说明 | +| `remark` | `String/null` | 否 | 大交通通用备注;既有字段继续保留 | + +响应示例: + +```json +{ + "code": 200, + "data": { + "transport": { + "arrive": { + "direction": "ARRIVAL", + "pickupRemark": "到达出口举牌接机", + "remark": "航班可能延误" + }, + "depart": { + "direction": "DEPARTURE", + "pickupRemark": "提前三小时送机", + "remark": "请再次确认航站楼" + }, + "batches": [ + { + "direction": "ARRIVAL", + "pickupRemark": "分批接机说明", + "remark": "分批通用备注" + } + ] + } + } +} +``` + +### 内部契约 + +```http +GET /v3/internal/order/orders/:orderId/fleet-detail-context +``` + +order-v3 → fleet 的共享 `OrderTransportForFleetDTO` 在整团段与分批段均独立传递 +`pickupRemark`、`remark`。这是兼容性增量:路径、HTTP 方法、既有字段、枚举、错误码及 +`pickupRequired` 三态口径均不变。 + +## 前端展示矩阵 + +| 方向/模式 | `pickupRemark` | `remark` | 页面展示 | +| --- | --- | --- | --- | +| ARRIVAL,整团或分批 | 有 | 有 | 分别显示“接机说明”和“备注” | +| DEPARTURE,整团或分批 | 有 | 有 | 分别显示“送机说明”和“备注” | +| 任一方向 | 有 | 空 | 只显示接机/送机说明 | +| 任一方向 | 空 | 有 | 只显示备注 | +| 任一方向 | 空 | 空 | 两行均不显示 | + +前端不得根据 `pickupRequired` 推导说明文本,也不得用一个字段回填另一个字段。 + +## 前端处理清单 + +- [ ] 派单弹窗 Step1 大交通卡片读取 `pickupRemark`,按方向显示“接机说明”或“送机说明”。 +- [ ] 通用备注继续读取 `remark`,与接机/送机说明分行展示。 +- [ ] 同时覆盖 `arrive`、`depart`、`batches[]`。 +- [ ] 对 `null`、空字符串和纯空白字符串使用单字段空态规则。 +- [ ] 不显示 `travelerIds` 等内部关联字段;既有出行人脱敏规则不变。 + +## 契约验证状态 + +- OpenAPI/oasdiff:`not_configured`。项目当前未配置稳定 Swagger2 → OAS3 导出与 oasdiff 基线。 +- 消费者契约/Spring Cloud Contract:`not_configured`。项目当前未配置 SCC。 +- fallback:源码与 Codemap 影响比对、order-v3 生产者测试、fleet 消费者/Controller 测试以及完整 reactor 验证。 +- 本次没有临时安装 oasdiff 或 Spring Cloud Contract 依赖。 + +## 验证证据 + +- 合并提交:`ca3c5c7310ddc142398382644a40ab57d951248e`。 +- 定向生产者/消费者测试:88 项通过。 +- 影响范围测试:25 个 reactor 模块全部通过。 +- Fleet 完整验证:2361 项测试,0 失败、0 错误、1 跳过;Spotless 606 个 Java 文件通过。 +- 测试部署: + - order-v3 任务 `a5916436`,8086/8186 双实例成功; + - fleet 任务 `a198456e`,8087/8187 双实例成功。 +- 部署面板与 Nacos 均确认两个服务 2/2 running、healthy、enabled;部署后日志新增错误匹配为 0。 +- 经测试网关验证真实团单:列表与详情 HTTP/业务码均为 200,`relatedDetailReady=true`; + ARRIVAL、DEPARTURE 均同时返回非空且取值不同的 `pickupRemark`、`remark`。 + +## 不影响范围 + +- 不修改 `D:/work2/hl-ui`。 +- 不修改大交通录入、接送默认值、接送需求聚合、派车状态机或历史数据。 +- 不新增 DDL,不清理、不回填存量大交通备注。 + +> 后端与网关已验证;`frontend_status: pending` 表示等待前端真实领取,不代表页面已实现、发布或验证。