docs(前端通知): 保险计划使用分类打标弹窗单选改多选——后端零改动同一端点

wx 看到 mmg 刚做的打标弹窗(单选 客人/司机/通用)要求改多选。
后端 usage_category 单值列三值恰好是{客人,司机}全部非空子集,BOTH=两个都选,
故纯前端改: 下拉换两个多选项(客人/司机),按映射表换算回同一 usageCategory 值,
PUT /v3/admin/insurance/plans/{planId}/usage-category 端点入参白名单一字不变。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

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

@@ -0,0 +1,60 @@
+# 【前端调整·管理后台】保险计划「使用分类」打标弹窗：单选下拉 → 客人/司机 多选 —— 后端零改动，仍调同一端点
+
+> 端：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`，且计划出现在「司机投保 → 保险计划」下拉里。