changelog(v2): 车型价格日历三模式调价+节假日筛选+互斥校验 §9 全块说明 (PR #3714)

2026-06-12 10:59:04 +08:00 · 2026-06-12 10:59:04 +08:00 · 0cd5ee479e
--- a/changelogs-v2/2026-06/12_3714_车型价格日历三模式调价与节假日筛选-修改接口-管理后台.md
+++ b/changelogs-v2/2026-06/12_3714_车型价格日历三模式调价与节假日筛选-修改接口-管理后台.md
@ -0,0 +1,175 @@
+# 【修改接口·管理后台】车型价格日历——三模式调价(ABS/DELTA/PERCENT)+节假日筛选+互斥校验落地(§9 全块说明)
+
+> 服务:hl-fleet-service(8087) | 分支:dev-v3 | PR:#3714 | 已部署测试服并 22 项 API 实测通过(2026-06-12)
+> 契约出处:FLEET API §9.1-§9.4(文档已同 PR 更新至 v1.5.61) | 前端触发位:车管控制台「价格日历」页(page_pricing 原型 BulkPriceSheet)
+> 本文是价格日历**整块 4 接口的完整说明**(应后端要求全面同步),已上线功能 + 本次新增一并列出,前端可按本文直接对接。
+
+## ⚠️ 关键说明
+
+1. **完全向后兼容,已对接代码零改动**:本次新增字段全部可选。不传 `adjustMode` 默认 `ABS`(固定价),与原行为完全一致。
+2. **新增三模式调价**(本次 PR):`adjustMode` = `ABS`(设为固定价) / `DELTA`(在各日现价上加减金额) / `PERCENT`(按百分比调整)。`DELTA`/`PERCENT` 时 `dayPrice` 不需要传,改传 `adjustValue`。
+3. **DELTA/PERCENT 的基准价规则**:命中日已设价 → 用当日现价计算;未设价 → 用车型 `basePrice` 兜底;两者都没有 → **该日跳过不写**(不报错)。计算结果 < 0 一律按 `0.00` 落库。`PERCENT` 结果四舍五入保留两位(HALF_UP)。
+4. **新增仅节假日筛选**(本次 PR):`holidayOnly=true` 只设置节假日(节假日清单由后端 Nacos 配置维护,**当前为验证占位日期,业务法定节假日清单待车管确认后由后端配置**,前端无需关心数据源)。
+5. **三筛选互斥**(本次 PR,行为变更):`weekdayOnly` / `weekendOnly` / `holidayOnly` 同时传两个及以上 `true` → 返 `code=400` 参数错(此前是静默 0 命中返成功,**前端若有依赖旧静默行为的逻辑请注意**)。
+6. **金额字段两位小数**(本次 PR):`dayPrice`/`adjustValue` 传超过 2 位小数返 `code=400`。
+7. **防双击/并发**(本次 PR):三个写端点(批量设价/批量改状态/区间清除)都加了幂等(同参数 3 秒窗口重复提交返「…处理中,请勿重复提交」)+ 同车型并发互斥锁。前端连点按钮会收到 400 类提示,正常单次操作无感。
+8. **错误码口径勘正**:参数校验失败统一返业务码 **400**(HTTP 恒 200,错误信息在 `message`)。文档旧版写的 `400001` 为笔误,以 400 为准。
+9. 所有金额出参为**字符串**(如 `"800.00"`),雪花 ID 出参为字符串,前端勿当数字解析。
+
+## 1. 查询价格日历(月视图) — 无变更,完整契约
+
+`GET /admin/fleet/pricing-calendar/{vehicleModelId}?year=2026&month=3`
+
+| 参数 | 位置 | 类型 | 必填 | 说明 |
+|---|---|---|---|---|
+| vehicleModelId | path | string | 是 | 车型型号 ID(车型树 models[].id) |
+| year | query | number | 是 | 年份(2020-2100,越界返 400) |
+| month | query | number | 是 | 月份(1-12,越界返 400) |
+
+### 请求示例
+
+```bash
+curl -k "https://web.test.1814.love:9443/admin/fleet/pricing-calendar/2057378612593823745?year=2099&month=1" \
+  -H "Authorization: Bearer {token}"
+```
+
+### 响应示例(测试服实测)
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "year": 2099,
+    "month": 1,
+    "vehicleModelId": "2057378612593823745",
+    "modelName": "丰田普拉多",
+    "prices": [
+      { "date": "2099-01-01", "dayPrice": "800.00", "status": "AVAILABLE", "remark": "旺季价格" },
+      { "date": "2099-01-08", "dayPrice": "900.00", "status": "CLOSED",    "remark": "临时停租" }
+    ]
+  }
+}
+```
+
+| 出参字段 | 说明 |
+|---|---|
+| prices | **仅返回已设置价格的日期**(未设价日期不出现,空月返回空数组) |
+| prices[].dayPrice | 当日租赁价,**字符串**两位小数 |
+| prices[].status | 可售状态:`AVAILABLE`=可售 / `CLOSED`=关闭 |
+
+## 2. 批量设置价格 — 本次新增三模式/节假日/互斥,完整契约
+
+`PUT /admin/fleet/pricing-calendar/{vehicleModelId}`
+
+### 入参(body)
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| startDate | string | 是 | 开始日期 yyyy-MM-dd |
+| endDate | string | 是 | 结束日期,须 ≥ startDate 且总天数 ≤ 366 |
+| adjustMode | string | 否 | 🆕 调价模式:`ABS`=设为固定价 / `DELTA`=现价加减金额 / `PERCENT`=现价按百分比调;**不传默认 ABS**(向后兼容);非法值返 400 |
+| dayPrice | string | ABS 必填 | 当日租赁价(¥,≥0,两位小数)。**仅 ABS 模式必填且生效**,DELTA/PERCENT 不需要传 |
+| adjustValue | string | DELTA/PERCENT 必填 | 🆕 调整值:DELTA=加减金额(可负,如 `-100.00`) / PERCENT=百分比数值(`10`=+10%,`-5`=-5%)。两位小数 |
+| status | string | 否 | `AVAILABLE` / `CLOSED`,不传默认 AVAILABLE,非法值返 400 |
+| remark | string | 否 | 备注 |
+| weekdayOnly | boolean | 否 | 仅工作日(命中周末跳过) |
+| weekendOnly | boolean | 否 | 仅周末(命中工作日跳过) |
+| holidayOnly | boolean | 否 | 🆕 仅节假日(命中非节假日跳过,节假日清单后端 Nacos 维护) |
+| selectedWeekdays | number[] | 否 | 指定星期几(1=周一…7=周日),非空则只设命中星期 |
+| excludeDates | string[] | 否 | 排除日期列表(区间内这些日期不设置) |
+
+> ⚠️ `weekdayOnly`/`weekendOnly`/`holidayOnly` **互斥**,≥2 个同时 true 返 400「工作日/周末/节假日筛选不可同时启用」。
+
+### 请求示例 1——固定价(原有用法,完全不变)
+
+```bash
+curl -k -X PUT "https://web.test.1814.love:9443/admin/fleet/pricing-calendar/2057378612593823745" \
+  -H "Authorization: Bearer {token}" -H "Content-Type: application/json" \
+  -d '{"startDate":"2099-01-01","endDate":"2099-01-05","dayPrice":"800.00","remark":"旺季价格"}'
+```
+
+### 请求示例 2——🆕 全月工作日涨 100 元(DELTA)
+
+```bash
+curl -k -X PUT "https://web.test.1814.love:9443/admin/fleet/pricing-calendar/2057378612593823745" \
+  -H "Authorization: Bearer {token}" -H "Content-Type: application/json" \
+  -d '{"startDate":"2099-01-01","endDate":"2099-01-31","adjustMode":"DELTA","adjustValue":"100","weekdayOnly":true}'
+```
+
+### 请求示例 3——🆕 节假日统一上浮 15%(PERCENT + holidayOnly)
+
+```bash
+curl -k -X PUT "https://web.test.1814.love:9443/admin/fleet/pricing-calendar/2057378612593823745" \
+  -H "Authorization: Bearer {token}" -H "Content-Type: application/json" \
+  -d '{"startDate":"2099-01-01","endDate":"2099-01-31","adjustMode":"PERCENT","adjustValue":"15","holidayOnly":true}'
+```
+
+### 响应
+
+成功:`{ "code": 200, "message": "成功" }`(无 data)
+
+### 测试服实测数据点(可作前端联调预期)
+
+| 操作 | 结果 |
+|---|---|
+| ABS 800 后 DELTA +100 | 900.00 |
+| 900 后 PERCENT -10 | 810.00 |
+| DELTA +100 作用于未设价日(车型 basePrice=1000) | 1100.00 |
+| DELTA -99999(负穿) | 0.00(兜底) |
+| holidayOnly=true,区间 11 天含 1 个节假日 | 仅节假日 1 天写入 |
+| weekdayOnly+weekendOnly 同 true | code=400 |
+| adjustMode="FOO" / DELTA 缺 adjustValue / ABS 缺 dayPrice / dayPrice 三位小数 | code=400 |
+
+## 3. 批量修改状态 — 无变更(新增幂等防护),完整契约
+
+`PUT /admin/fleet/pricing-calendar/{vehicleModelId}/status`
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| startDate | string | 是 | 开始日期 yyyy-MM-dd |
+| endDate | string | 是 | 结束日期 |
+| status | string | 是 | `AVAILABLE` / `CLOSED`,非法值返 400 |
+| remark | string | 否 | 备注;**不传则保留各记录原备注** |
+
+只改区间内**已有记录**的状态(不影响价格,未设价日期不会凭空建记录)。
+
+```bash
+curl -k -X PUT "https://web.test.1814.love:9443/admin/fleet/pricing-calendar/2057378612593823745/status" \
+  -H "Authorization: Bearer {token}" -H "Content-Type: application/json" \
+  -d '{"startDate":"2099-01-01","endDate":"2099-01-31","status":"CLOSED","remark":"临时停租"}'
+```
+
+成功:`{ "code": 200, "message": "成功" }`
+
+## 4. 清除价格日历 — 无变更(新增幂等防护),完整契约
+
+`DELETE /admin/fleet/pricing-calendar/{vehicleModelId}?startDate=2099-01-01&endDate=2099-01-31`
+
+| 参数 | 位置 | 类型 | 必填 | 说明 |
+|---|---|---|---|---|
+| startDate | query | string | 是 | 开始日期 yyyy-MM-dd |
+| endDate | query | string | 是 | 结束日期 |
+
+软删除区间内该车型全部价格记录;删后**可重新设置同日价格**(测试服实测通过)。
+
+```bash
+curl -k -X DELETE "https://web.test.1814.love:9443/admin/fleet/pricing-calendar/2057378612593823745?startDate=2099-01-01&endDate=2099-01-31" \
+  -H "Authorization: Bearer {token}"
+```
+
+成功:`{ "code": 200, "message": "成功" }`
+
+## 5. 错误码表(§9 全块)
+
+| code | message | 触发场景 | 涉及端点 |
+|---|---|---|---|
+| 400 | (具体校验消息) | 参数校验失败:必填缺失/格式错/枚举非法/互斥冲突/超两位小数/year·month 越界 | 全部 |
+| 600500 | 日租价不能为负 | dayPrice < 0(防御兜底,正常会先被 400 拦) | §9.2 |
+| 600501 | 日期范围非法:开始日期不能晚于结束日期 | startDate > endDate | §9.2 |
+| 600502 | 日期范围不能超过 366 天 | 区间总天数(含首尾) > 366 | §9.2 |
+| 600503 | 车型型号不存在 | vehicleModelId 无效/已软删 | §9.1 / §9.2 / §9.3 |
+| 401 | 未登录 | token 缺失/过期 | 全部 |
+
+> §9.4 清除接口不校验车型存在性(按契约,清不存在车型的区间等于无操作返 200)。
+> HTTP 状态码恒 200,业务错误看 `code` 字段。