# 修复:产品「完成设计 / 上架审批」校验「可选车型」必填,草稿放行

**类型**: 后端 BUG 修复
**关联**: 工单 #1564 / PR #1569
**日期**: 2026-04-30
**前端处理者**: 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)