From 92ce44f6b44ac6a2444a81b4c1ea00744ea8ea1c Mon Sep 17 00:00:00 2001
From: jw <jinwei@1814.love>
Date: Thu, 24 Sep 2026 15:13:09 +0800
Subject: [PATCH] =?UTF-8?q?docs(changelog):=20#8219=20=E5=9B=A2=E7=BA=A7?=
 =?UTF-8?q?=E6=AD=A3=E5=BC=8F=E7=94=A8=E8=BD=A6=E9=9C=80=E6=B1=82=E6=9C=AA?=
 =?UTF-8?q?=E6=8F=90=E4=BA=A4=E6=88=B7=E9=98=BB=E6=96=AD=E4=B8=8E=E8=B1=81?=
 =?UTF-8?q?=E5=85=8D=E6=88=B7=E6=B8=85=E5=8D=95=EF=BC=88=E4=BF=AE=E6=94=B9?=
 =?UTF-8?q?=E6=8E=A5=E5=8F=A3=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 ...œ€æ±‚未æ��交户阻断与è±�å…�户清å�•-修改接å�£-管ç�†å�Žå�°.md | 710 ++++++++++++++++++
 1 file changed, 710 insertions(+)
 create mode 100644 changelogs-v2/2026-09/24_8219_团级正�用车需求未�交户阻断与��户清�-修改接�-管���.md

diff --git a/changelogs-v2/2026-09/24_8219_团级正�用车需求未�交户阻断与��户清�-修改接�-管���.md b/changelogs-v2/2026-09/24_8219_团级正�用车需求未�交户阻断与��户清�-修改接�-管���.md
new file mode 100644
index 00000000..a7282c91
--- /dev/null
+++ b/changelogs-v2/2026-09/24_8219_团级正�用车需求未�交户阻断与��户清�-修改接�-管���.md
@@ -0,0 +1,710 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8219"
+title: "团级正�用车需求：有户能交没交时�存被拒（809123），交�了的户列为��户"
+consumer: "admin"
+author: "jw(GIT)"
+change_type: "修改接�"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "新增错误� 809123；三个接�新增��户清�字段；809122 / 809121 ��报��户"
+updated_at: "2026-09-24"
+base: "dev-v3"
+---
+
+# order-v3: 团级正�用车需求——未�交户阻断�存���户显�列出
+
+> **存放目录**: `changelogs-v2/{YYYY-MM}/`
+>
+> **�务**: hl-order-service-v3 (端� 8007)
+> **PR**: #8317�#8319
+> **Issue**: #8219
+> **日期**: 2026-09-24
+> **影�范围**: 管���「团期详情 → 用车 Tab�的正�用车需求编辑弹窗（�存�自动汇总）与整团确认预检横幅
+
+---
+
+## ⚠� 关键�化
+
+1. **�存正�用车需求多一个拒�� 809123**：团里有户「本�以�交行程用车需求�没�交�时，`PUT .../vehicle-requirement` 直接拒�，报文�户列出团�（无团�回�订��）。改��存完全�看户侧有没有�交，而 809109 ��求�个需车户�日被分组覆盖，���能把没�交的户也编进分组�替它编车型人数�能存下去。
+2. **三个接�新增��户清�**：`exemptHouseholds`（�存�应�自动汇总�应）/ `vehicleExemptHouseholds`（整团确认预检）。��户是「此刻在系统里�交�了行程用车需求�的户，它们**�阻断**�存 / 汇总 / 确认，也**��求被分组覆盖**，但会�户连�原因列出�，�端需�展示。
+3. **809122（预检 / 整团确认）与 809121（自动汇总）��报��户**：三处判定��，��户�出现在��户清�里，��被当�「未�交�。
+4. **809109 �对已�交户判覆盖**：没有行程用车需求的户（无论未�交还是��）都��被�求编进分组。
+
+---
+
+## 一�背景
+
+团期详情页用车 Tab 上，管�员�存团级正�行程用车需求时，系统�检查�户有没有�交行程用车需求；�时 809109 �求�个需车户的出�～返回日都被�个分组覆盖。结果是有户没�交时，管�员为了存下去�能把那户也编进分组�替它填车型人数，这份编出�的数���会下�给车务。
+
+本次把「户有没有�交�收�一份判定，三类户分别处�：
+
+| 户的类别 | 判定 | �存（PUT） | 整团确认预检 | 自动汇总 |
+|------|------|------|------|------|
+| 已�交 | 有 active 行程用车需求 | 照常�与 809109 覆盖 | 照常 | 照常进�稿 |
+| 未�交 | 订�定制中，且（团期未冻结 或 该户最新行程用车需求被打回） | **809123 拒�** | 809122 | 809121 |
+| �� | 订��在定制中；或团期已过资�准备�该户未被打回 | �阻断，列入 `exemptHouseholds` | �报 809122，列入 `vehicleExemptHouseholds` | �报 809121��进�稿，列入 `exemptHouseholds` |
+
+---
+
+## 二��更接�清�
+
+| # | 接� | 方法 | 路径 | �更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | �存团期正�用车需求 | PUT | `/v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement` | 新增错误� + 出�新增字段 | 新增 809123；�应新增 `exemptHouseholds` |
+| 2 | GB-ADM-012 整团确认需求缺失预检 | GET | `/v3/admin/order/group-batch/{groupBatchId}/requirement/confirm-check` | 出�新增字段 + �值�径�更 | 新增 `vehicleExemptHouseholds`；809122 ��报��户 |
+| 3 | 自动汇总正�用车需求�稿 | GET | `/v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement/aggregate-draft` | 出�新增字段 + �值�径�更 | 新增 `exemptHouseholds`；809121 ��报��户���户�进�稿 |
+
+---
+
+## 三�接�详情
+
+### 1. �存团期正�用车需求 `PUT /v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement`
+
+**VO**: `GroupVehicleRequirementSaveReqVO → GroupVehicleRequirementRespVO`
+
+#### 使用场景
+
+用车 Tab「编辑正�用车需求�弹窗点�存时调用，全�替�整份团级正�用车需求（主表备注 + 全部乘车分组 + 全部�日行）。本次新增：团里存在「本�以�交�没�交�行程用车需求的户时，�存被 809123 拒�；�交�了的户（��户）�阻断�存，在�应 `exemptHouseholds` 里列出。鉴�走 `group-batch:demand:confirm`，仅「资�准备中�阶段��存。
+
+#### 入�
+
+| 字段 | �置 | 类型 | 必填 | 约� | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long | ✅ | 雪花 ID，团期��主键 | 团期 ID |
+| version | Body | Integer | � | 首次�存传 `null`；之�必须回传上次�应的 `version` | �观�版本� |
+| remark | Body | String | � | — | 整份备注 |
+| groups | Body | Array | ✅ | �能为 `null`；空数组�法（有需车户时会被 809103 拒） | 全部乘车分组 |
+| groups[].groupId | Body | Long | � | 沿用已有分组时必须回传 | 分组主键 |
+| groups[].groupCode | Body | String | ✅ | �空；�一份内���；已有分组�得改� | 分组键 |
+| groups[].vehicleType | Body | String | ✅ | �空；须在车队车型字典内 | 车型 |
+| groups[].serviceStartDate | Body | String | ✅ | `yyyy-MM-dd` | 本组�务开始日 |
+| groups[].serviceEndDate | Body | String | ✅ | `yyyy-MM-dd`，�早于开始日 | 本组�务结�日 |
+| groups[].seats | Body | Integer | � | 与 `count` �填�空 | �车座�数 |
+| groups[].count | Body | Integer | � | 与 `seats` �填�空 | 车辆数 |
+| groups[].specialTags | Body | Array | � | 字典 `vehicle_special_demand` 编� | 特殊诉求标签 |
+| groups[].remark | Body | String | � | — | 分组备注 |
+| groups[].days | Body | Array | ✅ | �空；须正好铺满本组�务日范围 | �日用车明细 |
+| groups[].days[].tripDate | Body | String | ✅ | `yyyy-MM-dd` | 行程日 |
+| groups[].days[].headcount | Body | Integer | ✅ | ��于当日�员户数 | 当日用车人数 |
+| groups[].days[].memberOrderIds | Body | Array | ✅ | �空；须全属本团在团户 | 当日乘车�订� ID |
+
+#### 出� `Result<GroupVehicleRequirementRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data.requirementId | String | 正�需求主键 |
+| data.groupBatchId | String | 团期��主键 |
+| data.status | String | �存��为 `DRAFT` |
+| data.version | Integer | 新版本�，下次�存回传 |
+| data.remark | String | 整份备注 |
+| data.confirmedBy | String | DRAFT 时为 `null` |
+| data.confirmedAt | String | DRAFT 时为 `null` |
+| data.groups[] | Array | �存�的全部乘车分组（字段与改�一致） |
+| data.exemptHouseholds[] | Array | **本次新增**：本次�存时被��的在团需车户，按 orderId ��；无��户时为空数组 `[]` |
+| data.exemptHouseholds[].orderId | String | �订� ID |
+| data.exemptHouseholds[].orderNo | String | �订�� |
+| data.exemptHouseholds[].reason | String | ��原因�；本接��会出现 `ORDER_NOT_CUSTOMIZING`，�六.5 |
+| data.exemptHouseholds[].reasonName | String | ��原因中文�（�端下�） |
+
+`GroupVehicleRequirementRespVO` 的其余字段（�车刷新观测� `planRefreshState` 等）与改�一致。**`exemptHouseholds` �在�存�应里填充**；�一个 VO 在读接�（`GET .../vehicle-requirement`）�撤回��车��开的�应里该字段为 `null`，表示「这个�应�回答��问题�。
+
+#### 请求示例
+
+TEST 实测往返（团期 `2103018513226752001`，三户：两户已�交�一户待支付未�交）：
+
+```json
+{
+  "version": null,
+  "remark": "#8219 AC-5 �功用例(ii)",
+  "groups": [
+    {
+      "groupCode": "BUS",
+      "vehicleType": "bus",
+      "serviceStartDate": "2026-12-11",
+      "serviceEndDate": "2026-12-13",
+      "days": [
+        { "tripDate": "2026-12-11", "headcount": 4, "memberOrderIds": ["2103018513088339969", "2103018515806265346"] },
+        { "tripDate": "2026-12-12", "headcount": 4, "memberOrderIds": ["2103018513088339969", "2103018515806265346"] },
+        { "tripDate": "2026-12-13", "headcount": 4, "memberOrderIds": ["2103018513088339969", "2103018515806265346"] }
+      ]
+    }
+  ]
+}
+```
+
+#### �应示例
+
+�一次请求的真实�应（�车刷新观测�字段�略，与改�一致）：
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "data": {
+    "requirementId": "2103018859139407874",
+    "groupBatchId": "2103018513226752001",
+    "status": "DRAFT",
+    "version": 1,
+    "remark": "#8219 AC-5 �功用例(ii)",
+    "confirmedBy": null,
+    "confirmedAt": null,
+    "groups": [
+      {
+        "groupId": "2103018859143602177",
+        "groupCode": "BUS",
+        "vehicleType": "bus",
+        "vehicleTypeName": "大巴系列",
+        "serviceStartDate": "2026-12-11",
+        "serviceEndDate": "2026-12-13",
+        "days": [
+        { "tripDate": "2026-12-11", "headcount": 4, "memberOrderIds": ["2103018513088339969", "2103018515806265346"], "memberOrderCount": 2 },
+        { "tripDate": "2026-12-12", "headcount": 4, "memberOrderIds": ["2103018513088339969", "2103018515806265346"], "memberOrderCount": 2 },
+        { "tripDate": "2026-12-13", "headcount": 4, "memberOrderIds": ["2103018513088339969", "2103018515806265346"], "memberOrderCount": 2 }
+        ]
+      }
+    ],
+    "exemptHouseholds": [
+      {
+        "orderId": "2103018517358141442",
+        "orderNo": "HL20260924150741326",
+        "reason": "ORDER_NOT_CUSTOMIZING",
+        "reasonName": "订��在定制中"
+      }
+    ]
+  },
+  "traceId": null,
+  "success": true
+}
+```
+
+#### 空数� / �级�应
+
+没有��户时 `exemptHouseholds` 是空数组，�是 `null`（TEST 实测团期 `2103018935689650178`，两户都已�交）；其余结构�上：
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "data": {
+    "groupBatchId": "2103018935689650178",
+    "status": "DRAFT",
+    "version": 1,
+    "exemptHouseholds": []
+  },
+  "traceId": null,
+  "success": true
+}
+```
+
+#### 错误�应
+
+团里有户本�以�交�没�交行程用车需求（本次新增，测试环境实测原文）：
+
+```json
+{
+  "code": 809123,
+  "message": "团期「第30期 T29 #7441 AC-29 batch6�有 2 户尚未�交行程用车需求，暂�能�存正�用车需求：26-0674�26-7797",
+  "data": null,
+  "traceId": null,
+  "success": false
+}
+```
+
+需车户存在但一个分组都没�交（改�已有）：
+
+```json
+{
+  "code": 809103,
+  "message": "本团存在需�用车的�订�，至少��交一个乘车分组",
+  "data": null,
+  "traceId": null,
+  "success": false
+}
+```
+
+| 错误� | 触��件 |
+|------|------|
+| 809123 | **新增**：存在未�交户；报文列出户数与�户团�（无团�回�订��），�� orderId |
+| 809103 | 需车户�空但 `groups` 为空数组 |
+| 809101 / 809102 / 809104~809110 / 809115 | 与改�一致 |
+| 589501 | 团期阶段�是「资�准备中� |
+
+#### 业务边界
+
+- 判�：阶段守� → �车�守�（809115）→ �状�守�（809101）→ �观�（809102）→ 分组改�守�（809104）→ **未�交户阻断（809123）** → 六��日校验（809103~809110）。809123 排在�日校验之�：有户没交时先让��去催定制师，而�是先看到�户�天没被覆盖。
+- 809123 与 809103 ~ 809110 一样是整笔零写入：拒�时库里的正�需求版本��。
+- 本接��在「资�准备中��调，这个阶段定制师都能�交需求，所以本接�的��户�有「订��在定制中�一�，`exemptHouseholds[].reason` �会是 `ORDER_NOT_CUSTOMIZING`。
+- ��户��求被任何分组覆盖（809109 �对已�交户判），也�以被编进分组（�会报错）。
+- 全团需车户都是��户时，`groups` 为空数组�报 809103；分组的 `memberOrderIds` ��能为空，这�团按现行�径�么把��户编进分组，�么走整团�车（`POST .../vehicle-requirement/waive`）。
+- 809123 报文里�列团�（团�为空时列订��），�带雪花 orderId，与 809121 / 809112 / 809114 �一�径；�端展示报文��，��从报文里解�订��。
+
+---
+
+### 2. GB-ADM-012 整团确认需求缺失预检 `GET /v3/admin/order/group-batch/{groupBatchId}/requirement/confirm-check`
+
+**VO**: `Path �数 → GroupBatchRequirementCheckRespVO`
+
+#### 使用场景
+
+管���点「整体确认需求�之�调用，把按钮置�并摊开缺失清�。它与 `POST .../requirement/confirm` 共用�一套校验。本次新增 `vehicleExemptHouseholds`：列出�交�了行程用车需求�因而�报 809122 的户；809122 �报「本�以�交�没�交�的户。鉴�走 `group-batch:demand:confirm`。
+
+#### 入�
+
+| 字段 | �置 | 类型 | 必填 | 约� | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long | ✅ | 雪花 ID，团期��主键 | 团期 ID；无 Query�无 Body |
+
+#### 出� `Result<GroupBatchRequirementCheckRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data.groupBatchId | String | 团期��主键 |
+| data.batchStatus | String | 团期当�状�� |
+| data.ready | Boolean | �整体确认：`missing` 空且 `vehicleMissing` 空且阶段�确认。��户�影� `ready` |
+| data.missing[] | Array | �宿缺失清�（与改�一致） |
+| data.vehicleWaived | Boolean | 整团�车时为 `true` |
+| data.vehicleMissing[] | Array | 车侧缺失清�（结构与改�一致） |
+| data.vehicleMissing[].reason | String | `HOUSEHOLD_REQUIREMENT_NOT_SUBMITTED`（809122）**本次起�报未�交户，��报��户** |
+| data.vehicleMissing[].orderId | String | 涉�的�订� ID；团级�目为 `null` |
+| data.vehicleMissing[].orderNo | String | �订��；团级�目为 `null` |
+| data.vehicleMissing[].detail | String | 人�报文 |
+| data.vehicleExemptHouseholds[] | Array | **本次新增**：车侧��户，按 orderId ��；`vehicleWaived=true` 或无��户时为空数组 `[]` |
+| data.vehicleExemptHouseholds[].orderId | String | �订� ID |
+| data.vehicleExemptHouseholds[].orderNo | String | �订�� |
+| data.vehicleExemptHouseholds[].reason | String | `ORDER_NOT_CUSTOMIZING` 或 `REQUIREMENT_FROZEN`，�六.5 |
+| data.vehicleExemptHouseholds[].reasonName | String | ��原因中文� |
+| data.groupVehicleRequirementId | String | 活跃正�用车需求主键；无则 `null` |
+| data.groupVehicleRequirementStatus | String | 活跃正�用车需求状�；无则 `null` |
+| data.groupVehicleRequirementVersion | Integer | 活跃正�用车需求版本�；无则 `null` |
+
+其余字段（`batchStatusName`�`checkedResourceTypes`�`transferSubmitEnabled`�`transferDeclaredWithoutRequirement` 等）与改�一致。
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch/2099927193172815873/requirement/confirm-check HTTP/1.1
+Host: <网关地�>
+Authorization: Bearer <admin token>
+```
+
+#### �应示例
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "data": {
+    "groupBatchId": "2099927193172815873",
+    "batchStatus": "RESOURCE_PREPARING",
+    "ready": false,
+    "missing": [],
+    "vehicleWaived": false,
+    "vehicleMissing": [
+      {
+        "reason": "HOUSEHOLD_REQUIREMENT_NOT_SUBMITTED",
+        "groupCode": null,
+        "tripDate": null,
+        "orderId": "2099927193143455746",
+        "orderNo": "HL20260916022352215",
+        "detail": "该户尚未�交行程用车需求，请先让定制师�交��整团�交车务"
+      },
+      {
+        "reason": "HOUSEHOLD_REQUIREMENT_NOT_SUBMITTED",
+        "groupCode": null,
+        "tripDate": null,
+        "orderId": "2099927202878435329",
+        "orderNo": "HL20260916022354533",
+        "detail": "该户尚未�交行程用车需求，请先让定制师�交��整团�交车务"
+      }
+    ],
+    "vehicleExemptHouseholds": [
+      {
+        "orderId": "2099927222981734402",
+        "orderNo": "HL20260916022359336",
+        "reason": "ORDER_NOT_CUSTOMIZING",
+        "reasonName": "订��在定制中"
+      },
+      {
+        "orderId": "2099927233643655170",
+        "orderNo": "HL20260916022401707",
+        "reason": "ORDER_NOT_CUSTOMIZING",
+        "reasonName": "订��在定制中"
+      }
+    ],
+    "groupVehicleRequirementId": "2099927498304131073",
+    "groupVehicleRequirementStatus": "DRAFT",
+    "groupVehicleRequirementVersion": 4
+  },
+  "traceId": null,
+  "success": true
+}
+```
+
+#### 空数� / �级�应
+
+整团�车或没有��户时，`vehicleExemptHouseholds` 为空数组（�是 `null`）：
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "data": {
+    "groupBatchId": "2099927193172815873",
+    "batchStatus": "RESOURCE_PREPARING",
+    "ready": true,
+    "missing": [],
+    "vehicleWaived": false,
+    "vehicleMissing": [],
+    "vehicleExemptHouseholds": []
+  },
+  "traceId": null,
+  "success": true
+}
+```
+
+#### 错误�应
+
+```json
+{
+  "code": 589500,
+  "message": "团期�存在",
+  "data": null,
+  "traceId": null,
+  "success": false
+}
+```
+
+无需求确认��：
+
+```json
+{
+  "code": 589507,
+  "message": "无�作��（当�角色未授予团期��，或该团期�在您�下）",
+  "data": null,
+  "traceId": null,
+  "success": false
+}
+```
+
+#### 业务边界
+
+- 本接��读，�写库，�安全��调用。
+- ��户**�进** `vehicleMissing`�**�影�** `ready`；它是�示信�，�是缺失。
+- `vehicleExemptHouseholds` 的户集�是「在团需车户�（�已完�订�），`REQUIREMENT_FROZEN` �在团期已过资�准备时出现（例如物料准备中）。
+- 没有活跃正�用车需求（`vehicleMissing` 里有 `GROUP_REQUIREMENT_NOT_FOUND`）时，��户清�照常列出。
+- 打回�未��的户算未�交：冻结期内它����，所以照报 809122，�进��户清�。
+- `POST .../requirement/confirm` 与本接��一判定：存在 809122 �目时确认被拒�零写入；�有��户未�交时确认照常通过。
+
+---
+
+### 3. 自动汇总正�用车需求�稿 `GET /v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement/aggregate-draft`
+
+**VO**: `Path �数 → GroupVehicleAggregateDraftRespVO`
+
+#### 使用场景
+
+编辑弹窗里点「自动汇总�时调用，按��订�的 active 行程用车需求汇总出一份�原样 PUT 的�稿，零写入。本次起��户�进汇总��报 809121，改列在 `exemptHouseholds`；809121 �报「本�以�交�没�交��车型 / 日期 / 人数缺失的户。鉴�与 `GET .../vehicle-requirement` ��。
+
+#### 入�
+
+| 字段 | �置 | 类型 | 必填 | 约� | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long | ✅ | 雪花 ID，团期��主键 | 团期 ID；无 Query�无 Body |
+
+#### 出� `Result<GroupVehicleAggregateDraftRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data.groupBatchId | String | 团期 ID |
+| data.currentStatus | String | 当�正�需求状�；未形�时为 `null` |
+| data.draft | Object | 汇总�稿，与�存请求体�形（`version` / `remark` / `groups`）；��户�在任何分组里 |
+| data.droppedFleetItems[] | Array | 被丢弃的车型项（与改�一致） |
+| data.staleHeadcountOrders[] | Array | 实时人数与冻结人数��的户（与改�一致） |
+| data.paddedOrderDays[] | Array | 补进分组的日期（与改�一致） |
+| data.violations[] | Array | �稿预检�规（与�存�一份校验） |
+| data.exemptHouseholds[] | Array | **本次新增**：��户，按 orderId ��；无则空数组 `[]` |
+| data.exemptHouseholds[].orderId | String | �订� ID |
+| data.exemptHouseholds[].orderNo | String | �订�� |
+| data.exemptHouseholds[].reason | String | `ORDER_NOT_CUSTOMIZING` 或 `REQUIREMENT_FROZEN`，�六.5 |
+| data.exemptHouseholds[].reasonName | String | ��原因中文� |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch/2099751749718822913/vehicle-requirement/aggregate-draft HTTP/1.1
+Host: <网关地�>
+Authorization: Bearer <admin token>
+```
+
+#### �应示例
+
+测试环境实测（该团唯一的需车户订�待出��没�交行程用车需求，被列为��户，因此 809121 ��触�；�稿零分组，�存�一份校验报 809103）：
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "data": {
+    "groupBatchId": "2099751749718822913",
+    "currentStatus": null,
+    "draft": { "version": null, "remark": null, "groups": [] },
+    "droppedFleetItems": [],
+    "staleHeadcountOrders": [],
+    "paddedOrderDays": [],
+    "violations": [
+      {
+        "code": 809103,
+        "reason": "NO_GROUP",
+        "detail": "本团存在需�用车的�订�，至少��交一个乘车分组",
+        "groupCode": null,
+        "tripDate": null,
+        "orderId": null
+      }
+    ],
+    "exemptHouseholds": [
+      {
+        "orderId": "2099751749693657090",
+        "orderNo": "HL20260915144643265",
+        "reason": "ORDER_NOT_CUSTOMIZING",
+        "reasonName": "订��在定制中"
+      }
+    ]
+  },
+  "traceId": null,
+  "success": true
+}
+```
+
+#### 空数� / �级�应
+
+全部需车户都已�交时 `exemptHouseholds` 为空数组；团里没有在团户时�稿 `groups` 为空数组：
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "data": {
+    "groupBatchId": "2099751749718822913",
+    "currentStatus": null,
+    "draft": { "version": null, "remark": null, "groups": [] },
+    "droppedFleetItems": [],
+    "staleHeadcountOrders": [],
+    "paddedOrderDays": [],
+    "violations": [],
+    "exemptHouseholds": []
+  },
+  "traceId": null,
+  "success": true
+}
+```
+
+#### 错误�应
+
+有户本�以�交�没�交（测试环境实测原文；�团�有 2 户已完�订�被��，�在清�里）：
+
+```json
+{
+  "code": 809121,
+  "message": "团期 「第30期 T29 #7441 AC-29 batch6� 有 2 户缺少�汇总的行程用车需求，暂�能自动汇总：26-0674：未�交行程用车需求�26-7797：未�交行程用车需求",
+  "data": null,
+  "traceId": null,
+  "success": false
+}
+```
+
+车型字典��用：
+
+```json
+{
+  "code": 809120,
+  "message": "车队车型字典暂��用，无法校验车型，请���试",
+  "data": null,
+  "traceId": null,
+  "success": false
+}
+```
+
+#### 业务边界
+
+- 本接��读，�写库。
+- 809121 的户数�计未�交户与车型 / 日期 / 人数缺失的户，�计��户；报文按团�列户。
+- ��户�进�稿分组，�稿原样 PUT 时也�会因为��户没被覆盖而报 809109。
+- ��户与 809123（�存）/ 809122（预检）是�一份判定：汇总放行的户，�存时也�会被判�未�交。
+- `REQUIREMENT_FROZEN` �能出现在本接�（团期已过资�准备时）；�一份�稿在该阶段�能�存（�存��许资�准备中）。
+
+---
+
+## 四�契约约�与正确调用方�
+
+> 本节�写**�端返回什么��端�什么判定**。
+
+### 「�存正�用车需求�按钮的置��件
+
+以预检接�为判�，满足任一��置��存按钮并�示原因：
+
+| �件 | 判定写法 | �示 |
+|------|----------|------|
+| 有未�交户 | `confirm-check` 的 `vehicleMissing.some(i => i.reason === 'HOUSEHOLD_REQUIREMENT_NOT_SUBMITTED')` | 列出这些�目的 `orderNo`，�示先让定制师�交行程用车需求（�存会报 809123） |
+| 阶段���存 | `batchStatus !== 'RESOURCE_PREPARING'` | 仅资�准备中�编辑正�用车需求 |
+
+��户**�是**置��件：`vehicleExemptHouseholds` �空时按钮照常�点。
+
+### ✅ 正确 / � 错误的判定写法
+
+| 场景 | 判定写法 |
+|------|----------|
+| ✅ 判「这户需�催定制师� | `vehicleMissing[].reason === 'HOUSEHOLD_REQUIREMENT_NOT_SUBMITTED'`，户� `orderId` / `orderNo` |
+| ✅ 判「这户没交但�用催� | 在 `vehicleExemptHouseholds[]` / `exemptHouseholds[]` 里；原因展示 `reasonName` |
+| ✅ ��户展示 | 在弹窗 / 预检横幅里�独列一�「以下户未�与排车�，�户显示订�� + `reasonName`；��混进缺失清� |
+| � 用 `exemptHouseholds` 判「能�能�存� | ��户�阻断�存，能�能�存看 809123 与 `vehicleMissing` |
+| � 从 809123 / 809121 报文里抠订�� | 报文�带团�，结构化户信�读 `vehicleMissing[].orderNo` / `exemptHouseholds[].orderNo` |
+| � �设��户清�在读接� `GET .../vehicle-requirement` 里有值 | 该字段�在�存�应里填充，读接�为 `null` |
+
+---
+
+## 五�数�库行为
+
+- 无 DDL�无 Flyway 脚本�无新表 / 新列 / 新状�值。
+- `PUT .../vehicle-requirement`：809123 在任何写入之�抛出，整笔事务零写入；�存�功时的写库行为（失活旧版本 + �新版本与分组 / �日行）与改�一致，��户清���库，是�存那一刻按户侧状�算出�的。
+- `GET .../confirm-check`�`GET .../aggregate-draft`：�读，零写入。
+- 判定读的是既有数�：订�状�（`order_main.order_status`）�团期状�（`order_group_batch.batch_status`）�行程用车需求行（`order_vehicle_requirement`，�历�版本判断是�被打回）。
+
+---
+
+## 六�边界行为
+
+- 未登录 → 401（网关拦截）。
+- 团期�存在 → HTTP 200 + `code=589500`。
+- 无�� → HTTP 200 + `code=589507`。
+- ��户清�在「无��户�时是空数组 `[]`；`GET .../vehicle-requirement` 等��存�应里 `exemptHouseholds` 为 `null`。
+- 整团�车（`vehicleWaived=true`）时车侧整体跳过，`vehicleExemptHouseholds` 为空数组。
+- 全团需车户都是��户：�存空分组报 809103，分组�员��能为空；按现行�径把��户编进分组或走整团�车。
+- 809123 报文的户标识：团� → 订�� → 「��订��，��雪花 ID。
+
+---
+
+## 六.5�枚举 / 数�字典
+
+### exemptHouseholds[].reason / vehicleExemptHouseholds[].reason（��原因）
+
+**所属字段**: `GroupVehicleExemptHouseholdVO.reason` | **类型**: `String`
+
+| 值 | 中文（reasonName） | 说明 | 出现在哪些接� |
+|----|------|------|------|
+| `ORDER_NOT_CUSTOMIZING` | 订��在定制中 | 订�状��是定制中（待支付 / 待出� / 出行中 / 已完�），定制师�交行程用车需求会被 582017 拒 | �存�预检�自动汇总 |
+| `REQUIREMENT_FROZEN` | 团期需求已冻结且该户未被打回 | 团期已过资�准备（物料准备中�之�），该户从没�交过或最新版本未被打回，定制师�交会被 589536 拒 | 仅预检�自动汇总；�存接��会出现 |
+
+### 新增错误�
+
+| 错误� | 模� | 说明 |
+|------|------|------|
+| 809123 | `{0}有 {1} 户尚未�交行程用车需求，暂�能�存正�用车需求：{2}` | `{0}` 团期人��（如 `团期「第30期 …�`，快照缺失为 `该团期`）；`{1}` 户数；`{2}` �户团�，顿�分隔，无团�回�订�� |
+
+## 六.6�修改��对比
+
+### 字段级对比
+
+| 字段 | 改� | 改� |
+|------|------|------|
+| `GroupVehicleRequirementRespVO.exemptHouseholds` | �存在 | �存�应填充（数组），其它�应为 `null` |
+| `GroupBatchRequirementCheckRespVO.vehicleExemptHouseholds` | �存在 | �为数组 |
+| `GroupVehicleAggregateDraftRespVO.exemptHouseholds` | �存在 | �为数组 |
+| 错误� 809123 | �存在 | �存时有未�交户 |
+
+### 行为级对比
+
+| 行为 | 改� | 改� |
+|------|------|------|
+| �存时有户能交没交 | �检查；若该户没被分组覆盖报 809109，逼��替它编�员 | 报 809123，点�这些户 |
+| �存时有户交�了（如订�待支付） | �上，必须编进分组 | �阻断���求覆盖，列入 `exemptHouseholds` |
+| 809109 的检查对象 | 全部在团需车户 | �检查已�交户 |
+| 预检 809122 | 凡没有 active 行程用车需求的放行户都报 | �报未�交户；��户改列 `vehicleExemptHouseholds` |
+| 自动汇总 809121「未�交行程用车需求� | 凡没有行程用车需求的需车户都报 | �报未�交户；��户�进�稿�改列 `exemptHouseholds` |
+| 整团确认时�有��户没交 | 报 809122 拒� | 照常确认 |
+
+## 六.7�影�评估
+
+- **是�破���兼容**: �（字段层�）。三个接��新增字段；错误��新增 809123。行为上�存会多一�拒�（809123），�端按通用错误处�展示 `message` ��正确工作。
+- **�端是�必须�步上线**: �。�改�端时：809123 按通用错误弹窗展示；新增字段被忽略，��户�会显示在页�上（��看�到哪些户没�与排车）。展示��户清�与按钮置�需��端改动。
+- **�端 workaround 清�点**: 若页�有「把没�交的户也塞进分组�能�存�的�作引导，�以撤掉。
+- **风险�**: ��户��与排车，真�用车但订�尚在待支付的户需���从��户清�里看到并跟进。
+
+## 七��影�范围
+
+- **仅影�**: 上述三个管���接�，以�与预检�一判定的 `POST /v3/admin/order/group-batch/{groupBatchId}/requirement/confirm`（请求 / �应结构��，�是��户��触� 809122）。
+- **零影�**:
+  - �程�端（mp）全部接�。
+  - �订�级行程用车需求�交 / 打回链路：582017�589536 的触��件��。
+  - `GET /v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement` 读接��撤回��车��开：结构��（`exemptHouseholds` 为 `null`）。
+  - 接�机（TRANSFER）相关：�看行程用车（TRAVEL）。
+  - 数�库：无 DDL�无�移。
+
+---
+
+## 八�测试环境已验�
+
+部署：`hl-order-service-v3` @ `dev-v3` `c0be69b02`，2026-09-24 11:04 两个实例（8086 / 8186）� UP。�网关（自签 admin token）实测，全部为�读或被拒的写：
+
+```
+PUT /v3/admin/order/group-batch/2099927193172815873/vehicle-requirement（version=4，�放已�交户）
+  → 200；code=809123「团期「第30期 T29 #7441 AC-29 batch6�有 2 户尚未�交行程用车需求，
+    暂�能�存正�用车需求：26-0674�26-7797�；两个实例返回一致 ✓
+  → �团 2 户已完�订�未被点� ✓；库里正�需求�为 v4 DRAFT active（零写入）✓
+  → �带 token → 401「缺少有效的 Authorization 头�✓
+
+GET /v3/admin/order/group-batch/2099927193172815873/requirement/confirm-check
+  → 200；vehicleMissing 的 809122 �有 26-0674 / 26-7797 两户 ✓
+  → vehicleExemptHouseholds = HL20260916022359336�HL20260916022401707（ORDER_NOT_CUSTOMIZING）✓
+
+GET /v3/admin/order/group-batch/2099958693339566081/requirement/confirm-check（物料准备中）
+  → 200；定制中且从没�交的 HL20260916042902319 �报 809122，
+    列入 vehicleExemptHouseholds（REQUIREMENT_FROZEN）✓
+
+GET /v3/admin/order/group-batch/2099927193172815873/vehicle-requirement/aggregate-draft
+  → 200；code=809121，�数到 2 户（26-0674�26-7797），��户�在清� ✓
+
+GET /v3/admin/order/group-batch/2099751749718822913/vehicle-requirement/aggregate-draft
+  → 200；exemptHouseholds 列出 HL20260915144643265（ORDER_NOT_CUSTOMIZING），�报 809121 ✓
+```
+
+�存�功路径（2026-09-24 15:0x，自建团期，团期��缀 `8219-AC5-jw-`，�为资�准备中）：
+
+```
+团期 2103018513226752001（A�B 定制中，C 待支付且无行程用车需求）
+PUT（分组�放 A）
+  → 200；code=809123「…有 1 户尚未�交行程用车需求…：HL20260924150740940�，�点� B��� C；零写入 ✓
+B �交行程用车需求� PUT（分组放 A�B）
+  → 200；code=200，DRAFT v1；exemptHouseholds �有 C（HL20260924150741326，ORDER_NOT_CUSTOMIZING）✓
+  → GET 回读：分组�员�有 A�B，C �在任何分组 ✓
+
+团期 2103018935689650178（两户都已�交）
+PUT（分组放两户）
+  → 200；code=200，DRAFT v1；exemptHouseholds = [] ✓；回读两户都在分组�员里 ✓
+```
+
+---
+
+## ��相关文档
+
+- 关� Issue: [wx/HL#8219](https://git.1814.love/wx/HL/issues/8219)
+- 关� PR: [wx/HL#8317](https://git.1814.love/wx/HL/pulls/8317)�[wx/HL#8319](https://git.1814.love/wx/HL/pulls/8319)
+- 809122 的��：`changelogs-v2/2026-09/23_8249_查看需求页未�交状�与户级用车预检-修改接�-管���.md`
+- 自动汇总端点：`changelogs-v2/2026-09/23_8220_团期正�行程用车需求自动汇总�稿-新增接�-管���.md`
+
+## 关� / �系人
+
+### 链接
+
+- **Issue**: [#8219](https://git.1814.love/wx/HL/issues/8219)
+- **PR**: [#8317](https://git.1814.love/wx/HL/pulls/8317)�[#8319](https://git.1814.love/wx/HL/pulls/8319)
+- **Merge commit**: [c0be69b02](https://git.1814.love/wx/HL/commit/c0be69b02809baabb0a557f3d940d092e4344604)
+
+### �系人
+
+- **�端负责人**: @jw