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

> 端：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；端点未变，仅复用验证）

```bash
# 「客人+司机都勾」→ 提交 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`，且计划出现在「司机投保 → 保险计划」下拉里。
