diff --git a/changelogs-v2/2026-06/15_保险计划使用分类打标弹窗单选改多选-后端零改动同一端点-管理后台.md b/changelogs-v2/2026-06/15_保险计划使用分类打标弹窗单选改多选-后端零改动同一端点-管理后台.md new file mode 100644 index 0000000..f26ac12 --- /dev/null +++ b/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` | +| **回显(读当前分类)** | `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 " -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 " +# → data[].plans[].usageCategory ∈ CUSTOMER/DRIVER/BOTH +``` + +## 验收 + +打开某计划「设置使用分类」弹窗 → 改为多选两个勾选项(客人 / 司机)→ 同时勾上两个 → 保存 → 重新打开弹窗,两个应都为勾选态;用 `GET .../products/all` 看该计划 `usageCategory` 应为 `BOTH`。只勾「司机」时该值为 `DRIVER`,且计划出现在「司机投保 → 保险计划」下拉里。