c7c8a7299c
一些检查失败了
changelog-filename-gate / validate (push) Failing after 2s
修改原因：hl-ui changelog loop 需要把前端消费进度回写到契约源，避免领取、实现状态与实际交付脱节。 修改内容：将 frontend_status 与已有 legacy frontend 同步为 claimed，记录负责人 hl-ui-codex，实现引用保持为空；发布和验收字段保持不变。 实际验证：回写器已校验目标文件、状态单调性、提交范围和 Front Matter 内容，提交只包含当前 changelog。 Frontend-Status: tools/mcp-api-sync/.changelog-repo/changelogs-v2/2026-07/25_5244_派单详情分别返回接送说明与通用备注-修改接口-管理后台.md
140 行
5.1 KiB
Markdown
140 行
5.1 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "5244"
|
||
title: "派单详情分别返回接送说明与通用备注"
|
||
consumer: "admin"
|
||
change_type: "修改接口"
|
||
backend_status: "deployed"
|
||
gateway_status: "verified"
|
||
frontend_status: "claimed"
|
||
frontend_owner: "hl-ui-codex"
|
||
frontend_ref: ""
|
||
target_release: ""
|
||
verified_at: ""
|
||
status_note: "后端 PR #5246 已合并并部署；前端需在派单 Step1 大交通卡片分别渲染两个字段。"
|
||
updated_at: "2026-07-25T01:20:57.894Z"
|
||
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` 表示等待前端真实领取，不代表页面已实现、发布或验证。
|