---
schema: "hl-changelog/v2"
ticket: "5244"
title: "派单详情分别返回接送说明与通用备注"
consumer: "admin"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "implemented"
frontend_owner: "hl-ui-codex"
frontend_ref: "mmg/hl-ui@ede7d025e2d6d0d90e570d0bfa5d90f588431842"
target_release: ""
verified_at: ""
status_note: "后端 PR #5246 已合并并部署；前端需在派单 Step1 大交通卡片分别渲染两个字段。"
updated_at: "2026-07-25T01:24:40.528Z"
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` 表示等待前端真实领取，不代表页面已实现、发布或验证。