docs: report fleet team layout and dark mode (#5131 )

chore(changelog): 标记前端已实现 #5236
修改原因：hl-ui changelog loop 需要把前端消费进度回写到契约源，避免领取、实现状态与实际交付脱节。修改内容：将 frontend_status 与已有 legacy frontend 同步为 implemented，记录负责人 hl-ui-codex，并关联 mmg/hl-ui@85851ad68d427e161d9342525af4567c1d108d5f；发布和验收字段保持不变。实际验证：回写器已校验目标文件、状态单调性、提交范围和 Front Matter 内容，提交只包含当前 changelog。 Frontend-Status: tools/mcp-api-sync/.changelog-repo/changelogs-v2/2026-07/24_5236_用车接送改由大交通默认驱动-修改接口-管理后台.md
2026-07-24 19:06:59 +08:00 · 2026-07-24 18:59:50 +08:00 · 2026-07-24 18:48:28 +08:00 · 2026-07-24 18:46:30 +08:00 · 2026-07-24 18:45:34 +08:00 · 2026-07-24 18:24:27 +08:00
@@ -0,0 +1,122 @@
+---
+schema: "hl-changelog/v2"
+ticket: "5236"
+title: "用车接送改由大交通默认驱动"
+consumer: "admin"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "implemented"
+frontend_owner: "hl-ui-codex"
+frontend_ref: "mmg/hl-ui@85851ad68d427e161d9342525af4567c1d108d5f"
+target_release: ""
+verified_at: ""
+status_note: "后端 PR #5241 已合并至 dev-v3（9578f78d5），order/fleet 已部署测试环境（b57ce915/0da3b9e6），双实例 internal 契约与网关汇总/列表/详情已验证；前端仍为 pending，待删除车辆接送开关并改用大交通摘要。"
+updated_at: "2026-07-24T10:59:50.144Z"
+base: "dev-v3"
+---
+
+# 用车接送改由大交通默认驱动
+
+## 关联
+
+- Issue: [wx/HL#5236](https://git.1814.love:8443/wx/HL/issues/5236)
+- Backend PR: [wx/HL#5241](https://git.1814.love:8443/wx/HL/pulls/5241)
+- Supersedes: [wx/HL#5193](https://git.1814.love:8443/wx/HL/issues/5193) 中“用车需求独立决定接送”的业务口径
+- 服务: `hl-order-service-v3`、`hl-fleet-service`
+- 前端仓库/分支: `mmg/hl-ui` / `v2.1`
+
+## 关键变化
+
+车辆安排不再让定制师重复选择“是否需要接机/接站”和“是否需要送机/送站”。
+接送结论由订单当前大交通批次直接决定：
+
+- `ARRIVAL` 批次聚合接机/接站。
+- `DEPARTURE` 批次聚合送机/送站。
+- 同方向任一批 `pickupRequired=true`，该方向为需要接送。
+- 同方向全部批次均为 `false`，该方向为客人自理。
+- 没有该方向批次时返回 `null`，表示未知。
+- 新建大交通未传 `pickupRequired` 时默认保存为 `true`；显式 `false` 保持客人自理。
+
+用车需求和订单调整中的 `pickupRequired`、`dropoffRequired` 字段暂不删除，继续兼容旧请求和回显，
+但不再覆盖实时大交通结论。
+
+## 变更接口
+
+| 方法 | 路径 | 变化 |
+|---|---|---|
+| `POST` | `/v3/admin/order/:id/transport-plan/add` | 新增大交通未传 `pickupRequired` 时默认 `true` |
+| `POST` | `/v3/admin/order/:id/transport-plan/batch` | 批量替换中每个未传值的批次默认 `true` |
+| `POST` | `/v3/admin/order/:id/transport-plan/:planId/edit` | 未传该字段时保留原值；显式值正常覆盖 |
+| `PUT` | `/v3/admin/order/:id/vehicle-requirement` | 两个接送字段改为兼容字段，不再是权威来源 |
+| `GET` | `/v3/admin/order/:id/adjustment/snapshot?scope=VEHICLE_REQ` | 继续通过 `vehicleTransportSummary` 返回大交通批次摘要 |
+| `POST` | `/v3/admin/order/:id/adjustment/submit` | `updates.vehicleRequirement` 中两个接送字段仅兼容接收 |
+| `GET` | `/admin/fleet/board/orders` | 卡片接送就绪状态改为按实时大交通方向聚合 |
+| `GET` | `/admin/fleet/board/orders/:orderId` | `transport.pickupRequired/dropoffRequired` 只取实时大交通聚合 |
+
+小程序内部大交通新增与批量接口使用相同默认规则，但本 changelog 的前端处理范围仅为管理后台。
+
+## 字段语义
+
+### 大交通请求 `pickupRequired`
+
+| 场景 | 入参 | 保存结果 |
+|---|---|---|
+| 新增单批/批量批次未传 | 字段省略或 `null` | `true` |
+| 新增单批/批量批次显式自理 | `false` | `false` |
+| 编辑既有批次未传 | 字段省略或 `null` | 保留原值 |
+| 编辑既有批次显式修改 | `true` / `false` | 按提交值覆盖 |
+
+数据库列仍为 `TINYINT(1) NOT NULL`，仅把新记录的数据库默认值从 `0` 改为 `1`，不回填或改写历史行。
+
+### 派单详情响应
+
+| 字段 | 类型 | 空值 | 说明 |
+|---|---|---|---|
+| `transport.pickupRequired` | `Boolean` | 无 ARRIVAL 批次时为 `null` | ARRIVAL 批次聚合 |
+| `transport.dropoffRequired` | `Boolean` | 无 DEPARTURE 批次时为 `null` | DEPARTURE 批次聚合 |
+| `transport.arrive/depart` | `Object/null` | 对应整团批次不存在时为 `null` | 到达/返程整团大交通 |
+| `transport.batches[]` | `Object[]` | 无分批时为空数组 | 分批大交通，保留方向、时间、站点和关联出行人 |
+
+## 前端处理
+
+1. 删除“调整订单 → 车辆安排”中的“是否需要接机/接站”和“是否需要送机/送站”两个开关。
+2. 提交用车需求或订单调整时，不再主动提交 `pickupRequired`、`dropoffRequired`。
+3. 车辆安排页直接展示 `vehicleTransportSummary.arrivals[]` 与 `departures[]`；继续使用其中的
+   `direction`、`time`、`station`、`transportNo`、`pickupRequired`、`pickupRemark` 和
+   `travelerNames[]`。
+4. 派单看板和详情不得回退到 `vehicleRequirement.pickupRequired/dropoffRequired`；
+   使用看板接送摘要与详情 `transport.pickupRequired/dropoffRequired`。
+5. 雪花 ID 仍按字符串处理，本次没有字段删除、类型变化或新增错误码。
+
+## 展示矩阵
+
+| 大交通场景 | 接机/接站 | 送机/送站 | 页面展示 |
+|---|---:|---:|---|
+| ARRIVAL 任一批需要，DEPARTURE 全部自理 | `true` | `false` | 分方向显示“平台接 / 客人自理” |
+| ARRIVAL 全部自理，DEPARTURE 任一批需要 | `false` | `true` | 分方向显示“客人自理 / 平台送” |
+| 同方向多批混合 | `true` | 按返程批次聚合 | 明细保留每个批次及关联出行人 |
+| 只有 ARRIVAL | 按到达批次聚合 | `null` | 返程显示未提供，不回退旧用车需求 |
+| 只有 DEPARTURE | `null` | 按返程批次聚合 | 到达显示未提供，不回退旧用车需求 |
+| 完全无大交通 | `null` | `null` | 显示“暂无接送机时间” |
+
+## 验证证据
+
+- Order 定向测试 57 项通过。
+- Fleet `BoardOrderServiceTest` 50 项通过。
+- 调整/需求/出行人兼容链路 357 项通过。
+- 调整快照完整字段断言 `AdjustmentServiceTest` 10 项通过。
+- `mvn -pl hl-order-service-v3 -am verify` 通过。
+- Order 模块 Surefire 汇总 6646 项，0 失败、0 错误、28 跳过。
+- `mvn -pl hl-fleet-service -am verify` 通过：Fleet 模块 2361 项，0 失败、0 错误、1 跳过。
+- Fleet `spotless:check` 与 `git diff --check` 通过。
+- OpenAPI/oasdiff: `not_configured`，使用源码字段/语义比对和测试作为 fallback。
+- Spring Cloud Contract: `not_configured`，使用 order-v3 生产者与 Fleet 消费者测试作为 fallback。
+- 后端 PR #5241 已合并，merge commit 为 `9578f78d5f0241db502d94b22283cbff0a351c53`。
+- 测试环境部署任务：order `b57ce915`、fleet `0da3b9e6`。
+- `order_transport_plan.pickup_required` 已验证为 `TINYINT(1) NOT NULL DEFAULT 1`，Flyway
+  `20260724.001` 执行成功。
+- order `8086/8186` 均通过 `/v3/internal/order/orders/:orderId/transport` 与批量看板上下文实测；
+  `true/false/null` 三态及 ARRIVAL/DEPARTURE 分方向聚合符合字段语义。
+- 测试网关 `/admin/fleet/board/summary`、`/orders`、`/orders/:orderId` 均返回成功；
+  详情连续 4 次通过，运行时证据为 `D:/work2/hl-workflow/.tmp/5236-gateway-evidence.json`。
@@ -121,10 +121,30 @@ user-service 在“车务管理”目录下新增子菜单：

 ## 前端必须修改的范围

+### 2026-07-24 页面复测反馈：列表列宽与暗色模式
+
+测试环境 `/fleet/teams` 页面已经能展示负责人和脱敏电话，但当前样式仍需前端修正，本反馈不涉及后端接口或字段变化：
+
+1. 表格列宽分配失衡。“车队名称”列占用过多空白，把“负责人 / 负责人电话”等核心联系人信息推到页面右侧，首屏信息密度过低。
+2. 暗色模式不能只替换页面背景。当前筛选区、表头、行分隔线、空值、状态标签和操作区的层级与对比度不足，部分边界难以辨认。
+3. 样式必须复用项目主题 token；禁止在本页写死仅适用于浅色模式的背景色、文字色或边框色。负责人电话仍只展示接口返回的脱敏值，样式调整不得绕过脱敏。
+
+#### 展示矩阵
+
+| 视口 / 主题 | 车队名称 | 负责人 / 负责人电话 | 其他列 | 验收表现 |
+| --- | --- | --- | --- | --- |
+| `>= 1440px`，浅色 | 弹性列，限制最大占比；超长省略并可查看完整名称 | 建议分别保留约 `120px / 140px`，左对齐 | 类型、付款方式、数量、排序、状态和操作按内容定宽 | 联系人紧邻业务字段，首屏无大段无意义空白 |
+| `>= 1440px`，暗色 | 同浅色列宽规则 | 同浅色列宽规则 | 使用暗色主题 token | 页面、筛选区、表头、数据行、状态标签和操作区层级清楚 |
+| `1024px - 1439px`，浅色/暗色 | 优先收缩并省略，不能无限占宽 | 不压缩为空或挤出主要阅读区 | 保留操作列可用宽度 | 联系人信息仍可直接阅读 |
+| `< 1024px`，浅色/暗色 | 设置表格最小宽度 | 保持可读宽度 | 允许横向滚动 | 不通过隐藏关键列或强行挤压完成适配 |
+
+空负责人和空电话统一显示 `—`。联系人文本左对齐；车辆数、排序、状态和操作居中。浅色与暗色模式都必须覆盖默认、悬停、聚焦、禁用和空数据状态；普通文本与背景建议至少达到 `4.5:1` 对比度，控件边界和状态提示应清晰可辨。
+
 ### 管理后台

 1. 新增 `src/api/fleet/teams.js` 和 `src/views/fleet/teams/index.vue`，完成车队分页、新增、编辑、启停和删除：
   - “车队管理”必须显示在“车务管理”目录内，不得作为一级菜单处理。
+   - 按上面的展示矩阵修正表格列宽和明暗主题样式，不能让“车队名称”列挤占联系人信息区域。
   - 仅 `vehicleCount === 0` 时展示/启用删除动作；调用删除接口后刷新列表。
   - 后端仍会独立校验车辆及未完结司机录入关联，返回 `601107` 时提示“请先完成车辆/司机转移”。
   - 编辑历史迁入车队时补齐负责人、负责人电话、付款方式和排序。
@@ -189,6 +209,8 @@ DELETE FROM sys_dict_type WHERE dict_type = 'fleet_attribution';
 ## 验收清单

 - [ ] 独立车队菜单可分页、新增、编辑、启停，付款方式与资源页选项一致。
+- [ ] `/fleet/teams` 在桌面端不再由“车队名称”列制造大段空白，负责人和脱敏电话位于首屏连续阅读区；窄屏按展示矩阵滚动而不是隐藏或挤压关键列。
+- [ ] `/fleet/teams` 的浅色、暗色模式均使用主题 token，筛选区、表头、数据行、空值、状态标签和操作区在默认/悬停/聚焦/禁用状态下层级清晰。
 - [ ] “车队管理”位于“车务管理”目录下；空车队可删除，非空车队删除入口禁用或明确提示后端 `601107`。
 - [ ] 历史迁入车队可通过编辑补齐负责人、负责人电话、付款方式和排序，保存时不允许提交空资料。
 - [ ] 车辆新增/编辑/筛选/详情/导入均使用动态车队，不再出现固定三项。
作者	SHA1	备注	提交日期
API Changelog Bot	1e2f39e76f	docs: report fleet team layout and dark mode (#5131 ) changelog-filename-gate / validate (pull_request) Successful in 1s 详情	2026-07-24 19:06:59 +08:00
Mimingguang	4d7d0d5e5c	chore(changelog): 标记前端已实现 #5236 changelog-filename-gate / validate (push) Failing after 2s 详情修改原因：hl-ui changelog loop 需要把前端消费进度回写到契约源，避免领取、实现状态与实际交付脱节。修改内容：将 frontend_status 与已有 legacy frontend 同步为 implemented，记录负责人 hl-ui-codex，并关联 mmg/hl-ui@85851ad68d427e161d9342525af4567c1d108d5f；发布和验收字段保持不变。实际验证：回写器已校验目标文件、状态单调性、提交范围和 Front Matter 内容，提交只包含当前 changelog。 Frontend-Status: tools/mcp-api-sync/.changelog-repo/changelogs-v2/2026-07/24_5236_用车接送改由大交通默认驱动-修改接口-管理后台.md	2026-07-24 18:59:50 +08:00
Mimingguang	93d013f1d4	chore(changelog): 标记前端已领取 #5236 changelog-filename-gate / validate (push) Failing after 1s 详情修改原因：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/24_5236_用车接送改由大交通默认驱动-修改接口-管理后台.md	2026-07-24 18:48:28 +08:00
wx	9891fee76e	Merge pull request #27 from docs/5236-transport-driven-transfer changelog-filename-gate / validate (push) Successful in 1s 详情 docs: publish transport-driven transfer handoff (#5236)	2026-07-24 18:46:30 +08:00
wx	7a3c0d70b7	docs: record deployment evidence (#5236 ) changelog-filename-gate / validate (pull_request) Successful in 2s 详情	2026-07-24 18:45:34 +08:00
wx	4877596de1	docs: hand off API contract (#5236 ) changelog-filename-gate / validate (pull_request) Failing after 1s 详情	2026-07-24 18:24:27 +08:00