From 0fa10a884607a4187c85ad52f4dcfa59711636a3 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Fri, 7 Aug 2026 20:54:29 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20candidates=E6=94=B6=E8=B4=B9?= =?UTF-8?q?=E6=97=A5=E6=B3=A8=E9=87=8A=E5=AF=B9=E9=BD=90+=E5=AD=90?= =?UTF-8?q?=E9=9B=86=E6=94=B6=E8=B4=B9=E5=9B=9E=E6=98=BE=E9=94=81=E5=AE=9A?= =?UTF-8?q?=EF=BC=88#5666=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...对齐行为加子集收费回显锁定-修改接口-管理后台.md | 57 +++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 changelogs-v2/2026-08/07_5666_candidates收费日注释对齐行为加子集收费回显锁定-修改接口-管理后台.md diff --git a/changelogs-v2/2026-08/07_5666_candidates收费日注释对齐行为加子集收费回显锁定-修改接口-管理后台.md b/changelogs-v2/2026-08/07_5666_candidates收费日注释对齐行为加子集收费回显锁定-修改接口-管理后台.md new file mode 100644 index 0000000..f67b424 --- /dev/null +++ b/changelogs-v2/2026-08/07_5666_candidates收费日注释对齐行为加子集收费回显锁定-修改接口-管理后台.md @@ -0,0 +1,57 @@ +--- +schema: "hl-changelog/v2" +ticket: "5666" +title: "candidates 收费日注释对齐行为（空数组=全部收费预览）+ 子集收费回显口径锁定" +consumer: "admin" +author: "wx" +change_type: "修改接口" +backend_status: "deployed" +gateway_status: "verified" +frontend_status: "pending" +frontend_owner: "" +frontend_ref: "" +target_release: "" +verified_at: "" +status_note: "文档/口径对齐，无行为变更：#5643 起空数组已按全部收费预览，本次仅修正 ApiModelProperty 注释并补子集收费回显测试。矩阵派车司机回填与 ¥0 两症状经排查为前端问题，由协调台另行前端 changelog 分流。" +updated_at: "2026-08-07" +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（与锁定口径一致）。