From 0cd5ee479ec3e404ec263bb2cb8d00c07f2238ea Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Fri, 12 Jun 2026 10:59:04 +0800
Subject: [PATCH] =?UTF-8?q?changelog(v2):=20=E8=BD=A6=E5=9E=8B=E4=BB=B7?=
 =?UTF-8?q?=E6=A0=BC=E6=97=A5=E5=8E=86=E4=B8=89=E6=A8=A1=E5=BC=8F=E8=B0=83?=
 =?UTF-8?q?=E4=BB=B7+=E8=8A=82=E5=81=87=E6=97=A5=E7=AD=9B=E9=80=89+?=
 =?UTF-8?q?=E4=BA=92=E6=96=A5=E6=A0=A1=E9=AA=8C=20=C2=A79=20=E5=85=A8?=
 =?UTF-8?q?=E5=9D=97=E8=AF=B4=E6=98=8E=20(PR=20#3714)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...—¥åŽ†ä¸‰æ¨¡å¼�调价与节å�‡æ—¥ç­›é€‰-修改接å�£-管ç�†å�Žå�°.md | 175 ++++++++++++++++++
 1 file changed, 175 insertions(+)
 create mode 100644 changelogs-v2/2026-06/12_3714_车型价格日历三模�调价与节�日筛选-修改接�-管���.md

diff --git a/changelogs-v2/2026-06/12_3714_车型价格日历三模�调价与节�日筛选-修改接�-管���.md b/changelogs-v2/2026-06/12_3714_车型价格日历三模�调价与节�日筛选-修改接�-管���.md
new file mode 100644
index 0000000..627125a
--- /dev/null
+++ 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` 字段。