---
schema: "hl-changelog/v2"
ticket: "5666"
title: "candidates 收费日注释对齐行为（空数组=全部收费预览）+ 子集收费回显口径锁定"
consumer: "admin"
author: "wx"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "not_required"
frontend_owner: ""
frontend_ref: ""
target_release: ""
verified_at: ""
status_note: "文档/口径对齐，无行为变更：#5643 起空数组已按全部收费预览，本次仅修正 ApiModelProperty 注释并补子集收费回显测试。矩阵派车司机回填与 ¥0 两症状经排查为前端问题，由协调台另行前端 changelog 分流。"
updated_at: "2026-08-08"
base: "dev-v3"
generated: "2026-08-07T21:00:00+08:00"
---

# candidates 收费日口径对齐（#5666 后端小加固）

## 背景

排查 #5666（矩阵派车司机回填/¥0）时发现 `POST /admin/fleet/assignments/candidates` 的 `chargeableServiceDates` 注释（"空数组表示全部免费"）与实际行为不一致：#5643 起空数组刻意按"全部服务日收费"预览（防止全免 ¥0 陷阱），且已有测试锁定。注释为 #5643 前残留。

## 变更内容

| 项 | 变更 |
|---|---|
| `AssignmentCandidateReqVO.chargeableServiceDates` 注释 | 对齐行为：不传或空数组均按全部服务日收费预览；明确与创建派单接口语义差异（创建接口空数组=全部免费且需 confirmAllServiceDatesFree+免费原因）；子集时仅子集收费、其余免费回显 |
| 测试 | 新增 `query_subsetChargeableServiceDates_marksOtherDaysFree`：锁定"子集收费日→仅子集 CALENDAR、其余 FREE ¥0、总价仅含子集"回显口径 |

**无任何运行时行为变更**（纯文档注解 + 测试）。

## 前端/调用方注意（既有行为复述，非新变更）

- candidates：`chargeableServiceDates` 不传/空数组 = 全部收费预览；传子集 = 仅子集收费，其余日 `assignmentPrice=0.00`/`source=FREE`（免费日 `calendarPrice=null`，`calendarPriceMissing` 仅收费日缺价时为 true）。
- 创建/改派写接口语义不变：空数组 = 全部免费，须 `confirmAllServiceDatesFree=true` + 免费原因。
- 矩阵派车司机回填（suggestedDriverId 消费）与部分收费日传入两个症状的修复见协调台前端 changelog。

## 关联 / 联系人

- 工单：https://git.1814.love:8443/wx/HL/issues/5666
- 后端：wx

## 变更接口或验证证据

### 接口契约

- `POST /admin/fleet/assignments/candidates` 请求字段 `chargeableServiceDates`：仅 Swagger 文档注释对齐既有行为，类型/约束/行为均无变更。

### 验证证据

- 定向：`AssignmentCandidateServiceTest` 49 全过（含新增子集收费用例与 #5643 空数组用例）；fleet spotless:check 通过。
- 全量：`mvn -pl hl-fleet-service -am verify`（日志见证据目录）。
- 网关：口径探针复测 candidates 空数组=全收费、子集=[首日]=首日 CALENDAR 其余 FREE（与锁定口径一致）。