244 行
8.8 KiB
Markdown
244 行
8.8 KiB
Markdown
# 【前端对接·管理后台】派单看板团号与定制师下拉筛选
|
||
|
||
> 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 <fleet-admin-token>
|
||
```
|
||
|
||
请求无参数。车务管理员可直接调用，不需要切换成 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 <fleet-admin-token>
|
||
```
|
||
|
||
查询参数：
|
||
|
||
| 参数 | 类型 | 必填 | 规则 |
|
||
|------|------|------|------|
|
||
| `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. 不影响范围
|
||
|
||
- 不修改前端代码。
|
||
- 不改变派单看板现有状态枚举、排序与分页上限。
|
||
- 不改变订单详情、派单详情及矩阵派单的既有请求结构。
|
||
- 不新增数据库字段，不迁移历史数据。
|
||
|
||
## 9. 前端验收补充（2026-07-10）
|
||
|
||
> 前端跟进工单：[wx/hl-ui#5](https://git.1814.love:8443/wx/hl-ui/issues/5)
|
||
|
||
远端 `hl-ui v2.1` 已接入定制师下拉与 `getConsultantDisplayName()`，但列表卡片仍有条件渲染错误：
|
||
|
||
- `OrderRowList.vue` 将“定制师”放在 `vehicleAdvice` 区块内。
|
||
- 只有客户留言、没有车辆建议时，即使接口已返回 `consultantDisplayName`，卡片仍不会显示定制师。
|
||
- 定制师展示必须独立于 `vehicleAdvice/customerNote`：只要 `getConsultantDisplayName(o, '')` 非空，就显示“定制师 {昵称}”。
|
||
- 密集表格视图已经独立展示定制师，保持现状即可。
|
||
|
||
复现订单：
|
||
|
||
```json
|
||
{
|
||
"orderNo": "HL20260708144554930",
|
||
"teamNo": "26-0095",
|
||
"consultantId": "2021059720172838914",
|
||
"consultantDisplayName": "王骁",
|
||
"vehicleAdvice": null,
|
||
"customerNote": "Codex 造数：第 1 笔订单出行人资料已补全"
|
||
}
|
||
```
|
||
|
||
预期：列表卡片始终显示“定制师 王骁”。当前未显示属于前端渲染问题，后端字段和网关响应已验证正常。
|