hl-api-changelog/changelogs-v2/2026-06/15_保险计划使用分类打标弹窗单选改多选-后端零改动同一端点-管理后台.md

【前端调整·管理后台】保险计划「使用分类」打标弹窗：单选下拉 → 客人/司机 多选 —— 后端零改动，仍调同一端点

端：hl-ui（保险管理 → 保险产品 → 计划「设置使用分类」弹窗）| 服务：hl-order-service-v3 AdminInsuranceController（SRS §9.17.3）| 后端零改动（端点/入参/白名单一字不变） | wx 2026-06-15 看到打标弹窗后要求「改为多选」 衔接：本条是 15_催办_保险计划使用分类司机可用打标UI仍缺… 的细化——打标弹窗你们已做出来（截图：单选下拉 客人/司机/通用），wx 要求把单选改成多选。

⚠️ 关键说明：为什么后端不用动（一句话）

后端 usage_category 是单值列，白名单只有三值 CUSTOMER / DRIVER / BOTH，而 BOTH（通用） 的语义就是「客人和司机都适用」。也就是说，这三值恰好是「客人 / 司机」两个基础项的全部非空组合：

多选勾了什么	等价的单值（提交给后端的 usageCategory）
只勾 客人	CUSTOMER
只勾 司机	DRIVER
客人 + 司机 都勾	BOTH
一个都没勾	❌ 不允许，至少选一个（保持必填，等同原来下拉不能为空）

所以「单选改多选」只是前端的展示形态变化：把原来的「客人/司机/通用」三选一下拉，换成「客人 / 司机」两个可多选的勾选项，提交前按上表换算成同一个 usageCategory 字符串。调的端点、请求体、白名单、错误码全部不变，后端无感。

1. 前端要改什么（只动这一个弹窗）

• 把「设置使用分类」弹窗里的单选下拉（客人/司机/通用 三选一）改成多选控件（多选下拉 / 复选框 / 多选 tag 均可），选项只留客人(CUSTOMER)、司机(DRIVER) 两个，去掉「通用 BOTH」这个显式选项（它被「两个都勾」替代）。
• 提交：按上表把勾选集合换算成单个 usageCategory 值，仍调原端点（见第 2 节），请求体不变。
• 回显（打开弹窗时根据当前 usageCategory 勾上）：
  • CUSTOMER → 勾【客人】
  • DRIVER → 勾【司机】
  • BOTH → 勾【客人】+【司机】
• 校验：至少勾一项才能提交（空集不允许），等价于原下拉的必填约束。

2. 端点不变（后端零改动，照旧调）

用途	方法 + 路径	入参 / 出参
打标（设使用分类）	PUT /v3/admin/insurance/plans/{planId}/usage-category	body {"usageCategory":"BOTH"}；白名单 CUSTOMER/DRIVER/BOTH，非法值返 540223；返回 Result<Void>
回显（读当前分类）	GET /v3/admin/insurance/products/all	每个产品 plans[].usageCategory ∈ CUSTOMER/DRIVER/BOTH，按上表反向勾选

planId 是雪花 id，当字符串透传（别转 JS Number 致科学计数法）。

3. 注意

• 不要新增/改后端字段：后端不接受数组，仍是单个字符串值；「两个都选」请前端换算成 BOTH 再提交，别传 ["CUSTOMER","DRIVER"]。
• 司机投保下拉口径不变：仍只列 usageCategory ∈ {DRIVER, BOTH} 的计划；客人端不收紧。改多选不影响这条口径——勾了「司机」（DRIVER 或 BOTH）的计划照常进司机下拉。
• 保游「同步产品」不覆盖本标注（增量护栏），放心标。

curl 实测（测试服网关 9443，真 admin token；端点未变，仅复用验证）

# 「客人+司机都勾」→ 提交 BOTH
curl -k -X PUT "https://api.test.1814.love:9443/v3/admin/insurance/plans/2054773833342451714/usage-category" \
  -H "Authorization: Bearer <adminToken>" -H "Content-Type: application/json" \
  -d '{"usageCategory":"BOTH"}'
# → {"code":200,"success":true}

# 回显：读各计划当前分类，按映射表反向勾选
curl -k "https://api.test.1814.love:9443/v3/admin/insurance/products/all" -H "Authorization: Bearer <adminToken>"
# → data[].plans[].usageCategory ∈ CUSTOMER/DRIVER/BOTH

验收

打开某计划「设置使用分类」弹窗 → 改为多选两个勾选项（客人 / 司机）→ 同时勾上两个 → 保存 → 重新打开弹窗，两个应都为勾选态；用 GET .../products/all 看该计划 usageCategory 应为 BOTH。只勾「司机」时该值为 DRIVER，且计划出现在「司机投保 → 保险计划」下拉里。