From e7467fc9bb21f7bbbe5468ec9c5c728163afca3b Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Mon, 15 Jun 2026 11:15:41 +0800 Subject: [PATCH] =?UTF-8?q?docs(=E5=89=8D=E7=AB=AF=E9=80=9A=E7=9F=A5):=20?= =?UTF-8?q?=E6=8A=95=E4=BF=9D=E4=B8=8B=E5=8D=95=E9=80=89=E6=8B=A9=E5=8F=B8?= =?UTF-8?q?=E6=9C=BA=E4=B8=8B=E6=8B=89=E6=94=B9=E8=B0=83=E8=BD=BB=E9=87=8F?= =?UTF-8?q?=20/options=20=E7=AB=AF=E7=82=B9=20(PR=20#3817)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit /page 作类型搜索下拉太慢(全表seasonCounts聚合+N+1标签+常驻车反查); 新增 GET /admin/fleet/drivers/options 只返 driverId/name/脱敏phone,默认10上限20, keyword 姓名模糊/11位手机精确同 /page 语义;前端只换数据源。 Co-Authored-By: Claude Opus 4.8 --- ...择司机下拉改用轻量options端点-性能-管理后台.md | 54 +++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 changelogs-v2/2026-06/15_投保下单选择司机下拉改用轻量options端点-性能-管理后台.md diff --git a/changelogs-v2/2026-06/15_投保下单选择司机下拉改用轻量options端点-性能-管理后台.md b/changelogs-v2/2026-06/15_投保下单选择司机下拉改用轻量options端点-性能-管理后台.md new file mode 100644 index 0000000..33cb911 --- /dev/null +++ b/changelogs-v2/2026-06/15_投保下单选择司机下拉改用轻量options端点-性能-管理后台.md @@ -0,0 +1,54 @@ +# 【性能·管理后台】投保下单「选择司机」搜索下拉改调轻量端点 GET /admin/fleet/drivers/options（别再用 /page） + +> 端：hl-ui（保险订单 / 投保下单 → 人员类型=司机 → 「选择司机」搜索下拉）| 服务：hl-fleet-service `DriverController`（新增端点）| **后端已实现 + 部署测试服双实例 + 网关 9443 实测通过** | PR #3817 已合并 dev-v3 | 2026-06-15 +> 背景：wx 反馈「选择司机」搜索下拉太慢、需限 10 条。排查发现下拉复用了**重型档案分页列表** `/admin/fleet/drivers/page`，作类型搜索框（每敲字一次请求）开销过大。已新增专用轻量端点，请前端切过去。 + +## ⚠️ 关键说明：为什么 /page 慢（一句话） + +`/admin/fleet/drivers/page` 是司机**档案分页列表**，每次调用都干一堆下拉用不到的活： + +1. **全表 `GROUP BY season` 聚合**（seasonCounts，和返回几条无关，每次必跑全表）； +2. **N+1 标签查询**（每个司机单独查一次 tags）； +3. 常驻车反查 IN 查 + 每行 activeYears 解析。 + +下拉只需要「姓名 + 脱敏手机号」，上面全是浪费。**光传 `pageSize=10` 治标不治本**（全表 seasonCounts + N+1 标签每次还在跑）。 + +## 1. 前端要改什么（只换数据源） + +把「选择司机」搜索下拉的数据源**从 `/admin/fleet/drivers/page` 换成 `GET /admin/fleet/drivers/options`**。投保提交、保险计划下拉等其它逻辑都不变。 + +## 2. 新端点契约 + +| 项 | 内容 | +|---|---| +| 方法 + 路径 | `GET /admin/fleet/drivers/options` | +| 入参 | `keyword`（可选）：**姓名模糊**；输入**完整 11 位手机号**则**精确匹配**（手机号 AES 加密存储、密文等值，**不支持手机号模糊/前缀搜**——这就是搜索框提示「11 位手机号」的原因）。`limit`（可选）：默认 **10**，上限 **20**（超出封顶）。 | +| 出参 | `Result>`：`driverId`（雪花，**字符串**，别转 JS Number）/ `name` / `phone`（**脱敏** 135****5020）。**仅这三字段**，不再返 tags / 常驻车 / seasonCounts 等。 | +| 网关 | `/admin/fleet/**` 已覆盖，无需改网关。 | + +## 3. 注意 + +- 下拉口径与原 `/page` 一致：返回全部未软删司机（不按赛季/状态收紧），keyword 同语义。 +- 类型搜索框建议**输入时带 keyword 调用**（如防抖 300ms）；不传 keyword 也会返回最新 10 条作首屏候选。 +- 手机号要精确命中必须输满 11 位（密文等值），输前几位**搜不到**——属设计限制，请在交互上明确（提示已写「搜索司机姓名或11位手机号」即可）。 + +## curl 实测（测试服网关 9443，真 admin token） + +```bash +# 默认 10 条 +curl -k "https://api.test.1814.love:9443/admin/fleet/drivers/options?limit=10" \ + -H "Authorization: Bearer " +# → code=200, data 10 条: [{"driverId":"2065272153565020161","name":"巴特尔","phone":"135****5020"}, ...] + +# 姓名模糊 +curl -k "https://api.test.1814.love:9443/admin/fleet/drivers/options?keyword=巴" -H "Authorization: Bearer " +# → code=200, 4 条（含 巴特尔/135****5020） + +# limit 超限封顶 20 +curl -k "https://api.test.1814.love:9443/admin/fleet/drivers/options?limit=999" -H "Authorization: Bearer " +# → code=200, 20 条 +``` + +## 验收 + +「投保下单 → 司机 → 选择司机」下拉改调 `options` 后：键入姓名片段即时返候选（≤10 条，秒回，不再卡）；输入完整 11 位手机号能精确命中；选中后 driverId 正确带入投保提交。