diff --git a/changelogs-v2/2026-07/54_4876_派单看板团号与定制师下拉筛选-管理后台.md b/changelogs-v2/2026-07/54_4876_派单看板团号与定制师下拉筛选-管理后台.md new file mode 100644 index 0000000..6fddb9c --- /dev/null +++ b/changelogs-v2/2026-07/54_4876_派单看板团号与定制师下拉筛选-管理后台.md @@ -0,0 +1,217 @@ +# 【前端对接·管理后台】派单看板团号与定制师下拉筛选 + +> Issue: [wx/HL#4876](https://git.1814.love:8443/wx/HL/issues/4876) +> PR: [wx/HL#4877](https://git.1814.love:8443/wx/HL/pulls/4877) +> 服务: `hl-fleet-service` / `hl-order-service-v3` / `hl-user-service` +> 日期: 2026-07-10 +> 影响范围: 车务派单看板卡片、团号筛选、定制师筛选下拉 + +## 1. 结论 + +- 派单看板仍使用分页接口,不改为一次性全量拉取。 +- 卡片新增/补齐 `teamNo`、`consultantId`、`consultantDisplayName`,数据以 order-v3 当前订单为准,不再依赖可能为空的历史派单快照。 +- `teamNo` 是包含匹配:输入 `7218` 可以命中完整团号 `26-7218`。 +- 定制师筛选改为下拉:先调用 `GET /admin/user/customizers`,选中后向看板传 `consultantId`,后端做 ID 精确筛选。 +- 下拉显示 `enterpriseWechatName`。已绑定企微时该字段是企微昵称;未绑定或企微数据缺失时,后端已经回退为 `username`。 +- 旧的 `plannerName/consultantName` 文本筛选仍兼容,但新页面不要继续使用自由输入框。 + +> 本文替代 `53_4871_车务提需求派单看板闭环契约-管理后台.md` 第 5 节中“定制师文本筛选”的前端实现方式;其余状态、分页、操作能力契约继续有效。 + +## 2. 接口清单 + +| # | 接口 | 方法 | 路径 | 变更类型 | +|---|------|------|------|----------| +| 1 | 定制师下拉 | GET | `/admin/user/customizers` | 复用既有接口 | +| 2 | 派单看板列表 | GET | `/admin/fleet/board/orders` | 新增 `consultantId`;强化团号与响应字段 | + +## 3. 定制师下拉 + +```http +GET /admin/user/customizers +Authorization: Bearer +``` + +请求无参数。车务管理员可直接调用,不需要切换成 admin 或定制师角色。 + +成功响应示例: + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": [ + { + "adminId": "2021059720172838914", + "username": "wx", + "enterpriseWechatName": "王骁", + "avatar": null + }, + { + "adminId": "2021059720172838999", + "username": "designer_test", + "enterpriseWechatName": "designer_test", + "avatar": null + } + ] +} +``` + +字段说明: + +| 字段 | 类型 | 说明 | +|------|------|------| +| `adminId` | string | 下拉 value;提交给看板的 `consultantId`。 | +| `username` | string | 登录用户名,仅用于兼容或辅助搜索。 | +| `enterpriseWechatName` | string | 下拉 label;企微昵称优先,未绑定企微时后端回退用户名,正常情况下不会空白。 | +| `avatar` | string/null | 头像,可不展示。 | + +前端绑定: + +```ts +const options = data.map(item => ({ + value: item.adminId, + label: item.enterpriseWechatName || item.username +})) +``` + +注意: + +- 接口不分页,包含持有 `CUSTOMIZER` 角色的历史定制师;即使账号已锁定/停用仍可能返回,便于筛选历史订单。 +- 已软删除账号不返回。 +- 前端不要再次按状态过滤下拉,也不要自己请求企微用户接口拼昵称。 + +## 4. 派单看板查询 + +```http +GET /admin/fleet/board/orders?page=1&pageSize=10&teamNo=7218&consultantId=2021059720172838914 +Authorization: Bearer +``` + +查询参数: + +| 参数 | 类型 | 必填 | 规则 | +|------|------|------|------| +| `page` | int | 否 | 默认 1。 | +| `pageSize` | int | 否 | 默认 10,最大 100;看板保留分页。 | +| `teamNo` | string | 否 | 团号包含匹配;`7218`、`26-7218` 均可命中 `26-7218`。 | +| `consultantId` | string | 否 | 定制师管理员 ID 精确匹配,值来自下拉 `adminId`。 | +| `plannerName` | string | 否 | 旧定制师姓名模糊筛选,兼容保留。 | +| `consultantName` | string | 否 | `plannerName` 的旧别名,兼容保留。 | + +成功响应示例: + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "page": 1, + "pageSize": 10, + "total": 1, + "records": [ + { + "id": "HL20260708144557879", + "orderId": "2074746796763996161", + "orderNo": "HL20260708144557879", + "teamNo": "26-7218", + "consultantId": "2021059720172838914", + "plannerName": "王骁", + "consultantName": "王骁", + "consultantDisplayName": "王骁", + "assignmentStatus": "unassigned", + "assignmentStatusLabel": "待派车", + "startDate": "2026-07-20", + "endDate": "2026-07-22", + "headcount": 2, + "requiredVehicles": [ + { + "vehicleType": "suv", + "categoryLabel": "SUV", + "seats": 5, + "count": 2 + } + ], + "canAssign": true, + "canRejectRequirement": true + } + ] + } +} +``` + +空结果响应: + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "page": 1, + "pageSize": 10, + "total": 0, + "records": [] + } +} +``` + +字段口径: + +| 字段 | 类型 | 说明 | +|------|------|------| +| `teamNo` | string/null | order-v3 当前团号;没有团号时为 null。 | +| `consultantId` | string/null | order-v3 当前负责定制师 ID。 | +| `consultantDisplayName` | string/null | 卡片首选展示名。 | +| `consultantName` | string/null | 兼容字段,与展示名同口径。 | +| `plannerName` | string/null | 旧字段,继续返回。 | + +## 5. 前端必须调整 + +1. 定制师筛选控件改为可搜索、可清空的下拉,不再使用文本输入框。 +2. 下拉 `value=item.adminId`,`label=item.enterpriseWechatName || item.username`。 +3. 查询看板时传 `consultantId`,不要把下拉文字传到 `consultantName/plannerName`。 +4. 卡片展示定制师读 `consultantDisplayName || consultantName || plannerName`。 +5. 卡片展示完整团号读 `teamNo`;搜索框可以直接传用户输入的团号片段。 +6. 保留分页组件,并按响应 `total/page/pageSize` 驱动。 +7. `adminId/consultantId/orderId` 均按字符串处理,禁止转 JavaScript Number。 + +## 6. 降级与兼容 + +- order-v3 正常时,团号和当前负责定制师使用 `order_main` 当前值,因此老派单快照缺字段、订单转单后名称过期的问题已消除。 +- order-v3 临时不可用且未传 `consultantId` 时,看板会回退 `fleet_assignment` 本地快照,页面仍可打开。 +- order-v3 临时不可用且传了 `consultantId` 时,后端无法可靠确认当前负责人,会返回空记录而不是错误匹配。 +- 旧前端继续传 `plannerName/consultantName` 不会立即报错,但应尽快切换到 ID 下拉。 + +## 7. 测试环境验证 + +验证网关:`https://api.test.1814.love:9443`,真实角色:`fleet_mgr_4760 / VEHICLE_MANAGER`。 + +```text +GET /admin/fleet/board/orders?page=1&pageSize=100&teamNo=7218 +→ 200;命中 HL20260708144557879;teamNo=26-7218 ✓ + +GET /admin/fleet/board/orders?page=1&pageSize=100&consultantId=2021059720172838914 +→ 200;3 条记录全部 consultantId 精确相等,包含目标订单 ✓ + +GET /admin/fleet/board/orders?page=1&pageSize=100&teamNo=7218&consultantId=2021059720172838914 +→ 200;2 条记录同时满足团号片段与定制师 ID,包含目标订单 ✓ + +GET /admin/user/customizers +→ 200;21 个下拉项;18 个企微昵称与 username 不同;wx 显示为王骁 ✓ + +目标订单卡片 +→ consultantId=2021059720172838914 +→ consultantDisplayName=王骁 +→ 与下拉 enterpriseWechatName 完全一致 ✓ +``` + +车务完整回归:121/121 通过,覆盖新建订单、补全出行人/大交通、提交用车需求、派单/确认/取消/换司机/驳回、矩阵、车辆、司机、价格、对账、保险与车管模板。 + +## 8. 不影响范围 + +- 不修改前端代码。 +- 不改变派单看板现有状态枚举、排序与分页上限。 +- 不改变订单详情、派单详情及矩阵派单的既有请求结构。 +- 不新增数据库字段,不迁移历史数据。