diff --git a/changelogs-v2/2026-08/11_frontend_派单弹窗需求信息两处各缺一半-前端缺陷-管理后台.md b/changelogs-v2/2026-08/11_frontend_派单弹窗需求信息两处各缺一半-前端缺陷-管理后台.md new file mode 100644 index 0000000..6a061cb --- /dev/null +++ b/changelogs-v2/2026-08/11_frontend_派单弹窗需求信息两处各缺一半-前端缺陷-管理后台.md @@ -0,0 +1,150 @@ +--- +schema: "hl-changelog/v2" +ticket: "frontend" +title: "派单弹窗需求信息展示补全:Step1 缺结构化车型语句、Step2 缺特殊诉求与文字备注(后端字段已全部就绪)" +consumer: "admin" +change_type: "前端缺陷" +author: "wx(GIT)" +backend_status: "not_required" +gateway_status: "not_required" +frontend_status: "pending" +frontend_owner: "mmg" +frontend_ref: "" +target_release: "" +verified_at: "" +status_note: "原 #5848 后端工单经调研判定为纯前端渲染缺口,已关单转本条。三块信息(结构化车型语句 / 通用特殊诉求 / 文字备注)后端在 GET /admin/fleet/board/orders/{orderId} 同一份响应里全部已返回,测试服 26-3698 实测有值,无需任何后端改动。" +updated_at: "2026-08-11" +base: "dev-v3" +--- + +# 派单弹窗需求信息展示补全(原 #5848 → 转前端) + +> **页面**:车务管理 → 派单看板 → 订单派车弹窗 +> **后端**:**零改动**。三块信息早已在同一份详情响应里返回,只是前端两处各渲染了一半。 + +--- + +## 一、现状:两处各缺一半 + +| 位置 | 现在显示 | 缺什么 | +|------|---------|--------| +| **Step1「订单详情」→ 定制师/用车备注**区块 | 只有文字备注(例:`用车备注 杨子墨6人suv*2`) | **缺结构化车型语句** | +| **Step2「排车」→ 底部「当前需求」**区块 | 只有结构化语句(例:`当前需求:SUV7座×1 + 商务车7座×1`) | **缺通用特殊诉求 + 文字备注** | + +wx 的要求:**两处都要同时展示「结构化车型语句 + 通用特殊诉求 + 文字备注」三块完整信息**。车管在 Step2 排车时最需要看到「要儿童座椅」「要中文司机」这类诉求,现在只能看到车型数量。 + +--- + +## 二、数据来源:一个接口、一份响应、三个字段 + +**两处同源**——Step1 和 Step2 用的是**同一个 order 对象**,来自同一次请求: + +``` +GET /admin/fleet/board/orders/{orderId} +Authorization: Bearer +(无请求体) +``` + +响应 `data` 里三个字段: + +| 字段 | 类型 | 是否可空 | 说明 | +|------|------|---------|------| +| `requirementFleetText` | `String` | **可为 null** | 后端拼好的**结构化车型整句**,如 `SUV7座×1 + 商务车7座×1` | +| `specialTags` | `List` | **恒为数组**(无诉求时 `[]`) | 通用特殊诉求,**值本身就是中文标签** | +| `requirementRemark` | `String` | **可为 null** | 文字备注 / 其他诉求 | + +> `requirements` 是 `requirementRemark` 的**兼容别名**(同值),新代码请用 `requirementRemark`。 + +### 测试环境实测(2026-08-11,26-3698) + +```json +{ + "code": 200, + "message": "成功", + "data": { + "requirementFleetText": "SUV7座×1 + 商务车7座×1", + "specialTags": ["含高速油费"], + "requirementRemark": "和法国飞行速度", + "requirements": "和法国飞行速度", + "plannerNote": null + } +} +``` + +--- + +## 三、三个字段的使用口径(重要) + +### 1. `requirementFleetText` —— **原样渲染,禁止自行拼装** + +整句由后端统一拼好,格式是 #5817 定的「车队组成写法」:**座位内联 + 加号连接**。 + +``` +SUV7座×1 + 商务车7座×1 +``` + +规则(后端已实现,前端不需要复刻): +- 缺座位时省略座位:`SUV×2 + 商务车7座×1` +- 车型未知时回退原始值 +- 需求为空或 `fleet` 为空 → 返回 **`null`**(整块不渲染) + +⚠️ **禁止**用 `vehicleSlots[].requiredVehicleTypeLabel` 或 `requiredVehicles` 自己聚合拼这句话——那些是**派单行的历史快照**,需求换版后是**陈旧值**(会显示成换版前的旧车型)。只有 `requirementFleetText` 是当前生效需求的权威值。 + +### 2. `specialTags` —— **直接渲染,不要查字典翻译** + +数组里的值**本身就是中文标签**(后端字典 `vehicle_special_demand` 的 `dict_value` 与 `dict_label` 有意保持一致),直接当 tag 渲染即可: + +``` +["儿童安全座椅", "大行李空间", "中文司机", "老司机(5年以上)", "含高速油费", "静音车型", "有WiFi"] +``` + +恒为数组,`length === 0` 时不渲染该块。 + +### 3. `requirementRemark` —— 自由文本 + +可能为 `null`,判 falsy 时不渲染。 + +--- + +## 四、前端要做的两件事 + +### 1. Step1「定制师/用车备注」区块 —— 补车型语句 + +在现有的 `plannerNote` / `requirementRemark` / `specialTags` 之外,增渲染 `order.requirementFleetText`(原样输出)。`null` 时不显示该行。 + +### 2. Step2 底部「当前需求」区块 —— 补诉求与备注 + +在现有的 `requirementFleetText` 之后,补上: +- `order.specialTags` → tag 列表(空数组不渲染) +- `order.requirementRemark` → 文本(null 不渲染) + +--- + +## 五、版本一致性(验收项,后端已保证) + +「两处展示的三块信息来自同一版当前生效需求,不串版本」这一条**后端天然满足**: + +三个字段全部出自**同一个当前生效需求对象**(`is_active=1` 且 version 最大的那一版),一次取数、一起下发。前端只要都从这份响应取值,就不可能串版本。 + +反之,如果前端从 `vehicleSlots` 或 `requiredVehicles` 自己聚合,就会踩到派单行的陈旧快照——见上文第三节的警告。 + +--- + +## 六、空态汇总 + +| 场景 | 后端返回 | +|------|---------| +| 无生效需求 / 需求不可达 | `requirementFleetText: null`、`specialTags: []`、`requirementRemark: null` | +| `fleet` 为空数组或解析失败 | `requirementFleetText: null` | +| 无特殊诉求 | `specialTags: []`(**不是 null**) | +| 无备注 | `requirementRemark: null`(不转空串) | + +整块判空规则:整句 `null` → 不渲染该行;tags `length === 0` → 不渲染;备注 falsy → 不渲染。**不要出现空白区块或字面量 `null`。** + +--- + +## 七、关联 + +- 原后端工单 #5848(已关单,判定为纯前端渲染缺口) +- 车型语句格式定义:#5817 / `11_5810b_需求车型语句改车队组成写法-修改接口-管理后台.md` +- 陈旧快照坑的成因:#5871(换版后派单行 `required_vehicle_type` 不刷新)