# fix: 小蒙马班期保存 maxParticipants 改为必填字段

> **服务**: hl-product-service-v2
> **PR**: #927
> **Issue**: #859
> **日期**: 2026-04-19
> **前端是否需要改动**: **需要改动**（之前允许不传或传 null，现在必须显式传数字；0=不限）

---

## 一、背景

测试环境反馈前端保存班期时缺传 `maxParticipants` 会收到模糊的"违反约束"报错，用户无法分辨是哪个字段出问题。

后端之前 `ScheduleSaveReqVO.maxParticipants` 只用 `@ApiModelProperty(required=true)` 做了文档标记，Bean Validation 层未强制校验，结果 null 一路打到 SQL 层才报错。

## 二、变更接口

| 方法 | 路径 | 变更类型 |
|------|------|---------|
| POST | `/admin/product/item/{id}/schedule` | 请求体字段校验收紧 |
| POST | `/admin/product/item/{id}/schedule/batch-create` | 同上 |

## 三、字段约束变化

| 字段 | 之前 | 现在 | 允许值 |
|------|------|------|--------|
| `maxParticipants` | 可不传 / null（后端兜底 0） | **必传** | 0=不限；>0=上限人数 |

## 四、错误响应示例

### 缺传 maxParticipants

```json
POST /admin/product/item/123/schedule
{
  "batchName": "五一特别团",
  "departureDate": "2026-05-01",
  "adultPrice": 5160,
  "childPrice": 4580
}

// 响应（之前是 "数据操作违反约束，请检查输入"，歧义）
{
  "code": 400,
  "message": "最大参与人数不能为空",
  "success": false
}
```

### 正常请求

```json
POST /admin/product/item/123/schedule
{
  "batchName": "五一特别团",
  "departureDate": "2026-05-01",
  "adultPrice": 5160,
  "childPrice": 4580,
  "maxParticipants": 30,    // 必填
  "maxRooms": 15            // 可选，默认取行程最少房间数
}
```

## 五、前端改动建议

1. **班期创建/编辑表单**：`maxParticipants` 输入框加前端必填校验，避免到后端才被拦下
2. **批量创建表单**：同上
3. **提示文案**：如果字段空值，提示"最大参与人数不能为空，0 表示不限人数"

## 六、兼容性

- 前端原本填写 0 或具体数字的调用方不受影响
- 前端如有"不填=不限"的历史 UX，需改成"显式填 0=不限"
- 后端 Service 层 null→0 兜底代码保留作为双保险，但实际不会再走到