From 64c41a1aaeff2940710f7b11012d9e4b4c98c13b Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Fri, 12 Jun 2026 12:21:42 +0800
Subject: [PATCH] =?UTF-8?q?changelog(v2):=20=E4=BB=B7=E6=A0=BC=E6=97=A5?=
 =?UTF-8?q?=E5=8E=86=E8=81=9A=E5=90=88=E6=80=BB=E8=A7=88+=E5=A4=9A?=
 =?UTF-8?q?=E8=BD=A6=E5=9E=8B=E6=89=B9=E9=87=8F=E8=AE=BE=E4=BB=B7=E5=AF=B9?=
 =?UTF-8?q?=E9=BD=90=E5=8E=9F=E5=9E=8B=204=E2=86=926=20=E6=8E=A5=E5=8F=A3?=
 =?UTF-8?q?=20(PR=20#3727)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...†è�šå�ˆæ€»è§ˆä¸Žå¤šè½¦åž‹æ‰¹é‡�设价-新增接å�£-管ç�†å�Žå�°.md | 124 ++++++++++++++++++
 1 file changed, 124 insertions(+)
 create mode 100644 changelogs-v2/2026-06/12_3727_价格日历��总览与多车型批�设价-新增接�-管���.md

diff --git a/changelogs-v2/2026-06/12_3727_价格日历��总览与多车型批�设价-新增接�-管���.md b/changelogs-v2/2026-06/12_3727_价格日历��总览与多车型批�设价-新增接�-管���.md
new file mode 100644
index 0000000..d170908
--- /dev/null
+++ b/changelogs-v2/2026-06/12_3727_价格日历��总览与多车型批�设价-新增接�-管���.md
@@ -0,0 +1,124 @@
+# �新增接�·管���】价格日历——§9.5 ��总览 + §9.6 多车型批�设价(对�原型,4→6 接�)
+
+> �务:hl-fleet-service(8087) | 分支:dev-v3 | PR:#3727 | 已部署测试�并 14 项 API 实测通过(2026-06-12)
+> 契约出处:FLEET API v1.5.62 §9.5/§9.6(文档站已�步) | �端触��:车管控制�「价格日历�整页(page_pricing 原型)
+> 背景:�端�馈现有价格日历接�拼�出原型页�(原型需�一次拿到全部车型×日期价格矩阵+节�日+统计,且批�改价是多车型多选)——本次补�,**原有 4 接�零�更**。
+
+## ⚠� 关键说明
+
+1. **整页数�一次拉�**:新增 `GET /admin/fleet/pricing-calendar/overview`,一次返回[大类→车型→区间价格矩阵+统计]+节�日列表+全局价格区间。「全部大类�月�片��大类月热力�季度/�年视图全部用它,**��需�按车型�个调 §9.1**。
+2. **节�日数��收��端**:格�上的「��标记请改用 overview 返回的 `holidays` 数组判断(原型里�端硬编�的 HOLIDAYS_2026 删掉),真相�=�端 Nacos �置,�年由�端维护��端零改动。
+3. **`holidays` ��请求区间内的节�日**:批�改价弹窗如果选择了超出当�已加载区间的日期(例如页�加载了 1-5 月�批改 10 月国庆),请按所选区间�拉一次 overview �节�日。
+4. **月�片统计�径**:`stats` 按**请求区间**统计(�/低/高)。一次拉多个月时,�月统计请�端从 `prices[]` 按月自�(原型本�就是�端算的,矩阵数�完备);`yearAvgPrice`(全年�)�端已算好直接用。
+5. **多车型批�改价**:新增 `PUT /batch-set`,vehicleModelIds 1-50 个多选,**任一车型 ID �存在整批拒�**(600503,消�列出全部缺失 ID),三模�(ABS/DELTA/PERCENT)/仅周末/仅节�日等与�车型 §9.2 完全��。整批一个事务,失败全回滚无�批。
+6. 600503 消��级为「车型型��存在: {ID}�(带具体 ID,错误���,按 code 判断的�端无影�)。
+7. 金�出�一律字符串(如 `"999.00"`),雪花 ID 字符串。
+
+## 1. §9.5 价格日历��总览
+
+`GET /admin/fleet/pricing-calendar/overview?startDate=2026-01-01&endDate=2026-05-31`
+
+| �数 | �置 | 类型 | 必填 | 说明 |
+|---|---|---|---|---|
+| startDate | query | string | 是 | 开始日期 yyyy-MM-dd |
+| endDate | query | string | 是 | 结�日期,须 ≥ startDate 且区间 ≤ 366 天(600501/600502) |
+
+### �应示例(测试�实测�剪)
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "data": {
+    "startDate": "2026-01-01",
+    "endDate": "2026-05-31",
+    "globalMinPrice": "950.00",          // 区间内全部车型最低日价(色阶图例下界;无任何设价=null)
+    "globalMaxPrice": "4500.00",         // 区间内全部车型最高日价(色阶图例上界)
+    "holidays": ["2026-01-01", "2026-02-16", "2026-02-17"],  // 区间内节�日(格�「��标记数��,��)
+    "types": [                            // 车辆大类(sortOrder ��,仅�有型�的大类)
+      {
+        "vehicleTypeId": "2057378611889180674",
+        "typeKey": "suv2",
+        "typeName": "SUV系列",
+        "icon": "",
+        "models": [
+          {
+            "vehicleModelId": "2057378612593823745",
+            "modelName": "丰田普拉多",
+            "basePrice": "1000.00",       // 车型基准价(� null)
+            "stats": {
+              "avgPrice": "1673.00",      // 请求区间内已设价日�价(HALF_UP 两�;无设价=null)
+              "minPrice": "1500.00",      // 区间最低
+              "maxPrice": "2250.00",      // 区间最高
+              "yearAvgPrice": "1293.00"   // startDate 所在自然年的全年�价(�片「全年��)
+            },
+            "prices": [                   // 区间内已设价日(��;未设价日�出现)
+              { "date": "2026-01-01", "dayPrice": "2250.00", "status": "AVAILABLE", "remark": "" }
+            ]
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+> 无设价的车型也会返回(prices=[]�stats 字段全 null),�端展示全部车型无需�调车型树。
+
+### curl
+
+```bash
+curl -k "https://web.test.1814.love:9443/admin/fleet/pricing-calendar/overview?startDate=2026-01-01&endDate=2026-05-31" \
+  -H "Authorization: Bearer {token}"
+```
+
+## 2. §9.6 多车型批�设价
+
+`PUT /admin/fleet/pricing-calendar/batch-set`
+
+### 入�(body) = §9.2 �车型全部字段 + vehicleModelIds
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| vehicleModelIds | string[] | 是 | 车型型� ID 列表(1-50 个,雪花字符串);任一�存在整批拒� 600503;��自动去�;元素�能为 null |
+| startDate / endDate | string | 是 | � §9.2(≤366 天) |
+| adjustMode | string | � | ABS=固定价 / DELTA=现价加� / PERCENT=百分比,默认 ABS |
+| dayPrice | string | ABS 必填 | � §9.2 |
+| adjustValue | string | DELTA/PERCENT 必填 | � §9.2(�负;PERCENT 如 10=+10%) |
+| status / remark / weekdayOnly / weekendOnly / holidayOnly / selectedWeekdays / excludeDates | — | � | 全部与 §9.2 ��(三筛选互斥返 400) |
+
+### 请求示例——原型「批�改价�弹窗:选 2 个车型春节区间上浮 15%
+
+```bash
+curl -k -X PUT "https://web.test.1814.love:9443/admin/fleet/pricing-calendar/batch-set" \
+  -H "Authorization: Bearer {token}" -H "Content-Type: application/json" \
+  -d '{"vehicleModelIds":["2057378612593823745","2064998010110029826"],
+       "startDate":"2026-02-16","endDate":"2026-02-22",
+       "adjustMode":"PERCENT","adjustValue":"15","holidayOnly":true}'
+```
+
+�功:`{ "code": 200, "message": "�功" }`
+
+### 错误�
+
+| code | 触�场景 |
+|---|---|
+| 400 | �数校验(ID 列表空/>50/� null�三筛选互斥��件必填�白���两��数) |
+| 600501 / 600502 | 日期顺� / 区间超 366 天 |
+| 600503 | 任一车型�存在,消�列出全部缺失 ID,**整批�执行** |
+
+### 防护(�端无感知,连点会收到�示)
+
+- ��数 3 秒幂等窗�(传�顺�/�� ID �影�判�)+ 批�请求间互斥�
+- 整批一个事务:任一失败全部回滚,�会出现"改了一�"
+
+## 3. 测试�实测数�点
+
+| �作 | 结果 |
+|---|---|
+| overview 2099-02 区间(� 2 车型设价) | 200,types 树/stats/globalMin-Max/prices 全正确 |
+| overview holidays(�置节�日区间) | `["2099-01-15"]` 与 Nacos �置一致 |
+| batch-set 2 车型 ABS 999 | 两车型全部写入,overview 立��� |
+| batch-set ��存在 ID | 600503 消�带缺失 ID,整批未执行 |
+| 区间 >366 / start>end | 600502 / 600501 |
+| 原 §9.1 �车型月视图 | 回归正常,零�更 |