fix(product): 上架/完成设计校验可选车型 (#1564)

changelogs/2026-04/30_fix_product_vehicle-model-validation.md

@@ -0,0 +1,92 @@
+# 修复:产品「完成设计 / 上架审批」校验「可选车型」必填,草稿放行
+
+**类型**: 后端 BUG 修复
+**关联**: 工单 #1564 / PR #1569
+**日期**: 2026-04-30
+**前端处理者**: yst / mmg
+**影响范围**: 管理后台 CORE / CUSTOM 产品的「完成设计」按钮 + 「提交审核 / 直接上架」按钮
+
+---
+
+## 背景
+
+CORE / CUSTOM 类产品在「补充信息 → 车辆配置」中需要给出「可选车型」(supplement.vehicle_model_ids),否则线路下游派车流程拿不到车型选项,行程详情和报价也会缺数据。但此前后端在「完成设计」「上架」入口未做硬校验,导致出现「车型为空但已上架」的脏数据。
+
+GROUP(小蒙马)产品不走可选车型字段,本次跳过此校验。
+
+## 业务规则
+
+| 操作 | 路径 | 校验 |
+|---|---|---|
+| **保存草稿(补充信息)** | `PUT /admin/products/{id}/save-supplement` | **不校验**(允许中间状态空保存) |
+| **完成设计** | `POST /admin/products/{id}/complete-design` | **CORE / CUSTOM 必填**;GROUP 跳过 |
+| **提交上架审核 / 直接上架** | `POST /admin/products/{id}/toggle-publish` | **CORE / CUSTOM 必填**;GROUP 跳过 |
+| **下架 / 撤回 / 驳回回退** | 同上 | **不校验**(避免阻塞补救路径) |
+
+校验规则:`supplement.vehicle_model_ids` 与 `route_info.vehicle_model_id` **同时为空**才算未填(任一非空即可放行,兼容历史只填了 route_info 的产品)。
+
+## 后端改动
+
+- 新增校验落点:`completeDesign` + `togglePublish`(仅 SUBMIT_PUBLISH / DIRECT_PUBLISH 两个方向)入口处
+- 错误码 `ProductCoreErrorCode.PRODUCT_VEHICLE_MODEL_INCOMPLETE = 400405`
+- GROUP 产品 productType=GROUP 直接跳过
+- 草稿保存 `saveSupplement` 路径不动,允许 vehicle_model_ids 为空
+
+## 错误响应
+
+完成设计 / 提交上架时,可选车型为空返回:
+
+```jsonc
+HTTP 200 (业务错误码,非协议错误)
+{
+  "code": 400405,
+  "message": "请在「补充信息 → 车辆配置 → 可选车型」至少添加 1 个车型后再提交",
+  "data": null
+}
+```
+
+## 影响接口清单
+
+| 方法 | 路径 | 改动 |
+|------|------|------|
+| POST | `/admin/products/{id}/complete-design` | **新增** 400405 业务错误码 |
+| POST | `/admin/products/{id}/toggle-publish` | **新增** 400405 业务错误码 (仅 SUBMIT_PUBLISH / DIRECT_PUBLISH) |
+| PUT  | `/admin/products/{id}/save-supplement` | **不变**(允许空) |
+
+请求 / 响应签名(成功路径)完全不变,只是失败时多了一种 400405 业务码。
+
+## 前端要做的改动
+
+### 1. 草稿保存路径 — 无须改动
+
+补充信息保存仍允许 `vehicle_model_ids` 为空,前端可以保留中间保存的能力,不需要在保存按钮上加车型必填提示。
+
+### 2. 完成设计 / 提交上架按钮 — 处理 400405
+
+点击「完成设计」或「提交审核 / 直接上架」按钮后,如果后端返回 `code=400405`:
+
+- 直接弹出 `message` 文案(已经是给用户看的中文,可以原样展示):
+  ```
+  请在「补充信息 → 车辆配置 → 可选车型」至少添加 1 个车型后再提交
+  ```
+- 建议 UX:弹错后引导用户跳到「补充信息 → 车辆配置」Tab,聚焦「可选车型」字段,方便用户当场补齐再点完成设计/上架
+- GROUP(小蒙马)产品后端不会触发此错误码,前端无须额外区分
+
+### 3. 错误码字典
+
+| 业务码 | 含义 | 触发场景 |
+|---|---|---|
+| 400405 | 可选车型未填 | CORE / CUSTOM 产品完成设计 / 上架前预检 |
+
+(配套已在用的相关码:400404 行程未完整 — 见同日 `30_fix_product_itinerary-validate-on-publish.md`)
+
+## 不动
+
+- GROUP(小蒙马)产品完全不动,不走车型校验
+- `route_info.vehicle_model_id` 字段语义不动,仅作为兜底入参
+- 现存已上架但车型为空的历史产品不溯源处理(只在再次「完成设计/上架」时拦截)
+
+## 部署状态
+
+- 待 Deploy Panel 推送测试服 hl-product-service-v2 后生效
+- 正式环境暂未发布(等 dev → main release PR)