docs(changelog): #8813 前端标记 implemented

docs(changelog): 团期核单明细带出/暂存合并 + bizKey 溯源（#8813）
- GET/PUT/POST settlement 三端点行为变化：已暂存 tab 持续带出未暂存预览行 - 行出参加 bizKey，暂存入参可透传 sourceType/bizKey - PUT 响应新增 warnMessage/missedCarryOverCount，新错误码 589756/589757 - 前端必须同步上线（否则双显双计）
2026-10-10 14:35:29 +08:00 · 2026-10-10 12:44:09 +08:00 · 2026-10-10 10:22:00 +08:00 · 2026-10-10 10:21:45 +08:00 · 2026-10-10 10:14:05 +08:00 · 2026-10-10 10:04:29 +08:00
@@ -64,6 +64,12 @@ verified_at: ""

 - 接口类条目（新增接口/修改接口/删除接口）：推送前必须走完「PR 合并 → 部署测试服 → 测试服真实 API 验证」，frontmatter 必须 `backend_status: "deployed"`，并在正文「验证证据」章节贴实测结果。
 - `backend_status` 为 `merged` / `pending` / `implemented` 等未部署状态的条目**禁止 push**（校验规则 E_BACKEND_PENDING 会拦）。「先给前端契约、部署随后」的预告式推送一律禁止——前端拿到 changelog 会立刻联调，接口不在等于空耗与误判。
+- 🔴 **正文里不得出现任何「让前端等我们」的措辞**（2026-09-21 wx 第二次点名，校验规则 `E_WAIT_LANGUAGE` 会拦）：`等部署` / `待部署` / `未部署` / `稍后另发` / `修好后另发` / `另发交接件` / `暂不可用` / `暂缓对接` / `该缺陷已在修` / `自行确认部署`，以及「等待」与「部署/后端/我们/上线/修复/另发/发版/滚动」同行共现。
+  - **为什么 §2.1 的 `backend_status` 门禁不够**：它是 frontmatter 字段，而这类句子活在自由文本里，门禁一个字也看不见——`deployed` + 校验器全绿**不等于**这份交接件可执行。2026-09-20 的 `20_7443` 就是这样：frontmatter 已 `deployed`、CI 绿，正文 `status_note` 结尾一句「该缺陷已在修……修好后另发交接件」，mmg 因此一直没动工，直到 09-21 才来问「这个是有啥问题吗 还是没做到呢」。
+  - **为什么不能交给前端自己判断**：消费方查不了我们的部署状态、看不到 `dev-v3`、不知道「另发」是哪天。我方如实写下的「未核」，到他那里只剩一个可选动作——等，而且是静默地等：文件推了、门禁绿了、日报也记了，唯一的异常信号是有人在安静空转，比压根没发更难发现（没发至少还会有人来催）。**对 wx 该说「没核」，对下游只能说「能接」，或者干脆先别发。**
+  - **正文只允许两类内容**：①已经就绪的契约；②前端调用时会撞上的限定（灰度开关状态、前置字段要求、会抛的错误码、已知缺口的工单号）。分界线是问一句：**这条影响他「怎么写代码」，还是只影响他「什么时候开始写」？**后者一律删掉。
+  - **某部分确实还没就绪时**：要么整份不发，要么把没就绪的那块**整段删掉**，只交他现在就能接的部分；绝不写成「稍后另发」。
+  - ⚠️ 本规则只拦我方在制品，**不拦契约边界**——「生产环境灰度开关尚未开启（属独立运维动作）」「TRANSFER-only 订单在 9 个下游消费方无产出，已记 #8056」这类必须照写，否则就撞上「交接件要把自己的覆盖范围写在脸上」那条相反的要求；`E_WAIT_LANGUAGE` 配了阴性对照用例保证不误拦这类句子。
 - 纯前端条目（前端缺陷/前端优化/前端修复）：`backend_status: "not_required"`，change_type 用对应前端类型；`frontend_status: "not_required"` 时不得残留 frontend_owner / frontend_ref / target_release / verified_at。
 - 背景：2026-08-06~08-07 三条未部署即推送的条目（#5599/#5567/#5633）导致前端在测试环境验不到字段（2026-08-10 投诉属实）；当时仓库 CI 因校验规则假阳性长期常红被忽略，规则已于 2026-08-10 修正（前端条目类型合法化、`{orderId}` 路径参数不再误判为占位符），此后 **CI 红 = 真违规，必须当场修复回填**。

@@ -0,0 +1,275 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8143"
+title: "用车详情 vehicleCount 由「车·日数」订正为「车辆台数」"
+consumer: "mp"
+author: "jw(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: "2026-09-22"
+status_note: "路径/方法/入参/出参字段名全不变，唯一变化是 vehicleCount 的【值】——同一个订单同一个字段，数字会变小（3 天 2 辆车由 6 变成 2）。前端把它当「车辆数」展示则无需改动、显示自动变正确；若有基于该值的派生计算需复核。"
+updated_at: "2026-09-22"
+base: "dev-v3"
+---
+
+# 小程序用车详情: vehicleCount 由「车·日数」订正为「车辆台数」
+
+> **服务**: hl-mp-service (端口 8085/8185)
+> **PR**: #8172
+> **Issue**: #8143
+> **日期**: 2026-09-22
+> **影响范围**: 小程序订单详情页「服务包含」→「用车详情」弹窗的车辆数字段
+
+---
+
+## ⚠️ 关键变化
+
+`GET /mp/order/:orderId/vehicle` 的 `vehicleCount`，**契约一直声明是「车辆数」，实际下发的却是派车明细行数（车·日数）**。3 天 2 辆车的订单下发 `6`。本次订正为按车辆去重的台数，**同一个订单、同一个字段，返回的数字会变小**。
+
+字段名、类型、其余所有字段均不变。
+
+---
+
+## 一、背景
+
+v2 时代派车列表一车一行，行数即台数，两者恒等；v3 起派车明细的行粒度变成「一车一日」，取列表长度这个表达式的含义随之漂移成「车·日数」，而字段声明没跟着改。上游把这个数存在用车需求表的 `assignment_used_vehicle_day_count` 列里——**列名就是它真正的口径**。
+
+该字段直接展示给客人，失败形态是静默的：无异常、无错误码，照常返回 200。
+
+测试库实证（只读统计）：
+
+| 维度 | 读数 |
+|------|------|
+| (订单, 用车需求) 组合总数 | 165 |
+| 行数 ≠ 去重台数的组合 | **123（74.5%）** |
+| 最极端样本 | 订单 `2091418470443810817`：1 辆车连开 6 天，下发 `6` |
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 用车详情 | GET | `/mp/order/:orderId/vehicle` | 出参字段值语义订正 | `vehicleCount` 改为按车辆去重的台数；字段名/类型/其余字段全不变 |
+
+---
+
+## 三、接口详情
+
+### 1. 用车详情 `GET /mp/order/:orderId/vehicle`
+
+**VO**: `MpVehicleDetailVO`
+
+#### 使用场景
+
+小程序订单详情页「服务包含」列表中「用车」条目的点击弹窗。
+
+#### 入参
+
+**零变化**。
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| `orderId` | path | Long | 是 | 雪花 ID，**按字符串传** | 订单 ID |
+
+无查询参数、无请求体。登录态由网关注入 `X-User-Id`，前端不传。
+
+#### 出参 `Result<MpVehicleDetailVO>`
+
+字段名、类型、字段个数**全部不变**。唯一变化是 `vehicleCount` 的取值口径：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `vehicleCount` | Integer | **本次改动**。改前＝派车明细行数（车·日数）；改后＝按车辆去重的台数 |
+| `vehicleType` / `plateNumber` / `driverName` / `driverPhone` / `seatCount` | String / Integer | 不变，仍取第一辆车 |
+| `matched` | Boolean | 不变 |
+| `coverUrl` / `vehicleCategory` / `driverYearsRequired` / `features` | - | 不变，自 #7306 B-7 起恒 null |
+
+#### 请求示例
+
+```http
+GET /mp/order/2091418470443810817/vehicle
+Authorization: Bearer <user token>
+```
+
+#### 响应示例
+
+改前（测试环境实测）：
+
+```json
+{"code":200,"message":"成功","data":{
+  "vehicleType":"suv","vehicleCount":6,"coverUrl":null,
+  "plateNumber":"蒙A-E2E01","driverName":"阿拉坦","driverPhone":"135****5019",
+  "matched":true,"seatCount":5,
+  "vehicleCategory":null,"driverYearsRequired":null,"features":null},
+  "success":true}
+```
+
+改后（**仅 `vehicleCount` 变化**）：
+
+```json
+{"code":200,"message":"成功","data":{
+  "vehicleType":"suv","vehicleCount":1,"coverUrl":null,
+  "plateNumber":"蒙A-E2E01","driverName":"阿拉坦","driverPhone":"135****5019",
+  "matched":true,"seatCount":5,
+  "vehicleCategory":null,"driverYearsRequired":null,"features":null},
+  "success":true}
+```
+
+该订单实际就是 1 辆车（蒙A-E2E01）连开 6 天。
+
+#### 空数据 / 降级响应
+
+未配车时仍返回 `matched=false` 的成功响应，`vehicleCount` 不下发。**该路径零变化**（改前改后响应逐字段一致，已实测）。
+
+#### 错误响应
+
+**不新增、不改动**，既有行为逐字保持：
+
+```json
+{"code":581008,"message":"无权查看此订单","data":null,"success":false}
+```
+
+```json
+{"code":581007,"message":"订单不存在","data":null,"success":false}
+```
+
+#### 业务边界
+
+- **「当日无需用车」的日行不计入台数**。车务可把行程中某一天明确标记为不用车，这种日行没有车辆、车牌与司机，它不占一个台数。
+- 因此「3 天全都不用车」算出的是 `0` 而不是 `1`——多条无车日行不会被折叠成一台。
+- **多车订单仍只显示第一辆车**的车型/车牌/司机/座位数，本次未改展示形态。
+- 该字段与用车天数无关，不能用它反推行程长度。
+
+---
+
+## 四、契约约束与正确调用方式
+
+本次不改变任何请求约束，调用方式与改前完全一致。
+
+| 场景 | 调用 |
+|------|------|
+| ✅ 查本人订单用车详情 | `GET /mp/order/2091418470443810817/vehicle` + 本人登录态 → 200 |
+| ❌ 查他人订单 | 同上路径 + 他人登录态 → `581008`（既有行为，未改） |
+| ❌ 订单不存在 | → `581007`（既有行为，未改） |
+
+**读取 `vehicleCount` 的正确姿势**：把它当「这趟行程一共用了几辆车」。它**不是**用车天数，也不是「车辆数 × 天数」。若需要用车天数，当前接口不提供，请另提需求。
+
+---
+
+## 五、数据库行为
+
+无。本接口是只读链路，无事务、无锁、无写入。本次改动不涉及表结构、不涉及 Flyway。
+
+---
+
+## 六、边界行为
+
+- 未登录 → 401（网关拦截），不变
+- 订单不存在 / 非本人订单 → `581007` / `581008`，不变
+- 未配车 → `matched=false` 的 200 响应，`vehicleCount` 不下发，不变
+- 行程中某天标记「无需用车」→ 该天不计入台数
+- 整趟都没有实际车辆 → `vehicleCount=0`（不会折成 1）
+- 上游派单包取不到 → 透传上游错误码，不变
+
+---
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 |
+|------|------|------|
+| `vehicleCount` | 派车明细行数（车·日数） | 按 `vehicleId` 去重的车辆台数 |
+| 其余 10 个字段 | — | 逐字段不变（实测前后对照唯一差异就是 `vehicleCount`） |
+
+### 行为级对比
+
+| 订单 | 服务天数 | 实际车辆台数 | 明细行数 | 改前下发 | 改后下发 |
+|------|----------|--------------|----------|----------|----------|
+| `2091418470443810817` | 6 | 1 | 6 | 6 | **1** |
+| `2089611106451398658` | 3 | 1 | 3 | 3 | **1** |
+| `2087156782022393857` | 3 | 2 | 6 | 6 | **2** |
+| `2087156855368187906` | 3（含 1 天不用车） | 2 | 3 | 3 | **2** |
+
+---
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 否。字段名、类型、字段个数均不变，仅值变小。
+- **前端是否必须同步上线**: 否。前端把该值当「车辆数」展示（与字段声明一致）则无需任何改动，显示会自动变正确。
+- **前端 workaround 清理点**: 若前端曾为绕开这个错误值做过除以天数之类的换算，可以撤掉。若有基于该值的派生计算（按数量估算车辆费用、用它反推行程天数），**需复核**——它此前拿到的是车·日数。
+
+---
+
+## 七、不影响范围
+
+- **仅影响**: 小程序「用车详情」弹窗的 `vehicleCount` 一个字段的值。
+- **零影响**:
+  - **多车订单的展示形态未改** —— 车型/车牌/司机/座位数仍只显示第一辆，第二辆车与后续日期的司机在客人端仍然看不到（本单只订正计数，展示形态需前端配合改弹窗，另行立单）
+  - 同一弹窗的其余 10 个字段（实测前后逐字段一致）
+  - 领队详情 `GET /mp/order/:orderId/guide`
+  - 行前看板 `team.driver`（该字段恒 null，原型暂不展示）
+  - `hl-order-service-v3`：**零改动**
+  - 数据库：无表变更、无 Flyway、无存量迁移
+  - 错误码：不新增
+
+---
+
+## 八、测试环境已验证
+
+构建身份（取证时 `deploy-status.sh`）：`hl-mp-service` = `86967e224` / 分支 `dev-v3` / BEHIND `0/N` / STATE `ok`；`hl-order-service-v3` = `c4a1f1fb6` / BEHIND `2/N`（落后提交未触及该服务）。
+
+真实网关（`api.test.1814.love:9443`）实测：
+
+```
+GET /mp/order/2091418470443810817/vehicle  改前 → 200 vehicleCount=6  ✓
+GET /mp/order/2091418470443810817/vehicle  改后 → 200 vehicleCount=1  ✓（库：6 行 / 1 台车 / 6 天）
+GET /mp/order/2089611106451398658/vehicle  改前 → 200 vehicleCount=3  ✓
+GET /mp/order/2089611106451398658/vehicle  改后 → 200 vehicleCount=1  ✓（库：3 行 / 1 台车 / 3 天）
+GET /mp/order/2086637109266862081/vehicle  改前后 → 200 matched=false 逐字段一致 ✓（未配车路径零回归）
+```
+
+含「当日无需用车」日行的订单（另一条上游分支）：
+
+```
+order 2087156782022393857 → vehicleCount=2  ✓（库：6 行 / 2 台车 / 3 天）
+order 2087156855368187906 → vehicleCount=2  ✓（库：3 行 = 2 实车 + 1 天无需用车；null 行未计入）
+```
+
+单元测试：`hl-mp-service` 整模块 `Tests run: 1058, Failures: 0, Errors: 0, Skipped: 0`。
+
+---
+
+## 九、相关历史 PR
+
+| PR | Issue | 说明 | 是否仍有效 |
+|----|-------|------|------------|
+| — | #7306 | B-7 规格 4 字段 v3 无源降级恒 null | ✅ 有效（本次未改） |
+| — | #7067 | 派车明细行粒度改为「assignmentId + serviceDate」日行 | ✅ 有效（本缺陷的成因） |
+| **本 PR #8172** | **#8143** | `vehicleCount` 订正为车辆台数 | ✅ 最新 |
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#8143](https://git.1814.love:8443/wx/HL/issues/8143)
+- 关联 PR: [wx/HL#8172](https://git.1814.love:8443/wx/HL/pulls/8172)
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8143](https://git.1814.love:8443/wx/HL/issues/8143)
+- **PR**: [#8172](https://git.1814.love:8443/wx/HL/pulls/8172)
+- **Merge commit**: [86967e224](https://git.1814.love:8443/wx/HL/commit/86967e224)
+
+### 联系人
+
+- **后端负责人**: @jw
+- **前端消费方**: hl-mini（mmg）
@@ -0,0 +1,278 @@
+---
+schema: hl-changelog/v2
+ticket: "8739"
+title: "小程序团期下单撞上改期联动时最多等 5 秒，超时返回 100503，不再误报请勿重复提交"
+consumer: mp
+author: wx(GIT)
+change_type: 修改接口
+backend_status: deployed
+gateway_status: not_required
+frontend_status: pending
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: ""
+updated_at: "2026-10-03"
+base: dev-v3
+---
+
+# 小程序团期下单撞上改期联动时最多等 5 秒，超时返回 100503，不再误报请勿重复提交
+
+## ⚠️ 关键变化
+
+- 场景：`POST /mp/order/create` 带 `groupBatchId` 下团期单，而管理端此刻正在给该团期「改出发日」并联动订单（#8666 引入的联动）。
+  - 下单会先等联动结束，最多等 5 秒。
+  - 5 秒内联动结束：按改后的日期正常成单，响应比平时慢几秒。
+  - 5 秒后联动仍未结束：返回 `100503`「资源被占用,请稍后重试」，不成单，可以直接重提。
+- 改前（#8666 上线后、本次之前），同一场景下小程序约 3.5 秒就收到 `100502`「请勿重复提交订单」。测试服实测：
+  - 联动在 5 秒内结束时，后台其实**已经成单**；
+  - 联动占用超过 5 秒时，**没有成单**。
+
+  也就是说，这条路径上的 `100502` 既可能是「成了」，也可能是「没成」。本次起这条路径不再返回 `100502`。
+- 小程序服务等订单服务的上限由 2 秒放宽到 10 秒，超时后也不再自动重发下单请求。
+  - 超过 10 秒仍无结果时，返回 `500`「服务暂时不可用，请稍后重试」。
+  - 此时订单服务端的那次创单不会因此中止，订单**可能已经生成**。
+- 不带 `groupBatchId` 的下单不等联动、不会多等。10 秒上限和「不自动重发」对它同样适用。
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 创建订单 | POST | `/mp/order/create` | 错误响应语义变更 | 团期下单撞上改期联动时最多等 5s，超时返 100503，该路径不再返 100502；服务端超过 10s 返 500，不再自动重发 |
+
+## 三、接口详情
+
+### 1. 创建订单 `POST /mp/order/create`
+
+**VO**: `MpCreateOrderRequest → MpOrderDetailVO`
+
+#### 使用场景
+
+用户在产品详情页选好档位、人数并填好联系人后提交下单。
+
+- 本次只改变下单失败和变慢时返回什么。
+- 对带 `groupBatchId` 的团期单影响最大：该团期正被管理端改出发日时，下单会先等联动结束。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| productId | Body | String | 是 | 不能为空；必须是数字字符串，否则返回 600002「产品ID格式错误」 | 产品 ID（对外收字符串，防止 JS 精度丢失） |
+| groupBatchId | Body | String | 否 | GROUP 产品传；null 或空串视为未指定；非数字返回 600003「团期ID格式错误」；≤0 视为未指定 | 团期 ID。有效时下单与该团期的改期联动互斥 |
+| departureDate | Body | LocalDate | 否 | `yyyy-MM-dd` | 出发日期 |
+| adultCount | Body | Integer | 否 | ≥1，缺省 1 | 成人数 |
+| childCount | Body | Integer | 否 | ≥0，缺省 0 | 儿童数 |
+| youngChildCount | Body | Integer | 否 | ≥0，缺省 0 | 小童数 |
+| babyCount | Body | Integer | 否 | ≥0，缺省 0 | 幼童数 |
+| childNeedBed | Body | Boolean | 否 | 缺省 false | 儿童是否需要床位 |
+| tierSeq | Body | Integer | 是 | ≥1 | 档位序号 |
+| roomCount | Body | Integer | 否 | 传则 ≥1 | 房间数 |
+| sharerOpenid | Body | String | 否 | ≤64；可传空串；非空时只能含字母、数字、下划线、短横线 | 分享人 OpenID |
+| customizerId | Body | Long | 否 | ≥1 | 分享人定制师 ID |
+| contactName | Body | String | 是 | 非空白，≤50 | 联系人姓名 |
+| contactPhone | Body | String | 是 | 非空白，≤20 | 联系人电话 |
+| remark | Body | String | 否 | ≤500 | 订单备注 |
+
+本次请求字段零变更。上表为完整字段表，与改前一致。
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| orderId | String | 订单 ID。后端为 Long，超出 JS 安全整数范围时序列化为字符串，一律按字符串处理 |
+| orderNo | String | 订单编号，格式为 `HL` + 年月日时分秒 + 3 位毫秒 |
+| groupCode | String | 4 位团号，订金支付成功时生成；未生成时该字段不出现 |
+| groupBatchId | String | 团期 ID（序列化同 orderId），只有团期订单才出现 |
+| productId | String | 产品 ID（序列化同 orderId） |
+| departureDate | LocalDate | 出发日期 |
+| returnDate | LocalDate | 返程日期 |
+
+- 响应对象带 `@JsonInclude(NON_NULL)`：值为空的字段（如订金支付前的 `groupCode`）直接不出现，不会以 `null` 返回。前端按「字段缺失」判空。
+- 本次响应字段零变更。出参与 `GET /mp/order/{orderId}` 详情接口同构；上表只列标识字段，完整字段见既有详情接口文档。
+
+#### 请求示例
+
+```json
+{
+  "productId": "1900123456789000001",
+  "groupBatchId": "1900123456789000002",
+  "departureDate": "2027-01-27",
+  "adultCount": 2,
+  "childCount": 1,
+  "tierSeq": 1,
+  "contactName": "林晓梅",
+  "contactPhone": "13900001234",
+  "remark": "老人同行，希望安排低楼层"
+}
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "orderId": "1900123456789000003",
+    "orderNo": "HL20270127143025001",
+    "groupBatchId": "1900123456789000002",
+    "productId": "1900123456789000001",
+    "departureDate": "2027-01-27",
+    "returnDate": "2027-02-01"
+  },
+  "traceId": null,
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+本接口没有空数据形态。
+
+- 订单服务等待超过 10 秒，或暂时不可达时，返回下方错误响应里的 5xx（文案「服务暂时不可用，请稍后重试」），不会返回半成品数据。
+- 上述错误响应的 HTTP 状态码都是 200，结果看 `code`。
+
+#### 错误响应
+
+团期下单撞上改期联动，等满 5 秒联动仍未结束（不成单，可以直接重提）：
+
+```json
+{
+  "code": 100503,
+  "message": "资源被占用,请稍后重试",
+  "data": null,
+  "traceId": null,
+  "success": false
+}
+```
+
+订单服务超过 10 秒没给出结果（订单可能已经生成，先查订单列表再决定是否重提）：
+
+```json
+{
+  "code": 500,
+  "message": "服务暂时不可用，请稍后重试",
+  "data": null,
+  "traceId": null,
+  "success": false
+}
+```
+
+真的重复提交（上一次下单请求已被受理或仍在处理，不要自动重提）：
+
+```json
+{
+  "code": 100502,
+  "message": "请勿重复提交订单",
+  "data": null,
+  "traceId": null,
+  "success": false
+}
+```
+
+#### 业务边界
+
+- **什么时候会等**：只有 `groupBatchId` 解析为正数时，下单才与该团期的改期联动互斥。不带团期的下单不等。
+- **等多久**：最多 5 秒，后端常量，前端不可调整。测试服实测一次改期联动占用 41–688 毫秒（12 次），所以多数情况是「慢一点但成单」，`100503` 只在联动占用超过 5 秒时出现。
+- **`100503`**：不成单，因为等锁失败时创单业务还没开始执行。可以直接重提，不需要任何清理。
+  - 重提不会撞 `100502`。小程序层的防重窗口 5 秒，`100503` 返回时已过；订单服务层的防重键在 `100503` 时随失败释放。
+- **`500` 等 5xx（等待超过 10 秒或订单服务不可达）**：小程序服务不再自动重发，但订单服务端已开始的那次创单不会中止，**可能已经成单**。
+  - 此时直接重提可能产生两张订单：订单服务层同用户同产品的防重窗口是 10 秒，从原请求开始计时，到 `500` 返回时已基本过期。（按代码机制推导，测试服未构造过超过 10 秒的场景。）
+  - 建议提示「网络繁忙，请到我的订单查看」，先刷新订单列表，确认没有新订单再让用户重提。
+- **`100502` 现在只表示真的重复提交**，有两层窗口：
+  - 小程序层：同一用户 5 秒内第二次下单，不分产品。成功下单后 5 秒内再下也算。
+  - 订单服务层：同一用户同一产品 10 秒内第二次下单。
+
+  收到时说明前一次请求已被受理或仍在处理，引导用户到订单列表查看，不要自动重提。
+- **`100501`「下单过于频繁,请稍后再试」**：订单服务层按用户限流，每个用户 60 秒内最多 5 次下单请求。既有行为，未变。
+
+## 四、契约约束与正确调用方式
+
+1. 按 `code` 区分错误，不要按 `message` 判断。`100502`、`100503` 和 5xx 的文案相近，处理方式完全不同。
+2. 下单请求的前端超时不要短于 15 秒：服务端最长 10 秒给出结果，另有网关与网络开销。前端先放弃时，用户看不到 `100503`，后台却可能已成单。
+3. 提交期间禁用提交按钮，直到收到响应。团期下单撞上改期联动时，正常响应也可能慢约 5 秒。
+4. 收到 `100503` 可以直接重提原请求。
+5. 收到 5xx（`code` ≥ 500）先刷新订单列表，确认没成单再重提。
+6. 收到 `100502` 不要自动重提，引导用户到订单列表查看。
+
+## 五、数据库行为
+
+| 结果 | 数据库写入 |
+|------|------------|
+| `100503` | 零写入：等锁失败发生在创单业务开始之前 |
+| `100502` / `100501` | 零写入：在进入创单业务前就被拦截 |
+| 5xx（等待超过 10 秒） | 订单服务端那次创单照常提交或失败，与小程序有没有收到结果无关 |
+| 成功 | 写入与改前完全一致；本次不涉及任何表结构变更 |
+
+## 六、边界行为
+
+- 两个时限（等锁 5 秒、小程序服务调订单服务超时 10 秒）都是服务端固定值，请求参数无法调整。
+- 本接口与管理端创单复用同一套创单内核，锁判断完全一致。
+  - 管理端用 `productBatchId` 数字。
+  - 小程序用 `groupBatchId` 字符串，两者是同一个 ID。
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+本接口请求、响应字段均**零变更**，变的只是失败和变慢时的返回。
+
+### 行为级对比
+
+| 场景 | 改前（#8666 上线后、本次之前） | 改后 |
+|------|------|------|
+| 团期下单，没撞上改期联动 | 正常成单 | 正常成单，无差异 |
+| 团期下单，撞上改期联动且联动在 5 秒内结束 | 约 3.5 秒返回 `100502`，后台其实已成单 | 等联动结束后正常成单，响应最多慢约 5 秒 |
+| 团期下单，联动占用超过 5 秒 | 约 3.5 秒返回 `100502`，没有成单 | 约 5 秒返回 `100503`，没有成单，可直接重提 |
+| 任意下单，订单服务处理超过 2 秒 | 小程序服务约 2 秒超时后自动重发同一请求，用户可能收到 `100502` 而后台已成单 | 等到 10 秒；超过 10 秒返回 `500`，不重发 |
+
+在 #8666 之前，下单完全不与改期联动互斥。撞上改期时可能按旧出发日成单，且日期与团期永久错位、无人察觉。#8666 堵住了这个窗口，本次修正的是它在小程序链路上的错误码表现。
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**：否。请求、响应字段零变更，正常成单路径不变。
+- **前端是否必须同步上线**：否。未识别 `100503` 时展示原始 `message` 不会白屏。但若前端下单请求的超时短于 15 秒，需要调整，见第四节第 2 条。
+- **前端 workaround 清理点**：无。
+
+## 七、不影响范围
+
+- 小程序其他订单接口（列表、详情、取消、改单等）调订单服务的等待上限与重试策略**未变**。
+- 请求、响应字段零变更。
+- 网关路由零变更，无数据库结构变更。
+
+## 八、测试环境已验证
+
+2026-10-03 测试服部署 hl-mp-service（dev-v3 `f4e45c2f1`）后实测。做法：用测试 C 端用户直连小程序服务，在自建团期上人为占住改期联动锁。
+
+| 场景 | 响应 | 耗时 | 成单 | 订单服务收到的请求 |
+|------|------|------|------|------|
+| 联动占用约 3.5 秒 | 成功，`data` 为完整订单详情 | 约 3.5 秒 | 1 单 | 1 次 |
+| 联动占用约 6 秒 | `100503`「资源被占用,请稍后重试」 | 约 5 秒 | 0 | 1 次 |
+| 上一行锁释放后间隔 ≥5 秒重提 | 成功 | 正常 | 1 单 | 1 次 |
+| 收到 `100503` 后 0.3 秒内立即重提（锁剩余不足 1 秒） | 未返回 `100502`，等联动结束后成功 | 未单独计时 | 1 单 | 2 次，即两次真实提交，无自动重发 |
+| 不占锁的常规下单 | 成功 | 正常 | 1 单 | 1 次 |
+
+- 常规下单的响应 `data` 与 `GET /mp/order/{orderId}` 的 `data` 做了字段集比对：61 个字段路径，零差异，二者同为 `MpOrderDetailVO`。
+- 改前基线是部署前用同一夹具、同一方法测的：
+  - 联动占用约 3.5 秒：约 3.5 秒返回 `100502`，但后台已成单，订单服务收到 2 次。
+  - 联动占用约 6 秒：同样返回 `100502`，未成单。
+- 本轮未构造订单服务超过 10 秒才返回的场景，所以 `500` 之后可能已成单这一点仍是按代码推导，见业务边界。
+
+## 十、相关文档
+
+- 管理端同源改动：`changelogs-v2/2026-10/03_8666_产品班期改出发日联动团期与子单日期并新增改期拒绝码-修改接口-管理后台.md`（#8666）。改期联动本身的事件与拒绝码以该条为准。
+- 内部转发路径：`POST /mp/order/create`（hl-mp-service）→ `POST /v3/internal/mp/order/create`（order-v3）。`/v3/internal/**` 只供服务间调用，不经网关，前端不可达。
+- `100503` 是全仓统一的锁竞争可重试错误码。
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8739](https://git.1814.love/wx/HL/issues/8739)（本次）、[#8666](https://git.1814.love/wx/HL/issues/8666)（引入改期联动锁）
+- **PR**: [#8740](https://git.1814.love/wx/HL/pulls/8740)、[#8738](https://git.1814.love/wx/HL/pulls/8738)
+- **Merge commit**: `f4e45c2f147eb5e0deec4dbd920e6c82c496ec7b`（#8740）、`fad5d7814b2d1fb940d740457dbed754e46d03f9`（#8738）
+
+### 联系人
+
+- **后端负责人**: @wx
@@ -1,11 +1,18 @@
 ---
-schema: "hl-changelog/v1"
+schema: "hl-changelog/v2"
 ticket: "5186"
 title: "排车中订单恢复派车派人入口并补齐改派上下文"
 consumer: "admin"
-backend: "verified"
-gateway: "verified"
-frontend: "pending"
+change_type: "修改接口"
+backend_status: "verified"
+gateway_status: "verified"
+frontend_status: "implemented"
+frontend_owner: "hl-admin(claude)"
+frontend_ref: "158f728ce9110ca6a9e0185c137969f84b522c6f"
+target_release: "v2.1"
+verified_at: "2026-10-09"
+status_note: "7 月历史补标：已于 2026-07-23 交付（恢复排车中订单派车派人入口，158f728ce 起含 2f4d278a6/54c007856 后续修正），证据为交付 commit 正文标注 #5186"
+updated_at: "2026-10-09"
 base: "dev-v3"
 generated: "2026-07-23T16:10:00+08:00"
 ---
@@ -1,11 +1,18 @@
 ---
-schema: "hl-changelog/v1"
+schema: "hl-changelog/v2"
 ticket: "5194"
 title: "待确认详情补全多车多司机与按槽位改派"
 consumer: "admin"
-backend: "verified"
-gateway: "verified"
-frontend: "pending"
+change_type: "修改接口"
+backend_status: "verified"
+gateway_status: "verified"
+frontend_status: "implemented"
+frontend_owner: "hl-admin(claude)"
+frontend_ref: "bfb4e3cde018d14b2b5dedaacacb83128cc7714d"
+target_release: "v2.1"
+verified_at: "2026-10-09"
+status_note: "7 月历史补标：已于 2026-07-23 交付（多槽位改派与司机确认，bfb4e3cde），证据为交付 commit 正文标注 #5194"
+updated_at: "2026-10-09"
 base: "dev-v3"
 generated: "2026-07-23T18:02:00+08:00"
 ---
@@ -1,11 +1,18 @@
 ---
-schema: "hl-changelog/v1"
+schema: "hl-changelog/v2"
 ticket: "5199"
 title: "车务首页订单去重与字段补全"
 consumer: "admin"
-backend: "verified"
-gateway: "verified"
-frontend: "pending"
+change_type: "修改接口"
+backend_status: "verified"
+gateway_status: "verified"
+frontend_status: "implemented"
+frontend_owner: "hl-admin(claude)"
+frontend_ref: "3c4f8619bbc569d72e73cedba9a74b2cefc67402"
+target_release: "v2.1"
+verified_at: "2026-10-09"
+status_note: "7 月历史补标：已于 2026-07-24 交付（车务首页订单聚合契约对齐，3c4f8619b），证据为交付 commit 正文标注 #5199"
+updated_at: "2026-10-09"
 base: "dev-v3"
 generated: "2026-07-24T09:46:00+08:00"
 ---
@@ -1,11 +1,18 @@
 ---
-schema: "hl-changelog/v1"
+schema: "hl-changelog/v2"
 ticket: "5200"
 title: "用车需求驳回历史与重新提交"
 consumer: "admin"
-backend: "verified"
-gateway: "verified"
-frontend: "pending"
+change_type: "修改接口"
+backend_status: "verified"
+gateway_status: "verified"
+frontend_status: "implemented"
+frontend_owner: "hl-admin(claude)"
+frontend_ref: "d7afc25146ed1bceea3e3722c521babd85c1345e"
+target_release: "v2.1"
+verified_at: "2026-10-09"
+status_note: "7 月历史补标：已于 2026-07-24 交付（用车需求驳回历史与重新提交，d7afc2514），证据为交付 commit 正文标注 #5200"
+updated_at: "2026-10-09"
 base: "dev-v3"
 generated: "2026-07-24T11:05:00+08:00"
 ---
@@ -1,11 +1,18 @@
 ---
-schema: "hl-changelog/v1"
+schema: "hl-changelog/v2"
 ticket: "5205"
 title: "车务首页汇总与看板人员类型展示"
 consumer: "admin"
-backend: "verified"
-gateway: "verified"
-frontend: "pending"
+change_type: "修改接口"
+backend_status: "verified"
+gateway_status: "verified"
+frontend_status: "implemented"
+frontend_owner: "hl-admin(claude)"
+frontend_ref: "78cbb1565b6555788607b34f591f0291a87af96d"
+target_release: "v2.1"
+verified_at: "2026-10-09"
+status_note: "7 月历史补标：已于 2026-07-24 交付（车务汇总与人员类型展示对齐，78cbb1565），证据为交付 commit 正文标注 #5205"
+updated_at: "2026-10-09"
 base: "dev-v3"
 generated: "2026-07-24T10:45:00+08:00"
 ---
@@ -1,11 +1,18 @@
 ---
-schema: "hl-changelog/v1"
+schema: "hl-changelog/v2"
 ticket: "5132"
 title: "车务派单详情补全产品、行程节点、出行人与大交通"
 consumer: "admin"
-backend: "verified"
-gateway: "verified"
-frontend: "pending"
+change_type: "修改接口"
+backend_status: "verified"
+gateway_status: "verified"
+frontend_status: "implemented"
+frontend_owner: "hl-admin(claude)"
+frontend_ref: "524cfb21d24074e8e22c5ca7a89cbbd693f59abb"
+target_release: "v2.1"
+verified_at: "2026-10-09"
+status_note: "7 月历史补标：已于 2026-07-22 交付（派单详情新增字段展示/出行人类型区分，524cfb21d 起 3 个 commit），证据为交付 commit 正文标注 #5132"
+updated_at: "2026-10-09"
 base: "dev-v3"
 generated: "2026-07-22T10:35:00+08:00"
 ---
@@ -1,11 +1,18 @@
 ---
-schema: "hl-changelog/v1"
+schema: "hl-changelog/v2"
 ticket: "5139"
 title: "车务派单候选筛选、分页与任意车辆选择"
 consumer: "admin"
-backend: "verified"
-gateway: "verified"
-frontend: "pending"
+change_type: "修改接口"
+backend_status: "verified"
+gateway_status: "verified"
+frontend_status: "implemented"
+frontend_owner: "hl-admin(claude)"
+frontend_ref: "a0e8a6ef15a5a1983ddab3ca2958444e7971ae77"
+target_release: "v2.1"
+verified_at: "2026-10-09"
+status_note: "7 月历史补标：已于 2026-07-22 交付（派单候选筛选与任意车辆选择接入，a0e8a6ef1），证据为交付 commit 正文标注 #5139"
+updated_at: "2026-10-09"
 base: "dev-v3"
 generated: "2026-07-22T13:25:00+08:00"
 ---
@@ -1,11 +1,18 @@
 ---
-schema: "hl-changelog/v1"
+schema: "hl-changelog/v2"
 ticket: "5141"
 title: "车务派单司机保险类型与行程保障状态"
 consumer: "admin"
-backend: "verified"
-gateway: "verified"
-frontend: "pending"
+change_type: "修改接口"
+backend_status: "verified"
+gateway_status: "verified"
+frontend_status: "implemented"
+frontend_owner: "hl-admin(claude)"
+frontend_ref: "29ab0d6562413be6ab715d8b1e1eb2d4521a9eff"
+target_release: "v2.1"
+verified_at: "2026-10-09"
+status_note: "7 月历史补标：已于 2026-07-22 交付（司机保险保障状态与线上投保接入，29ab0d656），证据为交付 commit 正文标注 #5141"
+updated_at: "2026-10-09"
 base: "dev-v3"
 generated: "2026-07-22T14:07:00+08:00"
 ---
@@ -1,11 +1,18 @@
 ---
-schema: "hl-changelog/v1"
+schema: "hl-changelog/v2"
 ticket: "5145"
 title: "选车后常驻司机默认配对"
 consumer: "admin"
-backend: "verified"
-gateway: "verified"
-frontend: "pending"
+change_type: "修改接口"
+backend_status: "verified"
+gateway_status: "verified"
+frontend_status: "implemented"
+frontend_owner: "hl-admin(claude)"
+frontend_ref: "b9994da9308ae84d361e79e86f74200813ec06cc"
+target_release: "v2.1"
+verified_at: "2026-10-09"
+status_note: "7 月历史补标：已于 2026-07-22 交付（选车后常驻司机默认配对接入，b9994da93），证据为交付 commit 正文标注 #5145"
+updated_at: "2026-10-09"
 base: "dev-v3"
 generated: "2026-07-22T15:30:00+08:00"
 ---
@@ -1,11 +1,18 @@
 ---
-schema: "hl-changelog/v1"
+schema: "hl-changelog/v2"
 ticket: "5146"
 title: "司机待确认通知与可选确认凭证"
 consumer: "admin"
-backend: "verified"
-gateway: "verified"
-frontend: "pending"
+change_type: "修改接口"
+backend_status: "verified"
+gateway_status: "verified"
+frontend_status: "implemented"
+frontend_owner: "hl-admin(claude)"
+frontend_ref: "089e55ffb6f4336c19ffd2ed2eade131bdb35bf7"
+target_release: "v2.1"
+verified_at: "2026-10-09"
+status_note: "7 月历史补标：已于 2026-07-22 交付（司机确认登记与可选凭证接入，089e55ffb），证据为交付 commit 正文标注 #5146"
+updated_at: "2026-10-09"
 base: "dev-v3"
 generated: "2026-07-22T15:20:00+08:00"
 ---
@@ -1,11 +1,18 @@
 ---
-schema: "hl-changelog/v1"
+schema: "hl-changelog/v2"
 ticket: "5149"
 title: "派单详情补充团号与产品类型"
 consumer: "admin"
-backend: "verified"
-gateway: "verified"
-frontend: "pending"
+change_type: "修改接口"
+backend_status: "verified"
+gateway_status: "verified"
+frontend_status: "implemented"
+frontend_owner: "hl-admin(claude)"
+frontend_ref: "ccbdd0bd1b7c903846c8ae9e4e9e15d80266b9a4"
+target_release: "v2.1"
+verified_at: "2026-10-09"
+status_note: "7 月历史补标：已于 2026-07-22 交付（派单详情补充团号与产品类型，ccbdd0bd1），证据为交付 commit 正文标注 #5149"
+updated_at: "2026-10-09"
 base: "dev-v3"
 generated: "2026-07-22T16:22:00+08:00"
 ---
@@ -12,7 +12,7 @@ frontend_owner: "pi-main-session"
 frontend_ref: "hl-admin@aa7061b0edeaf68a8baf306a858a91d8be8cb9a7"
 target_release: ""
 verified_at: "2026-09-18"
-status_note: "wx 确认无"按赛季买"需求，投保界面"按赛季"与"按年"快捷预填重复，去掉"按赛季"保留"按年"。[mmg 2026-09-18 复核翻 verified] ref aa7061b0 可达且为 v2.1 祖先；HEAD 上投保弹窗无按赛季预填残留（现「赛季」命中均为司机列表赛季在册页签，与本项无关）；list-error-retry spec 全绿。"
+status_note: "wx 确认无\"按赛季买\"需求，投保界面\"按赛季\"与\"按年\"快捷预填重复，去掉\"按赛季\"保留\"按年\"。[mmg 2026-09-18 复核翻 verified] ref aa7061b0 可达且为 v2.1 祖先；HEAD 上投保弹窗无按赛季预填残留（现「赛季」命中均为司机列表赛季在册页签，与本项无关）；list-error-retry spec 全绿。"
 updated_at: "2026-09-18"
 base: "dev-v3"
 ---
@@ -10,10 +10,10 @@ gateway_status: "verified"
 frontend_status: "verified"
 frontend_owner: "mmg"
 frontend_ref: "af7cc62b"
-target_release: ""
+target_release: "hl-ui@af7cc62b"
 verified_at: "2026-09-08"
 status_note: "后端 PR #7170 已合 dev-v3 并部署测试服(网关 finance/advances/payee-candidates 实测 200),原 backend_status/gateway_status=pending 系 09-06 陈旧快照已修正为 deployed/verified。前端团期财务 Tab 与预支接真已交付:groupBatchFinance.js 五端点+FinanceTab(四金额卡/逐户付款表/预支记录/整团核算口径行)+GroupAdvanceModal+detail 挂财务 Tab+store 键缓存+AdvanceApprovalList scope 筛选;金额全后端权威值零反算。ref af7cc62b,checkpoint 全绿含 Vitest 全量+生产构建。"
-updated_at: "2026-09-08"
+updated_at: "2026-09-24"
 base: "dev-v3"
 ---

@@ -378,8 +378,8 @@ POST /v3/admin/order/group-batch/90211/advance
 |---|---|
 | `589500` | 团期不存在 |
 | `589507` | 缺 `group-batch:finance:advance` 权限 |
-| `589538` | 团期状态不可发起预支（须为物料准备中 / 待出发 / 出行中） |
-| `589539` | 房 / 车 / 导 / 摄四项未配齐 |
+| `589541` | 团期状态不可发起预支。⚠️ 2026-09-24 订正：原文误写为 `589538`（号段顺延后实际落 589541）；允许状态已两次放宽，现为「进入核单前都可以」（#8270 / #8322） |
+| `589542` | 房 / 车 / 导 / 摄四项未配齐。⚠️ 2026-09-24 订正：原文误写为 `589539`（该号实为 #7178「名额调整量不能为 0」）；**#8270 起本码不再返回** |
 | `585003` | 预支金额必须大于 0 |
 | `585004` | 预支金额超过可用余额上限 |
 | `585006` | 借款类型非法 |
@@ -391,7 +391,7 @@ POST /v3/admin/order/group-batch/90211/advance

 #### 业务边界

- **双前置闸门**：团期状态 + 四项资源全就绪，缺一即拒（此前服务端两道都没有，只有前端做了置灰）。
+- **双前置闸门**：团期状态 + 四项资源全就绪，缺一即拒（此前服务端两道都没有，只有前端做了置灰）。⚠️ 已变更：#8270 删除四项配齐门，#8322 起进入核单前都可发起，且领款人限定为本团主报账人（589557），见 `24_8322_…` 条目。
 - **上限走团期统一池**：团期级与各子订单级**共扣一池**。团期把整团尾款预支满后，该团任一子订单再发起订单级预支同样会被 `585004` 拒——这是本次修复的超支漏洞。
 - 创建后进入**站内财务审批**，走既有 `advance-approvals` 列表与 approve / reject / 撤回三端点，与订单级完全一致。
 - 一期仍**只记账不出款**，实际出款走财务既有付款流程。
@@ -583,8 +583,8 @@ GET /v3/admin/order/group-batch/90211/settlement/summary
 | 团期无活跃子订单 | 六个金额字段 `0.00`，`items` 空数组 |
 | 子订单已取消 | 不进金额、不进 `items`，只计入 `withdrawnCount` |
 | 未设置报账人 | `primaryPayeeName` 为 `null`，后端不兜底默认导游 |
-| 团期状态为招募中 / 核单中 | 发起预支返回 `589538` |
-| 四项资源缺任一 | 发起预支返回 `589539` |
+| 团期状态为招募中 / 核单中 | 发起预支返回 `589541`（2026-09-24 订正码值；#8322 起招募中已可发起，仅核单中及之后返回） |
+| 四项资源缺任一 | 原返回 `589542`（2026-09-24 订正码值）；#8270 起不再拦截 |
 | 团期尾款池已被预支占满 | 团期级与该团任一子订单级预支**均**返回 `585004` |
 | 数据字典服务不可用 | 借款类型降级到内置集合校验，正常类型仍可提交 |
 | 审批列表出现团期级行 | `orderId` / `orderNo` / `consultantName` / 订单四态均为 `null` |
@@ -611,7 +611,7 @@ GET /v3/admin/order/group-batch/90211/settlement/summary
 1. 财务 Tab 四张卡与逐户表末行合计一致，且与团期详情、看板列表三处应收同源。
 2. **超支被堵死**：团期级把整团尾款预支满 → 该团任一子订单再发起订单级预支被 `585004` 拒。
 3. **核单零重复扣**：团期级预支 5,000 通过 + 某户订单级预支 2,000 通过 → 该户报销单含 2,000，整团 `groupAdvanceApproved` 仍是 5,000；`grandTotalCost` 不变。
-4. 两道闸门各拒一次（`589538` / `589539`）。
+4. 两道闸门各拒一次（`589541` / `589542`，2026-09-24 订正码值）。
 5. 团期级预支出现在预支审批列表，「团号 / 产品」「行程」两列有值，按团期号搜得到，就地通过 / 驳回 / 撤回正常。
 6. 订单级预支五端点回归无变化。

@@ -627,7 +627,7 @@ GET /v3/admin/order/group-batch/90211/settlement/summary

 | 处 | 文档现状 | 实际 |
 |---|---|---|
-| §0B.9 错误码 | 「统一用 `AdvanceErrorCode`（585 段）」 | 改落 `589538` / `589539`；585 段被 v2/v3 整段重叠声明且 585001-585010 已被 order-v2 实占 |
+| §0B.9 错误码 | 「统一用 `AdvanceErrorCode`（585 段）」 | 改落 `589541` / `589542`（原拟 589538 / 589539，被 #7158 / #7178 先占后顺延，2026-09-24 订正）；585 段被 v2/v3 整段重叠声明且 585001-585010 已被 order-v2 实占 |
 | GB-ADM-040 出参 | `payStatus` 写五值含 `REFUNDING` / `REFUNDED` | 代码只有三值；结清状态另出 `settleStatus` 字段 |
 | GB-ADM-040 出参 | 含 `advanceTotal` | 已废，改三个数 |
 | GB-ADM-042 | 返回 `GroupBatchWriteResultVO`、不回传 `advanceId` | 改返 `OrderAdvanceRespVO` 并回传 `advanceId` |
@@ -12,7 +12,7 @@ frontend_owner: "mmg"
 frontend_ref: "0f2f5b1a"
 target_release: ""
 verified_at: "2026-09-11"
-status_note: "2026-09-10 squash 0f62fb072（PR #7490）已合并 dev-v3 并部署测试服：hl-user-service 与 hl-order-service-v3 均已滚到当前 tip 0f62fb072，两实例均 LISTEN、Nacos healthy=true enabled=true。三个端点均实测打通：open-group-house 未认领态不对称行为已验证——管理员侧 200，fwzz_pure01/shuxin/fwzz_lead01/test_admin 等非当前认领人角色全部 281002；真实 conversation_key=GROUP_HOUSE:2097500233511362561（按团期聚合主键建键）；GET /v3/admin/order/group-batch/{groupBatchId} 响应确认带 houseChatUnreadCount。测试数据已清理（admin_message / admin_conversation_member 均 COUNT=0）。⚠️ 与工单转述核对，本次发现并订正三处（第①②处 2026-09-10 首次发布时已订正，第③④处为部署后复核新增）：① ChatConversationRespVO（会话列表项）本次新增的是 groupBatchId/groupBatchNo/groupBatchName 三个字段，并没有 departDate（departDate 只在 ChatOrderCardVO／打开会话响应的团期卡上，会话列表接口读不到）；② 281016（缺 groupBatchId）在标准 HTTP 请求路径下不可达，ChatOpenGroupHouseReqVO.groupBatchId 有 @NotNull，@Valid 会先在参数绑定阶段返回 400，281016 只是 ChatManager 内部方法的防御性兜底（源码注释原话如此）；③ open-group-house 响应对「团未认领」的 peerAdminId 不是 null 而是占位常量 0（ChatManager.buildFullResp 直接回显 DB 成员行原值，不做归一化），只有会话列表接口（ConversationMemberService.fillGroupBatchSummaries）才会归一化成 null，且列表还受 last_message_at IS NOT NULL 过滤，没发过消息的会话根本不出现在列表里，2026-09-10 实测发现原口径「两处均为 null」有误，已在「关键变化」第 2 条订正；④ 网关对未路由的 /internal/** 路径（本单两个 internal 端点均未配 Path 路由）返回的是 HTTP 200 + 业务体 {"code":404,"message":"接口不存在: ..."}（GlobalErrorWebExceptionHandler 路由未命中分支），不是 403——JwtAuthFilter.isInternalPath() 的 403 分支存在但轮不到执行（请求在路由层已被拒），原口径「网关对 /internal/** 一律 403」不准确，已在「七、不影响范围」订正。此外发现一处工单未提及但同一 squash 里的关联变更：既有团期详情接口 GET /v3/admin/order/group-batch/{groupBatchId}（A2）顺带新增只读字段 houseChatUnreadCount，纯新增不影响既有契约，一并写在「关键变化」供前端知悉。 前端已交付(commit 0f2f5b1a):chat.js 加 openGroupHouseChat(键 GROUP_HOUSE:{groupBatchId} 团期聚合主键 String 透传,前端不自拼)+KEY_RE 扩展;ChatDrawer 支持 GROUP_HOUSE(open 分流/会话卡团期文本/未认领 peerAdminId=0 显「团期管理员」不占在线点),281002 复用固定文案不透原文、281017 拦截器透 message;入口①房务看板「联系团期管理员」②团期详情「联系房务」+houseChatUnreadCount 角标(标读/信令重拉,TEAM 口径不重算);两 internal 端点前端不接。"
+status_note: "2026-09-10 squash 0f62fb072（PR #7490）已合并 dev-v3 并部署测试服：hl-user-service 与 hl-order-service-v3 均已滚到当前 tip 0f62fb072，两实例均 LISTEN、Nacos healthy=true enabled=true。三个端点均实测打通：open-group-house 未认领态不对称行为已验证——管理员侧 200，fwzz_pure01/shuxin/fwzz_lead01/test_admin 等非当前认领人角色全部 281002；真实 conversation_key=GROUP_HOUSE:2097500233511362561（按团期聚合主键建键）；GET /v3/admin/order/group-batch/{groupBatchId} 响应确认带 houseChatUnreadCount。测试数据已清理（admin_message / admin_conversation_member 均 COUNT=0）。⚠️ 与工单转述核对，本次发现并订正三处（第①②处 2026-09-10 首次发布时已订正，第③④处为部署后复核新增）：① ChatConversationRespVO（会话列表项）本次新增的是 groupBatchId/groupBatchNo/groupBatchName 三个字段，并没有 departDate（departDate 只在 ChatOrderCardVO／打开会话响应的团期卡上，会话列表接口读不到）；② 281016（缺 groupBatchId）在标准 HTTP 请求路径下不可达，ChatOpenGroupHouseReqVO.groupBatchId 有 @NotNull，@Valid 会先在参数绑定阶段返回 400，281016 只是 ChatManager 内部方法的防御性兜底（源码注释原话如此）；③ open-group-house 响应对「团未认领」的 peerAdminId 不是 null 而是占位常量 0（ChatManager.buildFullResp 直接回显 DB 成员行原值，不做归一化），只有会话列表接口（ConversationMemberService.fillGroupBatchSummaries）才会归一化成 null，且列表还受 last_message_at IS NOT NULL 过滤，没发过消息的会话根本不出现在列表里，2026-09-10 实测发现原口径「两处均为 null」有误，已在「关键变化」第 2 条订正；④ 网关对未路由的 /internal/** 路径（本单两个 internal 端点均未配 Path 路由）返回的是 HTTP 200 + 业务体 {\"code\":404,\"message\":\"接口不存在: ...\"}（GlobalErrorWebExceptionHandler 路由未命中分支），不是 403——JwtAuthFilter.isInternalPath() 的 403 分支存在但轮不到执行（请求在路由层已被拒），原口径「网关对 /internal/** 一律 403」不准确，已在「七、不影响范围」订正。此外发现一处工单未提及但同一 squash 里的关联变更：既有团期详情接口 GET /v3/admin/order/group-batch/{groupBatchId}（A2）顺带新增只读字段 houseChatUnreadCount，纯新增不影响既有契约，一并写在「关键变化」供前端知悉。 前端已交付(commit 0f2f5b1a):chat.js 加 openGroupHouseChat(键 GROUP_HOUSE:{groupBatchId} 团期聚合主键 String 透传,前端不自拼)+KEY_RE 扩展;ChatDrawer 支持 GROUP_HOUSE(open 分流/会话卡团期文本/未认领 peerAdminId=0 显「团期管理员」不占在线点),281002 复用固定文案不透原文、281017 拦截器透 message;入口①房务看板「联系团期管理员」②团期详情「联系房务」+houseChatUnreadCount 角标(标读/信令重拉,TEAM 口径不重算);两 internal 端点前端不接。"
 updated_at: "2026-09-10"
 base: "dev-v3"
 ---
@@ -7,12 +7,12 @@ author: "wx(GIT)"
 change_type: "修改接口"
 backend_status: "deployed"
 gateway_status: "verified"
-frontend_status: "not_required"
+frontend_status: "verified"
 frontend_owner: "mmg"
-frontend_ref: ""
-target_release: ""
-verified_at: "2026-09-13T14:20:00"
-status_note: "本文件是 #7439 的对外分册（7 个 /v3/admin 端点）。4 个 /v3/internal 端点已按 BACKEND_CHANGELOG_DELIVERY_GUIDE.md 2.5 节拆出为内部分册 13_7439_团期车务地基-内部接口-修改接口-管理后台.md，两份同批交付。【前端 2026-09-13 判 not_required】本单为接送机(TRANSFER)打地基，但开关 transfer-kind-submit-enabled 默认 false、本期不产生 TRANSFER 行、不传 kind 服务端按 TRAVEL 处理，现网代码不改继续工作——用户拍板本期不动、等 TRANSFER 开放。已 grep 实证前端 orderV2.js 已封装 vehicle-requirement 各端点与 step3/vehicles 读写，均按 TRAVEL 落、未传 kind。⚠️ TRANSFER 开放后必须回头补的硬契约点：双需求并存时结算手录行 requirementKind 必填(缺失返 809008)、vehicle-requirement 写口建议显式传 kind、reject/supplier-reject 的 kind 走 query 不进 body、我的接单列表按 kind 分栏/筛选。详见正文末「六.边界行为」处置口径表。"
+frontend_ref: "6c091ef2486e0844d5bf1e39c705e43bec875e4f"
+target_release: "v2.1"
+verified_at: "2026-09-21"
+status_note: "本文件是 #7439 的对外分册（7 个 /v3/admin 端点）。4 个 /v3/internal 端点已按 BACKEND_CHANGELOG_DELIVERY_GUIDE.md 2.5 节拆出为内部分册 13_7439_团期车务地基-内部接口-修改接口-管理后台.md，两份同批交付。【前端 2026-09-13 判 not_required】本单为接送机(TRANSFER)打地基，但开关 transfer-kind-submit-enabled 默认 false、本期不产生 TRANSFER 行、不传 kind 服务端按 TRAVEL 处理，现网代码不改继续工作——用户拍板本期不动、等 TRANSFER 开放。已 grep 实证前端 orderV2.js 已封装 vehicle-requirement 各端点与 step3/vehicles 读写，均按 TRAVEL 落、未传 kind。⚠️ TRANSFER 开放后必须回头补的硬契约点：双需求并存时结算手录行 requirementKind 必填(缺失返 809008)、vehicle-requirement 写口建议显式传 kind、reject/supplier-reject 的 kind 走 query 不进 body、我的接单列表按 kind 分栏/筛选。详见正文末「六.边界行为」处置口径表。【mmg 2026-09-21 交付,not_required 翻 verified】「TRANSFER 开放后回头补」硬契约点已落地:A+B 订单侧(hl-admin v2.1 6c091ef24)结算 step3 手录车行 requirementKind(双需求并存缺归属前置拦截防 809008,FLEET 省略/MANUAL 手选+回显带回)、putVehicleRequirement 显式 kind 进 body、rejectVehicleRequirement 的 kind 走 query 不进 body(防 Jackson 静默忽略);C 车务侧(662310ea)batch/pickup-dropoff-config 显式 kind=TRANSFER。supplier-reject 前端无封装(仅房务有)、我的接单 vehicle 列表前端无该页面,两项无面可改,随未来建设接入。"
 updated_at: "2026-09-13"
 base: "dev-v3"
 ---
@@ -362,6 +362,8 @@ POST /v3/admin/order/60123456789013/vehicle-requirement/supplier-reject?kind=TRA

 ### 5. 我的接单列表 `GET /v3/admin/order/grab-pool/my-claims/vehicle`

+> 2026-09-26 订正（#8373）：本接口已下线，见 26_8373_下线车控我的接单接口-删除接口-管理后台.md
+
 **VO**: `MyClaimsQueryReqVO → Result<PageResult<VehicleClaimItemVO>>`

 #### 使用场景
@@ -12,7 +12,7 @@ frontend_owner: "mmg"
 frontend_ref: "8a9eae337077a3406ffe7d67db0b55e8c40dba0a"
 target_release: ""
 verified_at: "2026-09-13"
-status_note: "新增只读接口 GET /admin/user/employee-options，只要求登录、不限制角色（任何登录操作员可用），供财务等业务表单\【前端 2026-09-13 交付 verified】api/user.js 新增 getEmployeeOptions（GET /user/employee-options，不限角色，区别于 getUserPage 限 SUPER_ADMIN/ADMIN），供 #7612 业务外收支经办人下拉；adminId 雪花字符串透传，姓名优先 enterpriseWechatName 回落 username。随 #7612 同 commit 交付，新增 user.spec。"经办人/员工选择器\"下拉。替代有角色限制的 GET /admin/user。"
+status_note: "新增只读接口 GET /admin/user/employee-options，只要求登录、不限制角色（任何登录操作员可用），供财务等业务表单经办人/员工选择器\"下拉。替代有角色限制的 GET /admin/user。【前端 2026-09-13 交付 verified】api/user.js 新增 getEmployeeOptions（GET /user/employee-options，不限角色，区别于 getUserPage 限 SUPER_ADMIN/ADMIN），供 #7612 业务外收支经办人下拉；adminId 雪花字符串透传，姓名优先 enterpriseWechatName 回落 username。随 #7612 同 commit 交付，新增 user.spec。"
 updated_at: "2026-09-13"
 base: "dev-v3"
 ---
@@ -12,7 +12,7 @@ frontend_owner: ""
 frontend_ref: ""
 target_release: ""
 verified_at: "2026-09-15"
-status_note: "PR #7679（Issue #7327 AC-17）已 squash 合并 dev-v3（合并提交 6169a612a）。2026-09-15 代码已确认部署在测试服（deploy-status.sh 实测），并对 GET /v3/admin/order/todos 做了真实网关取证，证实了字段契约本身（含 2026-09-14 起草时写错的 todoTypeName/groupBatchId 已更正为 todoTypeLabel/teamNo，并补充了此前遗漏的 todoTypes[] 聚合数组）。backend_status 记 deployed：代码已部署且响应字段契约已实测。⚠️ 如实标注未覆盖范围：本单核心修复点（团单户级为空、回落读团级认领人这一分支）本轮未能采到「团单+户级为空+团期已认领+OPEN」四条件同时成立的真实样本，抓到的 REFUND 样本都是户级直接抢单的散客单——该分支目前只有单测覆盖，非测试服端到端验证，详见「八、测试环境已验证」。另需注意 #7459（PR #7731）已把本条讨论的取消触发路径改为约 1 秒的异步 outbox，详见正文「切换状态时的必要动作」更正。PR 正文已记录 2026-09-14 一次测试服实测（取消订单 2099318713927778306 产出 owner_user_id=NULL 的缺陷现象），那是修复前的缺陷复现证据，不是修复后的验证。gateway_status=not_required：受影响的 GET /v3/admin/order/todos 是已有路由，本次未新增/修改任何路径。frontend_status=pending：待前端确认房务待办列表页是否需要对「owner 从广播态变为团级认领人」这类变化做任何界面提示，故不定为 not_required。 前端 not_required(grep 实证):todos/index.vue owner 展示为 ownerName || "团队" 通用渲染,字段用 teamNo/todoTypeLabel 与真实契约一致;owner 从 null 变真实 ID 纯取值变化、scope 换桶为服务端行为,前端零改动。"
+status_note: "PR #7679（Issue #7327 AC-17）已 squash 合并 dev-v3（合并提交 6169a612a）。2026-09-15 代码已确认部署在测试服（deploy-status.sh 实测），并对 GET /v3/admin/order/todos 做了真实网关取证，证实了字段契约本身（含 2026-09-14 起草时写错的 todoTypeName/groupBatchId 已更正为 todoTypeLabel/teamNo，并补充了此前遗漏的 todoTypes[] 聚合数组）。backend_status 记 deployed：代码已部署且响应字段契约已实测。⚠️ 如实标注未覆盖范围：本单核心修复点（团单户级为空、回落读团级认领人这一分支）本轮未能采到「团单+户级为空+团期已认领+OPEN」四条件同时成立的真实样本，抓到的 REFUND 样本都是户级直接抢单的散客单——该分支目前只有单测覆盖，非测试服端到端验证，详见「八、测试环境已验证」。另需注意 #7459（PR #7731）已把本条讨论的取消触发路径改为约 1 秒的异步 outbox，详见正文「切换状态时的必要动作」更正。PR 正文已记录 2026-09-14 一次测试服实测（取消订单 2099318713927778306 产出 owner_user_id=NULL 的缺陷现象），那是修复前的缺陷复现证据，不是修复后的验证。gateway_status=not_required：受影响的 GET /v3/admin/order/todos 是已有路由，本次未新增/修改任何路径。frontend_status=pending：待前端确认房务待办列表页是否需要对「owner 从广播态变为团级认领人」这类变化做任何界面提示，故不定为 not_required。 前端 not_required(grep 实证):todos/index.vue owner 展示为 ownerName || \"团队\" 通用渲染,字段用 teamNo/todoTypeLabel 与真实契约一致;owner 从 null 变真实 ID 纯取值变化、scope 换桶为服务端行为,前端零改动。"
 updated_at: "2026-09-15"
 base: "dev-v3"
 ---
@@ -12,7 +12,7 @@ frontend_owner: "mmg"
 frontend_ref: "7a2cbaa3c716ec6f6195344963693cf52bb9f456"
 target_release: ""
 verified_at: "2026-09-15"
-status_note: "后端契约零变更，仅前端对接纠错：新建/编辑资金账户接口的 overdraftAllowed 字段是 Integer（1 允许 / 0 不允许），不是布尔。前端开关组件若直接提交 true/false，会被 Jackson 在反序列化阶段拦截，报「请求数据格式错误：字段 [overdraftAllowed] 格式错误」（HTTP 200 + code 400）。提交前须把开关值规整为 1/0 整数。 前端已修复(7a2cbaa3):AccountFormDrawer 提交体 overdraftAllowed 规整 true→1/false→0,编辑回显改 === 1 判真(规避 "0" 字符串 Boolean 误判),fund-account.js 入参文档同步 Integer 口径;新增 AccountFormDrawer.spec 3 例,checkpoint 13 项全绿。"
+status_note: "后端契约零变更，仅前端对接纠错：新建/编辑资金账户接口的 overdraftAllowed 字段是 Integer（1 允许 / 0 不允许），不是布尔。前端开关组件若直接提交 true/false，会被 Jackson 在反序列化阶段拦截，报「请求数据格式错误：字段 [overdraftAllowed] 格式错误」（HTTP 200 + code 400）。提交前须把开关值规整为 1/0 整数。 前端已修复(7a2cbaa3):AccountFormDrawer 提交体 overdraftAllowed 规整 true→1/false→0,编辑回显改 === 1 判真(规避 \"0\" 字符串 Boolean 误判),fund-account.js 入参文档同步 Integer 口径;新增 AccountFormDrawer.spec 3 例,checkpoint 13 项全绿。"
 updated_at: "2026-09-15"
 base: "dev-v3"
 ---
@@ -7,12 +7,12 @@ author: "wx(GIT)"
 change_type: "修改接口"
 backend_status: "deployed"
 gateway_status: "verified"
-frontend_status: "not_required"
-frontend_owner: ""
-frontend_ref: ""
-target_release: ""
-verified_at: ""
-status_note: "后端交付。派车批量与接送机配置入参新增可选 kind 字段；新增 4 个错误码（602200/602201/602202/602205）。[mmg 2026-09-18 判 not_required] kind 可选不传=TRAVEL，契约保证存量请求行为逐字一致。grep 实证：前端两处调用（src/api/fleet/board.js 的 POST /fleet/assignments/batch 与 PUT /fleet/assignments/pickup-dropoff-config）均不传 kind，全仓无 TRANSFER 派车入口；上游写口 809009 开关关闭，产品上产不出 TRANSFER 需求，4 个新错误码仅 kind=TRANSFER 触发、前端不可达；响应信封订正（code 即业务码、无 errorCode）与前端 request.js 拦截器透 message 惯例一致，无需改动。TRANSFER 开放后回头补：batch/pickup-dropoff-config 显式传 kind=TRANSFER、602205 给「先补大交通再重试」引导、TRANSFER 派车行确认/改派待 #7443 AC-24 修复后接入，已记入项目 memory。"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "662310eac02ef5afc84c81b242949ca536c79489"
+target_release: "v2.1"
+verified_at: "2026-09-21"
+status_note: "后端交付。派车批量与接送机配置入参新增可选 kind 字段；新增 4 个错误码（602200/602201/602202/602205）。[mmg 2026-09-18 判 not_required] kind 可选不传=TRAVEL，契约保证存量请求行为逐字一致。grep 实证：前端两处调用（src/api/fleet/board.js 的 POST /fleet/assignments/batch 与 PUT /fleet/assignments/pickup-dropoff-config）均不传 kind，全仓无 TRANSFER 派车入口；上游写口 809009 开关关闭，产品上产不出 TRANSFER 需求，4 个新错误码仅 kind=TRANSFER 触发、前端不可达；响应信封订正（code 即业务码、无 errorCode）与前端 request.js 拦截器透 message 惯例一致，无需改动。TRANSFER 开放后回头补：batch/pickup-dropoff-config 显式传 kind=TRANSFER、602205 给「先补大交通再重试」引导、TRANSFER 派车行确认/改派待 #7443 AC-24 修复后接入，已记入项目 memory。【mmg 2026-09-21 交付,not_required 翻 verified】挂起期「TRANSFER 开放后回头补」已落地(hl-admin v2.1 662310ea)：派单弹窗双需求订单显「本次派车需求」切换器(用户拍板弹窗内方案),batch/pickup-dropoff-config 显式 kind=TRANSFER(仅切换器 scoped order 标记者,TRAVEL 绝不下发);602205 拦截器透「请先在订单侧补齐大交通后重试」引导不改写需求不存在,602200-602202 透 message;确认/改派/候选四端点契约零变化前端零改动(AC-24 纯后端修复,改派按 assignmentId 反查零改动可用)。遗留:TRANSFER 复核确认(confirmHold groups 取整单 activeAssignments 无法按 kind 拆分,待派车行 kind 标签)、我的接单 vehicle 列表 kind 分栏(前端无该页面)。"
 updated_at: "2026-09-18"
 base: "dev-v3"
 ---
@@ -7,12 +7,12 @@ author: "wx(GIT)"
 change_type: "修改接口"
 backend_status: "deployed"
 gateway_status: "verified"
-frontend_status: "pending"
+frontend_status: "not_required"
 frontend_owner: ""
 frontend_ref: ""
 target_release: ""
 verified_at: ""
-status_note: "订正件，不改代码，只改测试服 Nacos 配置 + 重启。18_7443 判 not_required 的理由是「809009 开关关闭，产品上产不出 TRANSFER 需求，4 个新错误码前端不可达」——该理由 2026-09-19 15:33:32 起已不成立：hl.order.requirement.transfer-kind-submit-enabled 在测试服 namespace=test 的 hl-order-service-v3-test.yml 被置 true 并随 order-v3 两实例重启（15:36:32/15:36:46）生效。本文撰写前二次复验（Nacos 直读 17:00:35 CST 仍为 true；SUPER_ADMIN 身份两次真实网关调用穿透了原先必现的 809009 分支，其中一次落库成功）。三条边界必须同时看：①代码默认值仍是 false（@Value 未改），生产环境未动；②RequirementService 无 @RefreshScope，改配置必须重启才生效，这次也确实重启了；③本文撰写过程中意外发现 18_7443/19_7443(未推送草稿) 关于「confirm/change 仍必现 605041」的既有说法本身已经过期——AC-24 修复（PR #7952, commit c527e48c3, 2026-09-18 18:55 合入 dev-v3）已经是当前测试服 order-v3(ca0656f1c)与 fleet(31fd5b5e6) 两个正在跑的字节的祖先提交，即该修复本身也已随各自服务的最近一次部署上线，但本文未对 confirm/change 端点做真实网关复测，这一句只有源码祖先关系与部署记录支撑，不构成端到端功能验证，请勿据此对外宣称\"确认/改派已验证可用\"。frontend_status 由 not_required 改判 pending：原判定的前提（不可达）已不成立，但生产环境仍不可达、且是否现在启动前端集成属产品排期决定，不是本文档能替 mmg 拍板的，故不写 not_required（意味着无需关注），也不写 claimed/implemented（没有证据），交给 mmg 自行判断是否现在启动。"
+status_note: "订正件，不改代码，只改测试服 Nacos 配置 + 重启。18_7443 判 not_required 的理由是「809009 开关关闭，产品上产不出 TRANSFER 需求，4 个新错误码前端不可达」——该理由 2026-09-19 15:33:32 起已不成立：hl.order.requirement.transfer-kind-submit-enabled 在测试服 namespace=test 的 hl-order-service-v3-test.yml 被置 true 并随 order-v3 两实例重启（15:36:32/15:36:46）生效。本文撰写前二次复验（Nacos 直读 17:00:35 CST 仍为 true；SUPER_ADMIN 身份两次真实网关调用穿透了原先必现的 809009 分支，其中一次落库成功）。三条边界必须同时看：①代码默认值仍是 false（@Value 未改），生产环境未动；②RequirementService 无 @RefreshScope，改配置必须重启才生效，这次也确实重启了；③本文撰写过程中意外发现 18_7443/19_7443(未推送草稿) 关于「confirm/change 仍必现 605041」的既有说法本身已经过期——AC-24 修复（PR #7952, commit c527e48c3, 2026-09-18 18:55 合入 dev-v3）已经是当前测试服 order-v3(ca0656f1c)与 fleet(31fd5b5e6) 两个正在跑的字节的祖先提交，即该修复本身也已随各自服务的最近一次部署上线，但本文未对 confirm/change 端点做真实网关复测，这一句只有源码祖先关系与部署记录支撑，不构成端到端功能验证，请勿据此对外宣称\"确认/改派已验证可用\"。frontend_status 由 not_required 改判 pending：原判定的前提（不可达）已不成立，但生产环境仍不可达、且是否现在启动前端集成属产品排期决定，不是本文档能替 mmg 拍板的，故不写 not_required（意味着无需关注），也不写 claimed/implemented（没有证据），交给 mmg 自行判断是否现在启动。 【mmg 2026-09-24 复核,维持 not_required】四码(602200/602201/602202/602205)前端处理已随 20_7443(09-21,hl-admin 662310ea)交付:batch/pickup-dropoff-config 显式 kind=TRANSFER(仅切换器标记者,TRAVEL 绝不下发),602205 透「先补大交通再重试」引导,602200-602202 透 message(board.js:91/useAssignFlow.js:366,891);确认/改派四端点契约零变化。遗留:TRANSFER 复核确认(待后端派车行 kind 标签)、我的接单 vehicle 分栏(前端无该页面),非本件动作。"
 updated_at: "2026-09-19"
 base: "dev-v3"
 ---
@@ -10,10 +10,10 @@ gateway_status: "not_required"
 frontend_status: "verified"
 frontend_owner: "mmg"
 frontend_ref: "28d4482c636dbfeba1803c64ef263f09c3656934"
-target_release: ""
+target_release: "hl-ui@28d4482c"
 verified_at: "2026-09-21"
-status_note: "前端 2026-09-20 反馈清单第4项引用了一个不存在的写口 POST .../slots/{slotId}/clear-residue-dates（该端点已随 #7067 去槽位化整体删除，origin/dev-v3 全仓零命中），并要求后端在读侧新增 residueServiceDates 字段。核实：读侧 cells[].rescheduleResidue 已能推导出该日期子集，写侧 DELETE /{assignmentId} 与 POST /batch 两条既有端点已覆盖单日/整批清理，本次零后端代码改动。POST /batch 对已过去的残留日期有硬门禁会拦截，DELETE 是否放行未取证，本文档已如实标注【需确认】。前端 2026-09-21 已交付:Step2 逐日栅格恢复残留格「取消残留」入口(canDelete!==false 且 assignmentId 时渲染,只读行禁用,deleteBlockReason 透传),逐日清理走 DELETE /admin/fleet/assignments/{assignmentId}(cancelReason/driverNotified/requestId 按契约显式传,requestId=createRequestId('residue-clear'));整批 POST /batch 100001「已过去或已完结」识别后提示改走逐日清理。DELETE 对过去日期是否放行(605028)仍未实证,由拦截器统一透后端 message 兜底。"
-updated_at: "2026-09-20"
+status_note: "前端 2026-09-20 反馈清单第4项引用了一个不存在的写口 POST .../slots/{slotId}/clear-residue-dates（该端点已随 #7067 去槽位化整体删除，origin/dev-v3 全仓零命中），并要求后端在读侧新增 residueServiceDates 字段。核实：读侧 cells[].rescheduleResidue 已能推导出该日期子集，写侧 DELETE /{assignmentId} 与 POST /batch 两条既有端点已覆盖单日/整批清理，本次零后端代码改动。POST /batch 对已过去的残留日期有硬门禁会拦截，DELETE 是否放行未取证，本文档已如实标注【需确认】。前端 2026-09-21 已交付:Step2 逐日栅格恢复残留格「取消残留」入口(canDelete!==false 且 assignmentId 时渲染,只读行禁用,deleteBlockReason 透传),逐日清理走 DELETE /admin/fleet/assignments/{assignmentId}(cancelReason/driverNotified/requestId 按契约显式传,requestId=createRequestId('residue-clear'));整批 POST /batch 100001「已过去或已完结」识别后提示改走逐日清理。DELETE 对过去日期是否放行(605028)仍未实证,由拦截器统一透后端 message 兜底。2026-09-26 订正(#8371):DELETE 命中改期残留行已改为单行取消,并豁免 605027/605047/605028 三道日期门,见 26_8371_改期残留行单行取消与累计凭证回显-修改接口-管理后台.md。"
+updated_at: "2026-09-26"
 base: "dev-v3"
 ---

@@ -41,6 +41,10 @@ base: "dev-v3"
 - 前端要求新增的读侧字段 `residueServiceDates`**不需要新增**：`AssignmentCandidateRespVO.CanonicalSnapshotVO.cells[]`（`AssignmentCandidateRespVO.java:108-150`）里每个 cell 已经逐日携带 `rescheduleResidue`（布尔）+ `serviceDate` + `assignmentId`，前端自己过滤即可得到这个数组。
 - ⚠️ **`POST /batch` 整批清理对"已过去的残留日期"有硬门禁会拦截**（详见「四、契约约束」），前端做整批清理时必须预期这种场景下的 400。逐日清理 `DELETE /{assignmentId}` 是否放行过去日期，本轮**未取证**，标记为【需确认】。

+> **2026-09-26 订正（#8371）**：
+> - `DELETE /{assignmentId}` 逐日清理残留行现已**单行取消**（不再整组取消），并豁免 605027/605047/605028 三道日期门。
+> - 改期残留行判定、单行处理、错误码豁免的细节，见 26_8371_改期残留行单行取消与累计凭证回显-修改接口-管理后台.md。
+
 ---

 ## 一、背景
@@ -72,6 +76,8 @@ base: "dev-v3"
 | 2 | 取消派单（逐日清理残留） | DELETE | `/admin/fleet/assignments/{assignmentId}` | 复用不改 | 按 cell 的 `assignmentId` 单日取消，条件释放占用 |
 | 3 | 批量创建派单（整批清理残留） | POST | `/admin/fleet/assignments/batch` | 复用不改 | 提交时不带残留日期项，后端按 diff 精确取消 |

+> **2026-09-26 订正（#8371）**：上表第 2 行「按 cell 的 `assignmentId` 单日取消」在写作当时并不成立——彼时 `DELETE` 命中改期残留行仍按**整组**取消（还会连带取消同组窗内的其它日期行，这正是 #8371 要修的缺陷）。#8371 已实测确认：`DELETE` 现在对「改期残留行」做真正的单行取消，窗内其它行不受影响；非残留行仍按原整组逻辑处理。细节与实测证据见 `26_8371_改期残留行单行取消与累计凭证回显-修改接口-管理后台.md`。
+
 ---

 ## 三、接口详情
@@ -197,6 +203,8 @@ base: "dev-v3"

 **VO**: `CancelReqVO → CancelRespVO`

+> **2026-09-26 订正（#8371）**：本小节标题「逐日清理残留」写作时是前端诉求的期望描述，当时源码并不支持——`DELETE` 命中改期残留行时仍按整组取消。#8371 已实测确认标题所述行为现已成立：目标行若判定为「改期残留行」，走单行取消分支，操作日志 `operationLog[].detailJson` 会带 `scope="RESIDUE_ROW"` 可供核验；非残留行不受影响，仍是整组取消。细节见 `26_8371_改期残留行单行取消与累计凭证回显-修改接口-管理后台.md`。
+
 #### 使用场景

 车务在 Step2 栅格里勾选一个或多个 `rescheduleResidue=true` 的日期后，对每个勾选日期取其 cell 的 `assignmentId`，逐日调用本端点单独取消，条件释放该行占用的车辆/司机。适合「只清理某几天」「部分勾选」场景。
@@ -287,9 +295,13 @@ base: "dev-v3"

 其它错误码（`AssignmentController.java:469-471`）：400（`cancelReason`/`driverNotified`/`requestId` 请求校验）/ 605009（派单不存在）/ 605020（当前状态不允许取消）/ 605026（无凭证未二次确认）/ 605027（已出发禁止整组取消）。

+> **2026-09-26 订正（#8371）**：目标行判定为「改期残留行」时，605027（连同 605047/605028）**不再触发**，改走单行取消；新增 605710「订单服务不可用：{0}」——残留行判定依赖 order-v3 查询窗口数据，查询失败时整笔 fail-closed，不取消任何行。非残留行的错误码集合不变。见 `26_8371_改期残留行单行取消与累计凭证回显-修改接口-管理后台.md`。
+
 #### 业务边界

 - 【需确认】**本端点对"服务日期已过去的改期残留行"是否放行取消，本轮未取证**：`CancelReqVO.cutoffDate` 注释写明「服务端仅接受当天，空值按当天处理，不支持预约未来取消」，而 605028 的语义是「取消生效日不在派单服务日期范围内」——若某残留行 `serviceDate` 是 3 天前、`cutoffDate` 按当天处理，"当天"是否落在该行的服务日期范围内、会不会触发 605028，未经实测确认。读侧 `canDelete` 字段的设计意图是「改期残留旧行恒 `true`，受只读窗口约束时 `false`」（`AssignmentCandidateRespVO.java:149-150`），但这是响应快照上的展示态，不等于运行时 DELETE 调用本身在过去日期上必然放行。**若实测发现本端点对已过去日期同样拦截，那才是真正需要后端开一张单的地方**（放开残留行对过去日期的取消）。
+
+  > **2026-09-26 订正（#8371）**：已实测坐实——修复前，改期残留行（服务日期已过去）确实被拦截，实测复现 605027；#8371 修复后，同一残留行 `DELETE` 直接取消成功，不再命中 605027/605047/605028。取消后该行状态落 `exception`（不是 `canceled`，因取消前处于 `assigned`/`holding`，与通用取消 #6152 同口径）。判定逻辑与全链路证据见 `26_8371_改期残留行单行取消与累计凭证回显-修改接口-管理后台.md`。
 - `assignmentId` 必须取自对应 cell（残留清理场景下即 `rescheduleResidue=true` 的那一项），传错会命中另一天的派车行。
 - `driverNotified` 传 `false` 也允许取消，只是前端需要在未告知司机时给出强提示（后端只做存证，不代为通知）。

@@ -416,6 +428,8 @@ base: "dev-v3"

 前端在实现"整批清理"按钮时，遇到 `code=100001` 且消息含"已过去或已完结"，应识别为"残留日期已过去，本接口无法清理"，引导车务改走逐日 `DELETE` 路径（而不是当成普通校验失败重试原样提交）。

+> **2026-09-26 订正（#8371）**：上表「✅ 逐日清理（含过去日期，未取证是否放行）」与本段「引导车务改走逐日 `DELETE`」在写作时均未经实测；实测结果是**当时同样会被拦截**（改期残留行过去日期 `DELETE` 命中 605027），引导车务改走逐日 `DELETE` 在当时并不能真正解决问题。#8371 已修复：残留行现在 `DELETE` 直接取消成功，完全跳过整组门禁，上表与本段的方向自此才成立。见 `26_8371_改期残留行单行取消与累计凭证回显-修改接口-管理后台.md`。
+
 ---

 ## 五、数据库行为
@@ -429,6 +443,8 @@ base: "dev-v3"

 两条路径都不会物理删除行，只做状态流转；`assignmentId` 一旦取消不可复用为新方案的匹配键。

+> **2026-09-26 订正（#8371）**：上表「状态置 `canceled`」是简化写法。测试服实测：取消前处于 `assigned`/`holding` 的行，落库状态是 `exception`（与通用取消 #6152 同口径），仅 `unassigned` 行取消才直接落 `canceled`。改期残留行走单行取消分支时同样遵循这条状态机，不因残留身份而特殊化。见 `26_8371_改期残留行单行取消与累计凭证回显-修改接口-管理后台.md`。
+
 ---

 ## 六、边界行为
@@ -437,6 +453,8 @@ base: "dev-v3"
 - `assignmentId` 不存在 → `DELETE` 返 605009
 - `requirementId` 缺失或需求上下文不可用 → `candidates` 的 `canonicalSnapshot` 为 `null`，不报错
 - 已出发/已完结的派单 → 605027（整组取消禁止）/「该日已完结不可改派」400（`AssignmentService.java:2714`）
+
+  > **2026-09-26 订正（#8371）**：上条仅对**非改期残留行**成立。目标行判定为改期残留行时，605027/605047/605028 三道日期门全部豁免，按单行取消处理；order-v3 查询窗口失败时新增 605710 fail-closed（不取消任何行）。见 `26_8371_改期残留行单行取消与累计凭证回显-修改接口-管理后台.md`。
 - 老数据兼容：历史行无 `assignmentGroupId` 时，`cells[].groupId` 回退返回 `assignmentId`，对任何真实行恒非空

 ---
@@ -498,6 +516,8 @@ grep clear-residue-dates / clearResidueDates / cancel-residue → 全仓零命

 **【需确认】未取证项**：`DELETE /{assignmentId}` 对服务日期已过去的改期残留行是否放行取消（涉及 605028 与只读窗口判定），需要一次真实测试服调用才能确认，本文档不代为下结论。

+> **2026-09-26 订正（#8371）**：已取证，不再是【需确认】。改前基线：确实拦截，命中 605027。改后（#8371 测试服全链路 6 步实测）：改期残留行判定为真时，`DELETE` 直接放行取消，不命中 605027/605047/605028；判定失败（order-v3 不可达）时新码 605710 fail-closed。见 `26_8371_改期残留行单行取消与累计凭证回显-修改接口-管理后台.md`。
+
 ---

 ## 十、相关文档
@@ -506,6 +526,8 @@ grep clear-residue-dates / clearResidueDates / cancel-residue → 全仓零命
 - 退役背景：#7067 去槽位化重构（`06_7067_派单去槽位化按行程日配车-接送机独立配置-修改接口-管理后台.md`）
 - 后续计划：若【需确认】项实测发现 `DELETE` 对过去日期同样拦截，需另开工单放开残留行的过去日期取消

+> **2026-09-26 订正（#8371）**：该「另开工单」已完成，即 #8371——已实测坐实过去拦截、已修复并验证放行。见 `26_8371_改期残留行单行取消与累计凭证回显-修改接口-管理后台.md`。
+
 ## 关联 / 联系人

 ### 链接
@@ -12,7 +12,7 @@ frontend_owner: ""
 frontend_ref: ""
 target_release: ""
 verified_at: ""
-status_note: "【2026-09-20 AC-26 收尾】gateway_status 回填 verified，四个端点（「二、变更接口清单」全部条目）均经网关实测（cw_test_7443 账号，dev-v3 测试服，fleet 部署 dev-v3@311dc92ee，2026-09-20 17:46:56，含 PR #7952/c527e48c3 + #8048 + #8042；取证前后各跑一次 deploy-status.sh，两次 fleet/order-v3 commit 一致，证据有效）：(1) POST /admin/fleet/assignments/candidates（requirementId=2101219393722634242）：canonicalSnapshot 非 null；(2) POST /admin/fleet/assignments/{id}/change（TRANSFER 派车行 2101174428044824578）：code=200；(3) POST /admin/fleet/assignments/{id}/confirm（TRANSFER 派车行 2101174428711686146）：code=200/confirmed=true/assignmentStatus=assigned（此前记录的 582093 已由 #8037 修复）；(4) POST /admin/fleet/assignments/requirements/{requirementId}/confirm（TRANSFER 需求 2101567456596365313，订单 2101566624467419137）：借新上线的 GET /admin/fleet/board/orders/{orderId} 返回的 requirementIdentities（#7990/#8048 一并带来的新字段，含 requirementVersion/requirementSha256/dispatchPlanGeneration 三个本端点必需的真值，此前全仓无接口能给出）取得 expectedRequirementVersion=1/expectedRequirementSha256=814e3f85.../expectedPlanGeneration=359984828583645184，groups[] 取自 candidates 返回的 retainedGroupIds 两个 assignmentGroupId，实测 code=200/confirmed=true/finalPlanPublished=true。四项证据补全，判据满足，回填 verified。 前端实证维持 not_required(mmg 2026-09-20):四端点入参/出参零变化、TRAVEL 逐字不变、TRANSFER 前端不可达(809009 开关仍关,#7443 维持挂起);canonicalSnapshot=null 自验:AssignModal applyCanonicalSnapshotToDraft 首行 `!snapshot` 静默 return,不报错、草稿保持现状,合法降级形态既有处理;#7443 启动条件更新为 产品排期+809009 开关+outbox 修复交接件(AC-24 本件已销),已入前端 memory。"
+status_note: "【2026-09-20 AC-26 收尾】gateway_status 回填 verified，四个端点（「二、变更接口清单」全部条目）均经网关实测（cw_test_7443 账号，dev-v3 测试服，fleet 部署 dev-v3@311dc92ee，2026-09-20 17:46:56，含 PR #7952/c527e48c3 + #8048 + #8042；取证前后各跑一次 deploy-status.sh，两次 fleet/order-v3 commit 一致，证据有效）：(1) POST /admin/fleet/assignments/candidates（requirementId=2101219393722634242）：canonicalSnapshot 非 null；(2) POST /admin/fleet/assignments/{id}/change（TRANSFER 派车行 2101174428044824578）：code=200；(3) POST /admin/fleet/assignments/{id}/confirm（TRANSFER 派车行 2101174428711686146）：code=200/confirmed=true/assignmentStatus=assigned（此前记录的 582093 已由 #8037 修复）；(4) POST /admin/fleet/assignments/requirements/{requirementId}/confirm（TRANSFER 需求 2101567456596365313，订单 2101566624467419137）：借新上线的 GET /admin/fleet/board/orders/{orderId} 返回的 requirementIdentities（#7990/#8048 一并带来的新字段，含 requirementVersion/requirementSha256/dispatchPlanGeneration 三个本端点必需的真值，此前全仓无接口能给出）取得 expectedRequirementVersion=1/expectedRequirementSha256=814e3f85.../expectedPlanGeneration=359984828583645184，groups[] 取自 candidates 返回的 retainedGroupIds 两个 assignmentGroupId，实测 code=200/confirmed=true/finalPlanPublished=true。四项证据补全，判据满足，回填 verified。 前端实证维持 not_required(mmg 2026-09-20):四端点入参/出参零变化、TRAVEL 逐字不变、TRANSFER 前端不可达(809009 开关仍关,#7443 维持挂起);canonicalSnapshot=null 自验:AssignModal applyCanonicalSnapshotToDraft 首行 `!snapshot` 静默 return,不报错、草稿保持现状,合法降级形态既有处理;#7443 启动条件更新为 产品排期+809009 开关+outbox 修复交接件(AC-24 本件已销),已入前端 memory。【mmg 2026-09-21 C 段实证补充】#7443 C 交付(hl-admin v2.1 662310ea)再次确认本件前端零改动:四端点请求/响应契约逐字未变,改派按 assignmentId 反查服务端自取基线,TRANSFER 行零改动可用;canonicalSnapshot=null 合法降级既有处理(applyCanonicalSnapshotToDraft 首行静默 return)不动。"
 updated_at: "2026-09-20"
 base: "dev-v3"
 ---
@@ -7,13 +7,13 @@ author: "wx(GIT)"
 change_type: "修改接口"
 backend_status: "deployed"
 gateway_status: "verified"
-frontend_status: "pending"
+frontend_status: "verified"
 frontend_owner: "mmg"
-frontend_ref: ""
-target_release: ""
-verified_at: "2026-09-20"
-status_note: "后端已合入 dev-v3（PR #8024，squash 提交 920f29d76）并部署测试服：deploy-status.sh 回读 hl-order-service-v3 = dev-v3 @ 920f29d76、BEHIND=0/N、STATE=ok，两实例滚动重启均 UP，判据 git merge-base --is-ancestor 920f29d76 920f29d76 = true。gateway_status=verified 的依据是四条真实网关调用而非源码推断：①读口双槽（含阳性对照：未提交需求的订单两个字段都是 null，证明不是恒有值）②一次 submit 同时提交两份 → HTTP 200，落库两条 active 行，fleet 分别为 bus/19座/1台 与 mpv/7座/2台 ③调整记录两条 label 原文不同 ④无大交通时 809002。🔴 一条必须连着读的限定：本文只验证了「提交」这一段。同一次实测观测到 TRANSFER 需求同步给车务的 outbox 命令持续失败（order_fleet_command_outbox command_type=RECONCILE，TRAVEL=SUCCEEDED 而 TRANSFER=PENDING/retry_count=2，last_error_message='Fleet 用车需求换版失败: code=605905, message=需求版本过期'），根因是 hl-fleet-service AssignmentService:11492 requireCurrentVehicleRequirementForMutation 取当前需求时不带 kind、恒取 TRAVEL，与 TRANSFER 的 requirementId 比对必然不等。即：前端按本文接完即可正常提交并回显，但提交出去的接送机需求在修复该缺陷之前到不了车务侧，端到端业务尚未打通。该缺陷已在修（属 #7990 那一族），修好后另发交接件，不影响本文的前端契约。"
-updated_at: "2026-09-20"
+frontend_ref: "6c091ef2486e0844d5bf1e39c705e43bec875e4f"
+target_release: "v2.1"
+verified_at: "2026-09-21"
+status_note: "后端已合入 dev-v3（PR #8024，squash 提交 920f29d76）并部署测试服：deploy-status.sh 回读 hl-order-service-v3 = dev-v3 @ 920f29d76、BEHIND=0/N、STATE=ok，两实例滚动重启均 UP，判据 git merge-base --is-ancestor 920f29d76 920f29d76 = true。gateway_status=verified 的依据是四条真实网关调用而非源码推断：①读口双槽（含阳性对照：未提交需求的订单两个字段都是 null，证明不是恒有值）②一次 submit 同时提交两份 → HTTP 200，落库两条 active 行，fleet 分别为 bus/19座/1台 与 mpv/7座/2台 ③调整记录两条 label 原文不同 ④无大交通时 809002。提交同步给车务走的是异步 outbox 命令（command_type=RECONCILE）：HTTP 200 代表订单侧落库成功，车务侧的确认在其后异步完成，两者有一个时间间隔。该链路已于 2026-09-21 在测试服端到端实测打通——hl-fleet-service 部署至 dev-v3 @ c238f38c3（含 #7990 的两个修复提交 53c2ff2d1 / bf4fba5a2，git merge-base --is-ancestor 均为 true），同一订单一次提交两类需求后 order_fleet_command_outbox 两行 RECONCILE（TRAVEL requirement_id=2101937490971742210、TRANSFER requirement_id=2101937491068211201）均 status=SUCCEEDED、last_error_message 为 NULL，两类对称。前端调用时会遇到的限定另见正文「2026-09-21 补充」小节：环境开关 hl.order.requirement.transfer-kind-submit-enabled、809002 的触发条件、以及工单 #8056（TRANSFER-only 订单在若干消费方上静默出不了数）目前仍 open，均不挡本文描述的提交/回显契约，但请知悉。前端已于 2026-09-21 交付 A+B 订单侧(hl-admin v2.1 6c091ef24)：调整弹窗双槽(snapshot transferRequirement 回显独立槽、hasPickupTime!==true 置灰引导防 809002、单槽走 putVehicleRequirement 显式 kind、双槽走 submitAdjustment 同事务两键)、既有写口补显式 kind(reject 走 query 不进 body)、结算 step3 手录车行 requirementKind 归属(FLEET 省略/MANUAL 手选+回显带回/双需求缺归属前置拦截防 809008)。C 车务侧 TRANSFER 派车属 18_7443 范围另起交付。"
+updated_at: "2026-09-21"
 base: "dev-v3"
 ---

@@ -28,7 +28,7 @@ base: "dev-v3"

 ## ⚠️ 关键变化

-**接口契约本身已闭环（可正常提交、可双槽回显），但接送机（TRANSFER）需求同步给车务的链路目前恒失败，业务尚未端到端打通。** 前端可以按本文正常开工，但不要把"提交成功"等同于"车务已收到派车任务"。完整证据与根因见「六、边界行为」§「本文的覆盖边界」。
+**接口契约已闭环，同步车务链路也已端到端实测打通**（提交 → 双槽回显 → 车务侧 RECONCILE 命令 TRAVEL / TRANSFER 双双 `SUCCEEDED`，读数见「六、边界行为」§「同步车务链路：已端到端实测」）。唯一要记住的语义差别：提交接口返回 200 代表**订单侧**落库成功，车务侧的确认由异步 outbox 命令在其后完成，两者之间有一个异步间隔——不要拿 200 去断言"车务此刻已收到派车任务"。三条调用时会实际撞上的限定（单槽写口 `kind` 默认值、`809002` 触发条件、环境开关状态）与已知的下游消费方缺口见「六、边界行为」及其后的「2026-09-21 补充」。

 ---

@@ -237,7 +237,7 @@ GET /v3/admin/order/2101219133700952066/adjustment/snapshot?scope=VEHICLE_REQ
 - 只传 `vehicleRequirement` → 行为与改动前逐字节一致；改动前的请求体不含 `transferRequirement` 字段，旧前端请求不受影响（向后兼容）
 - `fleet[].vehicleType` 只接受 `suv`/`mpv`/`bus`/`sedan` 四个大类 key，后端兼容历史别名并归一
 - 调整记录 `adjustment-record` 会为两类需求各产出一条可区分的 `VEHICLE_REQ` 条目（`行程用车需求已调整` / `接送机用车需求已调整`），见「八、测试环境已验证」③
- 🔴 提交成功仅代表**订单侧**需求已落库；同步给车务的 outbox 命令目前对 `TRANSFER` 恒失败，详见「六、边界行为」的覆盖边界说明——业务尚未端到端打通
+- 提交成功代表**订单侧**需求已落库，车务侧由异步 outbox 命令（`command_type=RECONCILE`）在其后确认；该链路 TRAVEL / TRANSFER 两类已于 2026-09-21 在测试服实测双双 `SUCCEEDED`，前端无需为它写任何补偿逻辑，只是不要拿提交接口的 200 去断言车务此刻已确认（读数见「六、边界行为」§「同步车务链路：已端到端实测」）

 ---

@@ -260,7 +260,7 @@ GET /v3/admin/order/2101219133700952066/adjustment/snapshot?scope=VEHICLE_REQ
 | ✅ 只提交接送机用车（订单已录大交通） | `{"updates":{"transferRequirement":{"fleet":[...]}}}` | 200，落 1 条 `TRANSFER` 需求 |
 | ✅ 同页两类都提交 | `{"updates":{"vehicleRequirement":{...},"transferRequirement":{...}}}` | 200，落 2 条 active 需求（见「八」②实测） |
 | ❌ 提交接送机用车但订单未录大交通 | `{"updates":{"transferRequirement":{"fleet":[...]}}}` | `809002`，整笔回滚（见「八」④实测） |
-| ❌ 提交接送机用车但开关未开（生产默认） | 同上 | `809009` |
+| ❌ 提交接送机用车但开关未开（默认关闭） | 同上 | `809009` |
 | ❌ 期望通过入参指定 `serviceDates` | `{"updates":{"transferRequirement":{"serviceDates":[...]}}}` | **无效**——该字段不在 `VehicleRequirementBodyVO` 定义内，传了也会被忽略，服务日仍按后端派生规则计算 |

 ### 前端必须处理的前置：没有大交通时提交接送机需求会失败
@@ -276,13 +276,13 @@ GET /v3/admin/order/2101219133700952066/adjustment/snapshot?scope=VEHICLE_REQ
 | 错误码 | 触发条件 | 前端应做的下一步 |
 |---|---|---|
 | `809002` | 该订单尚未录入大交通行程，却提交了 `transferRequirement` | **去补大交通**——引导用户先在大交通模块录入行程，而不是重试提交 |
-| `809009` | `hl.order.requirement.transfer-kind-submit-enabled` 开关未开（生产环境默认关闭） | **找后端开开关**——这不是数据问题，重试/补数据都无效，需要后端改配置并重启实例 |
+| `809009` | 当前环境的 `hl.order.requirement.transfer-kind-submit-enabled` 开关未开启 | **找后端确认该环境的开关**——这不是数据问题，重试/补数据都无效，需要后端改配置并重启实例 |

 ### 环境开关

 `hl.order.requirement.transfer-kind-submit-enabled`
- **代码默认 `false`**；生产环境未开，提交 `kind=TRANSFER` 返 `809009`
- **测试服已置 `true`**（2026-09-19 15:33:32 发布，随 order-v3 重启生效）
+- **代码默认 `false`**：未显式置 `true` 的环境上，提交 `kind=TRANSFER` 返 `809009`
+- **测试服已置 `true`**（随 order-v3 重启生效）
 - ⚠️ 该配置无 `@RefreshScope`（源码 `RequirementService` 注释确认），改完必须重启服务才生效，Nacos 热推不生效

 ---
@@ -315,18 +315,34 @@ GET /v3/admin/order/2101219133700952066/adjustment/snapshot?scope=VEHICLE_REQ
 - `updates` 全部子字段为空 → `587012`
 - 老数据兼容：改动前落库的旧行仍被正确识别为 `requirement_kind=TRAVEL` 并映射进 `vehicleRequirement`，不会因为响应新增字段而出现兼容异常

-### 🔴 本文的覆盖边界：只验到「提交」为止
+### 同步车务链路：已端到端实测（2026-09-21）

-同一次实测里观测到：TRANSFER 需求同步给车务的 outbox 命令**持续失败**
-（`order_fleet_command_outbox`，`command_type=RECONCILE`：TRAVEL `SUCCEEDED`，
-**TRANSFER `PENDING` / `retry_count=2` / `last_error_message="Fleet 用车需求换版失败: code=605905, message=需求版本过期"`**）。
+提交接口返回 HTTP 200 代表**订单侧**需求已落库；同步给车务走的是异步 outbox 命令（`command_type=RECONCILE`），
+车务侧的确认在其后完成。**这条链路 TRAVEL / TRANSFER 两类已实测打通，前端按本文接入即可，不必为它写补偿逻辑。**

-⇒ **前端按本文接完即可正常提交并回显，但提交出去的接送机需求目前到不了车务侧。**
-该缺陷在 fleet（`AssignmentService:11492` 取当前需求不带 kind、恒取 TRAVEL），已在修，
-修好后另发交接件。**它不改变本文的前端契约**，可以并行开工。
+| 实测项 | 读数 |
+|---|---|
+| hl-fleet-service 部署版本 | `dev-v3 @ c238f38c3`，`STATE=ok`；`c238f38c3` 已含 #7990 的两个修复提交 `53c2ff2d1` / `bf4fba5a2`（`git merge-base --is-ancestor` 均为 `true`） |
+| outbox 行 · TRAVEL | `requirement_id=2101937490971742210` → `status=SUCCEEDED`，`last_error_message=NULL` |
+| outbox 行 · TRANSFER | `requirement_id=2101937491068211201` → `status=SUCCEEDED`，`last_error_message=NULL` |
+| 读口双槽 | 同一订单 `snapshot?scope=VEHICLE_REQ` 的 `vehicleRequirement` 与 `transferRequirement` 均非 `null`；阳性对照单 `2087157633055064066`（未提交过接送机需求）的 `transferRequirement` 为 `null`，证明该字段不是恒有值 |

-⚠️ 写下这段是因为「四条实测全达成」这个汇总句**丢掉边界之后会变强**——
-会被读成「接送机用车已经端到端可用」，而那句话今天还不成立。
+样本订单 `9199000000000000002`（2026-09-21 新造，一次提交两类需求触发换版 RECONCILE），两类对称、`605905` 未再出现。
+
+唯一需要前端记住的语义差别仍是：**200 ≠ 车务此刻已确认**，中间隔着一次异步投递，不要拿前者断言后者。
+下面「2026-09-21 补充」的三条限定是**契约自带的**，请一并读完再接入。
+
+### 2026-09-21 补充：前端调用时会遇到的三个限定
+
+这三条都是**契约本身自带的限定**（不是内部进度），无论后端那条同步链路处于什么状态都成立，前端接入前务必确认：
+
+1. **单槽快捷写口不要漏传 `kind`**：`putVehicleRequirement`（单槽写口）用的是 `VehicleRequirementReqVO.kind`，`@Pattern` 限定取值 `TRAVEL|TRANSFER`，**不传时默认 `TRAVEL`**。走这条快捷写口提交接送机需求，必须显式传 `kind=TRANSFER`，否则会被当成行程用车落库。
+2. **`hasPickupTime=false` 时提交 TRANSFER 会报 `809002`**：当 `vehicleTransportSummary.hasPickupTime=false`（即该订单没有大交通声明，没有抵达/出发时间可锚定接送机服务日）时，无论走单槽还是双槽写口提交 `TRANSFER` 需求都会抛 `809002`。前端应在没有大交通数据时禁用或提示「接送机用车」入口，而不是让用户提交后才看到报错。
+3. **环境开关是独立配置项**：接送机需求提交受开关 `hl.order.requirement.transfer-kind-submit-enabled` 控制，**代码默认 `false`**，关闭时提交 `kind=TRANSFER` 一律返 `809009`（写口直接拒绝，一行都不落库）。**测试服已开启**，本文所有实测读数都是在开关打开的前提下取得的。收到 `809009` 即表示所在环境的开关没开，属配置问题，重试与补数据均无效。
+
+另外，工单 **#8056**（TRANSFER-only 订单在若干下游消费方上静默出不了数——「取当前需求恒取 TRAVEL」这一类缺陷的剩余落点）**仍处于 open 状态**：只提交 TRANSFER、不提交 TRAVEL 的订单，在部分下游消费方上可能仍会静默缺数据。这条不影响本文描述的提交/回显契约，但请知悉，遇到"只提了接送机、下游看不到数据"的反馈时可以先对号排查这条。
+
+**后端双槽契约可以对接**：实测样本 `GET /v3/admin/order/2100856430239121409/adjustment/snapshot?scope=VEHICLE_REQ` 返回里 `transferRequirement` 键**存在**、值为 `null`（说明字段已经在响应结构里，只是这张单目前没有提交过接送机需求，不是字段缺失）。提交时按「二、变更接口清单」里的写口，在 `updates.transferRequirement` 放一份与 `updates.vehicleRequirement` **完全相同的结构**即可写入第二行（`requirement_kind=TRANSFER` 的那一行）。

 ---

@@ -395,7 +411,7 @@ GET /v3/admin/order/2101219133700952066/adjustment/snapshot?scope=VEHICLE_REQ
 - **是否破坏向后兼容**: 否——`vehicleRequirement` 字段名/类型/语义零变更，旧前端请求体（不含 `transferRequirement`）行为与改动前逐字节一致
 - **前端是否必须同步上线**: 否，本次是纯新增字段/新增可选提交槽，前端可延后接入；接入前不会影响现网「行程用车」链路
 - **前端 workaround 清理点**: 无——此前接送机用车没有任何前端录入通道，不存在需要撤下的旧 workaround
- 🔴 **业务闭环限制**：接口契约本身已闭环（提交 + 回显），但 TRANSFER 需求同步给车务的链路当前恒失败（见「六、边界行为」覆盖边界），前端接入后用户能成功提交，但接送机需求实际派不出车，直到 fleet 侧缺陷修复为止
+- **提交与车务确认之间隔着一次异步投递**：接口契约已闭环（提交 + 回显），"提交成功"代表订单侧已落库，车务侧由异步 outbox 命令在其后确认——该链路两类需求已于 2026-09-21 实测双双 `SUCCEEDED`；读数见「六、边界行为」§「同步车务链路：已端到端实测」，调用限定见其后的「2026-09-21 补充」

 ---

@@ -466,7 +482,8 @@ updates.transferRequirement = {fleet:[{vehicleType:"mpv", seats:7,  count:2}]}

 - 关联 Issue: [wx/HL#7443](https://git.1814.love:8443/wx/HL/issues/7443)
 - 关联 PR: [wx/HL#8024](https://git.1814.love:8443/wx/HL/pulls/8024)（squash 合并至 dev-v3 @`920f29d76`）
- fleet 侧 outbox 换版失败（`code=605905`）已在修，属 `#7990` 那一族，修好后另发交接件——不影响本文描述的前端契约
+- 关联 Issue（仍 open）: [wx/HL#8056](https://git.1814.love:8443/wx/HL/issues/8056)（TRANSFER-only 订单在若干下游消费方上静默出不了数，详见「2026-09-21 补充」）
+- 关联 Issue: [wx/HL#7990](https://git.1814.love:8443/wx/HL/issues/7990)（接送机需求同步车务曾恒返 `605905`）——修复提交 `53c2ff2d1` / `bf4fba5a2` 已随 hl-fleet-service `c238f38c3` 部署测试服，2026-09-21 实测 TRANSFER 侧 RECONCILE `SUCCEEDED`，`605905` 未再出现

 ## 关联 / 联系人

@@ -7,12 +7,12 @@ author: "wx(GIT)"
 change_type: "修改接口"
 backend_status: "deployed"
 gateway_status: "verified"
-frontend_status: "not_required"
+frontend_status: "verified"
 frontend_owner: "mmg"
-frontend_ref: ""
-target_release: ""
-verified_at: ""
-status_note: "backend 已部署到 311dc92ee（hl-fleet-service，2026-09-20 17:46:56，STATE=ok；jar 字节口径已验：605311 命中 2 处，阳性对照老码 605015 命中 1 处，两者都非零说明检索方法本身有效）。gateway_status=verified 依据 2026-09-20 18:0x 经测试网关（api.test.1814.love:9443，账号 cw_test_7443）实测 GET /admin/fleet/board/orders/2101566624467419137 返 HTTP 200（该订单同时有 TRAVEL 与 TRANSFER 两条已确认需求，修复前此形态必返 500），requirementIdentities 返两项：TRAVEL(requirementId=2101567456462147586, version=1, sha256=bcfea7cf…c5cb, generation=359969759900602368) 与 TRANSFER(requirementId=2101567456596365313, version=1, sha256=814e3f85…c21c, generation=359984828583645184)。该组值随后被原样用于 POST /admin/fleet/assignments/requirements/2101567456596365313/confirm，返 code=200, confirmed=true, finalPlanPublished=true （两个执行段均 assigned）——即本字段不只是返回了，而是真的能驱动接送机需求确认走通，这是本篇的效果判据。frontend_status=pending：响应结构新增字段，前端取接送机确认参数必须改用 requirementIdentities 里 kind 匹配的那一项，顶层三字段恒指 TRAVEL。 前端实证翻 not_required(mmg 2026-09-20,挂起期判定):requirementIdentities/605311 全仓零命中;需求级确认取参 useAssignFlow.js 用顶层 requirementSha256(恒 TRAVEL),对现行 TRAVEL 流程逐字正确;500 修复与 605311 由拦截器透 message 自动受益。TRANSFER 接入时(#7443 启动)义务已入前端 memory:取参必须 requirementIdentities.find(kind==='TRANSFER')(禁顶层三字段与 driverConfirmationSummary.dispatchPlanGeneration),且接送机天然多段须走需求级确认端点(单车 confirm 恒 605057)。"
+frontend_ref: "662310eac02ef5afc84c81b242949ca536c79489"
+target_release: "v2.1"
+verified_at: "2026-09-21"
+status_note: "backend 已部署到 311dc92ee（hl-fleet-service，2026-09-20 17:46:56，STATE=ok；jar 字节口径已验：605311 命中 2 处，阳性对照老码 605015 命中 1 处，两者都非零说明检索方法本身有效）。gateway_status=verified 依据 2026-09-20 18:0x 经测试网关（api.test.1814.love:9443，账号 cw_test_7443）实测 GET /admin/fleet/board/orders/2101566624467419137 返 HTTP 200（该订单同时有 TRAVEL 与 TRANSFER 两条已确认需求，修复前此形态必返 500），requirementIdentities 返两项：TRAVEL(requirementId=2101567456462147586, version=1, sha256=bcfea7cf…c5cb, generation=359969759900602368) 与 TRANSFER(requirementId=2101567456596365313, version=1, sha256=814e3f85…c21c, generation=359984828583645184)。该组值随后被原样用于 POST /admin/fleet/assignments/requirements/2101567456596365313/confirm，返 code=200, confirmed=true, finalPlanPublished=true （两个执行段均 assigned）——即本字段不只是返回了，而是真的能驱动接送机需求确认走通，这是本篇的效果判据。frontend_status=pending：响应结构新增字段，前端取接送机确认参数必须改用 requirementIdentities 里 kind 匹配的那一项，顶层三字段恒指 TRAVEL。 前端实证翻 not_required(mmg 2026-09-20,挂起期判定):requirementIdentities/605311 全仓零命中;需求级确认取参 useAssignFlow.js 用顶层 requirementSha256(恒 TRAVEL),对现行 TRAVEL 流程逐字正确;500 修复与 605311 由拦截器透 message 自动受益。TRANSFER 接入时(#7443 启动)义务已入前端 memory:取参必须 requirementIdentities.find(kind==='TRANSFER')(禁顶层三字段与 driverConfirmationSummary.dispatchPlanGeneration),且接送机天然多段须走需求级确认端点(单车 confirm 恒 605057)。【mmg 2026-09-21 交付,not_required 翻 verified】requirementIdentities 已随 #7443 C 段消费(hl-admin v2.1 662310ea):AssignModal requirementScopedOrder 按 kind 匹配项覆写 requirementId/requirementVersion/requirementSha256/dispatchPlanGeneration(顶层三字段与整单 summary 均禁用,代际 null 透传),kind 切换走 initializationIdentity 统一重置;新派 batch 取参义务已落地。需求级确认端点按 kind 取参目前仅新派链路使用,confirmHold 复核(整单 activeAssignments 无法按 kind 拆 groups)留后续项。"
 updated_at: "2026-09-20"
 base: "dev-v3"
 ---
@@ -0,0 +1,166 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7105"
+title: "团期合同保险出具门已打通，撤销上一版「按钮恒失败」的说明"
+consumer: "admin"
+author: "jw(GIT)"
+change_type: "修复"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "f3a22be3a9efa374aaa6442302780d6a02b8ce8e"
+target_release: "v2.1"
+verified_at: "2026-09-21"
+status_note: "更正 2026-09-07 那条 #7105 的首段警告。彼时说「酒店 ready 线上无写入方(#4132)，故 issuable 恒 false、手动开/作废重开恒返 589548」——两个前提现已都不成立：#7248/PR#7249 把出具门从「判团期状态」改成「资源准备中+四项 ready 全 true 即放行」；house 域已有三处回填 hotel_ready。2026-09-21 TEST 实测：RESOURCE_PREPARING 团期 issuable=true，issue 端点返 200 逐户结果而非整单 589548，四项配齐团期里 40 户已确认行程的子订单合同全 SIGNED、保险全 INSURED。前端需调整：不要再把出具按钮按恒失败处理，失败语义从整单 BusinessException 改为 200+逐户 outcome=FAILED+message。接口契约零变更，无需改调用代码。【前端交付 2026-09-21 mmg：实证两处要求早已具备——按钮按面板 issuable 字段置灰（ChipItemsPanel）、逐户失败 200+outcome=FAILED+message 逐行原样展示（ContractActionModal），行为零改动；仅清理过期口径：出具置灰 tooltip 去掉「（#4132 待后端）」用户可见标注 + 五处注释更新，hl-admin v2.1 f3a22be3。】"
+updated_at: "2026-09-21"
+base: "dev-v3"
+---
+
+# 团期「合同保险」：出具门已打通，撤销上一版的「按钮恒失败」说明
+
+> **服务**: hl-order-service-v3 (端口 8086/8186)
+> **Issue**: #7105（本条更正）、#7248 / PR #7249（实际修复）
+> **日期**: 2026-09-21
+> **影响范围**: 管理后台「团期详情 → 合同保险」Tab 的按钮可用性判断与失败处理分支。
+
+---
+
+## ⚠️ 关键变化
+
+上一版 `2026-09/07_7105_团期合同保险面板与逐户出具-新增接口-管理后台.md` 开头那段
+「**当前不可用的部分（重要）**」说：
+
+> 酒店 ready 线上**没有**写入方（HL#4132）→ `issuable` **恒为 false**、
+> 手动开 / 作废重开 **恒返 589548**、团期单合同与保险**不会自动出具**。
+
+**这段话现已失效，本条予以撤销。** 实际现在是：
+
+- `issuable` **会返 true**，团期停在「资源准备中」也能返 true
+- 手动开 / 作废重开 **不再整单返 589548**
+- 团期单的合同与保险 **会自动出具**
+
+**接口契约（路径、入参、出参字段、返回值结构）零变更**，前端不必改调用代码，
+但**要改按钮可用性与失败处理这两处判断**，详见第三节。
+
+---
+
+## 一、上一版为什么会写错
+
+两条前提当时都成立，之后各自被改掉了：
+
+| 前提 | 当时 | 现在 |
+|---|---|---|
+| 出具门怎么判 | 判「团期状态已进入 MATERIAL_PREPARING 及之后」 | #7248 / PR #7249（`9f47f620f`，2026-09-07）改判四个 ready 标志：**资源准备中 + 四项 ready 全 true 即放行** |
+| `hotel_ready` 有没有写入方 | 没有，挂在一个从未发出的事件上（#4132） | 有，house 域三处在回填 |
+
+当时那个判法和 #7023 的进阶门首尾相接，构成完全死锁：
+
+```
+要出合同 → 需 MATERIAL_PREPARING → 需合同全部已签 → 需先出过合同
+```
+
+`hotel_ready` 现有的三处写入方：
+
+| 写入点 | 文件 |
+|---|---|
+| 团期逐日房态确认 | `house/groupbatch/manager/GroupBatchRoomDayConfirmManager.java:457` |
+| 同上（另一条分支） | `house/groupbatch/manager/GroupBatchRoomDayConfirmManager.java:767` |
+| 团期整团配房 | `house/service/HouseGroupBatchAssignmentService.java:201` |
+
+> ℹ️ #4132 工单本身在 Gitea 上仍是 open / 待处理，**光看工单状态会以为还堵着**。
+> 它描述的那条 baseline 事件链路确实还没做，但 `hotel_ready` 的回填已由上面三处覆盖，
+> 出具门不再依赖 #4132。
+
+---
+
+## 二、现在的实际行为
+
+### 出具门判定（`GroupBatchContractResolver.issuable`）
+
+| 团期状态 | 是否放行 |
+|---|---|
+| 招募中 RECRUITING | ❌ 不放行（未成团，四项必不全） |
+| **资源准备中 RESOURCE_PREPARING** | ✅ **四项 ready 全 true 就放行**（原死锁点，本次变化就在这一行） |
+| 物资准备中 MATERIAL_PREPARING 及之后（待出行 / 出行中 / 核验中 / 已结算） | ✅ 放行（必然已配齐过，不依赖存量标志是否回填） |
+| 已流团 CANCELLED | ❌ 不放行 |
+
+### 失败语义（前端最需要注意的一点）
+
+`589548`（四项未配齐）现在只在**整单**层面出现，且只在团期真的没配齐时出现。
+门过了之后，**逐户的失败不再是 589548，而是 HTTP 200 + 逐户 `outcome=FAILED` + `message`**：
+
+```json
+{
+  "code": 200, "message": "成功", "success": true,
+  "data": {
+    "totalCount": 1, "successCount": 0, "failCount": 1, "skipCount": 0,
+    "results": [
+      { "orderId": "2099947354713993217", "target": "CONTRACT",
+        "outcome": "FAILED", "message": "请先确认行程后再创建合同" }
+    ]
+  }
+}
+```
+
+最常见的一条逐户失败是 **`请先确认行程后再创建合同`**（合同域 `510220`）：
+合同只能在子订单处于 `PENDING_DEPARTURE` 或 `TRAVELLING` 时创建
+（`ContractCreateService.CONTRACT_CREATABLE_ORDER_STATUSES`）。
+也就是说，**团期四项配齐只是开了团期这道门，子订单自己还没确认行程的户依然出不了合同**，
+这是两道独立的前置，页面上要能把这条 `message` 原样显示给操作人，不要吞掉。
+
+---
+
+## 三、前端要改的两处
+
+| # | 改前（按上一版说明写的） | 改后 |
+|---|---|---|
+| 1 | 出具类按钮按「反正恒失败」处理（常驻置灰 / 挂提示 / 干脆不接） | **按 `issuable` 字段置灰**。它现在会真的返 true，按钮要能点 |
+| 2 | 失败一律当 589548 整单报错 | 先看 HTTP 层 `code`：`589548` 仍是整单拒绝（四项未配齐）；`code=200` 时要**逐户读 `results[].outcome`**，`FAILED` 的户把 `message` 原样展示 |
+
+其余不用动：三态徽标继续用后端 `contractStateText` / `insuranceStateText`，
+不要自己映射；权限码仍是读 `group-batch:view`、写 `group-batch:contract:issue`。
+
+---
+
+## 四、TEST 实测记录（2026-09-21）
+
+均经真实网关 `api.test.1814.love`，非单测。
+
+| # | 验证项 | 结果 |
+|---|---|---|
+| 1 | `GET .../group-batch/2100129355043627009/contracts` | `issuable=true`，`batchStatus=RESOURCE_PREPARING`。**旧实现在此状态下必为 false**，这条直接证明门已改 |
+| 2 | `GET .../group-batch/2099947334803632130/contracts` | 同上，`issuable=true`，3 户明细正常返回 |
+| 3 | `POST .../contracts/issue`（`target=CONTRACT`） | 返 `code=200` + 逐户结果，**不再是整单 589548**；该户因自身未确认行程返 `outcome=FAILED` / `请先确认行程后再创建合同` |
+| 4 | TEST 库 `order_group_batch` 四项 ready 全 1 的团期 | 共 28 个（物资准备中 17、资源准备中 5、核验中 2、待出行 2、出行中 1、行程结束 1）；`hotel_ready=1` 的记录共 52 条 |
+| 5 | 上述团期下**已确认行程**的子订单合同 / 保险状态 | 40 户（已完成 23 + 出行中 10 + 待出行 7）**合同全部 SIGNED、保险全部 INSURED**，无一户卡在「已确认行程但合同未出」，最新一条更新时间 2026-09-21 15:31 |
+
+第 5 条是自动出具链路当前工作正常的证据：如果门还锁着，这些户会全部停在「未出」。
+
+**未实测**：单次「手动开 → 合同真的开出来」的正向成功路径。TEST 上四项配齐的团期里，
+已确认行程的户合同都已由自动链路出过（无可补开的户），未确认行程的户被 `510220` 挡住，
+现成数据里没有可打的靶子；造一个需要先补该订单的酒店供应商字段。
+门已通的结论由第 1、3、5 条支撑，不依赖这一条。
+
+**取证范围仅 TEST**。正式环境本机无查询通道，上一版原文里的「线上」二字本条不予断言。
+
+---
+
+## 五、不影响范围
+
+- **接口契约零变更**：四个端点的路径、方法、入参、出参字段、错误码全部未动
+- **散客单不受影响**：`productBatchId` 为空的订单在出具门上恒放行，从头到尾没被这个问题波及
+- **零影响**：小程序端、订单侧合同 / 保险接口（`create-by-scheme` / `purchase-by-scheme` 等）、网关配置、权限码
+
+---
+
+## 六、相关文档
+
+- 被本条更正的条目：`changelogs-v2/2026-09/07_7105_团期合同保险面板与逐户出具-新增接口-管理后台.md`
+- 修复提交：`9f47f620f`（`fix(group): 合同出具门改判四项 ready，解开与 #7023 的死锁 Closes #7248`）
+- 接口文档：`docs/group/团期模块接口文档-v2.0.html` GB-ADM-030 / GB-ADM-031 章节
+
+## 关联 / 联系人
+
+- 后端：jw
+- 相关工单：#7105（原交付）、#7248 / PR #7249（门锁修复）、#7023（进阶门）、#4132（仍 open，但已不阻塞本功能）
@@ -0,0 +1,383 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7211"
+title: "团期子订单「调整订单」弹窗联系入口由联系房务/联系车务改为联系团期管理员（沿用既有 open-group 能力）"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "前端缺陷"
+backend_status: "deployed"
+gateway_status: "not_required"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "4d092b09bec1e9e4c9e1326940616b4a19865aa7"
+target_release: "v2.1"
+verified_at: "2026-09-21"
+status_note: "wx 2026-09-21 定：团期子订单的定制师不能直接联系车务/房务，只能联系团期管理员。这是前端 UI 口径变更 + 后端既有能力复用，后端零代码改动。判据字段：GET /v3/admin/order/{id}/itinerary 响应 ItineraryVO.groupBatchId 非空即团期子订单（javadoc 原文『前端「联系团期管理员」按钮显隐只看本字段』），不要用 OrderMainVO.groupBatchId（两者派生口径不同，历史兼容单上后者为 null 会误判为非团期单）。联系入口调 POST /admin/message/chat/open-group（网关路由 /admin/message/** → lb://hl-user-service），请求体只收 orderId，团期管理员是团队制不接受 peerAdminId；准入=当前定制师或持权限码 group-batch:demand:confirm，鉴权失败 281002 且零写入；错误码另有 281012(缺 orderId)/281015(非团期单)。【前端交付 2026-09-21 mmg：FunItemAdjustModal 标题栏按 itineraryGroupBatchId 切换——团期单只显「联系团期管理员」（角标 itineraryGroupUnreadCount，emit chat group 走既有 GROUP 会话链），普通单维持联系房务+联系车务；判据禁 OrderMainVO.groupBatchId 已 spec 钉住，32 例全过，hl-admin v2.1 4d092b09。】改动原因：团期子订单在房务侧被 808650 无条件拒绝逐户抢单，结构上永远没有房务认领人，定制师点「联系房务」建出的是 peer=0 占位会话。⚠️ 『团期房务链路不读这条会话』这一句是源码推断——com.hulalv.house.groupbatch 包对聊天相关接口 grep 零命中，阳性对照 HouseDetailAggregator.java 命中 25 处（复核后的实际数字，不是最初口头给出的 20 处，以本文复核为准）——不是在库里对一条真实占位会话做过 SELECT/已读水位验证，本文档已如实标注为推断而非实测结论，不作为确定性事实使用。范围不含车务侧：接送机沟通仍走订单维度 FLEET:{orderId}，#7440 既有定案不动；open-fleet/open-house 两端点本次不加团期守卫，仍可被直接调用，老客户端行为照旧。"
+updated_at: "2026-09-21"
+base: "dev-v3"
+---
+
+# 管理后台：团期子订单「调整订单」弹窗联系入口改为联系团期管理员
+
+> **存放目录**: 二期(v3) → `changelogs-v2/2026-09/`
+> **服务**: hl-order-service-v3（判据字段来源：`GET /v3/admin/order/{id}/itinerary`）+ hl-user-service（联系入口能力：`/admin/message/**`）
+> **PR**: 无（零代码改动，未产生新 PR）
+> **Issue**: #7211（沿用该单引入的 open-group 能力；本次是新增应用场景，不是新单）
+> **日期**: 2026-09-21
+> **影响范围**: 管理后台订单详情「调整订单」弹窗标题栏联系入口按钮（仅团期子订单）；普通订单不受影响
+
+---
+
+## ⚠️ 关键变化
+
+**本次没有新增、修改或删除任何接口，后端零代码改动。** 变化在前端：团期子订单的「调整订单」弹窗标题栏，原来并排的「联系房务」「联系车务」两个按钮应当隐藏，替换为「联系团期管理员」一个入口；判据字段与联系接口都是已经存在、已经部署的能力（`ItineraryVO.groupBatchId` + `POST open-group`），不需要等后端。普通（非团期）订单行为完全不变。
+
+---
+
+## 一、背景
+
+wx 2026-09-21 定案：**团期订单的定制师不能直接联系车务/房务，只能联系团期管理员。**
+
+### 为什么要改（不是单纯挪按钮）
+
+团期子订单在房务侧是**无条件拒绝逐户抢单**的（`HouseGroupBatchErrorCode.java:340`，`code=808650`「团期订单不支持逐户抢单/转单，请到团期抢单池整团认领」），所以团期子订单**结构上永远不会有房务认领人**。于是定制师点「联系房务」建出来的是一条 `peer=0` 的占位会话——消息能落库，但没有真实对端。这是一个静默黑洞：前端界面上显示发送成功，业务上大概率无人接收。
+
+「联系车务」不受影响（车务侧沟通不走本次改动，见「七、不影响范围」）。
+
+### 与原 #7211 changelog 的关系
+
+`open-group` 这条能力**不是本次新增**，它在 `changelogs-v2/2026-09/07_7211_定制师团期管理员站内会话GROUP-新增接口-管理后台.md` 里已经交付并于 2026-09-08 验证通过（`frontend_status: verified`，`frontend_ref: 86340b24`）。但那份文档覆盖的应用场景是**订单详情「住宿安排卡」**；本次是把同一个已验证的后端能力，接到**「调整订单」弹窗标题栏**这个不同的 UI 位置。接口本身、请求体、权限判定、返回结构，均与原文档完全一致，未改一行代码。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 查询订单行程安排 Tab（团期判据 + 未读角标） | GET | `/v3/admin/order/{id}/itinerary` | 复用不改 | `groupBatchId` 非空即团期子订单；`groupUnreadMessageCount` 是新按钮的未读角标字段 |
+| 2 | 打开/找回团期订单会话（联系团期管理员） | POST | `/admin/message/chat/open-group` | 复用不改 | 会话键 `GROUP:{orderId}`；请求体只收 `orderId` |
+
+---
+
+## 三、接口详情
+
+### 1. 查询订单行程安排 Tab `GET /v3/admin/order/{id}/itinerary`
+
+**VO**: 无独立请求VO（GET 路径参数 orderId）→ `ItineraryVO`
+
+#### 使用场景
+
+前端渲染订单详情「调整订单」弹窗标题栏之前，需要判断当前订单是否为团期子订单，以决定显示「联系房务」+「联系车务」两个按钮，还是显示「联系团期管理员」一个按钮；判据字段与对应未读角标字段均已存在于本接口的既有返回里，不需要新增字段或新接口。
+
+#### 入参字段表
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| id | Path | Long | 是 | - | 订单ID（`{id}`） |
+
+#### 出参字段表（`Result<ItineraryVO>`，仅列与本次判据/角标相关字段）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data.groupBatchId | String(Long) | 运营团期ID，取统一归团解析结果（含历史兼容单按 `product_batch_id` 反查的情形）。**前端「联系团期管理员」按钮显隐只看本字段**（非空即显示）。与 `OrderMainVO.groupBatchId`（直映射 `order_main` 原始列）语义不同：那个字段对历史兼容单为 `null`（`ItineraryVO.java:46-52`） |
+| data.groupUnreadMessageCount | Integer | 「联系团期管理员」按钮未读角标；当前登录定制师在本订单 GROUP 会话的未读数；非团期子订单/聊天未读 Feign 降级/未登录均返 0（`ItineraryVO.java:42-44`） |
+| data.unreadMessageCount | Integer | 「联系房务」按钮未读角标（HOUSE 会话），团期单改动后本按钮不再显示，该字段仍会返回但前端不读它 |
+| data.fleetUnreadMessageCount | Integer | 「联系车务」按钮未读角标（FLEET 会话），本次不受影响 |
+| data.canContactFleet | Boolean | 是否允许联系车务（存在 active 用车需求时为 true） |
+| data.contactFleetDisabledReason | String | `canContactFleet=false` 时的不可联系原因文案 |
+
+#### 请求示例
+
+```
+GET /v3/admin/order/2100856430239121409/itinerary
+```
+
+（GET 请求，无请求体）
+
+#### 响应示例
+
+> 按 `ItineraryVO` 字段契约构造（仅摘录与联系入口判据相关字段，`hotelGroup`/`vehicleGroup`/`vehicleHistory` 等字段本文档不展开），非测试服抓包实测：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "groupBatchId": "70001",
+    "groupUnreadMessageCount": 1,
+    "unreadMessageCount": 0,
+    "fleetUnreadMessageCount": 0,
+    "canContactFleet": true,
+    "contactFleetDisabledReason": null
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+非团期子订单时 `groupBatchId` 为 `null`（不是空字符串或 `0`），前端应据此隐藏「联系团期管理员」入口，保留原「联系房务」「联系车务」；聊天未读 Feign 降级时未读角标字段恒返回 `0`，不阻断行程 Tab 渲染、不报错：
+
+```json
+{ "code": 200, "message": "成功", "data": { "groupBatchId": null, "groupUnreadMessageCount": 0 }, "success": true }
+```
+
+#### 错误响应
+
+```json
+{ "code": 581007, "message": "订单不存在", "data": null, "success": false }
+```
+
+房务角色调用本接口会被拦（`OrderViewGuard.assertNotHouseRole()`）：
+
+```json
+{ "code": 581045, "message": "房务角色无权查看订单详情，房务仅可配房", "data": null, "success": false }
+```
+
+#### 业务边界
+
+- 判据字段唯一权威来源是 `ItineraryVO.groupBatchId`，**禁止使用 `OrderMainVO.groupBatchId`**——两者派生口径不同：后者直映射 `order_main` 原始列，历史兼容单（该列未回填、需按 `product_batch_id` 反查归团的单）在该字段上为 `null`，会被误判为非团期单。
+- 本接口不是本次新增，前端此前已在使用；本次变化只是在既有响应上新增"用 `groupBatchId` 驱动按钮显隐"这一层前端逻辑，不涉及接口改造。
+
+---
+
+### 2. 打开/找回团期订单会话（联系团期管理员） `POST /admin/message/chat/open-group`
+
+**VO**: `ChatOpenGroupReqVO → ChatOpenFullRespVO`
+
+#### 使用场景
+
+定制师在「调整订单」弹窗标题栏点击「联系团期管理员」时调用本端点；一个团期子订单对应一条会话（键 `GROUP:{orderId}`），双向可发起，一次调用返回会话元信息 + 订单卡 + 首屏消息 + 合并未读总数，并标记本会话已读。
+
+#### 入参字段表
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| orderId | Body | String(Long) | 是 | `@NotNull` | 团期子订单id。**请求体只收这一个字段，不接受 `peerAdminId`**——团期管理员是团队制（不指派到人，`batch_manager_id` 全站契约写死不启用），传了也不会被读取（`ChatOpenGroupReqVO.java`） |
+
+#### 出参字段表（`Result<ChatOpenFullRespVO>`）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data.conversationKey | String | 规范化会话键，固定形如 `GROUP:{orderId}` |
+| data.peerAdminId | Long | 团队制会话恒 `0`（无单一对端） |
+| data.peerName | String | 对方名称快照，如「团期管理员」 |
+| data.peerRole | String | 恒 `GROUP_ADMIN` |
+| data.peerRoleLabel | String | 中文角色标签 |
+| data.peerOnline | Boolean | 团队侧是否有在线成员 |
+| data.unreadCount | Integer | 我在该会话的未读数 |
+| data.isNew | Boolean | `true`=新建会话，`false`=找回已有会话 |
+| data.order | Object | 订单卡（`ChatOrderCardVO`）：`orderNo`/`teamNo`/`customerName`/`destination`/`tripDays`/`productName`/`adultCount`/`childCount`/`groupBatchId`/`groupBatchNo`/`groupBatchName`/`departDate` 等，其中 `groupBatchId`/`groupBatchNo` 供前端深链团期详情 |
+| data.thread | Object | 首屏消息（`conversationKey`/`hasMore`/`nextCursor`/`list[]`，最新一页20条） |
+| data.thread.list[] | Array | 单条消息字段（`ChatMessageRespVO`）：`messageId`/`senderAdminId`/`senderName`/`senderRole`/`msgType`/`priority`/`content`/`isMine`/`readByPeer`/`sentAt` |
+| data.unreadTotal | Integer | 标记本会话已读后，我的合并未读总数（NOTIFY+CHAT），供前端刷新顶部角标 |
+
+#### 请求示例
+
+```json
+{ "orderId": "2100856430239121409" }
+```
+
+#### 响应示例
+
+> 按 `ChatOpenFullRespVO` 字段契约构造；字段结构与 `changelogs-v2/2026-09/07_7211_定制师团期管理员站内会话GROUP-新增接口-管理后台.md` 中 2026-09-08 已实测验证过的样本一致（当时应用场景是「住宿安排卡」，本次是同一接口在「调整订单」弹窗标题栏的新用法，接口本身未变），**本轮未重新抓包**：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "conversationKey": "GROUP:2100856430239121409",
+    "peerAdminId": 0,
+    "peerName": "团期管理员",
+    "peerRole": "GROUP_ADMIN",
+    "peerRoleLabel": "团期管理员",
+    "peerOnline": true,
+    "unreadCount": 0,
+    "isNew": false,
+    "order": {
+      "orderNo": "HL2609010001",
+      "teamNo": "T20260901001",
+      "customerName": "李四",
+      "destination": "三亚",
+      "tripDays": 4,
+      "productName": "豪华蜜月游",
+      "adultCount": 2,
+      "childCount": 0,
+      "groupBatchNo": "G20260901001",
+      "groupBatchId": "70001",
+      "groupBatchName": null,
+      "departDate": null
+    },
+    "thread": { "conversationKey": "GROUP:2100856430239121409", "hasMore": false, "nextCursor": null, "list": [] },
+    "unreadTotal": 0
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+首次打开、尚无历史消息时 `thread.list` 为空数组 `[]`（不是 `null`），`hasMore=false`、`nextCursor=null`：
+
+```json
+{ "code": 200, "data": { "thread": { "conversationKey": "GROUP:2100856430239121409", "hasMore": false, "nextCursor": null, "list": [] } }, "success": true }
+```
+
+#### 错误响应
+
+```json
+{ "code": 281012, "message": "缺少订单上下文", "data": null, "success": false }
+```
+
+```json
+{ "code": 281015, "message": "该订单不是团期子订单，无法联系团期管理员", "data": null, "success": false }
+```
+
+```json
+{ "code": 281002, "message": "无权访问该会话", "data": null, "success": false }
+```
+
+#### 业务边界
+
+- 准入：该单当前定制师（`CUSTOMIZER`），或 token 当前角色持权限码 `group-batch:demand:confirm`（超管天然通过）；其余一律 281002，且**授权前不创建任何成员或水位**——`ChatManager.java:467-472` 原文注释「先授权、后检查模块前置」，鉴权失败零写入。
+- 前置条件只看摘要 `groupBatchId` 是否非空，**不要求先提交需求**——与车务 `open-fleet` 的 281013（必须先有 active 用车需求）不同（`ChatErrorCode.java:61-66`）。
+- `orderId` 缺失被 `@NotNull` 拦下走参数校验（400 系），不进入业务判定分支。
+
+---
+
+## 四、契约约束与正确调用方式
+
+> 本节只写后端接受/拒绝 payload 的规则，不写 UI 渲染建议。
+
+### ✅ 正确 / ❌ 错误 用法对照
+
+| 场景 | 用法 |
+|------|------|
+| ✅ 判断是否团期子订单 | 读 `GET /itinerary` 响应 `data.groupBatchId`，非空即团期单 |
+| ❌ 判断是否团期子订单 | 用 `OrderMainVO.groupBatchId`（另一接口的另一字段，历史兼容单上为 `null`，会误判为非团期单） |
+| ✅ 联系团期管理员 | `POST open-group`，body 只传 `{ "orderId": "..." }` |
+| ❌ 联系团期管理员 | body 里传 `peerAdminId` 试图指定接收人——不接受，团期管理员是团队制，传了也不生效 |
+
+### 切换按钮显隐的必要动作
+
+前端渲染「调整订单」弹窗标题栏时，用 `itinerary` 接口已经返回的 `groupBatchId` 做一次判断：非空 → 只渲染「联系团期管理员」按钮（角标取 `groupUnreadMessageCount`）；为空（含 `null`）→ 保持原有「联系房务」「联系车务」两个按钮不变。不需要额外调用一个专门的"是否团期单"接口。
+
+---
+
+## 五、数据库行为
+
+本次零改动。以下是既有行为，供前端理解结果落库口径：团期会话消息与车务/房务会话共用同一张消息表，只按会话键 `GROUP:{orderId}`（与 `FLEET:{orderId}`/`HOUSE:{orderId}` 同构）区分，不存在专属的团期消息表，本次也不改任何会话键格式。
+
+---
+
+## 六、边界行为
+
+- 未登录/网关未透传角色 → 401（网关拦截）
+- 订单不存在 → `itinerary` 接口返 `581007`
+- 房务角色调用 `itinerary` → `581045`
+- `open-group` 缺 `orderId` → `281012`
+- 订单不是团期子订单（摘要 `groupBatchId` 为空）→ `281015`
+- 非该单定制师且不持权限码 → `281002`，且授权前零写入
+- 老数据兼容：团期归团解析对历史兼容单同样走统一门面解析出 `groupBatchId`，判据行为与新单一致，不会因为是历史单而漏判
+
+---
+
+## 六.5、枚举 / 数据字典
+
+### peerRole（`ChatOpenRespVO.peerRole`，`open-group` 场景固定值）
+
+**所属字段**: `data.peerRole` | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `GROUP_ADMIN` | 团期管理员 | `open-group` 场景固定返回该值，团队制占位角色，不对应具体某个 adminId |
+
+---
+
+## 六.6、修改前后对比
+
+本文档不涉及接口改造（两条端点均为「复用不改」），无字段级契约对比；以下是 UI 行为级对比：
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| 团期子订单「调整订单」弹窗标题栏按钮 | 联系房务 + 联系车务 | 联系团期管理员（替换前两者） |
+| 普通订单「调整订单」弹窗标题栏按钮 | 联系房务 + 联系车务 | 不变 |
+| 团期子订单点击「联系房务」的后果（改前遗留问题） | 建出 `peer=0` 占位会话，消息落库但缺乏真实对端（是否被团期房务链路读到未经 DB 实测，仅源码推断为否） | 入口不再出现，不会再产生这类占位会话 |
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 否——两条接口字段/类型/语义零变更，只是前端新增了一层判断分支
+- **前端是否必须同步上线**: 后端不强制（零改动，不阻塞任何前端节奏），但业务上 wx 希望尽快切换以消除「联系房务」占位会话黑洞
+- **前端 workaround 清理点**: 无——本次是新增判断分支，不是撤销旧 workaround
+
+---
+
+## 七、不影响范围
+
+- **仅影响**: 管理后台订单详情「调整订单」弹窗标题栏联系入口按钮的渲染逻辑（仅团期子订单）
+- **零影响**:
+  - 车务侧自己的页面与沟通入口：接送机沟通仍走订单维度 `FLEET:{orderId}`，是 #7440 D-A6/AC-16 的既有定案，本次不动（`ChatMessageController.java:188` 原文注释「接送机等订单级沟通仍走 open-fleet 的 FLEET:orderId，本端点不替代它」）
+  - 后端 `open-fleet` / `open-house` 端点：本次不加团期守卫，仍可被直接调用；老客户端（mmg 本次发版前）行为照旧
+  - 不新建任何业务表，不改任何会话键格式
+  - `itinerary` / `open-group` 两接口在非团期单场景、及本文未提及字段上的既有契约与行为
+
+---
+
+## 八、测试环境已验证
+
+本文档描述的是既有能力的新应用场景（新按钮位置）。联系入口 `open-group` 本轮在测试服网关**真实调用过**（含反例，见本节末「2026-09-21 测试服实测」）；判据字段 `ItineraryVO.groupBatchId` 本轮未做新的 HTTP 实测，按 `origin/dev-v3` 源码引用取证：
+
+```
+OrderController.java:305-311            GET /v3/admin/order/{id}/itinerary 端点存在，返回 ItineraryVO ✓
+ItineraryVO.java:46-52                  groupBatchId 字段 + javadoc「前端按钮显隐只看本字段」✓
+ItineraryVO.java:42-44                  groupUnreadMessageCount 字段存在 ✓
+ChatMessageController.java:153-158      POST /admin/message/chat/open-group 端点存在 ✓
+ChatOpenGroupReqVO.java                 请求体仅 orderId 一个字段（@NotNull） ✓
+ChatManager.java:380-382,467-472        openGroup 委托 openTeamInternal，先授权后检查前置、零写入 ✓
+TeamChatAuthorizationService.java:45    权限码 group-batch:demand:confirm 判团队侧准入 ✓
+ChatErrorCode.java:19-20,42-44,61-66    281002/281012/281015 错误码定义 ✓
+application.yml:157-160                 网关路由 /admin/message/** → lb://hl-user-service ✓
+HouseGroupBatchErrorCode.java:340       808650「团期订单不支持逐户抢单/转单」定义 ✓
+grep -rin chat com/hulalv/house/groupbatch/  → 0 命中（团期房务相关包对聊天接口零引用）✓
+grep -in chat HouseDetailAggregator.java     → 25 命中（阳性对照：普通房务侧代码大量引用聊天相关字段/服务）✓
+```
+
+**【推断，非实测】** 「团期房务链路不读团期占位会话」这一条，是基于上面两条 grep 结果的结构性推断（团期房务代码路径找不到读聊天表/调用聊天服务的代码，普通房务代码路径有 25 处引用），**不是在测试库里对一条真实 `peer=0` 占位会话做过 SELECT 或已读水位验证**。如果需要把这条坐实成确定性结论，需要另外找一条真实产生过的团期占位会话，去库里核对它是否被任何团期房务角色读过。
+
+### 2026-09-21 测试服实测（本轮补做）
+
+`open-group` 端点本轮在测试服网关上真实调用过，带反例对照（账号 `cw_test_7442`）：
+
+| 场景 | 请求 | 响应 |
+|---|---|---|
+| 团期子订单（阳性） | `POST /admin/message/chat/open-group`，body `{"orderId":"2101935981273976833"}` | `code=200`，`data.isNew=true`（该订单此前无 GROUP 会话，本次新建） |
+| 非团期订单（反例） | 同上端点，body `{"orderId":"9199000000000000002"}` | `code=281015`「该订单不是团期子订单，无法联系团期管理员」 |
+
+反例那一行是本文判据的分辨力证明：端点确实按「是不是团期子订单」分流，而不是对任何订单都放行——
+所以前端用 `groupBatchId` 控制按钮显隐后，即便漏判也不会把非团期单的会话建出来，只会收到 `281015`。
+
+**同一接口在旧场景的实测依据**：`open-group` 端点的响应结构与权限判定，已于 2026-09-08 随 `07_7211_定制师团期管理员站内会话GROUP-新增接口-管理后台.md` 在「住宿安排卡」场景下测试服实测通过（该文档 `frontend_status: verified`，`frontend_ref: 86340b24`）。本文档只是把同一个已验证的能力接到新的按钮位置，未重复实测。
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#7211](https://git.1814.love:8443/wx/HL/issues/7211)
+- 原始能力交接件: `changelogs-v2/2026-09/07_7211_定制师团期管理员站内会话GROUP-新增接口-管理后台.md`（`open-group` 端点首次交付，2026-09-08 已验证）
+- 相关定案: #7440 D-A6/AC-16（接送机沟通走 `FLEET:{orderId}` 的既有定案，本次不动）
+- 相关工单: #7322（团期整团抢单守卫 `808650` 的来源）
+- `docs/group/团期模块接口文档-v2.0.html` §0C.11.3
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#7211](https://git.1814.love:8443/wx/HL/issues/7211)
+- **PR**: 无（零代码改动，未产生新 PR）
+
+### 联系人
+
+- **后端负责人**: @wx
@@ -7,12 +7,12 @@ author: "wx(GIT)"
 change_type: "修改接口"
 backend_status: "deployed"
 gateway_status: "verified"
-frontend_status: "pending"
-frontend_owner: "mmg"
+frontend_status: "not_required"
+frontend_owner: ""
 frontend_ref: ""
 target_release: ""
-verified_at: "2026-09-21"
-status_note: "gateway_status=verified 的判据（2026-09-21 10:09:15 / 10:09:17 取证，原文见第八节）：经网关对 POST .../share-groups 发起两次真实调用，两次请求体逐字相同、唯一差异是 confirmCrossResident 字段——不传得 605036（消息点名的车牌与司机姓名与夹具构造的跨常驻组合一致），带 true 得 200 并建出 ACTIVE 共用关系，取证完毕已按 survivorPolicy=RELEASE 清场。部署点判据：hl-fleet-service 测试服部署于 51571c58a，git merge-base --is-ancestor 076654889 51571c58a = true。⚠️ 部署点是时点读数——2026-09-21 复核时 origin/dev-v3 已前进到 79722aef1，但 51571c58a..origin/dev-v3 在 hl-fleet-service/ 下只有 a948c1b60（#7994，GroupDispatchService 空组码行收编判定）一条，与本篇 605036 链路零交集，故该读数不因部署点落后而失效。此前两轮保持 pending 的原因是「同一个端点被调通」不等于「本篇登记的那个入参被走到」；本轮已造出跨常驻场景直接触发 605036 分支，该顾虑解除，状态位是取证换来的、不是为过门禁改的。本篇是补记：#7973/#7978 合入以来 docs/ 与 hl-workflow/ 下 grep 7973/7978 零命中，此前没有任何交接件提过这个新增入参。"
+verified_at: ""
+status_note: "gateway_status=verified 的判据（2026-09-21 10:09:15 / 10:09:17 取证，原文见第八节）：经网关对 POST .../share-groups 发起两次真实调用，两次请求体逐字相同、唯一差异是 confirmCrossResident 字段——不传得 605036（消息点名的车牌与司机姓名与夹具构造的跨常驻组合一致），带 true 得 200 并建出 ACTIVE 共用关系，取证完毕已按 survivorPolicy=RELEASE 清场。部署点判据：hl-fleet-service 测试服部署于 51571c58a，git merge-base --is-ancestor 076654889 51571c58a = true。⚠️ 部署点是时点读数——2026-09-21 复核时 origin/dev-v3 已前进到 79722aef1，但 51571c58a..origin/dev-v3 在 hl-fleet-service/ 下只有 a948c1b60（#7994，GroupDispatchService 空组码行收编判定）一条，与本篇 605036 链路零交集，故该读数不因部署点落后而失效。此前两轮保持 pending 的原因是「同一个端点被调通」不等于「本篇登记的那个入参被走到」；本轮已造出跨常驻场景直接触发 605036 分支，该顾虑解除，状态位是取证换来的、不是为过门禁改的。本篇是补记：#7973/#7978 合入以来 docs/ 与 hl-workflow/ 下 grep 7973/7978 零命中，此前没有任何交接件提过这个新增入参。前端实证 not_required(mmg 2026-09-21):share-groups/shareGroup 前端 src 全仓零命中——共用关系确认端点无调用方,属 #7444 未接入挂起域,confirmCrossResident 新入参当前无接入点;605036 全仓零命中,看板派单路径走 precheck/candidates 证据链不解析消息原文,消息模板变详细零影响;看板既有 confirmCrossResident 是 assignments create/change 派单写路径的同名字段,该路径契约本次零变更。随 #7444 接入共用关系确认 UI 时按本文实现:precheck 逐成员探路(cross_resident warning)→二次确认弹窗→带 confirmCrossResident=true 原样重发;605036 文案须补「车辆-司机常驻组合冲突」解释不直接弹原文。frontend_owner/verified_at 系后端预填,按 not_required 门禁口径(ba87a9b)清空。"
 updated_at: "2026-09-21"
 base: "dev-v3"
 ---
@@ -0,0 +1,378 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7988"
+title: "团期配车需求详情响应新增七个配车刷新态观测字段"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "3df2c6f8df7902b31886e7ca0fc0ec88807d7032"
+target_release: "v2.1"
+verified_at: "2026-09-21"
+status_note: "接口已在测试环境部署并通过网关验证；七个字段在 origin/dev-v3 已就绪；order-v3 commit d30cd9561 是最新且已部署 前端 2026-09-21 核销:与 20_7988 同一观测块,已随 #7442 PR-C2 增量1 交付(hl-admin v2.1 3df2c6f8,GroupVehicleRequirementSection 观测块——planRefreshStalled 判据/replayExhausted 分叉/PENDING 短轮询),本份 AC-6 交接件零增量代码。"
+updated_at: "2026-09-21"
+base: "dev-v3"
+---
+
+# 团期配车需求: 查询接口新增七个配车刷新态观测字段
+
+> **服务**: hl-order-service-v3（order-v3）
+> **PR**: #8130 ｜ **Issue**: #7988 ｜ **验收项**: AC-6
+> **日期**: 2026-09-21
+> **影响范围**: 管理后台「团期详情」配车需求查询接口响应体
+
+---
+
+## ⚠️ 关键变化
+
+**响应体新增七个只读观测字段，描述配车计划刷新的状态与停滞告警。**
+
+最重要的三件事：
+
+1. **🔴 判「要不要告警」的主字段是 `planRefreshStalled`，不是 `planRefreshState`。** `planRefreshState` 是原始状态机值（null/PENDING/DONE/FAILED），`PENDING` 在窗口内属于正常在途，不应报警。后端已把「窗口内/窗口外」「重投耗尽」「命令失败」这些判断收敛进了 `planRefreshStalled` 这**一个布尔值**。→ 前端判告警只看 `planRefreshStalled`；`planRefreshState` 仅用于展示原始状态。
+
+2. **`FAILED` 是显式告警态。** 它进来时 `planRefreshStalled=true`、`planRefreshStalledReason=STATE_FAILED`。前端不需自己推导「FAILED 算不算停滞」。
+
+3. **⚠️ `null` 不等于出错。** `planRefreshState=null` 表示这条需求**从未登记过刷新**（例如免车、或还没确认过），此时 `planRefreshStalled=false`、其余字段为 null / 0。这是安静态，不是异常态。
+
+---
+
+## 一、背景
+
+之前这七个观测字段**只在写口的响应里**（`POST /v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement/confirm` 与 `POST /v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement/reopen`），导致「查一下配车刷新死没死」只能调一个会改状态的端点——实测 `confirm` 会先做一次受控重投，把刚才的 `FAILED` 改成 `PENDING`，结果就是 **`FAILED` 态在只读查询端点根本看不到，因为读它的动作会把它改掉**。本次补在只读查询端点上，「查现场」不再改变现场。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 团期配车需求详情 | GET | `/v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement` | 响应新增七字段 | 配车刷新态观测；只读投影，不参与提交 |
+
+---
+
+## 三、接口详情
+
+### 1. 团期配车需求详情 `GET /v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement`
+
+**VO**: `GroupVehicleRequirementRespVO → Result<GroupVehicleRequirementRespVO>`
+
+#### 使用场景
+
+管理后台「团期详情」页加载配车需求信息时调用。前端需要据 `planRefreshStalled` 判是否在需求卡片上显示告警；据 `planRefreshStalledReason` 和 `planRefreshTimeoutAt` 展示「为什么停滞」和「倒计时」。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| `groupBatchId` | Path | Long | ✅ | — | 团期聚合主键 |
+
+#### 出参 `Result<GroupVehicleRequirementRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `planRefreshState` | String / null | 配车刷新状态原值：`null`(从未登记) / `PENDING`(刷新中) / `DONE`(闭环) / `FAILED`(已失败)；**单看此字段不足以判停滞，看 `planRefreshStalled`** |
+| `planRefreshReplayCount` | Integer | 人工受控重投累计次数（管理员点确认触发的，不含自动重试）；上限 5，从未重投过为 0 |
+| `blockedStage` | String / null | 团期阻断阶段快照：`null`(未阻断) / `RESOURCE_PREPARING` / `MATERIAL_PREPARING` / `PENDING_DEPARTURE`；非空表示该团正卡在这一步等重新配车 |
+| `planRefreshStalled` | Boolean | **行动判据主字段（恒非 null）**：`true`=不会自愈，必须有人处置；`false`=无需动作。判「要不要现在找人」**只看本字段** |
+| `planRefreshStalledReason` | String / null | 停滞归因：`STATE_FAILED`(刷新已失败) / `COMMAND_FAILED`(命令行已失败但状态未回写) / `TIMEOUT`(超时)；`planRefreshStalled=false` 时恒为 null |
+| `planRefreshTimeoutAt` | LocalDateTime / null | 本轮刷新超时时刻（= 发起时刻 + 管理员定的窗口时长，缺省 120 分钟）。PENDING 且已登记发起时刻时有值；其余为 null；过了这个点仍是 PENDING 即判停滞 |
+| `planRefreshReplayExhausted` | Boolean | 人工重投额度是否已耗尽（恒非 null）：`true`=已达 5 次上限，再点确认报 809210；`false`=停滞时仍可重新确认触发重投 |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch/2099716954674597889/vehicle-requirement
+Authorization: Bearer <token>
+```
+
+#### 响应示例
+
+**场景1：从未登记刷新（多数团期的正常态）**
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "success": true,
+  "data": {
+    "requirementId": "2099716962786373633",
+    "groupBatchId": "2099716954674597889",
+    "status": "CONFIRMED",
+    "version": 1,
+    "remark": "全程 33 座",
+    "confirmedBy": "1001",
+    "confirmedAt": "2026-09-15 12:28:29",
+    "planRefreshState": null,
+    "planRefreshReplayCount": 0,
+    "blockedStage": null,
+    "planRefreshStalled": false,
+    "planRefreshStalledReason": null,
+    "planRefreshTimeoutAt": null,
+    "planRefreshReplayExhausted": false,
+    "groups": []
+  }
+}
+```
+
+**场景2：刷新已闭环（DONE 态）**
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "success": true,
+  "data": {
+    "requirementId": "2100669178103910402",
+    "groupBatchId": "2100668723156193282",
+    "status": "CONFIRMED",
+    "version": 2,
+    "remark": "全程 28 座",
+    "confirmedBy": "2101000047331078146",
+    "confirmedAt": "2026-09-19 01:43:03",
+    "planRefreshState": "DONE",
+    "planRefreshReplayCount": 0,
+    "blockedStage": null,
+    "planRefreshStalled": false,
+    "planRefreshStalledReason": null,
+    "planRefreshTimeoutAt": null,
+    "planRefreshReplayExhausted": false,
+    "groups": []
+  }
+}
+```
+
+#### 空数据 / 降级响应
+
+接口无空数据场景（群编码、需求 ID 缺失返回 404）。七个新字段恒有值：`planRefreshStalled` 和 `planRefreshReplayExhausted` 恒为 Boolean，其余可为 null / 0。
+
+#### 错误响应
+
+```json
+{
+  "code": 404,
+  "message": "团期不存在或无权限访问",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- **七个字段都是只读投影，不接受回传、不参与任何提交。** 它们由后端从 fleet 数据和受控重开日志投影而出，前端提交时忽略这些字段。
+- **`planRefreshState` 单看分不清「在跑」和「已经死」。** `PENDING` 有三种现实——正常在途、命令已终态但状态未回写、超过时限卡死。后两种必须报警，此时看 `planRefreshStalled`。
+- **`null` 不等于缺失。** `planRefreshState=null` 是「从未登记过刷新」的完全正常形态（绝大多数团期），此时 `planRefreshStalled=false`，前端不要做任何提示。
+- **`FAILED` 在本接口可观测。** 与写口不同，本查询接口不改任何状态，`FAILED` 态会原样返回。
+- **重投次数有上限。** `planRefreshReplayCount >= 5` 时 `planRefreshReplayExhausted=true`；此时再点「重新确认」会收到错误码 809210。
+- **超时时刻可变。** 每次管理员「重新确认」时可重定义窗口时长（缺省 120 分钟），`planRefreshTimeoutAt` 会随之变化。
+
+---
+
+## 四、契约约束与正确调用方式
+
+### 判停滞告警的唯一正确方式
+
+| 场景 | planRefreshStalled | planRefreshState | 前端动作 |
+|------|-------------------|------------------|---------|
+| ✅ 未登记 | false | null | 不告警，正常展示 |
+| ✅ 在途中（正常） | false | PENDING | 不告警，展示「配车中」 |
+| ✅ 已闭环 | false | DONE | 不告警，展示「已配车」 |
+| ❌ 停滞（命令失败） | **true** | FAILED | **告警**，原因为 `STATE_FAILED` |
+| ❌ 停滞（超时） | **true** | PENDING | **告警**，原因为 `TIMEOUT`，可读 `planRefreshTimeoutAt` 判是否逾期 |
+| ❌ 停滞（未回写） | **true** | PENDING | **告警**，原因为 `COMMAND_FAILED` |
+
+**核心规则**：`planRefreshStalled == true` 时无条件告警，不要根据 `planRefreshState` 额外判断。`planRefreshState` 只用于展示「当前原始状态」；`planRefreshStalledReason` 用于展示「为什么停滞」。
+
+### 错误码与重投限制
+
+- **809210**: 人工重投次数已达上限（5 次），不能再点「重新确认」；此时 `planRefreshReplayExhausted=true`，前端应显示「联系后台排查」而非重试按钮。
+- 每次 `planRefreshReplayCount` 自增是在 `POST /v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement/confirm` 触发的受控重投，不含自动重试次数。
+
+---
+
+## 五、数据库行为
+
+接口为只读查询，无数据库写操作。七个新字段映射到既有表：
+
+| 表 / 字段 | 来源 | 说明 |
+|----------|------|------|
+| `order_vehicle_plan_refresh.plan_refresh_state` | 直读 | 原始状态机值 |
+| `order_vehicle_plan_refresh.replay_count` | 直读 | 人工重投次数 |
+| `order_vehicle_plan_refresh.blocked_stage` | 直读 | 阻断阶段快照 |
+| `planRefreshStalled` / `planRefreshStalledReason` / `planRefreshTimeoutAt` / `planRefreshReplayExhausted` | 实时计算 | 读取时动态投影，无落库 |
+
+---
+
+## 六、边界行为
+
+- **团期不存在** → 404
+- **无权限访问** → 404（鉴权失败的兜底；前置字段、角色判权在 Controller 层）
+- **字段为 null 时的序列化** → JSON 中保留 null 值，不省略字段；前端据此判断该字段是否有值
+- **超大团期（>10000 人）查询响应** → 七个新字段不涉及复杂 JOIN，查询耗时无额外增长
+
+---
+
+## 六.5、枚举 / 数据字典
+
+### planRefreshState（配车刷新状态）
+
+**所属字段**: `planRefreshState` | **类型**: `String / null`
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `null` | 从未登记 | 团期从未走过受控重开，也未自动触发刷新。这是绝大多数团期的正常状态，**不表示异常** |
+| `PENDING` | 刷新中 | 刷新命令已发出，等 fleet 侧回包。窗口内正常，超时则判停滞 |
+| `DONE` | 已闭环 | 本轮刷新已有结果，fleet 已回包且后端已处理。可能包含部分成功（部分车型配上、部分待自主响应） |
+| `FAILED` | 已失败 | fleet 已明确拒绝或超过自动重试次数，需人工介入。此时 `planRefreshStalled=true` / `planRefreshStalledReason=STATE_FAILED` |
+
+### planRefreshStalledReason（停滞归因）
+
+**所属字段**: `planRefreshStalledReason` | **类型**: `String / null`
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `null` | 未停滞 | `planRefreshStalled=false` 时恒为 null |
+| `STATE_FAILED` | 状态失败 | fleet 已判 FAILED（自动重试耗尽或被 fleet 终结）。排障：查 fleet 服务日志为什么拒绝 |
+| `COMMAND_FAILED` | 命令行失败 | 命令行已失败但后端未收到状态回写（网络、hook 失败等）。排障：查回写状态的终态钩子 |
+| `TIMEOUT` | 超时 | 超过本轮窗口时限仍无结果（可读 `planRefreshTimeoutAt` 判具体何时逾期）。排障：查队列是否积压 |
+
+### blockedStage（阻断阶段）
+
+**所属字段**: `blockedStage` | **类型**: `String / null`
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `null` | 未阻断 | 团期可正常流转 |
+| `RESOURCE_PREPARING` | 资源筹备中 | 团期卡在配车需求确认后、资源分配前 |
+| `MATERIAL_PREPARING` | 物资筹备中 | 团期卡在资源分配后、物资分配前 |
+| `PENDING_DEPARTURE` | 待出团 | 团期卡在物资准备完、出团前。最常见的阻断点 |
+
+---
+
+## 六.6、修改前后对比
+
+| 项 | 改前 | 改后 |
+|---|---|---|
+| 查询需求状态 | 调用 `confirm` / `reopen` 这类**写口**端点 | 调用 GET 只读端点，不改任何状态 |
+| 能否观测 `FAILED` 态 | 不能（读的动作会改状态） | 可以（不改状态的纯查询） |
+| 响应体新增字段数 | 0 | 7（全是观测字段，只读） |
+| 告警判据 | 需要前端自己推导「PENDING + 超时」= 告警 | 后端已收敛为 `planRefreshStalled`，前端一个布尔值判定 |
+| 人工重投上限可见 | 无 | 可见：`planRefreshReplayCount` / `planRefreshReplayExhausted` |
+| 超时时刻 | 无 | 可见：`planRefreshTimeoutAt`，支持倒计时展示 |
+
+## 六.7、影响评估
+
+| 维度 | 评估 |
+|---|---|
+| **破坏向后兼容** | 否。只新增字段，不改既有字段；既有消费方可忽略新字段正常工作 |
+| **前端是否必须同步** | 是。新字段是告警判据的唯一来源，不同步则无法正确判停滞；`planRefreshStalled` 与 `planRefreshStalledReason` 必须实现 |
+| **路径 / HTTP 方法** | 不变 |
+| **入参 / 出参结构** | 只新增 7 个字段，不删不改既有字段 |
+| **FAILED 态生产可达** | 是。`FAILED` 态在测试环境中无法构造（刷新在途窗口过短，异步消费方在窗口内即完成），但**生产环境可达**。前端**必须**实现 `planRefreshStalled=true` + `planRefreshStalledReason=STATE_FAILED` 这条分支 |
+| **性能影响** | 极小。七个字段由既有表直读或实时计算，无新 JOIN、无新子查询 |
+| **下游兼容** | 安全。字段全是观测投影，无外发依赖 |
+
+---
+
+## 七、不影响范围
+
+- **零影响**：接口路径、HTTP 方法（GET）、既有响应字段
+- **零影响**：写口端点（`confirm` / `reopen` / `withdraw` / `waive`）的响应、逻辑、校验
+- **零影响**：其他团期查询接口（`list` / `group-batch/{id}` 等）
+- **零影响**：前置条件与鉴权（角色、数据权限）；新字段投影后的鉴权与既有相同
+- **未新建端点、未删端点**
+
+---
+
+## 八、测试环境已验证
+
+✅ **2026-09-21 UTC 14:42:32 ~ 14:42:39 经网关 `https://api.test.1814.love:9443` 真实调用验证**
+
+部署信息：
+- 测试服 order-v3 当前部署 commit `d30cd9561`
+- 七字段的祖先提交 `587af48cd` 已在其中（`git merge-base --is-ancestor 587af48cd d30cd9561` 实测为真）
+- 接口已在线可调
+
+实测用例（两次调用，响应均 `code=200 / success=true`）：
+
+| # | 场景 | 七字段全部到位 | 与数据库一致性 | 备注 |
+|---|------|-------------|----------|------|
+| 1 | 从未登记刷新 | ✅ | ✅ | planRefreshState=null, planRefreshStalled=false, 其余字段为 null / 0 |
+| 2 | 刷新已闭环 | ✅ | ✅ | planRefreshState=DONE, planRefreshStalled=false, blockedStage=null, 其余字段为 null / 0 |
+
+**原始响应体（两份）**：
+
+NULL 态：
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "requirementId": "2099716962786373633",
+    "groupBatchId": "2099716954674597889",
+    "status": "CONFIRMED",
+    "version": 1,
+    "confirmedBy": "1001",
+    "confirmedAt": "2026-09-15 12:28:29",
+    "planRefreshState": null,
+    "planRefreshReplayCount": 0,
+    "blockedStage": null,
+    "planRefreshStalled": false,
+    "planRefreshStalledReason": null,
+    "planRefreshTimeoutAt": null,
+    "planRefreshReplayExhausted": false,
+    "groups": []
+  },
+  "success": true
+}
+```
+
+DONE 态：
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "requirementId": "2100669178103910402",
+    "groupBatchId": "2100668723156193282",
+    "status": "CONFIRMED",
+    "version": 2,
+    "confirmedBy": "2101000047331078146",
+    "confirmedAt": "2026-09-19 01:43:03",
+    "planRefreshState": "DONE",
+    "planRefreshReplayCount": 0,
+    "blockedStage": null,
+    "planRefreshStalled": false,
+    "planRefreshStalledReason": null,
+    "planRefreshTimeoutAt": null,
+    "planRefreshReplayExhausted": false,
+    "groups": []
+  },
+  "success": true
+}
+```
+
+---
+
+## 十、相关文档
+
+- 团期需求文档：`docs/group/`（dev-v3 分支）
+- 配车刷新业务设计：工单 #7988 正文与 AC-1 ~ AC-6
+- 受控重开流程：#7996（与本单共线依赖）
+
+---
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#7988](https://git.1814.love:8443/wx/HL/issues/7988)
+- **PR**: [#8130](https://git.1814.love:8443/wx/HL/pulls/8130)
+- **验收项**: AC-6
+
+### 联系人
+
+- **后端负责人**: @wx
@@ -0,0 +1,378 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7994"
+title: "团期配车受控重开窗口：分组列上线前的历史派车行现在可以被收编，不再让团期卡死"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "2044ec5281e0eb4a0fb3b1567a92e73916bd4204"
+target_release: ""
+verified_at: "2026-09-21"
+status_note: "gateway_status=verified 的判据：2026-09-21 经测试服网关 https://api.test.1814.love:9443 对团期 2099959465330556929 实跑了完整四步（重开窗口 → 重配 → 确认配车 → 确认需求），全部 200，三行历史派车行的分组由空写成 GC、团期车务就绪位由 0 置 1，逐步请求/响应已记入工单 #7994 AC-3。backend_status=deployed 有两条互相独立的判据：①行为自证——这四步在本次修复之前必然报 602013（工单背景节实测过两次），能走通本身就说明跑着的字节里含本次修复；②测试服上 /opt/hulalv/jars/hl-fleet-service-1.0.0-SNAPSHOT.jar 的 mtime 是 2026-09-21 10:18:22，晚于本次修复合入 dev-v3 的 09:47:35。🔴 顺带订正一条会误导人的登记值：另一条取证线记录的 fleet 部署点 51571c58a 与上述两条判据矛盾（51571c58a 的提交时刻是 04:25，且本次修复不是它的祖先）——那是 10:18 重滚之前的陈旧读数，别再据它判断「某修复还没上测试服」。⚠️ 未覆盖：团期状态推进（本次只解开死路，未推进 batch_status）；计划刷新是同步还是异步未区分（两者终态相同）。"
+updated_at: "2026-09-21"
+base: "dev-v3"
+---
+
+# 团期车务：受控重开窗口内，无分组的历史派车行可以被收编（工单 #7994）
+
+> **存放目录**: 二期（order-v3 标签工单）→ `changelogs-v2/2026-09/`
+>
+> **服务**: hl-fleet-service（8087）
+> **PR**: #8085
+> **Issue**: #7994
+> **日期**: 2026-09-21
+> **影响范围**: 管理后台「团期配车页」——受控重开窗口内的重新配车操作，以及它报错时的提示文案
+
+---
+
+## ⚠️ 关键变化
+
+- **请求体和响应体的字段一个都没变**，前端**不需要改接口对接代码**。变的是两件事：①一类原先必定被拒的请求现在会成功；②被拒时的提示文案变长了，且**新文案里带着操作指引**。
+- 🔴 **唯一需要前端确认的一点：`602013` 的提示文案现在可能很长，必须完整展示给车务，不能截断、不能只显示前一行。** 新增的那半句正是告诉车务「该怎么自救」的部分，截掉了这条路就没人找得到（详见「三、接口详情 → 错误响应」）。
+- 这次改动**没有放松任何权限或范围校验**：窗口授权范围以外的分组、以外的日期，行为一字未变，仍然整批拒绝且零写入。
+
+---
+
+## 一、背景
+
+「分组」这一列是 2026-09-17 才加到团期派车记录上的。在那之前排的车，记录上**没有分组**——不是脏数据，是那个事实当时就不存在。
+
+车务给一个团期开「受控重开窗口」重新配车时，系统要检查每一行改动有没有越出窗口授权的范围。此前的规则是：**没有分组的历史行一律判越界**（说不出它属于哪个组，就不敢让窗口里的操作动它）。
+
+这条规则本身没错，但它和另一条规则撞上了：团期进入「物资准备」阶段后，**不开窗口就不许配车**。两条一叠加，一个带历史派车行的团期就成了单向死路：
+
+| 车务的走法 | 结果 |
+|---|---|
+| 开窗口后重新配车 | 拒绝：「本次配车改动越出重开窗口授权范围」（602013） |
+| 不开窗口直接配车 | 拒绝：「团期当前状态不可配车: 物资准备中」（600010） |
+| 跳过配车直接确认 | 拒绝：「整组未排车」（602008，历史行不算数） |
+
+而开窗口这个动作本身会把团期的**车务就绪位清零**，于是团期再也过不了发团门禁——**出不了团，也修不回去**。测试环境实际撞上这个状态的团期有 1 个。
+
+### 改后的判定口径：按「这一行会被怎么处理」分，而不是按「它属于哪个组」分
+
+没有分组的历史行，在一次重新配车里只有两种下场，风险完全不对称：
+
+| 下场 | 什么时候发生 | 改后 |
+|---|---|---|
+| **被收编**——这一行被写上分组 | 车务在本次请求里**带上了同一辆车、同一天**，并给了分组 | ✅ **放行** |
+| **被删除**——这一行被撤掉、占用被释放 | 车务在本次请求里**没写**这辆车这一天 | ❌ **仍然拒绝**（602013），一字未变 |
+
+放行为什么是安全的：收编时写进去的那个分组，**本身仍要经过窗口授权范围的检查**。想把历史行收编进一个没被授权的分组，一样会被拒。⇒ 历史行永远不可能被写进未授权的分组，也永远不可能被窗口删掉。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 整团逐日配车提交（重新配车） | POST | `/admin/fleet/group-dispatch/batches/{groupBatchId}/reconfigure` | 行为放宽 + 错误提示文案变化 | 请求体/响应体结构零变化 |
+
+---
+
+## 三、接口详情
+
+### 1. 整团逐日配车提交 `POST /admin/fleet/group-dispatch/batches/{groupBatchId}/reconfigure`
+
+**VO**: `GroupDispatchReconfigureReqVO` → `GroupDispatchReconfigureRespVO`（**字段无增删改**）
+
+#### 使用场景
+
+管理后台「团期配车页」，车务在受控重开窗口有效期内提交整团逐日的配车安排。本次改动只影响**团期带有「分组列上线前的历史派车行」**这一种情形；不带历史行的团期，行为逐字不变。
+
+#### 入参（**本次无变化**）
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| groupBatchId | path | Long | 是 | — | 团期主订单 ID |
+| requirementId | body | Long | 是 | 须等于基线当前活跃需求 | 正式团级用车需求 ID，落后抛 602005 |
+| requirementVersion | body | Integer | 是 | 须等于基线当前版本 | 需求版本，落后抛 602005 |
+| clearAll | body | Boolean | 否 | 默认 false | 显式整团清零标志 |
+| reconfigureWindowToken | body | String | 条件必填 | 团期已过资源准备阶段时必填 | 受控重开窗口令牌；缺失/不匹配/过期抛 602012 |
+| survivorPolicy | body | String | 条件必填 | clearAll=true 且存在 active 共用关系时必填 | 幸存共用派单处置策略 |
+| demands | body | Array | 条件必填 | clearAll=false 时必填 | 逐日配车需求列表 |
+| demands[].tripDate | body | LocalDate | 是 | `yyyy-MM-dd` | 行程日期 |
+| demands[].assignments | body | Array | 是 | 非空 | 当日排车项列表 |
+| demands[].assignments[].groupId | body | String | 是 | 非空白；须在窗口授权范围内 | 乘车分组键（= 需求侧 group_code） |
+| demands[].assignments[].vehicleId | body | Long | 是 | — | 派出车辆 ID |
+| demands[].assignments[].driverId | body | Long | 否 | 可空 = 仅排车未排司机 | 派出司机 ID |
+| demands[].assignments[].remark | body | String | 否 | — | 备注 |
+
+🔴 **收编一条历史行的做法就落在这张表里，没有任何新字段**：把历史行所在的「`tripDate` + `vehicleId`」原样写进 `demands`，并给它一个 `groupId`。
+
+#### 出参（**本次无变化**，字段来源：`GroupDispatchReconfigureRespVO` 的 `@ApiModelProperty` 声明）
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| groupBatchId | Long | 团期主订单 ID |
+| requirementId | Long | 正式团级用车需求 ID |
+| requirementVersion | Integer | 正式团级用车需求版本 |
+| planVersion | Long | 团期计划版本 |
+| addedCount | Integer | 新增派车记录数 |
+| removedCount | Integer | 软删派车记录数 |
+| keptCount | Integer | 保留未变派车记录数 |
+| updatedCount | Integer | **就地更新派车记录数**——收编走的就是这一格 |
+| aliveCount | Integer | 存活派车记录总数 |
+| addedDispatchIds | List&lt;Long&gt; | 新增派车记录主键列表 |
+| idempotentShortCircuit | Boolean | 本次是否被计划去重短路（幂等成功，**非失败**） |
+| coverage | Object | 按乘车分组的覆盖明细，含 `groups` / `missingGroupCodes` / `wholeBatchSatisfied` |
+| legacyGroupRowCount | Integer | **无分组键的历史派车行数（非错误，仅留痕）**——这一格就是本次改动针对的那类行 |
+| releasedShareGroupIds | List&lt;Long&gt; | 本次连带解除的共用关系 ID 清单 |
+| keptSourceIds | List&lt;Long&gt; | 保留占用的 claim 来源 ID 清单 |
+| releasedSourceIds | List&lt;Long&gt; | 占用已被真正释放的派单 ID 清单 |
+| pendingReassignSourceIds | List&lt;Long&gt; | 待人工改派的派单 ID 清单（占用已释放、当前无车） |
+
+#### 请求示例
+
+收编三行历史派车行（同一辆车、三个连续日期），给它们分组 `GC`：
+
+```json
+{
+  "requirementId": 2099959465330556930,
+  "requirementVersion": 5,
+  "clearAll": false,
+  "reconfigureWindowToken": "<重开窗口返回的令牌>",
+  "demands": [
+    {
+      "tripDate": "2026-11-27",
+      "assignments": [
+        { "groupId": "GC", "vehicleId": 2064995255698010113, "driverId": 2065272145289658370 }
+      ]
+    },
+    {
+      "tripDate": "2026-11-28",
+      "assignments": [
+        { "groupId": "GC", "vehicleId": 2064995255698010113, "driverId": 2065272145289658370 }
+      ]
+    },
+    {
+      "tripDate": "2026-11-29",
+      "assignments": [
+        { "groupId": "GC", "vehicleId": 2064995255698010113, "driverId": 2065272145289658370 }
+      ]
+    }
+  ]
+}
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 0,
+  "msg": "操作成功",
+  "data": {
+    "groupBatchId": 2099959465330556929,
+    "planVersion": 2,
+    "addedCount": 0,
+    "removedCount": 0,
+    "keptCount": 0,
+    "updatedCount": 3,
+    "aliveCount": 3,
+    "addedDispatchIds": [],
+    "idempotentShortCircuit": false,
+    "coverage": {
+      "missingGroupCodes": [],
+      "wholeBatchSatisfied": true
+    },
+    "legacyGroupRowCount": 0
+  }
+}
+```
+
+⚠️ **上例中只有 `updatedCount` / `addedCount` / `removedCount` / `wholeBatchSatisfied` 四项是 2026-09-21 实测读数**（见「八、测试环境已验证」）；其余字段按其语义填的示意值，且为便于阅读省略了 `coverage.groups` 与几个空数组字段——**不要拿它当字段全集**，字段全集以上面的出参表为准。
+
+📌 收编是**就地更新**，不是删掉重建：三行历史行被收编后 `updatedCount=3` / `addedCount=0` / `removedCount=0`，派车记录的 id 不变。前端若按派车记录 id 做过本地缓存或选中态，**不会失效**。
+
+#### 空数据 / 降级响应
+
+- **团期一条派车行都没有**：`aliveCount=0`、`coverage.wholeBatchSatisfied=false`、`coverage.missingGroupCodes` 列出缺的组码；这是正常响应不是错误。
+- **重复提交同一份计划**（超出 10 秒防重窗口）：正常受理并返回 `idempotentShortCircuit=true`，`addedCount/removedCount/updatedCount` 全 0——**那是成功**（计划未变、未落库），前端不要按错误提示。
+- **10 秒内重复提交**：被防重窗口拒绝，提示「团期配车重配处理中，请勿重复提交」，前端按「稍后重试」处理。
+- 以上三种在本次改动中**行为一字未变**。
+
+#### 错误响应
+
+`602013` 的 `message` 此前只有越界项清单。改后，**当越界项里含「(无分组历史行)」时**，末尾会追加一段操作指引：
+
+```json
+{
+  "code": 602013,
+  "msg": "本次配车改动越出重开窗口授权范围: (无分组历史行):2026-11-27,(无分组历史行):2026-11-28; 其中 (无分组历史行) 是分组列上线前的历史派车行, 本次请求没有它因而会被删除; 窗口内不允许删除它, 请把该日期该车一并写进本次配车请求并给出正确的乘车分组, 即可将其收编",
+  "data": null
+}
+```
+
+⇒ 🔴 **请确认「团期配车页」的错误提示区能完整展示这段文字**（多行换行展示即可，不要单行截断、不要因为 tooltip 放不下就省略）。这段话是车务自救的唯一入口。
+
+📌 越界项里**不含**「(无分组历史行)」时（即普通的分组越界、日期越界），`message` 与改前**逐字节相同**，不会变长：
+
+```json
+{
+  "code": 602013,
+  "msg": "本次配车改动越出重开窗口授权范围: GA:2026-11-27",
+  "data": null
+}
+```
+
+错误码清单（**本次不新增、不删除任何错误码**）：
+
+| code | 说明 | 本次是否变化 |
+|---|---|---|
+| 602013 | 本次配车改动越出重开窗口授权范围 | **触发条件收窄**；含历史行时文案追加指引 |
+| 602012 | 重开窗口令牌缺失/不匹配/已过期 | 不变 |
+| 602011 | 窗口内不允许整团清空 | 不变 |
+| 602008 | 整组未排车 | 不变（但历史行被收编后不再误报） |
+| 602005 | 需求身份落后 | 不变 |
+| 602000 | 配车请求缺少乘车分组 | 不变 |
+| 600010 | 团期当前状态不可配车 | 不变 |
+| 600006 / 600007 | 车辆/司机当天已被占用 | 不变 |
+
+#### 业务边界
+
+- 只有**同时满足「同一行程日 + 同一车辆」**的历史行才会被收编；只对上日期或只对上车辆都不算，仍按删除处理并拒绝。
+- 收编时给的 `groupId` **照样要过窗口授权范围校验**：不在范围内仍返 602013，且**零写入**。
+- 本次改动**不触碰**窗口授权范围本身的计算，也不触碰「窗口内不允许整团清空」（602011）。
+- 一次请求里可以同时收编多行；三行历史行在一次请求里全部收编是实测过的形态。
+- 收编不改变派车记录的主键，也不产生新的派车记录。
+
+---
+
+## 四、契约约束与正确调用方式
+
+### ✅ 正确 / ❌ 错误 的应对方式
+
+遇到「越出重开窗口授权范围」且提示里出现「(无分组历史行)」时：
+
+| | 做法 | 结果 |
+|---|---|---|
+| ❌ | 去找管理员**重开一个范围更大的窗口** | 没用。窗口里写什么分组都授权不了「没有分组」的行——这条路改前改后都走不通 |
+| ✅ | 把提示里**点名的那个日期、那辆车**一并写进本次 `demands`，并给它一个正确的乘车分组 | 该行被就地收编，计入 `updatedCount` |
+
+### 前端需要做什么
+
+| 事项 | 是否需要改 |
+|---|---|
+| 请求体字段 | ❌ 不用改 |
+| 响应体字段 | ❌ 不用改 |
+| 错误码分支 | ❌ 不用改（没有新错误码） |
+| **602013 提示文案的展示** | ✅ **确认能完整展示长文案，不截断** |
+| 页面文案/引导 | 选做：若「团期配车页」有配车失败的帮助文案，可以补一句「提示里出现『无分组历史行』时，把它点名的日期和车辆一并加进本次配车即可」
+
+前端已交付(mmg 2026-09-21, hl-admin 2044ec52):配车计划编辑器(GroupDispatchPlanEditor)提交失败时若 message 含「无分组历史行」,在编辑器内常驻 n-alert 完整展示该指引(自然换行不截断),再次提交自动清空;其余错误仍走拦截器 toast。请求/响应字段零变化,对接代码未动。editor spec 6 例全过(长文案常驻展示+普通失败不出常驻块),checkpoint 通过。 |
+
+---
+
+## 五、数据库行为
+
+- 收编走的是**就地 UPDATE**：派车记录表 `fleet_group_dispatch` 中被收编的行，`group_id` 由 NULL 写成请求里给的分组码，`version` +1，**主键 `dispatch_id` 不变**，不产生新行、不软删旧行。
+- 实测三行（2026-11-27/28/29，同车同司机）：`group_id` NULL → `GC`、`status` ASSIGNED → CONFIRMED（第 3 步确认配车所致）、`version` 0 → 1。
+- 被拒绝时（602013）**零写入**——这一点改前改后相同，本次未放松。
+- 无新增表、无新增列、**无 Flyway 迁移**。
+
+---
+
+## 六、边界行为
+
+| 情形 | 改前 | 改后 |
+|---|---|---|
+| 历史行所在的「日期 + 车辆」出现在本次 `demands` 里 | 602013 | ✅ **成功**，该行分组被写成请求里给的值，计入 `updatedCount` |
+| 历史行所在的「日期 + 车辆」**没有**出现在本次 `demands` 里 | 602013 | **602013**（不变） |
+| 收编时给的分组不在窗口授权范围内 | 602013 | **602013**（不变） |
+| 团期里没有任何无分组历史行 | 按窗口授权范围判 | **完全不变**（越界集合与错误文案两侧都逐字节相同） |
+| 普通的分组越界 / 日期越界 | 602013 | **602013**，文案逐字节不变 |
+
+---
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+**无任何字段变化**——请求体、响应体、错误信封三处的字段名、类型、层级全部与改前一致。这也是本篇不要求前端改对接代码的原因。
+
+### 行为级对比
+
+| 维度 | 改前 | 改后 |
+|---|---|---|
+| 判定依据 | 这一行**属于哪个组**（没有组 ⇒ 一律越界） | 这一行**会被怎么处理**（被收编 ⇒ 放行；被删除 ⇒ 越界） |
+| 带历史行的团期 | 单向死路，出不了团也修不回 | 车务可自行收编后继续走确认流程 |
+| 602013 文案 | 只有越界项清单 | 含历史行时追加操作指引；不含时逐字节不变 |
+
+---
+
+## 六.7、影响评估
+
+- **前端**：只有一处——602013 长文案的展示。无字段改动、无错误码改动。
+- **后端**：仅 hl-fleet-service 一个服务，改动落在受控重开窗口的范围校验与错误文案两处。
+- **数据**：不需要任何存量数据订正。历史行被收编是**车务在页面上的正常操作**，不需要刷库。
+- **回归面**：不带无分组历史行的团期，越界判定与错误文案两侧结构性不可达本次改动（非空分组码走的仍是改前那条判断，一字未改），且该类的 10 条既有单测一字未动全绿。
+
+---
+
+## 七、不影响范围
+
+显式声明**没有**被这次改动碰到的东西，帮前端/QA 缩小排查面：
+
+- **整团清空**（`clearAll=true`）与 `survivorPolicy` 的处理：**未碰**。
+- 窗口授权范围本身怎么算出来的：**未碰**。
+- 602012（令牌）、602011（窗口内禁清空）、602005（需求身份落后）、600010（团期状态不可配车）、600006/600007（车/人被占）的触发条件：**全部未碰**。
+- 共用关系（share-group）的建立、解除、收缩：**未碰**。
+- 权限点 `fleet:group-dispatch:write` / `fleet:group-dispatch:view`：**未碰**。
+- 防重窗口与幂等短路（`idempotentShortCircuit`）：**未碰**。
+- 团期状态机的推进：**未碰**——本次只解开死路，`batch_status` 不因这次改动而变化。
+
+---
+
+## 八、测试环境已验证
+
+2026-09-21 经测试服网关 `https://api.test.1814.love:9443`，对团期 `2099959465330556929`（三行 2026-11-27/28/29 的无分组历史派车行）走完整链路，四步全部 200：
+
+| # | 动作 | 结果 |
+|---|---|---|
+| 1 | 重开受控窗口 | 200，拿到新窗口令牌 |
+| 2 | 带窗口重新配车（请求里带上那辆车 + 三天 + 分组 `GC`） | 200，`updatedCount=3` / `addedCount=0` / `removedCount=0`，`wholeBatchSatisfied=true` |
+| 3 | 确认配车 | 200，`confirmedCount=3`（**改前此处报 602008「整组未排车」**） |
+| 4 | 确认团期车务需求 | 200，需求状态转 `CONFIRMED` |
+
+三行派车记录的分组由**空**变为 `GC`，团期**车务就绪位由 0 置 1**，单向死路解除。
+
+⚠️ **取证中踩到的一个坑**（与本次改动无关，但会影响联调）：以 `ADMIN` 角色调 `/admin/fleet/**` 全部端点返 **403「无权限访问车务管理」**，必须切到**车务角色或超级管理员**。这是既有的路径级角色门禁，不是本次引入的。
+
+⚠️ **本次未覆盖**：团期状态推进（本次只解开死路，`batch_status` 仍是物资准备中）；「计划刷新」是同步完成还是极快的异步消费，两者终态相同，本次没有做间隔采样因而分不出来——这只影响时序假设，不影响上表任何一行结论。
+
+---
+
+## 九、相关历史 PR
+
+| PR | 说明 |
+|---|---|
+| #8085 | 本次修复（工单 #7994） |
+| 工单 #7442 | 分组列与受控重开窗口的来源——本次要修的死路正是这两条规则叠加出来的 |
+
+---
+
+## 十、相关文档
+
+- 工单 #7994（含逐条验收取证与本次改动的结构性论证）
+- 工单 #7442（分组列 + 受控重开窗口的原始需求）
+- 同期同服务的相邻变更：`20_8051_解除共用关系不再跨服务日跨团误清派车行-修改接口-管理后台.md`、`20_8061_解除共用关系只清成员占用同槽非成员不动-修改接口-管理后台.md`
+
+---
+
+## 关联 / 联系人
+
+### 链接
+
+- Issue: #7994
+- PR: #8085
+- 服务: hl-fleet-service（8087）
+- 网关: `https://api.test.1814.love:9443`
+
+### 联系人
+
+- 后端: wx
+- 前端（管理后台）: mmg
@@ -0,0 +1,370 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8006"
+title: "团期 staff 保存支持按角色范围覆盖，不再跨配置位清空"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "2e8850800bc0715c35d77a9496aab39128cf8e64"
+target_release: "v2.1"
+verified_at: "2026-09-21"
+status_note: "2026-09-21 于网关 https://api.test.1814.love:9443 经验证：带 scopeRoles 的请求触发错误码 582115 并返回预期报文（「提交的人员角色（GUIDE）超出本次保存声明的角色范围（PHOTOGRAPHER）」），去掉 scopeRoles 同一笔请求返回 200 走全量覆盖；这证实网关透传了新增字段 scopeRoles 无拦截或裁剪，后端校验正常执行。PR #8117 已合入 dev-v3（合并提交 094521f0b），当前测试环境部署 commit d30cd9561。 前端 2026-09-21 已交付(hl-admin v2.1 2e885080,commit 全哈希见 frontend_ref):saveGroupBatchStaff 加 scopeRoles 第三参(空数组不下发),配置弹窗改范围覆盖只提交本位行、导游位 GUIDE+LEADER 同传;checkpoint 全量绿。"
+updated_at: "2026-09-21"
+base: "dev-v3"
+---
+
+# 团期人员配置：保存接口新增角色范围声明，支持按配置位分部分保存
+
+> **服务**: hl-order-service-v3
+> **PR**: #8117 ｜ **Issue**: #8006 ｜ **合并提交**: `094521f0b`
+> **影响范围**: 管理后台「团期详情 → 配置导游/摄影」弹窗保存按钮的后端接口
+
+---
+
+## ⚠️ 关键变化
+
+**团期 staff 配置是按弹窗（导游位 + 摄影位）分两次各自维护的。改前，任何一次保存都会全量覆盖整期所有角色，导致保存导游位时漏带摄影位就把摄影师清空——即使摄影位根本没动。**
+
+**现在可选择：不传 `scopeRoles` 时行为不变（整期全量覆盖），传了则只覆盖指定的几个角色，别的角色既有人员保持不动。导游位与摄影位终于能互不干扰地维护。**
+
+同时新增一个拒绝条件：提交的人员角色如果落在 `scopeRoles` 声明的范围之外，后端拒绝（错误码 `582115`），不会接受超出范围的人员配置。
+
+---
+
+## 一、背景
+
+团期 staff 配置分两个弹窗：
+- 导游位：选导游/领队，对应 `GUIDE` + `LEADER` 两个角色
+- 摄影位：选摄影师，对应 `PHOTOGRAPHER` 一个角色
+
+全量覆盖的模式要求"保存时把你要的所有人员一口气提交"，否则没提交的就被清空。但实际场景是前端打开弹窗改一处、保存一次，改另一处、再保存一次，两个弹窗分离维护。导致**只要有一次漏带了另一弹窗的既有人员，那一弹窗的人就被静默清空**。
+
+本次改动让后端对保存范围更聪慧：前端只需声明"我这次改的是哪些角色"，后端就只删那个范围内的旧行、只插那个范围内的新行，其他角色的人员一行不动。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 保存团期人员配置 | PUT | `/v3/admin/group-batch/{productBatchId}/staff` | **请求体新增字段** | 新增 `scopeRoles`；错误码新增 `582115` |
+
+---
+
+## 三、接口详情
+
+### 1. 保存团期人员配置 `PUT /v3/admin/group-batch/{productBatchId}/staff`
+
+**VO**: `BatchStaffConfigReqVO → BatchStaffConfigRespVO`
+
+#### 使用场景
+
+「配置导游」或「配置摄影」弹窗点保存时调用，将本弹窗的人员配置提交到后端。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| `productBatchId` | Path | Long | ✅ | — | 产品侧班期 ID |
+| `scopeRoles` | Body | `List<String>` | ❌ | 元素取值: `LEADER` / `GUIDE` / `DRIVER` / `PHOTOGRAPHER` / `OTHER` / `GUIDE_ASSISTANT` / `STUDY_TEACHER` / `LIFE_TEACHER`；**不传 = 整期全量覆盖**（历史行为），**传了就必须 ≥ 1 项**（传空数组 400 拒绝） | **新增**。本次保存覆盖的角色范围。不传时全量覆盖整期（与改前一致），传了则只在这些角色内覆盖，范围外的既有行不动。**特别注意：导游位并收 `GUIDE` 与 `LEADER` 两个角色，保存导游位时必须同时传这两个，只传其中一个会导致 `582115` 拒绝**（见下方错误响应） |
+| `staffList` | Body | `List<Item>` | ✅ | — | 本范围内要保存的人员列表。传空数组 `[]` 表示清空该范围内的人员（与改前一致） |
+| `staffList[].staffId` | Body | Long | ✅ | — | 资源域人员 ID |
+| `staffList[].staffRole` | Body | String | ✅ | 同上 `scopeRoles` 的取值域 | 人员在本配置中的角色。如果传了 `scopeRoles`，这里的每一项都必须在范围内，否则 `582115` 拒绝 |
+| `staffList[].sortOrder` | Body | Integer | ❌ | — | 展示排序（缺省 0） |
+
+#### 出参 `Result<BatchStaffConfigRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `productBatchId` | Long | 回显路径参数 |
+| `groupBatchId` | Long | 运营团期 ID（由 productBatchId 反查得到） |
+| `staffList` | `List<Item>` | **保存后的整期最终状态**（见下方说明） |
+| `affectedOrderCount` | Integer | 扇出影响的活跃子订单数 |
+
+**`staffList` 回显语义变化**：
+- **改前**：只回显本次提交的 items（即请求体的 `staffList`）
+- **改后**：回显**保存完成后整个团期的最终状态**——无论你是全量保存还是按范围保存，返回都是整期全部人员的完整快照
+  - 好处 1：前端无需再发第二个 GET 请求去拿最新名单
+  - 好处 2：前端能看到"我这一存操作扇出到多少订单"和"团期现在全部配置是啥"，更清楚整体状态
+  - 注意：如果你传了 `scopeRoles=["PHOTOGRAPHER"]` 只保存摄影位，返回的 `staffList` 仍然包含导游位的人（如果有的话），这是正常的，代表团期的完整配置
+
+#### 请求示例
+
+**场景 1：按范围保存（新用法）**
+
+前端打开导游位弹窗，改了导游/领队名单，保存时只声明导游位：
+
+```json
+{
+  "scopeRoles": ["GUIDE", "LEADER"],
+  "staffList": [
+    {
+      "staffId": 1005,
+      "staffRole": "LEADER",
+      "sortOrder": 0
+    },
+    {
+      "staffId": 1002,
+      "staffRole": "GUIDE",
+      "sortOrder": 1
+    }
+  ]
+}
+```
+
+**场景 2：全量保存（历史用法，不传 `scopeRoles`）**
+
+```json
+{
+  "staffList": [
+    {
+      "staffId": 1005,
+      "staffRole": "LEADER",
+      "sortOrder": 0
+    },
+    {
+      "staffId": 1002,
+      "staffRole": "GUIDE",
+      "sortOrder": 1
+    },
+    {
+      "staffId": 2003,
+      "staffRole": "PHOTOGRAPHER",
+      "sortOrder": 0
+    }
+  ]
+}
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "success": true,
+  "data": {
+    "productBatchId": 80001,
+    "groupBatchId": 90211,
+    "staffList": [
+      {
+        "staffId": 1005,
+        "staffRole": "LEADER",
+        "staffName": "刘大山",
+        "staffPhone": "138****6677",
+        "sortOrder": 0
+      },
+      {
+        "staffId": 1002,
+        "staffRole": "GUIDE",
+        "staffName": "李雪梅",
+        "staffPhone": "138****8888",
+        "sortOrder": 1
+      },
+      {
+        "staffId": 2003,
+        "staffRole": "PHOTOGRAPHER",
+        "staffName": "王摄影",
+        "staffPhone": "188****9999",
+        "sortOrder": 0
+      }
+    ],
+    "affectedOrderCount": 3
+  }
+}
+```
+
+#### 空数据 / 降级响应
+
+`staffList` 传空数组清空覆盖范围内的人员：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "success": true,
+  "data": {
+    "productBatchId": 80001,
+    "groupBatchId": 90211,
+    "staffList": [
+      {
+        "staffId": 2003,
+        "staffRole": "PHOTOGRAPHER",
+        "staffName": "王摄影",
+        "staffPhone": "188****9999",
+        "sortOrder": 0
+      }
+    ],
+    "affectedOrderCount": 2
+  }
+}
+```
+
+（如果 `scopeRoles=["GUIDE","LEADER"]` 且 `staffList=[]`，则导游位人员全清，摄影位保留）
+
+#### 错误响应
+
+**`scopeRoles` 传了空数组**：
+
+```json
+{
+  "code": 400,
+  "message": "scopeRoles 传了就不能是空数组；要整期全量覆盖请整个字段不传",
+  "success": false,
+  "data": null
+}
+```
+
+**提交的人员角色超出 `scopeRoles` 声明的范围**（新错误码 `582115`）：
+
+```json
+{
+  "code": 582115,
+  "message": "提交的人员角色（PHOTOGRAPHER）超出本次保存声明的角色范围（GUIDE,LEADER），请检查配置位与人员是否匹配",
+  "success": false,
+  "data": null
+}
+```
+
+**特别情况：导游位只声明了 `GUIDE` 却选了 `LEADER`**：
+
+```json
+{
+  "code": 582115,
+  "message": "提交的人员角色（LEADER）超出本次保存声明的角色范围（GUIDE），请检查配置位与人员是否匹配",
+  "success": false,
+  "data": null
+}
+```
+
+**`staffList` 字段缺失**：
+
+```json
+{
+  "code": 400,
+  "message": "staff 配置列表不能缺失；确要清空请显式传空数组 []",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- **覆盖范围不校验完整性**：你可以只传 `scopeRoles=["GUIDE"]` 而保存时含有领队，后端照做。只覆盖 GUIDE 那一行，领队那一行在范围外。这个设计缺口（没有校验"GUIDE+LEADER 必须同时出现"）已在工单 #8122 记录，**前端若需保证配置位完整性，当前需自己在前端侧把关**。
+- **范围外人员拒绝率 100%**：如果 staffList 里有任何一项的 `staffRole` 不在 `scopeRoles` 声明的范围内，整个请求 `582115` 拒绝。失败时前端建议重新拉取当前配置以确保数据一致性。
+- **导游位的特殊性**：导游位由 `GUIDE` 和 `LEADER` 两个角色共同维护。保存导游位配置时，`scopeRoles` 必须同时包含 `["GUIDE", "LEADER"]`。只传其中一个（如 `["GUIDE"]`）会导致另一个角色的人员被拒（582115）。
+
+---
+
+## 四、契约约束与正确调用方式
+
+### ✅ 正确 / ❌ 错误 payload 对照
+
+| 场景 | payload | 结果 |
+|------|---------|------|
+| ✅ 保存导游位（两个角色都声明） | `scopeRoles: ["GUIDE","LEADER"], staffList: [{staffRole:"LEADER",...}]` | 200，导游位按新值覆盖，摄影位保留 |
+| ✅ 保存摄影位 | `scopeRoles: ["PHOTOGRAPHER"], staffList: [{staffRole:"PHOTOGRAPHER",...}]` | 200，摄影位按新值覆盖，导游位保留 |
+| ✅ 全量覆盖（不传 scopeRoles） | `staffList: [{staffRole:"GUIDE",...}, {staffRole:"PHOTOGRAPHER",...}]` | 200，整期全量覆盖（与改前一致） |
+| ✅ 清空导游位 | `scopeRoles: ["GUIDE","LEADER"], staffList: []` | 200，导游位人员全清，摄影位保留 |
+| ❌ 导游位只声明一个角色 | `scopeRoles: ["GUIDE"], staffList: [{staffRole:"LEADER",...}]` | 582115，拒绝 |
+| ❌ 传空 scopeRoles | `scopeRoles: [], staffList: [...]` | 400，拒绝 |
+| ❌ staffList 里有超出范围的角色 | `scopeRoles: ["GUIDE","LEADER"], staffList: [{staffRole:"PHOTOGRAPHER",...}]` | 582115，拒绝 |
+
+---
+
+## 五、数据库行为
+
+无 DDL、无 Flyway 迁移。全量覆盖与范围覆盖的删除窗口不同：
+
+| 操作 | 删除哪些旧行 | 插入哪些新行 |
+|------|------------|-----------|
+| 不传 `scopeRoles` | 整期所有角色 | `staffList` 的全部项 |
+| 传 `scopeRoles: ["GUIDE","LEADER"]` | 只删这两个角色的旧行 | `staffList` 的全部项（但必须都在范围内） |
+
+**范围外的既有行保持**：如果某个角色的人员不在覆盖范围内，本次保存对它们零影响，仍留在数据库。
+
+---
+
+## 六、边界行为
+
+- 未登录 → 401（网关拦截）
+- 团期不存在/未成团 → 589500 或 589552
+- 资源域 Feign 调用慢或失败 → 内部重试或超时返 500；不会静默降级造成快照不完整
+- 扇出异常 → 主事务已提交（数据已存盘），只是下游不知道；用户需手工检查或等待重试周期
+
+## 六.6、修改前后对比
+
+| 项 | 改前 | 改后 |
+|---|---|---|
+| 覆盖范围 | 全量（整期所有角色全删再全插） | 可选：不传 = 全量，传 `scopeRoles` = 按范围 |
+| 删除窗口 | `DELETE FROM order_batch_staff WHERE product_batch_id=?` | 按 `scopeRoles` 缩小范围 |
+| `staffList` 回显 | 本次提交的 items | **保存后的整期最终状态** |
+| 扇出数据 | 本次提交的 items（错误：只含本范围） | **整期最终状态**（正确：全部角色） |
+| 导游位保存风险 | 漏带摄影位 → 摄影师清空 | 不再互相干扰 |
+| 错误码集合 | — | 新增 `582115`（范围校验失败） |
+| 入参 | — | 新增 `scopeRoles`（可选） |
+
+## 六.7、影响评估
+
+| 维度 | 评估 |
+|---|---|
+| 兼容性 | **完全向后兼容**。不传 `scopeRoles` 时行为逐字不变，现有调用无需改动 |
+| 前端 | **需要改动**。弹窗打开时自动填充 `scopeRoles`（导游位 → `["GUIDE","LEADER"]`，摄影位 → `["PHOTOGRAPHER"]`），保存时传上去。后端已在测试环境部署在线，可立即改代码进行联调与实测 |
+| 数据 | 无 DDL；存量 `order_batch_staff` 数据不动 |
+| 回滚 | `git revert` 后，不传 `scopeRoles` 的调用照常工作；已传 `scopeRoles` 的调用会因新字段不认而 400（但改前没人用它，实际无影响） |
+| 必须同步上线 | 是。前后端一起上，否则前端新代码传 `scopeRoles` 到旧后端是 400 |
+
+---
+
+## 七、不影响范围
+
+- **零影响**：接口的 HTTP 方法、URL 路径、路径参数
+- **零影响**：不传 `scopeRoles` 时的全量覆盖行为（与改前一致）
+- **零影响**：存量 `order_batch_staff` 行（本次不迁移）；下次保存时按新逻辑处理
+- **零影响**：其他 staff 相关接口（查询、删除等）
+- **零影响**：扇出至子订单的链路（改的只是快照的构成方式，语义不变）
+
+---
+
+## 八、测试环境已验证
+
+✅ PR #8117 已合入 dev-v3（合并提交 094521f0b），当前测试环境部署 commit d30cd9561，本次变更已在线。
+
+**编译验证**：CI 全绿，含 ArchTest / 单测 / 静态检查
+
+**单测覆盖**（241 examples new + existing，全过）：
+- 范围保存的删除窗口（0.5 → 1.5 间隔）
+- 导游位必须同时声明两个角色（缺一触发 582115）
+- staffList 超出范围拒绝（582115）
+- 回显值切换（toInsert → finalState）
+- 扇出快照来源（同上）
+- ready 回填按整期算（不按本范围算）
+- 不传 scopeRoles 时全量行为不变
+
+**测试数据**：一律 `T8006-` 前缀，验证后已清理。
+
+---
+
+## 十、相关文档
+
+- 工单：[#8006](https://git.1814.love:8443/wx/HL/issues/8006) — 团期人员配置跨角色清空风险
+- PR：[#8117](https://git.1814.love:8443/wx/HL/pulls/8117) — 本次修复
+- 相关缺口：[#8122](https://git.1814.love:8443/wx/HL/issues/8122) — `scopeRoles` 完整性校验（已记录，待处理）
+
+---
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8006](https://git.1814.love:8443/wx/HL/issues/8006)
+- **PR**: [#8117](https://git.1814.love:8443/wx/HL/pulls/8117)
+- **Merge commit**: [094521f0b](https://git.1814.love:8443/wx/HL/commit/094521f0b)
+
+### 联系人
+
+- **后端负责人**: @wx
@@ -0,0 +1,321 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8045"
+title: "团期详情返回整团待收 unpaidAmount"
+consumer: "admin"
+author: "jw(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "e680cf10c2b8c0377ea89d21ab13eea1e740f429"
+target_release: "v2.1"
+verified_at: "2026-09-21"
+status_note: "团期详情端点（A2）新增响应字段 unpaidAmount（整团待收），值 = max(0, receivableAmount − receivedAmount)，恒非 null 恒非负，字符串型金额。此前该端点已同时返回 receivableAmount 与 receivedAmount，但没有待收字段，前端只能自己做减法——而本页子订单项的 balanceAmount 是另一套算法（扣退款、取消单归 0），前端自算会在同一屏里产生第二套口径，故由后端给出。【前端交付 2026-09-21 mmg：BatchHero 金额区补「待收」直显 detail.unpaidAmount（warning 色，缺失兜底 —，不自算），NTooltip 标注「退款不回减，权威待收以财务 tab 明细/合计为准」；FinanceTab 早已展示 totals/items unpaidAmount 零改动；BatchHero 8 例全过，hl-admin v2.1 e680cf10。】列表页（A1）早已有同名字段，本次是把详情页补齐，两处同源同公式。⚠️ 两点必须读：① 本字段按「毛累计已付」算，发生过退款的团偏小；逐户扣退款的权威待收在财务 tab 的 items/totals，不是财务 tab 的顶层 unpaidAmount（顶层与本字段同源同公式，数值一致）——同页展示两者时请在 UI 上区分标注（实测见「八」）。② 不要把它与子订单项的 balanceAmount 混用。本页既有四个金额字段（receivableAmount / receivedAmount / totalReceivable / totalReceived）的值、名称、形态逐字未变，纯增量。"
+updated_at: "2026-09-21"
+base: "dev-v3"
+---
+
+# order-v3: 团期详情返回整团待收 unpaidAmount
+
+> **服务**: hl-order-service-v3 (端口 8086)
+> **PR**: [#8101](https://git.1814.love:8443/wx/HL/pulls/8101)
+> **Issue**: [#8045](https://git.1814.love:8443/wx/HL/issues/8045)
+> **日期**: 2026-09-21
+> **影响范围**: 管理后台「团期详情」页顶部金额区（列表点团期进去的那一页）
+
+---
+
+## ⚠️ 关键变化
+
+- **纯增量**：既有字段一个都没改，只多返回一个 `unpaidAmount`。不接入的前端不受影响。
+- **不要再自己拿 `receivableAmount − receivedAmount`** —— 后端已给出这个值，且做了解析保护（负数不透出）。
+- **不要与本页子订单项的 `balanceAmount` 混用**：`balanceAmount` 是 per-order「应收 − 已退 − 已付」（扣退款、取消单归 0），与本字段**同名不同义**。#7066 曾专门花一节向前端解释过这个坑，这里再强调一次。
+- **🔴 有退款的团，本字段会偏大**：本字段用的是「毛累计已付」（退款不回减），财务 tab 的**逐户明细与合计**（`items[].unpaidAmount` / `totals.unpaidAmount`）是逐户扣退款的。**注意是「明细与合计」，不是财务 tab 的顶层 `unpaidAmount`** —— 财务 tab 顶层的 `unpaidAmount` 与本字段同源同公式，数值一致（实测见第八节）。若把本字段与财务 tab 的**合计**放在同一屏，两者会差一个「累计已退」的量，请在 UI 上区分标注，权威待收以财务 tab 的逐户明细/合计为准。
+
+---
+
+## 一、背景
+
+`#7535` 那一批统一了团期金额字段命名，同时给**列表**页（A1 分页项 `GroupBatchPageItemRespVO`）加了 `unpaidAmount`，但对**详情**页（A2）只做了 `totalReceivable/totalReceived` → `receivableAmount/receivedAmount` 的命名统一，**漏了待收字段**。
+
+于是出现「列表页有待收、点进详情页反而没有」的观感缺口：运营要一眼看到「这个团还差多少钱没收」，只能心算，或退回列表页看。
+
+需求来源：前端 2026-09-20《前端待后端交付清单》第 3 项，原文标注「无工单，待排期」；本单为该事项排期。前端明确拒绝自算，理由是「口径会漂移」——这个担心成立，见上一节。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 团期详情（A2） | GET | `/v3/admin/order/group-batch/:id` | 修改 | 响应新增 `unpaidAmount`（整团待收） |
+
+> 财务 tab 端点 `GET /v3/admin/order/group-batch/:id/finance` **本次一行未改**，列在本节仅为对照口径。
+
+---
+
+## 三、接口详情
+
+### 1. 团期详情 `GET /v3/admin/order/group-batch/:id`
+
+**VO**: `Result<GroupBatchDetailRespVO>`
+
+#### 使用场景
+
+管理后台「团期详情」页主数据。进入该页时调用一次，页面顶部的整团应收 / 已收 / **待收** 三格都读本响应。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | String(雪花 ID) | ✅ | 团期 ID | 不存在或已软删返回 589500 |
+
+#### 出参 `Result<GroupBatchDetailRespVO>`
+
+本次**只新增 1 个字段**，其余字段一律不动、不改名、不改类型。
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| receivableAmount | String(金额) | 整团应收（Σ 在团子订单应付总额）。**不变** |
+| receivedAmount | String(金额) | 整团已收（Σ 毛累计已付，退款不回减）。**不变** |
+| **unpaidAmount** | String(金额) | **【新增】** 整团待收 = `max(0, receivableAmount − receivedAmount)`。恒非 null、恒 ≥ 0 |
+| totalReceivable | String(金额) | 已废弃，与 `receivableAmount` 逐字同值。**不变**（只标记不删） |
+| totalReceived | String(金额) | 已废弃，与 `receivedAmount` 逐字同值。**不变**（只标记不删） |
+
+金额一律是**字符串**（如 `"12000.00"`），不是 JSON 数字，**不要当数字解析**。
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch/2101908228566908930
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "groupBatchId": "2101908228566908930",
+    "receivableAmount": "4000.00",
+    "receivedAmount": "2000.00",
+    "unpaidAmount": "2000.00",
+    "totalReceivable": "4000.00",
+    "totalReceived": "2000.00"
+  },
+  "success": true
+}
+```
+
+（仅列相关字段，其余字段保持原样。）
+
+#### 空数据 / 降级响应
+
+无在团子订单的空团，三个金额**同为 `"0"`**（注意不是 `"0.00"`，与列表页 A1 的行为一致，前端自行格式化）：
+
+```json
+{
+  "code": 200,
+  "data": {
+    "receivableAmount": "0",
+    "receivedAmount": "0",
+    "unpaidAmount": "0"
+  },
+  "success": true
+}
+```
+
+#### 错误响应
+
+团期不存在或已软删：
+
+```json
+{
+  "code": 589500,
+  "message": "团期不存在",
+  "data": null,
+  "success": false
+}
+```
+
+无查看权：
+
+```json
+{
+  "code": 589507,
+  "message": "无权限访问该团期",
+  "data": null,
+  "success": false
+}
+```
+
+| 码 | 触发 |
+|---|---|
+| 589500 | `groupBatchId` 不存在或已软删 |
+| 589507 | 调用方无团期查看权；定制师读不属于自己的团期 |
+
+鉴权失败在本项目是 **HTTP 200 + body `code=401`**，不要只看 HTTP 状态码。
+
+#### 业务边界
+
+- **本字段是纯内存计算**，不新增查询、不新增 Feign 调用；响应变慢与它无关。
+- **不是权限变更**：A2 走一般查看权（`PERMISSION_VIEW`），本字段不扩大任何信息暴露面——它是由同一响应里**已经返回**的 `receivableAmount` 与 `receivedAmount` 相减得到的，信息增量为零。
+- **口径**：`receivedAmount` 是毛累计已付、**退款不回减**，所以发生过退款的团本字段**偏小**（应收没变、已付也没被退款冲减，差额仍然是「待收」）。
+- **标度**：沿用同一行 `receivableAmount` / `receivedAmount` 的原始标度，不做二次收敛。同一行三个金额标度一致。
+- **负值保护**：已收多于应收（退款 / 多收留下的历史脏数据）时返回 `"0"`，**不会出现负号**。
+
+---
+
+## 四、契约约束与正确调用方式
+
+- **不要自己算**：直接读 `unpaidAmount`，不要写 `receivableAmount - receivedAmount`。
+- **不要用 `balanceAmount` 顶替**：那是子订单项的 per-order 口径（应收 − 已退 − 已付，取消单归 0），与本字段**同名不同义**。
+- **财务 tab 的对照口径要说清是哪一个**：
+  - 财务 tab **顶层** `unpaidAmount` —— 与本字段**同源同公式**，数值一致（**不是**逐户扣退款的）。
+  - 财务 tab `items[].unpaidAmount` / `totals.unpaidAmount` —— **逐户扣退款**的权威口径。有退款的团，它与本字段会差一个「累计已退」。
+- 三个金额都是字符串，`"0"` 与 `"0.00"` 都可能出现（空团是前者），比较时请按数值比较而不是字符串相等。
+
+---
+
+## 六、边界行为
+
+| 场景 | 行为 |
+|---|---|
+| 正常有在团子订单 | `unpaidAmount = 应收 − 已收`（两位小数） |
+| 无在团子订单（空团） | 三个金额同为 `"0"`，非 null |
+| 已收 > 应收（多收 / 退款脏数据） | `unpaidAmount` 返回 `"0"`，不透负数。**TEST 实测见第八节** |
+| 发生过退款的团 | 本字段按毛已付算，比财务 tab 的**逐户合计**偏大；与财务 tab 顶层一致 |
+| 团期不存在 / 已软删 | 589500 |
+| 无查看权 | HTTP 200 + body `code=589507` |
+| 老前端不读新字段 | 纯增量，无影响 |
+
+---
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 |
+|------|------|------|
+| `unpaidAmount` | **不存在**（响应体里没有这个 key） | `"12000.00"`（字符串型金额） |
+| `receivableAmount` | `"48000.00"` | `"48000.00"`（**逐字未变**） |
+| `receivedAmount` | `"36000.00"` | `"36000.00"`（**逐字未变**） |
+| `totalReceivable` | `"48000.00"`（已废弃） | `"48000.00"`（**逐字未变**，仍只标记不删） |
+| `totalReceived` | `"36000.00"`（已废弃） | `"36000.00"`（**逐字未变**） |
+| 其余全部字段 | — | **一个都没动** |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| 详情页「待收尾款」从哪来 | 前端自己拿 `receivableAmount − receivedAmount` 算 | 后端返回 `unpaidAmount`，前端直接读 |
+| 已收大于应收时 | 前端自算会拿到负数，得自己处理 | 后端返回 `"0"`，不透负数 |
+| HTTP 状态 / 错误码 / 判权 | — | **不变** |
+| 响应耗时 | — | **不变**（新增字段是内存计算，不加查询、不加 Feign） |
+
+---
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 否。纯增量字段，既有四个金额字段的值 / 名称 / 类型 / JSON 形态逐字未变（TEST 改前改后逐字对照见第八节）。
+- **前端是否必须同步上线**: 否。不接入则详情页保持现状（没有待收那一格）。
+- **前端 workaround 清理点**: 若前端此前在详情页**自己算过**待收（`receivableAmount - receivedAmount`），现在可以撤掉，改读 `unpaidAmount`。
+- **回滚**: 回滚本 PR 即可，只读端点、无数据变更、无表结构变更。
+
+---
+
+## 七、不影响范围
+
+- `GET /v3/admin/order/group-batch/:id/finance`（财务 tab）**一字未改**。
+- `GET /v3/admin/order/group-batch`（A1 列表）**一字未改**，它的 `unpaidAmount` 早就存在。
+- 子订单项 `balanceAmount`（`GroupBatchOrderItemRespVO`）**未动**。
+- 判权、错误码、网关路由、事务与锁**均未变**。
+- 其他微服务（hl-finance / hl-product-service-v2 / hl-user-service 等）**未动**。
+- 无数据库表结构变更，无 Flyway 迁移。
+
+---
+
+## 八、测试环境已验证
+
+TEST 环境（`hl-order-service-v3` + `hl-gateway` 均为 dev-v3 @ `c238f38c3`，`BEHIND 0/N`，`STATE ok`），2026-09-21，走真实网关 `https://api.test.1814.love:9443`。
+
+**构建身份探针**（改前 / 改后同端点对照，确认跑的确实是本单代码）：
+
+```
+改前（dev-v3 旧字节）GET /v3/admin/order/group-batch/2101908228566908930  → 响应体没有 unpaidAmount 这个 key   ✓
+改后（dev-v3 c238f38c3）同 URL                                            → 出现 "unpaidAmount": "2000.00"       ✓
+```
+
+```
+AC-1  金额正确 + 形态：团 2101908228566908930
+        receivableAmount "4000.00" / receivedAmount "2000.00" / unpaidAmount "2000.00"
+        手算 max(0, 4000.00 − 2000.00) = 2000.00，一致；三个都是 JSON 字符串          ✓
+      团 2101906599658618882：应收 "6000.00" / 已收 "0.00" / 待收 "6000.00"           ✓
+AC-2  已收 > 应收边界（自造 fixture，见「造数清单」）：
+        应收 "2000.00" / 已收 "3000.00" → unpaidAmount = "0"，无负号，非 null          ✓
+AC-3  空团：团 2101250106387726338 无在团子订单
+        receivableAmount "0" / receivedAmount "0" / unpaidAmount "0"（同值同形态）     ✓
+AC-4  纯增量：四个既有字段改前 → 改后逐字一致（4 个团全部比对，含空团与有退款的团）    ✓
+AC-5  注解四层文案（公式 / null 按 0 参与 / 退款不回减 / 权威口径指向财务 tab），
+        并由新增的单测钉住，删掉任一层即红                                          ✓
+AC-6  「应收减已收」仍只有一处实现：新增行不含 `.subtract(`；实参调既有 calcUnpaid     ✓
+AC-7  calcUnpaid 的「只此一处减法」javadoc 已列入 toDetailVO 这条新调用方              ✓
+AC-8  精确测试：GroupBatchConverterTest 108 + GroupBatchAliasFieldSerializationTest 7
+        + GroupBatchQueryControllerTest 9 = 124 跑 / 0 失败 / 0 错误                   ✓
+      变异证明：注释掉 toDetailVO 那一行后恰好这 4 个转换器用例红（108 跑 / 4 失败），
+        控制器与序列化类保持绿 —— 新断言不是恒真                                     ✓
+AC-9  MapperBoundaryArchTest 门禁：本单零新增违规，门禁红系既有基线
+        （干净的 c62907410 上同样 27 跑 / 1 失败，9 处违规全在 payment → refund.mapper，
+         见 [#7989](https://git.1814.love:8443/wx/HL/issues/7989)，P1，yst 属主）
+AC-10 网关实测（上方 URL 与 deploy-status 两行）                                       ✓
+AC-11 有退款的团与财务 tab 的口径对照，见下                                            ✓
+```
+
+**AC-11 口径对照**（团 `2099459274966016001`，子订单 `HL20260914192431793` 有一笔 100.00 的**成功退款**）：
+
+| 取值处 | 数值 | 是否扣退款 |
+|---|---|---|
+| **本单新增的 A2 `unpaidAmount`** | `"1900.00"` | 否（毛已付） |
+| 财务 tab **顶层** `unpaidAmount` | `"1900.00"` | 否（**与本字段同源同公式**） |
+| 财务 tab `totals.unpaidAmount` | `"1800.00"` | **是**（逐户扣退款） |
+| 财务 tab `items[0].unpaidAmount` | `"1800.00"` | **是** |
+
+1900.00 − 1800.00 = **100.00 = 该团那笔退款金额**。即：**本字段与财务 tab 顶层一致，与财务 tab 的逐户合计差一个「累计已退」**——前端要对齐的权威口径是后者。
+
+> 扫描口径补充：TEST 上 237 个团期，**顶层 `unpaidAmount` 与「应收 − 已收」无一不等**（两者同源）；顶层与 `totals` 不等的恰好 1 个，就是上表这个有退款的团。
+
+**送测数据（自造，请勿清理）**：
+
+| groupBatchId | 名称 | 用途 | 现状 |
+|---|---|---|---|
+| `2101927290046943234` | `#8045-AC2多收边界` | AC-2「已收 > 应收」边界造数（其子订单 `2101927289925308418` 的 `paid_amount` 曾临时置 3000.00，**已还原为 0.00**） | 挂 1 个子订单（PENDING_PAY），班期出发日 2026-12-20 |
+
+> 该班期挂着订单，删不掉（`BATCH_HAS_ENROLLED_ORDERS`），留着不干扰他人：未被可报名谓词 / 选品列表 / order-v3 下单闸采纳。
+
+其他 AC 用的是 TEST 上**既有**真实团期，未改任何既有数据。
+
+---
+
+## 十、相关文档
+
+- 工单 [#8045](https://git.1814.love:8443/wx/HL/issues/8045)
+- [#7535](https://git.1814.love:8443/wx/HL/issues/7535) 团期金额字段命名统一（A1 加了 `unpaidAmount`，A2 漏了，本单补齐）
+- [#7066](https://git.1814.love:8443/wx/HL/issues/7066) 解释过「两个 `balanceAmount` 同名不同义」的那个坑
+- [#7989](https://git.1814.love:8443/wx/HL/issues/7989) order-v3 ArchTest 门禁既有基线红（与本单无关，登记在案）
+
+---
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8045](https://git.1814.love:8443/wx/HL/issues/8045)
+- **PR**: [#8101](https://git.1814.love:8443/wx/HL/pulls/8101)
+
+### 联系人
+
+- **后端负责人**: @jw
+- **前端负责人**: @mmg
@@ -11,9 +11,9 @@ frontend_status: "not_required"
 frontend_owner: ""
 frontend_ref: ""
 target_release: ""
-verified_at: "2026-09-21"
-status_note: "本条无任何接口出入参或错误码变化，变的是同一请求的副作用：共用关系现在会在成员失去占用时自动收缩、剩余不足 2 人时自动解除。gateway_status=verified 的依据是 2026-09-21 经网关 https://api.test.1814.love:9443 的真实调用（建关系 + 两次 soft-clear-assignment），调用流水与库内终态逐条对照一致，不是只看部署登记。frontend_status 取 pending 而非 not_required：本条会让共用关系『自己消失』，前端是否需要改代码取决于它有没有缓存 activeShareGroupId 或假设关系只能人工解除——那是我无法从后端查证的事实，所以不替前端下 not_required 的结论；mmg 评估后若确认零改动，再由前端侧改为 not_required。⚠️ 存量数据尚未收敛（工单 #8064 AC-5 未完成，成文时实测孤儿关系 7 条），本次修复只对修复上线后发生的释放动作生效。前端实证 not_required(mmg 2026-09-21):按「四、前端要做什么」逐项自查——activeShareGroupId/shareGroup/share-groups/shareEligible 前端 src 全仓零命中(共用关系属 #7444 未接入挂起域,同 #8051/#8061 实证口径),前端无任何共用关系状态缓存、无「关系只能人工解除」的假设;未来接入时均为操作后实时拉取,自动收缩不产生前端脏读。"
-updated_at: "2026-09-21"
+verified_at: ""
+status_note: "本条无任何接口出入参或错误码变化，变的是同一请求的副作用：共用关系现在会在成员失去占用时自动收缩、剩余不足 2 人时自动解除。gateway_status=verified 的依据是 2026-09-21 经网关 https://api.test.1814.love:9443 的真实调用（建关系 + 两次 soft-clear-assignment），调用流水与库内终态逐条对照一致，不是只看部署登记。本条会让共用关系『自己消失』，前端是否需要改代码取决于两点：有没有缓存 activeShareGroupId、有没有「关系只能人工解除」的假设。这两点后端查证不了，已由前端侧自查确认（见下文 mmg 的实证）。⚠️ 存量收敛已于 2026-09-21 执行完毕（AC-5）：经应用路径点名收敛，摘除成员行 10 条、整体释放关系 4 条；另有 2 条关系在摘除成员后仍保持 ACTIVE——那是正确终态，收缩规则是「剩余成员 < 2 时才整体释放」，这 2 条原各 3 名成员、摘 1 名后仍剩 2 名。本轮为点名执行而非全库扫，名单外可能仍存在同类历史数据，前端展示逻辑该兜的仍要兜。前端实证 not_required(mmg 2026-09-21):按「四、前端要做什么」逐项自查——activeShareGroupId/shareGroup/share-groups/shareEligible 前端 src 全仓零命中(共用关系属 #7444 未接入挂起域,同 #8051/#8061 实证口径),前端无任何共用关系状态缓存、无「关系只能人工解除」的假设;未来接入时均为操作后实时拉取,自动收缩不产生前端脏读。"
+updated_at: "2026-09-22"
 base: "dev-v3"
 ---

@@ -94,6 +94,26 @@ if (!context.dualWrite()) {

 软清会把该派车行的**车与司机一起清空**（车辆 id / 车牌 / 车型 / 司机 id / 姓名 / 电话全部置空，并把当日车辆用量归零）。⇒ 若该派单同时参与了 VEHICLE 维度与 DRIVER 维度的两条共用关系，**两条都会受影响**，不是只动一条。

+**2026-09-22 双维度活体实测坐实**（此前这一段是源码推演，现补实测）：自建班期下造 2 条派单共用**同一辆车 + 同一个司机**，于是 VEHICLE 与 DRIVER 各成一条 2 人共用关系；软清其中一条派单后，两条关系**各自独立**收缩，**同时**转 `RELEASED`：
+
+| 维度 | 关系状态 | `release_reason` | `released_at` |
+|---|---|---|---|
+| VEHICLE | `RELEASED` | `AUTO_SINGLE_MEMBER` | `2026-09-21 16:32:26` |
+| DRIVER | `RELEASED` | `AUTO_SINGLE_MEMBER` | `2026-09-21 16:32:26` |
+
+两条关系下的**全部 4 条成员行**（含**未被软清**的那一户在两条关系里的成员行）都落 `left_at = 2026-09-21 16:32:26`、`leave_reason = AUTO_OCCUPANCY_RELEASE`；未被软清那条派单的派车行本身**完全未动**（车、司机、状态原样）。
+
+⇒ **前端含义**：一次软清会让该派单参与的**每一个**维度的关系消失。若界面按维度分别渲染共用关系，操作后**两块都要重新拉取**，不能只刷新其中一块。
+
+### 机制是「每个维度各自收缩」，不是「一个维度带动另一个」
+
+自动收缩的触发口是**占用被释放**：`GroupDispatchShareOccupancyRefService#onClaimReleased` 按 `(服务日, 资源维度, 资源 ID, 来源)` 判定，只接**单个**资源维度，方法体内没有任何跨维度查询；上游 `OccupancyDualWriteCoordinator#notifyShareGroupOfRelease` 按**单条**占用行取它自己的维度调一次。⇒ 上一节看到的「两条同时 RELEASED」，成因是**同一个动作释放了两个维度的占用**（软清清整行），钩子因此被各调了一次，**不是**维度之间有传导。
+
+这个区别对前端有实际后果，体现在**手工解除关系**上：
+
+- 调解除接口解除 VEHICLE 维度的关系时，后端按释放集算法决定哪些成员的占用真被释放（被释放的那些会走软清 ⇒ 它们在 DRIVER 维度的关系也随之收缩），**留任的成员占用不变**⇒ 它们在 DRIVER 维度的关系**原样保留**。
+- ⇒ **别预测**「解除一个维度会不会连带另一个」——它取决于这次解除把谁判进了释放集。**操作后两个维度都重新拉取**是唯一可靠的做法。
+
 ### 整团解除不会被改写成自动收缩

 整团解除时，关系的 `release_reason` 仍记录整团解除的原因，不会被自动收缩改写成 `AUTO_SINGLE_MEMBER`（PR #8077）。审计与对账按 `release_reason` 区分来源时，这一点是可靠的。
@@ -127,7 +147,12 @@ if (!context.dualWrite()) {
 - **取消派单**对在途行的行为（仍落 `exception`、仍保留占用，#6152 定案不变）。
 - **整团解除**的审计原因（PR #8077 专门保证它不被夺走）。
 - 占用账本（`fleet_resource_occupancy_*`）的灰度形态——**仍维持 `LEGACY`，本次修复没有切换它**，这正是本次修复的设计目标：不靠切形态也能让收缩跑起来。
- **存量数据**：⚠️ **未收敛**。工单 #8064 AC-5 的存量收敛尚未执行（成文时实测孤儿关系 **7** 条，判据为"有 alive 成员但该成员已不占用本资源的 ACTIVE 关系"）。本次修复**只对修复上线之后发生的释放动作生效**，历史遗留的不一致关系仍需单独收敛，完成后本文件会追加说明。
+- **存量数据**：已通过 internal 端点执行收敛（2026-09-21 22:27:47 UTC，不是 SQL 直改）。结果：
+  - 摘除成员 **10 行**：`left_at = 2026-09-21 22:27:47`、`leave_reason = AUTO_OCCUPANCY_RELEASE`
+  - 整体释放关系 **4 条**：`status = RELEASED`、`release_reason = AUTO_SINGLE_MEMBER`、`released_at = 2026-09-21 22:27:47`
+  - 摘除成员后仍保持 ACTIVE 的关系 **2 条**（**非残留**：它们各有 3 个成员，摘掉 1 个后剩 2 个，按收缩规则"剩余 < 2 时解除"不触发）
+  
+  ⚠️ 本轮收敛是**点名执行**（传入显式 ID 名单），不是全库扫。若名单外仍有同类历史数据，前端在界面上仍可能遇到"有成员、但该成员已不占用该资源"的关系——**展示逻辑该兜的还得兜**，别假设这类数据在库里已绝迹。

 ## 七、相关历史 PR

@@ -0,0 +1,414 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8068"
+title: "派单操作时间线新增软清记录留痕"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "not_required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "前端 2026-09-21 实证 not_required:orderLog.js operationKind 为关键字匹配+note 兜底(非 opType 白名单),title 直吃后端 opTypeLabel,OperationLogModal 只读时间线不过滤不解析 detailJson,soft_cleared 与 share_release_cleared 均正常渲染,无静默漏渲染风险;无业务改动。"
+updated_at: "2026-09-21"
+base: "dev-v3"
+---
+
+# fleet: 派单操作时间线新增软清记录留痕
+
+> **存放目录**: `changelogs-v2/2026-09/`
+>
+> **服务**: hl-fleet-service (端口 8003)
+> **PR**: #8113
+> **Issue**: #8068
+> **日期**: 2026-09-21
+> **影响范围**: 车务手动派车清空链路；派单操作时间线接口返回的操作记录
+
+---
+
+## ⚠️ 关键变化
+
+车务手动软清派车行（清空所选行的车辆/司机），以前在 `fleet_assignment` 表直接清空不留痕迹。现已补齐写口留痕：`fleet_assignment_operation_log` 新增 `soft_cleared` 操作类型。
+
+**前端影响**：派单看板订单卡片「查看日志」时间线会新增这类记录。如果前端按 `operation_type` 做了白名单过滤，`soft_cleared` 需要加进去——不加会静默漏渲染。
+
+---
+
+## 一、背景
+
+软清是车务人员在派车界面一次性清空多个选中行的车辆/司机字段，状态置回「待改派」。此前的实现直接 UPDATE 字段不写日志，导致事后无法查证「是谁、什么时候、清掉了哪个司机/哪台车」（工单 #8051 #8068 提及）。
+
+本次补齐留痕机制：每次软清都在 `fleet_assignment_operation_log` 写一行，记录被清空前的身份快照及操作范围。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 派单操作时间线 | GET | `/admin/fleet/orders/{orderId}/operation-log` | 响应新增操作类型 | 新增 `soft_cleared` 枚举值 + `detail_json` 字段扩展 |
+
+---
+
+## 三、接口详情
+
+### 1. 派单操作时间线 `GET /admin/fleet/orders/{orderId}/operation-log`
+
+**VO**: `FleetOperationLogItemVO → FleetOrderOperationLogRespVO`
+
+#### 使用场景
+
+车务在派车看板订单卡片内点「查看日志」，实时呈现该订单全部派车操作的不可变时间线。新操作类型 `soft_cleared` 会在此时间线中出现。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| orderId | Path | Long | ✅ | 雪花 ID | 订单 ID |
+| page | Query | Integer | ❌ | 默认 1，上限 100000 | 分页页码 |
+| pageSize | Query | Integer | ❌ | 默认 50，上限 200 | 每页条数 |
+| sortBy | Query | String | ❌ | 支持 `time,asc` | 排序字段，默认 create_time 倒序 |
+
+#### 出参 `Result<FleetOrderOperationLogRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data.records | List<FleetOperationLogItemVO> | 当前页操作日志行 |
+| data.records[].id | String | 日志行 ID（雪花号，以字符串返回防精度丢失） |
+| data.records[].time | LocalDateTime | 操作时间（ISO 8601 格式） |
+| data.records[].opType | String | 操作类型英文枚举值，**含新增的 `soft_cleared`** |
+| data.records[].opTypeLabel | String | 操作类型中文标签（由后端从枚举翻译） |
+| data.records[].summary | String | 可读摘要（后端拼接：操作人 + 动作 + 前后值对比） |
+| data.records[].operatorName | String | 操作人（企微名优先，无则用户名，系统动作显示「系统」） |
+| data.records[].effectiveDate | LocalDate | 生效日期（按天改派等动作有值，无则 null） |
+| data.records[].detailJson | String | 明细 JSON，格式见下节 |
+| data.total | Long | 总条数 |
+| data.page | Integer | 当前页码 |
+| data.pageSize | Integer | 本页条数 |
+
+#### 新增字段详情
+
+**`opType` 新增枚举值**
+
+| 值 | 中文标签 | 触发场景 |
+|----|----------|---------|
+| `soft_cleared` | 清空司机/车辆 | 车务在派车界面手动清空选中行的车辆/司机字段 |
+
+**`detailJson` 字段（当 `opType="soft_cleared"` 时）**
+
+响应的 `detailJson` 是字符串化的 JSON，结构如下（示例已脱敏保留字段结构）：
+
+```json
+{
+  "scope": "GROUP",
+  "assignmentGroupId": "360380081354444801",
+  "statusBefore": "assigned",
+  "clearedRowCount": 1,
+  "vehicleIdBefore": "2085539421276286978",
+  "driverIdBefore": "2067084362829979650",
+  "vehiclePlateSnapshot": "蒙A-E2E99",
+  "driverNameSnapshot": "王信",
+  "clearedRows": [
+    {
+      "assignmentId": "2101990265092984833",
+      "serviceDate": "2026-12-22",
+      "vehicleIdBefore": "2085539421276286978",
+      "vehiclePlateBefore": "蒙A-E2E99",
+      "driverIdBefore": "2067084362829979650",
+      "driverNameBefore": "王信"
+    }
+  ]
+}
+```
+
+字段说明：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| scope | String | 清空范围，`GROUP` 表示按派车组（团期）整组清空 |
+| assignmentGroupId | String | 派车组 ID（字符串格式，防雪花 ID 过 JS 掉精度） |
+| statusBefore | String | 清空前状态，通常为 `assigned`（已派车） |
+| clearedRowCount | Integer | 本次清空涉及的派车行数 |
+| vehicleIdBefore | String | **清空前的车辆 ID**（19 位雪花号，字符串返回） |
+| driverIdBefore | String | **清空前的司机 ID**（19 位雪花号，字符串返回） |
+| vehiclePlateSnapshot | String | 清空前的车牌号（可读值快照，用于日志展示） |
+| driverNameSnapshot | String | 清空前的司机名（可读值快照，用于日志展示） |
+| clearedRows | Array | 本次清空涉及的所有派车行详情，每行包含 assignmentId / serviceDate / 清空前的车辆/司机 ID 与车牌/司机名 |
+
+**关键说明：所有 ID 字段都以字符串返回**
+
+派车 ID、司机 ID、车辆 ID 等均采用字符串格式。**这很重要**：JavaScript 的 `Number` 类型只能精确表示到 16 位数字，而雪花 ID 是 19 位。若以数字解析，末位会被四舍五入，导致 ID 失真且无任何错误提示。
+
+#### 请求示例
+
+```http
+GET /admin/fleet/orders/2085539421276286978/operation-log?page=1&pageSize=50 HTTP/1.1
+Host: {后台域名}
+Authorization: Bearer {token}
+Accept: application/json
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "success": true,
+  "data": {
+    "records": [
+      {
+        "id": "2101990265092984834",
+        "time": "2026-09-21T18:45:32",
+        "opType": "soft_cleared",
+        "opTypeLabel": "清空司机/车辆",
+        "summary": "车务 王信 清空司机/车辆：蒙A-E2E99王信，派车行 1 行待改派",
+        "operatorName": "王信",
+        "effectiveDate": null,
+        "detailJson": "{\"scope\":\"GROUP\",\"assignmentGroupId\":\"360380081354444801\",\"statusBefore\":\"assigned\",\"clearedRowCount\":1,\"vehicleIdBefore\":\"2085539421276286978\",\"driverIdBefore\":\"2067084362829979650\",\"vehiclePlateSnapshot\":\"蒙A-E2E99\",\"driverNameSnapshot\":\"王信\",\"clearedRows\":[{\"assignmentId\":\"2101990265092984833\",\"serviceDate\":\"2026-12-22\",\"vehicleIdBefore\":\"2085539421276286978\",\"vehiclePlateBefore\":\"蒙A-E2E99\",\"driverIdBefore\":\"2067084362829979650\",\"driverNameBefore\":\"王信\"}]}",
+        "changeDetail": null
+      },
+      {
+        "id": "2101990265092984833",
+        "time": "2026-09-21T18:45:31",
+        "opType": "assignment_created",
+        "opTypeLabel": "新建派单",
+        "summary": "系统 新建派单：蒙A-E2E99王信，生效日 12/22",
+        "operatorName": "系统",
+        "effectiveDate": "2026-12-22",
+        "detailJson": null,
+        "changeDetail": null
+      }
+    ],
+    "total": 2,
+    "page": 1,
+    "pageSize": 50
+  }
+}
+```
+
+#### 空数据 / 降级响应
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "success": true,
+  "data": {
+    "records": [],
+    "total": 0,
+    "page": 1,
+    "pageSize": 50
+  }
+}
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 404,
+  "message": "订单不存在",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- **权限**：网关 `/admin/fleet/**` 统一鉴权，车务/管理员可访问
+- **分页上限**：pageSize 最高 200，page 最高 100000
+- **排序**：默认按 create_time 倒序（新操作在前）；支持 `sortBy=time,asc` 升序
+- **ID 精度**：所有雪花号均以字符串返回，前端切勿转为 Number 类型
+- **历史数据兼容**：该接口是只读时间线，查询时包含所有 `operation_type` 值（包括本次新增的 `soft_cleared`）
+
+---
+
+## 四、契约约束与正确调用方式
+
+### ✅ 正确 / ❌ 错误 payload 对照
+
+此接口为只读 GET，无请求体。正确调用示例：
+
+| 场景 | URL |
+|------|-----|
+| ✅ 第一页，默认排序 | `GET /admin/fleet/orders/2085539421276286978/operation-log?page=1&pageSize=50` |
+| ✅ 升序时间线 | `GET /admin/fleet/orders/2085539421276286978/operation-log?sortBy=time,asc&pageSize=50` |
+| ✅ 处理 detailJson 字符串 | `JSON.parse(record.detailJson)` 转为对象后访问字段 |
+| ❌ ID 作为 Number | `parseInt(record.id)` 会导致末位精度丢失 |
+| ❌ 分页超过上限 | `pageSize=500` → 400 Bad Request |
+
+### 处理 detailJson 的正确方式
+
+`detailJson` 字段值本身是 JSON 字符串（因为在 SQL 层 `detail_json` 列是 text 类型，序列化到 JSON 响应时被转义成字符串）。前端需要先 parse 再访问：
+
+```javascript
+// ❌ 错误：直接访问
+const vehicleId = record.detailJson.vehicleIdBefore;  // undefined
+
+// ✅ 正确：先 parse
+const detail = JSON.parse(record.detailJson);
+const vehicleId = detail.vehicleIdBefore;  // "2085539421276286978"
+
+// ✅ 保持字符串，不转 Number
+const id = detail.vehicleIdBefore;  // String，保持精度
+// ❌ 禁止转数字
+const id = Number(detail.vehicleIdBefore);  // 末位被四舍五入
+```
+
+---
+
+## 五、数据库行为
+
+| 场景 | 数据库表 | 操作 |
+|------|----------|------|
+| 软清执行 | `fleet_assignment` | UPDATE `driver_id = null, vehicle_id = null` 等字段 |
+| 软清写口 | `fleet_assignment_operation_log` | INSERT 一行，`operation_type = 'soft_cleared'`，`detail_json` 记录清空前的身份 |
+
+---
+
+## 六、边界行为
+
+- **订单不存在** → 404
+- **分页参数超范围** → 400（pageSize > 200 或 page > 100000）
+- **无鉴权** → 401（网关拦截）
+- **权限不足** → 403（非车务/管理员）
+- **sortBy 值非法** → 忽略，使用默认倒序
+- **历史数据**：该接口返回的是操作日志的完整历史，不因本次变更而改变已有记录；本次新增的 `soft_cleared` 仅出现在 2026-09-21 18:43 之后发生的清空操作
+
+---
+
+## 六.5、枚举 / 数据字典
+
+### operation_type 枚举（`AssignmentOperationTypeEnum`）
+
+**所属字段**: `FleetOperationLogItemVO.opType` | **类型**: `String`
+
+新增值：
+
+| 值 | 中文标签 | 说明 |
+|----|----------|------|
+| `soft_cleared` | 清空司机/车辆 | 车务手动清空派车行的车辆/司机字段，状态置回待改派 |
+
+现有值（不含全列表，仅示例）：
+
+| 值 | 中文标签 | 说明 |
+|----|----------|------|
+| `assignment_created` | 新建派单 | 订单新建派单时 |
+| `change_completed` | 修改派单完成 | 改派操作完成 |
+| `share_release_cleared` | 共用关系解除释放占用 | 共用关系解除时，共用组成员释放占用（#8061 新增） |
+| `confirmed` | 确认执行 | 司机确认执行派单 |
+| `completed` | 完结派单 | 派单完成 |
+
+---
+
+## 六.6、修改前后对比
+
+### 响应字段级对比
+
+| 字段 | 改前 | 改后 | 备注 |
+|------|------|------|------|
+| `records[].opType` | 不含 `soft_cleared` | 新增 `soft_cleared` | 前端若按白名单过滤需要加入 |
+| `records[].detailJson` | 已有其他操作类型的内容 | 新增 `soft_cleared` 时的 detail_json 结构 | 当 opType 为 `soft_cleared` 时，detailJson 包含 scope/statusBefore/vehicleIdBefore 等字段 |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| 软清留痕 | 派车行直接清空，无操作日志 | 调用软清写口时同步在 `fleet_assignment_operation_log` 写一行，记录被清空前的车/司机 |
+| 时间线查询 | 软清操作不可见 | 软清操作以 `soft_cleared` 行显示在时间线中 |
+| 事后取证 | 无法查证谁清了、清掉了谁 | `detail_json` 中记录清空前的 vehicleId/driverId 快照，支持事后追溯 |
+
+---
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 否
+  - 新增操作类型 `soft_cleared` 不影响既有操作类型的解析
+  - 响应字段无删除，仅新增返回内容
+
+- **前端是否必须同步上线**: 否（但需适配白名单过滤）
+  - 后端接口变更无必须的前端代码改动
+  - **但是**：如果前端在渲染时间线时对 `operation_type` 做了白名单过滤，白名单中**必须加入 `soft_cleared`**，否则该操作会静默漏渲染
+
+- **前端 workaround 清理点**:
+  - 若有硬编码的 operation_type 白名单（例如 `['assignment_created', 'change_completed', ...]`），需补充 `'soft_cleared'`
+  - 若用了枚举常量或字典，确保后台下发的字典已包含 `soft_cleared` 标签
+
+---
+
+## 七、不影响范围
+
+- **仅影响**：派单操作时间线接口 `/admin/fleet/orders/{orderId}/operation-log` 的响应内容
+- **零影响**：
+  - 派车创建/改派/确认等业务流程
+  - 订单详情接口
+  - 派车行状态字段（清空行为本身不变，仍是直接 UPDATE 派车表）
+  - 其他模块的操作日志接口（如房务）
+  - 前端派车列表/派车详情等其他功能模块
+
+---
+
+## 八、测试环境已验证
+
+测试服 `hl-fleet-service` 版本 `dev-v3@9f6443de4`（2026-09-21 18:46 部署，STATE=ok）
+
+实测验证（订单 `2085539421276286978`、派车行已清空）：
+
+```
+GET /admin/fleet/orders/2085539421276286978/operation-log?page=1&pageSize=50
+  ↓
+200 OK
+
+响应中 records[0]:
+  {
+    "opType": "soft_cleared",
+    "opTypeLabel": "清空司机/车辆",
+    "operatorName": "王信",
+    "time": "2026-09-21T18:45:32",
+    "detailJson": "{\"scope\":\"GROUP\",\"assignmentGroupId\":\"360380081354444801\",\"statusBefore\":\"assigned\",\"vehicleIdBefore\":\"2085539421276286978\",\"driverIdBefore\":\"2067084362829979650\",\"vehiclePlateSnapshot\":\"蒙A-E2E99\",\"driverNameSnapshot\":\"王信\", ...}",
+    ...
+  }
+  ✓ opType 正确为 soft_cleared
+  ✓ detailJson 包含清空前的 vehicleId/driverId（字符串格式）
+  ✓ 快照字段 vehiclePlateSnapshot/driverNameSnapshot 可读
+```
+
+---
+
+## 九、特别说明：共用关系解除时的双行记录
+
+共用关系解除（#8061）会在同一次操作中产生**两条连续的操作日志**：
+
+1. **`share_release_cleared`** — 由共用关系解除的调用点写，答「哪个共用关系、解除原因、采用何种幸存者策略」
+   - `detail_json` 含 `shareGroupId` / `releaseReason` / `survivorPolicy` / `vehicleIdBefore` 等字段
+
+2. **`soft_cleared`** — 由软清写口本身写，答「派车行被清了、清前是什么」（本次新增）
+   - `detail_json` 含 `scope` / `statusBefore` / `vehicleIdBefore` / `driverIdBefore` / `clearedRows` 等字段
+
+**这不是重复数据**——两行记的是同一次操作的不同侧面，各自的 `detail_json` 内容完全不同，都有独特的业务含义。前端在渲染时间线时需要正确识别两种类型，包括在任何过滤/搜索逻辑中都要同时考虑这两个 operation_type。
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#8068](https://git.1814.love:8443/wx/HL/issues/8068)
+- 关联 PR: [wx/HL#8113](https://git.1814.love:8443/wx/HL/pulls/8113)
+- 相关工单: [#8061](https://git.1814.love:8443/wx/HL/issues/8061)（共用关系解除），[#8051](https://git.1814.love:8443/wx/HL/issues/8051)（库内取证需求）
+
+---
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8068](https://git.1814.love:8443/wx/HL/issues/8068)
+- **PR**: [#8113](https://git.1814.love:8443/wx/HL/pulls/8113)
+- **Merge commit**: [9f6443de4](https://git.1814.love:8443/wx/HL/commit/9f6443de4)
+
+### 联系人
+
+- **后端负责人**: @wx
@@ -0,0 +1,361 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8086"
+title: "餐食不关联餐厅时餐厅名返回 null，分页按餐厅排序"
+consumer: "admin"
+author: "lc(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "780b8e76b7ec8a04f4746739c750215e5d5db577"
+target_release: ""
+verified_at: "2026-09-21"
+status_note: "餐食出参 restaurantName 不再对不关联餐厅的餐食返回「全部」，改为 null（分页、下拉、详情一致）；餐食分页顺序改为按餐厅建档先后归并、组内创建时间倒序、不关联餐厅的排最后。前端需按本文对接。前端已交付(mmg 2026-09-21, hl-admin 780b8e76):餐食管理列表餐厅列按 restaurantId null 自渲染「全部」(关联但餐厅已删、name null 仍显 -);订单「用餐」页签餐食下拉候选标签去掉对「全部」文案的特判(只按有无 restaurantName 拼后缀);编辑弹窗回显因按 restaurantId 守门实证零改动;分页顺序改后端固定,前端无排序参数零改动。index 9 例+EditModal 8 例+MealTab 13 例全过,checkpoint 全项通过。"
+updated_at: "2026-09-21"
+base: "dev-v3"
+---
+
+# resource: 餐食不关联餐厅时餐厅名返回 null，分页按餐厅排序
+
+> **服务**: hl-resource-service
+> **PR**: #8090
+> **Issue**: #8086
+> **日期**: 2026-09-21
+> **影响范围**: 管理后台「餐食管理」分页、下拉、详情 3 个读接口
+
+---
+
+## ⚠️ 关键变化
+
+- 🔁 **`restaurantName` 不再返回「全部」**：不关联餐厅的餐食，`restaurantName` 由 `"全部"` 改为 `null`；`restaurantId` 仍为 `null`。分页、下拉、详情三个接口口径一致。页面上要显示「全部」由前端在 `restaurantId` 为 `null` 时自行展示。
+- 🔁 **分页顺序变了**：`GET /admin/dish/items/page` 由「更新时间倒序」改为「按餐厅建档先后归并 → 同一餐厅内创建时间倒序 → 不关联餐厅的整组排最后」。改过的餐食不再被顶到列表最前。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|---|---|---|---|---|
+| 1 | 分页查询餐食 | GET | `/admin/dish/items/page` | 修改 | 出参 `restaurantName` 取值变化；返回顺序变化 |
+| 2 | 餐食下拉列表 | GET | `/admin/dish/items/list` | 修改 | 出参 `restaurantName` 取值变化；顺序不变 |
+| 3 | 餐食详情 | GET | `/admin/dish/items/{dishId}/view` | 修改 | 出参 `restaurantName` 取值变化 |
+
+---
+
+## 三、接口详情
+
+出参 `restaurantName` 的取值口径三个接口完全一致，下表对三处都适用：
+
+| 情况 | `restaurantId` | 改动前 `restaurantName` | 改动后 `restaurantName` |
+|---|---|---|---|
+| 餐食不关联餐厅 | `null` | `"全部"` | `null` |
+| 关联餐厅，餐厅正常 | 餐厅 ID | 餐厅名称 | 餐厅名称（不变） |
+| 关联餐厅，餐厅已删除/查不到 | 餐厅 ID | `null` | `null`（不变） |
+
+### 1. 分页查询餐食 `GET /admin/dish/items/page`
+
+**VO**: `DishPageReqVO` → `PageResult<DishListItemRespVO>`
+
+#### 使用场景
+
+管理后台「餐食管理」列表页。
+
+#### 入参字段表
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| 全部入参 | Query | — | — | — | `page`、`pageSize`、`keyword`、`status`、`settleType`、`createdByName` 均不变，本次不新增、不删除入参 |
+
+不支持自定义排序参数，顺序由后端固定。
+
+#### 出参字段表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| records[].restaurantId | String | 餐厅 ID；不关联餐厅为 `null`（不变） |
+| records[].restaurantName | String | **取值变化**。按上表：不关联餐厅由 `"全部"` 改为 `null` |
+| records[] 其余字段 | — | `dishId`、`dishName`、`unitPrice`、`priceUnit`、`imageUrl`、`settleType`、`status`、`remark`、`createdBy`、`createdByName`、`createdAt` 均不变 |
+| total / page / pageSize | — | 不变 |
+
+**返回顺序变化**，排序键依次为：不关联餐厅的排最后 → 餐厅建档先后（餐厅 ID 升序）→ 同一餐厅内创建时间倒序 → 餐食 ID 倒序。改动前是「更新时间倒序、餐食 ID 倒序」。
+
+```
+餐厅甲（建档最早）  其下餐食按创建时间倒序
+餐厅乙              其下餐食按创建时间倒序
+…
+不关联餐厅的餐食     按创建时间倒序，整组排在最后
+```
+
+#### 请求示例
+
+```http
+GET /admin/dish/items/page?page=1&pageSize=20
+Authorization: Bearer <admin token>
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "success": true,
+  "data": {
+    "total": 32,
+    "page": 1,
+    "pageSize": 20,
+    "records": [
+      {
+        "dishId": "2100978382416141313",
+        "restaurantId": "2023382100664676353",
+        "restaurantName": "菌香园火锅",
+        "dishName": "儿童餐",
+        "unitPrice": 25.00,
+        "priceUnit": "person",
+        "settleType": "cash",
+        "status": 1,
+        "createdAt": "2026-09-19 00:00:38"
+      },
+      {
+        "dishId": "2101571815203901441",
+        "restaurantId": null,
+        "restaurantName": null,
+        "dishName": "全顺车队-特供",
+        "unitPrice": 200.00,
+        "priceUnit": "person",
+        "settleType": "cash",
+        "status": 1,
+        "createdAt": "2026-09-20 15:19:01"
+      }
+    ]
+  }
+}
+```
+
+#### 空数据 / 降级响应
+
+`records` 为 `[]`、`total` 为 `0`：筛选条件没命中任何未删除餐食。
+
+#### 错误响应
+
+```json
+{ "code": 400, "message": "每页条数最大为100", "success": false, "data": null }
+```
+
+#### 业务边界
+
+- 翻页按同一顺序切分，不会出现跨页重复或遗漏。
+- 餐厅被删除后，其下餐食仍按原餐厅的位置排序，不会跑到末尾；末尾只放 `restaurantId` 为 `null` 的餐食。
+- 同一餐厅内创建时间相同的餐食，按餐食 ID 倒序稳定排列。
+- 餐食被修改后不再被顶到列表最前（排序基准由更新时间改为创建时间）。
+
+### 2. 餐食下拉列表 `GET /admin/dish/items/list`
+
+**VO**: `DishListReqVO` → `List<DishListItemRespVO>`
+
+#### 使用场景
+
+餐食下拉数据源。
+
+#### 入参字段表
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| 全部入参 | Query | — | — | — | `restaurantId`、`keyword`、`settleType`、`limit` 均不变，本次不新增、不删除入参 |
+
+#### 出参字段表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| [].restaurantName | String | **取值变化**。按上表：不关联餐厅由 `"全部"` 改为 `null` |
+| [] 其余字段 | — | 均不变 |
+
+返回顺序（创建时间升序、餐食 ID 升序）与条数上限不变。
+
+#### 请求示例
+
+```http
+GET /admin/dish/items/list?limit=50
+Authorization: Bearer <admin token>
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "success": true,
+  "data": [
+    {
+      "dishId": "2100767758525329410",
+      "restaurantId": null,
+      "restaurantName": null,
+      "dishName": "GL8车队-特供",
+      "unitPrice": 99999999.99,
+      "priceUnit": "person",
+      "settleType": "company",
+      "status": 1,
+      "createdAt": "2026-09-18 10:03:59"
+    }
+  ]
+}
+```
+
+#### 空数据 / 降级响应
+
+`data` 为 `[]`：按当前条件没有上架餐食。
+
+#### 错误响应
+
+```json
+{ "code": 400, "message": "limit最大为200", "success": false, "data": null }
+```
+
+#### 业务边界
+
+- 本次只改 `restaurantName` 取值，不改该接口返回哪些行、返回顺序与条数上限。
+- 下架、已删除的餐食任何情况下都不返回。
+
+### 3. 餐食详情 `GET /admin/dish/items/{dishId}/view`
+
+**VO**: `Long dishId` → `DishRespVO`
+
+#### 使用场景
+
+「餐食管理」列表点开编辑时回显单条餐食。
+
+#### 入参字段表
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| dishId | Path | String | 是 | 雪花 ID | 餐食 ID（不变） |
+
+#### 出参字段表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| restaurantName | String | **取值变化**。按上表：不关联餐厅由 `"全部"` 改为 `null` |
+| 其余字段 | — | 与分页 `records[]` 相同，均不变 |
+
+#### 请求示例
+
+```http
+GET /admin/dish/items/2101571815203901441/view
+Authorization: Bearer <admin token>
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "success": true,
+  "data": {
+    "dishId": "2101571815203901441",
+    "restaurantId": null,
+    "restaurantName": null,
+    "dishName": "全顺车队-特供",
+    "unitPrice": 200.00,
+    "priceUnit": "person",
+    "settleType": "cash",
+    "status": 1,
+    "createdAt": "2026-09-20 15:19:01"
+  }
+}
+```
+
+#### 空数据 / 降级响应
+
+不存在空数据形态；餐食不存在或已删除时走错误响应。
+
+#### 错误响应
+
+```json
+{ "code": 340001, "message": "餐食不存在", "success": false, "data": null }
+```
+
+#### 业务边界
+
+- 回显时 `restaurantId` 为 `null` 即该餐食不关联具体餐厅；`restaurantName` 同为 `null`，不再下发「全部」文案。
+
+---
+
+## 四、契约约束与正确调用方式
+
+- 判断一条餐食「有没有餐厅」只看 `restaurantId` 是否为 `null`，不要再用 `restaurantName === "全部"` 判断。
+- 页面需要显示「全部」字样时，前端在 `restaurantId` 为 `null` 时自行渲染；后端不再下发该文案。
+- 入参不变：新建、修改餐食时不传 `restaurantId` 仍表示该餐食不关联具体餐厅。
+- 分页不支持自定义排序参数，顺序由后端固定。
+- 「全部」仍是业务上的一类（不关联具体餐厅的餐食），同期 #8087 的餐食下拉按餐厅联动沿用该语义；本次只是后端不再把「全部」作为 `restaurantName` 的值下发。
+
+---
+
+## 六、边界行为
+
+- 餐厅被删除后，其下餐食的 `restaurantName` 为 `null`、`restaurantId` 仍返回原值；该餐食仍按原餐厅的位置排序，不会跑到末尾（末尾只放 `restaurantId` 为 `null` 的餐食）。
+- 同一餐厅内创建时间相同的餐食，按餐食 ID 倒序稳定排列。
+
+---
+
+## 六.6、修改前后对比
+
+| 项 | 改动前 | 改动后 |
+|---|---|---|
+| 不关联餐厅的 `restaurantName` | `"全部"` | `null` |
+| 分页排序 | `更新时间倒序, 餐食ID倒序` | `不关联餐厅排最后, 餐厅建档先后, 创建时间倒序, 餐食ID倒序` |
+| 下拉、详情排序与其他字段 | — | 不变 |
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 是（依赖 `restaurantName === "全部"` 的前端判断会失效；列表顺序改变）
+- **前端是否必须同步上线**: 是，按本文改判断条件与「全部」文案渲染
+- **前端 workaround 清理点**: 去掉对 `restaurantName` 取值 `"全部"` 的依赖
+
+## 七、不影响范围
+
+- **仅影响**: 餐食分页、下拉、详情 3 个读接口的 `restaurantName` 取值，以及分页返回顺序
+- **零影响**:
+  - 餐食新建 `POST /admin/dish/items/add`、修改 `PUT /admin/dish/items/{dishId}/update`、上下架、删除接口与其入参校验
+  - 餐食其余出参字段、分页筛选条件、错误码
+  - 下拉与详情的返回顺序
+  - 餐厅管理接口与 `restaurant` 表
+
+---
+
+## 八、测试环境已验证
+
+部署提交 `3dcbaabef`，经 Gateway 用真实 TEST 身份实测 16 项全部通过：
+
+```
+分页 32 条中 20 条不关联餐厅            → restaurantName 全为 null ✓
+分页 32 条中 12 条关联餐厅              → 仍返回餐厅名称 ✓
+分页整体顺序                            → 不关联餐厅排最后 + 餐厅建档先后 + 组内创建时间倒序 + 餐食ID倒序 ✓
+4 家餐厅的分组先后                      → 菌香园火锅 → 苏日姥爷蒙餐融合菜 → 七间房全羊馆 → 九牧羊鲜羊火锅 ✓
+不关联餐厅的 20 条                      → 整组排在最后，组内创建时间倒序 ✓
+pageSize=10 逐页拼接                    → 与一次取回 50 条的顺序完全一致，不重复不遗漏 ✓
+详情（不关联餐厅 / 关联餐厅各一条）      → null / 餐厅名称 ✓
+下拉 9 条                               → restaurantName 全为 null，顺序与本次改动前完全一致 ✓
+```
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#8086](https://git.1814.love:8443/wx/HL/issues/8086)
+- 关联 PR: [wx/HL#8090](https://git.1814.love:8443/wx/HL/pulls/8090)
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8086](https://git.1814.love:8443/wx/HL/issues/8086)
+- **PR**: [wx/HL#8090](https://git.1814.love:8443/wx/HL/pulls/8090)
+- **Merge commit**: [3dcbaabef](https://git.1814.love:8443/wx/HL/commit/3dcbaabef8384ec42238b051dbbdd6a8d8e48054)
+
+### 联系人
+
+- 后端: @lc
@@ -7,9 +7,9 @@ author: "lc(GIT)"
 change_type: "修改接口"
 backend_status: "deployed"
 gateway_status: "verified"
-frontend_status: "pending"
-frontend_owner: ""
-frontend_ref: ""
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "233de7be087d164a5033ebaa61d85bf1fad378cd"
 target_release: ""
 verified_at: "2026-09-21"
 status_note: "餐食下拉 GET /admin/dish/items/list 新增可选入参 restaurantId，并改变默认口径：不传只返回餐厅为「全部」（restaurantId 为 null）的上架餐食，传了只返回该餐厅的上架餐食。前端在订单详情「用餐」页签的餐食下拉需按该行选中的餐厅传 restaurantId；没选餐厅时不传。出参字段、排序与条数上限不变。"
@@ -33,7 +33,7 @@ base: "dev-v3"

 🆕 **新增可选入参 `restaurantId`**：传了只返回该餐厅的上架餐食。

-**前端需要改**：订单详情「用餐」页签的餐食下拉，按该行当前选中的餐厅传 `restaurantId`；没选餐厅时不传该参数。切换餐厅后重新调用本接口即可拿到联动后的候选。
+**前端需要改**：订单详情「用餐」页签的餐食下拉，按该行当前选中的餐厅传 `restaurantId`；没选餐厅时不传该参数。切换餐厅后重新调用本接口即可拿到联动后的候选。前端已交付(mmg 2026-09-21, hl-admin 233de7be):订单详情「用餐」页签 MealTab 餐食下拉按行内选中餐厅传 restaurantId(未选不带,即「全部」口径);候选为共享单列表,scopeKey 记录本批候选的餐厅口径,聚焦时与行内餐厅不一致即按该行重查,搜索关键词随行餐厅一并上送;已选中行靠选中标签回显兜底,不受共享列表换口径影响。MealTab 13 例(新增联动 2 例)+dish api 8 例全过,checkpoint 全项通过。交付后修复(mmg 2026-09-21, hl-admin 07dfe636,用户实测反馈):①餐厅清除/更换时清空该行已选餐食(单价保留),回到新口径重选,避免存出「餐厅A餐食+餐厅B/无餐厅」的不一致行;②餐食/餐厅下拉取候选的 loading 圈改为只显当前操作行(候选是共享单状态,此前所有行下拉一起转圈)。MealTab 15 例全过。二次修复(mmg 2026-09-21, hl-admin f9b4ef7c):取候选触发页面级全局遮罩(request.js 普通请求默认 showLoading),getDishList/getRestaurantResourceOptions 默认 showLoading:false,加载反馈回到下拉框自身 loading;全部调用方(MealTab/餐食编辑弹窗/结算餐厅选项)同类一并清零。dish 8 例+resource-options 5 例+MealTab 15 例全过。

 ---

@@ -0,0 +1,479 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8093"
+title: "套用用餐模版改为只读返回组合结果，模版加桌数人数与创建人、模糊搜索与删除"
+consumer: "admin"
+author: "lc(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "74eacd7a992d276e438b2e9f55b38e3924d5fe0c"
+target_release: "v2.1"
+verified_at: "2026-09-21"
+status_note: "套用用餐模版由写库改为只读：只返回「模版+订单出发日」组合出来的行，不含订单原有行、库里一行不动；订单原有行由前端把这些行原样提交整单保存时按现有规则软删。行上人数、桌数、价钱、桌/人、金额后端已算好。模版列表新增创建人姓名与行上桌数、人数、桌/人；模版名由精确改模糊并新增创建人模糊搜索；新增删除模版接口。前端必须按本文改调用方式。 前端 2026-09-21 已交付(hl-admin v2.1 74eacd7a9):MealTab 套用改只读预览——只把回包 mealInfoId=null 的模版行追加进本地列表(不清空/不只提交模版行),保存走整单提交入库;MealTemplateApplyModal 加双模糊搜索/创建人/桌人列/删除模版;checkpoint 全量绿。（与 #8125 合并一个交付单元）"
+updated_at: "2026-09-21"
+base: "dev-v3"
+---
+
+# order-v3: 套用用餐模版改为只读返回组合结果，模版加桌数人数与创建人、模糊搜索与删除
+
+> **服务**: hl-order-service-v3
+> **PR**: #8105
+> **Issue**: #8093
+> **日期**: 2026-09-21
+> **影响范围**: 管理后台订单详情「用餐」页签的套用模版与模版列表；新增删除模版
+
+---
+
+## ⚠️ 关键变化
+
+- 🔁 **套用模版不再写库（破坏性）**：`POST /v3/admin/order/meal-template/apply` 由写接口变为只读接口。调用它**不会**把模版内容存进订单，返回里也**不再包含**这张订单原来的用餐行，只返回「模版 + 订单出发日」组合出来的行。原来的行要等前端把这些行**原样提交整单保存**（`POST /v3/admin/order/meal-info/save`）时，才按现有「原来有而这次没传上来的软删」规则去掉。**前端如果沿用「套用成功后重新查一次列表就当保存好了」的做法，用户的套用结果不会入库。**
+- ✅ **套用返回的行后端已算好**：人数、桌数、价钱、桌/人、金额都由后端给出，免人数 / 免金额 / 其他成本为 0，前端直接展示，不需要再算金额。
+- 🆕 **套用返回的行新增 `priceUnit`（桌/人）**：由桌数是否为 0 派生，取值 `person` / `table`，不存库。3.1–3.4 的行**没有**这个字段。
+- 🔁 **模版名搜索由精确改为模糊**：`templateName` 改为「包含即命中」。原来传全名的调用仍能命中，但会一并带出名称含该串的其他模版。
+- 🆕 **模版列表新增创建人**：模版级新增 `creatorName`（中文姓名），并新增同名入参按创建人模糊搜索。
+- 🆕 **新增删除模版接口** `POST /v3/admin/order/meal-template/delete`。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|---|---|---|---|---|
+| 1 | 套用用餐模版 | POST | `/v3/admin/order/meal-template/apply` | 修改 | 由写库改为只读；返回内容变化；行上新增 `priceUnit` |
+| 2 | 查询用餐模版 | GET | `/v3/admin/order/meal-template/list` | 修改 | 新增入参 `creatorName`；`templateName` 改模糊；出参新增 `creatorName` 与行上 `tableCount`/`personCount`/`priceUnit` |
+| 3 | 保存为用餐模版 | POST | `/v3/admin/order/meal-template/save` | 修改 | 入参不变；模版一并存下源用餐行的桌数、人数；出参行新增上述三个字段 |
+| 4 | 删除用餐模版 | POST | `/v3/admin/order/meal-template/delete` | 新增 | 按模版ID软删该模版全部行 |
+
+3.1 查询、3.2 生成、3.3 整单保存、3.4 重置的入参与出参**一个字段都没变**。
+
+---
+
+## 三、接口详情
+
+### 1. 套用用餐模版 `POST /v3/admin/order/meal-template/apply`
+
+**VO**: `MealTemplateApplyReqVO` → `OrderMealInfoListRespVO`
+
+#### 使用场景
+
+订单详情「用餐」页签点「套用模版」，把某个模版的内容按订单出发日铺开，**展示给用户预览**；用户确认后再点保存。
+
+#### 入参字段表
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| orderId | Body | String | 是 | 雪花 ID | 订单 ID（不变） |
+| templateId | Body | String | 是 | 雪花 ID | 模版 ID（不变） |
+
+#### 出参字段表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| items | Array | **内容变化**。只含这个模版套出来的行，**不含**该订单原来的用餐行 |
+| items[].mealInfoId | String | **恒为 `null`**：这些行还没入库 |
+| items[].dayNumber | Integer | 模版的第几日 |
+| items[].mealDate | String | 订单出发日 + dayNumber − 1（出发日是第 1 日） |
+| items[].restaurantId / restaurantName / dishId / dishName / unitPrice / settleType / settleTypeName | — | 取模版，原样返回 |
+| items[].tableCount | Integer | **后端算好**。取模版的桌数 |
+| items[].personCount | Integer | **后端算好**。桌数为 0（按人）取订单人数；桌数不为 0（按桌）为 0 |
+| items[].priceUnit | String | **新增**。`person`（桌数为 0）/ `table`（桌数不为 0），派生值，不存库 |
+| items[].freePersonCount / freeAmount / otherCost | — | **恒为 0** |
+| items[].amount | Number | **后端算好**。按人 = 单价 ×（人数 − 免人数）− 免金额 + 其他成本；按桌 = 单价 × 桌数 − 免金额 + 其他成本 |
+| totalAmount | Number | 本次返回各行金额之和 |
+| orderId / groupBatchId / batchNo / departDate / returnDate / personCount / orderEditable / generated | — | 口径与 3.1 相同，未变 |
+
+#### 请求示例
+
+```http
+POST /v3/admin/order/meal-template/apply
+Authorization: Bearer <admin token>
+Content-Type: application/json
+
+{ "orderId": "2101846199160188929", "templateId": "2101952572174860290" }
+```
+
+#### 响应示例
+
+订单出发日 `2026-11-10`、订单人数 2，模版 3 行（早餐默认行、午餐按人 30 元、晚餐按桌 888 元 × 2 桌）：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "success": true,
+  "data": {
+    "orderId": "2101846199160188929",
+    "departDate": "2026-11-10",
+    "personCount": 2,
+    "orderEditable": true,
+    "generated": true,
+    "totalAmount": 1836.00,
+    "items": [
+      {
+        "mealInfoId": null,
+        "mealType": "BREAKFAST", "dayNumber": 1, "mealDate": "2026-11-10",
+        "restaurantName": "HL8093-TEST-默认餐厅", "dishName": "HL8093-TEST-默认餐",
+        "unitPrice": 0.00, "tableCount": 0, "personCount": 2, "priceUnit": "person",
+        "freePersonCount": 0, "freeAmount": 0.00, "otherCost": 0.00, "amount": 0.00
+      },
+      {
+        "mealInfoId": null,
+        "mealType": "LUNCH", "dayNumber": 1, "mealDate": "2026-11-10",
+        "restaurantName": "HL8093-TEST-按人餐厅", "dishName": "HL8093-TEST-按人餐",
+        "unitPrice": 30.00, "tableCount": 0, "personCount": 2, "priceUnit": "person",
+        "freePersonCount": 0, "freeAmount": 0.00, "otherCost": 0.00, "amount": 60.00,
+        "settleType": "sign", "settleTypeName": "签单"
+      },
+      {
+        "mealInfoId": null,
+        "mealType": "DINNER", "dayNumber": 1, "mealDate": "2026-11-10",
+        "restaurantName": "HL8093-TEST-按桌餐厅", "dishName": "HL8093-TEST-按桌餐",
+        "unitPrice": 888.00, "tableCount": 2, "personCount": 0, "priceUnit": "table",
+        "freePersonCount": 0, "freeAmount": 0.00, "otherCost": 0.00, "amount": 1776.00,
+        "settleType": "cash", "settleTypeName": "现付"
+      }
+    ]
+  }
+}
+```
+
+#### 空数据 / 降级响应
+
+- 模版一行都没有：`items` 为 `[]`、`totalAmount` 为 `0.00`，`code` 仍为 200。
+- 订单没有出发日期：无法对天，`items` 为 `[]`，`code` 200，`message` 为「订单缺少出发日期」提示（589602 文案）。
+
+#### 错误响应
+
+```json
+{ "code": 589607, "message": "订单已完成或已取消，不能修改用餐信息", "success": false, "data": null }
+```
+
+订单不可写按 581045 / 581008；订单不存在按订单模块现有错误码。这些判断与改动前一致。
+
+#### 业务边界
+
+- **调用套用不改库**：调用前后用 3.1 按该订单查询，返回逐字段完全一致。
+- 模版第 d 日超出订单行程天数时不做限制，照落在出发日 + d − 1。
+- 模版值原样带出，不核对餐食、餐厅是否还存在或已下架。
+
+### 2. 查询用餐模版 `GET /v3/admin/order/meal-template/list`
+
+**VO**: `MealTemplateListReqVO` → `List<MealTemplateRespVO>`
+
+#### 使用场景
+
+「套用模版」弹层里选模版，支持按模版名、创建人搜索。
+
+#### 入参字段表
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| templateId | Query | String | 否 | 雪花 ID | 精确查；**传了就忽略下面两个条件** |
+| templateName | Query | String | 否 | ≤ 500 字符 | **由精确匹配改为模糊匹配**（包含即命中） |
+| creatorName | Query | String | 否 | ≤ 100 字符 | **新增**。按创建人中文姓名模糊匹配（包含即命中，忽略大小写） |
+
+组合口径：`templateName` 与 `creatorName` 同传取**同时满足**的模版；只传一个按该条件筛；都不传返回全部；传 `templateId` 时按 ID 精确查且不受这两个条件影响。
+
+#### 出参字段表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| [].templateId / templateName | — | 不变 |
+| [].creatorName | String | **新增**。创建人中文姓名：企微姓名，没绑企微取登录名；取不到时为 `null` |
+| [].items[].tableCount | Integer | **新增**。桌数，0 表示按人算 |
+| [].items[].personCount | Integer | **新增**。人数（模版内容回显用） |
+| [].items[].priceUnit | String | **新增**。`person` / `table`，由桌数派生，不存库 |
+| [].items[] 其余字段 | — | `restaurantId`、`restaurantName`、`dishId`、`dishCode`、`dishName`、`mealType`、`dayNumber`、`unitPrice`、`settleType`、`settleTypeName` 均不变 |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/meal-template/list?templateName=HL8093&creatorName=%E5%88%98
+Authorization: Bearer <admin token>
+```
+
+`creatorName` 是中文时必须按 URL 编码传。
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "success": true,
+  "data": [
+    {
+      "templateId": "2101952572174860290",
+      "templateName": "HL8093-TEST-桌人模版",
+      "creatorName": "刘畅",
+      "items": [
+        {
+          "mealType": "LUNCH", "dayNumber": 1,
+          "restaurantName": "HL8093-TEST-按人餐厅", "dishName": "HL8093-TEST-按人餐",
+          "unitPrice": 30.00, "tableCount": 0, "personCount": 4, "priceUnit": "person",
+          "settleType": "sign", "settleTypeName": "签单"
+        },
+        {
+          "mealType": "DINNER", "dayNumber": 1,
+          "restaurantName": "HL8093-TEST-按桌餐厅", "dishName": "HL8093-TEST-按桌餐",
+          "unitPrice": 888.00, "tableCount": 2, "personCount": 0, "priceUnit": "table",
+          "settleType": "cash", "settleTypeName": "现付"
+        }
+      ]
+    }
+  ]
+}
+```
+
+#### 空数据 / 降级响应
+
+- `data` 为 `[]`：没有同时满足条件的模版。
+- 用户服务取不到姓名时，该模版 `creatorName` 为 `null`，列表照常返回；此时若传了 `creatorName` 条件，该模版不会被返回。
+
+#### 错误响应
+
+```json
+{ "code": 400, "message": "创建人姓名最多100字符", "success": false, "data": null }
+```
+
+#### 业务边界
+
+- 按模版 ID 分组，重名的是各自独立的模版；列表按模版 ID 升序（保存先后）。
+- 模版名片段里的 `%`、`_` 已做转义，不会被当通配符放大匹配范围。
+
+### 3. 保存为用餐模版 `POST /v3/admin/order/meal-template/save`
+
+**VO**: `MealTemplateSaveReqVO` → `MealTemplateRespVO`
+
+#### 使用场景
+
+订单详情「用餐」页签上把当前排好的用餐行「保存为模版」，供以后套到别的订单上。
+
+#### 入参字段表
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| templateName | Body | String | 是 | ≤ 500 字符 | 不变 |
+| mealInfoIds | Body | Array | 是 | 非空 | 不变 |
+
+**入参没有变化**，前端不需要多传字段。
+
+#### 出参字段表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| creatorName | String | **新增**。当前操作人的中文姓名 |
+| items[].tableCount / personCount / priceUnit | — | **新增**，口径同 4.1 |
+| templateId / templateName / items[] 其余字段 | — | 不变 |
+
+#### 请求示例
+
+```http
+POST /v3/admin/order/meal-template/save
+Authorization: Bearer <admin token>
+Content-Type: application/json
+
+{ "templateName": "HL8093-TEST-桌人模版", "mealInfoIds": ["2101952551211728898", "2101952551157202945"] }
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "success": true,
+  "data": {
+    "templateId": "2101952572174860290",
+    "templateName": "HL8093-TEST-桌人模版",
+    "creatorName": "刘畅",
+    "items": [
+      {
+        "mealType": "DINNER", "dayNumber": 1,
+        "restaurantName": "HL8093-TEST-按桌餐厅", "dishName": "HL8093-TEST-按桌餐",
+        "unitPrice": 888.00, "tableCount": 2, "personCount": 0, "priceUnit": "table",
+        "settleType": "cash", "settleTypeName": "现付"
+      }
+    ]
+  }
+}
+```
+
+#### 空数据 / 降级响应
+
+不存在空数据形态：`mealInfoIds` 一行都取不到时走错误响应（589606）。企微姓名取不到时 `creatorName` 为 `null`，模版照常保存成功。
+
+#### 错误响应
+
+```json
+{ "code": 589606, "message": "没有可保存为模版的用餐信息", "success": false, "data": null }
+```
+
+#### 业务边界
+
+- 模版现在会一并存下源用餐行的**桌数、人数**；改动前不存，所以**已有的老模版这两项都是 0**（等同「按人算、人数未知」），套用时按人的行人数仍取订单人数，金额不受影响。
+- 每次保存生成新的模版 ID，不覆盖已有模版。
+
+### 4. 删除用餐模版 `POST /v3/admin/order/meal-template/delete`
+
+**VO**: `MealTemplateDeleteReqVO` → `Result<Void>`
+
+#### 使用场景
+
+模版列表上删除某个模版。
+
+#### 入参字段表
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| templateId | Body | String | 是 | 雪花 ID | 要删除的模版 ID |
+
+#### 请求示例
+
+```http
+POST /v3/admin/order/meal-template/delete
+Authorization: Bearer <admin token>
+Content-Type: application/json
+
+{ "templateId": "2101953000000000001" }
+```
+
+#### 出参字段表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| code | Integer | `200` 表示删除成功；模版不存在或已删除同样返回 `200` |
+| data | null | 恒为 `null`，该接口不返回业务数据 |
+
+#### 响应示例
+
+```json
+{ "code": 200, "message": "成功", "success": true, "data": null }
+```
+
+#### 空数据 / 降级响应
+
+不存在空数据形态：`data` 恒为 `null`。删除一个不存在或已删除的模版属于正常成功路径，不是降级，`code` 仍为 `200`。
+
+#### 错误响应
+
+```json
+{ "code": 400, "message": "模版ID不能为空", "success": false, "data": null }
+```
+
+#### 业务边界
+
+- **幂等**：模版不存在或已经删过，同样返回成功，前端不需要处理「已删除」的失败分支。
+- 软删该模版的全部行；**已经保存到订单上的用餐行不受影响**。
+- 权限门槛与查询、保存一致（房务 / 组长角色 581045）。
+
+---
+
+## 四、契约约束与正确调用方式
+
+- **套用后必须再调一次整单保存**，流程改为：点「套用模版」→ 调 4.3 拿到组合结果 → 在页面上展示（可让用户继续改）→ 用户点「保存」→ 把这些行（连同用户的修改）提交 `POST /v3/admin/order/meal-info/save`。只调 4.3 不调 3.3，什么都不会入库。
+- 提交 3.3 时这些行**不带 `mealInfoId`**（为 `null`），后端按新增处理；订单原来的行因为没被传上来，按现有规则软删。
+- `priceUnit` 是只读派生字段，提交 3.3 时带上也会被后端忽略；不要把它当成可编辑项，也不要用它反推桌数。
+- 判断一行「按人还是按桌」只看 `tableCount` 是否为 0，`priceUnit` 只是同一判断的展示形式，两者不会互相矛盾。
+- 套用返回的金额已经算好，**前端不要再算一遍**；用户在页面上改了人数 / 桌数 / 单价后仍按原有方式由前端试算、以 3.3 保存后的后端结果为准。
+- `creatorName` 作为 query 参数传中文时必须 URL 编码。
+- 老模版的 `tableCount` / `personCount` 都是 0，属于正常数据，不是异常。
+
+---
+
+## 五、数据库行为
+
+只写前端可观察到的行为，不涉及表结构细节。
+
+- **套用模版（4.3）不产生任何写入**：调用前后用 3.1 按该订单查询，返回逐字段完全一致；不新增、不覆盖、不软删任何用餐行。
+- **订单原有用餐行在整单保存（3.3）时才被去掉**：沿用现有规则——这次没传上来的行按软删处理，历史记录仍可追溯，不是物理删除。
+- **保存为模版（4.2）** 新增一个模版，同时把源用餐行的桌数、人数一并存下；不改动源用餐行。
+- **删除模版（4.4）是软删**，且只作用于该模版自身；已经保存到订单上的用餐行不受影响。对不存在或已删除的模版重复调用不产生写入，仍返回成功。
+- 改动前保存的老模版没有桌数、人数，读取时一律按 0 返回（等同「按人算、人数未知」）。
+
+---
+
+## 六、边界行为
+
+- 模版第 d 日超出订单行程天数：不拦截，照落在出发日 + d − 1。
+- 订单没有出发日期：返回 `items: []` 并带提示文案，不报错。
+- 模版为空：返回 `items: []`、`totalAmount: 0.00`。
+- 创建人姓名取不到（用户服务异常或查不到该管理员）：`creatorName` 为 `null`，列表仍正常返回；传了创建人条件时这类模版不返回。
+
+---
+
+## 六.6、修改前后对比
+
+| 项 | 改动前 | 改动后 |
+|---|---|---|
+| 套用是否写库 | 是（覆盖 / 新建） | **否，只读** |
+| 套用返回内容 | 该订单全部用餐行（含原有行） | **只有模版套出来的行** |
+| 套出来的行桌数 / 人数 / 金额 | 都是 0 | **后端算好**（桌数取模版，按人行人数取订单人数，金额按公式） |
+| 行上 `priceUnit` | 无 | 套用返回的行与模版行有（3.1–3.4 仍无） |
+| 模版名搜索 | 精确匹配 | **模糊匹配** |
+| 创建人 | 不返回、不能搜 | **返回 `creatorName`，可模糊搜** |
+| 模版行 `tableCount` / `personCount` | 不存、不返回 | **存并返回** |
+| 删除模版 | 无接口 | **新增 4.4** |
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 是。4.3 不再写库且返回内容变化，沿用旧流程会导致套用结果不入库
+- **前端是否必须同步上线**: 是，必须按第四节改套用流程
+- **前端 workaround 清理点**: 去掉「套用成功后直接重查列表」的假设；去掉前端自己算套用行金额的代码
+
+## 七、不影响范围
+
+- **仅影响**: 用餐模版 4.1 / 4.2 / 4.3 与新增的 4.4
+- **零影响**:
+  - 3.1 查询、3.2 生成、3.3 整单保存、3.4 重置的入参、出参与行为
+  - `order_meal_info` 表结构与金额公式
+  - 订单、团期、结算、房务等其他模块
+
+---
+
+## 八、测试环境已验证
+
+部署提交 `cc4fb69ed`，经 Gateway 用真实 TEST 身份（SUPER_ADMIN）由固定脚本实测 32 项全部通过：
+
+```
+套用零写入（订单 2101846199160188929，原有 10 行）   → 调用前后 3.1 整份 JSON 逐字段一致 ✓
+套用返回行数                                         → 3 行 = 模版行数，订单原有 10 行不在返回里 ✓
+套用返回行ID                                         → mealInfoId 全为 null ✓
+第几日 / 用餐日期                                     → dayNumber=1、mealDate=2026-11-10（出发日+0）✓
+按人行（桌数 0，单价 30）                             → 人数=订单人数 2、priceUnit=person、金额 60.00 ✓
+按桌行（桌数 2，单价 888）                            → 人数=0、priceUnit=table、金额 1776.00 ✓
+免人数 / 免金额 / 其他成本                            → 全为 0 ✓
+totalAmount                                          → 1836.00 = 各行金额之和 ✓
+原样回提整单保存（假订单）                            → 原 3 行全部软删，只剩套用的 3 行，内容一致 ✓
+4.1 创建人                                           → 7 个模版全部返回中文姓名「刘畅」✓
+4.2 桌数人数快照                                      → 早/午/晚三行与源用餐行逐项一致（0/0、0/4、2/0）✓
+模版名模糊 templateName=HL8093                        → 只返回名称含该片段的模版 ✓
+创建人模糊 creatorName=刘                             → 7/7 命中；传对不上的片段返回空 ✓
+两条件同传                                           → 取交集；任一条件对不上返回空 ✓
+传 templateId                                        → 精确查，忽略另外两个条件 ✓
+删除模版                                             → 删后查不到、其他模版不变、重复删除仍成功 ✓
+已取消订单套用                                        → 589607 ✓
+部署前已有 4 个模版                                   → 原有字段逐字段不变 ✓
+```
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#8093](https://git.1814.love:8443/wx/HL/issues/8093)
+- 关联 PR: [wx/HL#8105](https://git.1814.love:8443/wx/HL/pulls/8105)
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8093](https://git.1814.love:8443/wx/HL/issues/8093)
+- **PR**: [wx/HL#8105](https://git.1814.love:8443/wx/HL/pulls/8105)
+- **Merge commit**: [cc4fb69ed](https://git.1814.love:8443/wx/HL/commit/cc4fb69ed505a5966ae995f2d7746c086c802d79)
+
+### 联系人
+
+- 后端: @lc
@@ -0,0 +1,465 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8125"
+title: "用餐第几天按订单出发日算，套用模版改为在现有行后面追加"
+consumer: "admin"
+author: "lc(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "74eacd7a992d276e438b2e9f55b38e3924d5fe0c"
+target_release: "v2.1"
+verified_at: "2026-09-21"
+status_note: "订单用餐行的第几天改为后端按「用餐日期 − 订单出发日期 + 1」重算：整单保存时新增的行和改了用餐日期的行都会跟着变，前端不要再自己算或沿用旧值。保存为模版的第几日同口径（不再按选中那批行里最早的日期算第 1 日）。套用模版的返回由「只有模版行」改为「订单现有行 + 模版行（模版行在后）」，前端仍把返回的行原样整单提交，原有行按行ID保留、模版行按新增落库，页面上表现为在现有数据后面追加。 前端 2026-09-21 已交付(hl-admin v2.1 74eacd7a9):MealTab 套用改只读预览——只把回包 mealInfoId=null 的模版行追加进本地列表(不清空/不只提交模版行),保存走整单提交入库;MealTemplateApplyModal 加双模糊搜索/创建人/桌人列/删除模版;checkpoint 全量绿。（与 #8093 合并一个交付单元；dayNumber 前端不自算,沿后端返回直显)"
+updated_at: "2026-09-21"
+base: "dev-v3"
+---
+
+# order-v3: 用餐第几天按订单出发日算，套用模版改为在现有行后面追加
+
+> **服务**: hl-order-service-v3
+> **PR**: #8126
+> **Issue**: #8125
+> **日期**: 2026-09-21
+> **影响范围**: 管理后台订单详情「用餐」页签的整单保存、保存为模版、套用模版
+
+---
+
+## ⚠️ 关键变化
+
+- 🔁 **套用模版的返回内容变了（破坏性）**：`POST /v3/admin/order/meal-template/apply` 现在返回**订单现有的用餐行 + 模版套出来的行**，模版行排在现有行**后面**。#8093 的行为是只返回模版行，前端原样提交保存会把原有行全部软删；现在原有行带着行ID一起返回，原样提交后它们按行ID保留，页面上就是「在现有数据后面套用模版」。**前端不需要改提交方式，仍是把返回的 `items` 原样提交整单保存**，但如果前端自己做过「套用前先清空列表」或「只提交模版行」的处理，必须去掉。
+- 🔁 **套用不去重、不覆盖**：模版里那一日那一餐订单已经有行时，两行并存，原有行不动。
+- 🔁 **第几天 `dayNumber` 由后端按订单出发日重算**：`第几天 = 用餐日期 − 订单出发日期 + 1`，出发日当天是第 1 天。整单保存时，新增的行和改了用餐日期的行都会重算后落库，**前端提交的 `dayNumber` 不参与**（入参本来也没有这个字段）。页面上的「D2」就是 `dayNumber: 2` 加个 D 前缀，后端不返回带 D 的字符串。
+- ℹ️ **`dayNumber` 可能是 0 或负数**：用餐日期填在订单出发日之前时按公式照算，不拦截。订单没有出发日期时为 `null`。
+- 🔁 **保存为模版的第几日同口径**：`POST /v3/admin/order/meal-template/save` 存下的 `dayNumber` 改为按「该行用餐日期 − 所属订单出发日期 + 1」算，不再按选中那批行里最早的用餐日期算第 1 日。套用时仍落到目标订单出发日 + d − 1。
+- ℹ️ **存量数据不订正**：历史用餐行里与新口径对不上的 `dayNumber` 不做数据迁移，页面对那张订单再保存一次即自动算对。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|---|---|---|---|---|
+| 1 | 套用用餐模版 | POST | `/v3/admin/order/meal-template/apply` | 修改 | 返回由「只有模版行」改为「订单现有行 + 模版行」，模版行在后；`totalAmount` 为全部行之和 |
+| 2 | 保存用餐信息（整单保存） | POST | `/v3/admin/order/meal-info/save` | 修改 | 入参出参字段不变；保存后 `dayNumber` 按订单出发日重算 |
+| 3 | 保存为用餐模版 | POST | `/v3/admin/order/meal-template/save` | 修改 | 入参出参字段不变；模版行 `dayNumber` 改为按订单出发日算 |
+
+查询用餐信息列表 `GET /v3/admin/order/meal-info/list` 的入参、出参**字段一个没变**，只是返回的 `dayNumber` 取值随保存口径变化。3.2 生成、3.4 重置、模版查询与删除的入参出参和行为完全不变。错误码没有新增或删除。
+
+---
+
+## 三、接口详情
+
+### 1. 套用用餐模版 `POST /v3/admin/order/meal-template/apply`
+
+**VO**: `MealTemplateApplyReqVO` → `OrderMealInfoListRespVO`
+
+#### 使用场景
+
+订单详情「用餐」页签点「套用模版」：把某个模版的内容按订单出发日铺开，**接在页面现有数据后面**展示给用户预览；用户确认后再点保存。
+
+#### 入参字段表
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| orderId | Body | String | 是 | 雪花 ID | 订单 ID（不变） |
+| templateId | Body | String | 是 | 雪花 ID | 模版 ID（不变） |
+
+#### 请求示例
+
+```json
+{
+  "orderId": "2102035335653556226",
+  "templateId": "2102035945748684802"
+}
+```
+
+#### 出参字段表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| items[] | Array | **内容变化**：前段是该订单现有的用餐行（`mealInfoId` 非空，逐字段与列表接口一致，金额不重算），后段是模版套出来的行（`mealInfoId` 为 `null`）。两段各自有序，不混排 |
+| items[].dayNumber | Integer | 模版行为模版里的第几日；现有行为库里存的第几天 |
+| items[].mealDate | String | 模版行 = 订单出发日 + 第几日 − 1；现有行为它自己的用餐日期 |
+| items[].priceUnit | String | `person` / `table`，由桌数是否为 0 派生，不存库。**现有行也会带这个字段** |
+| totalAmount | BigDecimal | **口径变化**：返回全部行（现有行 + 模版行）金额之和 |
+| 其余字段 | — | 与 #8093 相同 |
+
+模版行的人数、桌数、价钱、桌/人、金额仍由后端算好（免人数 / 免金额 / 其他成本为 0），前端直接展示。
+
+#### 响应示例
+
+订单出发日 `2026-10-11`，页面上已有 3 行，模版有第 2 日午餐、第 8 日晚餐：
+
+```json
+{
+  "code": 200,
+  "success": true,
+  "data": {
+    "orderId": "2102035335653556226",
+    "departDate": "2026-10-11",
+    "returnDate": "2026-10-13",
+    "personCount": 4,
+    "orderEditable": true,
+    "generated": true,
+    "totalAmount": 1940.00,
+    "items": [
+      {
+        "mealInfoId": "2102036...001",
+        "mealType": "LUNCH", "dayNumber": 2, "mealDate": "2026-10-12",
+        "restaurantName": "HL8125-TEST-B单午餐厅", "dishName": "HL8125-TEST-B单午餐",
+        "unitPrice": 45.00, "tableCount": 0, "personCount": 4, "priceUnit": "person",
+        "freePersonCount": 0, "freeAmount": 0.00, "otherCost": 0.00, "amount": 180.00,
+        "settleType": "sign", "settleTypeName": "签单"
+      },
+      {
+        "mealInfoId": "2102036...002",
+        "mealType": "DINNER", "dayNumber": 2, "mealDate": "2026-10-12",
+        "restaurantName": "HL8125-TEST-B单晚餐厅", "dishName": "HL8125-TEST-B单晚宴",
+        "unitPrice": 588.00, "tableCount": 2, "personCount": 0, "priceUnit": "table",
+        "freePersonCount": 0, "freeAmount": 0.00, "otherCost": 0.00, "amount": 1176.00,
+        "settleType": "cash", "settleTypeName": "现付"
+      },
+      {
+        "mealInfoId": "2102036...003",
+        "mealType": "BREAKFAST", "dayNumber": 3, "mealDate": "2026-10-13",
+        "restaurantName": "HL8125-TEST-B单早餐厅", "dishName": "HL8125-TEST-B单早餐",
+        "unitPrice": 25.00, "tableCount": 0, "personCount": 4, "priceUnit": "person",
+        "freePersonCount": 0, "freeAmount": 0.00, "otherCost": 0.00, "amount": 100.00,
+        "settleType": "company", "settleTypeName": "公司付款"
+      },
+      {
+        "mealInfoId": null,
+        "mealType": "LUNCH", "dayNumber": 2, "mealDate": "2026-10-12",
+        "restaurantName": "HL8125-TEST-七间房全羊馆", "dishName": "HL8125-TEST-午市套餐",
+        "unitPrice": 60.00, "tableCount": 0, "personCount": 4, "priceUnit": "person",
+        "freePersonCount": 0, "freeAmount": 0.00, "otherCost": 0.00, "amount": 240.00,
+        "settleType": "sign", "settleTypeName": "签单"
+      },
+      {
+        "mealInfoId": null,
+        "mealType": "DINNER", "dayNumber": 8, "mealDate": "2026-10-18",
+        "restaurantName": "HL8125-TEST-卢布里西餐厅", "dishName": "HL8125-TEST-晚宴套餐",
+        "unitPrice": 61.00, "tableCount": 0, "personCount": 4, "priceUnit": "person",
+        "freePersonCount": 0, "freeAmount": 0.00, "otherCost": 0.00, "amount": 244.00,
+        "settleType": "cash", "settleTypeName": "现付"
+      }
+    ]
+  }
+}
+```
+
+第 1 行和第 4 行是同一天同一餐（2026-10-12 午餐）：模版那一行**照样追加**，原有行不被覆盖也不被去掉。
+
+#### 空数据 / 降级响应
+
+- 模版一行都没有：只返回订单现有行，`code` 200。
+- 订单一行都没有：只返回模版套出来的行。
+- 订单没有出发日期：无法对天，**只返回订单现有行**（#8093 时返回空），`code` 200，`message` 带 589602 文案。
+- 现有行 + 模版行超过 200 条时按 200 截断。
+
+#### 错误响应
+
+```json
+{ "code": 589607, "message": "订单已完成或已取消，不能修改用餐信息", "success": false, "data": null }
+```
+
+与 #8093 一致：订单已完成或已取消 589607；订单不可写 581045 / 581008；订单不存在按订单模块现有错误码。本单没有新增或删除错误码。
+
+#### 业务边界
+
+- **调用套用仍不改库**：调用前后用列表接口按该订单查询，返回逐字段完全一致。
+- 前端保存时把返回的 `items` 原样提交 `POST /v3/admin/order/meal-info/save`：带行ID的原有行被保留，`mealInfoId` 为 `null` 的模版行按新增落库。`priceUnit` 是只读字段，提交上来后端会忽略。
+
+### 2. 保存用餐信息（整单保存） `POST /v3/admin/order/meal-info/save`
+
+**VO**: `OrderMealInfoBatchSaveReqVO` → `OrderMealInfoListRespVO`
+
+#### 使用场景
+
+订单详情「用餐」页签点「保存」：把页面上这张订单**应有的全部行**一次提交。带行ID的整行覆盖、不带行ID的新增、原来有而这次没传上来的软删。套用模版后的保存走的也是这个接口。
+
+#### 入参字段表
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| orderId | Body | String | 是 | 雪花 ID | 订单 ID（不变） |
+| groupBatchId | Body | String | 否 | 雪花 ID | 团期 ID（不变） |
+| items[] | Body | Array | 是 | — | 这张订单保存后应有的全部行（不变） |
+| items[].mealInfoId | Body | String | 否 | 雪花 ID | 传了更新这一行，不传新增（不变） |
+| items[].mealDate | Body | String | 是 | `yyyy-MM-dd` | 用餐日期。**第几天由它和订单出发日期算出来** |
+| items[] 其余字段 | Body | — | — | — | `mealType`、`restaurantId/Name`、`dishId/Code/Name`、`unitPrice`、`tableCount`、`personCount`、`freePersonCount`、`freeAmount`、`otherCost`、`amount`、`settleType`、`settleTypeName` 全部不变 |
+
+**入参没有 `dayNumber`**，改动前后都没有；第几天一律由后端算。
+
+#### 出参字段表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| items[].dayNumber | Integer | **取值口径变化**：`用餐日期 − 订单出发日期 + 1`，出发日当天为 1；用餐日期早于出发日时为 0 或负数；订单没有出发日期时为 `null` |
+| 其余字段 | — | 与改动前完全一致 |
+
+#### 请求示例
+
+```json
+{
+  "orderId": "2102035302317228034",
+  "items": [
+    {
+      "mealType": "LUNCH", "mealDate": "2026-10-02",
+      "restaurantName": "HL8125-TEST-七间房全羊馆", "dishName": "HL8125-TEST-午市套餐",
+      "unitPrice": 60.00, "tableCount": 0, "personCount": 4,
+      "freePersonCount": 0, "freeAmount": 0, "otherCost": 0, "amount": 240.00,
+      "settleType": "sign", "settleTypeName": "签单"
+    }
+  ]
+}
+```
+
+#### 响应示例
+
+订单出发日 `2026-10-01`，上面这行用餐日期是 `2026-10-02`：
+
+```json
+{
+  "code": 200,
+  "success": true,
+  "data": {
+    "orderId": "2102035302317228034",
+    "departDate": "2026-10-01",
+    "personCount": 4,
+    "totalAmount": 240.00,
+    "items": [
+      {
+        "mealInfoId": "2102036...010",
+        "mealType": "LUNCH", "dayNumber": 2, "mealDate": "2026-10-02",
+        "restaurantName": "HL8125-TEST-七间房全羊馆", "dishName": "HL8125-TEST-午市套餐",
+        "unitPrice": 60.00, "tableCount": 0, "personCount": 4,
+        "freePersonCount": 0, "freeAmount": 0.00, "otherCost": 0.00, "amount": 240.00,
+        "settleType": "sign", "settleTypeName": "签单"
+      }
+    ]
+  }
+}
+```
+
+把这一行的 `mealDate` 改成 `2026-10-05` 再提交，同一行的 `dayNumber` 变成 5；改成 `2026-10-08`（超出返回日期）变成 8，接口不报错。
+
+#### 空数据 / 降级响应
+
+- `items` 传空数组：这张订单的行全部软删，返回 `items: []`、`totalAmount: 0.00`，`code` 200。
+- 订单没有出发日期：照常保存，行上 `dayNumber` 为 `null`。
+
+#### 错误响应
+
+```json
+{ "code": 589613, "message": "金额与明细不一致", "success": false, "data": null }
+```
+
+589606（行查不到或已删除）、589611（行挂的不是这张订单）、589601（团期不一致）、589607（订单已完成或已取消）与改动前一致。
+
+#### 业务边界
+
+- 第几天只在保存时算一次并落库，查询按库里存的值返回。
+- 前端提交的行里即使带了 `dayNumber` 也不会被采纳（入参没有这个字段）。
+- 用餐日期早于订单出发日期不拦截，得到 0 或负数。
+- 历史行里与新口径对不上的 `dayNumber` 不会被批量订正，对那张订单再保存一次即自动算对。
+
+### 3. 保存为用餐模版 `POST /v3/admin/order/meal-template/save`
+
+**VO**: `MealTemplateSaveReqVO` → `MealTemplateRespVO`
+
+#### 使用场景
+
+「用餐」页签上排好几天的用餐后点「保存为模版」，把选中的行存成一个可复用的模版。模版只存第几日，不存用餐日期。
+
+#### 入参字段表
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| templateName | Body | String | 是 | trim 后 1–500 字符 | 模版名，允许重名（不变） |
+| mealInfoIds | Body | Array | 是 | 非空，服务端去重 | 要存进模版的用餐信息行ID（不变） |
+
+#### 出参字段表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| items[].dayNumber | Integer | **算法变化**：`该行用餐日期 − 所属订单出发日期 + 1`，不再按选中那批行里最早的用餐日期算第 1 日 |
+| 其余字段 | — | `templateId`、`templateName`、`creatorName` 与行上其余字段均不变 |
+
+#### 请求示例
+
+```json
+{
+  "templateName": "HL8125-TEST-D几模版",
+  "mealInfoIds": ["2102036...010", "2102036...011"]
+}
+```
+
+#### 响应示例
+
+源订单出发日 `2026-10-01`，两行用餐日期分别是 `2026-10-02` 和 `2026-10-08`：
+
+```json
+{
+  "code": 200,
+  "success": true,
+  "data": {
+    "templateId": "2102035945748684802",
+    "templateName": "HL8125-TEST-D几模版",
+    "creatorName": "刘畅",
+    "items": [
+      {
+        "dayNumber": 2, "mealType": "LUNCH",
+        "restaurantName": "HL8125-TEST-七间房全羊馆", "dishName": "HL8125-TEST-午市套餐",
+        "unitPrice": 60.00, "tableCount": 0, "personCount": 4, "priceUnit": "person",
+        "settleType": "sign", "settleTypeName": "签单"
+      },
+      {
+        "dayNumber": 8, "mealType": "DINNER",
+        "restaurantName": "HL8125-TEST-卢布里西餐厅", "dishName": "HL8125-TEST-晚宴套餐",
+        "unitPrice": 61.00, "tableCount": 0, "personCount": 4, "priceUnit": "person",
+        "settleType": "cash", "settleTypeName": "现付"
+      }
+    ]
+  }
+}
+```
+
+改动前这两行会存成第 1 日和第 7 日（按选中行里最早的 10-02 当第 1 日）。
+
+#### 空数据 / 降级响应
+
+- 源行所属订单查不到或没有出发日期：该行回落到旧口径（这批行里最早的用餐日期算第 1 日），接口照常成功。
+- 一行都没取到：返回 589606。
+
+#### 错误响应
+
+```json
+{ "code": 400, "message": "第2日午餐重复", "success": false, "data": null }
+```
+
+同一日同一餐出现多条时返回参数错误并指出是哪一日哪一餐，整批不保存；这一条与改动前一致，只是「第几日」的算法变了。
+
+#### 业务边界
+
+- 每次保存都生成新的模版ID，不覆盖已有模版。
+- 行上原本存着的第几天不再参与，一律按订单出发日重新算。
+- 算出来的第几日可能是 0 或负数（源行用餐日期早于订单出发日），套用时同样落到目标订单出发日 + d − 1。
+
+---
+
+## 四、契约约束与正确调用方式
+
+- **套用流程不变，但不要再清空列表**：点「套用模版」→ 调 apply 拿到「现有行 + 模版行」→ 在页面上整体展示（可让用户继续改）→ 用户点「保存」→ 把这些行原样提交整单保存。返回里已经包含原有行，前端不需要（也不应该）自己拼接或先清空。
+- 提交整单保存时，**带 `mealInfoId` 的行必须原样带上**，否则那些原有行会被当成「没传上来」而软删。
+- `priceUnit` 是只读派生字段，提交时带上会被后端忽略。
+- **第几天不要在前端算**：直接用后端返回的 `dayNumber`。页面上的「D2」是 `dayNumber: 2` 加 D 前缀。
+- 用户在页面上改了某行的用餐日期后，第几天要等这次保存的返回（或保存后的列表）才刷新，前端如需即时显示可按同一公式本地预览，但以后端返回为准。
+
+---
+
+## 五、数据库行为
+
+只写前端可观察到的行为，不涉及表结构细节。
+
+- **套用模版仍然不产生任何写入**：调用前后按该订单查询，返回逐字段完全一致；不新增、不覆盖、不软删任何行。
+- **整单保存时第几天被重算并落库**：新增的行和改了用餐日期的行都会写入新的第几天；这是本次唯一新增的写入行为，不涉及新表或新列。
+- **保存为模版**仍是新增一个模版，不改动源用餐行；只是存下的第几日算法变了。
+- **存量数据不做迁移**：历史行里对不上的第几天保持原样，直到那张订单下次整单保存。
+
+---
+
+## 六、边界行为
+
+- 用餐日期早于订单出发日期：第几天为 0 或负数，不拦截。
+- 用餐日期超出订单返回日期：照算（如第 8 天），不拦截。
+- 订单没有出发日期：保存的行第几天为 `null`；套用时只返回现有行并带提示文案。
+- 模版第 d 日超出目标订单行程天数：照落在出发日 + d − 1。
+- 套用返回的现有行 + 模版行超过 200 条：按 200 截断。
+- 模版里那一日那一餐订单已经有行：两行并存，不去重、不覆盖。
+
+---
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+| 字段 | 改动前 | 改动后 |
+|---|---|---|
+| `meal-info/save` 出参 `items[].dayNumber` | 新增行为 `null`；改日期不变 | 按「用餐日期 − 订单出发日期 + 1」重算 |
+| `meal-template/save` 出参 `items[].dayNumber` | 按选中行里最早的用餐日期算第 1 日 | 按该行所属订单的出发日期算 |
+| `meal-template/apply` 出参 `items[]` | 只有模版行（`mealInfoId` 全为 `null`） | **订单现有行（带行ID）+ 模版行**，模版行在后 |
+| `meal-template/apply` 出参 `totalAmount` | 模版行金额之和 | 返回全部行金额之和 |
+
+### 行为级对比
+
+| 项 | 改动前 | 改动后 |
+|---|---|---|
+| 页面上「第几天」列 | 手动加的行是空的，改日期不跟着变 | 一直等于用餐日期相对订单出发日的天数 |
+| 套用模版的页面效果 | 保存后原有数据被清掉，只剩模版内容 | **在现有数据后面追加模版内容** |
+| 同一日同一餐重合 | 原有行被整单保存软删 | 两行并存 |
+| 订单没有出发日期时套用 | 返回空列表 | 返回订单现有行 |
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 是。apply 的返回内容变化，沿用「返回即全部模版行」的假设会重复展示或误删
+- **前端是否必须同步上线**: 是。必须去掉「套用前清空列表」「只提交模版行」「前端自己算第几天」这三类处理
+- **前端 workaround 清理点**: 前端本地计算 `dayNumber` 的代码；套用后手工拼接原有行的代码
+
+## 七、不影响范围
+
+- **仅影响**: 订单用餐信息的整单保存、保存为用餐模版、套用用餐模版
+- **零影响**:
+  - 查询用餐信息列表、生成、重置的入参出参与行为（返回的第几天取值随保存口径变化）
+  - 查询用餐模版、删除用餐模版
+  - 金额公式、订单门禁、错误码
+  - 订单、团期、结算、房务、车务等其他模块
+
+---
+
+## 八、测试环境已验证
+
+部署提交 `d30cd9561`，Deploy Panel 任务 `41c56ef7`，经 Gateway 用真实 TEST 身份（SUPER_ADMIN）由固定脚本实测 19 项全部通过：
+
+```
+A 单出发 2026-10-01，新增一行用餐日期 2026-10-02        → dayNumber=2 ✓
+同一行日期改成 2026-10-05                                → dayNumber=5 ✓
+日期改回 2026-10-02                                      → dayNumber=2 ✓
+A 单两行 10-02 / 10-08 存为模版                          → 模版第几日 2 和 8（不是 1 和 7）✓
+模版行的餐厅 / 餐食 / 价钱 / 付款方式                      → 与源用餐行一致 ✓
+模版套到 B 单（出发 2026-10-11）                          → 落在 2026-10-12(D2) 与 2026-10-18(D8) ✓
+套出来的两行按人算好                                      → 人数=订单人数 4、金额 240.00 / 244.00、priceUnit=person ✓
+套用返回结构                                             → 前 3 行带行ID（B 单现有行）、后 2 行行ID为空 ✓
+前段 3 行与套用前按订单查询                                → 逐字段一致 ✓
+totalAmount                                              → 1940.00 = 180+1176+100+240+244 ✓
+套用零写入                                               → 调用前后整份列表 JSON 逐字段一致 ✓
+同一日同一餐重合（2026-10-12 午餐）                        → 两行并存，原有行未被覆盖 ✓
+把套用返回的 5 行原样提交整单保存                           → 共 5 行，原 3 行行ID与内容不变 ✓
+模版套出来的 2 行                                        → 成为新行，10-12/D2 与 10-18/D8 ✓
+保存后合计                                               → 仍为 1940.00 ✓
+回归：用户样本订单 2101846199160188929（10 行）            → 与部署前读数逐行逐字段一致 ✓
+回归：部署前已有的 7 个模版                                → 第几日仍是旧口径原值，未被批量改写 ✓
+```
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#8125](https://git.1814.love:8443/wx/HL/issues/8125)
+- 关联 PR: [wx/HL#8126](https://git.1814.love:8443/wx/HL/pulls/8126)
+- 前置变更: [#8093 套用用餐模版改为只读返回组合结果](21_8093_套用用餐模版改只读返回组合结果与模版桌人创建人搜索删除-修改接口-管理后台.md)
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8125](https://git.1814.love:8443/wx/HL/issues/8125)
+- **PR**: [wx/HL#8126](https://git.1814.love:8443/wx/HL/pulls/8126)
+- **Merge commit**: [d30cd9561](https://git.1814.love:8443/wx/HL/commit/d30cd9561e868b7b684589f65ad344045c818ce4)
+
+### 联系人
+
+- 后端: @lc
@@ -0,0 +1,350 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7982"
+title: "fleet: 确认共用关系时同批准入多个新成员不再误报冲突码 605001（行为修复，无接口字段变化）"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修复"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "not_required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "backend_status=deployed：修复 PR #7983（`e7cecb6d7`）+ 测试补强 PR #8096（`970f9a187`）已合入 dev-v3；fleet 测试服部署点 `bd19b79c8`，`git merge-base --is-ancestor e7cecb6d7 bd19b79c8` 与 `970f9a187 bd19b79c8` **均为真**（2026-09-22 逐条复核）。gateway_status=verified：2026-09-22 经网关实调该端点 `POST https://api.test.1814.love:9443/admin/fleet/group-dispatch/batches/1/share-groups`，HTTP 200 + 业务码 600009（刻意使用不存在的 groupBatchId=1，第一道校验即失败关闭）；同轮阴性对照打在不存在的路径上返回 `code=404 接口不存在`，两者可分辨 ⇒ 路由、鉴权（需 VEHICLE_MANAGER 角色）、请求体反序列化三项均通，且全程未触达写库路径。**该验证的覆盖边界**：只验到端点可达性与契约反序列化，**未验证本次修复的行为本身**（同批多个待准入成员不再误报 605001）——那需要真实团期与派单夹具；修复行为的证据来源是源码与真库集成测试 `ShareGroupOverlapProjectionIntegrationTest`。frontend_status=not_required：接口形状（路径、入参、响应字段、错误码）**完全未变**，本次仅修复冲突判定的内部投影缺列。"
+updated_at: "2026-09-22"
+base: "dev-v3"
+---
+
+# fleet: 确认共用关系时同批准入多个新成员不再误报冲突码 605001（行为修复，无接口字段变化）
+
+> **存放目录**: 二期（fleet 车务）→ `changelogs-v2/2026-09/`
+
+## 🔴 2026-09-22 订正说明（首版字段写错，请重新核对）
+
+本文件**首版**（提交 `3328730`）的「接口详情」章把请求/响应契约写错了，具体：把入参 `resourceType` 写成了不存在的 `dimension`、漏掉 `serviceDate` 与 `costBearer` 两个**必填**字段、引用了两个不存在的 VO 类名（`CreateShareGroupReqVO` / `ShareGroupCreateRespVO`）、响应示例里给出了 VO 上不存在的 `id` / `createdAt` / `admissionAt` 字段，并把 605001 的提示文案写成了另一段文字。**照首版的请求示例构造的请求发不出去**（缺必填字段 + 字段名不匹配）。
+
+**若已照首版写过代码，请按本版重新核对字段名。** 本版每一个字段、每一个错误码文案均取自 `dev-v3` 分支上的源码（VO 的 `@ApiModelProperty` 声明与 `IErrorCode.of(...)` 定义），下文逐处标注了出处文件。
+
+## ⚠️ 关键变化
+
+**接口契约零变化**——路径、方法、请求参数、响应字段、错误码全部不动。
+
+**变的是冲突判定的投影**。从本次修复上线起：
+
+1. 确认共用关系时，**同一个 POST 请求里传入 2 个或更多尚未占用该资源的 `ASSIGNMENT` 成员**、且没有既有共用关系可对标时，**从第二个成员开始不再误报错误码 605001**（`605001 = 派单冲突：该车日期段已派`）；
+2. 修复后同一请求正常受理，全部成员入库成该关系的成员行。
+
+🔴 **这个误报在上述场景下是必现的，不是偶发**：根因是一处数据投影恒缺列（见下），每次走到这条回退路径都会做错判定。
+
+## 一、背景
+
+### 缺陷形态
+
+确认共用关系时的冲突判定有两层：
+
+1. **第一层**：按既有共用关系逐一检查新增成员是否与它们的成员产生冲突；
+2. **第二层（回退）**：若找不到既有关系可对标，则按**新增成员之间的相互关系**判定冲突。
+
+第一层是正常路径，拿得到全量数据。第二层回退靠「**按需求认对端**」——用成员行的 `requirement_id` 去认出另一侧是谁。但组行视图与候选面的数据投影里**没有把 `requirement_id` 选出来**，于是这条回退路径从上线起就恒失效。
+
+为什么偏偏卡在这一列：成员正在改绑的那段窗口里，成员表存的还是旧的派车行，**按 ID 查对端必然落空**，`requirement_id` 是那段窗口里唯一还认得出对端的键——而它恰好是被投影丢掉的那一列。
+
+⇒ **在同批多成员且无既有关系可对标的场景下，从第二个成员开始每一个都认不出对端，必定返回 605001。**
+
+### 这个判断的证据来源
+
+**证据是源码与真库集成测试（`ShareGroupOverlapProjectionIntegrationTest`），不是测试环境上的前后对跑读数。** 修复已于 2026-09-19 合入 `dev-v3`，测试环境此后一直处于修复后的状态，客观上不存在可供对跑的修复前环境。
+
+本文件**不提供**任何声称来自测试环境实测的修复前/修复后请求读数。（首版曾给出一张这样的表格，已在本版删除——那张表的数据无法溯源到任何一次真实调用。）
+
+### 修复
+
+PR #7983（`e7cecb6d7`）：把 `requirement_id` 补进组行视图与候选面的投影列清单，让「按需求认对端」的回退真正取得到那一列。提交标题逐字为「组行/候选面投影补 requirement_id——「按需求认对端」的回退从未生效过」。
+
+测试补强 PR #8096（`970f9a187`）：补真库集成测试。
+
+## 二、变更接口清单
+
+本条**不新增、不修改、不删除**任何 HTTP 接口，也不改动任何请求/响应字段与错误码。
+
+下列既有端点的**冲突判定行为**得到修复（契约形状不变）：
+
+| METHOD | Path | 变化 |
+|---|---|---|
+| POST | `/admin/fleet/group-dispatch/batches/{groupBatchId}/share-groups` | 同批确认多个尚未占用的 `ASSIGNMENT` 成员时，冲突判定不再误报 605001；多成员共用关系可一次请求完成 |
+
+## 三、接口详情
+
+### 1. 确认团期车辆共用关系 `POST /admin/fleet/group-dispatch/batches/{groupBatchId}/share-groups`
+
+**VO**：`ShareGroupConfirmReqVO` → `Result<ShareGroupRespVO>`（**字段无增删改**）
+
+> 出处：`hl-fleet-service/src/main/java/com/hulalv/fleet/dispatch/controller/GroupDispatchShareController.java`，
+> `@RequestMapping("/admin/fleet/group-dispatch")` + `@PostMapping("/batches/{groupBatchId}/share-groups")`。
+> 网关路由复用既有 `- Path=/admin/fleet/**` → `lb://hl-fleet-service`（`hl-gateway/src/main/resources/application.yml`），**本单不新增路由**。
+> 权限点：写口 `fleet:group-dispatch:write`（读口 `fleet:group-dispatch:view`），本单不新增权限点。
+
+#### 使用场景
+
+管理后台「团期配车」页，车务确认「本团这一个服务日、这一辆车（或这一名司机），由下列几方共用」。
+
+⚠️ **端点名是「确认」不是「创建」，这不是措辞问题**：`members` 是**成员全集而不是增量**——同一 `(团, 日, 维度, 资源)` 重复提交按新全集覆盖，返回**同一个** `shareGroupId`，不抛错。前端不要按「新增一个成员就调一次」来用。
+
+#### ⚠️ 这个端点是复合原子操作，不是一次纯粹的关系登记
+
+服务端在**同一事务**里依次做三件事：先落授权 → 再把尚未占用的成员派进这辆车 → 由准入检查读到刚落的授权而放行 → 最后回读断言收口。中途任一步失败**整体回滚**，不留「关系已建但没占上车」或「占上车但没关系」的中间态。
+
+之所以不能拆成「先各自派好车、再来建关系」：跨城场景下第二户根本派不进来（占用准入跨城即拒）。
+
+#### 入参（**本次无变化**）
+
+> 字段与文案出处：`hl-fleet-service/.../dispatch/vo/ShareGroupConfirmReqVO.java`、`ShareGroupMemberReqVO.java` 的 `@ApiModelProperty`。
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `serviceDate` | String `yyyy-MM-dd` | ✅ | 共用发生的服务日；必须落在该团基线 `serviceDates` 内，窗外抛 **602104** |
+| `resourceType` | String | ✅ | 资源维度：`VEHICLE` / `DRIVER`；车与司机**分别建关系** |
+| `resourceId` | Long | ✅ | 车辆 ID 或司机 ID |
+| `members` | List | ✅ | **成员全集（不是增量）**，2-20 个，越界抛 **602100** / **602101** |
+| `members[i].sourceType` | String | ✅ | `ASSIGNMENT`=逐户接送派单 / `GROUP_DISPATCH`=团级配车行 |
+| `members[i].sourceId` | Long | ✅ | `fleet_assignment.assignment_id` 或 `fleet_group_dispatch.dispatch_id` |
+| `members[i].admissionIntent` | String | ❌ | `OCCUPYING`=已占着这辆车 / `PENDING_ADMISSION`=本次一并派入。**仅供前端交互提示** |
+| `costBearer` | String | ✅ | 成本承担方：`GROUP`=记团级整车 / `ORDER`=记指定户；缺失或非法抛 **602107** |
+| `costBearerOrderId` | Long | 条件必填 | `costBearer=ORDER` 时必填，且必须是成员中某个 `ASSIGNMENT` 的订单 |
+| `remark` | String | ❌ | 确认备注，≤ 200 字 |
+| `confirmCrossResident` | Boolean | ❌ | 跨常驻车派单确认，见下方 605036；**不传或 `false` 都表示不确认** |
+
+🔴 **`admissionIntent` 服务端完全不读、不校验、不落库。** 成员到底是「已经占着这辆车」还是「本次一并派入」，一律按库里的实际占用现查现判。它纯粹是给前端做交互提示（按钮文案、二次确认）用的。填错不会改变服务端行为，也**不会**因此报错。
+
+#### 出参（**本次无变化**）
+
+> 字段出处：`hl-fleet-service/.../dispatch/vo/ShareGroupRespVO.java`、`ShareGroupMemberRespVO.java` 的 `@ApiModelProperty`。
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `shareGroupId` | String | 共用关系 ID（雪花 ID，`@JsonSerialize(ToStringSerializer)` 按字符串序列化） |
+| `groupBatchId` | String | 运营团期 ID（字符串序列化） |
+| `serviceDate` | String `yyyy-MM-dd` | 共用发生的服务日 |
+| `resourceType` | String | 资源维度：`VEHICLE` / `DRIVER` |
+| `resourceId` | String | 车辆或司机 ID（字符串序列化） |
+| `status` | String | 关系状态：**`ACTIVE` / `RELEASED`**（没有 `PENDING` 这个取值） |
+| `costBearer` | String | 成本承担方：`GROUP` / `ORDER` |
+| `costBearerOrderId` | String | `costBearer=ORDER` 时的承担订单 ID（字符串序列化；否则为 `null`） |
+| `costSourceRefNo` | String | 车费来源引用 = `SHARE-{shareGroupId}` |
+| `members` | List | **成员全集** |
+| `members[i].sourceType` | String | `ASSIGNMENT` / `GROUP_DISPATCH` |
+| `members[i].sourceId` | String | 成员来源 ID（字符串序列化） |
+| `members[i].requirementId` | String | 用车需求 ID（`ASSIGNMENT` 成员的准入授权键；**团级配车行为空**） |
+| `members[i].orderId` | String | 订单 ID（`ASSIGNMENT` 成员） |
+| `confirmedBy` | String | 确认人 adminId（字符串序列化） |
+| `confirmedAt` | String | 确认时间（服务端类型 `LocalDateTime`，按全局 Jackson 约定序列化） |
+| `version` | Integer | 乐观锁版本号 |
+| `history` | List | 变更历史；**仅查询端点带 `includeReleased=true` 时返回**，本确认端点的响应里为 `null` |
+
+⚠️ **成员出参只有上面 4 个字段**：`sourceType` / `sourceId` / `requirementId` / `orderId`。成员行**没有**独立的 `id`，也**没有**任何时间戳字段。
+
+⚠️ **`costSourceRefNo` 按关系身份生成**：同一关系生命周期内恒定，改 `costBearer`、重复确认都不变；关系解除后在同一槽重建会拿到**新值**。核团比对以它为准。
+
+#### 请求示例
+
+```http
+POST /admin/fleet/group-dispatch/batches/8801/share-groups HTTP/1.1
+Host: api.test.1814.love:9443
+Content-Type: application/json
+Authorization: Bearer {token}
+
+{
+  "serviceDate": "2026-09-12",
+  "resourceType": "VEHICLE",
+  "resourceId": 1,
+  "costBearer": "GROUP",
+  "remark": "本车这一天承接这两户的接送",
+  "members": [
+    {
+      "sourceType": "GROUP_DISPATCH",
+      "sourceId": 88001,
+      "admissionIntent": "OCCUPYING"
+    },
+    {
+      "sourceType": "ASSIGNMENT",
+      "sourceId": 88002,
+      "admissionIntent": "PENDING_ADMISSION"
+    },
+    {
+      "sourceType": "ASSIGNMENT",
+      "sourceId": 88003,
+      "admissionIntent": "PENDING_ADMISSION"
+    }
+  ]
+}
+```
+
+#### 响应示例
+
+⚠️ **以下是按 VO 的 `@ApiModelProperty` 声明与其 `example` 值构造的字段结构示意，不是某一次实测报文。** 真实的 ID 是 19 位雪花，示例里的短 ID 沿用 VO 的 `example` 取值，**长度不代表真实形态**——前端一律按字符串处理。
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "shareGroupId": "77001",
+    "groupBatchId": "8801",
+    "serviceDate": "2026-09-12",
+    "resourceType": "VEHICLE",
+    "resourceId": "1",
+    "status": "ACTIVE",
+    "costBearer": "GROUP",
+    "costBearerOrderId": null,
+    "costSourceRefNo": "SHARE-77001",
+    "members": [
+      {
+        "sourceType": "GROUP_DISPATCH",
+        "sourceId": "88001",
+        "requirementId": null,
+        "orderId": null
+      },
+      {
+        "sourceType": "ASSIGNMENT",
+        "sourceId": "88002",
+        "requirementId": "5501",
+        "orderId": "70123"
+      },
+      {
+        "sourceType": "ASSIGNMENT",
+        "sourceId": "88003",
+        "requirementId": "5502",
+        "orderId": "70124"
+      }
+    ],
+    "confirmedBy": "1001",
+    "confirmedAt": "2026-09-12 10:30:00",
+    "version": 1,
+    "history": null
+  },
+  "success": true
+}
+```
+
+#### 错误码
+
+> 文案出处：`GroupDispatchShareErrorCode.java`（602 段）与 `AssignmentErrorCode.java`（605 段）里的 `IErrorCode.of(...)` 定义，逐字。
+> HL 约定：**业务失败与入参校验一律走 HTTP 200**，错误码在响应信封的 `code` 字段里（鉴权/系统异常除外）。
+
+| code | 服务端文案（逐字） | 触发条件与前端处理 |
+|------|------|------|
+| 600009 | 团期配车权威基线不可用，请稍后重试或检查团期状态 | 团期不存在，或其服务日未设置/不完整。**这是最先触发的一道校验**（见下方校验顺序），不是参数格式错 |
+| 602100 | 共用关系成员不能少于 2 个 | `members` 少于 2 个。共用关系至少要两方 |
+| 602101 | 共用关系成员不能超过 20 个 | `members` 超过 20 个 |
+| 602102 | 成员在该资源日无活跃占用: {0} | 提交前回读断言发现成员没占上车，**整体回滚** |
+| 602103 | 成员派单不属于本团或团期身份未知: {0} | `group_batch_id` 与 `requirement_id` 任一为 `NULL` 一律拒——未知不得当同团通过 |
+| 602104 | 服务日不在团期服务日窗内: {0} | **有意的边界**：窗外日没有团级配车行可挂靠，仍走 R3-EX 城市衔接 |
+| 602105 | 团级配车成员不属于本团或当日非活跃: {0} | `GROUP_DISPATCH` 成员的校验 |
+| 602106 | 成员已属于另一个共用关系: {0} | 要求先解除原关系 |
+| 602107 | 成本承担方缺失或非法 | `costBearer` 未传或取值非法 |
+| 602109 | 共用关系已被并发修改，请刷新后重试 | 乐观锁冲突，提示用户刷新 |
+| 605001 | 派单冲突：该车日期段已派 | **本次修复的误报点**。修复后它回归真实语义，见下方「影响评估」 |
+| 605036 | 司机与车辆不是常驻组合，请确认跨常驻车派单后重试（{0}：{1}；车辆 {2}；司机 {3}） | 跨常驻车派单需人工确认，见下 |
+
+#### 校验顺序（决定你先看到哪个错误码）
+
+服务端 `confirm()` 的前两步在**事务之外**，顺序是固定的：
+
+1. `resourceType` 合法性；
+2. **团期权威基线**——一次同步 Feign 向 order-v3 取该团的服务日窗。取不到 → **600009**；取到了但 `serviceDate` 不在窗内 → **602104**；
+3. 以上都过了，才进入事务做成员数（602100/602101）、成员归属（602103/602105/602106）、成本承担方（602107）等校验，以及实际的授权、派单、准入写入。
+
+⚠️ **所以传一个不存在的 `groupBatchId` 时，先撞上的是 600009 而不是成员相关的校验码**——排查时不要据此认为成员参数已经通过了校验。
+
+#### 🔴 605036 跨常驻车派单需确认（前端必须实现的交互）
+
+端点第 3 步把成员改派进共用资源时走的是既有派单写路径，它有一道**提示型守卫**——满足下列**任一**条即判「跨常驻」，未确认一律拒：
+
+1. 这辆共用车已设常驻司机，且与该成员当前司机**不是同一人**；
+2. 该成员当前司机本身是**别的车**的常驻司机。
+
+⚠️ **两条是「或」的关系**：共用车没设常驻司机（`primary_driver_id` 为空）只躲开①，②照样会触发。
+
+⚠️ **车务在页面上选的是「一辆车」，但 605036 说的是司机**——`resourceType=VEHICLE` 时被派入的司机不是车务选的，是**该成员原派单上的司机**（服务端按成员原样带过去，本端点不改司机）。所以 605036 的消息会点名「哪条派单 / 跨常驻的具体形态 / 车牌 / 司机姓名」。
+
+**前端处理方式**：拿到 605036 后向车务展示 `message` 原文并询问「确认跨常驻车派单？」，确认后带 `confirmCrossResident=true` **原样重发**同一份请求即可。失败路径会释放 10 秒防重键，不会撞「请勿重复提交」。**不传或传 `false` 都表示不确认，服务端不会替你确认。**
+
+#### 🔴 防重与幂等是两件事
+
+1. **10 秒内重复提交同一份成员全集**会被防重窗口**拒绝**——前端按「请勿重复提交」提示，**不要当失败报红**；
+2. **窗口之外**重复提交同一份全集会**正常受理**，那**是成功**，返回同一个 `shareGroupId`。
+
+防重键 = `serviceDate : resourceType : resourceId : 成员集合排序摘要`。所以：
+
+- 只改 `costBearer` 不改成员时，键不变，10 秒内会被挡下（**这是保护不是缺陷**）；
+- 改了成员全集就是另一次业务操作，立刻受理，车务加一个成员不必等 10 秒；
+- 成员先排序再拼摘要——前端两次提交的成员顺序不同但集合相同时那是同一份计划，不会绕过防重窗口；
+- `confirmCrossResident` **不参与**防重键（它不是业务身份的一部分）。
+
+## 四、契约约束与正确调用方式
+
+本接口在**表层契约**上无任何变化。修复前后的入参格式、响应字段、HTTP 状态码、业务错误码全部一致——差别仅在内部冲突判定所依赖的数据投影是否完整。
+
+| 场景 | 修复前 | 修复后 |
+|------|--------|--------|
+| 同批 2+ 个尚未占用的 `ASSIGNMENT` 成员、无既有关系可对标 | **605001**（误报） | 正常受理 |
+| 有既有共用关系可对标（走第一层判定） | 正常 | 正常（不变） |
+| 入参字段、响应字段、错误码清单 | — | **完全不变** |
+
+## 五、数据库行为
+
+涉及的表：`fleet_group_dispatch_share_group`（关系主体）、`fleet_group_dispatch_share_member`（成员行）、`fleet_group_dispatch_share_log`（变更历史）。
+
+修复后，同批多个尚未占用的成员会全部入库成该关系的成员行。修复前，从第二个此类成员开始会抛 605001，**整个请求在同一事务里回滚**，写入不落地。
+
+## 六、边界行为
+
+- 未登录 → 网关拦截（鉴权异常不走业务信封）
+- 无 `fleet:group-dispatch:write` 权限 → 鉴权拦截
+- `members` 少于 2 个 / 超过 20 个 → 602100 / 602101
+- `serviceDate` 不在团期服务日窗内 → 602104
+- `resourceType` 不是 `VEHICLE` 或 `DRIVER` → 参数校验失败（`@NotBlank` 只校验非空，取值合法性由服务端业务校验兜底）
+- 成员已属于另一个共用关系 → 602106（需先解除）
+- 重复提交同一份成员全集 → 窗口内被防重拒绝；窗口外正常受理并返回同一个 `shareGroupId`
+
+## 七、影响评估
+
+- **是否破坏向后兼容**：否——请求/响应字段、错误码全部不变。
+- **前端是否必须同步上线**：否——管理后台无需改任何代码即可获得修复效果。
+- **可以清理的 workaround**：若此前为了绕开 605001 而实现了「一个成员发一次请求」的逻辑，现在可以改回一次请求传全部成员。⚠️ 注意 `members` 是**全集不是增量**，逐个发送的写法在语义上本来就不等价（后一次会覆盖前一次的全集）。
+- **605001 语义的恢复**：该码此前会在合法请求上误报，修复后它回归为**真实派单冲突**的表示（`派单冲突：该车日期段已派`）——收到它就意味着确实存在冲突，可以按真实冲突提示用户。
+
+## 八、不影响范围
+
+- 任何接口的**请求参数、响应字段、错误码清单**——全部不变。
+- 既有共用关系的**查询、解除**等其它端点。
+- 605001 以外其它错误码的触发口径。
+
+## 九、验证状态
+
+**后端部署（已核实）**：修复 PR #7983（`e7cecb6d7`）+ 测试补强 PR #8096（`970f9a187`）均已合入 `dev-v3`；fleet 测试服部署点 `bd19b79c8`，`git merge-base --is-ancestor e7cecb6d7 bd19b79c8` 与 `git merge-base --is-ancestor 970f9a187 bd19b79c8` **均为真**（本次逐条复核）。
+
+**修复行为的证据来源**：源码 + 真库集成测试 `ShareGroupOverlapProjectionIntegrationTest`。
+
+**本文件明确不提供的东西**：测试环境上的修复前/修复后对跑读数。修复 2026-09-19 已合入，测试环境此后一直是修复后状态，不存在可对跑的修复前环境。
+
+**网关侧（2026-09-22 实调）**：经网关 `POST https://api.test.1814.love:9443/admin/fleet/group-dispatch/batches/1/share-groups` → HTTP 200 + 业务码 **600009**（刻意用不存在的 `groupBatchId=1`，在第一道校验即失败关闭）。同轮阴性对照打在一个不存在的路径上 → `code=404`、`接口不存在: POST ...`，与业务码**可分辨**。
+
+⇒ 由此坐实三项：**路由通**（`/admin/fleet/**` → `lb://hl-fleet-service`，无 `/v3` 前缀；带 `/v3` 的变体返回 404）、**鉴权通**（需切换到 `VEHICLE_MANAGER` 角色，权限点 `fleet:group-dispatch:write`）、**请求体反序列化通**（请求驱动到了 `confirm()` 内部的业务校验，而非停在 `@Valid` 阶段）。
+
+⚠️ **这次实调的覆盖边界**：它验的是**端点可达性与契约反序列化**，**没有**验证本次修复的行为本身（同批多个待准入成员不再误报 605001）——那需要真实的团期与派单夹具。修复行为的证据来源见上一条。该请求全程未触达写库路径：`confirm()` 里抛 600009 的 `assertServiceDateInWindow` 位于唯一写库入口 `confirmInTransaction` 之前，且其 javadoc 明确「基线是一次同步 Feign，刻意留在事务外拉」。
+
+## 十、相关文档
+
+- 工单：[wx/HL#7982](https://git.1814.love:8443/wx/HL/issues/7982)
+- 修复 PR：[wx/HL#7983](https://git.1814.love:8443/wx/HL/pulls/7983)（`e7cecb6d7`）
+- 测试补强 PR：[wx/HL#8096](https://git.1814.love:8443/wx/HL/pulls/8096)（`970f9a187`）
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#7982](https://git.1814.love:8443/wx/HL/issues/7982)
+- **PR**: [#7983](https://git.1814.love:8443/wx/HL/pulls/7983)（修复）、[#8096](https://git.1814.love:8443/wx/HL/pulls/8096)（测试）
@@ -0,0 +1,323 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8006"
+title: "团期 staff 保存新增可选入参 scopeRoles，支持按角色范围覆盖"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "not_required"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "2e8850800bc0715c35d77a9496aab39128cf8e64"
+target_release: "v2.1"
+verified_at: "2026-09-22"
+status_note: "backend_status=deployed: hl-order-service-v3 测试服部署 sha=7811104b4，是本单合并提交 094521f0b（PR #8117）的后代，且区间内零提交触及 GroupBatchStaffConfigService（该核验由本工单此前 AC 完成，本会话直接引用，未重新验证）。gateway_status=not_required: git show 094521f0b --stat --name-only 核对，本单改动的 9 个文件全在 hl-order-service-v3 模块内，未涉及 hl-gateway 任何路由/Nacos 配置；PUT /v3/admin/group-batch/{productBatchId}/staff 是存量端点、路径本身未变，命中的是既有通配路由 order-service-v3（predicates: Path=/v3/admin/**，hl-gateway/src/main/resources/application.yml:223，自 #3264 起生效），本单没有引入任何新路径段。frontend_status=pending: mmg/hl-ui 的 origin/v2.1 分支（sha b5666b38，2026-09-22 03:37）src/api/orderV2GroupBatch.js:298 的 saveGroupBatchStaff(groupBatchId, staffList, scopeRoles, config) 已带该参数、GroupBatchStaffConfigModal.vue:256 与 __tests__/GroupBatchStaffConfigModal.spec.js:143 已对接并有断言——这是源码事实，不等于该分支已合并进前端主干或已部署到某个可联调环境；按规范后端不代填 implemented/released/verified，是否完成需前端自行回写 frontend_owner 与 verified_at。 前端回写(2026-09-22, mmg): 正式交接件与 21_8006 已交付实现逐点一致——saveGroupBatchStaff 第三参 scopeRoles 仅非空下发防 400;GroupBatchStaffConfigModal 按配置位 scopeRoles=roleMeta.memberRoles(GUIDE 位含 GUIDE+LEADER 双角色),只提交本位行;582115 拦截链透 message;交付 commit 2e885080,弹窗 6 例+api 1 例全过。零增量代码。"
+updated_at: "2026-09-22"
+base: "dev-v3"
+---
+
+# order-v3: 团期 staff 保存新增可选入参 scopeRoles，支持按角色范围覆盖
+
+> **存放目录**: `changelogs-v2/2026-09/`
+>
+> **服务**: hl-order-service-v3 (端口 8006)
+> **PR**: #8117
+> **Issue**: #8006
+> **日期**: 2026-09-22
+> **影响范围**: 团期 staff 配置保存接口 `PUT /v3/admin/group-batch/{productBatchId}/staff`
+
+---
+
+## ⚠️ 关键变化
+
+`PUT /v3/admin/group-batch/{productBatchId}/staff` 新增**可选**请求体字段 `scopeRoles`（角色范围数组）。**不传时行为与改前逐字一致**（整期全量覆盖：请求体 `staffList` 即为该团期的最终名单，未包含的人员会被移除）。
+
+这不是一个纯粹的新增字段——它同时改变了写入行为的语义边界：团期 staff 实际按**配置位**分两个弹窗维护（导游位 = GUIDE + LEADER、摄影位 = PHOTOGRAPHER）。改前只有"整期全量覆盖"一种写法，任一侧保存时若没有把另一侧的既有行原样带回来，另一侧的人就会被静默清空。传入 `scopeRoles` 后，保存只在声明的角色范围内覆盖，范围外的既有行一行不动。
+
+---
+
+## 一、背景
+
+`order_batch_staff` 表原先的保存语义是"整期全删再全插"：每次 `PUT` 都把该团期名下所有角色的既有行软删，再按请求体重建。团期 staff 页面按配置位分两个弹窗各自维护（导游位 / 摄影位），这就要求任一侧保存时都必须把另一侧的既有行原样带回请求体——漏带一次，另一侧的人就被清空且没有任何提示（工单 #8006 描述的缺陷）。
+
+本单给保存接口加了一条可选的"范围覆盖"路径：传 `scopeRoles` 只软删并重建这些角色的行，其余角色的行不受影响；不传则保持改前的整期全删语义，零行为变化。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 保存团期 staff 配置 | PUT | `/v3/admin/group-batch/{productBatchId}/staff` | 请求体新增可选字段 | 新增 `scopeRoles`（角色范围覆盖），未传时行为不变 |
+
+---
+
+## 三、接口详情
+
+### 1. 保存团期 staff 配置（含扇出） `PUT /v3/admin/group-batch/{productBatchId}/staff`
+
+**VO**: `BatchStaffConfigReqVO → BatchStaffConfigRespVO`
+
+#### 使用场景
+
+团期详情页"导游位""摄影位"两个弹窗各自维护本位人员时调用。改前两个弹窗必须各自把对方弹窗的既有人员原样带回请求体，否则会被整期全删覆盖清空；本次新增 `scopeRoles` 后，每个弹窗可以只声明并提交自己负责的角色范围，互不影响。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| productBatchId | Path | Long | ✅ | 雪花 ID | 产品侧排期 ID（`group_tour_batch.batch_id`，非运营团期主键） |
+| scopeRoles | Body | List\<String\> | ❌（**新增**） | 传了不能是空数组（空数组 400）；元素取值域同 `staffList[].staffRole` | 本次保存覆盖的角色范围。**不传 = 整期全量覆盖**（历史行为，团期内所有角色的既有配置先全删再按 `staffList` 重建）；传了则只在这些角色内覆盖，范围外角色的既有行一行不动。**导游位必须同时传 `GUIDE` 与 `LEADER`**——导游位并收这两个角色，只传其中一个而选了另一个会被拒（582115）。`staffList` 里出现范围外角色一律拒绝且**零写入**（582115） |
+| staffList | Body | List\<Item\> | ✅ | 缺失 400；显式传 `[]` 即清空覆盖范围内的配置 | 覆盖范围内的最终状态。不传 `scopeRoles` 时 `[]` = 清空整期；传了 `scopeRoles` 时 `[]` = 只清空这些角色 |
+| staffList[].staffId | Body | Long | ✅ | - | 用户域员工 ID |
+| staffList[].staffRole | Body | String | ✅ | 取值域：`LEADER`/`GUIDE`/`DRIVER`/`PHOTOGRAPHER`/`OTHER`/`GUIDE_ASSISTANT`/`STUDY_TEACHER`/`LIFE_TEACHER` | 员工角色。若传了 `scopeRoles`，本字段取值必须落在 `scopeRoles` 声明的范围内 |
+| staffList[].sortOrder | Body | Integer | ❌ | 默认 0 | 展示排序 |
+| staffList[].remark | Body | String | ❌ | ≤500 字符 | 备注 |
+
+#### 出参 `Result<BatchStaffConfigRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data.productBatchId | String | 产品侧排期 ID（回显路径参数，雪花号以字符串返回） |
+| data.groupBatchId | String | 运营团期 ID（`order_group_batch` 主键，由 `productBatchId` 反查），本端点 200 响应中恒非 null |
+| data.staffList | Array | **保存后的整期最终状态**（不是本次提交的子集）。不传 `scopeRoles` 时它就是本次提交的名单；传了 `scopeRoles` 时它是覆盖后的整期全量——范围保存的调用方一次拿到完整名单，无需再补一次 GET |
+| data.staffList[].id | String | 记录 ID（雪花号，字符串返回） |
+| data.staffList[].staffId | String | 用户域员工 ID |
+| data.staffList[].staffRole | String | 员工角色（**导游位落库时会按人员真实类型在 GUIDE/LEADER 之间归一**，见四节） |
+| data.staffList[].staffRoleName | String | 员工角色中文名 |
+| data.staffList[].staffName | String | 员工姓名（快照） |
+| data.staffList[].staffPhone | String | 员工手机（脱敏，前 3 后 4） |
+| data.staffList[].avatarUrl | String | 头像 URL（快照，可为 null） |
+| data.staffList[].sortOrder | Integer | 展示排序 |
+| data.staffList[].remark | String | 备注 |
+| data.staffList[].reporterRank | String | 报账人等级：`PRIMARY`/`SECONDARY`/`NONE`，历史空值归一为 `NONE`，恒非 null |
+| data.staffList[].reporterRankName | String | 报账人等级中文名 |
+| data.affectedOrderCount | Integer | 扇出影响的活跃订单数 |
+
+#### 请求示例
+
+```json
+{
+  "scopeRoles": ["PHOTOGRAPHER"],
+  "staffList": [
+    { "staffId": 40002, "staffRole": "PHOTOGRAPHER", "sortOrder": 2, "remark": "新摄影备注" }
+  ]
+}
+```
+
+字段值取自本单已合并的真库集成测试 `GroupBatchStaffSaveConfigScopedMysqlTest#scopedToPhotographer_keepsGuideAndDriverRowsAlive`（该团期夹具此前已有 `staffId=1(LEADER)`、`staffId=4(DRIVER)` 两行存量配置）。
+
+#### 响应示例
+
+按上述请求提交后，该团期同时存在的存量导游位（LEADER）、司机行与本次提交的摄影位行全部回显在 `staffList`（真库断言：`aliveBatchRows(BATCH)` 返回 `["1:LEADER","4:DRIVER","40002:PHOTOGRAPHER"]`，`affectedOrderCount` 取自夹具里挂在该团期下的活跃订单数=1）：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "success": true,
+  "data": {
+    "productBatchId": "8006900",
+    "groupBatchId": "80106",
+    "staffList": [
+      { "id": "9001", "staffId": "1", "staffRole": "LEADER", "staffRoleName": "领队", "staffName": "存量领队", "staffPhone": "138****0001", "avatarUrl": null, "sortOrder": 1, "remark": null, "reporterRank": "NONE", "reporterRankName": "非报账人" },
+      { "id": "770002", "staffId": "40002", "staffRole": "PHOTOGRAPHER", "staffRoleName": "摄影", "staffName": "新摄影", "staffPhone": "139****0002", "avatarUrl": "https://cdn.example/avatar/40002.png", "sortOrder": 2, "remark": "新摄影备注", "reporterRank": "NONE", "reporterRankName": "非报账人" },
+      { "id": "9003", "staffId": "4", "staffRole": "DRIVER", "staffRoleName": "司机", "staffName": "存量司机", "staffPhone": "138****0004", "avatarUrl": null, "sortOrder": 3, "remark": null, "reporterRank": "NONE", "reporterRankName": "非报账人" }
+    ],
+    "affectedOrderCount": 1
+  }
+}
+```
+
+⚠️ 本例按 `BatchStaffConfigRespVO` 字段映射规则重新组装：`id="9001"`/`"9003"` 与除 `avatarUrl`/`remark` 外的其余字段取自该 IT 真实夹具与断言，`staffPhone` 按 `SensitiveDataUtil.maskPhone`（前 3 后 4）逐字计算；新增行的 `id="770002"` 是服务端写入时生成的雪花号，该 IT 只断言了 `staffId:staffRole` 组合、未断言具体 ID 值，本例按字段真实格式（字符串化雪花号）给出示意值，不代表某次具体运行的原始输出。整份响应信封本身未经网关实测捕获（本会话未做该端点的真实网关调用，详见八节）。
+
+#### 空数据 / 降级响应
+
+`scopeRoles` 传了但 `staffList` 传空数组 `[]`：清空该角色范围内的配置，范围外行不受影响。
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "success": true,
+  "data": {
+    "productBatchId": "8006900",
+    "groupBatchId": "80106",
+    "staffList": [
+      { "id": "9001", "staffId": "1", "staffRole": "LEADER", "staffRoleName": "领队", "staffName": "存量领队", "staffPhone": "138****0001", "avatarUrl": null, "sortOrder": 1, "remark": null, "reporterRank": "NONE", "reporterRankName": "非报账人" },
+      { "id": "9003", "staffId": "4", "staffRole": "DRIVER", "staffRoleName": "司机", "staffName": "存量司机", "staffPhone": "138****0004", "avatarUrl": null, "sortOrder": 3, "remark": null, "reporterRank": "NONE", "reporterRankName": "非报账人" }
+    ],
+    "affectedOrderCount": 1
+  }
+}
+```
+
+#### 错误响应
+
+`scopeRoles=["GUIDE"]`，但 `staffList` 里提交了一名真实类型为 `LEADER` 的人员（导游位漏传 `LEADER`）：
+
+```json
+{
+  "code": 582115,
+  "message": "提交的人员角色（LEADER）超出本次保存声明的角色范围（GUIDE），请检查配置位与人员是否匹配",
+  "success": false,
+  "data": null
+}
+```
+
+`scopeRoles` 传空数组 `[]`：
+
+```json
+{
+  "code": 400,
+  "message": "scopeRoles 传了就不能是空数组；要整期全量覆盖请整个字段不传",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- **权限**：网关 `/v3/admin/**` 统一鉴权；本端点额外要求 `GroupBatchPermissionGuard.PERMISSION_MANAGE`（#7455），无权限一律拒绝且**零写入**
+- **不传 `scopeRoles`**：行为与改前逐字一致，整期全量覆盖，现有前端代码零改动即可继续工作
+- **传 `scopeRoles` 但为空数组**：400（`@Size(min=1)` 校验），清空语义只能由 `staffList=[]` 表达，不能用空 `scopeRoles` 表达
+- **导游位并收 GUIDE + LEADER**：`scopeRoles` 只传其中一个、`staffList` 里出现了另一个，一律 582115 且**零写入**（连软删都不执行）
+- **`staffList` 里出现范围外角色**：一律 582115，零写入（两道守卫：一道按请求声明的角色查，另一道按落库后解析出的真实角色再查一遍——导游位人员的 `staffRole` 会按其在资源域的真实类型在 `GUIDE`/`LEADER` 之间归一，只查第一道会漏掉这条）
+- **团期未成团**：589552（已成团但未建团 589553）；两个错误码在本次改动前就存在，未受影响
+- **`staffId` 重复**：589582，整批不写库（改前既有校验，未受影响）
+
+---
+
+## 四、契约约束与正确调用方式
+
+### ✅ 正确 / ❌ 错误 payload 对照
+
+| 场景 | payload |
+|------|---------|
+| ✅ 不传 scopeRoles，整期全量覆盖（历史行为） | `{ "staffList": [...] }` |
+| ✅ 只覆盖摄影位 | `{ "scopeRoles": ["PHOTOGRAPHER"], "staffList": [{ "staffId": 40002, "staffRole": "PHOTOGRAPHER" }] }` |
+| ✅ 只覆盖导游位（必须两个角色一起声明） | `{ "scopeRoles": ["GUIDE", "LEADER"], "staffList": [{ "staffId": 1, "staffRole": "LEADER" }] }` |
+| ✅ 清空摄影位（不动导游位/司机） | `{ "scopeRoles": ["PHOTOGRAPHER"], "staffList": [] }` |
+| ❌ 导游位只传 GUIDE，人员却是 LEADER | `{ "scopeRoles": ["GUIDE"], "staffList": [{ "staffId": 1, "staffRole": "LEADER" }] }` → 582115 |
+| ❌ scopeRoles 传空数组 | `{ "scopeRoles": [], "staffList": [] }` → 400 |
+| ❌ staffList 缺失 | `{ "scopeRoles": ["PHOTOGRAPHER"] }` → 400 |
+
+### 切换到范围保存时的必要动作
+
+若前端按配置位拆分弹窗各自保存，每个弹窗提交时都必须传 `scopeRoles`，且**导游位弹窗必须同时把 `GUIDE` 与 `LEADER` 放进 `scopeRoles`**（哪怕本次提交的人员只有其中一种真实类型）——否则另一种类型的存量人员会在下一次同角色保存时找不到删除窗口，变成无法再被删除的幽灵行。两个弹窗各自只传自己的 `scopeRoles`，不需要互相携带对方的既有名单。
+
+---
+
+## 五、数据库行为
+
+| 场景 | 数据库表 | 操作 |
+|------|----------|------|
+| 不传 scopeRoles（整期全量覆盖） | `order_batch_staff` | 软删该团期全部角色的旧行，再批量 INSERT 新行（与改前逐字一致） |
+| 传 scopeRoles（范围覆盖） | `order_batch_staff` | 只软删 `scopeRoles` 命中角色的旧行，范围外角色的旧行不执行任何 UPDATE/DELETE |
+| 保存成功后 | `order_staff_assignment` | 异步扇出：对团内每个活跃订单，软删该订单 `source=GROUP_BATCH` 的旧行、按**保存后的整期最终状态**重新插入（范围保存时扇出的不是本次提交的子集，而是覆盖后的整期全量，避免把范围内的清空误传播为整期清空） |
+| 校验失败（582115 / 400 等） | - | 零写入：不软删、不 INSERT、不触发扇出 |
+
+---
+
+## 六、边界行为
+
+- **未登录** → 401（网关拦截）
+- **无 `PERMISSION_MANAGE` 权限** → 拒绝，零写入
+- **团期未建团** → 589553；**已建团未成团** → 589552（本次改动前已有校验，未变）
+- **`staffId` 在请求体内重复** → 589582，整批零写入（本次改动前已有校验，未变）
+- **人员角色与资源域真实类型不符**（如把领队配成摄影）→ 582114（本次改动前已有校验，未变）
+- **提交角色超出 scopeRoles 声明范围** → 582115，零写入（本次新增）
+- **老数据兼容**：历史保存请求（不含 `scopeRoles` 字段）解析后 `scopeRoles=null`，服务端按整期全量覆盖处理，与改前行为逐字一致
+
+---
+
+## 六.5、枚举 / 数据字典
+
+### scopeRoles / staffList[].staffRole（`SettlementStaffRoleEnum`）
+
+**所属字段**: `BatchStaffConfigReqVO.scopeRoles`、`BatchStaffConfigReqVO.staffList[].staffRole` | **类型**: `String` / `List<String>`
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `LEADER` | 领队 | 导游位成员之一 |
+| `GUIDE` | 导游 | 导游位成员之一。落库时若该人员资源域真实类型为 `LEADER`，会归一存成 `LEADER` |
+| `DRIVER` | 司机 | 由车务派车投影产生，一般不由本接口写入；不属于任何配置位，不受 scopeRoles 范围校验约束 |
+| `PHOTOGRAPHER` | 摄影 | 摄影位唯一成员 |
+| `OTHER` | 其他 | 兜底位；不属于任何配置位，不受 scopeRoles 范围校验约束 |
+| `GUIDE_ASSISTANT` | 导游助理 | 不属于导游位/摄影位任一配置位 |
+| `STUDY_TEACHER` | 研学老师 | 不属于导游位/摄影位任一配置位 |
+| `LIFE_TEACHER` | 生活老师 | 不属于导游位/摄影位任一配置位 |
+
+---
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 |
+|------|------|------|
+| `staffList`（请求体） | 唯一入参，传入即为整期最终状态 | 不变 |
+| `scopeRoles`（请求体） | 不存在 | **新增可选字段**；不传行为与改前逐字一致 |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| 保存范围 | 恒为整期全量覆盖 | 不传 scopeRoles=整期全量覆盖（不变）；传了 scopeRoles=只覆盖声明的角色 |
+| 跨配置位清空风险 | 任一弹窗保存漏带另一侧既有行 → 另一侧被静默清空 | 各弹窗传各自的 scopeRoles 即可互不影响，不再需要互相携带对方名单 |
+| 提交角色超出范围时 | 无此校验（scopeRoles 不存在） | 582115，零写入 |
+| 扇出快照 | 用的是本次提交的 toInsert | 不传 scopeRoles 时二者相同；传了 scopeRoles 时改为用保存后的**整期最终状态**扇出 |
+
+---
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**：否。`scopeRoles` 是纯新增可选字段，不传时请求/响应结构与既有行为逐字不变，历史前端代码零改动即可继续工作。
+- **前端是否必须同步上线**：否（不采用范围保存可以继续用旧写法）；**但**若要修复"两个弹窗互相清空对方"的问题，前端必须改为按配置位分别传 `scopeRoles`，且导游位弹窗必须把 `GUIDE` 与 `LEADER` 一起传入。
+- **前端 workaround 清理点**：若前端此前用"保存前先 GET 回另一侧既有名单、拼进本次 staffList 一起提交"的方式规避跨配置位清空问题，改用 `scopeRoles` 后可以去掉这个 workaround，弹窗只需提交本位人员。
+
+---
+
+## 七、不影响范围
+
+- **仅影响**：`PUT /v3/admin/group-batch/{productBatchId}/staff` 一个端点的请求体解析与保存范围
+- **零影响**：
+  - `GET /v3/admin/group-batch/{productBatchId}/staff`（查询团期 staff 配置列表）请求/响应结构
+  - `GET /v3/admin/group-batch/{productBatchId}/staff/candidates`、`.../staff/candidates/page`（候选列表/候选分页）
+  - `PUT /v3/admin/group-batch/{productBatchId}/staff/{staffId}/reporter-rank`（设置报账人等级）
+  - 订单侧 staff 增删改接口（`source=ORDER` 的行本次改动前后均不受团期保存的删除窗口影响）
+  - 团期成团判定、四 ready 闸门的判定条件本身（仅回填时改用整期最终状态计算，判定逻辑未变）
+
+---
+
+## 八、测试环境已验证
+
+**后端部署**：`hl-order-service-v3` 测试服部署 sha `7811104b4`，是本单合并提交 `094521f0b`（PR #8117）的后代，且区间内零提交触及 `GroupBatchStaffConfigService`。该核验由本工单此前 AC 完成，本会话直接引用、未重新验证（如实披露）。
+
+**真库集成测试**（`GroupBatchStaffSaveConfigScopedMysqlTest` / `GroupBatchStaffSaveConfigBaselineMysqlTest`，均为 PR #8131 新增，已合入 dev-v3；MySQL 8.0.33 Testcontainers + 真 MyBatis-Plus + 真 `GroupBatchStaffConfigService` Bean，非纯 Mockito）：
+
+- `scopedToPhotographer_keepsGuideAndDriverRowsAlive`：同一份请求体只提交摄影位一人 + `scopeRoles=["PHOTOGRAPHER"]`，导游位（LEADER）与司机的存量行在保存后仍然存活（`deleted_at IS NULL`），订单侧 `order_staff_assignment` 的 `GROUP_BATCH` 副本也保留了这两行；`ready` 回填按整期最终状态计算，触发 `markGuideReady`（因为导游位仍有人）。
+- 阳性对照（Baseline 类同一请求体、不传 `scopeRoles`）：同样的存量导游位/司机行**被整期全删**，`ready` 回填触发的是 `markGuideNotReady`——两轮唯一差异是 `scopeRoles` 字段，终态却完全相反，证明这套断言组合对"范围覆盖是否生效"具备分辨力，不是恒真结论。
+- `BatchStaffConfigReqVOValidationTest`（Bean Validation 层，@Valid 触发路径同 Controller）：`scopeRoles` 不传合法；传合法角色集合通过；传空数组 `[]` 被拒，违规信息命中 `scopeRoles` 字段、消息含"不能是空数组"；传入取值域外的角色被拒，消息含"不在员工角色取值域内"。
+
+**受限说明**：本会话本次未对该端点执行真实网关调用（无该操作所需的测试服管理员会话），三节的请求/响应示例按 `BatchStaffConfigReqVO`/`BatchStaffConfigRespVO` 字段映射规则、依据上述真库 IT 的夹具与断言重新组装，已在三节逐条标注哪些字段取自真实断言、哪些是格式示意值。
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#8006](https://git.1814.love:8443/wx/HL/issues/8006)
+- 关联 PR: [wx/HL#8117](https://git.1814.love:8443/wx/HL/pulls/8117)（后端修复实现）、[wx/HL#8131](https://git.1814.love:8443/wx/HL/pulls/8131)（补充真库集成测试）
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8006](https://git.1814.love:8443/wx/HL/issues/8006)
+- **PR**: [#8117](https://git.1814.love:8443/wx/HL/pulls/8117)
+- **Merge commit**: [094521f0b](https://git.1814.love:8443/wx/HL/commit/094521f0b)
+
+### 联系人
+
+- **后端负责人**: @wx
@@ -0,0 +1,679 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8056"
+title: "TRANSFER-only 订单用车数据静默丢失修复（行程详情 / 确认前置 Checklist）"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修复"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "not_required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "#8056 记录的用车数据丢失共 10 个落点，均已在同一提交（commit 62c28d502，PR #8118）中一并修复并合入 dev-v3，测试环境已部署（hl-order-service-v3@d30cd9561，2026-09-21 21:55:58）。本文逐字段交付其中 3 处：已通过网关实测的两个只读端点（行程详情、确认前置 Checklist），以及经源码核查、本次未做独立网关实测的派单看板列表端点（三、接口详情第 3 节，行为完全由已验证部署的 hl-order-service-v3 驱动，hl-fleet-service 侧代码未改动）；其余落点未在本文展开。前端侧已核实 mmg/hl-ui 对本文相关字段为纯透传渲染，无需改动代码，见六.7。POST /v3/admin/order/{id}/settlement/finalize 的车务车费一致性校验不在本次交接范围内，见七、不影响范围。"
+updated_at: "2026-09-22"
+base: "dev-v3"
+---
+
+# 订单核心服务: TRANSFER-only 订单用车数据静默丢失修复（行程详情 / 确认前置 Checklist）
+
+> **存放目录**: 二期(v3) → `changelogs-v2/2026-09/`
+>
+> **服务**: hl-order-service-v3（主体，第 1/2 节）+ hl-fleet-service（第 3 节派单看板列表；字段结构未变、代码未改动，行为完全由 hl-order-service-v3 侧修复驱动）
+> **PR**: #8118
+> **Issue**: #8056
+> **日期**: 2026-09-22
+> **影响范围**: TRANSFER-only 订单（只提交了接送机用车需求、没有提交行程用车需求）在「订单详情-行程安排 Tab」与「确认订单前置 Checklist」两个只读端点上的用车相关字段；另涉及混合订单（同一订单同时有有效 TRAVEL 与 TRANSFER 需求）在「派单看板列表」端点上的兜底展示行为（见三、接口详情第 3 节）
+
+---
+
+## ⚠️ 关键变化
+
+- **本次变了什么**：`GET /v3/admin/order/{id}/itinerary` 与 `GET /v3/admin/order/{id}/confirm-checklist` 这两个只读端点在 **TRANSFER-only 订单**（只有接送机用车需求、没有行程用车需求）上的用车数据读取逻辑被修复。此前这两个端点把「该读哪一类用车需求」硬编码成了 TRAVEL，TRANSFER-only 订单在这两个口子上查到的用车相关字段恒为空。
+- **前端/调用方以前以为的是什么**：`vehicleGroup: null` + `canContactFleet: false` + `contactFleetDisabledReason: "请先提交有效用车需求后再联系车务"`，或 `confirm-checklist` 里 `VEHICLE_DONE` 项恒 `false`、`failReason` 固定为「未提交用车需求」/「用车需求未完成」——这组返回值此前是**唯一信号**，而且和「这个订单本来就没安排车」在返回结构上完全无法区分：**HTTP 200，无异常，无错误码，字段静默为空/false/固定文案**。
+- **实际现在是什么**：对已提交有效接送机用车需求的 TRANSFER-only 订单，这两个端点现在会返回真实数据（车辆/司机/座位数等），`canContactFleet` 会按实际情况变为 `true`，`confirm-checklist` 的 `allPassed` 在其余 4 项通过时也能正确变为 `true`。**过去在这两个端点上读到的「空」，不代表订单真的没有安排车辆，需要按本次修复后的语义重新核对**，不要沿用旧的「空即无车」假设。
+- **另需知悉（看板新增展示，非新引入缺陷）**：派单看板列表 `GET /admin/fleet/board/orders`（hl-fleet-service，见「三、接口详情」第 3 节）对**混合订单**（同一订单同时存在有效 TRAVEL 与 TRANSFER 需求）新增了一种兜底展示：此前若 TRAVEL 需求处于不可联络状态，整单会从看板消失；本次修复后由 TRANSFER 需求兜底展示一行，订单不再整单消失。「整单消失」本身就是 `#8056` 静默丢数问题的又一种表现，此项是同一次修复顺带解决的，不是新引入的行为回归。
+- `#8056` 记录的用车数据丢失共 10 个落点，均已在同一提交（`62c28d502`）中一并修复并合入 `dev-v3`；本文逐字段交付其中 3 处——已在测试环境网关实测的两个只读端点（行程详情、确认前置 Checklist），以及经源码核查、本次未做独立网关实测的派单看板列表端点（见「三、接口详情」第 3 节）；其余落点未在本文展开。
+
+---
+
+## 一、背景
+
+`VehicleRequirement` 按 `kind` 分为 `TRAVEL`（行程用车）与 `TRANSFER`（接送机用车）两类（#7439 引入）。#8056 修复前，行程详情/确认预览等单值消费点各自把 kind 参数硬编码为 `TRAVEL`，本次收口到 `RequirementService#resolveSingleValueVehicleKind`（TRAVEL 优先，没有 TRAVEL 时回落 TRANSFER）统一解析。
+
+| 维度 | 改前 | 改后 |
+|------|------|------|
+| 用车需求类别解析方式 | 调用点各自硬编码 `VehicleRequirementKind.TRAVEL` | 收口到 `resolveSingleValueVehicleKind`：TRAVEL 优先，无 TRAVEL 时回落 TRANSFER |
+| TRANSFER-only 订单命中查询的结果 | 恒为空（按 TRAVEL 类别查，0 条命中） | 命中回落解析出的 TRANSFER 记录 |
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 订单详情行程安排 Tab | GET | `/v3/admin/order/{id}/itinerary` | 数据修复 | TRANSFER-only 订单的 `vehicleGroup`/`vehicleHistory`/`canContactFleet`/`contactFleetDisabledReason` 不再恒为空/false/固定文案 |
+| 2 | 确认订单前置 Checklist | GET | `/v3/admin/order/{id}/confirm-checklist` | 数据修复 | TRANSFER-only 订单的 `VEHICLE_DONE` 判定与 `preview` 司机栏不再恒判未完成/留空 |
+| 3 | 派单看板列表 | GET | `/admin/fleet/board/orders` | 行为增强（结构未变） | 混合订单（同时有效 TRAVEL 与 TRANSFER 需求）中，若 TRAVEL 需求不可联络，改前整单从看板消失，改后由 TRANSFER 需求兜底展示一行（服务：hl-fleet-service） |
+
+---
+
+## 三、接口详情
+
+### 1. 订单详情行程安排 Tab `GET /v3/admin/order/{id}/itinerary`
+
+**VO**: 无 ReqVO（路径参数 `id`）→ `ItineraryVO`
+
+#### 使用场景
+
+管理后台订单详情页「行程安排」Tab 加载时调用，展示配房组/配车组的需求摘要+实配记录、已失活的配车需求历史，以及「联系房务/车务/团期管理员」按钮的未读消息角标与可用状态。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| id | Path | Long | ✅ | 订单雪花 ID | 订单 ID |
+
+#### 出参 `Result<ItineraryVO>`
+
+顶层字段：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| hotelGroup | HotelGroupVO | 配房需求+实配；本次未改动，结构与既有行为一致 |
+| vehicleGroup | VehicleGroupVO | 配车需求+实配；本次修复的核心字段，见下方子表 |
+| vehicleHistory | List\<VehicleRequirementBriefVO\> | 已失活的配车需求历史（版本倒序）；与 `vehicleGroup` 在同一次请求内按同一个解析出的类别查询，见「业务边界」 |
+| unreadMessageCount | Integer | 「联系房务」按钮未读消息数角标 |
+| fleetUnreadMessageCount | Integer | 「联系车务」按钮未读消息数角标 |
+| groupUnreadMessageCount | Integer | 「联系团期管理员」按钮未读消息数角标 |
+| groupBatchId | String（雪花 ID，字符串序列化） | 运营团期 ID；非团期子订单为 `null` |
+| canContactFleet | Boolean | 是否允许联系车务；本次修复后，TRANSFER-only 订单在存在有效用车需求时为 `true`（此前恒为 `false`） |
+| contactFleetDisabledReason | String | 不可联系车务原因；`canContactFleet=false` 时有值 |
+
+`vehicleGroup`（VehicleGroupVO）：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| requirement | VehicleRequirementBriefVO | 配车需求摘要，见下表 |
+| assignments | List\<VehicleAssignmentVO\> | 实际配车列表，见下表 |
+
+`vehicleGroup.requirement` / `vehicleHistory[]`（VehicleRequirementBriefVO）：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| requirementId | String（雪花 ID） | 需求 ID |
+| version | Integer | 版本号 |
+| status | String | PENDING/PROCESSING/DONE |
+| isActive | Boolean | 是否当前生效版本 |
+| manualUrgent | Boolean | 是否由定制师手动加急 |
+| submittedAt | String（`yyyy-MM-dd HH:mm:ss`） | 提交时间 |
+| returnedAt | String（`yyyy-MM-dd HH:mm:ss`） | 驳回时间；非驳回历史版本为 `null` |
+| returnRemark | String | 驳回原因；非驳回历史版本为 `null` |
+| vehicleTypeSummary | String | 车型摘要，如「商务车×2 / SUV×1」 |
+| passengerCount | Integer | 订单乘车人数 |
+| vehicleCount | Integer | 车辆总数 |
+| totalSeatCount | Integer | 车辆座位总数（含司机座） |
+| driverSeatCount | Integer | 司机占用座位数 |
+| passengerSeatCapacity | Integer | 可载客座位数 |
+| remainingPassengerSeats | Integer | 剩余可载客座位数 |
+| specialTags | List\<String\> | 特殊诉求标签列表 |
+| pickupRequired | Boolean | 兼容回显字段；接机/接站以大交通信息为准 |
+| dropoffRequired | Boolean | 兼容回显字段；送机/送站以大交通信息为准 |
+| remark | String | 备注 |
+
+`vehicleGroup.assignments[]`（VehicleAssignmentVO）：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| assignmentId | String（雪花 ID） | 配车记录 ID |
+| vehicleType | String | 车型（冻结快照） |
+| vehicleCount | Integer | 车辆数（本段） |
+| licensePlate | String | 车牌（冻结快照） |
+| brand | String | 品牌（冻结快照） |
+| seats | Integer | 座位数（冻结快照） |
+| fleetTeamId | String（雪花 ID） | 车辆所属车队 ID |
+| fleetTeamName | String | 车辆所属车队名称 |
+| startDate | String（`yyyy-MM-dd`） | 连续服务开始日期 |
+| endDate | String（`yyyy-MM-dd`） | 连续服务结束日期 |
+| serviceDays | Integer | 连续服务天数（首尾日期均计入） |
+| plannedDailyFee | String（金额，字符串序列化） | 计划日单价 |
+| driverName | String | 司机姓名（冻结快照） |
+| driverPhoneMasked | String | 司机手机（脱敏，格式 `138****1111`） |
+| remark | String | 备注 |
+
+#### 请求示例
+
+```
+GET /v3/admin/order/3401829901234567890/itinerary
+Authorization: Bearer {token}
+```
+
+无请求体。
+
+#### 响应示例
+
+TRANSFER-only 订单，已提交并完成一条接送机用车需求（修复后）：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "hotelGroup": null,
+    "vehicleGroup": {
+      "requirement": {
+        "requirementId": "3401829901234567890",
+        "version": 1,
+        "status": "DONE",
+        "isActive": true,
+        "manualUrgent": false,
+        "submittedAt": "2026-09-10 09:15:00",
+        "returnedAt": null,
+        "returnRemark": null,
+        "vehicleTypeSummary": "商务车7座×1",
+        "passengerCount": 4,
+        "vehicleCount": 1,
+        "totalSeatCount": 7,
+        "driverSeatCount": 1,
+        "passengerSeatCapacity": 6,
+        "remainingPassengerSeats": 2,
+        "specialTags": [],
+        "pickupRequired": true,
+        "dropoffRequired": true,
+        "remark": null
+      },
+      "assignments": [
+        {
+          "assignmentId": "3401830011122334455",
+          "vehicleType": "商务车7座",
+          "vehicleCount": 1,
+          "licensePlate": "京A12345",
+          "brand": "别克GL8",
+          "seats": 7,
+          "fleetTeamId": "40001",
+          "fleetTeamName": "自有车队",
+          "startDate": "2026-09-20",
+          "endDate": "2026-09-20",
+          "serviceDays": 1,
+          "plannedDailyFee": "800.00",
+          "driverName": "王师傅",
+          "driverPhoneMasked": "138****1111",
+          "remark": null
+        }
+      ]
+    },
+    "vehicleHistory": [],
+    "unreadMessageCount": 0,
+    "fleetUnreadMessageCount": 0,
+    "groupUnreadMessageCount": 0,
+    "groupBatchId": null,
+    "canContactFleet": true,
+    "contactFleetDisabledReason": null
+  },
+  "traceId": "a1b2c3d4-e5f6-7890",
+  "success": true
+}
+```
+
+字段名/类型/嵌套结构逐一核对自 `ItineraryVO` 源码；业务数值为示意构造，非测试服原始抓包逐字节留存。
+
+#### 空数据 / 降级响应
+
+订单确实没有提交任何用车需求（TRAVEL 与 TRANSFER 均无）时，`vehicleGroup` 仍合法为 `null`——这是真实的「没有配车」状态，**不是**本次修复要处理的缺陷：
+
+```json
+{
+  "code": 200,
+  "data": {
+    "hotelGroup": null,
+    "vehicleGroup": null,
+    "vehicleHistory": [],
+    "unreadMessageCount": 0,
+    "fleetUnreadMessageCount": 0,
+    "groupUnreadMessageCount": 0,
+    "groupBatchId": null,
+    "canContactFleet": false,
+    "contactFleetDisabledReason": "请先提交有效用车需求后再联系车务"
+  },
+  "success": true
+}
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 581007,
+  "message": "订单不存在",
+  "success": false,
+  "data": null
+}
+```
+
+其余可能的错误码：`581008`「无权查看此订单」（非本单定制师且非超管/管理员/车务管理员）、`581045`「房务角色无权查看订单详情，房务仅可配房」（Controller 层 `OrderViewGuard.assertNotHouseRole()` 反向门禁）。
+
+#### 业务边界
+
+- 鉴权顺序：未登录 → 401（网关拦截）；订单不存在 → 581007；越权查看 → 581008；房务/房务组长角色 → 581045。
+- TRANSFER-only 订单在**没有**有效用车需求时，`vehicleGroup` 仍为 `null`、`canContactFleet` 仍为 `false`——合法状态，见「空数据/降级响应」。
+- **两类需求都存在**（既有 TRAVEL 又有 TRANSFER）的订单：`vehicleGroup`/`vehicleHistory` 仍只反映 TRAVEL 一类，TRANSFER 数据不会出现在这两个字段里，这不是遗留缺陷，是既定的单值契约（见「四、契约约束」）。
+- `vehicleHistory` 与 `vehicleGroup` 在同一次请求内使用同一个解析出的类别，不会出现「当前需求是接送机、变更历史却按行程用车查」的类别错位。
+- 响应体所有 VO 均不暴露 `kind`/`requirementKind` 字段，前端不能从返回值判断当前数据属于 TRAVEL 还是 TRANSFER。
+
+---
+
+### 2. 确认订单前置 Checklist `GET /v3/admin/order/{id}/confirm-checklist`
+
+**VO**: 无 ReqVO（路径参数 `id`）→ `ConfirmChecklistRespVO`
+
+#### 使用场景
+
+管理后台订单详情页点击「确认订单」按钮前调用，用于校验 5 项前置条件（款项/出行人/房型/用车/合同方案）是否全部满足；全部满足时同时返回确认弹框的预览数据。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| id | Path | Long | ✅ | 订单雪花 ID | 订单 ID |
+
+#### 出参 `Result<ConfirmChecklistRespVO>`
+
+顶层字段（`allPassed` 为唯一开关，`items`/`preview` 互斥）：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| allPassed | Boolean | 是否全部通过；`true` 时 `items=null`、`preview` 有值，`false` 时 `items` 有值、`preview=null` |
+| items | List\<ChecklistItemVO\> | 5 项详细结果，仅 `allPassed=false` 时返回 |
+| preview | PreviewVO | 确认弹框预览数据，仅 `allPassed=true` 时返回 |
+
+`items[]`（ChecklistItemVO）：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| code | String | 检查项代码：`PAYMENT_OK`/`TRAVELER_COMPLETE`/`HOTEL_DONE`/`VEHICLE_DONE`/`CONTRACT_TEMPLATE_OK` |
+| checkName | String | 检查项中文名称 |
+| passed | Boolean | 是否通过 |
+| failReason | String | 未通过原因；通过时为 `null` |
+
+`preview`（PreviewVO）：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| departureDate | String（`yyyy-MM-dd`） | 出发日期 |
+| totalPeopleCount | Integer | 总出行人数 |
+| driverName | String | 司机姓名；本次修复后 TRANSFER-only 订单在有对应配车记录时正确回填（此前恒为 `null`） |
+| driverPhoneMasked | String | 司机手机（脱敏）；同上 |
+| hotels | List\<HotelSummaryVO\> | 酒店列表（按行程城市分组） |
+| staffs | List\<StaffItemVO\> | 本单配置人员列表（报账人 PRIMARY 排首） |
+| contractAutoAction | ContractAutoActionVO | 确认后自动生成合同副作用 |
+| insuranceAutoAction | InsuranceAutoActionVO | 确认后自动投保副作用 |
+
+`preview.hotels[]`（HotelSummaryVO）：`cityName`（String，城市名）、`hotelName`（String，酒店名）。
+
+`preview.staffs[]`（StaffItemVO）：`assignmentId`（String 雪花 ID）、`staffId`（String 雪花 ID）、`staffName`（String）、`staffPhone`（String，脱敏）、`staffRole`（String，`DRIVER`/`LEADER`/`GUIDE`/`PHOTOGRAPHER`/`OTHER`）、`staffRoleName`（String）、`isPrimaryReporter`（Boolean）。
+
+`preview.contractAutoAction`（ContractAutoActionVO）：`planName`（String）、`autoSign`（Boolean）。
+
+`preview.insuranceAutoAction`（InsuranceAutoActionVO）：`planName`（String）、`peopleCount`（Integer）、`effectiveDescription`（String）。
+
+#### 请求示例
+
+```
+GET /v3/admin/order/3401829901234567890/confirm-checklist
+Authorization: Bearer {token}
+```
+
+无请求体。
+
+#### 响应示例
+
+TRANSFER-only 订单，接送机用车需求已完成、其余 4 项也已满足（修复后 `allPassed` 可正确为 `true`）：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "allPassed": true,
+    "items": null,
+    "preview": {
+      "departureDate": "2026-09-20",
+      "totalPeopleCount": 4,
+      "driverName": "王师傅",
+      "driverPhoneMasked": "138****1111",
+      "hotels": [],
+      "staffs": [
+        {
+          "assignmentId": "1234567890123456789",
+          "staffId": "9876543210987654321",
+          "staffName": "王师傅",
+          "staffPhone": "138****1111",
+          "staffRole": "DRIVER",
+          "staffRoleName": "司机",
+          "isPrimaryReporter": false
+        }
+      ],
+      "contractAutoAction": {
+        "planName": "标准接送机方案 v1.0",
+        "autoSign": true
+      },
+      "insuranceAutoAction": {
+        "planName": "安联境内旅行险 · 尊享版",
+        "peopleCount": 4,
+        "effectiveDescription": "出发前 24h 内生效"
+      }
+    }
+  },
+  "traceId": "a1b2c3d4-e5f6-7890",
+  "success": true
+}
+```
+
+字段名/类型/互斥结构逐一核对自 `ConfirmChecklistRespVO` 源码；业务数值为示意构造，非测试服原始抓包逐字节留存。
+
+#### 空数据 / 降级响应
+
+同一批 TRANSFER-only 订单，用车已判定完成但**其余项尚未满足**（例如合同方案未配置）——修复只纠正用车判定本身，不代表订单必然可确认：
+
+```json
+{
+  "code": 200,
+  "data": {
+    "allPassed": false,
+    "items": [
+      { "code": "PAYMENT_OK", "checkName": "款项校验", "passed": true, "failReason": null },
+      { "code": "TRAVELER_COMPLETE", "checkName": "出行人信息", "passed": true, "failReason": null },
+      { "code": "HOTEL_DONE", "checkName": "房型安排", "passed": true, "failReason": null },
+      { "code": "VEHICLE_DONE", "checkName": "用车安排", "passed": true, "failReason": null },
+      { "code": "CONTRACT_TEMPLATE_OK", "checkName": "合同方案配置", "passed": false, "failReason": "未配置合同方案" }
+    ],
+    "preview": null
+  },
+  "success": true
+}
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 581007,
+  "message": "订单不存在",
+  "success": false,
+  "data": null
+}
+```
+
+其余可能的错误码：`581008`「无权查看此订单」、`581045`「房务角色无权查看订单详情，房务仅可配房」。
+
+#### 业务边界
+
+- 鉴权同「订单详情行程安排 Tab」：581007/581008/581045。
+- `allPassed`/`items`/`preview` 三者互斥，前端渲染前先判 `allPassed`，不要同时依赖 `items` 与 `preview` 都非空。
+- TRANSFER-only 订单不需要用车（`needsVehicle=false`）或所在团整团免车时，`VEHICLE_DONE` 项直接通过，不受本次修复影响。
+- `preview.driverName`/`driverPhoneMasked` 只在能定位到「当前 active 用车需求绑定的配车记录」时才回填；团车合法缺席场景下该两个字段合法为 `null`，不是异常。
+- `POST /v3/admin/order/{id}/settlement/finalize` 的车务车费一致性校验**不在本次修复范围内**（见七、不影响范围），`confirm-checklist` 返回 `allPassed=true` 不代表 `settlement/finalize` 一定会成功，前端仍需按其可能返回业务失败码处理。
+
+---
+
+### 3. 派单看板列表 `GET /admin/fleet/board/orders`
+
+**VO**: `BoardOrderPageReqVO → BoardOrderPageRespVO`
+
+> 本端点属于 **hl-fleet-service**（不是 hl-order-service-v3），经网关 `Path=/admin/fleet/**` 路由（`hl-gateway/application.yml:230-233`，无 `StripPrefix`），前端可直接调用；路径本身早于 `#8056` 修复即已存在（既有派单看板契约）。本次收录的行为变化完全来自其上游依赖 hl-order-service-v3 的 `OrderFleetProviderService#batchFleetBoardContexts`（同一修复提交 `62c28d502`），**hl-fleet-service 自身代码本次未改动**（全仓 grep `8056` 零命中），不需要为此单独重新部署 hl-fleet-service。
+
+#### 使用场景
+
+车务派单看板列表页首次加载/翻页/筛选时调用，按当前有效用车需求展示订单及其派车进度。
+
+#### 入参字段表
+
+本次修复**未修改**该端点任何入参字段（`BoardOrderPageReqVO` 源码本轮未改动），以下为现状字段，供核对结构未变：
+
+| 字段 | 位置 | 类型 | 必填 | 说明 |
+|------|------|------|------|------|
+| statuses | Query | String[] | 否 | 多状态筛选（含派生态，后端翻译），空=不过滤 |
+| status | Query | String | 否 | 状态筛选别名（单值/逗号分隔），与 statuses 合并 |
+| startDayFrom / startDayTo | Query | LocalDate（`yyyy-MM-dd`） | 否 | 行程区间 `[start_date,end_date]` 重叠筛选 |
+| startDate / endDate | Query | LocalDate（`yyyy-MM-dd`） | 否 | startDayFrom/startDayTo 别名，未传前者时生效 |
+| vehicleTypeKeys / typeKeys | Query | String[] | 否 | 车型大类多选：`suv`/`mpv`/`bus`/`sedan` |
+| driverName | Query | String | 否 | 司机姓名模糊搜索 |
+| keyword | Query | String | 否 | 统一文字搜索（司机/联系人/团号/订单号/定制师显示名任一包含） |
+| contactName / contactKeyword | Query | String | 否 | 联系人/客户名模糊搜索 |
+| teamNo | Query | String | 否 | 团号模糊搜索（仅真实团号，不匹配订单号） |
+| groupBatchId | Query | Long | 否 | 运营团期精确筛选 |
+| consultantId | Query | Long | 否 | 定制师精确筛选（下拉值） |
+| plannerName / consultantName | Query | String | 否 | 定制师姓名模糊搜索（兼容旧前端） |
+| variant | Query | String | 否 | `list`（默认）/`grid`，其余值返 100001 |
+| page | Query | Integer | 否 | 页码，默认 1，最小 1 |
+| pageSize | Query | Integer | 否 | 每页条数，默认 20，最大 100 |
+
+#### 出参字段表
+
+`BoardOrderPageRespVO`（**结构未变**，`records`/`total`/`page`/`pageSize` 平级）：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| records | List\<BoardOrderRecordVO\> | 当前页记录（确定性排序：紧急组置顶→常规→终态沉底→id 兜底） |
+| total | Long | 总条数（筛选后全量） |
+| page | Integer | 当前页码 |
+| pageSize | Integer | 每页条数 |
+
+`records[]`（`BoardOrderRecordVO`，**结构未变**；完整字段清单见既有契约 FLEET v1.5 §6.1，本次不重复列出，仅摘录与本次行为变化直接相关的字段）：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| orderId | String（雪花，字符串序列化） | 订单 ID |
+| requirementId | String（雪花） | 当前代表本行的用车需求 ID；混合订单在 TRAVEL 不可联络时，本次修复后该字段可能改为指向 TRANSFER 需求，见「业务边界」 |
+| dailySummary | BoardDailySummaryVO | 代表日行摘要，随 `requirementId` 所属需求联动 |
+
+#### 请求示例
+
+```
+GET /admin/fleet/board/orders?page=1&pageSize=20&statuses=unassigned
+Authorization: Bearer {token}
+```
+
+无请求体。
+
+#### 响应示例
+
+混合订单（同时有 TRAVEL 与 TRANSFER 需求，TRAVEL 处于不可联络状态、TRANSFER 可联络）兜底展示出的一行：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "records": [
+      {
+        "id": "HL202609200001",
+        "orderNo": "HL202609200001",
+        "orderId": "3401829901234567890",
+        "requirementId": "3401829901234599102"
+      }
+    ],
+    "total": 1,
+    "page": 1,
+    "pageSize": 20
+  },
+  "traceId": "a1b2c3d4-e5f6-7890",
+  "success": true
+}
+```
+
+字段名/类型逐一核对自 `BoardOrderRecordVO` 源码；为避免与既有契约重复，本示例只展示与本次行为变化直接相关的字段，其余字段结构未变、照旧下发，未在本例中重复列出；业务数值为示意构造，非测试服原始抓包逐字节留存（本端点本次未做独立网关实测，见「八、测试环境已验证」后的说明）。
+
+#### 空数据 / 降级响应
+
+订单没有任何满足 `isFleetBoardRequirement` 条件的活跃需求时，该订单不进入 `records`（既有行为，本次未改动）：
+
+```json
+{
+  "code": 200,
+  "data": { "records": [], "total": 0, "page": 1, "pageSize": 20 },
+  "success": true
+}
+```
+
+order-v3 整体不可达时，`OrderQueryFacade#getFleetBoardContextsOrNull` 返回 `null`，服务按既有降级路径回退到 fleet 本地派单快照渲染（该降级路径本次未改动）。
+
+#### 错误响应
+
+```json
+{
+  "code": 100001,
+  "message": "参数非法",
+  "success": false,
+  "data": null
+}
+```
+
+`variant` 传非 `list`/`grid` 时触发上述 100001；未登录 → 401（网关拦截）。
+
+#### 业务边界
+
+- **定性为改进，不是回归**：改前，混合订单若 TRAVEL 需求处于不可联络状态（`RequirementStatus.isFleetContactable` 判 `false`，仅 `PENDING`/`PROCESSING`/`DONE` 判 `true`），整单从看板消失——车务完全看不到该订单，且没有任何错误信号；这属于 `#8056` 静默丢数问题的又一种表现。改后由 TRANSFER 需求兜底展示一行，混合订单不再整单消失。
+- **可达性如实说明**：当前数据下，触发该兜底所需的两个条件（TRAVEL 不可联络 ∧ TRANSFER 可联络）在同一订单上的交集为 **0 条**；但两个子条件各自都有样本（TRAVEL 处于 `PENDING_REVIEW` 态：30 条；TRANSFER 可联络：88 条），交集为空是当前数据的**巧合**，不是结构性约束——没有任何机制阻止同一订单同时满足这两个条件。当前同时存在有效 TRAVEL 与 TRANSFER 需求的混合订单共 25 单。
+- **两类需求各自独立查询、独立判歧义**（`OrderFleetProviderService.java:242-276`），不是合并成一次查询——这是刻意保留的既有行为：合并查询会让两类并存的订单拿到 2 条、被 `size()==1` 判为歧义而整单掉出看板，那会是对行程用车（TRAVEL）看板行为的回归。
+- `records[]` 出参结构未变，字段来自 TRAVEL 还是 TRANSFER 需求对前端不可见（响应体不暴露 `kind`/`requirementKind` 字段，与「三、接口详情」第 1/2 节一致）。
+- 前端渲染该行为完全数据驱动；对 `mmg/hl-ui` 的 `src/views/fleet/` 目录的穷举 grep（证据见「六.7、影响评估」）未发现任何按用车需求种类分支的代码，本行为变化不要求前端改动。
+- 同一订单同一类别（TRAVEL 或 TRANSFER）内存在多条活跃需求时，该类别整体被判定为歧义并跳过（记 warn 日志），不会猜测采用哪一条；这与「四、契约约束」中单值端点 `resolveSingleValueVehicleKind` 的歧义处理是两套独立实现，互不影响。
+
+---
+
+## 四、契约约束与正确调用方式
+
+> 本节只写后端在「该读哪一类用车需求」上的实际行为，不写 UI 渲染建议。
+
+### ✅ 正确 / ⚠️ 需注意 理解对照
+
+| 场景 | 说明 |
+|------|------|
+| ✅ TRANSFER-only 订单（只有接送机用车需求） | 这两个端点现在会读到该订单的 TRANSFER 需求数据 |
+| ✅ TRAVEL-only 订单（只有行程用车需求） | 行为不变，仍读 TRAVEL 数据 |
+| ⚠️ 两类需求都存在的订单（既有行程用车又有接送机用车） | 这两个端点**仍然只返回 TRAVEL 数据**，不会合并展示 TRANSFER；这不是本次修复遗留的缺陷，是既定的单值契约，不要据此误判为「接送机数据又丢了」 |
+| ❌ 试图从响应中读取 `kind`/`requirementKind` 字段区分当前数据属于哪一类 | 两个端点的响应 VO 都不暴露该字段（见「三、接口详情」出参表），无法从返回值本身判断 |
+| ⚠️ 派单看板列表（`GET /admin/fleet/board/orders`，见「三、接口详情」第 3 节）的 TRAVEL 优先/TRANSFER 兜底 | 与本节两个单值端点所用的 `resolveSingleValueVehicleKind` 是**两套独立实现**（看板按 TRAVEL/TRANSFER 两类分别查询、分别判歧义，见 `OrderFleetProviderService.java:242-276`），不要假设两者共用同一份解析逻辑或行为完全对称 |
+
+### 为什么是「优先」而不是「合并」
+
+这两个端点的响应契约是**单值**的（一条需求、一个 requirementId、一组司机车辆），容不下两类数据同时返回。两类需求都存在时，返回值逐字段与修复前一致（仍是 TRAVEL）；只有「TRAVEL 那类根本不存在」的订单（即 TRANSFER-only 订单）行为发生变化。
+
+### 请求侧无需改动
+
+两个端点均为 `GET` + 路径参数 `id`，请求方式、Header、鉴权方式本次均未改动，无需修改请求代码；本次改动只影响响应体里用车相关字段的取值。
+
+---
+
+## 五、数据库行为
+
+两个端点均为只读 `GET`，不接受请求体，不写库。本次修复只改变了读取用车需求时选择的类别（TRAVEL/TRANSFER），不引入、不修改任何写入行为。
+
+---
+
+## 六、边界行为
+
+- 未登录 → 401（网关拦截）
+- 订单不存在 → 581007
+- 越权查看（非本单定制师且非超管/管理员/车务管理员）→ 581008
+- 房务/房务组长角色查看这两个只读端点 → 581045（`OrderViewGuard.assertNotHouseRole()`）
+- 订单确实没有任何用车需求（TRAVEL 与 TRANSFER 均无）→ 两个端点均按「没有配车」的合法状态返回（见「三、接口详情」空数据/降级响应），不是异常
+- 团车合法缺席（非 DAILY_V3 契约 + 团级配车完成）→ `confirm-checklist` 的 `VEHICLE_DONE` 项照常通过，但 `preview.driverName`/`driverPhoneMasked` 合法留空
+
+---
+
+## 六.5、枚举 / 数据字典
+
+`VehicleRequirementKind`（`TRAVEL`/`TRANSFER`）是本次修复涉及的分类依据，但**不是**任何请求/响应字段的显式取值——`ItineraryVO`/`ConfirmChecklistRespVO` 及其全部嵌套 VO 均不暴露 `kind`/`requirementKind` 字段（见「四、契约约束」）。因此本节不适用于字段级枚举值表；`TRAVEL`/`TRANSFER` 的选择规则见「四、契约约束」。
+
+---
+
+## 六.6、修改前后对比
+
+### 字段级对比（均限定为 TRANSFER-only 订单场景）
+
+| 字段 | 改前 | 改后 |
+|------|------|------|
+| `itinerary.vehicleGroup` | 存在有效接送机用车需求时仍恒为 `null` | 存在有效需求时返回真实的 `requirement`+`assignments` |
+| `itinerary.canContactFleet` | 恒为 `false` | 存在有效需求时为 `true` |
+| `itinerary.contactFleetDisabledReason` | 恒为「请先提交有效用车需求后再联系车务」（误导：需求已提交，只是类别没读到） | 存在有效需求时为 `null` |
+| `itinerary.vehicleHistory` | 按 TRAVEL 类别查询，恒为空数组（即使 TRANSFER 侧有历史驳回记录） | 按订单实际单值类别（TRAVEL 优先/TRANSFER 回落）查询 |
+| `confirm-checklist.items[code=VEHICLE_DONE].passed` | 用车已实际完成时仍为 `false` | 正确反映实际完成状态 |
+| `confirm-checklist.items[code=VEHICLE_DONE].failReason` | 恒为「未提交用车需求」（误导） | 用车确已完成时该 item 不再出现在 `items`（因 `allPassed` 可能变为 `true`） |
+| `confirm-checklist.allPassed` | 即使其余 4 项都通过也恒为 `false`（被 VEHICLE_DONE 拖累） | 5 项均满足时可正确为 `true` |
+| `confirm-checklist.preview.driverName` / `driverPhoneMasked` | 恒为 `null` | 有对应配车记录时正确回填 |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| TRANSFER-only 订单在行程 Tab 展示配车信息 | 页面表现为「没有安排车辆」（实际已安排） | 正确展示已安排的车辆/司机信息 |
+| TRANSFER-only 订单发起「确认订单」 | 恒被 VEHICLE_DONE 项拦截，无法确认 | 用车确已完成且其余项满足时可正常确认 |
+| 失败可见性 | 无异常、无错误码，HTTP 200，字段静默为空/false，与「真的没安排车」无法区分 | 同样 HTTP 200，但字段现在反映真实数据 |
+| 混合订单（同时有效 TRAVEL 与 TRANSFER 需求）在派单看板列表，TRAVEL 需求处于不可联络状态时 | 整单从看板消失，车务完全看不到该订单（`#8056` 静默丢数的又一种表现，无任何错误信号） | 由 TRANSFER 需求兜底展示一行，字段来自 TRANSFER 需求；订单不再消失（见「三、接口详情」第 3 节） |
+
+---
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 否——响应结构（字段名、类型、层级）未变，只是同一批字段在 TRANSFER-only 订单上的取值范围从「恒为空/false/固定文案」变为「反映真实数据」。TRAVEL-only 订单与两类都没有活跃需求的订单，这两个端点的返回值逐字段不变。派单看板列表端点（第 3 节）同理：`BoardOrderPageRespVO`/`BoardOrderRecordVO` 字段结构未变，只是混合订单在特定条件下代表行从「整单消失」变为「TRANSFER 需求兜底展示一行」。
+- **前端是否必须同步上线**: 否——已核实管理后台前端对本文相关字段是纯透传渲染，无需任何代码改动即可直接受益于修复后的数据，核实依据见下方「前端 workaround 清理点」。
+- **前端 workaround 清理点（管理者已对 `mmg/hl-ui` 代为核实，转录核实结果供核对）**：查证对象为 **origin ref**（非本地树；本地树落后 520 个提交，若沿用会得出过时/错误结论），基线 `origin/v2.1 @ 56dc9455`（2026-09-22 提交，2026-09-22 读取）。核实结果：
+  - `src/views/order-v2/detail/_shared/v3Adapter.js:1007-1008`——`canContactFleet`/`contactFleetDisabledReason` 是直接透传映射，无分支逻辑。
+  - `src/views/order-v2/detail/components/VehicleArrangeCard.vue:434,437`——`canContactFleet === false` 时禁用按钮并展示 `contactFleetDisabledReason || '请先提交有效用车需求后再联系车务'`，纯数据驱动。
+  - `src/views/order-v2/detail/modals/FunItemAdjustModal.vue:2559-2560`——同样的透传模式。
+  - `src/views/order-v2/detail/_shared/confirmChecklistActions.js:5`——`VEHICLE_DONE` 只映射到 `{label:'查看配车', tab:'arrange'}`，不参与通过/未通过的判定逻辑。
+  - **负控**：对该仓库 `src/views/order-v2/detail/` 与 `src/views/fleet/` 目录穷举 grep `TRANSFER|接送机`，全部命中均与本缺陷无关（`BANK_TRANSFER` 支付渠道、`CONSULTANT_TRANSFER`/`HOUSE_TRANSFER` 时间线事件类型、`transport.transferTimeHint`）——**零命中**专门针对 `VehicleRequirementKind.TRANSFER` 的分支代码；`src/views/fleet/` 属于派单看板前端所在目录，该负控同时覆盖「三、接口详情」第 3 节的前端影响判断。
+  - **结论**：管理后台前端对这一批字段（含派单看板列表相关字段）是纯透传渲染，不存在针对本缺陷写过的 workaround/特判代码，无需任何前端改动。
+
+---
+
+## 七、不影响范围
+
+- **仅影响**: `GET /v3/admin/order/{id}/itinerary` 与 `GET /v3/admin/order/{id}/confirm-checklist` 两个只读端点在 **TRANSFER-only 订单**上的用车相关字段；以及 `GET /admin/fleet/board/orders`（hl-fleet-service）在**混合订单**（同时有效 TRAVEL 与 TRANSFER 需求）上的代表行兜底展示行为（见「三、接口详情」第 3 节）。
+- **零影响**:
+  - 纯 TRAVEL（行程用车）订单，或两类需求都没有的订单：这两个端点的返回值逐字段不变。
+  - 两类需求都存在（既有 TRAVEL 又有 TRANSFER）的订单：仍只返回 TRAVEL 数据（见「四、契约约束」），本次修复不改变这类订单在这两个端点上的表现。
+  - `POST /v3/admin/order/{id}/settlement/finalize` 的车务车费一致性校验：**不在本次修复范围内**，前端仍需按其可能返回业务失败码（如 `584100`「车务车辆总车费暂时不可用，请稍后重试」）处理，不能假设该接口现在必然成功。
+  - `#8056` 记录的用车数据丢失共 10 个落点，均已在同一提交（`62c28d502`）中一并修复并合入 `dev-v3`；本文逐字段交付其中 3 处（两个网关实测的只读端点 + 一个源码核查的派单看板列表端点，见「三、接口详情」），其余落点未在本文展开。
+
+---
+
+## 八、测试环境已验证
+
+```
+部署版本：hl-order-service-v3 @ d30cd9561（2026-09-21 21:55:58 部署，经 git merge-base --is-ancestor 确认包含修复提交 62c28d502）
+
+GET https://api.test.1814.love:9443/v3/admin/order/{id}/itinerary
+  TRANSFER-only 订单（仅接送机用车需求、无行程用车需求）：
+  vehicleGroup.assignments 返回真实配车记录（含 assignmentId/车型/车牌/座位数/司机姓名/脱敏手机号/服务天数），
+  此前该字段为空数组 ✓
+
+GET https://api.test.1814.love:9443/v3/admin/order/{id}/confirm-checklist
+  同一批 TRANSFER-only 订单：allPassed 可正确为 true；
+  此前恒被 VEHICLE_DONE 项拦截，failReason 固定为「未提交用车需求」/「用车需求未完成」✓
+```
+
+> 「三、接口详情」第 3 节（派单看板列表 `GET /admin/fleet/board/orders`）**本次未做独立网关实测**，未列入上表。该行为变化完全依赖已验证部署的 hl-order-service-v3@d30cd9561（含同一提交 `62c28d502`）；hl-fleet-service 侧代码本身未改动（全仓 grep `8056` 零命中），故不需要 hl-fleet-service 单独部署即可生效，见第 3 节开头说明。
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#8056](https://git.1814.love:8443/wx/HL/issues/8056)
+- 关联 PR: [wx/HL#8118](https://git.1814.love:8443/wx/HL/pulls/8118)
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8056](https://git.1814.love:8443/wx/HL/issues/8056)
+- **PR**: [#8118](https://git.1814.love:8443/wx/HL/pulls/8118)
+- **Merge commit**: [62c28d502](https://git.1814.love:8443/wx/HL/commit/62c28d502)
+
+### 联系人
+
+- **后端负责人**: @wx
@@ -0,0 +1,206 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8070"
+title: "应付款建议清单/统计页切流读推送台账，出参补 applied/paid/owed 口径字段"
+consumer: "admin"
+author: "yst(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "not_required"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "7fa22462cb04658b36bfa2370c9e8673bcf289ab"
+target_release: "v2.1"
+verified_at: "2026-09-22"
+status_note: "backend_status: deployed - hl-order-service-v3 已部署测试服（dev-v3，含 finance 同进程），Epic #8070 三轮 E2E PASS + 最终验收已交付（2026-09-21 取证）; gateway_status: not_required - 零网关改动，/admin/finance/** 走 hl-gateway 既有通配路由; frontend_status: pending - 前端适配情况未知，后端不代填。 前端核验(2026-09-22): #7396/#7398 交付时已消费 appliedAmount/owedAmount 并处理 eligible 禁勾+eligibleReason 直显,台账口径切换纯服务端零行为增量;唯一冲突为旧注释「欠付后端保证非负」,已订正为 owed 可为负=多付(PayableStatsList.vue 头注+payable.js 三态注释),owedAmount 全消费点 money() 纯展示无钳制;ref=hl-admin 7fa22462(docs 注释订正,checkpoint 全量 13 项全绿)。"
+updated_at: "2026-09-22"
+base: "dev-v3"
+---
+
+# 财务：应付款建议清单/统计页切流读推送台账（Epic #8070 PR-5）
+
+> 应付款「申请建议清单」与「按供应商/按团统计」接口的数据源由实时扫订单切换为读应付款推送台账（`fin_payable_line/team/supplier` 三表），出参补充申请中/已付/欠款口径字段，并前置台账锁定闸。
+
+## ① 接口背景
+
+应付款域此前「建议清单」「统计页」靠实时聚合订单/配房/行程节点数据计算，口径分散、与台账不一致。Epic #8070 建立应付款推送台账星型模型（明细行 `fin_payable_line` + 团头 `fin_payable_team` + 供应商头 `fin_payable_supplier`），订单确认/配房确认即推送台账。PR-5 把**读侧**（申请建议清单 + 统计页）切流到台账，让申请、审批、统计共用同一套 applied（申请中）/paid（已付）/owed（欠款）口径，并加 `isLocked` 前置闸（审批中行锁定禁重复申请）。
+
+## ② 变更清单
+
+| 类型 | 接口 | 变更 |
+|---|---|---|
+| 修改 | `GET /admin/finance/payments/suggestion` 申请建议清单 | 数据源切台账；行出参补口径/资格字段 |
+| 修改 | `GET /admin/finance/payments/stats/by-supplier` 按供应商统计 | 数据源切台账头表；出参补 applied/owed |
+| 修改 | `GET /admin/finance/payments/stats/by-team` 按团统计 | 数据源切台账头表；出参补 applied/owed |
+
+> 申请/审批写入侧（建单占用 applied、付讫转 paid、驳回释放）同步切台账，属内部实现，接口签名不变。
+
+## ③ 接口详情
+
+### 3.1 申请建议清单
+
+```
+GET /admin/finance/payments/suggestion?...
+```
+
+返回可申请的应付款明细行（来自台账 NORMAL 行），每行带是否可申请资格与原因，已被申请占用或审批锁定的行不可重复申请。
+
+### 3.2 按供应商统计 / 按团统计
+
+```
+GET /admin/finance/payments/stats/by-supplier?...
+GET /admin/finance/payments/stats/by-team?...
+```
+
+返回台账头表聚合的应付/申请中/已付/欠款四口径，与明细行求和一致。
+
+## ④ 入参
+
+入参字段与旧版一致（分页 + 既有筛选条件），无新增/无删除。
+
+## ⑤ 出参
+
+### 5.1 建议清单行 `PaymentSuggestionRowVO`（关键字段）
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `sourceType` | string | 来源类型（配房/行程节点等） |
+| `sourceId` | Long(string) | 来源单据 ID |
+| `resourceId` / `resourceName` | Long / string | 资源 ID / 名称 |
+| `qty` / `unitPrice` / `amount` | number | 数量 / 单价 / 应付金额 |
+| `payWay` | string | 付款方式 |
+| `paymentType` | string | 付款类型（fin_payment_type 字典标签） |
+| `supplierId` / `supplierName` | Long / string | 供应商 ID / 名称（降级行可空） |
+| `payeeAccountId` | Long(string) | 供应商生效收款账户 |
+| `eligible` | boolean | 是否可申请（false 时看 `eligibleReason`） |
+| `eligibleReason` | string | 不可申请原因（已占用/审批锁定/无价等） |
+| `alreadyGenerated` | boolean | 是否已生成付款单 |
+
+### 5.2 按供应商统计行 `PaymentStatsBySupplierRowVO`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `supplierId` / `supplierName` | Long / string | 供应商 ID / 名称 |
+| `category` | string | 类别（fin_payment_type 字典标签） |
+| `payableAmount` | number | 应付总额 |
+| `appliedAmount` | number | **申请中金额（新增/真值化）** |
+| `paidAmount` | number | 已付金额 |
+| `owedAmount` | number | **欠款 = 应付 − 已付（可为负=多付）** |
+| `teamCount` | int | 涉及团数 |
+| `status` | string | 状态 |
+
+### 5.3 按团统计行 `PaymentStatsByTeamRowVO`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `teamNo` | string | 团号 |
+| `productName` / `customerName` / `orderNos` | string | 产品 / 客户 / 订单号 |
+| `departDate` / `returnDate` | string(date) | 出团 / 回团日期 |
+| `payableAmount` | number | 应付总额 |
+| `appliedAmount` | number | **申请中金额（新增/真值化）** |
+| `paidAmount` | number | 已付金额 |
+| `owedAmount` | number | **欠款 = 应付 − 已付** |
+| `supplierCount` | int | 涉及供应商数 |
+| `status` | string | 状态 |
+
+## ⑥ 枚举/数据字典
+
+- `paymentType` / `category` 走 `fin_payment_type` 字典标签：住宿 / 门票·游玩 / 餐食 / 车辆 / 导游 / 摄影 / 保险 / 其他支出 / 退款 / 其他应付。
+- 台账行 `line_type`：`NORMAL` 正常 / `CLOSED` 红冲（建议清单只出 NORMAL）。
+- 台账行 `close_status` / `recover_status` 为内部治理字段，不外透出参。
+
+## ⑦ 错误码
+
+本批为读侧切流，无新增对外错误码。台账推送/占用相关错误码（5996xx 段）见既有应付款推送台账 changelog。
+
+## ⑧ 示例
+
+### 8.1 按供应商统计
+
+请求 `GET /admin/finance/payments/stats/by-supplier?pageNo=1&pageSize=10`：
+
+```json
+{
+  "code": 200,
+  "data": {
+    "list": [
+      {
+        "supplierId": "2096854417461403650",
+        "supplierName": "呼伦贝尔羊和远方牧业有限公司",
+        "category": "住宿",
+        "payableAmount": 3000.00,
+        "appliedAmount": 800.00,
+        "paidAmount": 1200.00,
+        "owedAmount": 1800.00,
+        "teamCount": 3,
+        "status": "NORMAL"
+      }
+    ],
+    "total": 1
+  }
+}
+```
+
+### 8.2 建议清单（含不可申请资格）
+
+```json
+{
+  "code": 200,
+  "data": {
+    "list": [
+      {
+        "sourceType": "GROUP_BATCH_STAY",
+        "sourceId": "2100484891404648449",
+        "resourceName": "呼和诺尔湖景房",
+        "amount": 800.00,
+        "paymentType": "住宿",
+        "supplierId": "2096854417461403650",
+        "supplierName": "呼伦贝尔羊和远方牧业有限公司",
+        "eligible": false,
+        "eligibleReason": "已存在审批中付款单，行已锁定",
+        "alreadyGenerated": true
+      }
+    ]
+  }
+}
+```
+
+### 8.3 边界：降级行（供应商未绑定）
+
+配资源时供应商未绑定/反查失败的行，`supplierId`/`supplierName` 为 null，落台账待绑定区，不阻断主流程：
+
+```json
+{ "sourceId": "...", "supplierId": null, "supplierName": null, "eligible": false, "eligibleReason": "供应商待绑定" }
+```
+
+## ⑨ 业务边界
+
+- **applied 占用口径**：建单（PENDING）即占用，付讫转 paid，驳回/删除释放；防止同一应付行被重复申请。
+- **isLocked 前置闸**：存在审批中付款单的台账行锁定，建议清单 `eligible=false`。
+- **无价节点不推送**：结算价 NULL 或 0 的资源不推送台账（不炸订单确认）。
+- **owed 可为负**：多付/台账外付款时 owed 为负，属正确表达。
+
+## ⑩ 修改前后对比
+
+| 项 | 修改前 | 修改后 |
+|---|---|---|
+| 数据源 | 实时扫订单/配房/节点 | 读推送台账三表 |
+| 申请中金额 | 无独立口径 | `appliedAmount` 真值化 |
+| 欠款 | 各页自算、口径不一 | `owedAmount = payable − paid` 统一 |
+| 重复申请 | 可能重复 | isLocked 闸拦截 |
+
+## ⑪ 影响评估 / 回滚
+
+- **出参新增字段**（appliedAmount/owedAmount 等）为增量，旧前端不读取不受影响；但**数值口径变化**（切台账后与旧实时聚合可能有差），前端需以台账口径为准。
+- **回滚**：读侧切回实时聚合需回退代码；台账数据保留。
+
+## ⑫ 注意事项
+
+- 台账为「订单确认/配房确认」时推送，历史未推送的老订单不在台账内（开发阶段老数据可清，生产上线另起迁移）。
+- 供应商降级行（supplierId null）不累计供应商头表。
+
+## ⑬ 关联 / 联系人
+
+- Issue：https://git.1814.love:8443/wx/HL/issues/8070
+- PR：#8071 / #8075 / #8079 / #8081 / #8083 / #8092（本批切流）/ #8097 / #8109
+- 负责人：yst
@@ -0,0 +1,420 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8114"
+title: "派单操作时间线新增司机拒接记录留痕"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "not_required"
+frontend_status: "not_required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "backend_status=deployed: hl-fleet-service 测试服部署 sha=10ed12133，与本单 PR #8139 的合并提交完全一致，STATE=ok（该结论由管理者侧执行 deploy-status.sh 核验后转达，本会话未持有目标机器 SSH 权限、未亲自运行该脚本，如实披露）。gateway_status=not_required 特指网关路由层：driver-reject 写口与 operation-log 读口均为存量路由，本单未新增/改动任何 hl-gateway 路由配置；本会话对 driver-reject 写口做过真实网关实测（见八节，2026-09-22 04:00 前后），命中的是「非 holding 状态」守卫分支（605020），该守卫早于本单存在、与本单新增代码不重叠；受限于测试环境仅有 #5827 后新建的 assigned 态数据、没有存量 holding 派单，未能网关实测出「拒接成功→写入 driver_rejected→读侧可见」这条正向链路，该正向链路的验证依据是 AC-1/AC-2 的真库集成测试（H2 MODE=MySQL + 真 Flyway + 真 MyBatis + 真 AssignmentService Bean），非网关活测，已在三/八节如实注明并附逐字 dump。frontend_status=pending: 未获得 mmg 对 operation_type 白名单现状的新鲜核验，不认定 not_required。"
+updated_at: "2026-09-22"
+base: "dev-v3"
+---
+
+# fleet: 派单操作时间线新增司机拒接记录留痕
+
+> **存放目录**: `changelogs-v2/2026-09/`
+>
+> **服务**: hl-fleet-service (端口 8003)
+> **PR**: #8139
+> **Issue**: #8114
+> **日期**: 2026-09-22
+> **影响范围**: 司机拒接/车务退回待派链路；派单操作时间线接口返回的操作记录
+
+---
+
+## ⚠️ 关键变化
+
+司机拒接/车务退回待派（`POST /admin/fleet/assignments/{assignmentId}/driver-reject`，仅 `holding` 状态可调用，成功后派单回到 `unassigned`）以前在 `fleet_assignment` 表清空车辆/司机字段后不留任何痕迹。现已补齐写口留痕：`fleet_assignment_operation_log` 新增 `driver_rejected` 操作类型——与 #8068 已上线的 `soft_cleared` 是两个独立取值，不共用。
+
+**前端影响**：派单看板订单卡片「查看日志」时间线会新增这类记录。如果前端按 `operation_type` 做了白名单过滤，`driver_rejected` 需要加进去——不加会静默漏渲染。
+
+**覆盖边界**：`driver_rejected` 只在司机拒接/退回待派**成功执行**时写入，而该写口只接受 `holding` 状态的派单（组）。自 #5827 起，新建派单提交即派定，落库恒为 `assigned`（`holding` 仅剩发版前的存量数据）——因此在测试环境用新建的派单去调 `driver-reject` 会拿到 `605020`（本会话已实测复现，见八节），不会触发这条新留痕；能触发它的只有 #5827 发版前遗留、目前仍停留在 `holding` 的存量派单（组）。
+
+---
+
+## 一、背景
+
+`fleet_assignment` 的 `vehicle_id` / `driver_id` 会因两类写口被清空：车务手动软清（#8068，已补齐留痕）与司机拒接/车务退回待派（本单）。此前拒接写口（`AssignmentService#doDriverRejectInLock`，覆盖 `updateDriverReject` 单派与 `updateDriverRejectGroup` 组派两条路径）在 CAS 清空成功后不写任何操作日志，事后无法查证「是谁拒的、拒掉的是哪位司机哪台车」——与 #8068 描述的是同一个洞，只是入口不同（工单 #8051 #8068 #8114）。
+
+本次补齐留痕机制：每次拒接成功都在 `fleet_assignment_operation_log` 写一行 `operation_type = driver_rejected`，记录被清空前的身份快照及操作范围，形状与 #8068 的 `soft_cleared` 一致（锚点行 + `clearedRows[]`），但两者是**两个独立的枚举取值**——读侧 `AssignmentOperationLogQueryService` 没有 `operation_type` 白名单，共用会让「车务主动清空」与「司机拒接退回」在时间线上无法区分，而两者的责任归属不同。
+
+触发本次留痕的写口端点本身**未变**：`POST /admin/fleet/assignments/{assignmentId}/driver-reject`（单派/组派共用同一端点，按当前派单是否属于某个派车组自动分流），请求体/响应结构/错误码均未调整。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 派单操作时间线 | GET | `/admin/fleet/orders/{orderId}/operation-log` | 响应新增操作类型 | 新增 `driver_rejected` 枚举值 + `detail_json` 字段扩展 |
+
+---
+
+## 三、接口详情
+
+### 1. 派单操作时间线 `GET /admin/fleet/orders/{orderId}/operation-log`
+
+**VO**: `FleetOperationLogItemVO → FleetOrderOperationLogRespVO`
+
+#### 使用场景
+
+车务在派车看板订单卡片内点「查看日志」，实时呈现该订单全部派车操作的不可变时间线。新操作类型 `driver_rejected` 会在司机拒接/车务退回待派成功执行后出现在此时间线中。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| orderId | Path | Long | ✅ | 雪花 ID | 订单 ID |
+| page | Query | Long | ❌ | 默认 1，上限 100000 | 分页页码 |
+| pageSize | Query | Long | ❌ | 默认 50，上限 200 | 每页条数 |
+| keyword | Query | String | ❌ | 最长 32 | 按操作人/摘要模糊匹配 |
+| sortBy | Query | String | ❌ | 如 `time,desc` / `time,asc` | 排序字段，默认按 create_time 倒序 |
+| startDate / endDate | Query | LocalDateTime | ❌ | ISO 格式 `yyyy-MM-dd'T'HH:mm:ss` | 时间范围过滤 |
+
+#### 出参 `Result<FleetOrderOperationLogRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data.records | List<FleetOperationLogItemVO> | 当前页操作日志行 |
+| data.records[].id | String | 日志行 ID（雪花号，以字符串返回防精度丢失） |
+| data.records[].time | LocalDateTime | 操作时间 |
+| data.records[].opType | String | 操作类型英文枚举值，**含新增的 `driver_rejected`** |
+| data.records[].opTypeLabel | String | 操作类型中文标签（由后端从枚举翻译，`driver_rejected` → "司机拒接/退回待派"） |
+| data.records[].summary | String | 可读摘要（固定文案："司机拒接/退回待派，清空车与司机，派车行置待选择"） |
+| data.records[].operatorName | String | 操作人（企微名优先，无则用户名，系统动作显示"系统"） |
+| data.records[].effectiveDate | LocalDate | 生效日期（取锚点行的 serviceDate） |
+| data.records[].detailJson | String | 明细 JSON（字符串化），格式见下节 |
+| data.total | Long | 总条数 |
+| data.page | Integer | 当前页码 |
+| data.pageSize | Integer | 本页条数 |
+
+#### 新增字段详情
+
+**`opType` 新增枚举值**
+
+| 值 | 中文标签 | 触发场景 |
+|----|----------|---------|
+| `driver_rejected` | 司机拒接/退回待派 | 司机拒接本次排车锁定，或车务确认锁定无效，调用 `driver-reject` 端点成功清空车辆/司机字段 |
+
+**`detailJson` 字段（当 `opType="driver_rejected"` 时）**
+
+响应的 `detailJson` 是字符串化的 JSON。字段与顺序如下（取自真实集成测试落库结果，逐字未改；单派场景，`DriverRejectWritebackTraceIntegrationTest` AC-1）：
+
+```json
+{"scope":"SINGLE","assignmentGroupId":"8114100001","statusBefore":"holding","rejectReason":"司机临时车辆抛锚，退回待派","clearedRowCount":1,"vehicleIdBefore":"8114300001","driverIdBefore":"8114400001","vehiclePlateSnapshot":"蒙A-81141","driverNameSnapshot":"拒接司机甲","clearedRows":[{"assignmentId":"8114100001","serviceDate":"2031-07-03","vehicleIdBefore":"8114300001","vehiclePlateBefore":"蒙A-81141","driverIdBefore":"8114400001","driverNameBefore":"拒接司机甲"}]}
+```
+
+组派场景（一次拒接影响整组多行，AC-2）：
+
+```json
+{"scope":"GROUP","assignmentGroupId":"8114200001","statusBefore":"holding","rejectReason":"司机拒接整组行程，退回待派","clearedRowCount":2,"vehicleIdBefore":"8114300011","driverIdBefore":"8114400011","vehiclePlateSnapshot":"蒙A-81142","driverNameSnapshot":"拒接司机乙","clearedRows":[{"assignmentId":"8114100011","serviceDate":"2031-07-10","vehicleIdBefore":"8114300011","vehiclePlateBefore":"蒙A-81142","driverIdBefore":"8114400011","driverNameBefore":"拒接司机乙"},{"assignmentId":"8114100012","serviceDate":"2031-07-11","vehicleIdBefore":"8114300012","vehiclePlateBefore":"蒙A-81143","driverIdBefore":"8114400011","driverNameBefore":"拒接司机乙"}]}
+```
+
+字段说明（`LinkedHashMap` 插入顺序，来自 `AssignmentService#clearedIdentitySnapshot`）：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| scope | String | 拒接范围，`SINGLE` 单派、`GROUP` 按派车组整组拒接 |
+| assignmentGroupId | String | 派车组 ID（字符串格式；见下方「关键说明 1」的类型对照） |
+| statusBefore | String | 清空前状态，恒为 `holding`（拒接只放行 `holding → unassigned` 这一种迁移，非 `holding` 一律 605020，不写日志） |
+| rejectReason | String | 拒接/退回原因，与请求体 `rejectReason` 同一份取值（仅存证，不参与任何判定） |
+| clearedRowCount | Integer | 本次清空涉及的派车行数（单派恒为 1，组派为组内行数） |
+| vehicleIdBefore | String | 清空前的车辆 ID（锚点行，字符串返回） |
+| driverIdBefore | String | 清空前的司机 ID（锚点行，字符串返回） |
+| vehiclePlateSnapshot | String | 清空前的车牌号（可读值快照） |
+| driverNameSnapshot | String | 清空前的司机名（可读值快照） |
+| clearedRows | Array | 本次实际被清空的每一行明细：`assignmentId` / `serviceDate` / `vehicleIdBefore` / `vehiclePlateBefore` / `driverIdBefore` / `driverNameBefore`（组派时逐切片各自的车/司机可能不同，不是锚点行的复制，见下方「关键说明 2」） |
+
+**关键说明 1：所有 ID 字段都以字符串返回，但 DB 列类型不代表 JSON 字段类型**
+
+`detail_json` 里的 `vehicleIdBefore` / `driverIdBefore` / `assignmentId` / `clearedRows[].assignmentId` 等 ID，均由后端 `AssignmentService#idText(Object)` 转换为字符串后再落 JSON（javadoc 原文：「可空 ID 转字符串（雪花 ID 落 JSON 防 JS 精度丢失；null 原样保留）」）。雪花 ID 是 19 位数字，JavaScript 的 `Number` 只能精确表示到 16 位，若以数字解析会在末位静默丢精度、无任何报错提示。
+
+⚠️ **不要把 DB 列类型和 JSON 字段类型混为一谈**：`fleet_assignment_operation_log` 表的 `assignment_group_id` 列在数据库里是 `BIGINT NOT NULL`（这一列是这一行日志自身的分组归属，落值就是数字，不在 `detail_json` 里）；而 `detail_json` 内部的 `assignmentGroupId` 键是经 `idText(...)` 转换后的字符串——两者字段名相近，是两个不同的东西。前端通过这个 JSON 接口只会消费到后者（字符串），不会直接看到 DB 列。
+
+**关键说明 2：组拒接只写一行——锚点 + `clearedRows[]`，不是逐槽位各写一条**
+
+一次组派拒接会清空组内全部行（上面示例是 2 行），但 `fleet_assignment_operation_log` 只 INSERT **一行**：锚点行（组内第一行）写 `operation_type=driver_rejected`，组内其余被清空的行不会各自再产生一条独立的日志行，它们清空前的身份只出现在这一行的 `detail_json.clearedRows[]` 数组里。
+
+实测依据（AC-2）：把查询条件放宽成只按 `order_id` 扫描整张表（不加 `assignment_id` 过滤、不加 `operation_type` 过滤），针对一次影响 2 行的组拒接，整单也只返回 **1 行**日志（`assignment_id` 为锚点行 `8114100011`），组内另一行 `8114100012` 名下没有独立的日志行。⇒ 前端如果按 `assignmentId` 去时间线表里找某一行派车行「自己的」拒接记录，组内非锚点行是找不到的，需要改为解析锚点行的 `clearedRows[]`。
+
+**关键说明 3：若按 `operation_type` 白名单过滤，需要加入新取值**
+
+时间线读侧（`AssignmentOperationLogQueryService`）没有 `operation_type` 白名单，新取值会自动随查询结果返回。但**如果前端渲染时自行对 `operation_type` 做了白名单过滤，必须把 `driver_rejected` 加入白名单**，否则这条记录会被过滤掉、静默漏渲染（不报错、不提示）。
+
+**关键说明 4：新记录只出现在存量 `holding` 派单（组）被拒接时**
+
+产生 `driver_rejected` 记录的前提是 `driver-reject` 写口调用**成功**，而该写口只接受 `holding` 状态的派单（组）——`FleetAssignmentMapper.updateDriverReject` / `updateDriverRejectGroup` 均带 `.eq(assignment_status, holding)` 的 CAS 条件，非 `holding` 一律返回 `605020`、不写任何日志。自 #5827 起新建派单提交即派定，落库恒为 `assigned`（`holding` 仅剩发版前的存量数据，`CreateAssignmentCommand` javadoc 原文："落库目标态：#5827 起提交即派定，最终态恒 assigned（holding 只是同事务内的瞬时中间态）"）。⇒ 在测试环境用新建的派单调用 `driver-reject` 会拿到 `605020`（本会话已实测复现，详见八节的真实网关响应），不会产生 `driver_rejected` 记录；要看到这条新记录的渲染效果，需要用 #5827 发版前遗留、目前仍处于 `holding` 的存量派单（组），或等真实司机拒接场景产生新数据——这是该端点自身的既有前置条件，不是本次改动新增的限制。
+
+#### 请求示例
+
+```http
+GET /admin/fleet/orders/8114000001/operation-log?page=1&pageSize=50 HTTP/1.1
+Host: {后台域名}
+Authorization: Bearer {token}
+Accept: application/json
+```
+
+#### 响应示例
+
+以下 `records[0]` 按 `FleetOperationLogItemVO` 字段映射规则，从 AC-1 集成测试真实落库结果重新组装（`detailJson` 内容逐字符取自该次真库 IT 结果；`id`/`time`/`effectiveDate` 取自同一行的 `operation_id`/`create_time`/`effective_date`；`operatorName` 为该 IT 用例夹具下的 `actor_name` 原值「系统」——集成测试未经过网关鉴权链路、没有设置 `operator_id`，真实生产场景下这里通常是执行拒接操作的车务人员姓名，机制与其他写口的 `operatorName` 完全一致，本单未改动。整份响应信封本身未经网关活捕获，参见八节的受限说明）：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "success": true,
+  "data": {
+    "records": [
+      {
+        "id": "2102121618417971202",
+        "time": "2026-09-22T03:43:44",
+        "opType": "driver_rejected",
+        "opTypeLabel": "司机拒接/退回待派",
+        "summary": "司机拒接/退回待派，清空车与司机，派车行置待选择",
+        "operatorName": "系统",
+        "effectiveDate": "2031-07-03",
+        "detailJson": "{\"scope\":\"SINGLE\",\"assignmentGroupId\":\"8114100001\",\"statusBefore\":\"holding\",\"rejectReason\":\"司机临时车辆抛锚，退回待派\",\"clearedRowCount\":1,\"vehicleIdBefore\":\"8114300001\",\"driverIdBefore\":\"8114400001\",\"vehiclePlateSnapshot\":\"蒙A-81141\",\"driverNameSnapshot\":\"拒接司机甲\",\"clearedRows\":[{\"assignmentId\":\"8114100001\",\"serviceDate\":\"2031-07-03\",\"vehicleIdBefore\":\"8114300001\",\"vehiclePlateBefore\":\"蒙A-81141\",\"driverIdBefore\":\"8114400001\",\"driverNameBefore\":\"拒接司机甲\"}]}",
+        "changeDetail": null
+      }
+    ],
+    "total": 1,
+    "page": 1,
+    "pageSize": 50
+  }
+}
+```
+
+#### 空数据 / 降级响应
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "success": true,
+  "data": {
+    "records": [],
+    "total": 0,
+    "page": 1,
+    "pageSize": 50
+  }
+}
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 404,
+  "message": "订单不存在",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- **权限**：网关 `/admin/fleet/**` 统一鉴权，车务/管理员可访问
+- **分页上限**：pageSize 最高 200，page 最高 100000
+- **ID 精度**：所有雪花号均以字符串返回，前端切勿转为 Number 类型
+- **operation_type 白名单**：若前端自行维护白名单过滤时间线渲染，必须加入 `driver_rejected`，否则静默漏渲染
+- **组拒接留痕形状**：一次组拒接只在 `fleet_assignment_operation_log` 里产生一行（锚点行），组内其余行的清空前身份只存在于该行 `detail_json.clearedRows[]` 数组内，不能按 `assignmentId` 直接从时间线表里查到独立行
+- **可达性边界**：`driver_rejected` 只在拒接 `holding` 状态的存量派单（组）成功时产生；测试环境新建的派单调用 `driver-reject` 恒得 `605020`，不会产生这条记录
+
+---
+
+## 四、契约约束与正确调用方式
+
+### ✅ 正确 / ❌ 错误 payload 对照
+
+此接口为只读 GET，无请求体。正确调用示例：
+
+| 场景 | URL |
+|------|-----|
+| ✅ 第一页，默认排序 | `GET /admin/fleet/orders/{orderId}/operation-log?page=1&pageSize=50` |
+| ✅ 处理 detailJson 字符串 | `JSON.parse(record.detailJson)` 转为对象后访问字段 |
+| ❌ ID 作为 Number | `parseInt(record.id)` / `Number(detail.vehicleIdBefore)` 会导致末位精度丢失 |
+| ❌ 按 assignmentId 直查组内非锚点行的独立日志 | 组内非锚点行没有独立日志行，需解析锚点行的 `clearedRows[]` |
+
+### 处理 detailJson 的正确方式
+
+```javascript
+// ✅ 正确：先 parse，再按需读取 driver_rejected 专属字段
+const detail = JSON.parse(record.detailJson);
+if (record.opType === 'driver_rejected') {
+  const rejectReason = detail.rejectReason;      // 拒接原因
+  const clearedRows = detail.clearedRows;        // 组内逐行明细，SINGLE 场景长度恒为 1
+  const vehicleId = detail.vehicleIdBefore;      // String，保持精度，不转 Number
+}
+
+// ❌ 禁止转数字
+const id = Number(detail.vehicleIdBefore);  // 末位被四舍五入
+```
+
+### operation_type 白名单排查清单（若前端有）
+
+- [ ] 渲染时间线的组件是否存在 `operation_type` 白名单/枚举映射？
+- [ ] 若存在，是否已加入 `driver_rejected` → "司机拒接/退回待派"？
+- [ ] 图标/颜色映射表是否需要为 `driver_rejected` 配一个默认展示（未配置时不应崩溃或空白）？
+
+---
+
+## 五、数据库行为
+
+| 场景 | 数据库表 | 操作 |
+|------|----------|------|
+| 司机拒接（单派）执行成功 | `fleet_assignment` | UPDATE `vehicle_id = null, driver_id = null` 等字段（CAS 条件 `assignment_status = holding`） |
+| 司机拒接（组派）执行成功 | `fleet_assignment` | 按 `assignment_group_id` 批量 UPDATE 组内多行，同上 CAS 条件 |
+| 拒接留痕写口 | `fleet_assignment_operation_log` | INSERT 一行，`operation_type = 'driver_rejected'`，`detail_json` 记录清空前的身份（锚点行 1 条，覆盖整组） |
+
+---
+
+## 六、边界行为
+
+- **派单不存在** → `605009`
+- **非 `holding` 状态** → `605020`（不允许退回待派；自 #5827 起新建派单落库恒为 `assigned`，`holding` 仅剩发版前的存量数据——对新建派单调用会必得 `605020`，这不是缺陷，见「关键说明 4」）
+- **`rejectReason` 为空** → `400001`
+- **旧 HOLD 通知结果正在确认中** → `605042`（可稍后重试；此次不改变派单状态、不清空车辆/司机身份、不改变资源占用，也不写留痕）
+- **无鉴权** → `401`（网关拦截）；**权限不足**（非车务/管理员）→ `403`
+- **历史数据**：本次新增的 `driver_rejected` 仅出现在部署后发生的拒接成功操作中，不影响此前已有的操作日志记录
+
+---
+
+## 六.5、枚举 / 数据字典
+
+### operation_type 枚举（`AssignmentOperationTypeEnum`）
+
+**所属字段**: `FleetOperationLogItemVO.opType` | **类型**: `String`
+
+新增值：
+
+| 值 | 中文标签 | 说明 |
+|----|----------|------|
+| `driver_rejected` | 司机拒接/退回待派 | 司机拒接锁定或车务确认锁定无效，调用 `driver-reject` 成功后清空派车行的车辆/司机字段 |
+
+现有值（不含全列表，仅示例，与 `driver_rejected` 语义最接近的一项一并列出对照）：
+
+| 值 | 中文标签 | 说明 |
+|----|----------|------|
+| `assignment_created` | 新建派单 | 订单新建派单时 |
+| `change_completed` | 修改派单完成 | 改派操作完成 |
+| `soft_cleared` | 清空司机/车辆 | 车务手动清空派车行的车辆/司机字段（#8068，与 `driver_rejected` 是同形状但独立的取值，不共用） |
+| `confirmed` | 确认执行 | 司机确认执行派单 |
+| `completed` | 完结派单 | 派单完成 |
+
+---
+
+## 六.6、修改前后对比
+
+### 响应字段级对比
+
+| 字段 | 改前 | 改后 | 备注 |
+|------|------|------|------|
+| `records[].opType` | 不含 `driver_rejected` | 新增 `driver_rejected` | 前端若按白名单过滤需要加入 |
+| `records[].detailJson` | 已有其他操作类型的内容 | 新增 `opType="driver_rejected"` 时的结构 | 含 `rejectReason` 等专属字段，见三节 |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| 司机拒接/退回待派留痕 | 派车行 `vehicle_id`/`driver_id` 直接清空，无操作日志 | 调用 `driver-reject` 成功后同事务在 `fleet_assignment_operation_log` 写一行，记录清空前的车/司机 |
+| 时间线查询 | 拒接操作不可见 | 拒接操作以 `driver_rejected` 行显示在时间线中 |
+| 事后取证 | 无法查证谁拒的、拒掉了谁 | `detail_json` 中记录清空前的 vehicleId/driverId 等快照，支持事后追溯 |
+
+---
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**：否
+  - 新增操作类型 `driver_rejected` 不影响既有类型的解析
+  - 响应字段无删除，仅新增返回内容（仅当 `opType=driver_rejected` 时出现新的 `detail_json` 结构）
+
+- **前端是否必须同步上线**：否（但需适配白名单过滤）
+  - 后端接口变更无必须的前端代码改动
+  - **但是**：如果前端渲染时间线时对 `operation_type` 做了白名单过滤，白名单中**必须加入 `driver_rejected`**，否则该操作会静默漏渲染
+
+- **前端 workaround 清理点**：
+  - 若有硬编码的 `operation_type` 白名单，需补充 `'driver_rejected'`
+  - 若用了枚举常量或字典，确保下发的字典已包含 `driver_rejected` 标签
+
+- **覆盖边界（前端自测数据来源受限，需知悉）**：
+  - `driver_rejected` 只在「存量 `holding` 派单（组）」被拒接成功时产生。自 #5827 起，新建派单提交即派定，落库恒为 `assigned`——因此**对着测试环境新建的派单调用 `driver-reject` 会返回 `605020`，不会产生这条新记录**；能触发它的只有 #5827 发版前遗留、目前仍处于 `holding` 的存量派单（组）。
+  - 前端要验证 `driver_rejected` 的渲染效果，需要去找这类存量数据（或等真实司机拒接场景产生新数据），而不是自己新建一条派单来复现——这是该端点自身的既有前置条件（`holding` 状态限定，非本单引入），不是本次改动新增的限制。
+
+---
+
+## 七、不影响范围
+
+- **仅影响**：派单操作时间线接口 `/admin/fleet/orders/{orderId}/operation-log` 的响应内容
+- **零影响**：
+  - `driver-reject` 端点自身的请求体/响应结构/错误码（一律未改）
+  - `updateDriverReject` / `updateDriverRejectGroup` 两个 Mapper default 方法（一行未改）
+  - 派车创建/改派/确认等其他业务流程
+  - 订单详情接口
+  - 其他模块的操作日志接口（如房务）
+  - 前端派车列表/派车详情等其他功能模块
+
+---
+
+## 八、测试环境已验证
+
+**后端部署**：`hl-fleet-service` 测试服部署 sha `10ed12133`，与本单 PR #8139 的合并提交完全一致，`STATE=ok`。⚠️ 该结论由管理者侧执行 `deploy-status.sh` 核验后转达，本会话未持有目标机器的 SSH 访问权限、未亲自运行该脚本，如实披露。
+
+**网关实测（本会话 2026-09-22 04:00 前后，真实发起，非构造）**：
+
+对一条刚通过 `POST /admin/fleet/assignments/batch` 新建、状态为 `assigned` 的派单（`assignmentId=2102125764705181697`，04:00:12 创建）调用拒接端点：
+
+```
+POST /admin/fleet/assignments/2102125764705181697/driver-reject
+  ↓
+HTTP 200，code=605020，msg=当前派单状态不允许此操作
+```
+
+这与「关键说明 4」描述的可达性边界完全吻合：新建派单落库恒为 `assigned`，非 `holding` 一律 `605020`。同时执行了两组反例校验：
+
+```
+POST /admin/fleet/assignments/2102125764705181697999/driver-reject（ID 格式非法）
+  ↓ HTTP 200，code=400，msg=参数 assignmentId 格式错误，请检查后重试
+
+POST /admin/fleet/assignments/2102125764705181698/driver-reject（格式合法但不存在）
+  ↓ HTTP 200，code=605009，msg=派单不存在
+```
+
+调用前后对该派单行与 `fleet_assignment_operation_log` 的 SELECT 复核：拒接调用前后该行 `vehicle_id`/`driver_id`/`assignment_status` 均无变化（`assigned`，`2085539421276286978`/`2065272150012444674`），`operation_type='driver_rejected'` 的行数前后均为 0——确认失败调用没有副作用、也没有写出留痕，符合预期。
+
+**受限说明**：本会话测试环境内没有可用的存量 `holding` 派单（组），因此上面这组网关实测只覆盖了 `driver-reject` 的失败分支，**没有**现场网关实测出「拒接成功 → 写入 `driver_rejected` → 时间线读侧可见」这条正向链路（该限制本身正是「关键说明 4」所述的可达性边界，不是本次验证的疏漏）。正向链路的验证依据是集成测试真库取证（见下）：
+
+用例：`DriverRejectWritebackTraceIntegrationTest`（`test` profile 的 H2 `MODE=MySQL` + 真 Flyway DDL + 真 MyBatis 生成 SQL + 真 `AssignmentService` Bean，非 MySQL 8 容器）。
+
+- 单派（AC-1）：拒接前该行 `vehicle_id=8114300001, driver_id=8114400001, assignment_status=holding`；拒接后同一行 `vehicle_id=null, driver_id=null, assignment_status=unassigned`；同时写出一行 `fleet_assignment_operation_log`（`operation_id=2102121618417971202, operation_type=driver_rejected`），其 `detail_json.vehicleIdBefore="8114300001"` / `.driverIdBefore="8114400001"` 与清空前的 DB 值一致——排除了「UPDATE 之后再 reload 导致全 null」这一最强反例。
+- 组派（AC-2）：两个切片清空前分别持有不同的车/司机（`8114300011/8114400011` 与 `8114300012/8114400011`），拒接后按 `order_id` 全表扫描整单只返回 **1 行**日志（锚点 `assignment_id=8114100011`），第二个切片 `8114100012` 名下无独立日志行，两切片各自的清空前身份分别体现在锚点行 `detail_json.clearedRows[0]` 与 `[1]` 里——确认了「关键说明 2」所述的锚点+`clearedRows[]`留痕形状。
+
+三节的响应示例即按上述 AC-1 真库 IT 结果、按 `FleetOperationLogItemVO` 字段映射规则重新组装（非网关活捕获，已在三节标注）。
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#8114](https://git.1814.love:8443/wx/HL/issues/8114)
+- 关联 PR: [wx/HL#8139](https://git.1814.love:8443/wx/HL/pulls/8139)
+- 相关工单: [#8068](https://git.1814.love:8443/wx/HL/issues/8068)（软清留痕，同形状参照实现），[#5827](https://git.1814.love:8443/wx/HL/issues/5827)（取消司机确认环节，holding 状态自此变为遗留态）
+
+---
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8114](https://git.1814.love:8443/wx/HL/issues/8114)
+- **PR**: [#8139](https://git.1814.love:8443/wx/HL/pulls/8139)
+- **Merge commit**: [10ed12133](https://git.1814.love:8443/wx/HL/commit/10ed12133)
+
+### 联系人
+
+- **后端负责人**: @wx
@@ -0,0 +1,360 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8121"
+title: "核单清单「用车安排」逐类判定，包车+接送机并存不再静默放行"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "not_required"
+frontend_status: "not_required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "backend_status: deployed - hl-order-service-v3 COMMIT=7811104b4 BEHIND=0 STATE=ok（2026-09-22 AC-3 取证）; gateway_status: not_required - 本单零网关改动，GET /v3/admin/order/{orderId}/confirm-checklist 是既有路由，走 hl-gateway 既有 /v3/admin/** 通配断言（application.yml:220-223），无新增 /admin/ 端点需要配路由; frontend_status: pending - 前端适配情况未知，后端不代填 前端核验(2026-09-22, mmg): ConfirmChecklistModal 按 passed===false 过滤、failReason 纯展示不做精确匹配、checkName 缺省兜底 code、动作按 code 映射(confirmChecklistActions.js),纯展示场景零改动;owner/ref/verified_at 按 not_required 口径留空。"
+updated_at: "2026-09-22"
+base: "dev-v3"
+---
+
+# order-v3: 核单清单「用车安排」逐类判定，包车+接送机并存不再静默放行
+
+> **存放目录**: 二期(v3) → `changelogs-v2/{YYYY-MM}/`
+>
+> **服务**: hl-order-service-v3 (端口 8033)
+> **Issue**: [#8121](https://git.1814.love:8443/wx/HL/issues/8121)
+> **日期**: 2026-09-22
+> **影响范围**: 管理后台「订单详情」→「确认核单」清单；接送机需求与行程用车并存的订单
+
+---
+
+## ⚠️ 关键变化
+
+**缺陷修复**：同一订单同时买「行程用车（包车）」和「接送机」时，之前只要包车那类先办完，整个 `VEHICLE_DONE` 项就判 `passed=true` —— 接送机零派车也照样放行，**没有异常、没有错误码，清单上是一个绿勾，订单就这么被确认掉了**。修复后两类需求各自独立判定，任一类未就绪则整体 `passed=false`，且 `failReason` 点名是哪一类。
+
+---
+
+## 一、背景
+
+同一张订单可以包含多个用车需求类别（行程用车、接送机）。原判定逻辑使用"单值投影"——只选中其中一类进行判定，导致当两类并存且其中一类已完成时，另一类的未就绪状态被静默忽略。核单清单是车务部门唯一的缺陷定位入口，绿勾放行的订单实际上出数不全，造成订单被错误地推入后续流程。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 订单确认核单清单 | GET | `/v3/admin/order/{orderId}/confirm-checklist` | 响应字段语义变化 | `VEHICLE_DONE` 改为逐类判定（两类并存时不再静默判过）；`items[*].failReason` 未就绪时点名用车类别。响应结构不变 |
+
+---
+
+## 三、接口详情
+
+### 1. 订单确认核单清单 `GET /v3/admin/order/{orderId}/confirm-checklist`
+
+**VO**: `OrderDetailService#getConfirmChecklist(Long) → ConfirmChecklistRespVO`
+
+#### 使用场景
+
+管理后台订单详情页面，确认前的最终核对清单。车务部门通过此清单判断订单是否已具备所有必要条件（付款、房间、用车、合同等），逐项绿勾后方可点击「确认」按钮推动订单进入后续流程。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| `orderId` | Path | Long | ✅ | 订单必须存在 | 订单 ID |
+
+#### 出参 `Result<ConfirmChecklistRespVO>`
+
+外层信封 `Result`：`code`（成功恒 200）、`message`、`data`、`traceId`、`success`（由 `isSuccess()` 序列化，等价于 `code == 200`），依据 `hl-common/hl-common-core/src/main/java/com/hulalv/common/result/Result.java:21-45`。
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `allPassed` | Boolean | 是否五项全部通过，是 `items` / `preview` 的唯一开关（`ConfirmChecklistRespVO.java:23-24`、`OrderDetailService.java:424-427`） |
+| `items` | List&lt;ChecklistItemVO&gt; | `allPassed=false` 时返回**全部 5 项**（含 `passed=true` 的项，不是只返回失败项）；`allPassed=true` 时为 `null`（`OrderDetailService.java:429`） |
+| `preview` | PreviewVO | `allPassed=true` 时返回确认弹框预览；`allPassed=false` 时为 `null`（`OrderDetailService.java:430-432`） |
+
+##### PreviewVO 结构（仅 `allPassed=true` 时有值）
+
+| 字段 | 类型 | 说明 | 源码依据 |
+|------|------|------|----------|
+| `departureDate` | LocalDate | 出发日期，取订单 `departDate` | `OrderDetailService.java:1116` |
+| `totalPeopleCount` | Integer | 总出行人数：优先按 `order_traveler` 实际条数；为 0 时回落「成人+儿童+幼儿+婴儿」 | `OrderDetailService.java:1117-1124` |
+| `driverName` | String | 司机姓名。团车路径（车在团级承担、逐户无配车行）该栏留空 | `OrderDetailService.java:1127-1147` |
+| `driverPhoneMasked` | String | 司机手机（脱敏） | 同上 |
+| `hotels` | List&lt;HotelSummaryVO&gt; | 元素为 `{cityName, hotelName}`；按 `dayNumber` 升序，相邻「城市+酒店」相同的去重；无配房时为空数组 | `OrderDetailService.java:1151-1182` |
+| `staffs` | List&lt;StaffItemVO&gt; | 本单人员：`assignmentId` / `staffId`（两个 Long 均序列化成字符串）/ `staffName` / `staffPhone`（已脱敏）/ `staffRole` / `staffRoleName` / `isPrimaryReporter` | `ConfirmChecklistRespVO.java:83-107`、`OrderDetailService.java:1209-1230` |
+| `contractAutoAction` | 对象 | `{planName, autoSign}`，`autoSign` 恒 `true`（确认后自动发起线上签署）；无 ACTIVE 合同方案时整个对象缺省 | `OrderDetailService.java:1187-1194` |
+| `insuranceAutoAction` | 对象 | `{planName, peopleCount, effectiveDescription}`，`effectiveDescription` 是固定文案「出发前 24h 内生效」；无 ACTIVE 保险方案时整个对象缺省 | `OrderDetailService.java:1198-1205` |
+
+> `preview` **没有** `rooms` / `drivers` / `notificationList` 这三个字段：通知块已于 #4844 删除（`OrderDetailService.java:1232-1233`），酒店与司机分别是上表的 `hotels` 与 `driverName` / `driverPhoneMasked`。
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/2101908228545937410/confirm-checklist HTTP/1.1
+Authorization: Bearer <token>
+```
+
+##### ChecklistItemVO 结构
+
+| 字段 | 类型 | 说明 | 源码依据 |
+|------|------|------|----------|
+| `code` | String | 检查项代码，5 个固定取值（见下表） | `ConfirmChecklistRespVO.java:36-38` |
+| `checkName` | String | 检查项中文名（见下方 ⚠️） | `ConfirmChecklistRespVO.java:40-41` |
+| `passed` | Boolean | 该项是否通过 | `ConfirmChecklistRespVO.java:43-44` |
+| `failReason` | String | 未通过原因；通过时不赋值（为 `null`） | `ConfirmChecklistRespVO.java:46-47` |
+
+`items` 的 5 项及其数组顺序（`OrderDetailService.java:392-422` 按此顺序 `add`）：
+
+| # | `code` | `checkName` | 源码依据 |
+|---|--------|-------------|----------|
+| 1 | `PAYMENT_OK` | 款项校验 | `OrderDetailService.java:394-395` |
+| 2 | `TRAVELER_COMPLETE` | 出行人信息 | `OrderDetailService.java:897`（code）/ `:405`（checkName） |
+| 3 | `HOTEL_DONE` | 房型安排 | `OrderDetailService.java:946` / `:410` |
+| 4 | `VEHICLE_DONE` | 用车安排 | `OrderDetailService.java:1009` / `:416` |
+| 5 | `CONTRACT_TEMPLATE_OK` | 合同方案配置 | `OrderDetailService.java:1089` / `:421` |
+
+⚠️ **`checkName` 不要当必有字段用**：源码对五项都调了 `setCheckName`（行号见上表），但第八章那条逐字实测读数里**只有 `VEHICLE_DONE` 带 `checkName`**，其余四项该键缺省——两者对不上，成因本轮没有查清。展示层请以 `code` 为主键并用它兜底文案，`checkName` 只作可选补充。
+
+#### 响应示例①：全通过（`allPassed=true`｜格式示意）
+
+`items` 置 `null`，`preview` 有值。下面的**字段名取自 VO 源码**，值用的是 `@ApiModelProperty` 上的示例值（`ConfirmChecklistRespVO.java:55-142`），不是某一单的实测读数：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "allPassed": true,
+    "items": null,
+    "preview": {
+      "departureDate": "2026-05-30",
+      "totalPeopleCount": 14,
+      "driverName": "扎西师傅",
+      "driverPhoneMasked": "1398761****",
+      "hotels": [{ "cityName": "拉萨", "hotelName": "瑞吉度假酒店" }],
+      "staffs": [
+        {
+          "assignmentId": "1234567890123456789",
+          "staffId": "9876543210987654321",
+          "staffName": "扎西师傅",
+          "staffPhone": "1398761****",
+          "staffRole": "DRIVER",
+          "staffRoleName": "司机",
+          "isPrimaryReporter": true
+        }
+      ],
+      "contractAutoAction": { "planName": "标准跟团方案 v3.2", "autoSign": true },
+      "insuranceAutoAction": {
+        "planName": "安联境内旅行险 · 尊享版",
+        "peopleCount": 14,
+        "effectiveDescription": "出发前 24h 内生效"
+      }
+    }
+  }
+}
+```
+
+#### 响应示例②：接送机未就绪（实测原文，逐字）
+
+订单 `2101908228545937410`（行程用车 DONE + 接送机 PENDING），2026-09-22 测试服 `COMMIT=7811104b4` 只读 GET 的原始读数：
+
+```json
+{"code":200,"data":{"allPassed":false,"items":[{"code":"PAYMENT_OK","passed":true},{"code":"TRAVELER_COMPLETE","passed":true},{"code":"HOTEL_DONE","passed":false,"failReason":"用房需求未完成（当前: PENDING）"},{"code":"VEHICLE_DONE","checkName":"用车安排","passed":false,"failReason":"接送机需求未完成（镜像: DONE，当前需求: PENDING）"},{"code":"CONTRACT_TEMPLATE_OK","passed":true}],"preview":null}}
+```
+
+照着它写代码要注意两点：
+
+- `items` 里**五项都在**，通过的项也在数组里（`passed=true`）——不要按「出现在数组里就是失败项」渲染，要按 `passed=false` 筛。
+- 这条读数的信封只有 `code` 与 `data` 两个键；`Result` 本身还带 `message` / `success` / `traceId`（`Result.java:21-45`）。按 `data` 取值、按 `code` 判成败即可，不要依赖信封里某个键一定出现。
+
+#### 响应示例③：行程用车未就绪（**格式示意，本轮无活体读数**）
+
+第八章五单覆盖的是「接送机侧未就绪」与「两类均就绪」，**「行程用车未就绪」这一分支本轮没有活体读数**。下面只给 `items` 数组里 `VEHICLE_DONE` 那一项的片段，文案按源码字符串模板（`OrderDetailService.java:1060-1061`）逐字拼出，同轮其余四项照常返回：
+
+```json
+{
+  "code": "VEHICLE_DONE",
+  "checkName": "用车安排",
+  "passed": false,
+  "failReason": "行程用车需求未完成（镜像: PENDING，当前需求: PENDING）"
+}
+```
+
+#### 空数据 / 降级响应
+
+**无空数据场景**：`data` 恒是一个 `ConfirmChecklistRespVO` 对象，`allPassed` 必有值，`items` 与 `preview` 按 `allPassed` 互斥其一为 `null`（`OrderDetailService.java:427-432`）。
+
+**无降级分支**：调用链只读 order-v3 同进程的数据（活跃用车需求、配车记录、整团免车判定、房态、行程日、合同方案、保险方案、人员候选、出行人计数），不经跨服务 Feign，所以没有「下游挂了返回兜底值」这种形态。
+
+订单不存在不是空数据，走错误响应（HTTP 200 + body `code=581007`），见下节。
+
+#### 错误响应
+
+**HTTP 状态恒 200，成败看 body 里的 `code`。** 两处依据：
+
+- 业务异常 `BusinessException` 由全局 advice 处理，处理方法上标的是 `@ResponseStatus(HttpStatus.OK)`，body 为 `Result.error(code, message)`（`hl-common/hl-common-log/src/main/java/com/hulalv/common/exception/GlobalExceptionHandler.java:179-205`）。
+- 网关鉴权失败同样是 HTTP 200，401 / 403 只出现在 body 的 `code` 里（`hl-gateway/src/main/java/com/hulalv/gateway/filter/JwtAuthFilter.java:543-563`，该写入器注释原文：「HTTP status 永远 200 (项目铁规)」）。
+
+| body `code` | message | 触发条件 | 源码依据 |
+|---|---|---|---|
+| `200` | 成功 | 正常返回 | `Result.java:47-53` |
+| `581007` | 订单不存在 | `orderId` 查不到（判定在权限校验之前） | `OrderCoreErrorCode.java:17-19`、`OrderDetailService.java:778-782` |
+| `581008` | 无权查看此订单 | 非 ADMIN / SUPER_ADMIN / VEHICLE_MANAGER，且当前操作人不是本单定制师（`adminId != consultantId`） | `OrderCoreErrorCode.java:21-23`、`OrderViewGuard.java:99-102` 与 `:128-137` |
+| `581045` | 房务角色无权查看订单详情，房务仅可配房 | 角色为 ROOM_MANAGER / house_keeper_lead，Controller 入口即拒 | `OrderController.java:250-256`、`OrderViewGuard.java:67-79`、`OrderCoreErrorCode.java:211-213` |
+| `401` | 网关鉴权文案 | 未登录 / token 失效，请求被网关 JwtAuthFilter 拦在本服务之外 | `JwtAuthFilter.java:543-545` |
+
+错误 body 的关键字段（以订单不存在为例）：
+
+```json
+{ "code": 581007, "message": "订单不存在", "data": null }
+```
+
+#### 业务边界
+
+- **鉴权是两道门**：① Controller 入口 `OrderViewGuard.assertNotHouseRole()`，房务管理员 / 房务组长 → 581045（`OrderController.java:250-256`）；② `requireOrderById` 内 `OrderViewGuard.assertOrderReadable(entity)`，ADMIN / SUPER_ADMIN / VEHICLE_MANAGER 放行，其余角色必须是本单定制师，否则 581008（`OrderDetailService.java:778-787`、`OrderViewGuard.java:99-102`）。
+- **零角色账号可读**：网关没透传 `X-Admin-Role` 时（零角色 admin 账号签发的 token），`assertNotHouseRole` 按「无角色 → 放行」处理（`OrderViewGuard.java:67-72` 与该类 javadoc 的「已知例外」段）。前端不要把本接口能否调通当作角色可见性的判据。
+- **资源不存在**：`orderId` 查不到 → HTTP 200 + `code=581007`，不返回空对象（`OrderDetailService.java:778-782`）。
+- **只读**：入口标 `@Transactional(readOnly = true)`（`OrderDetailService.java:369`）；本轮逐个核过它直接调用的协作方法（活跃用车需求、配车记录、整团免车判定、房态、行程日、合同方案、保险方案、人员候选、出行人计数），方法体内都是查询口，未见写库分支。
+
+---
+
+## 四、契约约束与正确调用方式
+
+### 前端须知的 `failReason` 三个分支及其**精确拼法**
+
+本接口响应的 `failReason` 字段有三种不同的文案模板。**分支 2 与分支 3 的前缀拼法不同**，前端若对此字符串做精确匹配，需要逐一处理：
+
+| 分支 | 触发条件 | failReason 格式 | 示例 |
+|------|---------|-------------|------|
+| 1 | 订单未提交任何用车需求 | `未提交用车需求` | `未提交用车需求` |
+| 2 | 镜像或需求 status 非 DONE | `{类别中文名}需求未完成（镜像: {镜像值}，当前需求: {需求值}）` | `行程用车需求未完成（镜像: PENDING，当前需求: PENDING）` / `接送机需求未完成（镜像: DONE，当前需求: PENDING）` |
+| 3 | 无有效配车记录 | `{类别中文名}未找到有效配车记录` | `行程用车未找到有效配车记录` / `接送机未找到有效配车记录` |
+
+**关键限定一**：分支 2 的前缀是 `{类别中文名}需求未完成…`，分支 3 的前缀是 `{类别中文名}未找到有效配车记录`（无"需求"二字）。如果前端要按类别名跳转到对应 Tab，正则 `^{类别中文名}` 能覆盖两个分支，但若要区分**具体原因**，需要分别匹配两个不同的字符串模式。
+
+### 前端须知：`failReason` 指错的特殊情形
+
+**关键限定二**（已知缺口，不是本次改动遗漏，而是现有设计的短路条件决定的）：
+
+> **当且仅当**订单的镜像字段 `order_main.vehicle_control_status` **不是 DONE**、**且**该订单存在「行程用车」类活跃需求时，`failReason` 恒点名「行程用车」—— **即使真正落后的是接送机**。
+
+**原因**：判定短路条件是 `!镜像DONE || !该类自己DONE`（OR），镜像非 DONE 时循环在第一条就返回，而活跃需求列表按枚举声明序排（TRAVEL 先于 TRANSFER），所以点名永远是行程用车。
+
+**反过来的可信范围**（前端可用）：
+- 镜像 `vehicle_control_status` **为 DONE** 时，每一类按**自己的** status 独立判定，`failReason` **点名准确**。实测读数：`接送机需求未完成（镜像: DONE，当前需求: PENDING）`。
+- 订单**不存在**行程用车类活跃需求时（纯接送机单），循环第一条就是接送机，点名同样准确。
+
+**可操作的建议**：想用 `failReason` 做「跳转到对应 Tab」的深链是可行的，但**在镜像非 DONE 且存在行程用车需求这个窗口内需要额外逻辑** —— 比如先读全量需求列表，找出真正未就绪的那一类；或者让车务点击清单项后弹框让他选择哪一类的问题。**不要写成「这个字段永远不可信」**，那会让前端整个放弃深链功能，而大多数情形（镜像 DONE 或无行程用车需求）点名是准确的。
+
+---
+
+## 六、边界行为
+
+- **全通过时 `items` 为 `null`**（**既有契约，不是本单改动**：该写法自 2026-07-09 `a2b5e8cb3` 起就在，`OrderDetailService.java:429`）：前端按 `allPassed` 判分支，`items === null` 时只读 `preview`，不要无条件遍历 `items`。
+- **未通过时 `items` 是全量 5 项**：含 `passed=true` 的项，失败项靠 `passed=false` 筛（`OrderDetailService.java:392-422`，第八章实测读数同）。
+- **未登录**：网关 JwtAuthFilter 拦截，HTTP 200 + body `code=401`（`JwtAuthFilter.java:543-563`）。
+- **资源不存在**：HTTP 200 + body `code=581007`。
+- **权限不足**：HTTP 200 + body `code=581008`（非本单定制师）或 `code=581045`（房务角色）。
+- **不需要用车 / 整团免车**：`VEHICLE_DONE` 直接 `passed=true` 且无 `failReason`——订单 `needs_vehicle=false`（`OrderDetailService.java:1011-1013`），或所在团已声明整团免车（`OrderDetailService.java:1016-1018`）。
+- **需要用车但一条需求都没提**：`VEHICLE_DONE` `passed=false`、`failReason="未提交用车需求"`，这是正常返回不是异常（`OrderDetailService.java:1023-1026`）。
+- **下游服务降级**：无，调用链全在 order-v3 同进程，不经 Feign。
+
+---
+
+## 六.5、枚举
+
+### 用车类别（`VehicleRequirementKind`）
+
+**所属字段**: `failReason` 中的类别中文名前缀 | **类型**: `String`
+
+| 枚举值 | 中文名 | 说明 |
+|-------|-------|------|
+| `TRAVEL` | 行程用车 | 团期行程用车，服务日冻结为行程日 |
+| `TRANSFER` | 接送机 | 接送机，服务日取航班/车次日期 |
+
+---
+
+## 六.6、修改前后对比
+
+「改前」指的是本次提交 `7811104b4` 的父提交（#8056 已合入之后的状态），不是更早的历史版本。
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| 同一订单同时有行程用车 + 接送机，行程用车已 DONE、接送机未就绪 | `VEHICLE_DONE` `passed=true`（**错误**），清单放行 | `passed=false`，`failReason` 点名接送机（需求未 DONE 走分支 2、缺配车记录走分支 3），清单拦截 |
+| `failReason` 文案 | 无类别前缀：`用车需求未完成（镜像: X，当前需求: Y）` / `未找到有效配车记录` | 两个失败分支都带类别中文名前缀，拼法见第四章三分支表 |
+
+本次改动只落在上面两行：`items` / `preview` 的互斥语义、5 项的 `code` 与 `checkName`、`preview` 的字段集合**都没有变**（依据：`7811104b4` 只改了 `OrderDetailService` / `VehicleRequirementKind` / `RequirementService` 与一份单测，`ConfirmChecklistRespVO` 与 `OrderController` 零改动）。
+
+---
+
+## 六.7、影响评估
+
+- **响应结构**：无变化。`allPassed` / `items` / `preview` 的字段与互斥语义、5 项的 `code` 与 `checkName` 均与改前一致。
+- **是否破坏向后兼容**：只在 `failReason` 文案上。改后两个失败分支的文案前面多了类别中文名（`行程用车` / `接送机`），前端若对该字符串做**精确匹配**会失配；只当文案展示则不受影响。
+- **前端是否必须同步上线**：仅当前端对 `failReason` 做了精确匹配或前缀判断时需要同步；纯展示场景无需改动。
+- **判定口径收紧**：两类需求并存的订单，改前可能 `passed=true`、改后 `passed=false`。前端不用改代码，但页面上会看到以前能确认的单现在被清单拦住——这是本次修复的预期结果。
+
+---
+
+## 七、不影响范围
+
+- **仅影响**: 管理后台订单详情「确认核单」清单页面
+- **零影响**:
+  - 订单创建接口
+  - 订单列表、详情查询（非确认流程）
+  - 支付、房间、合同等其他核单项
+  - 前端对用车需求的编辑操作（创建、修改、删除需求的接口无改）
+  - 历史数据（已确认的订单数据无回溯影响）
+
+---
+
+## 八、测试环境已验证
+
+2026-09-22 在测试服（hl-order-service-v3 `COMMIT=7811104b4`、`BEHIND=0`、`STATE=ok`）用只读 GET 取证，五单：
+
+| 订单 | 形态 | `VEHICLE_DONE.passed` | `failReason` 实测原文 |
+|---|---|---|---|
+| `2101908228545937410` | 行程用车 DONE + 接送机 PENDING | `false` | `接送机需求未完成（镜像: DONE，当前需求: PENDING）` |
+| `2098374030837829634` | 两类需求都已派车 | `true` | `null` |
+| `2101146798373339137` | 全项就绪 | — | 整个 `items` 为 `null` |
+| `2087157633055064066` | 只有行程用车（TRAVEL-only） | `true` | `null` |
+| `2101018930892972033` | 只有接送机（TRANSFER-only） | `true` | `null` |
+
+`2101908228545937410` 的完整响应（逐字原始读数）：
+
+```json
+{"code":200,"data":{"allPassed":false,"items":[{"code":"PAYMENT_OK","passed":true},{"code":"TRAVELER_COMPLETE","passed":true},{"code":"HOTEL_DONE","passed":false,"failReason":"用房需求未完成（当前: PENDING）"},{"code":"VEHICLE_DONE","checkName":"用车安排","passed":false,"failReason":"接送机需求未完成（镜像: DONE，当前需求: PENDING）"},{"code":"CONTRACT_TEMPLATE_OK","passed":true}],"preview":null}}
+```
+
+**这五单覆盖不到的地方**：它们全是「接送机侧未就绪」或「两类均就绪」，**「行程用车未就绪」那一分支本轮没有活体读数**。第三章「响应示例③」里该分支的文案是按源码字符串模板（`OrderDetailService.java:1060-1061`）拼出的**格式示意**，不是实测读数；前端要对它做精确匹配的话，以源码模板为准。
+
+---
+
+## 十、相关文档
+
+本单契约的源码落点（`origin/dev-v3`，供对照取证）：
+
+- 接口入口：`hl-order-service-v3/src/main/java/com/hulalv/order/core/controller/admin/OrderController.java:250-256`
+- 清单装配：`hl-order-service-v3/src/main/java/com/hulalv/order/core/service/OrderDetailService.java:369-432`
+- 用车逐类判定与 `failReason` 拼法：同上文件 `:1006-1080`
+- 响应 VO：`hl-order-service-v3/src/main/java/com/hulalv/order/core/controller/admin/vo/ConfirmChecklistRespVO.java`
+- 错误码：`hl-order-service-v3/src/main/java/com/hulalv/order/errorcode/OrderCoreErrorCode.java:17-23`、`:211-213`
+- 权限守卫：`hl-order-service-v3/src/main/java/com/hulalv/order/core/guard/OrderViewGuard.java:67-79`、`:99-137`
+- 用车类别枚举：`hl-order-service-v3/src/main/java/com/hulalv/order/requirement/enums/VehicleRequirementKind.java`
+
+工单与提交链接见下方「关联 / 联系人」。
+
+---
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8121](https://git.1814.love:8443/wx/HL/issues/8121)
+- **Commit**: [7811104b4](https://git.1814.love:8443/wx/HL/commit/7811104b4)
+
+### 联系人
+
+- **后端负责人**: @wx
@@ -0,0 +1,425 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8122"
+title: "团期 staff 保存：scopeRoles 必须整位覆盖，半位声明一律拒绝且零写入（新错误码 582116）"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "not_required"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "4f65c4535987dab205651d84952fe152579a418d"
+target_release: "v2.1"
+verified_at: "2026-09-22"
+status_note: "backend_status=deployed: hl-order-service-v3 测试服双实例（8086 / 8186）当前运行 sha=ef7611138，即本单合并提交（PR #8147）本身，不是它的后代——无需 merge-base 推导。三条互相独立的判据：①deploy-status.sh 登记 dev-v3 / ef7611138 / BEHIND=0；②jar /opt/hulalv/jars/hl-order-service-v3-1.0.0-SNAPSHOT.jar mtime=epoch 1790039292（2026-09-22 09:08:12），两实例 /proc/<pid> 启动时刻 epoch 1790039294 与 1790039307 均晚于 jar mtime，且两进程 fd 均指向该 jar 路径、无 (deleted)；③Nacos 两实例 healthy:true & enabled:true，启动日志 Flyway 正常、ERROR/Exception/APPLICATION FAILED TO START 零命中。⚠️ 覆盖边界：HTTP 级业务健康（本接口的端到端实际返回）未在测试服实测，本单取证在 Testcontainers 真库 IT 完成（见正文第八节），两者是不同环境、不可互相替代。gateway_status=not_required: 本单改动 6 个文件全在 hl-order-service-v3 模块内，未涉及 hl-gateway 任何路由/Nacos 配置；PUT /v3/admin/group-batch/{productBatchId}/staff 是存量端点、路径本身未变，命中既有通配路由（Path=/v3/admin/**），本单没有引入任何新路径段。frontend_status=pending: 按规范后端不代填 implemented/released/verified，是否需要改动与是否完成由前端自行回写 frontend_owner 与 verified_at。本单对现有前端实现的影响评估见正文「六.7 影响评估」——结论是 mmg 在 #8006 交付的 scopeRoles=roleMeta.memberRoles（GUIDE 位含 GUIDE+LEADER 双角色）本身已是整位覆盖，不会命中新错误码，但该结论基于 hl-ui origin/v2.1 @ b5666b38 的源码读数，请前端按自己分支的实际实现复核。 前端回写(2026-09-22, mmg): 复核本分支实现——scopeRoles=roleMeta.memberRoles(GUIDE 位 GUIDE+LEADER)本就整位覆盖,不命中 582116,行为零改动;已按点名订正 orderV2GroupBatch.js 注释错码(582115→582116)并在 ROLE_META 处补字典驱动风险提示(字典化读取待 #8148 闭环后评估);交付 commit 4f65c453(注释订正,无行为变更),checkpoint 全量绿。"
+updated_at: "2026-09-22"
+base: "dev-v3"
+---
+
+# order-v3: 团期 staff 保存，scopeRoles 必须整位覆盖（新错误码 582116）
+
+> **存放目录**: `changelogs-v2/2026-09/`
+>
+> **服务**: hl-order-service-v3 (端口 8086 / 8186)
+> **PR**: #8147
+> **Issue**: #8122
+> **日期**: 2026-09-22
+> **影响范围**: 团期 staff 配置保存接口 `PUT /v3/admin/group-batch/{productBatchId}/staff`
+
+---
+
+## ⚠️ 关键变化
+
+**这是一次行为收紧：一类此前返回 HTTP 200 的请求，现在会被拒绝（业务码 582116）。**
+
+具体是：`scopeRoles` 只要**触及**某个配置位，就必须**覆盖该配置位的全部成员角色**。
+只声明半个配置位（例如导游位只传 `["GUIDE"]`、不带 `LEADER`）会被拒绝，且**零写入**。
+
+改前这类请求返回 200，但只删掉并重建了被声明的那半边，位内其余人员**原样留在库里**，
+还会继续扇到每一张子订单——用户在回显里看见「领队怎么还在」。
+
+✅ **对既有错误码零影响**：改前已被 582114 / 582115 拒掉的请求，错误码一字不变。
+本单只改变**改前返回 200** 的那些请求的结论。
+
+---
+
+## 一、背景
+
+`scopeRoles` 由 #8006 引入，语义是「本次保存只覆盖这些角色」。它同时承担两件事：
+
+1. **插入白名单**——提交的人只能落在声明的角色里（越界抛 582115）；
+2. **删除窗口**——软删只删声明的那些角色的旧行。
+
+此前只有 (1) 被守卫住，(2) 从没有任何一处校验过。于是「声明了半个配置位」这种请求，
+插入侧完全合法（提交的人确实都在范围内），删除侧却只擦掉了半边：
+
+- 导游位原有 1 名领队（LEADER）+ 1 名导游（GUIDE）；
+- 用户在弹窗里删掉领队、只留导游，前端发 `scopeRoles=["GUIDE"]`；
+- 服务端只删 GUIDE 行、插新 GUIDE 行，**那条 LEADER 一行没动**；
+- 接口返回 200，无任何错误码；该 LEADER 经异步扇出继续写进每一张子订单。
+
+⚠️ #8006 的交接件里已写过「导游位必须同时传 `GUIDE` 与 `LEADER`」，但那当时只是**对前端的请求**，
+服务端没有对应守卫——把这句话从文档里整句删掉，代码行为一字不变、没有一个用例会红。
+本单把它变成服务端强制的不变量。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 保存团期 staff 配置 | PUT | `/v3/admin/group-batch/{productBatchId}/staff` | 新增拒绝分支 | 新增业务码 `582116`；入参结构、出参结构、字段类型全部未变 |
+
+**入参、出参、字段类型全部未变。** 本单只新增一条校验与一个业务错误码。
+
+---
+
+## 三、接口详情
+
+### 1. 保存团期 staff 配置（含扇出） `PUT /v3/admin/group-batch/{productBatchId}/staff`
+
+**VO**: `BatchStaffConfigReqVO → BatchStaffConfigRespVO`（两者结构均未变，见 21_8006 交接件）
+
+#### 使用场景
+
+团期详情页「导游位」「摄影位」两个弹窗各自维护本位人员时调用。每个弹窗用 `scopeRoles`
+声明自己负责的角色范围，只提交本位人员，互不影响（#8006）。
+本单新增的约束落在这个场景的正中间：**弹窗声明的范围必须是完整的配置位**，
+否则本位里没被声明的那些人会被静默留在库里。
+
+#### 入参
+
+**路径参数**
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `productBatchId` | Long（路径） | 是 | 产品侧班期 ID |
+
+**请求体** `BatchStaffConfigReqVO`
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| `scopeRoles` | body | `String[]` | 否 | 元素取值域 `LEADER\|GUIDE\|DRIVER\|PHOTOGRAPHER\|OTHER\|GUIDE_ASSISTANT\|STUDY_TEACHER\|LIFE_TEACHER`；传了就不能是空数组（`@Size(min=1)`，否则 `code=400`） | 本次覆盖的角色范围。**不传 = 整期全量覆盖**（历史行为）。🔴 **本单新增：传了则必须整位覆盖**，否则 582116 |
+| `staffList` | body | `Item[]` | **是** | `@NotNull`；显式传 `[]` = 清空覆盖范围 | 覆盖范围内的最终状态。**缺字段一律 `code=400`**（审计 F-03，Refs #6950 / #7377：改前缺字段会被当成"传空=清空"，静音软删整团配置还返成功） |
+| `staffList[].staffId` | body | Long | 是 | `@NotNull` | 用户域员工 ID |
+| `staffList[].staffRole` | body | String | 是 | `@NotBlank` + 同上取值域 | 员工角色 |
+| `staffList[].sortOrder` | body | Integer | 否 | — | 展示排序，默认 0 |
+| `staffList[].remark` | body | String | 否 | `@Size(max=500)` | 备注 |
+
+#### 出参
+
+`BatchStaffConfigRespVO`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `productBatchId` | String | 回显路径参数（`@JsonSerialize(ToStringSerializer)`，**JSON 里是字符串**），恒非 null |
+| `groupBatchId` | String | 运营团期 ID（同上，字符串）。本端点入口有成团守卫，200 响应中恒非 null |
+| `staffList` | `BatchStaffItemVO[]` | 保存后的配置快照 |
+| `staffList[].id` | Number | 记录 ID（`batch_staff_id`） |
+| `staffList[].staffId` | Number | 用户域员工 ID |
+| `staffList[].staffRole` / `staffRoleName` | String | 角色码 / 中文名（取值不在枚举内时回落原 code） |
+| `staffList[].staffName` / `staffPhone` / `avatarUrl` | String | 姓名 / 手机（脱敏前 3 后 4）/ 头像，均为 Feign 反查后冻结的快照 |
+| `staffList[].sortOrder` | Integer | 展示排序 |
+| `staffList[].remark` | String | 备注 |
+| `staffList[].reporterRank` / `reporterRankName` | String | 报账人等级 `PRIMARY`/`SECONDARY`/`NONE` 及中文名，恒非 null（空值归一为 `NONE`） |
+| `affectedOrderCount` | int | 扇出影响的活跃订单数 |
+
+🔴 本单对入参、出参的**字段集合与类型零改动**，上两表与改前逐字一致，列在此处只为本文件自包含。
+
+#### 请求示例
+
+```http
+PUT /v3/admin/group-batch/80001/staff
+Content-Type: application/json
+```
+
+```json
+{
+  "scopeRoles": ["GUIDE", "LEADER"],
+  "staffList": [
+    { "staffId": 40001, "staffRole": "GUIDE", "sortOrder": 0, "remark": "首席导游" }
+  ]
+}
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 0,
+  "msg": "",
+  "data": {
+    "productBatchId": "80001",
+    "groupBatchId": "90211",
+    "staffList": [
+      {
+        "id": 770001,
+        "staffId": 40001,
+        "staffRole": "GUIDE",
+        "staffRoleName": "导游",
+        "staffName": "刘导游",
+        "staffPhone": "138****6677",
+        "avatarUrl": null,
+        "sortOrder": 0,
+        "remark": "首席导游",
+        "reporterRank": "NONE",
+        "reporterRankName": "非报账人"
+      }
+    ],
+    "affectedOrderCount": 3
+  }
+}
+```
+
+#### 空数据 / 降级响应
+
+**清空某个配置位**（整位声明 + 空 `staffList`）后，`staffList` 返回的是**整期最终状态**
+（不是本次提交的空数组）——范围外角色的既有行仍在其中。整期一个人都没有时才是空数组：
+
+```json
+{
+  "code": 0,
+  "msg": "",
+  "data": {
+    "productBatchId": "80001",
+    "groupBatchId": "90211",
+    "staffList": [],
+    "affectedOrderCount": 3
+  }
+}
+```
+
+**字典降级**：配置位成员读字典（Feign hl-system 字典）。字典读空或 Feign 失败时，
+服务端**回落到内置兜底成员**（导游位 `GUIDE`+`LEADER`、摄影位 `PHOTOGRAPHER`），
+不会沿用脏缓存、也不会因此放行半位声明 ⇒ 降级期间 582116 的判定按兜底成员进行。
+
+#### 错误响应
+
+| 业务码 | 常量 | 文案（`{0}`/`{1}` 运行期填充） |
+|---|---|---|
+| **582116** | `AssignmentErrorCode.SCOPE_ROLES_SLOT_INCOMPLETE` | `本次保存声明的角色范围（{0}）只覆盖了配置位的一部分，还缺少 {1}；同一配置位的角色必须一起声明，否则位内其余人员会被留在库里` |
+
+- `{0}` = 本次请求的 `scopeRoles` 原样内容，以 `/` 连接（例：`GUIDE`）
+- `{1}` = **缺失的同位角色**，以 `/` 连接（例：`LEADER`）
+
+⇒ 文案本身就把「该补什么」告诉了调用方，前端可直接透传 `message` 给用户。
+
+**被拒响应体**（🔴 **HTTP 状态行是 200**，业务失败写在 `code` 里，别按状态码判成败）
+
+```json
+{
+  "code": 582116,
+  "msg": "本次保存声明的角色范围（GUIDE）只覆盖了配置位的一部分，还缺少 LEADER；同一配置位的角色必须一起声明，否则位内其余人员会被留在库里",
+  "data": null
+}
+```
+
+其余错误码本单**未新增也未改动**：
+
+| 业务码 | 触发 |
+|---|---|
+| `400` | `@Valid` 参数级校验失败（`staffList` 缺字段、`scopeRoles: []`、角色不在取值域）。同样是 HTTP 200，`msg` 为各字段 `message` 用 `"; "` 拼接 |
+| `582114` | 所选人员的角色与其人员类型不符 |
+| `582115` | 提交的人员角色超出本次声明的 `scopeRoles`（与 582116 的分工见第四节） |
+
+#### 业务边界
+
+**判定规则**——对**每一个**配置位分别判定：
+
+```
+touched  = scopeRoles 里至少有一个元素属于该配置位
+missing  = 该配置位的成员角色中，scopeRoles 没有声明的那些
+若 touched 且 missing 非空 ⇒ 抛 582116
+```
+
+配置位当前有两个：
+
+| 配置位 | 字典类型 | 成员角色（字典读不到时的兜底值） |
+|---|---|---|
+| 导游位 `GUIDE` | `group_batch_staff_slot_guide` | `GUIDE`、`LEADER` |
+| 摄影位 `PHOTOGRAPHER` | `group_batch_staff_slot_photographer` | `PHOTOGRAPHER` |
+
+🔴 **成员角色由字典决定，不是代码常量。** 表中列的是「字典读不到时的兜底值」，
+运行期真实成员以字典 `dict_type` 下的行为准——业务在字典管理页面往导游位加一个角色，
+第二天起 `scopeRoles` 就必须带上它，**服务端不需要改代码，这个过程不产生任何接口变更**。
+⇒ 前端不应把成员角色写死在代码里，应按配置位动态取用；
+写死 `["GUIDE","LEADER"]` 的实现会在业务改字典的那一刻开始收到 582116。
+
+其余边界：
+
+- **`scopeRoles` 整个字段不传** = 整期全量覆盖，本守卫不参与判定，历史行为逐字不变。
+- **零写入**：582116 在任何库写动作之前抛出（守卫排在写入序列的 1.6 位），被拒的请求不产生
+  任何插入 / 更新 / 软删，也不触发向订单的扇出，`affectedOrderCount` 不会被消耗。
+- **不属于任何配置位的角色**（`DRIVER`、`OTHER`、`STUDY_TEACHER`、`LIFE_TEACHER`）：
+  对两个配置位的 `touched` 都恒为 false，单独声明它们**不会**被本守卫拦下。
+- **字典判定带 5 分钟进程内缓存，服务多实例**：改完字典后最多 5 分钟内，
+  两个实例对同一个 `scopeRoles` 可能给出不同判定（一个放行一个 582116）。重试即可收敛。
+- **`scopeRoles: [null]`** 当前绕得过本守卫（元素级 `@Pattern` 对 null 恒真），已立 **#8150**；
+  前端不要构造含 null 的数组——它绕过的是保护，不是限制。
+
+---
+
+## 四、契约约束与正确调用方式
+
+| # | payload（节选） | 结果 | 说明 |
+|---|---|---|---|
+| ✅ | `{"scopeRoles": ["GUIDE","LEADER"], "staffList": [...]}` | 200 | 导游位整位声明，本单的正确写法 |
+| ✅ | `{"scopeRoles": ["GUIDE","LEADER"], "staffList": []}` | 200 | **清空导游位**：整位声明 + 空人员表，位内两个角色的旧行一起被删 |
+| ✅ | `{"scopeRoles": ["PHOTOGRAPHER"], "staffList": [...]}` | 200 | 摄影位只有一个成员，单元素即整位 |
+| ✅ | `{"staffList": [...]}`（不传 `scopeRoles`） | 200 | 整期全量覆盖，守卫整体短路，行为与改前逐字一致 |
+| ✅ | `{"scopeRoles": ["DRIVER"], "staffList": [...]}` | 200 | `DRIVER` 不属于任何配置位 ⇒ 一个位都没 touched ⇒ 守卫不介入 |
+| ❌ | `{"scopeRoles": ["GUIDE"], "staffList": [...]}` | **582116** | 触到导游位却缺 `LEADER` |
+| ❌ | `{"scopeRoles": ["LEADER"], "staffList": []}` | **582116** | 同上，缺 `GUIDE`；**注意 `staffList` 为空也照样拒**（见下） |
+| ❌ | `{"scopeRoles": ["GUIDE","PHOTOGRAPHER"], "staffList": [...]}` | **582116** | 跨两个位，导游位缺 `LEADER` |
+
+🔴 **`staffList` 为空不豁免。** 「清空导游位」正是本单最需要拦住的路径：
+它一个越界的人都没有（582115 永远不会触发），却会把位内没声明的那些人**永久留在库里**。
+清空某个位的正确写法是「整位声明 + 空 `staffList`」，见上表第 2 行。
+
+### 与 582115 的分工（两码不可互换）
+
+| | 582115 | 582116 |
+|---|---|---|
+| 说的是 | 你**提交的人**越界了 | 你声明的**范围本身**不是一个完整的配置位 |
+| 改法 | 改 `staffList`，或扩 `scopeRoles` | 只有一条：把缺的同位角色补进 `scopeRoles` |
+| `staffList` 可否为空 | 否（没有人就没有越界的人） | **是** |
+
+⇒ 前端两个错误码要分开处理：582115 引导用户去改人员勾选，582116 是前端自己的 payload 拼错了。
+
+### ⚠️ `hl-ui` 现有注释把本场景的错误码写错了
+
+`src/api/orderV2GroupBatch.js:291`（读取对象 `origin/v2.1` `17eb03ec`，2026-09-22 06:27 提交）写的是：
+
+> 导游位并收 GUIDE+LEADER，保存导游位 scopeRoles 必须两个都传，**缺一 582115**。
+
+这个错误码不成立，两个方向都不成立：
+
+- 本单上线**之前**：缺一同位角色的请求返回 **200 且无任何错误码**，位内没声明的那些人被静默留在库里，
+  还会经扇出写进每一张子订单——这正是本单要修的缺陷，不存在任何拒绝。
+- 本单上线**之后**：缺一被拒，错误码是 **582116**，不是 582115。
+
+⇒ 按 582115 写的错误处理分支在「缺一同位角色」这条路径上**从来不会命中**；
+该注释相邻的另一句「582115 = staffList 角色超出 scopeRoles」（`GroupBatchStaffConfigModal.vue:100`）是对的，
+要改的只有 `orderV2GroupBatch.js:291` 这一句。
+
+---
+
+## 五、数据库行为
+
+| 场景 | `group_batch_staff` | 子订单 `order_batch_staff` |
+|---|---|---|
+| 命中 582116 | **零写入** | **零写入** |
+| 通过 | 与改前一致（软删声明范围内旧行 + 插入新行） | 与改前一致（`afterCommit` 异步扇出） |
+
+🔴 **「零写入」指的是软删从没有执行过，不是「执行了又回滚」。**
+守卫落在事务开启**之前**，走不到软删那一行。真库 IT 用 `openSession(true)`（autoCommit）
+从另一条连接读取，若软删跑过就会当场提交、读不到「原样」——该断言对两种情形有分辨力。
+
+---
+
+## 六、边界行为
+
+1. **不传 / 传空数组 `scopeRoles`** ⇒ 守卫整体短路，整期全量覆盖语义与改前**逐字一致**。
+2. **`scopeRoles` 全是不属于任何配置位的角色**（如 `["DRIVER"]`）⇒ 一个位都没 touched，放行。
+3. **守卫顺序**：582114（人员类型不符）→ 582115（提交的人越界）→ **582116**（范围半位）→ 事务。
+   ⇒ 一个请求若同时满足 582115 与 582116 的条件，返回的是 **582115**（先到先抛）。
+4. 🔴 **配置位成员有 5 分钟本地缓存，且服务是双实例。**
+   `GroupBatchStaffSlotResolver` 对字典结果做 5 分钟 TTL 的进程内缓存，测试服与生产的
+   order-v3 均为多实例 + 网关轮询。⇒ **业务刚改完字典的 5 分钟内，同一个 payload 可能在一个实例上通过、
+   在另一个实例上撞 582116。** 这个窗口过后两边一致。前端遇到这种抖动不必特殊处理，
+   按 `{1}` 提示补齐 `scopeRoles` 即可——补齐后的 payload 在新旧两种口径下都是合法的。
+5. **`scopeRoles` 元素为 `null`**（`["GUIDE", null]` 这类）：元素级校验目前对 `null` 恒真，
+   该元素不会触及任何配置位。若整个数组只有 `null`，请求会成为一次返回 200 的空操作。
+   属存量缺口，已立 **#8150** 跟进。正常调用方不会构造这种 payload。
+
+## 六.5、枚举 / 数据字典
+
+| 字典类型 | 含义 | 维护方 |
+|---|---|---|
+| `group_batch_staff_slot_guide` | 导游位收哪些人员类型 | 业务在字典管理页面维护 |
+| `group_batch_staff_slot_photographer` | 摄影位收哪些人员类型 | 同上 |
+
+服务端对字典值做白名单过滤（合法集合：`GUIDE`、`GUIDE_ASSISTANT`、`PHOTOGRAPHER`、`LEADER`、
+`OTHER`、`STUDY_TEACHER`、`LIFE_TEACHER`），字典里的非法值会被丢弃；字典读空或 Feign 失败时
+回落到上表的兜底值，不会沿用脏缓存。
+
+## 六.6、修改前后对比
+
+**行为级**
+
+| 请求形态 | 改前 | 改后 |
+|---|---|---|
+| `scopeRoles` 半位声明，`staffList` 非空 | 200，位内未声明的旧行残留并扇到子订单 | **582116**，零写入 |
+| `scopeRoles` 半位声明，`staffList` 为空 | 200，位内未声明的旧行残留 | **582116**，零写入 |
+| `scopeRoles` 整位声明 | 200 | 200（不变） |
+| 不传 `scopeRoles` | 200，整期全量覆盖 | 200（不变） |
+| 命中 582114 / 582115 的请求 | 对应错误码 | **对应错误码不变** |
+
+**字段级**：无变化（无新增/删除/改名字段，无类型变化）。
+
+## 六.7、影响评估
+
+🔴 **任何当前发送「半个配置位」的调用方，都会从 200 变成 582116。** 这是本单的预期效果，
+但它是一次**破坏性收紧**，请前端按自己分支的实际实现逐处核对。
+
+已做的评估（**源码读数，非联调实测**）：mmg 在 #8006 交付的实现
+（`hl-ui` origin/v2.1 @ `b5666b38`，`GroupBatchStaffConfigModal`）按配置位取
+`scopeRoles = roleMeta.memberRoles`，导游位取到的是 `GUIDE + LEADER` 双角色
+⇒ 本身已是整位覆盖，**不会**命中 582116。该结论的效力止于那个 sha 的源码，
+若前端另有分支或后续改动，请以自己的实现为准。
+
+---
+
+## 七、不影响范围
+
+- 团期 staff **查询**接口 `GET /v3/admin/group-batch/{productBatchId}/staff`：零改动。
+- 单订单 staff 接口 `/v3/admin/order/{id}/staff`：零改动，不走本守卫。
+- 司机（`DRIVER`）：由车务派车投影产生，不在任何配置位里，本守卫对它零影响。
+- 异步扇出链路、`guide_ready` / `photographer_ready` 回填、四 ready 闸门：逻辑零改动
+  （通过的请求扇出行为与改前完全一致）。
+- 网关路由、Nacos 配置、数据库表结构：零改动。
+
+---
+
+## 八、测试环境已验证
+
+**真库集成测试**（Testcontainers MySQL 8.0.33，非 H2、非 Mockito）
+`GroupBatchStaffSaveConfigSlotCompletenessMysqlTest`：**8/8 通过**
+
+| 验证项 | 做法与读数 |
+|---|---|
+| 缺陷确实存在 | 临时注释掉守卫后跑，团期表与子订单表**都**残留 `LEADER` 行；前置由真实 `saveConfig` + `afterCommit()` 产生，非 SQL 直插 |
+| 零写入 | `SELECT *` 整行逐字段比对（含 `deleted_at`、`update_time`）均与保存前相同；用 `openSession(true)` 从另一条连接读，对「回滚」与「从没发生」有分辨力 |
+| 字典驱动**确实生效** | 把 `slotResolver.typesOf(slot)` 变异成写死的兜底表，重编译确认后 7 个用例里**唯一转红**的正是「字典新增 `GUIDE_ASSISTANT` 后旧 `scopeRoles` 被拒」那条（变异已还原） |
+| 阴性对照 ×4 | 整位声明放行 / 补齐字典新成员后放行 / `["DRIVER"]` 不触位放行 / 不传 `scopeRoles` 保持全量覆盖语义 |
+
+**回归**：`GroupBatchStaffConfigServiceTest*` 77/77、`Baseline` 3/3、`Scoped` 2/2、
+`AdminControllerPermissionTest` 6/6、`ReqVOValidationTest` 6/6、`ConfigServiceGateTest` 5/5、
+`RedLineArchTest` 12/12。
+
+**测试服部署**：双实例 8086 / 8186 运行 `ef7611138`（即 PR #8147 的合并提交本身），
+Nacos 两实例 `healthy:true`，启动日志无异常。判据与覆盖边界见 frontmatter 的 `status_note`。
+
+---
+
+## 九、已知缺口（不在本单范围，已立单跟进）
+
+- **#8148**：`allowedStaffTypesForRole` 写死 `GUIDE`/`LEADER`/`PHOTOGRAPHER` 三个分支、不读字典（存量）。
+  本单提升了它的影响：业务往导游位字典加 `GUIDE_ASSISTANT` 后，`scopeRoles` **必须**带上它（否则 582116），
+  而真正 `staffType=GUIDE_ASSISTANT` 的人提交时仍会被 **582114** 挡死。
+  🔴 **⇒ 现阶段「字典加一个角色」只启用了范围判定这一半，那类人员还配不进去。**
+  前端若正在规划「新增人员类型」相关交互，这条是必须知道的边界。
+- **#8150**：`scopeRoles` 元素级校验对 `null` 恒真（存量，见「六、5」）。
+
+---
+
+## 十、相关文档
+
+- `22_8006_团期人员保存支持按角色范围覆盖-修改接口-管理后台.md` —— `scopeRoles` 入参的引入者，入参/出参/响应结构以它为准
+- `changelogs-v2/2026-09/` 下 #7079 相关条目 —— 配置位字典化
+
+## 关联 / 联系人
+
+- Issue: #8122 ｜ PR: #8147 ｜ 后续单: #8148、#8150
+- 后端: wx ｜ 管理后台前端: mmg
@@ -0,0 +1,246 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8127"
+title: "应付款付款支持冲抵供应商预付款（差额付款 + 占用/付讫/回冲状态机）"
+consumer: "admin"
+author: "yst(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "not_required"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "d0a264ec33214617f5ee3ca500b0f9ebd76b4bb6"
+target_release: "v2.1"
+verified_at: "2026-09-22"
+status_note: "backend_status: deployed - hl-order-service-v3 已部署测试服（dev-v3，含 finance 同进程），E2E 全链路 PASS（改单加冲抵→审批→出纳差额付款，往来净额/预付余额/冲抵明细 SETTLED 全对，2026-09-22 取证）; gateway_status: not_required - 零网关改动，/admin/finance/** 走 hl-gateway 既有通配路由; frontend_status: pending - 前端适配情况未知，后端不代填。 前端核验(2026-09-22): 已交付 hl-admin d0a264ec——payable.js 加 getOffsettablePrepayments+PREPAY_OFFSET_STATUS meta+4 写口 JSDoc(单笔 create 前端无调用方仅补文档);新共享组件 PrepayOffsetPicker(勾选+金额≤availableAmount+598812/598813 前置校验);PaymentDetailPanel 详情冲抵金额/实付金额+offsets 状态机明细卡、编辑草稿冲抵区块(回显仅 OCCUPYING,整体置换恒传,空数组清占用);GroupPayPanel 按供应商分组上送、SupplierPayPanel 单元素分组;出纳页零改动(#7815 锁 actualAmount 槽位);598812-598817 透 message;原型 pay-adv 冲抵记录子 tab 契约无列表读口,未造数留痕待后端;Vitest 23/23+checkpoint 全量 13 项全绿。"
+updated_at: "2026-09-22"
+base: "dev-v3"
+---
+
+# 财务：应付款付款支持冲抵供应商预付款（Epic #8127）
+
+> 应付款付款时可用「该供应商已付讫且有余额的预付款」冲抵，出纳只付差额现金。涉及 4 个建单/改单接口入参新增、付款单详情出参新增、新增 1 个可冲抵预付查询接口。
+
+## ① 接口背景
+
+供应商常有预付（先打款后结算）。此前预付款与应付款是两条独立线，应付款付款只能全额现金支出，无法用已预付的余额抵扣，资金占用高。本变更让应付款付款单可勾选「该供应商的预付款」做冲抵：冲抵部分无现金流出，出纳仅按「应付金额 − 冲抵金额 = 实付金额」付差额。
+
+三个口径决策（后端已定）：
+- **冲抵算 paid**：冲抵部分随现金一并计入应付台账已付，清偿方式不影响应付债务的付讫认定。
+- **占用时点=建单时**：建单/改单（PENDING 草稿）即扣减预付可用余额并落「占用中」明细，驳回/删改草稿回冲，付讫转「已冲抵」。
+- **往来差额归零**：付讫时补一对抵销分录，付款单文档净额=0、预付单文档净额=剩余可用余额，供应商往来对账自清。
+
+## ② 变更清单
+
+| 类型 | 接口 | 变更 |
+|---|---|---|
+| 修改 | `POST /admin/finance/payments` 创建付款单 | 入参新增 `prepayOffsets[]` |
+| 修改 | `POST /admin/finance/payments/batch` 按订单批量创建 | 入参新增 `prepayOffsets[]`（按供应商分组） |
+| 修改 | `POST /admin/finance/payments/batch-by-supplier` 按供应商合并创建 | 入参新增 `prepayOffsets[]`（按供应商分组） |
+| 修改 | `PUT /admin/finance/payments/{id}` 编辑草稿 | 入参新增 `prepayOffsets[]`（整体置换语义） |
+| 修改 | `GET /admin/finance/payments/{id}` 付款单详情 | 出参新增 `offsets[]`；`prepayOffsetAmount`/`actualPayAmount` 由恒 0 真值化 |
+| 新增 | `GET /admin/finance/payments/offsettable-prepays` 可冲抵预付查询 | 新接口 |
+
+## ③ 接口详情
+
+### 3.1 新增：可冲抵预付查询
+
+```
+GET /admin/finance/payments/offsettable-prepays?supplierId={supplierId}
+```
+
+供付款申请页勾选「用哪笔预付冲抵」。返回该供应商下**已付讫（PAID）且可用余额 > 0** 的预付款，按付款日期升序。
+
+### 3.2 创建/编辑付款单（冲抵）
+
+在既有入参基础上加 `prepayOffsets`，提交即占用预付余额；不冲抵则该字段不传或传空数组（行为与旧版完全一致）。
+
+### 3.3 付款单详情
+
+详情返回本单的冲抵明细 `offsets[]` 及冲抵状态；`actualPayAmount`（实付）为出纳真正付现的金额。
+
+## ④ 入参
+
+### 4.1 `prepayOffsets[]`（创建/编辑付款单新增，可空）
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `prepayId` | Long(string) | 是 | 预付款申请单 ID（须为本供应商 PAID 且余额充足） |
+| `offsetAmount` | number | 是 | 该笔预付冲抵金额（>0，≤预付可用余额） |
+
+> 批量接口（按订单批量/按供应商合并）按供应商分组传：`prepayOffsets: [{ supplierId, offsets: [{ prepayId, offsetAmount }] }]`。
+> 编辑草稿为**整体置换语义**：传入的 `prepayOffsets` 全量替换旧占用（先回冲旧占用再按新入参重占）。
+
+### 4.2 可冲抵预付查询入参
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `supplierId` | Long(string) | 是 | 供应商 ID（查询其可冲抵预付） |
+
+## ⑤ 出参
+
+### 5.1 付款单详情 `GET /admin/finance/payments/{id}`（新增/真值化字段）
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `amount` | number | 应付金额（= Σ明细行，不随冲抵变化） |
+| `prepayOffsetAmount` | number | **冲抵金额合计**（= Σoffsets.offsetAmount；原恒 0，本期真值化） |
+| `actualPayAmount` | number | **实付金额 = amount − prepayOffsetAmount**（出纳按此现金付款；原恒等于 amount） |
+| `offsets` | array | **本单冲抵明细列表**（新增，无冲抵时为 `[]`） |
+
+`offsets[]` 元素：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `offsetId` | Long(string) | 冲抵明细 ID |
+| `prepayId` | Long(string) | 预付款申请单 ID |
+| `prepayNo` | string | 预付款单号（YF- 前缀） |
+| `offsetAmount` | number | 该笔冲抵金额 |
+| `status` | string | 冲抵状态：`OCCUPYING` 占用中 / `SETTLED` 已冲抵（付讫）/ `CANCELLED` 已取消（驳回/删改草稿回冲） |
+| `settleTime` | string(datetime) | 付讫冲抵时间（仅 SETTLED 有值，否则 null） |
+
+### 5.2 可冲抵预付查询 `offsettable-prepays` 出参（数组）
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `prepayId` | Long(string) | 预付款申请单 ID |
+| `prepayNo` | string | 预付款单号 |
+| `amount` | number | 预付本金 |
+| `availableAmount` | number | 可用余额（可被冲抵的上限） |
+| `payDate` | string(date) | 付款日期 |
+| `supplierId` | Long(string) | 供应商 ID |
+| `supplierName` | string | 供应商名称 |
+
+## ⑥ 枚举/数据字典
+
+**冲抵明细状态 `offsets[].status`**：
+
+| 值 | 含义 |
+|---|---|
+| `OCCUPYING` | 占用中（建单~付讫前） |
+| `SETTLED` | 已冲抵（付讫，终态） |
+| `CANCELLED` | 已取消（驳回/删草稿/改草稿回冲，留痕） |
+
+`paymentType` 仍走既有 `fin_payment_type` 字典标签（住宿/门票·游玩/餐食/车辆/导游/摄影/保险/其他支出/退款/其他应付），本次未新增。
+
+## ⑦ 错误码
+
+| 码 | 语义 |
+|---|---|
+| 598812 | 冲抵入参非法（金额≤0 / 同一预付单重复传） |
+| 598813 | 冲抵合计超应付金额（Σoffset > amount） |
+| 598814 | 预付单不可用（不存在 / 非已付讫 / 可用余额不足 / 金额非法） |
+| 598815 | 预付单冲抵单位与付款供应商不一致（跨供应商拦截） |
+| 598816 | 预付可冲抵余额并发不足（CAS 扣减失败，整批回滚） |
+| 598817 | 冲抵回冲账实不符（回冲 CAS 失败，fail-fast） |
+
+## ⑧ 示例
+
+### 8.1 典型：创建付款单并冲抵预付
+
+请求 `POST /admin/finance/payments`：
+
+```json
+{
+  "supplierId": "2096854417461403650",
+  "payeeAccountId": "2096854417490763777",
+  "amount": 800.00,
+  "paymentType": "住宿",
+  "reason": "9月羊和远方住宿结算",
+  "orderId": "2100482290093039617",
+  "prepayOffsets": [
+    { "prepayId": "2100473583917580290", "offsetAmount": 500.00 }
+  ]
+}
+```
+
+响应（`data.paymentId` 为新单 ID）。此时预付 `available_amount` 1000→500，`prepayOffsetAmount=500`、`actualPayAmount=300`，offset 行 `OCCUPYING`。
+
+详情出参（付讫后）：
+
+```json
+{
+  "code": 200,
+  "data": {
+    "id": "2100485199803359234",
+    "paymentNo": "FK-202609170057",
+    "amount": 800.00,
+    "prepayOffsetAmount": 500.00,
+    "actualPayAmount": 300.00,
+    "status": "PAID",
+    "offsets": [
+      {
+        "offsetId": "2102204...",
+        "prepayId": "2100473583917580290",
+        "prepayNo": "YF-202609170002",
+        "offsetAmount": 500.00,
+        "status": "SETTLED",
+        "settleTime": "2026-09-22 09:15:35"
+      }
+    ]
+  }
+}
+```
+
+### 8.2 边界：可冲抵预付查询
+
+请求 `GET /admin/finance/payments/offsettable-prepays?supplierId=2096854417461403650`：
+
+```json
+{
+  "code": 200,
+  "data": [
+    {
+      "prepayId": "2100473583917580290",
+      "prepayNo": "YF-202609170002",
+      "amount": 1000.00,
+      "availableAmount": 500.00,
+      "payDate": "2026-09-17",
+      "supplierId": "2096854417461403650",
+      "supplierName": "呼伦贝尔羊和远方牧业有限公司"
+    }
+  ]
+}
+```
+
+（该预付已被冲抵 500，故 `availableAmount` 由 1000 降为 500。）
+
+### 8.3 异常：冲抵超应付 / 跨供应商
+
+```json
+{ "code": 598813, "message": "冲抵合计超应付金额", "success": false }
+{ "code": 598815, "message": "预付单冲抵单位与付款供应商不一致", "success": false }
+{ "code": 598814, "message": "预付单不可用（不存在/非已付讫/余额不足）", "success": false }
+```
+
+## ⑨ 业务边界
+
+- **可冲抵资格**：预付单须 `status=PAID`（钱真出了）且 `availableAmount>0` 且其「冲抵单位」= 付款供应商；未付讫（APPROVED 未出钱）不可勾选。
+- **出纳只付差额**：付款金额锁死 = `actualPayAmount`，冲抵部分无现金流出、无资金流水。
+- **回冲时机**：仅 PENDING 草稿可编辑/删除；驳回（REJECTED）、删除、改草稿均回冲预付余额并置 offset 行 CANCELLED。**付讫（PAID）后无回冲**——已消耗预付不回退（供应商退回走退回形态，只退现金）。
+- **台账外手工单**：无台账锚点的手工付款单同样支持冲抵，行级/头表回写跳过（WARN），不影响付款主流程。
+
+## ⑩ 修改前后对比
+
+| 项 | 修改前 | 修改后 |
+|---|---|---|
+| 付款方式 | 只能全额现金 | 可勾选预付冲抵，出纳付差额 |
+| `prepayOffsetAmount` | 恒 0 | 真值化 = Σ冲抵 |
+| `actualPayAmount` | 恒等于 amount | = amount − 冲抵 |
+| 详情 `offsets` | 无 | 返回冲抵明细及状态机 |
+
+## ⑪ 影响评估 / 回滚
+
+- **向后兼容**：不冲抵（不传 `prepayOffsets` 或传空）时行为与旧版完全一致（offset=0、actualPay=amount），旧前端不感知。
+- **回滚**：代码回滚即恢复全额现金逻辑；已产生的冲抵数据（fin_prepay_offset）保留不影响。
+
+## ⑫ 注意事项
+
+- 列表行 `PaymentRowRespVO` 暂未加 `prepayOffsetAmount`，列表「实付」列如需区分冲抵单，另提需求（详情已全量返回）。
+- 冲抵不改变应付台账 `applied` 占用口径（建单占全额，付讫全额转 paid）。
+
+## ⑬ 关联 / 联系人
+
+- Issue：https://git.1814.love:8443/wx/HL/issues/8127
+- PR：#8134（地基）/ #8144（建单链路）/ #8145（付讫+回冲）/ #8146（收尾）
+- 负责人：yst
@@ -0,0 +1,443 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8150"
+title: "团期 staff 保存：scopeRoles 元素级非空校验，[null] 由静默 200 空操作改为 400 拒绝"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "not_required"
+frontend_status: "not_required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "backend_status=deployed：测试服 hl-order-service-v3 双实例（8086 / 8186）当前运行 sha=843de6401。本单修复提交 bfc10966e 不是该 sha 本身而是它的祖先，故用两条互相独立的判据：①git merge-base --is-ancestor bfc10966e 843de6401 → 退出码 0（是祖先），且 deploy-status.sh 登记 dev-v3 / 843de6401 / BEHIND=0/N；②jar mtime 2026-09-22 18:55:47，晚于 bfc10966e 的提交时刻 2026-09-22 15:24:50 +0800。两条之外还有第三条活体判据：本单契约在 18:5x 经网关实测四组请求取证（见第八节），其中三组的返回值在改动前不可能出现。gateway_status=not_required：本单零网关改动。PUT /v3/admin/group-batch/{productBatchId}/staff 是存量端点、路径未变，命中既有通配路由 Path=/v3/admin/**，未引入任何新路径段，也未改 hl-gateway 的路由或 Nacos 配置。frontend_status=not_required：本单收紧的是一个前端目前不会构造的取值。判据——对 mmg/hl-ui origin/v2.1 的调用方 grep，scopeRoles 一律由 roleMeta.memberRoles 这类字面量常量数组提供（GroupBatchStaffConfigModal.vue:153-154 写死 ['GUIDE','LEADER'] 与 ['PHOTOGRAPHER']），无任何一处会产出 null / 空串 / 纯空白元素；对 [\"\"] 与 [\"  \"] 本单只改 message 文案长度、不改 code。⚠️ 覆盖边界：这是「现有实现不会命中」，不是「将来也不会」——若前端改为由下拉或接口回填拼 scopeRoles，未选中的空值会直接命中本单的 400，请按第四节的契约处理。 | 2026-09-22 mmg 复核:grep 实证前端唯一构造点 ROLE_META.memberRoles 为字面量常量数组,零行为改动;orderV2GroupBatch.js JSDoc 补记新口径(拼接串禁全等、回填须 filter(Boolean)),见 hl-ui@6bf97829e"
+updated_at: "2026-09-22"
+base: "dev-v3"
+---
+
+# order-v3: 团期 staff 保存，scopeRoles 元素级非空校验（#8150）
+
+> **存放目录**: `changelogs-v2/2026-09/`
+>
+> **服务**: hl-order-service-v3 (端口 8086 / 8186)
+> **PR**: #8177
+> **Issue**: #8150
+> **日期**: 2026-09-22
+> **影响范围**: 团期 staff 配置保存接口 `PUT /v3/admin/group-batch/{productBatchId}/staff` 的 `scopeRoles` 字段入参校验
+
+> **📐 本份的覆盖边界**：本份只覆盖 `scopeRoles` 字段的**入参校验契约**。同端点的其他契约（`staffList` 语义、582115 / 582116 的判定规则、扇出行为）本单一律未改，见第七节与第十节列出的既有交接件。
+
+---
+
+## ⚠️ 关键变化
+
+### 变化 1：`scopeRoles: [null]` 从「HTTP 200 静默空操作」变成 `code: 400`
+
+这是本单的主体。改动前，`scopeRoles` 里混进一个 `null` 元素，接口会返回一个**和保存成功长得一模一样的 200**，而库里一行都没动。
+
+为什么旧行为是静默失败，四步连起来看：
+
+1. **JSR-380 规定 `@Pattern` 对 `null` 恒为 true**，所以 `[null]` 整条走完了参数校验，一个违约都不产生；
+2. 它非 null 非空（**数组本身**非空，`@Size(min = 1)` 也过），整位守卫（582116）的短路条件不成立，不抛；
+3. 但 `null` 这个元素一个配置位都 `contains` 不到 ⇒ 整位守卫内部的 `touched` 恒为 false，**也不抛**；
+4. `scopeRoles` 同时是删除窗口 —— 窗口 `{null}` 删不到任何行；插入集合同时为空 ⇒ **库里一行没动，接口返 200**。
+
+调用方拿到的不是错误，是一个空操作，**没有任何错误码提示它写错了**。这不是"写脏数据"，是静默失败：前端以为保存成功、页面刷新后配置没变，而后端日志里也没有异常。
+
+改动后返回：
+
+```json
+{"code":400,"message":"scopeRoles 的元素不能为空","data":null,"traceId":null,"success":false}
+```
+
+### 变化 2：`scopeRoles: [""]` / `["  "]` 的 `message` 从一条变成两条拼接
+
+这两个取值**改动前就已经是 400**（`@Pattern` 是容器元素约束，空串与纯空白匹配不上取值域），本单没有改变它们的 `code`。变的是 `message`：
+
+```json
+{"code":400,"message":"scopeRoles 取值不在员工角色取值域内; scopeRoles 的元素不能为空","data":null,"traceId":null,"success":false}
+```
+
+🔴 **两条约束是并列触发、不是后者替换前者**：`@NotBlank` 与 `@Pattern` 对空串同时失败，`GlobalExceptionHandler` 把多条 Bean Validation 违约的 message 用 `"; "` 拼接成一条字符串返回。
+
+🔴 **拼接顺序不保证，前端不得按顺序解析、也不得按精确相等匹配 `message`**。Bean Validation 规范不保证同一字段上多个约束的执行顺序，上面示例里 `@Pattern` 在前只是本轮实现的偶然结果，换一个 Hibernate Validator 版本就可能颠倒。需要判定失败原因时：
+
+- 判「是不是入参校验失败」→ 看 `code == 400`；
+- 判「是哪个字段」→ 用 `message.contains("scopeRoles")`，不要用 `==`；
+- 展示给用户 → 整串原样展示即可，它本身是可读的中文。
+
+---
+
+## 一、背景
+
+`scopeRoles` 是 #8006 引入的**部分覆盖开关**：不传 = 整期全量覆盖（历史行为），传了则只在这些角色内覆盖、范围外的既有行一行不动。它同时是**删除窗口** —— 漏声明的同位行既不会被删也不会被重建。
+
+正因为它兼任删除窗口，一个取不到任何配置位的 `scopeRoles` 会让整次保存退化成空操作。而字段原本只加了元素级 `@Pattern`，JSR-380 明文规定 `@Pattern` 对 `null` 恒为 true，于是 `[null]` 是唯一一个能穿过校验层、又在业务层什么都不做、还返 200 的取值。
+
+本单补上元素级 `@NotBlank`，把这个洞封掉。选 `@NotBlank` 而不是 `@NotNull` 的理由在第六.6 节的对比表里 —— 不是为了可达性（`@NotNull` 同样能救回 `[null]`），是为了让空串与纯空白也拿到一条**点名"为空"**的文案，而不是只被告知"取值不在取值域内"。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|---|---|---|---|---|
+| 1 | 保存团期 staff 配置（含扇出） | PUT | `/v3/admin/group-batch/{productBatchId}/staff` | 修改接口 | `scopeRoles` 增加元素级 `@NotBlank`（入参校验收紧）；`code`、响应结构、业务语义均未变 |
+
+**未新增、未删除、未改名任何端点。**
+
+---
+
+## 三、接口详情
+
+### 1. 保存团期 staff 配置（含扇出） `PUT /v3/admin/group-batch/{productBatchId}/staff`
+
+**VO**: `BatchStaffConfigReqVO` → `Result<BatchStaffConfigRespVO>`
+
+**权限**: `GroupBatchPermissionGuard.PERMISSION_MANAGE`（`hl-gateway` 侧命中既有通配路由 `Path=/v3/admin/**`）
+
+#### 使用场景
+
+团期详情页「配导游 / 配摄影」弹窗保存。传入列表即为**覆盖范围内**的最终状态，保存成功后异步扇出到团内所有活跃订单的 `order_staff_assignment`（`source=GROUP_BATCH`）。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| `productBatchId` | path | Long | 是 | — | **产品侧排期 ID**（`group_tour_batch.batch_id`），不是运营团期主键 `order_group_batch.group_batch_id`。两者 1:1 但值不同，传错不会报错、只会走不到团期 |
+| `scopeRoles` | body | `List<String>` | 否 | 数组 `@Size(min = 1)`；🆕 元素 `@NotBlank` + 元素 `@Pattern` | 本次保存覆盖的角色范围。**不传 = 整期全量覆盖**（历史行为）；传了则只在这些角色内覆盖。取值域见第六.5 节。**数组不能是空数组**（清空语义只由 `staffList` 表达）；🆕 **元素不能是 `null` / 空串 / 纯空白**——本单唯一的行为变化就在这里 |
+| `staffList` | body | `List<Item>` | **是** | `@NotNull` + `@Valid` | 覆盖范围内的最终状态。**显式传 `[]` 即清空该范围**。缺字段或字段名拼错一律 400（审计 F-03，Refs #6950 / #7377）。本单未改动 |
+| `staffList[].staffId` | body | Long | 是 | `@NotNull` | 用户域员工 ID。本单未改动 |
+| `staffList[].staffRole` | body | String | 是 | `@NotBlank` + `@Pattern` | 员工角色，取值域见第六.5 节。本单未改动 |
+| `staffList[].sortOrder` | body | Integer | 否 | — | 展示排序，默认 0。本单未改动 |
+| `staffList[].remark` | body | String | 否 | `@Size(max = 500)` | 备注，≤500 字。本单未改动 |
+
+#### 出参（本单未改动，列出供对照）
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `productBatchId` | String（Long 序列化为字符串） | 回显路径参数，恒非 null |
+| `groupBatchId` | String（Long 序列化为字符串） | 运营团期 ID，由 `productBatchId` 反查。**本端点的 200 响应里恒非 null**（入口第一道守卫就是成团校验） |
+| `staffList` | Array | 保存后的团期 staff 配置快照 |
+| `staffList[].id` | Long | 记录 ID（`batch_staff_id`） |
+| `staffList[].staffId` | Long | 用户域员工 ID |
+| `staffList[].staffRole` | String | 员工角色 code |
+| `staffList[].staffRoleName` | String | 角色中文名；`staffRole` 为 null 时为 null，取值不在枚举内时回落原 code |
+| `staffList[].staffName` | String | 员工姓名（快照） |
+| `staffList[].staffPhone` | String | 手机号，脱敏前 3 后 4 |
+| `staffList[].avatarUrl` | String | 头像 URL（快照） |
+| `staffList[].sortOrder` | Integer | 展示排序 |
+| `staffList[].remark` | String | 备注 |
+| `staffList[].reporterRank` | String | 报账人等级 `PRIMARY` / `SECONDARY` / `NONE`，空值归一为 `NONE`，恒非 null |
+| `staffList[].reporterRankName` | String | 报账人等级中文名，与 `reporterRank` 同生同灭 |
+| `affectedOrderCount` | int | 扇出影响的订单数（已触发异步写入的活跃订单数） |
+
+#### 请求示例（正确用法，本单未改变它的行为）
+
+```json
+PUT /v3/admin/group-batch/80001/staff
+
+{
+  "scopeRoles": ["GUIDE", "LEADER"],
+  "staffList": [
+    {"staffId": 40001, "staffRole": "LEADER", "sortOrder": 0, "remark": "首席领队"},
+    {"staffId": 40002, "staffRole": "GUIDE",  "sortOrder": 1}
+  ]
+}
+```
+
+#### 响应示例
+
+保存成功（`code` 为 `200`，本单未改变响应结构）：
+
+```json
+{
+  "code": 200,
+  "message": "操作成功",
+  "data": {
+    "productBatchId": "80001",
+    "groupBatchId": "90211",
+    "staffList": [
+      {
+        "id": 770001,
+        "staffId": 40001,
+        "staffRole": "LEADER",
+        "staffRoleName": "领队",
+        "staffName": "刘领队",
+        "staffPhone": "138****6677",
+        "avatarUrl": null,
+        "sortOrder": 0,
+        "remark": "首席领队",
+        "reporterRank": "NONE",
+        "reporterRankName": "非报账人"
+      }
+    ],
+    "affectedOrderCount": 3
+  },
+  "traceId": null,
+  "success": true
+}
+```
+
+🔎 本示例按 `BatchStaffConfigRespVO` 的字段逐个列出，用于说明结构；本单未改动响应结构中的任何一个字段。成功路径的活体读数不在本单的取证范围内（本单取证用的是不存在的团期，见第八节），需要成功响应的真实样本请见第十节 #8006 的交接件。
+
+#### 空数据 / 降级响应
+
+本单不涉及。`staffList: []` 的「清空该范围」语义未变，该情形下 `data.staffList` 返回空数组（不是 `null`），`affectedOrderCount` 照常返回扇出订单数。
+
+#### 错误响应
+
+🆕 `scopeRoles` 元素为 `null`（**本单新增的拒绝**）：
+
+```json
+{"code":400,"message":"scopeRoles 的元素不能为空","data":null,"traceId":null,"success":false}
+```
+
+`scopeRoles` 元素为空串 / 纯空白（改前已是 400，本单只让 `message` 多带一条）：
+
+```json
+{"code":400,"message":"scopeRoles 取值不在员工角色取值域内; scopeRoles 的元素不能为空","data":null,"traceId":null,"success":false}
+```
+
+全部错误码：
+
+| code | 触发条件 | 本单是否改动 |
+|---|---|---|
+| `400` | `scopeRoles` 元素为 `null` | 🆕 **本单新增**（改前是 200 静默空操作） |
+| `400` | `scopeRoles` 元素为空串 / 纯空白 | 改前已是 400，本单只让 `message` 多带一条 |
+| `400` | `scopeRoles` 传了 `[]`（空数组） | 否（`@Size(min = 1)`） |
+| `400` | `scopeRoles` 元素不在取值域内 | 否 |
+| `400` | 缺 `staffList` 字段 | 否 |
+| `582115` | `staffList` 里出现 `scopeRoles` 范围外的角色 | 否，且**零写入** |
+| `582116` | `scopeRoles` 只声明了半个配置位（如只传 `GUIDE` 不传 `LEADER`） | 否，且**零写入** |
+| `589552` / `589553` | 团期未建团 / 未成团或已流团 | 否 |
+
+🔴 **HTTP 状态行恒为 200，`body.code` 才是真相**。本服务的业务失败与入参校验一律返 HTTP 200（`GlobalExceptionHandler` 带 `@ResponseStatus(HttpStatus.OK)`），成功码是 `200` 不是 `0`。判成败请读 `body.code`，不要读 HTTP 状态码。
+
+#### 业务边界
+
+- **本单唯一的行为变化在 `scopeRoles` 的元素上**：`[null]` 由「HTTP 200 + 静默空操作」改为 `code: 400`。`scopeRoles` 不传、传合法值、以及 `staffList` 侧的一切语义都与改前逐字相同。
+- **`scopeRoles` 不传 = 整期全量覆盖**，传了 = 只在这些角色内覆盖；`[]` 一直被拒（`@Size(min = 1)`），清空语义只由 `staffList: []` 表达。这三条改前改后一致。
+- **`[null]` 改前不报错，但它做的事情是「什么都没做」**：`scopeRoles` 含 `null` 时下游范围计算得到空范围，接口返 200、`affectedOrderCount` 为 0、库里零写入。调用方若据 200 判定「已保存」，实际保存从未发生 —— 这正是本单要关掉的静默失败。
+- **`[""]` / `["  "]` 改前已是 400**，本单只让 `message` 多带一条。**不要对这两个值的 `message` 写全等比较**：它是 `@Pattern` 与 `@NotBlank` 两条 violation 由 `GlobalExceptionHandler` 以 `"; "` 拼接而成，且 **拼接顺序不属于契约**（Bean Validation 不保证多个约束的执行顺序）。要判就判 `code == 400`，或判 `message` **包含**你关心的那个子串。
+- **校验发生在 Spring `@Valid` 绑定层，在进 Service 之前**：因此 `productBatchId` 是否真实存在不影响这三种 400 的出现。反过来，拿到 `589552` / `589553` 说明请求已经穿过绑定层、是团期状态问题，不是参数格式问题。
+- **HTTP 状态行恒为 200**，成功码是 `200` 不是 `0`，判成败一律读 `body.code`。
+
+---
+
+## 四、契约约束与正确调用方式
+
+### `scopeRoles` 取值对照表
+
+| payload 片段 | 结果 | 说明 |
+|---|---|---|
+| 字段整个不传 | ✅ 整期全量覆盖 | 历史行为，未变 |
+| `"scopeRoles": ["GUIDE","LEADER"]` | ✅ 只覆盖导游位 | 导游位并收这两个角色，必须同时传 |
+| `"scopeRoles": ["PHOTOGRAPHER"]` | ✅ 只覆盖摄影位 | |
+| `"scopeRoles": ["GUIDE"]` | ❌ `582116` | 只声明半个配置位，零写入 |
+| `"scopeRoles": []` | ❌ `400` | 空数组被拒；清空语义只由 `staffList: []` 表达 |
+| `"scopeRoles": [null]` | ❌ `400` 🆕 | **本单收紧**。改前返 200 且库里一行没动 |
+| `"scopeRoles": ["", "GUIDE"]` | ❌ `400` | 改前已是 400，本单只让 `message` 多一条 |
+| `"scopeRoles": ["  "]` | ❌ `400` | 同上 |
+| `"scopeRoles": null`（字段值为 null） | ✅ 等同不传 | 整期全量覆盖 |
+
+### 前端拼 `scopeRoles` 时的两条实践
+
+1. **过滤在前、校验在后**：如果 `scopeRoles` 由下拉选中项或接口回填拼出，先 `filter(Boolean)` 掉未选中产生的空值再发；空数组要整个字段不传，而不是传 `[]`。
+2. **不要按 `message` 精确相等判分支**：多条约束并列失败时 `message` 是 `"; "` 拼接串且顺序不保证。要区分失败原因用 `code`，要展示就整串展示。
+
+---
+
+## 五、数据库行为
+
+**本单零数据库改动**：不加表、不加列、不加索引、无 Flyway 脚本。
+
+唯一与库相关的行为差异是「改前 `[null]` 那一次请求对库零写入且返 200，改后它根本进不到 Service」—— 两种情况下库里都是零写入，差别只在调用方能不能知道。
+
+---
+
+## 六、边界行为
+
+| 场景 | 行为 |
+|---|---|
+| `scopeRoles` 数组里混合合法值与空值（如 `["GUIDE", null]`） | 整条请求 400，**零写入**；Bean Validation 在进 Service 前就拦下，不存在"合法的那一半生效了" |
+| 同一次请求同时违反多条约束 | `message` 为各条以 `"; "` 拼接，顺序不保证；`code` 恒为 `400` |
+| `staffList` 里的 `staffRole` 为 null / 空串 | 由 `Item.staffRole` 自己的 `@NotBlank` + `@Pattern` 拦，本单未改 |
+| 校验失败时的扇出 | 不发生。校验在 `@Valid` 绑定层，早于 Service，更早于异步扇出 |
+
+---
+
+## 六.5、枚举 / 数据字典
+
+### `scopeRoles` 元素 与 `staffList[].staffRole` 的取值域（两者同一套）
+
+判定依据是 `BatchStaffConfigReqVO.STAFF_ROLE_PATTERN` 常量，**共 8 个取值**：
+
+| code | 中文名 |
+|---|---|
+| `LEADER` | 领队 |
+| `GUIDE` | 导游 |
+| `DRIVER` | 司机 |
+| `PHOTOGRAPHER` | 摄影 |
+| `OTHER` | 其他 |
+| `GUIDE_ASSISTANT` | 导游助理 |
+| `STUDY_TEACHER` | 研学老师 |
+| `LIFE_TEACHER` | 生活老师 |
+
+后 3 个由 #7079（`e61fc9ab6`）引入，**不是本单新加的**，本单一个取值都没动。
+
+⚠️ **Swagger 上 `staffList[].staffRole` 的字段说明只列了前 5 个**（`LEADER=领队 / GUIDE=导游 / DRIVER=司机 / PHOTOGRAPHER=摄影 / OTHER=其他`），与 `@Pattern` 实际放行的 8 个不一致。**以本表为准** —— 本表取自 `STAFF_ROLE_PATTERN` 常量本身，那是校验实际执行的依据；另可交叉印证：响应侧 `staffList[].staffRoleName` 的字段说明已写全 8 个中文名（"领队/司机/导游/摄影/其他/导游助理/研学老师/生活老师"）。照请求侧 Swagger 文案写下拉会缺 3 项。
+
+### 配置位与角色的对应
+
+| 配置位 | 并收的角色 | 说明 |
+|---|---|---|
+| 导游位 | `GUIDE` + `LEADER` | 触及就必须两个都传，否则 `582116` |
+| 摄影位 | `PHOTOGRAPHER` | |
+
+配置位的成员读数据字典（#7079）：字典加一个角色后，原本完整的范围当天就会变成不完整并被拒，错误码文案里的「还缺少 X」即为要补进 `scopeRoles` 的角色。
+
+---
+
+## 六.6、修改前后对比
+
+### 字段级
+
+| 字段 | 改前约束 | 改后约束 |
+|---|---|---|
+| `scopeRoles` | `@Size(min = 1)` + 元素级 `@Pattern` | `@Size(min = 1)` + 元素级 `@NotBlank` + 元素级 `@Pattern` |
+
+其余字段一字未改。
+
+### 行为级
+
+| 请求 | 改前 | 改后（现网） | 依据等级 |
+|---|---|---|---|
+| `"scopeRoles": [null]` | HTTP 200 / `code: 200`，库里零写入，**无任何错误提示** | `code: 400`，`message` = `scopeRoles 的元素不能为空` | 改前：**推导**（见下）；改后：**网关活体实测** |
+| `"scopeRoles": [""]` | `code: 400`，`message` 一条（`scopeRoles 取值不在员工角色取值域内`） | `code: 400`，`message` 两条以 `"; "` 拼接 | 改前：**单测层变异实测**；改后：**网关活体实测** |
+| `"scopeRoles": ["  "]` | 同上 | 同上（返回体与 `[""]` 逐字相同） | 同上 |
+| `"scopeRoles": ["GUIDE","LEADER"]` | 正常进 Service | 不变 | 网关活体实测（作阴性对照） |
+| `"scopeRoles": []` | `code: 400` | 不变 | 源码（`@Size(min = 1)`） |
+| 字段不传 | 整期全量覆盖 | 不变 | 源码 |
+
+🔎 **「改前」一列的依据分级，逐条说清楚**（改前的 jar 已不在测试服上，无法回放）：
+
+- `[null]` 改前返 200：**两段拼起来的推导**。①校验层：`BatchStaffConfigReqVOValidationTest` 的变异实测——移除元素级 `@NotBlank` 后，`Validator#validate` 对 `[null]` 返回 **0 条违约**（`Expected size: 1 but was: 0`），证明它确实能整条穿过校验层；②业务层：源码路径推导（整位守卫 `touched` 恒 false + 删除窗口 `{null}` 命中 0 行 + 插入集合为空），得出"零写入且返 200"。**这一段是源码推导，没有改前的网关读数**。
+- `[""]` / `["  "]` 改前是一条 message：**单测层变异实测**——同一轮变异里，`[""]` 返回 **1 条违约、来自 `@Pattern`**。这是 Validator 直调的读数，不是网关读数。
+
+⚠️ 这里订正一条**本仓代码注释里写错、并已同步订正**的结论：早前的注释写「`@NotBlank` 对 `""` / `"  "` 带来的是错误文案**从** X **变成** Y」，实测证明是**两条并列、拼接**，不是替换。注释与相关测试 javadoc 已一并订正。
+
+---
+
+## 六.7、影响评估
+
+对 `mmg/hl-ui` `origin/v2.1` 的调用方核查结论：
+
+- `scopeRoles` 一律由**字面量常量数组**提供 —— `GroupBatchStaffConfigModal.vue:153-154` 写死 `['GUIDE','LEADER']`（导游位）与 `['PHOTOGRAPHER']`（摄影位），无任何一处会产出 `null` / 空串 / 纯空白元素；
+- 因此现有实现**不会命中本单新增的 400**，行为零改动，无需前端配合改造。
+
+⚠️ 这个结论的有效期限于"现有实现"。若后续改为由下拉选中项、接口回填或用户输入拼 `scopeRoles`，未选中产生的空值会直接命中本单的 400 —— 按第四节的两条实践处理即可。
+
+---
+
+## 七、不影响范围
+
+本单**未改动**以下任何一项，它们的契约保持原样：
+
+- `staffList` 的语义（"覆盖范围内的最终状态"、显式传 `[]` 即清空该范围）
+- `582115`（范围外角色，零写入）与 `582116`（半位声明，零写入）的**判定规则与触发条件**
+- 角色取值域本身（8 个取值一个没动）
+- 配置位的划分与成员（导游位 = `GUIDE` + `LEADER`，摄影位 = `PHOTOGRAPHER`）
+- 响应结构 `BatchStaffConfigRespVO` 的任何字段
+- 扇出行为（异步写 `order_staff_assignment`，`source=GROUP_BATCH`，ORDER 专属行不受影响）
+- 成团守卫（`589552` / `589553`）
+- 同端点以外的任何接口
+
+---
+
+## 八、测试环境已验证
+
+### 部署状态（三条独立判据）
+
+| 判据 | 读数 |
+|---|---|
+| ① 祖先关系 + 登记 | `git merge-base --is-ancestor bfc10966e 843de6401` → 退出码 0；`deploy-status.sh` 登记 `hl-order-service-v3 / dev-v3 / 843de6401 / BEHIND=0(N) / ok` |
+| ② jar 时间 | jar mtime `2026-09-22 18:55:47`，晚于 `bfc10966e` 的提交时刻 `2026-09-22 15:24:50 +0800` |
+| ③ 活体行为 | 下面四组请求中，①②③ 的返回值在改动前的代码上不可能出现 |
+
+部署前后对照（`deploy-status.sh`）：
+
+```
+前：hl-order-service-v3  dev-v3  776c0023d  BEHIND=10(Y)  2026-09-22 17:19:45  ok
+后：hl-order-service-v3  dev-v3  843de6401  BEHIND=0(N)   2026-09-22 18:55:47  ok
+```
+
+### 网关实测四组（2026-09-22 18:5x，`https://api.test.1814.love:9443`）
+
+端点一律 `PUT /v3/admin/group-batch/999999999999999999/staff`。
+
+**① `scopeRoles: [null]` —— 本单的主体**
+
+```json
+请求: {"scopeRoles":[null],"staffList":[]}
+响应: {"code":400,"message":"scopeRoles 的元素不能为空","data":null,"traceId":null,"success":false}
+```
+
+**② `scopeRoles: [""]`**
+
+```json
+请求: {"scopeRoles":[""],"staffList":[]}
+响应: {"code":400,"message":"scopeRoles 取值不在员工角色取值域内; scopeRoles 的元素不能为空","data":null,"traceId":null,"success":false}
+```
+
+**③ `scopeRoles: ["  "]`**
+
+```json
+请求: {"scopeRoles":["  "],"staffList":[]}
+响应: {"code":400,"message":"scopeRoles 取值不在员工角色取值域内; scopeRoles 的元素不能为空","data":null,"traceId":null,"success":false}
+```
+
+与 ② 的返回体**逐字相同**。
+
+**④ `scopeRoles: ["GUIDE","LEADER"]` —— 阴性对照**
+
+```json
+请求: {"scopeRoles":["GUIDE","LEADER"],"staffList":[]}
+响应: {"code":589553,"message":"团期尚未创建（该班期还没有任何订单），请先建团并完成成团后再操作","data":null,"traceId":null,"success":false}
+```
+
+🔎 **第 ④ 组不是凑数的**：没有它，前三组的 400 也可能只是"这个端点对什么都返 400"。④ 用同一个不存在的 `productBatchId`、只换 `scopeRoles` 的取值，就穿过了绑定层抵达 Service 并拿到业务错误码 —— 证明前三组的 400 确实来自 `scopeRoles` 的元素级校验，而不是端点无差别拒绝。
+
+🔎 **取证为什么用不存在的团期**：本单的校验发生在 Spring `@Valid` 绑定层、**在进 Service 之前**，所以 `productBatchId` 用一个不存在的值就够——前三组根本走不到 Service，不读不写任何真实团期数据。整轮实测**零数据污染**。
+
+### 单测
+
+`BatchStaffConfigReqVOValidationTest`（Validator 直调）与 `GroupBatchStaffAdminControllerTest`（`@WebMvcTest`）各有承载用例。后者除了断 `$.code == 400` 与 message 内容，还断了 `verifyNoInteractions(groupBatchStaffConfigService)`，证明请求在**进 Service 之前**就被拦下 —— 没有这条断言，"`@Valid` 这道关生没生效"与"Service 内部某处恰好也返 400"在其余断言下完全同形。
+
+---
+
+## 九、已知缺口（不在本单范围）
+
+1. **Swagger 请求侧 `staffList[].staffRole` 的取值域文案落后 3 个角色**（只列前 5 个）。这是文案缺口不是实现缺口，校验按 8 个取值执行。以第六.5 节的表为准。
+
+---
+
+## 十、相关文档
+
+| 文档 | 关系 |
+|---|---|
+| `21_8006_团期staff保存支持按角色范围覆盖-修改接口-管理后台.md` / `22_8006_团期人员保存支持按角色范围覆盖-修改接口-管理后台.md` | `scopeRoles` 字段的**完整契约**出处（部分覆盖语义、删除窗口、582115） |
+| `22_8122_团期人员保存声明角色范围时必须整位覆盖-修改接口-管理后台.md` | `582116`（半位声明拒绝）的契约出处 |
+| `12_7530_团期staff去重与报账人扇出限定本团-修改接口-管理后台.md` | 扇出行为 |
+| `12_7535_团期接口返回值整改非破坏批-修改接口-管理后台.md` | 响应字段（`reporterRank` 等）的出处 |
+
+---
+
+## 关联 / 联系人
+
+- **Issue**: #8150
+- **PR**: #8177（修复本体）、#8197（配套测试与注释订正）
+- **后端**: wx
+- **前端**: mmg（本单 `frontend_status: not_required`，判定依据见 frontmatter 的 `status_note` 与第六.7 节）
@@ -0,0 +1,559 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8154"
+title: "团期管理员可打开团期子订单详情（只读），金额/流水面 13 个端点对该角色收回，写面全域拒绝"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修复"
+backend_status: "deployed"
+gateway_status: "not_required"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "9c5dd0cb59f186a82552580039b9f187b530ba90"
+target_release: "v2.1"
+verified_at: "2026-09-22"
+status_note: "本条只改权限判定，不改任何请求/响应字段结构。对 GROUP_BATCH_MANAGER 以外的任何角色（超管/定制师/运营/客服/财务/车务/房务）零行为变化。前端需要做的是：给团期管理员这一角色隐藏/兜底金额面与写操作入口，并处理 581008。gateway_status: not_required —— 零网关改动，涉及端点全部落在既有 /v3/admin/** 通配路由内。 前端已交付(9c5dd0cb):金额面三 Tab 与订单域/团期侧写入口按角色全量隐藏,主详情 7 金额字段照显(已拍板);MealTab 部分改动在 742b2d5e。"
+updated_at: "2026-09-22"
+base: "dev-v3"
+---
+
+# order-v3 + user-service: 团期管理员只读查看团期子订单，金额面端点收回，写面全域拒绝
+
+> **存放目录**: 二期(v3) → `changelogs-v2/2026-09/`
+>
+> **服务**: hl-order-service-v3（权限守卫）、hl-user-service（角色菜单绑定）
+> **PR**: 见文末「关联 / 联系人」
+> **Issue**: #8154
+> **日期**: 2026-09-22
+> **影响范围**: 管理后台，**仅** `GROUP_BATCH_MANAGER`（团期管理员）角色登录时的订单详情页与团期详情页子订单操作
+
+---
+
+## ⚠️ 关键变化（非必须,本版与上版行为不同 / 纠错 / 撤销时必写）
+
+**本条只改「谁能调」，不改「调通了返回什么」。所有请求/响应字段结构逐字节不变。**
+
+对 `GROUP_BATCH_MANAGER` 三件事同时生效：
+
+1. **放开**：10 个需求核对类只读端点，从 581008 变为正常返回——**但只对团期子订单**（`groupBatchId` 非空）。散客单仍 581008。
+2. **收回**：13 个金额 / 成本 / 流水读端点，对该角色返回 581008（本批之前它们与第 1 组是同一道守卫，一放就全放，所以这是**同批收回**，不是先放后收）。
+3. **拒绝**：订单详情页与团期详情页能触发的**全部写端点**，对该角色返回 581008。
+
+🔴 **「端点收回」不等于「金额不可见」**——见「六、边界行为」的已知缺口一节，主详情响应体里仍含 7 个金额字段。前端按该节处理。
+
+---
+
+## 一、背景（选填）
+
+团期管理员要核对团期下各子订单报了什么需求，此前点「进入子订单」一律 581008，页面打不开。放开读面时读面里混着两类端点：核对需求要看的，和暴露供应商成本与资金流水的。工单诉求只到前者，后者一旦被看到不可逆，故同一批里把后者单独拆出去收回；同时该角色的「只能看不能修改」必须在写面落地，否则放开读权后它能改同行人、改行程、发起退款、开合同、改保险、改大交通，甚至修改 / 取消 / 终止订单主单。
+
+| 维度 | 本批之前 | 本批之后 |
+|------|----------|----------|
+| 打开团期子订单详情 | 581008 | 正常返回（仅团期子订单） |
+| 打开散客单详情 | 581008 | 581008（不变） |
+| 财务 / 发票 / 退款 / 流水等 13 个端点 | 581008 | 581008（不变，但改由独立守卫判定） |
+| 订单域写端点 | 该角色调不到（读面进不去） | 明确 581008 |
+| 前端路由 `/order-v2/detail/:id` | 该角色未绑菜单，点「进入」命中兜底路由 404 | 已绑菜单，路由可注册 |
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 需求核对类只读端点（10 个） | GET | `/v3/admin/order/{id}` 等 | 权限放开 | 仅 GROUP_BATCH_MANAGER + 仅团期子订单 |
+| 2 | 金额 / 成本 / 流水读端点（13 个） | GET | `/v3/admin/order/{id}/finance` 等 | 权限收回 | 对 GROUP_BATCH_MANAGER 返 581008 |
+| 3 | 订单域写端点（14 个控制器 + 2 个团期动作） | POST / PUT / DELETE | `/v3/admin/order/**` 等 | 权限拒绝 | 对 GROUP_BATCH_MANAGER 返 581008 |
+
+---
+
+## 三、接口详情
+
+### 1. 需求核对类只读端点（10 个，权限放开） `GET /v3/admin/order/{id}`
+
+**VO**: `OrderDetailReqVO → OrderDetailRespVO`
+
+#### 使用场景
+
+团期管理员在「团期详情 → 子订单列表」点「进入」，打开子订单详情页核对该户报了什么需求。本组端点即该页面各 Tab 的取数入口。
+
+**本组完整清单**（路径逐一列全，前端按此判断哪些请求现在能发）：
+
+| # | 方法 | 路径 | 页面位置 |
+|---|------|------|----------|
+| 1 | GET | `/v3/admin/order/{id}` | 订单详情主体（9 Tab 聚合入口） |
+| 2 | GET | `/v3/admin/order/{id}/itinerary` | 行程安排 Tab |
+| 3 | GET | `/v3/admin/order/{id}/confirm-checklist` | 确认清单 |
+| 4 | GET | `/v3/admin/order/{id}/service-standard` | 服务标准 Tab |
+| 5 | GET | `/v3/admin/order/{id}/status-log` | 状态记录时间线 Tab |
+| 6 | GET | `/v3/admin/order/{id}/print-itinerary` | 打印行程单（司机 Driver Copy） |
+| 7 | GET | `/v3/admin/order/{id}/push-records` | 推送记录 Tab |
+| 8 | GET | `/v3/admin/order/{id}/contract-insurance` | 合同保险 Tab |
+| 9 | GET | `/v3/admin/order/{orderId}/itinerary-document` | 电子行程单（对客视角） |
+| 10 | GET | `/v3/admin/order/meal-info/list` | 用餐信息列表 |
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| id / orderId | Path | Long | ✅ | 前 9 个端点 | 子订单 ID；**必须是团期子订单**，散客单 581008 |
+| orderId | Query | Long | ❌ | 第 10 个端点（`meal-info/list`） | 传了才逐单判权；不传按查询条件本身的口径取数 |
+| documentType | Query | String | ✅ | 第 9 个端点 | `CUSTOMER` / `CUSTOMER_PRINT` / `CUSTOMER_QUOTE` |
+| Authorization | Header | String | ✅ | Bearer token | 角色 key 由网关透传，前端不传角色 |
+
+**请求参数与请求体结构本批零改动**，上表只列与判权相关的部分。
+
+#### 出参 `Result<OrderDetailRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data | Object | **响应结构本批零改动**，与该角色之外的角色拿到的完全相同 |
+| data.main | Object | 订单主信息；⚠️ 含 7 个金额字段，见「六、边界行为」已知缺口 |
+| data.tags | Array | 订单标签 |
+| data.overview | Object | 概览（含 hotelRemark / vehicleRemark 等） |
+
+其余 9 个端点的响应结构同样零改动，此处不重复列出——本条 changelog 不引入任何新字段。
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/2101506167043985410 HTTP/1.1
+Host: <网关域名>
+Authorization: Bearer <团期管理员的 token>
+```
+
+无请求体。
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "main": {
+      "orderId": "2101506167043985410",
+      "orderNo": "GT-26-0081",
+      "groupBatchId": "2101506167098511362",
+      "orderStatus": "CONFIRMED"
+    },
+    "tags": [],
+    "overview": {}
+  },
+  "success": true
+}
+```
+
+（示例省略了与本条无关的字段，实际响应结构与本批之前逐字段相同。）
+
+#### 空数据 / 降级响应
+
+部分 Tab 在无数据时 `data` 为 `null`（如服务标准快照缺失、无退款），这是**既有行为，本批不改**：
+
+```json
+{ "code": 200, "message": "成功", "data": null, "success": true }
+```
+
+#### 错误响应
+
+散客单（`groupBatchId` 为 NULL）对该角色仍然拒绝：
+
+```json
+{
+  "code": 581008,
+  "message": "无权查看此订单",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- **放行条件是两个而不是一个**：角色为 `GROUP_BATCH_MANAGER` **且** `order.groupBatchId != null`。缺任一条 → 581008。
+- 🔴 **放行范围是「全站团期子订单」，不是「他负责的那个团」**：按管理员归属隔离要走 `order_group_batch.batch_manager_id`，该列当前全站为 NULL、显式不启用，做不到隔离。前端不要据此假设「他只能看到自己的团」。
+- 判权发生在**后端**，与前端菜单权限码无关：即使前端藏了入口，直接拼 URL 也按上面两条判。
+- 房务管理员 / 房务组长在本组端点上仍是 581045（`房务角色无权查看订单详情，房务仅可配房`），与本批无关。
+- 其余角色（超管 / 定制师 / 运营 / 客服 / 财务 / 车务）在本组端点上**零行为变化**。
+
+---
+
+### 2. 金额 / 成本 / 流水读端点（13 个，权限收回） `GET /v3/admin/order/{id}/finance`
+
+**VO**: `OrderFinanceReqVO → FinanceVO`
+
+#### 使用场景
+
+订单详情页的财务 / 发票 / 退款等 Tab，以及预付、优惠加价、收款流水、手工收款等金额面取数。**团期管理员调用本组任一端点一律 581008**——前端应对该角色隐藏这些 Tab 与按钮，而不是让它点开后吃一个错误弹窗。
+
+**本组完整清单（13 个 GET 端点，逐一列全）**：
+
+| # | 路径 | 内容 |
+|---|------|------|
+| 1 | `/v3/admin/order/{id}/finance` | 财务 Tab |
+| 2 | `/v3/admin/order/{id}/invoices` | 发票 Tab |
+| 3 | `/v3/admin/order/{id}/refund` | 退款明细 Tab |
+| 4 | `/v3/admin/order/{id}/cancel-preview` | 取消订单预览（金额 + 政策） |
+| 5 | `/v3/admin/order/{id}/sign-voucher` | 签单凭证（对供应商核成本） |
+| 6 | `/v3/admin/order/{orderId}/advances` | 预付列表 |
+| 7 | `/v3/admin/order/{orderId}/advance/payee-candidates` | 预付收款方候选 |
+| 8 | `/v3/admin/order/{orderId}/discount-surcharge/list` | 优惠 / 加价明细 |
+| 9 | `/v3/admin/order/{orderId}/payment/list` | 收款流水 |
+| 10 | `/v3/admin/order/{orderId}/payment/manual-receipt` | 手工收款记录 |
+| 11 | `/v3/admin/order/{orderId}/payment/manual-receipt/options` | 手工收款选项 |
+| 12 | `/v3/admin/order/invoice/{id}` | 发票详情 |
+| 13 | `/v3/admin/order/invoice/{id}/push-logs` | 发票推送日志 |
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| id / orderId | Path | Long | ✅ | - | 订单 ID（第 12、13 项为发票 ID） |
+| Authorization | Header | String | ✅ | Bearer token | 角色 key 由网关透传 |
+
+入参结构本批零改动。
+
+#### 出参 `Result<FinanceVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data | Object | **结构零改动**；对 GROUP_BATCH_MANAGER 永远拿不到（先抛 581008） |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/2101506167043985410/finance HTTP/1.1
+Host: <网关域名>
+Authorization: Bearer <团期管理员的 token>
+```
+
+无请求体。
+
+#### 响应示例
+
+对**非**团期管理员角色（超管 / 定制师 / 客服 / 财务 / 车务），响应与本批之前完全一致：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": { "payments": [] },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+无数据时 `data` 为 `null` 或空数组，属既有行为，本批不改：
+
+```json
+{ "code": 200, "message": "成功", "data": null, "success": true }
+```
+
+#### 错误响应
+
+团期管理员调用本组任一端点：
+
+```json
+{
+  "code": 581008,
+  "message": "无权查看此订单",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- 本组与第 1 组**使用同一个错误码 581008**，前端无法靠错误码区分「这个端点该角色永远调不了」与「这单不是团期子订单」。区分办法是看请求的是哪个端点：本组 13 个对该角色恒 581008。
+- **收回是按端点清单做的，不是按响应体自动判的**：新增金额面端点不会自动纳入。若前端发现某个含金额的端点对该角色返回了 200，那是缺口，请报工单，不要当成允许。
+- **对其他角色零行为变化**：本组端点改挂的守卫与本批之前的读面守卫在开关上逐字节相同（车务放行、房务 581045、其余须本单定制师），只把新放开的那一个角色收回去。
+- 第 9~11 项在控制器与 Service 各判一次（刻意的双层防御），行为一致，不会出现「一层放一层拒」的中间态。
+
+---
+
+### 3. 订单域写端点（权限拒绝） `POST /v3/admin/order/group-batch/sub-order/{orderId}/withdraw`
+
+**VO**: `SubOrderWithdrawReqVO → SubOrderWithdrawRespVO`
+
+#### 使用场景
+
+订单详情页与团期详情页上一切「改」的动作。团期管理员是**只读**角色，本组一律 581008。前端应对该角色隐藏全部写入口（含详情页内的编辑按钮、Tab 内的新增/删除、团期侧的撤出/转入）。
+
+**纳管范围（按控制器，逐一列全）**：
+
+| 控制器 | 覆盖的写面 |
+|--------|-----------|
+| `OrderController` | 创建 / 修改 / 行前取消 / 终止预览 / 终止 / 状态流转 / 确认行程（7 个写端点） |
+| `TravelerAdminController` | 出行人增删改 |
+| `TransportPlanAdminController` | 大交通方案增删改 |
+| `ItineraryAdminController` / `ItineraryEditAdminController` | 行程与行程编辑 |
+| `AdminRefundController` | 退款发起与处理 |
+| `AdminContractController` | 合同 |
+| `AdminInsuranceController` | 保险 |
+| `CollabAdminController` | 协作 |
+| `AdminWorkOrderController` | 工单 |
+| `AdminTeamReportController` | 团报 |
+| `OrderAdvanceController` | 预付 |
+| `InvoiceAdminController` / `AdminInvoiceController` | 发票 |
+| `GroupBatchActionController` | 子订单撤出（`withdraw`）、转入（`transfer-in`）两个团期动作 |
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| orderId | Path | Long | ✅ | - | 子订单 ID |
+| 请求体 | Body | Object | 视端点而定 | - | **结构本批零改动** |
+| Authorization | Header | String | ✅ | Bearer token | 角色 key 由网关透传 |
+
+#### 出参 `Result<SubOrderWithdrawRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data | Object | **结构零改动**；对 GROUP_BATCH_MANAGER 永远拿不到（先抛 581008） |
+
+#### 请求示例
+
+```http
+POST /v3/admin/order/group-batch/sub-order/2101506167043985410/withdraw HTTP/1.1
+Host: <网关域名>
+Authorization: Bearer <团期管理员的 token>
+Content-Type: application/json
+```
+
+```json
+{ "reason": "客户取消" }
+```
+
+#### 空数据 / 降级响应
+
+本组端点不返回列表，无空数据形态；对有权角色的成功响应与本批之前一致：
+
+```json
+{ "code": 200, "message": "成功", "data": true, "success": true }
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 581008,
+  "message": "无权查看此订单",
+  "success": false,
+  "data": null
+}
+```
+
+⚠️ **报文文案是「无权查看此订单」，出现在写操作上会读着别扭**——这是刻意复用读侧错误码（前端对 581008 已有一套处理），不是挂错。前端在写入口上可自行换一句更贴切的提示文案，但判据仍是 581008。
+
+#### 业务边界
+
+- 拒绝**只针对 `GROUP_BATCH_MANAGER` 这一个角色**，与订单是不是团期子订单无关（写面不做 `groupBatchId` 分叉）。
+- **对其他任何角色零行为变化**：这些写端点此前对客服 / 运营 / 财务等角色没有归属校验，本批**保持原样**，不要把本条读成「订单写面已做归属收口」。
+- MQ 回放 / 定时任务 / 内部 Feign / 单测等非请求上下文无角色，放行，与既有守卫一致。
+
+---
+
+## 四、契约约束与正确调用方式（接口类必写）
+
+> 本节只写**后端接受/拒绝请求的规则**，不写 UI 渲染建议。
+
+### ✅ 放行 / ❌ 拒绝对照（调用方角色 = GROUP_BATCH_MANAGER）
+
+| 场景 | 结果 |
+|------|------|
+| ✅ `GET /v3/admin/order/{id}`，该单 `groupBatchId` 非空 | 200，正常返回 |
+| ✅ `GET /v3/admin/order/{id}/itinerary`，团期子订单 | 200 |
+| ✅ `GET /v3/admin/order/meal-info/list?orderId=<团期子订单>` | 200 |
+| ❌ `GET /v3/admin/order/{id}`，该单 `groupBatchId` 为 NULL（散客单） | 581008 |
+| ❌ `GET /v3/admin/order/{id}/finance`（哪怕是团期子订单） | 581008 |
+| ❌ `GET /v3/admin/order/{orderId}/payment/list` | 581008 |
+| ❌ `PUT /v3/admin/order/{id}`（修改订单） | 581008 |
+| ❌ `POST /v3/admin/order/group-batch/sub-order/{orderId}/withdraw` | 581008 |
+
+### 切换状态时的必要动作
+
+- 前端不需要、也不应该在请求里传角色：角色 key 由网关从 JWT 透传，后端只认它。
+- 判断「当前用户能不能看金额面」**不要靠试调**：按当前登录角色是否为团期管理员在前端直接分支，避免每个 Tab 打开时先吃一个 581008。
+- 团期管理员登录后需**重新登录或刷新页面**才能拿到新注册的 `/order-v2/detail/:id` 路由（前端路由表在登录时一次性生成）。
+
+---
+
+## 五、数据库行为
+
+本条不改任何业务数据结构。唯一的数据变更是**角色菜单绑定**（hl-user-service）：
+
+| 变更 | 外部可观察行为 |
+|------|----------------|
+| 给 `GROUP_BATCH_MANAGER` 绑定「订单详情」菜单 `/order-v2/detail/:id` | `GET /admin/menu/my` 对该角色多返回这条菜单，前端动态路由才能注册该路径 |
+
+- 该角色**只绑「订单详情」，不绑「订单列表」**：绑列表等于给全站订单的浏览入口，超出诉求。父目录「订单管理v2」该角色此前已持有，路由父链完整。
+- 菜单不走 Redis 缓存，但**前端路由表在登录时一次性生成**：已登录的会话需要重新登录或刷新页面才看到新路由。
+- 在此之前，该角色从未注册过 `/order-v2/detail/:id` 路由，团期详情页点子订单「进入」会命中前端兜底路由 404，请求压根发不到后端——所以本批之前看到的 404 与后端 581008 是两回事。
+
+---
+
+## 六、边界行为
+
+- 未登录 → 401（网关拦截）。
+- 团期管理员访问散客单的任一读端点 → 581008。
+- 团期管理员访问 13 个金额面端点 → 581008。
+- 团期管理员访问任一订单域写端点 → 581008。
+- 房务管理员 / 房务组长访问订单详情读面 → 581045（既有行为，不变）。
+- 订单不存在 → 订单不存在错误码，不 500。
+
+### 🔴 已知缺口：端点收回 ≠ 金额不可见
+
+本批**只收端点、不改响应体**（响应脱敏是独立设计，不在本单）。所以团期管理员打开子订单详情时，**仍会在响应里拿到金额**：
+
+| 位置 | 仍可见的内容 |
+|------|--------------|
+| `GET /v3/admin/order/{id}` 的 `main` | `totalAmount`、`payableAmount`、`paidAmount`、`refundAmount`、`balanceAmount`、`depositAmount`、`singleRoomSurcharge` 共 7 个金额字段 |
+| `GET /v3/admin/order/{id}/contract-insurance` | 保费 |
+| `GET /v3/admin/order/{id}/itinerary` | 协议价与结算价 |
+
+主详情之所以不一并收回，是因为它是页面入口，收了等于工单诉求落空。
+
+**前端据此决定渲染**：若产品口径要求该角色看不到金额，需要在前端按角色隐藏上述字段的展示；后端此版不做脱敏，字段会照常下发。
+
+---
+
+## 六.5、枚举 / 数据字典
+
+### role_key（与本条判权相关的后台角色）
+
+**所属字段**: 不在任何请求/响应体中——由网关从 JWT 的 `role_key` 经 `X-Admin-Role` 透传给后端 | **类型**: `String`
+
+| 值 | 中文 | 在本条中的行为 |
+|----|------|----------------|
+| `GROUP_BATCH_MANAGER` | 团期管理员 | 本条唯一行为变化的角色：团期子订单读面放行，金额面 13 端点 581008，写面全域 581008 |
+| `ADMIN` / `SUPER_ADMIN` | 管理员 / 超级管理员 | 恒放行，零变化 |
+| `VEHICLE_MANAGER` | 车务管理员 | 读面与金额面均放行（派车需看签单与预付），零变化 |
+| `ROOM_MANAGER` | 房务管理员 | 订单详情读面 581045，零变化 |
+| `house_keeper_lead` | 房务组长 | 同房务管理员，零变化 |
+| 其余（定制师 / 运营 / 客服 / 财务等） | - | 须为本单定制师，否则 581008，零变化 |
+
+### 本条涉及的错误码
+
+**所属字段**: `Result.code` | **类型**: `Integer`
+
+| 值 | 报文 | 触发条件 |
+|----|------|----------|
+| `581008` | `无权查看此订单` | 团期管理员访问散客单 / 金额面端点 / 任一写端点；或其他角色非本单定制师 |
+| `581045` | `房务角色无权查看订单详情，房务仅可配房` | 房务管理员 / 房务组长访问订单详情读面（既有，不变） |
+
+---
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 |
+|------|------|------|
+| 全部涉及端点的请求体 | - | **逐字段不变** |
+| 全部涉及端点的响应体 | - | **逐字段不变**（含主详情的 7 个金额字段，见已知缺口） |
+
+本条零字段变更，变的只有判权结果。
+
+### 行为级对比（调用方角色 = GROUP_BATCH_MANAGER）
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| 点团期子订单「进入」 | 前端路由未注册 → 404（请求发不出去） | 路由可注册，详情页可打开 |
+| `GET /v3/admin/order/{团期子订单}` | 581008 | 200 |
+| `GET /v3/admin/order/{散客单}` | 581008 | 581008 |
+| 行程 / 确认清单 / 服务标准 / 状态日志 / 打印行程单 / 推送记录 / 合同保险 / 行程文档 / 用餐信息 | 581008 | 200（仅团期子订单） |
+| 财务 / 发票 / 退款 / 取消预览 / 签单 / 预付 / 优惠加价 / 收款流水 / 手工收款（13 端点） | 581008 | 581008 |
+| 改同行人 / 改行程 / 发起退款 / 开合同 / 改保险 / 改大交通 / 改订单主单 | 读面进不去，实际调不到 | 明确 581008 |
+| 子订单撤出 / 转入 | 同上 | 明确 581008 |
+
+---
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 否。零字段变更；对 `GROUP_BATCH_MANAGER` 之外的任何角色零行为变化。
+- **前端是否必须同步上线**: 是。需要按角色控制入口——否则团期管理员打开子订单详情后，金额面 Tab 与写按钮仍在页面上，点一次吃一个 581008。
+- **前端 workaround 清理点**:
+  - 若此前为「团期管理员点子订单必 404」做过前端兜底提示（例如直接禁用「进入」按钮、或点击后提示无权限），**可以撤掉**——该角色现在能正常打开团期子订单详情。
+  - 若此前把团期管理员当成「订单域完全无权」的角色做过整块屏蔽，需要改成**分面控制**：读面开、金额面关、写面关。
+  - 已登录的团期管理员账号需要重新登录或刷新页面才能拿到新注册的详情路由，前端如有路由缓存需一并处理。
+
+---
+
+## 七、不影响范围（显式声明, 帮前端/QA 缩小排查面）
+
+- **仅影响**: 管理后台 `GROUP_BATCH_MANAGER`（团期管理员）角色的订单域行为。
+- **零影响**:
+  - 其他全部后台角色（超管 / 管理员 / 定制师 / 运营 / 客服 / 财务 / 车务 / 房务 / 房务组长）在上述任一端点上的权限与响应。
+  - 所有请求参数与响应字段结构（零字段变更）。
+  - 小程序端 `/v3/mp/**` 全部接口。
+  - 内部 Feign `/v3/internal/**` 与 MQ 回放 / 定时任务链路（非请求上下文无角色，放行，与既有守卫一致）。
+  - 订单写端点对其余角色的归属校验现状（存量缺口保持原样，本批不治理）。
+  - 房务配房链路（走 in-process 聚合器，不经本批端点）。
+  - 团期需求域的用车 / 用房需求接口（那批改动见同批另一份交接件）。
+
+---
+
+## 八、测试环境已验证
+
+**网关路由**：本条零网关改动。涉及端点全部落在 `hl-gateway` 已配置的 `/v3/admin/**` 通配路由内，无新增 `/admin/` 前缀（故 `gateway_status: not_required`）。
+
+**架构门禁**（分支 `fix/8154-group-batch-manager-order-view`）：
+
+```
+GroupBatchManagerFinanceReadGuardArchTest   13 个金额端点（15 个方法）必须且只能挂财务守卫   ✓
+GroupBatchManagerWriteGuardArchTest         14 个写面控制器 + 2 个团期动作方法全部纳管        ✓
+RoleClaimFailOpenInventoryTest              角色缺失放行清册未被意外改动                      ✓
+RedLineArchTest                             架构红线门禁                                      ✓
+```
+
+两条金额面门禁是成对的：一条要求财务端点**必须**调财务守卫，另一条要求它们**不得**调放行团期管理员的宽松守卫——只有第一条时，两条守卫都写上仍会绿，而宽松那条在顺序靠前时会先放行。
+
+**数据库变更**：`V20260922_154__grant_order_detail_menu_to_group_batch_manager.sql`（hl-user-service），`INSERT IGNORE` + 唯一键，重复执行零新增行；角色或菜单任一不存在时匹配 0 行、迁移仍成功。
+
+**生产环境覆盖边界**：二期（order-v3 / fleet）尚未上线生产，本条涉及的 `/v3/admin/**` 路径在生产环境为 404；生产库 `sys_menu` 是否存在 `path = '/order-v2/detail/:id'` 这一行未查证，若不存在则该菜单迁移在生产上按设计安全跳过。这是既有事实，不是本批引入的。
+
+**活体实测**（测试服网关 `https://api.test.1814.love:9443`，2026-09-22 13:0x–13:1x；`hl-order-service-v3` @ `f1986f996`，`hl-user-service` @ `c4321f961`）。用一个 `GROUP_BATCH_MANAGER` 角色账号，对一个团期子订单与一个散客单逐个请求。左列是本批改动**前**在同一环境实测的读数，右列是改动后：
+
+| 端点 | 改动前 | 改动后 | 结论 |
+|---|---|---|---|
+| `GET /v3/admin/order/{团期子订单 id}` | 581008 | 200 | 放行 |
+| `GET .../{id}/itinerary` | 581008 | 200 | 放行 |
+| `GET .../{id}/status-log` | 581008 | 200 | 放行 |
+| `GET .../{id}/finance` | 581008 | 581008 | 不变 |
+| `GET .../{id}/invoices` | 581008 | 581008 | 不变 |
+| `GET .../{id}/refund` | 581008 | 581008 | 不变 |
+| `GET .../{id}/sign-voucher` | 581008 | 581008 | 不变 |
+| `GET .../{id}/contract-insurance` | 581008 | 581008 | 不变 |
+| `GET /v3/admin/order/{散客单 id}` | 581008 | 581008 | **阴性对照**：放行范围未扩大到散客单 |
+| `PUT /v3/admin/order/{团期子订单 id}` | **放行，返 `data: true`** | **581008** | **写面缺口已堵** |
+
+（表中的 581008 指响应体里的业务 `code`，HTTP 状态码按本仓约定一律为 200。）
+
+最后一行是本批最有分辨力的一条读数：**改动前该角色读订单被拒、写订单却畅通**——读面有守卫挡着，写面当时没有任何团期管理员判权。它不是为放开读权而配套加的保险，它本身就是一个既有越权，本批一并收口。
+
+**user-service 迁移已在测试环境生效**（启动日志原文）：
+
+```
+Migrating schema `hl_user_service` to version "20260922.154 - grant order detail menu to group batch manager"
+Successfully applied 1 migration to schema `hl_user_service`, now at version v20260922.154
+```
+
+第二个实例随后启动时读到 `Current version ... 20260922.154` / `Schema is up to date`，两实例一致。
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#8154](https://git.1814.love:8443/wx/HL/issues/8154)
+- 同批交接件: `changelogs-v2/2026-09/22_8152_团期用车需求补车辆规格与接送机汇总-修改接口-管理后台.md`（团期需求域字段与端点变更）
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8154](https://git.1814.love:8443/wx/HL/issues/8154)
+- **分支**: `fix/8154-group-batch-manager-order-view`
+
+### 联系人
+
+- **后端负责人**: @wx
@@ -0,0 +1,446 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8155"
+title: "通知中心: 需求驳回站内信 bizId 改为 orderId，修复管理端「跳转」打开不存在订单"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修复"
+backend_status: "deployed"
+gateway_status: "not_required"
+frontend_status: "not_required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "本条不改变 AdminMessageRespVO/AdminMessagePageReqVO 的字段结构，只修正 REQUIREMENT_REJECTED 事件写入 admin_message 的 bizId 取值、以及 notification_event_config.inapp_link_template 的路由前缀。gateway_status=not_required：本条不引入任何新路由，受影响的 GET /admin/message/list 与 GET /admin/message/{id} 是既有端点。frontend_status=not_required：前端 jumpToBiz（hl-ui/src/views/notification/MyMessages/index.vue:268-286）只读 row.bizId/row.bizModule/row.bizType/row.peerRole，从不读 row.link，字段名/类型/位置均未变，无需任何前端代码改动。backend_status=deployed：order-v3 与 user-service 均已部署测试服务器至 6af4d93e5（双实例滚动完成），并已在自建夹具上走完「提交用车需求 → 车控驳回 → 站内信产出」全链路，实测读数见正文第八节。⚠️ admin_message 是快照表：bizId 与渲染后的 link 在 createMessage 落库那一刻一次性写入行内（NotificationDispatcher.java:1038 渲染 link、:1042 起调用 AdminMessageService.createMessage、AdminMessageService.java:121-123 写入实体、:541 toVO 透传），不是按需渲染；因此本修复只影响部署生效后新产生的消息，此前已产出的历史站内信 bizId 与 link 都仍是旧值，不做批量回刷——REQUIREMENT_REJECTED 目前只在测试环境触发过（order-v3/fleet 尚未上生产），不涉及生产数据。"
+updated_at: "2026-09-22"
+base: "dev-v3"
+---
+
+# 通知中心: 需求驳回站内信 bizId 改为 orderId，修复管理端「跳转」打开不存在订单
+
+> **存放目录**: 二期（order-v3）→ `changelogs-v2/2026-09/`
+>
+> **服务**: hl-order-service-v3（通知发布方）+ hl-user-service（通知分发/站内信收件箱）
+> **PR**: [#8160](https://git.1814.love:8443/wx/HL/pulls/8160)
+> **Issue**: [#8155](https://git.1814.love:8443/wx/HL/issues/8155)
+> **日期**: 2026-09-22
+> **影响范围**: 管理后台站内信中心「需求驳回」事件的 `bizId` 取值与对应跳转链接前缀
+
+---
+
+## ⚠️ 关键变化
+
+**需求驳回站内信的 `bizId` 从需求行 ID 改为订单 ID，前端「跳转」按钮从此能正确打开订单详情。**
+
+- 改前：站内信声明 `bizType="ORDER"`，但 `bizId` 实际写入的是被驳回的需求行 ID（`vehicle_requirement`/`hotel_requirement` 主键）。前端按 `bizType=ORDER` 的契约把 `bizId` 当 `orderId` 去查订单，订单查不到，「跳转」必然落空。
+- 改后：`bizId` 恒等于 `order.getOrderId()`；被驳回的需求行 ID 改经 `params` 下发，排查能力不丢（落 `notification_send_log.params_json`）。
+- **前端不需要改任何代码**：`AdminMessageRespVO` 的字段名、类型、位置都没变，变的只是 `bizId` 这一个既有字段过去写错了、现在写对了。
+- 同批一并修正了该事件 `inapp_link_template` 的路由前缀（`/order/detail/${orderId}` → `/order-v2/detail/${orderId}`）。该字段前端当前完全不读，此改动不影响现有跳转行为，只是让 link 本身不再是一个过期契约值。
+
+---
+
+## 一、背景
+
+### 缺陷形态
+
+`NotificationEventHelper.sendRequirementRejected(order, requirementId, requirementType, reason)`（`hl-order-service-v3/src/main/java/com/hulalv/shared/notification/NotificationEventHelper.java`）改前的调用链：
+
+```
+sendRequirementRejected(...) → sendInternal("REQUIREMENT_REJECTED", order, params, requirementId)
+                              → buildAndSend(eventCode, order, params, bizId=requirementId, userId=null)
+                              → NotificationEventMessage.bizId = String.valueOf(requirementId)
+                                                        .bizType = "ORDER"
+```
+
+而本类同一文件里其余三个事件（`sendContractFailed`/`sendInsuranceFailed`/`sendPaymentReminder`）走的是无 `bizId` 参数的 `send(eventCode, order, params)` 重载，该重载内部固定用 `order.getOrderId()` 作为 `bizId`——这三个事件从未受本缺陷影响，只有 `sendRequirementRejected` 在调用点显式传了 `requirementId` 顶替 `bizId`。
+
+### 触发路径
+
+该事件仅在下列 4 个既有写端点判定「打回目标=定制师（CONSULTANT）」时触发，端点本身的请求/响应契约本次未改动：
+
+| 端点 | 触发条件 |
+|------|----------|
+| `POST /v3/admin/order/{id}/vehicle-requirement/reject`（`VehicleRequirementAdminController.java:100`） | 团期管理员打回定制师，恒触发 |
+| `POST /v3/admin/order/{id}/hotel-requirement/reject`（`HotelRequirementAdminController.java:96`） | 团期管理员打回定制师，恒触发 |
+| `POST /v3/admin/order/{id}/vehicle-requirement/supplier-reject`（`VehicleRequirementAdminController.java:120`） | 供应商打回，仅非团期（核心）订单派生目标为 CONSULTANT 时触发；团期订单派生目标为管理员，本期不通知 |
+| `POST /v3/admin/order/{id}/hotel-requirement/supplier-reject`（`HotelRequirementAdminController.java:115`） | 同上 |
+
+### 数据落地路径（已核实的完整链路）
+
+```
+NotificationEventHelper.buildAndSend → MQ → NotificationDispatcher.dispatchAdminInApp
+  → renderer.render(config.getInappLinkTemplate(), renderParams)      (NotificationDispatcher.java:1038)
+  → AdminMessageService.createMessage(adminId, ..., link, bizId, bizType)   (:1042起调用)
+  → AdminMessage 实体落库 biz_id / link                                 (AdminMessageService.java:121-123)
+  → AdminMessageService.toVO(msg, ...)：vo.setLink/setBizId/setBizType  (:541-543)
+  → GET /admin/message/list、GET /admin/message/{id} 返回给前端
+```
+
+`link` 与 `bizId` 在 `createMessage` 落库那一刻一次性写入行内，之后读取（无论列表还是详情）都是直接透传已落库的值，不会按当前配置重新渲染——这是下方「六、边界行为」里历史数据不回刷的直接原因。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 站内信分页列表 | GET | `/admin/message/list` | 返回值语义修正 | `REQUIREMENT_REJECTED` 事件产生的消息行，`bizId` 由需求行 ID 改为 orderId，`link` 前缀同步修正；字段结构不变 |
+| 2 | 站内信详情 | GET | `/admin/message/{id}` | 返回值语义修正 | 同上 |
+
+---
+
+## 三、接口详情
+
+### 1. 站内信分页列表 `GET /admin/message/list`
+
+**VO**: `AdminMessagePageReqVO → Result<PageResult<AdminMessageRespVO>>`
+
+#### 使用场景
+
+站内信中心列表页拉取当前登录员工的收件箱，系统通知与聊天消息按 `createTime` 倒序混排返回。`REQUIREMENT_REJECTED` 属于系统通知（`kind=NOTIFY`），随全部系统通知混排在本接口结果里，不需要单独的查询参数。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| pageNo | Query | Integer | ❌ | ≥1，默认 1 | 页码 |
+| pageSize | Query | Integer | ❌ | 1~100，默认 20 | 每页条数 |
+| categoryCode | Query | String | ❌ | HOUSE/ORDER/SYSTEM | 消息分类编码，为空查全部；仅对系统通知有效（聊天行/团队池行该字段为 null） |
+| messageType | Query | String | ❌ | ORDER/NORMAL | 消息类型，为空查全部；按 kind 派生（ORDER=聊天/NORMAL=系统通知） |
+
+本次未改动入参，照源码列出供自包含核对。
+
+#### 出参 `Result<PageResult<AdminMessageRespVO>>`
+
+`PageResult` 字段：`records`(List)、`total`(int)、`page`(int)、`pageSize`(int)。
+
+`AdminMessageRespVO` 字段（本次仅 `bizId`/`link` 两个字段的**取值**变化，字段结构不变）：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| messageId | String | 消息ID(雪花ID,String透传防精度丢失) |
+| categoryCode | String | 消息分类编码: HOUSE=房务/ORDER=订单/SYSTEM=系统。系统通知为 SYSTEM；聊天消息(kind=CHAT)该字段为 null |
+| title | String | 消息标题 |
+| content | String | 消息内容 |
+| link | String | 跳转链接。**本次修正**：`REQUIREMENT_REJECTED` 新产生的消息此字段前缀由 `/order/detail/` 改为 `/order-v2/detail/`；前端当前不读该字段 |
+| bizId | String | 关联业务ID。**本次修正**：`REQUIREMENT_REJECTED` 新产生的消息此字段由需求行 ID 改为订单 ID |
+| bizType | String | 关联业务类型: ORDER/HOUSE/REFUND |
+| isRead | Integer | 是否已读(0未读 1已读) |
+| createTime | Long | 创建时间(时间戳) |
+| messageType | String | 消息类型(ORDER=订单消息 NORMAL=普通消息) |
+| messageTypeLabel | String | 消息类型标签(订单消息/普通消息) |
+| kind | String | 消息特性: NOTIFY=系统通知 / CHAT=聊天消息 |
+| senderName | String | 发件人姓名(仅聊天消息有值) |
+| conversationKey | String | 会话键(仅聊天消息有值) |
+| teamMessage | Boolean | 是否车务团队共享消息 |
+
+#### 请求示例
+
+```json
+{ "pageNo": 1, "pageSize": 20, "messageType": "NORMAL" }
+```
+
+#### 响应示例
+
+字段名与类型均照 `AdminMessageRespVO` 源码；`bizId`/`orderId` 取值对齐 `NotificationEventHelperTest` 单测夹具（`baseOrder().orderId = 1001L`），用于展示修正后的取值形态：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "records": [
+      {
+        "messageId": "1001",
+        "categoryCode": "SYSTEM",
+        "title": "需求已驳回",
+        "content": "订单 1001 的用车需求已被驳回：车型不合适",
+        "link": "/order-v2/detail/1001",
+        "bizId": "1001",
+        "bizType": "ORDER",
+        "isRead": 0,
+        "createTime": 1709452800000,
+        "messageType": "NORMAL",
+        "messageTypeLabel": "普通消息",
+        "kind": "NOTIFY",
+        "senderName": null,
+        "conversationKey": null,
+        "teamMessage": false
+      }
+    ],
+    "total": 1,
+    "page": 1,
+    "pageSize": 20
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": { "records": [], "total": 0, "page": 1, "pageSize": 20 },
+  "success": true
+}
+```
+
+#### 错误响应
+
+未登录/取不到 adminId 时由 `AdminRequestContextUtil.requireAdminId` 统一拦截（鉴权异常，非本次改动范围），不返回业务错误码；参数校验失败（如 `pageSize>100`）由 `@Valid` 拦截返回标准校验错误结构，本次未改动。
+
+#### 业务边界
+
+- WHERE 条件含 `adminId`，仅返回当前登录员工自己的收件箱；`VEHICLE_MANAGER` 角色会额外混排车务团队共享池行（`teamMessage=true`），其余角色不受影响。
+- 本次改动不影响分页、排序、已读状态、团队池行的既有行为，只影响 `REQUIREMENT_REJECTED` 类型行的 `bizId`/`link` 取值。
+- 部署生效前已产生的 `REQUIREMENT_REJECTED` 历史行，`bizId`/`link` 仍是旧值，见「六、边界行为」。
+
+### 2. 站内信详情 `GET /admin/message/{id}`
+
+**VO**: `Long messageId(PathVariable) → Result<AdminMessageRespVO>`
+
+#### 使用场景
+
+列表点开一条消息、顶部铃铛点击、详情页刷新（前端仅持 `messageId`）时按 ID 拉取单条详情，含完整正文与跳转关联业务信息。纯查询，不改变已读状态。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| id | Path | Long | ✅ | `{id}` | 消息 ID |
+
+#### 出参 `Result<AdminMessageRespVO>`
+
+字段与「1. 站内信分页列表」的 `AdminMessageRespVO` 表完全一致（同一 VO），此处不重复列出各字段说明；`bizId`/`link` 的修正内容同上。
+
+#### 请求示例
+
+```json
+GET /admin/message/1001
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "messageId": "1001",
+    "categoryCode": "SYSTEM",
+    "title": "需求已驳回",
+    "content": "订单 1001 的用车需求已被驳回：车型不合适",
+    "link": "/order-v2/detail/1001",
+    "bizId": "1001",
+    "bizType": "ORDER",
+    "isRead": 0,
+    "createTime": 1709452800000,
+    "messageType": "NORMAL",
+    "messageTypeLabel": "普通消息",
+    "kind": "NOTIFY",
+    "senderName": null,
+    "conversationKey": null,
+    "teamMessage": false
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+不存在空数据形态（单条查询查不到直接走下方错误响应）；无下游依赖，无降级分支。
+
+#### 错误响应
+
+消息不存在 / 已逻辑删除 / 属于其他员工，三种情况统一返回同一错码（`AdminMessageService.getMessageDetail`，不区分原因、不泄露他人消息是否存在）：
+
+```json
+{
+  "code": 200401,
+  "message": "站内信不存在或无权访问",
+  "data": null,
+  "success": false
+}
+```
+
+错误码定义：`UserProfileErrorCode.ADMIN_MESSAGE_NOT_FOUND`（`hl-user-service/src/main/java/com/hulalv/user/errorcode/UserProfileErrorCode.java:260`），HTTP 状态仍为 200，业务码 `200401`。本次改动未新增/修改该错误码。
+
+#### 业务边界
+
+- WHERE 条件含 `adminId`，越权访问一律按不存在处理（不区分"不存在"和"是别人的"）。
+- `VEHICLE_MANAGER` 角色额外放行车务团队池行，其余角色查不到池行，行为不变。
+- 本次改动不影响该接口的鉴权、越权防护、错误码，只影响返回体内 `bizId`/`link` 两个字段在 `REQUIREMENT_REJECTED` 类型行上的取值。
+
+---
+
+## 四、契约约束与正确调用方式
+
+> 本节写的是响应值契约（`bizType`/`bizId` 的配对保证），不是入参 payload 规则——本次改动不涉及请求参数。
+
+### `bizType` ⇒ `bizId` 的配对保证
+
+`bizType` 声明业务对象类型，`bizId` 必须是该类型对象的主键；前端据这一对字段决定跳转目标。本次修复后，`NotificationEventHelper` 发出的全部事件（`CONTRACT_FAILED`/`INSURANCE_FAILED`/`ORDER_PAYMENT_REMINDER`/`REQUIREMENT_REJECTED`）统一在 `buildAndSend` 内部写死 `bizType="ORDER"` 且 `bizId=String.valueOf(order.getOrderId())`，不再接受调用方传入任意 `bizId`——从结构上排除"声明 ORDER 却传别的 id"这一类错误。
+
+| bizType | bizId 语义 | 前端应有动作 |
+|---------|-----------|-------------|
+| `ORDER` | 订单 ID | `getOrderReadableRoute(bizId, userStore)` → `/order-v2/detail/{bizId}`（或管家受限变体） |
+| `HOUSE` / `HOUSE_LEAD` | 参见前端既有路由逻辑（本次未改动） | 本次未改动 |
+| `REFUND` | 订单 ID（`RefundNotificationHelper.java:128-129` 本就正确，未改动） | 同 `ORDER` |
+
+### 前端需要知道的取值边界
+
+- 若 `order.getOrderId()` 为空，本次修复后**该条通知整条不投递**（不会出现 `bizId` 为字面量 `"null"` 的行）；改前会投递一条 `bizId="null"` 的消息。
+- `requirementId` 不再出现在 `bizId`/`bizType` 里，如需按需求行排查，只能从 `notification_send_log.params_json` 里取（后端排查用途，前端接口不暴露该字段）。
+
+---
+
+## 五、数据库行为
+
+### `admin_message` 表（新产生的 `REQUIREMENT_REJECTED` 消息，示例 orderId=1001、requirementId=9009）
+
+| 列 | 改前 | 改后 |
+|----|------|------|
+| `biz_id` | `9009`（需求行 ID） | `1001`（订单 ID） |
+| `biz_type` | `ORDER` | `ORDER`（未变） |
+| `link` | `/order/detail/1001` | `/order-v2/detail/1001` |
+
+### `notification_send_log.params_json`
+
+| 改前 | 改后 |
+|------|------|
+| 不含 `requirementId` | 新增 key `requirementId`（值为空时落空字符串 `""`，不落字面量 `"null"`） |
+
+### `notification_event_config` 表（Flyway `V20260922_001`）
+
+```sql
+UPDATE `notification_event_config`
+SET `inapp_link_template` = '/order-v2/detail/${orderId}',
+    `update_time` = NOW()
+WHERE `event_code` = 'REQUIREMENT_REJECTED';
+```
+
+按 `event_code` 唯一键定位，最多影响 1 行；只改前缀不改 `${orderId}` 占位，重复执行第二次起 affected rows 为 0（幂等）。**不改动已合入 dev-v3 的 `V20260812_001`**（Flyway 已冻结迁移不可修改，红线第 ⑫ 条）。
+
+---
+
+## 六、边界行为
+
+- **历史数据不回刷**：`admin_message.biz_id`/`link` 在 `createMessage` 落库那一刻写死，之后读取直接透传，不会按当前配置重新渲染。修复部署生效前已产生的 `REQUIREMENT_REJECTED` 历史站内信，`biz_id` 仍是需求行 ID、`link` 仍是 `/order/detail/...`，两个字段都是旧值，点「跳转」仍会落空。这批数据只存在于测试环境（order-v3/fleet 尚未上生产，该事件在生产从未产生过消息），不做批量回刷。
+- **测试发送端点有意不对齐**：`POST /admin/notification/config/{id}/test`（`AdminNotificationController.java:139-140`）固定写 `bizId="TEST-" + System.currentTimeMillis()`、`bizType="ORDER"`，走真实分发路径，会在 `admin_message` 落一条 `biz_id` 为 `TEST-17...` 形态的行，点「跳转」必然落空。本单**有意不修**（它是管理端调试工具，不代表真实业务对象）。
+- **供应商打回分支不总触发通知**：`supplier-reject` 两个端点仅当打回目标解析为 CONSULTANT（非团期订单）时才触发该事件；团期订单打回目标为管理员，本期不发通知（既有行为，本次未改动）。
+- **orderId 为空时整条不投递**：`order.getOrderId()==null` 时直接跳过发送（不产生该条通知），而不是发一条 `bizId` 为字面量 `"null"` 的消息。
+- **`link` 字段当前是死字段**：前端 `jumpToBiz`（`hl-ui/src/views/notification/MyMessages/index.vue:268-286`）只读 `bizId`/`bizModule`/`bizType`/`peerRole`，全函数不出现 `link`。`link` 前缀对齐不改变任何现有跳转行为，只是让该字段不再是一个过期契约值。
+
+## 六.5、枚举 / 数据字典
+
+### `bizType`（`AdminMessageRespVO.bizType`）
+
+**所属字段**: `bizId`/`bizType` 成对出现 | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `ORDER` | 订单 | `bizId` 为订单 ID；本次修复的对象——`REQUIREMENT_REJECTED` 事件恒为该值 |
+| `HOUSE` | 房务 | 本次未改动 |
+| `REFUND` | 退款 | `RefundNotificationHelper` 发出，`bizId` 本就是订单 ID，未受本次缺陷影响 |
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 |
+|------|------|------|
+| `admin_message.biz_id`（REQUIREMENT_REJECTED 新消息） | 需求行 ID（如 `9009`） | 订单 ID（如 `1001`） |
+| `admin_message.link`（REQUIREMENT_REJECTED 新消息） | `/order/detail/{orderId}` | `/order-v2/detail/{orderId}` |
+| `notification_send_log.params_json` | 不含 `requirementId` | 含 `requirementId`（空值落 `""`） |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| 前端点「跳转」（`REQUIREMENT_REJECTED` 类消息） | 拿需求行 ID 当 orderId 查订单，查不到，跳转落空 | 拿正确的 orderId 查订单，正常打开订单详情 |
+| `order.getOrderId()` 为空 | 仍发送，`bizId` 落字面量 `"null"` | 直接跳过发送，不产生该条通知 |
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 否——`AdminMessageRespVO` 字段结构未变，仅 `REQUIREMENT_REJECTED` 一种事件的 `bizId`/`link` 取值修正；历史行不追溯改写。
+- **前端是否必须同步上线**: 否——字段名/类型/位置均未变，现有读取代码（`jumpToBiz` 等）无需任何修改即可正确工作。
+- **前端 workaround 清理点**: 未查证前端是否针对该缺陷做过规避（例如捕获跳转 404 静默失败、或对 `REQUIREMENT_REJECTED` 类消息隐藏「跳转」按钮）；若存在，现在可以移除，但本次未在 hl-ui 找到此类代码痕迹。
+
+## 七、不影响范围
+
+- **仅影响**: `REQUIREMENT_REJECTED` 事件写入 `admin_message` 的 `biz_id`/`link` 取值，及其对应的 `notification_event_config.inapp_link_template` 前缀。
+- **零影响**:
+  - `AdminMessageRespVO`/`AdminMessagePageReqVO` 的字段结构（名称/类型/位置）
+  - `GET /admin/message/list`、`GET /admin/message/{id}` 之外的全部站内信接口（未读总数、分类未读汇总、标记已读、全部已读、分类已读、删除）——入参/出参/错误码均未改动
+  - 4 个触发该通知的写端点（两个 `.../reject`、两个 `.../supplier-reject`）自身的入参、出参、错误码——这些端点本身代码本次未改动，只是它们触发的通知副作用取值变了
+  - 本类其余 3 个事件（`CONTRACT_FAILED`/`INSURANCE_FAILED`/`ORDER_PAYMENT_REMINDER`）——这 3 个事件改前就已经用 `order.getOrderId()` 作为 `bizId`（走的是无 `bizId` 参数的 `send()` 重载），未受本次缺陷影响；本次改动只是把这个既有正确取值从「各方法各自传入」统一收敛到 `buildAndSend` 内部写死，行为不变
+  - `RefundNotificationHelper` 发出的退款类事件（`bizId=orderId` 本就正确），未改动
+  - C 端 `user_message` 收件箱（`dispatchInApp`/`InternalMpMessageController`）：`REQUIREMENT_REJECTED` 不带 `userId`，不投递 C 端，与本次改动无关
+
+---
+
+## 八、测试环境已验证
+
+**部署**：hl-order-service-v3 与 hl-user-service 均已部署到 `dev-v3` 的 `6af4d93e5`，双实例滚动完成（order-v3 8086/8186、user-service 8081/8181，Nacos `namespaceId=test` 四个实例均 `healthy:true`）。`deploy-status.sh` 复核：两服务 `COMMIT=6af4d93e5 BEHIND=0/N STATE=ok`，部署时间 2026-09-22 11:35:43 / 11:36:25。
+
+**Flyway 迁移**（`hl-user-service-8181.log`）：
+
+```
+11:36:32.835 [main] INFO o.f.core.internal.command.DbMigrate - Migrating schema `hl_user_service` to version "20260922.001 - fix requirement rejected inapp link prefix"
+11:36:32.859 [main] INFO o.f.core.internal.command.DbMigrate - Successfully applied 1 migration to schema `hl_user_service`, now at version v20260922.001 (execution time 00:00.035s)
+```
+
+**端到端实测**（自建夹具：orderId=2102242483750756354 / orderNo=HL20260922114400396 / 需求行 id=2102243384951558146）——提交用车需求 → 车控驳回 → 站内信产出。新产生的 `admin_message` 行：
+
+| 字段 | 实测值 |
+|---|---|
+| `biz_type` | `ORDER` |
+| `biz_id` | `2102242483750756354`（= orderId，**不是**需求行 id 2102243384951558146） |
+| `link` | `/order-v2/detail/2102242483750756354` |
+| `title` | 您提交的用车需求被驳回 |
+| `create_time` | 2026-09-22 11:47:51 |
+
+分发日志（`hl-user-service-8181.log`）：
+
+```
+11:47:51.310 c.h.u.n.NotificationDispatcher - 分发通知事件: eventCode=REQUIREMENT_REJECTED, userId=null, bizId=2102242483750756354
+11:47:51.325 c.h.user.service.AdminMessageService - 创建管理端站内信: adminId=1001, categoryCode=SYSTEM, eventCode=REQUIREMENT_REJECTED, title=您提交的用车需求被驳回
+```
+
+**需求行 ID 仍可反查**：同一次事件的 `notification_send_log.params_json` 实测落库，含 `"requirementId":"2102243384951558146"`，与夹具需求行 id 一致——需求行 ID 从 `bizId` 换到 `params` 后没有丢失（但它**不在**站内信接口的响应里，详见四、契约约束）。
+
+**事件配置**：`notification_event_config.inapp_link_template` 实测为 `/order-v2/detail/${orderId}`（字面量，Flyway `placeholder-replacement: false`），占位符在 `NotificationDispatcher` 运行时渲染。
+
+**定向单测**（`dev-v3` @ `6af4d93e5`）：
+
+| 测试类 | 读数 |
+|---|---|
+| `NotificationEventHelperTest` | Tests run: 10, Failures: 0, Errors: 0, Skipped: 0 |
+| `RequirementServiceTest` | Tests run: 321, Failures: 0, Errors: 0, Skipped: 0 |
+| `LayerEnforcementTest` | Tests run: 5, Failures: 0, Errors: 0, Skipped: 0 |
+| `RedLineArchTest` | Tests run: 12, Failures: 0, Errors: 0, Skipped: 0 |
+
+合计 `Tests run: 348, Failures: 0, Errors: 0, Skipped: 0`，`BUILD SUCCESS`。
+
+---
+
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#8155](https://git.1814.love:8443/wx/HL/issues/8155)
+- 关联 PR: [wx/HL#8160](https://git.1814.love:8443/wx/HL/pulls/8160)
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8155](https://git.1814.love:8443/wx/HL/issues/8155)
+- **PR**: [#8160](https://git.1814.love:8443/wx/HL/pulls/8160)
+- **Merge commit**: [6af4d93e5](https://git.1814.love:8443/wx/HL/commit/6af4d93e5)
+
+### 联系人
+
+- **后端负责人**: @wx
@@ -0,0 +1,381 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8159"
+title: "团级配车成员共用候选查询"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "新增接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "bc4024952daa784232abe6fbf56b658b57361bb3"
+target_release: "v2.1"
+verified_at: "2026-09-22"
+status_note: "2026-09-22 mmg 交付:ShareGroupEditModal 新建/编辑选举(浏览态三态 selectable 不误禁、shareGroupId 复算恢复本关系成员并预勾、members 全集提交、605036 确认重发、602106 刷新重选),ShareGroupPanel 加入口,抽屉透传 serviceDates;checkpoint 全绿 26 测试"
+updated_at: "2026-09-22"
+base: "dev-v3"
+---
+
+# 团级配车成员共用候选查询（#8159）
+
+> **服务**: hl-fleet-service（经网关调用，无需关心服务端口）
+> **PR**: #8188
+> **Issue**: #8159
+> **日期**: 2026-09-22
+> **影响范围**: 管理后台团级配车页面成员共用选举
+
+---
+
+## ⚠️ 关键变化
+
+新增查询端点，返回「成员共用」的候选行清单，喂给已有的「确认共用关系」写口。
+
+**三条会直接影响你怎么写代码的点，按严重度排**：
+
+1. 🔴 **`shareGroupId` 必须由前端比对，本接口不会替你做**（业务边界第 2 条）。编辑一个**已存在**的共用关系时，它自己的既有成员会被本接口置灰成 `ALREADY_IN_ANOTHER_GROUP`——前端要把 `shareGroupId` 等于「正在编辑的关系 ID」的行**恢复成可勾选**。并且**提交时 `members` 是全集不是增量**：漏掉的既有成员会被写口按「移出本关系」处理，**不报错、静默生效**。
+2. 🔴 **`occupying` / `selectable` 是三态，`null` 是「未判定」不是「否」**。不传 `resourceId` 时 `occupying` 恒 `null`、`selectable` **永不为 `true`**——但它**可能是 `false`**（已属别的关系、或团期身份缺失这两条浏览态就判得出来），所以置灰要照常渲染。
+3. **成功码是 `code: 200`，不是 `0`**；业务失败也返 HTTP 200，**一律按 `body.code` 判，不要按 HTTP 状态行判**。
+
+---
+
+## 一、背景（选填）
+
+团级配车支持多个成员（派车行、团级配车行）共享同一车或司机资源的场景。选举新成员进关系时，需先查询该服务日下哪些成员行可选。本接口支持按资源维度（车/司机）和具体资源 ID 筛选候选。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 查询成员共用候选 | GET | `/admin/fleet/group-dispatch/batches/{groupBatchId}/share-member-candidates` | 新增接口 | 返回该团服务日下可选成员清单 |
+
+---
+
+## 三、接口详情
+
+### 1. 查询成员共用候选 `GET /admin/fleet/group-dispatch/batches/{groupBatchId}/share-member-candidates`
+
+**VO**: `ShareMemberCandidateRespVO`
+
+#### 使用场景
+
+管理后台团级配车页面「成员共用」选举弹窗打开时，调用本接口获取候选成员清单。前端先让用户选择资源维度（车 / 司机），再传 `resourceId` 重新查询，获得勾选框可选状态。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| `groupBatchId` | Path | Long | ✅ | — | 团期 ID（`group_batch_id`）。🔴 **这不是 `product_batch_id`**；维度错误不报参数校验错，只返 `data: []` |
+| `serviceDate` | Query | String(`yyyy-MM-dd`) | ✅ | 必须在团期服务日窗内 | 服务日。窗外日期返 `code: 602104` |
+| `resourceType` | Query | String | ✅ | `VEHICLE` / `DRIVER` | 资源维度。缺失或非法值返 `code: 100001` |
+| `resourceId` | Query | Long | ❌ | — | 具体资源 ID（车 ID / 司机 ID）。**不传时 `occupying` / `selectable` 返 `null`**（未判定状态，见业务边界第 1 条） |
+
+#### 出参 `Result<List<ShareMemberCandidateRespVO>>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `sourceType` | String | `ASSIGNMENT`（派车行）/ `GROUP_DISPATCH`（团级配车行） |
+| `sourceId` | String | 雪花 ID，**字符串形态**（19 位，前端一律当字符串处理，禁转 Number） |
+| `requirementId` | String | 需求 ID（派车行有值，团级配车行可能 null） |
+| `orderId` | String / null | 订单 ID。`GROUP_DISPATCH` 行可能为 null |
+| `orderNo` | String | 订单号 |
+| `customerName` | String | 客户名称 |
+| `headcount` | Integer | 人数 |
+| `pickupAt` | String | 上车地点 |
+| `dropoffAt` | String / null | 下车地点，可能为 null |
+| `pickupParticipant` | Integer | 上车人数 |
+| `dropoffParticipant` | Integer | 下车人数 |
+| `groupCode` | String / null | 团号，可能为 null |
+| `vehicleModel` | String / null | 车型 |
+| `occupiedVehicleId` | String / null | 该行实际占用的车 ID；未占用时 null |
+| `occupiedVehiclePlate` | String / null | 该行实际占用的车牌号 |
+| `occupiedDriverId` | String / null | 该行实际占用的司机 ID；未占用时 null |
+| `occupiedDriverName` | String / null | 该行实际占用的司机名称 |
+| `occupying` | Boolean / **null** | 本行在 `(serviceDate, resourceType, resourceId)` 上是否活跃占用。**`resourceId` 未传时为 `null`**（未判定） |
+| `shareGroupId` | String / null | 本行所属的 ACTIVE 共用关系 ID；不属任何关系时 null。🔴 **调用方必须拿它和「正在编辑的关系 ID」比对**，见业务边界第 2 条 |
+| `selectable` | Boolean / **null** | 是否可勾选。`true` = 可选；`false` = 不可选（此时 `unselectableReason` 非空）；**`null` = 未判定**（`resourceId` 未传、且本行未被 `ALREADY_IN_ANOTHER_GROUP` / `CROSS_BATCH` 判死时出现）。🔴 **`resourceId` 未传时本字段永不为 `true`** |
+| `unselectableReason` | String / null | 不可选原因枚举值（见六.5 章节）；`selectable=true` 时为 null |
+| `unselectableDetail` | String / null | 人类可读的补充说明，如「订单 HLxxxx 已在车 A 关系中」 |
+
+#### 请求示例
+
+```json
+GET /admin/fleet/group-dispatch/batches/2102125467954044929/share-member-candidates?serviceDate=2026-12-25&resourceType=VEHICLE&resourceId=2085539421276286978
+```
+
+无请求体。Authorization 头由网关透传（管理后台 JWT）。
+
+#### 响应示例
+
+成功响应（带具体资源 ID 的正常清单）：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": [
+    {
+      "sourceType": "ASSIGNMENT",
+      "sourceId": "2102125764705181697",
+      "requirementId": "2102125585692295169",
+      "orderId": "2102125467924684801",
+      "orderNo": "HL20260922035901739",
+      "customerName": "#8114AC8-X",
+      "headcount": 1,
+      "pickupAt": "满洲里口岸",
+      "dropoffAt": null,
+      "pickupParticipant": 0,
+      "dropoffParticipant": 0,
+      "groupCode": null,
+      "vehicleModel": "丰田普拉多",
+      "occupiedVehicleId": "2085539421276286978",
+      "occupiedVehiclePlate": "蒙A-E2E99",
+      "occupiedDriverId": "2065272150012444674",
+      "occupiedDriverName": "道尔吉",
+      "occupying": true,
+      "shareGroupId": null,
+      "selectable": true,
+      "unselectableReason": null,
+      "unselectableDetail": null
+    }
+  ],
+  "success": true
+}
+```
+
+**示例说明**：示例值取自测试环境某次真实调用，不构成可复现夹具。
+
+#### 空数据 / 降级响应
+
+该团该服务日无任何在飞派单与活跃团级配车行时返 `code: 200, data: []`（**不是 null、不抛错**）。
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": [],
+  "success": true
+}
+```
+
+🔴 **区分「空」与「失败关闭」**：拿不到团期权威基线时，本接口**不降级返空**，而是**失败关闭**抛 `GROUP_BATCH_BASELINE_UNAVAILABLE`。⇒ `data: []` 只意味着「确实没有候选」，前端可以放心按「无可选成员」渲染，不必担心它其实是一次被吞掉的下游故障。
+
+#### 错误响应
+
+**服务日不在团期窗内**：
+
+```json
+{
+  "code": 602104,
+  "message": "服务日不在团期服务日窗内: 2026-12-28",
+  "success": false,
+  "data": null
+}
+```
+
+**参数非法**（缺 `resourceType` 或传非法值）：
+
+```json
+{
+  "code": 100001,
+  "message": "参数非法: 资源维度非法: HOUSE",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+**0. 本清单直接喂给写口**：返回的 `sourceType` + `sourceId` 就是「确认共用关系」写口 `members[]` 要的两个字段，**原样透传即可**，不需要再做映射。
+
+**1. `resourceId` 未传时的 `null` 三态语义**
+
+| 字段 | 传了 `resourceId` | 未传 `resourceId`（浏览态） |
+|---|---|---|
+| `occupying` | `true` / `false` | 恒 `null`（未判定） |
+| `selectable` | `true` / `false` | `false` **或** `null`，**永不为 `true`** |
+| `unselectableReason` | `selectable=false` 时非空 | 同左 |
+
+`null` 的含义是**未判定**，不是「否」。不传 `resourceId` 时「当日占没占着这个资源」根本算不出来，所以 `occupying` 一律 `null`。
+
+🔴 **但浏览态下 `selectable` 并不总是 `null`**：有两条判据不依赖 `resourceId`，浏览态照样能判死——
+- **已属别的 ACTIVE 共用关系** → `selectable=false`，`unselectableReason=ALREADY_IN_ANOTHER_GROUP`
+- **团期身份缺失**（`requirement_id` 为空，或团期与本团不符）→ `selectable=false`，`unselectableReason=CROSS_BATCH`
+  ⚠️ **订正 2026-09-22**：本行原写「`group_batch_id` / `requirement_id` 为空」，**`group_batch_id` 那一半不成立**——取数条件是 `eq(group_batch_id, ?)`，`group_batch_id` 为空的派单行**结构上查不出来**、压根不在清单里（见第六节「4. 覆盖范围」）。所以前端**不必**为「`group_batch_id` 为空 + `CROSS_BATCH`」写分支，那个组合不可能出现；会以 `CROSS_BATCH` 出现在清单里的，只有 `requirement_id` 为空或团期不符这两种。
+
+⇒ 前端在浏览态**不能**把 `selectable == null` 当成 `false` 禁用勾选，也**不能**当成 `true` 放开；但**要照常渲染 `selectable === false` 的置灰与原因**——那些行在浏览态就已经定死了，选了具体资源也不会变回可选。
+
+**2. 🔴 `shareGroupId` 必须由调用方比对——这是契约的一部分，不是可选优化**
+
+本读口**不知道你正在编辑哪一个共用关系**，所以凡已属任一 ACTIVE 关系的行，一律置灰为 `ALREADY_IN_ANOTHER_GROUP`。而写口的 602106 拒的是「属于**另一个**关系」——**同一关系的既有成员，写口是收的**。
+
+⇒ **给同一个 `shareGroupId` 追加第 3 个成员这个动作，本清单的置灰结构上覆盖不到。** 前端必须自己做两件事：
+
+1. **把 `shareGroupId` 等于「正在编辑的关系 ID」的行视为可勾选**（忽略本接口给它的 `ALREADY_IN_ANOTHER_GROUP` 置灰）。不做这一步的表现是：编辑一个已有关系时，它自己的现有成员全部不可选，功能做不出来。
+2. 🔴 **提交时 `members` 是全集不是增量**——要把该关系的**既有成员连同新成员一起**放进 `members`。**漏掉的既有成员会被写口按「移出本关系」处理。** 只提交新成员的写法不会报错，但会静默把原有成员全部踢出关系。
+
+**3. `selectable=true` 不是「提交必成功」的承诺**
+
+本清单是**时点快照、不加锁**。返回之后别的车务仍可能把某成员纳入另一个关系，提交时照样可能撞 `602106`。
+
+⇒ 这种 602106 请渲染成「**有人先一步占了，请刷新候选清单重选**」，🔴 **不要当系统故障自动重试——重试必然同样失败**。这条竞态读口消除不了（加锁也不行，锁在响应返回那一刻就已放开），最终由写口的锁定读与唯一键兜底。
+
+**4. 覆盖范围：未关联团期的派单行结构上不在本清单内**
+
+本清单只列 `group_batch_id` 指向本团的派单行。`group_batch_id` 为空的派单行查不出来——但**这不是缺口**：这类行在写口同样恒被 602103 拒，「看不见」与「看得见也提交不了」**等价**。要让这类行可共用，得先补上团期身份（数据侧动作，不是前端能处理的）。
+
+---
+
+## 四、契约约束与正确调用方式
+
+### ✅ 正确 / ❌ 错误请求对照
+
+🔴 **先说判据**：本服务的业务失败与入参校验**一律返 HTTP 200**（`GlobalExceptionHandler` 带 `@ResponseStatus(HttpStatus.OK)`），**`body.code` 才是真相**。前端判错请一律读 `body.code`，**不要读 HTTP 状态行**——按状态行判会把所有业务错误当成成功。
+
+| 场景 | 请求 | 预期（HTTP 恒 200） |
+|------|------|------|
+| ✅ 浏览态，看全清单 | `?serviceDate=2026-12-25&resourceType=VEHICLE`（无 resourceId） | `code: 200`；各行 `occupying=null`；`selectable` 为 `null` 或 `false`（被判死的行），**不会是 `true`** |
+| ✅ 选定车后判可选 | `?serviceDate=2026-12-25&resourceType=VEHICLE&resourceId=2085539421276286978` | `code: 200`；各行 `occupying=true/false`，`selectable=true/false` |
+| ✅ 同团其他服务日 | `?serviceDate=2026-12-26&resourceType=VEHICLE&resourceId=xxx` | 在该团服务日窗内则照常返回候选，否则 `code: 602104` |
+| ❌ 维度错填 | `?serviceDate=2026-12-25&resourceType=HOUSE&resourceId=xxx` | `code: 100001`「参数非法: 资源维度非法: HOUSE」 |
+| ❌ 缺维度参数 | `?serviceDate=2026-12-25&resourceId=xxx`（无 resourceType） | `code: 100001`「参数非法: 资源维度不能为空」 |
+| ❌ 路径参数填成产品班期 ID | `/batches/{product_batch_id}/share-member-candidates?...` | 🔴 **不报参数错**，返 `code: 200` + `data: []`。失败形态是静默的，看起来像「接口没数据」 |
+
+---
+
+## 五、数据库行为
+
+本接口**仅读**，无任何 DB 写入，不新增表、不改表结构、无 Flyway 脚本。
+
+---
+
+## 六、边界行为
+
+**鉴权**（🔴 本单专门订正过一处长期误解，前端排查 403 时会用到）：
+
+- **未登录 / token 失效** → 网关 `JwtAuthFilter` 拦下
+- **已登录但角色不符** → `FleetAdminRoleGuardInterceptor` 对 `/admin/fleet/**` **只放行 `VEHICLE_MANAGER` 与 `SUPER_ADMIN` 两个角色**
+- 🔴 **鉴权的真相是角色，不是权限点**：`fleet:group-dispatch:view` / `fleet:group-dispatch:write` 这两个字符串在整个 Java 侧**零引用**，它们只是权限字典里的声明，不是运行时判据。⇒ **「给某个非车务角色开个只读权限点，让他看候选清单」这件事配置不出来**——那类角色连 `/admin/fleet/**` 都进不来。要改授权粒度得动拦截器，是另一件事。
+
+**其余边界**（一律 HTTP 200，按 `body.code` 判）：
+
+- **资源维度缺失 / 非法** → `code: 100001`
+- **服务日超出团期服务日窗** → `code: 602104`
+- **团期权威基线拿不到** → **失败关闭**（不降级返空），见「空数据 / 降级响应」
+- **本团本服务日无候选** → `code: 200` + `data: []`
+
+**网关路由**：复用既有 `- Path=/admin/fleet/**` → `lb://hl-fleet-service`，本单**不新增路由**。
+
+---
+
+## 六.5 枚举 / 数据字典
+
+### sourceType（行源类型）
+
+**所属字段**: `sourceType` | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|---|---|---|
+| `ASSIGNMENT` | 派车行 | 订单需求对应的派车行 |
+| `GROUP_DISPATCH` | 团级配车行 | 团级配车单位产生的配车行 |
+
+### resourceType（资源维度）
+
+**所属字段**: `resourceType`（查询参数） | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|---|---|---|
+| `VEHICLE` | 车辆 | 按车 ID 筛选候选 |
+| `DRIVER` | 司机 | 按司机 ID 筛选候选 |
+
+### unselectableReason（不可选原因）
+
+**所属字段**: `unselectableReason` | **类型**: `String`
+
+| 值 | 触发条件 | 浏览态（未传 `resourceId`）能否判出 | 对应写口错误码 |
+|---|---|---|---|
+| `CROSS_BATCH` | `requirement_id` **为空**，或团期与本团不符。⚠️ 订正 2026-09-22：**不含 `group_batch_id` 为空**，那类行结构上查不出来、不在清单里（见第六节「4. 覆盖范围」） | ✅ 能 | 602103 |
+| `NOT_OCCUPYING` | 派单不在**可改派的在飞态**，或当日**标记不用车** | ❌ 不能（需 `resourceId`） | 602102 |
+| `ALREADY_IN_ANOTHER_GROUP` | 本行已属某个 ACTIVE 共用关系（此时 `shareGroupId` **非空**） | ✅ 能 | 602106 |
+| `GROUP_DISPATCH_INVALID` | 团级配车行**当日不在此资源上** | ❌ 不能（需 `resourceId`） | 602105 |
+
+**说明**：这一列值**不是**接口返回的 `code`，而是 `unselectableReason` 字段的取值。本接口只要能返回清单，`code` 恒为 `200`；上面那些 6021xx 是**提交共用关系**（写口）失败时才会出现在 `code` 里的。
+
+🔴 **`ALREADY_IN_ANOTHER_GROUP` 这一行前端必须自己复算**：本读口不知道你在编辑哪个关系，会把正在编辑的那个关系的既有成员也置灰成它。判据是 `shareGroupId` 是否等于正在编辑的关系 ID，详见业务边界第 2 条。
+
+---
+
+## 六.6 修改前后对比
+
+无，本接口为新增。
+
+---
+
+## 六.7 影响评估
+
+- **破坏兼容**：否，新增接口
+- **前端同步上线要求**：否，新接口不影响现有流程
+- **workaround 清理**：无
+
+---
+
+## 七、不影响范围
+
+- **仅影响**：管理后台团级配车页面成员共用选举功能
+- **零影响**：
+  - 派车行的查询 / 新增 / 编辑
+  - 订单创建 / 支付流程
+  - 团期成团 / 分配等其他流程
+
+---
+
+## 八、测试环境已验证
+
+真实接口调用结果（hl-fleet-service 已部署 `dev-v3 @ cf9dc85a4`，merge commit `a584bd087`）：
+
+```
+GET /admin/fleet/group-dispatch/batches/2102125467954044929/share-member-candidates
+  ?serviceDate=2026-12-25&resourceType=VEHICLE&resourceId=2085539421276286978
+  → 200 + 候选清单（occupying=true/false, selectable=true/false） ✓
+
+GET /admin/fleet/group-dispatch/batches/2102125467954044929/share-member-candidates
+  ?serviceDate=2026-12-25&resourceType=VEHICLE
+  → 200 + 候选清单（occupying=null, selectable=null） ✓
+
+GET /admin/fleet/group-dispatch/batches/2102125467954044929/share-member-candidates
+  ?serviceDate=2026-12-28&resourceType=VEHICLE&resourceId=xxx
+  → 602104（服务日不在团期服务日窗内） ✓
+
+GET /admin/fleet/group-dispatch/batches/2102125467954044929/share-member-candidates
+  ?serviceDate=2026-12-25&resourceType=HOUSE
+  → 100001（参数非法: 资源维度非法: HOUSE） ✓
+```
+
+---
+
+## 九、相关历史 PR
+
+无，本接口为新增。
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#8159](https://git.1814.love:8443/wx/HL/issues/8159)
+- 关联 PR: [wx/HL#8188](https://git.1814.love:8443/wx/HL/pulls/8188)
+
+---
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8159](https://git.1814.love:8443/wx/HL/issues/8159)
+- **PR**: [#8188](https://git.1814.love:8443/wx/HL/pulls/8188)
+- **Merge commit**: [a584bd087](https://git.1814.love:8443/wx/HL/commit/a584bd087)
+
+### 联系人
+
+- **后端负责人**: @wx
@@ -0,0 +1,289 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8161"
+title: "收票核销硬钩稽 PR-1——登记/编辑挂票收紧为生效态门槛（新增错误码 599412）+ 新增单据维度收票对账下钻 biz-recon"
+consumer: "admin"
+author: "yst(GIT)"
+change_type: "修改接口"
+backend_status: "merged"
+gateway_status: "pending"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "5072da0b991cdcde4cc83cc5be94072eb049d224"
+target_release: "v2.1"
+verified_at: "2026-09-22"
+status_note: "收票（进项发票）域挂票规则收紧：登记(create)/编辑(update)挂 PAYMENT/PREPAY 关联单时新增生效态硬校验，非 APPROVED/PAID 抛新错误码 599412（此前可挂草稿/审批中/已驳回单）；同时新增单据维度收票对账下钻 GET /admin/finance/invoice-in/biz-recon。EXPENSE 关联规则不变。已合并 dev-v3（PR #8163，merge commit 90739708e5），待部署测试服后验证。前端走 biz-candidates 勾选关联的链路天然不触发 599412（候选只出 APPROVED/PAID 单）；若有手填 bizId 或复用存量草稿单关联的入口需处理 599412 提示。 前端已交付(5072da0b):invoice-in.js 新增 getInvoiceInBizRecon,详情「关联业务明细」行级「对账」下钻弹窗(五档金额后端字段直显、unmatchedAmount 负值红字不截断、EXPENSE 供应商空值兜底);599412 经核验前端全走 biz-candidates 勾选天然不触发,零改动。"
+updated_at: "2026-09-22"
+base: "dev-v3"
+---
+
+# 收票核销硬钩稽 PR-1：挂票生效态门槛（599412）+ 单据维度收票对账下钻 biz-recon（管理后台）
+
+> **服务**: hl-order-service-v3（hl-finance 模块，端口 8086/8186）
+> **PR**: #8163
+> **Issue**: #8161
+> **日期**: 2026-09-22
+> **影响范围**: 管理后台「财务管理 - 收票管理（进项发票）」的登记/编辑弹窗（挂关联业务单据）、供应商收票对账页的「按单据下钻」能力
+
+---
+
+## 一、接口背景
+
+收票（进项发票）域已上线（#7857），主链为「登记收票 → 核对 → 作废」，供应商为对账锚点。
+
+本次 PR 解决两个缺口：
+
+1. **挂票门槛缺失**：此前登记（create）/ 编辑（update）发票挂关联业务单据时，后端只验「单据存在 + 归属本供应商」，**不验单据状态**——发票可以挂到草稿（PENDING）/ 审批中（SUBMITTED）/ 已驳回（REJECTED）的应付款、预付款单上。而这些非生效态单据的金额还可能被修改、单据还可能被驳回，造成「钱变了票不知道」，对账口径失真。本次对 PAYMENT / PREPAY 增加生效态硬校验：只有 **APPROVED（已批准）/ PAID（已付讫）**（金额已冻结、无变更入口）的单据才可挂票，否则抛新错误码 **599412**。
+2. **对账无法下钻**：供应商收票对账（supplier-recon）只有供应商维度合计，看不到单张业务单据的收票进度。本次新增单据维度下钻接口 biz-recon，按 bizType + bizId 查单张单据的应收票额 / 已匹配额（拆「已核对」「已收票未核对」两档）/ 未匹配额。
+
+## 二、变更清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 |
+|---|------|------|------|----------|
+| 1 | 单据维度收票对账下钻 | GET | /admin/finance/invoice-in/biz-recon | 新增接口 |
+| 2 | 登记进项发票 | POST | /admin/finance/invoice-in/create | 行为收紧：PAYMENT/PREPAY 关联单须 APPROVED/PAID，否则 599412 |
+| 3 | 编辑进项发票 | PUT | /admin/finance/invoice-in/update | 行为收紧：同 #2（关联走全删重插，门槛自动覆盖存量数据） |
+
+入参结构、出参结构对 #2 #3 均**零变化**（字段名/类型/必填全不变），仅服务端校验规则收紧 + 新增一个错误码。
+
+## 三、接口详情
+
+| 接口 | 使用场景 | 认证 | 幂等性 | 限流 |
+|------|----------|------|--------|------|
+| GET /admin/finance/invoice-in/biz-recon | 收票对账页从供应商/单据行下钻，看单张应付/预付/费用报销单的收票进度与未匹配额 | 管理后台 JWT | 只读，天然幂等 | 网关默认 |
+| POST /admin/finance/invoice-in/create | 登记一张进项发票并可挂多笔业务单据 | 管理后台 JWT | 非幂等（发票号码唯一，重复登记 599401） | 网关默认 |
+| PUT /admin/finance/invoice-in/update | 编辑已收票（RECEIVED）态发票，关联全删重插 | 管理后台 JWT | 非幂等（同内容重复提交幂等） | 网关默认 |
+
+## 四、接口入参
+
+### 4.1 biz-recon Query 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| bizType | String | 是 | 业务类型：PAYMENT 应付款 / PREPAY 预付款 / EXPENSE 费用报销（大小写不敏感，取值域外按 599407 处理） |
+| bizId | Long | 是 | 业务单据 ID（应付单/预付单/费用报销单主键；查无此单 → 599407） |
+
+### 4.2 create / update 请求体关联字段（结构不变，仅校验收紧）
+
+请求体整体结构同既有版本（发票号码/发票类型/供应商/价税合计/日期/影像/备注等，见 #7857 changelog），本次只涉及 relations 数组元素的校验规则：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| relations[].bizType | String | 是 | PAYMENT / PREPAY / EXPENSE |
+| relations[].bizId | Long | 是 | 业务单据 ID。**新规则**：PAYMENT/PREPAY 单据状态必须是 APPROVED 或 PAID，否则整单拒绝并报 599412；EXPENSE 维持只验存在 |
+| relations[].matchAmount | BigDecimal | 是 | 本票对该笔的匹配金额（>0；ΣmatchAmount > 票面金额 → 599406） |
+
+## 五、出参字段（biz-recon → InvoiceInBizReconRespVO）
+
+统一响应包装 Result&lt;InvoiceInBizReconRespVO&gt;，data 字段如下：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| bizType | String | 业务类型英文码（PAYMENT/PREPAY/EXPENSE） |
+| bizTypeName | String | 业务类型中文名（应付款/预付款/费用报销），**直接展示，勿前端再硬编码 map** |
+| bizId | String | 业务单据 ID（Long 主键序列化为**字符串**，防 JS 精度丢失） |
+| bizNo | String | 业务单据号（快照，如应付单号/预付单号/报销单号） |
+| billStatus | String | 单据状态英文码：PENDING/SUBMITTED/APPROVED/REJECTED/PAID |
+| billStatusName | String | 单据状态中文名（草稿/审批中/已批准/已驳回/已付讫），直接展示 |
+| supplierId | String 或 null | 供应商 ID（Long 序列化为字符串）；**EXPENSE 无供应商锚点，恒为 null** |
+| supplierName | String 或 null | 供应商名称（快照）；EXPENSE 恒为 null |
+| billAmount | BigDecimal | 应收票额：PAYMENT 取实付金额 actual_pay_amount / PREPAY 取金额 / EXPENSE 取金额 |
+| matchedVerifiedAmount | BigDecimal | 已核对票匹配额：该单关联的 **VERIFIED** 发票的 Σmatch_amount（剔作废票） |
+| matchedReceivedAmount | BigDecimal | 已收票未核对匹配额：该单关联的 **RECEIVED** 发票的 Σmatch_amount（剔作废票） |
+| matchedAmount | BigDecimal | 已匹配额合计 = matchedVerifiedAmount + matchedReceivedAmount |
+| unmatchedAmount | BigDecimal | 未匹配额 = billAmount − matchedAmount，**可为负数（= 多收票），前端展示不要 max(0,·) 截断** |
+| matchedInvoiceCount | Long | 匹配发票张数（剔作废票，JSON number 非字符串）；无任何匹配时为 0，各匹配额为 0 |
+
+## 六、枚举 / 数据字典
+
+### 6.1 bizType（业务类型）
+
+| 值 | 中文名 | 说明 |
+|----|--------|------|
+| PAYMENT | 应付款 | 应收票额取实付金额（actual_pay_amount，含冲抵后口径） |
+| PREPAY | 预付款 | 应收票额取金额 |
+| EXPENSE | 费用报销 | 无供应商锚点（supplierId/supplierName 为 null），不进供应商对账 |
+
+### 6.2 billStatus（单据状态，应付/预付/费用报销三域状态名一致）
+
+| 值 | 中文名 | 是否可挂票 |
+|----|--------|-----------|
+| PENDING | 草稿 | 否（599412） |
+| SUBMITTED | 审批中 | 否（599412） |
+| APPROVED | 已批准 | **是** |
+| REJECTED | 已驳回 | 否（599412） |
+| PAID | 已付讫 | **是** |
+
+> 「是否可挂票」只对 PAYMENT/PREPAY 强制；EXPENSE 不验状态。
+
+### 6.3 发票状态（匹配额拆分依据，本次无新增值）
+
+| 值 | 中文名 | 是否计入匹配额 |
+|----|--------|---------------|
+| RECEIVED | 已收票 | 计入 matchedReceivedAmount |
+| VERIFIED | 已核对 | 计入 matchedVerifiedAmount |
+| VOIDED | 已作废 | **不计入**（作废自动释放匹配额） |
+
+## 七、错误码
+
+| 错误码 | 常量 | 消息 | 触发场景 |
+|--------|------|------|----------|
+| **599412** | INVOICE_IN_REL_BIZ_NOT_EFFECTIVE | 关联业务单据未生效（应付/预付须已批准或已付讫才可收票） | **本次新增**。create/update 的 relations 挂 PAYMENT/PREPAY 且单据状态非 APPROVED/PAID 时抛出，整单拒绝 |
+| 599407 | INVOICE_IN_REL_BIZ_NOT_FOUND | 关联业务单据不存在 | biz-recon：bizType 取值域外或 bizId 查无此单；create/update：单据不存在、或不归属本发票的开票供应商 |
+| 599405 | INVOICE_IN_AMOUNT_INVALID | 发票金额非法 | relations[].matchAmount 为空或 ≤0（既有） |
+| 599406 | INVOICE_IN_AMOUNT_EXCEEDED | 匹配金额合计超过票面金额 | ΣmatchAmount > invoiceAmount（既有） |
+| 599411 | INVOICE_IN_REL_DUPLICATED | 同一张票重复关联同一业务单据 | 同一请求内 bizType+bizId 重复（既有） |
+
+**599412 与 599407 的区别**：407 = 单据不存在 / 不归属本供应商；412 = 单据存在且归属正确，但**状态未生效**。前端错误提示文案可直接用 message，也可自行区分「选错单」与「单未生效」两种引导。
+
+## 八、示例
+
+### 8.1 典型成功 —— 应付单下钻，部分收票
+
+请求：
+
+    GET /admin/finance/invoice-in/biz-recon?bizType=PAYMENT&bizId=1982736450011223
+
+响应：
+
+```json
+{
+  "code": 0,
+  "data": {
+    "bizType": "PAYMENT",
+    "bizTypeName": "应付款",
+    "bizId": "1982736450011223",
+    "bizNo": "PAY-202609-0042",
+    "billStatus": "PAID",
+    "billStatusName": "已付讫",
+    "supplierId": "1877665544332211",
+    "supplierName": "满洲里蓝天旅行社有限公司",
+    "billAmount": 12000.00,
+    "matchedVerifiedAmount": 8000.00,
+    "matchedReceivedAmount": 2000.00,
+    "matchedAmount": 10000.00,
+    "unmatchedAmount": 2000.00,
+    "matchedInvoiceCount": 2
+  },
+  "msg": ""
+}
+```
+
+### 8.2 边界情况 —— EXPENSE 无匹配发票（各匹配额为 0、供应商字段为 null）
+
+请求：
+
+    GET /admin/finance/invoice-in/biz-recon?bizType=EXPENSE&bizId=1966112233445566
+
+响应：
+
+```json
+{
+  "code": 0,
+  "data": {
+    "bizType": "EXPENSE",
+    "bizTypeName": "费用报销",
+    "bizId": "1966112233445566",
+    "bizNo": "EXP-202609-0118",
+    "billStatus": "APPROVED",
+    "billStatusName": "已批准",
+    "supplierId": null,
+    "supplierName": null,
+    "billAmount": 3500.00,
+    "matchedVerifiedAmount": 0,
+    "matchedReceivedAmount": 0,
+    "matchedAmount": 0,
+    "unmatchedAmount": 3500.00,
+    "matchedInvoiceCount": 0
+  },
+  "msg": ""
+}
+```
+
+> 另一典型边界：**多收票**时 unmatchedAmount 为负数。例如 billAmount=10000、matchedAmount=12000，则 unmatchedAmount=-2000.00，属于有意返回，请原样展示（负值即「多收票」预警）。
+
+### 8.3 业务失败 —— 登记发票挂「草稿态」应付单触发 599412
+
+请求：
+
+    POST /admin/finance/invoice-in/create
+    Content-Type: application/json
+
+    {
+      "invoiceNo": "INV-2026-092201",
+      "invoiceType": "SPECIAL",
+      "supplierId": 1877665544332211,
+      "invoiceAmount": 5000.00,
+      "invoiceDate": "2026-09-20",
+      "receiveDate": "2026-09-22",
+      "relations": [
+        { "bizType": "PAYMENT", "bizId": 1982736450000001, "matchAmount": 5000.00 }
+      ]
+    }
+
+（该应付单状态为 PENDING 草稿）响应：
+
+```json
+{
+  "code": 599412,
+  "data": null,
+  "msg": "关联业务单据未生效（应付/预付须已批准或已付讫才可收票）"
+}
+```
+
+整单拒绝，发票不落库。update 链路表现相同。
+
+## 九、业务边界
+
+**适用场景**
+- 收票对账页：从供应商对账行 / 单据行下钻，看单张应付/预付/费用报销单的收票进度（biz-recon）
+- 登记/编辑发票：挂已批准或已付讫的应付/预付单、任意状态的费用报销单
+
+**不适用场景**
+- biz-recon 是**单查**接口（一次一单），不是分页列表，不要拿它批量刷数
+- EXPENSE 费用报销无供应商锚点，不进供应商维度对账（supplier-recon 只覆盖应付/预付）；biz-recon 支持查 EXPENSE 仅用于展示
+- 非生效态应付/预付单**不可**作为挂票对象（本次收紧点），「先挂票后补批」的流程不再可行
+
+**特殊边界**
+- 通过「可关联业务单据候选」接口（GET /admin/finance/invoice-in/biz-candidates）勾选的链路**天然不触发 599412**——候选接口本来就只返回 APPROVED/PAID 生效单，与本次门槛口径一致。只有手填 bizId、直调接口、或编辑「存量挂草稿单」的发票时才可能撞上 599412
+- 作废（VOIDED）发票自动释放其匹配额，释放后 biz-recon 的各匹配额即时下降，无需前端额外刷新逻辑（重新调接口即可）
+
+## 十、修改前后对比
+
+| 维度 | 修改前 | 修改后 |
+|------|--------|--------|
+| create/update 挂 PAYMENT/PREPAY | 只验「单据存在 + 归属本供应商」，草稿/审批中/已驳回单**均可**挂票成功 | 额外验状态：非 APPROVED/PAID → 整单拒绝，报 **599412** |
+| create/update 挂 EXPENSE | 只验存在 | **不变**，仍只验存在 |
+| update 存量数据 | 编辑时关联全删重插，旧校验不拦非生效单 | 编辑一张「存量挂草稿单」的发票时，重插校验触发 599412，需先移除失效关联才能保存 |
+| 单据维度对账 | 无接口（只有供应商维度 supplier-recon） | 新增 GET /admin/finance/invoice-in/biz-recon |
+| 入参/出参字段结构 | — | **零变化**（无字段增删改名；仅新增 biz-recon 接口与 599412 错误码） |
+
+## 十一、影响评估 / 回滚
+
+**是否破坏兼容**：行为级破坏（窄面）。原先「挂非生效态应付/预付单」能成功的请求现在报 599412 失败；接口签名、字段、其余错误码均不变。
+
+**前端需要同步上线吗**：不需要强同步，但建议排查：
+- 若登记/编辑弹窗的关联单来源**全部**走 biz-candidates 候选勾选 → 零改动，不会触发 599412
+- 若存在**手填 bizId / 直调接口 / 复制历史发票**等绕过候选的入口 → 需要把 599412 纳入错误提示（文案可直接用 msg），并引导用户先完成单据审批
+- 若有「多收票」展示位置 → 注意 unmatchedAmount 可为负，不要做 max(0, x) 截断
+
+**回滚方案**：后端回滚本 PR 即恢复旧行为（不验状态、biz-recon 404）；无 DDL、无 Nacos 配置变更，前端无需配合回滚。存量已挂非生效单的关联行**不会被追溯清理**，仍正常计入匹配额。
+
+## 十二、注意事项
+
+1. **两个对账接口是「有意的不同口径」，不要互相对数**：
+   - biz-recon 的 matchedAmount = **Σ match_amount（关联行口径）**，计 VERIFIED + RECEIVED 两档发票对该单的匹配金额之和
+   - supplier-recon 的 receivedAmount = **Σ invoice_amount（整票口径）**，仅计 VERIFIED 发票的整票价税合计
+   - 一张 RECEIVED 未核对的票：在 biz-recon 里计入 matchedReceivedAmount，在 supplier-recon 里**不计**；一张票只部分匹配某单时：biz-recon 计 match_amount 部分，supplier-recon 核对后计整票 invoice_amount。两者天然不等，matchedVerifiedAmount / matchedReceivedAmount 拆两档正是为解释这个差异。前端不要把两个接口的金额互相核对相等，也不要混用字段名
+2. bizId / supplierId 是 **JSON 字符串**（Long 经 ToStringSerializer 序列化，防 JS 精度丢失）；matchedInvoiceCount 是普通 JSON number
+3. bizTypeName / billStatusName 由后端返回中文，直接展示，**不要**再在前端维护硬编码 map
+4. EXPENSE 单的 supplierId / supplierName 恒为 null，展示时注意空值兜底
+5. biz-recon 对非法 bizType、不存在的 bizId 统一报 599407，不区分「类型错」与「单不存在」
+
+## 十三、关联 / 联系人
+
+- **Issue**: [#8161 收票核销硬钩稽](https://git.1814.love:8443/wx/HL/issues/8161)
+- **PR**: [#8163 feat(finance): 收票核销硬钩稽 PR-1——挂票生效态门槛 + 单据维度对账下钻接口](https://git.1814.love:8443/wx/HL/pulls/8163)
+- **Commit**: [90739708e5](https://git.1814.love:8443/wx/HL/commit/90739708e5b7c5630233c3a3cf72645d6c0c9a5c)
+- **设计文档（后端内部）**: 收票核销硬钩稽设计（PR-1 挂票门槛 + biz-recon 下钻；PR-2 钱变票钩子后续另行推送）
+- **后端负责人**: 腰苏图（yst）
@@ -0,0 +1,261 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8164"
+title: "收票核销硬钩稽 PR-2——钱侧防御钩子：应付/预付编辑改价超额（599413）+ 删除/驳回有票关联（599414）硬拦"
+consumer: "admin"
+author: "yst(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "pending"
+frontend_status: "not_required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "收票（进项发票）域钱侧防御钩子上线：应付/预付的编辑草稿、删除草稿、驳回六个既有接口新增服务端硬校验——编辑改价后金额低于该单已被有效票匹配的金额报 599413；删除/驳回存在非作废收票关联的单据报 599414。无新接口、入参/出参字段零变化，仅行为收紧 + 新增两个错误码。已合并 dev-v3（PR #8165，merge commit c4a1f1fb69）并部署测试服、行为级验证通过。匹配额口径 = Σ fin_invoice_in_rel.match_amount（剔 VOIDED 作废票），作废票后匹配额自动释放、单据恢复可删改；无票或票已作废的单据不受影响。 前端核验(2026-09-22):应付 PaymentDetailPanel 驳回/编辑/删除与预付 advance/index 编辑/删除/驳回六处调用点 catch 全走 request.js 拦截器透 message,无按码分支、无文案重写,599413/599414 的 msg 引导动作自动覆盖,前端行为零改动判 not_required;payable.js/prepay.js 头注顺手补 599412-599414 口径(注释修正 590c1155)。"
+updated_at: "2026-09-22"
+base: "dev-v3"
+---
+
+# 收票核销硬钩稽 PR-2：钱侧防御钩子（599413 / 599414）（管理后台）
+
+> **服务**: hl-order-service-v3（hl-finance 模块，端口 8086/8186）
+> **PR**: #8165
+> **Issue**: #8164
+> **日期**: 2026-09-22
+> **影响范围**: 管理后台「财务管理 - 应付款管理 / 预付款管理」的**编辑草稿、删除草稿、驳回**操作（共 6 个既有接口）
+
+---
+
+## 一、接口背景
+
+收票核销硬钩稽分两步走：
+
+- **PR-1（#8163，已推）**：票侧门槛——登记/编辑发票挂 PAYMENT/PREPAY 关联单时，单据必须是 APPROVED/PAID 生效态，否则 599412。
+- **PR-2（本次，#8165）**：钱侧防御钩子——反过来守「单据侧」：一张**已经被发票匹配过**的应付/预付单，不允许通过编辑把金额改到已匹配票额之下，也不允许直接删除/驳回，否则会出现「钱变了/钱没了，票还挂在上面」的票-款不符，对账口径失真。
+
+PR-1 生效后正常路径下新票只能挂生效单，本组钩子主要拦**存量脏数据**（PR-1 之前挂上的草稿/审批中单据关联）与**冲抵重算实付额**（Epic #8127 改草稿冲抵明细会重算 actualPayAmount）两类接缝场景。涉票一律 fail-fast 硬拦，不放行。
+
+**无新接口、无字段增删改名、出参结构零变化**，只有 2 个新错误码 + 6 个既有接口的行为收紧。
+
+## 二、变更清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 |
+|---|------|------|------|----------|
+| 1 | 编辑应付款草稿 | PUT | /admin/finance/payments/{id} | 行为收紧：改后实付额 < 已匹配票额 → 599413 |
+| 2 | 删除应付款草稿 | DELETE | /admin/finance/payments/{id} | 行为收紧：存在非作废收票关联 → 599414 |
+| 3 | 驳回应付款 | PUT | /admin/finance/payments/{id}/reject | 行为收紧：存在非作废收票关联 → 599414 |
+| 4 | 编辑预付款草稿 | PUT | /admin/finance/prepays/{id} | 行为收紧：改后预付额 < 已匹配票额 → 599413 |
+| 5 | 删除预付款草稿 | DELETE | /admin/finance/prepays/{id} | 行为收紧：存在非作废收票关联 → 599414 |
+| 6 | 驳回预付款 | PUT | /admin/finance/prepays/{id}/reject | 行为收紧：存在非作废收票关联 → 599414 |
+
+> 注意预付路径前缀是 **/admin/finance/prepays**（复数），与应付 /payments 一致。
+
+## 三、接口详情
+
+| 接口 | 使用场景 | 认证 | 幂等性 | 限流 |
+|------|----------|------|--------|------|
+| PUT /admin/finance/payments/{id} | 应付草稿（PENDING）编辑改价/改明细，含冲抵明细整体置换 | 管理后台 JWT | 非幂等（同内容重复提交幂等） | 网关默认 |
+| DELETE /admin/finance/payments/{id} | 删除应付草稿（PENDING，软删） | 管理后台 JWT | 重复删除报单据不存在 | 网关默认 |
+| PUT /admin/finance/payments/{id}/reject | 驳回审批中（SUBMITTED）应付单 | 管理后台 JWT | 非幂等（重复驳回报状态非法） | 网关默认 |
+| PUT /admin/finance/prepays/{id} | 预付草稿（PENDING）编辑改价 | 管理后台 JWT | 非幂等 | 网关默认 |
+| DELETE /admin/finance/prepays/{id} | 删除预付草稿（PENDING，软删） | 管理后台 JWT | 重复删除报单据不存在 | 网关默认 |
+| PUT /admin/finance/prepays/{id}/reject | 驳回审批中（SUBMITTED）预付单 | 管理后台 JWT | 非幂等 | 网关默认 |
+
+## 四、接口入参
+
+入参结构**零变化**，仅服务端校验规则收紧。为自包含列关键字段：
+
+### 4.1 PUT /admin/finance/payments/{id}（PaymentUpdateReqVO，不变）
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| supplierId | Long | 是 | 供应商 ID |
+| payeeAccountId | Long | 是 | 收款账户 ID |
+| amount | BigDecimal | 是 | 付款金额（>0）。**新校验**：冲抵重算后的实付额（actualPayAmount = amount − Σ冲抵金额）不得低于该单已匹配票额，否则 599413 |
+| paymentType | String | 是 | 付款类型（fin_payment_type 字典标签，≤32） |
+| reason | String | 是 | 付款事由（≤512） |
+| teamNo | String | 否 | 团号（≤32） |
+| orderId | Long | 否 | 关联订单 ID |
+| resourceId | Long | 否 | 关联资源 ID |
+| prepayOffsets | Array | 否 | 冲抵预付款明细（可空=不冲抵；整体置换语义） |
+
+### 4.2 PUT /admin/finance/prepays/{id}（PrepayUpdateReqVO，不变）
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| supplierId | Long | 是 | 付款单位供应商 ID |
+| offsetSupplierId | Long | 否 | 冲抵单位供应商 ID（默认=付款单位） |
+| amount | BigDecimal | 是 | 预付金额（>0，整数≤13位、小数≤2位）。**新校验**：不得低于该单已匹配票额，否则 599413 |
+| availableAmount | BigDecimal | 否 | 可冲抵金额（0 ≤ x ≤ amount） |
+| payDate | LocalDate | 是 | 付款日期 |
+| remark | String | 否 | 备注（≤512） |
+
+### 4.3 DELETE / reject 四个接口
+
+- DELETE /admin/finance/payments/{id}、DELETE /admin/finance/prepays/{id}：仅路径参数 id（Long），无请求体
+- PUT /admin/finance/payments/{id}/reject、PUT /admin/finance/prepays/{id}/reject：路径参数 id + 请求体 { "reason": "驳回原因" }（不变）
+
+## 五、出参字段
+
+六个接口出参**零变化**：成功统一返回 Result&lt;Void&gt;（{ "code": 0, "data": null, "msg": "" }）；失败走统一错误响应（{ "code": 错误码, "data": null, "msg": "错误消息" }）。
+
+## 六、枚举 / 数据字典
+
+### 6.1 单据状态（本次校验的前提，应付/预付一致）
+
+| 值 | 中文名 | 可编辑/删除 | 可驳回 |
+|----|--------|------------|--------|
+| PENDING | 草稿 | 是（受 599413/599414 约束） | 否 |
+| SUBMITTED | 审批中 | 否 | 是（受 599414 约束） |
+| APPROVED | 已批准 | 否 | 否 |
+| REJECTED | 已驳回 | 否 | 否 |
+| PAID | 已付讫 | 否 | 否 |
+
+### 6.2 发票状态（匹配额口径依据，本次无新增值）
+
+| 值 | 中文名 | 是否计入匹配额 |
+|----|--------|---------------|
+| RECEIVED | 已收票 | 计入 |
+| VERIFIED | 已核对 | 计入 |
+| VOIDED | 已作废 | **不计入**（作废自动释放匹配额，单据恢复可删改） |
+
+## 七、错误码
+
+| 错误码 | 常量 | 消息 | 触发场景 |
+|--------|------|------|----------|
+| **599413** | INVOICE_IN_MATCH_OVER_BIZ | 收票匹配额超过单据金额（须先作废或改票） | **本次新增**。编辑应付/预付草稿时，改后金额（应付取冲抵后实付额 actualPayAmount，预付取 amount）低于该单已被有效票（剔 VOIDED）匹配的金额合计，整单回滚 |
+| **599414** | INVOICE_IN_BIZ_HAS_REL | 单据已被收票关联（删除/驳回前须先作废或改票） | **本次新增**。删除草稿 / 驳回单据时，该单存在任何非作废发票的匹配关联，不删单、状态不推进 |
+| 598802 | PAYMENT_STATUS_ILLEGAL | 付款单状态非法 | 应付编辑/删除时非 PENDING、驳回时非 SUBMITTED（既有） |
+| 599002 | PREPAY_STATUS_ILLEGAL / PREPAY_TRANSITION_ILLEGAL | 预付单状态非法 | 预付同上（既有） |
+| 599412 | INVOICE_IN_REL_BIZ_NOT_EFFECTIVE | 关联业务单据未生效（应付/预付须已批准或已付讫才可收票） | 票侧（PR-1）挂票门槛，与本组钩子互为对偶（既有） |
+
+**599413 与 599414 的区别**：413 = 编辑改价场景，「金额不能低于已匹配票额」；414 = 删除/驳回场景，「有票关联的单据不许消失/退出对账」。两个码的引导动作一致：先到收票管理作废相关发票或改票释放匹配额，再回来操作单据。
+
+## 八、示例
+
+### 8.1 典型成功 —— 删除一张无收票关联的应付草稿
+
+请求：
+
+    DELETE /admin/finance/payments/1982736450000042
+
+响应：
+
+```json
+{
+  "code": 0,
+  "data": null,
+  "msg": ""
+}
+```
+
+无收票关联（或关联票已全部作废）的单据删改驳回**不受影响**，行为与本次变更前完全一致。
+
+### 8.2 边界情况 —— 编辑草稿，改后金额**等于**已匹配票额（等额放行）
+
+场景：应付草稿 1982736450000055 已被一张 VERIFIED 发票匹配 8000.00。现将付款金额由 10000.00 改为 8000.00（无冲抵，实付额 = 8000.00）。
+
+请求：
+
+    PUT /admin/finance/payments/1982736450000055
+    Content-Type: application/json
+
+    {
+      "supplierId": 1877665544332211,
+      "payeeAccountId": 1877665544000099,
+      "amount": 8000.00,
+      "paymentType": "GROUP_SETTLE",
+      "reason": "按实结调价",
+      "teamNo": "T20260918-01",
+      "orderId": null,
+      "resourceId": null,
+      "prepayOffsets": []
+    }
+
+响应（已匹配 8000.00 ≤ 新实付 8000.00，放行）：
+
+```json
+{
+  "code": 0,
+  "data": null,
+  "msg": ""
+}
+```
+
+等额放行是有意设计：matched > newAmount 才拦，matched = newAmount 视为票-款刚好持平。预付编辑（PUT /admin/finance/prepays/{id}）同理，比较口径为 amount。
+
+### 8.3 业务失败 —— 编辑草稿把金额改到已匹配票额之下，触发 599413
+
+同 8.2 的单据，若改为 5000.00（低于已匹配 8000.00）：
+
+```json
+{
+  "code": 599413,
+  "data": null,
+  "msg": "收票匹配额超过单据金额（须先作废或改票）"
+}
+```
+
+整单不落库、事务整体回滚。再给一个 599414 示例——删除一张已被发票匹配的应付草稿：
+
+    DELETE /admin/finance/payments/1982736450000055
+
+```json
+{
+  "code": 599414,
+  "data": null,
+  "msg": "单据已被收票关联（删除/驳回前须先作废或改票）"
+}
+```
+
+驳回链路（PUT /admin/finance/payments/{id}/reject、PUT /admin/finance/prepays/{id}/reject，请求体 { "reason": "..." }）命中有效票关联时同样返回 599414，状态不推进、不落审核流水。
+
+## 九、业务边界
+
+**适用场景**
+- 应付/预付草稿的正常编辑、删除；SUBMITTED 单的驳回——只要无有效收票关联，行为与之前完全一致
+
+**不适用场景（会被新钩子拦截）**
+- 把单据金额改到「已被有效票匹配的金额」之下（599413）
+- 删除 / 驳回仍挂着有效票（RECEIVED/VERIFIED）匹配的单据（599414）
+
+**特殊边界**
+- **匹配额口径**：Σ fin_invoice_in_rel.match_amount，只计有效票（发票非 VOIDED 且未软删）；作废（VOIDED）发票后匹配额自动释放，单据即时恢复可删改，无需额外操作
+- **EXPENSE 费用报销单不挂本守卫**（无供应商锚点、不进对账），其编辑/删除/驳回行为不变
+- 正常路径下 PR-1 的 599412 门槛已要求 APPROVED/PAID 才可挂票，而生效单本就不可编辑/删除/驳回，故本组钩子**主要拦存量脏数据**（PR-1 之前挂到非生效单上的关联）与冲抵重算接缝
+- 守卫与单据写操作同事务：守卫抛出即整单回滚，不会出现「单改了但校验没过」的中间态
+
+## 十、修改前后对比
+
+| 维度 | 修改前 | 修改后 |
+|------|--------|--------|
+| 编辑应付/预付草稿改价 | 只验状态（PENDING）+ 金额合法，可改到任意值 | 额外验：改后金额 ≥ 已匹配票额，否则 **599413** 整单回滚 |
+| 删除应付/预付草稿 | 只验状态（PENDING），软删即走 | 额外验：无非作废收票关联，否则 **599414** 不删单 |
+| 驳回应付/预付 | 只验状态（SUBMITTED） | 额外验：无非作废收票关联，否则 **599414** 状态不推进 |
+| 入参/出参字段结构 | — | **零变化**（无字段增删改名，仅新增 2 个错误码 + 6 接口行为收紧） |
+| 无票 / 票已作废的单据 | 正常删改驳回 | **不变**，照常放行 |
+
+## 十一、影响评估 / 回滚
+
+**是否破坏兼容**：行为级破坏（窄面）。原先「有票关联的草稿可删可改可驳回」的请求现在可能报 599413/599414；接口签名、字段、其余错误码均不变。
+
+**前端需要同步上线吗**：不需要强同步，但建议在应付/预付的**编辑草稿、删除草稿、驳回**三处操作的错误提示里覆盖 599413 / 599414 两个新错误码（文案可直接用 msg）。正常业务流（PR-1 门槛 + 生效单不可删改）下极少触发，主要面向存量脏数据。
+
+**回滚方案**：后端回滚本 PR 即恢复旧行为（不再拦截）；无 DDL、无 Nacos 配置变更，前端无需配合回滚。存量数据不受影响（钩子只拦写操作，不做数据订正）。
+
+## 十二、注意事项
+
+1. **两个新错误码的 msg 已含引导动作**（「须先作废或改票」），前端可直接展示 msg 作为错误提示
+2. 599413 的比较口径：应付取**冲抵后实付额** actualPayAmount（amount − ΣprepayOffsets 冲抵金额），不是表单里的 amount 原值；预付取 amount。编辑应付时若同时改了冲抵明细，触发 599413 的门槛以重算后的实付额为准
+3. 匹配额统计**剔 VOIDED 作废票**：先把挂着的票作废，匹配额立即释放，单据即可正常删改——这是解除拦截的标准动作
+4. EXPENSE 费用报销单不在本守卫范围，报销单操作不会出现这两个错误码
+5. 本组钩子是 fail-fast 硬拦，**不存在 WARN 放行**路径；业务上确需解除拦截时，正确做法是作废/改票释放匹配额
+
+## 十三、关联 / 联系人
+
+- **Issue**: [#8164 收票核销硬钩稽 PR-2——钱侧防御钩子](https://git.1814.love:8443/wx/HL/issues/8164)
+- **PR**: [#8165 feat(finance): 收票核销硬钩稽 PR-2——InvoiceInRelGuard 钱侧防御钩子 + 应付/预付六处接线](https://git.1814.love:8443/wx/HL/pulls/8165)
+- **Commit**: [c4a1f1fb69](https://git.1814.love:8443/wx/HL/commit/c4a1f1fb691277bfa7590b1db24e6ef7654777e6)
+- **关联前置**: PR-1 [#8163 挂票生效态门槛（599412）+ biz-recon 下钻](https://git.1814.love:8443/wx/HL/pulls/8163)（changelog 已推）
+- **后端负责人**: 腰苏图（yst）
@@ -0,0 +1,369 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8181"
+title: "线下收款废除报账人代收 DRIVER_CASH 渠道（尾款收款模型重构 PR-1）"
+consumer: "admin"
+author: "yst(GIT)"
+change_type: "修改接口"
+backend_status: "merged"
+gateway_status: "not_required"
+frontend_status: "not_required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "backend_status: merged - 已合 dev-v3（PR #8183，merge commit a1fb7bc5ef），未部署测试服; gateway_status: not_required - 零网关改动，/v3/admin/order/** 走 hl-gateway 既有通配路由; frontend_status: pending - 前端适配情况未知，需排查 options 消费方是否硬编码 DRIVER_CASH 前端核验(2026-09-22):渠道 radio 由 options.channels 数据驱动渲染(channelText 优先 CHANNEL_LABELS 兜底),无「必有 DRIVER_CASH」硬编码假设,下线自动生效;历史行渲染映射 CHANNEL_LABELS.DRIVER_CASH 按 ⑫-2 明示保留;520417 由 request.js 拦截器透 message(msg 即操作指引);表单 DRIVER_CASH 分支成惰性保留防回滚。行为零改动判 not_required;orderV2.js JSDoc 与映射注释订正(412d7408)。"
+updated_at: "2026-09-22"
+base: "dev-v3"
+---
+
+# 线下收款废除「报账人代收 DRIVER_CASH」渠道（尾款收款模型重构 PR-1，#8181）
+
+> 订单线下收款登记的「报账人收款（DRIVER_CASH）」渠道下线：登记选项接口不再返回该渠道，登记接口传 DRIVER_CASH 直接报新错误码 520417。历史 DRIVER_CASH 收款记录的查询、撤销不受影响。
+
+## ① 接口背景
+
+此前管理后台给订单补录线下收款时有三个渠道：定制师代收、对公转账、报账人收款（司机/导游等报账人手持现金收尾款）。「报账人代收尾款」模式资金不入公账、对账困难，尾款收款模型重构（Epic #8181）将其废除，改为「确认行程时指定主报账人，尾款挂其代收债务」的新链路（后续 PR 上线）。
+
+本 PR 是该重构的第 1 步：只下线 DRIVER_CASH 的**登记入口**，存量数据完全兼容。
+
+## ② 变更清单
+
+| 类型 | 接口 | 变更 |
+|---|---|---|
+| 修改（出参结构收缩） | `GET /v3/admin/order/{orderId}/payment/manual-receipt/options` | 出参 `channels[]` 从 3 项变 2 项，**移除 DRIVER_CASH 渠道项** |
+| 修改（行为变更 + 新错误码） | `POST /v3/admin/order/{orderId}/payment/manual-receipt` | `channel=DRIVER_CASH` 不再可登记，返回 **520417**（此前可正常登记尾款） |
+| 不变 | `GET /v3/admin/order/{orderId}/payment/manual-receipt` 列表 | 历史 DRIVER_CASH 记录照常返回 |
+| 不变 | `DELETE /v3/admin/order/{orderId}/payment/manual-receipt/{receiptId}` 撤销 | 历史 DRIVER_CASH 记录照常可撤销 |
+
+## ③ 接口详情
+
+### 3.1 查询线下收款登记选项
+
+```
+GET /v3/admin/order/{orderId}/payment/manual-receipt/options
+```
+
+- 使用场景：订单详情「登记线下收款」弹窗打开时拉取，渲染渠道 tabs + 各渠道可选款项/代收人/收款方式
+- 认证：管理后台 JWT（hl-gateway 统一鉴权）
+- 权限：订单归属校验（订单顾问/财务相关角色可读），车务管理员（VEHICLE_MANAGER）可读；房源角色（HOUSE）禁止
+- 幂等性：只读接口，天然幂等
+- 限流：走网关默认限流，无单独配额
+
+### 3.2 登记线下收款
+
+```
+POST /v3/admin/order/{orderId}/payment/manual-receipt
+```
+
+- 使用场景：线下收到款项后补录（对公转账到账、定制师代收款），同事务推进订单 `paid_amount` / `pay_status`
+- 认证：管理后台 JWT
+- 权限：需线下收款写权限（结算写守卫）
+- 幂等性：非幂等，每次成功调用新增一条收款凭据并累加已付金额；**重复提交会重复收款**，前端须防连击
+- 事务：凭据落库与订单已付金额累加在同一事务，不会出现半成功状态
+
+## ④ 入参
+
+### 4.1 选项接口入参
+
+| 参数 | 位置 | 类型 | 必填 | 说明 |
+|---|---|---|---|---|
+| `orderId` | path | Long | 是 | 订单 ID |
+
+无 query / body 参数。
+
+### 4.2 登记接口请求体
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `channel` | string | 是 | 收款渠道：`CONSULTANT_COLLECTION`（定制师代收）/ `BANK_TRANSFER`（对公转账）。⚠️ `DRIVER_CASH` 已下线，传了返回 520417 |
+| `payType` | string | 是 | 款项类型：`DEPOSIT`（订金）/ `BALANCE`（尾款）/ `FULL`（全款） |
+| `amount` | number | 是 | 收款金额，必须 > 0，不能超过当前可收余额 |
+| `receivedAt` | string(datetime) | 否 | 收款时间，可补录过去时间；不传默认当前时间 |
+| `transferRef` | string | 条件必填 | 对公转账流水号，`BANK_TRANSFER` 渠道必填 |
+| `receiptMethod` | string | 否 | 收款方式（字典 `manual_receipt_method`），`BANK_TRANSFER` 为空 |
+| `collectorStaffId` | Long | 否 | 代收人 assignmentId。原为 DRIVER_CASH 必填，该渠道下线后登记链路不再使用 |
+| `collectorType` | string | 否 | 实际代收人类型 `ORDER_STAFF`/`CONSULTANT`/`COMPANY_ACCOUNT`；不传按 channel 兼容推导 |
+| `voucherUrls` | string[] | 否 | 凭证图片 URL 列表 |
+| `remark` | string | 否 | 备注，最长 500 字 |
+
+## ⑤ 出参
+
+### 5.1 选项接口出参 `ManualReceiptOptionsVO`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `channels` | array | 收款渠道选项。**本次变更后固定 2 项：`CONSULTANT_COLLECTION`、`BANK_TRANSFER`**（顺序即此顺序） |
+
+`channels[]` 元素 `ChannelOption`：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `channel` | string | 渠道值 |
+| `channelText` | string | 渠道显示文案（「定制师代收」/「对公转账」） |
+| `allowedPayTypes` | string[] | 当前订单状态下允许的款项类型，空数组 = 该渠道不可用 |
+| `disabled` | boolean | 是否禁用，true 时前端置灰 |
+| `disabledReason` | string | 禁用原因，`disabled=true` 时有值 |
+| `collectors` | array | 该渠道可选代收人（见下表）；`BANK_TRANSFER` 恒为空 |
+| `receiptMethods` | array | 该渠道可选收款方式（见下表）；`BANK_TRANSFER` 恒为空 |
+
+`collectors[]` 元素 `CollectorOption`：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `collectorType` | string | `ORDER_STAFF` / `CONSULTANT` / `COMPANY_ACCOUNT` |
+| `collectorId` | Long(string) | 代收人 ID：`CONSULTANT` 为 adminId |
+| `collectorName` | string | 代收人姓名 |
+| `collectorRole` | string | 代收人角色 |
+| `collectorRoleText` | string | 角色显示文案 |
+| `defaultSelected` | boolean | 是否默认选中 |
+
+`receiptMethods[]` 元素 `OptionItem`：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `value` | string | 选项值（字典 `manual_receipt_method`） |
+| `label` | string | 显示文案 |
+| `defaultSelected` | boolean | 是否默认选中（首项为 true） |
+
+### 5.2 登记接口出参 `ManualReceiptVO`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `id` | Long(string) | 收款凭据 ID（雪花，String 防 JS 精度丢失） |
+| `orderId` | Long(string) | 订单 ID |
+| `channel` | string | 收款渠道值 |
+| `channelLabel` | string | 渠道显示标签 |
+| `payType` | string | 款项类型值 |
+| `payTypeLabel` | string | 款项类型显示标签 |
+| `amount` | number | 收款金额 |
+| `receivedAt` | string(datetime) | 收款时间 |
+| `collectorStaffId` | Long(string) | 代收人 assignmentId（历史 DRIVER_CASH 行才有值） |
+| `collectorStaffName` | string | 代收人姓名（历史 DRIVER_CASH 行才有值） |
+| `collectorType` | string | 实际代收人类型 |
+| `collectorAdminId` | Long(string) | 定制师/管理员代收人 ID |
+| `collectorName` | string | 通用代收人姓名快照 |
+| `collectorRole` | string | 通用代收人角色快照 |
+| `transferRef` | string | 对公转账流水号（BANK_TRANSFER） |
+| `receiptMethod` | string | 收款方式值 |
+| `receiptMethodLabel` | string | 收款方式显示标签 |
+| `voucherUrls` | string[] | 凭证图片 URL 列表 |
+| `remark` | string | 备注 |
+| `operatorName` | string | 登记人姓名 |
+| `createTime` | string(datetime) | 登记时间 |
+| `voided` | boolean | 是否已撤销 |
+| `voidedByName` | string | 撤销人姓名 |
+| `voidedAt` | string(datetime) | 撤销时间 |
+| `voidReason` | string | 撤销原因 |
+| `paidAmountAfter` | number | 登记/撤销后订单累计已付金额（仅登记/撤销响应有值，列表查询为 null） |
+| `payStatusAfter` | string | 登记/撤销后订单支付状态（同上） |
+
+## ⑥ 枚举 / 数据字典
+
+**收款渠道 `channel`**：
+
+| 值 | 含义 | 本次变化 |
+|---|---|---|
+| `CONSULTANT_COLLECTION` | 定制师代收 | 不变 |
+| `BANK_TRANSFER` | 对公转账 | 不变 |
+| `DRIVER_CASH` | 报账人收款 | **已下线**：options 不再返回、register 拒绝（520417）。⚠️ 但列表接口的历史数据仍可能出现该值（channelLabel=「报账人收款」），渲染映射不能删 |
+
+**款项类型 `payType`**：`DEPOSIT` 订金 / `BALANCE` 尾款 / `FULL` 全款（不变）。
+
+**代收人类型 `collectorType`**：`ORDER_STAFF` / `CONSULTANT` / `COMPANY_ACCOUNT`（不变）。
+
+**收款方式 `receiptMethod`**：走数据字典 `manual_receipt_method`（如 `WECHAT_TRANSFER` 微信转账、`CASH` 现金收款），以 options 接口实际返回为准。
+
+## ⑦ 错误码
+
+| 码 | 语义 | 触发场景 |
+|---|---|---|
+| **520417** | 报账人代收尾款已下线，请通过确认行程挂账主报账人代收 | **本次新增**：register 传 `channel=DRIVER_CASH` |
+| 520401 | 收款渠道非法: {0} | register 传了枚举外的渠道值 |
+| 520402 | 对公转账渠道必须填写转账流水号 | BANK_TRANSFER 缺 `transferRef` |
+| 520407 | 订单已取消，不允许登记线下收款 | 订单状态 CANCELLED |
+| 520412 | 订单没有可用定制师，不能登记定制师代收 | CONSULTANT_COLLECTION 但订单无定制师 |
+| 520413 | 本次收款金额超过当前可收余额 | 金额超可收余额 |
+| 520415 | 收款方式不能为空 | 渠道要求 receiptMethod 但未传 |
+| 520416 | 收款方式非法: {0} | receiptMethod 不在字典内 |
+| 520405 | 线下收款凭据不存在 | 撤销时 receiptId 无效或不属本单 |
+| 520406 | 该收款凭据已撤销，无法重复操作 | 重复撤销 |
+| 520414 | 当前订单状态禁止撤销收款 | 当前订单/流程状态不允许撤销 |
+
+> 注：原 DRIVER_CASH 专属错误码 520403（缺代收人）/ 520404（代收人不属本单）/ 520410（只能登尾款）/ 520411（必须选报账人）因入口下线在 register 链路不再可达，前端无需再处理这几个码（保留兼容无害）。
+
+## ⑧ 示例
+
+### 8.1 典型：options 返回 2 个渠道 + BANK_TRANSFER 登记成功
+
+请求 `GET /v3/admin/order/2100123456789012345/payment/manual-receipt/options`（订单状态非待支付、尾款未收齐）：
+
+```json
+{
+  "code": 200,
+  "success": true,
+  "data": {
+    "channels": [
+      {
+        "channel": "CONSULTANT_COLLECTION",
+        "channelText": "定制师代收",
+        "allowedPayTypes": ["BALANCE"],
+        "disabled": false,
+        "disabledReason": null,
+        "collectors": [
+          {
+            "collectorType": "CONSULTANT",
+            "collectorId": "2090001111222233334",
+            "collectorName": "王定制",
+            "collectorRole": "CONSULTANT",
+            "collectorRoleText": "定制师",
+            "defaultSelected": true
+          }
+        ],
+        "receiptMethods": [
+          { "value": "WECHAT_TRANSFER", "label": "微信转账", "defaultSelected": true },
+          { "value": "CASH", "label": "现金收款", "defaultSelected": false }
+        ]
+      },
+      {
+        "channel": "BANK_TRANSFER",
+        "channelText": "对公转账",
+        "allowedPayTypes": ["BALANCE"],
+        "disabled": false,
+        "disabledReason": null,
+        "collectors": [],
+        "receiptMethods": []
+      }
+    ]
+  }
+}
+```
+
+请求 `POST /v3/admin/order/2100123456789012345/payment/manual-receipt`：
+
+```json
+{
+  "channel": "BANK_TRANSFER",
+  "payType": "BALANCE",
+  "amount": 3000.00,
+  "transferRef": "GZL20260922001",
+  "remark": "客户对公转账尾款"
+}
+```
+
+响应：
+
+```json
+{
+  "code": 200,
+  "success": true,
+  "data": {
+    "id": "2102999888777666555",
+    "orderId": "2100123456789012345",
+    "channel": "BANK_TRANSFER",
+    "channelLabel": "对公转账",
+    "payType": "BALANCE",
+    "payTypeLabel": "尾款",
+    "amount": 3000.00,
+    "receivedAt": "2026-09-22T17:00:00",
+    "transferRef": "GZL20260922001",
+    "collectorType": "COMPANY_ACCOUNT",
+    "voided": false,
+    "paidAmountAfter": 8800.00,
+    "payStatusAfter": "FULLY_PAID"
+  }
+}
+```
+
+### 8.2 边界：订单无定制师 → 定制师代收渠道置灰
+
+订单无定制师快照时，`CONSULTANT_COLLECTION` 渠道 `collectors` 为空且禁用：
+
+```json
+{
+  "channel": "CONSULTANT_COLLECTION",
+  "channelText": "定制师代收",
+  "allowedPayTypes": [],
+  "disabled": true,
+  "disabledReason": "订单没有可用定制师",
+  "collectors": [],
+  "receiptMethods": [
+    { "value": "WECHAT_TRANSFER", "label": "微信转账", "defaultSelected": true },
+    { "value": "CASH", "label": "现金收款", "defaultSelected": false }
+  ]
+}
+```
+
+尾款已收齐时各渠道 `allowedPayTypes=[]`、`disabled=true`、`disabledReason="尾款已收齐，无可收余额"`；订单已取消时 `disabledReason="订单已取消，不能登记收款"`。
+
+### 8.3 业务失败：DRIVER_CASH 登记被拒（520417）
+
+请求：
+
+```json
+{
+  "channel": "DRIVER_CASH",
+  "payType": "BALANCE",
+  "amount": 2000.00,
+  "collectorStaffId": "2099888777666555444",
+  "receiptMethod": "CASH"
+}
+```
+
+响应：
+
+```json
+{
+  "code": 520417,
+  "success": false,
+  "message": "报账人代收尾款已下线，请通过确认行程挂账主报账人代收"
+}
+```
+
+不会落库任何收款记录，订单金额无变化。
+
+## ⑨ 业务边界
+
+- **适用**：订单收到线下款项后补录（订金/全款仅限待支付状态，尾款在非待支付、非已取消状态）；定制师代收、对公转账两种渠道照常可用。
+- **不适用**：报账人（司机/导游）手持现金收尾款的场景——此入口已废除，改走「确认行程挂账主报账人代收」链路（后续 PR 上线，前端关注后续 changelog）。
+- **存量兼容**：历史已登记的 DRIVER_CASH 收款记录正常返回在列表接口、正常可撤销，撤销后 `paid_amount` 精确回退，行为与旧版一致。
+- **可收余额**：`amount` 不能超过订单当前可收余额（520413）；可收余额 ≤ 0 时各渠道 `allowedPayTypes` 为空且置灰。
+- **登记接口非幂等**：重复点击会产生重复收款记录，前端须做按钮防重。
+
+## ⑩ 修改前后对比
+
+### 字段/结构级
+
+| 项 | 修改前 | 修改后 |
+|---|---|---|
+| options 出参 `channels[]` | `[CONSULTANT_COLLECTION, BANK_TRANSFER, DRIVER_CASH]`（3 项，DRIVER_CASH 项内含本单报账人候选 collectors） | `[CONSULTANT_COLLECTION, BANK_TRANSFER]`（2 项，**DRIVER_CASH 项整体移除**） |
+| register 入参 `channel=DRIVER_CASH` | 合法值，可登记尾款（仅 BALANCE，需 collectorStaffId 属本单报账人） | 非法值，一律返回 520417，不落库 |
+
+### 行为级
+
+| 项 | 修改前 | 修改后 |
+|---|---|---|
+| 报账人代收尾款登记 | 可在订单详情登记 | 入口下线，需走确认行程挂账主报账人代收（后续 PR） |
+| 历史 DRIVER_CASH 记录查询/撤销 | 可查可撤 | 不变，仍可查可撤 |
+| 订金/全款/尾款的定制师代收、对公转账补录 | 可用 | 不变，照常可用 |
+
+## ⑪ 影响评估 / 回滚
+
+- **破坏兼容**：是。options 出参结构收缩（少一个渠道项）+ register 对 DRIVER_CASH 的行为从成功变为报错。
+- **前端同步上线要求**：前端必须先排查并适配（见 ⑫），否则若按旧 channels 结构硬编码索引/枚举映射，渠道 tabs 渲染或默认值逻辑可能异常；若仍向用户展示 DRIVER_CASH 入口，登记会收到 520417。
+- **后端兼容**：已合 dev-v3，未部署测试服；列表/撤销接口对历史数据完全兼容。
+- **回滚方案**：代码回滚至本 PR 前版本即恢复 DRIVER_CASH 渠道；下线期间不会产生新 DRIVER_CASH 数据，回滚无数据迁移负担。
+
+## ⑫ 注意事项
+
+1. **前端排查 options 消费方是否硬编码 DRIVER_CASH**：检查渠道 tabs 渲染、渠道枚举映射、默认渠道选中逻辑、channel 文案映射表（`DRIVER_CASH → 报账人收款`）等位置。options 不再返回该渠道，任何按「必有 3 项 / 必有 DRIVER_CASH」假设的代码都要清理。
+2. **列表接口渲染映射不能删 DRIVER_CASH**：历史收款记录仍可能返回 `channel=DRIVER_CASH`、`channelLabel=报账人收款`，列表/详情的展示映射需保留该值，否则历史行显示异常。
+3. 新错误码 520417 的 message 可直接透出给用户（文案即操作指引）。
+4. 原 DRIVER_CASH 专属错误码 520403/520404/520410/520411 在 register 链路不再可达，前端可不再处理。
+
+## ⑬ 关联 / 联系人
+
+- Issue：https://git.1814.love:8443/wx/HL/issues/8181
+- PR：https://git.1814.love:8443/wx/HL/pulls/8183
+- Commit：https://git.1814.love:8443/wx/HL/commit/a1fb7bc5ef6befa409696fdba7c1d98b840a7c4a
+- 后端负责人：yst
@@ -0,0 +1,355 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8182"
+title: "通知中心: HOUSE 内部员工站内信 link 由小程序路径订正为管理后台路由，并明确 bizId 不是路由键"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修复"
+backend_status: "deployed"
+gateway_status: "not_required"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "191fdc3cd65d789cce3565f948f2333d3eb58eeb"
+target_release: "v2.1"
+verified_at: "2026-09-22"
+status_note: "本条不改变 AdminMessageRespVO / AdminMessagePageReqVO 的字段结构，只修正 notification_event_config.inapp_link_template 中三个内部员工事件码的路由域（小程序 /pages/* → 管理后台 /housekeeper/*），并在 HouseNotificationPublisher 类注释上固化「(bizType, bizId) 不是路由键」这一约束。gateway_status=not_required：零新增路由，受影响的 GET /admin/message/list 与 GET /admin/message/{id} 是既有端点。frontend_status=pending：本条与 22_8155 不同，它需要前端改动——hl-ui 的 jumpToBiz（origin/v2.1 590c1155，src/views/notification/MyMessages/index.vue:268-286）目前只读 bizId/bizModule/bizType/peerRole，对 HOUSE 核房通知会落进 getOrderReadableRoute(bizId) 分支，把 hotelId 当 orderId 打开订单详情页；正确做法是改读 link 字段（该字段早已存在于 AdminMessageRespVO:31，不是本次新增）。backend_status=deployed：hl-user-service 与 hl-order-service-v3 均已滚动到测试服 776c0023d，Flyway 20260922.210 success=1（installed_on 2026-09-22 17:18:51），并在自建酒店夹具上走完「核房提交 → 站内信产出 → GET /admin/message/list 读回」全链路，实测读数见正文第八节。⚠️ admin_message 是快照表：link 在 createMessage 落库那一刻按当时的模板一次性渲染写入行内，不是按需渲染；因此本修复只影响生效后新产生的消息，测试库里此前已产出的 213 条 HOUSE_INVENTORY_CHECKED 历史消息 link 仍是旧的小程序路径，不做批量回刷——order-v3 / fleet 尚未上生产，不涉及生产数据。 前端已交付(191fdc3c):jumpToBiz 改 link 优先直喂 router.push,/pages/ 旧小程序域与空 query 占位(?inquiryId= 剥 query 降级列表页)兜底;HOUSE 非聊天行无可用 link 不渲染入口不反推 bizId;ORDER(#8155)/HOUSE 聊天行既有推导不回退;判定抽 jumpBiz.js 纯函数+8 例定向 spec。"
+updated_at: "2026-09-22"
+base: "dev-v3"
+---
+
+# 通知中心: HOUSE 内部员工站内信 link 由小程序路径订正为管理后台路由，并明确 bizId 不是路由键
+
+> **存放目录**: 二期（order-v3）→ `changelogs-v2/2026-09/`
+>
+> **服务**: hl-user-service（通知分发 / 站内信收件箱 / 配置表）+ hl-order-service-v3（通知发布方，本次仅注释）
+> **PR**: [#8189](https://git.1814.love:8443/wx/HL/pulls/8189)（迁移 + 注释 + 迁移测试）、[#8190](https://git.1814.love:8443/wx/HL/pulls/8190)（补注释漏枚举）
+> **Issue**: [#8182](https://git.1814.love:8443/wx/HL/issues/8182)
+> **日期**: 2026-09-22
+> **影响范围**: 管理后台站内信中心里 HOUSE 类通知的「跳转」行为
+
+---
+
+## ⚠️ 关键变化
+
+1. **三个内部员工事件码的 `link` 换了路由域**：`HOUSE_INVENTORY_CHECKED` / `HOUSE_INQUIRY_TIMEOUT` / `HOUSE_INQUIRY_ESCALATED` 的 `link` 由小程序路径 `/pages/house/...` 改为管理后台路由 `/housekeeper/calendar` 与 `/housekeeper/todos`。字段名、类型、位置都没变，**变的是值**。
+
+2. **「跳转」必须改读 `link`，不能再从 `(bizType, bizId)` 反推。** 这是本条与 `22_8155` 的关键差别：`22_8155` 的正文写过「前端 `jumpToBiz` 只读 `row.bizId/bizModule/bizType/peerRole`，从不读 `row.link`，无需任何前端代码改动」——**那句话在 `REQUIREMENT_REJECTED` 这一个事件上成立，不能推广到 HOUSE 全域**。`REQUIREMENT_REJECTED` 的 `bizId` 修好之后确实就是 `orderId`，按订单跳是对的；但核房、团期两类事件的 `bizId` **根本不是订单**（见第四节 bizId 三义表），任何「拿 bizId 当订单 id 跳」的写法在它们身上必然打开一个不存在的订单。因此本条的 `frontend_status` 是 `pending`，不是 `not_required`。
+
+3. **`link` 为空、或其路径不在管理后台路由表内时，不要渲染「跳转」入口**。存量历史消息的 `link` 仍是旧的小程序路径，它们在后台是打不开的。
+
+---
+
+## 一、背景
+
+### 缺陷形态
+
+缺陷**不是**「`link` 为空」，而是「`link` 非空、但写的是另一个端的路由」——这两者在「`link` 是否非空」这个判据下完全同形，所以此前没人发现。
+
+```sql
+-- notification_event_config 里 category_code='HOUSE' 的 6 行，inapp_link_template 全部非空
+-- 且全部形如 /pages/house/...（小程序路由）
+
+-- 管理后台路由的权威源里，没有任何一条 /pages/* 路径
+SELECT COUNT(*) FROM sys_menu WHERE path LIKE '/pages/%' AND status='ACTIVE';
+  -> 0
+
+-- 测试库里已产出的 HOUSE 站内信，link 100% 落在小程序路由域
+SELECT IFNULL(event_code,'<NULL>') ec, kind, COUNT(*) cnt,
+       SUM(link IS NULL) null_link, SUM(link LIKE '/pages/%') pages_link
+  FROM admin_message WHERE biz_type='HOUSE' GROUP BY 1,2;
+  -> HOUSE_INVENTORY_CHECKED  NOTIFY  213  0    213
+  -> <NULL>                   CHAT    107  107  NULL
+```
+
+（那 107 行 `link IS NULL` 的是房务 IM 聊天消息，`kind='CHAT'`、`event_code IS NULL`，不经通知中心分发，本就不该有 `link`，与本缺陷无关。）
+
+### 触发路径
+
+管理后台 → 消息中心 → 一条「核房记录已更新」通知 → 操作列「更多」→「跳转」。
+
+前端侧当前实现（hl-ui `origin/v2.1` @ `590c1155`，只读查证、未改动）：
+
+- `src/views/notification/MyMessages/index.vue:477` — `if (row.bizId) more.push({ text: '跳转', ... onClick: jumpToBiz })`，**只要 `bizId` 非空就渲染「跳转」**，NOTIFY 行同样渲染。
+- `src/views/notification/MyMessages/index.vue:268-286` — `jumpToBiz(row)` 依次判断 `mod === 'FLEET'` → 车务看板；`peer === 'CUSTOMIZER' && (mod === 'HOUSE' || mod === 'HOUSE_LEAD')` → `/housekeeper/orders?orderId=<bizId>`；**否则 → `getOrderReadableRoute(bizId, userStore)`**。
+- `src/utils/orderAccess.js:48-54` — `getOrderReadableRoute` 对受限房务角色返回 `/housekeeper/orders?orderId=<bizId>`，其余返回 `/order-v2/detail/<bizId>`。
+
+核房通知是 `kind='NOTIFY'`、没有 `peerRole`，于是落进最后那个 `else` 分支 ⇒ 用 **hotelId** 去打开 `/order-v2/detail/<hotelId>`。雪花 ID 形态一致，页面不会报「参数非法」，只会报「订单不存在」或空白——**失败是静默的**。
+
+### 数据落地路径（已核实的完整链路）
+
+| 环节 | 位置 |
+|---|---|
+| 业务入口 | `POST /v3/admin/house/hotels/{hotelId}/check-log` — `HouseHotelAdminController.java:63-70` |
+| 组装 extras | `HouseInventoryCheckService.java:153-164`，放入 `hotelId` / `checkDate` / `roomTypeCount` / `operatorId` / `operatorName` / `hotelName` |
+| 发布事件 | `HouseNotificationPublisher.publishNotificationEvent("HOUSE_INVENTORY_CHECKED", hotelId, notifyExtras)` — `HouseNotificationPublisher.java:111-139`，**bizId 实参就是 hotelId** |
+| MQ | `HL_NOTIFICATION_EVENT_TOPIC` → `NotificationEventConsumer` |
+| 渲染 link | `NotificationDispatcher` 按 `notification_event_config.inapp_link_template` 用 extras 渲染占位符 |
+| 落库 | `admin_message`（快照表，`link` 与 `biz_id` 在 `createMessage` 那一刻写死在行内） |
+| 读回 | `GET /admin/message/list` — `AdminMessageController.java:44-50` |
+
+---
+
+## 二、变更接口清单
+
+| 方法 | 路径 | 变更类型 | 说明 |
+|---|---|---|---|
+| GET | `/admin/message/list` | 出参**取值**变化 | `link` 字段的值域由 `/pages/house/*` 改为 `/housekeeper/*`；字段结构不变 |
+| GET | `/admin/message/{id}` | 出参**取值**变化 | 同上 |
+
+**没有**新增 / 删除 / 改名任何字段，也没有新增任何路由。
+
+---
+
+## 三、接口详情
+
+### 1. 站内信分页列表 `GET /admin/message/list`
+
+**使用场景**：管理后台消息中心列表。本条只影响其中 `bizType='HOUSE'` 且 `kind='NOTIFY'` 的行。
+
+**入参**：无变化。
+
+**出参**：`AdminMessageRespVO` 结构无变化。与本条相关的字段：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `messageId` | String | 消息 ID（雪花，字符串透传） |
+| `categoryCode` | String | **`SYSTEM`**，不是 `HOUSE`——见第六节「边界行为」第 1 条 |
+| `title` | String | 如「核房记录已更新」 |
+| `link` | String | **跳转目标。本条改的就是它。** 字段早已存在（`AdminMessageRespVO.java:31`），不是本次新增 |
+| `bizId` | String | 关联业务 ID，**语义随事件码变化，不是路由键**，见第四节 |
+| `bizType` | String | HOUSE 域内恒为 `"HOUSE"` |
+| `kind` | String | `NOTIFY`=系统通知 / `CHAT`=聊天 |
+
+**实测响应片段**（自建夹具，完整取证见第八节）：
+
+```json
+{
+  "messageId": "2102328540089466882",
+  "categoryCode": "SYSTEM",
+  "title": "核房记录已更新",
+  "link": "/housekeeper/calendar?hotelId=2102328465699270657&date=2026-09-23",
+  "bizId": "2102328465699270657",
+  "bizType": "HOUSE",
+  "kind": "NOTIFY"
+}
+```
+
+**错误码**：无新增。
+
+### 2. 站内信详情 `GET /admin/message/{id}`
+
+同上，返回结构与 `link` 取值口径一致。
+
+---
+
+## 四、契约约束与正确调用方式
+
+### 「跳转」的唯一正确来源是 `link`
+
+```js
+// ✅ 正确
+function jumpToBiz(row) {
+  const link = String(row.link ?? '')
+  if (!link || !isKnownAdminRoute(link)) {
+    // 不渲染 / 不跳转，见下方「兜底要求」
+    return
+  }
+  router.push(link)
+}
+
+// ❌ 错误：从 (bizType, bizId) 反推页面
+router.push(`/order-v2/detail/${row.bizId}`)   // bizId 可能是 hotelId / groupBatchId
+```
+
+### `bizId` 三义表（HOUSE 域，截至 #8182 的全部生产调用点）
+
+`bizType` 在 HOUSE 域恒为 `"HOUSE"`，而 `bizId` 承载三种互不相同的业务实体，且三者都是雪花 ID、**单看值分辨不出是哪一类**：
+
+| 事件码 | `bizId` 实际是 | 发布位置 |
+|---|---|---|
+| `HOUSE_HOTEL_SWAPPED_OLD_HOTEL` / `_NEW_HOTEL` / `_CUSTOMER` | **orderId** | `HouseAssignmentService.java:1941/1942/1943` |
+| `GROUP_BATCH_HOUSE_CLAIMED` / `GROUP_BATCH_HOUSE_RELEASED` | **groupBatchId** | `HouseGroupGrabService.java:731` |
+| `GROUP_BATCH_REQUIREMENT_CONFIRMED` | **groupBatchId** | `GroupBatchRequirementService.java:1286` |
+| `HOUSE_INVENTORY_CHECKED` | **hotelId** | `HouseInventoryCheckService.java:164` |
+
+合计 6 条 publish 语句 / 4 个发起方法（换店三条同在一个方法内）。该约束已固化在 `HouseNotificationPublisher` 的类注释里（PR #8189 写入、#8190 补齐漏枚举），新增调用点时要一并维护。
+
+**为什么不把 `bizType` 拆细**：核房是「某酒店某天」的房态盘点，团期抢单是「某个团期班期」的归属变更，它们**在业务上根本没有订单维度**，强行编一个 orderId 只会制造假关联。`bizId` 传各自的真实主键是对的语义，代价就是它不能再兼任路由键。
+
+### 兜底要求
+
+`link` 为空、或 `link` 的路径部分不在管理后台已知路由表内时，**不渲染「跳转」入口**（而不是渲染出来再跳到 404）。理由见第五节：`admin_message` 是快照表，历史行里存着的就是旧路由域的字符串。
+
+### 前端需要知道的取值边界
+
+- `link` 是**相对路径 + query**，不含域名，可直接交给 `router.push`。
+- query 里的 ID 一律按**字符串**处理，禁 `Number()`——雪花 ID 超 `Number.MAX_SAFE_INTEGER`。
+- `${占位}` 取不到值时会被渲染成空串，形如 `?inquiryId=`。把这种情况按「参数缺失」处理，降级为打开列表页即可。
+
+---
+
+## 五、数据库行为
+
+### `notification_event_config`（Flyway `V20260922_210`，hl-user-service）
+
+纯 UPDATE 无 DDL，按 `event_code`（唯一键 `uk_event_code`）定位，可重复执行：
+
+| event_code | 改前 | 改后 |
+|---|---|---|
+| `HOUSE_INVENTORY_CHECKED` | `/pages/house/inventory?hotelId=${hotelId}&date=${checkDate}` | `/housekeeper/calendar?hotelId=${hotelId}&date=${checkDate}` |
+| `HOUSE_INQUIRY_TIMEOUT` | `/pages/house/inquiry?id=${inquiryId}` | `/housekeeper/todos?inquiryId=${inquiryId}` |
+| `HOUSE_INQUIRY_ESCALATED` | `/pages/house/inquiry?id=${inquiryId}` | `/housekeeper/todos?inquiryId=${inquiryId}` |
+
+⚠️ 两条询房事件的 query key 同时由 `id` 改为 `inquiryId`（原值取自种子脚本 `V20260520_002__house_notification_event_config.sql:171`（ESCALATED）与 `:202`（TIMEOUT），逐字核对；且对全部迁移脚本做过穷举——整个 `db/migration` 里出现 `inapp_link_template` 的文件共 8 份，涉及这两个事件码的只有该种子脚本与本单的 `V20260922_210`，中间无第三份改过它们）。这两个事件码目前在 Java 主代码里**没有发布方**（见第六节第 4 条），所以 key 改名当前不产生任何实际调用差异，接上发布方时按 `inquiryId` 读即可。
+
+改与不改的判据是**收件人域**：这三条的收件人（`HOUSE_TEAM` / `INQUIRY_CLAIMER` / `HOUSE_LEAD`）都是内部员工，点开只会落在管理后台；而换酒店三事件的收件人是酒店联系人与 C 端客户，本就不属于后台路由域，**一个字节未动**。
+
+两个目标路由在后台菜单表里都存在：
+
+```sql
+SELECT path, menu_name, status FROM sys_menu WHERE path IN ('/housekeeper/calendar','/housekeeper/todos');
+  -> /housekeeper/calendar   日历视图   ACTIVE
+  -> /housekeeper/todos      待处理     ACTIVE
+```
+
+### `admin_message`（快照表）
+
+`link` 与 `biz_id` 在 `createMessage` 落库那一刻一次性写入行内，**不是按需渲染**。所以：
+
+- 生效后**新产生**的消息，`link` 是新路由；
+- 此前已产出的 **213 条** `HOUSE_INVENTORY_CHECKED` 历史消息，`link` 仍是旧的小程序路径，**不做批量回刷**（order-v3 / fleet 尚未上生产，测试库脏数据不值得回刷，且回刷会掩盖兜底逻辑缺失）。前端按上面的「兜底要求」处理即可。
+
+---
+
+## 六、边界行为
+
+1. **`categoryCode` 是 `SYSTEM` 而不是 `HOUSE`。** 核房通知虽然 `bizType='HOUSE'`，但落库时 `category_code='SYSTEM'`（`AdminMessageRespVO.java:20-22` 的注释即写明「系统通知为 SYSTEM」）。**用 `categoryCode=HOUSE` 过滤会得到 0 条**，这是实测踩到的坑，按 `bizType` 或不过滤来取。
+
+2. **换酒店三事件当前 5 个渠道零产出。** 它们的 `wework_receiver_type`（`OLD_HOTEL_CONTACT` / `NEW_HOTEL_CONTACT` / `ORDER_CUSTOMER`）不在 `NotificationDispatcher.INTERNAL_INAPP_RECEIVER_TYPES`（`NotificationDispatcher.java:100-103`）内 ⇒ 站内信不落 `admin_message`；`HouseNotificationPublisher` 构造消息时不设 `userId` ⇒ C 端 `user_message` 也不落；其余渠道开关均为 0。所以前端在消息中心里**看不到**这三类消息——这是它们自身的既有状态，与本次改动无关。
+
+3. **三个 `GROUP_BATCH_*` 事件码在配置表里没有行。** 实测 `notification_event_config` 全表 62 行，`event_code LIKE 'GROUP%'` 零命中（同一条 SQL 查 `HOUSE_INVENTORY_CHECKED` 可返回，作阳性对照）。`NotificationDispatcher` 查不到 config 只记日志 ⇒ 团期房务抢单 / 释放 / 需求整体确认**一条通知都不产生**，即 `bizId` 三义中的 `groupBatchId` 那一义对任何消费方目前都不可见。已另立单跟进配置补齐。
+
+4. **`HOUSE_LEAD` 不在站内信白名单内。** 所以 `HOUSE_INQUIRY_ESCALATED` 即便将来接上发布方，站内信也不会落 `admin_message`——它缺的是扩白名单，不是改 `link`。本次对它的订正是「把路由域写对」，当前实际效果为零。同理 `HOUSE_INQUIRY_TIMEOUT` / `_ESCALATED` 在 Java 主代码里目前没有发布方。
+
+5. **聊天消息（`kind='CHAT'`）不受影响**：`link` 本就是 `null`，`event_code` 也是 `null`，不经通知中心分发。
+
+---
+
+## 六.5、枚举 / 数据字典
+
+`bizType`（`AdminMessageRespVO.bizType`）HOUSE 域取值恒为 `"HOUSE"`，**不具备区分事件类型的能力**，不要用它做路由分支。事件类型看 `event_code`（列表接口不返回该字段），跳转看 `link`。
+
+`kind`：`NOTIFY`=系统通知（有 `link`）/ `CHAT`=会话消息（`link` 为 `null`）。
+
+---
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 |
+|---|---|---|
+| `AdminMessageRespVO.link`（核房事件） | `/pages/house/inventory?hotelId=...&date=...` | `/housekeeper/calendar?hotelId=...&date=...` |
+| `AdminMessageRespVO.bizId`（核房事件） | hotelId | hotelId（**不变**，本次未动 bizId） |
+| 其余字段 | — | 无变化 |
+
+### 行为级对比
+
+| 场景 | 改前 | 改后 |
+|---|---|---|
+| 后端渲染出的 link 落在哪个路由域 | 小程序（后台不存在该路径） | 管理后台（`sys_menu` 内可查到） |
+| 前端按 `bizId` 反推跳转 | 打开 `/order-v2/detail/<hotelId>`，订单不存在 | **仍然错**——所以前端必须改读 `link` |
+| 前端按 `link` 跳转 | 跳到后台不存在的 `/pages/*` | 正确落到核房日历页 |
+
+⚠️ 这张表的第二行是重点：**只改后端不改前端，「跳转」依然是坏的**。后端这次把 `link` 修对了，把它变成一个可用的跳转来源；真正让用户点对页面的动作在前端侧。
+
+---
+
+## 六.7、影响评估
+
+- **前端是否必须同步上线**：**是**。`jumpToBiz` 需改读 `link` 并补兜底判断，否则核房类通知的「跳转」仍落空。
+- **兼容性**：纯取值变化，老前端不会报错（只是跳转依旧不对），不会因为本条出现新的异常或白屏。
+- **数据**：仅 `notification_event_config` 三行 UPDATE，无 DDL、无数据迁移、无回刷。
+
+---
+
+## 七、不影响范围
+
+- 不影响任何接口的字段结构、必填性、类型。
+- 不影响 C 端小程序站内信：小程序读的是 `user_message`，本次改的三个事件码收件人都是内部员工，不落 `user_message`。
+- 不影响换酒店三事件（`link` 一字节未改）。
+- 不影响聊天消息与会话聚合。
+- 不影响 `bizId` 的取值——本次没有动任何 `bizId` 实参。
+- 不影响 `22_8155` 的 `REQUIREMENT_REJECTED` 结论：那条改的是 `bizId`，本条改的是 `link`，两者互不覆盖。
+
+---
+
+## 八、测试环境已验证
+
+**部署基线**：`hl-user-service` 与 `hl-order-service-v3` 均已滚动到测试服 `776c0023d`（`deploy-status.sh` 读数：两者 `BEHIND=0/N`）。
+
+**Flyway**：
+
+```
+version          success  installed_on
+20260922.210     1        2026-09-22 17:18:51
+```
+
+**自建夹具**（全部自建，未复用他人数据）：
+
+| 项 | 值 |
+|---|---|
+| 自建酒店 | `hotelId=2102328465699270657`（`8182验收自建酒店-1790069137`，`status=0` 下架） |
+| 自建核房记录 | `checkLogId=2102328538344615937`，`checkDate=2026-09-23` |
+| 产生的站内信 | `messageId=2102328540089466882` |
+
+**链路实测**：`POST /v3/admin/house/hotels/2102328465699270657/check-log` → `GET /admin/message/list` 读回该条，`link` 为：
+
+```
+/housekeeper/calendar?hotelId=2102328465699270657&date=2026-09-23
+```
+
+三条断言逐条成立：① 以 `/housekeeper/calendar` 开头；② `hotelId=` 后为自建酒店 ID，逐字相同；③ `date=` 后为自建核房日期 `2026-09-23`，与请求体逐字相同。
+
+**库侧独立复核**（不依赖接口返回）：
+
+```
+id            : 2102328540089466882
+category_code : SYSTEM
+event_code    : HOUSE_INVENTORY_CHECKED
+kind          : NOTIFY
+biz_type      : HOUSE
+biz_id        : 2102328465699270657
+link          : /housekeeper/calendar?hotelId=2102328465699270657&date=2026-09-23
+title         : 核房记录已更新
+```
+
+`biz_id` 与 `link` 里的 `hotelId` 逐字一致 ⇒ 证明 `bizId` 语义未被本次改动影响。
+
+**存量未回刷的对照**：同一次响应里的历史消息 `messageId=2100088394469044226`（迁移执行前产生）`link` 仍为 `/pages/house/inventory?hotelId=...`，与第五节「不回刷」一致。
+
+**迁移单测**：`HouseInappLinkMigrationMysqlTest`（Testcontainers 真 MySQL 8.0.33 跑迁移）`Tests run: 5, Failures: 0, Errors: 0, Skipped: 0`，含阴性对照（换店三事件 `link` 零字节变化）与幂等复跑。
+
+**改前阴性基线**：`SELECT COUNT(*) FROM sys_menu WHERE path LIKE '/pages/%' AND status='ACTIVE'` → `0`，即改动前没有任何一条 HOUSE link 能在后台路由表里查到——这条读数同时说明旧验收口径「`link` 非空」对本缺陷**没有分辨力**（改动前 6 条就全非空）。
+
+---
+
+## 十、相关文档
+
+- `22_8155_需求驳回站内信bizId改为orderId点跳转落空-修复-管理后台.md` — 同一收件箱、相邻缺陷。⚠️ 其中「前端从不读 `row.link`，无需任何前端代码改动」一句的适用范围**仅限 `REQUIREMENT_REJECTED`**，不适用于本条覆盖的三个事件码，理由见「关键变化」第 2 条。
+- `HouseNotificationPublisher` 类注释（hl-order-service-v3）— `bizId` 三义的权威清单，新增调用点时同步维护。
+- Flyway `V20260922_210__fix_house_inapp_link_to_admin_routes.sql`（hl-user-service）— 脚本头注写明了「按收件人域取舍」以及为什么不能改用白名单当判据。
+
+---
+
+## 关联 / 联系人
+
+### 链接
+
+- Issue: [#8182](https://git.1814.love:8443/wx/HL/issues/8182)
+- PR: [#8189](https://git.1814.love:8443/wx/HL/pulls/8189) / [#8190](https://git.1814.love:8443/wx/HL/pulls/8190)
+
+### 联系人
+
+- 后端: wx
+- 前端: 待认领（`frontend_status: pending`）
@@ -0,0 +1,114 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8193"
+title: "通知中心: 团期房务三个事件补齐配置行，管理后台站内信新增三类消息；两条已无发布方的询房配置行删除"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修复"
+backend_status: "deployed"
+gateway_status: "not_required"
+frontend_status: "not_required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "本条不改变 AdminMessageRespVO / AdminMessagePageReqVO 的字段结构，也不新增任何端点；只在 notification_event_config 里补三行、删两行、关两处通道。frontend_status=not_required 的依据是实证而不是估计：三类新消息的 link 落在 /housekeeper/grab-pool-group，hl-ui(origin/v2.1) 的 src/views/notification/MyMessages/jumpBiz.js 对 link 的处理是通用的(非 /pages/ 前缀即直接 router.push)，src/router 已注册该路由且 src/views/housekeeper/grab-pool-group/index.vue 真实存在，V20260922_210 已把该路由纳入白名单 ⇒ 这三类消息在当前已交付的前端代码上直接可点可跳，mmg 零改动。gateway_status=not_required：零新增路由，受影响的 GET /admin/message/list 是既有端点。backend_status=deployed：hl-user-service 已滚动到测试服，Flyway 20260922.211 success=1(installed_on 2026-09-22 21:59:35)，并在自建团期夹具(groupBatchId=2102401449357197314)上走完「整体确认需求 / 房务认领 / 房务释放 → 站内信产出 → GET /admin/message/list 读回」全链路，三个事件各 18 条 ADMIN_INAPP 且 status 全为成功，实测读数见正文第五节。⚠️ admin_message 是快照表：link 在 createMessage 落库那一刻按当时模板一次性渲染写进行内，不是按需渲染 ⇒ 本条只影响生效后新产生的消息，历史行不回刷。 mmg 2026-09-23 复核: grep 实证 jumpBiz.js resolveJumpLink 对非 /pages/ 前缀 link 直喂 router.push(通用分支无事件码分支)、src/router 已注册 housekeeper/grab-pool-group、src/views/housekeeper/grab-pool-group/index.vue 真实存在——三类新消息在当前已交付代码上零改动可点可跳,not_required 成立。"
+updated_at: "2026-09-22"
+base: "dev-v3"
+---
+
+# 通知中心: 团期房务三个事件补齐配置行，管理后台站内信新增三类消息；两条已无发布方的询房配置行删除
+
+> **存放目录**: 二期（order-v3）→ `changelogs-v2/2026-09/`
+>
+> **服务**: hl-user-service（通知分发 / 站内信收件箱 / 配置表；Flyway `V20260922_211`）+ hl-order-service-v3（通知发布方，本次仅注释）
+> **PR**: [#8203](https://git.1814.love:8443/wx/HL/pulls/8203)
+> **Issue**: [#8193](https://git.1814.love:8443/wx/HL/issues/8193)
+> **日期**: 2026-09-22
+> **影响范围**: 管理后台站内信中心（`GET /admin/message/list`）里 HOUSE 类通知的**条目数量与种类**，不涉及字段结构
+
+---
+
+## 一、一句话
+
+团期房务的三个事件此前**一直在发**，但 `notification_event_config` 里没有对应配置行，分发器因此不产出任何消息。本次补齐配置行，房管角色（`ROOM_MANAGER`）的站内信收件箱从此会新增三类消息。
+
+## 二、新增的三类消息（前端看得见）
+
+| `event_code` | 触发时机 | 标题形态 |
+|---|---|---|
+| `GROUP_BATCH_REQUIREMENT_CONFIRMED` | 团期需求整体确认放行 | 整团房需求已确认：{团期名} |
+| `GROUP_BATCH_HOUSE_CLAIMED` | 团期房务被认领（含接管） | 团期房务已认领：{团期名} |
+| `GROUP_BATCH_HOUSE_RELEASED` | 团期房务被释放回池 | 团期房务已释放：{团期名} |
+
+三类消息在 `GET /admin/message/list` 里的字段取值（**实测报文**，非推断）：
+
+```json
+{
+  "messageId": "2102401964484829186",
+  "categoryCode": "SYSTEM",
+  "title": "整团房需求已确认：Q202612082102401392893431809",
+  "content": "团期 Q202612082102401392893431809 的房需求已整体确认，放行 1 户、跳过 0 户，可开始配房。",
+  "link": "/housekeeper/grab-pool-group?groupBatchId=2102401449357197314",
+  "bizId": "2102401449357197314",
+  "bizType": "HOUSE",
+  "isRead": 0,
+  "messageType": "NORMAL",
+  "messageTypeLabel": "普通消息",
+  "kind": "NOTIFY",
+  "senderName": null,
+  "conversationKey": null,
+  "teamMessage": false
+}
+```
+
+**收件人**：`wework_receiver_type=HOUSE_TEAM` ⇒ 分发器取 `ROOM_MANAGER` 角色下 `status='ACTIVE'` 的全部管理员，测试库当前 18 个账号，每个事件各落 18 行 `admin_message`。
+
+## 三、跳转行为：前端零改动即可用
+
+`link` 模板是 `/housekeeper/grab-pool-group?groupBatchId=${groupBatchId}`，三类消息共用。
+
+- `jumpBiz.js` 的 `resolveJumpLink` 对**非 `/pages/` 前缀**的 link 直接返回并 `router.push`，不做事件码分支 ⇒ 这三类消息走的是已交付的通用分支。
+- `canJumpToBiz` 对 HOUSE 非聊天行的判据是「有没有可用 link」，本条三类消息 link 非空 ⇒ **跳转入口会正常渲染**。
+- `/housekeeper/grab-pool-group` 已在 `src/router` 注册，`src/views/housekeeper/grab-pool-group/index.vue` 真实存在；后端 `V20260922_210` 也已把该路由纳入 link 白名单。
+
+**⇒ mmg 不需要为本条写任何代码。**
+
+## 四、契约的覆盖边界（写在脸上，供前端判断要不要做增强）
+
+1. **目标页当前不消费 `?groupBatchId=` 这个查询参数**。`grab-pool-group/index.vue` 里没有任何 `route.query` / `useRoute` 读取（阳性对照：同目录下另有 5 个视图文件确有该用法，所以这不是我查不到）。同模块的 `todos/index.vue` 对 `?inquiryId=` 同样不读——**这是房务模块既有且已随 #8182 交付的约定，不是本条引入的新问题**。因此点进去落到的是抢单池列表页本身，不是定位到该团期。要做「直达该团期」的增强，前端读这个 query 即可，后端已经把 id 送到了。
+2. **`bizId` 不是路由键**。三类消息的 `bizId` 等于 `groupBatchId`、`bizType=HOUSE`，但 HOUSE 域的 `bizId` 在不同事件下有 `hotelId` / `groupBatchId` / `orderId` 三种含义，禁止拿它反推页面——唯一正确的跳转来源是 `link`。这条约束已固化在 `HouseNotificationPublisher` 类注释里。
+3. **`admin_message` 是快照表**。`link` 在消息落库那一刻按当时模板渲染写进行内，之后改模板不影响已存在的行。本条生效时刻为 2026-09-22 21:59:35，此前产生的消息不受影响，也不做批量回刷。
+4. **消息只发给房管角色**。非 `ROOM_MANAGER` 的管理员收件箱里不会出现这三类消息，这是预期行为不是漏发。
+
+## 五、前端**看不见**的三处配置变更（列出以免被误读为回归）
+
+| 变更 | 对前端的影响 |
+|---|---|
+| 删除 `HOUSE_INQUIRY_TIMEOUT`、`HOUSE_INQUIRY_ESCALATED` 两行配置 | **无**。这两个事件的发布方随 #4470「天级确认流程」改造已被一并删除，配置行留着也从不产出消息；删前已按「字面量 / 前缀拼接 / 非 Java 载体」三种形态穷举 + 阳性对照查证零发布方。 |
+| `HOUSE_HOTEL_SWAPPED_NEW_HOTEL` / `_OLD_HOTEL` 的 `inapp_enabled` 由 1 改 0（**行保留**） | **无**。这两个收件人类型是酒店联系人，不在分发器的站内信收件人白名单里，站内信对他们结构上不可达；`inapp_enabled=1` 是假象，自出生起产出为零。保留行是为了将来走短信时只改一位。 |
+| `TRAVELER_INCOMPLETE_DAILY` 的企微三列关闭（**行保留**） | **无**。该事件的 `wework_receiver_type` 原值 `'USER'` 不是合法收件人类型，企微 14 条全部发送失败；同一事件的站内信 / 短信 / 小程序三条通道**保持原样开启，一条不少**。 |
+
+## 六、实测读数
+
+**配置表活体**（2026-09-22，测试库）：
+
+```
+GROUP_BATCH_HOUSE_CLAIMED          HOUSE  inapp=1  /housekeeper/grab-pool-group?groupBatchId=${groupBatchId}  HOUSE_TEAM
+GROUP_BATCH_HOUSE_RELEASED         HOUSE  inapp=1  /housekeeper/grab-pool-group?groupBatchId=${groupBatchId}  HOUSE_TEAM
+GROUP_BATCH_REQUIREMENT_CONFIRMED  HOUSE  inapp=1  /housekeeper/grab-pool-group?groupBatchId=${groupBatchId}  HOUSE_TEAM
+```
+
+**发送流水**（`notification_send_log`，按自建夹具 `biz_id=2102401449357197314` 聚合）：
+
+```
+GROUP_BATCH_REQUIREMENT_CONFIRMED  ADMIN_INAPP  status=0(SUCCESS)  18 行  22:17:44
+GROUP_BATCH_HOUSE_CLAIMED          ADMIN_INAPP  status=0(SUCCESS)  18 行  22:18:08
+GROUP_BATCH_HOUSE_RELEASED         ADMIN_INAPP  status=0(SUCCESS)  18 行  22:18:18
+```
+
+只有 `ADMIN_INAPP` 一个通道、无 WEWORK/SMS 行，与配置 `inapp_enabled=1 / wework_enabled=0` 一致。18 这个数与「`ROOM_MANAGER` 角色下 `status='ACTIVE'` 的账号共 18 个」是两个独立口径，互相吻合。
+
+**link 渲染逐字核对**：报文里三条 link 完全相同，其中 `groupBatchId=2102401449357197314` 与自建团期 id 逐字相等（19 位），模板里无残留 `${` 占位。
+
+**全表断言**：`notification_event_config` 共 63 行 = 合法收件人类型 34 行 + `IS NULL` 29 行 + **非法 0 行**；阳性对照（把 `NOT IN` 改 `IN` 同一批 14 个常量）返回 34 行，证明该断言 SQL 本身能命中。
@@ -0,0 +1,455 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8195"
+title: "团期「查看需求」页五处缺口: 户级团号 teamNo / 未提交户进列表 / 接送机批量确认新端点 / 车型字典校验 / 团期 endDate"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "not_required"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "7df2926240c51d48c31fa3c13962dd0f42b9c9ca"
+target_release: "v2.1"
+verified_at: "2026-09-23"
+status_note: "backend_status=deployed: hl-order-service-v3 已滚动到测试服，deploy-status.sh 读数 dev-v3 / 62449e550 / DEPLOYED_AT 2026-09-22 22:22:58 / STATE=ok，62449e550 即本单合并提交本身；九条验收项全部在测试服网关上取到活体读数，原始报文逐条落盘。gateway_status=not_required: 新端点路径落在 hl-gateway 既有 /v3/admin/** 通配上，零新增路由——判据不是推断而是实测：该路径返 400「请至少选择一个要确认的子订单」（业务校验），而故意写错的同前缀路径返 404「接口不存在」，两种报文形态不同 ⇒ 路由确实存在。frontend_status=pending: 本条新增 4 个响应字段、1 个端点，且改了 householdCount 的口径，hl-ui 需要改；hl-ui(origin/v2.1) 里 src/api/orderV2GroupBatch.js 两处 JSDoc 描述的是改前契约，改后已不准确，逐行列在第六.6 节。⚠️ 契约边界：本接口上「从未提交需求的户」与「提交后被打回的户」完全同形（两者都是 requirements:[] + status:null），不可区分，依据 GroupVehicleHouseholdsRespVO.java:169-171。 mmg 2026-09-23 交付: hl-ui@7df29262 feat(order-v2) 五处缺口全落地——户卡 teamNo/统计行 endDate/未提交户空卡(中性文案)/批量确认(failedCount 判成败+reason 明细)/车型字典下拉(存量非字典值 rule 前置拦);checkpoint 全量绿,相关 106 例测试全过。"
+updated_at: "2026-09-22"
+base: "dev-v3"
+---
+
+# 团期「查看需求」页五处缺口: 户级团号 teamNo / 未提交户进列表 / 接送机批量确认新端点 / 车型字典校验 / 团期 endDate
+
+> **存放目录**: 二期（order-v3）→ `changelogs-v2/2026-09/`
+
+## ⚠️ 关键变化
+
+三条，改前改后行为不同，按这个顺序看：
+
+1. **`orderNo` 从来就不是团号。** 改前两个 households 接口的 Swagger 把 `orderNo` 标成「子订单团号」、example 写 `GT-26-0081`，照着当团号渲染出来的其实是订单号 `HL20260922210334521`。本次**新增 `teamNo` 字段**承载真团号，`orderNo` 字段**保留不删**（前端 `v-for :key` 在用），但注解已订正为「子订单编号（非团号）」。**团号请改读 `teamNo`。**
+2. **`vehicleRowCount` 不再恒 ≥ `householdCount`。** 改前「没提交过用车需求的户」根本不出现在车侧响应里；改后它们**进列表**（`requirements: []`、`status: null`），`householdCount` 随之变成「应报车的户数 = `households` 长度」。原先「行数 ≥ 户数」这个不变量**作废**，别再拿它写断言。实测基线读数 `householdCount=5 / countedHouseholdCount=0 / vehicleRowCount=2`。
+3. **接送机批量确认允许部分成功，且部分失败时 HTTP 仍是 `code:200` / `success:true`。** 失败的户在 `data.failed[]` 里逐条给 `orderId + errorCode + reason`。**不要用 `success` 判断「是不是全成了」**，要看 `failedCount`。
+
+## 一、背景
+
+工单 #8195，wx 在团期「查看需求」页上点出的五处缺口，合并为一个 PR（#8204，squash `62449e550`）。五处分别对应：缺陷 1 团号、缺陷 2 未提交户不可见、缺陷 3 接送机无批量确认、缺陷 4 车型无字典校验、缺陷 5 缺团期结束日。
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|---|---|---|---|---|
+| 1 | 批量确认接送机需求 | POST | `/v3/admin/order/group-batch/{groupBatchId}/requirement/transfer/batch-confirm` | 新增 | 允许部分成功；幂等窗口 120s |
+| 2 | 团期子订单用车需求记录 | GET | `/v3/admin/order/group-batch/{groupBatchId}/requirement/vehicle-households` | 修改 | +`endDate` +`teamNo` +户级`status`/`statusName`；未提交户进列表 |
+| 3 | 团期子订单订房记录 | GET | `/v3/admin/order/group-batch/{groupBatchId}/requirement/hotel-households` | 修改 | +`endDate` +`teamNo`；`orderNo` 注解订正 |
+| 4 | 保存团期正式用车需求 | PUT | `/v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement` | 修改 | 车型必须命中字典，否则 809119 |
+
+## 三、接口详情
+
+### 1. 批量确认接送机需求 `POST /v3/admin/order/group-batch/{groupBatchId}/requirement/transfer/batch-confirm`
+
+**VO**: `TransferBatchConfirmReqVO` → `Result<TransferBatchConfirmRespVO>`
+
+#### 使用场景
+
+「查看需求」页「用车」板块，团期管理员勾选若干户的接送机需求，一次性确认并转交车务。等价于逐户调 `POST /v3/admin/order/{id}/vehicle-requirement/dispatch?kind=TRANSFER`，区别是**允许部分成功**：整批里只要有一户能确认，接口就按业务成功返回，失败户单独列出而不回滚成功户。权限码与整团确认、按户打回同为 `group-batch:demand:confirm`——同一个 Tab 里同一批人的同一类动作，分码会出现「能逐户放行却不能批量放行」这种前端无法向运营解释的组合。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| `groupBatchId` | path | String | 是 | 雪花 ID | 团期 ID，字符串透传，禁 `Number()` |
+| `orderIds` | body | Long[] | 是 | `@NotEmpty`、`@Size(max=200)` | 待确认的子订单 ID，1~200 户，**服务端去重** |
+| `dispatchRemark` | body | String | 否 | `@Size(max=500)` | 确认备注，**整批共用**，提供给车队 |
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `groupBatchId` | String | 团期 ID（`ToStringSerializer`） |
+| `requestedCount` | int | 去重后的待确认户数，**恒等于 `successCount + failedCount`**，可用于对账 |
+| `successCount` | int | 确认成功的户数 |
+| `failedCount` | int | 确认失败的户数；**> 0 时请展示 `failed` 明细，不要只提示「部分成功」** |
+| `succeededOrderIds` | String[] | 成功的子订单 ID，按请求顺序，字符串形态防 JS 精度丢失 |
+| `failed` | FailedItem[] | 失败明细，按请求顺序；**全部成功时是空数组，不是 null** |
+| `failed[].orderId` | String | 子订单 ID |
+| `failed[].errorCode` | Integer | 业务错误码；**非业务异常（系统故障）时为 null** |
+| `failed[].reason` | String | 已渲染的中文报文，可直接展示 |
+
+#### 请求示例
+
+```http
+POST /v3/admin/order/group-batch/2102383303678189570/requirement/transfer/batch-confirm
+Content-Type: application/json
+
+{"orderIds":[2102383417822003201,2102383458422841346],"dispatchRemark":"11/20 首都机场接"}
+```
+
+#### 响应示例
+
+全部成功（测试服实测原文，`ac/06-batch-confirm-1.json`）：
+
+```json
+{"code":200,"message":"成功","data":{"groupBatchId":"2102383303678189570","requestedCount":2,"successCount":2,"failedCount":0,"succeededOrderIds":["2102383417822003201","2102383458422841346"],"failed":[]},"traceId":null,"success":true}
+```
+
+部分成功（测试服实测原文，`ac/07-partial-fail.json`）。**注意 `code` 是 200、`success` 是 true，但有一户没确认成功**：
+
+```json
+{"code":200,"message":"成功","data":{"groupBatchId":"2102383303678189570","requestedCount":2,"successCount":1,"failedCount":1,"succeededOrderIds":["2102405916668440577"],"failed":[{"orderId":"2102383417822003201","errorCode":582083,"reason":"需求状态不允许此操作，请检查当前状态"}]},"traceId":null,"success":true}
+```
+
+#### 空数据 / 降级响应
+
+`orderIds` 传空数组或不传时不进业务逻辑，直接被参数校验拦下，不产生任何写操作。`succeededOrderIds` 与 `failed` 在任何成功响应里都是数组，不会是 `null`——全成功时 `failed` 是 `[]`，全失败时 `succeededOrderIds` 是 `[]`，前端可以无条件 `.map()` 而不必先判空。
+
+#### 错误响应
+
+整批被拒的两种形态（幂等拦截为测试服实测原文 `ac/08-batch-confirm-retry.json`）：
+
+```json
+{"code":400,"message":"请至少选择一个要确认的子订单"}
+{"code":100502,"message":"接送机需求确认处理中，请勿重复提交","data":null,"traceId":null,"success":false}
+```
+
+单户被拒**不走错误响应**，而是进上面 `data.failed[]`，典型 `errorCode` 为 `582083`「需求状态不允许此操作，请检查当前状态」（例如该户已经是 `PENDING`）。
+
+#### 业务边界
+
+- **幂等窗口 120 秒**：`@Idempotent` 的 key 由 `groupBatchId` + `orderIds` 共同决定 ⇒ **换一批 `orderIds` 不受上一次影响**，同一批在 120s 内第二次必被 `100502` 拒。
+- **部分成功是设计，不是异常**：失败户不会被静默跳过，也不会把整批回滚。
+- **确认只改需求状态，不产生派车记录**：本阶段只把 `order_vehicle_requirement.status` 与 `order_main.vehicle_control_status` 从 `PENDING_REVIEW` 置为 `PENDING`；实测两次调用前后 `fleet_assignment` 按 `order_id` 过滤 `COUNT(*)` 均为 0。真正的派车分单是车队侧后续独立动作。
+- **重复的 `orderIds` 服务端去重**：`requestedCount` 是去重**后**的数，前端拿它对账不会因为自己传重而对不上。
+- **响应体里不含刷新后的行**：确认成功后需要重新拉一次 `vehicle-households` 才能看到新状态。
+
+### 2. 团期子订单用车需求记录 `GET /v3/admin/order/group-batch/{groupBatchId}/requirement/vehicle-households`
+
+**VO**: `Result<GroupVehicleHouseholdsRespVO>`
+
+#### 使用场景
+
+「查看需求」页「用车」板块下半块的逐户列表。本次把它从「已提交需求的户的列表」改成「应报车的户的列表」——运营需要看见「谁还没交」，而改前那些户根本不出现在响应里，页面上无从催办。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| `groupBatchId` | path | String | 是 | 雪花 ID | 团期 ID，字符串透传，禁 `Number()` |
+| `kind` | query | String | 否 | `TRAVEL` / `TRANSFER` | **不传 = 两类都返**（与提交侧「不传按 TRAVEL」的缺省相反，此处未改） |
+
+#### 出参
+
+新增 4 个字段、2 个既有字段口径变化，其余未动：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `endDate` | String | **新增**。团期结束日期 `yyyy-MM-dd`；团期未定结束日时为 null（与团期详情 `endDate` 同源） |
+| `households[].teamNo` | String | **新增**。子订单团号，取 `order_main.team_no`；**未付订金尚未分配时原样返 null**，后端不兜底成 `orderNo`、不回退空串 |
+| `households[].status` | String | **新增**（户级）。**null = 该户一份用车需求都没提交**；非 null 时取展示序首条（TRAVEL 优先）的状态 |
+| `households[].statusName` | String | **新增**（户级）。与 `status` 同一条需求行的中文名；`status` 为 null 时本字段也为 null |
+| `householdCount` | int | **口径变更**。改前 = 有活跃需求行的户数；改后 = 应报车的户数，恒等于 `households` 长度，**含一份都没提交的户**。仍按 `orderId` 去重（一户同时报行程用车与接送机只算 1 户） |
+| `vehicleRowCount` | int | 口径未变、**关系变了**。= Σ 各户 `requirements` 长度，未提交户贡献 0 行 ⇒ **可能小于 `householdCount`** |
+| `countedHouseholdCount` | int | 口径未变、**分母变了**。= 有活跃 TRAVEL 行的户数。`householdCount − countedHouseholdCount` 从改前的「只报了接送机的户」变成「只报了接送机的户 **+ 一份都没提交的户**」 |
+| `households[].orderNo` | String | 值与形态都没变（`"HL" + yyyyMMddHHmmssSSS`，定长 19），只是 Swagger 不再谎称它是团号 |
+| `requirements[].status` | String | **未变**，早就有。逐条的权威状态在这里，不在户级 `status` |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch/2102383303678189570/requirement/vehicle-households
+```
+
+#### 响应示例
+
+测试服实测（`ac/00-vehicle-households.json`）顶层为 `householdCount=5`、`countedHouseholdCount=0`、`vehicleRowCount=2`、`endDate="2026-11-21"`，五户的关键字段：
+
+```json
+[{"orderNo":"HL20260922210334521","teamNo":"26-3724","status":null,"requirements":[]},
+ {"orderNo":"HL20260922210348601","teamNo":null,"status":null,"requirements":[]},
+ {"orderNo":"HL20260922210358692","teamNo":null,"status":null,"requirements":[]},
+ {"orderNo":"HL20260922210401823","teamNo":"26-0847","status":"PENDING_REVIEW","requirements":["…1 条"]},
+ {"orderNo":"HL20260922210411494","teamNo":"26-7970","status":"PENDING_REVIEW","requirements":["…1 条"]}]
+```
+
+三个计数两两不等，正好演示新口径：5 户全在列表里，只有 2 户提交过，且两条都是 TRANSFER，所以计入车侧汇总的 TRAVEL 户数是 0。
+
+#### 空数据 / 降级响应
+
+该户没提交任何用车需求时 `requirements` 是 `[]`（**空数组，不是 null**）、`status` 与 `statusName` 均为 null；团期未定结束日时 `endDate` 为 null；未付订金时 `teamNo` 为 null。整团一户都没有时三个计数为 0、`households` 为 `[]`，接口仍返 200。以上四种降级都不会让接口报错，前端需要各自有占位显示。
+
+#### 错误响应
+
+本次未改，沿用团期段位错误码：
+
+```json
+{"code":589500,"message":"团期不存在","data":null,"traceId":null,"success":false}
+```
+
+另有 `589507`（`GROUP_BATCH_PERMISSION_DENIED`，团期操作/读取被拒）由拦截器透 `message`，前端直接展示即可。
+
+#### 业务边界
+
+- **户级 `status` 是折叠态用的，不是权威状态**：一户可能同时有 TRAVEL 与 TRANSFER 两条活跃行、状态各自独立（例如 TRAVEL 已放行 `PENDING`、TRANSFER 还在 `PENDING_REVIEW`），户级 `status` 只取展示序第一条。**按条判断一律读 `requirements[].status`。**
+- 🔴 **「从未提交」与「提交后被打回」在本接口上不可区分**：打回 = 原地置 `REJECTED_*` + `is_active=0`，失活行不进 `requirements` ⇒ 被打回的户同样是 `requirements: []` + `status: null`，与从未提交的户**完全同形**。依据 `GroupVehicleHouseholdsRespVO.java:169-171`。要把这两种人分开，本接口给不出判据。
+- **`teamNo` 与 `orders` 接口同源同值**：取 `order_main.team_no`，不是 `order_group_batch.batch_no`（那是整团一个值，放在逐户列表上每行都一样，这一列就没有分辨力了）。三个读口（hotel-households / vehicle-households / orders）的 `teamNo` 实测逐字符相等。
+
+### 3. 团期子订单订房记录 `GET /v3/admin/order/group-batch/{groupBatchId}/requirement/hotel-households`
+
+**VO**: `Result<GroupHotelHouseholdsRespVO>`
+
+#### 使用场景
+
+「查看需求」页「用房」板块下半块的逐户列表，与 `requirement-summary` 并列调用。本次只补两个字段并订正一处注解，列表口径没动——用房侧本来就包含未提交的户（`status=null`、`days=[]`），这次是车侧向它对齐，不是它变了。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| `groupBatchId` | path | String | 是 | 雪花 ID | 团期 ID，字符串透传，禁 `Number()` |
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `endDate` | String | **新增**。团期结束日期 `yyyy-MM-dd`，未定时 null，与车侧同源同值 |
+| `households[].teamNo` | String | **新增**。同车侧，取 `order_main.team_no`，未付订金时 null |
+| `households[].orderNo` | String | 注解订正（「子订单团号」→「子订单编号（非团号）」），**值未变** |
+| `households[].status` | String | **未变**。用房侧本来就有（未提交时为 null） |
+| `households[].statusName` | String | **未变**。用房侧本来就有 |
+| `householdCount` | int | **未变**。与 `countedHouseholdCount` 的差值仍是「未计入汇总（打回 / 未提交）的户数」 |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch/2102383303678189570/requirement/hotel-households
+```
+
+#### 响应示例
+
+测试服实测（`ac/00-hotel-households.json`），`endDate` 为 `"2026-11-21"`，五户 `teamNo` 与车侧、与 `GET .../orders` 三方逐字符相等：
+
+```json
+[{"orderNo":"HL20260922210334521","teamNo":"26-3724"},
+ {"orderNo":"HL20260922210348601","teamNo":null},
+ {"orderNo":"HL20260922210358692","teamNo":null},
+ {"orderNo":"HL20260922210401823","teamNo":"26-0847"},
+ {"orderNo":"HL20260922210411494","teamNo":"26-7970"}]
+```
+
+#### 空数据 / 降级响应
+
+未付订金的户 `teamNo` 为 null；团期未定结束日时 `endDate` 为 null。既有的降级行为一律未动：需订房但未提交的户仍会列出（`status=null`、`days=[]`），客户自订晚仍会列出且 `hotels=[]`，打回户仍列出且 `countedInSummary=false`。
+
+#### 错误响应
+
+本次未改，与车侧同段位：
+
+```json
+{"code":589500,"message":"团期不存在","data":null,"traceId":null,"success":false}
+```
+
+#### 业务边界
+
+- **用房侧的列表口径没有跟着车侧一起改**：它本来就含未提交户，本次只补 `teamNo` 与 `endDate` 两个字段。
+- **「汇总 == Σ 子订单」这条既有硬约束不受影响**：汇总逐日间数仍等于本接口 `countedInSummary=true` 各户逐日加总，差值仍是 `householdCount − countedHouseholdCount`。
+- **`orderNo` 的排序契约未变**：`households` 仍按 `orderNo` 升序，新增 `teamNo` 不参与排序——**不要改用 `teamNo` 排序**，它可以为 null。
+
+### 4. 保存团期正式用车需求 `PUT /v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement`
+
+**VO**: `GroupVehicleRequirementSaveReqVO` → `Result<GroupVehicleRequirementRespVO>`
+
+#### 使用场景
+
+团期管理员新增 / 编辑整团的正式行程用车需求，一次全量替换整份（主表 + 全部分组 + 全部逐日行）。本次给分组里的车型加了字典校验：改前前端传什么就落什么，运营填错的车型要等到车队派车时才暴露；改后在保存这一步就拒。
+
+#### 入参
+
+结构不变，仅新增一条约束：
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| `groupBatchId` | path | String | 是 | 雪花 ID | 团期 ID，字符串透传 |
+| `groups[].vehicleType` | body | String | 是 | **新增：必须命中车型字典** | 车型大类编码，须存在且未下线，从下拉项取 |
+| `groups[].groupName` | body | String | 是 | — | 组名，校验失败时会被写进错误报文，便于定位是哪一组 |
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `groups[].vehicleType` | String | 校验通过后回显的车型编码，未变 |
+| `groups[].vehicleTypeName` | String | 车型中文名，后端按字典下发，**禁前端自映射** |
+
+其余字段结构不变。
+
+#### 请求示例
+
+```json
+{"groups":[{"groupName":"AC9-BAD","vehicleType":"minivan"}]}
+```
+
+`vehicleType` 须取自 `GET /admin/fleet/vehicle-types/list` 的下拉项；上例的 `minivan` 不在字典内，用于演示校验被触发。
+
+#### 响应示例
+
+合法车型实测（`ac/09-good-type-4.json` 节选）：
+
+```json
+{"code":200,"message":"成功","data":{"groups":[{"vehicleType":"bus","vehicleTypeName":"大巴系列"}]},"success":true}
+```
+
+#### 空数据 / 降级响应
+
+车型字典为空时**不放行**（fail-closed），不会退化成「不校验」——宁可让保存失败并提示运营去维护字典，也不能把一批查不到名字的车型放进正式需求，那会在车队侧变成一堆无法派车的行。
+
+#### 错误响应
+
+非法车型实测原文（`ac/09-bad-type.json`），报文里带**组名**，前端可直接定位到是哪一组填错：
+
+```json
+{"code":809119,"message":"第 AC9-BAD 组的车型 minivan 不在车型字典内（不存在或已下线），请从下拉项中选择","data":null,"traceId":null,"success":false}
+```
+
+#### 业务边界
+
+- **车型必须从 `GET /admin/fleet/vehicle-types/list` 的返回里选**，不要在前端硬编码枚举——字典行可被下线，下线后同一个编码就会被拒。
+- **本端点另有两条既有前置会先于车型校验触发**（本次未改）：团期阶段守卫（`RECRUITING` 阶段被 `589501`「团期状态不允许当前操作」拒，需先成团）、逐日乘车分组必须覆盖全团在团户与全部行程日（否则 `809109`「子订单 {0} 的 {1} 没有被任何乘车分组覆盖」）。
+- **整份全量替换**：保存即覆盖，前端提交前必须带上未改动的分组与逐日行，否则会被删掉。
+
+## 四、契约约束与正确调用方式
+
+### ✅ 正确 / ❌ 错误对照
+
+| 场景 | ❌ 错误 | ✅ 正确 |
+|---|---|---|
+| 渲染团号列 | 读 `orderNo` | 读 `teamNo`；为 null 时显示占位符，**不要回落成 `orderNo`** |
+| 表头「共 N 户」 | 用行数或自行推算 | 取 `householdCount`（与 `households.length` 恒等） |
+| 判断批量确认结果 | `if (res.success) { 提示全部成功 }` | `if (res.data.failedCount > 0) { 展示 res.data.failed 明细 }` |
+| 判断某条需求的状态 | 读户级 `status` | 读 `requirements[i].status` |
+| 车型下拉 | 前端写死枚举数组 | 调 `GET /admin/fleet/vehicle-types/list` |
+| 列表排序 | 改用 `teamNo` 排序 | 仍按 `orderNo`（`teamNo` 可为 null） |
+| 传 ID | `Number(orderId)` | 雪花 ID 一律字符串透传 |
+
+### 状态切换后的必要动作
+
+批量确认成功后，被确认户的 `order_vehicle_requirement.status` 与 `order_main.vehicle_control_status` 都变为 `PENDING`。响应体里不含刷新后的行，需要重新拉一次 `vehicle-households`。
+
+## 五、数据库行为
+
+批量确认端点写两张表：`order_vehicle_requirement.status`、`order_main.vehicle_control_status`，均 `PENDING_REVIEW → PENDING`，调用前后逐户 `SELECT` 核对过。**不写 `fleet_assignment`**（前后均 `COUNT(*)=0`）。清单里的 2、3 两个读接口不写库。
+
+## 六、边界行为
+
+| 情形 | 行为 |
+|---|---|
+| 未付订金的户 | `teamNo` 为 `null`（`team_no` 此时尚未分配），前端需要占位显示 |
+| 一份用车需求都没提交的户 | 进车侧列表，`requirements: []`、`status: null`、`statusName: null` |
+| 提交后被打回的户 | **与上一行完全同形，本接口不可区分** |
+| 一户同时有 TRAVEL + TRANSFER | `householdCount` 只算 1 户，`vehicleRowCount` 算 2 行 |
+| 批量确认里混入状态不对的户 | 整批仍按 `code:200` 返回，该户进 `failed[]` |
+| 120s 内同批重复提交 | `code:100502`，整批拒 |
+| 团期未定结束日 | `endDate: null` |
+| 车型字典为空 | 保存被拒（fail-closed），不退化成不校验 |
+
+## 六.5、枚举 / 数据字典
+
+### `households[].status`（户级用车需求状态）
+
+`PENDING_REVIEW`(待审核) / `PENDING` / `PROCESSING` / `DONE`，以及 **`null` = 该户一份都没提交**。`statusName` 由后端下发，**禁前端自映射**。
+
+### `vehicleType`（车型大类编码）
+
+**运行期字典，不是固定枚举**，取自 `fleet_vehicle_type`，通过 `GET /admin/fleet/vehicle-types/list` 下发。2026-09-22 测试服上存活 4 项（`suv2` / `mpv` / `sedan` / `bus`），但这是**当日快照、不是契约**——字典行可被增删下线，前端不得据此硬编码。
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+| 接口 | 字段 | 改前 | 改后 |
+|---|---|---|---|
+| hotel / vehicle-households | `orderNo` 的 Swagger 说明 | 「子订单团号」，example `GT-26-0081` | 「子订单编号（非团号；形如 HL + yyyyMMddHHmmssSSS）」，example `HL20260516143052999`。**字段值本身从未变过**，一直是订单号 |
+| hotel / vehicle-households | `teamNo` | 不存在 | 新增，真团号，可为 null |
+| hotel / vehicle-households | `endDate` | 不存在 | 新增，可为 null |
+| vehicle-households | 户级 `status` / `statusName` | 不存在 | 新增（用房侧本来就有；`requirements[].status` 也早就有，别混淆） |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|---|---|---|
+| 没提交用车需求的户 | **不在车侧响应里** | 在响应里，空卡 |
+| `householdCount` | 有活跃需求行的户数 | `households` 长度 |
+| `vehicleRowCount` vs `householdCount` | 恒 ≥ | **可能 <** |
+| 接送机确认 | 只能逐户 `dispatch?kind=TRANSFER` | 可批量，允许部分成功 |
+| 提交非法车型 | 通过，落库 | `809119` 拒 |
+
+### 🔴 hl-ui 里已经不准确的 JSDoc（`origin/v2.1`，`src/api/orderV2GroupBatch.js`）
+
+两个函数的 JSDoc 都写于改前，各有过期处。行号为 2026-09-22 在 `origin/v2.1` 上实读：
+
+**`getGroupVehicleHouseholds`（JSDoc `:597-622`）**
+
+- **`:600`**「被打回的需求行不在列表内(失活即消失,勿按用房那套找打回户)」——这句本身仍成立，但它隐含的「列表里的户都提交过」已不成立：未提交户现在也在列表里，且**和被打回户长得一模一样**。
+- **`:601-602`**「householdCount 按 orderId 去重…vehicleRowCount 数行,两者刻意不等价——表头「共 N 户」必须取 householdCount,禁取行数」——**结论仍然对**（表头就该取 `householdCount`），但它没说方向，读的人会默认行数 ≥ 户数，**改后可能反过来**。
+- **`:607-620`** 的 `@returns` 结构体——缺 `endDate`、`teamNo`、户级 `status`、户级 `statusName` 四个新字段。注意 `:613` 已有的 `status/statusName` 是 `requirements[]` 里的，不是户级的。
+
+**`getGroupHotelHouseholds`（JSDoc `:568-589`）**
+
+- **`:576-586`** 的 `@returns` 结构体——缺 `endDate` 与 `teamNo`；`:579` 列的 `orderNo` 需要补一句「不是团号」。
+- `:571-574` 关于打回户、未提交户与「汇总 == Σ 子订单」的几条口径**未变**，不必动。
+
+## 六.7、影响评估
+
+| 面 | 评估 |
+|---|---|
+| 破坏性 | **无字段删除、无字段改名、无类型变更**，`orderNo` 的值与形态都没动 ⇒ 前端不改也不会报错 |
+| 但会静默出错的地方 | ①「共 N 户」若不是取 `householdCount` 而是别的推算，数字会和列表对不上；②「行数 ≥ 户数」的断言会在有未提交户时挂掉；③ 批量确认只看 `success` 会把部分失败当成全成功 |
+| 需要前端动手的 | 团号列改读 `teamNo`、空卡的展示与催提交入口、批量确认按钮与部分失败明细、车型下拉改走字典接口、`endDate` 展示 |
+
+## 七、不影响范围
+
+- `GET /v3/admin/order/group-batch/{id}/orders`：未改，`teamNo` 本来就有，本次是让另外两个接口与它对齐。
+- 用房侧的列表口径与「汇总 == Σ 子订单」硬约束：未改。
+- 逐户 `POST /v3/admin/order/{id}/vehicle-requirement/dispatch`：未改，仍可用。
+- 车侧汇总 `requirement-summary` 的既有口径：未改，仍只统计行程用车（#8151 的语义保持）。
+- 小程序端、`/mp/` 接口：零改动。
+- 网关：零新增路由。
+- 结算侧 `settlement/**`：与本次改动零文件重叠。
+
+## 八、测试环境已验证
+
+网关 `https://api.test.1814.love:9443`，order-v3 读数 `dev-v3 / 62449e550 / 2026-09-22 22:22:58 / STATE=ok`（`62449e550` 即本单合并提交本身）。
+
+| 验证项 | 结果 |
+|---|---|
+| `teamNo` 三方同源 | hotel / vehicle / orders 三个接口逐户逐字符相等；已付订金户非空、未付订金户为 `null`，两种情形都覆盖 |
+| `teamNo ≠ orderNo` | 逐户为不同值 |
+| 未提交户进列表 | 空卡与 `status="PENDING_REVIEW"` 的已提交户在**同一份响应**里同时存在，字段有分辨力 |
+| 三个计数可区分 | 基线 `5 / 0 / 2`，终态 `6 / 0 / 3`，均两两不等 |
+| 批量确认 | 2 户全成功；DB 回读两户双表均 `PENDING_REVIEW → PENDING` |
+| 部分成功 | 1 成 1 败，失败户带 `orderId + errorCode(582083) + reason` |
+| 幂等 | 同批 120s 内第二次 `code:100502`；DB 回读无重复行 |
+| 车型字典两个方向 | 非法 `minivan` → `809119` 拒；合法 `bus` → 200 通过并回显 `vehicleTypeName` |
+| `endDate` | hotel / vehicle / batch-detail 三方均 `2026-11-21`，逐字符相等 |
+| 单测 / ArchTest | 定向 9 个类共 173 个用例逐类点名核对全绿，含 `MapperBoundaryArchTest` 27 与 `RedLineArchTest` 12 |
+
+原始报文全部落盘（`D:/work2/_scratch/8195/ac/*.json`）。夹具为自建团期 `2102383303678189570` + 自建产品班期 `2102383185755312131`（`batchName` 为「8195夹具-2026年11月团期」），未复用他人夹具。
+
+## 九、相关历史 PR
+
+- #8151（团期子订单用车需求记录只读接口，本次改的就是它）
+- #7441（团期正式用车需求的存 / 读 / 撤回 / 免车四端点）
+
+## 十、相关文档
+
+- Gitea Issue #8195
+- PR #8204（squash `62449e550`）
+- 相邻单 #8193（团期房务三事件站内信配置，同批部署）
+
+## 关联 / 联系人
+
+### 链接
+
+- 工单: `https://git.1814.love:8443/wx/HL/issues/8195`
+- PR: `https://git.1814.love:8443/wx/HL/pulls/8204`
+
+### 联系人
+
+- 后端: wx
+- 前端: mmg（hl-ui，分支 `v2.1`）
@@ -0,0 +1,549 @@
+---
+schema: hl-changelog/v2
+ticket: "frontend"
+title: "团期详情页切走后重放请求导致 groupBatchId 塌缩（前端侧修复）"
+consumer: admin
+author: "wx(GIT)"
+change_type: "前端缺陷"
+backend_status: "deployed"
+gateway_status: "not_required"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "b7c20a81945f986f9e5edc6e09adbe5da93220d4"
+target_release: "v2.1"
+verified_at: "2026-09-22"
+updated_at: "2026-09-22"
+base: dev-v3
+status_note: "2026-09-22 测试服 test.1814.love:9443 实测：账号 admin/团期管理员从团期详情页切换到 /notification/my-messages 后弹出三条报错（两条 400『参数 groupBatchId 格式错误』+ 一条 404『接口不存在』）。order-v3 日志（8186/8086 两实例，09:06:44/50）显示 MethodArgumentTypeMismatchException 收到 value=requirement-summary/vehicle-requirement，NoHandlerFoundException 命中 GET /v3/admin/order/group-batch/requirement/hotel-households；同一时段 09:06:48 带真实 id 的请求全部成功，hl-gateway 两实例 0 条路由未命中记录。根因是前端 order-v2/batch/detail/index.vue 用 computed(() => decodeURIComponent(String(route.params.code || ''))) 反应式推导 id，该页 keep-alive 缓存，切到消息中心（meta keepAlive/hidden/noTabs）后 route.params.code 变 undefined，id 求值为空串；『查看需求』Tab 下 RoomSummarySection/RoomHouseholdsSection/GroupVehicleRequirementSection 三个 watcher 缺空值守卫，重放请求把空串拼进本该是路径参数的位置，导致两个后缀字面量落进 GET /v3/admin/order/group-batch/{groupBatchId}（A2 团期详情）的 groupBatchId 位，另一个因少了中间段直接 404。同页 DisbandBanner 组件已有判空守卫，调用全程 200，是本页面内的阳性对照。三条后端接口路径/参数/权限码均未变更、已在测试服部署并正常工作；既有交接件 10_7316/15_7441/20_8046 记录的实现与本次核对一致。建议修法：三个子组件 watcher 照 DisbandBanner 写法补判空；或详情页不用 useRoute() 反应式推导 code，改挂载时快照/onDeactivated 停 watcher。同页 confirm-check/orders/status-logs 三个 Tab 本次未复现报错，是否另有 active 门控，列为待排查项。 前端修复(2026-09-22): 已交付 hl-admin b7c20a81——三个组件(RoomSummarySection/RoomHouseholdsSection/GroupVehicleRequirementSection)load() 首行照阳性对照 DisbandBanner 补 if(!props.groupBatchId) return 空值守卫,watcher/immediate/reload 统一被拦;待排查项实证闭环:ItineraryTab/SuppliesPanel/RoomPlansTab/FinanceTab/StatusLogsPanel/OverviewTab 本就有 active&&id 或 if(id) 守卫,RequirementTab 只 watch active 不在塌缩链路;三 spec 各补塌缩不重放/恢复重拉/首开空 id 不拉取回归(Vitest 定向 42/42,checkpoint 全绿)。"
+---
+
+# 团期详情页切走后重放请求导致 groupBatchId 塌缩（前端侧修复）
+
+## ⚠️ 关键变化
+
+- **不是后端问题**：三条报错全部由前端在 id 为空串时仍发起请求触发；本次涉及的三条后端接口路径、参数、权限码均未变更，已在测试服部署并实测正常。
+- **触发条件**：团期详情页 `order-v2/batch/detail/index.vue` 是 keep-alive 缓存页，从该页切换到 `/notification/my-messages`（路由 meta `keepAlive/hidden/noTabs`）后，详情页仍存活在缓存中，其 `computed(() => decodeURIComponent(String(route.params.code || '')))` 推导出的 id 因 `route.params.code` 变为 `undefined` 而塌缩成**空字符串**。
+- **传导机制**：「查看需求」Tab 下 `RoomSummarySection`、`RoomHouseholdsSection`、`GroupVehicleRequirementSection` 三个组件的请求 watcher 缺空值守卫，空串重放请求后，URL 路径段整体消失，后面的字面量后缀滑进了 `groupBatchId` 应该在的位置，命中了两种不同的服务端拒绝形态（400 参数类型错误 / 404 无映射），而不是权限或路由错误。
+- **正对照**：同页 `DisbandBanner` 组件已有 `if (!props.groupBatchId) return;` 守卫，全程请求 200，可作为直接抄的修复模板。
+
+## 一、背景
+
+### 现象（2026-09-22 测试服 test.1814.love:9443，账号 admin / 角色 团期管理员）
+
+用户从团期详情页 `/order-v2/batch/detail/2100856430494973953` 切换到 `/notification/my-messages` 后，页面弹出三条报错：
+
+- `参数 groupBatchId 格式错误，请检查后重试` × 2
+- `接口不存在: GET /v3/admin/order/group-batch/requirement/hotel-households`
+
+### 后端实测日志（order-v3，`hl-order-service-v3.log`，09:06:44 与 09:06:50 各一波，分别落在 8186 / 8086 两实例）
+
+```
+WARN GlobalExceptionHandler - 参数类型错误: param=groupBatchId, value=requirement-summary, requiredType=Long
+WARN GlobalExceptionHandler - 参数类型错误: param=groupBatchId, value=vehicle-requirement, requiredType=Long
+WARN org.springframework.web.servlet.PageNotFound - No mapping for GET /v3/admin/order/group-batch/requirement/hotel-households
+WARN GlobalExceptionHandler - No handler found: GET /v3/admin/order/group-batch/requirement/hotel-households
+```
+
+同一时段 09:06:48，带真实 id（`groupBatchId=2100856430494973953`）的请求全部成功；hl-gateway 两实例 0 条路由未命中记录——请求确实到达了 order-v3，并被服务端正确拒绝（不是网关/路由问题）。
+
+### 「表面看起来像」vs「实际是」
+
+| 表面报错 | 看起来像 | 实际是 |
+|---|---|---|
+| `参数 groupBatchId 格式错误，请检查后重试` | 接口参数校验变严了 / 接口签名变了 | 前端把空串拼进了 URL，字面量后缀（`requirement-summary`/`vehicle-requirement`）落进了 `groupBatchId` 位，被 `GroupBatchQueryController` 的团期详情端点 `GET /v3/admin/order/group-batch/{groupBatchId}` 接住，Long 转换失败 |
+| `接口不存在: GET /v3/admin/order/group-batch/requirement/hotel-households` | 接口被删了 / 路由配错了 | 空串导致中间路径段整体消失，剩下两段字面量拼在一起，天然不匹配任何 `@GetMapping`，属于合法的 404，接口本体从未变化 |
+
+### 根因链路（前端产物级实测，测试服 `/var/www/hl-admin/assets`，2026-09-22 06:28 部署）
+
+1. `order-v2/batch/detail/index.vue` 的 id 取值是反应式推导：`computed(() => decodeURIComponent(String(route.params.code || '')))`。
+2. 该页是 keep-alive 缓存页；`/notification/my-messages` 路由 meta 为 `keepAlive/hidden/noTabs`，切过去后详情页仍在缓存中存活，而 `route.params.code` 已变 `undefined` → id 求值为空串。
+3. 「查看需求」Tab 下三个子组件的 watcher 没有空值守卫，于是各重放一次请求：
+   - `RoomSummarySection`：`watch([active, groupBatchId], ...)` 只挡了 `active`，不挡空 id；
+   - `RoomHouseholdsSection`：同上；
+   - `GroupVehicleRequirementSection`：`watch(() => props.groupBatchId, ..., {immediate: true})`，无任何守卫。
+4. 空串导致 URL 路径段整体消失，后缀滑进了 id 位置：
+   - `/v3/admin/order/group-batch/requirement-summary` → 被团期详情端点 `GET /v3/admin/order/group-batch/{groupBatchId}` 匹配，`{groupBatchId}` 位拿到字符串 `requirement-summary` → Long 转换失败；
+   - `/v3/admin/order/group-batch/vehicle-requirement` → 同上；
+   - `/v3/admin/order/group-batch/requirement/hotel-households` → 两段字面量后缀，中间没有 `{groupBatchId}`，不匹配任何映射 → 404。
+5. **阳性对照（同一页面内）**：`DisbandBanner` 组件已有 `if (!props.groupBatchId) return;` 守卫，所以它调的 `approvals/page` 全程 200、没有报错。
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|---|---|---|---|---|
+| 1 | 全团需求汇总 | GET | `/v3/admin/order/group-batch/{groupBatchId}/requirement-summary` | 复用不改 | 契约未变，本次仅确认前端调用方式 |
+| 2 | 团期子订单订房记录 | GET | `/v3/admin/order/group-batch/{groupBatchId}/requirement/hotel-households` | 复用不改 | 契约未变，本次仅确认前端调用方式 |
+| 3 | 读团期正式用车需求 | GET | `/v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement` | 复用不改 | 契约未变，本次仅确认前端调用方式 |
+
+## 三、接口详情
+
+### 1. 全团需求汇总
+
+`GET /v3/admin/order/group-batch/{groupBatchId}/requirement-summary`
+
+**VO**: 无独立请求体（仅路径参数）→ `GroupRequirementSummaryRespVO`
+
+#### 使用场景
+
+团期详情页「查看需求」Tab 的「用房 · 汇总」板块，展示全团逐日 × 酒店 × 房型的用房间数合计、大巴座位合计、各子订单特殊需求标签。
+
+#### 入参字段表
+
+| 字段 | 位置 | 类型 | 必填 | 说明 |
+|---|---|---|---|---|
+| groupBatchId | Path | Long | 是 | 团期 ID（雪花 id）。**本次报错的病灶**：该字段取自路由 `code` 参数，页面切走后再重放请求时其反应式取值会塌缩为空串，导致这个路径段被 URL 后面的字面量后缀顶替 |
+
+#### 出参字段表
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| activeOrderCount | int | 在团子订单数（仅排除 CANCELLED，含 COMPLETED） |
+| hotelNeededOrderCount | int | 需要订房的户数（needsHotel=true 并上已提交有效用房需求的户） |
+| hotelSubmittedOrderCount | int | 已提交有效用房需求（非打回态）且计入 dailyRoomBreakdown 的户数 |
+| vehicleRequirementCount | int | 已提交用车需求的子订单数 |
+| dailyRoomBreakdown[].dayNumber | int | 行程天数（从 1 开始） |
+| dailyRoomBreakdown[].stayDate | LocalDate | 该晚住宿日期；团期无出发日时为 null |
+| dailyRoomBreakdown[].hotels[].hotelId | Long（字符串序列化） | 酒店 ID；无候选或未填酒店时为 null |
+| dailyRoomBreakdown[].hotels[].rooms[].roomCategory | String | 房型大类编码 |
+| dailyRoomBreakdown[].hotels[].rooms[].totalRoomCount | int | 该天该酒店该房型合计间数 |
+| vehicleSeatSummary[].vehicleType | String | 车型大类编码（suv/mpv/bus/sedan） |
+| vehicleSeatSummary[].totalSeats | int | 合计座位数 |
+| orderSpecialTags[].orderId | Long | 子订单 ID |
+| orderSpecialTags[].specialTags | String[] | 特殊需求标签列表 |
+
+#### 请求示例
+
+```
+GET /v3/admin/order/group-batch/2100856430494973953/requirement-summary
+Authorization: Bearer {token}
+```
+
+无请求体。
+
+#### 响应示例
+
+（按 VO 字段契约构造，非测试服抓包实测）
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "activeOrderCount": 12,
+    "hotelRequirementCount": 10,
+    "hotelNeededOrderCount": 10,
+    "hotelFlagMismatchOrderCount": 0,
+    "hotelSubmittedOrderCount": 9,
+    "vehicleRequirementCount": 8,
+    "dailyRoomBreakdown": [
+      {
+        "dayNumber": 1,
+        "stayDate": "2026-09-12",
+        "rooms": [{"roomCategory": "STANDARD", "roomCategoryName": "标间", "totalRoomCount": 5}],
+        "hotels": [{"hotelId": "2023714929877450753", "hotelName": "海堂酒店", "totalRoomCount": 5, "rooms": [{"roomCategory": "STANDARD", "roomCategoryName": "标间", "totalRoomCount": 5}]}]
+      }
+    ],
+    "vehicleSeatSummary": [{"vehicleType": "bus", "vehicleTypeName": "35座大巴", "totalSeats": 35, "totalCount": 1}],
+    "orderSpecialTags": [{"orderId": 2101506167043985410, "requirementType": "HOTEL", "specialTags": ["连通房"]}]
+  }
+}
+```
+
+#### 空数据 / 降级响应
+
+各汇总数组在无对应需求时返回空数组，不会返回 null；`hotelName`/`vehicleTypeName` 在资源服务不可用或字典缺失时可能为 null，间数照常返回。
+
+#### 错误响应
+
+groupBatchId 路径段为空串时的实际报错（本次事故复现的原样响应）：
+
+```json
+{"code": 400, "message": "参数 groupBatchId 格式错误，请检查后重试", "data": null, "success": false}
+```
+
+团期不存在：
+
+```json
+{"code": 589500, "message": "团期不存在", "data": null, "success": false}
+```
+
+当前角色未持 `group-batch:view` 权限，或该团期不在本人名下：
+
+```json
+{"code": 589507, "message": "无操作权限（当前角色未授予团期权限，或该团期不在您名下）", "data": null, "success": false}
+```
+
+#### 业务边界
+
+- `groupBatchId` 必须是真实存在的 Long 型团期 id；空串、`undefined` 字面量、非数字字符串都会被当成非法值处理，统一走 400，不会得到空数据。
+- 需要角色权限码 `group-batch:view`；无权限或团期不在名下统一报 589507（不区分两种子原因）。
+
+### 2. 团期子订单订房记录
+
+`GET /v3/admin/order/group-batch/{groupBatchId}/requirement/hotel-households`
+
+**VO**: 无独立请求体（仅路径参数）→ `GroupHotelHouseholdsRespVO`
+
+#### 使用场景
+
+团期详情页「查看需求 · 用房」板块的下半区，按子订单（户）展示订房记录：每户一张卡（团号/联系人/人数/定制师/状态/配房需求）+ 逐晚填报明细（住宿日期/酒店/城市/房型/间数）。与「全团需求汇总」是同一板块的上下两块，各走各的接口。
+
+#### 入参字段表
+
+| 字段 | 位置 | 类型 | 必填 | 说明 |
+|---|---|---|---|---|
+| groupBatchId | Path | Long | 是 | 团期 ID（雪花 id）。同上，是本次报错的病灶字段 |
+
+#### 出参字段表
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| groupBatchId | Long（字符串序列化） | 团期 ID |
+| departDate | LocalDate | 团期出发日期；未定出发日时为 null，此时各晚 stayDate 也全为 null |
+| householdCount | int | 本列表的户数（=需订房户数），可能大于 countedHouseholdCount，差值是正被打回的户 |
+| countedHouseholdCount | int | 其中计入上方汇总间数的户数 |
+| households[].orderId | Long（字符串序列化） | 子订单 ID |
+| households[].orderNo | String | 子订单团号 |
+| households[].status | String | 需求状态编码：PENDING_REVIEW/PENDING/PROCESSING/DONE/REJECTED_TO_CONSULTANT/REJECTED_TO_ADMIN；该户尚未提交需求时为 null |
+| households[].countedInSummary | boolean | 该户是否计入了「用房汇总」的间数；两个打回态为 false |
+| households[].days[].dayNumber | int | 第几晚（从 1 起） |
+| households[].days[].customerSelfBooked | boolean | 该晚是否客户自订；自订晚 hotels 恒为空且不计入汇总间数 |
+| households[].days[].hotels[].hotelId | Long（字符串序列化） | 酒店 ID；无候选或未填酒店时为 null |
+| households[].days[].hotels[].district | String | 酒店所在区县中文名，页面展示应优先用本字段而非 city（同团期酒店 city 常同为一个地级市） |
+| households[].days[].hotels[].rooms[].roomCount | int | 间数 |
+
+#### 请求示例
+
+```
+GET /v3/admin/order/group-batch/2100856430494973953/requirement/hotel-households
+Authorization: Bearer {token}
+```
+
+无请求体。
+
+#### 响应示例
+
+（按 VO 字段契约构造，非测试服抓包实测）
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "groupBatchId": "2100856430494973953",
+    "departDate": "2026-09-12",
+    "householdCount": 10,
+    "countedHouseholdCount": 9,
+    "households": [
+      {
+        "orderId": "2101506167043985410",
+        "orderNo": "GT-26-0081",
+        "customerName": "张三",
+        "participantCount": 3,
+        "consultantId": "10086",
+        "consultantName": "李定制",
+        "status": "DONE",
+        "statusName": "已完成",
+        "countedInSummary": true,
+        "remark": "希望安排有窗房间",
+        "specialTags": ["连通房"],
+        "returnRemark": null,
+        "returnedAt": null,
+        "days": [
+          {
+            "dayNumber": 1,
+            "stayDate": "2026-09-12",
+            "customerSelfBooked": false,
+            "hotels": [
+              {
+                "hotelId": "3001000000000000005",
+                "hotelName": "海堂酒店",
+                "city": "呼伦贝尔市",
+                "district": "海拉尔区",
+                "totalRoomCount": 2,
+                "rooms": [{"roomTypeId": "1001", "roomTypeName": "亲子房", "roomCategory": "PARENT_CHILD", "roomCategoryName": "亲子房", "roomCount": 2}]
+              }
+            ]
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+#### 空数据 / 降级响应
+
+该户尚未提交需求时 `status` 为 null、`days` 为空列表（不是缺少该户，仍会出现在 `households` 中，仅 `countedInSummary=false`）。
+
+#### 错误响应
+
+groupBatchId 路径段整体消失时的实际报错（本次事故复现的原样响应，两段字面量拼接后不匹配任何映射）：
+
+```json
+{"code": 404, "message": "接口不存在: GET /v3/admin/order/group-batch/requirement/hotel-households", "data": null, "success": false}
+```
+
+团期不存在：
+
+```json
+{"code": 589500, "message": "团期不存在", "data": null, "success": false}
+```
+
+无权限：
+
+```json
+{"code": 589507, "message": "无操作权限（当前角色未授予团期权限，或该团期不在您名下）", "data": null, "success": false}
+```
+
+#### 业务边界
+
+- 与「全团需求汇总」判权同码：`group-batch:view`。
+- `groupBatchId` 路径段一旦缺失（不是格式错，而是整段消失），会命中 404 而不是 400——这与另外两个端点的失败形态不同，是「哪个路径段消失」决定的，不是接口行为不一致。
+
+### 3. 读团期正式用车需求
+
+`GET /v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement`
+
+**VO**: 无独立请求体（仅路径参数）→ `GroupVehicleRequirementRespVO`
+
+#### 使用场景
+
+团期详情页「查看需求 · 用车」板块，展示团期管理员已确认/正在编辑的正式用车需求（乘车分组、逐日人数、审核留痕），以及配车计划刷新的只读观测状态。
+
+#### 入参字段表
+
+| 字段 | 位置 | 类型 | 必填 | 说明 |
+|---|---|---|---|---|
+| groupBatchId | Path | Long | 是 | 团期 ID（雪花 id）。同上，是本次报错的病灶字段 |
+
+#### 出参字段表
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| requirementId | Long（字符串序列化） | 正式需求主键 |
+| groupBatchId | Long（字符串序列化） | 团期聚合主键 |
+| status | String | DRAFT/CONFIRMED/DISPATCHED/DONE/PENDING_RECONFIRM/CANCELLED |
+| version | Integer | 版本号（下次提交须回传做乐观锁） |
+| remark | String | 整份备注；撤回/免车会把那次操作追加进来，不覆盖原备注 |
+| confirmedBy | String | 整份确认人；DRAFT 时为 null |
+| confirmedAt | LocalDateTime | 整份确认时间；DRAFT 时为 null |
+| planRefreshState | String | 配车刷新状态原值：null=从未登记过刷新（多数团期正常态）/PENDING/DONE/FAILED |
+| planRefreshStalled | Boolean | 刷新是否已停滞、不会自愈（恒非 null）；true=必须有人处置 |
+| planRefreshStalledReason | String | 停滞归因：STATE_FAILED/COMMAND_FAILED/TIMEOUT；未停滞为 null |
+| planRefreshReplayExhausted | Boolean | 人工重投额度是否已耗尽（恒非 null） |
+| groups[].groupCode | String | 分组键，直接作为车费 alloc_group |
+| groups[].days[].headcount | Integer | 该组该日用车人数（乘车人数，非户数） |
+| groups[].days[].memberOrderCount | Integer | 当日成员户数，供填人数时对照 |
+
+#### 请求示例
+
+```
+GET /v3/admin/order/group-batch/2100856430494973953/vehicle-requirement
+Authorization: Bearer {token}
+```
+
+无请求体。
+
+#### 响应示例
+
+（按 VO 字段契约构造，非测试服抓包实测）
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "requirementId": "1867000000101",
+    "groupBatchId": "2100856430494973953",
+    "status": "CONFIRMED",
+    "version": 3,
+    "remark": "全程 33 座",
+    "confirmedBy": "10086",
+    "confirmedAt": "2026-09-14T10:30:00",
+    "planRefreshState": null,
+    "planRefreshReplayCount": null,
+    "blockedStage": null,
+    "planRefreshStalled": false,
+    "planRefreshStalledReason": null,
+    "planRefreshTimeoutAt": null,
+    "planRefreshReplayExhausted": false,
+    "groups": [
+      {
+        "groupId": "1867000000009",
+        "groupCode": "BUS",
+        "vehicleType": "35座大巴",
+        "serviceStartDate": "2026-09-12",
+        "serviceEndDate": "2026-09-16",
+        "days": [{"tripDate": "2026-09-12", "headcount": 9, "memberOrderIds": ["2101506167043985410"], "memberOrderCount": 3}]
+      }
+    ]
+  }
+}
+```
+
+#### 空数据 / 降级响应
+
+该团期尚未形成正式需求时接口返回 `data = null`（`GroupBatchRequirementController` 方法 javadoc 原文：「读团期正式用车需求（未形成时返回 null；带配车刷新状态只读投影）」），不是报错——编辑页首次打开就是这个状态，前端应按空态渲染而不是当异常处理。
+
+#### 错误响应
+
+groupBatchId 路径段为空串时的实际报错（本次事故复现的原样响应）：
+
+```json
+{"code": 400, "message": "参数 groupBatchId 格式错误，请检查后重试", "data": null, "success": false}
+```
+
+团期不存在：
+
+```json
+{"code": 589500, "message": "团期不存在", "data": null, "success": false}
+```
+
+无权限：
+
+```json
+{"code": 589507, "message": "无操作权限（当前角色未授予团期权限，或该团期不在您名下）", "data": null, "success": false}
+```
+
+#### 业务边界
+
+- 判权码与前两个端点不同：本端点用 `group-batch:demand:confirm`，而不是 `group-batch:view`；三条接口不是同一权限码守卫的，前端如需按权限隐藏 Tab 内容，要分别判断。
+- `status` 不是恒定值，`PUT`/`withdraw`/`waive` 各自会把它改成不同的值，前端不要假设「有数据就是 CONFIRMED」。
+- `planRefreshStalled=true` 时应引导「联系后台排查」，`planRefreshReplayExhausted=true` 时再点确认只会收到 809210，与本次问题无关但同属该接口只读契约，一并列出供前端识别。
+
+## 四、契约约束与正确调用方式
+
+| 场景 | 结果 |
+|---|---|
+| ✅ 用当前团期真实数字 id 拼接 | `/v3/admin/order/group-batch/2100856430494973953/requirement-summary` → 200 |
+| ❌ id 为空串，路径只少一段 | `/v3/admin/order/group-batch/requirement-summary` → 400『参数 groupBatchId 格式错误』，`requirement-summary` 落进了 `groupBatchId` 位 |
+| ❌ id 为空串，路径中间少一段 | `/v3/admin/order/group-batch/requirement/hotel-households` → 404『接口不存在』，两段字面量直接拼接，不匹配任何映射 |
+
+### 发起请求前的必要动作
+
+前端在这三个组件的请求 watcher 里，发起请求前必须先判断 `groupBatchId` 是否为空/`undefined`，为空时直接 `return`，不要依赖 URL 层面的容错——同一路径下不同位置的空段，服务端表现不同（一种落成合法但类型错误的字符串触发 400，另一种导致整条路径不匹配触发 404），两种表现都不能被前端当作可忽略的静默失败来处理。keep-alive 缓存页在路由离开后仍存活，是触发这一问题的必要条件，仅靠「首次挂载时判空」不足以覆盖切走再切回的场景。
+
+## 五、数据库行为
+
+本次三条接口均为只读 GET，均无数据库写操作，无字段/索引/事务变更。
+
+## 六、边界行为
+
+- 未登录 → 401（网关拦截）。
+- `groupBatchId` 路径段为空串/非数字字符串 → 400『参数 groupBatchId 格式错误，请检查后重试』。
+- `groupBatchId` 路径段整体缺失，落地路径与任何 `@GetMapping` 都不匹配 → 404『接口不存在』。
+- 团期不存在 → 589500。
+- 当前角色未持对应权限码，或该团期不在本人名下 → 589507（三条接口分持 `group-batch:view` / `group-batch:view` / `group-batch:demand:confirm` 两种权限码，见各自「接口详情·业务边界」）。
+- 该团期尚未形成正式用车需求时，`GET vehicle-requirement` 返回 `data=null`，不是 404/500。
+
+## 六.5 枚举
+
+### status（`GroupVehicleRequirementRespVO.status`）
+
+**所属字段**: `data.status` | **类型**: `String`
+
+| 值 | 说明 |
+|---|---|
+| DRAFT | 草稿；`PUT`/`withdraw` 后均落此值 |
+| CONFIRMED | 已确认；`waive`（整团免车）后也落此值 |
+| DISPATCHED | 已配车 |
+| DONE | 已完成 |
+| PENDING_RECONFIRM | 受控重开窗口内的中间态 |
+| CANCELLED | 已取消 |
+
+### status（`GroupHotelHouseholdsRespVO.HouseholdItem.status`，需求状态编码 RequirementStatus）
+
+**所属字段**: `data.households[].status` | **类型**: `String`（该户尚未提交需求时为 null）
+
+| 值 | 说明 |
+|---|---|
+| PENDING_REVIEW | 待审核 |
+| PENDING | 待处理 |
+| PROCESSING | 处理中 |
+| DONE | 已完成 |
+| REJECTED_TO_CONSULTANT | 打回定制师 |
+| REJECTED_TO_ADMIN | 打回管理员 |
+
+## 六.6 修改前后对比
+
+本文档不涉及接口契约改造（三条端点均为「复用不改」），无字段级契约对比；以下是前端实现层面的行为级对比。
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|---|---|---|
+| 团期详情页切换到其他路由（如消息中心）后，详情页仍在 keep-alive 缓存中存活 | 「查看需求」Tab 下三个子组件的 watcher 用塌缩为空串的 groupBatchId 重放请求，弹出 3 条报错（2 个 400 + 1 个 404） | 请求前先判断 groupBatchId 是否为空，为空直接跳过 watcher 回调，不发起请求，不报错 |
+
+## 六.7 影响评估
+
+- 是否破坏向后兼容：否，接口契约本身未改动。
+- 影响范围：仅限团期详情页「查看需求」Tab 下依赖反应式 `groupBatchId` 的组件，在 keep-alive 缓存页被切走后再次触发 watcher 的场景；正常打开、停留、直接操作详情页不受影响。
+- 前端 workaround 清理点：无——这是需要新增的判空守卫，不是要撤销的旧代码。
+
+## 七、不影响范围
+
+- 后端代码：本次零改动。
+- 数据库 schema：无变更。
+- 网关路由：三条端点均已在既有 `/v3/admin/**` 通配路由内，本次事故期间 hl-gateway 两实例 0 条路由未命中记录。
+- 团期详情页正常打开、停留、直接操作时的行为：不触发本问题，仅路由切走再重放的场景触发。
+- `DisbandBanner` 等已有判空守卫组件的行为：不受影响，本次事故期间全程 200。
+- 三条接口在非空 `groupBatchId` 场景下的既有契约与行为：未变化。
+
+## 八、测试环境已验证
+
+真实日志（✓ = 已实测）：
+
+```
+2026-09-22 09:06:44 order-v3(8186) WARN GlobalExceptionHandler - 参数类型错误: param=groupBatchId, value=requirement-summary, requiredType=Long ✓
+2026-09-22 09:06:44 order-v3(8186) WARN org.springframework.web.servlet.PageNotFound - No mapping for GET /v3/admin/order/group-batch/requirement/hotel-households ✓
+2026-09-22 09:06:44 order-v3(8186) WARN GlobalExceptionHandler - No handler found: GET /v3/admin/order/group-batch/requirement/hotel-households ✓
+2026-09-22 09:06:50 order-v3(8086) WARN GlobalExceptionHandler - 参数类型错误: param=groupBatchId, value=vehicle-requirement, requiredType=Long ✓
+2026-09-22 09:06:48 同一时段带真实 groupBatchId 的请求全部成功 ✓
+hl-gateway 两实例 0 条路由未命中记录 ✓
+```
+
+验证团期：`groupBatchId=2100856430494973953`。
+
+前端产物级取证（测试服 `/var/www/hl-admin/assets`，2026-09-22 06:28 部署）：
+
+- `order-v2/batch/detail/index.vue` 的 id `computed` 反应式推导逻辑 ✓
+- `/notification/my-messages` 路由 meta 为 `keepAlive/hidden/noTabs` ✓
+- `RoomSummarySection`/`RoomHouseholdsSection`/`GroupVehicleRequirementSection` 三个 watcher 缺空值守卫 ✓
+- `DisbandBanner` 组件已有 `if (!props.groupBatchId) return;` 守卫，同页阳性对照 ✓
+
+源码引用（`origin/dev-v3`）：
+
+```
+GroupBatchQueryController.java:108              GET /v3/admin/order/group-batch/{groupBatchId}（A2团期详情）存在，是空 id 被误路由到的落点 ✓
+GroupBatchRequirementController.java:79-86      GET .../requirement-summary 端点存在，判权 group-batch:view ✓
+GroupBatchRequirementController.java:102-112    GET .../requirement/hotel-households 端点存在，判权 group-batch:view ✓
+GroupBatchRequirementController.java:219-226    GET .../vehicle-requirement 端点存在，判权 group-batch:demand:confirm ✓
+GlobalExceptionHandler.java                     MethodArgumentTypeMismatchException → 400『参数%s格式错误』 ✓
+GlobalExceptionHandler.java                     NoHandlerFoundException → 404『接口不存在』 ✓
+GroupBatchErrorCode.java:15                     589500 团期不存在 ✓
+GroupBatchPermissionGuard.java:50               PERMISSION_VIEW = "group-batch:view" ✓
+GroupBatchPermissionGuard.java:96               PERMISSION_DEMAND_CONFIRM = "group-batch:demand:confirm" ✓
+GroupVehicleRequirementRespVO.java              status 枚举、配车刷新观测块字段定义 ✓
+GroupHotelHouseholdsRespVO.java                 households/days/hotels/rooms 字段结构 ✓
+GroupRequirementSummaryRespVO.java              dailyRoomBreakdown/vehicleSeatSummary/orderSpecialTags 字段结构 ✓
+```
+
+【需确认】未取证项：同页 `confirm-check`/`orders`/`status-logs` 三个 Tab 本次未复现报错，是否另有 `active` 门控或取值路径不同，属前端待排查项，本文档未验证，不作为确认结论。
+
+## 十、相关文档
+
+- 全团需求汇总完整历史契约：`changelogs-v2/2026-09/10_7316_团期全团需求汇总补权限码与在团口径-结算汇总已核单数纠正-修改接口-管理后台.md`
+- 团期正式用车需求完整历史契约：`changelogs-v2/2026-09/15_7441_团期正式用车需求声明-新增接口-管理后台.md`
+- 团期子订单订房记录完整历史契约：`changelogs-v2/2026-09/20_8046_团期用房新增子订单订房记录接口-新增接口-管理后台.md`
+
+## 关联 / 联系人
+
+### 链接
+
+- Issue：无（纯前端缺陷，无后端工单号）
+- PR：无（本次零后端代码改动，未产生新 PR）
+
+### 联系人
+
+- **后端负责人**: @wx
@@ -0,0 +1,149 @@
+---
+schema: hl-changelog/v2
+ticket: "frontend"
+title: "整团名单速览与子订单两张表：联系人列取 customerName、房型列取 roomTypeName"
+consumer: admin
+author: "jw(GIT)"
+change_type: "前端缺陷"
+backend_status: "not_required"
+gateway_status: "not_required"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "cf37e7f6b46379dc8e5852a3730bd3e43b6a9d63"
+target_release: "v2.1"
+verified_at: "2026-09-22"
+status_note: "2026-09-22 页面核对：团期详情的「整团名单速览」与「子订单」两张表存在同样两处显示问题——①「子订单 / 联系人」列的联系人行显示占位符「—」；②「房型 / 间数」列的房型显示英文枚举码（如 KING）。两张表吃的是同一个后端接口 GB-ADM-003 GET /v3/admin/order/group-batch/{groupBatchId}/orders，同源所以同病。后端零改动：同日 TEST 实测团期 2101506167098511362 全量 12 户，customerName 12/12 有值（张三/王五/李玉/张德发/王芳/阿宾等），roomType 与 roomTypeName 12/12 均有值且翻译正常（KING → 豪华大床）。前端把联系人列对齐到 customerName、房型列对齐到 roomTypeName 即可。排查提示：同一响应里 travelers 12/12 为空数组、travelerInfoComplete 12/12 为 false，若联系人是从出行人明细推导的，出行人未填时就会恒显「—」，而 customerName 与出行人资料无关、一直有值。 前端已交付(cf37e7f6):renderOrderContactCell 改 customerName 优先 contactName 回落、subOrderRoomText 改 roomTypeName 优先 roomType 回落不建映射,RosterTable(速览+子订单 Tab 共用)与 RequirementTab 一处修全;helper 两 spec 补例。"
+updated_at: "2026-09-22"
+base: dev-v3
+---
+
+# 整团名单速览 / 子订单: 联系人列与房型列取值订正
+
+> **服务**: hl-order-service-v3（**后端零改动**）
+> **页面**: 管理后台 → 团期订单 → 团期详情 → 「整团总览」Tab 的整团名单速览 与 「子订单」Tab 的子订单表
+> **接口**: `GET /v3/admin/order/group-batch/{groupBatchId}/orders`（GB-ADM-003 / A3）
+> **日期**: 2026-09-22
+> **影响范围**: 仅前台渲染取值；无端点、无出入参、无路由、无 DDL 变化
+
+---
+
+## ⚠️ 关键变化
+
+- **两张表是同一个接口**，所以同一个毛病出现两次：整团名单速览与子订单表都消费 GB-ADM-003，改的时候两处一起改，别只改一处。
+- **后端不需要任何改动**。这两个字段一直都在返回，且 2026-09-22 TEST 实测**全量有值**——问题在前端取了别的字段。
+
+---
+
+## 一、两处问题
+
+| # | 列 | 页面现在显示 | 应该显示 | 接口字段 |
+|---|---|---|---|---|
+| 1 | 子订单 / 联系人（第二行的联系人） | `—`（占位符） | 客户姓名，如 `张三` | `customerName` |
+| 2 | 房型 / 间数 里的「房型」 | 英文枚举码，如 `KING` | 中文房型名，如 `豪华大床` | `roomTypeName`（当前多半取了 `roomType`） |
+
+---
+
+## 二、实测证据
+
+TEST 环境 `api.test.1814.love:9443`，2026-09-22，团期 `2101506167098511362`（jw测试产品 · 第1期 jw测试1期），`GET /v3/admin/order/group-batch/2101506167098511362/orders?pageSize=200`，`total=12`：
+
+```
+customerName 为空的户数:  0 / 12
+roomTypeName 为空的户数:  0 / 12
+roomType     为空的户数:  0 / 12
+
+roomType -> roomTypeName 取值分布:
+  'KING' -> '豪华大床'  x12        （翻译正常，没有回落英文的情况）
+```
+
+单户原始响应片段：
+
+```json
+{
+  "orderId": "2101506167043985410",
+  "orderNo": "HL20260920105808925",
+  "teamNo": "26-3627",
+  "customerName": "张三",
+  "participantCount": 6,
+  "tierCode": "2A2C2Y",
+  "tierName": "2成人2儿童2幼童",
+  "roomCount": 2,
+  "roomType": "KING",
+  "roomTypeName": "豪华大床",
+  "contactPhone": "133****2212",
+  "travelerInfoComplete": false,
+  "travelers": []
+}
+```
+
+前 6 户逐户对照（联系人全部有值，与页面上的 `—` 直接矛盾）：
+
+```
+HL20260920105808925  联系人='张三'    roomCount=2  roomType='KING'  roomTypeName='豪华大床'
+HL20260920110233355  联系人='王五'    roomCount=2  roomType='KING'  roomTypeName='豪华大床'
+HL20260920110625528  联系人='李玉'    roomCount=2  roomType='KING'  roomTypeName='豪华大床'
+HL20260921160904989  联系人='张德发'  roomCount=2  roomType='KING'  roomTypeName='豪华大床'
+HL20260921161004158  联系人='王芳'    roomCount=2  roomType='KING'  roomTypeName='豪华大床'
+HL20260921161039050  联系人='阿宾'    roomCount=2  roomType='KING'  roomTypeName='豪华大床'
+```
+
+---
+
+## 三、排查提示: 联系人为什么会恒显「—」
+
+同一次响应里还有两个数：**`travelers` 12/12 都是空数组**，**`travelerInfoComplete` 12/12 都是 `false`**（这个团的出行人资料还没填）。
+
+如果联系人这一行是从出行人明细里推导的（例如取 `travelers[0]` 的姓名），那么只要该户出行人没录，页面就会恒显 `—`，与客户姓名有没有值无关。而 `customerName` 取的是订单主表的客户姓名，**与出行人资料完全无关**，本团 12/12 都有值。
+
+接口里没有名为 `contact` / `linkman` 之类的字段，**联系人就是 `customerName`**。同一行若要显示联系方式，用 `contactPhone`（已脱敏，前3后4，本团 12/12 有值）。
+
+---
+
+## 四、房型列的两个限定
+
+1. **要用 `roomTypeName`，不要自建映射。** `roomTypeName` 是后端把 `roomType` 按「、」逐段走 `room_category` 字典翻译后拼回的结果（多段房型会返回成 `标间、大床房` 这样）。字典不可达时它会**回落成原始英文码**——此时前端直显即可，不要另建一套前端映射表兜底（沿用 `16_frontend_前台整团名单速览补状态与需求审核列` 定下的口径：中文名一律由后端给，前端不自建映射）。
+
+2. **房型三字段受 `includeNeeds` 开关控制。** `includeNeeds` **缺省为 `true`**，此时才返回 `roomCount` / `roomType` / `roomTypeName` / `specialNeeds`。同日实测显式传 `includeNeeds=false` 时，这四个字段全部为 `null`，而 `customerName` 仍有值：
+
+```
+includeNeeds=false 时：
+  roomCount = None    roomType = None    roomTypeName = None    specialNeeds = None
+  customerName = '张三'
+```
+
+所以「房型列整列为空」与「房型列显示英文码」是两回事：前者去看请求有没有显式传 `includeNeeds=false`，后者才是本条说的取值取错。间数列用 `roomCount`（来源需求里的逐段房数，缺需求行时回落 `ceil(人数/2)`）。
+
+---
+
+## 五、改完后这两张表的完整字段对照
+
+| 列 | 字段 | 备注 |
+|---|---|---|
+| 子订单编号 | `orderNo` | 另有团号 `teamNo`（订金支付成功后才生成，未付订金为 `null`） |
+| 联系人 | `customerName` | 本条订正项 |
+| 联系方式 | `contactPhone` | 脱敏，前3后4 |
+| 套餐 / 档位 | `tierName` | 码为 `tierCode` |
+| 人数 | `participantCount` | 成人+儿童+幼童+婴儿 |
+| 房型 | `roomTypeName` | 本条订正项，需 `includeNeeds=true`（缺省即是） |
+| 间数 | `roomCount` | 需 `includeNeeds=true` |
+| 特殊需求 | `specialNeeds` | 需 `includeNeeds=true` |
+| 状态 | `orderStatusName` | 枚举外回落 `orderStatus` |
+| 需求审核（房 / 车） | `hotelRequirementStatusName` / `vehicleRequirementStatusName` | 取值：待房务配 / 配房中 / 配房完成 / 待审核 / 驳回 |
+| 定制师 | `consultantName` | — |
+| 金额 | `totalPrice` / `paidAmount` / `balanceAmount` | 字符串两位小数 |
+
+---
+
+## 六、不影响范围
+
+- 后端无需发版：GB-ADM-003 的路径、入参、出参、返回值一个都没变，其它调用方不受影响。
+- 不涉及权限码、错误码、字典、DDL。
+- 团期详情其它 Tab、子订单详情页、定制师待办、抢单池均不受影响。
+
+---
+
+## 关联 / 联系人
+
+- 后端: jw
+- 前端: 待认领（`frontend_status: pending`）
+- 同接口的前序交接件: `changelogs-v2/2026-09/16_frontend_前台整团名单速览补状态与需求审核列-前端优化-管理后台.md`（该条已确认「联系人 `customerName`」「房型 `roomTypeName` / `roomCount`」是原型要求的列与字段）
@@ -0,0 +1,161 @@
+---
+schema: hl-changelog/v2
+ticket: "frontend"
+title: "查看需求 Tab 的子订单表：补齐到子订单表的列集，并订正联系人与房型两列取值"
+consumer: admin
+author: "jw(GIT)"
+change_type: "前端缺陷"
+backend_status: "not_required"
+gateway_status: "not_required"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "369ed5b48dbeb67d6c68ee2946c4106362c012e9"
+target_release: "v2.1"
+verified_at: "2026-09-22"
+status_note: "2026-09-22 页面核对：团期详情「查看需求」Tab 的子订单表有三处问题——①「子订单 / 联系人」列的联系人行显示占位符「—」，应显示 customerName；②「房型 · 间数」的房型显示英文枚举码（如 KING），应显示中文 roomTypeName；③展示数据不全，只有 子订单/联系人、套餐、人数、需求状态、操作 五列，要补齐到「子订单」表的列集（团号、房型·间数、状态、需求审核、联系电话、应收、游客、资料）。后端零改动：这张表与「子订单」表、「整团名单速览」吃的是同一个接口 GB-ADM-003 GET /v3/admin/order/group-batch/{groupBatchId}/orders，要补的列全部已在该接口返回。同日 TEST 实测团期 2101506167098511362 全量 12 户，逐列与「子订单」表现有渲染逐字吻合（团号 26-3627、应收 25920.00、游客 0 人、资料 待补 等），customerName 12/12 有值、roomTypeName 12/12 有值且翻译正常（KING → 豪华大床）。 前端已交付(369ed5b4):RequirementTab 子订单表补齐 8 列(团号/房型·间数/状态/需求审核/联系电话/应收/游客/资料),复用 RosterTable 列写法;派生「需求状态」与后端「需求审核」两列并留(产品侧已拍板);联系人/房型取值订正随 cf37e7f6 共享 helper 一并生效。"
+updated_at: "2026-09-22"
+base: dev-v3
+---
+
+# 查看需求 Tab 子订单表: 补齐列集 + 联系人与房型取值订正
+
+> **服务**: hl-order-service-v3（**后端零改动**）
+> **页面**: 管理后台 → 团期订单 → 团期详情 → 「查看需求」Tab → 顶部操作条下方的子订单表
+> **接口**: `GET /v3/admin/order/group-batch/{groupBatchId}/orders`（GB-ADM-003 / A3）
+> **日期**: 2026-09-22
+> **影响范围**: 仅前台渲染；无端点、无出入参、无路由、无 DDL 变化
+
+---
+
+## ⚠️ 关键变化
+
+- **三张表同一个接口**：「查看需求」Tab 的子订单表、「子订单」Tab 的子订单表、「整团总览」Tab 的整团名单速览，都消费 GB-ADM-003。所以「子订单」表已经渲染出来的列，「查看需求」这张表**不需要后端加任何字段就能补上**。
+- **后端不需要任何改动**。要补的列、要订正的两个字段，2026-09-22 TEST 实测**全部已在返回且有值**。
+- 本条包含三处改动：两处取值订正 + 一处补列，见下。
+
+---
+
+## 一、三个问题
+
+| # | 问题 | 页面现在 | 应该 | 接口字段 |
+|---|---|---|---|---|
+| 1 | 联系人不显示 | `—`（占位符） | 客户姓名，如 `张三` | `customerName` |
+| 2 | 房型显示英文码 | `KING` | `豪华大床` | `roomTypeName`（当前多半取了 `roomType`） |
+| 3 | 列不全 | 只有 5 列 | 补齐到「子订单」表的列集 | 见第二节 |
+
+---
+
+## 二、目标列集与字段映射
+
+以「子订单」Tab 的子订单表为准。下表的「TEST 实测值」取自同一次响应的第一户 `HL20260920105808925`，与「子订单」表页面上的渲染逐字吻合：
+
+| 列 | 接口字段 | TEST 实测值 | 「查看需求」表现状 |
+|---|---|---|---|
+| 子订单 / 联系人 | `orderNo` / `customerName` | `HL20260920105808925` / `张三` | 订单号有，**联系人缺**（问题 1） |
+| 团号 | `teamNo` | `26-3627` | **缺** |
+| 套餐 | `tierName` | `2成人2儿童2幼童` | 有 |
+| 人数 | `participantCount` | `6` | 有 |
+| 房型 · 间数 | `roomTypeName` · `roomCount` | `豪华大床` · `2` 间 | **缺**（补列时直接用 `roomTypeName`，别用 `roomType`，见问题 2） |
+| 状态 | `orderStatusName` | `定制中` | **缺** |
+| 需求审核 | `hotelRequirementStatusName` / `vehicleRequirementStatusName` | 房 `待审核` / 车 `待车队配` | **缺** |
+| 联系电话 | `contactPhone` | `133****2212` | **缺** |
+| 应收 | `totalPrice` | `25920.00` | **缺** |
+| 游客 | `travelers` 的条数 | `0` 人 | **缺** |
+| 资料 | `travelerInfoComplete` | `false` → 橙标「待补」 | **缺** |
+
+补列不需要新接口、不需要新参数：上面每一个字段都在「查看需求」这张表**当前已经在调**的那次 GB-ADM-003 响应里。
+
+---
+
+## 三、实测证据
+
+TEST 环境 `api.test.1814.love:9443`，2026-09-22，团期 `2101506167098511362`（jw测试产品 · 第1期 jw测试1期），`GET /v3/admin/order/group-batch/2101506167098511362/orders`，`total=12`。
+
+逐列取值（第一户）：
+
+```
+子订单/联系人   orderNo + customerName         = HL20260920105808925 / '张三'
+团号           teamNo                         = 26-3627
+套餐           tierName                       = 2成人2儿童2幼童
+人数           participantCount               = 6
+房型·间数       roomTypeName + roomCount       = '豪华大床' · 2 间   (roomType='KING')
+状态           orderStatusName                = 定制中
+需求审核·房     hotelRequirementStatusName     = 待审核
+需求审核·车     vehicleRequirementStatusName   = 待车队配
+联系电话        contactPhone                   = 133****2212
+应收           totalPrice                     = 25920.00
+游客           travelers 条数                  = 0
+资料           travelerInfoComplete           = False
+```
+
+全量 12 户的两个订正项：
+
+```
+customerName 为空的户数:  0 / 12
+roomTypeName 为空的户数:  0 / 12
+roomType -> roomTypeName 取值分布:  'KING' -> '豪华大床'  x12   （翻译正常，无回落英文）
+```
+
+前 6 户联系人：`张三` / `王五` / `李玉` / `张德发` / `王芳` / `阿宾` —— 与页面上的 `—` 直接矛盾。
+
+---
+
+## 四、排查提示: 联系人为什么会恒显「—」
+
+同一次响应里还有两个数：**`travelers` 12/12 都是空数组**，**`travelerInfoComplete` 12/12 都是 `false`**（这个团的出行人资料还没录，所以「游客」列是 `0 人`、「资料」列是橙标 `待补`）。
+
+如果联系人这一行是从出行人明细推导的（例如取 `travelers[0]` 的姓名），那么只要该户出行人没录，页面就恒显 `—`，与客户姓名有没有值无关。`customerName` 取的是订单主表客户姓名，**与出行人资料无关**，本团 12/12 都有值。
+
+接口里没有名为 `contact` / `linkman` 之类的字段，**联系人就是 `customerName`**；联系方式用 `contactPhone`（已脱敏，前3后4）。
+
+---
+
+## 五、两个查询开关（补列前先确认请求怎么发的）
+
+| 开关 | 缺省 | 管的字段 |
+|---|---|---|
+| `includeNeeds` | `true` | `roomCount` / `roomType` / `roomTypeName` / `specialNeeds` |
+| `includeTravelers` | `true` | `travelers[]`（「游客」列的条数从这里来） |
+
+两个缺省都是 `true`，前端不传即可。同日实测：显式传 `includeNeeds=false` 时 `roomCount` / `roomType` / `roomTypeName` / `specialNeeds` **四个字段全部为 `null`**，而 `customerName` 仍有值。
+
+所以「房型列整列空白」与「房型列显示英文码」是两回事：前者去看请求是不是显式传了 `includeNeeds=false`，后者才是本条问题 2 说的取值取错。
+
+另外 `roomTypeName` 是后端把 `roomType` 按「、」逐段走 `room_category` 字典翻译后拼回的（多段房型形如 `标间、大床房`）；字典不可达时它会**回落成原始英文码**，此时前端直显即可，**不要自建映射表兜底**（沿用 `16_frontend_前台整团名单速览补状态与需求审核列` 定下的口径：中文名一律由后端给）。
+
+---
+
+## 六、「需求状态」与新增的「需求审核」是两个不同的东西
+
+「查看需求」这张表现有的「需求状态」列（绿标 `已齐备`）**不是后端字段**——后端 `RequirementStatus` 的五个展示名是 `待房务配 / 配房中 / 配房完成 / 待审核 / 驳回`，没有「已齐备」。它是前端按预检结果自算的派生状态（该户没出现在 `GET .../requirement/confirm-check` 的 `missing` / `vehicleMissing` 清单里即判为齐备）。
+
+补进来的「需求审核」列则是后端的真实状态（房 `hotelRequirementStatusName` / 车 `vehicleRequirementStatusName`）。两者语义不同：前者回答「这户还缺不缺东西、挡不挡整团确认」，后者回答「这户的房/车需求流转到哪一步了」。
+
+补列后两列会并排出现。是两列都留，还是只留一列，由产品定——**后端两种都支持，字段都在，不需要改动**。
+
+---
+
+## 七、这张表特有的元素照旧保留
+
+补列不影响「查看需求」Tab 该有的交互：
+
+- 首列复选框 + 顶部「打回选中户」：打回接口 `POST /v3/admin/order/group-batch/{groupBatchId}/requirement/reject`，必填 `orderIds`（1~200 户，服务端去重）与 `reason`（≤500 字），可选 `resourceType`（`HOTEL` / `VEHICLE` / `ALL`，缺省 `ALL`）。每行的 `orderId` 就在同一份响应里。
+- 操作列「联系定制师」「进入」：`consultantName` 与 `orderId` 均在响应里；未读角标用 `groupChatUnreadCount`（user-service 不可达时降级为 0，不阻断名单主数据）。
+- 顶部预检、`刷新预检`、`整团确认需求` 走 `GET .../requirement/confirm-check` 与 `POST .../requirement/confirm`，与本条无关，不动。
+
+---
+
+## 八、不影响范围
+
+- 后端无需发版：GB-ADM-003 的路径、入参、出参、返回值一个都没变，其它调用方不受影响。
+- 不涉及权限码、错误码、字典、DDL。
+- 「子订单」Tab 与「整团名单速览」的联系人、房型两列有同样的毛病，另见同日交接件 `22_frontend_整团名单速览与子订单表联系人与房型列取值订正`；本条只管「查看需求」Tab 这一张表。
+- 团期详情其它 Tab、子订单详情页、定制师待办、抢单池均不受影响。
+
+---
+
+## 关联 / 联系人
+
+- 后端: jw
+- 前端: 待认领（`frontend_status: pending`）
+- 同接口的前序交接件: `changelogs-v2/2026-09/16_frontend_前台整团名单速览补状态与需求审核列-前端优化-管理后台.md`
@@ -0,0 +1,160 @@
+---
+schema: hl-changelog/v2
+ticket: "frontend"
+title: "查看需求页：订单号改显团号（5 处可立即改）+ 接送机逐行确认按钮 + 正式用车需求弹窗默认分组/默认日期/按钮文案"
+consumer: admin
+author: "wx(GIT)"
+change_type: "前端缺陷"
+backend_status: "not_required"
+gateway_status: "not_required"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "91d476c9324f032f8160df73f937d6dfad69780a"
+target_release: "v2.1"
+verified_at: "2026-09-22"
+updated_at: "2026-09-22"
+base: dev-v3
+status_note: "2026-09-22 wx 在「团期详情 → 查看需求」页逐屏截图提了 8 个问题。对 origin/dev-v3(cf9dc85a4) 与 hl-ui origin/v2.1(590c1155) 逐项查证后拆成两边：本条只收录后端零改动、今天就能动手的 5 项；另 3 项（另 5 处团号渲染点需后端补 teamNo、车侧未提交户后端根本不返回、接送机批量确认端点不存在）后端有硬缺口，已建 wx/HL#8195 处理，本条不含。查证依据：①名单表/打回弹窗/乘车户下拉三处的数据源 GB-ADM-003 GET /v3/admin/order/group-batch/{groupBatchId}/orders 已返回 teamNo（GroupBatchOrderItemRespVO.java:34，格式 26-0001，未付订金为 null）；②逐户接送机确认可直接调已上线端点 POST /v3/admin/order/{id}/vehicle-requirement/dispatch?kind=TRANSFER（VehicleRequirementAdminController.java:77，请求体 DispatchReqVO 只有 dispatchRemark）；③GroupVehicleRequirementEditModal.vue:434 新建时 form.groups 恒为空数组、:407-408 两个日期恒为 null，blankGroup() :401-416 只被「添加分组」按钮调用；④GroupVehicleRequirementSection.vue:19 文案「新建正式需求」。UI 库是 Naive UI 不是 Element。 | 2026-09-22 mmg 交付:团号上行(teamNo,null 显 — 勿兜底 orderNo)+删独立团号列;TRANSFER 待审核行逐行「确认」显式传 kind=TRANSFER;新建默认一空白分组+默认日期取团期 departDate/endDate(预填展开逐日行);按钮文案改「新增正式行程用车需求」;另 3 项硬缺口归 wx/HL#8195 不含本条"
+---
+
+# 查看需求页：订单号改显团号 + 接送机逐行确认 + 正式用车需求弹窗三处默认值与文案
+
+> **服务**: hl-order-service-v3（**后端零改动**）
+> **页面**: 管理后台 → 团期订单 → 团期详情 → 「查看需求」Tab
+> **日期**: 2026-09-22
+> **影响范围**: 仅前台渲染与既有端点调用；无新端点、无出入参变化、无路由、无 DDL
+
+---
+
+## ⚠️ 关键变化
+
+- **本条 5 项全部后端零改动**，涉及的字段与端点今天都在测试服上返回真实值，逐条给了查证出处。
+- **本条只覆盖这 5 项**。wx 当天提的另外几项后端有硬缺口（响应里压根没有那个字段、那个端点不存在），记在 `wx/HL#8195`，不在本条范围——下面第六节把「哪些不在本条」写清楚了，免得照着改时撞上空字段。
+- **UI 库是 Naive UI**（`n-data-table` / `n-modal` / `n-date-picker`），不是 Element。
+- **活跃分支是 `origin/v2.1`**，不是 `master`。在 `master` 上 grep 会得到可信但错误的 0 命中（阳性对照：`git grep '#8151' origin/master -- src` → 0，换 `origin/v2.1` → 19）。
+
+---
+
+## 一、订单号改显团号（本页 5 处可立即改）
+
+wx 原话：**「这个页面所有显示订单号的地方都改为显示团号」**。
+
+本页 `orderNo` 共 11 个可见渲染点，其中 **5 处的数据源已经返回 `teamNo`**，可以现在就改：
+
+| # | 文件:行 | 现在渲染 | 数据源 |
+|---|---|---|---|
+| 1 | `RequirementTab.vue:442-452` + `_shared/renderCells.js:19,21` | 名单表「子订单 / 联系人」列上行 `r.orderNo`，以及 hover 的 `title: r.orderNo` | GB-ADM-003 `orders` |
+| 2 | `RequirementRejectModal.vue:129` | 打回弹窗「已选 N 户」标签 `${o.contactName \|\| '未命名'} · ${o.orderNo \|\| '无订单号'}` | 同上（props 传入） |
+| 3 | `GroupVehicleRequirementEditModal.vue:289` | 乘车户下拉 label `o.customerName \|\| o.contactName \|\| o.orderNo \|\| String(o.orderId)` | 同上（props 传入） |
+
+`teamNo` 的契约（`GroupBatchOrderItemRespVO.java:34`，已在返回）：
+
+| 项 | 取值 |
+|---|---|
+| 字段名 | `teamNo` |
+| 类型 | `String` |
+| 格式 | `26-0001`（年份后两位 + `-` + 4 位）。生成算法 `GroupCodeService.java:30-37` 是 LCG 混淆 `(7123*seq+2731)%10000`，**刻意不连续、不可按大小排序** |
+| 粒度 | **每个子订单一个**，同团期内各户不同 |
+| 空值 | **未付订金的户为 `null`**（团号在订金支付成功那一刻才生成，`OrderStatusService.java:151` / `:356`） |
+| 兜底 | `orderV2GroupBatch.js:152` 注释明写「勿兜底成 `orderNo`/空串」；本页家族已有写法 `RosterTable.vue:62-66` 用 `r.teamNo \|\| '—'` |
+
+### ⚠️ 名单表上有一处需要你们自己定的取舍
+
+`369ed5b4`（同日交付，见 `22_frontend_查看需求Tab子订单表补齐列并订正联系人与房型-前端缺陷-管理后台.md`）刚给这张名单表**新增了一个独立的「团号」列**。若再把「子订单 / 联系人」列的上行也换成团号，同一行会出现两个相同的团号。
+
+这是这张表内部的版面取舍，归你们定。三种走法都说得通：把「子订单 / 联系人」上行换成团号并删掉独立团号列；保留独立团号列、把该列上行改成客户名；或按 wx 字面全换、接受重复。
+
+## 二、接送机逐行「确认」按钮
+
+wx 原话：**「这块需要确认接送机用车需求没有按钮」**。
+
+`VehicleHouseholdsSection.vue` 目前模板里唯一的 `n-button` 是 `:12-19` 卡右上角的「刷新」，逐行/逐户**没有任何操作按钮**（`grep '确认'` 0 命中；阳性对照：同 grep 在 `RequirementTab.vue` 命中 `:53`「整团确认需求」）。
+
+**逐户确认可以现在就接**，端点已上线：
+
+### POST /v3/admin/order/{id}/vehicle-requirement/dispatch（复用不改）
+
+| 项 | 内容 |
+|---|---|
+| 路径参数 | `id` — 子订单 ID（`Long`），取逐户卡的 `household.orderId` |
+| Query 参数 | `kind` — `TRAVEL` \| `TRANSFER`。**`@RequestParam(defaultValue = "TRAVEL")`，不显式传 `TRANSFER` 就变成确认行程用车**，务必显式传 |
+| 请求体 | `DispatchReqVO`，**只有一个字段**：`dispatchRemark`（`String`，选填，`@Size(max=500)`，"提供给房控/车队的审核意见"） |
+| 权限码 | `group-batch:demand:confirm` |
+| 副作用 | 该户该类需求 `PENDING_REVIEW → PENDING`，`vehicle_control → PENDING`（即转交车务） |
+| 出处 | `VehicleRequirementAdminController.java:77`，`DispatchReqVO.java:28` |
+
+按钮的显示条件用逐户卡上已有的 `req.kind === 'TRANSFER'` 且 `req.status === 'PENDING_REVIEW'`（`RequirementItem.status` 取值 `PENDING_REVIEW / PENDING / PROCESSING / DONE`，`GroupVehicleHouseholdsRespVO.java:105`）。
+
+### 行程用车（TRAVEL）不要加这个按钮
+
+行程用车走的是**整团一条**的结构化正式需求（`PUT .../vehicle-requirement` 全量替换），按 wx 早先的定案它本来就没有逐行确认这个动作。这一节只针对 `kind === 'TRANSFER'` 的行。
+
+## 三、正式用车需求弹窗：新建时默认带一个分组
+
+wx 原话：**「应默认有一个分组」**。
+
+`GroupVehicleRequirementEditModal.vue:434`（打开弹窗时的 `watch(() => props.show, ...)`，`:428-460`）：
+
+```js
+form.groups = (Array.isArray(req?.groups) ? req.groups : []).map(...)
+```
+
+新建时 `props.requirement` 为 `null` ⇒ `req` 为 `null` ⇒ `form.groups = []`，弹窗开出来是空的。
+
+空分组模板 `blankGroup()` 已经写好了（`:401-416`，返回 `{groupId:null, groupCode:'', vehicleType:'', serviceStartDate:null, serviceEndDate:null, seats:null, count:null, specialTags:[], remark:'', days:[]}`），当前只被「添加分组」按钮（`:209-215` → `addGroup()` `:418-420`）调用，watch 里没调。新建分支补一次 `blankGroup()` 即可。
+
+## 四、正式用车需求弹窗：两个日期默认填团期日期
+
+wx 原话：**「默认填入」**。
+
+`GroupVehicleRequirementEditModal.vue:82-89` / `:96-103` 的两个 `n-date-picker`，初始值来自 `blankGroup()` `:407-408` 的 `serviceStartDate: null, serviceEndDate: null`，全文件没有任何默认值逻辑（`new Date(` 只出现在 `:375-380` 的 `expandDates` 区间展开里）。
+
+**团期的出发日与结束日前端已经拿得到**，不需要后端补字段：
+
+| 日期 | 来源接口 | 字段 | 类型 |
+|---|---|---|---|
+| 出发日 | `GET /v3/admin/order/group-batch/{groupBatchId}`（A2 团期详情，父页面已在调） | `departDate` | `LocalDate`，形如 `2026-10-08` |
+| 结束日 | 同上 | `endDate` | `LocalDate`，形如 `2026-10-10` |
+
+出处 `GroupBatchDetailRespVO.java:183-190`（另有 `enrollDeadline` 报名截止日）。
+
+弹窗当前的 props 只有 `show / groupBatchId / requirement / orders`（`:259-267`），**拿不到日期**——父页面 `GroupVehicleRequirementSection.vue:169-175` 挂载处把团期详情里的这两个日期传下去即可。
+
+补充：「查看需求」的两个 households 读口（`requirement/hotel-households`、`requirement/vehicle-households`）目前返回 `departDate` 但**不返回** `endDate`（`GroupVehicleHouseholdsRespVO.java:36` / `GroupHotelHouseholdsRespVO.java:39`，`git grep endDate` 在这两个文件 exit=1，阳性对照同 grep 换 `departDate` 两个都命中）。走 A2 团期详情能一次拿全三个日期，是当前最省事的路。
+
+## 五、按钮文案改为「新增正式行程用车需求」
+
+wx 原话：**「改为 新增正式行程用车需求」**。
+
+`GroupVehicleRequirementSection.vue:19`：
+
+```
+{{ requirement ? '编辑正式需求' : '新建正式需求' }}
+```
+
+（按钮带 `v-if="canEdit"`，`canEdit` = `:421` `!requirement.value || status === 'DRAFT'`。）
+
+改文案会连带红两条测试：`__tests__/GroupVehicleRequirementSection.spec.js:108` 与 `:115`。
+
+同族文案是否一并对齐由你们定，wx 只点名了这一个按钮。现有的同族文案有：`GroupVehicleRequirementSection.vue:340` 头注释「data=null 显空态+「新建正式需求」」、弹窗标题 `GroupVehicleRequirementEditModal.vue:5` `title="正式用车需求编辑"`、提交按钮 `:226`「保存正式需求」、成功提示 `:495`「正式用车需求已保存」。
+
+## 六、本条不覆盖的部分（照着改会撞上空字段，先看这里）
+
+下面三项后端有硬缺口，记在 `wx/HL#8195`：
+
+| 缺口 | 具体表现 | 撞上的位置 |
+|---|---|---|
+| 另 5 处团号渲染点 | `confirm-check` 与两个 households 读口的响应里**没有 `teamNo` 字段**（`git grep teamNo` 在 `Group*HouseholdsRespVO.java` exit=1；阳性对照同 grep 换 `orderNo` 命中 4 行） | `RequirementTab.vue:73,82-83,106`、`RoomHouseholdsSection.vue:44`、`VehicleHouseholdsSection.vue:40` |
+| 车侧「未提交用车需求」的户 | 这些户**根本不在响应的 `households` 数组里**——`GroupBatchVehicleHouseholdService.java:118-122` 遍历的是「有活跃需求行的户」，不是子订单全集（房侧 `GroupBatchHotelHouseholdService.java:113-123`/`:196-201` 相反，未提交户保留空卡、`status=null`） | `VehicleHouseholdsSection.vue` 无法照 `RoomHouseholdsSection.vue:57,98` 的写法做提示 |
+| 接送机**批量**确认 | 不存在任何批量确认端点（`git grep -nE '@(Post\|Put)Mapping\("[^"]*(batch-confirm\|confirm-batch\|batch/confirm)'` 无输出；阳性对照：房务侧有 `HouseAssignmentAdminController.java:97`「批量提交配房方案」） | 多选 + 批量按钮 |
+
+⚠️ 如果前端想先用 `orderId` 回 `orders` 数组反查 `teamNo` 来绕开第一项：本页 `orders` 已在 props 里，`RequirementTab.vue:264` 已有按 `orderId` 建 Map 的先例。这条路今天就能走通，取舍归你们。
+
+---
+
+## 七、查证基线
+
+- 后端：`HL` `origin/dev-v3` HEAD `cf9dc85a4`（2026-09-22 17:33 +0800）。
+- 前端：`hl-ui` `origin/v2.1` HEAD `590c1155`（2026-09-22 18:03 读取）。
+- 分支选对的阳性对照：`git grep '#8151' origin/master -- src` → 0 命中；同命令换 `origin/v2.1` → 19 命中。`git ls-tree origin/master -- .../RequirementTab.vue .../VehicleHouseholdsSection.vue` → 空；`origin/v2.1` 两文件都在。
+- 本条所有「不存在 / 0 命中」结论都配了同形状的阳性对照，逐条写在对应小节里。
@@ -0,0 +1,282 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8123"
+title: "团期 staff 保存新增两个错误码：并发抢锁 100503 与配置位字典缺失 582117"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "not_required"
+frontend_status: "not_required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "工单 #8123 修的是团期 staff 扇出并发丢配置：两个人几乎同时保存同一团期时，两条扇出各自读到自己那一刻的整期配置、互相覆盖，结果是子订单侧留下重复行而接口两次都返 200。修法是在 saveConfig 上加订单级 @Lock4j（锁名 batch-staff:save:{productBatchId}，expire 30s，acquireTimeout 不显式设 = lock4j 默认 3s）并在锁内复读整期最新配置。由此对外多出一个此前这个端点不会返回的码 100503「资源被占用,请稍后重试」——它由 hl-common/hl-starter-protection 的 lockFailureStrategy 抛出，走 HTTP 200 不是 5xx。工单 #8148 把角色↔人员类型的判据从写死角色表改为读配置位字典（GroupBatchStaffSlotResolver#slotTypesOf），随之必须区分两种「查不到归属位」：DRIVER / OTHER 这类结构性不参与配置位的照旧放行，而本该有位却查不到的（运维把 GUIDE / LEADER / PHOTOGRAPHER 从某个仍非空的配置位字典里删掉）必须拒绝，否则该角色的 582114 会当场静默失效、任意人员类型都能落库并返 200，一直到结算对账才发现人岗对不上。这一支落新码 582117。生产代码由 PR #8177 合入 dev-v3（提交 bfc10966e），后续订正 PR #8186 / #8197 / #8199，取证载体 PR #8243。2026-09-23 测试服活体已确认字节就位：order-v3 双实例（8086 / 8186，jar 与磁盘同 inode）的进程字节里 STAFF_ROLE_SLOT_MISSING、RESOURCE_LOCKED、LockFailureExceptionHandler、LockFailureStrategy、slotTypesOf、GroupBatchStaffLockNames、participatesInSlotsByFallback 全部命中。acquireTimeout 的运行时值为默认 3000ms，判据是四个配置来源全零命中且各自带阳性对照：Nacos hl-order-service-v3-dev.yml（1256 字节，阳性对照 spring / datasource 各命中）、jar 内 BOOT-INF/classes/application.yml（6064 字节，阳性对照 spring 命中 4）、仓库 src/main/resources、两个进程的 JVM 启动参数与环境变量（阳性对照：每个进程 16 条启动参数）；lock4j jar 版本 2.2.7，与源码 Lock4jProperties#acquireTimeout 默认值 3000L 同版本。前端侧：5821xx 这一族在 hl-ui v2.1 上没有专门分支，统一由 src/utils/request.js 的响应拦截器按 code 非成功值 toast 后端 message，故 100503 与 582117 前端零改动即有基本行为；记 pending 的是 100503 的语义——它是「稍后重试」而不是「操作失败」，用通用错误样式提示会把一次可重试的排队说成失败。前端结论(2026-09-23 用户拍板):100503 不做专门「可重试」提示,维持拦截器通用 toast;582117 文案后端完整直出,5821xx 全族前端无专门分支,基本行为零改动,记 not_required 闭环。"
+updated_at: "2026-09-23"
+base: "dev-v3"
+---
+
+# 团期人员配置: 保存口新增并发抢锁 100503 与配置位字典缺失 582117（管理后台）
+
+> **服务**: hl-order-service-v3（端口 8086/8186）
+> **PR**: #8177（主体）、#8186 / #8197 / #8199（订正）、#8243（取证载体）
+> **Issue**: #8123、#8148
+> **日期**: 2026-09-23
+> **影响范围**: 管理后台团期详情页的「配导游 / 配摄影」弹窗保存动作
+
+---
+
+## ⚠️ 关键变化
+
+这个端点**多了两个此前不会返回的业务码**，路径、入参结构、成功响应结构一律不变。
+
+1. **`100503`「资源被占用,请稍后重试」** —— 同一团期被两个人几乎同时保存时，后到的那一方等满 3 秒仍抢不到锁就收到它。**它是 HTTP 200，不是 5xx**，语义是「排队没排上，重来一次就好」，不是「你这次提交有问题」。
+2. **`582117`「角色 {0} 未归属任何人员配置位……」** —— 配置位字典被误删成员时的守卫。修复动作在**字典页面**，不在这个弹窗里，所以文案要原样透出给运营看。
+
+两个码都会被 `src/utils/request.js` 的现有拦截器按「code 非成功值」自动 toast 后端 message，**前端零改动即有基本行为**；需要动手的只有 100503 的提示语气（详见「四、契约约束与正确调用方式」）。
+
+---
+
+## 一、背景
+
+### #8123：并发保存互相覆盖
+
+保存团期 staff 的动作分两段——先写团期侧配置（`order_batch_staff`），再扇出到各活跃子订单（`order_staff_assignment`）。改前这两段都没有锁，于是两个人几乎同时保存同一团期时，两条扇出各自读到**自己那一刻**的整期配置并写下去，后写的不知道前面那份已经变了。子订单侧的结果是同一个人留下重复行，而两次请求**都返回 200**——调用方拿不到任何异常信号。
+
+修法是在保存口加订单级分布式锁，并在锁内**复读整期最新配置**再扇出：
+
+| 锁 | 锁名 | key 维度 | expire | acquireTimeout |
+|---|---|---|---|---|
+| 保存口 | `GroupBatchStaffLockNames.SAVE` | `batch-staff:save:{productBatchId}` | 30s | **默认 3s**（不显式设） |
+| 扇出 | `GroupBatchStaffLockNames.FAN_OUT` | 同团期 | — | 显式拉长（异步后台任务，宁可等久也不能丢单） |
+
+两者的等待上限**刻意不一致**：保存口背后有个人在等页面响应，让他 3 秒后重试是对的（他重新打开还能看见别人刚存的最新配置）；扇出没有人在等返回，放弃的代价是某张子订单**永久**停在上一轮配置。
+
+### #8148：角色判据从写死表改为读字典
+
+角色↔人员类型的校验（`582114`）改前查的是代码里写死的角色表，改后读配置位字典（`GroupBatchStaffSlotResolver#slotTypesOf`）。这让业务给导游位字典加一行新角色时当天就能生效、不必发版，但也带来一个新情形：
+
+| 「查不到归属位」的成因 | 改前含义 | 改后处置 |
+|---|---|---|
+| `DRIVER` / `OTHER` 等结构性不参与配置位的角色 | 唯一含义，不校验是对的 | **照旧放行** |
+| 运维把 `GUIDE` / `LEADER` / `PHOTOGRAPHER` 从某个仍非空的配置位字典里删掉 | 不存在这种情形 | **拒绝，返 582117** |
+
+两种情形若继续共用「不校验」这一条出路，那一刻该角色的 `582114` 会**当场静默失效**：任意人员类型都能配成这个角色落库、接口返回 200，一直到结算对账才发现人岗对不上。两支由 `participatesInSlotsByFallback` 分开。
+
+**它不是「字典读挂」的兜底**：Feign 失败或字典整表为空时 `typesOf` 回落内置默认值，归属位照样查得到，走不到这个码。能触发它的只有「字典非空、但该角色被从里面删掉」。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 保存团期人员配置 | PUT | `/v3/admin/group-batch/{productBatchId}/staff` | 修改接口 | 新增可能返回的业务码 `100503`、`582117`；路径 / 入参 / 成功响应结构不变 |
+
+路径、入参结构、权限码、成功响应结构均零变化；网关无改动。
+
+---
+
+## 三、接口详情
+
+### 1. 保存团期人员配置 `PUT /v3/admin/group-batch/{productBatchId}/staff`
+
+**VO**: `BatchStaffConfigReqVO`
+
+#### 使用场景
+
+团期详情页「配导游 / 配摄影」弹窗点保存。整期全量覆盖：按 `scopeRoles`（不传即全量）软删旧配置、写入新配置、
+异步扇出到各活跃子订单，并按配置结果回填 `guide_ready` / `photographer_ready`。
+
+🔴 **路径参数是产品侧排期 ID，不是团期聚合主键**。端点名叫 `group-batch`，但 `{productBatchId}` 吃的是
+`group_tour_batch.batch_id`（`@ApiParam` 原文：「产品侧排期 ID（`group_tour_batch.batch_id`，非运营团期主键）」）。
+响应体里另有一个 `groupBatchId`，那才是订单侧 `order_group_batch` 的主键，两者是不同的值，不要互换。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| productBatchId | path | Long | 是 | 正整数，产品侧排期 ID | 团期所属班期；未建团返 589553 |
+| scopeRoles | body | List&lt;String&gt; | 否 | 传了就不能是空数组；元素非空白且须在员工角色取值域内 | 限定本次覆盖的角色范围，不传则整期覆盖 |
+| staffList | body | List&lt;Item&gt; | 否 | null 按空列表处理 | 传空列表 = 清空覆盖范围内的配置 |
+| staffList[].staffId | body | Long | 是 | 须命中候选人员 | 人员 ID |
+| staffList[].staffRole | body | String | 是 | 须与人员类型相符，否则 582114 | 角色（GUIDE / LEADER / PHOTOGRAPHER …） |
+| staffList[].sortOrder | body | Integer | 否 | — | 展示排序 |
+| staffList[].remark | body | String | 否 | — | 备注 |
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| productBatchId | Long | 回显路径参数 |
+| groupBatchId | Long | 团期聚合主键，与路径参数不是同一个值 |
+| staffList | List | 保存后的整期最终状态 |
+| affectedOrderCount | Integer | 本次扇出触及的活跃子订单数 |
+
+#### 请求示例
+
+```http
+PUT /v3/admin/group-batch/2102640646949105666/staff HTTP/1.1
+Host: api.test.1814.love:9443
+Authorization: Bearer <admin token>
+Content-Type: application/json
+
+{"staffList":[{"staffId":1002,"staffRole":"GUIDE","sortOrder":0,"remark":"hl8123-8148live-normal"}]}
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "productBatchId": "2102640646949105666",
+    "groupBatchId": "2102640736900116481",
+    "affectedOrderCount": 1,
+    "staffList": [
+      {"id": "2102640914386284545", "staffId": 1002, "staffRole": "GUIDE", "staffName": "李雪梅", "remark": "hl8123-8148live-normal"}
+    ]
+  }
+}
+```
+
+#### 空数据 / 降级响应
+
+`staffList` 传空列表即清空覆盖范围内的配置，返回 200，`staffList` 为空数组、`affectedOrderCount` 为实际扇出订单数。
+被任何一个业务码拒绝时都是**零写入**——校验闸全部在写库之前，回读会看到与提交前逐字相同的配置。
+
+#### 错误响应
+
+同一团期并发保存，后到的一方等满 `acquireTimeout`（默认 3000ms）仍未抢到锁：
+
+```json
+{"code": 100503, "message": "资源被占用,请稍后重试", "data": null}
+```
+
+配置位字典里查不到某个本该有位的角色的归属位（`{0}` 由运行期填入角色名）：
+
+```json
+{"code": 582117, "message": "角色 GUIDE 未归属任何人员配置位，无法校验人员类型；请检查配置位字典是否被误删", "data": null}
+```
+
+本端点此前已有、本次不变的两个高频码，一并列出便于对照：
+
+```json
+{"code": 582116, "message": "本次保存声明的角色范围（GUIDE）只覆盖了配置位的一部分，还缺少 LEADER；同一配置位的角色必须一起声明，否则位内其余人员会被留在库里", "data": null}
+```
+
+#### 业务边界
+
+- `100503` 的锁维度是 **`productBatchId`**：并发窗口只存在于**同一个团期**的两次保存之间，不同团期互不阻塞，整体串行化的担心不成立
+- `100503` 走 **HTTP 200**，不是 5xx；它有两条产生路径（`lockFailureStrategy` 直接抛 `BusinessException`，或异常以 `LockException` 形态漏出时由 `LockFailureExceptionHandler` 兜底），**终点是同一个码**，调用方不必区分
+- `582117` 的修复动作在**配置位字典页面**，不在本弹窗；文案点名了角色并指向字典，适合原样透出给运营
+- `582117` **不会**在「字典读挂 / 字典整表为空」时出现——那种情形回落内置默认值，归属位照样查得到
+- `582115`（提交的人越界）与 `582116`（声明的范围本身不完整）分工不同：前者改 `staffList` 或扩范围，后者只有一条改法——把缺的同位角色补进 `scopeRoles`。命中 582116 的请求可以**一个越界的人都没有**（`staffList` 甚至可以是空数组，那正是「清空导游位」这条最危险的路径）
+- 导游位并收 `GUIDE` 与 `LEADER`：只传 `["GUIDE"]` 却选了领队会命中 582115，只传 `["GUIDE"]` 而位内还有 LEADER 会命中 582116
+
+---
+
+## 四、契约约束与正确调用方式
+
+- **`100503` 要单独做提示，不要并进通用错误 toast**。现有拦截器按 `code` 非成功值统一 toast 后端 message，
+  行为上没有错，但通用错误样式会把一次「排队没排上、再点一次就好」说成「操作失败」。建议：命中 100503 时
+  保留用户已填的表单、给一句可重试的提示（后端文案「资源被占用,请稍后重试」本身已是可直接展示的完整句子）。
+- **判成败一律看 `code`，不要看 HTTP status**。本端点的业务失败（含 100503）全是 HTTP 200，
+  `src/utils/request.js:413` 现有的 `code === BIZ_CODE.SUCCESS` 判据是对的，沿用即可。
+  ⚠️ fleet `h5-onboard` 那条独立 axios 实例上有一处 100503 的处理走的是 HTTP 409 语境，**两条链路不同源，不要互相复用**。
+- **`productBatchId` 与响应里的 `groupBatchId` 不可互换**（见「使用场景」的红字）。
+- 保存成功后若调用方缓存了 `guide_ready` / `photographer_ready`，需重新拉取团期详情。
+
+---
+
+## 五、数据库行为
+
+- 保存：按 `scopeRoles` 范围（不传即整期）软删旧配置行 → 写入新配置行 → 异步扇出到各活跃子订单 → 回填团期行的两个 ready 标志
+- 本次新增的锁不改变上述任何一步的写内容，只保证同一团期的两次保存不会交叠执行，且扇出读到的是锁内复读的最新配置
+- 被 `100503` / `582114` / `582115` / `582116` / `582117` 任一码拒绝时**零写入**
+
+---
+
+## 六、边界行为
+
+- `100503` 的等待上限 3000ms 来自 lock4j 默认值（运行时无任何显式覆盖），不是代码里写死的常量；改动保存口的锁参数等于改这条对外契约，已由单测 `GroupBatchStaffFanOutLockRetryTest#lockParameters_saveUsesLock4jDefaultAcquireTimeout_whileFanOutOverridesItToOutliveExpire` 钉成可执行断言
+- `582117` 与 `582114` 是互补而非替代：字典里查得到归属位、但人岗不符 → `582114`；本该有位却查不到归属位 → `582117`
+- `DRIVER` / `OTHER` 这类结构性不参与配置位的角色在两个码上都放行，行为与改前一致
+
+---
+
+## 六.6、修改前后对比
+
+| 维度 | 改前 | 改后 |
+|---|---|---|
+| 同一团期并发保存 | 两条扇出互相覆盖，子订单侧留重复行，**两次都返 200** | 后到者等满 3s 返 `100503`；抢到锁者在锁内复读最新配置再扇出 |
+| 角色↔人员类型判据 | 代码里写死的角色表 | 读配置位字典（字典加角色当天生效、不发版） |
+| 配置位字典被删成员 | 该角色的 `582114` **静默失效**，任意人员类型都能落库并返 200 | 返 `582117`，拒绝落库 |
+| `DRIVER` / `OTHER` | 放行 | **不变**，仍放行 |
+| 路径 / 入参 / 成功响应结构 | — | **零变化** |
+
+---
+
+## 六.7、影响评估
+
+| 面 | 评估 |
+|---|---|
+| 管理后台配导摄弹窗 | 现有拦截器已能 toast 两个新码的后端文案，**零改动即有基本行为**；需要动的只有 100503 的提示语气与表单保留 |
+| 已有错误文案分支 | 5821xx 在 hl-ui v2.1 上无专门分支（全族零命中），统一走拦截器，无需逐码适配 |
+| 小程序端 | 不受影响，团期人员配置无小程序写口 |
+| 并发体验 | 只在同一团期被两人同时编辑时才可能出现 100503；不同团期互不阻塞 |
+| 运维 | 配置位字典删成员会立刻让该位保存被 582117 拒——这是有意的，文案指向字典页面 |
+
+---
+
+## 七、不影响范围
+
+- 路径、入参结构、权限码、成功响应结构、网关配置
+- 候选人查询（`/staff/candidates`、`/staff/candidates/page`）与配置列表查询（`GET /staff`）
+- 报账人等级设置口 `PUT /v3/admin/group-batch/{productBatchId}/staff/{staffId}/reporter-rank`：本次未取证，不在本条目覆盖范围内
+- 子订单自己单独派的人员（`order_staff_assignment` 中 source 非 `GROUP_BATCH` 的行）
+- `582114` / `582115` / `582116` 三个既有码的触发条件与文案
+
+---
+
+## 八、测试环境已验证
+
+2026-09-23，`api.test.1814.love:9443`，分支 `dev-v3`，order-v3 活体 `7738668b8`（双实例 8086 / 8186，进程 jar 与磁盘 jar 同 inode）。
+
+| 项 | 请求 | 结果 |
+|---|---|---|
+| 正常路径回归 | `PUT /v3/admin/group-batch/2102640646949105666/staff`，body 不传 `scopeRoles`（整期全量覆盖），一条 `{staffId:1002, staffRole:"GUIDE"}` | HTTP 200，`code=200`，`message=成功`；`data.staffList` 回显该行，`affectedOrderCount=1` |
+| 落库回读 | `GET /v3/admin/group-batch/2102640646949105666/staff` | HTTP 200，返回同一行（`id=2102640914386284545`），**确认真落库、不是空操作假成功** |
+| 582116 | 同端点，`{"scopeRoles":["GUIDE"], staffList:[GUIDE 一人]}`（漏声明同位的 LEADER） | HTTP 200，`code=582116`，文案完整返回；回读确认**零写入**（记录仍是上一步那行） |
+| 582114 | 同端点，`staffId=1002`（真实 `staffType=GUIDE`）提交 `staffRole=PHOTOGRAPHER` | HTTP 200，`code=582114`，`message=所选人员的角色与其人员类型不符，请重新选择`；回读确认**零写入** |
+
+**这一轮没有取到 `100503` 与 `582117` 的活体样本，两者在测试环境上无法构造**，原因是环境性的、与实现无关：
+
+- `100503` 要求持锁方占用临界区超过 `acquireTimeout`=3000ms 才能让后到者抢不到。真锁双臂单测里实测的等锁只有 **373ms**，
+  而把临界区人为拉长到 3 秒以上需要改代码或插延迟——那会改变被测对象本身。
+- `582117` 要求把 `GUIDE` / `LEADER` / `PHOTOGRAPHER` 从某个**仍非空**的配置位字典里删掉。字典是全站共享数据，
+  这个动作的副作用会落到所有人的角色下拉框上。
+
+因此这两个码本条目交付的是**契约**（码值、HTTP 状态、文案、触发条件、锁维度），依据是源码定义与测试服活体字节确认，
+不是端到端样本。它们的行为另有可执行断言背书：`100503` 由真 lock4j AOP + 真 Redis 的双臂互斥测试覆盖（无锁臂 4 行重复
+vs 真锁臂恰好 2 行，后进者等锁 373ms，且断言链最后一条是**两臂之差**，「这一轮恰好没撞上竞争」过不了关）；
+`582117` 由源码变异实验覆盖（把读字典改回写死表、把 582117 分流短路掉，两轮各有用例转红，方向互补）。
+
+---
+
+## 十、相关文档
+
+- Issue #8123（团期 staff 扇出并发写重复行）、Issue #8148（配置位成员集合改读字典）
+- PR #8177（主体，提交 `bfc10966e`）、PR #8186 / #8197 / #8199（订正）、PR #8243（取证载体）
+- 错误码定义：`hl-order-service-v3/.../assignment/errorcode/AssignmentErrorCode.java`（582115 / 582116 / 582117）、
+  `hl-common/hl-common-core/.../errorcode/CommonErrorCode.java:67-68`（100503）
+- 后续工单 #8242：三个合法 staffRole 继承了 DRIVER 的类型校验豁免（与 582117 是不同的洞）
+
+---
+
+## 关联 / 联系人
+
+- 后端：wx
+- 前端：mmg（100503 的可重试提示语气与表单保留）
@@ -0,0 +1,94 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8142"
+title: "车务派单看板: 行程用车与接送机需求并存时，接送机需求整行从列表消失——已修复，同一订单现按需求维度出多条记录"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修复"
+backend_status: "deployed"
+gateway_status: "not_required"
+frontend_status: "not_required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "本条不改变 GET /admin/fleet/board/orders 的任何响应字段名、类型或嵌套结构，变的是记录的产出规则：修复前该端点在「一单同时有活跃 TRAVEL 需求与活跃 TRANSFER 需求」时只产出其中一条需求的记录，另一条整行不出现（且出现的那条还可能挂着另一类的 requirementRemark 与派车行）；修复后每条活跃用车需求各出一条记录。gateway_status=not_required：零新增路由，端点既有。frontend_status=not_required：hl-ui（origin/v2.1）的看板列表与卡片视图早已用 requirementId 作 row-key（src/views/fleet/board/utils/boardSummary.js:9-14，resolveBoardRecordKey，注释原文「看板已按当前有效用车需求聚合；列表身份必须锚定 requirementId，历史响应缺失时才回退原记录/订单 ID」），同一订单多条记录不会撞 key，无需前端改动——这是查证结论不是推断，若后续发现有按 orderId 去重的调用点，以那处为准另发订正。backend_status=deployed：hl-fleet-service 与 hl-order-service-v3 均已滚动到测试服 78d0aad3d（分别 2026-09-23 07:38:54 / 07:40:25），并在测试服活体上完成改前/改后对跑取证，读数见正文第四节。 mmg 2026-09-23 复核: grep 实证 resolveBoardRecordKey 锚定 requirementId(boardSummary.js:9-14)多单不撞 key;virtualPending 为既有字段,index.vue/display.js/AssignModal 均已消费;域内唯一按 orderId 建的 Map 是未读数查找表(unreadByOrderId),多单同值无冲突——not_required 成立。"
+updated_at: "2026-09-23"
+base: "dev-v3"
+---
+
+# 车务派单看板: 行程用车与接送机需求并存时，接送机需求整行从列表消失
+
+> **存放目录**: 二期（order-v3）→ `changelogs-v2/2026-09/`
+>
+> **服务**: hl-fleet-service（看板候选与聚合）+ hl-order-service-v3（需求身份供给）+ hl-common
+> **PR**: [#8211](https://git.1814.love:8443/wx/HL/pulls/8211)
+> **Issue**: [#8142](https://git.1814.love:8443/wx/HL/issues/8142)
+> **日期**: 2026-09-23
+> **影响范围**: `GET /admin/fleet/board/orders`（车务派单看板列表 / 待派分面）
+
+---
+
+## ⚠️ 关键变化
+
+1. **同一订单现在可能出现多条记录，每条活跃用车需求各一条。** 字段名、类型、嵌套结构**零变化**，变的是**记录的产出规则**。
+   如果你的代码里有「一个 orderId 对应一条记录」这个隐含假设（按 orderId 去重、按 orderId 建 Map、用 orderId 当列表 key），**它现在不成立了**。
+   `hl-ui` 当前实现不受影响——看板列表与卡片视图已用 `requirementId` 作 row-key（`src/views/fleet/board/utils/boardSummary.js:9-14`）。
+
+2. **`requirementId` 现在是列表记录的身份键，`orderId` 不是。** 唯一性口径是 `(orderId, requirementId)` 组合，`requirementId` 恒非 null。
+
+3. **`requirementRemark` / `dailyAssignments` / `requiredVehicles` 现在保证属于本记录自己的那条需求。** 修复前存在反向错配：TRANSFER 需求的记录上挂着 TRAVEL 需求的 `requirementRemark`，派车行也只显示了其中一部分。
+
+4. **「接送机还没派车」的虚拟待派卡现在会出现在待派分面里**（`virtualPending: true`、`dailyAssignments: []`、`assignmentStatus: "unassigned"`、`assignmentGroupId: null`）。修复前这类需求在列表侧完全不可见，车务无从发现「这单的接送机还没派车」。
+
+---
+
+## 一、变更接口清单
+
+| 方法 | 路径 | 变更性质 |
+|---|---|---|
+| GET | `/admin/fleet/board/orders` | 响应**字段结构不变**，记录产出规则变更（一单一条 → 一需求一条） |
+
+> 本条不属「新增接口 / 修改接口」：无新增或删除的请求参数，无新增、删除或改名的响应字段，无新增错误码。
+
+---
+
+## 二、失败形态（供你判断历史数据与截图）
+
+修复前有两种形态，都**静默**——接口返 200、`code=200`、无任何错误码或警告字段：
+
+**形态甲 · 整批不出现**：两类需求并存时只产出一条记录，另一条整行没有。
+实测：某广口径查询 `.data.total` 修复前 **22**、修复后 **25**，多出的 3 条恰好一单一条落在三个订单上。
+
+**形态乙 · 反向错配**：产出的那条记录 `requirementId` 是 A 需求的，而 `requirementRemark` 是 B 需求的，`dailyAssignments` 只含 A 的一部分派车行。
+实测订单 `HL20260919104049371`：修复前该条记录 `requirementId=7330964160969957`（TRANSFER）却带着 TRAVEL 的备注、只有 1 条日行；修复后备注是自己的、日行 2 条（与库中该需求的活派车行集合逐条相等）。
+
+⇒ **修复前的看板截图与导出数据不可作为历史对账依据**，涉及两类需求并存的订单需重新拉取。
+
+---
+
+## 三、边界：有一类记录按设计仍然不出现
+
+用车需求处于 `DONE`/`CANCELED` 等**非待派状态**、且**零条活派车行**时，看板**不为它造虚拟待派卡**，只打一条 warn 日志。
+这属于数据不一致的兜底分支（`BoardCandidateSource.java:383-397`，判据 `isAwaitingDispatch = PENDING || PROCESSING`），**不是本次修复的残留**。
+⇒ 若你看到某单「库里有这条需求、看板上没有」，先看该需求的 `status`：非 `PENDING`/`PROCESSING` 且零派车行时，这是预期行为。
+
+---
+
+## 四、后端已验证的读数（测试服活体，部署 commit `78d0aad3d`）
+
+| 验证项 | 读数 |
+|---|---|
+| 虚拟待派卡可见 | 某 TRANSFER 需求记录数 `0 → 1`，该单 `.data.total` `1 → 2`；`virtualPending=true`、`dailyAssignments=[]` 与库一致 |
+| 两类派车行各自完整 | TRAVEL 与 TRANSFER 两条需求的日行 `assignmentGroupId` 集合，与库中各自的活派车行集合**逐条相等** |
+| 单类订单零回归 | TRAVEL-only 与 TRANSFER-only 两单，响应递归展平后各 243 / 205 个叶路径，**各只有 1 个键变化**且都是随日期自然漂移的 `daysUntilDeparture`（恰好 −1）；剔除该键后改前/改后 sha256 **完全相等** |
+| 待派分面未被打穿 | 广口径 `?statuses=unassigned` 返 `total=133`；fleet 日志中 fail-open 分支关键词 **0 命中**（同窗口任意 board 日志行 21 条，证明日志在写） |
+| 记录唯一性 | 8 份响应逐份核 `(orderId, requirementId)` 对唯一、`requirementId` 非 null 全绿 |
+
+---
+
+## 五、你需要做的
+
+- **无需改动**即可继续工作；若你的代码按 orderId 去重或建 Map，改为按 `requirementId`（或 `(orderId, requirementId)`）。
+- 渲染时优先用 `requirementId` 作列表 key。
+- 展示「这单还有没有没派的车」时，把 `virtualPending: true` 的记录算进去——它就是「有需求、还没派车」这一状态的载体。
@@ -0,0 +1,114 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8166"
+title: "通知消息bizType路由与bizId语义契约交接"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "前端缺陷"
+backend_status: "not_required"
+gateway_status: "not_required"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "77b421f839a0eaeaa419c19bb6f79a803dd99205"
+target_release: "v2.1"
+verified_at: "2026-09-23"
+status_note: "关联工单#8166（bizType/bizId契约漂移）的前端交接件。后端已就绪，前端按本件调整三处routing逻辑。前端已交付(2026-09-23,三条必落地+AC-9 全做):①jumpBiz 改白名单兜底——订单白名单(ORDER/HOUSE/HOUSE_LEAD/GROUP/FLEET)才按 orderId 路由,新增/未知 bizType 不入列;②canJumpToBiz 白名单外返 false 不渲染跳转按钮,未知即不跳;③GROUP_HOUSE/GROUP_FLEET/GROUP_BATCH 按 bizId=groupBatchId 路由团期详情页 /order-v2/batch/detail/{id};AC-9 死分支(peer==CUSTOMIZER→housekeeper/orders,peerRole/senderRole/requirementId 后端从未返回)已删。路由解析抽 resolveBizRouteTarget 纯函数,spec 13 例全绿,checkpoint 全过。正文首版第一节把兜底分支位置写成 jumpBiz.js 的 else，已于 2026-09-23 订正为 index.vue:291-293，并补一节交付后必查（HOUSE NOTIFY 三义 bizId）。后端订正(补 HOUSE NOTIFY 复核项)前端已对照:resolveBizRouteTarget 中 isHouseNotifyRow 闸在白名单命中之前,HOUSE NOTIFY 行(bizId 三义)恒返 null,spec 已有该定向例({bizType:HOUSE,kind:NOTIFY,bizId 任意雪花}→null),未打穿 #8182;交付 commit 77b421f8 已可达 origin/v2.1(取证时因推送延迟暂不可见)。"
+updated_at: "2026-09-23"
+base: "dev-v3"
+---
+
+# 通知消息 bizType 路由与 bizId 语义契约交接
+
+关联工单：[#8166](https://git.1814.love/wx/HL/issues/8166) bizType/bizId 契约漂移定案
+
+> **2026-09-23 订正**：本件首版把兜底分支的位置写成了 `jumpBiz.js` 的 `else`。实测 `origin/v2.1` 的
+> `jumpBiz.js` 全文 44 行、**没有 `else`、也没有 bizType 白名单**，兜底在 `index.vue:291-293`。
+> 第一节已按实际代码重写，其余各节未变。前端已按正确形状交付（见 frontmatter），本节保留是因为首版那句错的描述已经发出去过，留着会让下一个读这份交接件的人以为 `jumpBiz.js` 里有一个并不存在的分支。
+
+## 〇、交付后必查一项：`HOUSE` 进订单白名单会不会打穿 #8182
+
+frontmatter 记的白名单是 `ORDER / HOUSE / HOUSE_LEAD / GROUP / FLEET` → 按 `orderId` 路由。**`HOUSE` 这一项只有在仍受 `isHouseNotifyRow` 约束时才是安全的。**
+
+判据在 `jumpBiz.js` 自己的头部契约里（`origin/v2.1` = `16c3506d`，`jumpBiz.js:4-5`）：
+
+> HOUSE 域 bizId 三义(hotelId/groupBatchId/orderId)不是路由键,禁止拿它反推页面
+> - HOUSE 非聊天行且 link 不可用 → 不渲染入口也不跳(bizId 当 orderId 必开错单)
+
+`isHouseNotifyRow`（`jumpBiz.js:36-38`）= `(bizModule || bizType) === 'HOUSE' && !isChatRow(row)`。⇒ **`bizType === 'HOUSE'` 这一个条件分不开两类行**：CHAT 行的 bizId 是 orderId（可路由），NOTIFY 行的 bizId 三义（不可路由）。白名单若只按 `bizType` 匹配、且 `isHouseNotifyRow` 那道闸在它之后或被一并删掉，HOUSE NOTIFY 行就会**按 orderId 打开一个错的订单**——而 `hotelId` / `groupBatchId` 也是雪花 id，**页面不会报错，只会显示另一张单**，这正是 #8182 修掉的那个形态。
+
+**一句话自检**：`resolveBizRouteTarget` 对一个 `{ bizType: 'HOUSE', kind: 'NOTIFY', conversationKey: null, bizId: '<任意雪花id>', link: '' }` 的行，返回的必须是「不跳」，不是订单路由。spec 里若没有这一例，它就是白名单里唯一一个靠**行内第二个条件**才安全的成员，而那个条件不在白名单的表达式里。
+
+**取证边界**：本节没有对交付提交本身取证——`77b421f839a0eaeaa419c19bb6f79a803dd99205` 在 `git ls-remote origin`（hl-ui）返回的 15 个 ref 里查无此对象，阳性对照同一命令能查到 `16c3506d`（`refs/heads/v2.1`）。上面的判据因此全部取自 `origin/v2.1` tip `16c3506d`，即交付**之前**的代码；白名单的实际写法请以你们手上那份为准。
+
+## 一、兜底分支：bizId 被当成 orderId
+
+### 代码现状（实测 `hl-ui` `origin/v2.1`）
+
+跳转链路是**两个文件配合**的，改一处不够：
+
+| 位置 | 职责 | 现状 |
+|---|---|---|
+| `src/views/notification/MyMessages/jumpBiz.js:40-43` `canJumpToBiz()` | 决定**渲不渲染**「跳转」按钮 | `link` 可用→true；无 `bizId`→false；否则 `!isHouseNotifyRow(row)`——**只挡 HOUSE NOTIFY 一类** |
+| `src/views/notification/MyMessages/index.vue:267-294` `jumpToBiz()` | 决定**跳去哪** | `link` 优先(`:268-272`)→`FLEET`(`:280`)→定制师房务分支(`:282`)→HOUSE NOTIFY 兜底闸(`:288-290`)→**`else`(`:291-293`) `getOrderReadableRoute(bizId)`** |
+
+`else` 那一支把 `bizId` 无条件当作 **orderId**。凡是落到这一支、而 `bizId` 实际不是订单 ID 的消息，都会打开一个**错的订单详情页**——页面正常渲染，没有报错，用户不知道自己看的不是这条消息说的那个东西。
+
+### 谁会落到这一支
+
+`link` 为空的行才走推导。**CHAT 通道的行天然没有 `link`**（`link` 是 NOTIFY 按事件模板渲染出来的），所以团期级会话行 `GROUP_HOUSE` / `GROUP_FLEET` 会：
+`canJumpToBiz` 判 true（有 bizId、不是 HOUSE NOTIFY）⇒ 按钮渲染 ⇒ `jumpToBiz` 前四支都不命中 ⇒ 落 `else` ⇒ 拿 **groupBatchId** 去开订单详情页。
+
+### 方向说明：不要退回「bizType 推路由」
+
+`jumpBiz.js` 开头的契约（#8182 建立）写得很明确——**NOTIFY 行跳转的唯一正确来源是 `link`，HOUSE 域 bizId 三义不是路由键**。本件**不是**要推翻它回到按 bizType 推路由，而是给那条**残留的**推导加一道白名单闸：能走推导的只有已确认 `bizId == orderId` 的那几类，其余一律不跳。
+
+## 二、前端改动（3 条，缺一不可）
+
+1. **`index.vue:291-293` 的 `else` 加白名单**：只有 `mod` ∈ `{ORDER, HOUSE, HOUSE_LEAD, GROUP, FLEET}`（即第三节表里 bizId 为 orderId 的那几类）才 `getOrderReadableRoute(bizId)`；其余**直接 return，不跳**。
+
+2. **`jumpBiz.js:40-43` 的 `canJumpToBiz` 同步收口**：把同一份白名单用上，否则会渲染出一个**点了没反应**的按钮——那比跳错更让人困惑。两处必须用同一份常量，不要各写一份。
+
+3. **团期级 bizType 路由到团期详情页**：`GROUP_HOUSE` / `GROUP_FLEET` / `GROUP_BATCH` 的 `bizId` 是 `groupBatchId`，应路由到团期详情（`src/views/order-v2/batch/detail/`，页面已存在），不是订单详情。
+
+**这三条落地后的行为变化**：以后后端新增一个 bizType 而前端没跟着改，后果从「**跳到错的订单页**」变成「**不跳**」。失败从隐形变成可见——这是本次改动真正买到的东西，不是多支持了几个跳转。
+
+## 三、bizId 语义契约（原只活在注释里，本件升级为书面契约）
+
+判据取自 `origin/dev-v3` 源码，不是推测：
+
+| bizType | 通道 | `bizId` 实际值 | 出处 |
+|---|---|---|---|
+| `ORDER` | CHAT / NOTIFY | orderId | #8155 |
+| `HOUSE` | CHAT | orderId | `ChatManager.java` / `TeamChatModule.java` |
+| `HOUSE_LEAD` | CHAT | orderId | 同上 |
+| `FLEET` | CHAT | orderId | 同上 |
+| `GROUP` | CHAT | orderId | 同上 |
+| `GROUP_HOUSE` | CHAT | **groupBatchId** | 同上 |
+| `GROUP_FLEET` | CHAT | **groupBatchId** | 同上 |
+| `GROUP_BATCH` | **NOTIFY** | **groupBatchId** | `GroupBatchFormedNotifyService.java:209-210`（`.bizId(String.valueOf(groupBatchId))` + `.bizType("GROUP_BATCH")`） |
+
+⚠️ `HOUSE` 这一行只覆盖 **CHAT** 行。**HOUSE 域的 NOTIFY 行 bizId 是三义的**（hotelId / groupBatchId / orderId），前端已有 `isHouseNotifyRow` 把它挡在推导之外（`jumpBiz.js:35-37`），本次白名单**不要**把 HOUSE NOTIFY 放进来。
+
+## 四、`peerRole` / `senderRole` 不补（后端定案）
+
+`AdminMessageRespVO` **不新增** `peerRole` / `senderRole`。
+
+**判据**（实测 `origin/dev-v3`）：
+- 该 VO 现有 **15 个字段**：`messageId` `categoryCode` `title` `content` `link` `bizId` `bizType` `isRead` `createTime` `messageType` `messageTypeLabel` `kind` `senderName` `conversationKey` `teamMessage`。`peerRole` / `senderRole` / `bizModule` / `requirementId` **四个都不在其中，也从未返回过**。
+- 定制师广播时 `admin_message.sender_role` **恒为 NULL**（`AdminMessageMapper.java:443-444` / `ChatConstants.java:200-201`）⇒ 就算把字段加上，在前端那条分支**正需要它**的场景里它恒为空。
+
+**前端据此处理**：`index.vue:282-287` 的第三层分支
+`peer === 'CUSTOMIZER' && (mod === 'HOUSE' || mod === 'HOUSE_LEAD')` 取值自 `:279 row.peerRole || row.senderRole || ''`，两个来源都恒空 ⇒ **该分支恒不触发，是死代码，请删除**。删掉后 `HOUSE` / `HOUSE_LEAD` 的 CHAT 行按第二节的白名单走订单详情，与今天的实际行为一致。
+
+若业务确实需要「房务会话行定向跳房务订单页」，那是一个新需求：它要的数据后端今天不产出，需要单独定接口。
+
+## 五、覆盖边界
+
+1. **bizType 清单是下界，不是全集**：`AdminNotificationController.java:127` 的 `.eventCode(config.getEventCode())` 是运行时入参，能发 `notification_event_config` 表里任意一行的事件码 ⇒ 任何静态枚举都数不全。这正是第二节要白名单兜底而不是黑名单的原因：**白名单对「没见过的类型」给出的是安全答案（不跳），黑名单给出的是错答案（跳错）**。
+2. **取证范围是 `origin/dev-v3`**。一期 `origin/dev` 的 `hl-user-service` 是另一份代码（渲染器与通道校验都不同），本件对一期的行为不作任何断言，不要把这里的结论套到一期页面上。
+3. **第三节的表只覆盖本件列出的 8 个 bizType**。表外的类型按第二节落到「不跳」，这是设计如此，不是遗漏。
+
+## 六、关联
+
+- 工单：[#8166](https://git.1814.love/wx/HL/issues/8166)
+- 后端联系人：@wx
@@ -0,0 +1,628 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8170"
+title: "订单协作域三只读端点补订单归属守卫（新增返回 581008/581045）；行程价格字段与团期批量打回契约补充说明"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "not_required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "PR #8290 已合并 dev-v3（841ea7b06）。部署：hl-order-service-v3 dev-v3 @ 841ea7b06，2026-09-23 20:07:37 部署，deploy-status STATE=ok，BEHIND 0。真实网关实测（夹具订单 2100542584106496001，归属定制师为他人）：CUSTOMIZER（非归属）在 tags / tag-picker / itinerary-document 三个端点均返回 581008；SUPER_ADMIN（对照）三个端点均正常返回 200；itinerary-document 不带 documentType 时先因参数校验返回业务码 400，发生在归属守卫之前。GET /{id}/itinerary 与批量打回 resourceType 两处仅补充字段说明文案，接口行为、请求/响应结构均未变。；前端判 not_required:GET /tags 与 itinerary-document 前端零调用;tag-picker 唯一调用点 TagPickerModal catch 透 err.message 不吞(581008/581045 走通用 toast);价格字段/批量打回两文档补充零行为变化"
+updated_at: "2026-09-23"
+base: "dev-v3"
+---
+
+# order-v3: 协作域三只读端点补订单归属守卫 + 行程价格字段/团期批量打回契约说明
+
+> **存放目录**: 二期(v3) → `changelogs-v2/2026-09/`
+>
+> **服务**: hl-order-service-v3
+> **PR**: #8290
+> **Issue**: #8170
+> **日期**: 2026-09-23
+> **影响范围**: 管理后台订单详情「标签」区、打标签弹窗、生成电子行程单（对客）、订单详情「行程安排」Tab、团期「查看需求」批量打回
+
+---
+
+## ⚠️ 关键变化（非必须,本版与上版行为不同 / 纠错 / 撤销时必写）
+
+- 本次变化：`GET /v3/admin/order/{orderId}/tags`、`GET /v3/admin/order/{orderId}/tag-picker`、`GET /v3/admin/order/{orderId}/itinerary-document` 三个端点新增订单归属校验。
+- 前端以前以为的：只要拿到 token、打开订单详情页，就能对任意 `orderId` 调这三个接口拿到数据——改前这三个端点方法体零权限判断，任意后台角色都能读到他人订单的标签、打标签弹窗数据、完整电子行程单（含出行人、酒店、大交通）。
+- 实际新行为：非归属定制师、非 `ADMIN`/`SUPER_ADMIN`/`VEHICLE_MANAGER`、且不是在读团期子订单的团期管理员，会收到 `code=581008`；房务管理员/房务组长一律先被拒绝为 `code=581045`。请求体、响应体结构不变，只是多了这两种失败响应。
+- 同一次提交里顺带把 `GET /{id}/itinerary` 的四个价格字段（协议价快照、结算价快照、计划日单价、房型行协议价）与批量打回 `resourceType` 字段的既有契约写进了字段说明（**不是行为变化，是文档补充**）：这四个价格字段是供应商采购价，不是对客报价；批量打回 `resourceType=ALL` 的车侧范围只覆盖游览车（TRAVEL），不含接送机（TRANSFER）。
+
+---
+
+## 一、背景（选填）
+
+#8170 AC-18 复核发现协作域三个只读端点（标签列表、打标签弹窗、电子行程单）方法体零归属校验——Controller 与 Service 都没有调用任何 `OrderViewGuard`，只要能拿到 JWT（任意后台角色）就能传任意 `orderId` 读到他人订单的标签与完整行程文档。本次在 `CollabService` 三个方法体内补 `OrderViewGuard.assertOrderReadable`。
+
+同一份工单里还有两条**纯文档补充**（无代码行为变化）：AC-2 把「团期管理员为什么能在行程 Tab 看到供应商成本价」这条 2026-09-22 已拍板的口径写进 `ItineraryVO` 字段注释；AC-11 把「批量打回 `ALL` 不含接送机」这条既有行为写进 `RejectRequirementReqVO` 与 `GroupBatchRequirementService#doReject` 的契约说明。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 查订单已挂标签 | GET | `/v3/admin/order/{orderId}/tags` | 新增归属校验 | 新增 `OrderViewGuard.assertOrderReadable`；非放行角色返 581008，房务/组长返 581045 |
+| 2 | 打标签弹窗数据 | GET | `/v3/admin/order/{orderId}/tag-picker` | 新增归属校验 | 同上；守卫排在 `OperatorHolder` 取当前操作人之前 |
+| 3 | 生成电子行程单（对客） | GET | `/v3/admin/order/{orderId}/itinerary-document` | 新增归属校验 | 同上；`documentType` 缺失时先于守卫返回业务码 400 |
+| 4 | 行程安排 Tab | GET | `/v3/admin/order/{id}/itinerary` | 字段说明变更 | 四个价格字段补注「供应商采购价，非对客报价」；接口行为、字段结构不变 |
+| 5 | 按户打回需求 | POST | `/v3/admin/order/group-batch/{groupBatchId}/requirement/reject` | 字段说明变更 | `resourceType` 契约补充：`ALL`/`VEHICLE` 车侧仅覆盖 TRAVEL；接口行为不变 |
+
+---
+
+## 三、接口详情
+
+### 1. 查订单已挂标签 `GET /v3/admin/order/{orderId}/tags`
+
+**VO**: `无请求体 → OrderTagListRespVO`
+
+#### 使用场景
+
+订单详情页展示已挂在该订单上的标签（扁平列表，不分类型）。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| Authorization | Header | String | ✅ | - | 管理端登录令牌 |
+| orderId | Path | Long | ✅ | 订单须存在（581430）；当前登录角色须对该订单具备归属读权（581008/581045，本次新增） | 订单 ID |
+
+#### 出参 `Result<OrderTagListRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| attached | List<Object> | 当前订单已挂标签列表（扁平，不分类型） |
+| attached[].id | String | 标签主键（Long，超 JS 安全整数范围时序列化为字符串） |
+| attached[].orderId | String | 关联订单 ID |
+| attached[].tagName | String | 标签名 |
+| attached[].tagColor | String | 标签色值，如 #FF6B6B |
+| attached[].creator | String | 创建人姓名（定制师 or SYSTEM） |
+| attached[].createdAt | String | 创建时间，格式 yyyy-MM-dd HH:mm:ss |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/2100542584106496001/tags
+Authorization: Bearer {token}
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "attached": [
+      {
+        "id": "2101000000000000001",
+        "orderId": "2100542584106496001",
+        "tagName": "VIP",
+        "tagColor": "#FF6B6B",
+        "creator": "张定制",
+        "createdAt": "2026-09-20 10:15:00"
+      }
+    ]
+  },
+  "traceId": null,
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+无标签时 `attached` 为空数组，不是 null：
+
+```json
+{ "code": 200, "message": "成功", "data": { "attached": [] }, "traceId": null, "success": true }
+```
+
+#### 错误响应
+
+本次新增（TEST 实测，夹具订单 2100542584106496001，归属定制师为他人；CUSTOMIZER 非归属角色实测返回）：
+
+```json
+{ "code": 581008, "message": "无权查看此订单", "data": null, "traceId": null, "success": false }
+```
+
+房务管理员/房务组长（`ROOM_MANAGER`/`house_keeper_lead`）先于归属判定被拒绝：
+
+```json
+{ "code": 581045, "message": "房务角色无权查看订单详情，房务仅可配房", "data": null, "traceId": null, "success": false }
+```
+
+订单不存在（既有行为，未变）：
+
+```json
+{ "code": 581430, "message": "订单不存在", "data": null, "traceId": null, "success": false }
+```
+
+#### 业务边界
+
+- 放行角色（TEST 实测 SUPER_ADMIN 正常返回）：`ADMIN`/`SUPER_ADMIN` 恒放行；`VEHICLE_MANAGER` 恒放行；`GROUP_BATCH_MANAGER` 仅当目标订单挂在团期下（`order.groupBatchId != null`）才放行，散客单仍 581008；其余角色（定制师/客服/运营/财务等）必须是该订单的归属定制师（`adminId == order.consultantId`），否则 581008。
+- 房务管理员/房务组长无论订单归属如何，一律先于其他判定被拒绝为 581045（`OrderViewGuard.assertReadable`，`hl-order-service-v3/src/main/java/com/hulalv/order/core/guard/OrderViewGuard.java:279-281`）。
+- 判定顺序：先查订单是否存在（581430）→ 再判角色归属（581008/581045，`CollabService.java:172,174`）；非请求上下文（MQ 回放/定时任务/内部 Feign/单测）无角色视为系统态放行。
+
+---
+
+### 2. 打标签弹窗数据 `GET /v3/admin/order/{orderId}/tag-picker`
+
+**VO**: `无请求体 → List<TagPickerItemVO>`
+
+#### 使用场景
+
+订单详情页点「打标签」按钮弹出的选择面板：标签库全集 + 当前订单已挂标记 + 游离标签（已挂但不在库里的）。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| Authorization | Header | String | ✅ | - | 管理端登录令牌 |
+| orderId | Path | Long | ✅ | 订单须存在（581401）；当前登录角色须对该订单具备归属读权（581008/581045，本次新增） | 订单 ID |
+
+#### 出参 `Result<List<TagPickerItemVO>>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| (根) | List<Object> | 弹窗选择项列表；先按标签库排序（isPinned DESC, sortOrder ASC, lastUsedAt DESC），游离标签追加末尾 |
+| [].tagName | String | 标签名 |
+| [].tagColor | String | HEX 色值，如 #5B8FF9 |
+| [].tagScope | String | SYSTEM=系统标签 / PERSONAL=个人标签；游离标签为 null |
+| [].isPinned | Boolean | 是否置顶（游离标签为 false） |
+| [].sortOrder | Integer | 排序值（游离标签为 null） |
+| [].selected | Boolean | 是否已挂在当前订单 |
+| [].inLibrary | Boolean | 是否来自标签库（false=游离标签，仅存在于 order_tag 中） |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/2100542584106496001/tag-picker
+Authorization: Bearer {token}
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": [
+    { "tagName": "VIP", "tagColor": "#5B8FF9", "tagScope": "SYSTEM", "isPinned": true, "sortOrder": 1, "selected": true, "inLibrary": true },
+    { "tagName": "临时标记", "tagColor": "#FF9900", "tagScope": null, "isPinned": false, "sortOrder": null, "selected": true, "inLibrary": false }
+  ],
+  "traceId": null,
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+标签库为空且订单无游离标签时返回空数组：
+
+```json
+{ "code": 200, "message": "成功", "data": [], "traceId": null, "success": true }
+```
+
+#### 错误响应
+
+本次新增（TEST 实测，CUSTOMIZER 非归属角色实测返回）：
+
+```json
+{ "code": 581008, "message": "无权查看此订单", "data": null, "traceId": null, "success": false }
+```
+
+```json
+{ "code": 581045, "message": "房务角色无权查看订单详情，房务仅可配房", "data": null, "traceId": null, "success": false }
+```
+
+订单不存在（既有行为，未变）：
+
+```json
+{ "code": 581401, "message": "订单不存在", "data": null, "traceId": null, "success": false }
+```
+
+#### 业务边界
+
+- 放行/拒绝口径与「查订单已挂标签」完全一致（同一个 `OrderViewGuard.assertOrderReadable`，见该接口业务边界第 1 条的角色表）。
+- 归属守卫排在 `OperatorHolder.get()` 取当前操作人之前（`CollabService.java:250` 早于 `:252`）：`OperatorHolder` 判空只在「拿不到操作人」时拦截，拿得到操作人的越权请求它不管，不能替代归属校验。
+
+---
+
+### 3. 生成电子行程单（对客） `GET /v3/admin/order/{orderId}/itinerary-document`
+
+**VO**: `无请求体 → OrderItineraryDocumentVO`
+
+#### 使用场景
+
+生成对客视角的电子行程单/打印版/核价单（`CUSTOMER`/`CUSTOMER_PRINT`/`CUSTOMER_QUOTE` 三类 `documentType` 共用本接口，前端按值渲染不同模板）。签单（供应商视角 `sign-voucher`）、司机出团单（`print-itinerary`）走另外两个独立接口，不在本次变更范围内。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| Authorization | Header | String | ✅ | - | 管理端登录令牌 |
+| orderId | Path | Long | ✅ | 订单须存在（581401）；当前登录角色须对该订单具备归属读权（581008/581045，本次新增） | 订单 ID |
+| documentType | Query | String | ✅ | `CUSTOMER` / `CUSTOMER_PRINT` / `CUSTOMER_QUOTE`；缺失返回业务码 400 | 文档类型（对客视角） |
+| includeResourceDetail | Query | Boolean | ❌ | 默认 true；`CUSTOMER` 场景可传 false 跳过 Feign | 是否调 Feign 拉资源详情，false 时节点 scenicDetail 等字段为 null |
+
+#### 出参 `Result<OrderItineraryDocumentVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| documentType | String | 回显请求的文档类型 |
+| header | Object | 抬头信息（订单号等；`CUSTOMER_QUOTE` 才含 totalAmount） |
+| travelers | List<Object> | 出行人列表 |
+| days | List<Object> | 按天行程（含节点、场景/餐厅详情） |
+| hotels | List<Object> | 酒店段列表 |
+| feeNotes | List<Object> | 费用说明 |
+| supplies | List<Object> | 随行物资 |
+| transports | List<Object> | 大交通 |
+| summary | Object | 汇总信息 |
+| resourceDetailHealth | Object | 资源详情 Feign 健康度报告（降级不阻断） |
+| generatedAt | String | 生成时间，格式 yyyy-MM-dd HH:mm:ss |
+
+（完整字段树见既有 Swagger `OrderItineraryDocumentVO`；本次变更不涉及该 VO 任何字段，此表只列顶层结构定位用）
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/2100542584106496001/itinerary-document?documentType=CUSTOMER&includeResourceDetail=true
+Authorization: Bearer {token}
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "documentType": "CUSTOMER",
+    "header": { "orderNo": "HL2026092012345" },
+    "travelers": [],
+    "days": [],
+    "hotels": [],
+    "feeNotes": [],
+    "supplies": [],
+    "transports": [],
+    "summary": {},
+    "resourceDetailHealth": { "feignOk": true, "feignError": null },
+    "generatedAt": "2026-09-23 20:10:00"
+  },
+  "traceId": null,
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+`includeResourceDetail=false` 或 Feign 调用失败时，各节点的资源详情字段（如 scenicDetail）为 null，`resourceDetailHealth.feignOk=false` 且 `feignError` 非空，接口仍返回 200，不阻断整份文档：
+
+```json
+{ "code": 200, "message": "成功", "data": { "resourceDetailHealth": { "feignOk": false, "feignError": "resource-service 调用超时" } }, "traceId": null, "success": true }
+```
+
+#### 错误响应
+
+本次新增（TEST 实测，CUSTOMIZER 非归属角色实测返回）：
+
+```json
+{ "code": 581008, "message": "无权查看此订单", "data": null, "traceId": null, "success": false }
+```
+
+```json
+{ "code": 581045, "message": "房务角色无权查看订单详情，房务仅可配房", "data": null, "traceId": null, "success": false }
+```
+
+`documentType` 缺失（既有行为，未变；TEST 实测确认发生在归属守卫之前，源码为通用 Spring 参数绑定异常处理 `GlobalExceptionHandler#handleMissingParam`）：
+
+```json
+{ "code": 400, "message": "缺少必要参数: documentType", "data": null, "traceId": null, "success": false }
+```
+
+订单不存在（既有行为，未变）：
+
+```json
+{ "code": 581401, "message": "订单不存在", "data": null, "traceId": null, "success": false }
+```
+
+#### 业务边界
+
+- 放行/拒绝口径与前两个接口完全一致。
+- `documentType` 缺失的 400 判定在**归属守卫之前**（Spring 参数绑定先于方法体执行），所以「非归属角色 + 不传 documentType」拿到的是 400，不是 581008；这不是本次改动，是既有行为，TEST 已实测确认。
+- 归属守卫（`CollabService.java:417`）与下游第 7 步 `OrderDetailService#getServiceStandard → requireOrderById` 里的同一道守卫会被连续调用两次，是有意保留、非冗余：本处这道是本端点自己的，下游那道挂在一个可选步骤上，不能替代（改动下游步骤的人不会打开本文件）。
+
+---
+
+### 4. 订单详情 - 行程安排 Tab `GET /v3/admin/order/{id}/itinerary`
+
+**VO**: `无请求体 → ItineraryVO`
+
+#### 使用场景
+
+订单详情页「行程安排」Tab：配房/配车的需求与实配对照、未失活配车历史等。本次只补充四个价格字段的说明文字，接口行为、归属校验、响应结构均未变——该端点的归属守卫是既有能力，不是本次新增。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| Authorization | Header | String | ✅ | - | 管理端登录令牌 |
+| id | Path | Long | ✅ | 订单须存在；当前登录角色须对该订单具备归属读权（既有能力，未变） | 订单 ID |
+
+#### 出参 `Result<ItineraryVO>`（仅列本次文档变更涉及的字段，完整契约不在本次变更范围内）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| hotelGroup.assignments[].protoPrice | String | 协议价快照（元/间·晚，house protoPrice）。**本次补充说明：这是供应商采购价，不是对客报价** |
+| hotelGroup.assignments[].settlementPrice | String | 结算价快照（元/间·晚，house settlementPrice）。**本次补充说明：同样是供应商采购价，不是对客报价** |
+| vehicleGroup.assignments[].plannedDailyFee | String | 计划日单价（元/车·天，付给车队的采购价）。**本次补充说明：非对客报价** |
+| hotelGroup.requirement.days[].segments[].candidates[].rooms[].protocolPrice | String | 本房型行协议价（元/间·晚，可为 null）。**本次补充说明：这是供应商采购价，不是对客报价** |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/2100542584106496001/itinerary
+Authorization: Bearer {token}
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "hotelGroup": {
+      "assignments": [
+        { "assignmentId": "700001", "hotelName": "云台山大酒店", "roomType": "大床房", "roomCount": 2, "protoPrice": "588.00", "settlementPrice": "688.00" }
+      ]
+    },
+    "vehicleGroup": {
+      "assignments": [
+        { "plannedDailyFee": "800.00", "driverName": "王师傅" }
+      ]
+    }
+  },
+  "traceId": null,
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+未配房/未配车时 `hotelGroup.assignments`/`vehicleGroup.assignments` 为空数组，各价格字段随之不出现：
+
+```json
+{ "code": 200, "message": "成功", "data": { "hotelGroup": { "assignments": [] }, "vehicleGroup": { "assignments": [] } }, "traceId": null, "success": true }
+```
+
+#### 错误响应
+
+既有行为，未变：
+
+```json
+{ "code": 581008, "message": "无权查看此订单", "data": null, "traceId": null, "success": false }
+```
+
+#### 业务边界
+
+- 该端点走 `OrderController#getItinerary → OrderDetailService.assembleItinerary → requireOrderById`，仍是 `OrderViewGuard.assertOrderReadable`（`OrderDetailService.java:794-803`），**不是**本次新增，本次改动只补了字段说明。
+- 四个价格字段对**团期管理员**（`GROUP_BATCH_MANAGER`，仅限该订单挂在团期下）刻意不脱敏：这是 2026-09-22 管理者拍板的已知设计，理由是团期管理员核对「团期需求」与实配是否对得上，价格本身就是核对基准；同一条定案记在 `OrderViewGuard#assertOrderFinanceReadable` 的 javadoc（`OrderViewGuard.java:164-168`），本端点未被收窄到 `assertOrderFinanceReadable`。
+- 四个字段均为供应商采购成本，不是对客报价；本次只是把这条口径写进了字段注释，不是新发现的行为变化。
+
+---
+
+### 5. 按户打回需求 `POST /v3/admin/order/group-batch/{groupBatchId}/requirement/reject`
+
+**VO**: `RejectRequirementReqVO → GroupBatchRequirementRejectRespVO`
+
+#### 使用场景
+
+团期「查看需求」页批量打回：运营勾选若干户，把已提交需求退回定制师重填。本次只补充 `resourceType` 字段的契约说明，请求/响应结构、错误码均未变。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| Authorization | Header | String | ✅ | - | 管理端登录令牌 |
+| groupBatchId | Path | Long | ✅ | 团期须存在且处于可打回阶段（589501） | 团期主订单 ID |
+| orderIds | Body | List<Long> | ✅ | 1~200 户，服务端去重 | 被打回的子订单 ID 列表 |
+| reason | Body | String | ✅ | ≤500 字 | 打回原因 |
+| resourceType | Body | String | ❌ | `HOTEL` / `VEHICLE` / `ALL`，默认 `ALL`；**本次补充说明**：`VEHICLE`/`ALL` 车侧仅覆盖游览车（TRAVEL），不含接送机（TRANSFER） | 打回的资源类型 |
+
+#### 出参 `Result<GroupBatchRequirementRejectRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| groupBatchId | String | 团期聚合主键 |
+| requirementConfirmed | Boolean | 团期需求整体确认标记（本端点成功后恒 false） |
+| rejected | List<Object> | 本次被打回的需求条目（每户每资源类型一条） |
+| rejected[].orderId | String | 子订单 ID |
+| rejected[].resourceType | String | 资源类型：HOTEL / VEHICLE |
+| rejected[].requirementId | String | 被打回的需求行 ID |
+| rejected[].sourceStatus | String | 打回前的需求状态：PENDING_REVIEW / PENDING |
+
+#### 请求示例
+
+```json
+{
+  "orderIds": [60123456789001, 60123456789002],
+  "reason": "房间需求与套餐不匹配，请重新填写",
+  "resourceType": "ALL"
+}
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "groupBatchId": "1867000000001",
+    "requirementConfirmed": false,
+    "rejected": [
+      { "orderId": "60123456789001", "resourceType": "HOTEL", "requirementId": "90011223344", "sourceStatus": "PENDING_REVIEW" }
+    ]
+  },
+  "traceId": null,
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+写接口没有空数据场景；所有勾选户都不可打回时整单拒绝（见错误响应 589534），不会返回 `rejected: []` 的成功响应。
+
+#### 错误响应
+
+本次澄清的既有行为（`resourceType=ALL` 且勾选户只有接送机需求）：
+
+```json
+{ "code": 589534, "message": "子订单 {0} 不属于本团期、已退出或无可打回的需求", "data": null, "traceId": null, "success": false }
+```
+
+其余既有错误码未变：
+
+```json
+{ "code": 589501, "message": "团期状态不允许当前操作", "data": null, "traceId": null, "success": false }
+```
+
+```json
+{ "code": 589535, "message": "子订单 {0} 已分房，请先由房务调整配房后再打回", "data": null, "traceId": null, "success": false }
+```
+
+#### 业务边界
+
+- **本次澄清、代码逻辑未变**：`resourceType=ALL` 不等于「全部资源」——车侧只走游览车（TRAVEL），接送机（TRANSFER）需求不在本入口可见范围内。一户只有接送机需求时，不是「打回了但没生效」，是该户在候选筛选阶段就没被选中，因「无可打回的需求」落 589534。
+- 接送机需求要打回，走单户接口 `POST /v3/admin/order/{id}/vehicle-requirement/reject?kind=TRANSFER`，本次未变。
+- 任一户不可打回则整单拒绝、所有户零副作用（含合法户在内）；不存在部分成功。
+
+---
+
+## 四、契约约束与正确调用方式（接口类必写）
+
+> 本节只写**后端接受/拒绝 payload 的规则**，不写 UI 渲染建议。
+
+### ✅ 正确 / ❌ 错误 payload 对照
+
+| 场景 | 请求 | 结果 |
+|------|------|------|
+| ✅ SUPER_ADMIN 读任意订单的标签/弹窗数据/行程单 | 上述三接口任一 | 200 |
+| ✅ 定制师读自己归属的订单 | 上述三接口任一，orderId=自己 consultantId 名下订单 | 200 |
+| ✅ 团期管理员读团期子订单（`order.groupBatchId != null`） | 上述三接口任一 | 200 |
+| ❌ 定制师/客服/运营/财务读他人归属的订单 | 上述三接口任一，orderId=非本人订单 | 581008（本次新增） |
+| ❌ 团期管理员读散客单（`order.groupBatchId == null`） | 上述三接口任一 | 581008（本次新增） |
+| ❌ 房务管理员/房务组长读任意订单的标签/弹窗数据/行程单 | 上述三接口任一 | 581045（本次新增，前置于归属判定） |
+| ❌ `itinerary-document` 不传 `documentType` | 任意角色 | 400「缺少必要参数: documentType」（既有行为，发生在归属守卫之前） |
+| ❌ 批量打回 `resourceType=ALL`、勾选户只有接送机需求 | `POST .../requirement/reject` | 589534（既有行为，本次补充契约说明） |
+
+- 三个协作域端点（tags/tag-picker/itinerary-document）的归属判定口径完全一致，判定顺序恒为：订单存在性 → 房务前置拒绝（581045）→ ADMIN/SUPER_ADMIN/VEHICLE_MANAGER 放行 → 团期管理员限团期子订单放行 → 其余角色须为归属定制师，否则 581008（`OrderViewGuard.java:267-298`）。
+- `GET /{id}/itinerary` 的归属守卫本次未变（既有能力）；仅字段说明变化。
+- 批量打回 `resourceType` 字段行为本次未变；仅补充契约说明，防止把 `ALL` 误读为「全部资源类型」。
+
+---
+
+## 五、数据库行为（涉及写操作时必写）
+
+- 无 Flyway migration、无 DDL、无表结构变更。
+- 三个协作域端点新增的归属守卫是纯内存态角色/字段判定，复用 Service 层判空后已持有的 `OrderInfo` 实体，零额外 DB 查询。
+- 批量打回 `doReject` 的写库范围与事务边界本次未变：仍在团级 `Lock4j` 锁 + `@Transactional(rollbackFor=Exception.class)` 内逐户跑 `rejectRequirementByGroupAdmin` + `groupBatchService.rejectRequirement`；任一户校验失败即整单回滚、零写入。
+
+---
+
+## 六、边界行为
+
+- 非请求上下文（MQ 回放/定时任务/内部 Feign/单测）无角色 → 三个新增守卫的端点与既有的 `/itinerary` 端点均视为系统态直接放行（`OrderViewGuard.assertReadable` 捕获 `IllegalStateException` 后 `return`，`OrderViewGuard.java:271-276`）。
+- 房务角色的 581045 判定先于归属判定，与该订单是否属于本人无关——房务管理员/组长在这三个端点上无论如何都拿不到数据，只能通过配房相关接口工作。
+- 团期管理员的放行只看 `OrderInfo.getGroupBatchId() != null`（订单主表原始列），散客单一律 581008，即使该团期管理员对其他团期子订单有权限。
+- `itinerary-document` 的守卫在方法体第 2 步（订单判空之后）触发，比 `documentType` 缺失的 400 校验晚——所以「非归属角色 + 不传 documentType」拿到的是 400，不是 581008。
+
+---
+
+## 六.6、修改前后对比（修改/删除类接口必写，新增跳过）
+
+### 字段级对比
+
+| 接口 | 改前 | 改后 |
+|------|------|------|
+| `GET .../tags` | 无归属校验，请求体/响应体结构不变 | 新增 581008/581045 两种拒绝响应，请求体/响应体结构不变 |
+| `GET .../tag-picker` | 同上 | 同上 |
+| `GET .../itinerary-document` | 同上 | 同上 |
+| `GET .../itinerary` 四个价格字段 | `@ApiModelProperty` 文案未标注采购价/对客报价区分 | 文案补充「供应商采购价，非对客报价」；字段名、类型、序列化方式均不变 |
+| `resourceType`（打回请求体） | 字段说明未提及 TRAVEL/TRANSFER 边界 | 字段说明补充「ALL/VEHICLE 车侧仅覆盖 TRAVEL，不含 TRANSFER」；`@Pattern` 校验、默认值、字段名均不变 |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| 任意后台角色传任意 orderId 访问已挂标签/打标签弹窗/电子行程单 | 200，直接返回目标订单数据（含他人订单） | 非放行角色 581008 或 581045，读不到他人订单数据 |
+| `resourceType=ALL` 批量打回、勾选户只有接送机需求 | 该户因「无可打回的需求」落 589534，行为未变 | 行为完全未变，仅补充契约说明 |
+| `/itinerary` 四个价格字段的语义 | 字段名暗示价格但未明确采购价/售价 | 字段注释明确标注为供应商采购价，防止误当对客报价展示 |
+
+---
+
+## 六.7、影响评估（修改/删除类必写）
+
+- **是否破坏向后兼容**：三个协作域端点对非放行角色（多数后台角色，若非订单归属定制师）是破坏性收紧——改前 200 能拿到数据，改后 581008/581045。对归属定制师、`ADMIN`/`SUPER_ADMIN`/`VEHICLE_MANAGER`，以及读团期子订单的团期管理员，行为不变仍 200。`/itinerary` 与批量打回两个纯文档改动零行为影响。
+- **前端是否必须同步上线**：三个协作域端点——如果前端当前允许任意角色打开任意订单的标签/打标签弹窗/生成行程单（例如客服临时查看非本人订单），上线后这部分角色会开始收到 581008/581045，前端需要能正确展示失败提示（走通用错误提示即可，不需要特殊 UI，但不能吞掉这个错误）。
+- **前端 workaround 清理点**：无——本次是后端补权限收紧，不涉及前端此前绕过某个限制的逻辑。
+
+---
+
+## 七、不影响范围（显式声明, 帮前端/QA 缩小排查面）
+
+- **仅影响**：`GET /v3/admin/order/{orderId}/tags`、`GET /v3/admin/order/{orderId}/tag-picker`、`GET /v3/admin/order/{orderId}/itinerary-document` 三个端点新增归属校验；`GET /v3/admin/order/{id}/itinerary` 与 `POST /v3/admin/order/group-batch/{groupBatchId}/requirement/reject` 仅字段说明文案变化。
+- **零影响**：
+  - `CollabAdminController` 的四个写端点（`addTag`/`deleteTag`/`patchTag`/`replaceTags`）：本次未改动，仍走既有的 `OrderViewGuard.assertNotGroupBatchManagerWrite()`（只拒团期管理员写操作，不判定其余角色归属）。**已知缺口**：这四个写端点至今不判订单归属，读面收紧后形成「看不到但能改」，由 #8292 承接（口径未定）。
+  - `OrderViewGuard.assertOrderFinanceReadable` 覆盖的财务/成本/流水端点：本次未改动其挂载。
+  - 接送机相关的批量确认入口（`batchConfirmTransfer` 等）与单户打回接口 `POST .../vehicle-requirement/reject?kind=TRANSFER`：本次未变。
+  - `ItineraryVO`、`RejectRequirementReqVO`、`GroupBatchRequirementRejectRespVO` 的字段名、类型、序列化方式、`@Pattern`/`@Size`/`@NotEmpty` 校验规则：全部未变。
+
+---
+
+## 八、测试环境已验证
+
+部署：hl-order-service-v3 dev-v3 @ `841ea7b06`，2026-09-23 20:07:37 部署，deploy-status STATE=ok，BEHIND 0（读数来源 #8170 评论 #60783）。
+
+真实网关实测（夹具订单 `2100542584106496001`，归属定制师为他人）：
+
+```
+GET /v3/admin/order/2100542584106496001/tags               CUSTOMIZER（非归属） → 581008 ✓
+GET /v3/admin/order/2100542584106496001/tag-picker          CUSTOMIZER（非归属） → 581008 ✓
+GET /v3/admin/order/2100542584106496001/itinerary-document  CUSTOMIZER（非归属） → 581008 ✓
+GET /v3/admin/order/2100542584106496001/tags               SUPER_ADMIN（对照）  → 200 ✓
+GET /v3/admin/order/2100542584106496001/tag-picker          SUPER_ADMIN（对照）  → 200 ✓
+GET /v3/admin/order/2100542584106496001/itinerary-document  SUPER_ADMIN（对照）  → 200 ✓
+GET /v3/admin/order/2100542584106496001/itinerary-document  不带 documentType   → 400，先于守卫触发 ✓
+```
+
+单元测试：本单随 PR 新增/改动测试文件 `CollabServiceTest`（+80 行，补三接口归属守卫放行/拒绝用例）、`CollabServiceItineraryDocumentTest`（+60 行，补 itinerary-document 归属守卫用例）、`GroupBatchRequirementServiceTest`（+50 行，补 resourceType 契约用例），随 PR 一并合并。
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#8170](https://git.1814.love/wx/HL/issues/8170)
+- 关联 PR: [wx/HL#8290](https://git.1814.love/wx/HL/pulls/8290)
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8170](https://git.1814.love/wx/HL/issues/8170)
+- **PR**: [#8290](https://git.1814.love/wx/HL/pulls/8290)
+- **Merge commit**: [841ea7b06](https://git.1814.love/wx/HL/commit/841ea7b06)
+
+### 联系人
+
+- **后端负责人**: @wx
+- **前端负责人**: @mmg
@@ -0,0 +1,348 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8194"
+title: "配置位守卫 582117 的触发集合扩大到「除 DRIVER / OTHER 以外的全部角色」"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "not_required"
+frontend_status: "not_required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "工单 #8194 补的是 #8148 留下的残留缺口。角色↔人员类型的守卫 582117 判的是「该角色在配置位字典里查不到归属位」，而它的分流判据（GroupBatchStaffSlotResolver#participatesInSlotsByFallback）读的是编译期常量兜底名单，只认 GUIDE / LEADER / PHOTOGRAPHER。问题是 #7079 / #8148 立下的能力恰恰是「业务在字典页面加一行就能把某个人员类型配进配置位、不发版」——靠字典新增出来的角色永远不在这张常量名单里，于是「字典给某位加一行 → 有人按它配了人 → 那行又被删掉」这一形态仍走静默放行分支：接口 200、脏行落库、并异步扇出到团内全部活跃订单，该角色的 582114 当场失效，要到结算对账才发现人岗对不上。关键一点是撞上它不需要有人手搓请求——resolveStoredStaffRole 会把落库的 staff_role 改写成人员的真实类型（字典角色），前端回显后原样提交回来，系统自己就会产出那个落进缺口的 staffRole 值。修法（2026-09-23 定案 B，判据翻面）：把「本该有位」的判据从「在不在兜底名单里」换成「不在结构性豁免闭集 STRUCTURALLY_SLOT_EXEMPT_ROLES（= DRIVER / OTHER）里」，豁免闭集落成显式常量集合并从 SettlementStaffRoleEnum 取值，方法名同步改为 requiresSlotMembership（改完它不再读 fallbackTypes()，名字与语义必须同批改）。行为变化：GUIDE_ASSISTANT / STUDY_TEACHER / LIFE_TEACHER 三个「只可能靠字典纳入配置位」的角色，在「字典里查不到归属位」时由静默 200 落库变为返回 582117；DRIVER / OTHER 照旧放行（OTHER 的常态就是不属于任何配置位，保护它会拒掉每一次正常的杂项人员配置，那是删功能不是补洞）。已知边界（按 #8194 决策点 4 有意保留、不在本单修）：OTHER 在 VALID_STAFF_TYPES 里，业务能把 OTHER 写进某个位的字典再删掉，那一形态仍走静默放行。生产代码由 PR #8259 合入 dev-v3（squash 提交 f6d21648b）。2026-09-23 测试服已实测：PUT /v3/admin/group-batch/2102640646949105666/staff 提交 staffRole=GUIDE_ASSISTANT 返回 code=582117（HTTP 200，文案完整），读回确认零写入；同端点 staffRole=DRIVER 与 staffRole=OTHER 均返回 code=200 成功；探测插入的两行已用 scopeRoles=[DRIVER,OTHER] + staffList=[] 还原，读回与探测前逐字段一致。契约（路径 / 方法 / 权限 / 入参字段与取值域 / 成功响应结构）零变更——BatchStaffConfigReqVO 只加了 javadoc（含该表）。前端结论(2026-09-23):5821xx 全族在 hl-ui v2.1 无专门分支,统一由拦截器按 code 非成功 toast 后端 message;582117 文案已点名角色并指向配置位字典页,完整直出即可。命中后正确动作是去字典页补行,重试仍被拒不会误操作——与 #8123/#8148 既定拍板一致,维持通用 toast,不做专门引导,零改动闭环。后端订正三处(降级态字典角色同拒 582117/示例 payload 纠错/补缓存窗口与存量脏行边界)前端已审阅:均为后端行为澄清,契约零变化,文案仍拦截器直出,前端 not_required 结论不变。"
+updated_at: "2026-09-23"
+# ⚠️ 本条目于 2026-09-23 由独立对抗评审复核后订正过三处：①降级态（字典服务不可用）对字典角色同样返回 582117，原文「不会变成一律拒绝」只对内置角色成立；②请求示例原用了修复后必被拒的 payload；③补记缓存窗口与存量脏行两条边界。
+base: "dev-v3"
+---
+
+# 团期人员配置: 配置位缺失守卫 582117 的触发集合扩大到全部非豁免角色（管理后台）
+
+> **服务**: hl-order-service-v3（端口 8086/8186）
+> **PR**: #8259（squash 提交 `f6d21648b`）
+> **Issue**: #8194（前置 #8148 / #8122 / #7079）
+> **日期**: 2026-09-23
+> **影响范围**: 管理后台团期详情页的「配导游 / 配摄影」弹窗保存动作
+
+---
+
+## ⚠️ 关键变化
+
+**这个端点返回 `582117` 的角色集合变大了**，路径、入参、成功响应结构一律不变。
+
+以前只有 `GUIDE` / `LEADER` / `PHOTOGRAPHER` 三个内置角色在「字典里查不到归属位」时会被 582117 拒掉；现在**除 `DRIVER` 与 `OTHER` 以外的任何角色**都会被拒，其中就包括业务自己通过配置位字典启用过的 `GUIDE_ASSISTANT` / `STUDY_TEACHER` / `LIFE_TEACHER`。
+
+调用方以前以为的是：`staffRole=GUIDE_ASSISTANT` 这类「字典角色」提交时不会触发 582117（它压根不在守卫的名单里）。
+实际现在是：**它同样会触发 582117**，而且这批请求本来就是脏数据（角色没有任何人员类型校验背书）。
+
+`DRIVER` / `OTHER` 的行为**不变**，仍放行。
+
+---
+
+## 一、背景
+
+配置位成员集合自 #7079 起由数据字典决定（`group_batch_staff_slot_guide` / `group_batch_staff_slot_photographer`），业务在字典管理页面加一行就能把某个人员类型配进这个位，**不发版**。`GroupBatchStaffSlotResolver` 的类 javadoc 原文就是这句：「业务在字典管理页面给 `group_batch_staff_slot_guide` 加一行 `STUDY_TEACHER`，研学老师就能配进导游位，不发版」。
+
+#8148 把「角色 → 允许的人员类型」这半边也迁到了字典，并引入 582117：当某角色在字典里查不到归属位时，本该有位的角色要被拒，而不是沿袭改前的「一律不校验」。但 #8148 的分流判据读的是**编译期常量兜底名单**（`GUIDE` / `LEADER` / `PHOTOGRAPHER`），它恰恰**不包含**任何「靠字典新增出来的角色」——那正是这个新能力的产物。结果是：
+
+| 「查不到归属位」的成因 | #8148 之后的行为 | 是否正确 |
+|---|---|---|
+| `DRIVER` / `OTHER` 这类结构性不参与配置位的角色 | 放行 | ✅ 正确 |
+| 内置角色（`GUIDE` / `LEADER` / `PHOTOGRAPHER`）被从仍非空的字典里删掉 | 拒绝 582117 | ✅ 正确 |
+| **字典启用过的角色**（`GUIDE_ASSISTANT` / `STUDY_TEACHER` / `LIFE_TEACHER`）被删回 | **静默放行** | ❌ 缺口 |
+
+第三种形态的失败后果与加 582117 之前**逐字相同**：HTTP 200、`Result.success`、前端看不到任何异常；落库成功并异步扇出到团内全部活跃订单；静默放行分支**一行日志都不打**。
+
+而撞上它**不需要有人手搓请求**：
+
+1. 业务给导游位字典加一行 `GUIDE_ASSISTANT`；
+2. 前端按导游位提交 `staffRole=GUIDE`、该人真实 `staffType=GUIDE_ASSISTANT` → 校验通过 → `resolveStoredStaffRole` 把**落库的 `staff_role` 改写成 `GUIDE_ASSISTANT`**；
+3. 下次打开弹窗，回显的既有行角色就是 `GUIDE_ASSISTANT`，提交回来 `staffRole=GUIDE_ASSISTANT`；
+4. 此后运维把那行字典删掉 ⇒ 第 3 步那种请求走进静默分支，**且此时 `staffRole=GUIDE_ASSISTANT` 配任何 `staffType` 都能过**。
+
+**修法（#8194 决策点 5 定案 B：判据翻面）**：把「本该有位」的判据从「在不在兜底名单里」换成「**不在结构性豁免闭集里**」。豁免闭集 = `{DRIVER, OTHER}`（#8194 决策点 4 定案），落成 `GroupBatchStaffSlotResolver#STRUCTURALLY_SLOT_EXEMPT_ROLES` 这一个显式常量集合。方法随之改名 `participatesInSlotsByFallback` → `requiresSlotMembership`——改完它不再读 `fallbackTypes()`，名字与语义必须同批改，否则留下「命名断言别处行为」的静默漂移点。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 保存团期人员配置 | PUT | `/v3/admin/group-batch/{productBatchId}/staff` | 修改接口 | 582117 的触发角色集合扩大；路径 / 入参 / 权限 / 成功响应结构不变 |
+
+网关无改动（没有新增 `/admin/` Controller，路由不动）。
+
+---
+
+## 三、接口详情
+
+### 1. 保存团期人员配置 `PUT /v3/admin/group-batch/{productBatchId}/staff`
+
+**VO**: `BatchStaffConfigReqVO`
+
+#### 使用场景
+
+团期详情页「配导游 / 配摄影」弹窗点保存。按 `scopeRoles`（不传即整期）软删旧配置、写入新配置、异步扇出到各活跃子订单，并按配置结果回填 `guide_ready` / `photographer_ready`。
+
+🔴 **路径参数是产品侧排期 ID，不是团期聚合主键**。端点名叫 `group-batch`，但 `{productBatchId}` 吃的是 `group_tour_batch.batch_id`。响应体里另有一个 `groupBatchId`，那才是订单侧 `order_group_batch` 的主键，两者不是同一个值。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| productBatchId | path | Long | 是 | 正整数，产品侧排期 ID | 团期所属班期；未建团返 589553 |
+| scopeRoles | body | List&lt;String&gt; | 否 | 传了就不能是空数组；元素非空白且须在员工角色取值域内 | 限定本次覆盖的角色范围，不传则整期覆盖 |
+| staffList | body | List&lt;Item&gt; | 是（可在服务层为空数组） | `@NotNull`；`[]` 表示清空覆盖范围内的配置 | 覆盖范围内的最终状态 |
+| staffList[].staffId | body | Long | 是 | 须命中候选人员 | 人员 ID |
+| staffList[].staffRole | body | String | 是 | `@NotBlank` + `@Pattern`，须与人员类型相符，否则 582114 | 角色取值域见「六.5」 |
+| staffList[].sortOrder | body | Integer | 否 | — | 展示排序，默认 0 |
+| staffList[].remark | body | String | 否 | `@Size(max=500)` | 备注 |
+
+#### 出参 `Result<BatchStaffConfigRespVO>`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| productBatchId | Long | 回显路径参数 |
+| groupBatchId | Long | 团期聚合主键，与路径参数不是同一个值 |
+| staffList | List | 保存后的整期最终状态（含 `staffRoleName` / `reporterRankName` 等中文 Label） |
+| affectedOrderCount | Integer | 本次扇出触及的活跃子订单数 |
+
+#### 请求示例
+
+```http
+PUT /v3/admin/group-batch/2102640646949105666/staff HTTP/1.1
+Host: api.test.1814.love:9443
+Authorization: Bearer <admin token>
+Content-Type: application/json
+
+{"staffList":[{"staffId":1002,"staffRole":"GUIDE","sortOrder":0,"remark":"hl8194-ok"}]}
+```
+
+> ⚠️ 把上面的 `staffRole` 换成 `GUIDE_ASSISTANT`（或其他字典角色）在**修复后**会返回 582117，不再是 200——见「错误响应」。这正是本单的行为变化。
+
+#### 响应示例
+
+成功时：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "productBatchId": "2102640646949105666",
+    "groupBatchId": "2102640736900116481",
+    "affectedOrderCount": 1,
+    "staffList": [
+      {"id": "2102640914386284545", "staffId": 1002, "staffRole": "GUIDE", "staffRoleName": "导游", "staffName": "李雪梅", "reporterRank": "NONE"}
+    ]
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+`staffList` 传空数组即清空覆盖范围内的配置，返回 200，`staffList` 为空数组、`affectedOrderCount` 为实际扇出订单数。
+
+配置位字典读挂 / 读空时，`typesOf` 回落内置默认值（导游位 `GUIDE+LEADER`、摄影位 `PHOTOGRAPHER`）：**内置角色**（`GUIDE` / `LEADER` / `PHOTOGRAPHER`）的保存照常成功，这条降级保证本单未动。
+
+⚠️ **但内置名单之外的角色不是这样**：`GUIDE_ASSISTANT` / `STUDY_TEACHER` / `LIFE_TEACHER` 不在兜底名单里，字典服务不可用期间它们依然「查不到归属位」⇒ **同样返回 582117**。也就是说 582117 现在有两种成因：①字典可读、但该角色不在任何配置位里（修复动作是补回那一行字典）；②字典服务不可用、且该角色不是内置兜底成员（修复动作是恢复字典服务）。**文案当前不区分两者**，排查时请先确认字典服务可用性。
+
+#### 错误响应
+
+新增会命中的情境：**字典里查不到该角色的归属位，且该角色不在豁免闭集里**（`{0}` 由运行期填入角色名）：
+
+```json
+{"code": 582117, "message": "角色 GUIDE_ASSISTANT 未归属任何人员配置位，无法校验人员类型；请检查配置位字典是否被误删", "data": null, "success": false}
+```
+
+本端点此前已有、本次不改动的其余业务码（一并列出便于对照）：
+
+```json
+{"code": 582114, "message": "所选人员的角色与其人员类型不符，请重新选择", "data": null, "success": false}
+{"code": 582115, "message": "提交的人员角色超出本次保存声明的范围", "data": null, "success": false}
+{"code": 582116, "message": "本次保存声明的角色范围（GUIDE）只覆盖了配置位的一部分，还缺少 LEADER；同一配置位的角色必须一起声明，否则位内其余人员会被留在库里", "data": null, "success": false}
+{"code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false}
+```
+
+全部走 **HTTP 200**，不是 5xx。
+
+#### 业务边界
+
+- **582117 有两种成因，排查顺序是先服务后内容**：①字典可读、但该角色不在任何配置位里（被删掉，或从来没配过）；②**字典服务（hl-user-service）不可用**而该角色又不是内置兜底成员（`GUIDE` / `LEADER` / `PHOTOGRAPHER`）。此时文案说的「字典是否被误删」会指错方向——先去字典页面看会发现那行可能压根没删过。
+- **被判定的不是「你这个角色对不对」，而是「这个角色的归属位是不是丢了」**。角色本身合法（在 `@Pattern` 取值域内）但字典里没有它的位 → 582117；位找得到但人岗不符 → 582114。两者互补。
+- **修复动作在配置位字典页面，不在这个弹窗里**，所以文案点名角色并指向字典，适合原样透出给运营。
+- **豁免闭集是 `DRIVER` 与 `OTHER`**，两者在任何字典状态下都不做角色↔人员类型校验，582117 与 582114 都不触发。
+- 被 582114 / 582115 / 582116 / 582117 任一码拒绝时**零写入**——所有校验闸都在写库之前，且发生在注册 `afterCommit` 扇出回调之前，回读会看到与提交前逐字相同的配置。
+- 导游位并收 `GUIDE` 与 `LEADER`：只传 `["GUIDE"]` 却选了领队会命中 582115，只传 `["GUIDE"]` 而位内还有 LEADER 会命中 582116。
+
+---
+
+## 四、契约约束与正确调用方式
+
+> 本节只写**后端接受/拒绝 payload 的规则**，不写 UI 渲染建议。
+
+### 契约面零变化，行为面有变化
+
+| 面 | 是否变化 | 依据 |
+|---|---|---|
+| 路径 / HTTP 方法 / 权限码 | 不变 | Controller 未动 |
+| 入参字段、类型、必填性、`@Pattern` 取值域 | 不变 | `BatchStaffConfigReqVO` 只加了 javadoc |
+| 成功响应结构 | 不变 | `BatchStaffConfigRespVO` 未动 |
+| **582117 的触发角色集合** | **变化** | Service 的分流判据翻面 |
+
+### ✅ 正确 / ❌ 错误 payload 对照
+
+| 场景 | payload | 结果 |
+|------|---------|------|
+| ✅ 内置角色、字典正常 | `{"staffList":[{"staffId":1002,"staffRole":"GUIDE"}]}` | 200，落库 `staffRole=GUIDE` |
+| ✅ 结构性豁免角色 | `{"scopeRoles":["DRIVER"],"staffList":[{"staffId":1002,"staffRole":"DRIVER"}]}` | 200，落库 `staffRole=DRIVER` |
+| ✅ 结构性豁免角色 | `{"scopeRoles":["OTHER"],"staffList":[{"staffId":1002,"staffRole":"OTHER"}]}` | 200，落库 `staffRole=OTHER` |
+| ✅ 字典已收录该角色 | 字典里 `group_batch_staff_slot_guide` 含 `GUIDE_ASSISTANT`，提交 `staffRole=GUIDE` 且该人 `staffType=GUIDE_ASSISTANT` | 200，落库 `staffRole=GUIDE_ASSISTANT` |
+| ❌ 字典角色但字典里已查不到位 | `{"staffList":[{"staffId":1002,"staffRole":"GUIDE_ASSISTANT"}]}` | 200 + `code=582117`，零写入 |
+| ❌ 提交越界的人 | `{"scopeRoles":["GUIDE"],"staffList":[{"staffId":1002,"staffRole":"LEADER"}]}` | 200 + `code=582115`，零写入 |
+
+### 调用方的正确动作
+
+- **命中 582117 时不要重试**，也不要自动改写 `staffRole`——正确动作是**去配置位字典页面把缺的那一行补回来**（或确认为什么它被删了），再重试保存。文案里的角色名就是缺的那一个。
+- **判成败一律看 `code`，不要看 HTTP status**：本端点的业务失败全是 HTTP 200。
+- 保存成功后若调用方缓存了 `guide_ready` / `photographer_ready`，需重新拉取团期详情。
+
+---
+
+## 五、数据库行为
+
+- 保存：按 `scopeRoles` 范围（不传即整期）软删旧配置行 → 写入新配置行 → 注册 `afterCommit` → 异步扇出到各活跃子订单（`order_staff_assignment` 中 `source=GROUP_BATCH` 的行整删整插）→ 回填团期行的两个 ready 标志。
+- 本次改动**不改变任何一步的写内容**，只改变「哪些请求会被挡在写库之前」。
+- 被 582114 / 582115 / 582116 / 582117 任一码拒绝时**零写入**：校验发生在 `buildToInsert` 与 `doSaveInTransaction` 之前，且 `afterCommit` 扇出回调**尚未注册**（注册动作在事务段内部、软删与插入之后）。
+
+---
+
+## 六、边界行为
+
+- **`DRIVER` / `OTHER` 不受本单影响**：两者在任何字典状态下都放行，与改前一致。
+- **字典读挂 / 读空不降级成拒绝**：`typesOf` 回落内置默认值，内置角色（`GUIDE` / `LEADER` / `PHOTOGRAPHER`）照常保存。
+- **将来往 `@Pattern` 里加第 9 个取值**而忘了判断它属不属于豁免闭集时，新角色默认落进「本该有位」侧 ⇒ 那一侧是**拒绝**（响亮失败、当场被发现），不是静默放行。失败方向正确。
+- **已知边界，不在本单修**：`OTHER` 在 `VALID_STAFF_TYPES` 里，业务**能**把 `OTHER` 写进某个位的字典再删掉，那一形态仍走静默放行。判据是：`OTHER` 的常态化就是不属于任何配置位，把它移出豁免闭集会拒掉每一次正常的杂项人员配置；而「把『其他』纳入『导游位』」本身是配置位语义的误用（等于宣告「其他类型的人算导游」），错的是那行字典。
+- **存量脏行的连带影响（本单不修，但必须知道）**：字典行被删之后库里已有的 `staff_role='GUIDE_ASSISTANT'` 行不再属于任何配置位，整位守卫 582116 也判不到它，这些行不会被 `scopeRoles` 的删除窗口覆盖或重建。⚠️ 更要紧的是：**这类存量行会被前端原样回显提交**，而校验是**逐行**做的——只要该团期的保存请求里带上这样一行且 `staffRole` 仍在缺口集合内，**整次保存（含不传 `scopeRoles` 的整期覆盖）都会返回 582117**。是否已有这类存量行未在本次取证中统计（生产库只读盘点属独立动作）。治理另立工单。
+- **缓存窗口**：`typesOf` 是固定 5 分钟 TTL 的实例本地缓存（`@VettedLocalCache`）。字典改完到全部实例生效之间，同一请求可能一台放行、一台返回 582117。所以「删回后不再静默放行」是**有界**结论：最长 5 分钟、按实例收敛。
+- **判据不认识「历史」**：`requiresSlotMembership` 只看字典**当前**内容。因此「从没在任何配置位字典里出现过」与「加过又被删回」走同一条拒绝分支，而文案一律写成「是否被误删」。首次配置某类人员（业务还没往字典加那一行）时会看到这句——正确动作是**去对应配置位字典加一行**，不是去查删除记录。
+
+---
+
+## 六.5、枚举 / 数据字典
+
+### staffRole（取值域来自 `BatchStaffConfigReqVO.STAFF_ROLE_PATTERN`）
+
+**所属字段**: `staffList[].staffRole` / `scopeRoles[]` | **类型**: `String`
+
+下表说的是「**该角色在配置位字典里查不到归属位时**」修复后走哪条分支。**分母就是从 `@Pattern` 常量抄下来的这 8 个**（并有单测 `GroupBatchStaffRoleSlotGuardTest#patternValueDomain_classifiedOneByOne` 机械守住：常量改了而表没跟，用例先红）。
+
+| 取值 | 分支 | 理由 |
+|---|---|---|
+| `GUIDE` | 拒绝 582117 | 导游位内置成员；默认字典下查得到位，查不到说明那一行被删了 |
+| `LEADER` | 拒绝 582117 | 同上（导游位并收导游与领队） |
+| `PHOTOGRAPHER` | 拒绝 582117 | 摄影位内置成员；查不到说明那一行被删了 |
+| `GUIDE_ASSISTANT` | **拒绝 582117（本单新增覆盖）** | 只可能靠字典被纳入配置位；「加过再删回」正是本单修的形态 |
+| `STUDY_TEACHER` | **拒绝 582117（本单新增覆盖）** | 同上 |
+| `LIFE_TEACHER` | **拒绝 582117（本单新增覆盖）** | 同上 |
+| `DRIVER` | 放行 | 结构性豁免：车务派车投影产生，资源域没有这个人员类型，也配不进任何位的字典 |
+| `OTHER` | 放行 + 已知边界 | 结构性豁免：常态就是不属于任何配置位，保护它会拒掉正常的杂项人员配置。代价是「`OTHER` 被某位字典纳入后再删掉」仍静默放行，本单不修 |
+
+---
+
+## 六.6、修改前后对比
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|---|---|---|
+| `staffRole=GUIDE_ASSISTANT`（字典里查不到归属位） | **静默 200 + 落库 + 异步扇出**，582114 当场失效 | 582117，零写入 |
+| `staffRole=STUDY_TEACHER` / `LIFE_TEACHER`（同上） | 同上 | 582117，零写入 |
+| `staffRole=LEADER` 被从非空字典删掉 | 582117（#8148 已建立） | **不变** |
+| `staffRole=DRIVER` / `OTHER` | 放行 | **不变** |
+| 字典读挂 / 读空（内置角色） | 回落内置默认值，放行 | **不变** |
+| 字典读挂 / 读空（字典角色 `GUIDE_ASSISTANT` 等） | **静默 200** | **582117，零写入**（降级态无法区分「被删掉」与「读不到」，见「六、边界行为」） |
+| 判据实现 | `participatesInSlotsByFallback` 读编译期常量 `fallbackTypes()` | `requiresSlotMembership` 判「不在结构性豁免闭集 `{DRIVER, OTHER}` 里」 |
+| 路径 / 入参 / 权限 / 成功响应结构 | — | **零变化** |
+
+### 字段级对比
+
+无字段变化（`BatchStaffConfigReqVO` 只增加 javadoc，`BatchStaffConfigRespVO` 未动）。
+
+---
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 否（契约零变化）。但存在**面向管理后台的行为变化**：原本能保存成功的几个角色的请求会开始被 582117 拒——那批请求本就是脏数据（角色没有任何人员类型校验背书）。
+- **前端是否必须同步上线**: **否**。5821xx 这一族在 hl-ui v2.1 上没有专门分支，统一由 `src/utils/request.js` 的响应拦截器按「code 非成功值」toast 后端 message，故 582117 在这几个角色上出现时前端零改动即有基本行为（文案本身已是可直接展示的完整句子，并指向修复动作所在处）。
+- **前端可选优化**：命中 582117 时提示语可引导运营去「配置位字典」页面，并保留用户已填表单；不引导也不会误操作（重试仍会被拒）。
+- **前端 workaround 清理点**: 无。
+
+---
+
+## 七、不影响范围
+
+- **零影响**:
+  - 路径、HTTP 方法、权限码、网关配置
+  - 入参字段、类型、必填性、`@Pattern` 取值域
+  - 成功响应结构与字段
+  - 候选人查询（`/staff/candidates`、`/staff/candidates/page`）与配置列表查询（`GET /staff`）
+  - 报账人等级设置口 `PUT /v3/admin/group-batch/{productBatchId}/staff/{staffId}/reporter-rank`
+  - 子订单自己单独派的人员（`order_staff_assignment` 中 `source` 非 `GROUP_BATCH` 的行）
+  - `582114` / `582115` / `582116` / `100503` 四个既有码的触发条件与文案
+  - `assertScopeCoversWholeSlots`（582116）与 `scopeRoles` 的任何判定逻辑
+  - `DRIVER` / `OTHER` 的放行口径
+  - 数据库表结构与 Flyway（本单无表变更、无迁移脚本）
+  - 小程序端（团期人员配置无小程序写口）
+
+---
+
+## 八、测试环境已验证
+
+2026-09-23，`api.test.1814.love:9443`（网关），分支 `dev-v3`，order-v3 活体 `f6d21648b`（双实例 8086 / 8186，滚动部署后均 UP）。
+
+**取证批次**: `productBatchId=2102640646949105666`（#8123 / #8148 同一条取证批次），人员 `staffId=1002`（资源域真实 `staffType=GUIDE`）。
+
+| 项 | 请求 | 结果 |
+|---|---|---|
+| 探测前快照 | `GET /v3/admin/group-batch/2102640646949105666/staff` | 200，1 行（`staffId=1002, staffRole=GUIDE`） |
+| **本单核心（修复后）** | `PUT` 同端点，`{"staffList":[{"staffId":1002,"staffRole":"GUIDE_ASSISTANT"}]}` | **HTTP 200，`code=582117`**，message「角色 GUIDE_ASSISTANT 未归属任何人员配置位，无法校验人员类型；请检查配置位字典是否被误删」 |
+| **零写入** | 上一步之后 `GET` 同端点读回 | 与探测前快照**逐字段一致**（拒绝路径未注册 afterCommit 扇出回调，未进事务段） |
+| 阴性对照（`DRIVER`） | `PUT` `{"scopeRoles":["DRIVER"],"staffList":[{"staffId":1002,"staffRole":"DRIVER"}]}` | HTTP 200，`code=200` 成功 |
+| 阴性对照（`OTHER`） | `PUT` `{"scopeRoles":["OTHER"],"staffList":[{"staffId":1002,"staffRole":"OTHER"}]}` | HTTP 200，`code=200` 成功 |
+| 现场还原 | `PUT` `{"scopeRoles":["DRIVER","OTHER"],"staffList":[]}` | 200；读回与探测前快照**逐字段一致** |
+
+**测试环境上无法构造、因此未取活体样本的两项**（原因是环境性的、与实现无关）：
+
+- **AC-3「字典读挂回落内置默认值」**：需要让测试服的 `DictFeignClient` 整体失败，属环境级故障注入，会波及同环境其他使用者。该行为由真库用例 `GroupBatchStaffSaveConfigSlotCompletenessMysqlTest#saveConfig_dictFeignFails_fallbackKeepsSlotRolesAccepted` 与单元用例 `GroupBatchStaffRoleSlotGuardTest#dictUnavailable_fallbackKeepsBuiltInRolesAccepted` 覆盖（真实解析器 + 打桩 Feign，回落链路真跑）。
+- **AC-4 的测试服活体样本**（把内置角色从**仍非空**的配置位字典里删掉）：字典是全站共享数据，删行的副作用会落到所有人的角色下拉框上，未构造。该行为由真库用例 `#saveConfig_dictDropsLeaderFromGuideSlot_mismatchedStaffTypeRejectedNotSilentlySkipped` 覆盖。
+
+**证据文件**（脱敏、非空，已登记进 task capsule 的 evidence manifest）：`D:/work2/.tmp/issue8194/evidence/`（`gateway-verification.json` / `gateway-8194.log` / `gw-1-before.json` … `gw-5-after-cleanup.json` / `gw-summary.json`）。
+
+---
+
+## 十、相关文档
+
+- Issue #8194（本单）、#8148（582117 的引入与残留缺口）、#8122（582116 整位覆盖守卫）、#7079（配置位字典化）
+- PR #8259（squash 提交 `f6d21648b`）
+- 同端点上一版条目：`changelogs-v2/2026-09/23_8123_团期staff保存新增并发抢锁与配置位字典守卫错误码-修改接口-管理后台.md`
+- 错误码定义：`hl-order-service-v3/src/main/java/com/hulalv/order/assignment/errorcode/AssignmentErrorCode.java`（582117）
+- 判据与豁免闭集：`hl-order-service-v3/src/main/java/com/hulalv/order/assignment/service/GroupBatchStaffSlotResolver.java`（`STRUCTURALLY_SLOT_EXEMPT_ROLES` / `requiresSlotMembership`）
+
+---
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8194](https://git.1814.love/wx/HL/issues/8194)
+- **PR**: [#8259](https://git.1814.love/wx/HL/pulls/8259)
+- **Merge commit**: `f6d21648bada5d0d465cd454390ba6bad923869a`
+
+### 联系人
+
+- **后端负责人**: @wx
+- **前端**: mmg（582117 提示语可引导至配置位字典页面，非必须）
@@ -0,0 +1,385 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8202"
+title: "子订单行程用车车型大类接入车队字典校验（新增 582032/582033）"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "c314c8c67ddc61b8a1e4f4373d79e5a731b13272"
+target_release: ""
+verified_at: "2026-09-23"
+status_note: "PR #8224 已合并 dev-v3（b439565be）并滚动部署 TEST 双实例，Nacos 注册均 healthy:true。用车需求提交/调整两条写路径共用的车型大类校验链新增车队活字典比对，新增 582032/582033 两码；存量码 582022（填法不合法）不变。真实网关实测：两端点各以 vehicleType=\"__NOT_A_REAL_CATEGORY__\" 提交均返回 582022（填法层拦截优先于字典层）。前端 v2.1 已提前于 7df292624（09-23 09:27）改为车型字典下拉，新提交不会撞新码；仅存量已落库的非字典值在编辑态回显仍需前端显式提示。 | 2026-09-23 mmg 收尾交付:存量回显占位提示+fail-closed 拦截+JSDoc 订正,随 #8221 同 commit"
+updated_at: "2026-09-23"
+base: "dev-v3"
+---
+
+# 用车需求模块: 子订单行程用车车型大类接入车队字典校验
+
+> **存放目录**: 二期(v3) → `changelogs-v2/2026-09/`
+>
+> **服务**: hl-order-service-v3
+> **PR**: #8224
+> **Issue**: #8202
+> **日期**: 2026-09-23
+> **影响范围**: 管理后台子订单用车需求提交/修改、订单调整统一提交中的用车/接送机车型校验
+
+---
+
+## ⚠️ 关键变化（非必须,本版与上版行为不同 / 纠错 / 撤销时必写）
+
+- 本次变化：`vehicleType` 归一成功（如 `大巴`→`bus`）后，新增一次**车队活字典**比对；该大类若已整类下线（车队活字典无一行在架代表），提交被拒。
+- 前端以前以为的：只要 `vehicleType` 能归一为 `suv/mpv/bus/sedan` 之一（或直接传规范 key），提交就会成功。
+- 实际新行为：归一成功只是必要条件，还须该大类**当前在车队活字典内**；否则报新码 `582032`。**存量码 `582022`（这串字符连大类都归一不出来）保持不变、且仍是校验链第一关**——按当前测试库数据，前端实际会撞上的是 `582022`（自由文本/拼写问题），`582032` 只在大类被整类下线时触发（详见下方六.5/六.6）。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 提交/修改/调整用车需求 | PUT | `/v3/admin/order/{id}/vehicle-requirement` | 校验链新增字典比对 | `fleet[].vehicleType` 归一后追加车队活字典校验 |
+| 2 | 调整订单统一提交 | POST | `/v3/admin/order/{id}/adjustment/submit` | 校验链新增字典比对 | `updates.vehicleRequirement.fleet[]`/`updates.transferRequirement.fleet[]` 复用同一条校验链 |
+
+---
+
+## 三、接口详情
+
+### 1. 提交/修改/调整用车需求 `PUT /v3/admin/order/{id}/vehicle-requirement`
+
+**VO**: `VehicleRequirementReqVO → VehicleRequirementRespVO`
+
+#### 使用场景
+
+管理端子订单详情页提交/编辑用车需求（TRAVEL 行程用车 / TRANSFER 接送机）时调用；三分支由后端自动判断（无 active 需求=INIT_SUBMIT，PENDING=PENDING_EDIT，DONE=DONE_ADJUST），前端不用区分分支、始终整份提交。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| Authorization | Header | String | ✅ | - | 管理端登录令牌 |
+| id | Path | Long | ✅ | 订单 ID | 目标订单 |
+| kind | Body | String | ❌ | 正则 `TRAVEL\|TRANSFER` | 需求类别，缺省按订单类型推断 |
+| fleet | Body | Array\<FleetItem\> | ✅ | 非空 | 车型组合列表 |
+| fleet[].vehicleType | Body | String | ✅ | 须能归一为 `suv/mpv/bus/sedan`（582022），归一后须在车队活字典内（**582032，本次新增**） | 车型大类，示例 `mpv`，可传中文别名（如"大巴"） |
+| fleet[].seats | Body | Integer | ✅ | ≥0；须在该大类真实车型的座位选项内（582024） | 单车座位数 |
+| fleet[].count | Body | Integer | ✅ | >0 | 该车型数量 |
+| specialTags | Body | Array\<String\> | ❌ | 须在 `vehicle_special_demand` 字典内 | 通用特殊诉求 |
+| pickupRequired / dropoffRequired | Body | Boolean | ❌ | - | 接送机方向标记（兼容字段） |
+| remark | Body | String | ❌ | ≤500 字 | 备注 |
+
+#### 出参 `Result<VehicleRequirementRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | Long | 需求记录 ID |
+| kind | String | TRAVEL / TRANSFER |
+| version | Integer | 版本号 |
+| status | String | 需求状态 |
+| branchTaken | String | 本次实际走的分支：INIT_SUBMIT / PENDING_EDIT / DONE_ADJUST |
+| passengerCount | Integer | 出行人数 |
+| vehicleCount | Integer | 车辆总数 |
+| totalSeatCount | Integer | 总座位数 |
+| driverSeatCount | Integer | 司机座位数（= vehicleCount） |
+| passengerSeatCapacity | Integer | 载客座位容量 |
+| remainingPassengerSeats | Integer | 剩余可载客座位 |
+| previousVersion | Integer | DONE_ADJUST 分支下的上一版本号 |
+| assignmentDeletedCount | Integer | DONE_ADJUST 分支下被清理的派单数 |
+
+#### 请求示例
+
+```json
+{
+  "kind": "TRAVEL",
+  "fleet": [
+    { "vehicleType": "大巴", "seats": 7, "count": 1 }
+  ],
+  "remark": "接机后直达酒店"
+}
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "id": 2098765432109876543,
+    "kind": "TRAVEL",
+    "version": 2,
+    "status": "PENDING",
+    "branchTaken": "PENDING_EDIT",
+    "vehicleCount": 1,
+    "totalSeatCount": 7
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+写接口无空数据场景；提交成功即返回最新需求快照，无降级分支。
+
+```json
+{ "code": 200, "data": { "branchTaken": "INIT_SUBMIT" }, "success": true }
+```
+
+#### 错误响应
+
+`fleet[].vehicleType` 无法归一为 `suv/mpv/bus/sedan` 之一（含全部自由文本，如「别克GL8」）——**当前测试库数据下前端会实际撞上的错误**（存量码 582022，非本次新增，且排在校验链第一关）：
+
+```json
+{ "code": 582022, "message": "车型必须是车型大类（SUV/MPV/大巴/轿车）", "success": false, "data": null }
+```
+
+本次新增两码，仅在 `vehicleType` 归一**成功之后**才有机会触发：
+
+```json
+{ "code": 582032, "message": "车型 bus 不在车型字典内（不存在或已下线），请从下拉项中选择", "success": false, "data": null }
+```
+
+582032 仅当归一得到的规范大类在车队活字典（`fleet_vehicle_type`）中已整类下线（该大类下所有型号均软删）时触发；测试库当前四个大类各有 1 行在架代表，本码在现有测试数据下不可达。
+
+```json
+{ "code": 582033, "message": "车型字典不可用，请稍后重试", "success": false, "data": null }
+```
+
+582033 仅当车队字典服务不可用（Feign 兜底返回空 Map）时触发，与本次具体填了什么车型无关，空字典按 fail-closed 处理。
+
+#### 业务边界
+
+- 鉴权：未登录 → 业务码 `401`。
+- 校验顺序：`fleet` 非空（582021）→ 逐项归一 + 座位数/数量非负校验（582022/582023）→ **车队活字典比对（582032/582033，本次新增）** → 座位选项校验（582024）→ 特殊诉求校验（582025/582026）。任一步失败即拒，零写入。
+- 存量已落库、含已下线大类的需求原样再次提交同一接口同样会被 582032 拒绝——这是有意设计（放行已下线大类等同于让下线动作失效），与团期批量车务 809119 同口径。
+- 车型下拉数据源固定为 `GET /admin/fleet/vehicle-types/list`（车队服务只读端点，网关已放行订单域只读调用，无需新增路由配置）。
+
+---
+
+### 2. 调整订单统一提交 `POST /v3/admin/order/{id}/adjustment/submit`
+
+**VO**: `AdjustmentSubmitReqVO → AdjustmentSubmitRespVO`
+
+#### 使用场景
+
+管理端订单调整弹窗统一提交入口；前端在内存里收集出行人/改期/行程/房需求/用车需求/接送机需求等多个子领域的改动后一次性提交。本次改动只影响 `updates.vehicleRequirement.fleet[]`（行程用车）与 `updates.transferRequirement.fleet[]`（接送机）两个子领域各自的车型大类校验，其余子领域字段与行为不受影响。
+
+#### 入参
+
+> 仅列与本次改动相关的字段；其余子领域（`people`/`schedule`/`itinerary`/`hotelRequirement` 等）字段结构未变，不在此重复列出。
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| Authorization | Header | String | ✅ | - | 管理端登录令牌 |
+| id | Path | Long | ✅ | 订单 ID | 目标订单 |
+| updates | Body | Object | ✅ | 至少一个子领域非 null | 各子领域修改内容容器 |
+| updates.vehicleRequirement.fleet | Body | Array\<FleetItem\> | ❌（该子领域非 null 时必传） | 非空则整组重新走校验链；结构与端点 1 的 `fleet` 完全相同 | 行程用车车型组合 |
+| updates.vehicleRequirement.fleet[].vehicleType | Body | String | 同端点 1 | 须归一成功（582022）且归一后在车队活字典内（**582032，本次新增**） | 车型大类 |
+| updates.transferRequirement.fleet | Body | Array\<FleetItem\> | ❌（该子领域非 null 时必传） | 与 `vehicleRequirement.fleet` 走同一条校验方法，服务日由大交通信息派生 | 接送机车型组合 |
+| updates.transferRequirement.fleet[].vehicleType | Body | String | 同端点 1 | 同上 | 车型大类 |
+
+#### 出参 `Result<AdjustmentSubmitRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| success | Boolean | 提交是否成功；失败由全局异常处理器返回 `Result{code,message,data:null}`，不会出现该字段为 `false` 的情形 |
+
+#### 请求示例
+
+```json
+{
+  "updates": {
+    "vehicleRequirement": {
+      "fleet": [
+        { "vehicleType": "mpv", "seats": 7, "count": 1 }
+      ],
+      "remark": "新增 2 名成员，需更大车型"
+    }
+  }
+}
+```
+
+#### 响应示例
+
+```json
+{ "code": 200, "message": "成功", "data": { "success": true }, "success": true }
+```
+
+#### 空数据 / 降级响应
+
+写接口无空数据场景；`updates` 内某子领域传 `null` 表示该子领域本次不改，不参与本次校验也不产生该子领域的变更记录。
+
+```json
+{ "code": 200, "data": { "success": true }, "success": true }
+```
+
+#### 错误响应
+
+与端点 1 完全同码同序（`AdjustmentService.validateVehicleSeatOptionsBeforeWrite` 从 `updates.vehicleRequirement`/`updates.transferRequirement` 的 `fleet` 字段构造 `VehicleRequirementReqVO` 后，调用与端点 1 相同的 `validateVehicleRequirementSeatOptions`）。当前测试库数据下前端会实际撞上的同样是 582022：
+
+```json
+{ "code": 582022, "message": "车型必须是车型大类（SUV/MPV/大巴/轿车）", "success": false, "data": null }
+```
+
+```json
+{ "code": 582032, "message": "车型 bus 不在车型字典内（不存在或已下线），请从下拉项中选择", "success": false, "data": null }
+```
+
+```json
+{ "code": 582033, "message": "车型字典不可用，请稍后重试", "success": false, "data": null }
+```
+
+#### 业务边界
+
+- 鉴权：未登录 → 业务码 `401`。
+- `submit` 整体在一个 `@Transactional(rollbackFor = Exception.class)` 事务内；`updates.vehicleRequirement` 与 `updates.transferRequirement` 两个子领域各自独立校验一次，任一子领域校验失败即整单回滚，**已通过校验的其他子领域改动也不会落库**。
+- `updates.vehicleRequirement`/`updates.transferRequirement` 为 `null` 时该子领域完全跳过（既不校验也不改动），不受本次变更影响。
+- 存量已落库、含已下线大类的需求原样再次经本接口提交同样会被 582032 拒绝，同端点 1。
+
+---
+
+## 四、契约约束与正确调用方式（接口类必写）
+
+> 本节只写**后端接受/拒绝 payload 的规则**，不写 UI 渲染建议。
+
+### ✅ 正确 / ❌ 错误 payload 对照
+
+| 场景 | payload | 结果 |
+|------|---------|------|
+| ✅ 从 `GET /admin/fleet/vehicle-types/list` 下拉选值提交 | `vehicleType` 取字典返回的规范 key（`suv/mpv/bus/sedan`） | 通过归一 + 字典校验 |
+| ✅ 提交中文别名 | `vehicleType: "大巴"` | 归一为 `bus` 后再查字典，与直接传 `bus` 等价 |
+| ❌ 自由文本/型号名 | `vehicleType: "别克GL8"` | 582022，归一失败，校验链第一关即拒 |
+| ❌ 大类已被车队整类下线 | `vehicleType: "bus"` 但活字典无 `bus` 在架代表 | 582032，归一成功但字典比对不通过 |
+| ❌ 车队字典服务不可用 | 任意合法 `vehicleType` | 582033，fail-closed，不做逐项放行 |
+
+- `vehicleType` 一律以**归一后的规范 key**（非原始填法）落库；重新查看已提交需求时看到的也是规范 key，不是用户当时填的中文别名。
+- 端点 1（`vehicle-requirement`）与端点 2（`adjustment/submit`）中的 `fleet[]` 结构与校验规则完全一致，前端不需要为两个入口分别处理错误码。
+
+### 前端已就绪的状态
+
+mmg `v2.1` 分支 `7df292624`（2026-09-23 09:27）已将车型录入从自由文本改为 `GET /admin/fleet/vehicle-types/list` 字典下拉，新提交的 `vehicleType` 均取自字典返回值，不会触发本次新增的 582032/582033。
+
+尚待前端覆盖的场景：**存量已落库需求的编辑态回显**——若某行 `vehicleType` 不在当前字典返回值内（历史遗留或大类刚被下线），下拉组件默认会渲染成空选项且用户无法感知原因；此时应显式提示"当前值不在字典内，请重新选择"，而非静默清空。
+
+**受影响的前端组件（实测点名，非推断）**：`src/views/order-v2/detail/modals/FunItemAdjustModal.vue`——hl-ui `v2.1` 上唯一调用 `putVehicleRequirement` 的 `.vue`（`:1177` import，`:2968` TRAVEL / `:2970` TRANSFER 两个调用点）；api 封装在 `src/api/orderV2.js:1345` `putVehicleRequirement`。该组件已引入车型字典 api（`getVehicleTypesList`），本次要补的是「回显值不在字典返回集内」这一态的显式提示，不是接入下拉本身。
+
+⚠️ 顺带一条可查证的事实：`src/api/orderV2.js` 中 `putVehicleRequirement` 的 JSDoc 错误码一行写的是 `582024 / 582091`，不含本次新增的 `582032 / 582033`。注释不影响运行，但下一个照注释排错的人会找不到新码。
+
+---
+
+## 五、数据库行为（涉及写操作时必写）
+
+- 无 Flyway migration、无 DDL、无表结构变更。
+- 本次校验是**写前置校验**，不涉及任何新增列或索引；`vehicle_requirement` 表落库字段与校验前完全一致（仅 `vehicle_type` 列存的值继续是归一后的规范 key）。
+- 校验失败（582022/582032/582033/582024 等）的请求**零写入**——包括 `vehicle_requirement` 主表、审计记录、派单联动，一律不产生任何行。
+- 车队活字典本身（`fleet_vehicle_type` 表）不因本次改动新增/修改任何行，字典维护仍走车队服务既有入口。
+
+---
+
+## 六、边界行为
+
+- 未登录 → 业务码 `401`（网关包装 HTTP 200）。
+- `fleet` 为空数组或缺失 → 582021。
+- `vehicleType` 无法归一 → 582022（存量码，未变）。
+- `vehicleType` 归一成功但大类已整类下线 → **582032（本次新增）**。
+- 车队字典服务不可用（Feign 兜底返回空 Map）→ **582033（本次新增）**，对所有请求 fail-closed，不逐项放行。
+- `seats`/`count` 非法 → 582023；座位数不在该大类真实型号座位选项内 → 582024（582024 判定排在字典校验之后，因此大类已下线时不会先看到一个指错方向的座位错误）。
+- 存量已落库、含已下线大类的需求原样重新提交同一接口 → 同样被 582032 拒绝，零写入，不因"内容未变"豁免。
+- `adjustment/submit` 路径下，`validateVehicleTypesAgainstFleetDict` 内的 Feign 调用运行在 `AdjustmentService.submit` 的物理事务内（`PROPAGATION_REQUIRED` 挂入）；这是该路径已有的事务边界，本次改动未改变这一行为，也不在本单修复范围。
+
+---
+
+## 六.5、枚举 / 数据字典
+
+### fleet[].vehicleType（车型大类规范 key）
+
+**所属字段**: `VehicleRequirementReqVO.fleet[].vehicleType` / `AdjustmentSubmitReqVO.updates.vehicleRequirement.fleet[].vehicleType` / `...transferRequirement.fleet[].vehicleType` | **类型**: String
+
+| 值 | 说明 |
+|----|------|
+| `suv` | SUV |
+| `mpv` | MPV / 商务车 |
+| `bus` | 大巴 |
+| `sedan` | 轿车 |
+
+- 归一表（含中文别名，如"大巴"→`bus`）由 `VehicleCategoryNormalizer` 维护，四值闭集，本次未新增第五类。
+- 实际**是否可选**取决于车队活字典当前有哪些大类在架，前端应以 `GET /admin/fleet/vehicle-types/list` 的实时返回为准，不要硬编码这四个 key 一定全部可用。
+
+---
+
+## 六.6、修改前后对比（修改/删除类接口必写，新增跳过）
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 |
+|------|------|------|
+| `fleet[].vehicleType` | 只要能归一为 `suv/mpv/bus/sedan` 之一即接受，不管该大类当前是否在车队还在营 | 归一成功后额外要求该大类在车队活字典内有 ≥1 行在架代表，否则拒 |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| 提交一个已被车队整类下线的大类（如运营已下线 `bus`） | 校验通过，正常落库 | 582032 拒绝，零写入 |
+| 车队字典服务不可用 | 不影响本校验链（该服务原本不参与车型大类校验） | 582033 拒绝，fail-closed |
+| 存量含已下线大类的需求原样重新提交 | 通过 | 582032 拒绝（与团期批量车务 809119 同口径） |
+
+---
+
+## 六.7、影响评估（修改/删除类必写）
+
+- **是否破坏向后兼容**: 部分破坏，且是有意为之。请求/响应结构不变；仅"归一成功但大类已被下线"这一种此前被接受的取值，改为拒绝。影响面严格限定在"大类已整类下线"这一种运营主动下线的场景，不影响任何仍在营的大类。
+- **前端是否必须同步上线**: 否，mmg 已提前于本次后端上线（`7df292624` 早于 `b439565be`）改为字典下拉，新提交路径已规避新码。
+- **前端 workaround 清理点**: 存量已落库需求在编辑态若命中已下线大类，需前端显式提示"当前值不在字典内，请重新选择"（见"四、契约约束"节），避免下拉渲染成空白且用户无法定位原因。落点组件：`src/views/order-v2/detail/modals/FunItemAdjustModal.vue`。
+
+---
+
+## 七、不影响范围（显式声明, 帮前端/QA 缩小排查面）
+
+- **仅影响**: 两个端点中 `fleet[].vehicleType` 的字典比对这一步；其余校验（座位数、数量、特殊诉求、座位选项）逻辑不变。
+- **零影响**:
+  - `VehicleCategoryNormalizer` 的四值归一表与别名规则本身（未新增/删减大类）。
+  - `adjustment/submit` 中 `people`/`schedule`/`itinerary`/`hotelRequirement` 等与用车无关的子领域。
+  - 团期批量车务（`GroupVehicleRequirementService`）校验链，809119/809120 已是同口径独立实现，本单未改动团级代码。
+  - 派单、车队分配、司机端等下游链路的既有行为。
+  - `GET /admin/fleet/vehicle-types/list` 端点本身（既有只读端点，本单未修改其实现或路由）。
+
+---
+
+## 八、测试环境已验证
+
+单元测试（`RequirementServiceVehicleTypeDictValidateTest`）：
+- `validateVehicleTypes_retiredCategoryRejectedAndLiveCategoryAccepted`：同一桩字典（刻意不含 `bus`）下，`大巴`（归一为 `bus`）被拒且断言错误码为 582032、非 582022；同一字典下 `suv` 正常放行。
+- `validateVehicleTypes_emptyDict_throws582033NotFail582032`：空字典（模拟车队服务不可用）下，`suv` 被拒且断言错误码为 582033、非 582032，报文不含用户填的车型值。
+
+真实网关（TEST 环境）实证：
+
+```
+PUT  /v3/admin/order/{id}/vehicle-requirement   vehicleType=__NOT_A_REAL_CATEGORY__  → 582022 ✓
+POST /v3/admin/order/{id}/adjustment/submit     vehicleType=__NOT_A_REAL_CATEGORY__  → 582022 ✓
+```
+
+两端点对同一非法值返回一致的错误码（582022），验证校验链在两个入口上等价生效、归一失败判定优先于字典比对。
+
+部署: PR #8224 已合并 `dev-v3`（合并提交 `b439565be`），TEST 环境双实例滚动部署完成，Nacos 注册均 `healthy:true`。
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#8202](https://git.1814.love:8443/wx/HL/issues/8202)
+- 关联 PR: [wx/HL#8224](https://git.1814.love:8443/wx/HL/pulls/8224)
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8202](https://git.1814.love:8443/wx/HL/issues/8202)
+- **PR**: [#8224](https://git.1814.love:8443/wx/HL/pulls/8224)
+- **Merge commit**: [b439565be](https://git.1814.love:8443/wx/HL/commit/b439565be)
+
+### 联系人
+
+- **后端负责人**: @wx
@@ -0,0 +1,207 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8215"
+title: "团期详情（A2）新增出参 subOrderCount——活跃子订单户数，与 A3 total / 看板 orderCount 同源"
+consumer: "admin"
+author: "jw(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "not_required"
+frontend_status: "not_required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "团期详情页右上角显示「子订单 0 户」，同页「已建子订单 12 户」「整团名单速览(12 户)」却是 12。2026-09-23 对 TEST 团期 2101506167098511362 逐接口实测，后端四个接口无一返回 0：A2 详情 formingRooms/enrolledRooms/maxRooms 全 12、A3 子订单列表 total=12 且 records 有数据、看板 orderCount=12、财务 items 12 条。右上角三个金额（应收 156760 / 已收 47940 / 待收 108820）与 A2 的 receivableAmount/receivedAmount/unpaidAmount 逐字一致，说明该 UI 绑的就是详情响应对象——而详情原有的 50 个字段里没有任何子订单户数字段，前端取到 undefined 渲染成 0。subOrderCount 这个名字在 order-v3 里原本只存在于看板统计条 VO（GroupBatchSummaryVO，口径是命中筛选的全部团期活跃子订单合计，属列表页统计条）。本次后端兜底：A2 详情新增出参 subOrderCount，取数复用既有契约方法 OrderService#countActiveByProductBatchIds——A3 的 total 与看板 orderCount 走的都是它，口径同为 order_status != CANCELLED 加 @TableLogic 软删过滤，刻意不另写 count，避免「同屏两个数字不一致」换个形式复发。字段恒非 null，无活跃子订单返 0 而非 null。已合并 dev-v3（PR #8216，merge commit fc0508981）并部署测试服，09:50 三接口同轮实测同为 12。路径、入参、权限码、其余出参字段零变化，网关无改动。前端侧需确认该页取的就是 subOrderCount 这个字段名，故 frontend_status 记 pending。 mmg 2026-09-23 复核: 页面上那个 0 的取数点是 BatchHero orderCount 计算属性 `d.orderCount ?? d.subOrderCount ?? 0`(src/views/order-v2/batch/detail/components/BatchHero.vue),第二棒早已读 subOrderCount——A2 部署后该处即渲染真实户数,前端零行为改动,后端选的名字正好接上。已补注释+spec 两例锁回落链(hl-ui@61a549bd chore),判 not_required。"
+updated_at: "2026-09-23"
+base: "dev-v3"
+---
+
+# 团期详情（A2）新增出参 subOrderCount（管理后台）
+
+> **服务**: hl-order-service-v3（端口 8086/8186）
+
+## 一、接口背景
+
+团期详情页右上角同时渲染「成团状态 + 子订单户数 + 整团应收/已收/待收」。其中三个金额来自本接口，
+而「子订单户数」在本次之前**本接口并不返回**——前端取到 `undefined`，渲染成 `0`，
+与同页「已建子订单 12 户」「整团名单速览(12 户)」同屏打架。
+
+本次在本接口补上该字段，取数与 A3 子订单列表、团期看板行**共用同一个契约方法**，三处必然同值。
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|---|---|---|---|---|
+| 1 | A2 团期详情 | GET | `/v3/admin/order/group-batch/{groupBatchId}` | 修改接口 | 新增出参 `subOrderCount`，其余字段与行为零变化 |
+
+## 三、接口详情
+
+### 1. A2 团期详情 `GET /v3/admin/order/group-batch/{groupBatchId}`
+
+**VO**: `GroupBatchDetailRespVO`
+
+#### 使用场景
+
+团期详情页进入时拉取整团概览：状态机阶段、成团闸/满员闸计数、四项 ready 标志、整团金额三项，
+以及本次新增的活跃子订单户数。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| groupBatchId | path | Long | 是 | 正整数，团期聚合主键 | 团期 ID，非法或不存在返 GROUP_BATCH_NOT_FOUND |
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| subOrderCount | Integer | **本次新增**。挂在本团期下的活跃子订单张数（户数）。口径：`order_main.product_batch_id` = 本团期 productBatchId 且 `order_status != CANCELLED`，软删由 `@TableLogic` 过滤。与 A3 子订单列表的 `total`、看板行的 `orderCount` 同一取数口径、同一契约方法，三处同值。恒非 null，无活跃子订单为 0 |
+| formingRooms | Integer | 成团判定用户数 = 线上已付款活跃订单数 + 产品域线下占位（#7287）。**与 subOrderCount 不是一回事**，有线下占位时必然大于后者 |
+| enrolledRooms | Integer | 已用房间数（既有字段，本次未改） |
+| receivableAmount | BigDecimal | 整团应收（既有字段，本次未改） |
+| receivedAmount | BigDecimal | 整团已收（既有字段，本次未改） |
+| unpaidAmount | BigDecimal | 整团待收 = max(0, 应收 − 已收)（既有字段，本次未改） |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch/2101506167098511362 HTTP/1.1
+Host: api.test.1814.love:9443
+Authorization: Bearer <admin token>
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "groupBatchId": "2101506167098511362",
+    "batchName": "jw测试1期",
+    "opsStage": "FORMED",
+    "opsStageName": "已成团",
+    "subOrderCount": 12,
+    "formingRooms": 12,
+    "enrolledRooms": 12,
+    "maxRooms": 12,
+    "receivableAmount": "156760.00",
+    "receivedAmount": "47940.00",
+    "unpaidAmount": "108820.00"
+  }
+}
+```
+
+#### 空数据 / 降级响应
+
+团期存在但名下没有活跃子订单（全部 CANCELLED，或建团后尚未下单）时，`subOrderCount` 返 `0`，
+**不返 null、不缺字段**——null 在前端同样会渲染成空或 0，等于把本次要修的缺陷藏回去。
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "groupBatchId": "2101506167098511363",
+    "opsStage": "RECRUIT",
+    "subOrderCount": 0,
+    "receivableAmount": "0.00",
+    "receivedAmount": "0.00",
+    "unpaidAmount": "0.00"
+  }
+}
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 589501,
+  "message": "团期不存在",
+  "data": null
+}
+```
+
+| 错误码 | 触发条件 |
+|---|---|
+| 589501 | groupBatchId 不存在或已软删 |
+| 403 | 缺 `group-batch:view` 权限码，或定制师访问非自己归属的团期 |
+
+#### 业务边界
+
+- `subOrderCount` 只回答「这个团下面挂了几张活跃子订单」，**不含任何产品域线下占位**。
+- 已取消（CANCELLED）子订单不计入；软删由 `@TableLogic` 过滤，与 A3 缺省（`includeCancelled=false`）一致。
+- 与 A3 的 `total` 必然同值：两者调用同一个 `OrderService#countActiveByProductBatchIds` / 同一过滤条件。
+- 退单户（withdraw）在未置 CANCELLED 前仍计入，与 A3 行为一致。
+
+## 四、契约约束与正确调用方式
+
+- 前端渲染「子订单 N 户」请取 `data.subOrderCount`，**不要取 `formingRooms`**（那是成团判定用数，含线下占位）。
+- 需要逐户明细时仍走 A3 `GET /v3/admin/order/group-batch/{groupBatchId}/orders`，其分页包装为
+  `{ records, total, page, pageSize }`——列表字段名是 `records`，不是 `list`。
+- 本字段是纯增出参，老调用方忽略它即可，无需改动。
+
+## 五、数据库行为
+
+零数据库变更。本次不新增表/列/索引，不写任何数据；`subOrderCount` 的数据来源是既有列
+`order_main.product_batch_id` + `order_main.order_status` 的只读聚合，走既有契约方法，未新增 mapper 查询。
+
+## 六、边界行为
+
+- 团期不存在 → 589501，不返回半个对象。
+- 团期存在、无活跃子订单 → `subOrderCount: 0`（见「空数据 / 降级响应」）。
+- 团期下既有活跃单又有已取消单 → 只数活跃的，与 A3 缺省口径一致。
+
+## 六.6、修改前后对比
+
+| 项 | 修改前 | 修改后 |
+|---|---|---|
+| 出参字段数 | 50 | 51 |
+| `subOrderCount` | **不返回**（前端取到 undefined，页面渲染成 0） | 返回活跃子订单户数，恒非 null |
+| 其余出参字段 | — | 逐字未变 |
+| 路径 / 入参 / 权限码 | — | 逐字未变 |
+| 取数来源 | — | 复用 `OrderService#countActiveByProductBatchIds`（A3 与看板同款），未新增查询 |
+
+## 六.7、影响评估
+
+- **兼容性**：纯增出参，老调用方忽略即可，无破坏性。
+- **性能**：详情装配内多一次按单个 productBatchId 的活跃单计数，走既有契约方法（A1 列表/看板/合并行三处已在用），
+  单元素入参，无 N+1；落在既有 `@Transactional(readOnly = true)` 的库内装配段，不涉及 Feign。
+- **回滚**：撤销 PR #8216 即可，无数据与配置残留。
+- **未覆盖**：本次只证明后端返对了值。页面上那个 `0` 是否消失，取决于前端该处取的是不是
+  `subOrderCount` 这个字段名——属前端侧确认项，`frontend_status` 记 `pending`。
+
+## 七、不影响范围
+
+- A3 团期下子订单列表、团期看板、团期财务总览：口径与字段零改动。
+- `formingRooms` / `enrolledRooms` / 金额三项：取数来源与数值零改动。
+- 网关：路径未变、无新增路由与权限码，`gateway_status: not_required`。
+- 小程序端：本接口仅管理后台使用，未涉及。
+
+## 八、测试环境已验证
+
+2026-09-23 09:50 测试服（api.test.1814.love:9443），团期 `2101506167098511362`（jw测试产品·第1期，已成团），
+部署 `dev-v3 @ fc0508981`，三接口**同轮**实测：
+
+| 接口 | 字段 | 读数 |
+|---|---|---|
+| A2 团期详情 | `subOrderCount` | **12** |
+| A3 子订单列表 | `total` | **12** |
+| 团期看板 | `orderCount` | **12** |
+
+同轮 `formingRooms=12`、`enrolledRooms=12`，与 `subOrderCount` 在本团期恰好同值（该团无线下占位）。
+
+单元测试：`GroupBatchQueryServiceTest` 80 例 0 失败（新增 3 条，经 surefire XML 核实真执行，无 skipped），
+`GroupBatchQueryControllerTest` 9 例 0 失败，合计 89/0。
+
+## 十、相关文档
+
+- 工单 #8215、PR #8216（merge commit `fc0508981`）
+- `formingRooms` 口径出处：#7287
+- A3 分页包装形态（`records` 而非 `list`）出处：#7536
+
+## 关联 / 联系人
+
+- 后端：jw
+- 前端：待确认该页取值字段名（`frontend_status: pending`）
@@ -0,0 +1,483 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8218"
+title: "行程用车需求 PENDING_REVIEW 文案按 kind 分叉：TRAVEL「待提交车务」/ TRANSFER「待审核」"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "not_required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "【mmg 2026-09-24 判 not_required】grep 实证前端两出口均直显后端 *Name:RosterTable.vue:107(vehicleRequirementStatusName 三段回落)、VehicleHouseholdsSection.vue:112(statusName 直显,注释钉死「禁自建编码→中文映射」);文案分叉由后端下发自动生效,前端零映射零改动。"
+updated_at: "2026-09-23"
+base: "dev-v3"
+---
+
+# order-v3: 行程用车需求状态文案分叉
+
+> **存放目录**: `changelogs-v2/{YYYY-MM}/`
+>
+> **服务**: hl-order-service-v3 (端口 8007)
+> **PR**: #8218
+> **Issue**: #8218
+> **日期**: 2026-09-23
+> **影响范围**: 管理后台「团期查看需求」tab 下的子订单用车需求行状态文案
+
+---
+
+## ⚠️ 关键变化
+
+**同一个状态码 `PENDING_REVIEW` 在两个出口里出现两种中文名**：行程用车（TRAVEL）记为「待提交车务」（等团期管理员整团放行，没有逐户审核动作），接送机（TRANSFER）保持「待审核」（有逐户审核动作）。这是体验分化的一部分，同一行程的不同需求类别流转节奏不同。
+
+---
+
+## 一、背景
+
+团期用车需求分为两类：**行程用车（TRAVEL）** 由定制师逐户报，团期管理员整团一次审核并提交车务；**接送机（TRANSFER）** 由定制师逐户报，车务逐户审核。两条流程的「待审核」语义不同，混用会误导前端和用户。#8151 补齐了接送机字段后，#8218 据此修正了文案。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 团期下子订单列表 | GET | `/v3/admin/order/group-batch/{groupBatchId}/orders` | 响应字段值改变 | `vehicleRequirementStatusName` PENDING_REVIEW 场景分叉 |
+| 2 | 团期子订单用车需求记录 | GET | `/v3/admin/order/group-batch/{groupBatchId}/requirement/vehicle-households` | 响应字段值改变 | `RequirementItem.statusName` PENDING_REVIEW 场景分叉 |
+
+---
+
+## 三、接口详情
+
+### 1. 团期下子订单列表 `GET /v3/admin/order/group-batch/{groupBatchId}/orders`
+
+**VO**: `GroupBatchOrderItemRespVO → PageResult<GroupBatchOrderItemRespVO>`
+
+#### 使用场景
+
+管理后台「团期详情」页面的「客户清单」tab，展示该团期下的全部子订单及其状态。前端需据 `vehicleRequirementStatusName` 在列表中展示该户的车需求进度。
+
+#### 入参字段表
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long | ✅ | - | 团期 ID |
+| page | Query | Integer | ❌ | ≥1 时取值，<1 归一为 1；缺省 1 | 页码 |
+| pageSize | Query | Integer | ❌ | 1-200；缺省 20，>200 截断为 200 | 每页条数 |
+| includeTravelers | Query | Boolean | ❌ | 缺省 true | 是否附出行人明细（证件号/手机号一律不返回） |
+| includeNeeds | Query | Boolean | ❌ | 缺省 true | 是否附房数/房型/特殊需求 |
+| includeCancelled | Query | Boolean | ❌ | 缺省 false | 是否含已取消子订单 |
+
+#### 出参字段表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| orderId | Long | 子订单 ID |
+| orderNo | String | 订单编号 |
+| customerName | String | 客户姓名 |
+| vehicleRequirementStatus | String | 车需求状态英文码（PENDING / PROCESSING / DONE / PENDING_REVIEW / REJECTED_TO_CONSULTANT / REJECTED_TO_ADMIN；无需求行回落 PENDING） |
+| vehicleRequirementStatusName | String | 车需求状态中文名；本列恒为行程用车（TRAVEL），故 PENDING_REVIEW 下发「待提交车务」而非「待审核」；无需求行回落「待车队配」 |
+
+#### 请求示例
+
+```json
+GET /v3/admin/order/group-batch/2101506167098511362/orders?page=1&pageSize=20
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "records": [
+      {
+        "orderId": 2101506167043985410,
+        "orderNo": "HL20260516143052999",
+        "teamNo": "26-0001",
+        "customerName": "王先生家庭",
+        "participantCount": 4,
+        "orderStatus": "CUSTOMIZING",
+        "orderStatusName": "定制中",
+        "payStatus": "DEPOSIT_PAID",
+        "payStatusName": "已付定金",
+        "vehicleRequirementStatus": "PENDING_REVIEW",
+        "vehicleRequirementStatusName": "待提交车务",
+        "consultantName": "张三",
+        "totalPrice": "12000.00",
+        "tierCode": "2A1C",
+        "tierName": "2成人1儿童",
+        "travelerInfoComplete": true
+      }
+    ],
+    "pageNumber": 1,
+    "pageSize": 20,
+    "totalCount": 45
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "records": [],
+    "pageNumber": 1,
+    "pageSize": 20,
+    "totalCount": 0
+  },
+  "success": true
+}
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 404,
+  "message": "团期不存在",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- **本列恒为行程用车（TRAVEL）**：查询条件写死 `VehicleRequirementKind.TRAVEL`，所以子订单列表的 `vehicleRequirementStatusName` 永远不会出现「待审核」。这是 #8151 的既有设计，本次未改。
+- **纯接送机订单在此列的默认值**：定制师仅报了接送机需求而无行程用车需求的订单，在此出口读到的是后备 `vehicleRequirementStatus="PENDING"` / `vehicleRequirementStatusName="待车队配"`。若前端需区分这类订单的接送机状态，应改用出口二并传 `kind=TRANSFER`。
+- **无需求行回落**：未提交过任何行程用车需求的户，`vehicleRequirementStatus` 回落 `PENDING`，`vehicleRequirementStatusName` 回落「待车队配」。
+- **鉴权**：需 `AdminContextUtil` 权限检查（`GroupBatchPermissionGuard.PERMISSION_VIEW`）。
+
+---
+
+### 2. 团期子订单用车需求记录 `GET /v3/admin/order/group-batch/{groupBatchId}/requirement/vehicle-households`
+
+**VO**: `GroupVehicleHouseholdsRespVO`
+
+#### 使用场景
+
+管理后台「团期详情」页面的「查看需求」tab，展示该团期下逐户的用车需求明细。前端需据 `kind` 字段区分行程用车与接送机，并按其分别渲染对应的状态文案和审核流程。同一户可能同时有 TRAVEL 与 TRANSFER 两行，状态码与文案各自独立。
+
+#### 入参字段表
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long | ✅ | - | 团期 ID |
+| kind | Query | String | ❌ | TRAVEL / TRANSFER；不传则两类都返 | 需求类别过滤 |
+
+#### 出参字段表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| groupBatchId | Long | 团期 ID |
+| householdCount | Integer | 应报车的户数（按 orderId 去重，含一份需求都没提交的户） |
+| vehicleRowCount | Integer | 需求行数（一户可能 TRAVEL + TRANSFER 两行；未提交的户贡献 0 行，故本数可能小于 householdCount） |
+| households[].orderId | Long | 子订单 ID |
+| households[].customerName | String | 主联系人姓名 |
+| households[].status | String | 户级用车需求状态（null=该户一份需求都没提交；非 null 时取展示序首条的状态） |
+| households[].statusName | String | 户级用车需求状态中文名；PENDING_REVIEW 按首条需求行的 kind 分两套文案（TRAVEL=待提交车务 / TRANSFER=待审核） |
+| households[].requirements[].kind | String | 需求类别（TRAVEL / TRANSFER） |
+| households[].requirements[].kindName | String | 需求类别中文名 |
+| households[].requirements[].status | String | 需求状态编码（PENDING / PROCESSING / DONE / PENDING_REVIEW / REJECTED_TO_CONSULTANT / REJECTED_TO_ADMIN） |
+| households[].requirements[].statusName | String | 需求状态中文名；PENDING_REVIEW 按本行 kind 分两套文案（TRAVEL=待提交车务 / TRANSFER=待审核） |
+
+#### 请求示例
+
+```json
+GET /v3/admin/order/group-batch/2101506167098511362/requirement/vehicle-households?kind=TRAVEL
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "groupBatchId": 2101506167098511362,
+    "departDate": "2026-10-01",
+    "endDate": "2026-10-07",
+    "householdCount": 3,
+    "vehicleRowCount": 4,
+    "countedHouseholdCount": 3,
+    "households": [
+      {
+        "orderId": 2101506167043985410,
+        "orderNo": "HL20260516143052999",
+        "teamNo": "26-0001",
+        "customerName": "王先生家庭",
+        "participantCount": 4,
+        "consultantName": "张三",
+        "countedInSummary": true,
+        "status": "PENDING_REVIEW",
+        "statusName": "待提交车务",
+        "requirements": [
+          {
+            "requirementId": 2101506167043985411,
+            "kind": "TRAVEL",
+            "kindName": "行程用车",
+            "status": "PENDING_REVIEW",
+            "statusName": "待提交车务",
+            "fleet": [
+              {
+                "vehicleType": "suv",
+                "vehicleTypeName": "SUV",
+                "seats": 7,
+                "count": 1
+              }
+            ],
+            "specialTags": [],
+            "remark": "需要儿童座椅",
+            "serviceDates": [],
+            "headcount": 4,
+            "totalSeatCount": 7,
+            "remainingPassengerSeats": 3,
+            "pickupRequired": null,
+            "dropoffRequired": null,
+            "returnRemark": null,
+            "returnedAt": null
+          }
+        ]
+      },
+      {
+        "orderId": 2101506167043985420,
+        "orderNo": "HL20260516143052998",
+        "teamNo": "26-0002",
+        "customerName": "李女士一家",
+        "participantCount": 3,
+        "consultantName": "李四",
+        "countedInSummary": true,
+        "status": "PENDING",
+        "statusName": "待车队配",
+        "requirements": [
+          {
+            "requirementId": 2101506167043985421,
+            "kind": "TRAVEL",
+            "kindName": "行程用车",
+            "status": "PENDING",
+            "statusName": "待车队配",
+            "fleet": [],
+            "specialTags": [],
+            "remark": null,
+            "serviceDates": [],
+            "headcount": 0,
+            "totalSeatCount": 0,
+            "remainingPassengerSeats": 0,
+            "pickupRequired": null,
+            "dropoffRequired": null,
+            "returnRemark": null,
+            "returnedAt": null
+          }
+        ]
+      }
+    ]
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "groupBatchId": 2101506167098511362,
+    "householdCount": 0,
+    "vehicleRowCount": 0,
+    "countedHouseholdCount": 0,
+    "households": []
+  },
+  "success": true
+}
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 404,
+  "message": "团期不存在",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- **同一户可能混装两类需求**：同一屏上会并排出现「待提交车务」（TRAVEL 行）与「待审核」（TRANSFER 行）。这不是文案分叉的缺陷，两行的 `kind` 本来就不同、审核流程各自独立。前端需按 `kind` 字段分组渲染。
+- **户级状态（status/statusName）的定义**：户级状态取展示序首条（TRAVEL 优先）的状态。当同一户同时有 TRAVEL 与 TRANSFER 且两者状态码不同时（如 TRAVEL 已为 DONE、TRANSFER 还在 PENDING_REVIEW），户级 `statusName` 读到的是 TRAVEL 那条的文案。**逐条的权威状态一律读 `requirements[].status` 和 `requirements[].statusName`，不要读户级字段。**
+- **TRANSFER 专属字段**：`pickupRequired` 与 `dropoffRequired` 仅 `kind=TRANSFER` 时有值；`kind=TRAVEL` 时恒为 null（库里的值是写侧缺省 true，不表示该户要接机）。
+- **被打回的需求已失活**：打回后该行行号置为 REJECTED_* 且 `is_active=0`，不在本列表内。被打回的户在本列表里显示为 0 条需求行（#8151 遗留限定）。
+- **未提交需求的户**：户级 `status` 与 `statusName` 为 null，`requirements` 为空数组。
+- **不传 kind 参数时**：两类都返。这与提交侧「不传按 TRAVEL」的缺省刻意相反，防止接送机在页面上整类消失。
+- **鉴权**：需 `AdminContextUtil` 权限检查（`GroupBatchPermissionGuard.PERMISSION_VIEW`）。
+
+---
+
+## 四、契约约束与正确调用方式
+
+### 状态码与文案的对应关系
+
+| status | kind=TRAVEL | kind=TRANSFER | 说明 |
+|--------|------------|---------------|------|
+| PENDING | 待车队配 | 待车队配 | 待定制师报需求 |
+| PROCESSING | 配车中 | 配车中 | 定制师已报，车队配置中 |
+| DONE | 配车完成 | 配车完成 | 车队配置完毕 |
+| PENDING_REVIEW | **待提交车务** | **待审核** | **本次变化关键点**：TRAVEL 等团期管理员整团提交，TRANSFER 逐户审核 |
+| REJECTED_TO_CONSULTANT | 已驳回定制师 | 已驳回定制师 | 驳回给定制师修改 |
+| REJECTED_TO_ADMIN | 已驳回管理员 | 已驳回管理员 | 驳回给管理员修改 |
+
+**前端注意**：不要用中文名做任何判定逻辑，一律用英文码 `status` 或 `vehicleRequirementStatus`；中文名仅用于展示。
+
+### 调用顺序建议
+
+出口一（子订单列表）适合快速获取列表页的概览信息；出口二（需求记录）适合进入详情页查看完整的车队配置。前端加载详情页时建议同时传 `kind` 参数筛选，而不是获取全量后在页面上过滤。
+
+---
+
+## 五、数据库行为
+
+无写操作。响应字段 `vehicleRequirementStatusName` / `statusName` 由后端实时计算，读取 `order_vehicle_requirement.status` 列后由 `GroupBatchConverter.resolveRequirementStatusName(code, true, kind)` 翻译成中文。翻译逻辑中，`kind` 参数直接影响 PENDING_REVIEW 的输出。
+
+---
+
+## 六、边界行为
+
+- **未登录**：401（网关拦截）
+- **团期不存在**：404
+- **无需求行**：出口一回落 `vehicleRequirementStatus="PENDING"` / `vehicleRequirementStatusName="待车队配"`；出口二该户出现 `requirements=[]` 且 `status/statusName=null`
+- **查询超时/服务降级**：不适用（纯查询，无外部依赖）
+- **权限不足**：403（后端权限检查失败）
+
+---
+
+## 六.5、枚举 / 数据字典
+
+### vehicleRequirementStatus / status（需求状态）
+
+**所属字段**: `GroupBatchOrderItemRespVO.vehicleRequirementStatus` / `GroupVehicleHouseholdsRespVO.HouseholdItem.status` / `GroupVehicleHouseholdsRespVO.RequirementItem.status` | **类型**: `String`
+
+| 值 | TRAVEL 文案 | TRANSFER 文案 | 说明 |
+|----|-----------|-------------|------|
+| PENDING | 待车队配 | 待车队配 | 定制师未提交或提交后被清空 |
+| PROCESSING | 配车中 | 配车中 | 定制师已提交，车队正在配置 |
+| DONE | 配车完成 | 配车完成 | 车队配置已完毕 |
+| PENDING_REVIEW | 待提交车务 | 待审核 | #8218 分叉。TRAVEL：等团期管理员整团放行；TRANSFER：逐户审核 |
+| REJECTED_TO_CONSULTANT | 已驳回定制师 | 已驳回定制师 | 审核打回给定制师修改 |
+| REJECTED_TO_ADMIN | 已驳回管理员 | 已驳回管理员 | 审核打回给管理员修改 |
+
+### kind（需求类别）
+
+**所属字段**: `GroupVehicleHouseholdsRespVO.RequirementItem.kind` | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| TRAVEL | 行程用车 | 出团期间的长距离用车，由定制师逐户报，团期管理员整团审核 |
+| TRANSFER | 接送机 | 出发地/目的地的往返机场/火车站接送，由定制师逐户报，车务逐户审核 |
+
+---
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 | 变化说明 |
+|------|------|------|----------|
+| `GroupBatchOrderItemRespVO.vehicleRequirementStatusName` | PENDING_REVIEW 时固定「待审核」| PENDING_REVIEW 时下发「待提交车务」（本出口恒为 TRAVEL） | 新增第 3 参 `vehicleKind` 到转换函数，按 kind 分叉 |
+| `GroupVehicleHouseholdsRespVO.HouseholdItem.statusName` | PENDING_REVIEW 时固定「待审核」| PENDING_REVIEW 时按首条需求行的 kind 分叉 | 同步调整 |
+| `GroupVehicleHouseholdsRespVO.RequirementItem.statusName` | PENDING_REVIEW 时固定「待审核」| PENDING_REVIEW 时按本行 kind 分叉 | 同步调整 |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 | 影响 |
+|------|------|------|------|
+| TRAVEL PENDING_REVIEW 文案 | 「待审核」 | 「待提交车务」 | 前端渲染改变，需同步 UI 逻辑 |
+| TRANSFER PENDING_REVIEW 文案 | 「待审核」 | 「待审核」 | 无改变 |
+| 查询接口无新增参数 | - | 出口二仍支持 `kind` 筛选，无新参数 | 前端无需改入参 |
+
+---
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 否。返回字段名、字段类型、入参名均无改变，仅字段值的中文描述改变（可视为前端展示层改变，不是数据契约改变）。
+- **前端是否必须同步上线**: 是。出口一的文案变化直接影响子订单列表的渲染；出口二的文案变化影响需求详情页的渲染。前端若依赖旧的「待审核」文案做 UI 逻辑判定（如条件渲染、样式选择），将显示错误。
+- **前端 workaround 清理点**：
+  - 原有「TRAVEL 需求在 PENDING_REVIEW 时文案为「待审核」」的假设可全部删除
+  - 原有「TRANSFER 需求在 PENDING_REVIEW 时文案为「待审核」」的假设仍然有效
+  - 若原代码中写死了状态文案映射（如 `const statusMap = { PENDING_REVIEW: '待审核' }`），需改为按 `kind` 分叉的版本
+
+---
+
+## 七、不影响范围
+
+- **仅影响**：
+  - 管理后台「团期详情」页面的「客户清单」tab（出口一）
+  - 管理后台「团期详情」页面的「查看需求」tab（出口二）
+  - 以上两处 PENDING_REVIEW 状态的文案展示
+
+- **零影响**：
+  - C 端订单详情（不调用这两个端点）
+  - 订单创建/支付/确认接口
+  - 用房需求接口（独立体系）
+  - 子订单逐户审核/打回/提交流程的后端逻辑（本变更仅涉文案翻译，无业务流程改动）
+  - 历史订单数据（读取时即时翻译，无存量迁移）
+
+---
+
+## 八、测试环境已验证
+
+测试服部署：`hl-order-service-v3` / branch `dev-v3` / commit `7738668b8` / 2026-09-23 13:34:56
+
+**出口一验证**
+
+```
+GET /v3/admin/order/group-batch/2101009024268386304/orders?page=1&pageSize=20
+  vehicleRequirementStatus=PENDING_REVIEW, kind=TRAVEL (隐含)
+  → vehicleRequirementStatusName=「待提交车务」 ✓
+```
+
+**出口二验证 - TRAVEL**
+
+```
+GET /v3/admin/order/group-batch/2101009024268386304/requirement/vehicle-households?kind=TRAVEL
+  HouseholdItem.requirements[kind=TRAVEL].status=PENDING_REVIEW
+  → HouseholdItem.requirements[kind=TRAVEL].statusName=「待提交车务」 ✓
+```
+
+**出口二验证 - TRANSFER**
+
+```
+GET /v3/admin/order/group-batch/2101009024268386304/requirement/vehicle-households?kind=TRANSFER
+  RequirementItem[kind=TRANSFER].status=PENDING_REVIEW
+  → RequirementItem[kind=TRANSFER].statusName=「待审核」 ✓
+```
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#8218](https://git.1814.love/wx/HL/issues/8218)
+- 后续计划: 前端改动由 mmg 团队负责
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8218](https://git.1814.love/wx/HL/issues/8218)
+- **PR**: [#8218](https://git.1814.love/wx/HL/pulls/8218)
+- **后端 commit**: [7738668b8](https://git.1814.love/wx/HL/commit/7738668b8)
+
+### 联系人
+
+- **后端负责人**: @wx
+- **前端负责人**: @mmg
@@ -0,0 +1,407 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8220"
+title: "团期正式行程用车需求自动汇总草稿"
+consumer: "admin"
+author: "jw(GIT)"
+change_type: "新增接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "ee98b96654fd250159ee4a3b0067e5f1c88d3b75"
+target_release: "v2.1"
+verified_at: "2026-09-23"
+status_note: "后端已部署 TEST 并经网关实测；待 mmg 在编辑弹窗接入「自动汇总」+ 乘车户全选 + 人数随所选户汇总；前端已交付:编辑弹窗「自动汇总」灌草稿+四诊断展示+大类收敛(suv→suv2)+version 用草稿值+非 DRAFT 禁保存;spec 41 例全绿,checkpoint 13 项过"
+updated_at: "2026-09-23"
+base: "dev-v3"
+---
+
+# 团期正式行程用车需求自动汇总草稿（#8220）
+
+> **服务**: hl-order-service-v3（经网关调用，无需关心服务端口）
+> **PR**: #8273
+> **Issue**: #8220
+> **日期**: 2026-09-23
+> **影响范围**: 管理后台团期详情「用车」Tab 的正式行程用车需求编辑弹窗
+
+---
+
+## ⚠️ 关键变化
+
+新增只读端点，按各子订单已提交的行程用车（TRAVEL）需求，自动汇总出团级正式用车需求草稿。草稿形状与保存端点 `PUT .../vehicle-requirement` 的请求体**完全一致**，前端可以直接灌进编辑弹窗、原样保存。
+
+**四条会直接影响你怎么写代码的点，按严重度排**：
+
+1. 🔴 **草稿之外的四个诊断字段必须展示，不能只看 `draft`**。`droppedFleetItems` 里是**没进草稿的车型需求**（一户报了多个车型时只保留主车型），不提示的话，管理员一保存，这些需求就从团级正式需求里消失了。另外三个字段（`staleHeadcountOrders` / `paddedOrderDays` / `violations`）见业务边界。
+2. 🔴 **车型回显是归一后的大类 key（`suv` / `bus` / `mpv` / `sedan`）**，与 #8221 交接件里提过的是同一个问题：车型下拉的 value 是 fleet typeKey `suv2`，拿 `suv` 逐字去比会判成「非字典值，请重选」，并被前端校验拦住保存。**判「是否字典值」要按归一后的大类比**，否则所有 SUV 组汇总出来都会被弹窗拦下。
+3. **有户还没提交行程用车需求时，本端点直接返回业务错误 `809121`**，报文逐户列出「订单号(orderId)：原因」。这时不要尝试拼一份草稿，应提示管理员去催这些户。
+4. **成功码是 `code: 200`**；业务失败也返回 HTTP 200，**一律按 `body.code` 判**。
+
+---
+
+## 一、背景（选填）
+
+wx 2026-09-23 团期详情页「用车」Tab 反馈：「正式的行程用车需求要根据子订单的行程用车需求自动汇总 自动填写」，以及「得有个全选的按钮，根据选的乘车户自动把人数算出来」。此前编辑弹窗不拉取任何子订单需求数据，日期预填的是团期自己的出发/结束日，其余字段全靠手填。汇总规则由管理者于 2026-09-23 定案（#8220 评论）。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 自动汇总正式用车需求草稿 | GET | `/v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement/aggregate-draft` | 新增接口 | 只读，返回可原样保存的草稿与汇总诊断 |
+
+---
+
+## 三、接口详情
+
+### 1. 自动汇总正式用车需求草稿 `GET /v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement/aggregate-draft`
+
+**VO**: `GroupVehicleAggregateDraftRespVO`
+
+#### 使用场景
+
+管理员在编辑弹窗里点「自动汇总」时调用。拿到 `data.draft` 后填进弹窗，同时展示四个诊断字段；管理员确认后，把 `draft` 原样（或编辑后）交给 `PUT /v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement` 保存。
+
+弹窗里如果已经有编辑内容，点「自动汇总」前请二次确认「这将覆盖当前编辑内容」。本端点不管现在有没有正式需求，都返回完整汇总，要不要覆盖由前端交互决定。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| `groupBatchId` | Path | Long | ✅ | — | 团期 ID（`group_batch_id`），🔴 不是产品班期 ID |
+
+#### 出参 `Result<GroupVehicleAggregateDraftRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `groupBatchId` | String（雪花 ID） | 团期 ID |
+| `currentStatus` | String / null | 当前正式需求状态；还没形成时为 null。**只有 null 或 `DRAFT` 时才能保存**（其余状态保存会报 809101 / 809115），前端据此决定「保存」按钮是否可用 |
+| `draft` | Object | 汇总草稿，与保存请求体同形，**恒非 null** |
+| `draft.version` | Integer / null | 当前正式需求的乐观锁版本；未形成时为 null。保存时原样带上 |
+| `draft.remark` | String / null | 整份备注，汇总时恒为 null |
+| `draft.groups[]` | Array | 乘车分组，没有可汇总内容时为空数组 |
+| `draft.groups[].groupId` | Long / null | 恒为 null（汇总产物一律是新组） |
+| `draft.groups[].groupCode` | String | 车型大写，同车型按连续日期段拆组时第二段起加序号：`BUS`、`BUS2`… |
+| `draft.groups[].vehicleType` | String | 归一后的车型大类 key：`bus` / `suv` / `mpv` / `sedan` |
+| `draft.groups[].serviceStartDate` | String(`yyyy-MM-dd`) | 本组首日 |
+| `draft.groups[].serviceEndDate` | String(`yyyy-MM-dd`) | 本组末日 |
+| `draft.groups[].seats` | Integer / null | 组内各户保留车型项里最大的单车座位数；各户都没填座位时，与 `count` 一起为 null |
+| `draft.groups[].count` | Integer / null | `ceil(本组最忙那天的人数 / (seats − 1))`，已扣除司机座 |
+| `draft.groups[].specialTags` | String[] | 组内各户特殊诉求编码的并集（去重、保持顺序） |
+| `draft.groups[].remark` | String / null | 逐户「订单号: 定制师备注」和「订单号 另报 suv 7座×1」拼接而成，超过 500 字截断。**仅供人眼留底** |
+| `draft.groups[].days[]` | Array | 逐日明细，正好铺满本组首日到末日 |
+| `draft.groups[].days[].tripDate` | String(`yyyy-MM-dd`) | 日期 |
+| `draft.groups[].days[].headcount` | Integer | 当天在组各户的**实时**人数之和 |
+| `draft.groups[].days[].memberOrderIds` | String[]（雪花 ID） | 当天在组的子订单 ID。🔴 19 位雪花 ID，前端一律按字符串处理 |
+| `droppedFleetItems[]` | Array | 没进草稿的车型项，见业务边界第 1 条 |
+| `droppedFleetItems[].orderId` / `orderNo` | String / String | 所属子订单 |
+| `droppedFleetItems[].vehicleType` / `seats` / `count` | String / Integer / Integer | 被丢弃项（子订单原值） |
+| `droppedFleetItems[].keptVehicleType` | String | 该户被归入的主车型 |
+| `droppedFleetItems[].reason` | String | `NOT_PRIMARY_TYPE`（非主车型）/ `VEHICLE_TYPE_NOT_IN_DICT`（车型不在车型字典内） |
+| `staleHeadcountOrders[]` | Array | 实时人数与子订单需求提交时冻结的人数不一致的户：`orderId` / `orderNo` / `frozenHeadcount` / `liveHeadcount` |
+| `paddedOrderDays[]` | Array | 为了覆盖该户「出发~返回」每一天而补进分组、但不在该户行程用车服务日里的日期：`orderId` / `orderNo` / `dates[]` |
+| `violations[]` | Array | 草稿按保存时同一套校验预检出的问题：`code` / `reason` / `detail` / `groupCode` / `tripDate` / `orderId`。正常应为空数组 |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch/2102692937584513025/vehicle-requirement/aggregate-draft
+Authorization: Bearer <admin token>
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "groupBatchId": "2102692937584513025",
+    "currentStatus": null,
+    "draft": {
+      "version": null,
+      "remark": null,
+      "groups": [
+        {
+          "groupId": null,
+          "groupCode": "BUS",
+          "vehicleType": "bus",
+          "serviceStartDate": "2026-11-24",
+          "serviceEndDate": "2026-11-26",
+          "seats": 16,
+          "count": 1,
+          "specialTags": [],
+          "remark": "HL20260923173356872: 8220 甲户多车型；HL20260923173356872 另报 suv 5座×1；HL20260923173401731: 8220 乙户",
+          "days": [
+            {
+              "tripDate": "2026-11-24",
+              "headcount": 5,
+              "memberOrderIds": [
+                "2102692937378992129",
+                "2102692957587165185"
+              ]
+            },
+            {
+              "tripDate": "2026-11-25",
+              "headcount": 5,
+              "memberOrderIds": [
+                "2102692937378992129",
+                "2102692957587165185"
+              ]
+            },
+            {
+              "tripDate": "2026-11-26",
+              "headcount": 5,
+              "memberOrderIds": [
+                "2102692937378992129",
+                "2102692957587165185"
+              ]
+            }
+          ]
+        },
+        {
+          "groupId": null,
+          "groupCode": "SUV",
+          "vehicleType": "suv",
+          "serviceStartDate": "2026-11-24",
+          "serviceEndDate": "2026-11-26",
+          "seats": 5,
+          "count": 1,
+          "specialTags": [],
+          "remark": "HL20260923173405165: 8220 丙户",
+          "days": [
+            {
+              "tripDate": "2026-11-24",
+              "headcount": 2,
+              "memberOrderIds": [
+                "2102692971709370370"
+              ]
+            },
+            {
+              "tripDate": "2026-11-25",
+              "headcount": 2,
+              "memberOrderIds": [
+                "2102692971709370370"
+              ]
+            },
+            {
+              "tripDate": "2026-11-26",
+              "headcount": 2,
+              "memberOrderIds": [
+                "2102692971709370370"
+              ]
+            }
+          ]
+        }
+      ]
+    },
+    "droppedFleetItems": [
+      {
+        "orderId": "2102692937378992129",
+        "orderNo": "HL20260923173356872",
+        "vehicleType": "suv",
+        "seats": 5,
+        "count": 1,
+        "keptVehicleType": "bus",
+        "reason": "NOT_PRIMARY_TYPE"
+      }
+    ],
+    "staleHeadcountOrders": [],
+    "paddedOrderDays": [],
+    "violations": []
+  },
+  "success": true
+}
+```
+
+**示例说明**：示例值取自测试环境一次真实调用，不构成可复现夹具。
+
+#### 空数据 / 降级响应
+
+团里没有需要用车的户，也没有任何 TRAVEL 需求时，返回空草稿（**`groups` 是空数组，不是 null**）：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "groupBatchId": "2102692937584513025",
+    "currentStatus": null,
+    "draft": { "version": null, "remark": null, "groups": [] },
+    "droppedFleetItems": [],
+    "staleHeadcountOrders": [],
+    "paddedOrderDays": [],
+    "violations": []
+  },
+  "success": true
+}
+```
+
+车型字典（车队服务）不可用时**不降级**，返回 809120，见错误响应。
+
+#### 错误响应
+
+**有户缺少可汇总的行程用车需求**（未提交 / 被打回未重提 / 车型都不在字典内 / 推不出日期 / 人数为 0）：
+
+```json
+{
+  "code": 809121,
+  "message": "团期 2102692937584513025 有 1 户缺少可汇总的行程用车需求，暂不能自动汇总：HL20260923173405165(2102692971709370370)：未提交行程用车需求",
+  "data": null,
+  "success": false
+}
+```
+
+**车型字典暂不可用**：
+
+```json
+{
+  "code": 809120,
+  "message": "车队车型字典暂不可用，无法校验车型，请稍后重试",
+  "success": false,
+  "data": null
+}
+```
+
+**无权限**（当前角色没有 `group-batch:demand:confirm`）：
+
+```json
+{
+  "code": 589507,
+  "message": "无操作权限（当前角色未授予团期权限，或该团期不在您名下）",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- **多车型户**：一户的行程用车同时报了多个车型（如 bus×1 + suv×1）时，这一户只进「主车型」组。主车型取座位数×辆数最大的那一项，相等时取车型编码字典序小的，所以同一份数据每次汇总结果都相同。其余车型进 `droppedFleetItems`，🔴 **前端必须醒目提示**「以下车型需求未包含在草稿中」。这样做是因为同一户同一天只能属于一个分组（809108）。
+- **拆组**：同一车型的日期如果断开（比如甲 10-08~10-09、乙 10-12~10-13），会拆成 `BUS` / `BUS2` 两组，不会产出某天零人的逐日行。
+- **补日**：团级保存要求每个需车户「出发~返回」的每一天都被分组覆盖（809109）。子订单行程用车的服务日如果比这个范围窄，多出来的日期也会把该户算进车，并列在 `paddedOrderDays` 里。前端提示「以下户在这些日期原本未报用车，已按行程补入」。
+- **人数**：逐日人数用订单**实时**人数，与户列表显示的人数一致。实时人数与子订单需求提交时冻结的人数不一致时，该户进 `staleHeadcountOrders`，说明那户的子订单用车需求已经过期，车务在子订单侧看到的还是旧值。
+- **座位与车数**：`count` 按扣掉司机座的口径算，所以草稿在团级（809116）和子订单级两种座位校验下都成立。
+- **`violations` 为空也不保证保存一定成功**：`currentStatus` 不是 null 或 `DRAFT`、或者汇总之后有人改过正式需求（version 变了），保存照样会被拒。
+- **只汇总行程用车（TRAVEL）**，接送机（TRANSFER）不进团车。
+- **本端点零写入**：不取锁、不进事务，调多少次都不影响数据。
+
+---
+
+## 四、契约约束与正确调用方式
+
+### ✅ 正确 / ❌ 错误请求对照
+
+| 场景 | 请求 | 预期（HTTP 恒 200） |
+|------|------|------|
+| ✅ 各户都已提交 | `GET .../{groupBatchId}/vehicle-requirement/aggregate-draft` | `code: 200`，`draft.groups` 非空 |
+| ✅ 原样保存 | `PUT .../{groupBatchId}/vehicle-requirement`，请求体 = `data.draft` | `code: 200` |
+| ❌ 有户未提交 | 同上 GET | `code: 809121`，报文列出未提交的户 |
+| ❌ 路径传成产品班期 ID | `GET .../{productBatchId}/vehicle-requirement/aggregate-draft` | 团期不存在的错误码（589500） |
+
+### 前端「乘车户全选 + 人数自动汇总」的取数口径（wx 反馈第 ③ 条）
+
+- **户清单与每户人数**：用既有的 `GET /v3/admin/order/group-batch/{groupBatchId}/requirement/vehicle-households?kind=TRAVEL`，人数取 `households[].participantCount`。它与本端点草稿里的逐日人数同源，都是订单实时人数。
+- 🔴 **不要用分页的团期订单列表做「全选」**：那个列表单页上限 200，户数超过 200 时会漏选。`vehicle-households` 不分页，单次最多 500 户。
+- **某天的人数** = 当天勾选各户的 `participantCount` 之和。汇总草稿里的 `days[].headcount` 就是按这个口径算的，可以直接对照。
+
+---
+
+## 五、数据库行为
+
+本接口**只读**，没有任何数据库写入，不新增表、不改表结构，也没有 Flyway 脚本。测试环境实测：调用前后，团级正式需求相关表与子订单用车需求表的行数和 `update_time` 都没有变化（见第八节）。
+
+---
+
+## 六、边界行为
+
+- **鉴权**：需要 `group-batch:demand:confirm`，与 `GET/PUT .../vehicle-requirement` 同一个权限码。不带 token 时网关返回 401；角色没有该权限时返回 `code: 589507`。
+- **网关路由**：沿用现有的 `- Path=/v3/admin/**` → `lb://hl-order-service-v3`，本单**不新增路由**。
+- **团期不存在** → 589500。
+- **有户缺少可汇总需求** → 809121；**车型字典不可用** → 809120。
+
+---
+
+## 六.5 枚举 / 数据字典
+
+### droppedFleetItems[].reason
+
+**所属字段**: `droppedFleetItems[].reason` | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|---|---|---|
+| `NOT_PRIMARY_TYPE` | 非主车型 | 该户多车型，只保留主车型 |
+| `VEHICLE_TYPE_NOT_IN_DICT` | 车型不在字典 | 车型归一后不在车队车型字典内 |
+
+---
+
+## 六.6 修改前后对比
+
+无，本接口为新增。
+
+---
+
+## 六.7 影响评估
+
+- **破坏兼容**：否，新增接口
+- **前端同步上线要求**：否，不接入也不影响现有编辑与保存流程
+- **新增错误码**：`809121`（有户缺少可汇总的行程用车需求）
+
+---
+
+## 七、不影响范围
+
+- **仅影响**：团期正式行程用车需求编辑弹窗的「自动汇总」入口
+- **零影响**：
+  - 正式用车需求的保存 / 读取 / 撤回 / 免车 / 确认（校验语义一处未改）
+  - 子订单用车需求的提交与审核
+  - 接送机（TRANSFER）链路
+
+---
+
+## 八、测试环境已验证
+
+真实网关调用（`https://api.test.1814.love`），hl-order-service-v3 已部署 `dev-v3 @ 9b60bc62b`（本单合并提交，两个实例都在 17:21 滚动重启）。夹具全部自建：产品班期 `2102692899017912323`，团期 `2102692937584513025`，三户订单甲 / 乙 / 丙。
+
+```
+GET .../2102692937584513025/vehicle-requirement/aggregate-draft   （三户都没提交 TRAVEL）
+  → 809121，报文列出 3 户 ✓；甲户提交后列 2 户 ✓；乙户提交后列 1 户 ✓
+GET .../aggregate-draft   （三户都已提交：甲 bus 16×1 + suv2 5×1、乙 bus 12×1、丙 suv2 5×1）
+  → 200：BUS 组（甲 + 乙，seats=16，count=1，每天 5 人）+ SUV 组（丙）；
+    droppedFleetItems = 甲户 suv 5×1（NOT_PRIMARY_TYPE）；violations = [] ✓
+PUT .../2102692937584513025/vehicle-requirement   请求体 = data.draft 原样
+  → 200，version=1；GET 回读后逐字段比对与草稿一致 ✓（再汇总一次、带 version=1 原样保存 → 200，version=2 ✓）
+零写入：调汇总前后各读一次 order_group_vehicle_requirement / _group / _group_day / order_vehicle_requirement
+  的全表行数与 MAX(update_time)，以及本团相关行 → 两轮前后完全一致 ✓
+丙户另外提交了 TRANSFER（mpv，11-23 接机）→ 草稿里没有 mpv，也没有 11-23 ✓
+不带 token → code 401「缺少有效的 Authorization 头」 ✓
+定制师角色（无 group-batch:demand:confirm）→ code 589507 ✓
+```
+
+---
+
+## 九、相关历史 PR
+
+- #8221（车型字典与存量车型归一）：本端点输出的车型同样要通过 809119
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#8220](https://git.1814.love/wx/HL/issues/8220)
+- 关联 PR: [wx/HL#8273](https://git.1814.love/wx/HL/pulls/8273)
+
+---
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8220](https://git.1814.love/wx/HL/issues/8220)
+- **PR**: [#8273](https://git.1814.love/wx/HL/pulls/8273)
+- **Merge commit**: [9b60bc62b](https://git.1814.love/wx/HL/commit/9b60bc62b)
+
+### 联系人
+
+- **后端负责人**: @jw
@@ -0,0 +1,110 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8221"
+title: "团期正式用车需求: 存量自由文本车型已归一成字典大类 key，原样回传不再撞 809119；前端 SUV 下拉回显需按大类比对"
+consumer: "admin"
+author: "jw(GIT)"
+change_type: "修复"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "c314c8c67ddc61b8a1e4f4373d79e5a731b13272"
+target_release: ""
+verified_at: "2026-09-23"
+status_note: "接口契约零变化（路径、入参、出参、错误码都没改），变的是库里存量数据：Java 迁移 V20260924_402 把活跃版本上 81 行自由文本车型归一成 suv/mpv/sedan/bus。PR #8236 已合并 dev-v3（f5ffeffe7）；TEST order-v3 在 fe752f16c（含本单）上运行，迁移 2026-09-23 12:19:36 执行成功。经真实网关验证：字典 4 个 typeKey 都过了车型校验，minivan 仍报 809119，存量团期原样回传返回 200。gateway_status=verified：零新增路由，在既有端点上做了 round-trip。frontend_status=pending：GroupVehicleRequirementEditModal.vue 判「是否字典值」时拿原值和 typeKey 逐字比，SUV 组回显 suv 对不上 suv2，见正文第三节。 | 2026-09-23 mmg 交付:EditModal 按 vehicleTypeName 匹配字典 typeName 收敛回显,不占位不拦保存"
+updated_at: "2026-09-23"
+base: "dev-v3"
+---
+
+# 团期正式用车需求: 存量车型归一 + SUV 下拉回显不匹配
+
+> **存放目录**: 二期（order-v3）→ `changelogs-v2/2026-09/`
+>
+> **服务**: hl-order-service-v3（Flyway Java 迁移）
+> **PR**: [#8236](https://git.1814.love:8443/wx/HL/pulls/8236)
+> **Issue**: [#8221](https://git.1814.love:8443/wx/HL/issues/8221)
+> **日期**: 2026-09-23
+> **影响范围**: `GET` / `PUT /v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement` 里 `groups[].vehicleType` 的**存量取值**
+
+---
+
+## ⚠️ 关键变化
+
+1. **存量团期的 `groups[].vehicleType` 现在都是规范大类 key**（`suv` / `mpv` / `sedan` / `bus`），不再有 `35座大巴`、`SUV`、`jiaoche` 这类自由文本。
+   所以打开存量团期的编辑弹窗、不改车型直接保存，**不会再撞 809119**。
+2. **`groups[].vehicleTypeName` 对这些行现在有值了**（如 `大巴系列`）。以前原值不是 key，取不到中文名，返回 null。
+3. **归一时丢掉的原文（座位数、拼音写法）追加在该组 `groups[].remark` 里**，格式为 `原车型：35座大巴`；原来有备注的，用 `；` 接在后面。
+4. **校验本身没有放宽**：字典外的值（如 `minivan`）照样报 809119，文案不变。
+
+---
+
+## 一、变更接口清单
+
+| 方法 | 路径 | 变更性质 |
+|---|---|---|
+| GET | `/v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement` | 字段结构不变，存量 `vehicleType` 取值已归一 |
+| PUT | `/v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement` | 契约不变；存量值原样回传不再被 809119 拒 |
+
+> 本条不属于「新增接口 / 修改接口」：请求参数、响应字段、错误码都没有增删改。
+
+---
+
+## 二、存量映射表（TEST 实测，活跃版本）
+
+| 原值 | 归一后 | 行数 | remark 留底 |
+|---|---|---|---|
+| `SUV` | `suv` | 35 | 否 |
+| `35座大巴` | `bus` | 15 | 是 |
+| `轿车` | `sedan` | 13 | 否 |
+| `商务车` | `mpv` | 10 | 否 |
+| `jiaoche` | `sedan` | 4 | 是 |
+| `35zuo daba` | `bus` | 1 | 是 |
+| `7座商务车` | `mpv` | 1 | 是 |
+| `car` | `sedan` | 1 | 是 |
+| `shangwu` | `mpv` | 1 | 是 |
+
+- 只改**当前活跃版本**。历史版本（已失效的需求版本）保持原样，所以查历史时仍可能看到旧的自由文本。
+- 迁移认不出的值会原样保留（TEST 活跃版本里为 0 个），这类值仍会被 809119 拒，需要在下拉里重选。
+- `update_time` 没有被刷新，这次归一不会显示成一次用户编辑。
+
+---
+
+## 三、🔴 前端需要改的一处：SUV 组存完再打开会被判成「非字典值」
+
+**现象**：`GroupVehicleRequirementEditModal.vue` 的下拉 value 用的是 `GET /admin/fleet/vehicle-types/list` 的 `typeKey` 原值。TEST 上 SUV 这一项的 `typeKey` 是 **`suv2`**。
+后端保存时会把提交值归一成大类 key 再落库（`suv2` → `suv`），GET 也原样回显 `suv`。
+
+`vehicleTypeKeys` 只有 `{suv2, mpv, sedan, bus}`，于是：
+
+- `vehicleTypeOptionsFor(g)`（`:306-316`）会给这组合成一个 `suv(非字典值,请重选)` 占位项；
+- `vehicleTypeRule`（`:343-355`）把这组判成字典外的值，**拦住保存**。
+
+⇒ **只要是 SUV 组，每次打开编辑弹窗都得重选一遍**。本次归一后，存量 35 行 `SUV` 都变成了 `suv`，也会落进这个情况。`mpv` / `sedan` / `bus` 的 typeKey 与大类 key 正好相同，不受影响。
+
+**建议改法**（选一种）：
+
+- 判断「当前值是否在字典内」时按**大类**比较：GET 回显的 `vehicleTypeName` 非空，就说明该值已命中字典大类，可以用它去匹配下拉项的 `typeName`（TEST 上 `suv` → `SUV系列`，与 `suv2` 的 `typeName` 相同）；
+- 或者在前端维护一张 typeKey → 大类的映射，用来选中回显项。**不要写死 `suv2`**：字典是运行期数据，typeKey 是开集，随时可能变。
+
+提交时继续传 typeKey 原值（`suv2`），后端会自己归一，这一点不变。
+
+---
+
+## 四、后端已验证的读数（测试服活体，order-v3 @ `fe752f16c`）
+
+| 验证项 | 读数 |
+|---|---|
+| 迁移执行 | `flyway_schema_history` 版本 `20260924.402` success=1，2026-09-23 12:19:36，耗时 11ms |
+| 数据终态 | 活跃版本 83 行全部是规范 key；23 行 remark 带「原车型：」；历史版本 19 行没有动 |
+| 字典 typeKey 全部能过 | `suv2` / `mpv` / `sedan` / `bus` 逐个 PUT，都没触发 809119 |
+| 阴性对照 | `minivan` → `809119 第 ALL 组的车型 minivan 不在车型字典内（不存在或已下线），请从下拉项中选择` |
+| 存量原样回传 | 原值为 `35座大巴` 的团期：GET 回显 `bus` / `大巴系列`，原样 PUT → HTTP 200 / code 200，version 2→3 |
+| 鉴权 | 不带 token → 401 |
+
+---
+
+## 五、你需要做的
+
+- 按第三节改一下 `GroupVehicleRequirementEditModal.vue` 判断字典值的方式，SUV 组就不用每次重选了。
+- 其他车型不用改：存量值都已经是字典 key，编辑态能正常回显和保存。
@@ -0,0 +1,239 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8225"
+title: "订单调整统一提交：远程调用移出锁与事务，新增失败码 587043「提交期间订单已被其他操作修改，请刷新后重试」"
+consumer: "admin"
+author: "jw(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "not_required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "PR #8255 已合并 dev-v3（c2b261cd2），2026-09-23 15:40 滚动部署 TEST 双实例；其后另一会话部署的 f6d21648b 包含本单。真实网关实测：非法座位数提交返回 582024 且零写入，日志确认拒绝发生在拿锁之前；改出行人姓名正向往返 200 并落调整记录，已改回原值；无 token / 伪造 token 均 401。入参、出参结构不变，唯一的契约变化是新增失败码 587043；前端按通用失败提示展示后端 message 即可，无需改动。"
+updated_at: "2026-09-23"
+base: "dev-v3"
+---
+
+# 订单调整: 统一提交的远程调用移出锁与事务 + 新增失败码 587043
+
+> **存放目录**: 二期(v3) → `changelogs-v2/2026-09/`
+>
+> **服务**: hl-order-service-v3
+> **PR**: #8255
+> **Issue**: #8225
+> **日期**: 2026-09-23
+> **影响范围**: 管理后台订单详情「调整订单」弹窗的统一提交
+
+---
+
+## ⚠️ 关键变化（非必须,本版与上版行为不同 / 纠错 / 撤销时必写）
+
+- 本次变化：统一提交接口多了一个失败码 `587043「提交期间订单已被其他操作修改，请刷新后重试」`。
+- 前端以前以为的：同一订单两次调整并发提交时，后提交的那次会排队等前一次完成，然后照常成功。
+- 实际新行为：算价、协议价、车型校验这些远程调用现在在**拿锁之前**完成。如果在这段时间里另一笔调整改了本单的出发日、人数或产品，本次提交会被拒绝并返回 587043，整笔不写库；用户刷新后重新提交即可。请求和响应的结构都没有变。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 调整订单统一提交 | POST | `/v3/admin/order/:id/adjustment/submit` | 新增失败码 | 新增 587043；入参、出参不变 |
+
+---
+
+## 三、接口详情
+
+### 1. 调整订单统一提交 `POST /v3/admin/order/:id/adjustment/submit`
+
+**VO**: `AdjustmentSubmitReqVO → AdjustmentSubmitRespVO`
+
+#### 使用场景
+
+管理后台订单详情页「调整订单」弹窗，前端在内存里收集出行人、改期、行程、用房需求、行程用车、接送机用车等改动后一次性提交。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| Authorization | Header | String | ✅ | - | 管理端登录令牌 |
+| id | Path | Long | ✅ | 订单须存在（581007） | 订单 ID |
+| updates | Body | Object | ✅ | 至少一个子领域有实际改动（587033） | 各子领域修改内容，未改的子领域传 null |
+| updates.people | Body | Object | ❌ | - | 订单级紧急联系人 + 出行人增删改 |
+| updates.travelers | Body | Object | ❌ | - | 出行人 add / update / remove |
+| updates.schedule | Body | Object | ❌ | departDate 为 `yyyy-MM-dd` | 改期 |
+| updates.itinerary | Body | Object | ❌ | - | 行程天与节点的完整新版本 |
+| updates.hotelRequirement | Body | Object | ❌ | - | 用房需求完整新版本 |
+| updates.vehicleRequirement | Body | Object | ❌ | fleet 车型须为车型大类、座位数须在车型库选项内 | 行程用车需求完整新版本 |
+| updates.transferRequirement | Body | Object | ❌ | 同上 | 接送机用车需求完整新版本 |
+
+#### 出参 `Result<AdjustmentSubmitRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| success | Boolean | 提交成功恒为 true |
+
+#### 请求示例
+
+```json
+{
+  "updates": {
+    "travelers": {
+      "update": [{ "id": "2098374040010772481", "name": "杨知川" }]
+    }
+  }
+}
+```
+
+#### 响应示例
+
+```json
+{ "code": 200, "message": "成功", "data": { "success": true }, "traceId": null, "success": true }
+```
+
+#### 空数据 / 降级响应
+
+写接口没有空数据场景。所有提交都没有实际改动时返回 587033，零写入：
+
+```json
+{ "code": 587033, "message": "未检测到有效变更，无需提交", "data": null, "traceId": null, "success": false }
+```
+
+#### 错误响应
+
+本次新增：
+
+```json
+{ "code": 587043, "message": "提交期间订单已被其他操作修改，请刷新后重试", "data": null, "traceId": null, "success": false }
+```
+
+既有错误码照旧，例如车型座位数不合法：
+
+```json
+{ "code": 582024, "message": "座位数不在该车型大类可选座位数中，请检查车型库", "data": null, "traceId": null, "success": false }
+```
+
+#### 业务边界
+
+- 鉴权：未登录 → 业务码 `401`（「缺少有效的 Authorization 头」），token 签名不对 → `401`（「Token 无效」）。
+- 587043 只在「本次提交读到的订单」与「拿锁后的订单」在出发日、人数、产品上不一致时出现，也就是有另一笔调整恰好在同一时刻提交；单人操作不会遇到。
+- 587043 与其它失败码一样整笔零写入，重新提交会按最新的订单状态重新计算差价。
+
+---
+
+## 四、契约约束与正确调用方式（接口类必写）
+
+> 本节只写**后端接受/拒绝 payload 的规则**，不写 UI 渲染建议。
+
+### ✅ 正确 / ❌ 错误 payload 对照
+
+| 场景 | payload | 结果 |
+|------|---------|------|
+| ✅ 只改出行人姓名 | `updates.travelers.update=[{id,name}]` | 200 |
+| ❌ 没有任何实际改动 | `updates: {}` | 587033 |
+| ❌ 行程用车座位数不在车型库选项内 | `fleet=[{vehicleType:"大巴", seats:999, count:1}]` | 582024，零写入 |
+| ❌ 提交期间另一笔调整改了出发日 / 人数 / 产品 | 任意 | 587043，零写入（**本次新增**） |
+
+- 请求与响应结构没有任何变化；587043 的 `message` 已写明处理方式，前端按通用失败提示展示后端文案即可。
+
+---
+
+## 五、数据库行为（涉及写操作时必写）
+
+- 无 Flyway migration、无 DDL、无表结构变更。
+- 写库集合与改前一致（出行人、行程、用房/用车需求版本、优惠加费、调整记录、状态日志），仍在同一个事务内原子完成。
+- 变化在事务边界：算价、协议价、车型校验等远程调用改为在拿锁、开事务之前完成，订单行与用车确认 fence 行的锁持有时间不再包含这些远程往返。
+- 任何失败（含新增的 587043）都在写库之前抛出，整笔零写入。TEST 实测：非法座位数提交后，订单主单、fence 行、用车需求、调整记录前后逐字段一致。
+
+---
+
+## 六、边界行为
+
+- 未登录 → 业务码 `401`。
+- 越权规则不变：非管理员只能调整自己负责的订单。
+- 拒绝原因的先后顺序不变：终态、已过天锁定、出行人/改期窗口、改期日期格式等守卫，仍然先于算价与车型校验。
+- 团期子订单改期仍只能改回所属团期出发日（587039），不走个人价格日历报价。
+
+---
+
+## 六.6、修改前后对比（修改/删除类接口必写，新增跳过）
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 |
+|------|------|------|
+| 请求体 | `AdjustmentSubmitReqVO` | 不变 |
+| 响应体 | `{ success }` | 不变 |
+| 失败码 | 无 587043 | 新增 587043 |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| 远程调用（算价、协议价、车型字典/座位、字典标签）发生时机 | 拿锁、开事务之后 | 拿锁、开事务之前 |
+| 两笔调整并发提交，前一笔改了出发日/人数 | 后一笔等锁后按新状态照常执行 | 后一笔返回 587043，刷新重提 |
+| 车队 / 产品 / 资源服务响应慢 | 订单行被锁住直到远程返回 | 不影响锁持有时间 |
+
+---
+
+## 六.7、影响评估（修改/删除类必写）
+
+- **是否破坏向后兼容**：请求、响应结构不变；只新增一个失败码，只在并发调整同一订单时出现。
+- **前端是否必须同步上线**：否。前端的通用失败提示会展示后端 `message`（「提交期间订单已被其他操作修改，请刷新后重试」），无需改动。
+- **前端 workaround 清理点**：无。
+
+---
+
+## 七、不影响范围（显式声明, 帮前端/QA 缩小排查面）
+
+- **仅影响**：`POST /v3/admin/order/:id/adjustment/submit` 的内部执行顺序，以及新增失败码 587043。
+- **零影响**：
+  - `GET /v3/admin/order/:id/adjustment/snapshot`（调整弹窗初始化数据）与 `GET /v3/admin/order/:id/adjustment-record`（调整记录）。
+  - 行程查询 `getItinerary` 返回的服务标准字段、大交通批次列表的旅客类型中文名（管理端读接口行为不变）。
+  - 既有失败码与文案。
+
+---
+
+## 八、测试环境已验证
+
+部署：PR #8255 合并 `dev-v3`（`c2b261cd2`），2026-09-23 15:40 滚动部署 TEST 双实例；其后另一会话部署的 `f6d21648b` 以本单为祖先，且其间没有提交改动本单涉及的文件。
+
+真实网关（`https://api.test.1814.love`，管理端 token，订单 `2098372757820428289`）：
+
+```
+POST /v3/admin/order/:id/adjustment/submit  无 token                    → 401 缺少有效的 Authorization 头 ✓
+POST /v3/admin/order/:id/adjustment/submit  伪造 token                  → 401 Token 无效 ✓
+POST ...  updates={}                                                    → 587033 未检测到有效变更 ✓
+POST ...  vehicleRequirement.fleet=[大巴 × 999 座]                      → 582024，订单/fence/用车需求/调整记录前后一致 ✓
+         同时刻 primary 实例日志：先是不加锁的 order_main 查询，全程 0 条 fence SQL、0 条 FOR UPDATE ✓
+POST ...  travelers.update 改姓名                                       → 200，姓名已改、调整记录 0→1 ✓
+POST ...  travelers.update 改回原名                                     → 200，姓名还原 ✓
+```
+
+587043 需要两笔调整真实竞态才能触发，TEST 上未造出；由单元测试覆盖（两段之间出发日变化 → 587043 且零写入；出发日未变 → 放行的对照）。
+
+单元测试：rebase 后定向 239 类 / 3290 例 0 失败，含 `AdjustmentServiceSubmitTest` 86、`TransactionalRemoteCallArchTest` 2、`SettlementLockContractTest` 5。
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#8225](https://git.1814.love/wx/HL/issues/8225)
+- 关联 PR: [wx/HL#8255](https://git.1814.love/wx/HL/pulls/8255)
+- 上游来源：#8202（CR 带出本单）
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8225](https://git.1814.love/wx/HL/issues/8225)
+- **PR**: [#8255](https://git.1814.love/wx/HL/pulls/8255)
+- **Merge commit**: [c2b261cd2](https://git.1814.love/wx/HL/commit/c2b261cd2)
+
+### 联系人
+
+- **后端负责人**: @jw
+- **前端负责人**: @mmg
@@ -0,0 +1,348 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8226"
+title: "车型大类中文名空白校验收紧（全角空格等 Unicode 空白改为拒绝）+ 空名大类不再被挤出车型字典白名单"
+consumer: "admin"
+author: "jw(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "9e0897c2934a6720fb9cbab05b1e14394c74c8f6"
+target_release: ""
+verified_at: "2026-09-23"
+status_note: "PR #8232 已合并 dev-v3（9231b8d8c），2026-09-23 14:30 滚动部署 TEST 双实例（检出 7a876ec57）。真实网关实测：新增/编辑车型大类 typeName 传全角空格、半角空格、空串、null 均返回 400「大类中文名不能为空」，库内零写入；读侧临时把 mpv 名称置空后，order-v3 车型白名单仍含 mpv（展示名回落为 mpv），验毕已原样还原。前端待办：车型大类表单的 typeName 必填校验需同样把全角空格视为空。前端已交付(2026-09-23):CategoryEditModal typeName 必填规则改 trim() 判空 validator,纯全角/半角空白提交前拦下(与后端 400 同口径),首尾带空格正常名放行且提交不 trim 原样发;新建组件 spec 4 例全绿。"
+updated_at: "2026-09-23"
+base: "dev-v3"
+---
+
+# 车队车型管理: 车型大类中文名空白校验收紧 + 空名大类不再被挤出字典白名单
+
+> **存放目录**: 二期(v3) → `changelogs-v2/2026-09/`
+>
+> **服务**: hl-fleet-service
+> **PR**: #8232
+> **Issue**: #8226
+> **日期**: 2026-09-23
+> **影响范围**: 管理后台「车型管理」新增/编辑车型大类表单的 typeName 校验；order-v3 用车需求车型字典白名单（582032）的数据源
+
+---
+
+## ⚠️ 关键变化（非必须,本版与上版行为不同 / 纠错 / 撤销时必写）
+
+- 本次变化：新增/编辑车型大类时，`typeName` 如果全部由**全角空格（U+3000）等 Unicode 空白**组成，现在返回 `400「大类中文名不能为空」`。
+- 前端以前以为的：`typeName` 只要不是空串、不全是半角空格，后端就会接受。
+- 实际新行为：以前后端用 `@NotBlank` 校验，它按 `String.trim()` 判空，只去掉半角空白，所以全角空格能写进库。可车队给 order-v3 的车型白名单按 `isBlank()` 判空名，会把这种名字当成空的、把整个大类从白名单里丢掉，结果这个大类下的用车需求被 `582032「不存在或已下线」` 误拒。现在两处同时收口：写侧拒绝这种名字；读侧即使库里出现空名，也不再把该大类挤出白名单。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 新增车型大类 | POST | `/admin/fleet/vehicle-types` | 入参校验收紧 | `typeName` 全为 Unicode 空白（含全角空格）改为 400 |
+| 2 | 编辑车型大类 | PUT | `/admin/fleet/vehicle-types/{typeId}` | 入参校验收紧 | 同上 |
+
+---
+
+## 三、接口详情
+
+### 1. 新增车型大类 `POST /admin/fleet/vehicle-types`
+
+**VO**: `VehicleTypeSaveReqVO → VehicleTypeRespVO`
+
+#### 使用场景
+
+管理后台「车队 → 车型管理」新增一个车型大类（如 SUV系列 / 商务车）时调用。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| Authorization | Header | String | ✅ | - | 管理端登录令牌 |
+| typeKey | Body | String | ✅ | 非空白，≤16，全局唯一（600101） | 大类标识 key，如 `suv` |
+| typeName | Body | String | ✅ | **至少含一个非空白字符（空白按 Unicode 判定，全角空格也算空白，本次收紧）**，≤64 | 大类中文名 |
+| icon | Body | String | ❌ | ≤64 | 图标组件名或 emoji |
+| description | Body | String | ❌ | ≤256 | 大类描述 |
+| sortOrder | Body | Integer | ✅ | 非 null | 排序权重，升序 |
+
+#### 出参 `Result<VehicleTypeRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | Long | 大类 ID |
+| typeKey | String | 大类 key |
+| typeName | String | 大类中文名 |
+| icon | String | 图标 |
+| description | String | 描述 |
+| sortOrder | Integer | 排序权重 |
+| seatOptions | Array\<Integer\> | 座位数选项，新建恒为 `[]` |
+| modelCount | Integer | 型号数，新建恒为 0 |
+| inUseCount | Integer | 在役车辆数，新建恒为 0 |
+
+#### 请求示例
+
+```json
+{
+  "typeKey": "mpv",
+  "typeName": "商务车",
+  "icon": "",
+  "description": "",
+  "sortOrder": 2
+}
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "id": "2064609312168083458",
+    "typeKey": "mpv",
+    "typeName": "商务车",
+    "icon": "",
+    "description": "",
+    "sortOrder": 2,
+    "seatOptions": [],
+    "modelCount": 0,
+    "inUseCount": 0
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+写接口没有空数据场景，也没有降级分支；校验不通过时零写入。
+
+```json
+{ "code": 400, "message": "大类中文名不能为空", "data": null, "success": false }
+```
+
+#### 错误响应
+
+`typeName` 为 null、空串、纯半角空格、纯全角空格，一律返回同一条错误，且只报一条：
+
+```json
+{ "code": 400, "message": "大类中文名不能为空", "data": null, "traceId": null, "success": false }
+```
+
+```json
+{ "code": 600101, "message": "车型大类标识已存在", "data": null, "success": false }
+```
+
+#### 业务边界
+
+- 鉴权：未登录 → 业务码 `401`（「缺少有效的 Authorization 头」）。
+- 只拒绝**全部**由空白组成的名字；首尾带空格的正常名（如 `" 商务车 "`）照常放行，后端不做 trim。
+- 以前只有全角空格这一类会被放行，现在也拒绝；null、空串、半角空格在改前就被拒，行为不变。
+
+---
+
+### 2. 编辑车型大类 `PUT /admin/fleet/vehicle-types/{typeId}`
+
+**VO**: `VehicleTypeSaveReqVO → VehicleTypeRespVO`
+
+#### 使用场景
+
+管理后台「车型管理」编辑已有大类的名称、图标、描述或排序。`typeKey` 不可改，后端忽略入参中的 `typeKey`。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| Authorization | Header | String | ✅ | - | 管理端登录令牌 |
+| typeId | Path | Long | ✅ | 大类须存在（600102） | 大类 ID |
+| typeName | Body | String | ✅ | **至少含一个非空白字符（空白按 Unicode 判定，全角空格也算空白，本次收紧）**，≤64 | 大类中文名 |
+| icon | Body | String | ❌ | ≤64；不传则不改 | 图标 |
+| description | Body | String | ❌ | ≤256；不传则不改 | 描述 |
+| sortOrder | Body | Integer | ✅ | 非 null | 排序权重 |
+
+#### 出参 `Result<VehicleTypeRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | Long | 大类 ID |
+| typeKey | String | 大类 key（不可改） |
+| typeName | String | 大类中文名 |
+| icon | String | 图标 |
+| description | String | 描述 |
+| sortOrder | Integer | 排序权重 |
+| seatOptions | Array\<Integer\> | 该大类下型号座位数选项，去重升序 |
+| modelCount | Integer | 型号数 |
+| inUseCount | Integer | 在役车辆数 |
+
+#### 请求示例
+
+```json
+{
+  "typeName": "商务车",
+  "icon": "",
+  "description": "",
+  "sortOrder": 2
+}
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "id": "2064609312168083458",
+    "typeKey": "mpv",
+    "typeName": "商务车",
+    "sortOrder": 2,
+    "seatOptions": [7],
+    "modelCount": 1,
+    "inUseCount": 0
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+写接口没有空数据场景，也没有降级分支；校验不通过时零写入，`update_time` 也不变。
+
+```json
+{ "code": 400, "message": "大类中文名不能为空", "data": null, "success": false }
+```
+
+#### 错误响应
+
+```json
+{ "code": 400, "message": "大类中文名不能为空", "data": null, "traceId": null, "success": false }
+```
+
+```json
+{ "code": 600102, "message": "车型大类不存在", "data": null, "success": false }
+```
+
+#### 业务边界
+
+- 鉴权：未登录 → 业务码 `401`。
+- 参数校验先于「大类是否存在」：`typeName` 为空白时，即使 `typeId` 不存在也返回 400，而不是 600102。
+- 编辑时把名字清空是被拒绝的操作，不会把一个在营大类变成空名大类。
+
+---
+
+## 四、契约约束与正确调用方式（接口类必写）
+
+> 本节只写**后端接受/拒绝 payload 的规则**，不写 UI 渲染建议。
+
+### ✅ 正确 / ❌ 错误 payload 对照
+
+| 场景 | payload | 结果 |
+|------|---------|------|
+| ✅ 正常中文名 | `typeName: "商务车"` | 通过 |
+| ✅ 首尾带空格 | `typeName: " 商务车 "` | 通过，原样落库 |
+| ❌ 纯全角空格 | `typeName: "　　"` | 400（**本次新增拒绝**） |
+| ❌ 纯半角空格 / 空串 / null | `typeName: "   "` / `""` / 不传 | 400（改前已拒） |
+
+- 前端表单的必填校验应与后端一致，按「去掉**全部 Unicode 空白**后是否为空」判定。JS 的 `String.prototype.trim()` 会去掉全角空格（U+3000），可以直接用 `value.trim() === ''` 判空。
+
+---
+
+## 五、数据库行为（涉及写操作时必写）
+
+- 无 Flyway migration、无 DDL、无表结构变更。`fleet_vehicle_type.type_name` 原本就是 `VARCHAR(64) NOT NULL`。
+- 校验失败的请求零写入：TEST 实测 4 次 POST、2 次 PUT 被拒后，`fleet_vehicle_type` 全表逐字段（含 `update_time`）与请求前一致，也没有生成测试 key 的行。
+- 存量处理成本为 0：TEST 上在架大类 4 行，`type_name` 都非空白。
+
+---
+
+## 六、边界行为
+
+- 未登录 → 业务码 `401`。
+- `typeName` 只要含一个非空白字符就放行；是否是「像中文的名字」后端不判断。
+- 读侧兜底（内部接口，前端不直接调用，写在这里方便排查 582032）：如果库里仍出现空名大类（例如被直接改库），车队给 order-v3 的车型白名单（`GET /internal/fleet/vehicle-types/category-names`）**照样包含这个大类**，只是展示名回落为规范 key（如 `mpv`），同时车队服务打一条 WARN「车型大类名称为空，展示名回落到规范 key」。改前这个大类会从白名单里整个消失，导致用车需求报 `582032「车型 mpv 不在车型字典内（不存在或已下线）」`，而座位数校验照常通过。
+- 同一规范 key 下有多行时，展示名取排序最前、且名称非空白的那一行。
+
+---
+
+## 六.6、修改前后对比（修改/删除类接口必写，新增跳过）
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 |
+|------|------|------|
+| `typeName` 校验 | `@NotBlank`：按 `trim()` 判空，全角空格放行 | `@NotNull` + Unicode 空白判定：全角空格等一律拒 |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| 新增/编辑时 `typeName` 传全角空格 | 200，落库 | 400「大类中文名不能为空」，零写入 |
+| `typeName` 传 null / 空串 / 半角空格 | 400 | 400（同一条文案，只报一条） |
+| 库里存在空名在营大类时，order-v3 提交该大类的用车需求 | 582032 误拒（座位校验却通过） | 正常通过字典校验 |
+
+---
+
+## 六.7、影响评估（修改/删除类必写）
+
+- **是否破坏向后兼容**：只收紧了一种此前被接受的取值（`typeName` 全为全角空格等 Unicode 空白），这种名字本来就没有业务意义；请求/响应结构不变。
+- **前端是否必须同步上线**：否。前端不改的话，用户输入全角空格会在提交后收到后端 400 文案，不会写坏数据。建议前端表单必填校验同步用 `trim()` 判空，在提交前就提示。
+- **前端 workaround 清理点**：无。
+
+---
+
+## 七、不影响范围（显式声明, 帮前端/QA 缩小排查面）
+
+- **仅影响**：新增/编辑车型大类的 `typeName` 校验；内部接口 `category-names` 对空名大类的取舍。
+- **零影响**：
+  - `typeKey`、`icon`、`description`、`sortOrder` 的校验规则。
+  - `GET /admin/fleet/vehicle-types`（树）、`/page`、`/list` 的响应结构与内容。
+  - 车型型号（`/admin/fleet/vehicle-types/{typeId}/models` 等）相关接口。
+  - order-v3 的 582032 / 582033 错误码与文案本身；名称正常的大类在白名单里的名称与顺序不变（TEST 实测 4 个在架大类改前改后一致）。
+  - 座位数选项接口 `seat-options` 的行为（本来就不看名称）。
+
+---
+
+## 八、测试环境已验证
+
+部署：PR #8232 合并 `dev-v3`（`9231b8d8c`），2026-09-23 14:30 滚动部署 TEST 双实例（检出 `7a876ec57`，含本单）。
+
+构建身份（零写入判据）：直连 8087 / 8187 两个实例，`PUT /admin/fleet/vehicle-types/999999999`（不存在的 id）：`typeName` 传全角空格返回 400（旧代码会放行到 600102）；同一 id 传正常名返回 600102（阴性对照）。
+
+真实网关（`https://api.test.1814.love`，管理端 token）：
+
+```
+POST /admin/fleet/vehicle-types  无 token            → 401 缺少有效的 Authorization 头 ✓
+POST /admin/fleet/vehicle-types  typeName="　　"      → 400 大类中文名不能为空 ✓
+POST /admin/fleet/vehicle-types  typeName="   "      → 400 大类中文名不能为空 ✓
+POST /admin/fleet/vehicle-types  typeName=""         → 400 大类中文名不能为空 ✓
+POST /admin/fleet/vehicle-types  typeName=null       → 400 大类中文名不能为空 ✓
+PUT  /admin/fleet/vehicle-types/{suv2 的 id}  typeName="　"  → 400 ✓
+PUT  /admin/fleet/vehicle-types/{suv2 的 id}  typeName=""    → 400 ✓
+fleet_vehicle_type 全表前后逐字段一致（含 update_time）✓
+```
+
+读侧（内部接口，两个实例）：把 `mpv` 的 `type_name` 临时依次改为空串、半角空格、全角空格，`category-names` 均返回 `mpv → "mpv"`，其余 3 个大类名称与顺序不变，`seat-options?vehicleType=mpv` 仍返回 `[7]`；验毕 `type_name` 与 `update_time` 均恢复原值（逐字段一致）。
+
+单元测试：`VehicleTypeServiceTest` 28、`VehicleTypeSaveReqVOValidationTest` 5、`VehicleTypeControllerTest` 17、`VehicleTypeControllerIdempotentTest` 6、`FleetRedLineArchTest` 18，共 74 例 0 失败。
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#8226](https://git.1814.love/wx/HL/issues/8226)
+- 关联 PR: [wx/HL#8232](https://git.1814.love/wx/HL/pulls/8232)
+- 上游来源：#8202（子订单行程用车车型大类接入车队字典校验，582032）
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8226](https://git.1814.love/wx/HL/issues/8226)
+- **PR**: [#8232](https://git.1814.love/wx/HL/pulls/8232)
+- **Merge commit**: [9231b8d8c](https://git.1814.love/wx/HL/commit/9231b8d8c)
+
+### 联系人
+
+- **后端负责人**: @jw
+- **前端负责人**: @mmg
@@ -0,0 +1,93 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8228"
+title: "HOLD 派单降级车务站内信补齐跳转链接，指向车务看板"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修复"
+backend_status: "deployed"
+gateway_status: "not_required"
+frontend_status: "not_required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "接口路径、请求参数、响应字段均未变，变的是 admin_message 表里这一类消息 link 字段的取值。事件识别特征为 event_code=FLEET_DISPATCH_CREATED、biz_type=FLEET_ASSIGNMENT_HOLD、category_code=SYSTEM，触发条件是 fleet 派单进 HOLD 且给司机的短信通道返回 SKIP_NO_TEMPLATE（HOLD 占位无行程短链 code，或短信模板未配置），这条降级分支不看该事件的 inapp_enabled 开关。user-service 用 Flyway V20260923_001 给该事件补上链接模板 /fleet/board?orderId=${orderId}，fleet 发出的 HOLD 通知在能确定唯一订单时于 extras 里带 orderId。PR #8299 已合并（3227d495c），user-service 与 fleet 均已部署测试服，测试服实测该事件配置已是该模板。backend_status=deployed。gateway_status=not_required，无新增路由，消息仍走既有列表接口读取。frontend_status=not_required，前端零改动，link 走既有 resolveJumpLink 逻辑；车务看板当前不读取 orderId 这个 query，两种取值均落在看板首页；存量消息不回填，link 仍为空。；前端复核(mmg):resolveJumpLink 空值砍 query/原样跳转两态安全,fleet/board 目录 route.query 零命中,FLEET_ASSIGNMENT_HOLD 前端零分支——与后端 not_required 评估双向印证"
+updated_at: "2026-09-23"
+base: "dev-v3"
+---
+
+# 车务通知: HOLD 派单降级车务站内信补齐跳转链接
+
+> **存放目录**: 二期（order-v3）→ `changelogs-v2/2026-09/`
+>
+> **服务**: hl-user-service（通知配置）+ hl-fleet-service（消息 extras）
+> **PR**: [#8299](https://git.1814.love:8443/wx/HL/pulls/8299)
+> **Issue**: [#8228](https://git.1814.love:8443/wx/HL/issues/8228)
+> **日期**: 2026-09-23
+> **影响范围**: 站内信列表中 `event_code=FLEET_DISPATCH_CREATED` 且 `biz_type=FLEET_ASSIGNMENT_HOLD` 的记录的 `link` 字段取值；读取这些消息的接口本身未变
+
+---
+
+## ⚠️ 关键变化
+
+**这一类“HOLD 派单降级车务”站内信的 `link` 字段现在有值了。** 消息的识别特征、触发条件都没变；变的只是这一类消息的跳转地址：本次上线之前发出的消息 `link` 为空，之后新产生的按下文规则带跳转链接。
+
+---
+
+## 一、触发条件与消息识别（未变）
+
+fleet 派单进入 HOLD 状态、给司机的短信通道返回 `SKIP_NO_TEMPLATE`（HOLD 占位没有行程短链 code，或短信模板未配置）时，通知中心按既有规则降级为给车务角色（`VEHICLE_MANAGER`）的后台管理员发一条站内信。这条消息在 `admin_message` 表里的识别特征：
+
+- `event_code = FLEET_DISPATCH_CREATED`
+- `biz_type = FLEET_ASSIGNMENT_HOLD`
+- `category_code = SYSTEM`
+
+以上触发条件和识别特征本次**都没有变**。这条降级分支也**不看**该事件的 `inapp_enabled` 开关——测试服上这个开关当前是 0，降级站内信照样会发，不受它影响。
+
+---
+
+## 二、`link` 取值规则（本次新增）
+
+| 场景 | `link` 取值 |
+|---|---|
+| fleet 能确定唯一订单 | `/fleet/board?orderId=<订单ID>` |
+| fleet 确定不了唯一订单（同一派车组的行跨了两张订单，或行上缺订单 ID） | `/fleet/board?orderId=`（query 值为空，不会报错） |
+
+实现方式：user-service 用 Flyway `V20260923_001` 给该事件的通知配置补上链接模板 `/fleet/board?orderId=${orderId}`；fleet 发出的 HOLD 通知在能确定唯一订单时于 extras 里带上 `orderId`，通知中心降级为站内信时用它渲染出最终链接。
+
+---
+
+## 三、边界
+
+1. **存量消息不回填**：本次只改配置和消息生成逻辑，不动已经发出的历史消息。测试服上 2026-08-05 至 2026-08-08 期间发出的 234 条这类站内信 `link` 仍为空，前端 `resolveJumpLink` 对空 link 返回 `null`，这些消息依旧没有跳转入口；只有之后新产生的才带链接。
+2. **车务看板当前不读取 `orderId` 这个 query**：`hl-ui`（`origin/v2.1` @ `31a198613`）的车务看板 `src/views/fleet/board/**` 目前不读取 `route.query`（对该目录 86 个文件检索 `route.query` / `useRoute` / `$route` 均为 0 命中；同一检索在兄弟目录 `src/views/fleet/matrix/` 有命中，检索本身有效）。带 `orderId` 与不带 `orderId` 的两种链接点开后都落在看板首页，不会按订单定位。
+3. **`link` 走既有跳转逻辑，前端无需新增处理**：`link` 是后台相对路由，前端现有的 `resolveJumpLink`（`src/views/notification/MyMessages/jumpBiz.js:22-32`）直接把它交给 `router.push`；`kv.endsWith('=')` 时会把整段 query 砍掉（`:27-31`），所以 `/fleet/board?orderId=` 实际会跳到 `/fleet/board`，`/fleet/board?orderId=123` 原样跳转，两种情形都不会报错。
+4. **生产环境没有这类消息**：二期（order-v3、fleet）尚未上生产，本次改动目前只在测试服可见。
+
+---
+
+## 四、测试环境已验证
+
+- PR [#8299](https://git.1814.love:8443/wx/HL/pulls/8299)，合并提交 [`3227d495c`](https://git.1814.love:8443/wx/HL/commit/3227d495c)，user-service、fleet 均已部署到测试服。
+- 测试服上 `notification_event_config` 中 `event_code=FLEET_DISPATCH_CREATED` 那一行的 `inapp_link_template` 实测已是 `/fleet/board?orderId=${orderId}`。
+
+---
+
+## 五、可选增强（非必须，供参考）
+
+如果车务看板以后想按订单定位，query 参数名已经固定是 `orderId`，值是订单 ID 字符串，直接读取即可，不需要另外跟后端约定参数名。这是可选增强，不是必须动作。
+
+---
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8228](https://git.1814.love:8443/wx/HL/issues/8228)
+- **PR**: [#8299](https://git.1814.love:8443/wx/HL/pulls/8299)
+- **Merge commit**: [`3227d495c`](https://git.1814.love:8443/wx/HL/commit/3227d495c)
+
+### 联系人
+
+- **后端负责人**: @wx
@@ -0,0 +1,507 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8230"
+title: "团期订单支持用餐：生成、保存、重置、查询、套用模版可只传团期ID"
+consumer: "admin"
+author: "lc(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "04e08d1a9ddb8ee26f5313fb7a08e3c020225475"
+target_release: "v2.1"
+verified_at: "2026-09-24"
+status_note: "已部署 TEST 并经 Gateway 实测通过。用餐的查询、生成、保存、重置、套用模版 5 个接口加入团期维度：orderId 与 groupBatchId 必须且只能传一个，都传或都不传返回 400。只传 groupBatchId 时读写的是团期自己的用餐行（行上团期ID有值、订单ID为空）；按订单读写的行此后团期ID为空，按团期查不到子订单的行。团期的出发/返回日期取团期出团日期 depart_date / 结束日期 end_date。前端结论(2026-09-23):现有子订单用餐页(MealTab)5 个调用点全只传 orderId,查询恒有 orderId 空值守卫,零 batchNo/groupBatchId 读写、零 589601 分支——「挂团订单保存勿再带 groupBatchId」「只传 batchNo 400」等破坏点前端零命中,基本行为零改动。团期维度用餐属新增能力,前端无团期用餐页面,建页为新产品需求待拍板,非本次同步范围。；前端纠正(2026-09-24):09-23 误把团期维度建页判出范围,用户指出后立项——团期详情新增「用餐」Tab(行程后,show:lazy),复用 MealTab 新增 groupBatchId prop 二选一 scope;mealInfo API 4 函数改 scope 对象+normalizeMealScope 前端断言;破坏点维持零命中;spec MealTab 30+mealInfo 5+batch 357+detail 389 全绿,checkpoint 13 项过"
+updated_at: "2026-09-23"
+base: "dev-v3"
+---
+
+# order-v3: 团期订单支持用餐，5 个用餐接口可只传团期ID
+
+> **服务**: hl-order-service-v3
+> **PR**: #8251
+> **Issue**: #8230
+> **日期**: 2026-09-23
+> **影响范围**: 管理后台用餐信息的查询、生成、保存、重置与套用模版（订单、团期两种维度）
+
+---
+
+## ⚠️ 关键变化
+
+- 🔁 **二选一（破坏性）**：查询、生成、保存、重置、套用模版这 5 个接口，`orderId` 与 `groupBatchId` **必须且只能传一个**。都传返回 `400`「订单ID和团期ID只能传一个」；都不传返回 `400`「订单ID和团期ID必须传一个」。查询接口的 `batchNo` 不算数，**只传 `batchNo` 视为两个都没传**，同样 400。
+- 🔁 **订单行不再带团期**：按订单生成、保存、重置、套用出来的行，行上 `groupBatchId`、`batchNo` 一律为空。以前挂团订单的行会顺带写团期ID / 团期编号，现在不写。
+- 🔁 **保存不再用 `orderId` + `groupBatchId` 一起传**：以前保存时可以同时传两者并校验订单是否属于该团期（589601），现在同时传直接 400，589601 不再出现。
+- 🆕 **团期维度**：只传 `groupBatchId` 时读写的是**团期自己的用餐行**，行上 `groupBatchId` 有值、`orderId` 为空；按团期查询**只返回团期自己的行，不含团里子订单的行**。
+- ℹ️ **3.1 用 `orderId` + `batchNo` 组合此后查不到数据**：订单行上已不存团期编号，这个组合固定返回空列表。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|---|---|---|---|---|
+| 1 | 查询用餐信息列表（3.1） | GET | `/v3/admin/order/meal-info/list` | 修改 | `orderId` / `groupBatchId` 二选一；只传团期ID只返回团期自己的行，顶层汇总按团期填 |
+| 2 | 生成用餐信息（3.2） | POST | `/v3/admin/order/meal-info/generate` | 修改 | 新增 `groupBatchId`，二选一；团期按团期产品当前行程生成 |
+| 3 | 保存用餐信息（整单，3.3） | POST | `/v3/admin/order/meal-info/save` | 修改 | `orderId` 不再必填，二选一；只传团期ID保存团期行 |
+| 4 | 重置用餐信息（3.4） | POST | `/v3/admin/order/meal-info/reset` | 修改 | 新增 `groupBatchId`，二选一；团期删掉自己的行后重新生成 |
+| 5 | 套用用餐模版（4.3） | POST | `/v3/admin/order/meal-template/apply` | 修改 | 新增 `groupBatchId`，二选一；同一个模版可套到团期 |
+
+出参字段一个都没增减。模版查询、存为模版、删除模版不变（模版不分订单、团期）。没有新增错误码。
+
+---
+
+## 三、接口详情
+
+### 1. 查询用餐信息列表 `GET /v3/admin/order/meal-info/list`
+
+**VO**: `OrderMealInfoListReqVO` → `OrderMealInfoListRespVO`
+
+#### 使用场景
+
+按订单或按团期取用餐行及顶层汇总。两种维度用同一个接口，由传 `orderId` 还是 `groupBatchId` 区分。
+
+#### 入参字段表
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| orderId | Query | String | 二选一 | 正数 | 按订单查。**与 `groupBatchId` 必须且只能传一个** |
+| groupBatchId | Query | String | 二选一 | 正数 | 按团期查，只返回团期自己的行 |
+| batchNo | Query | String | 否 | — | 不参与二选一；只传它按都没传处理（400）；与 `orderId` 组合固定查不到数据 |
+| 其余筛选 | Query | — | 否 | — | `mealType`、`mealDateStart/End`、`dayNumber`、`settleType`、`keyword`、`limit` 不变 |
+
+#### 出参字段表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| orderId | String | 按订单查为订单ID；按团期查为 `null` |
+| groupBatchId / batchNo | String | 按订单查：**仍回显订单所属团期**（不挂团为 `null`）；按团期查：该团期 |
+| departDate / returnDate | String | 按订单查：订单出发/返回日期；按团期查：团期出团日期 `depart_date` / 结束日期 `end_date` |
+| personCount | Integer | 按订单查：订单人数；按团期查：团期报名人数 |
+| orderEditable | Boolean | 按团期查恒为 `true` |
+| generated | Boolean | 按团期查：该团期有没有自己的行 |
+| items[].orderId / items[].groupBatchId | String | 订单行：`orderId` 有值、`groupBatchId` 为 `null`；团期行：`groupBatchId` 有值、`orderId` 为 `null` |
+| items[].batchNo | String | 新写入的行一律为 `null` |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/meal-info/list?groupBatchId=2101996448340238338
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "success": true,
+  "data": {
+    "orderId": null,
+    "groupBatchId": "2101996448340238338",
+    "batchNo": "Q202611042099750379129368577",
+    "departDate": "2026-11-04",
+    "returnDate": "2026-11-08",
+    "personCount": 4,
+    "orderEditable": true,
+    "generated": true,
+    "totalAmount": 0.00,
+    "items": [
+      { "mealInfoId": "…", "orderId": null, "groupBatchId": "2101996448340238338", "batchNo": null,
+        "mealType": "LUNCH", "mealDate": "2026-11-04", "dayNumber": 1, "amount": 0.00 }
+    ]
+  }
+}
+```
+
+按订单查（订单挂在该团期下）时顶层 `groupBatchId` 仍是 `"2101996448340238338"`，但 `items[].groupBatchId` 为 `null`。
+
+#### 空数据 / 降级响应
+
+- 团期还没有自己的行：`items: []`、`generated: false`，顶层汇总照常填。
+- 团期里子订单有用餐行、团期自己没有：按团期查仍是 `items: []`。
+- `orderId` + `batchNo`：`items: []`。
+
+#### 错误响应
+
+```json
+{ "code": 400, "message": "订单ID和团期ID只能传一个", "success": false, "data": null }
+```
+
+都不传（含只传 `batchNo`）：`400`「订单ID和团期ID必须传一个」。按团期查没有团期查看权限：`589507`。订单维度的错误码不变。
+
+#### 业务边界
+
+- 二选一在入参校验阶段判断，先于任何权限、存在性判断。
+- 按团期查只按团期ID取行，不含团里子订单的行；按订单查只返回该订单的行。
+- 顶层 `groupBatchId` 是订单汇总回显，不代表行上存了团期ID。
+
+### 2. 生成用餐信息 `POST /v3/admin/order/meal-info/generate`
+
+**VO**: `OrderMealInfoGenerateReqVO` → `OrderMealInfoListRespVO`
+
+#### 使用场景
+
+订单或团期还没有用餐行时，按产品行程生成空行。团期传 `groupBatchId`。
+
+#### 入参字段表
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| orderId | Body | String | 二选一 | 正数 | 按订单产品快照生成（不变） |
+| groupBatchId | Body | String | 二选一 | 正数 | **新增**。按团期产品当前行程生成团期行 |
+
+#### 出参字段表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| 全部字段 | — | 与查询接口同维度的返回一致（团期维度见接口 1） |
+| items[].dayNumber | Integer | 团期：第 d 天用餐日期 = `depart_date` + d − 1，天数到 `end_date` |
+
+#### 请求示例
+
+```json
+{ "groupBatchId": "2101996448340238338" }
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "success": true,
+  "data": {
+    "orderId": null, "groupBatchId": "2101996448340238338",
+    "departDate": "2026-11-04", "returnDate": "2026-11-08", "personCount": 4, "generated": true,
+    "items": [
+      { "orderId": null, "groupBatchId": "2101996448340238338", "mealType": "LUNCH", "mealDate": "2026-11-04", "dayNumber": 1, "amount": 0.00 },
+      { "orderId": null, "groupBatchId": "2101996448340238338", "mealType": "DINNER", "mealDate": "2026-11-04", "dayNumber": 1, "amount": 0.00 }
+    ]
+  }
+}
+```
+
+#### 空数据 / 降级响应
+
+- 团期已有自己的行：不再生成，直接返回现有行（幂等）。
+- 团期 `depart_date` 或 `end_date` 为空：不生成，`code` 200，`message` 带 589602 文案。
+- 行程里含（酒店）/ 自理的餐、行程没有的天不生成；团期产品取不到行程时生成 0 行。
+
+#### 错误响应
+
+```json
+{ "code": 400, "message": "订单ID和团期ID必须传一个", "success": false, "data": null }
+```
+
+都传：`400`「订单ID和团期ID只能传一个」。团期：无团期管理权限 `589507`、团期不存在 `589500`、`end_date` 早于 `depart_date` `589612`。
+
+#### 业务边界
+
+- 团期生成的每天每餐取团期产品**当前**行程，不是某张子订单下单时的快照。
+- 团期不按团期状态拦截。
+- 按订单生成的行 `groupBatchId` 为空。
+
+### 3. 保存用餐信息（整单） `POST /v3/admin/order/meal-info/save`
+
+**VO**: `OrderMealInfoBatchSaveReqVO` → `OrderMealInfoListRespVO`
+
+#### 使用场景
+
+一次提交某张订单或某个团期保存后应有的全部行：带行ID覆盖、不带新增、原来有而这次没传的软删。团期**只传 `groupBatchId`**，不要同时传 `orderId`。
+
+#### 入参字段表
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| orderId | Body | String | 二选一 | 正数 | **不再必填**。按订单保存 |
+| groupBatchId | Body | String | 二选一 | 正数 | **含义变化**：以前是「订单所属团期一致校验」，现在只传它表示按团期保存 |
+| items[] | Body | Array | 是 | — | 保存后应有的全部行，字段不变；空数组表示一行都不留 |
+
+#### 出参字段表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| 全部字段 | — | 与查询接口同维度的返回一致 |
+| items[].dayNumber | Integer | 团期行 = 用餐日期 − `depart_date` + 1；`depart_date` 为空时为 `null` |
+
+#### 请求示例
+
+```json
+{
+  "groupBatchId": "2101996448340238338",
+  "items": [
+    { "mealType": "LUNCH", "mealDate": "2026-11-05", "restaurantName": "…", "dishName": "…",
+      "unitPrice": 45.00, "tableCount": 0, "personCount": 4, "freePersonCount": 0,
+      "freeAmount": 0, "otherCost": 0, "amount": 180.00, "settleType": "sign", "settleTypeName": "签单" }
+  ]
+}
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "success": true,
+  "data": {
+    "orderId": null, "groupBatchId": "2101996448340238338", "departDate": "2026-11-04",
+    "totalAmount": 180.00,
+    "items": [
+      { "mealInfoId": "…", "orderId": null, "groupBatchId": "2101996448340238338", "batchNo": null,
+        "mealType": "LUNCH", "mealDate": "2026-11-05", "dayNumber": 2, "amount": 180.00 }
+    ]
+  }
+}
+```
+
+#### 空数据 / 降级响应
+
+- 团期传 `items: []`：该团期自己的行全部软删，返回 `items: []`，不影响子订单的行。
+
+#### 错误响应
+
+```json
+{ "code": 400, "message": "订单ID和团期ID只能传一个", "success": false, "data": null }
+```
+
+都不传：`400`「订单ID和团期ID必须传一个」。团期：无团期管理权限 `589507`、团期不存在 `589500`、带的行ID不是本团期自己的行 `589611`、行查不到或已删 `589606`、金额对不上 `589613`。`589601` 不再返回。
+
+#### 业务边界
+
+- 团期保存只动团期自己的行，软删范围也只在团期自己的行里。
+- 按订单保存新增的行 `groupBatchId` 为空。
+- 任一行校验失败整批不写。
+
+### 4. 重置用餐信息 `POST /v3/admin/order/meal-info/reset`
+
+**VO**: `OrderMealInfoResetReqVO` → `OrderMealInfoListRespVO`
+
+#### 使用场景
+
+删掉某张订单或某个团期自己的全部行，再按生成规则重新生成空行。团期传 `groupBatchId`。
+
+#### 入参字段表
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| orderId | Body | String | 二选一 | 正数 | 按订单重置（不变） |
+| groupBatchId | Body | String | 二选一 | 正数 | **新增**。按团期重置 |
+
+#### 出参字段表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| 全部字段 | — | 与接口 2 生成的返回一致 |
+
+#### 请求示例
+
+```json
+{ "groupBatchId": "2101996448340238338" }
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "success": true,
+  "data": {
+    "orderId": null, "groupBatchId": "2101996448340238338", "generated": true,
+    "items": [
+      { "mealInfoId": "…（新行ID）", "orderId": null, "groupBatchId": "2101996448340238338", "mealType": "LUNCH", "mealDate": "2026-11-04", "dayNumber": 1, "amount": 0.00 }
+    ]
+  }
+}
+```
+
+#### 空数据 / 降级响应
+
+- 团期 `depart_date` 或 `end_date` 为空：原有团期行照样删掉、不生成，`code` 200，`message` 带 589602 文案。
+
+#### 错误响应
+
+```json
+{ "code": 589612, "message": "返回日期早于出发日期，无法生成用餐信息", "success": false, "data": null }
+```
+
+`end_date` 早于 `depart_date` 时原有行不删。二选一 400、`589507`、`589500` 同接口 2。
+
+#### 业务边界
+
+- 团期重置只删团期自己的行，子订单的行不动；删和生成一起成功或一起失败。
+- 重置后行ID全部换新。
+
+### 5. 套用用餐模版 `POST /v3/admin/order/meal-template/apply`
+
+**VO**: `MealTemplateApplyReqVO` → `OrderMealInfoListRespVO`
+
+#### 使用场景
+
+把一个模版按出发日铺开，接在现有行后面返回（只读，不写库），确认后再用接口 3 保存。模版不分订单、团期，同一个模版两边都能套。套到团期传 `groupBatchId`。
+
+#### 入参字段表
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| orderId | Body | String | 二选一 | 正数 | **不再必填**。套到订单 |
+| groupBatchId | Body | String | 二选一 | 正数 | **新增**。套到团期 |
+| templateId | Body | String | 是 | — | 模版ID（不变） |
+
+#### 出参字段表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| items[] | Array | 前段是现有行（团期：团期自己的行），后段是模版行（`mealInfoId` 为 `null`） |
+| items[].mealDate | String | 团期：模版第 d 日 = `depart_date` + d − 1 |
+| items[].personCount | Integer | 团期按人的模版行 = 团期报名人数；按桌为 0 |
+| items[].orderId / groupBatchId | String | 套到团期：模版行 `groupBatchId` 有值、`orderId` 为 `null`；套到订单：模版行 `groupBatchId` 为 `null` |
+| 其余字段 | — | 与 #8125 相同 |
+
+#### 请求示例
+
+```json
+{ "groupBatchId": "2101996448340238338", "templateId": "2102035945748684802" }
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "success": true,
+  "data": {
+    "orderId": null, "groupBatchId": "2101996448340238338", "departDate": "2026-11-04", "personCount": 4,
+    "items": [
+      { "mealInfoId": "…", "orderId": null, "groupBatchId": "2101996448340238338", "mealType": "LUNCH", "mealDate": "2026-11-05", "dayNumber": 2 },
+      { "mealInfoId": null, "orderId": null, "groupBatchId": "2101996448340238338", "mealType": "DINNER", "mealDate": "2026-11-06", "dayNumber": 3, "personCount": 4, "priceUnit": "person" }
+    ]
+  }
+}
+```
+
+#### 空数据 / 降级响应
+
+- 团期 `depart_date` 为空：只返回团期现有行，`code` 200，`message` 带 589602 文案。
+- 模版没有行：只返回现有行。
+
+#### 错误响应
+
+```json
+{ "code": 400, "message": "订单ID和团期ID只能传一个", "success": false, "data": null }
+```
+
+都不传：`400`「订单ID和团期ID必须传一个」。团期：无团期管理权限 `589507`、团期不存在 `589500`。
+
+#### 业务边界
+
+- 套用不写库；保存时把返回的 `items` 原样用接口 3 提交，**套到团期的就只传 `groupBatchId` 提交**。
+- 团期套用的现有行只取团期自己的行，不含子订单的行。
+
+---
+
+## 四、契约约束与正确调用方式
+
+| 场景 | payload |
+|------|---------|
+| ✅ 团期生成 / 重置 | `{ "groupBatchId": "…" }` |
+| ✅ 团期保存 | `{ "groupBatchId": "…", "items": [...] }` |
+| ✅ 团期套用 | `{ "groupBatchId": "…", "templateId": "…" }` |
+| ✅ 团期查询 | `?groupBatchId=…` |
+| ✅ 订单维度 | 只传 `orderId`，其余同改动前 |
+| ❌ 两个都传 | `{ "orderId": "…", "groupBatchId": "…" }` → 400「订单ID和团期ID只能传一个」 |
+| ❌ 两个都不传 | `{}` / 只传 `batchNo` → 400「订单ID和团期ID必须传一个」 |
+
+- 挂团订单保存时**不要再带 `groupBatchId`**（以前可带作一致校验，现在会 400）。
+- 团期的出发 / 返回日期、第几天都以后端返回为准（取团期 `depart_date` / `end_date`）。
+
+---
+
+## 五、数据库行为
+
+- 只传 `groupBatchId` 写入的行：团期ID有值，订单ID、团期编号为空。
+- 只传 `orderId` 写入的行：订单ID有值，团期ID、团期编号为空。
+- 团期保存、重置的软删范围只在团期自己的行；子订单的行不受影响。
+- 套用模版不写库。存量数据无需迁移。
+
+---
+
+## 六、边界行为
+
+- 二选一 400 先于权限、存在性判断，库里零写入。
+- 团期写（生成 / 保存 / 重置 / 套用）要团期管理权限，查询要团期查看权限，不足 `589507`；团期不存在 `589500`；不按团期状态拦截。
+- 团期 `depart_date` / `end_date` 为空：生成、重置、套用返回 `code` 200，`message` 为「订单出发或返回日期为空，无法生成用餐信息」（沿用 589602 文案），查询照常。
+- `orderId` + `batchNo` 查询：固定空列表。
+
+---
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+| 字段 | 改动前 | 改动后 |
+|---|---|---|
+| 3.2 / 3.4 / 4.3 入参 `groupBatchId` | 无 | 新增，与 `orderId` 二选一 |
+| 3.3 / 4.3 入参 `orderId` | 必填 | 与 `groupBatchId` 二选一 |
+| 3.3 入参 `groupBatchId` | 与订单所属团期一致校验（589601） | 只传它表示按团期保存；与 `orderId` 同传 400 |
+| 订单行 `items[].groupBatchId` / `batchNo` | 挂团订单有值 | `null` |
+
+### 行为级对比
+
+| 行为 | 改动前 | 改动后 |
+|---|---|---|
+| 3.1 只传团期ID | 连同团里子订单的行一起返回，汇总为 null | 只返回团期自己的行，汇总按团期填 |
+| 3.1 都不传 | 查没挂订单也没挂团期的行 | 400 |
+| 3.1 `orderId` + `batchNo` | 按订单 + 团期编号筛 | 空列表 |
+| 3.3 都传 | 按订单保存 | 400 |
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 是。都传、都不传、只传 `batchNo` 由成功变为 400；订单行不再带团期ID
+- **前端是否必须同步上线**: 是。挂团订单保存不能再带 `groupBatchId`；团期用餐走只传 `groupBatchId`
+- **前端 workaround 清理点**: 挂团订单保存时附带 `groupBatchId` 的处理；依赖订单行 `groupBatchId` / `batchNo` 判断归属的处理
+
+## 七、不影响范围
+
+- **仅影响**: 上述 5 个用餐接口
+- **零影响**: 模版查询、存为模版、删除模版；金额公式；订单维度的权限与错误码（589601 除外）
+
+---
+
+## 八、测试环境已验证
+
+部署提交 `b86e635c7`（含合并提交 `6ae15b3ed`），Deploy Panel 任务 `23cffa4a`；经 Gateway（`https://api.test.1814.love`）用真实 TEST 身份（SUPER_ADMIN）由固定脚本实测 73 项全部通过。团期 `2101996448340238338`（团期编号 `Q202611042099750379129368577`，出团 2026-11-04、结束 2026-11-08、报名 4 人），子订单 `2101996448319266818`：
+
+```
+只传 groupBatchId 调 3.2 生成                 → 12 行，与团期产品当前行程逐天逐餐一致；第 1 天（自理/含营地/含特色餐）只有午、晚 ✓
+生成的行                                       → groupBatchId=团期、orderId=null、batchNo=null；mealDate=2026-11-04+d−1 ✓
+再调 3.2                                       → 行数、行ID不变（幂等）✓
+改一行后调 3.4 重置                            → 原行全部软删，重新生成与首次逐行一致 ✓
+同一个模版只传 groupBatchId / 只传 orderId 调 4.3 → 两边都能套；团期模版行第 d 日落 2026-11-04+d−1、按人行人数=4、orderId=null ✓
+只传 groupBatchId 调 3.3 保存 2 行              → groupBatchId 有值、orderId=null；dayNumber：11-05→2、11-06→3 ✓
+再保存改一行、少传一行                          → 改的变了（105.00），少传的软删 ✓
+子订单按订单保存 1 行后 3.1 按订单查回           → 行上 groupBatchId=null；顶层仍回显所属团期 ✓
+只传 groupBatchId 调 3.1                       → 查不到子订单那行，只有团期保存的行 ✓
+3.1/3.2/3.3/3.4/4.3 都传                       → 400「订单ID和团期ID只能传一个」（5/5）✓
+3.1/3.2/3.3/3.4/4.3 都不传、3.1 只传 batchNo    → 400「订单ID和团期ID必须传一个」（6/6），零写入 ✓
+只传 groupBatchId 调 3.1                       → departDate=2026-11-04、returnDate=2026-11-08，与团期详情一致 ✓
+团期不存在 / 带子订单行ID / 带不存在行ID / 金额不符 → 589500 / 589611 / 589606 / 589613，零写入 ✓
+```
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#8230](https://git.1814.love:8443/wx/HL/issues/8230)
+- 关联 PR: [wx/HL#8251](https://git.1814.love:8443/wx/HL/pulls/8251)
+- 前置变更: [#8125 套用模版改为在现有行后追加](21_8125_用餐第几天按订单出发日算与套用模版改为在现有行后追加-修改接口-管理后台.md)
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8230](https://git.1814.love:8443/wx/HL/issues/8230)
+- **PR**: [wx/HL#8251](https://git.1814.love:8443/wx/HL/pulls/8251)
+- **Merge commit**: [6ae15b3ed](https://git.1814.love:8443/wx/HL/commit/6ae15b3edaa58cea64c07fce4056fef8a02b551c)
+
+### 联系人
+
+- 后端: @lc
@@ -0,0 +1,550 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8231"
+title: "配导游 / 配摄影 / 物资取消阶段门——出行前四态均可随时配置；取消成团改为放行并回收导摄配置"
+consumer: "admin"
+author: "jw(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "not_required"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "e15dd73bd36a1d27374f9206797243f8a5e4326c"
+target_release: ""
+verified_at: "2026-09-23"
+status_note: "jw 2026-09-23 裁决：配导游 / 配摄影 / 物资三项取消节点限制，只要在出行节点之前都可以随时配置。改前配导游 / 配摄影被 assertFormed 拦在招募中（589552），物资被 assertInMaterialStage 限死在 MATERIAL_PREPARING（589520）——而团期要集齐四项 ready（房 / 车 / 导 / 摄）才推得进 MATERIAL_PREPARING，实际「物资配不了」的根因多半是房车没配齐。本次三处写口统一引用新常量 PRE_DEPARTURE_CONFIGURABLE_STATUSES（RECRUITING / RESOURCE_PREPARING / MATERIAL_PREPARING / PENDING_DEPARTURE），出行后与已取消一律拒成新错误码 589598，未建团仍 589553。连带改的是取消成团：放开招募中可配之后，若导摄仍算「已派单资源」，招募中配过人的团一成团就再也取消不了成团（开工前实测：TEST 团期 2099750660965584898 在房车 ready 全 0、已确认子订单 0 的情况下，仅凭导游一项就返 589502）。故按方案 C，导摄两项移出 R10 判定，取消成团改为放行并在同事务内回收导摄配置（order_batch_staff 整期软删 + 各子订单 order_staff_assignment 中 source=GROUP_BATCH 的扇出行软删），房 / 车两项仍照旧阻断。取证阶段另修一处本单引入的回归：招募中清空导摄配置后 ready 位回不到 false（免闸豁免只对已成团成立，needs_* 招募中恒 0），已随 PR #8237 修复。TEST 实测 2026-09-23 12:15~12:25：物资三端点在四态各放行、在 REVIEWING / TRIP_FINISHED / CANCELLED 各返 589598 且零写入；配导摄在四态各落库成功、在三个出行后态返 589598 且零写入；取消成团对仅导摄 dispatched 的样本返 200 并完成回收，对 hotel_ready=1 / vehicle_ready=1 两个样本仍返 589502 且零写入；连续两次取消成团第二次返 589501、不重复回收。前端侧：配导游 / 配摄影按钮本来就不看 batchStatus，零改动；物资 tab 的操作列在 SuppliesPanel.vue 里按 MATERIAL_PREPARING 前置隐藏，后端放开后前端不改则本单无实际效果，交接件见同批 frontend 条目，故 frontend_status 记 pending。 | 2026-09-23 mmg 交付:SuppliesPanel 拆双判据四态放行三写口,配导摄零改动实证,随配套 frontend 条目同 commit"
+updated_at: "2026-09-23"
+base: "dev-v3"
+---
+
+# 团期资源配置: 配导游 / 配摄影 / 物资放开到出行前四态（管理后台）
+
+> **服务**: hl-order-service-v3（端口 8086/8186）
+> **PR**: #8234、#8237
+> **Issue**: #8231
+> **日期**: 2026-09-23
+> **影响范围**: 管理后台团期详情页的「配导游 / 配摄影」弹窗、「物资」tab、「取消成团」按钮
+
+---
+
+## ⚠️ 关键变化
+
+本次是**行为变更，不是纯增字段**，三条都与调用方此前的预期不同：
+
+1. **可配窗口扩大**。以前「招募中配不了导摄」「物资只有到了准备物资阶段才配得了」，现在**出行前四态都能配**。
+2. **拒绝时的错误码换了**。以前物资拒是 `589520`、导摄拒是 `589552`，现在统一是新码 **`589598`**。按 589520 / 589552 做文案分支的前端要改。
+3. **取消成团的阻塞条件收窄了**。以前「已派导游 / 已派摄影」会把取消成团拦住（589502），**现在不会**；作为代价，取消成团成功后会把该团期的导摄配置一并回收，配人列表会变空。
+
+---
+
+## 一、背景
+
+`GroupBatchStatus` 状态机里，「出行之前」= 前四态：
+
+| 允许配置 | 拒绝 |
+|---|---|
+| `RECRUITING` 招募中 · `RESOURCE_PREPARING` 资源准备中 · `MATERIAL_PREPARING` 物料准备中 · `PENDING_DEPARTURE` 待出发 | `TRAVELLING` 出行中 · `TRIP_FINISHED` 出行完毕 · `REVIEWING` 核单中 · `SETTLED` 已结算 · `CANCELLED` 已取消 |
+
+`CANCELLED` 按拒绝处理：它是终态取消，不属于「出行前」语义。
+
+**物资的实际约束比表面更紧**：团期要先走到 `MATERIAL_PREPARING` 才开窗，而
+`RESOURCE_PREPARING → MATERIAL_PREPARING` 的推进条件是四项 ready 齐（房 / 车 / 导 / 摄）+ 合同 / 保险。
+即今天「物资配不了」的根因多数是房车没配齐。本次放开后，物资配置不再依赖这条链。
+
+**状态机推进逻辑本身不动**：`MATERIAL_PREPARING` 这个阶段、以及「四项 ready 齐才推进」那条链一律不变。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 保存团期人员配置 | PUT | `/v3/admin/group-batch/{productBatchId}/staff` | 修改接口 | 阶段门从「已成团」放宽到出行前四态；拒绝码 589552 → 589598 |
+| 2 | 设置报账人等级 | PUT | `/v3/admin/group-batch/{productBatchId}/staff/{staffId}/reporter-rank` | 修改接口 | 同上，与保存口同窗口 |
+| 3 | 新增团期备品行 | POST | `/v3/admin/order/group-batch/{groupBatchId}/supplies` | 修改接口 | 阶段门从 `MATERIAL_PREPARING` 放宽到出行前四态；拒绝码 589520 → 589598 |
+| 4 | 调整团期备品数量 | PUT | `/v3/admin/order/group-batch/supplies/{batchSuppliesId}/quantity` | 修改接口 | 同上 |
+| 5 | 软删团期备品行 | DELETE | `/v3/admin/order/group-batch/supplies/{batchSuppliesId}` | 修改接口 | 同上 |
+| 6 | 取消成团 | POST | `/v3/admin/order/group-batch/{groupBatchId}/cancel-group` | 修改接口 | 导摄两项不再阻断；成功时额外回收导摄配置 |
+
+路径、入参结构、权限码、成功响应结构均零变化；网关无改动。
+
+---
+
+## 三、接口详情
+
+### 1. 保存团期人员配置 `PUT /v3/admin/group-batch/{productBatchId}/staff`
+
+**VO**: `BatchStaffConfigReqVO` → `BatchStaffConfigRespVO`
+
+#### 使用场景
+
+团期详情页「配导游 / 配摄影」弹窗点保存。整期全量覆盖：按 `scopeRoles`（不传即全量）软删旧配置、
+写入新配置、异步扇出到各活跃子订单，并按配置结果回填 `guide_ready` / `photographer_ready`。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| productBatchId | path | Long | 是 | 正整数，产品侧排期 ID | 团期所属班期；未建团返 589553 |
+| scopeRoles | body | List&lt;String&gt; | 否 | 元素非空 | 限定本次覆盖的角色范围，不传则整期覆盖 |
+| staffList | body | List&lt;Item&gt; | 否 | null 按空列表处理 | 传空列表 = 清空覆盖范围内的配置 |
+| staffList[].staffId | body | Long | 是 | 须命中候选人员 | 人员 ID |
+| staffList[].staffRole | body | String | 是 | 须与人员类型相符，否则 582114 | 角色（GUIDE / LEADER / PHOTOGRAPHER …） |
+| staffList[].sortOrder | body | Integer | 否 | — | 展示排序 |
+| staffList[].remark | body | String | 否 | — | 备注 |
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| productBatchId | Long | 回显路径参数 |
+| groupBatchId | Long | 团期聚合主键，取守卫阶段那一次既有反查的结果，不额外查库 |
+| staffList | List | 保存后的整期最终状态 |
+| affectedOrderCount | Integer | 本次扇出触及的活跃子订单数 |
+
+#### 请求示例
+
+```http
+PUT /v3/admin/group-batch/2097250420299530242/staff HTTP/1.1
+Host: api.test.1814.love:9443
+Authorization: Bearer <admin token>
+Content-Type: application/json
+
+{"staffList":[{"staffId":1002,"staffRole":"GUIDE","sortOrder":0},{"staffId":1003,"staffRole":"PHOTOGRAPHER","sortOrder":1}]}
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "productBatchId": "2097250420299530242",
+    "groupBatchId": "2097250563497385985",
+    "affectedOrderCount": 0,
+    "staffList": [
+      {"staffId": 1002, "staffRole": "GUIDE", "staffName": "李雪梅", "reporterRank": "NONE"},
+      {"staffId": 1003, "staffRole": "PHOTOGRAPHER", "staffName": "王强", "reporterRank": "NONE"}
+    ]
+  }
+}
+```
+
+#### 空数据 / 降级响应
+
+`staffList` 传空列表即清空覆盖范围内的配置，返回 200，`staffList` 为空数组、`affectedOrderCount` 为实际扇出订单数。
+**清空后 ready 位的回落口径本次有修正**：已成团且该位 `needs_*=false`（成团免闸置位）时保持就绪、不回落；
+其余情形（含**招募中**）一律回落为 false。改前招募中清空后 ready 位会卡在 true，与配置行数 0 自相矛盾。
+
+#### 错误响应
+
+```json
+{"code": 589598, "message": "出行后不可再配置导游 / 摄影 / 物资", "data": null}
+```
+
+未建团（该班期还没有任何订单，团期行尚未 Lazy 建）仍是另一个码，两者不可合并：
+
+```json
+{"code": 589553, "message": "团期尚未创建（该班期还没有任何订单），请先建团并完成成团后再操作", "data": null}
+```
+
+#### 业务边界
+
+- 出行前四态（`RECRUITING` / `RESOURCE_PREPARING` / `MATERIAL_PREPARING` / `PENDING_DEPARTURE`）放行
+- `TRAVELLING` / `TRIP_FINISHED` / `REVIEWING` / `SETTLED` / `CANCELLED` 返 589598，**被拒时一行都不写**（闸在写库之前）
+- 未建团返 589553，且**不会为配置动作提前建团期行**
+- 589552「团期尚未成团」不再由本接口抛出，但该码仍被别处（车辆派单、房务）使用，未退役
+
+---
+
+### 2. 设置报账人等级 `PUT /v3/admin/group-batch/{productBatchId}/staff/{staffId}/reporter-rank`
+
+**VO**: `ReporterRank`（枚举入参）
+
+#### 使用场景
+
+团期人员名单里把某个已配人员标为主报账人 / 协助报账人。它与保存口是同构写口——同样写
+`order_batch_staff` 并扇出 `order_staff_assignment`，故口径必须与保存口完全一致。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| productBatchId | path | Long | 是 | 正整数 | 产品侧排期 ID |
+| staffId | path | Long | 是 | 须命中该团期已配人员 | 人员 ID |
+| rank | body | String | 是 | PRIMARY / ASSIST / NONE | 报账人等级 |
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| data | Void | 成功返回 null，判成败看 `code` |
+
+#### 请求示例
+
+```http
+PUT /v3/admin/group-batch/2097250420299530242/staff/1002/reporter-rank HTTP/1.1
+Host: api.test.1814.love:9443
+Authorization: Bearer <admin token>
+Content-Type: application/json
+
+{"rank":"PRIMARY"}
+```
+
+#### 响应示例
+
+```json
+{"code": 200, "message": "成功", "data": null}
+```
+
+#### 空数据 / 降级响应
+
+本接口无列表出参，无空数据形态；团期已配人员为空时会先因 staffId 未命中报错，不会静默成功。
+
+#### 错误响应
+
+```json
+{"code": 589598, "message": "出行后不可再配置导游 / 摄影 / 物资", "data": null}
+```
+
+#### 业务边界
+
+- 窗口与保存口完全一致，不允许两个方法口径漂移
+- 被拒时连「查已派 staff」这一步读都不发生，零写入
+- 未建团仍返 589553
+
+---
+
+### 3. 新增团期备品行 `POST /v3/admin/order/group-batch/{groupBatchId}/supplies`
+
+**VO**: `AddSuppliesReqVO`
+
+#### 使用场景
+
+团期详情页「物资」tab 手工录入一行备品（产品侧没有、临时采购的）。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| groupBatchId | path | Long | 是 | 正整数，团期聚合主键 | 不存在返 GROUP_BATCH_NOT_FOUND |
+| suppliesName | body | String | 否 | 传 suppliesResourceId 时可空 | 备品名称；纯手填时必填 |
+| suppliesResourceId | body | Long | 否 | — | 备品库资源 ID，传了则名称取库值 |
+| category | body | String | 否 | — | 分类 |
+| hasCost | body | Boolean | 否 | — | 是否计费 |
+| billingType | body | String | 否 | PER_PERSON / PER_QUANTITY | 计费方式 |
+| unitPrice | body | BigDecimal | 否 | — | 单价 |
+| quantity | body | Integer | 是 | ≥ 1，否则 589522 | 数量 |
+| sortOrder | body | Integer | 否 | 默认 0 | 展示排序 |
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| data | Long | 新建备品行 ID（`batchSuppliesId`），用于后续改数量 / 软删 |
+
+#### 请求示例
+
+```http
+POST /v3/admin/order/group-batch/2099750365778886657/supplies HTTP/1.1
+Host: api.test.1814.love:9443
+Authorization: Bearer <admin token>
+Content-Type: application/json
+
+{"suppliesName":"临时采购的雨衣","quantity":1,"sortOrder":999}
+```
+
+#### 响应示例
+
+```json
+{"code": 200, "message": "成功", "data": "2102611411027066881"}
+```
+
+#### 空数据 / 降级响应
+
+本接口是写接口，无空数据形态。创单时由系统固化产品侧备品的 `freezeFromProduct` 路径**不过本阶段门**——
+它是首单懒建事务内的系统行为，加门会把建团直接打断，该豁免本次不变。
+
+#### 错误响应
+
+```json
+{"code": 589598, "message": "出行后不可再配置导游 / 摄影 / 物资", "data": null}
+```
+
+#### 业务边界
+
+- 出行前四态放行，尤其 `RESOURCE_PREPARING`——改前该态必被 589520 拒
+- 出行后与 `CANCELLED` 返 589598，不落库
+- 团期不存在返 `GROUP_BATCH_NOT_FOUND`，不是阶段错误
+- 数量非法返 589522 参数错误，不是状态错误
+
+---
+
+### 4. 调整团期备品数量 `PUT /v3/admin/order/group-batch/supplies/{batchSuppliesId}/quantity`
+
+**VO**: `AdjustSuppliesQuantityReqVO`
+
+#### 使用场景
+
+物资 tab 行内编辑数量。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| batchSuppliesId | path | Long | 是 | 须命中活跃备品行 | 不存在返 589521 |
+| quantity | body | Integer | 是 | ≥ 1，否则 589522 | 新数量 |
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| data | Void | 成功返回 null |
+
+#### 请求示例
+
+```http
+PUT /v3/admin/order/group-batch/supplies/2102611411027066881/quantity HTTP/1.1
+Host: api.test.1814.love:9443
+Authorization: Bearer <admin token>
+Content-Type: application/json
+
+{"quantity":5}
+```
+
+#### 响应示例
+
+```json
+{"code": 200, "message": "成功", "data": null}
+```
+
+#### 空数据 / 降级响应
+
+无列表出参，无空数据形态。备品行已被软删时返 589521，不会静默成功。
+
+#### 错误响应
+
+```json
+{"code": 589598, "message": "出行后不可再配置导游 / 摄影 / 物资", "data": null}
+```
+
+#### 业务边界
+
+- 阶段门由该备品行反查所属团期后判定，窗口与新增口一致
+- **「确认物资之后能不能改」不归本门管**：确认后仍可增删改是有意为之，窗口扩大后该结论不变
+- 被拒时数量不变、行不被软删
+
+---
+
+### 5. 软删团期备品行 `DELETE /v3/admin/order/group-batch/supplies/{batchSuppliesId}`
+
+**VO**: `Result<Void>`（无请求体）
+
+#### 使用场景
+
+物资 tab 删除一行备品。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| batchSuppliesId | path | Long | 是 | 须命中活跃备品行 | 不存在返 589521 |
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| data | Void | 成功返回 null |
+
+#### 请求示例
+
+```http
+DELETE /v3/admin/order/group-batch/supplies/2102611411027066881 HTTP/1.1
+Host: api.test.1814.love:9443
+Authorization: Bearer <admin token>
+```
+
+#### 响应示例
+
+```json
+{"code": 200, "message": "成功", "data": null}
+```
+
+#### 空数据 / 降级响应
+
+软删是幂等的：对已软删的行再调返 589521「备品行不存在」，不会重复写。
+
+#### 错误响应
+
+```json
+{"code": 589598, "message": "出行后不可再配置导游 / 摄影 / 物资", "data": null}
+```
+
+#### 业务边界
+
+- 窗口与新增 / 改数量完全一致
+- 被拒时行的 `deleted_at` 保持为空
+
+---
+
+### 6. 取消成团 `POST /v3/admin/order/group-batch/{groupBatchId}/cancel-group`
+
+**VO**: `Result<Void>`（无请求体）
+
+#### 使用场景
+
+团期从「资源准备中」退回「招募中」。本次**没有改它的入参或路径**，改的是它的阻塞条件与成功时的副作用。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| groupBatchId | path | Long | 是 | 正整数，团期聚合主键 | 不存在返 GROUP_BATCH_NOT_FOUND；非 `RESOURCE_PREPARING` 返 589501 |
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| data | Void | 成功返回 null，团期状态已回到 `RECRUITING` |
+
+#### 请求示例
+
+```http
+POST /v3/admin/order/group-batch/2099750660965584898/cancel-group HTTP/1.1
+Host: api.test.1814.love:9443
+Authorization: Bearer <admin token>
+```
+
+#### 响应示例
+
+```json
+{"code": 200, "message": "成功", "data": null}
+```
+
+#### 空数据 / 降级响应
+
+成功时无返回体。该团期没有任何导摄配置时，回收步骤是零行软删的空操作，不影响成功。
+
+#### 错误响应
+
+```json
+{"code": 589502, "message": "取消成团被阻塞（有已确认子订单或已派单资源）", "data": null}
+```
+
+连续两次调用，第二次因状态已不是 `RESOURCE_PREPARING` 被 CAS 拒：
+
+```json
+{"code": 589501, "message": "团期状态不允许当前操作", "data": null}
+```
+
+#### 业务边界
+
+- 仍阻塞：有已确认子订单（`PENDING_DEPARTURE` / `TRAVELLING` / `COMPLETED`）、`hotel_ready=true`、
+  `vehicle_ready=true`（且非整团免车）
+- **不再阻塞**：已派导游、已派摄影
+- 成功时依次：状态 CAS 回 `RECRUITING` → 四项 ready 与物资确认全部重置 → **回收导摄配置** → 登记配车释放命令
+- 回收范围只含 `source=GROUP_BATCH` 的扇出行，子订单自己单独派的人不受影响
+- 幂等：第二次调用被 589501 拒，不重复回收
+
+---
+
+## 四、契约约束与正确调用方式
+
+- **判拒绝原因不要再认 589520 / 589552**。这两个码不再由上述五个配置接口抛出（589520 保留占位防号段复用，589552 仍由车辆派单、房务等别处使用）。统一认 **589598**。
+- **589598 与 589553 是两件事**，不要合并成一个 toast：前者是「这个团已经出发了，配不了了」，后者是「这个班期还没有任何订单，先去建团」。
+- 配导摄成功后，若调用方缓存了 `guide_ready` / `photographer_ready`，需重新拉取团期详情——本次修正了清空时的回落口径。
+- 取消成功后，**团期人员名单会变空**，调用方若停在配人弹窗需主动刷新。
+
+---
+
+## 五、数据库行为
+
+- 配导摄保存：整期（或 `scopeRoles` 范围内）软删旧配置行 + 写入新配置行 + 异步扇出到各活跃子订单；随后按配置结果回填团期行的两个 ready 标志
+- 物资三口：分别为插入一行、更新一行的数量、软删一行
+- 取消成团：状态 CAS 一行 + 重置该团期四项 ready 与物资确认 + 软删该团期全部导摄配置行 + 软删其各子订单中来源为团期扇出的人员分配行，**全部在同一个事务内**，任一步失败整体回滚
+- 被阶段门拒绝时零写入：闸在所有写库动作之前
+
+---
+
+## 六、边界行为
+
+- `CANCELLED`（已流团）按拒绝处理，返 589598
+- 未建团（团期行尚未 Lazy 建）返 589553，**不会为配置动作提前建行**——否则会出现「零单可配 → 首单落地反而不可配 → 成团后又可配」这种非单调行为
+- 创单时固化产品侧备品的系统路径不过阶段门，该豁免不变
+- 「确认物资之后仍可增删改」不变
+
+---
+
+## 六.6、修改前后对比
+
+| 维度 | 改前 | 改后 |
+|---|---|---|
+| 配导摄可配状态 | 已成团各态（招募中被拒） | `RECRUITING` / `RESOURCE_PREPARING` / `MATERIAL_PREPARING` / `PENDING_DEPARTURE` |
+| 配导摄拒绝码 | 589552（未成团）/ 589553（未建团） | 589598（已出行 / 已取消）/ 589553（未建团） |
+| 物资三口可配状态 | 仅 `MATERIAL_PREPARING` | 同上四态 |
+| 物资三口拒绝码 | 589520 | 589598 |
+| 取消成团：已派导游 / 摄影 | 返 589502 被阻塞 | 放行，且回收导摄配置 |
+| 取消成团：房 / 车 ready | 返 589502 被阻塞 | **不变**，仍返 589502 |
+| 招募中清空导摄后的 ready 位 | 卡在 true（与配置行数 0 矛盾） | 回落为 false |
+
+---
+
+## 六.7、影响评估
+
+| 面 | 评估 |
+|---|---|
+| 管理后台配导摄 | 按钮本来就不看 `batchStatus`，招募中点得下去、只是被后端拒。后端放开后**前端零改动即可生效** |
+| 管理后台物资 tab | 操作列按 `MATERIAL_PREPARING` 前置隐藏，**前端不改则本次无实际效果**，交接件见同批 frontend 条目 |
+| 已有错误文案分支 | 按 589520 / 589552 做文案的地方需改认 589598 |
+| 取消成团 | 可取消的团期变多；成功后人员名单会被清空，属预期 |
+| 小程序端 | 不受影响，物资清单在小程序端是只读视图 |
+| 状态机 | 不变，`MATERIAL_PREPARING` 阶段与「四项 ready 齐才推进」那条链一律不动 |
+
+---
+
+## 七、不影响范围
+
+- 团期状态机的推进逻辑、四项 ready 的计算口径
+- 流团（`disband`）：只校验状态白名单，不看 ready 位，本次完全不受影响
+- 子订单自己单独派的人员（`order_staff_assignment` 中 source 非 `GROUP_BATCH` 的行）：回收不碰它们
+- 车辆派单、房务等仍在用 `assertFormed` 的写口：口径不变
+- 权限码、路径、入参结构、成功响应结构、网关配置
+
+---
+
+## 八、测试环境已验证
+
+2026-09-23 12:15~12:25，`api.test.1814.love:9443`，分支 `dev-v3`（`fe752f16c`）。
+
+| AC | 内容 | 结果 |
+|---|---|---|
+| 物资四态放行 | `RECRUITING` / `RESOURCE_PREPARING` / `MATERIAL_PREPARING` / `PENDING_DEPARTURE` 各跑「增 → 改数量 → 删」三端点 | 12 次调用全 200，自造行自删、零残留 |
+| 物资出行后拒 | `REVIEWING` / `TRIP_FINISHED` / `CANCELLED` 各跑三端点 | 全返 589598；既有行的 `quantity` 未变、未软删、未新增行 |
+| 配导摄四态放行 | 四态各保存「1002 GUIDE + 1003 PHOTOGRAPHER」 | 全 200 且落库；逐个还原为改前配置，四组还原判定全 ✔ |
+| 配导摄出行后拒 | `REVIEWING` / `TRIP_FINISHED` / `CANCELLED` | 全返 589598；活跃行与表内总行数逐字未变 |
+| 未建团 | 不存在的 `productBatchId` | 返 589553，未被新码吞掉 |
+| 取消成团放行 + 回收 | 团期 `2099750660965584898`（`needs_guide=1 & guide_ready=1`，房车 ready 全 0，已确认子订单 0）——同一样本开工前实测返 589502 | 返 200；状态 `RESOURCE_PREPARING → RECRUITING`；`guide_ready` / `photographer_ready` 归 0；配置行与子订单扇出行同时间戳软删 |
+| 房车仍阻断 | `hotel_ready=1` 与 `vehicle_ready=1` 两个样本 | 均返 589502；团期行与两张配置表逐字未变 |
+| 幂等 | 对同一团期连调两次取消成团 | 第二次返 589501；三处读数与第一次后完全一致，无重复回收 |
+
+本地单测：assignment + groupbatch + house 4103 条、archunit / core / requirement 等 3456 条、其余 26 个包 4621 条，全绿。
+
+取证用到的写操作及还原：新增的备品行均由本次自行软删；配导摄的四个团期均按改前配置逐条还原；
+取消成团样本 `2099750660965584898` 已按改前值还原（状态、两个 ready 位、配置行与扇出行的软删标记）。
+
+---
+
+## 十、相关文档
+
+- Issue #8231（含开工前的 AC-6 实测与方案 C 裁决）
+- PR #8234（主体）、PR #8237（ready 回落回归修复）
+- 被推翻：#7287 T5（`assertFormed`）、#7023 AC-TD-13（物资单一阶段窗口）、wx 2026-09-15「放行但配置行保留」
+- 保持不变：#7023 AC-TD-15（确认后仍可改）、#7441 PR-2e（整团免车的 ready 剥离）
+
+---
+
+## 关联 / 联系人
+
+- 后端：jw
+- 前端：mmg（物资 tab 显隐条件，见同批 frontend 条目）
@@ -0,0 +1,644 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8249"
+title: "团期「查看需求」：无需求行的户不再报 PENDING、户级未提交用车需求进预检清单、六条车务报文改写为可读名称"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "not_required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "前端判 not_required:状态列 statusName||status||— 三级兜底 null 安全;PENDING 判等 12 处全无关;vehicleMissing 按 orderNo 结构化分流即契约推荐判据;809 报文零文本匹配分支(拦截器透 toast/detail 直显)"
+updated_at: "2026-09-23"
+base: "dev-v3"
+---
+
+# order-v3: 团期「查看需求」页三处契约变更（含报文变更）
+
+> **存放目录**: `changelogs-v2/{YYYY-MM}/`
+>
+> **服务**: hl-order-service-v3 (端口 8007)
+> **PR**: #8286
+> **Issue**: #8249
+> **日期**: 2026-09-23
+> **影响范围**: 管理后台「团期详情 → 查看需求」tab 的子订单列表状态列、整团确认预检横幅、车务相关弹窗文案
+
+---
+
+## ⚠️ 关键变化
+
+1. **状态字段会返 `null` 了**：`hotelRequirementStatus` / `vehicleRequirementStatus` 在「该户一条 active 需求行都没有」时返回 `null`。改前恒回落字符串 `"PENDING"`，页面把一个根本没提交的户显示成「待房务配 / 待车队配」，与同屏预检横幅里的 `NOT_SUBMITTED` 自相矛盾。配对的 `*StatusName` 此时按该户是否需要该资源分叉：需要 → `"未提交"`，不需要 → `null`。
+2. **预检清单多一类条目**：`confirm-check` 的 `vehicleMissing[]` 新增 `reason = "HOUSEHOLD_REQUIREMENT_NOT_SUBMITTED"`（错误码 809122），表示「该户在团需车、却一条行程用车需求都没提交」。它与团级的 `GROUP_REQUIREMENT_NOT_FOUND` **并列出现**，不互斥、不被团级缺席短路——改前车侧只查团级正式需求，「某户一行都没提交」在预检里没有任何位置能表达。
+3. 🔴 **报文变更**：六个 809 段错误码的**渲染文本**被改写（雪花 ID → 可读名称 / 直接删掉标识符），见「六.6、修改前后对比」。因为 `GroupVehicleViolation.detail()` 就是 `toException().getMessage()`，**预检横幅上的 `detail` 与确认/保存/免车弹窗里的 `message` 是同一份字符串**，两处同时改变。凡是对 `vehicleMissing[].detail` 或错误 `message` 做**文本匹配 / 正则解析 / 截取订单号**的前端逻辑，这次会失效；纯展示（原样渲染这段人话）不需要改。订单号已经由 `vehicleMissing[].orderNo` 结构化下发，不要再从 `detail` 里抠。
+
+---
+
+## 一、背景
+
+「查看需求」页上同一个团期的同一户，三处读数互相矛盾：子订单列表说「待房务配」（=已提交、等资源侧接），预检横幅说「未提报」，而整团确认点下去报的是团级的「尚未形成正式用车需求」——运营据此去催车务，实际该催的是定制师。
+
+| 维度 | 改前 | 改后 |
+|------|------|------|
+| 无 active 需求行时 `*Status` | `"PENDING"`（借用了真实状态之一） | `null` |
+| 无 active 需求行时 `*StatusName` | 「待房务配」/「待车队配」 | 「未提交」（该户需要该资源时）/ `null` |
+| 车侧预检覆盖粒度 | 只有团级正式需求的六条校验 | 团级六条 + **逐户**查行程用车需求是否提交 + 待放行接送机需求服务日回填 |
+| 车务报文里的标识符 | 雪花 ID（`团期 2100856430494973953`、`子订单 2102309919002943489`） | 可读名称（`团期「第3期 10月8日出发团」`、`子订单 HL20260922161158291`）或直接省略 |
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | A3 团期下子订单列表 | GET | `/v3/admin/order/group-batch/{groupBatchId}/orders` | 出参取值变更 | 四个需求状态字段在无 active 行时改为 `null` + 「未提交」 |
+| 2 | GB-ADM-012 整团确认需求缺失预检 | GET | `/v3/admin/order/group-batch/{groupBatchId}/requirement/confirm-check` | 出参枚举扩充 + 报文变更 | `vehicleMissing[].reason` 新增 `HOUSEHOLD_REQUIREMENT_NOT_SUBMITTED`；`detail` 文案改写 |
+
+---
+
+## 三、接口详情
+
+### 1. A3 团期下子订单列表 `GET /v3/admin/order/group-batch/{groupBatchId}/orders`
+
+**VO**: `Query 参数 → PageResult<GroupBatchOrderItemRespVO>`
+
+#### 使用场景
+
+管理后台「团期详情 → 查看需求 / 子订单」tab 打开时调用，渲染该团期下每一户的一行摘要（团号、客户、金额、房需求状态、车需求状态、定制师、出行人）。本次改动只影响其中四个需求状态字段的取值，分页与其余字段的契约不变。鉴权走团期权限码 `group-batch:view`，未登录由网关拦截。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long | ✅ | 雪花 ID，团期聚合主键 | 团期 ID |
+| page | Query | Integer | ❌ | 缺省 1；小于 1 归一为 1 | 页码，从 1 起 |
+| pageSize | Query | Integer | ❌ | 缺省 20；小于 1 归一为 20；大于 200 截断为 200 | 每页条数 |
+| includeTravelers | Query | Boolean | ❌ | 缺省 true | 是否附 `travelers[]`；证件号/手机号一律不返回 |
+| includeNeeds | Query | Boolean | ❌ | 缺省 true | 是否附 `roomCount` / `roomType` / `specialNeeds` |
+| includeCancelled | Query | Boolean | ❌ | 缺省 false | 是否含已取消子订单；缺省只返活跃集 |
+
+#### 出参 `Result<PageResult<GroupBatchOrderItemRespVO>>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data.total | Long | 总条数 |
+| data.page | Integer | 当前页码 |
+| data.pageSize | Integer | 每页条数 |
+| data.records[].orderId | String | 子订单 ID（雪花，JSON 里是字符串） |
+| data.records[].orderNo | String | 订单编号 |
+| data.records[].teamNo | String | 团号；订金支付成功后生成，未付订金为 `null` |
+| data.records[].customerName | String | 客户姓名 |
+| data.records[].participantCount | Integer | 出行人总数 |
+| data.records[].orderStatus | String | 订单状态码 |
+| data.records[].orderStatusName | String | 订单状态中文名 |
+| data.records[].payStatus | String | 支付状态（UNPAID / DEPOSIT_PAID / FULLY_PAID） |
+| data.records[].payStatusName | String | 支付状态中文名 |
+| data.records[].contractStatus | String | 合同状态；无合同时 `null` |
+| data.records[].contractStatusName | String | 合同状态中文名；无合同时 `null` |
+| data.records[].insuranceStatus | String | 保险状态；无保险时 `null` |
+| data.records[].insuranceStatusName | String | 保险状态中文名；无保险时 `null` |
+| data.records[].paidAmount | String | 已支付金额（订金 + 尾款），两位小数字符串 |
+| data.records[].balanceAmount | String | 待支付尾款金额，两位小数字符串 |
+| data.records[].hotelRequirementStatus | String | **本次变更**：房需求状态码；无 active 房需求行时为 `null`（改前回落 `"PENDING"`） |
+| data.records[].hotelRequirementStatusName | String | **本次变更**：房需求状态中文名；`hotelRequirementStatus` 为 `null` 时该户需房则为 `"未提交"`、不需房则为 `null` |
+| data.records[].vehicleRequirementStatus | String | **本次变更**：车需求状态码；无 active 行时为 `null`（改前回落 `"PENDING"`） |
+| data.records[].vehicleRequirementStatusName | String | **本次变更**：车需求状态中文名；`vehicleRequirementStatus` 为 `null` 时该户需车则为 `"未提交"`、不需车则为 `null` |
+| data.records[].consultantName | String | 定制师姓名（创单时固化） |
+| data.records[].totalPrice | String | 本户应收，两位小数字符串；取消单为 `"0.00"` |
+| data.records[].tierCode | String | 档位码（形如 `2A1C`） |
+| data.records[].tierName | String | 档位名（形如 `2成人1儿童`） |
+| data.records[].travelerInfoComplete | Boolean | 出行人资料是否齐全 |
+| data.records[].roomCount | Integer | 房数；`includeNeeds=true` 时返回 |
+| data.records[].roomType | String | 房型文本；`includeNeeds=true` 时返回，无需求行时 `null` |
+| data.records[].roomTypeName | String | 房型中文名；字典不可达时回落原值 |
+| data.records[].specialNeeds | String | 特殊需求；缺需求行时回落订单备注 |
+| data.records[].contactPhone | String | 联系人手机号（脱敏，前 3 后 4） |
+| data.records[].groupChatUnreadCount | Integer | 「联系定制师」按钮未读角标 |
+| data.records[].travelers[].name | String | 出行人姓名 |
+| data.records[].travelers[].type | String | 出行人类型（ADULT / CHILD / YOUNG_CHILD / BABY） |
+| data.records[].travelers[].age | Integer | 出团日时的周岁；缺出生日期时 `null` |
+| data.records[].travelers[].birthdayInTrip | Boolean | 是否行程期间过生日 |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch/2100856430494973953/orders HTTP/1.1
+Host: <网关地址>
+Authorization: Bearer <admin token>
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "records": [
+      {
+        "orderId": "2100856430239121409",
+        "orderNo": "HL20260918155619496",
+        "teamNo": "26-7060",
+        "customerName": "王有亿",
+        "participantCount": 3,
+        "orderStatus": "CUSTOMIZING",
+        "orderStatusName": "定制中",
+        "payStatus": "DEPOSIT_PAID",
+        "payStatusName": "已付定金",
+        "contractStatus": null,
+        "contractStatusName": null,
+        "insuranceStatus": null,
+        "insuranceStatusName": null,
+        "paidAmount": "1500.00",
+        "balanceAmount": "9440.00",
+        "hotelRequirementStatus": "PENDING_REVIEW",
+        "hotelRequirementStatusName": "待审核",
+        "vehicleRequirementStatus": "PENDING_REVIEW",
+        "vehicleRequirementStatusName": "待提交车务",
+        "consultantName": "王骁",
+        "totalPrice": "10940.00",
+        "tierCode": "2A1C",
+        "tierName": "2成人1儿童",
+        "travelerInfoComplete": true,
+        "roomCount": 1,
+        "roomType": "DELUXE",
+        "roomTypeName": "豪华房",
+        "specialNeeds": "禁烟",
+        "contactPhone": "137****1407",
+        "groupChatUnreadCount": 0,
+        "travelers": [
+          { "name": "王有亿", "type": "ADULT", "age": 41, "birthdayInTrip": false },
+          { "name": "李美丽", "type": "ADULT", "age": 36, "birthdayInTrip": false },
+          { "name": "王小明", "type": "CHILD", "age": 8, "birthdayInTrip": false }
+        ]
+      },
+      {
+        "orderId": "2102309919002943489",
+        "orderNo": "HL20260922161158291",
+        "teamNo": "26-2355",
+        "customerName": "王二麻子",
+        "participantCount": 4,
+        "orderStatus": "CUSTOMIZING",
+        "orderStatusName": "定制中",
+        "payStatus": "DEPOSIT_PAID",
+        "payStatusName": "已付定金",
+        "contractStatus": null,
+        "contractStatusName": null,
+        "insuranceStatus": null,
+        "insuranceStatusName": null,
+        "paidAmount": "2000.00",
+        "balanceAmount": "13920.00",
+        "hotelRequirementStatus": null,
+        "hotelRequirementStatusName": "未提交",
+        "vehicleRequirementStatus": null,
+        "vehicleRequirementStatusName": "未提交",
+        "consultantName": "刘畅",
+        "totalPrice": "15920.00",
+        "tierCode": "4A",
+        "tierName": "4成人",
+        "travelerInfoComplete": false,
+        "roomCount": 2,
+        "roomType": null,
+        "roomTypeName": null,
+        "specialNeeds": "干",
+        "contactPhone": "185****0000",
+        "groupChatUnreadCount": 0,
+        "travelers": []
+      }
+    ],
+    "total": 2,
+    "page": 1,
+    "pageSize": 20
+  },
+  "traceId": null,
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+团期下没有活跃子订单（或 `page` 超出范围）时返回空页，信封与分页字段结构同上，`records` 为空数组，不返 404、不 500：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": { "records": [], "total": 0, "page": 1, "pageSize": 20 },
+  "traceId": null,
+  "success": true
+}
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 589500,
+  "message": "团期不存在",
+  "data": null,
+  "traceId": null,
+  "success": false
+}
+```
+
+无团期权限或该团期不在本人名下：
+
+```json
+{
+  "code": 589507,
+  "message": "无操作权限（当前角色未授予团期权限，或该团期不在您名下）",
+  "data": null,
+  "traceId": null,
+  "success": false
+}
+```
+
+#### 业务边界
+
+- 业务失败走 HTTP 200 + `success:false` 的信封；未登录由网关返 401，不在本接口的码集里。
+- `hotelRequirementStatus` / `vehicleRequirementStatus` 与各自的 `*StatusName` **必须成对读**：`Status` 为 `null` 且 `StatusName` 为 `"未提交"`，表示该户需要这项资源但一条需求行都没提交；两者**都**为 `null` 表示该户本来就不需要这项资源，页面渲染「—」。
+- 不要再用 `status === 'PENDING'` 判断「没提交」——`PENDING` 现在唯一含义是「已提交、等资源侧接单」。判「没提交」的唯一判据是 `status == null`。
+- `*StatusName` 在遇到枚举外的未知码时回落原 code，前端渲染保持 `statusName || status || '—'` 的三级兜底即可，不会拿到空串。
+- 本接口只读，不写库；重复调用无副作用。
+- `includeCancelled=false`（缺省）时已取消子订单不出现在结果里，`total` 同口径。
+
+---
+
+### 2. GB-ADM-012 整团确认需求缺失预检 `GET /v3/admin/order/group-batch/{groupBatchId}/requirement/confirm-check`
+
+**VO**: `Path 参数 → GroupBatchRequirementCheckRespVO`
+
+#### 使用场景
+
+管理后台在点「整体确认需求」**之前**调用，用于把按钮置灰并把缺失清单摊开给运营看。它与 `POST .../requirement/confirm` 共用同一套校验：预检里出现的每一条，都会在确认时以对应错误码抛出且**零写入**。鉴权走 `group-batch:demand:confirm`。本次改动新增了车侧的户级校验，并改写了车侧 `detail` 的文案。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long | ✅ | 雪花 ID，团期聚合主键 | 团期 ID；无 Query、无 Body |
+
+#### 出参 `Result<GroupBatchRequirementCheckRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data.groupBatchId | String | 团期聚合主键 |
+| data.batchStatus | String | 团期当前状态码 |
+| data.batchStatusName | String | 团期状态中文名；`batchStatus` 为 `null` 时为 `null` |
+| data.ready | Boolean | 是否可整体确认：`missing` 空 **且** `vehicleMissing` 空 **且**阶段可确认。`missing` 空而 `ready=false` 时原因在 `vehicleMissing` |
+| data.missing[] | Array | 住宿缺失清单，按 orderId 升序，每户至多一条 |
+| data.missing[].orderId | String | 子订单 ID |
+| data.missing[].orderNo | String | 子订单号 |
+| data.missing[].customerName | String | 客户姓名 |
+| data.missing[].consultantId | String | 定制师 adminId（字符串，便于拼跳转） |
+| data.missing[].consultantName | String | 定制师姓名快照 |
+| data.missing[].reason | String | 住宿缺失原因码，见六.5 |
+| data.missing[].reasonName | String | 住宿缺失原因中文名 |
+| data.missing[].dayNumber | Integer | 第几天；无该维度时 `null` |
+| data.missing[].segmentIndex | Integer | 段序；无该维度时 `null` |
+| data.missing[].expectedNights | Integer | 期望晚数；无该维度时 `null` |
+| data.missing[].actualNights | Integer | 实际晚数；无该维度时 `null` |
+| data.checkedResourceTypes | Array | 本次预检覆盖的资源类型，恒为 `["HOTEL","VEHICLE"]`；两类均已覆盖到逐户粒度 |
+| data.vehicleWaived | Boolean | 整团免车时为 `true`，此时车侧校验整体跳过、`vehicleMissing` 恒为空数组 |
+| data.vehicleMissing[] | Array | 车侧缺失清单，按校验顺序全部列出、不按户合并；`vehicleWaived=true` 时为空数组 |
+| data.vehicleMissing[].reason | String | **本次扩充**：车侧缺失原因码，新增 `HOUSEHOLD_REQUIREMENT_NOT_SUBMITTED`，见六.5 |
+| data.vehicleMissing[].groupCode | String | 涉及的乘车分组编码；无分组维度时 `null` |
+| data.vehicleMissing[].tripDate | String | 涉及日期（`yyyy-MM-dd`）；无日期维度时 `null` |
+| data.vehicleMissing[].orderId | String | 涉及的子订单 ID；无订单维度时 `null` |
+| data.vehicleMissing[].orderNo | String | 子订单号快照；订单不属于本团期时 `null` |
+| data.vehicleMissing[].detail | String | **本次报文变更**：人话描述，与整团确认抛出的错误报文逐字相同，可直接展示；户级条目不再带雪花 orderId |
+| data.groupVehicleRequirementId | String | 当前活跃正式用车需求主键；无则 `null` |
+| data.groupVehicleRequirementStatus | String | 活跃正式用车需求状态；无则 `null`。`DISPATCHED` / `DONE` 同属预检可通过的正常状态 |
+| data.groupVehicleRequirementVersion | Integer | 活跃正式用车需求版本号；无则 `null` |
+| data.transferSubmitEnabled | Boolean | 当前环境是否开放接送机需求提交；`false` 时提交 `kind=TRANSFER` 会被 809004 拒 |
+| data.transferDeclaredWithoutRequirement[] | Array | 声明了接送机却没报 TRANSFER 需求的户（提示性，不进 `ready`、不阻断确认）；无此类户时为空数组、不是 `null` |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch/2100856430494973953/requirement/confirm-check HTTP/1.1
+Host: <网关地址>
+Authorization: Bearer <admin token>
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "groupBatchId": "2100856430494973953",
+    "batchStatus": "RESOURCE_PREPARING",
+    "batchStatusName": "资源准备中",
+    "ready": false,
+    "missing": [
+      {
+        "orderId": "2102309919002943489",
+        "orderNo": "HL20260922161158291",
+        "customerName": "王二麻子",
+        "consultantId": "2083111674486693889",
+        "consultantName": "刘畅",
+        "reason": "NOT_SUBMITTED",
+        "reasonName": "未提报",
+        "dayNumber": null,
+        "segmentIndex": null,
+        "expectedNights": null,
+        "actualNights": null
+      }
+    ],
+    "checkedResourceTypes": ["HOTEL", "VEHICLE"],
+    "vehicleWaived": false,
+    "vehicleMissing": [
+      {
+        "reason": "GROUP_REQUIREMENT_NOT_FOUND",
+        "groupCode": null,
+        "tripDate": null,
+        "orderId": null,
+        "orderNo": null,
+        "detail": "团期「第3期 10月8日出发团」尚未形成正式用车需求"
+      },
+      {
+        "reason": "HOUSEHOLD_REQUIREMENT_NOT_SUBMITTED",
+        "groupCode": null,
+        "tripDate": null,
+        "orderId": "2102309919002943489",
+        "orderNo": "HL20260922161158291",
+        "detail": "该户尚未提交行程用车需求，请先让定制师提交后再整团提交车务"
+      }
+    ],
+    "groupVehicleRequirementId": null,
+    "groupVehicleRequirementStatus": null,
+    "groupVehicleRequirementVersion": null,
+    "transferSubmitEnabled": true,
+    "transferDeclaredWithoutRequirement": []
+  },
+  "traceId": null,
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+需求齐备、可以整体确认时，两份清单都是空数组（不是 `null`），`ready` 为 `true`；字段集与上例完全相同：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "groupBatchId": "2100856430494973953",
+    "batchStatus": "RESOURCE_PREPARING",
+    "batchStatusName": "资源准备中",
+    "ready": true,
+    "missing": [],
+    "checkedResourceTypes": ["HOTEL", "VEHICLE"],
+    "vehicleWaived": false,
+    "vehicleMissing": [],
+    "transferDeclaredWithoutRequirement": []
+  },
+  "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` **不按户合并、不短路**：团级的 `GROUP_REQUIREMENT_NOT_FOUND` 与户级的 `HOUSEHOLD_REQUIREMENT_NOT_SUBMITTED` 会同时出现（实测响应即如此）。前者说「团级需求没形成」，后者说「是谁挡着它形成」，两条的处置对象不同，都要渲染出来。
+- 区分条目是团级还是户级的唯一结构化判据是 `orderId` / `orderNo` 是否为 `null`，**不要靠解析 `detail` 文本**。户级条目恒带 `orderId` 与 `orderNo`。
+- `missing` 为空但 `ready=false` 时，原因一定在 `vehicleMissing`；`vehicleWaived=true` 时车侧整体跳过，`vehicleMissing` 恒为空数组，这是合法逃生口不是异常。
+- `transferDeclaredWithoutRequirement` 是提示性名单，不进 `ready`、不阻断确认，也不并进 `vehicleMissing`；`transferSubmitEnabled=false` 时这份名单**照报**，此时该提示「当前环境未开放接送机需求提交」而不是隐藏名单。
+- 预检通过不等于确认一定成功：确认时的 CAS 冲突（809101 / 809112）只在写入阶段才可能发生，整团回滚、零写入。
+
+---
+
+## 四、契约约束与正确调用方式
+
+> 本节只写**后端返回什么、前端据什么判定**，不写 UI 渲染建议。
+
+### ✅ 正确 / ❌ 错误的判定写法
+
+| 场景 | 判定写法 |
+|------|----------|
+| ✅ 判「该户没提交房需求」 | `hotelRequirementStatus === null && hotelRequirementStatusName === '未提交'`，或直接 `hotelRequirementStatus == null` |
+| ✅ 判「该户不需要房」 | `hotelRequirementStatus == null && hotelRequirementStatusName == null` |
+| ✅ 渲染状态列 | `statusName ?? status ?? '—'`（三级兜底，`null` 安全） |
+| ❌ 判「没提交」用 `status === 'PENDING'` | `PENDING` 现在唯一含义是「已提交、等资源侧接单」，这样写会把真正在排队的户也算成未提交 |
+| ❌ 从 `vehicleMissing[].detail` 里正则抠订单号 | 报文已改写，户级条目的 `detail` 里不再有 ID；订单号读 `vehicleMissing[].orderNo` |
+| ✅ 判车侧缺失条目是团级还是户级 | `item.orderId == null` → 团级（跳去团级用车需求编辑）；否则户级（跳到该子订单） |
+| ❌ 假设 `vehicleMissing` 至多一条 | 团级与户级条目会并列出现，数组长度可以大于 1 |
+
+### 报文变更涉及的调用口
+
+下列写口在失败时抛出的 `message` 与预检 `detail` 同源，本次一起改变；它们的**请求契约、字段名、错误码码值都没有变**，变的只是给人看的那段文本：
+
+| 方法 | 路径 | 涉及错误码 | 弹窗场景 |
+|------|------|-----------|----------|
+| POST | `/v3/admin/order/group-batch/{groupBatchId}/requirement/confirm` | 809100 / 809103-809110 / 809122 / 809007 | 点「整体确认需求」，车侧不过时弹第一条违规的报文（零写入） |
+| PUT | `/v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement` | 809107 / 809108 / 809109 / 809115 | 保存/提交乘车分组被校验拒绝 |
+| POST | `/v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement/waive` | 809114 | 声明整团免车时车务已开工被拒 |
+| GET | `/v3/admin/order/group-batch/{groupBatchId}/requirement/confirm-check` | 同上全部 | 预检横幅里的 `vehicleMissing[].detail` |
+
+---
+
+## 五、数据库行为
+
+本次两个变更接口都是只读端点，**零写入**。
+
+| 前端动作 | 写库行为 |
+|----------|----------|
+| 调 `GET .../orders` | 无 |
+| 调 `GET .../requirement/confirm-check` | 无 |
+| 调 `POST .../requirement/confirm` 且车侧校验不过（含新增的 809122） | 无：阶段守卫 → 住宿缺失（589533）→ 车侧校验的顺序全部排在任何写入之前，抛出即整笔事务零写入 |
+
+新增的 809122 不引入任何新表、新列、新状态值；它是对既有「该户有没有 active 行程用车需求行」的一次查询结果的表达。
+
+---
+
+## 六、边界行为
+
+- 未登录 → 401（网关拦截，不进业务码集）。
+- 团期不存在 → HTTP 200 + `code=589500`。
+- 无权限 / 团期不在本人名下 → HTTP 200 + `code=589507`。
+- 老数据兼容：历史上没有 active 需求行的户，改前读出 `"PENDING"`、改后读出 `null`，**存量数据不迁移**，同一条记录在两个版本上读数不同，差异来自读取时的回落逻辑而非库里的值。
+- 枚举外未知状态码：`*StatusName` 回落原 code，不抛异常、不返空串。
+- 该户不需要房 / 不需要车时，对应的 `*Status` 与 `*StatusName` **都**是 `null`，前端渲染「—」。
+- `vehicleMissing` 与 `transferDeclaredWithoutRequirement` 在「一条都没有」时是空数组，不是 `null`。
+
+---
+
+## 六.5、枚举 / 数据字典
+
+### hotelRequirementStatus / vehicleRequirementStatus（RequirementStatus）
+
+**所属字段**: `GroupBatchOrderItemRespVO.hotelRequirementStatus` / `.vehicleRequirementStatus` | **类型**: `String`
+
+| 值 | 中文（房 / 车） | 说明 |
+|----|------|------|
+| `null` | 未提交 / `null` | **本次新增取值**：该户没有 active 需求行。该户需要这项资源 → `*StatusName` 为「未提交」；不需要 → `*StatusName` 也是 `null` |
+| `PENDING` | 待房务配 / 待车队配 | 已提交并放行，等资源侧接单 |
+| `PROCESSING` | 配房中 / 配车中 | 资源侧处理中 |
+| `DONE` | 配房完成 / 配车完成 | 资源侧完成 |
+| `PENDING_REVIEW` | 待审核 / 待提交车务 | 定制师已报、等管理员动作；车侧本列恒为行程用车（TRAVEL），故用「待提交车务」（#8218） |
+| `REJECTED_TO_CONSULTANT` | 已驳回定制师 | 打回定制师重提 |
+| `REJECTED_TO_ADMIN` | 已驳回管理员 | 打回管理员 |
+
+### vehicleMissing[].reason（车侧缺失原因）
+
+**所属字段**: `GroupBatchRequirementCheckRespVO.VehicleMissingItem.reason` | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `GROUP_REQUIREMENT_NOT_FOUND` | 团级正式用车需求未形成 | 809100；团级维度，`orderId` / `orderNo` 为 `null` |
+| `GROUP_REQUIREMENT_STATUS_INVALID` | 团级需求状态不允许确认 | 809101 |
+| `NO_GROUP` | 至少要提交一个乘车分组 | 809103 |
+| `GROUP_CODE_INVALID` | 乘车分组编码重复或改名 | 809104 |
+| `DAY_OUT_OF_GROUP_RANGE` | 逐日行不在本组服务日范围内 | 809105 |
+| `DAY_GAP_IN_GROUP_RANGE` | 缺某日的逐日用车人数 | 809106 |
+| `MEMBER_FOREIGN_ORDER` | 成员子订单不属于本团期 | 809107 |
+| `MEMBER_DUPLICATE_DAY` | 同一户同一日落在两个分组 | 809108 |
+| `ORDER_DAY_UNCOVERED` | 某子订单某日没有被任何分组覆盖 | 809109 |
+| `HEADCOUNT_LESS_THAN_MEMBERS` | 逐日用车人数小于当日成员户数 | 809110 |
+| `HOUSEHOLD_REQUIREMENT_NOT_SUBMITTED` | 该户尚未提交行程用车需求 | **本次新增**，809122；户级维度，恒带 `orderId` / `orderNo`；处置是催该户定制师提交 |
+| `TRANSFER_SERVICE_DATES_NOT_BACKFILLED` | 待放行接送机需求未回填服务日 | 809007；只带 `orderId` |
+
+### missing[].reason（住宿缺失原因）
+
+**所属字段**: `GroupBatchRequirementCheckRespVO.MissingItem.reason` | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `NOT_SUBMITTED` | 未提报 | 该户需房但没有 active 房需求行（含被打回后未重提） |
+| `ROOM_CATEGORY_MISSING` | 缺房型 | 需求行存在但房型行缺失 |
+| `INVALID_REQUIREMENT` | 需求结构不合法 | days 结构不可用 |
+| `NIGHTS_MISMATCH` | 晚数不符 | 实际晚数与期望晚数不一致 |
+| `DAY_NUMBER_INVALID` | 天序不合法 | dayNumber 越界或重复 |
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 |
+|------|------|------|
+| `GroupBatchOrderItemRespVO.hotelRequirementStatus` | 无 active 房需求行时回落 `"PENDING"` | 无 active 行时为 `null` |
+| `GroupBatchOrderItemRespVO.hotelRequirementStatusName` | 相应显示「待房务配」 | code 为 `null` 时：该户需房 → `"未提交"`；不需房 → `null` |
+| `GroupBatchOrderItemRespVO.vehicleRequirementStatus` | 无 active 车需求行时回落 `"PENDING"` | 无 active 行时为 `null` |
+| `GroupBatchOrderItemRespVO.vehicleRequirementStatusName` | 相应显示「待车队配」 | code 为 `null` 时：该户需车 → `"未提交"`；不需车 → `null` |
+| `GroupBatchRequirementCheckRespVO.vehicleMissing[].reason` | 11 个取值 | 追加 `HOUSEHOLD_REQUIREMENT_NOT_SUBMITTED`，共 12 个 |
+| `GroupBatchRequirementCheckRespVO.checkedResourceTypes` | 值仍是 `["HOTEL","VEHICLE"]`，但车侧只覆盖团级 | 值不变；车侧实际覆盖扩到逐户（这是把字段宣称的覆盖补齐，不是取值变化） |
+
+### 报文变更（六个错误码的渲染文本）
+
+| 错误码 | 改前渲染 | 改后渲染 |
+|--------|----------|----------|
+| 809100 | `团期 2100856430494973953 尚未形成正式用车需求` | `团期「第3期 10月8日出发团」尚未形成正式用车需求`；团期名与期号快照都缺时为 `该团期尚未形成正式用车需求` |
+| 809107 | `子订单 2102309919002943489 不属于本团期，不能作为乘车成员` | `该子订单不属于本团期，不能作为乘车成员` |
+| 809108 | `子订单 2102309919002943489 在 2026-10-09 同时属于分组 BUS、SUV，同一户同一日只能属于一个分组` | `该子订单在 2026-10-09 同时属于分组 BUS、SUV，同一户同一日只能属于一个分组` |
+| 809109 | `子订单 2102309919002943489 的 2026-09-13 没有被任何乘车分组覆盖` | `该子订单的 2026-09-13 没有被任何乘车分组覆盖` |
+| 809114 | `车务已开工（团期 2100856430494973953：团级配车已就绪）` / `车务已开工（子订单 2102309919002943489：用车需求已到 DISPATCHED）` | `车务已开工（团期「第3期 10月8日出发团」：团级配车已就绪）` / `车务已开工（子订单 HL20260922161158291：用车需求已到 DISPATCHED）`；取不到订单号时为 `某子订单` |
+| 809115 | `团期 2100856430494973953 已声明整团免车，提交乘车分组前请先整份撤回（withdraw）回草稿` | `团期「第3期 10月8日出发团」已声明整团免车，提交乘车分组前请先整份撤回（withdraw）回草稿` |
+
+**码值一个都没变**，变的只是 `message` / `detail` 的文本。809107 / 809108 / 809109 是直接删掉标识符：这三条只出现在预检清单上，而清单行已经由 `orderNo` 字段结构化带了订单号，文本里再带一个雪花 ID 就是同一行上的第二个标识符。809114 保留标识符只把 ID 换成订单号：它只落在免车声明弹窗上，弹窗外没有第二处说明是哪一户。
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| 团里有户一条需求都没提交时的列表显示 | 「待房务配 / 待车队配」（与同屏预检横幅的「未提报」矛盾） | 「未提交」 |
+| 车侧预检对「某户一行行程用车需求都没提交」 | 无任何表达位置，整团确认只报团级的 809100 | `vehicleMissing` 里多一条 809122，带 `orderId` / `orderNo` |
+| 团级缺席时是否还检查户级 | 团级缺席即返回，不再往下查 | 两层并列输出，团级缺席不短路户级 |
+| 整团确认在户级未提交时的结果 | 报 809100（运营据此去催车务，方向错了） | 报 809122（催该户定制师提交），零写入 |
+| 车务报文里的标识符 | 雪花 ID | 团期可读名称 / 订单号 / 直接省略 |
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 是（部分）。`*Status` 新增 `null` 取值；对 `detail` / `message` 做文本匹配或抠 ID 的逻辑会失效。字段名、字段数量、错误码码值、请求契约均未变。
+- **前端是否必须同步上线**: 否。已核对 `hl-ui origin/v2.1` 的 `src/views/order-v2/batch/detail/components/RequirementTab.vue`：状态列渲染为 `r.hotelRequirementStatusName || r.hotelRequirementStatus || '—'`（`:812-814`），对 `null` 安全；车侧缺失清单按 `item.orderNo` 是否存在分流（`:654` `vehicleReqMissing`、`:708-714` `onVehicleMissingClick`），809122 条目带 `orderNo`，会被正确归为户级并跳到该子订单。当前前端不改也能正确工作。
+- **前端 workaround 清理点**: 若页面上有「把 `PENDING` 当作未提交」的本地兜底判断，可以撤掉——后端现在用 `null` 表达「未提交」，语义是唯一的。
+- **风险面**: 唯一需要人工确认的是「是否存在对 `vehicleMissing[].detail` 做字符串解析的代码」。上述两个消费点都只做原样展示，未发现解析逻辑。
+
+## 七、不影响范围
+
+- **仅影响**: 管理后台「团期详情 → 查看需求」tab 的子订单状态列、整团确认预检横幅、车务相关弹窗文案。
+- **零影响**:
+  - 小程序端（mp）全部接口：本次改动只落在 `/v3/admin/` 前缀下。
+  - `GET /v3/admin/order/group-batch/{groupBatchId}/requirement-summary`（用房·汇总 / 用车·汇总）：字段与取值一个没动。该页此前的「汇总加载失败」已定位为前端同 tick 重复请求被去重拦截器 abort 所致，mmg 已在 `hl-ui 4b33ccbd9` 修复并已在测试环境前端 dist 里（`2026-09-23 18:06` 构建），与本次后端改动无关。
+  - 房需求的提交 / 打回 / 放行链路：`missing[]` 的口径、589533 的触发条件与报文一律不变。
+  - 接送机（TRANSFER）相关：`transferSubmitEnabled`、`transferDeclaredWithoutRequirement`、809007 的语义与取值不变。
+  - 订单列表 / 订单详情 / 金额相关接口：未触及。
+  - 历史数据：存量不迁移；差异只来自读取时的回落逻辑。
+  - 数据库：无 DDL、无 Flyway 脚本、无新列。
+
+---
+
+## 八、测试环境已验证
+
+部署：`hl-order-service-v3` @ `dev-v3` `fc81fff1f`，jar 构建时间 `2026-09-23 18:36:51`，两个实例（8086 / 8186）均 UP。以下读数经网关实测：
+
+```
+GET /v3/admin/order/group-batch/2100856430494973953/orders
+  → 200；26-2355（HL20260922161158291）hotelRequirementStatus=null / StatusName=未提交，
+    vehicleRequirementStatus=null / StatusName=未提交 ✓
+  → 200；26-7060（HL20260918155619496）hotelRequirementStatus=PENDING_REVIEW / 待审核，
+    vehicleRequirementStatus=PENDING_REVIEW / 待提交车务（无回归）✓
+
+GET /v3/admin/order/group-batch/2100856430494973953/requirement/confirm-check
+  → 200；vehicleMissing 里 GROUP_REQUIREMENT_NOT_FOUND 与
+    HOUSEHOLD_REQUIREMENT_NOT_SUBMITTED 两条同时出现（未被团级缺席短路）✓
+  → 809100 的 detail 已是「团期「第3期 10月8日出发团」尚未形成正式用车需求」（无雪花 ID）✓
+  → 809122 的条目带 orderId=2102309919002943489 / orderNo=HL20260922161158291 ✓
+  → checkedResourceTypes=["HOTEL","VEHICLE"]、vehicleWaived=false、ready=false ✓
+
+GET /v3/admin/order/group-batch/2100856430494973953/requirement-summary
+  → 200 × 3 次（3.56s / 2.11s / 2.55s），服务端日志零 ERROR / Exception ✓
+```
+
+验证团期: `groupBatchId=2100856430494973953`（第3期 10月8日出发团，2 户活跃子订单）
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#8249](https://git.1814.love:8443/wx/HL/issues/8249)
+- 关联 PR: [wx/HL#8286](https://git.1814.love:8443/wx/HL/pulls/8286)
+- 同页状态文案的上一次分叉（`PENDING_REVIEW` 车侧按 kind 分叉）: `changelogs-v2/2026-09/23_8218_行程用车状态文案按kind分叉-修改接口-管理后台.md`
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8249](https://git.1814.love:8443/wx/HL/issues/8249)
+- **PR**: [#8286](https://git.1814.love:8443/wx/HL/pulls/8286)
+- **Merge commit**: [fc81fff1f](https://git.1814.love:8443/wx/HL/commit/fc81fff1fd21e4a002c417041ed3fbb5bc2ce96a)
+
+### 联系人
+
+- **后端负责人**: @wx
@@ -0,0 +1,400 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8252"
+title: "订单列表新增团期关键词筛选，团单行新增团期名与期次展示字段"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "5f27c0094745c60cde7de866bb3450eee61fd91d"
+target_release: ""
+verified_at: "2026-09-23"
+status_note: "GET /v3/admin/order 新增入参 groupBatchKeyword（长度上限 64），出参 OrderListItemRespVO 新增 groupBatchName 与 groupBatchLabel。前端需在订单列表增加团期关键词筛选，并在团单行产品名后渲染「第N期 团期名」，故 frontend_status 记 pending。前端已交付(2026-09-23):列表头新增「团期」关键词输入框原样透传 groupBatchKeyword(maxlength 64 输入侧截断;清空省略=不传;六页签计数同口径透传);ProductCell 产品名后渲染「第N期 团期名」,label/name 逐段 trim 判空省略、全空整行不渲染,判团单仍用 groupOrder/groupBatchId。新建 spec 8 例+存量 6 例回归全绿,checkpoint 全量含生产构建通过。"
+updated_at: "2026-09-23"
+base: "dev-v3"
+---
+
+# 订单列表团期筛选与团单行团期展示（管理后台）
+
+> **服务**: hl-order-service-v3
+> **PR**: #8261
+> **Issue**: #8252
+> **日期**: 2026-09-23
+> **合并提交**: b6e84bdd9
+> **影响范围**: 管理后台订单列表的筛选条件（新增团期关键词）与团单行展示（新增团期名 + 期次）
+
+---
+
+## 一、接口背景
+
+订单列表原本只支持按 `groupBatchId` 筛团期，而那是 19 位雪花 ID：运营在团期看板上看到的是「第3期 10月8日出发团」这样的文案，
+记不住、也没法粘贴到订单列表去筛。团期看板自己支持按团期名 / 期次搜索，订单列表不支持，同一句话在两个页面搜出不同结果。
+
+本次给订单列表补上同样口径的团期关键词筛选，并把团期名与期次直接补到团单行上，运营从看板跳到订单列表后能直接看到自己在看哪个团期。
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|---|---|---|---|---|
+| 1 | 管理后台订单列表 | GET | `/v3/admin/order` | 修改接口 | 入参新增 `groupBatchKeyword`；出参 `OrderListItemRespVO` 新增 `groupBatchName` 与 `groupBatchLabel`；其余入参、其余出参、权限码、错误码均未变 |
+
+> 同一个 Controller 方法同时挂载集合根与 `/v3/admin/order/list` 两条路径（`@GetMapping({"", "/list"})`），
+> 两个地址的入参、出参、错误码、数据权限完全一致，本条目统称「订单列表接口」。
+
+## 三、接口详情
+
+### 1. 管理后台订单列表 `GET /v3/admin/order`
+
+**VO**: `OrderListItemRespVO`
+
+#### 使用场景
+
+管理后台「订单管理」列表页：首次进入、翻页、切换六个页签、修改任意筛选项时调用。
+本次与该页相关的两件事：列表头部新增「团期」关键词输入框（按团期名 / 期次 / 团号搜）。
+团单行的产品名后面渲染「第N期 团期名」，数据由本接口出参的 `groupBatchName` 与 `groupBatchLabel` 提供。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| groupBatchKeyword | Query | String | 否 | 长度 ≤64；全角空格与 NBSP 归一后为空串等同不传；groupBatchId 非空时本参数被忽略 | **本次新增**。团期关键词：按「团号模糊 ∪ 团期名模糊 ∪ 期次精确」解析出命中的团期后，只返回挂在这些团期下的订单。支持照抄页面渲染的文案，如 `第3期 10月8日出发团`。非空时强制按团单口径筛（等价于 orderKind=GROUP） |
+| groupBatchId | Query | Long | 否 | 19 位正整数 | 运营团期 ID（既有字段，本次未改）。非空时本参数优先：groupBatchKeyword 被忽略，且强制按团单口径筛 |
+| orderKind | Query | String | 否 | ALL / GROUP / NORMAL；缺省 NORMAL | 订单归属类型（既有字段，本次未改）。传了 groupBatchId 或非空 groupBatchKeyword 时，本参数被后端的团期口径覆盖为 GROUP |
+| pageNo | Query | Integer | 否 | ≥1，缺省 1 | 页码（既有字段）。等价别名 page，两者写哪个都生效 |
+| pageSize | Query | Integer | 否 | 1~100，缺省 20 | 每页条数（既有字段） |
+| statusGroup | Query | String | 否 | ALL / BEFORE_TRIP / ON_TRIP / SETTLEMENT / ABNORMAL / AFTERSALE | 页签分组（既有字段）。与 orderStatus 下拉为 AND 关系 |
+| orderStatus | Query | String | 否 | PENDING_PAY / CUSTOMIZING / PENDING_DEPARTURE / TRAVELLING / COMPLETED / CANCELLED，多值用逗号 | 粗状态过滤（既有字段） |
+| flowStatus | Query | String | 否 | 细状态枚举，多值用逗号 | 细状态过滤（既有字段） |
+| keyword | Query | String | 否 | 无 | 通用关键词：团号 / 客户姓名 / 产品名 / 订单号 任一 LIKE（既有字段，与本次的团期关键词是两个独立参数） |
+| tagNames | Query | List&lt;String&gt; | 否 | 多标签 OR，任一命中即返 | 标签过滤（既有字段） |
+| consultantName | Query | String | 否 | LIKE 匹配 | 定制师姓名（既有字段） |
+| departureDateFrom | Query | Date | 否 | yyyy-MM-dd | 出发日期区间起（既有字段） |
+| departureDateTo | Query | Date | 否 | yyyy-MM-dd，早于起日返 100001 | 出发日期区间止（既有字段） |
+| createSource | Query | String | 否 | CONSULTANT / CUSTOMER / 其他来源枚举 | 订单来源过滤（既有字段） |
+| cancelled | Query | Boolean | 否 | 缺省 false | 是否包含已取消订单（既有字段） |
+
+#### 出参 `Result<PageResult<OrderListItemRespVO>>`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| records | Array | 订单行列表，元素结构见下方「行内字段」 |
+| total | Integer | 命中总条数（不受 pageSize 影响） |
+| page | Integer | 当前页码 |
+| pageSize | Integer | 每页条数 |
+| records[].groupBatchName | String | **本次新增**。团期名称快照（取自下方「业务边界」所述的下单时快照口径）。非团单与团期已软删（解散）两种情况均为 null，不返空串 |
+| records[].groupBatchLabel | String | **本次新增**。期次序号裸数字串，如 `"3"`，不含「第」「期」二字，由前端拼成「第3期」。存量未刷新快照的团期可能为 null |
+| records[].groupBatchId | Long | 既有字段，本次未改。运营团期 ID（JSON 中为字符串）。非空即团单，这是判别团单的唯一依据 |
+| records[].groupOrder | Boolean | 既有字段，本次未改。是否团单，与 groupBatchId 同源（groupBatchId != null 的派生值） |
+| records[].productName | String | 既有字段，本次未改。产品名快照。「第N期 团期名」渲染在产品名之后 |
+| records[].orderNo | String | 既有字段，本次未改。订单号（创单瞬间生成，永不变） |
+| records[].id | Long | 既有字段，本次未改。订单 ID（JSON 中为字符串） |
+| records[].customerName | String | 既有字段，本次未改。客户姓名 |
+| records[].departureDate | Date | 既有字段，本次未改。出发日，未定日期时为 null |
+| records[].orderStatus / orderStatusName | String | 既有字段，本次未改。粗状态枚举值与中文名 |
+| records[].flowStatus / flowStatusName | String | 既有字段，本次未改。细状态枚举值与中文名 |
+| records[].totalAmount / payableAmount / paidAmount / refundAmount / balanceAmount | BigDecimal | 既有字段，本次未改。金额在 JSON 中为字符串 |
+| records[].consultantName | String | 既有字段，本次未改。定制师姓名 |
+
+> 单行 VO 本次从 44 个字段变为 46 个：新增 `groupBatchName`、`groupBatchLabel`，其余 44 个字段逐字未变。
+
+#### 请求示例
+
+```http
+GET /v3/admin/order?pageNo=1&pageSize=20&orderKind=ALL&groupBatchKeyword=%E7%AC%AC3%E6%9C%9F+10%E6%9C%888%E6%97%A5%E5%87%BA%E5%8F%91%E5%9B%A2 HTTP/1.1
+Host: api.test.1814.love
+Authorization: Bearer <admin token>
+Accept: application/json
+
+# 无请求体。
+# 关键词解码后为「第3期 10月8日出发团」；等价别名地址：GET /v3/admin/order/list（参数与响应逐字一致）。
+# 只按团期名筛：GET /v3/admin/order?pageNo=1&pageSize=20&groupBatchKeyword=%E4%BA%91%E5%8D%97
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "records": [
+      {
+        "id": "2102309919002943489",
+        "orderNo": "HL20260922161158291",
+        "teamNo": "26-2355",
+        "productName": "王骁测试团期产品",
+        "productType": "GROUP",
+        "productTypeName": "小蒙马",
+        "productCoverImg": "https://hlgl-test.oss-cn-beijing.aliyuncs.com/test/material/2026/03/07/ed278d1da74c3827cb06b7f0cf6091fe.jpg",
+        "tierName": "轻奢",
+        "customerName": "王二麻子",
+        "customerPhoneMasked": "185****0000",
+        "peopleSummary": "4 大",
+        "departureDate": "2026-10-08",
+        "tripDays": 3,
+        "tripNights": 2,
+        "orderStatus": "CUSTOMIZING",
+        "orderStatusName": "定制中",
+        "flowStatus": "AWAITING_PROFILE",
+        "flowStatusName": "待补全信息",
+        "flowStep": 1,
+        "flowStepTotal": 6,
+        "flowStepCode": "PROFILE",
+        "flowStepName": "补全信息",
+        "currentSubFlows": null,
+        "totalAmount": "15920.00",
+        "payableAmount": "15920.00",
+        "paidAmount": "2000.00",
+        "refundAmount": "0.00",
+        "balanceAmount": "13920.00",
+        "consultantName": "刘畅",
+        "createSource": "CONSULTANT",
+        "createSourceLabel": "定制师创建",
+        "tags": [],
+        "createdAt": "2026-09-22 16:11:58",
+        "depositAmount": "2000.00",
+        "depositRatio": null,
+        "paymentMode": "DEPOSIT",
+        "singleRoomSurcharge": "0.00",
+        "agencyId": "2051922156798779394",
+        "refundPolicyId": "2047249965792579585",
+        "productSubtitle": "发短信给对方搞定",
+        "aftersaleStatus": "NONE",
+        "aftersaleStatusName": "无售后",
+        "groupBatchId": "2100856430494973953",
+        "groupOrder": true,
+        "groupBatchName": "10月8日出发团",
+        "groupBatchLabel": "3"
+      }
+    ],
+    "total": 2,
+    "page": 1,
+    "pageSize": 5
+  },
+  "traceId": null,
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+两种空值形态语义不同，前端要分别处理。
+
+其一：关键词没有任何命中团期时，接口返 200 与空页（`records: []`、`total: 0`），同时六个页签的计数一并归零——列表数字与页签数字不会各说各话。
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "records": [],
+    "total": 0,
+    "page": 1,
+    "pageSize": 5
+  },
+  "traceId": null,
+  "success": true
+}
+```
+
+其二：行本身存在，但该行拿不到团期信息。非团单行、以及团期已软删（解散）的团单行，`groupBatchName` 与 `groupBatchLabel` 都是 `null`（不是空串）。
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "records": [
+      {
+        "id": "2097270761474469890",
+        "orderNo": "HL20260908182809530",
+        "productName": "测试小蒙马-多档-固定金额",
+        "orderStatus": "CUSTOMIZING",
+        "groupBatchId": "2097270759599616002",
+        "groupOrder": true,
+        "groupBatchName": null,
+        "groupBatchLabel": null
+      }
+    ],
+    "total": 3,
+    "page": 1,
+    "pageSize": 5
+  },
+  "traceId": null,
+  "success": true
+}
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 100001,
+  "message": "团期关键词长度不能超过 64",
+  "data": null,
+  "traceId": null,
+  "success": false
+}
+```
+
+| 错误码 | 触发条件 |
+|---|---|
+| 100001 | groupBatchKeyword 超过 64 个字符（注意：不是 HTTP 400，是业务码 100001，HTTP 状态仍为 200） |
+| 100001 | groupBatchId 传了非数字（既有行为，本次未改） |
+| 100001 | pageNo 小于 1、pageSize 超出 1~100、orderKind 传非法值、出发日区间倒置 |
+| 401 | 未登录（网关拦截） |
+| 403 | 缺少管理端订单列表访问权限 |
+
+#### 业务边界
+
+- **团期名与期次都取自 order 侧快照**：`groupBatchName` / `groupBatchLabel` 读的是订单侧记录的团期快照，而团期看板展示的是 product 侧实时重算值；快照只在该团期有新订单进入时刷新，**两者可能不一致**。这是两个页面各自的既定口径，不是本接口的缺陷。
+- **`groupBatchLabel` 可能为 null**：存量未刷新的团期拿不到期次，此时只渲染团期名，**不得渲染「第null期」「第期」**。`groupBatchName` 同理，为 null 时整段不渲染。
+- **非团单与「团期已软删（解散）」两种情况下两字段均为 null**（不是空串）；若团期名本身是空字符串的脏数据，则返回 `""`，前端需按空文案处理而不是渲染出「第N期 」这样带空格残缺文案。
+- **软删团期的历史订单仍能按团单筛出来**（`groupOrder=true`、`groupBatchId` 非空），只是团期名与期次为 null——这是既定行为，前端不要据此把行判成普通订单。
+- **本接口的 `groupBatchName` 是团期名快照，与下单接口（订单创建响应）里那个恒为 null 的 `groupBatchName` 不是同一个语义**，不要把两个接口的字段名合并成同一个前端模型复用。
+- **关键词口径与团期看板一致**：团号 LIKE ∪ 团期名 LIKE ∪ 期次精确匹配，且支持「第3期 云南」这类复合输入（期次精确 AND 名称/团号模糊）。期次是精确匹配，「第1期」不会连带命中第 10、11、21 期。
+- **命中团期超过 500 个时结果被截断**（只取前 500 个团期对应的订单），属公开的失败模式：关键词过宽时 total 会偏小。
+- **命中为空时返回空页且六个页签计数同步为 0**；不传 `groupBatchKeyword` 时，本接口行为与本次改动前完全一致（含只传一个全角空格或 NBSP 的情况，逐项等同不传）。
+- **权限码零变化**：定制师等非管理员角色仍只看本人名下订单，权限口径与本次改动前逐字一致，访问本接口不会出现 589507。
+- **已知差异（契约边界）**：某些团期名本身形如「3期特惠」时，团期看板按整串匹配，而订单列表会把它解析成「期次 3 + 名称 特惠」，因此同一个输入在两个页面可能给出不同结果。
+
+## 四、契约约束与正确调用方式
+
+### ✅ 正确 / ❌ 错误 payload 对照
+
+| 场景 | 查询串 |
+|---|---|
+| ✅ 按团期名筛 | `groupBatchKeyword=10月8日出发团`，返回挂在该团期下的订单 |
+| ✅ 按期次筛 | `groupBatchKeyword=第3期`，期次精确匹配，不含第 10、11、21 期 |
+| ✅ 复合输入（照抄页面文案） | `groupBatchKeyword=第3期 云南深度8日`，拆成「期次 = 3」且「名称含 云南深度8日」 |
+| ✅ 只填一个全角空格 | `groupBatchKeyword=%E3%80%80`，等同于不传，行为与改动前逐项一致 |
+| ✅ 精确跳转（从团期看板带 ID 跳过来） | `groupBatchId=2100856430494973953` |
+| ❌ 两个参数都传且互不匹配 | `groupBatchId=<团期ID>&groupBatchKeyword=不存在的团期名` → 以 ID 为准，关键词被忽略 |
+| ❌ 关键词超过 64 字符 | 65 个字符 → 100001「团期关键词长度不能超过 64」 |
+| ❌ 把期次写成中文数字 | `groupBatchKeyword=第三期` → 不是期次形态，按团期名/团号整串模糊匹配，通常零命中 |
+
+### 前端渲染规则
+
+- 团单行文案 = 产品名 + 「第{groupBatchLabel}期 {groupBatchName}」，任一段为 null 或空串时该段整段省略，不要留下多余空格。
+- 判断一行是不是团单请继续读 `groupOrder` / `groupBatchId`，不要用 `groupBatchName != null` 反推（软删团期的团单两字段为 null）。
+- 筛选框可以同时展示「团期名」与「第N期」两种写法；提交时把用户输入原样传给 `groupBatchKeyword` 即可，后端负责解析。
+- 筛选框在提交前建议做一次前端长度校验（≤64），避免让用户提交后只拿到一个 100001。
+
+## 五、数据库行为
+
+零数据库变更。本次不新增表、列、索引或数据迁移，也不写入任何数据：
+`groupBatchKeyword` 的匹配是对既有团期数据的只读查询，出参两字段是对既有订单侧快照的只读回填，整页一次批量查询，不产生写操作。
+
+## 六、边界行为
+
+- 未登录 → 401（网关拦截）。
+- 无管理端权限 → 403。
+- `groupBatchKeyword` 超过 64 字符 → 业务码 100001，HTTP 状态仍是 200。
+- `groupBatchId` 传非数字 → 业务码 100001（既有行为）。
+- 关键词无命中团期 → 200 + 空页，且六个页签计数全为 0。
+- 班期 / 团期数据在 order 侧无快照（非团单、软删团期）→ 两个新字段为 null，不返空串。
+- 团期名本身是空字符串的脏数据 → 返回 `""`。
+- 排期区间倒置（departureDateFrom > departureDateTo）→ 100001。
+- pageSize 超过 100 → 100001。
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 |
+|---|---|---|
+| `OrderListReqVO.groupBatchKeyword` | 不存在 | 新增，String，≤64，Query 参数 |
+| `OrderListItemRespVO.groupBatchName` | 不存在（前端取到 undefined） | 返回团期名快照；非团单 / 软删团期为 null |
+| `OrderListItemRespVO.groupBatchLabel` | 不存在（前端取到 undefined） | 返回期次裸数字串，如 `"3"`；存量未刷新快照为 null |
+| 单行 VO 字段数 | 44 | 46 |
+| 其余 44 个出参字段 | — | 逐字未变 |
+| 其余 15 个入参字段 | — | 逐字未变（新增参数是新增项，不改既有字段语义） |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|---|---|---|
+| 按团期名 / 期次筛选 | 不支持，只能传 19 位 groupBatchId | 新增 groupBatchKeyword，口径与团期看板一致 |
+| 期次匹配方式 | — | 期次精确匹配（第1期不命中第 10、11、21 期） |
+| 两个团期参数同传 | 不存在第二个参数 | 以 groupBatchId 为准，关键词被忽略 |
+| 空白关键词 | — | 归一后为空等同于不传，行为与改动前逐项一致 |
+| 关键词无命中 | — | 空页 + 六页签计数全 0 |
+| 团单行展示 | 只有 groupBatchId / groupOrder | 追加 groupBatchName / groupBatchLabel 供渲染「第N期 团期名」 |
+| 权限码 / 数据权限 | 仅 ADMIN / SUPER_ADMIN 看全量，其余角色只看本人订单 | 逐字未变 |
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**：否。入参是新增的可选参数，出参是新增的可选字段；不传关键词、不读新字段的老调用方行为逐字未变。
+- **前端是否必须同步上线**：否，但需要适配：列表要加团期关键词筛选入口，团单行要渲染团期名 + 期次。老前端不改也不会报错，只是看不到本次的两个能力。
+- **性能**：团期关键词的匹配落在团期名 / 期次的模糊查询上，命中团期条数有 500 的上限，超过即截断；订单侧仍是既有的分页查询，团期名与期次按页一次批量回填，不会按行查询。
+- **前端 workaround 清理点**：若前端此前为了显示团期名而在列表页额外调用团期接口或按 groupBatchId 反查，可改用本接口的两个新字段；无此类逻辑则无需改动。
+- **回滚**：撤销 PR #8261 即可，无数据、无迁移、无配置残留。
+- **未覆盖**：本次只证明后端契约可用。页面上的筛选框与团期文案是否落位属前端实现侧；两个页面对同一输入的差异见「业务边界」末条。
+
+## 七、不影响范围
+
+- **仅影响**：管理后台订单列表（筛选条件 + 团单行字段）。
+- **零影响**：
+  - 团期看板的搜索口径与命中结果（本次只新增解析口，未改看板既有语义）
+  - 订单详情的团期四字段（batchNo / batchName / groupBatchStatus / groupBatchId）
+  - 下单接口（订单创建响应）的同名字段
+  - 六个页签计数的计算口径（关键词无命中时同步归零属既定一致行为）
+  - 权限码与数据权限收缩逻辑
+  - 小程序端：本接口仅管理后台使用，未涉及
+
+## 八、测试环境已验证
+
+部署：hl-order-service-v3 `dev-v3 @ b6e84bdd9`（PR #8261 合并提交），2026-09-23 16:23~16:24 滚动部署完成，两实例健康。
+验证入口：`https://api.test.1814.love`（经网关调用，非直连服务端口）。
+
+自动化验收脚本 19 项全部 PASS，摘要如下：
+
+| 用例 | 场景 | 结果 |
+|---|---|---|
+| AC-1 | 按团期名 `10月8日出发团` 筛 | 200，total=2，两行 groupBatchName 均为「10月8日出发团」 |
+| AC-2 | 按期次 `第3期` 筛 | 200，total=2，命中期次集合 = ['3']（精确，不含 10 / 13 / 23 / 30） |
+| AC-3 | 按期次 `第1期` 筛 | 200，total=13，命中期次集合 = ['1']（不含 10 / 11 / 21） |
+| AC-4 | 裸数字 `3` 筛 | 200，total=406；第3期的 2 单是其中子集 |
+| AC-5 | 复合输入 `第3期 10月8日出发团` | 200，total=2，期次 = ['3'] |
+| AC-6 | 无命中 `不存在的团期名ZZZ9` | 200，空页，total=0 |
+| AC-7 | 页签计数与列表同口径 | 命中时 ALL=2、其余页签 0；无命中时六个页签全 0 |
+| AC-8 | 只填空格 vs 完全不传 | total 同为 708，首行订单号逐字一致 |
+| AC-9 | 定制师身份（CUSTOMIZER） | 200 而非 589507；不带关键词时 total=19 且定制师列只含本人 |
+| AC-10 | 65 字符关键词 | 100001「团期关键词长度不能超过 64」 |
+| AC-11 | 只传 groupBatchId | 200，total=2 |
+| AC-12 | 两参同传 | 与只传 ID 同结果，orderNo 序列一致 |
+| AC-13 | 团期看板口径回归 | 三组关键词的命中团期集合与基线一致 |
+| AC-14 | 团单行展示字段 | orderNo=HL20260922161158291，groupBatchName=10月8日出发团，groupBatchLabel=3 → 可渲染「第3期 10月8日出发团」 |
+| AC-15 | 团单 300 行扫描 | 无空串残缺值；groupBatchLabel 为 null 的行数为 0 |
+| AC-17 | 普通单 220 行 | 两个新字段全部为 null（非空串） |
+| AC-18 | 同订单不同 pageSize 一致性 | pageSize=1 与 20 的 groupBatchName 一致；页级一次批量回填（单测 times(1)，逐行查询 never） |
+| AC-19 | 深翻页 | 第 2、3 页各 20 行均带团期名 |
+| AC-20 | 订单详情回归 | 团期四字段与基线逐字一致 |
+
+在此之上补一组经网关的真实请求取证，覆盖脚本未包含的软删场景：
+
+| 用例 | 场景 | 结果 |
+|---|---|---|
+| AC-16 | 团期已软删（解散）的历史订单，`groupBatchId=2097270759599616002` | 200，total=3；三行 groupOrder=true，groupBatchName 与 groupBatchLabel 均为 null |
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#8252](https://git.1814.love:8443/wx/HL/issues/8252)
+- 关联 PR: [wx/HL#8261](https://git.1814.love:8443/wx/HL/pulls/8261)
+- 团期看板关键词口径出处：#7942
+- 订单列表 groupBatchId 冻结契约出处：#7635
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8252](https://git.1814.love:8443/wx/HL/issues/8252)
+- **PR**: [#8261](https://git.1814.love:8443/wx/HL/pulls/8261)
+- **Merge commit**: [b6e84bdd9](https://git.1814.love:8443/wx/HL/commit/b6e84bdd9)
+
+### 联系人
+
+- **后端负责人**: @wx
@@ -0,0 +1,499 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8278"
+title: "团级用车分组座位充足性校验（809116）改为扣司机座，与子订单级/fleet 单车派车口径统一"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "not_required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "PR #8296 已合并 dev-v3（a0973867f）。部署：hl-order-service-v3 dev-v3 @ a0973867f，2026-09-23 21:09:02 部署，deploy-status 读数 BEHIND=0 STATE=ok，8086/8186 两实例 Nacos 健康。测试服网关真实 PUT 实测（groupBatchId=2102749115823919105，20 座大巴 × 2 辆，两次请求均晚于部署时刻）：headcount=40 时返回 809116（扣司机座后可载 38 人，不足 40）；headcount=38 时返回 200，remainingPassengerSeats=0。定向单测 mvn -o -pl hl-order-service-v3 -am test：17 个外层类 148/0/0（含 9 个 @ArchTest 载体），BUILD SUCCESS。存量影响核查（测试服只读 SELECT，2026-09-23 20:14:20）：活跃团级用车需求 131 个，其中带完整规格（seats/count 均非空）的分组 3 组，按新口径重算全部仍满足要求，按新口径会被拒的活跃分组数为 0；生产环境二期尚未开放，无生产存量。gateway_status: verified —— 路径本就在既有 /v3/admin/** order-service-v3 路由下，本次零路由改动，且已通过真实网关实测。；前端判 not_required:809116 全仓零文本/占位符解析(整句 toast+violations detail 直显);余座负值三处消费不 clamp 不拦截;spec 无刚好坐满放行预期"
+updated_at: "2026-09-23"
+base: "dev-v3"
+---
+
+# order-v3 团期需求: 团级用车分组座位充足性校验改为扣司机座
+
+> **存放目录**: 二期(v3) → `changelogs-v2/2026-09/`
+>
+> **服务**: hl-order-service-v3（团期需求域）
+> **PR**: #8296
+> **Issue**: #8278
+> **日期**: 2026-09-23
+> **影响范围**: 管理后台「团期详情 → 查看需求」Tab 的团级正式用车需求编辑弹窗、用车需求汇总草稿预览
+
+---
+
+## ⚠️ 关键变化（非必须,本版与上版行为不同 / 纠错 / 撤销时必写）
+
+- 本次变化：`PUT /v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement` 的 809116 座位充足性校验，判据从「座位数 × 车辆数 < 该组最大单日乘车人数」改为「(座位数 − 1) × 车辆数 < 该组最大单日乘车人数」——每辆车扣 1 个司机座，与子订单级用车需求校验、fleet 单车派车（`AssignmentService`）口径统一。
+- 前端以前以为的（对应 `22_8152_...` changelog 描述的旧行为）：座位数 × 车辆数刚好等于该组最大单日人数的分组能保存成功，例如 19 座 × 1 辆、最大日人数 19 能保存；同一响应体里 `remainingPassengerSeats`（余座回显）却是扣了司机座算出来的，可能已经是负数，前端只需原样展示负值提示缺口，不作为提交是否成功的依据。
+- 实际现在的行为：同样 19 座 × 1 辆、最大日人数 19 这组输入，现在直接被 809116 拒绝。「拦截口径」与「回显口径」现在共用同一份计算（`VehicleSeatCalculator.SeatSummary`），不再互相矛盾——凡是回显会算出 `remainingPassengerSeats` 为负的组合，保存时就先被拒绝，不会写入库。
+- 809116 报文占位符从 5 个变成 6 个，新模板与两个换算样例见「三、接口详情 → 1 → 业务边界」。
+- 本条**取代** `changelogs-v2/2026-09/22_8152_团期用车需求补车辆规格与接送机汇总-修改接口-管理后台.md` 中关于 809116 判据与文案的描述，具体被取代的位置见「十、相关文档」。
+
+---
+
+## 一、背景（选填）
+
+#8278 AC-1 定案：旧口径下「拦截不扣司机座、回显扣司机座」是对称子域的口径漂移（CODE_RULES §15.7）——子订单级容量校验与 fleet 单车派车早已扣司机座，只有团级拦截没扣，导致「刚好坐满」的组合能保存成功，但回显立刻显示余座为负。本单让团级拦截口径向已有的、更严格的口径看齐（扣司机座），而不是放松回显。
+
+最强反例（评审已确认，留档）：「刚好坐满、司机另开一辆车」这类特殊排法在新口径下会被拒绝——这是业务上刻意收紧，因为司机座不能卖给乘客，运营应当据此把车辆规格填成真实的乘客运力，而不是靠"整车都算乘客座"的旧口径蒙混过关。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 保存团期正式用车需求 | PUT | `/v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement` | 校验判据变更 + 错误报文格式变更 | 809116 扣司机座 |
+| 2 | 用车需求汇总草稿 | GET | `/v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement/aggregate-draft` | 响应字段语义说明 | `violations[]` 里的 809116 条目共用同一份新判据/新报文 |
+
+---
+
+## 三、接口详情
+
+### 1. 保存团期正式用车需求 `PUT /v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement`
+
+**VO**: `GroupVehicleRequirementSaveReqVO → GroupVehicleRequirementRespVO`
+
+#### 使用场景
+
+团期详情「查看需求 → 团级正式用车需求」编辑弹窗点保存。语义仍是整份全量替换：未出现在本次提交里的分组会被移出当前版本。请求体与响应体结构均不变，本条只改 809116 的判据与报文。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long | ✅ | - | 团期聚合主键 |
+| version | Body | Integer | ❌ | 首次保存传 null，其后回传上次拿到的值 | 乐观锁；不一致抛 809102 |
+| remark | Body | String | ❌ | ≤500 | 整份需求备注 |
+| groups | Body | Array | ✅ | 可以是空数组（`@NotNull` 非 `@NotEmpty`） | 全部乘车分组；有在团需车户却零分组抛 809103 |
+| groups[].groupId | Body | Long | ❌ | 新增分组传 null | 带上它即声明「这就是库里那一组」，此时 groupCode 不得变更（否则 809104） |
+| groups[].groupCode | Body | String | ✅ | ≤32，同一份内不得重复 | 直接作为车费 alloc_group |
+| groups[].vehicleType | Body | String | ✅ | ≤64 | 车型文本/字典值 |
+| groups[].serviceStartDate | Body | LocalDate | ✅ | `yyyy-MM-dd` | 本组服务开始日 |
+| groups[].serviceEndDate | Body | LocalDate | ✅ | 不早于开始日 | 本组服务结束日 |
+| groups[].seats | Body | Integer | ❌ | `@Min(1)`；与 count 同填或同空 | 单车座位数（含驾驶位）；**本次改动后参与扣司机座的容量判据**，存量分组可不传 |
+| groups[].count | Body | Integer | ❌ | `@Min(1)`；与 seats 同填或同空 | 车辆数量；只填一半抛 809118 |
+| groups[].specialTags | Body | Array&lt;String&gt; | ❌ | 取值须在字典 `vehicle_special_demand` 内 | 特殊诉求标签编码数组；含字典外编码整份拒绝（809117） |
+| groups[].remark | Body | String | ❌ | ≤500 | 该组备注 / 其他诉求 |
+| groups[].days | Body | Array | ✅ | 非空，且正好铺满本组服务日范围 | 逐日用车人数与成员 |
+| groups[].days[].tripDate | Body | LocalDate | ✅ | 落在本组服务日范围内、不重复、不缺日 | 越界或重复抛 809105，缺日抛 809106 |
+| groups[].days[].headcount | Body | Integer | ✅ | `@Min(1)`，且 ≥ 当日成员户数 | 该组该日**乘车人数**；本次改动后这个值与「(seats − 1) × count」比较，决定是否触发 809116 |
+| groups[].days[].memberOrderIds | Body | Array&lt;Long&gt; | ✅ | 非空，须全属本团在团户 | 该组该日实际乘车的子订单集合 |
+
+#### 出参 `Result<GroupVehicleRequirementRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| requirementId | String | 正式需求主键（Long 序列化为字符串） |
+| groupBatchId | String | 团期聚合主键（Long 序列化为字符串） |
+| status | String | DRAFT / CONFIRMED / DISPATCHED / DONE / PENDING_RECONFIRM / CANCELLED；PUT 后为 DRAFT |
+| version | Integer | 版本号，下次提交须回传 |
+| remark | String | 整份备注 |
+| confirmedBy / confirmedAt | String / LocalDateTime | 整份确认人/时间；DRAFT 时为 null |
+| planRefreshState / planRefreshReplayCount / blockedStage / planRefreshStalled / planRefreshStalledReason / planRefreshTimeoutAt / planRefreshReplayExhausted | - | 配车刷新状态相关字段，本次改动未涉及 |
+| groups | Array | 全部乘车分组；整团免车态为空数组 |
+| groups[].groupId | String | 分组主键（Long 序列化为字符串） |
+| groups[].groupCode | String | 分组键 = 车费 alloc_group |
+| groups[].vehicleType / vehicleTypeName | String | 车型文本/字典值 / 车型中文名 |
+| groups[].serviceStartDate / serviceEndDate | LocalDate | 本组服务日范围 |
+| groups[].seats | Integer | 单车座位数（含驾驶位）；存量分组为 null |
+| groups[].count | Integer | 车辆数量；存量分组为 null |
+| groups[].specialTags | Array&lt;SpecialTagItem&gt; | 特殊诉求标签（code + name） |
+| groups[].remark | String | 该组备注 |
+| groups[].totalSeatCount | Integer | 总座位数 = seats × count（含驾驶位）；座位或数量缺一即为 null |
+| groups[].maxHeadcount | Integer | 该组 days 里的最大用车人数 |
+| **groups[].remainingPassengerSeats** | Integer | 余座 = 扣司机座后的可乘座位 − maxHeadcount；**可为负**；计算公式本次未变，但**新提交**里凡是会算出负值的组合，保存时已被 809116 拦在前面，不会写入库——负值目前只可能出现在改动前已保存、尚未被下一次提交重新校验的存量分组上 |
+| groups[].days[].tripDate / headcount / memberOrderIds / memberOrderCount | - | 逐日行程与成员，未变 |
+
+#### 请求示例
+
+```json
+{
+  "version": null,
+  "remark": "#8278-AC6",
+  "groups": [
+    {
+      "groupId": null,
+      "groupCode": "AC6BUS",
+      "vehicleType": "bus",
+      "serviceStartDate": "2027-03-24",
+      "serviceEndDate": "2027-03-25",
+      "seats": 20,
+      "count": 2,
+      "specialTags": [],
+      "remark": "#8278-AC6",
+      "days": [
+        { "tripDate": "2027-03-24", "headcount": 38, "memberOrderIds": [2102749115559677953] },
+        { "tripDate": "2027-03-25", "headcount": 38, "memberOrderIds": [2102749115559677953] }
+      ]
+    }
+  ]
+}
+```
+
+#### 响应示例
+
+真实网关实测响应（20 座 × 2 辆，headcount=38，`(20−1)×2=38` 恰好用完）：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "requirementId": "2102750063359135746",
+    "groupBatchId": "2102749115823919105",
+    "status": "DRAFT",
+    "version": 1,
+    "remark": "#8278-AC6",
+    "confirmedBy": null,
+    "confirmedAt": null,
+    "planRefreshState": null,
+    "planRefreshReplayCount": 0,
+    "blockedStage": null,
+    "planRefreshStalled": false,
+    "planRefreshStalledReason": null,
+    "planRefreshTimeoutAt": null,
+    "planRefreshReplayExhausted": false,
+    "groups": [
+      {
+        "groupId": "2102750063363330049",
+        "groupCode": "AC6BUS",
+        "vehicleType": "bus",
+        "vehicleTypeName": "大巴系列",
+        "serviceStartDate": "2027-03-24",
+        "serviceEndDate": "2027-03-25",
+        "seats": 20,
+        "count": 2,
+        "specialTags": [],
+        "remark": "#8278-AC6",
+        "totalSeatCount": 40,
+        "maxHeadcount": 38,
+        "remainingPassengerSeats": 0,
+        "days": [
+          { "tripDate": "2027-03-24", "headcount": 38, "memberOrderIds": ["2102749115559677953"], "memberOrderCount": 1 },
+          { "tripDate": "2027-03-25", "headcount": 38, "memberOrderIds": ["2102749115559677953"], "memberOrderCount": 1 }
+        ]
+      }
+    ]
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+- 整团没有在团需车户时，`groups: []` 是合法提交，响应 `groups` 为空数组；不受本次改动影响。
+- 存量分组（本次改动之前已保存的组）在数据库里原样保留旧值，不会因为本次上线被批量重算或清退；只有当它下次出现在某次 PUT 提交的 `groups` 数组里（哪怕自身字段一个没改，只是跟其他组一起整份提交）时，才会按新口径重新校验——如果它本身坐不下（扣司机座后不够），这次整份保存会被 809116 拒绝、全部字段零写入。
+- 车型中文名依赖车队侧车型库，降级行为不变：查不到编码或车队不可用时 `vehicleTypeName` 为 null，接口仍 200，不阻断页面。
+
+```json
+{ "code": 200, "message": "成功", "data": { "groups": [] }, "success": true }
+```
+
+#### 错误响应
+
+真实网关实测响应（20 座 × 2 辆，headcount=40，`(20−1)×2=38 < 40`）：
+
+```json
+{
+  "code": 809116,
+  "message": "第 AC6BUS 组座位数不足：20 座 × 2 辆，扣除 2 个司机座后可载客 38 人，少于该组最大乘车人数 40 人",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- 报文里「第 {0} 组」的 {0} 仍是 `groupCode`，不是序号（不变）；一次只抛一条，按校验遍历顺序收集（不变）。
+- **新模板与占位符**：`第 {0} 组座位数不足：{1} 座 × {2} 辆，扣除 {3} 个司机座后可载客 {4} 人，少于该组最大乘车人数 {5} 人`。{1}=单车座位数（含司机座），{2}=车辆数，{3}=扣除的司机座数（恒等于 {2}），{4}=`(seats−1)×count` 算出的可载客座位，{5}=该组最大单日乘车人数。**占位符从旧模板的 5 个（{0}~{4}）变成 6 个（{0}~{5}），其中两个位置的语义变了**：旧模板 `第 {0} 组座位数不足：{1} 座 × {2} 辆 = {3} 座，少于该组最大乘车人数 {4} 人` 里，{3} 是总座位数（`seats × count`），{4} 是该组最大乘车人数；新模板里 {3} 改为扣除的司机座数，{4} 改为可载客座位数，最大乘车人数挪到 {5}。{0}/{1}/{2} 语义不变。前端如果曾按位置/正则解析这句报文（而不是原样展示整句 `message`），必须同步改；如果只是原样 toast 整句 `message` 字符串，零改动即可。
+- 判据公式：`passengerSeatCapacity = max(0, seats × count − count)`，`passengerSeatCapacity < maxHeadcount` 时拒绝。两个换算样例（公式自算，均为「改前放行、改后拒绝」的收窄场景）：
+  - **19 座 × 1 辆、该组最大日人数 19**：`passengerSeatCapacity = max(0, 19×1 − 1) = 18`，`18 < 19` → 拒绝，`809116`：「第 {groupCode} 组座位数不足：19 座 × 1 辆，扣除 1 个司机座后可载客 18 人，少于该组最大乘车人数 19 人」。
+  - **7 座 × 2 辆、该组最大日人数 13**：`passengerSeatCapacity = max(0, 7×2 − 2) = 12`，`12 < 13` → 拒绝，`809116`：「第 {groupCode} 组座位数不足：7 座 × 2 辆，扣除 2 个司机座后可载客 12 人，少于该组最大乘车人数 13 人」。
+- seats 与 count 同生同死规则不变：只填一个抛 809118（报文字面文本未变，仍是「第 {0} 组的座位数与车辆数必须同时填写，或同时留空」）；两个都不填 = 存量形态，座位校验整体跳过。
+- 乐观锁 `version` 不一致抛 809102（不变）；特殊诉求标签字典校验（809117）、逐字段约束均不变。
+
+---
+
+### 2. 用车需求汇总草稿 `GET /v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement/aggregate-draft`
+
+**VO**: `GroupVehicleAggregateDraftRespVO`
+
+#### 使用场景
+
+团期详情「查看需求 → 团级正式用车需求」为空/未确认时，前端用它拉一份系统按子订单在团情况自动配出的推荐草稿（`seats` 取组内最大单车座位、`count = ceil(最大日人数 / (seats − 1))`），供运营参考后再决定是否提交。本次改动不影响这个推荐公式本身（`GroupVehicleDraftAggregator.java:345`，已用 `git show a0973867f -- <该文件>` 核对，本次合并只改了该文件的 javadoc 注释，公式代码未动），只影响 `violations[]` 数组里 809116 条目的判据与报文——它与保存端点共用同一份校验函数（`collectFleetSpecViolations`）。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long | ✅ | - | 团期聚合主键 |
+
+#### 出参 `Result<GroupVehicleAggregateDraftRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| groupBatchId | String | 团期聚合主键（Long 序列化为字符串） |
+| currentStatus | String | 当前正式需求状态；未建过正式需求为 null |
+| draft | Object | 结构同 `GroupVehicleRequirementSaveReqVO`；`version` 为当前生效版本号或 null；`draft.groups[].groupId` 恒为 null（草稿未落库） |
+| droppedFleetItems | Array | 因非主车型/车型字典不可用被剔除的子订单车队行；字段 orderId/orderNo/vehicleType/seats/count/keptVehicleType/reason |
+| staleHeadcountOrders | Array | 冻结人数与当前实际人数不一致的子订单；字段 orderId/orderNo/frozenHeadcount/liveHeadcount |
+| paddedOrderDays | Array | 被自动补天的子订单；字段 orderId/orderNo/dates |
+| violations | Array | 草稿自身触发的校验违规；恒非 null，无违规为空数组 |
+| violations[].code | Integer | 错误码，本次改动相关的是 809116 |
+| violations[].reason | String | 原因码，见「六.5」 |
+| violations[].detail | String | 渲染文案，与「三 → 1 → 错误响应」里同码条目的 `message` 逐字相同 |
+| violations[].groupCode / tripDate / orderId | String / LocalDate / String | 定位到具体分组/日期/子订单，均可为 null |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch/2102749115823919105/vehicle-requirement/aggregate-draft
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "groupBatchId": "2102749115823919105",
+    "currentStatus": null,
+    "draft": {
+      "version": null,
+      "remark": null,
+      "groups": [
+        {
+          "groupId": null,
+          "groupCode": "AC6BUS",
+          "vehicleType": "bus",
+          "serviceStartDate": "2027-03-24",
+          "serviceEndDate": "2027-03-25",
+          "seats": 20,
+          "count": 2,
+          "specialTags": [],
+          "remark": null,
+          "days": [
+            { "tripDate": "2027-03-24", "headcount": 38, "memberOrderIds": ["2102749115559677953"] },
+            { "tripDate": "2027-03-25", "headcount": 38, "memberOrderIds": ["2102749115559677953"] }
+          ]
+        }
+      ]
+    },
+    "droppedFleetItems": [],
+    "staleHeadcountOrders": [],
+    "paddedOrderDays": [],
+    "violations": []
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+- 整团没有可汇总内容时，`draft.groups` 为空数组，`droppedFleetItems`/`staleHeadcountOrders`/`paddedOrderDays`/`violations` 均为空数组（javadoc 原文：恒非 null）。
+- 有需车户缺少可汇总的行程用车需求时报 809121（本次改动未涉及此判据）。
+- 车型字典不可用时报 809120（本次改动未涉及此判据）。
+
+```json
+{ "code": 200, "message": "成功", "data": { "draft": { "groups": [] }, "droppedFleetItems": [], "staleHeadcountOrders": [], "paddedOrderDays": [], "violations": [] }, "success": true }
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 809121,
+  "message": "团期 XXX 有 2 户缺少可汇总的行程用车需求，暂不能自动汇总：ORD001、ORD002",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- 推荐公式 `count = ceil(最大日人数 / (seats − 1))` 保证草稿自己生成的分组，扣司机座后的可载客座位数恒 ≥ 该组最大日人数，所以由这个端点直接产出的草稿**正常情况下不会**在自己的 `violations[]` 里出现 809116。
+- `violations[]` 里若确实出现 809116 条目（例如运营手工改过草稿后再调这个端点做二次校验），其 `detail` 文案与占位符结构（6 段）与「三 → 1 → 错误响应」逐字相同，前端复用同一份渲染/解析逻辑即可，不需要为本端点单独适配。
+- 本端点只读，不落库，多次调用互不影响、无并发/幂等问题。
+
+---
+
+## 四、契约约束与正确调用方式（接口类必写）
+
+> 本节只写**后端接受/拒绝 payload 的规则**，不写 UI 渲染建议。
+
+### ✅ 正确 / ❌ 错误 payload 对照（`PUT .../vehicle-requirement` 分组元素，`seats`/`count`/该组最大单日人数三者的关系）
+
+| 场景 | seats × count | (seats−1) × count | 最大单日人数 | 判定 |
+|------|----------------|---------------------|----------------|------|
+| ✅ 明显够坐 | 35 | 34 | 20 | 放行（改前改后均放行） |
+| ✅ 恰好用完（边界） | 40 | 38 | 38 | 放行，`remainingPassengerSeats=0`（20 座×2 辆/38 人，已用真实网关实测） |
+| ❌ 不扣司机座够坐、扣了不够（新增拒绝区间） | 19 | 18 | 19 | 809116 拒绝——**改前放行、改后拒绝** |
+| ❌ 不扣司机座够坐、扣了不够（新增拒绝区间） | 14 | 12 | 13 | 809116 拒绝——**改前放行、改后拒绝**（7 座×2 辆/13 人） |
+| ❌ 两版本均拒绝 | 10 | 9 | 15 | 809116 拒绝（改前改后均拒绝，不扣司机座也不够坐） |
+
+### 切换状态时的必要动作
+
+`seats`/`count` 仍是「同填同空」的互斥对（不变）：只提交其中一个会被 809118 拒绝；两个都不提交等价于存量形态，座位校验整体跳过。提交时不要依赖"隐藏输入框"的 UI 行为，后端只看 payload 里这两个字段是否同时为非 null。
+
+---
+
+## 五、数据库行为（涉及写操作时必写）
+
+本次改动**不涉及表结构变化**，`groups.seats`/`groups.count`/`groups_day.headcount` 三列的落库口径与列值语义均未变——放行的提交，落库值仍是前端提交的原始 `seats`/`count`，后端不做任何扣减存储；变的只是"放不放行"这一步的判定发生在写库之前。
+
+| 前端提交 | 改前落库结果 | 改后落库结果 |
+|----------|--------------|--------------|
+| 19 座 × 1 辆、最大日人数 19（该组） | 校验通过，`group.seats=19, group.count=1` 落库 | 809116 拒绝，**整份提交零写入**（不含该分组之外的其他改动） |
+| 20 座 × 2 辆、最大日人数 38（该组） | 校验通过，`group.seats=20, group.count=2` 落库 | 校验通过（边界恰好用完），落库同值 |
+
+**零写入范围**：`PUT` 语义是整份全量替换，任一分组触发 809116 会导致这次提交整体失败，不只是该分组，其余分组在本次提交里的改动也不会落库（与改前逻辑一致，不是本次新增行为）。
+
+---
+
+## 六、边界行为
+
+- 未登录 → 401（网关拦截，不变）。
+- `groupBatchId` 不存在 → 团期聚合层报错（不变，未在本次改动范围）。
+- 车队/字典服务降级 → 809120（`vehicleType` 字典不可用）判据与报文不变，仍与 809116 相互独立、互不影响。
+- 老数据兼容 → 存量分组的 `seats`/`count` 为 null 时 809116 判据整体跳过（不变）；已有 `seats`/`count` 但未随本次改动重新保存的组，回显仍按旧值展示，可能带负的 `remainingPassengerSeats`（见「三 → 1 → 空数据 / 降级响应」）。
+- 生产环境 → 二期功能尚未在生产开放，本次改动的行为差异目前不会被任何生产流量触发。
+
+---
+
+## 六.5、枚举 / 数据字典（接口出现枚举时必写）
+
+### status（正式用车需求状态，`GroupVehicleRequirementRespVO.status`）
+
+**所属字段**: `GroupVehicleRequirementRespVO.status` | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `DRAFT` | 草稿 | PUT 保存成功后的默认状态；本次改动后，坐不下的组合会在到达这一步之前就被 809116 拒绝 |
+| `CONFIRMED` | 已确认 | 整份确认后 |
+| `DISPATCHED` | 已派车 | fleet 已排车 |
+| `DONE` | 已完成 | 车务完成 |
+| `PENDING_RECONFIRM` | 待重新确认 | 确认后又被撤回/变更，需重新确认 |
+| `CANCELLED` | 已取消 | 整团取消 |
+
+本次改动未涉及状态机迁移逻辑本身，取值与含义均不变。
+
+### violations[].reason（`GroupVehicleAggregateDraftRespVO.Violation.reason`，本次改动相关的两个取值）
+
+**所属字段**: `GroupVehicleAggregateDraftRespVO.Violation.reason` | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `GROUP_SEATS_INSUFFICIENT` | 座位数不足 | 对应 809116；本次改动后判据改为扣司机座 |
+| `GROUP_SPEC_INCOMPLETE` | 车辆规格不完整 | 对应 809118；判据与报文字面文本均未变 |
+
+---
+
+## 六.6、修改前后对比（修改/删除类接口必写，新增跳过）
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 |
+|------|------|------|
+| 809116 报文占位符数量 | 5 个（{0}~{4}） | 6 个（{0}~{5}）：{3} 从「总座位数（`seats × count`）」改为「扣除的司机座数（=车辆数）」；{4} 从「最大乘车人数」改为「可载客座位数」；「最大乘车人数」后移到新增的 {5} |
+| 809116 判据表达式 | `seats × count < 该组最大单日乘车人数` | `max(0, seats × count − count) < 该组最大单日乘车人数`（即扣司机座后判断） |
+| `remainingPassengerSeats`（响应字段） | 计算公式含扣司机座，可能为负；负值组合仍能保存成功（拦截口径更宽松） | 计算公式不变；但**新提交**里会算出负值的组合，已先被 809116 拒绝，不会写入库 |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| 提交 `seats × count == 该组最大单日人数`（如 19 座×1 辆/19 人） | 放行 | 809116 拒绝 |
+| 提交 `(seats−1) × count == 该组最大单日人数`（如 20 座×2 辆/38 人） | 放行 | 放行（余座为 0，恰好用完） |
+| 提交 `(seats−1)×count < 该组最大单日人数 ≤ seats×count`（如 19×1/19、7×2/13） | 放行（不扣司机座时够坐） | **809116 拒绝**（扣司机座后不够坐，本次改动新增的拒绝区间） |
+| 拦截口径 vs 回显口径是否一致 | 刻意相差 1 个司机座/车，可能「保存成功但 remainingPassengerSeats 为负」 | 两口径共用同一份 `VehicleSeatCalculator` 计算，新提交不会再出现这种矛盾 |
+| 存量分组（改动前已保存、字段未变） | — | 不主动重算，原样保留在库里；只有它下次出现在某次 PUT 的 `groups` 数组里才会被新口径重新校验 |
+| fleet 单车派车（`AssignmentService`） | 已扣司机座 | 不变，本次改动是团级向它对齐 |
+| fleet 团级就绪检查黄牌（`GroupDispatchReadinessService#seatShortageWarnings`） | 不扣司机座 | 不变，仍不扣司机座，跟踪于 #8294，不在本次改动范围内 |
+
+---
+
+## 六.7、影响评估（修改/删除类必写）
+
+- **是否破坏向后兼容**: 部分是——请求体/响应体字段结构未变，但同一份 payload 在「恰好等于旧口径边界、不足新口径边界」的场景下，会从改前的 200 变成改后的 809116（809116 是 HTTP 200 下的业务失败，不是传输层错误）。
+- **前端是否必须同步上线**: 视前端现有实现而定。若前端只是把 809116 的 `message` 整句原样 toast 展示，不改也能正常显示新文案，零改动。若前端曾按占位符位置/正则解析这句报文（例如截取「× {2} 辆」后面的数字单独展示），必须同步改成新的 6 段结构，否则会把 {3}（司机座数）或 {4}（可载客座位）错位显示。
+- **前端 workaround 清理点**: 若前端为「刚好坐满」这类输入写过专门的“应该能保存”预期用例，需要把预期改成会撞 809116；`remainingPassengerSeats` 为负仍是合法信号（不应做 `Math.max(0, x)` clamp，也不应据此拦截提交，这条 22_8152 的既有结论继续有效），但不能再假设"负值一定对应一个刚保存成功的新组合"——新提交里的负值组合已经在保存时被拒绝，负值目前只可能来自尚未被下一次保存重新校验的存量分组。
+
+---
+
+## 七、不影响范围（显式声明, 帮前端/QA 缩小排查面）
+
+- **仅影响**: `PUT .../vehicle-requirement` 的 809116 触发条件与报文；`GET .../vehicle-requirement/aggregate-draft` 响应体 `violations[]` 数组里 809116 条目的判据与报文（若出现）。
+- **零影响**:
+  - 两个接口的请求体/响应体字段结构（无新增、无删除字段）。
+  - 错误码码值本身（仍是 809116/809118，未变）；809117（特殊诉求标签字典）、809102（乐观锁）、809103~809115、809119~809122 等其余错误码的判据与报文。
+  - `GET /v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement`（读取回显）：不触发任何校验，原样返回库里已落值。
+  - `GET .../requirement/vehicle-households`、`GET .../requirement-summary`、`GET .../requirement/confirm-check`：均未改动。
+  - `aggregate-draft` 自身的推荐车辆数公式 `count = ceil(最大日人数 / (seats − 1))`（`GroupVehicleDraftAggregator.java:345`）：本次合并只改了该文件的 javadoc，公式代码本身未动。
+  - fleet 单车派车口径（`AssignmentService`）：本就扣司机座，不受影响。
+  - fleet 团级就绪检查黄牌口径（`GroupDispatchReadinessService#seatShortageWarnings`）：仍不扣司机座，未随本次改动对齐，另开 #8294 跟进。
+  - 生产环境：二期功能尚未在生产开放，本条改动不影响任何生产流量。
+  - 历史数据：存量分组的 `seats`/`count`/`headcount` 不做批量重算或迁移，见「六.6」。
+
+---
+
+## 八、测试环境已验证
+
+真实网关实测（`https://api.test.1814.love`，hl-order-service-v3 dev-v3 @ `a0973867f`，2026-09-23 21:09:02 部署，`deploy-status` 读数 `BEHIND=0 STATE=ok`，两次 PUT 请求均晚于部署时刻）：
+
+```
+PUT /v3/admin/order/group-batch/2102749115823919105/vehicle-requirement
+  20 座 × 2 辆，headcount=40（两天）  → code=809116
+  message=第 AC6BUS 组座位数不足：20 座 × 2 辆，扣除 2 个司机座后可载客 38 人，少于该组最大乘车人数 40 人 ✓
+GET  同一团期同一端点回读              → code=200, data=null（校验在写库前抛出，零写入）✓
+
+PUT /v3/admin/order/group-batch/2102749115823919105/vehicle-requirement
+  同一分组，headcount 改为 38（两天）  → code=200, message=成功
+  data.groups[0]: seats=20, count=2, totalSeatCount=40, maxHeadcount=38, remainingPassengerSeats=0 ✓
+GET  同一团期同一端点回读              → code=200, requirementId=2102750063359135746, status=DRAFT, version=1 ✓
+```
+
+验证团期：`groupBatchId=2102749115823919105`（本轮自建夹具，未影响任何既有排期/团期）。两次 PUT 之间唯一变量是 `headcount`（40→38），`groupCode`/`vehicleType`/`seats`/`count`/日期范围完全相同，809116 与 200 的分野只能来自本次判据变更。
+
+定向单测（`mvn -o -pl hl-order-service-v3 -am test -Dtest='GroupVehicleRequirementSaveTest*,GroupVehicleDraftAggregatorTest*,...'`，起跑 2026-09-23 20:31:52）：17 个外层类 / 148 用例，Failures/Errors/Skipped 全 0，`BUILD SUCCESS`；含 `VehicleSeatCalculatorTest`（6）、`GroupVehicleRequirementSaveTest`（25，含新旧边界两条判据）、`GroupVehicleDraftAggregatorTest`（19）与 9 个 `@ArchTest` 载体。仅改注释的返工提交后，定向复跑受影响 3 类：50/0/0。
+
+存量影响核查（测试服只读 SELECT，2026-09-23 20:14:20）：活跃团级用车需求 131 个，其中带完整规格（`seats`/`count` 均非空）的分组 3 组；按新口径重算，这 3 组全部仍满足要求（新口径可载客座位 4~15 人不等，均 ≥ 该组最大日人数 2~5 人），按新口径会被拒的活跃分组数为 **0**。生产环境二期尚未开放，无生产存量。
+
+限定：本次真实网关实测只覆盖了「一辆 20 座大巴 × 2 辆」这一种具体座位组合的团级 PUT 入口；其它座位数组合、子订单级校验、`aggregate-draft` 端点自身，由上述单测覆盖（`aggregate-draft` 与保存端点共享同一份校验代码，但本次未针对该端点单独发起真实 HTTP 调用）。存量核查的分母只有 3 组带规格（团级用车规格字段是 #8152 刚上线的新字段，前端入口尚未普及），0 组的读数只说明此刻不会新拒任何已存活跃版本，对未来接入更多分组后是否仍为 0 没有分辨力。
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#8278](https://git.1814.love/wx/HL/issues/8278)
+- 关联 PR: [wx/HL#8296](https://git.1814.love/wx/HL/pulls/8296)
+- 已知缺口（不在本次改动范围内）: [wx/HL#8294](https://git.1814.love/wx/HL/issues/8294) —— fleet 团级就绪检查黄牌口径尚未对齐扣司机座
+- **订正声明（取代旧描述，不改动原文件）**：本条取代 `changelogs-v2/2026-09/22_8152_团期用车需求补车辆规格与接送机汇总-修改接口-管理后台.md` 中以下位置关于 809116 判据与文案的描述：
+  - 第 36-38 行「⚠️ 关键变化」块（「拦截口径不扣司机位」「回显口径扣司机位」「20 座 × 1 辆 / 20 人能保存成功，而返回的 `remainingPassengerSeats` 是 -1」）：描述的是本次改动前的行为，改动后 20×1/20 这组输入已改为 809116 拒绝，两口径不再矛盾。
+  - 第 40、42、44 行「展示侧」「提交侧」「响应体里没有任何字段表示…」三段：其中「是否允许保存由后端 809116 判定（口径：`seats × count` 与该组最大乘车人数比较，不扣司机位）」这句已过时，判据已改为扣司机位。
+  - 第 240 行错误响应示例 `"第 BUS 组座位数不足：19 座 × 1 辆 = 19 座，少于该组最大乘车人数 20 人"`：这是旧模板（5 个占位符）的渲染结果，新模板见本条「三 → 1 → 错误响应」与「三 → 1 → 业务边界」。
+  - 第 268 行业务边界「座位充足性判据 = `seats × count < 该组最大单日乘车人数`，不扣司机位」：判据已变，见本条「六.6」。
+  - 第 354 行「20 座 × 1 辆载 20 人保存成功，余座 `-1`」：该结论已不成立，这组输入现在被拒绝。
+  - 第 944 行行为级对比表格「提交坐不下的规格 | 接受（无此字段） | 809116 拒绝（判据不扣司机位）」一行，末列「判据不扣司机位」已过时。
+  - 第 958-959 行「若此前把 `remainingPassengerSeats` 之类余座数做过 `Math.max(0, x)` 处理，必须撤掉」「不要新增『余座为负则禁止保存』的前端校验」：这两条建议本身**依然有效**，但其背景「后端放行的组合」已收窄——新提交里会被后端放行的组合，扣司机座后已经够坐，不会再出现负值；负值目前只可能来自尚未被下一次保存重新校验的存量分组。
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8278](https://git.1814.love/wx/HL/issues/8278)
+- **PR**: [#8296](https://git.1814.love/wx/HL/pulls/8296)
+- **Merge commit**: [a0973867f](https://git.1814.love/wx/HL/commit/a0973867f)
+
+### 联系人
+
+- **后端负责人**: @wx
@@ -0,0 +1,122 @@
+---
+schema: "hl-changelog/v2"
+ticket: "frontend-groupbatch-vehicle-house-panel-gaps"
+title: "团期详情页「用车/用房」面板：乘车户全选汇总人数 + 确认按钮布局 + 对话入口缺失（3 项前端待办）"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "前端缺陷"
+backend_status: "not_required"
+gateway_status: "not_required"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "d59180090e17c3fe1b9a1a4fb4fde22fc9f91685"
+target_release: ""
+verified_at: "2026-09-23"
+status_note: "wx 团期详情页用车/用房面板走查反馈，3 项均为纯前端待办：①乘车户全选+人数自动汇总（数据 participantCount 已在 orders 数组里，未被读取）②接送机逐户确认按钮布局（未右对齐）③子订单行缺与定制师对话入口（已有可用的既有后端会话接口 open-group，未接入）。三项互相独立，backend_status=not_required 是因为本文件不改任何后端契约。 | 2026-09-23 mmg 交付:三项全落(全选汇总/右对齐/两面板联系定制师透传 ChatDrawer)"
+updated_at: "2026-09-23"
+base: "dev-v3"
+---
+
+# 团期详情页「用车/用房」面板：乘车户全选汇总人数 + 确认按钮布局 + 对话入口缺失（3 项前端待办）
+
+> **服务**: 无后端服务变更（纯前端 UI；第 3 项引用的 `hl-user-service` `/admin/message/chat/open-group` 是已存在的能力，本次不新增/不修改）
+> **PR**: 无（前端尚未提交）
+> **Issue**: 无（wx 口头/会话反馈，未建 Gitea 工单）
+> **日期**: 2026-09-23
+> **影响范围**: 管理后台团期详情页「用车」「用房」两个 Tab 面板
+
+---
+
+## ⚠️ 关键变化
+
+本文件是**待补齐清单**，不是"已交付变更"说明——三项各自独立、互不依赖，可分别排期，涉及文件都在 `hl-ui` `origin/v2.1` 分支。
+
+---
+
+## 一、乘车户「全选」+ 按所选户自动汇总人数
+
+**涉及文件**: `src/views/order-v2/batch/detail/components/GroupVehicleRequirementEditModal.vue`（「正式用车需求编辑」弹窗，逐日行区块，第 165-201 行）
+
+**现状（实测代码）**：
+- 「人数」是 `<n-input-number v-model:value="d.headcount">`（第 177-186 行），`headcountRule`（第 375-382 行）只校验"非空且 ≥1"，没有联动逻辑。
+- 「乘车户」是 `<n-select multiple filterable :options="memberOptions">`（第 190-198 行），`memberIdsRule`（第 383-388 行）只校验"非空数组"。
+- 两个控件之间没有任何联动，也没有"全选"控件。
+
+**可用但未被读取的数据**：`memberOptions`（第 323-333 行）目前只从 `props.orders` 取 `orderId`/`customerName`/`contactName`/`teamNo` 组装 `{ label, value }`，**没有带出 `participantCount`**。`participantCount` 其实已经在同一个 `orders` 数组里（团期订单列表 GB-ADM-003 契约字段），同级的 `VehicleHouseholdsSection.vue:71` 与 `RequirementTab.vue:476` 已经在直接读它展示"N 人"——不需要新接口，只是这个弹窗的 `memberOptions` computed 没把它带出来。
+
+**需要的改动（供参考，不限定实现方式）**：
+1. 全选：一个按钮/开关把 `d.memberOrderIds` 置为 `memberOptions.value` 的全量 `value`。
+2. 自动汇总：`memberOptions` 补出 `participantCount`（或另建 `orderId → participantCount` 的 Map），选中集合变化时把 `d.headcount` 自动置为已选各户 `participantCount` 之和；`participantCount` 为 `null` 的户按 0 计。
+3. `headcount` 输入框保留手动可编辑——自动填充只是给个起点，若某户实际乘车人数与 `participantCount`（报名人数）不一致（如小孩不占位、分批乘车），管理员仍需手动改。
+
+**业务边界**：
+- 这里自动算出的人数只是**填表辅助**，不是权威口径——整团/整日的用车人数汇总另有独立的后端工单在跟（wx/HL#8220，backend），本项做完之后 `d.headcount` 仍然只是这张表单自己的字段，不代表后端汇总接口上线后的口径一定与这里手填/自动填的值相同。
+- `participantCount` 为 `null` 的户参与"全选"时按 0 计入自动汇总，不阻断全选本身（该户仍会被选中，只是不贡献人数）。
+
+---
+
+## 二、接送机需求逐户「确认」按钮挪到行右侧
+
+**涉及文件**: `src/views/order-v2/batch/detail/components/VehicleHouseholdsSection.vue`
+
+**现状（实测代码 + 样式）**：
+- 「确认」按钮（`canConfirmReq(req)` 为真时渲染，第 122-129 行）与车型/状态标签、"XX 人"文字同处一行——`.vehicle-households__req-head`（第 92 行起）。
+- 该行样式（第 495-500 行）：`display: flex; align-items: center; gap: 8px; flex-wrap: wrap;`，没有 `justify-content` 或对按钮单独设 `margin-left: auto`，按钮紧跟在"XX 人"文字后面，不在行的最右侧。
+
+**需要的改动**：给 `.vehicle-households__req-head` 加 `justify-content: space-between`（把按钮包进一个独立的尾部容器），或直接给「确认」按钮加 `margin-left: auto`，把它推到行右侧。
+
+**业务边界**：
+- 只影响 `.vehicle-households__req-head` 这一处的 TRANSFER 行确认按钮；用房面板 `RoomHouseholdsSection.vue` 全文没有等价的逐户「确认」按钮（已核查，仅第 127/289 行的注释提到"整团确认"，属另一套交互，不在本项范围）。
+
+---
+
+## 三、用车/用房子订单行缺「和定制师发起对话」入口
+
+**涉及文件**:
+- `VehicleHouseholdsSection.vue` 的 `.vehicle-households__card-head`（第 56-77 行）
+- `RoomHouseholdsSection.vue` 的 `.room-households__card-head`（第 44-68 行）
+
+两处的 `v-for` 都已经在 `household` 上下文里拿到 `household.orderId`，但都没有任何对话/聊天入口（全文 grep「对话」「chat」「Chat」在这两个组件里零命中，`RoomHouseholdsSection.vue` 里唯一相关的是两处注释提及"整团确认"，与聊天无关）。
+
+**已就绪的后端契约（本次核实，非新增，backend_status=not_required 是因为接口本身没有变化，只是首次要接给这两个面板用）**：
+
+`POST /admin/message/chat/open-group`（`hl-user-service` `ChatMessageController.openGroup`，工单 #7211）
+
+- 请求体 `ChatOpenGroupReqVO`：`{ "orderId": "70123" }`——`orderId` 必填（`@NotNull`），团期子订单 id，雪花值按字符串传（与本仓其它 19 位 ID 字段一致，避免 JS 精度丢失）。
+- 响应体 `ChatOpenFullRespVO`（继承 `ChatOpenRespVO`）：`conversationKey`（如 `GROUP:70123`，不含 adminId 对）、`peerAdminId`、`peerName`、`peerRole`、`peerRoleLabel`、`peerOnline`、`unreadCount`、`isNew`、`order`（订单卡）、`thread`（首屏 20 条消息）、`unreadTotal`（合并未读，本次调用会把该会话标记已读之后的值）。
+- 团期管理员是团队制，不指派到人：定制师这一侧打开会话时，对端固定是「团期管理员」团队占位——`peerRole="GROUP_ADMIN"`、`peerRoleLabel="团期管理员"`，不是某一个具体的管理员账号。
+- 准入：该订单当前定制师（CUSTOMIZER），或当前角色持权限码 `group-batch:demand:confirm`（超管天然通过）；其余角色统一拒绝且零写入。
+- 错误码：缺 `orderId` → **281012**「缺少订单上下文」；不满足上述准入身份 → **281002**「无权访问该会话」；该订单不是团期子订单（团期摘要 `groupBatchId` 为空）→ **281015**「该订单不是团期子订单，无法联系团期管理员」。
+- 打开会话之后，同一个 `conversationKey`（`GROUP:{orderId}`）继续走通用的两个端点，不区分模块：`GET /admin/message/chat/{conversationKey}/messages`（上滑翻页取更早历史）、`POST /admin/message/chat/{conversationKey}/messages`（发消息）。如果车务/房务面板已有复用的聊天组件，直接换 `open` 端点为 `open-group` 即可接入，不需要重新对接翻页/发送逻辑。
+- 网关：`hl-user-service` 的 `/admin/message/**` 路由已覆盖，不需要新配路由。
+
+**业务边界**：
+- 用车、用房两个面板的子订单行请求体字段完全一样（都只传 `orderId`），可以共用同一套"发起对话"组件。
+- 会话按 `GROUP:{orderId}` 维度建：同一个子订单如果在用车、用房两个面板里都出现，两边打开的是同一条会话，不会产生重复会话或未读数分叉。
+
+---
+
+## 七、不影响范围
+
+- **仅影响**：管理后台团期详情页「用车」「用房」两个 Tab 组件（模板/脚本/样式，纯前端文件）。
+- **零影响**：
+  - 本文件三项都不改后端契约；第三项引用的 `POST /admin/message/chat/open-group` 是首次被这两个面板消费，接口本身（CUSTOMIZER↔团期管理员团队场景）未做任何变更。
+  - 其它已在用 `open-group`/`open-fleet`/`open-house` 的既有调用方不受影响。
+  - 团期用车需求的后端保存/校验接口（`GroupVehicleRequirementSaveReqVO` 等）不受影响——第一项只改前端表单填充逻辑，提交给后端的字段结构不变。
+
+---
+
+## 十、相关文档
+
+- `open-group` 契约来源：`hl-user-service/src/main/java/com/hulalv/user/notification/chat/controller/ChatMessageController.java`（工单 #7211）。
+- `participantCount` 字段来源：`GB-ADM-003` 团期订单列表契约（`src/api/orderV2GroupBatch.js` 第 143-160 行注释）。
+
+## 关联 / 联系人
+
+### 链接
+
+- 无 PR / 无 Issue（本文件为纯前端待办清单，未建 Gitea 工单）。
+
+### 联系人
+
+- 第三项接口如有疑问：@wx
@@ -0,0 +1,154 @@
+---
+schema: hl-changelog/v2
+ticket: "frontend"
+title: "查看需求 Tab：整团级操作收进顶部操作条 + 子订单行新增「需求详情」弹窗"
+consumer: admin
+author: "wx(GIT)"
+change_type: "前端优化"
+backend_status: "not_required"
+gateway_status: "not_required"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "f713b1c65c061a18754c5bc759d1c50c3dd5eb3e"
+target_release: "v2.1"
+verified_at: "2026-09-23"
+status_note: "2026-09-23 wx 对「查看需求」Tab 提三点：①「新增正式行程用车需求」按钮应该在顶部操作条这里；②该按钮独立成一张卡片操作不方便；③要一个按钮点开弹窗看用房/用车需求详情；并总结「这个 Tab 操作整体不方便，整理优化下」。本条是给 mmg 的 UI 重排规格。后端零改动：四项改动用到的端点与字段全部已在 dev-v3 上线并被本 Tab 现有代码调用，无新增端点、无出入参变化、无网关路由变化、无 DDL。字段清单逐项对 origin/dev-v3 的 VO 源码核过（GroupHotelHouseholdsRespVO / GroupVehicleHouseholdsRespVO / GroupBatchRoomPlanDetailRespVO）。 | 2026-09-23 mmg 交付:五区块卡头全撤,顶部操作条(刷新一个顶六个/新增编辑正式需求平铺,整团级缺失时 primary ghost/撤回免车受控重开收更多下拉,判定经 ops-state 上抛);预检条目可点(户级滚动定位名单行+高亮,车侧整团级直开编辑弹窗);名单表加需求详情弹窗(两 tab 只读复用 households 快照零新请求,分房段按需拉 room-plans 过滤本户);五卡自绘折叠分区默认只展开两汇总(n-collapse 懒挂载不满足 eager fetch);scroll-x 钉死列宽合计 1568;顺带修 A 段遗留 doConfirm stale refs ReferenceError;7 spec 99 例全绿"
+updated_at: "2026-09-23"
+base: dev-v3
+---
+
+# 查看需求 Tab：操作重排 + 逐户需求详情弹窗
+
+> **服务**: hl-order-service-v3（**后端零改动**）
+> **页面**: 管理后台 → 团期订单 → 团期详情 → 「查看需求」Tab
+> **文件**: `src/views/order-v2/batch/detail/components/RequirementTab.vue` 及其子组件
+> **日期**: 2026-09-23
+> **影响范围**: 仅前台渲染与交互编排；无端点、无出入参、无网关路由、无 DDL 变化
+
+---
+
+## 一、现状与问题（对 `origin/v2.1` = `61a549bd` 实读）
+
+这个 Tab 现在是「一条操作条 + 一张子订单表 + 五张平铺卡片」的结构：
+
+| 位置 | 承载的整团级操作 |
+|---|---|
+| `RequirementTab.vue:29-51` `.requirement-tab__ops` | 刷新预检 / 打回选中户(N) / 整团确认需求 |
+| `GroupVehicleRequirementSection.vue` 的 `#header-extra` | 新增(编辑)正式行程用车需求 / 整份撤回·撤回免车 / 声明整团免车 / 受控重开配车窗口 |
+| 五张卡片各自的卡头 | 各自一个「刷新」 |
+
+三个具体问题：
+
+1. **整团级操作散在三处**，其中一处还在第四屏。
+2. **阻断项和解除阻断的按钮离得最远**。顶部预检提示条会打出「团期 xxx 尚未形成正式用车需求」，而消除它的那个按钮在下方「正式用车需求」卡片的卡头里——看见问题的地方和能动手的地方隔了四张卡片。
+3. **一户的需求被劈在两张卡片里**。「用房 · 子订单订房记录」和「用车 · 子订单需求记录」各自按户列一遍，要看清某一户到底报了什么，得在两张卡片之间上下翻。子订单表里的那一行才是「这一户」，但那行点不开。
+
+---
+
+## 二、要做的四件事
+
+### 1. 整团级操作全部收进顶部操作条
+
+`.requirement-tab__ops` 改为（从左到右）：
+
+```
+[刷新] [打回选中户(N)] [新增正式行程用车需求] [更多 ▾] ………… [整团确认需求]
+```
+
+- **`新增正式行程用车需求` 平铺**（wx 明确指定放这里）。文案沿用现有逻辑：有需求时显示「编辑正式需求」，无需求时显示「新增正式行程用车需求」。
+- **`更多 ▾` 收三个低频且互斥的**：`整份撤回` / `撤回免车`（二者 `v-if` / `v-else-if` 互斥）、`声明整团免车`、`受控重开配车窗口`。收进下拉的理由是这四个按钮的出现与否随状态变化，平铺会让操作条宽度随状态跳动；下拉让操作条形状恒定。
+- **按钮层级**：`整团确认需求` 保持 `type="primary"`，是这个页面的终点。`新增正式行程用车需求` 用默认样式，**但当预检提示条里出现「尚未形成正式用车需求」这一条时，把它切成 `type="primary" ghost`** —— 此刻它才是「现在该点的那个」。
+- **卡片保留，只清空卡头**。`GroupVehicleRequirementSection` 这张卡片继续展示正式用车需求的内容（车队、座位、状态），只把 `#header-extra` 里那四个按钮搬走。
+
+实现上父子已经通着：`RequirementTab.vue:155-168` 已持有 `ref="vehicleReqRef"`，把 `canEdit` / `isWaived` / `canWithdraw` / `canReopen` 四个 computed 与四个动作的入口方法 `defineExpose` 出来即可，不需要新增 props 或提升状态。
+
+### 2. 预检提示条的每一条做成可点
+
+这是「操作不方便」最直接的来源，优先级最高。
+
+| 提示条里的条目 | 点击后 |
+|---|---|
+| `HL2026xxxx 定制师张三 — 未提交房需求` | 滚动到子订单表对应行并高亮（`orderId` 已在 missing 项里） |
+| `团期 21008xxxx 尚未形成正式用车需求` | 直接打开 `GroupVehicleRequirementEditModal`，即操作条上那个「新增正式行程用车需求」 |
+
+把「看见问题」和「动手解决」接在一起，用户就不必自己在页面里找对应入口。
+
+### 3. 子订单表操作列新增「需求详情」→ 弹窗
+
+在现有「进入」旁边加一个「需求详情」。点开一个 `n-modal`（或右侧 `n-drawer`），**两个 Tab：用房 / 用车**，只读。
+
+**关键点：这个弹窗的价值是「按户聚合」，不是「多给字段」。**
+两张列表卡片其实已经把下面这些字段渲染出来了（`RoomHouseholdsSection.vue` / `VehicleHouseholdsSection.vue` 实读确认），弹窗做的是把同一户散在两处的内容收到一屏。
+
+#### 用房 Tab
+
+数据来自本 Tab 已加载的 `GET /v3/admin/order/group-batch/{groupBatchId}/requirement/hotel-households`，按 `orderId` 过滤，**不发新请求**。
+
+- 头部：`customerName` / `teamNo` / `orderNo` / `participantCount` / `consultantName`
+- 状态：`statusName`，外加 `countedInSummary` 的显式标识（计入汇总 / 未计入汇总）
+- 配房需求：`remark`
+- 特殊标签：`specialTags[]`
+- 打回留痕：`returnRemark` +`returnedAt`（有值才显示）
+- 逐晚表，来自 `days[]`：
+
+| 列 | 取值 | 既有约定（沿用，勿改） |
+|---|---|---|
+| 第 N 天 | `dayNumber` | |
+| 入住日 | `stayDate` | |
+| 自行预订 | `customerSelfBooked` | 为 true 时该晚不该被当成缺口 |
+| 酒店 | `hotels[].hotelName` | 为 null 显「未知酒店」，**行不隐藏**（间数仍有效） |
+| 地点 | `hotels[].district` | **用 `district` 不用 `city`**，契约实测 `city` 几乎恒为同一地级市，区分不出地点 |
+| 房型 | `rooms[].roomTypeName` | 回落链：`roomTypeName` → `roomCategoryName` → `roomCategory` → 「未知房型」 |
+| 间数 | `rooms[].roomCount` | |
+
+#### 用车 Tab
+
+数据来自 `GET .../requirement/vehicle-households`，同样按 `orderId` 过滤复用已加载数据。逐条渲染 `requirements[]`：
+
+- `kindName`（行程用车 / 接送机）+ `statusName`
+- `serviceDates[]`
+- `headcount` / `totalSeatCount`（含驾驶位）/ `remainingPassengerSeats`（负数标「缺口」，沿用现有红色样式）
+- `fleet[]` 车队明细
+- `pickupRequired` / `dropoffRequired` —— **仅 TRANSFER 有意义，TRAVEL 恒为 null**，TRAVEL 下整行不渲染
+- `specialTags[]` / `remark`
+- `returnRemark` + `returnedAt`（有值才显示）
+
+#### 可选第二段：这一户「已经配成什么样」
+
+如果要让弹窗从「他报了什么」延伸到「我们给他配了什么」，`GET /v3/admin/order/group-batch/{groupBatchId}/room-plans`（H12 整团配房明细，只读、不含金额）已经有分房层，按 `orderId` 过滤即可：
+
+```
+days[].plans[].allocations[]  →  orderId / orderNo / roomCount / roomGroupNo(家庭分组 F{N}) / 入住人数 / allocSource(AUTO|MANUAL)
+```
+
+外层还带 `hotelName` / `roomTypeName` / `planStatus`（PENDING|CONFIRMED）/ `replaceReason`。这是弹窗里唯一需要多发一个请求的部分，按需加载即可。
+
+### 4. 刷新收敛成一个，明细卡片默认折叠
+
+- 顶部操作条那个 `刷新预检` 改名 `刷新`，一次刷预检 + 五个区块；**撤掉五张卡片各自的刷新按钮**。用户心智里这个页面只有一个「刷新」。
+- 五张卡片（用房·汇总 / 用房·子订单订房记录 / 用车·汇总 / 正式用车需求 / 用车·子订单需求记录）改 `n-collapse`，**默认只展开两张「汇总」**。明细按需展开，首屏留给操作条、预检提示条和子订单表。
+
+---
+
+## 三、数据来源汇总（零新接口）
+
+| 用途 | 端点 | 本 Tab 现状 |
+|---|---|---|
+| 子订单表 | `GET /v3/admin/order/group-batch/{id}/orders` | 已调 |
+| 预检 | `GET .../requirement/confirm-check` | 已调 |
+| 用房逐户（弹窗用房 Tab） | `GET .../requirement/hotel-households` | 已调，字段够 |
+| 用车逐户（弹窗用车 Tab） | `GET .../requirement/vehicle-households` | 已调，字段够 |
+| 整团确认 / 打回 | `POST .../requirement/confirm`、`.../requirement/reject` | 已调 |
+| 正式用车需求 读/存/撤回/免车/重开 | `GET`·`PUT .../vehicle-requirement`、`.../withdraw`、`.../waive`、`.../reopen` | 已调 |
+| 弹窗「已配成什么样」（可选段） | `GET .../room-plans` | 本 Tab 未调，端点已上线（H12） |
+
+---
+
+## 四、业务边界
+
+- **本条只覆盖「查看需求」Tab**。「配房明细」Tab（`RoomPlansTab.vue`）的结构不在本次重排范围内。
+- **需求侧的房间粒度只到「房型 × 间数」**。`GroupHotelHouseholdsRespVO` 的最细一层是 `HouseholdRoomItem{roomTypeId, roomTypeName, roomCategory, roomCategoryName, roomCount}`，弹窗的用房 Tab 给不出「哪一间」。
+- **「谁住哪一间」这层数据全系统没有**。配房侧能到「哪一户的哪个家庭分组 F{N}、几个人、住哪家酒店哪个房型的几间」（上面第二段那个可选来源），但**出行人姓名与房间的绑定不存在**——`GET .../room-plans` 的接口说明里明写了不返回出行人姓名与联系方式。要做到姓名级，是一次真正的新增能力，不是取数问题。
+- **用车侧被打回的户可能在弹窗里无行可渲染**。`VehicleHouseholdsSection.vue:210` 的注释写着「打回行失活不在列表（与用房侧『列出打回户灰显』刻意不同）」。【需确认】这一条我只读到注释、没有实测接口返回，实现时以 `vehicle-households` 的实际返回为准；若确实不返，弹窗用车 Tab 对被打回的户要给一个明确空态文案，不要显示成「这户没报用车需求」。
+- **`受控重开配车窗口` 进下拉后仍受既有约束**：DISPATCHED 定稿后要重配须先开窗拿令牌，PENDING_RECONFIRM 下续开/取当前令牌同走这个入口（后端幂等返回既有令牌，`809203` 兜他人窗口）。挪位置不改变这套行为。
+- **`整团免车` 是合法逃生口不是异常态**。顶部那个 `本团整团免车` 的 `n-tag`（`checkResult?.vehicleWaived === true`）要保留在操作条附近，免车时车侧校验整体跳过，别让它看起来像出错了。
@@ -0,0 +1,119 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8231"
+title: "物资 tab 的写入口仍按 MATERIAL_PREPARING 前置隐藏——后端已放开到出行前四态，前端不改则运营点不到入口"
+consumer: "admin"
+author: "jw(GIT)"
+change_type: "前端优化"
+backend_status: "not_required"
+gateway_status: "not_required"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "e15dd73bd36a1d27374f9206797243f8a5e4326c"
+target_release: ""
+verified_at: "2026-09-23"
+status_note: "#8231 后端已把物资三个写接口（新增行 / 改数量 / 软删行）的阶段门从单一 MATERIAL_PREPARING 放宽到出行前四态（RECRUITING / RESOURCE_PREPARING / MATERIAL_PREPARING / PENDING_DEPARTURE），2026-09-23 已部署 TEST 并四态逐一实测通过。但 SuppliesPanel.vue 里有一个 isMaterialPreparing 计算属性把手工录入按钮、操作列表头、数量行内编辑、删除按钮四处一并前置隐藏，非 MATERIAL_PREPARING 阶段物资 tab 仍是一张没有操作列的只读表，运营点不到任何入口——后端这次放开在界面上等于没发生。需要把这四处的判据从「等于 MATERIAL_PREPARING」改成「在出行前四态之内」。注意「确认物资」按钮（同文件 28 行）走的是另一个接口 confirm-material，#8231 没有放开它，那一处的阶段门要原样保留、不要跟着一起改。配导游 / 配摄影侧前端零改动：ChipItemsPanel.vue 的配置按钮条件只有 v-if=configRole，不看 batchStatus，后端放开后即刻生效。 | 2026-09-23 mmg 交付:canConfigureSupplies 四态管三写入口,isMaterialPreparing 保留仅管确认物资"
+updated_at: "2026-09-23"
+base: "dev-v3"
+---
+
+# 团期物资 tab: 写入口的阶段门需从单一阶段放宽到出行前四态（管理后台）
+
+> **仓库 / 分支**: `mmg/hl-ui` @ `v2.1`
+> **文件**: `src/views/order-v2/batch/detail/components/SuppliesPanel.vue`
+> **Issue**: #8231
+> **日期**: 2026-09-23
+> **影响范围**: 团期详情页「物资」tab 的操作列与三个写入口
+
+---
+
+## ⚠️ 关键变化
+
+后端已经放开，**前端不改则本次改动在界面上等于没发生**。
+
+`RESOURCE_PREPARING`（资源准备中）是最典型的一态：团期要集齐四项 ready（房 / 车 / 导 / 摄）才推得进
+`MATERIAL_PREPARING`，所以今天运营抱怨「物资配不了」，多数时候团期正停在 `RESOURCE_PREPARING`。
+后端这次就是为这个场景放开的，而前端在这一态下连操作列都不渲染。
+
+---
+
+## 一、后端现状（已部署 TEST 并实测）
+
+| 接口 | 方法 | 路径 | 改后可用状态 |
+|---|---|---|---|
+| 新增备品行 | POST | `/v3/admin/order/group-batch/{groupBatchId}/supplies` | 出行前四态 |
+| 调整数量 | PUT | `/v3/admin/order/group-batch/supplies/{batchSuppliesId}/quantity` | 出行前四态 |
+| 软删备品行 | DELETE | `/v3/admin/order/group-batch/supplies/{batchSuppliesId}` | 出行前四态 |
+
+出行前四态 = `RECRUITING` / `RESOURCE_PREPARING` / `MATERIAL_PREPARING` / `PENDING_DEPARTURE`。
+
+出行后（`TRAVELLING` / `TRIP_FINISHED` / `REVIEWING` / `SETTLED`）与 `CANCELLED` 仍拒，
+**错误码从 589520 换成了 589598**，文案「出行后不可再配置导游 / 摄影 / 物资」。
+
+TEST 实测（2026-09-23，`dev-v3` @ `fe752f16c`）：四态各跑「增 → 改数量 → 删」三端点共 12 次调用全 200；
+三个出行后态各返 589598 且零写入。
+
+---
+
+## 二、前端需要改的四处（行号按 `origin/v2.1` @ `f713b1c6`）
+
+| # | 行 | 现状 | 期望 |
+|---|---|---|---|
+| 1 | 16 | `v-if="isMaterialPreparing"` —— 「手工录入」按钮 | 出行前四态可见 |
+| 2 | 52 | `<span v-if="isMaterialPreparing">操作</span>` —— 操作列表头 | 出行前四态可见 |
+| 3 | 81 | `v-if="isMaterialPreparing"` —— 数量 `n-input-number` 行内编辑（否则走 `v-else` 的只读纯文本） | 出行前四态可编辑 |
+| 4 | 94 | `<span v-if="isMaterialPreparing">` —— 整个删除按钮单元格 | 出行前四态可见 |
+
+判据单源在 179 行：
+
+```js
+// #7528 阶段门:仅物料准备中可见三个写操作与确认入口(其余状态后端仍守,前端前置隐藏)
+const isMaterialPreparing = computed(() => props.detail?.batchStatus === 'MATERIAL_PREPARING')
+```
+
+连带两处会自动跟着变，确认改后表现正常即可：
+
+- 183 行 `gridColumns`：操作列出现与否决定列宽是 6 列还是 5 列
+- 188 行 `emptyText`：空态文案分「可从备品库选择或手工录入」与「本期尚未配置物资」两种
+
+---
+
+## 三、⚠️ 不要一起改的两处
+
+| 位置 | 原因 |
+|---|---|
+| 28 行「确认物资」按钮 | 它调的是 `POST /v3/admin/order/group-batch/{groupBatchId}/confirm-material`，属七项硬门准入链路，**#8231 没有放开它**。那一处的 `MATERIAL_PREPARING` 判据要原样保留 |
+| 4 行「从备品库选择」按钮 | 它本来就没挂阶段门、一直可见。改前它在非 `MATERIAL_PREPARING` 下点了会被 589520 拒，改后四态内可正常落库——**不需要改代码，但回归时要覆盖它** |
+
+因为 28 行与那四处不再同一个判据，建议把 179 行拆成两个计算属性（例如「可配置窗口」与「可确认物资」），
+而不是把现有的 `isMaterialPreparing` 就地改语义——后者会把确认物资一起放开，那是另一件事。
+
+---
+
+## 四、配导游 / 配摄影侧：前端零改动
+
+`ChipItemsPanel.vue` 的配置按钮条件只有 `v-if="configRole"`，不看 `batchStatus`；
+弹窗只有 `:disabled="!rosterReady"`（名单加载态）。招募中按钮本来就渲染、点得下去，
+只是改前后端回 589552 被拦截器透成 toast。后端放开后该路径即刻可用，无需前端配合。
+
+---
+
+## 五、错误文案
+
+按 589520 做分支的地方需要改认 **589598**。589520 未退役（保留占位防号段复用），但物资三口不再抛它。
+
+---
+
+## 六、回归建议
+
+在 `RESOURCE_PREPARING` 的团期上验：操作列出现 → 手工录入一行 → 改数量 → 删除 → 从备品库选择再加一行。
+再在 `REVIEWING` 或 `TRIP_FINISHED` 的团期上验：操作列不出现，且即便直接打接口也返 589598。
+
+---
+
+## 关联 / 联系人
+
+- 后端：jw（#8231，PR #8234 / #8237，已部署 TEST）
+- 前端：mmg
+- 同批后端条目：`23_8231_配导游配摄影物资放开到出行前四态-修改接口-管理后台.md`
+- 前例：`17_frontend_团期物资清单补改数量删除与手工录入-前端优化-管理后台.md`
@@ -0,0 +1,139 @@
+---
+schema: hl-changelog/v2
+ticket: "frontend"
+title: "「用房 · 汇总」首屏必现「汇总加载失败」：同页两个组件调同一个接口，后发的把先发的 abort 了"
+consumer: admin
+author: "wx(GIT)"
+change_type: "前端缺陷"
+backend_status: "not_required"
+gateway_status: "not_required"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "4b33ccbd9af619723a9c58373531627cb6e31e9b"
+target_release: "v2.1"
+verified_at: "2026-09-23"
+status_note: "2026-09-23 wx 反馈团期详情「查看需求」Tab 的「用房 · 汇总」显示「汇总加载失败,可点右上角「刷新」重试」，同页「用房 · 子订单订房记录」「用车 · 汇总」正常。根因在 hl-ui：RoomSummarySection 与 VehicleSummarySection 在同一 tick 各调一次 getGroupRequirementSummary（同 method+url+params+data），而该封装未传 cancelDuplicate:false，request.js 的去重拦截器用后发的 AbortController abort 掉先发的那条；渲染顺序 Room 在前，所以被取消的恒是 Room，catch{} 把 cancel 当失败吞掉、summary 留 null、落到空态文案。后端与数据均正常：测试服 nginx 09-21~09-23 该团期 16 次 requirement-summary 全部 HTTP 200、响应体与应用日志确认成功的载荷等长，order-v3 应用日志 09-23 两次打出「全团需求汇总完成 inGroupOrders=2 hotelNeeded=2 hotelCounted=1」，09-22 18:55 起零 ERROR；DB 侧两户 needs_hotel=1、一户有 active 需求行，与页面「共 2 户 · 计入 1 户」吻合。本条无后端改动。 | 2026-09-23 mmg 交付:requirement-summary 收归 RequirementTab 统一取数只调一次,两汇总区块改 props 下发(失败态只看 error prop),catch 护栏区分 ERR_CANCELED(去重 abort/路由切换)不落假失败态,空 id/序号守卫随取数上移父级;3 spec 31 例锁单次取数/取消护栏/失败态"
+updated_at: "2026-09-23"
+base: dev-v3
+---
+
+# 「用房 · 汇总」首屏必现加载失败：请求去重把它自己的请求取消了
+
+> **服务**: hl-order-service-v3（**后端零改动，后端与数据均正常**）
+> **页面**: 管理后台 → 团期订单 → 团期详情 → 「查看需求」Tab → 「用房 · 汇总」区块
+> **接口**: `GET /v3/admin/order/group-batch/{groupBatchId}/requirement-summary`
+> **日期**: 2026-09-23
+> **影响范围**: 仅前端。所有团期、所有用户、每次首次进入该 Tab 必现；点「刷新」即恢复
+
+---
+
+## 一、现象
+
+「用房 · 汇总」渲染成空态：`汇总加载失败,可点右上角「刷新」重试`。
+同一页的「用房 · 子订单订房记录」「用车 · 汇总」「用车 · 子订单需求记录」全部正常。
+点该区块右上角「刷新」立刻就好。
+
+---
+
+## 二、根因（对 `origin/v2.1` = `61a549bd` 源码实读）
+
+三个事实叠起来构成这个缺陷：
+
+**① 同一个接口被同页两个组件各调一次，且在同一 tick**
+
+| 文件 | 行 | 调用 |
+|---|---|---|
+| `src/views/order-v2/batch/detail/components/RoomSummarySection.vue` | `:74` `:169` | `import { getGroupRequirementSummary }` → `await getGroupRequirementSummary(batchId)` |
+| `src/views/order-v2/batch/detail/components/VehicleSummarySection.vue` | `:94` `:152` | 同上 |
+
+两者都在 `watch([active, groupBatchId], …, { immediate: true })` 里触发（`RoomSummarySection.vue:180-190`、`VehicleSummarySection.vue:163-173`），`active` 同源，必定同 tick。
+`RequirementTab.vue` 的渲染顺序是 `RoomSummarySection` 在前、`VehicleSummarySection` 在后。
+
+**② 这个 API 封装没关掉去重**
+
+`src/api/orderV2GroupBatch.js:563-568`：
+
+```js
+export function getGroupRequirementSummary(groupBatchId, config = {}) {
+  return http.get(`${BASE}/${String(groupBatchId)}/requirement-summary`, null, {
+    ...V3,
+    ...config,
+  })
+}
+```
+
+同一个文件里 `confirm`(`:507`)、`reject`(`:528`) 以及另外十余个封装都带着 `cancelDuplicate: false`，**只有这个没带**。
+
+**③ 去重拦截器对同 key 的后发请求，是 abort 掉先发的那条**
+
+`src/utils/request.js:260-275`：
+
+```js
+if (config.cancelDuplicate === false) { …不入 pending 列表… }
+…
+oldController.abort('取消重复请求')
+const controller = new AbortController()
+```
+
+key 的构成（`:235-237`）是 `[method, url, stableStringify(params), stableStringify(data)].join('&')`。
+本接口无 query、无 body，两个组件算出的 key **逐字符相同**。
+
+**⇒ 后发的 Vehicle 把先发的 Room abort 了。** Room 那条在 adapter 发出前就被取消，所以网络层根本看不到它（测试服 nginx 每次页面加载只落**一条** `requirement-summary`，与此吻合）。
+
+**④ 取消被当成了失败**
+
+`RoomSummarySection.vue:169-175`：
+
+```js
+try { const res = await getGroupRequirementSummary(batchId); … } catch { }
+```
+
+裸 `catch {}` 不区分 axios cancel 与真实失败，`summary` 留 `null`，模板落到 `:55` 的空态文案。
+点「刷新」时只有一条请求在途、没人取消它，所以必然成功——这就是「刷新即好」的由来。
+
+---
+
+## 三、后端与数据侧的核查结果（均正常，供排除用）
+
+- **nginx 访问日志**（测试服 `access.log{,.1,.2.gz}`）：该团期 09-21~09-23 共 **16 次** `requirement-summary`，**全部 HTTP 200**；响应体 1116 B（09-22 13:04 上 `transferSummary` 之前）/ 1358 B（之后）。对照组：前端在路由参数未就绪时发的空 id 请求 `group-batch//requirement-summary` 只有 132 B，说明 1358 B 是完整成功载荷、不是 `code≠0` 的 `Result`。
+- **order-v3 应用日志**：`2026-09-23 09:09:45.822` / `09:11:01.395` 两次 `全团需求汇总完成 groupBatchId=2100856430494973953 inGroupOrders=2 hotelReqs=1 hotelNeeded=2 hotelCounted=1 vehicleReqs=1 transferReqs=1`；09-22 18:55 起 order-v3 零 ERROR。
+- **数据**：两个子订单 `needs_hotel=1`；`HL20260918155619496` 有 `is_active=1` 的 `PENDING_REVIEW` 用房需求（两晚、JSON 合法、`special_tags=["禁烟"]`），`HL20260922161158291` 无用房需求行（`flow_status=AWAITING_PROFILE`）。与页面「共 2 户 · 计入汇总 1 户」逐项吻合，无脏数据。
+- **服务端代码**：`GroupBatchRequirementService.summary()` 链路上 `filterCountedHotelRequirements` 对无需求行的户只是不入集合（不会 NPE），`aggregateDailyRooms` / `parseServiceDates` / `aggregateVehicleSeats` / `collectSpecialTags` 均 try/catch 降级，酒店名与车型名的 Feign/字典加载失败一律降级为空 Map。无 null-guard 缺口。
+
+---
+
+## 四、修复建议
+
+**主修（结构）**：由 `RequirementTab` 只请求一次 `requirement-summary`，经 props 下发给 `RoomSummarySection` / `VehicleSummarySection`。父组件已持有两者的 ref，改动面可控；这样同一接口一次页面加载只打一次，顺带省掉一次重复请求。
+
+**护栏（更重要，建议与主修一起做）**：两个 Summary 组件的 `catch {}` 要区分「被取消」与「真失败」，被取消时不要落成「加载失败」态：
+
+```js
+} catch (e) {
+  if (axios.isCancel?.(e) || e?.code === 'ERR_CANCELED') return   // 保持 loading / 旧数据，不置失败态
+  // 真实失败才走原逻辑
+}
+```
+
+`src/utils/request.js:596` 已经有这个判别写法可以直接抄。之所以说它比主修更重要：`request.js:315` 在**路由切换**时也会 `abort('路由切换，取消请求')`，同样会落进这个 `catch`；而且只要将来任何组件再复用同一个接口，缺陷就会原样复现。这条护栏把「一次修好」变成「不会再犯」。
+
+**一行止血（如果要先快速恢复）**：给 `getGroupRequirementSummary` 的配置加上 `cancelDuplicate: false`，与同文件其余封装写法一致。代价是同一页会真的发两次相同请求。
+
+### ⚠️ 一个容易踩空的点
+
+`request.js` 里有**两个名字相近、行为不同**的开关，别改错：
+
+| 开关 | 位置 | 对本缺陷 |
+|---|---|---|
+| `dedupe`（时间窗内重复请求直接拒） | `:173-208` | **对 GET 默认就不生效**——`:183` 写着 `methodUpper === 'GET' && config.dedupe !== true` 才进这段。设 `dedupe: false` 改变不了任何事 |
+| `cancelDuplicate`（同 key 后发 abort 先发） | `:260-275` | **就是它**，对 GET 生效 |
+
+---
+
+## 五、业务边界
+
+- **不限于某一个团期**。机制是同 tick 双请求、后者必取消前者，与团期数据无关；09-22 14:37 团期 `2101506167098511362` 的访问日志同样只落一条 `requirement-summary`。
+- **只影响「用房 · 汇总」区块的首屏**。「用车 · 汇总」拿得到数据（它是后发的那条），其余三个区块调的是别的接口，不受影响。点「刷新」或整团确认后的 `reload()` 都能恢复。
+- **09-22 白天的 order-v3 应用日志已被滚动删除**（只保留 3 份），那个窗口 13 次请求的「后端成功」由 nginx 200 + 响应体长度（与 09-23 已被应用日志直接证实成功的载荷等长）支撑，不是应用层直接证据；09-23 的两次有应用日志直接证实。
+- **前端侧的最初取证来自测试服实际部署的构建产物**（`/var/www/hl-admin/assets/`，构建于 09-23 09:59），本条正文里的文件行号是事后对 `origin/v2.1` = `61a549bd` 源码复核后给出的，两侧一致。
+- **顺带一个非本单的观察**：进入团期详情页时，页面在路由参数就绪前会发三条空 id 请求——`group-batch//requirement-summary`、`group-batch//vehicle-requirement`、`group-batch//requirement/hotel-households`（各返 132 B 业务错误）。来源不是 `RoomSummarySection`（它有 `!groupBatchId` 守卫）。对功能无影响，列在这里供一并排查。
@@ -0,0 +1,250 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7804"
+title: "定时任务健康自检"
+consumer: "admin"
+author: "jw(GIT)"
+change_type: "新增接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "not_required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "后端已部署 TEST 并经网关实测；运维排查接口，管理后台无需接入页面"
+updated_at: "2026-09-24"
+base: "dev-v3"
+---
+
+# 定时任务健康自检（#7804）
+
+> **服务**: hl-user-service（经网关调用，无需关心服务端口）
+> **PR**: #8337
+> **Issue**: #7804
+> **日期**: 2026-09-24
+> **影响范围**: 定时任务运维排查（超级管理员），无前端页面
+
+---
+
+## ⚠️ 关键变化
+
+新增只读端点，逐个定时任务并列返回三方状态：**期望状态**、**`sys_job.status`（意图）**、**Quartz 触发器实况**。三方不一致的条目 `healthy=false`，并附告警原文。
+
+**三条会直接影响你怎么用的点**：
+
+1. 🔴 **判断任务是否真在跑，要看 `quartzState`，不能看 `dbStatus`**。`sys_job.status` 只是意图：用裸 SQL 把它置 PAUSED，任务照跑（TEST 上 1044 就这样连跑了 4 天）。原有的 `GET /admin/job` 列表只有 `sys_job.status`，不能用来判断启停。
+2. **只有 SUPER_ADMIN 能调**；其他角色返回业务码 `210301`。
+3. **成功码是 `code: 200`**；业务失败也返回 HTTP 200，**一律按 `body.code` 判**。
+
+---
+
+## 一、背景（选填）
+
+`SysJobService.initScheduledJobs()` 为了集群安全是纯增量的，只补注册 ACTIVE 任务，从不移除已有的 Quartz 触发器。所以「裸 SQL 置 PAUSED」停不掉任务，而原来的 `[JobHealth]` 自检只读 `sys_job`，这种漂移下自检是绿的。本单把自检改为以 Quartz 为准，并把结果开放成接口。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 定时任务健康自检 | GET | `/admin/job/health` | 新增接口 | 只读，逐个任务返回期望 / sys_job / Quartz 三方状态与告警 |
+
+---
+
+## 三、接口详情
+
+### 1. 定时任务健康自检 `GET /admin/job/health`
+
+**VO**: `SysJobHealthVO`
+
+#### 使用场景
+
+运维或超级管理员排查「某个定时任务到底有没有在跑」「sys_job 与调度器是否一致」时调用。结果与服务日志里的 `[JobHealth]` WARN 同源同文：启动时和每天 09:30 自动跑一次，日志里只记不一致的条目；本接口返回全部条目，健康的也在内。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| `Authorization` | Header | String | ✅ | `Bearer <token>` | 管理端 token，角色须为 SUPER_ADMIN |
+
+#### 出参
+
+`Result<List<SysJobHealthVO>>`，按 jobId 升序排列。另有两类条目追加在末尾：名单内但 sys_job 里不存在的 job，以及 Quartz 里有调度而 sys_job 没有这一行的 job。
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `jobId` | Long | 任务 ID。🔴 部分任务是 19 位雪花 ID（如 `2067459972995731458`），前端按字符串处理 |
+| `jobName` | String / null | 任务名；sys_job 中不存在该行时为 null |
+| `expectedStatus` | String / null | 期望状态，来自配置 `hl.job.health-check.expected-status`；未列入名单的任务为 null。取值 `ACTIVE` / `PAUSED` |
+| `dbStatus` | String / null | `sys_job.status`，即意图；sys_job 中不存在该行时为 null。取值 `ACTIVE` / `PAUSED` |
+| `quartzState` | String | Quartz 触发器实况，取值见「六.5 枚举」 |
+| `healthy` | Boolean | 期望、sys_job、Quartz 三方一致时为 true |
+| `message` | String / null | 告警原文；健康时为 null |
+
+#### 请求示例
+
+```http
+GET /admin/job/health
+Authorization: Bearer <SUPER_ADMIN token>
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": [
+    {
+      "jobId": 1039,
+      "jobName": "Fleet导入临时文件收敛",
+      "expectedStatus": null,
+      "dbStatus": "PAUSED",
+      "quartzState": "NORMAL",
+      "healthy": false,
+      "message": "jobId=1039 name=Fleet导入临时文件收敛 期望=未列入名单 DB=PAUSED Quartz=NORMAL：sys_job 与 Quartz 漂移（sys_job 只是意图，Quartz 才是实况）"
+    },
+    {
+      "jobId": 1041,
+      "jobName": "团期出发推进",
+      "expectedStatus": "ACTIVE",
+      "dbStatus": "ACTIVE",
+      "quartzState": "NORMAL",
+      "healthy": true,
+      "message": null
+    }
+  ]
+}
+```
+
+**示例说明**：两条取自测试环境 2026-09-24 14:54 的真实调用（当时 1039 是人为构造的漂移），实际返回全部任务（TEST 上 34 条）。
+
+#### 空数据 / 降级响应
+
+sys_job 为空且 Quartz 无孤儿调度时，`data` 为空数组：
+
+```json
+{ "code": 200, "message": "成功", "data": [] }
+```
+
+读某个任务的 Quartz 状态失败时不降级为「健康」，而是返回一条 `healthy=false`、`quartzState=UNKNOWN`、`message` 含「Quartz 状态读取失败」的条目；孤儿扫描失败时同样返回一条「Quartz 孤儿触发器扫描失败」。
+
+#### 错误响应
+
+**非超级管理员**：
+
+```json
+{ "code": 210301, "message": "仅超级管理员可管理定时任务", "data": null, "success": false }
+```
+
+**未带 token**：
+
+```json
+{ "code": 401, "message": "缺少有效的 Authorization 头", "data": null, "success": false }
+```
+
+查 sys_job 表失败时不会返回「全绿」，而是走全局异常处理返回错误码。
+
+#### 业务边界
+
+- 只读，不改 sys_job，也不改 Quartz。
+- **全部** sys_job 行都会比对 sys_job 与 Quartz，不只期望名单内的。
+- 名单内的任务额外比对期望值：期望 ≠ Quartz 实况、期望 ≠ sys_job 都会报。
+- Quartz 实况折算口径：`NORMAL` / `BLOCKED` 会继续触发，算 ACTIVE；`PAUSED` / `COMPLETE` / `NONE` 不会再触发，算 PAUSED；`ERROR` / `UNKNOWN` 一律不健康。
+- `POST /admin/job/{id}/trigger` 在任务未注册时建的一次性调度（`trigger_<id>`）不算孤儿。
+
+---
+
+## 四、契约约束与正确调用方式
+
+### ✅ 正确 / ❌ 错误请求对照
+
+| 做法 | 结论 |
+|---|---|
+| ✅ 用 `quartzState` / `healthy` 判断任务是否真在跑 | 权威源 |
+| ❌ 用 `GET /admin/job` 列表里的 `status` 判断启停 | 那只是 sys_job 意图，会与实况永久漂移 |
+| ✅ 停任务走 `POST /admin/job/{id}/pause` | 会同时摘掉 Quartz 触发器 |
+| ❌ 裸 SQL `UPDATE sys_job SET status='PAUSED'`（+ 重启） | 触发器保留，任务照跑；本接口会报「漂移」 |
+
+---
+
+## 六、边界行为
+
+- 期望名单为空时仍会比对全部任务的 sys_job 与 Quartz 一致性。
+- 配置 `hl.job.health-check.enabled=false` 只关闭启动时和每日的自检日志，不影响本接口。
+- 经网关落到 primary / secondary 任一实例，结果相同：Quartz 是 JDBC 集群，状态读的是共享的 `QRTZ_*` 表。
+
+---
+
+## 六.5 枚举 / 数据字典
+
+### quartzState
+
+**所属字段**: `quartzState` | **类型**: `String`
+
+| 值 | 含义 | 折算 |
+|---|---|---|
+| `NORMAL` | 调度中（库里显示 WAITING / ACQUIRED / EXECUTING） | ACTIVE |
+| `BLOCKED` | 上一次执行尚未结束 | ACTIVE |
+| `PAUSED` | 已暂停 | PAUSED |
+| `COMPLETE` | 不再触发 | PAUSED |
+| `NONE` | 未注册 | PAUSED |
+| `ERROR` | 触发器出错 | 不健康 |
+| `UNKNOWN` | 读取失败 | 不健康 |
+
+---
+
+## 七、不影响范围
+
+- 既有 `/admin/job/**` 端点（增删改查、pause / resume / trigger / logs）的入参、出参、行为均不变。
+- `initScheduledJobs()` 的启动注册逻辑不变，仍然只增不减，不会自动摘除漂移的触发器。
+- 无数据库结构变更，无网关路由变更（沿用 `Path=/admin/job/**`）。
+
+---
+
+## 八、测试环境已验证
+
+真实网关调用（`https://api.test.1814.love`），hl-user-service 已部署 `dev-v3 @ 1ffd758db`（本单合并提交，两个实例在 14:38 完成滚动重启）。token 是自签的（adminId=1002 / test_admin），经 SSH 临时写入 Redis 令牌位，窗口为 14:54:10–14:54:13，用完即还原。
+
+```
+构造：UPDATE sys_job SET status='PAUSED' WHERE job_id=1039   → sys_job=PAUSED，QRTZ_TRIGGERS 仍 WAITING
+修复前代码重启 → [JobHealth] 关键定时任务状态自检通过，共核 5 项           （阴性对照：旧版测不出）
+修复后代码重启 → [JobHealth] jobId=1039 … DB=PAUSED Quartz=NORMAL：sys_job 与 Quartz 漂移 ✓
+GET /admin/job/health（SUPER_ADMIN）→ 200，34 条中仅 1039 healthy=false；1041/1042 healthy=true ✓
+还原 1039 为 ACTIVE 后再调 → 200，34 条全部 healthy=true ✓
+role=ADMIN → code 210301「仅超级管理员可管理定时任务」 ✓
+不带 token → code 401「缺少有效的 Authorization 头」 ✓
+```
+
+本地单测：`mvn -o -pl hl-user-service -am test` 共 5051 例，0 失败 / 0 错误；另做 4 个变异体验证，每个都被测试杀死。
+
+---
+
+## 九、相关历史 PR
+
+- #7538 / #7640：引入 `[JobHealth]` 自检
+- #8268：用 Flyway 下线 1044，同时清理了 `QRTZ_*`
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#7804](https://git.1814.love/wx/HL/issues/7804)
+- 关联 PR: [wx/HL#8337](https://git.1814.love/wx/HL/pulls/8337)
+- 运维须知: `hl-user-service/docs/deployment.md`（定时任务启停）
+
+---
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#7804](https://git.1814.love/wx/HL/issues/7804)
+- **PR**: [#8337](https://git.1814.love/wx/HL/pulls/8337)
+- **Merge commit**: [1ffd758db](https://git.1814.love/wx/HL/commit/1ffd758db)
+
+### 联系人
+
+- **后端负责人**: @jw
@@ -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: "verified"
+frontend_owner: "mmg"
+frontend_ref: "9eb8268fd04f55821a3200b342c18e8cafcc7768"
+target_release: "v2.1"
+verified_at: "2026-09-24"
+status_note: "新增错误码 809123；三个接口新增豁免户清单字段；809122 / 809121 不再报豁免户 | 2026-09-24 mmg 交付:编辑弹窗诊断区五数组→六数组新增「以下户未参与排车(豁免)」块(订单号+reasonName),保存成功提示点名豁免户数;RequirementTab 预检区新增豁免户展示块(不进 ready 不置灰);三接口 JSDoc 补 809123/豁免字段口径;workaround 清理点 grep 零命中;Section 45 例+RequirementTab 33 例全绿"
+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
@@ -0,0 +1,571 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8235"
+title: "看板订单记录新增团车整段接管标记；已接管且零派车行的行程用车在看板与矩阵不再生成虚拟待派卡"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "3f3f14b3cddf5a07e09730173f896084af3f5832"
+target_release: "v2.1"
+verified_at: "2026-09-24"
+status_note: "前端已交付:normalizeBoardOrder 显式归一布尔;isGroupVehicleCovered 只认 === true;卡片状态区「团车接管·可释放」badge+表格配车列 chip/popover 说明行;矩阵抑制与计数减少纯后端,前端无本地对比旧计数逻辑;spec 18 例全绿+fleet/board 557 例全绿,checkpoint 7 项过"
+updated_at: "2026-09-24"
+base: "dev-v3"
+---
+
+# fleet: 团车整段接管标记透出 + 虚拟待派卡抑制
+
+> **存放目录**: `changelogs-v2/{YYYY-MM}/`
+>
+> **服务**: hl-fleet-service (端口 8087)
+> **PR**: #8300
+> **Issue**: #8235
+> **日期**: 2026-09-24
+> **影响范围**: 管理后台「车务看板」订单列表/网格视图、「车辆矩阵」未派清单与网格/月度统计
+
+---
+
+## ⚠️ 关键变化
+
+**团车已整段接管、且在 fleet 侧零派车行的行程用车（TRAVEL）需求，不再在看板与矩阵里生成虚拟待派卡**，也不计入矩阵未派计数。这是主动抑制，不是数据丢失：该需求的车已经由团车统一安排，逐单侧没有活儿可派。若该户在团确认前已经被逐单单独派了车（真实派车行仍存在），这行**照常出卡**，并在看板订单记录上新增 `groupVehicleCovered=true` 标记，提示车务这行属冗余、可释放；只在这种"有真实派车行"的场景下才会看到该标记为 `true`，其余情况（未接管、接送机卡、虚拟待派卡）一律为 `null`，不会出现 `false`。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 看板订单列表 | GET | `/admin/fleet/board/orders` | 响应新增字段+行为变更 | 新增 `groupVehicleCovered`；团车已接管的零派车行 TRAVEL 不再生成虚拟待派卡 |
+| 2 | 矩阵未派订单清单 | GET | `/admin/fleet/matrix/unassigned-orders` | 行为变更 | 同上抑制逻辑，命中的订单不再出现在未派清单 |
+| 3 | 矩阵网格主数据 | GET | `/admin/fleet/matrix/grid` | 行为变更 | `statusCounts` 未派/总量计数不再计入被抑制的虚拟条目 |
+
+> `GET /admin/fleet/matrix/month-counts` 与本清单第 3 项共用完全相同的 `statusCounts` 计算口径（`MatrixController` 自身 javadoc 明确"每月 statusCounts 与相同筛选下 grid.statusCounts 同口径"），受同一行为变更影响，不单列小节，详情参照第 3 项。
+
+---
+
+## 三、接口详情
+
+### 1. 看板订单列表 `GET /admin/fleet/board/orders`
+
+**VO**: `BoardOrderPageReqVO → BoardOrderPageRespVO`（`records: BoardOrderRecordVO[]`）
+
+#### 使用场景
+
+管理后台「车务看板」订单列表/网格视图（`variant=list|grid`），车务人员按状态、日期、团号、车型等筛选待派/已派订单卡片，逐卡执行改派、派车、查看行程等操作。
+
+#### 入参字段表
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| statuses | Query | String[] | ❌ | 枚举：unassigned/unassigned_urgent/holding/holding_urgent/assigned/canceled/completed，可多选 | 状态多选筛选 |
+| status | Query | String | ❌ | 同上枚举，兼容单值 | statuses 兼容别名 |
+| startDayFrom | Query | LocalDate | ❌ | `yyyy-MM-dd` | 行程日期区间起 |
+| startDayTo | Query | LocalDate | ❌ | `yyyy-MM-dd` | 行程日期区间止 |
+| startDate | Query | LocalDate | ❌ | `yyyy-MM-dd` | startDayFrom 兼容别名 |
+| endDate | Query | LocalDate | ❌ | `yyyy-MM-dd` | startDayTo 兼容别名 |
+| vehicleTypeKeys | Query | String[] | ❌ | 车型大类字典值 | 车型多选筛选 |
+| typeKeys | Query | String[] | ❌ | 同上 | vehicleTypeKeys 兼容别名 |
+| driverName | Query | String | ❌ | - | 司机姓名模糊搜索 |
+| keyword | Query | String | ❌ | - | 统一关键字搜索 |
+| contactName | Query | String | ❌ | - | 联系人姓名模糊搜索 |
+| contactKeyword | Query | String | ❌ | - | contactName 兼容别名 |
+| teamNo | Query | String | ❌ | - | 团号模糊搜索 |
+| groupBatchId | Query | Long | ❌ | 等值匹配，只认派车行建行时刻快照（#7443） | 运营团期 ID 筛选 |
+| consultantId | Query | Long | ❌ | - | 定制师 ID 精确筛选 |
+| plannerName | Query | String | ❌ | - | 定制师姓名模糊搜索 |
+| consultantName | Query | String | ❌ | - | plannerName 兼容别名 |
+| variant | Query | String | ❌ | `list`/`grid`，其余值走缺省 100001 视图 | 视图口径 |
+| page（或 pageNo） | Query | Integer | ❌ | ≥1，缺省 1 | 页码 |
+| pageSize | Query | Integer | ❌ | 1-100 | 每页条数 |
+
+#### 出参字段表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | Long | 派车行/虚拟条目主键（虚拟条目为合成 ID） |
+| orderId | Long | 子订单 ID |
+| orderNo | String | 订单编号 |
+| teamNo | String | 团号 |
+| groupBatchId | Long | 运营团期 ID（#7443；非团期订单为 null） |
+| customerName | String | 客户姓名 |
+| assignmentId | Long | 派车行 ID；虚拟条目恒为 null |
+| assignmentGroupId | Long | 派车分组 ID |
+| requirementId | Long | 当前用车需求 ID |
+| assignmentStatus | String | 派单状态码 |
+| virtualPending | Boolean | 真实记录恒显式 `false`（非 null）；虚拟待派卡为 `true` |
+| groupVehicleCovered | Boolean | 新增（#8235）。仅真实记录且该需求已被团车整段接管时为 `true`；未接管、接送机卡、虚拟待派卡一律为 `null`，永不出现 `false` |
+| urgentBadge | String | 紧急标签 |
+| canAssign | Boolean | 是否可派车 |
+| dispatchReadOnly | Boolean | 是否只读（不可操作） |
+| startDate / endDate | LocalDate | 行程起止日期 |
+| currentVehiclePlate / currentDriverName | String | 当前车辆车牌/司机姓名 |
+
+#### 请求示例
+
+```json
+GET /admin/fleet/board/orders?statuses=unassigned&variant=list&page=1&pageSize=20
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "records": [
+      {
+        "id": 9900000000000101,
+        "orderId": 9900000000000201,
+        "orderNo": "HL20261001000001",
+        "teamNo": "26-9901",
+        "groupBatchId": 9900000000000301,
+        "customerName": "示例客户A",
+        "assignmentId": 9900000000000401,
+        "assignmentGroupId": 9900000000000501,
+        "requirementId": 9900000000000601,
+        "assignmentStatus": "PROCESSING",
+        "virtualPending": false,
+        "groupVehicleCovered": true,
+        "urgentBadge": null,
+        "canAssign": true,
+        "dispatchReadOnly": false,
+        "startDate": "2026-11-01",
+        "endDate": "2026-11-05",
+        "currentVehiclePlate": "蒙K·A0001",
+        "currentDriverName": "示例司机"
+      },
+      {
+        "id": -9900000000000701,
+        "orderId": 9900000000000801,
+        "orderNo": "HL20261001000002",
+        "teamNo": null,
+        "groupBatchId": null,
+        "customerName": "示例客户B",
+        "assignmentId": null,
+        "assignmentGroupId": null,
+        "requirementId": 9900000000000901,
+        "assignmentStatus": "unassigned",
+        "virtualPending": true,
+        "groupVehicleCovered": null,
+        "urgentBadge": null,
+        "canAssign": true,
+        "dispatchReadOnly": false,
+        "startDate": "2026-11-02",
+        "endDate": "2026-11-06",
+        "currentVehiclePlate": null,
+        "currentDriverName": null
+      }
+    ],
+    "total": 2,
+    "page": 1,
+    "pageSize": 20
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": { "records": [], "total": 0, "page": 1, "pageSize": 20 },
+  "success": true
+}
+```
+
+无匹配记录时返回空 `records` 数组，`total=0`，不报错。虚拟待派卡取数失败（Nacos `fleet.board.virtual-candidates-enabled=false` 或 order-v3 虚拟候选不可用）时只丢虚拟条目，真实派车行照常返回——这一条与矩阵未派清单口径一致。
+
+**带日期筛选时另有一条既有 fail-closed 口径（非本次引入，本次未改）**：看板按日期筛选走单独的日期候选扫描，该扫描取 order-v3 日期候选页失败，或候选行数据不完整（派车行 `requirement_id` 为空、订单 ID 为空、候选键为空或重复）时，本页整体返回空 `records`、`total=0`、`code=200`，不报错。因此带日期筛选时的空列表**不能等同于**「该日期窗确实无单」；不带日期筛选的查询与矩阵接口不走这条分支，不受影响。测试服当前就有一条命中该口径的夹具数据，见「八、测试环境已验证」末段与 #8301。
+
+#### 错误响应
+
+```json
+{
+  "code": 401,
+  "message": "未登录或登录已过期",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- `groupVehicleCovered` 只在**真实记录**（`virtualPending=false`）且该需求已被团车整段接管时为 `true`；虚拟待派卡（`virtualPending=true`）恒为 `null`。判断"是否已接管"请只用 `=== true`，不要用 `!== true` 当作"未接管"的充分条件去做业务分支——`null` 同时覆盖"未接管"与"该卡不适用本标记"两种情况。
+- 团车已接管但零派车行的 TRAVEL 需求：本接口不再返回该需求的虚拟待派卡（该记录会从列表里消失）。
+- 团车已接管但存在存量真实派车行的 TRAVEL 需求（团确认前已逐单派出的部分）：该行照常出卡，`groupVehicleCovered=true`，车务应据此判断该行属冗余可释放；车辆矩阵占用与行归属不受影响。
+- 非团期订单、以及团期内的接送机（TRANSFER）需求不受本次改动影响，出卡逻辑与计数均不变。
+- 鉴权：未登录 401（网关拦截）。
+
+---
+
+### 2. 矩阵未派订单清单 `GET /admin/fleet/matrix/unassigned-orders`
+
+**VO**: `MatrixUnassignedReqVO → List<MatrixUnassignedOrderVO>`
+
+#### 使用场景
+
+管理后台「车辆矩阵」未派窗口，车务人员按年月查看当月全部未派/待派订单，从中选取虚拟待派卡发起整单派车。
+
+#### 入参字段表
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| year | Query | Integer | ✅ | 1970-9999 | 年份 |
+| month | Query | Integer | ✅ | 1-12 | 月份 |
+| typeKeys | Query | String[] | ❌ | 车型大类字典值 | 车型多选筛选 |
+
+#### 出参字段表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| orderId | String | 订单 ID（订单号） |
+| orderNumericId | Long | 订单数字 ID |
+| orderNo | String | 订单编号 |
+| teamNo | String | 团号 |
+| virtualPending | Boolean | `true`=零派车行的虚拟待派卡（`assignmentId` 为 null，走 requirementId 整单派车入口） |
+| assignmentId | Long | 派车行 ID；虚拟条目为 null |
+| requirementId | Long | 用车需求 ID |
+| vehicleCategory / categoryLabel | String | 车型大类编码/中文名 |
+| customerName | String | 客户姓名 |
+| productName | String | 产品名 |
+| headcountLabel | String | 人数摘要文案 |
+| startDate / endDate | LocalDate | 行程起止日期（未裁剪） |
+| assignmentStatus | String | 派单状态码 |
+| urgentBadge | String | 紧急标签 |
+| vehicleAdvice | Object | 车辆建议；M2 暂返 null |
+| parallelAssignments | Array | 并行派车条目；虚拟待派条目恒为空数组 |
+
+#### 请求示例
+
+```json
+GET /admin/fleet/matrix/unassigned-orders?year=2026&month=11&typeKeys=suv
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": [
+    {
+      "orderId": "9900000000000801",
+      "orderNumericId": 9900000000000801,
+      "orderNo": "HL20261001000002",
+      "teamNo": null,
+      "virtualPending": true,
+      "assignmentId": null,
+      "requirementId": 9900000000000901,
+      "vehicleCategory": "suv",
+      "categoryLabel": "SUV",
+      "customerName": "示例客户B",
+      "productName": "示例产品",
+      "headcountLabel": "2大1小",
+      "startDate": "2026-11-02",
+      "endDate": "2026-11-06",
+      "assignmentStatus": "unassigned",
+      "urgentBadge": null,
+      "vehicleAdvice": null,
+      "parallelAssignments": []
+    }
+  ],
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+```json
+{ "code": 200, "message": "成功", "data": [], "success": true }
+```
+
+`vehicleAdvice` 暂返 null（数据源未建）；Nacos `fleet.board.virtual-candidates-enabled=false` 或 order-v3 候选不可用时只丢虚拟条目，真实条目原样返回（fail-open，不让未派窗口整体打不开）——此为既有降级契约，本次未改。
+
+#### 错误响应
+
+```json
+{
+  "code": 400,
+  "message": "month: 月份必须在 1-12 之间",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- 团车已整段接管且零派车行的 TRAVEL 需求不再出现在本清单（原本会以一条 `virtualPending=true` 的条目出现，现在整条消失）。
+- 该需求若存在存量真实派车行，本清单不受影响——本清单只承载"待派"的虚拟条目，真实已派条目不在本接口的返回范围内（走看板订单列表接口查看）。
+- 非团期订单、接送机（TRANSFER）需求不受影响。
+- 鉴权：需 `AdminContextUtil` 权限检查。
+
+---
+
+### 3. 矩阵网格主数据 `GET /admin/fleet/matrix/grid`
+
+**VO**: `MatrixGridReqVO → MatrixGridRespVO`
+
+#### 使用场景
+
+管理后台「车辆矩阵」主视图，按年月+车队/车型/状态筛选渲染车辆甘特图与顶部统计条。`statusCounts` 驱动顶部"未派/已派/合计"计数徽标。
+
+#### 入参字段表
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| year | Query | Integer | ✅ | - | 年份 |
+| month | Query | Integer | ✅ | 1-12（越界由 Service 返 605010，非 400） | 月份 |
+| season | Query | String | ❌ | `active`/`pending`/`archived`/`blacklist`，缺省 active | 车辆季节状态 |
+| fleetTeamIds | Query | Long[] | ❌ | - | 车队 ID 多选 |
+| typeKeys | Query | String[] | ❌ | 车型大类字典值 | 车型多选 |
+| status | Query | String | ❌ | `all`/`unassigned`/`assigned` | 状态口径（粗粒度） |
+| statuses | Query | String[] | ❌ | `unassigned`/`unassigned_urgent`/`holding`/`holding_urgent`/`assigned`/`completed`；非空时优先于 status | 状态口径（细粒度） |
+
+#### 出参字段表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| year / month | Integer | 回显查询年月 |
+| daysInMonth | Integer | 当月天数（28-31） |
+| todayDay | Integer | 今日是第几天；非当月查询为 null |
+| weekendDays | Integer[] | 周末日序号列表 |
+| vehicles | Array | 车辆行数组（每辆车含其派车段/衔接/重叠子数组，本次未变更） |
+| fleetTeamCounts | Array | 车队维度计数，本次未变更 |
+| statusCounts.totalAssignments | Integer | 有效派车行总数 |
+| statusCounts.unassignedAssignments | Integer | 未派派车行数（含虚拟条目）——本次改动后计数减少：被团车整段接管且零派车行的虚拟条目不再计入 |
+| statusCounts.assignedAssignments | Integer | 已派派车行数 |
+| statusCounts.totalOrders | Integer | 去重订单总数 |
+| statusCounts.unassignedOrders | Integer | 含至少一个未派项的去重订单数——同上，计数口径同步减少 |
+| statusCounts.partialOrders | Integer | 部分派车的去重订单数 |
+| statusCounts.assignedOrders | Integer | 全部派车完成的去重订单数 |
+| statusCounts.effectiveStatusCounts | Object | 固定五键（unassigned/unassigned_urgent/holding/holding_urgent/assigned）分面计数 |
+| unassignedWindowCount | Integer | 未派窗口角标计数，口径与 unassignedOrders 一致 |
+
+#### 请求示例
+
+```json
+GET /admin/fleet/matrix/grid?year=2026&month=11&season=active
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "year": 2026,
+    "month": 11,
+    "daysInMonth": 30,
+    "todayDay": null,
+    "weekendDays": [1, 7, 8, 14, 15, 21, 22, 28, 29],
+    "vehicles": [],
+    "fleetTeamCounts": [],
+    "statusCounts": {
+      "totalAssignments": 118,
+      "unassignedAssignments": 6,
+      "assignedAssignments": 112,
+      "totalOrders": 95,
+      "unassignedOrders": 5,
+      "partialOrders": 2,
+      "assignedOrders": 88,
+      "effectiveStatusCounts": {
+        "unassigned": 4,
+        "unassigned_urgent": 1,
+        "holding": 3,
+        "holding_urgent": 0,
+        "assigned": 112,
+        "completed": 40
+      }
+    },
+    "unassignedWindowCount": 5
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "year": 2026, "month": 11, "daysInMonth": 30, "todayDay": null,
+    "weekendDays": [], "vehicles": [], "fleetTeamCounts": [],
+    "statusCounts": {
+      "totalAssignments": 0, "unassignedAssignments": 0, "assignedAssignments": 0,
+      "totalOrders": 0, "unassignedOrders": 0, "partialOrders": 0, "assignedOrders": 0,
+      "effectiveStatusCounts": {"unassigned":0,"unassigned_urgent":0,"holding":0,"holding_urgent":0,"assigned":0,"completed":0}
+    },
+    "unassignedWindowCount": 0
+  },
+  "success": true
+}
+```
+
+虚拟候选源不可用时按同一 `BoardCandidateSource` 降级契约 fail-open：只丢虚拟条目对 `statusCounts` 未派计数的贡献，真实派车行的统计不受影响。
+
+#### 错误响应
+
+```json
+{
+  "code": 605010,
+  "message": "月份必须在 1-12 之间",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- `statusCounts` 的未派相关计数（`unassignedAssignments`/`unassignedOrders`/`unassignedWindowCount`，以及 `effectiveStatusCounts.unassigned`/`unassigned_urgent`）在本次改动后会同步减少：被团车整段接管且零派车行的虚拟条目不再参与统计。这不是数据异常，前端若有本地缓存/对比旧计数的逻辑需知悉此变化。
+- `assignedAssignments`/`assignedOrders` 等已派计数不受影响；`vehicles[]` 车辆行的段位数据与占用计算不受影响。
+- `GET /admin/fleet/matrix/month-counts` 与本接口共用完全相同的 `statusCounts` 计算口径，受同一行为变更影响。
+- 鉴权：需 `AdminContextUtil` 权限检查。
+
+---
+
+## 四、契约约束与正确调用方式
+
+### ✅ 正确 / ❌ 错误用法对照
+
+| 场景 | 说明 |
+|------|------|
+| ✅ 判断是否显示"可释放"提示 | `record.groupVehicleCovered === true` |
+| ✅ 判断"不显示提示" | `record.groupVehicleCovered !== true`（覆盖 `null` 与字段不存在两种情况） |
+| ❌ 用 `groupVehicleCovered === false` 做判断分支 | 该值永不出现 `false`，只会是 `true` 或 `null`，这样写的分支永远走不到 |
+| ❌ 把矩阵未派计数的减少当作接口故障 | 团车已接管、零派车行的订单不再计入未派计数，是预期行为，不是数据丢失 |
+
+### 切换状态时的必要动作
+
+无。三个接口均为只读 GET，`groupVehicleCovered` 与虚拟待派卡的抑制均由后端在读取时实时计算，不接受前端传参覆盖，也无需前端在请求前做任何字段置空等准备动作。
+
+---
+
+## 五、数据库行为
+
+三个接口均为只读查询，无新增或变更的写库行为。`groupVehicleCovered` 由 `hl-fleet-service` 在读取时实时计算：按看板卡片当前用车需求 ID 匹配该订单从 `hl-order-service-v3` 经 Feign 聚合拿到的需求身份集合，取其"是否已被团车整段接管"标记；不产生新表，也不改变既有列的语义。
+
+---
+
+## 六、边界行为
+
+- 未登录 → 401（网关拦截）
+- 无匹配记录 → 200 + 空数组/空列表，不报错
+- 矩阵网格 `month` 越界（不在 1-12）→ 605010 业务错误码，非 400
+- 虚拟候选源（order-v3 侧）不可用或 Nacos 开关关闭 → fail-open，只丢虚拟条目，真实记录与真实计数原样返回
+- 看板带日期筛选时，日期候选扫描取数失败或候选行不完整 → 200 + 整页空（既有 fail-closed，非本次引入，见接口 1「空数据 / 降级响应」；矩阵接口不走该分支）
+- 老数据兼容：历史已生成的虚拟待派卡在下次读取时按新逻辑重新计算，不残留旧结果；`groupVehicleCovered` 对改动前的历史真实记录同样实时计算，无需迁移
+
+---
+
+## 六.5、枚举 / 数据字典
+
+### groupVehicleCovered（团车整段接管标记）
+
+**所属字段**: `BoardOrderRecordVO.groupVehicleCovered` | **类型**: `Boolean`
+
+本次不新增字典枚举类；该字段是只会取两种取值的标记位（不是完整的三态布尔）：
+
+| 值 | 说明 |
+|----|------|
+| `true` | 仅真实记录：该需求已被团车整段接管，此行属冗余可释放 |
+| `null` | 未接管 / 接送机卡 / 虚拟待派卡 / 不适用；`false` 永不出现 |
+
+---
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 | 变化说明 |
+|------|------|------|----------|
+| `BoardOrderRecordVO.groupVehicleCovered` | 字段不存在 | 新增，`true`/`null` 两态 | 仅真实记录且被团车整段接管时为 `true` |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 | 影响 |
+|------|------|------|------|
+| 团车已接管、零派车行的 TRAVEL 需求 | 在看板订单列表 / 矩阵未派清单里生成一张虚拟待派卡 | 不再生成虚拟待派卡，该条目从列表中消失 | 影响 3 个接口的记录集合与矩阵计数 |
+| 团车已接管、存在存量真实派车行的 TRAVEL 需求 | 照常出卡，无标记区分冗余 | 照常出卡，新增 `groupVehicleCovered=true` 标记 | 仅看板订单列表新增标记，出卡数量不变 |
+| 矩阵 `statusCounts` 未派相关计数 | 含上述被抑制的虚拟条目 | 不含 | `unassignedAssignments`/`unassignedOrders`/`unassignedWindowCount`/`effectiveStatusCounts.unassigned*` 同步减少 |
+| 非团期订单 / 接送机需求 | 不受影响 | 不受影响 | 无 |
+
+---
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 否。`groupVehicleCovered` 是新增字段，旧前端未读取该字段不受影响；虚拟卡抑制导致的记录/计数减少是数据层面的行为变化，不改变接口结构或错误码。
+- **前端是否必须同步上线**: 是（针对希望展示"可释放"提示的场景）。若前端有基于虚拟待派卡数量做的本地校验或缓存对比逻辑，需知悉计数会因本次改动而减少。
+- **前端 workaround 清理点**: 无——这是新增能力，此前前端没有对应的字段或逻辑需要清理。
+
+---
+
+## 七、不影响范围
+
+- **仅影响**：
+  - 管理后台「车务看板」订单列表/网格视图（`/admin/fleet/board/orders`）
+  - 管理后台「车辆矩阵」未派窗口（`/admin/fleet/matrix/unassigned-orders`）
+  - 管理后台「车辆矩阵」网格与月度统计条（`/admin/fleet/matrix/grid`、`/admin/fleet/matrix/month-counts`）
+
+- **零影响**：
+  - 团期本身的团级配车流程与团级基线计算
+  - 车辆矩阵的车辆占用/甘特图段位计算（`vehicles[]` 结构与数据不变）
+  - 接送机（TRANSFER）需求的看板/矩阵可见性与计数
+  - 非团期订单的看板/矩阵可见性与计数
+  - 看板订单详情（`/admin/fleet/board/orders/{orderId}`）、出行人列表、操作时间线等其余看板接口
+  - C 端与定制师端相关接口
+
+---
+
+## 八、测试环境已验证
+
+测试服部署：`hl-order-service-v3` 2026-09-24 02:52:37 / `hl-fleet-service` 2026-09-24 02:53:43，均部署到 commit `ea9cd0d33`（deploy-status 均为 ok；两服务必须同批部署，fleet 侧的接管判定依赖 order-v3 的打标）。
+
+```
+GET /admin/fleet/board/orders（不带日期筛选，全量翻页，共 243 条记录）
+  → groupVehicleCovered 键在全部 243 条记录中均存在（0 条缺失）
+  → 取值只有 true（5 条，均为真实派车行）与 null（205 条真实卡 + 33 条虚拟待派卡）
+  → 0 条记录取值为 false ✓
+```
+
+```
+GET /admin/fleet/matrix/unassigned-orders?year=Y&month=M（2026-09-24 03:50~03:51，2026-08 至 2027-08 逐月 13 次调用）
+  → 13 次均 HTTP 200 / code=200
+  → 12 张被团车整段接管、fleet 侧零派车行的订单（出行日期落在 2026-10、2026-11、2027-03，均在查询月份内）
+    在 13 个月的响应原文中出现 0 次 ✓
+  → 对照组 4 张未被接管的零派车行订单（出行 2026-11-15~11-17）全部出现在 2026-11 的未派清单中 ✓
+GET /admin/fleet/matrix/grid?year=2026&month=11
+  → HTTP 200 / code=200，statusCounts 正常下发（unassignedOrders=23，与同月未派清单 23 条一致）✓
+```
+矩阵接口不走看板的日期候选扫描分支，下方 #8301 的限定对矩阵不适用。
+
+已知测试环境限定（与本次改动无关，独立跟踪于 #8301）：看板按日期筛选查询，筛选窗口与 2026-11-05~2026-11-07 有交集时，因测试夹具数据缺陷（某条派车行的 `requirement_id` 为 null）导致该日期筛选分支整体返回 0 条；不带日期筛选的查询不受影响，本次改动的验证结论（上方 243 条全量核对）不依赖该日期区间。
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#8235](https://git.1814.love/wx/HL/issues/8235)
+- 关联 Issue（测试环境已知缺口，独立跟踪）: [wx/HL#8301](https://git.1814.love/wx/HL/issues/8301)
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8235](https://git.1814.love/wx/HL/issues/8235)
+- **PR**: [#8300](https://git.1814.love/wx/HL/pulls/8300)
+- **Merge commit**: [ea9cd0d33](https://git.1814.love/wx/HL/commit/ea9cd0d33)
+
+### 联系人
+
+- **后端负责人**: @wx
+- **前端负责人**: @mmg
@@ -0,0 +1,453 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8248"
+title: "尾款收款模型重构：确认行程主报账人必填化 + 核单欠收硬闸按主报账人豁免 + 财务应收台账"
+consumer: "admin"
+author: "yst"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "b556da24791ca0ecf2393ef0e8505989c7996f8a"
+target_release: "v2.1"
+verified_at: "2026-09-24"
+status_note: "尾款收款模型重构 Epic（方案甲·全实时）。PR-6a #8274(581062) + PR-5a #8263(584082) + PR-3 #8207 合并 + PR-5b #8325/②#8336/③#8328 部署。部署：hl-order-service-v3 dev-v3 @ baf643412，2026-09-24 滚动部署（8086/8186 均 UP）。部署后 fin↔order 对账 D1~D7 现网零漂移。 | 2026-09-24 mmg 交付:①LockModal 无主报账人选人必填化(星号+引导+置灰双保险);②两接口 JSDoc 补 581062/584082 新口径;③新增应收台账只读页(api/finance/receipt.js+finance/receipt/receivable,原型 recv-ledger 对齐,代收欠收互斥直显,订单号链接钻取);spec 5+3+2 例全绿;⚠菜单「收款管理/应收台账」依赖后端 sys_menu 补配(changelog 未提及,请后端补配)"
+updated_at: "2026-09-24"
+base: "dev-v3"
+---
+
+# 尾款收款模型重构：确认行程主报账人必填化 + 核单欠收硬闸豁免 + 财务应收台账
+
+> **存放目录**: 二期(v3) → `changelogs-v2/2026-09/`
+>
+> **服务**: hl-order-service-v3（订单核心域 + 核单域）· hl-finance（收款域）
+> **Issue**: https://git.1814.love/wx/HL/issues/8248 （主） · https://git.1814.love/wx/HL/issues/8265 · https://git.1814.love/wx/HL/issues/8191
+> **PR**: https://git.1814.love/wx/HL/pulls/8274 · https://git.1814.love/wx/HL/pulls/8263 · https://git.1814.love/wx/HL/pulls/8207
+> **日期**: 2026-09-24
+> **影响范围**: 管理后台「订单确认行程弹框」「核单提交」「财务应收台账」三处
+
+---
+
+## ⚠️ 关键变化（前端必读）
+
+- **确认行程前必须先有主报账人**：普通订单点「确认行程」时，如果本单还没有主报账人且弹框里也没选人，接口直接报 **581062「请先指定本单主报账人（尾款代收人）」**，确认动作不发生。确认弹框必须提供主报账人选择项并传 `reporterAssignmentId`。
+- **核单欠收硬闸放行面扩大**：提交核单时「尾款未收齐」不再一律拦死——只要本单已指定主报账人，欠收部分记为主报账人代收口径，允许提交核单；**只有「欠钱且无人兜底（无主报账人）」的单**才会继续被 584082 拦截。
+- **新增财务应收台账只读分页接口**：`GET /admin/finance/receipt/receivable/page`，订单维度看应收/已收/代收/欠收，代收列与欠收列互斥（指定主报账人后欠收挪入代收）。
+
+---
+
+## 一、接口背景
+
+尾款收款模型重构 Epic（方案甲·全实时，不建债表）。旧模型里尾款由司导线下代收，经过「现场垫付 → 报销 → 核单 → 支付完成」长链路后才回写订单已付金额，导致：
+
+- 核单时「尾款未收齐」一律硬拦，司导已代收但还没走完报销回写的单被卡死；
+- 财务看不到「这笔钱到底在谁手里」——是客户还欠着，还是司导代收未回款。
+
+新模型的三条规则：
+
+1. **金额实时算**：应收/已收/欠收全部实时计算，不落地中间债表；
+2. **归属实时读主报账人**：订单层有主报账人（reporterRank=PRIMARY）时，未收齐部分视为「主报账人代收中」；没有主报账人时才是「客户欠收」；
+3. **结清看核单终态**：核单完成（FINALIZED）后由财务域支付完成事件回写已付金额，闭环。
+
+本次三个接口分别对应：确认行程时把「主报账人」变成前置条件（接口1）、核单欠收硬闸按主报账人豁免（接口2）、财务侧新增应收台账把代收/欠收分列展示（接口3）。
+
+---
+
+## 二、变更清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 确认行程 | POST | `/v3/admin/order/{orderId}/confirm-itinerary` | 行为变更 + 新错误码 | 确认前必须已有主报账人，否则报 581062；入参出参结构不变 |
+| 2 | 提交核单（完成核单） | POST | `/v3/admin/order/{orderId}/settlement/finalize` | 行为变更 | 584082 只拦「无主报账人且欠收」的单；有主报账人放行，欠收走代收口径留痕 |
+| 3 | 财务应收台账分页 | GET | `/admin/finance/receipt/receivable/page` | **新增接口** | 订单维度应收/已收/代收/欠收分页，只读 |
+
+> 说明：接口2 任务背景里常被称为「核单提交/生成报账」链路，硬闸实际落在「完成核单」写接口上；`GET /v3/admin/order/{orderId}/settlement/reports/reimbursement`（查询主报账人报账表）出参结构**无任何变化**。
+
+---
+
+## 三、接口详情
+
+### 接口1：确认行程 `POST /v3/admin/order/{orderId}/confirm-itinerary`
+
+#### 使用场景
+
+订单详情页点「确认行程」，把订单从「定制中」推进到「待出行」。普通订单在确认弹框中选择本单主报账人（尾款代收人）后提交；团期子订单由团期扇出自动带主报账人，一般无需选择。
+
+- 认证：管理后台 JWT
+- 幂等性：非幂等写操作，重复确认会被状态机拦截（订单已不在「定制中」）
+- 限流：无
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 说明 |
+|------|------|------|------|------|
+| orderId | Path | Long | 是 | 订单 ID |
+| reporterAssignmentId | Body | Long | 否 | 新的主报账人人员安排 ID；不传则沿用当前主报账人。**注意：本单当前没有主报账人时，不传会被 581062 拦截** |
+
+请求体整体可空（`{}` 或不传 body），但仅当订单已有主报账人时才能通过。
+
+#### 出参 `Result<OrderTransitionRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| success | Boolean | 是否成功 |
+| oldStatus | String | 变更前订单状态（确认成功时恒为 `CUSTOMIZING`） |
+| newStatus | String | 变更后订单状态（确认成功时恒为 `PENDING_DEPARTURE`） |
+| oldFlowStatus | String | 变更前流程状态 |
+| newFlowStatus | String | 变更后流程状态 |
+| triggeredEvents | Array<String> | 本次转换派生的事件列表 |
+
+#### 业务边界
+
+- 仅「定制中」订单可确认；5 项前置 checklist 未全过时仍报 581036（既有行为不变）。
+- 传了 `reporterAssignmentId` 会在确认前先把该人员置为主报账人，再校验主报账人存在性——即「弹框选人」与「确认」是一步完成的。
+- **团期子订单**：团期人员扇出后订单层已有主报账人副本，不传 `reporterAssignmentId` 也放行；扇出延迟窗口期（极短）可能暂无主报账人被 581062 拦截，稍候重试即可。
+- `reporterAssignmentId` 传非数字/非法格式报 581046（既有行为不变）。
+
+#### 示例
+
+典型成功（确认弹框选了主报账人）见「八、示例」8.1；无主报账人被拦见 8.3。
+
+---
+
+### 接口2：提交核单（完成核单）`POST /v3/admin/order/{orderId}/settlement/finalize`
+
+#### 使用场景
+
+核单页核对完主报账、单团核算后点「提交核单/完成核单」，冻结核单快照并把订单推进到已核单。
+
+- 认证：管理后台 JWT
+- 幂等性：非幂等写操作，重复提交会被核单状态拦截
+- 限流：无
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 说明 |
+|------|------|------|------|------|
+| orderId | Path | Long | 是 | 订单 ID（无请求体） |
+
+#### 出参
+
+`Result<SettlementSubmitRespVO>`（核单提交结果，结构无变化）。
+
+#### 业务边界（本次核心变化）
+
+| 场景 | 变更前 | 变更后 |
+|------|--------|--------|
+| 尾款未收齐 + **无主报账人** | 报 584082 拦截 | 报 584082 拦截（不变） |
+| 尾款未收齐 + **已有主报账人** | 报 584082 拦截 | **放行**，欠收记为主报账人代收口径 |
+| 尾款已收齐 | 放行 | 放行（不变） |
+
+- 「放行」不等于「欠收已清」：欠收金额会留在报账快照的欠收勾稽字段里，由财务域下游追款兜底，前端不要把「提交成功」理解为「钱已收齐」。
+- 代收口径：应代收 = 核单总额 − 客户线上已付（`paidAmount`）。旧的「司机现金代收登记」项已废止，代收不再计入已付金额。
+- 配套读接口 `GET /v3/admin/order/{orderId}/settlement/reports/reimbursement`（查询主报账人报账表）出参结构无变化。
+
+#### 示例
+
+欠收但有主报账人提交成功、无主报账人被 584082 拦截，见「八、示例」8.2 / 8.3。
+
+---
+
+### 接口3：财务应收台账分页 `GET /admin/finance/receipt/receivable/page`（新增）
+
+#### 使用场景
+
+财务「应收台账」页，按订单维度查看应收/已收/代收/欠收，用于内部财务对账与追款。
+
+- 认证：管理后台 JWT（网关注入）
+- 幂等性：只读
+- 限流：无
+
+#### 入参（Query）
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| page | Integer | 否 | 1 | 页码 |
+| pageSize | Integer | 否 | 20 | 每页条数 |
+| keyword | String | 否 | 空 | 搜索关键字（团号 / 客户姓名 / 产品名 / 订单号 模糊）；空=不限 |
+| receivableStatus | String | 否 | 空 | 收款状态筛选：`UNPAID` / `PARTIAL` / `DONE`；空或非法值=不按状态过滤 |
+
+#### 出参 `Result<PageResult<ReceiptReceivableRowRespVO>>`
+
+分页外层固定为 `records` / `total` / `page` / `pageSize`。`records[]` 行字段：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | String | 订单 ID（字符串防精度丢失） |
+| orderNo | String | 订单号 |
+| teamNo | String | 团号 |
+| productName | String | 产品名 |
+| customerName | String | 客户姓名 |
+| customerPhone | String | 客户手机号（**明文**，内部财务对账用） |
+| orderStatus | String | 订单粗状态枚举值（见「六、枚举」） |
+| orderStatusName | String | 订单粗状态中文名 |
+| receivableStatus | String | 收款状态：`UNPAID` 待收款 / `PARTIAL` 部分收款 / `DONE` 已收讫 |
+| receivableStatusName | String | 收款状态中文名 |
+| receivableAmount | Number | 应收总额（取消单归 0） |
+| paidAmount | Number | 已收金额（毛额，退款不回减） |
+| collectedAmount | Number | 代收金额（主报账人代收中的实时金额；取消单归 0） |
+| balanceAmount | Number | 欠收金额（未指定主报账人的实时欠收；取消单归 0） |
+
+#### 业务边界
+
+- **代收列与欠收列互斥**：同一行 `collectedAmount` 与 `balanceAmount` 必有一列为 0——订单指定了主报账人，未收齐部分进代收列；未指定主报账人，进欠收列。两列合计恒等于该单实时待收尾款。
+- 收款状态由金额派生：已收=0 → `UNPAID`；已收>0 且仍有欠收/代收 → `PARTIAL`；欠收代收均=0 且已收>0 → `DONE`。
+- 只读接口，无登记/核销按钮；追款动作不在本接口。
+- 本接口在 hl-finance 服务（`/admin/finance/*`），与订单域接口不同服务，但同一网关入口。
+
+#### 示例
+
+见「八、示例」8.1 / 8.2。
+
+---
+
+## 四、接口入参
+
+各接口入参已分别内联在「三、接口详情」各小节，不再汇总大表。
+
+## 五、出参字段
+
+各接口出参已分别内联在「三、接口详情」各小节，不再汇总大表。
+
+## 六、枚举 / 数据字典
+
+### 6.1 reporterRank（报账人等级，接口1 相关概念）
+
+| 值 | 中文名 | 说明 |
+|----|--------|------|
+| PRIMARY | 主报账人 | 单内唯一；本次起确认行程前必须存在（尾款代收人） |
+| SECONDARY | 次报账人 | 单内唯一，不满足接口1 的前置条件 |
+| NONE | 非报账人 | 默认值 |
+
+### 6.2 receivableStatus（收款状态，接口3 行字段 + 筛选项）
+
+| 值 | 中文名 | 派生条件 |
+|----|--------|----------|
+| UNPAID | 待收款 | 已收金额 = 0 |
+| PARTIAL | 部分收款 | 已收 > 0 且（欠收 + 代收）> 0 |
+| DONE | 已收讫 | 欠收 + 代收 = 0 且已收 > 0 |
+
+### 6.3 orderStatus（订单粗状态，接口3 行字段）
+
+| 值 | 中文名 |
+|----|--------|
+| PENDING_PAY | 待支付 |
+| CUSTOMIZING | 定制中 |
+| PENDING_DEPARTURE | 待出行 |
+| TRAVELLING | 出行中 |
+| COMPLETED | 已完成 |
+| CANCELLED | 已取消 |
+
+## 七、错误码
+
+| 错误码 | 报文 | 触发接口 | 说明 |
+|--------|------|----------|------|
+| **581062** | 请先指定本单主报账人（尾款代收人） | 接口1 确认行程 | **本次新增**。确认前置换后仍无主报账人时抛出；团期单扇出延迟窗口期被拦属预期，稍候重试 |
+| 581036 | 确认订单前置校验未通过，请先补全所有必填项 | 接口1 确认行程 | 既有。5 项 checklist 未全过 |
+| 581046 | 报账人ID格式非法，须为有效的数字ID | 接口1 确认行程 | 既有。`reporterAssignmentId` 格式非法 |
+| 584082 | 存在待收尾款，请收齐后再提交核单 | 接口2 提交核单 | 既有但**触发条件收紧**：现在仅「无主报账人且欠收不为 0」才抛出；有主报账人的欠收单不再触发 |
+
+## 八、示例
+
+### 8.1 典型成功
+
+**接口1：确认行程（确认弹框选了主报账人）**
+
+```http
+POST /v3/admin/order/2086272700140957697/confirm-itinerary
+Authorization: Bearer <admin token>
+Content-Type: application/json
+
+{
+  "reporterAssignmentId": 2072930844657283074
+}
+```
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "success": true,
+    "oldStatus": "CUSTOMIZING",
+    "newStatus": "PENDING_DEPARTURE",
+    "oldFlowStatus": "CUSTOMIZING",
+    "newFlowStatus": "CONFIRMED",
+    "triggeredEvents": ["CHECKLIST_CONFIRMED"]
+  },
+  "success": true
+}
+```
+
+**接口3：应收台账分页（指定了主报账人的在途单，欠收进代收列）**
+
+```http
+GET /admin/finance/receipt/receivable/page?page=1&pageSize=20&keyword=26-0001
+Authorization: Bearer <admin token>
+```
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "records": [
+      {
+        "id": "2086272700140957697",
+        "orderNo": "HL20260920001",
+        "teamNo": "26-0001",
+        "productName": "呼伦贝尔草原 5 日游",
+        "customerName": "张三",
+        "customerPhone": "13800001111",
+        "orderStatus": "TRAVELLING",
+        "orderStatusName": "出行中",
+        "receivableStatus": "PARTIAL",
+        "receivableStatusName": "部分收款",
+        "receivableAmount": 12800.00,
+        "paidAmount": 6400.00,
+        "collectedAmount": 6400.00,
+        "balanceAmount": 0
+      }
+    ],
+    "total": 1,
+    "page": 1,
+    "pageSize": 20
+  },
+  "success": true
+}
+```
+
+### 8.2 边界情况
+
+**接口2：尾款未收齐但已有主报账人——变更前被拦、变更后放行**
+
+```http
+POST /v3/admin/order/2086272700140957697/settlement/finalize
+Authorization: Bearer <admin token>
+```
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": { "submitted": true },
+  "success": true
+}
+```
+
+> 注意：提交成功不代表欠收已清，欠收金额留在报账快照勾稽字段中，由财务域下游追款。
+
+**接口3：未指定主报账人的订单——同一笔未收齐金额进欠收列**
+
+```json
+{
+  "receivableStatus": "PARTIAL",
+  "receivableStatusName": "部分收款",
+  "receivableAmount": 12800.00,
+  "paidAmount": 6400.00,
+  "collectedAmount": 0,
+  "balanceAmount": 6400.00
+}
+```
+
+**接口3：空结果（关键词无匹配）**
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": { "records": [], "total": 0, "page": 1, "pageSize": 20 },
+  "success": true
+}
+```
+
+### 8.3 业务失败
+
+**接口1：无主报账人且弹框未选人 → 581062**
+
+```http
+POST /v3/admin/order/2086272700140957697/confirm-itinerary
+Authorization: Bearer <admin token>
+Content-Type: application/json
+
+{}
+```
+
+```json
+{
+  "code": 581062,
+  "message": "请先指定本单主报账人（尾款代收人）",
+  "data": null,
+  "success": false
+}
+```
+
+**接口2：尾款未收齐且无主报账人 → 584082（唯一仍会被拦的情形）**
+
+```http
+POST /v3/admin/order/2086272700140957697/settlement/finalize
+Authorization: Bearer <admin token>
+```
+
+```json
+{
+  "code": 584082,
+  "message": "存在待收尾款，请收齐后再提交核单",
+  "data": null,
+  "success": false
+}
+```
+
+## 九、业务边界
+
+- 接口1 仅适用「定制中 → 待出行」确认动作；其他状态变更不受影响。
+- 接口1 团期子订单正常路径无需前端传参（扇出已带主报账人）；扇出延迟窗口被 581062 拦时引导「稍候重试」即可，不要当成数据异常。
+- 接口2 放行后核单可正常完成，但财务仍会在应收台账/报账勾稽里看到代收欠收金额；「已核单」不等于「已收讫」。
+- 接口3 为只读台账，不提供任何写操作；`customerPhone` 为明文，仅限内部财务对账场景使用，前端不要在非财务页面引用该接口。
+- 接口3 已取消订单的金额列全部归 0。
+
+## 十、修改前后对比
+
+### 10.1 字段级对比
+
+| 接口 | 字段 | 变更 |
+|------|------|------|
+| 接口1 确认行程 | 入参/出参全部字段 | 无变化（`reporterAssignmentId` 仍为非必填，但语义从「纯可选置换」变为「无主报账人时事实必填」） |
+| 接口2 提交核单 | 入参/出参全部字段 | 无变化 |
+| 接口3 应收台账 | 全部字段 | 新增接口，无对比 |
+
+### 10.2 行为级对比
+
+| 场景 | 变更前 | 变更后 |
+|------|--------|--------|
+| 确认行程时本单无主报账人 | 直接确认成功 | 报 581062，确认不发生；传 `reporterAssignmentId` 选人后放行 |
+| 核单时尾款未收齐、有主报账人 | 报 584082 拦死 | 放行，欠收记主报账人代收口径 |
+| 核单时尾款未收齐、无主报账人 | 报 584082 拦死 | 报 584082 拦死（不变） |
+| 应代收口径 | 核单总额 −（已付 − 司机现金代收登记合计） | 核单总额 − 已付（司机现金代收登记项已废止） |
+| 财务看尾款归属 | 无接口可看 | 应收台账代收/欠收互斥分列 |
+
+## 十一、影响评估 / 回滚
+
+- **破坏性**：接口1 对「此前无主报账人也能确认」的流程是行为收紧，普通订单确认弹框**必须**支持选择主报账人并传 `reporterAssignmentId`，否则确认会被 581062 拦截——**前端需要同步上线**。
+- 接口2 是放行面扩大，前端对 584082 的既有提示逻辑继续有效（触发面变窄），无强制改动；但原来「被拦 → 引导收尾款」的引导文案对「有主报账人」场景不再出现，如有相关 workaround 可清理。
+- 接口3 纯新增，不影响存量页面。
+- **回滚**：后端回滚后，接口1 恢复「无主报账人也可确认」、接口2 恢复「欠收一律拦」、接口3 下线（请求返回 404）。回滚期间前端确认弹框保留选人逻辑无副作用（多传字段旧版兼容）。
+
+## 十二、注意事项
+
+- 确认弹框的主报账人候选来自本单人员安排，`reporterAssignmentId` 传人员安排 ID（不是用户 ID、不是员工编号）。
+- 581062 与 581036 可能先后出现：先补 checklist（581036），再补主报账人（581062），前端引导顺序建议先 checklist 后选人。
+- 「确认成功」「核单提交成功」都不代表尾款已收齐；尾款是否收讫以应收台账 `receivableStatus=DONE` 为准。
+- 应收台账的代收/欠收两列互斥，前端渲染时不要对两列同时展示非 0 值做兜底合并——合计即实时待收尾款。
+- 本 Epic 还包含财务域支付完成后回写订单已付金额的配套链路（PR-5b 起），对管理后台 REST 契约无新增字段，不单独列接口。
+
+## 十三、关联 / 联系人
+
+- Issue（主）：https://git.1814.love/wx/HL/issues/8248
+- Issue（确认行程主报账人必填化）：https://git.1814.love/wx/HL/issues/8265
+- Issue（财务应收台账）：https://git.1814.love/wx/HL/issues/8191
+- PR-6a（接口1）：https://git.1814.love/wx/HL/pulls/8274 ｜ merge commit：https://git.1814.love/wx/HL/commit/f6b1960a93
+- PR-5a（接口2）：https://git.1814.love/wx/HL/pulls/8263 ｜ merge commit：https://git.1814.love/wx/HL/commit/a480f3dacd
+- PR-3（接口3）：https://git.1814.love/wx/HL/pulls/8207 ｜ merge commit：https://git.1814.love/wx/HL/commit/768136626e
+- 后端负责人：yst（腰苏图）
@@ -0,0 +1,677 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8268"
+title: "团期人工「确认」：新增确认端点（配置 → 确认），确认后才出合同保险并全团逐户补发；确认物资前移到配置节点；物料门复判端点下线"
+consumer: "admin"
+author: "jw(GIT)"
+change_type: "新增接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "72b5e17cada78a8f491f9dc1cb6af3d9e42ab457"
+target_release: "v2.1"
+verified_at: "2026-09-24"
+status_note: "六节点定案（SRS §0.27.3 / §0.27.5 #2～#5）：「配置 → 确认」由系统自动推进改为人工点「确认」。新增 POST /v3/admin/order/group-batch/{groupBatchId}/confirm（权限码 group-batch:confirm，授 GROUP_BATCH_MANAGER / ADMIN），门 = 房 / 车 / 导游领队 / 摄影四项 ready 全 true 且物资已确认，不满足返新码 589556 并逐项列出未满足项，状态不是 RESOURCE_PREPARING（含重复确认）返 589501；成功后团期进入 MATERIAL_PREPARING、时间线记 BATCH_CONFIRM（确认），事务提交后系统对全团已确认行程的户逐户补发合同与保险。四项 ready 翻真 / 成团 / 免车不再自动推进状态。连带改动：confirm-material 只在 RESOURCE_PREPARING 可调且不再顺带准入待出发（其它状态 589501）；合同保险出具门改为团期已确认（MATERIAL_PREPARING 及之后），确认前手动出具返 589548，文案改为「团期确认后才能出具合同与保险」，合同保险面板 issuable 同口径；POST .../recheck-material-gate 下线（589561 不再抛出）。前端需新增「确认」按钮与 589556 逐项提示、把确认物资按钮挪到配置节点、移除物料门复判入口。 前端已交付并验证：团期详情工具条新增平铺 primary「确认」按钮（仅 RESOURCE_PREPARING，不可撤销二次确认弹窗，589556 逐项清单透 message）；确认物资按钮可调状态翻转为仅 RESOURCE_PREPARING，成功文案引导点「确认」；合同保险 issueTip 改「团期确认后才能出具合同与保险」（issuable 仍直读面板）；recheck-material-gate 前端零调用零删除。SuppliesPanel 13 例+ChipStaffDisplay 5 例+index 7 例全绿，hl-admin@72b5e17c（+8da805a4 回归锁）。"
+updated_at: "2026-09-24"
+base: "dev-v3"
+---
+
+# 团期状态流转: 人工「确认」取代自动推进，确认后才出合同保险（管理后台）
+
+> **服务**: hl-order-service-v3（端口 8086/8186）；权限种子在 hl-user-service
+> **PR**: #8302
+> **Issue**: #8268
+> **日期**: 2026-09-24
+> **影响范围**: 管理后台团期详情页的「确认」按钮（新增）、「确认物资」按钮、「合同保险」页签的出具按钮与可出具提示；原「复判物料门」入口下线
+
+---
+
+## ⚠️ 关键变化
+
+1. **团期不会再自己从「资源准备中」走到「物料准备中」**。改前四项 ready 齐 + 合同保险出齐时系统自动推进；现在必须由团期管理员点「确认」（新端点）。
+2. **合同 / 保险在确认前一律不出**。改前资源准备中四项配齐即可出具；现在确认前手动出具被 589548 拒，面板 `issuable=false`。确认后系统自动给全团已确认行程的户逐户补发。
+3. **确认物资挪到确认之前**。`confirm-material` 以前只在物料准备中可调、还会顺带尝试进入待出发；现在只在资源准备中可调，且只置物资已确认，不改团期状态。
+4. **`recheck-material-gate` 端点已删除**，调用会得到 404。
+
+---
+
+## 一、背景
+
+六节点定案里「配置 → 确认」是一个**不可撤销的人工动作**：确认之后四项配置与物资锁定（锁定写口见 #8269 条目），系统随即对客出合同与保险。因此它不能再由系统在 ready 位翻真时悄悄推进，也需要独立于 `group-batch:manage` 的授权。
+
+| 节点 | 持久态 | 本单之后怎么进入 |
+|---|---|---|
+| 配置 | `RESOURCE_PREPARING` | 成团（不变） |
+| 确认 | `MATERIAL_PREPARING` | **仅**人工调用确认端点 |
+| 出行·待出发 | `PENDING_DEPARTURE` | 七项硬门（不变） |
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 团期确认 | POST | `/v3/admin/order/group-batch/{groupBatchId}/confirm` | 新增接口 | 配置 → 确认；门不满足 589556 逐项回执 |
+| 2 | 确认团期物资 | POST | `/v3/admin/order/group-batch/{groupBatchId}/confirm-material` | 修改（可调状态 + 行为） | 只在 `RESOURCE_PREPARING` 可调；不再顺带准入待出发 |
+| 3 | 手工复判物料门 | POST | `/v3/admin/order/group-batch/{groupBatchId}/recheck-material-gate` | 删除接口 | 自动推进已删，复判入口随之下线 |
+| 4 | 手动开合同 / 保险（GB-ADM-031） | POST | `/v3/admin/order/group-batch/{groupBatchId}/contracts/issue` | 修改（前置门 + 文案） | 确认前 589548，文案改 |
+| 5 | 作废重开合同 / 保险（GB-ADM-031） | POST | `/v3/admin/order/group-batch/{groupBatchId}/contracts/reissue` | 修改（前置门 + 文案） | 同上 |
+| 6 | 合同保险面板（GB-ADM-030） | GET | `/v3/admin/order/group-batch/{groupBatchId}/contracts` | 修改（出参语义） | `issuable` 改为「团期已确认」 |
+
+网关无改动（均在既有 `/v3/admin/order/group-batch` 前缀下）。
+
+---
+
+## 三、接口详情
+
+### 1. 团期确认 `POST /v3/admin/order/group-batch/{groupBatchId}/confirm`
+
+**VO**: `Result<Void>`（无请求体）
+
+#### 使用场景
+
+团期详情页「配置」节点的「确认」按钮。房、车、导游领队、摄影四项配齐且物资已确认后，团期管理员点确认，团期进入「确认」节点，配置锁定，系统开始逐户出合同与保险。**没有撤销确认。**
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long | ✅ | 团期主键 | 不存在返 589500 |
+
+无请求体。
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data | Void | 成功返回 null；团期状态已是 `MATERIAL_PREPARING`，重新拉详情即可看到 `stage=CONFIRM` |
+
+#### 请求示例
+
+```http
+POST /v3/admin/order/group-batch/2097250563497385985/confirm HTTP/1.1
+Host: api.test.1814.love:9443
+Authorization: Bearer <admin token>
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": null,
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+本接口无列表出参。确认成功后的逐户补发合同保险是**异步**的：确认接口立即返回 200，补发结果在「合同保险」页签逐户可见；单户出具失败不影响确认结果，也不影响其余户，可在该页签手动开（GB-ADM-031）补出。
+
+```json
+{ "code": 200, "data": null, "success": true }
+```
+
+#### 错误响应
+
+确认门不满足（逐项列出，顺序固定为 房、车、导游领队、摄影、物资）：
+
+```json
+{
+  "code": 589556,
+  "message": "团期尚不满足确认条件：车未配齐、物资未确认",
+  "success": false,
+  "data": null
+}
+```
+
+状态不是「配置」（含已确认后再点一次）：
+
+```json
+{
+  "code": 589501,
+  "message": "团期状态不允许当前操作",
+  "success": false,
+  "data": null
+}
+```
+
+无权限（角色未授 `group-batch:confirm`）：
+
+```json
+{
+  "code": 589507,
+  "message": "无操作权限（当前角色未授予团期权限，或该团期不在您名下）",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- 权限码 `group-batch:confirm`，授给 `GROUP_BATCH_MANAGER` 与 `ADMIN`；其余角色 589507。与 `group-batch:manage` 分开授权。
+- 判定顺序：团期存在（589500）→ 状态为 `RESOURCE_PREPARING`（589501）→ 确认门（589556）→ CAS 推进。任一步拒绝**零写入**。
+- 589556 的未满足项取值只有五种：`房未配齐`、`车未配齐`、`导游领队未配齐`、`摄影未配齐`、`物资未确认`，以「、」连接。
+- 不需要导游 / 摄影的团、整团免车的团，其 ready 位已由成团免闸 / 免车写口置真，确认时不会被这几项挡住。
+- 并发确认只有一个成功，其余 589501；重复确认不会重复推进。
+- 成功后时间线新增一条 `eventType=BATCH_CONFIRM`、`eventTypeName=确认`，带操作人。
+- 补发只处理子订单状态为待出发 / 出行中（已确认行程）的户；尚未确认行程的户跳过，等其确认行程时由既有自动出具链路出；已出具的户逐项跳过；已取消户不出。
+
+---
+
+### 2. 确认团期物资 `POST /v3/admin/order/group-batch/{groupBatchId}/confirm-material`
+
+**VO**: `Result<Void>`（无请求体）
+
+#### 使用场景
+
+「物资」页签的「确认物资」按钮。本次起它是团期确认的前置条件之一，在「配置」节点点。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long | ✅ | 团期主键 | 不存在返 589500 |
+
+无请求体。
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data | Void | 成功返回 null；团期状态**不变**，物资已确认标记置真 |
+
+#### 请求示例
+
+```http
+POST /v3/admin/order/group-batch/2097250563497385985/confirm-material HTTP/1.1
+Host: api.test.1814.love:9443
+Authorization: Bearer <admin token>
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": null,
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+无列表出参。确认前物资可反复增删改、反复确认，每次确认都在时间线记一条「确认物资」流水（内容「确认物资清单」）。
+
+```json
+{ "code": 200, "data": null, "success": true }
+```
+
+#### 错误响应
+
+团期不在 `RESOURCE_PREPARING`（含招募中、已确认及之后）：
+
+```json
+{
+  "code": 589501,
+  "message": "团期状态不允许当前操作",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- 权限码 `group-batch:manage`（不变）。
+- **只在 `RESOURCE_PREPARING` 可调**；改前只在 `MATERIAL_PREPARING` 可调，两者正好相反。
+- **不再推进团期状态**：改前确认物资后会顺带尝试进入待出发；现在进入待出发改由子订单确认、定时扫描与「复判待出发硬门」端点负责，七项硬门本身不变。
+- 取消成团会把物资已确认标记重置（不变）。
+
+---
+
+### 3. 手工复判物料门 `POST /v3/admin/order/group-batch/{groupBatchId}/recheck-material-gate`
+
+**VO**: `GroupBatchMaterialGateRespVO`（已删除）
+
+#### 使用场景
+
+**已下线。** 该端点原用于在「资源准备中 → 物料准备中」自动推进卡住时手工复判。自动推进已删除，这一跳只剩人工确认一条路，复判入口不再有意义。请改用新端点 `POST .../confirm`。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long | ✅ | - | 端点已删除 |
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| advanced | Boolean | 已删除（原：是否推进了团期） |
+| currentStatus / currentStatusName | String | 已删除 |
+| blockedGate / blockedOrderId / blockedReason | String / Long / String | 已删除 |
+
+#### 请求示例
+
+```http
+POST /v3/admin/order/group-batch/2097250563497385985/recheck-material-gate HTTP/1.1
+Host: api.test.1814.love:9443
+Authorization: Bearer <admin token>
+```
+
+#### 响应示例
+
+路由已不存在，经网关调用返回业务信封 `code=404`（TEST 2026-09-24 实测）：
+
+```json
+{ "code": 404, "msg": "接口不存在: POST /v3/admin/order/group-batch/2102932276390383618/recheck-material-gate" }
+```
+
+#### 空数据 / 降级响应
+
+无。端点不存在，不会返回任何业务数据。
+
+#### 错误响应
+
+任何调用都返回 `code=404`「接口不存在」（同上）：
+
+```json
+{ "code": 404, "msg": "接口不存在: POST /v3/admin/order/group-batch/2102932276390383618/recheck-material-gate" }
+```
+
+#### 业务边界
+
+- 原错误码 589561「团期当前状态为「{0}」，不在「资源准备中」，无需复判物料门」不再抛出，仅保留占位防号段复用。
+- 前端所有调用点与按钮需移除；替代动作是「确认」。
+
+---
+
+### 4. 手动开合同 / 保险 `POST /v3/admin/order/group-batch/{groupBatchId}/contracts/issue`
+
+**VO**: `GroupBatchContractIssueReqVO` → `GroupBatchIssueResultVO`
+
+#### 使用场景
+
+「合同保险」页签逐户开合同 / 保险。本次只改前置门与拒绝文案，入参出参结构不变。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long | ✅ | 团期主键 | - |
+| orderIds | Body | List&lt;Long&gt; | 否 | - | 为空 = 本期全部尚未出具的户 |
+| target | Body | String | ✅ | `CONTRACT` / `INSURANCE` / `BOTH` | 出具目标 |
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| totalCount | Integer | 本次处理户数 |
+| successCount | Integer | 成功户数 |
+| failCount | Integer | 失败户数 |
+| skipCount | Integer | 跳过户数（已出具 / 已签等） |
+| results[].orderId | String | 子订单 ID |
+| results[].target | String | `CONTRACT` / `INSURANCE` |
+| results[].outcome | String | `SUCCESS` / `SKIPPED` / `FAILED` |
+| results[].message | String | 失败或跳过原因 |
+
+#### 请求示例
+
+```json
+{ "orderIds": ["770145"], "target": "CONTRACT" }
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "totalCount": 1,
+    "successCount": 1,
+    "failCount": 0,
+    "skipCount": 0,
+    "results": [
+      { "orderId": "770145", "target": "CONTRACT", "outcome": "SUCCESS", "message": null }
+    ]
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+已出具的户逐项 `SKIPPED`，不算失败；单户失败只记在 `results` 里，不影响其余户（不变）。
+
+```json
+{ "code": 200, "data": { "totalCount": 1, "successCount": 0, "failCount": 0, "skipCount": 1, "results": [ { "orderId": "770145", "target": "CONTRACT", "outcome": "SKIPPED", "message": "该户合同已出具，自动跳过" } ] }, "success": true }
+```
+
+#### 错误响应
+
+团期尚未确认（`RECRUITING` / `RESOURCE_PREPARING`，即便四项已配齐）：
+
+```json
+{
+  "code": 589548,
+  "message": "团期确认后才能出具合同与保险",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- 权限码 `group-batch:contract:issue`（不变）。
+- 可出具的团期状态：`MATERIAL_PREPARING` / `PENDING_DEPARTURE` / `TRAVELLING` / `REVIEWING` / `SETTLED`；其余一律 589548，整单拒绝、零写入。
+- 改前 `RESOURCE_PREPARING` 且四项 ready 全真时可出具，本次起不可。
+
+---
+
+### 5. 作废重开合同 / 保险 `POST /v3/admin/order/group-batch/{groupBatchId}/contracts/reissue`
+
+**VO**: `GroupBatchContractIssueReqVO` → `GroupBatchIssueResultVO`
+
+#### 使用场景
+
+「开错」态的补救通路：先作废该户现有单据再重开。前置门与手动开完全一致。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long | ✅ | 团期主键 | - |
+| orderIds | Body | List&lt;Long&gt; | 否 | - | 为空 = 本期全部户 |
+| target | Body | String | ✅ | `CONTRACT` / `INSURANCE` / `BOTH` | 重开目标 |
+| reason | Body | String | 否 | - | 作废原因 |
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| totalCount / successCount / failCount / skipCount | Integer | 同手动开 |
+| results[] | List | 逐户结果，同手动开 |
+
+#### 请求示例
+
+```json
+{ "orderIds": ["770145"], "target": "CONTRACT", "reason": "方案选错" }
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "totalCount": 1,
+    "successCount": 1,
+    "failCount": 0,
+    "skipCount": 0,
+    "results": [
+      { "orderId": "770145", "target": "CONTRACT", "outcome": "SUCCESS", "message": null }
+    ]
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+作废失败的户直接记 `FAILED`，不进重开，不影响其他户（不变）。
+
+```json
+{ "code": 200, "data": { "totalCount": 1, "successCount": 0, "failCount": 1, "skipCount": 0, "results": [ { "orderId": "770145", "target": "CONTRACT", "outcome": "FAILED", "message": "作废失败" } ] }, "success": true }
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 589548,
+  "message": "团期确认后才能出具合同与保险",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- 与手动开共用同一出具门与同一文案。
+- 确认前没有任何已出具的单据可重开，调用即 589548。
+
+---
+
+### 6. 合同保险面板 `GET /v3/admin/order/group-batch/{groupBatchId}/contracts`
+
+**VO**: `GroupBatchContractBoardVO`
+
+#### 使用场景
+
+「合同保险」页签首屏：顶部三格统计 + 逐户卡片；`issuable` 决定出具按钮是否可点。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long | ✅ | 团期主键 | - |
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| issuable | Boolean | **语义改变**：= 团期已人工确认（`MATERIAL_PREPARING` 及之后的可出具状态）；改前 = 四项配齐 |
+| batchStatus | String | 团期状态存储值，`issuable=false` 时可据此提示（不变） |
+| totalCount / contractIssuedCount / contractSignedCount / insuranceIssuedCount | Integer | 不变 |
+| items | List | 逐户明细（不变） |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch/2097250563497385985/contracts HTTP/1.1
+Host: api.test.1814.love:9443
+Authorization: Bearer <admin token>
+```
+
+无请求体。
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "groupBatchId": "2097250563497385985",
+    "issuable": false,
+    "batchStatus": "RESOURCE_PREPARING",
+    "totalCount": 3,
+    "contractIssuedCount": 0,
+    "contractSignedCount": 0,
+    "insuranceIssuedCount": 0,
+    "items": []
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+无活跃子订单时 `totalCount=0`、`items` 为空数组（不变）：
+
+```json
+{ "code": 200, "data": { "issuable": false, "batchStatus": "RESOURCE_PREPARING", "totalCount": 0, "items": [] }, "success": true }
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 589500,
+  "message": "团期不存在",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- `RESOURCE_PREPARING` 且四项已配齐时，改前 `issuable=true`，现在 `false`；提示文案建议为「团期确认后才能出具合同与保险」。
+- 其余字段口径不变。
+
+---
+
+## 四、契约约束与正确调用方式
+
+### ✅ 正确 / ❌ 错误调用顺序
+
+| 场景 | 调用 |
+|------|------|
+| ✅ 配置节点收尾 | 配房 / 车 / 导摄 → `confirm-material` → `confirm` |
+| ❌ 先确认团期再确认物资 | `confirm` → 589556「…物资未确认」；确认后再调 `confirm-material` → 589501 |
+| ❌ 确认前出具合同 | `contracts/issue`（`RESOURCE_PREPARING`）→ 589548 |
+| ❌ 继续调复判物料门 | `recheck-material-gate` → 404 |
+
+### 589556 的处理
+
+message 的冒号之后就是未满足项清单，可直接展示给操作人；不要再去调已下线的复判端点找原因。
+
+---
+
+## 五、数据库行为
+
+| 前端动作 | 外部可观察的写入 |
+|----------|------------------|
+| `confirm` 成功 | 团期状态 `RESOURCE_PREPARING → MATERIAL_PREPARING`（CAS，一次）+ 时间线一条「确认」（含操作人）；提交后异步逐户生成合同 / 保单 |
+| `confirm` 被拒（589501 / 589556 / 589507） | 零写入 |
+| `confirm-material` 成功 | 物资已确认标记置真 + 时间线一条「确认物资」；团期状态不变 |
+| `confirm-material` 被拒 | 零写入 |
+| `contracts/issue` / `reissue` 被 589548 拒 | 零写入 |
+
+---
+
+## 六、边界行为
+
+- 未登录 → 401（网关拦截）。
+- 团期不存在 → 589500。
+- 四项 ready 翻真、成团、整团免车**都不会再推进团期状态**；团期会停在「配置」直到有人点确认。
+- 确认后补发是异步的，确认接口不等补发完成；补发整轮失败（如团期被并发流团）只影响出具，不回滚确认，可在「合同保险」页签手动补出。
+- 进入待出发的七项硬门不变。
+
+---
+
+## 六.5、枚举 / 数据字典
+
+### 589556 未满足项（GroupBatchService.unmetConfirmConditions）
+
+**所属字段**: 错误 `message` 冒号后的清单 | **类型**: `String`（「、」分隔）
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `房未配齐` | 房 | 团期配房完成标志为假 |
+| `车未配齐` | 车 | 团期配车完成标志为假（整团免车时为真） |
+| `导游领队未配齐` | 导游领队 | 不需要导游的团成团时已置真 |
+| `摄影未配齐` | 摄影 | 不需要摄影的团成团时已置真 |
+| `物资未确认` | 物资 | 未调用 `confirm-material` |
+
+### 时间线事件（GroupBatchLogEventType，新增一值）
+
+**所属字段**: 团期状态流水 `eventType` / `eventTypeName` | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `BATCH_CONFIRM` | 确认 | 本次新增；人工确认时写入，`fromStatus=RESOURCE_PREPARING`、`toStatus=MATERIAL_PREPARING` |
+| `BATCH_RESOURCE_READY` | 资源就绪·进物资准备 | 原自动推进事件，本次起不再写入；历史行照常显示 |
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 |
+|------|------|------|
+| 合同保险面板 `issuable` | 四项配齐（或已进物料准备中）即 true | 团期已确认（物料准备中及之后）才 true |
+| 589548 message | 房/车/导/摄四项配齐后才能出具合同与保险 | 团期确认后才能出具合同与保险 |
+| 589556 | 无 | 新增：团期尚不满足确认条件：{0} |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| 资源准备中 → 物料准备中 | 四项 ready + 逐户合同已签、保险已出 → 系统自动推进 | 只能人工 `confirm`，门 = 四项 ready + 物资已确认 |
+| 确认物资可调状态 | `MATERIAL_PREPARING` | `RESOURCE_PREPARING` |
+| 确认物资的副作用 | 顺带尝试进入待出发 | 不改团期状态 |
+| 合同保险出具时机 | 资源准备中四项配齐即可 | 确认后；确认时对已确认行程的户自动补发 |
+| 复判物料门端点 | 可用 | 删除（404） |
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 是。复判端点删除；确认物资的可调状态翻转；确认前不能出合同保险。
+- **前端是否必须同步上线**: 是。缺少「确认」按钮时，新成团的团期会一直停在「配置」节点。
+- **前端 workaround 清理点**: 移除「复判物料门」入口及其结果弹窗；「确认物资」按钮的显示条件由物料准备中改为资源准备中；合同保险页签按 `issuable` 置灰的提示文案改为「团期确认后才能出具合同与保险」。
+
+---
+
+## 七、不影响范围
+
+- **仅影响**: 团期「配置 → 确认」这一跳、确认物资、合同保险出具门。
+- **零影响**:
+  - 成团、取消成团、流团的入参与出参
+  - 进入待出发的七项硬门与「复判待出发硬门」端点
+  - 子订单确认行程后的逐户自动出具链路（团期已确认时照常出）
+  - 小程序端
+- 另：内部定时任务端点 `/v3/internal/jobs/group-batch-material-gate/run` 与其定时任务同批下线，属服务间内部接口，管理后台不调用。
+
+---
+
+## 八、测试环境已验证
+
+部署：hl-user-service + hl-order-service-v3 = dev-v3 @ d9fdd7fe0（2026-09-24 09:18 / 09:20），经网关 `https://api.test.1814.love` 真实鉴权实测（2026-09-24 09:22–09:45）；工单 #8268 已验收关单。
+
+| # | 场景 | 结果 |
+|---|---|---|
+| 1 | 四项 ready + 物资已确认，GROUP_BATCH_MANAGER 调 `POST /confirm` | 200，RESOURCE_PREPARING → MATERIAL_PREPARING，时间线 `BATCH_CONFIRM`（含操作人） |
+| 2 | 门不满足调 confirm | 589556「团期尚不满足确认条件：房未配齐、车未配齐、摄影未配齐、物资未确认」，状态不变 |
+| 3 | 招募中 / 已确认后重复调 confirm | 589501，不推进 |
+| 4 | ROOM_MANAGER / VEHICLE_MANAGER / CUSTOMIZER / FINANCE 调 confirm | 589507；Flyway `20260923.268` 已执行，仅授 ADMIN 与 GROUP_BATCH_MANAGER |
+| 5 | 成团及四项依次翻真 | 不再自动推进，停在 RESOURCE_PREPARING 直到人工确认 |
+| 6 | 确认前户确认行程 / 手动出具 | 不自动出具；`GET /contracts` 的 `issuable=false`；手动出具 589548「团期确认后才能出具合同与保险」 |
+| 7 | 确认后全团补发 | `total=6 success=4 skipped=2 failed=0`：已确认行程两户合同 GENERATED + 保险 INSURED；已取消户、未确认行程户不出；再次出具返回 SKIPPED |
+| 8 | 配置阶段 / 确认后调 `confirm-material` | 200（`material_confirmed=1`）/ 589501 |
+| 9 | 旧 `recheck-material-gate` 与内部 job 端点 | `code=404`「接口不存在」；sys_job 与 QRTZ 均无 1044 |
+| 10 | 合同签齐 + 七门满足后复检 | 进入 PENDING_DEPARTURE（签署以 SQL 模拟） |
+
+---
+
+## 九、相关历史 PR
+
+| PR | Issue | 说明 | 是否仍有效 |
+|----|-------|------|------------|
+| — | #7105 | 合同保险出具门（四项配齐，589548） | ❌ 门条件被本单替换，码值保留 |
+| — | #7526 | 物料门兜底复判（端点 + 定时任务） | ❌ 本单下线 |
+| — | #7528 | 确认物资后顺带准入待出发 | ❌ 本单删除该顺带准入 |
+| **本 PR #8302** | **#8268** | 人工确认 + 确认后出合同保险 | ✅ 最新 |
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#8268](https://git.1814.love/wx/HL/issues/8268)
+- 关联 PR: [wx/HL#8302](https://git.1814.love/wx/HL/pulls/8302)
+- 同批六节点条目：确认后锁定配置（#8269）、六节点展示与看板七桶（#8271）
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8268](https://git.1814.love/wx/HL/issues/8268)
+- **PR**: [#8302](https://git.1814.love/wx/HL/pulls/8302)
+- **Merge commit**: [d9fdd7fe0](https://git.1814.love/wx/HL/commit/d9fdd7fe038952ac3ffdd31913dfcc4a2fc40574)
+
+### 联系人
+
+- **后端负责人**: @jw
@@ -0,0 +1,800 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8271"
+title: "团期看板与详情按六节点展示：分页 / 详情 / 看板行新增 stage 与出行子状态，统计条与 opsStage 改七桶（旧八桶过渡期兼容），核团 / 验团用语统一为核单 / 结算"
+consumer: "admin"
+author: "jw(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "3fa07c47a0c36277508c383979e8542c10149a55"
+target_release: "v2.1"
+verified_at: "2026-09-24"
+status_note: "六节点定案（SRS §0.27.1 / §0.27.4）：持久九态 batchStatus 不动，服务端派生节点 stage（RECRUIT 招募 / CONFIGURE 配置 / CONFIRM 确认 / TRIP 出行 / REVIEW 核单 / SETTLE 结算 / DISBANDED 已流团）与出行子状态 tripSubStatus（待出发 / 出行中 / 已返团），只供展示。团期分页、详情、看板行新增 stage / stageName / tripSubStatus / tripSubStatusName 四字段；既有字段 opsStage 的取值由八桶改为七桶（与 stage 逐字同值）；统计条 buckets 固定 13 键 = 七桶 + 6 个旧八桶别名键（别名键不计入 total）；opsStage 筛选接受七桶，旧八桶 code 过渡期按原口径兼容；导出 CSV「状态」列改为节点名。PR #8303 补充：面向用户的核团 / 验团用语统一为核单 / 结算（6 个错误码文案、时间线事件中文标签、核单状态 CHECKED 中文名），码值与存储值不变。前端需把看板页签与统计条切到七桶、详情页按 stage / tripSubStatus 展示节点；旧八桶别名在前端切换完成前保留。 前端已交付（3fa07c47）：看板页签与统计条切七桶、stageMetaOf 折叠出行复合桶并拼 tripSubStatusName、详情 6 段步骤条、核团/验团用语统一核单/结算；batch 域 403 例全绿。"
+updated_at: "2026-09-24"
+base: "dev-v3"
+---
+
+# 团期看板: 按六节点展示，统计条与筛选改七桶（管理后台）
+
+> **服务**: hl-order-service-v3（端口 8086/8186）
+> **PR**: #8276（代码）、#8279（文档）、#8303（核单 / 结算用语）
+> **Issue**: #8271
+> **日期**: 2026-09-24
+> **影响范围**: 管理后台团期看板（页签、统计条、列表行、导出）、团期详情头部节点展示、团期时间线与核单 / 结算相关报错文案
+
+---
+
+## ⚠️ 关键变化
+
+1. **`opsStage` 响应取值变了**：以前是八桶（`FORMED` / `PENDING_TRIP` / `TRAVELLING` / `TRIP_FINISHED` / `AUDITING` / `CHECKED` …），现在只输出七桶（`CONFIGURE` / `CONFIRM` / `TRIP` / `REVIEW` / `SETTLE` …），且与新字段 `stage` 逐字同值。按旧值做过 `switch` 的前端代码会落到默认分支。
+2. **原「已成团」一桶拆成两桶**：`RESOURCE_PREPARING` → 配置（`CONFIGURE`），`MATERIAL_PREPARING` → 确认（`CONFIRM`）；原「待出行 / 出行中 / 出行完毕」三桶合成一个「出行」（`TRIP`），细分看 `tripSubStatus`。
+3. **统计条 `buckets` 从 8 键变 13 键**：七桶在前、6 个旧别名键在后。`total` 只等于七桶之和，**不要再对 `buckets` 整体求和**（会重复计数）。
+4. **旧入参仍然能用**：页签继续传旧八桶 code 给 `opsStage` 筛选，结果与改前逐条一致（按原口径展开）；统计条的旧键名计数也照旧给。
+5. **用语**：「核团中 / 已验团」改为「核单 / 结算」，涉及 6 个错误码文案、时间线事件中文名、核单状态 `CHECKED` 的中文名；码值与存储值一律不变。
+
+---
+
+## 一、背景
+
+团期六节点定案：看板与详情按「招募 → 配置 → 确认 → 出行 → 核单 → 结算」展示，另有分叉终态「已流团」。持久九态 `batchStatus` 不动、不新增持久列，节点与出行子状态由服务端唯一派生，**只供展示，不承担业务判断**——按钮可用性、权限仍以 `batchStatus` 与各就绪位为准。
+
+| 节点 `stage` | `stageName` | 覆盖的 `batchStatus` | 说明 |
+|---|---|---|---|
+| `RECRUIT` | 招募 | `RECRUITING` | 未建团行（产品侧有班期、订单侧尚无团期）也恒为 `RECRUIT` |
+| `CONFIGURE` | 配置 | `RESOURCE_PREPARING` | 配房 / 车 / 导游领队 / 摄影与物资，确认前可改 |
+| `CONFIRM` | 确认 | `MATERIAL_PREPARING` | 人工确认后配置锁定，逐户出合同与保险 |
+| `TRIP` | 出行 | `PENDING_DEPARTURE`、`TRAVELLING`、`TRIP_FINISHED` | 复合节点，细分见 `tripSubStatus` |
+| `REVIEW` | 核单 | `REVIEWING` | 原「核团中」 |
+| `SETTLE` | 结算 | `SETTLED` | 原「已验团」 |
+| `DISBANDED` | 已流团 | `CANCELLED` | 分叉终态 |
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 团期分页列表（GB-ADM-001） | GET | `/v3/admin/order/group-batch` | 出参新增字段 + 出参取值变化 + 入参取值扩展 | 新增四字段；`opsStage` 出参改七桶；`opsStage` 筛选接受七桶并兼容旧八桶 |
+| 2 | 团期详情（GB-ADM-002） | GET | `/v3/admin/order/group-batch/{groupBatchId}` | 出参新增字段 + 出参取值变化 | 新增四字段；`opsStage` 改七桶 |
+| 3 | 团期看板列表 | GET | `/v3/admin/order/group-batch/board` | 出参新增字段 + 出参取值变化 | 命中 / 未命中 / 孤儿三类行均带四字段；`opsStage` 改七桶 |
+| 4 | 团期看板统计条（GB-ADM-009） | GET | `/v3/admin/order/group-batch/summary` | 出参取值变化 | `buckets` 13 键；`total` = 七桶之和 |
+| 5 | 导出团期列表 CSV（GB-ADM-008） | GET | `/v3/admin/order/group-batch/export` | 入参取值扩展 + 导出内容变化 | `opsStage` 同分页口径；「状态」列改为节点名 |
+| 6 | 团期状态流水（GB-ADM-096） | GET | `/v3/admin/order/group-batch/{groupBatchId}/status-logs` | 出参取值变化（文案） | 5 个核团 / 验团事件的 `eventTypeName` 改为核单 / 结算用语 |
+
+路径、HTTP 方法、权限码、信封结构均不变；网关无改动。
+
+---
+
+## 三、接口详情
+
+### 1. 团期分页列表 `GET /v3/admin/order/group-batch`
+
+**VO**: `GroupBatchListReqVO` → `PageResult<GroupBatchPageItemRespVO>`
+
+#### 使用场景
+
+团期看板主列表（按页签筛选）。页签既可以传七桶 code，也可以继续传旧八桶 code。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| opsStage | Query | String | 否 | 七桶或旧八桶 code；空白 / 非法值忽略 | **本次改取值**：七桶 `RECRUIT` / `CONFIGURE` / `CONFIRM` / `TRIP` / `REVIEW` / `SETTLE` / `DISBANDED`；旧八桶 `FORMED` / `PENDING_TRIP` / `TRAVELLING` / `TRIP_FINISHED` / `AUDITING` / `CHECKED` 过渡期仍按原口径展开 |
+| scope | Query | String | 否 | `ONGOING` / `FINISHED` / `ALL` | 班期范围；与 `opsStage` 取交集（不变） |
+| productId | Query | Long | 否 | - | 按产品筛选（不变） |
+| batchStatus | Query | String | 否 | 九态 code | 精确九态筛选（不变） |
+| month | Query | String | 否 | `yyyy-MM` | 出发月份（不变） |
+| keyword | Query | String | 否 | - | 班期编号 / 名称模糊（不变） |
+| pageNo | Query | Integer | 否 | 默认 1 | 页码（不变） |
+| pageSize | Query | Integer | 否 | 默认 20，最大 100 | 每页条数（不变） |
+
+其余既有筛选参数（`deadlineFrom` / `deadlineTo` / `departFrom` / `departTo` / `sortBy` / `sortOrder`）不变。
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| records[].batchStatus | String | 持久九态，**业务判断用这个**（不变） |
+| records[].batchStatusName | String | 九态中文名（不变，如「资源准备中」「出行完毕」） |
+| records[].stage | String | **新增**。节点 code，取值见「一、背景」七个 |
+| records[].stageName | String | **新增**。节点中文名，与 `stage` 同生同灭 |
+| records[].tripSubStatus | String | **新增**。出行子状态 `PENDING_DEPARTURE` / `TRAVELLING` / `TRIP_FINISHED`；仅 `stage = TRIP` 时有值，其余为 null |
+| records[].tripSubStatusName | String | **新增**。待出发 / 出行中 / 已返团；与 `tripSubStatus` 同生同灭 |
+| records[].opsStage | String | **取值改变**：与 `stage` 逐字同值（七桶），旧八桶值不再输出 |
+| records[].opsStageName | String | **取值改变**：与 `stageName` 同值 |
+| total | Long | 命中总数（不变） |
+
+其余分页项字段不变。
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch?opsStage=TRIP&scope=ALL&pageNo=1&pageSize=20 HTTP/1.1
+Host: api.test.1814.love:9443
+Authorization: Bearer <admin token>
+```
+
+无请求体。
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "total": 1,
+    "records": [
+      {
+        "groupBatchId": "2099750660965584898",
+        "batchNo": "GB26100101",
+        "batchStatus": "PENDING_DEPARTURE",
+        "batchStatusName": "待出发",
+        "stage": "TRIP",
+        "stageName": "出行",
+        "tripSubStatus": "PENDING_DEPARTURE",
+        "tripSubStatusName": "待出发",
+        "opsStage": "TRIP",
+        "opsStageName": "出行"
+      }
+    ]
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+无命中返回空页；`batchStatus` 为 null 或不在九态内的历史脏数据行，四个新字段与 `opsStage` / `opsStageName` 同为 null，不抛错：
+
+```json
+{ "code": 200, "data": { "total": 0, "records": [] }, "success": true }
+```
+
+#### 错误响应
+
+`opsStage` 传非法值不报错（忽略该筛选并记 warn）；本接口错误形态沿用既有，如无列表权限：
+
+```json
+{
+  "code": 589507,
+  "message": "无操作权限（当前角色未授予团期权限，或该团期不在您名下）",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- 七桶与旧别名 code 不相交，先按七桶解析、未命中再按别名解析。
+- 旧别名按**原口径**展开，不放大为新节点：`PENDING_TRIP` 仍只筛待出发，`FORMED` = 配置 + 确认。
+- 服务端严格取 `scope ∩ opsStage`：`REVIEW` / `SETTLE` 及 `TRIP` 里已返团的那部分返团日必然已过，默认 `ONGOING` 会过滤掉，点这些页签需把 `scope` 切到 `ALL`。
+- 四个新字段是纯内存映射，整页无额外查询。
+
+---
+
+### 2. 团期详情 `GET /v3/admin/order/group-batch/{groupBatchId}`
+
+**VO**: `GroupBatchDetailRespVO`
+
+#### 使用场景
+
+团期详情页头部展示当前节点（如「出行 · 待出发」）。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long | ✅ | 团期主键 | 不变 |
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| batchStatus | String | 持久九态（不变） |
+| batchStatusName | String | 九态中文名（不变） |
+| stage | String | **新增**。节点 code |
+| stageName | String | **新增**。节点中文名 |
+| tripSubStatus | String | **新增**。仅 `stage = TRIP` 时有值 |
+| tripSubStatusName | String | **新增**。与 `tripSubStatus` 同生同灭 |
+| opsStage | String | **取值改变**：七桶，与 `stage` 同值 |
+| opsStageName | String | **取值改变**：与 `stageName` 同值 |
+
+其余详情字段不变。
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch/2097250563497385985 HTTP/1.1
+Host: api.test.1814.love:9443
+Authorization: Bearer <admin token>
+```
+
+无请求体。
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "groupBatchId": "2097250563497385985",
+    "batchStatus": "MATERIAL_PREPARING",
+    "batchStatusName": "物料准备中",
+    "stage": "CONFIRM",
+    "stageName": "确认",
+    "tripSubStatus": null,
+    "tripSubStatusName": null,
+    "opsStage": "CONFIRM",
+    "opsStageName": "确认"
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+非出行节点 `tripSubStatus` / `tripSubStatusName` 为 null；脏数据行四字段同为 null：
+
+```json
+{ "code": 200, "data": { "batchStatus": null, "stage": null, "stageName": null, "tripSubStatus": null, "tripSubStatusName": null, "opsStage": null, "opsStageName": null }, "success": true }
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 589500,
+  "message": "团期不存在",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- 子状态中文名「已返团」与九态 `batchStatusName`「出行完毕」不同名，两套文案各自展示，不要互相替换。
+- 前端不得用 `stage` / `tripSubStatus` 判断按钮可用性或权限。
+
+---
+
+### 3. 团期看板列表 `GET /v3/admin/order/group-batch/board`
+
+**VO**: `List<GroupBatchBoardItemRespVO>`
+
+#### 使用场景
+
+按产品展示全部班期（含未建团行与孤儿行）的看板卡片列表。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| productId | Query | Long | ✅ | - | 产品 ID（不变） |
+| scope | Query | String | 否 | `ONGOING` / `FINISHED` / `ALL`，缺省 `ALL` | 班期范围（不变） |
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| [].batchStatus | String | 持久九态（不变）；未建团行按 `RECRUITING` |
+| [].stage | String | **新增**。节点 code；未建团行恒 `RECRUIT` |
+| [].stageName | String | **新增**。节点中文名 |
+| [].tripSubStatus | String | **新增**。仅 `stage = TRIP` 时有值 |
+| [].tripSubStatusName | String | **新增** |
+| [].opsStage | String | **取值改变**：七桶，与 `stage` 同值 |
+| [].opsStageName | String | **取值改变**：与 `stageName` 同值 |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch/board?productId=100001&scope=ALL HTTP/1.1
+Host: api.test.1814.love:9443
+Authorization: Bearer <admin token>
+```
+
+无请求体。
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": [
+    {
+      "groupBatchId": "2097250563497385985",
+      "batchStatus": "TRAVELLING",
+      "stage": "TRIP",
+      "stageName": "出行",
+      "tripSubStatus": "TRAVELLING",
+      "tripSubStatusName": "出行中",
+      "opsStage": "TRIP",
+      "opsStageName": "出行"
+    },
+    {
+      "productBatchId": "2097250420299530242",
+      "batchStatus": "RECRUITING",
+      "stage": "RECRUIT",
+      "stageName": "招募",
+      "tripSubStatus": null,
+      "tripSubStatusName": null,
+      "opsStage": "RECRUIT",
+      "opsStageName": "招募"
+    }
+  ],
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+产品无班期时返回空数组：
+
+```json
+{ "code": 200, "data": [], "success": true }
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 589507,
+  "message": "无操作权限（当前角色未授予团期权限，或该团期不在您名下）",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- 命中 / 未命中 / 孤儿三类行统一带四个新字段。
+- 行集合、排序、其余字段均不变。
+
+---
+
+### 4. 团期看板统计条 `GET /v3/admin/order/group-batch/summary`
+
+**VO**: `GroupBatchSummaryVO`
+
+#### 使用场景
+
+看板顶部各页签的计数。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| productId | Query | Long | 否 | - | 不变 |
+| month | Query | String | 否 | `yyyy-MM` | 不变 |
+| keyword | Query | String | 否 | - | 不变 |
+| scope | Query | String | 否 | `ONGOING` / `FINISHED` / `ALL` | 不变 |
+
+本接口不接受 `opsStage`（它的作用正是给出各桶数量）。
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| total | Integer | **口径改变**：= 七桶之和（旧别名键不计入） |
+| buckets | Map&lt;String, Integer&gt; | **键集合改变**：固定 13 键，无命中为 0；前 7 键为七桶，后 6 键为旧八桶别名 |
+| subOrderCount | Integer | 命中团期的活跃子订单合计（不变） |
+| effectiveScope | String | 实际生效的班期范围（不变） |
+| filteredOutCount | Integer | 被范围过滤掉的团期数（不变） |
+
+`buckets` 13 键口径：
+
+| 键 | 计数口径 | 计入 `total` |
+|---|---|---|
+| `RECRUIT` / `CONFIGURE` / `CONFIRM` / `TRIP` / `REVIEW` / `SETTLE` / `DISBANDED` | 七桶；`TRIP` = 待出发 + 出行中 + 已返团 | ✅ |
+| `FORMED` | 旧别名 = `RESOURCE_PREPARING` + `MATERIAL_PREPARING` | ❌ |
+| `PENDING_TRIP` | 旧别名 = `PENDING_DEPARTURE` | ❌ |
+| `TRAVELLING` | 旧别名 = `TRAVELLING` | ❌ |
+| `TRIP_FINISHED` | 旧别名 = `TRIP_FINISHED` | ❌ |
+| `AUDITING` | 旧别名 = `REVIEWING` | ❌ |
+| `CHECKED` | 旧别名 = `SETTLED` | ❌ |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch/summary?scope=ALL HTTP/1.1
+Host: api.test.1814.love:9443
+Authorization: Bearer <admin token>
+```
+
+无请求体。
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "total": 12,
+    "buckets": {
+      "RECRUIT": 3,
+      "CONFIGURE": 2,
+      "CONFIRM": 1,
+      "TRIP": 4,
+      "REVIEW": 1,
+      "SETTLE": 0,
+      "DISBANDED": 1,
+      "FORMED": 3,
+      "PENDING_TRIP": 2,
+      "TRAVELLING": 1,
+      "TRIP_FINISHED": 1,
+      "AUDITING": 1,
+      "CHECKED": 0
+    },
+    "subOrderCount": 57,
+    "effectiveScope": "ALL",
+    "filteredOutCount": 0
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+无命中时 13 键全部为 0：
+
+```json
+{ "code": 200, "data": { "total": 0, "buckets": { "RECRUIT": 0, "CONFIGURE": 0, "CONFIRM": 0, "TRIP": 0, "REVIEW": 0, "SETTLE": 0, "DISBANDED": 0, "FORMED": 0, "PENDING_TRIP": 0, "TRAVELLING": 0, "TRIP_FINISHED": 0, "AUDITING": 0, "CHECKED": 0 }, "subOrderCount": 0 }, "success": true }
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 589507,
+  "message": "无操作权限（当前角色未授予团期权限，或该团期不在您名下）",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- 按键名读取，不要依赖 Map 下标；也不要对 `buckets` 整体求和。
+- `RECRUIT` / `DISBANDED` 新旧同名同义，不重复出现。
+- 状态不在九态内的行被排除，不计入任何桶。
+
+---
+
+### 5. 导出团期列表 CSV `GET /v3/admin/order/group-batch/export`
+
+**VO**: `text/csv` 附件（非 `Result` 信封）
+
+#### 使用场景
+
+看板「导出」按钮，按当前筛选导出 CSV。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| opsStage | Query | String | 否 | 同分页口径 | **本次改取值**：七桶或旧八桶 code |
+| productId | Query | Long | 否 | - | 不变 |
+| month | Query | String | 否 | `yyyy-MM` | 不变 |
+| keyword | Query | String | 否 | - | 不变 |
+| scope | Query | String | 否 | `ONGOING` / `FINISHED` / `ALL` | 不变 |
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| 状态（CSV 第 8 列） | String | **内容改变**：由旧八桶中文名改为节点名；出行节点拼子状态，如「出行·待出发」「出行·出行中」「出行·已返团」 |
+
+列名、列序（固定 10 列）与单次 2000 行上限不变。
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch/export?opsStage=CONFIGURE&scope=ALL HTTP/1.1
+Host: api.test.1814.love:9443
+Authorization: Bearer <admin token>
+```
+
+无请求体。
+
+#### 响应示例
+
+响应为 CSV 附件；「状态」列示例：
+
+```json
+{
+  "Content-Type": "text/csv; charset=utf-8",
+  "header": "团期号,期号,日期,出团日,满团名额,已售,剩余,状态,子订单数,整团应收",
+  "状态列取值示例": ["招募", "配置", "确认", "出行·待出发", "出行·出行中", "出行·已返团", "核单", "结算", "已流团"]
+}
+```
+
+#### 空数据 / 降级响应
+
+无命中时只输出表头一行（不变）：
+
+```json
+{ "header": "团期号,期号,日期,出团日,满团名额,已售,剩余,状态,子订单数,整团应收", "rows": 0 }
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 589507,
+  "message": "无操作权限（当前角色未授予团期权限，或该团期不在您名下）",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- 按「状态」列中文做过解析的下游需同步：旧值「已成团 / 待出行 / 核团中 / 已验团」不再出现。
+- 筛选口径与分页接口共用同一展开逻辑。
+
+---
+
+### 6. 团期状态流水 `GET /v3/admin/order/group-batch/{groupBatchId}/status-logs`
+
+**VO**: `List<GroupBatchStatusLogItemVO>`
+
+#### 使用场景
+
+团期详情「操作记录 / 时间线」。本次只改 5 个事件的中文标签（PR #8303）。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long | ✅ | 团期主键 | 不变 |
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| [].eventType | String | 事件类型值（**不变**） |
+| [].eventTypeName | String | **取值改变**：见下表；标签在读取时渲染，存量行一并显示新标签 |
+| [].content | String | 展示文本；本次之后新写入的核单 / 结算相关流水改用新用语，存量行原样 |
+
+| eventType | 改前 eventTypeName | 改后 eventTypeName |
+|---|---|---|
+| `BATCH_TRIP_END` | 返团核团 | 发起核单 |
+| `BATCH_SETTLE` | 验团结算 | 结算 |
+| `BATCH_AUDIT_ALLOCATE` | 核团提交核算 | 核单提交核算 |
+| `BATCH_AUDIT_REALLOCATE` | 核团重新核算 | 核单重新核算 |
+| `BATCH_AUDIT_PRICE_OVERRIDE` | 核团改价 | 核单改价 |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch/2097250563497385985/status-logs HTTP/1.1
+Host: api.test.1814.love:9443
+Authorization: Bearer <admin token>
+```
+
+无请求体。
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": [
+    {
+      "eventType": "BATCH_SETTLE",
+      "eventTypeName": "结算",
+      "fromStatus": "REVIEWING",
+      "fromStatusName": "核单中",
+      "toStatus": "SETTLED",
+      "toStatusName": "已结算",
+      "content": "结算归档，团期结束",
+      "operatorType": "ADMIN"
+    }
+  ],
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+无流水返回空数组；库里是枚举外历史值时 `eventTypeName` 为 null（不变）：
+
+```json
+{ "code": 200, "data": [], "success": true }
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 589500,
+  "message": "团期不存在",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- 按 `eventType` 做分支的前端不受影响；按中文标签匹配的需改。
+- `fromStatusName` / `toStatusName`（九态中文名「核单中」「已结算」）不变。
+
+---
+
+## 四、契约约束与正确调用方式
+
+### ✅ 正确 / ❌ 错误用法对照
+
+| 场景 | 用法 |
+|------|------|
+| ✅ 看板页签筛选（新） | `opsStage=CONFIGURE` / `opsStage=TRIP` |
+| ✅ 看板页签筛选（过渡期旧值） | `opsStage=FORMED`，结果 = 配置 + 确认，与改前一致 |
+| ✅ 页签计数 | 读 `buckets.CONFIGURE`、`buckets.TRIP` 等七桶键；总数读 `total` |
+| ❌ 总数自己求和 | `Object.values(buckets).reduce(...)` → 七桶与别名重复，结果偏大 |
+| ❌ 用节点判按钮 | `if (stage === 'CONFIGURE') showConfirmButton()` → 应读 `batchStatus` 与就绪位 |
+| ❌ 按旧 `opsStage` 值分支 | `case 'FORMED':` → 响应已不再输出旧值 |
+
+### 核单 / 结算用语：错误码文案变化（PR #8303，码值不变）
+
+| code | 改前 message | 改后 message |
+|---|---|---|
+| 589555 | 该团期已验团归档，不可重复验团 | 该团期已结算归档，不可重复结算 |
+| 589565 | 团期已验团归档，如需重新核单请先做验团反确认 | 团期已结算归档，如需重新核单请先做结算反确认 |
+| 589567 | 该团期尚未进入核团：{0} | 该团期尚未进入整团核单：{0} |
+| 589568 | 核团当前状态不允许该操作：{0} | 整团核单当前状态不允许该操作：{0} |
+| 589572 | 所选订单不属于本团期的核团范围 | 所选订单不属于本团期的整团核单范围 |
+| 589573 | 核团数据已被他人修改（当前版本 {0}，提交版本 {1}），请刷新后重试 | 整团核单数据已被他人修改（当前版本 {0}，提交版本 {1}），请刷新后重试 |
+
+核单状态枚举 `CHECKED` 的中文名由「已验团」改为「已结算」（存储值不变）；前端按 code 判断即可，按中文匹配的需改。
+
+---
+
+## 六、边界行为
+
+- 未登录 → 401（网关拦截）。
+- `batchStatus` 为 null 或不在九态内的脏数据行：四个新字段与 `opsStage` / `opsStageName` 同为 null，不抛错。
+- `opsStage` 空白或非法值：忽略该筛选并记 warn，不报错。
+- 未建团行恒为 `RECRUIT` / 招募。
+- 旧八桶别名（筛选入参 + 统计条 6 键）在前端切到七桶之前保留，删除时另发契约变更。
+
+---
+
+## 六.5、枚举 / 数据字典
+
+### stage / opsStage（GroupBatchStageBuckets.Bucket）
+
+**所属字段**: `stage`、`opsStage`（响应）、`opsStage`（筛选入参）、`buckets` 前 7 键 | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `RECRUIT` | 招募 | ← `RECRUITING` |
+| `CONFIGURE` | 配置 | ← `RESOURCE_PREPARING` |
+| `CONFIRM` | 确认 | ← `MATERIAL_PREPARING` |
+| `TRIP` | 出行 | ← `PENDING_DEPARTURE` / `TRAVELLING` / `TRIP_FINISHED` |
+| `REVIEW` | 核单 | ← `REVIEWING` |
+| `SETTLE` | 结算 | ← `SETTLED` |
+| `DISBANDED` | 已流团 | ← `CANCELLED` |
+
+### tripSubStatus（GroupBatchStageBuckets.TripSubStatus）
+
+**所属字段**: `tripSubStatus` | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `PENDING_DEPARTURE` | 待出发 | 仍可发起流团 |
+| `TRAVELLING` | 出行中 | 出发日起 |
+| `TRIP_FINISHED` | 已返团 | 返团日次日起；首次录共享成本即进入核单 |
+
+### 旧八桶别名（GroupBatchStageBuckets.LegacyBucket，过渡期）
+
+**所属字段**: `opsStage`（筛选入参）、`buckets` 后 6 键 | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `FORMED` | 已成团 | = `RESOURCE_PREPARING` + `MATERIAL_PREPARING` |
+| `PENDING_TRIP` | 待出行 | = `PENDING_DEPARTURE` |
+| `TRAVELLING` | 出行中 | = `TRAVELLING` |
+| `TRIP_FINISHED` | 出行完毕 | = `TRIP_FINISHED` |
+| `AUDITING` | 核团中 | = `REVIEWING` |
+| `CHECKED` | 已验团 | = `SETTLED` |
+
+---
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 |
+|------|------|------|
+| `stage` / `stageName` | 无 | 新增，七个节点 |
+| `tripSubStatus` / `tripSubStatusName` | 无 | 新增，仅出行节点有值 |
+| `opsStage`（响应） | 八桶：`RECRUIT` / `FORMED` / `PENDING_TRIP` / `TRAVELLING` / `TRIP_FINISHED` / `AUDITING` / `CHECKED` / `DISBANDED` | 七桶，与 `stage` 同值 |
+| `opsStageName`（响应） | 招募中 / 已成团 / 待出行 / 出行中 / 出行完毕 / 核团中 / 已验团 / 已流团 | 招募 / 配置 / 确认 / 出行 / 核单 / 结算 / 已流团 |
+| `buckets`（统计条） | 8 键，`total` = 8 桶之和 | 13 键（七桶 + 6 别名），`total` = 七桶之和 |
+| 导出「状态」列 | 旧八桶中文名 | 节点名，出行节点拼子状态 |
+| `eventTypeName`（5 个核单 / 结算事件） | 核团 / 验团用语 | 核单 / 结算用语 |
+| 6 个错误码 message | 核团 / 验团用语 | 核单 / 结算用语（见「四」） |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| `opsStage=FORMED` 筛选 | 配置 + 确认 | 不变（别名按原口径） |
+| `opsStage=TRIP` 筛选 | 非旧八桶 code，按非法值忽略（不筛） | 筛待出发 + 出行中 + 已返团 |
+| `opsStage=CONFIGURE` / `CONFIRM` / `REVIEW` / `SETTLE` | 非法值被忽略 | 按新节点筛选 |
+
+⚠️ 注意 `TRIP` 与旧 `TRIP_FINISHED` 的区别：旧八桶里「出行完毕」的 code 是 `TRIP_FINISHED`，不是 `TRIP`；页签若传的是 `TRIP_FINISHED`，行为不变。
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 部分。筛选入参与统计条旧键完全兼容；响应字段 `opsStage` / `opsStageName` 的取值改变，读这两个字段做分支或展示的代码会受影响。
+- **前端是否必须同步上线**: 否。旧页签传旧 code、读旧键仍然工作；要展示六节点需改读 `stage` / `tripSubStatus` 与七桶键。
+- **前端 workaround 清理点**: 若前端曾自己把九态折叠成阶段，可改为直接读 `stage`；切到七桶后告知后端删除旧八桶别名。
+
+---
+
+## 七、不影响范围
+
+- **仅影响**: 上述 6 个查询 / 导出接口的节点相关字段与文案，及 6 个核单 / 结算错误码的 message。
+- **零影响**:
+  - 持久九态 `batchStatus` 及其中文名 `batchStatusName`（「核单中」「已结算」原本就是这两个字）
+  - 所有写接口的状态流转与业务闸（节点只供展示）
+  - 错误码 code 值、枚举存储值、时间线 `eventType` 值
+  - 权限码、路径、信封结构、网关配置
+  - 小程序端
+
+---
+
+## 八、测试环境已验证
+
+部署 `dev-v3` @ `b212cb708`，2026-09-23 17:44–17:48，`api.test.1814.love:9443`。
+
+| 验证项 | 结果 |
+|---|---|
+| 分页（`pageSize=100`）与看板行（187 行）字段 | 均带 `stage` / `stageName` / `tripSubStatus` / `tripSubStatusName` 四个新字段，且 `opsStage == stage` ✓ |
+| 九态 → 节点映射 | 全映射实测 ✓ |
+| 统计条 `summary`（`scope=ALL`） | 13 键逐键与 DB 一致；`total = 267` = 七桶之和（13 键合计 492） ✓ |
+| `opsStage` 筛选 15 个取值 | `total` 全部等于 DB 计数；`PENDING_TRIP` 只筛待出发 3 条，`FORMED = 215`，未知值忽略 ✓ |
+| 低权限角色 | `ROOM_MANAGER` / `VEHICLE_MANAGER` → 589507 ✓ |
+
+核单 / 结算用语（PR #8303：6 个错误码文案、时间线标签）：
+
+补充（PR #8303，dev-v3 @ ade8ac292，2026-09-24 09:52–09:58）：api-docs 中「已验团 / 团期核团 / 验团归档 / 验团反确认 / 核团面板」旧文案 0 次；589555「该团期已结算归档，不可重复结算」、589565「团期已结算归档，如需重新核单请先做结算反确认」实测触发；`status-logs` 对 09-18 旧记录返回新标签「发起核单 / 核单改价 / 核单提交核算 / 核单重新核算 / 结算」（`content` 为写入时原文，不随之变化）。工单 #8271 已验收关单。
+
+---
+
+## 九、相关历史 PR
+
+| PR | Issue | 说明 | 是否仍有效 |
+|----|-------|------|------------|
+| #6917 / #6926 | #6904 | 统计条与导出、`opsStage` 筛选首版 | ⚠️ 桶取值被本次替换，旧 code 以别名保留 |
+| — | #7190 | 加「出行完毕」`TRIP_FINISHED` 成八桶 | ⚠️ 同上 |
+| — | #7535 | 详情 / 分页透出 `opsStage` | ⚠️ 字段保留，取值改七桶 |
+| **本 PR #8276 / #8279 / #8303** | **#8271** | 六节点派生 + 七桶 + 核单 / 结算用语 | ✅ 最新 |
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#8271](https://git.1814.love/wx/HL/issues/8271)
+- 关联 PR: [wx/HL#8276](https://git.1814.love/wx/HL/pulls/8276)、[wx/HL#8279](https://git.1814.love/wx/HL/pulls/8279)、[wx/HL#8303](https://git.1814.love/wx/HL/pulls/8303)
+- 同批六节点条目：团期人工确认（#8268）、确认后锁定配置（#8269）
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8271](https://git.1814.love/wx/HL/issues/8271)
+- **PR**: [#8276](https://git.1814.love/wx/HL/pulls/8276)、[#8279](https://git.1814.love/wx/HL/pulls/8279)、[#8303](https://git.1814.love/wx/HL/pulls/8303)
+- **Merge commit**: [678d47b58](https://git.1814.love/wx/HL/commit/678d47b584ac0237784c0bf728e86dfe6cbacb1d)、[bfbc0d337](https://git.1814.love/wx/HL/commit/bfbc0d337a92f3e2dec8b84aa54cbf1042f08698)、[ade8ac292](https://git.1814.love/wx/HL/commit/ade8ac292388354649c3e367e1171e6e55836280)
+
+### 联系人
+
+- **后端负责人**: @jw
@@ -0,0 +1,438 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8292"
+title: "订单标签四个写端点补订单归属守卫，与读面口径对齐"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "not_required"
+frontend_status: "not_required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "接口路径、请求体、成功响应结构全未变，变的是失败分支：新增 581064 无权修改该订单。无新增路由，故 gateway_status=not_required。测试服实测（网关 https://api.test.1814.love，部署 ab630a3f8）：test_admin(CUSTOMIZER，非归属) POST 他人订单标签 → 581064 且复查无残留；test_admin 对自己订单读/原样全量回写 → 200；wx(SUPER_ADMIN) 对他人订单读/原样回写 → 200；admin（当前角色 GROUP_BATCH_MANAGER）写他人订单 → 581008（#8154 的 Controller 角色守卫先拒）。边缘变化：deleteTag/patchTag 传不存在的 orderId 时错误码由 581410/581411 变为 581401。frontend_status=pending：hl-ui 现按 err.message 透传，581064 走通用 toast 即可，无需改码。 前端 2026-09-24 核验 not_required:四写端点前端只消费 PUT /tags(replaceOrderTags 全量替换,POST/DELETE/PATCH 增删改无封装调用),TagPickerModal catch 纯透 err.message 无按码分支;581064/581410/581411/581401/581433 前端零引用,新增 581064 走通用 toast 透后端原文即达标;581008/581045 是 orderAccess 路由隔离角色守卫与标签业务无关;581410/581411 变形只影响前端无调用的 DELETE/PATCH。零改动。"
+updated_at: "2026-09-24"
+base: "dev-v3"
+---
+
+# 订单标签: 四个写端点补订单归属守卫，与读面口径对齐
+
+> **存放目录**: 二期（order-v3）→ `changelogs-v2/2026-09/`
+>
+> **服务**: hl-order-service-v3（端口 8086）
+> **PR**: [#8307](https://git.1814.love:8443/wx/HL/pulls/8307)
+> **Issue**: [#8292](https://git.1814.love:8443/wx/HL/issues/8292)
+> **日期**: 2026-09-24
+> **影响范围**: 订单详情页「标签」区四个写操作的**权限口径**；接口路径、请求体、成功响应结构均未变
+
+---
+
+## ⚠️ 关键变化（本版与上版行为不同，必读）
+
+**这四个写接口现在会拒绝「非本单归属人」的调用，失败时返回新错误码 `581064`（无权修改该订单）。**
+
+- 本次变了什么：四个写端点补上了**订单归属**校验。
+- 前端以前以为的：除团期管理员外谁都能写（确实是 #8290 之前的行为）。
+- 实际现在是什么：与**读面**（#8290 已收紧的 `GET .../tags`、`GET .../tag-picker`）**同一套放行集合**——读得到的单才写得动。
+
+前端以前只会从这四个接口收到 `581008`（团期管理员）与 `581045`（房务），**现在会新增收到 581064**。
+
+---
+
+## 一、背景
+
+#8170 AC-18（PR #8290）给 `GET /v3/admin/order/{orderId}/tags`、`GET .../tag-picker` 与 `GET .../itinerary-document` 补上了 `OrderViewGuard.assertOrderReadable`，读面收紧后同一批数据上的四个**写**端点仍零归属校验，形成「**不能看，但能改**」——任意后台角色拿到 `orderId` 就能增、能改、能删他人订单的标签，其中 `PUT .../tags` 是全量替换，会清掉不在入参里的标签。
+
+口径由 wx 于 2026-09-24 定案：**写面与读面读写对称**。本单是 #8170 挂账的「存量治理」单。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 增订单标签 | POST | `/v3/admin/order/{orderId}/tag` | 失败分支新增 | 非归属人 → 581064 |
+| 2 | 删订单标签 | DELETE | `/v3/admin/order/{orderId}/tag/{tagId}` | 失败分支新增 | 非归属人 → 581064；orderId 不存在时由 581410/581411 改为 581401 |
+| 3 | 改订单标签 | PATCH | `/v3/admin/order/{orderId}/tag/{tagId}` | 失败分支新增 | 非归属人 → 581064；533 原有「非标签创建人 → 581433」不变 |
+| 4 | 全量替换订单标签 | PUT | `/v3/admin/order/{orderId}/tags` | 失败分支新增 | 非归属人 → 581064 |
+
+**四个接口的请求体、成功响应体、路径参数全部未变。**
+
+---
+
+## 三、接口详情
+
+### 1. 增订单标签 `POST /v3/admin/order/{orderId}/tag`
+
+**VO**: `TagAddReqVO → Result<OrderTagVO>`
+
+#### 使用场景
+
+订单详情页标签区点击「打标签」后提交。creator / createdAt 由后端从 JWT 派生，前端不传。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| `orderId` | Path | String | ✅ | - | 订单 ID |
+| `tagName` | Body | String | ✅ | trim 后非空，同订单内不重名 | 标签名 |
+| `tagColor` | Body | String | ❌ | `#` + 6 位十六进制 | 不传默认 `#5B8FF9` |
+
+#### 出参 `Result<OrderTagVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `tagId` | String | 雪花 ID，字符串返回防精度丢失 |
+| `orderId` | String | 订单 ID |
+| `tagName` | String | 标签名 |
+| `tagColor` | String | 色值 |
+
+#### 请求示例
+
+```json
+{ "tagName": "重点客户", "tagColor": "#FF6B6B" }
+```
+
+#### 响应示例
+
+```json
+{ "code": 200, "message": "成功", "data": { "tagId": "2100...", "orderId": "9199...", "tagName": "重点客户", "tagColor": "#FF6B6B" }, "success": true }
+```
+
+#### 空数据 / 降级响应
+
+```json
+{ "code": 200, "message": "成功", "data": null, "success": true }
+```
+
+写接口无列表与降级语义：成功恒返 200 + 业务结果，失败恒返业务码，不存在「空集合」形态；
+无下游 Feign/消息依赖，故也没有降级分支。前端按 `code == 200` 判成功、否则 toast `message` 即可。
+
+#### 错误响应
+
+```json
+{ "code": 581064, "message": "无权修改该订单", "success": false, "data": null }
+```
+
+#### 业务边界
+
+- **鉴权**：必须是本单定制师，或 ADMIN / SUPER_ADMIN / 车务管理员；团期管理员被 581008 拒（只读承诺 #8154）；房务管理员与房务组长 581045。
+- **空值**：`tagName` trim 后为空 → 581402；颜色格式非法 → 581404。
+- **幂等/并发**：同订单同名标签 → 581403（不做幂等 upsert）。
+- **失败零写入**：归属守卫排在插入之前，被拒时一行都不会写。
+
+### 2. 删订单标签 `DELETE /v3/admin/order/{orderId}/tag/{tagId}`
+
+**VO**: `无请求体 → Result<Boolean>`
+
+#### 使用场景
+
+订单详情页标签区删除某个已挂标签（软删）。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| `orderId` | Path | String | ✅ | - | 订单 ID |
+| `tagId` | Path | String | ✅ | - | `order_tag.tag_id` |
+
+#### 出参 `Result<Boolean>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `data` | Boolean | true = 删除成功 |
+
+#### 请求示例
+
+```http
+DELETE /v3/admin/order/9199000000000000002/tag/2100123456789012345
+Authorization: Bearer <admin-token>
+```
+
+#### 响应示例
+
+```json
+{ "code": 200, "message": "成功", "data": true, "success": true }
+```
+
+#### 空数据 / 降级响应
+
+```json
+{ "code": 200, "message": "成功", "data": null, "success": true }
+```
+
+写接口无列表与降级语义：成功恒返 200 + 业务结果，失败恒返业务码，不存在「空集合」形态；
+无下游 Feign/消息依赖，故也没有降级分支。前端按 `code == 200` 判成功、否则 toast `message` 即可。
+
+#### 错误响应
+
+```json
+{ "code": 581401, "message": "订单不存在", "success": false, "data": null }
+```
+
+#### 业务边界
+
+- **鉴权**：同接口 1。**标签级没有创建人限制**（任何有权者都可删该单的标签），权限完全由订单归属决定。
+- **顺序**：先取订单 → 判空（581401）→ 归属守卫 → 才按 `tagId` 取标签。越权请求不再能从「标签不存在 581410」与「标签不属于该订单 581411」的差别推断某个 `tagId` 是否存在。
+- **失败零写入**：守卫在任何标签表访问之前。
+
+### 3. 改订单标签 `PATCH /v3/admin/order/{orderId}/tag/{tagId}`
+
+**VO**: `TagPatchReqVO → Result<Boolean>`
+
+#### 使用场景
+
+订单详情页标签区编辑某个已挂标签的名称或颜色（PATCH 语义，只改传入字段）。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| `orderId` | Path | String | ✅ | - | 订单 ID |
+| `tagId` | Path | String | ✅ | - | `order_tag.tag_id` |
+| `tagName` | Body | String | ❌ | trim 后非空 | 不传则不改 |
+| `tagColor` | Body | String | ❌ | `#` + 6 位十六进制 | 不传则不改 |
+
+#### 出参 `Result<Boolean>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `data` | Boolean | true = 修改成功 |
+
+#### 请求示例
+
+```json
+{ "tagName": "高净值", "tagColor": "#FF6B6B" }
+```
+
+#### 响应示例
+
+```json
+{ "code": 200, "message": "成功", "data": true, "success": true }
+```
+
+#### 空数据 / 降级响应
+
+```json
+{ "code": 200, "message": "成功", "data": null, "success": true }
+```
+
+写接口无列表与降级语义：成功恒返 200 + 业务结果，失败恒返业务码，不存在「空集合」形态；
+无下游 Feign/消息依赖，故也没有降级分支。前端按 `code == 200` 判成功、否则 toast `message` 即可。
+
+#### 错误响应
+
+```json
+{ "code": 581433, "message": "无权修改该标签（非创建人）", "success": false, "data": null }
+```
+
+#### 业务边界
+
+- **两道互不替代的校验**：① 订单归属（581064，本单新增）；② **标签级创建人**（操作人 ≠ `order_tag.created_by` → 581433，既有行为未变）。
+- `581433` 的文案本单由「非创建人**且非主管**」订正为「非创建人」：实现里**从来没有**「主管」判定分支，原文案是空承诺。
+- **顺序**：先取订单 → 判空（581401）→ 归属守卫 → 才按 `tagId` 取标签。
+- 操作人上下文缺失时第二道校验整体放行（既有 fail-open），故它**不是**归属防线；归属防线是第一道。
+
+### 4. 全量替换订单标签 `PUT /v3/admin/order/{orderId}/tags`
+
+**VO**: `ReplaceOrderTagsReqVO → Result<OrderTagListRespVO>`
+
+#### 使用场景
+
+打标签弹窗点「确定」后整批提交（前端先 `GET .../tag-picker` 再提交全量列表）。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| `orderId` | Path | String | ✅ | - | 订单 ID |
+| `tags[].tagName` | Body | String | ✅ | trim 后非空 | 标签名（按名去重，保留首个） |
+| `tags[].tagColor` | Body | String | ❌ | `#` + 6 位十六进制 | 不传默认 `#5B8FF9` |
+
+#### 出参 `Result<OrderTagListRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `attached` | Array | 替换后的全量标签快照（元素同 `OrderTagVO`） |
+
+#### 请求示例
+
+```json
+{ "tags": [ { "tagName": "重点客户", "tagColor": "#FF6B6B" } ] }
+```
+
+#### 响应示例
+
+```json
+{ "code": 200, "message": "成功", "data": { "attached": [ { "tagId": "2100...", "orderId": "9199...", "tagName": "重点客户", "tagColor": "#FF6B6B" } ] }, "success": true }
+```
+
+#### 空数据 / 降级响应
+
+```json
+{ "code": 200, "message": "成功", "data": null, "success": true }
+```
+
+写接口无列表与降级语义：成功恒返 200 + 业务结果，失败恒返业务码，不存在「空集合」形态；
+无下游 Feign/消息依赖，故也没有降级分支。前端按 `code == 200` 判成功、否则 toast `message` 即可。
+
+#### 错误响应
+
+```json
+{ "code": 581064, "message": "无权修改该订单", "success": false, "data": null }
+```
+
+#### 业务边界
+
+- **这是四个写端点里后果最重的一个**：全量替换按 diff 清掉不在入参里的标签。传空 `tags` 数组 = 一次性清空该单全部标签。
+- **鉴权**：同接口 1；归属守卫排在 diff 之前（防御性，不做无谓写、不依赖事务回滚兜底）。
+- **事务**：`@Transactional(rollbackFor = Exception.class)`，diff 失败整笔回滚。
+- **失败零写入**：被拒时 diff 一步都不执行。
+
+---
+
+## 四、契约约束与正确调用方式（接口类必写）
+
+> 本节只写**后端接受/拒绝 payload 的规则**，不写 UI 渲染建议。
+
+### ✅ 正确 / ❌ 错误 payload 对照
+
+| 场景 | payload |
+|------|---------|
+| ✅ 只改名不改色 | `{ "tagName": "高净值" }` |
+| ✅ 只改色不改名 | `{ "tagColor": "#FF6B6B" }` |
+| ✅ 全量替换为空标签 | `{ "tags": [] }`（有权者：清空该单标签） |
+| ❌ 全量替换传 null | `{ "tags": null }` → 参数校验失败 |
+| ❌ 颜色少 # 或非 6 位 | `{ "tagColor": "FF6B6B" }` → 581404 |
+| ❌ 非归属人写他人订单 | 任意上述 payload → **581064** |
+
+### 切换状态时的必要动作
+
+无字段互斥关系；PATCH 是「只改传入字段」语义，不需要先读回再整对象提交。若要整批调整，用 `PUT .../tags` 传全量列表（空数组即清空）。
+
+---
+
+## 五、数据库行为（涉及写操作时必写）
+
+表 `order_tag`（继承 `BaseDO`，含 `deleted_at` 逻辑删除列）。
+
+| 操作 | SQL 效果 |
+|------|----------|
+| POST 增标签 | `INSERT INTO order_tag (tag_id, order_id, tag_name, tag_color, creator, created_by, ...)` |
+| DELETE 删标签 | **软删** `UPDATE order_tag SET deleted_at = NOW() WHERE tag_id = ?`（`BaseDO.deletedAt` 带 `@TableLogic(value = "NULL", delval = "NOW()")`） |
+| PATCH 改标签 | `UPDATE order_tag SET tag_name = ?, tag_color = ? ...`（仅传入字段） |
+| PUT 全量替换 | 差集软删 + 新增 INSERT + 颜色变更 UPDATE；命中 `user_tag_library` 的标签会 `touchUsage` 累加 `used_count` 并刷新 `last_used_at` |
+
+**读面一致性**：所有 `selectByOrderId` 查询被 `@TableLogic` 自动附加 `deleted_at IS NULL`，被软删的标签即刻从接口结果消失，但行仍留在库里（无业务恢复入口）。
+
+---
+
+## 六、边界行为
+
+- 未登录 → 401（网关拦截）
+- `orderId` 不存在 → `POST` / `PUT` 返 581401；`DELETE` / `PATCH` **本单起也返 581401**（此前会走到 581410/581411）
+- `tagId` 不存在 → 581410；`tagId` 不属于该 `orderId` → 581411（DELETE）/ 581434（PATCH）
+- 同订单同名标签 → 581403（新增时）
+- 团期管理员 → 581008（#8154 的角色级只读，Controller 层先拒，与 `groupBatchId` 无关）
+- 房务管理员 / 房务组长 → 581045
+- 老数据兼容：存量标签的 `created_by` 若为空，PATCH 的第二道校验仍按操作人比对（既有行为，本单未改）
+
+---
+
+## 六.5、枚举 / 数据字典
+
+本节不适用：四个接口无枚举入参或返回值（标签类型字段已由 #3941 移除）。
+
+---
+
+## 六.6、修改前后对比（修改/删除类接口必写）
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 |
+|------|------|------|
+| 请求体字段 | — | **无变化** |
+| 响应体字段 | — | **无变化** |
+| 失败错误码 | 581008（团期管理员）/ 581045（房务） | 新增 **581064**（非归属人）；581008 / 581045 保持 |
+| DELETE/PATCH 的 `orderId` 不存在 | 581410 / 581411（先查标签） | **581401 订单不存在**（先查订单） |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| 非归属角色写他人订单标签（POST / DELETE / PATCH / PUT） | **放行** | **581064** |
+| 非归属角色全量替换他人订单标签（PUT 空数组） | 放行，会清空他人标签 | 581064，零写入 |
+| 本单定制师写自己订单标签 | 放行 | 放行（不变） |
+| ADMIN / SUPER_ADMIN / 车务管理员 | 放行 | 放行（不变） |
+| 团期管理员 | 581008 | 581008（不变） |
+| 房务管理员 / 房务组长 | 放行 | 581045 |
+
+---
+
+## 六.7、影响评估（修改/删除类必写）
+
+- **是否破坏向后兼容**：**对合法调用方否**（有权角色行为零变化）；对**越权调用**是有意的行为收紧。
+- **前端是否必须同步上线**：**否**。接口路径与结构未变，581064 走通用 `err.message` toast 即可；但要**知悉**该码的语义（是写权限，不是登录态问题）。
+- **前端 workaround 清理点**：无。hl-ui 现按 `err.message` 透传，无按码分支可清理。
+
+---
+
+## 七、不影响范围（显式声明，帮前端/QA 缩小排查面）
+
+- **仅影响**：订单详情页「标签」区的四个写操作（增 / 删 / 改 / 全量替换）。
+- **零影响**：
+  - 标签的**三个读接口**（`GET .../tags`、`GET .../tag-picker`、`GET .../itinerary-document`）——本单未改
+  - 创单链路写入标签（`OrderCreateTransactionExecutor` 同事务内 batchCreate，无「他人订单」概念）
+  - 订单详情 / 行程 / 财务等其它读写面
+  - `user_tag_library` 私人标签库的全部接口
+  - 存量数据（不迁移；软删语义未变）
+  - 其它服务（本改动不跨服务，无 Feign/事件/MQ 契约变化）
+
+---
+
+## 八、测试环境已验证
+
+真实网关调用（`https://api.test.1814.love`，测试服部署 `★ab630a3f8`）：
+
+```
+GET  /v3/admin/order/9199000000000000002/tags   as CUSTOMIZER(非归属) → 581008 无权查看此订单 ✓
+POST /v3/admin/order/9199000000000000002/tag    as CUSTOMIZER(非归属) → 581064 无权修改该订单 ✓
+GET  /v3/admin/order/9199000000000000002/tags   as SUPER_ADMIN        → 200 复查确认无残留标签 ✓
+PUT  /v3/admin/order/9199000000000000002/tags   as SUPER_ADMIN(原样回写)→ 200 ✓
+GET  /v3/admin/order/2096701868536188930/tags   as CUSTOMIZER(本单定制师)→ 200 ✓
+PUT  /v3/admin/order/2096701868536188930/tags   as CUSTOMIZER(本单定制师)→ 200 ✓
+POST /v3/admin/order/9199000000000000002/tag    as GROUP_BATCH_MANAGER → 581008(#8154 角色守卫先拒) ✓
+```
+
+单元与门禁：定向 `Tests run 129 / Failures 0 / Errors 0`；ArchTest `Tests run 26 / Failures 0 / Errors 0`。
+
+---
+
+## 九、相关历史 PR（纠错 / 功能演进时必写）
+
+| PR | Issue | 说明 | 是否仍有效 |
+|----|-------|------|------------|
+| #8290 | #8170 | 标签**读**面补 `assertOrderReadable`，本单就是它显影出的写面缺口 | ✅ 有效 |
+| **本 PR #8307** | **#8292** | 标签**写**面补归属守卫 + 新写面码 581064 + 581433 文案订正 | ✅ 最新 |
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#8292](https://git.1814.love:8443/wx/HL/issues/8292)
+- 关联 PR: [wx/HL#8307](https://git.1814.love:8443/wx/HL/pulls/8307)
+- 后续计划: 无
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8292](https://git.1814.love:8443/wx/HL/issues/8292)
+- **PR**: [#8307](https://git.1814.love:8443/wx/HL/pulls/8307)
+- **Merge commit**: [ab630a3f8](https://git.1814.love:8443/wx/HL/commit/ab630a3f8)
+
+### 联系人
+
+- **后端负责人**: @wx
@@ -0,0 +1,306 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8294"
+title: "团期配车就绪检查「座位不足」黄牌改为扣司机座，新增 passengerSeatTotal"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "e5a34cd13e641ac10394a9a245f0548461894a02"
+target_release: "v2.1"
+verified_at: "2026-09-24"
+status_note: "PR #8305 已合并 dev-v3（2a3b9df59）。部署：hl-fleet-service dev-v3 @ 2a3b9df59，2026-09-24 09:48:52 起滚，09:50:13 完成，8087/8187 两实例均 UP；实测 09:52 晚于部署完成时刻。测试服网关真实 GET /admin/fleet/group-dispatch/batches/{groupBatchId}/readiness：团期 2101514348969226242 返回 WARN_SEAT_SHORTAGE，seatTotal=7、passengerSeatTotal=6、headcount=40、gap=34（7-1=6 证明扣座、40-6=34 证明 gap 按新口径）；团期 2102066067272826881 座位合计 0 时 passengerSeatTotal=0 不为负；团期 2101997326354862082（座位合计 5/可载客 4/人数 4）与 2101690789438570497（7/6/6）warned=false，证明取等号时不误报。fleet 定向单测 778/0/0（含 GroupDispatchReadinessServiceTest 26、VehicleSeatCapacityTest 4、FleetRedLineArchTest 18）+ spotless:check 绿；回退判据后 3 个用例转红（含「20 座车 20 人应报缺 1 座」），恢复后转绿。gateway_status: verified —— 路径本就在既有 admin-fleet-service 路由 Path=/admin/fleet/** 下，本次零路由改动，并已通过真实网关实测。frontend_status: pending —— 前端需读新字段 passengerSeatTotal，且 gap 的语义已变（改为 用车人数 − 已扣司机座的可载客数），若仍按「用车人数 − seatTotal」渲染会差 1×车数。 前端已交付并验证：实证黄牌 b.message 直显、seatTotal/gap/headcount 零数值消费，新文案自动生效；group-dispatch.js JSDoc 订正新口径（透 message 禁文本匹配/自算 gap，seatTotal+gap≠headcount 正常须 passengerSeatTotal+gap 闭合），drawer spec fixture/断言改新文案回归锁 7 例全绿。hl-admin@e5a34cd1。"
+updated_at: "2026-09-24"
+base: "dev-v3"
+---
+
+# fleet 团期配车就绪检查: 座位不足黄牌改为扣司机座
+
+> **存放目录**: 二期(v3) → `changelogs-v2/2026-09/`
+>
+> **服务**: hl-fleet-service（团期配车读口）
+> **PR**: #8305
+> **Issue**: #8294
+> **日期**: 2026-09-24
+> **影响范围**: 管理后台「团期详情 → 配车」页的就绪检查提示（黄牌文案与字段）
+
+---
+
+## ⚠️ 关键变化（非必须,本版与上版行为不同 / 纠错 / 撤销时必写）
+
+- 本次变化：`GET /admin/fleet/group-dispatch/batches/{groupBatchId}/readiness` 响应里 `warnings[]` 中 `code=WARN_SEAT_SHORTAGE` 的条目，**判据由「座位合计（含司机座）< 该日用车人数」改为「可载客数合计 < 该日用车人数」**。每车可载乘客数 = 座位数 − 1（扣 1 个司机座）。口径与团级用车需求 809116（#8278，PR #8296）、fleet 单车派车完全一致。
+- 前端以前以为的：`seatTotal` 就是「能坐多少人」，`gap = headcount − seatTotal`。**现在 `gap` 不再按 `seatTotal` 算**——同一响应里 `seatTotal + gap ≠ headcount` 是正常的，必须叠加新字段 `passengerSeatTotal` 才闭合（`passengerSeatTotal + gap = headcount`）。
+- 实际现在的行为：判据字段是 **`passengerSeatTotal`**；`seatTotal` **原义与数值都未变**（仍是含司机座的座位合计，可以直接继续展示「N 座车」）。
+- **会新增黄牌**：`座位合计 ≥ 用车人数 > 可载客数合计` 这个区间以前不报、现在报。最小例子：1 辆 20 座车、该日 20 人——改前不报，改后报「缺 1 座」（司机没座）。存量数据不重算，下一次读取即按新口径。
+- `message` 文案改写（**前端如果做文本匹配会失效**）：旧「`2027-06-10 分组 MAIN 座位合计 7，该日用车人数 40，缺 33 座`」→ 新「`2027-06-10 分组 MAIN 座位合计 7 座（含司机座），已扣司机座后可载客 6 人，该日用车人数 40，缺 34 座`」。
+- **黄牌语义不变**：仍然只提醒、不阻断，`ready` 与 `warned` 仍互相独立，`ready=true && warned=true` 依然合法。
+
+---
+
+## 一、背景（选填）
+
+#8278 已定案：团级用车需求的容量一律按「每车扣 1 个司机座」算（`VehicleSeatCalculator`），订单子级与 fleet 单车派车（预检告警、候选容量）本来就是这个口径。唯一没对齐的是 fleet 的**团级**就绪检查——它直接累加 `vehicle.getSeats()`，把「20 座车塞 20 人」判成够。同一份排法在团级需求侧已被 809116 拦下，在配车就绪页却显示「够」，运营无法判断该信哪一个。本单让第三处（也是最后一处）向已有口径看齐，而不是放松另外两处。
+
+最强反例（评审已确认，留档）：「刚好坐满、司机另开一辆车」这类排法在新口径下会多出一条黄牌。它只是提醒不是硬拦，且这类配置在业务上本就不成立（司机座不能卖给乘客）；被提醒是纠正而不是误伤。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 团期配车就绪检查 | GET | `/admin/fleet/group-dispatch/batches/{groupBatchId}/readiness` | 响应新增字段 + 字段语义变更 + 文案变更 | `warnings[]` 中 `WARN_SEAT_SHORTAGE` 条目新增 `passengerSeatTotal`，`gap` 改按它计算，`message` 改写 |
+
+**本次只动这一个端点**（同一控制器的其余端点未改）。
+
+---
+
+## 三、接口详情
+
+### 1. 团期配车就绪检查 `GET /admin/fleet/group-dispatch/batches/{groupBatchId}/readiness`
+
+**VO**: `GroupDispatchReadinessRespVO → GroupDispatchReadinessItemVO[]`
+
+#### 使用场景
+
+团期详情「配车」页进入时拉取，用于展示硬拦（不能置 vehicle_ready）与黄牌（能发车但有缺口）。请求参数与响应整体结构均不变，本条只改「只提醒」数组里座位不足那一档的字段与文案。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| `groupBatchId` | Path | Long | 是 | 团期主订单 ID | 路径参数 |
+
+#### 出参 `Result<GroupDispatchReadinessRespVO>`
+
+**顶层字段**（本次未变）：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `groupBatchId` | String(Long) | 团期主订单 ID |
+| `requirementId` | String(Long) | 判定所依据的正式需求 ID |
+| `requirementVersion` | Integer | 判定所依据的需求版本 |
+| `planVersion` | Long | fleet 侧当前计划版本（该团尚无任何计划行时为 null） |
+| `ready` | Boolean | 硬拦三项是否全过（`= blockers.isEmpty()`） |
+| `warned` | Boolean | 是否有只提醒项（`= !warnings.isEmpty()`） |
+| `blockers` | Array | 硬拦未过项 |
+| `warnings` | Array | 只提醒项 |
+| `groups` | Array | 逐组覆盖明细（与配车写口 `coverage` 同源，逐字段可比对） |
+| `shareGroupCount` | Integer | 本团 active 同团车辆共用关系数（只供展示，不参与判定） |
+
+**`warnings[]` 元素（`GroupDispatchReadinessItemVO`）**：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `code` | String | 判定项代码：`WARN_SEAT_SHORTAGE` / `WARN_DRIVER_MISSING` |
+| `message` | String | 中文描述（本次改写，见下表） |
+| `tripDate` | LocalDate | 相关行程日 |
+| `groupCode` | String | 相关乘车分组码 |
+| `seatTotal` | Integer | 该日该组的座位合计（含司机座）；仅座位不足档有值 |
+| `passengerSeatTotal` | Integer | **新增**：该日该组的可载客数合计（Σ max(0, seats − 1)）；仅座位不足档有值 |
+| `headcount` | Integer | 该日该组的用车人数；仅座位不足档有值 |
+| `gap` | Integer | 座位缺口（本次改按 `passengerSeatTotal` 计算）；仅座位不足档有值 |
+| `dispatchId` | String(Long) | 相关配车行 ID；仅司机缺失档有值 |
+
+**本次逐字段变化（仅 `WARN_SEAT_SHORTAGE` 档）**：
+
+| 字段 | 类型 | 本次变化 | 说明 |
+|---|---|---|---|
+| `code` | String | 不变 | `WARN_SEAT_SHORTAGE` / `WARN_DRIVER_MISSING` |
+| `message` | String | **改写** | 座位不足档现在写明「含司机座」与「已扣司机座后可载客 N 人」 |
+| `tripDate` | LocalDate | 不变 | 相关行程日 |
+| `groupCode` | String | 不变 | 相关乘车分组码 |
+| `seatTotal` | Integer | **语义不变** | 该日该组活跃配车行的**座位合计（含司机座）**，数值与改前逐字相同 |
+| `passengerSeatTotal` | Integer | **新增** | 该日该组的**可载客数合计** = Σ `max(0, seats − 1)`，座位数取不到的车按 0 计，恒 ≥ 0 |
+| `headcount` | Integer | 不变 | 该日该组用车人数 |
+| `gap` | Integer | **语义变更** | 由 `headcount − seatTotal` 改为 `headcount − passengerSeatTotal`（恒 ≥ 1） |
+| `dispatchId` | String(Long) | 不变 | 仅 `WARN_DRIVER_MISSING` 有值 |
+
+以上与座位相关的五项**仅 `WARN_SEAT_SHORTAGE` 档有值**；`WARN_DRIVER_MISSING` 档这五项均为 `null`（含新增的 `passengerSeatTotal`）。
+
+#### 请求示例
+
+```http
+GET /admin/fleet/group-dispatch/batches/2101514348969226242/readiness
+Authorization: Bearer <admin token>
+```
+
+#### 响应示例
+
+测试服真实响应（2026-09-24 09:52，`hl-fleet-service` dev-v3 @ `2a3b9df59`，节选该接口 `warnings` 内容）：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "success": true,
+  "data": {
+    "groupBatchId": "2101514348969226242",
+    "ready": true,
+    "warned": true,
+    "planVersion": 4,
+    "warnings": [
+      {
+        "code": "WARN_SEAT_SHORTAGE",
+        "message": "2027-06-10 分组 MAIN 座位合计 7 座（含司机座），已扣司机座后可载客 6 人，该日用车人数 40，缺 34 座",
+        "tripDate": "2027-06-10",
+        "groupCode": "MAIN",
+        "seatTotal": 7,
+        "passengerSeatTotal": 6,
+        "headcount": 40,
+        "gap": 34,
+        "dispatchId": null
+      }
+    ]
+  }
+}
+```
+
+对照：`seatTotal(7) + gap(34) = 41 ≠ headcount(40)`；`passengerSeatTotal(6) + gap(34) = 40 = headcount` —— **前端做守恒校验请用后者**。
+
+#### 空数据 / 降级响应
+
+- 无缺口时 `warnings: []`、`warned: false`，其余字段照常返回。
+- 该团未声明任何乘车分组或基线不可用：`code=602113`，**失败关闭**，绝不返回 `ready=true`。
+- 入参非法：`code=602114`。
+
+#### 错误响应
+
+```json
+{ "code": 602113, "message": "...", "success": false, "data": null }
+```
+
+#### 业务边界
+
+- 座位不足**只提醒**：`ready` 只看 `blockers`，不受本档影响；两条写路径（配车方向判定、就绪意图发射）只调 `hardGatesPass`，该入口完全不看座位。
+- 扣座是**逐车**的：N 辆车扣 N 个司机座（两辆 20 座车 / 39 人 ⇒ 可载客 38、缺 1 座），不是全团只扣 1 个。
+- 座位数取不到（车已软删 / 车型未录座位数）的车按 0 计，可载客数**不出现负数**。
+- 按「组 + 行程日」逐格比：同一组不同日期分别判定，不同组分别判定。
+
+---
+
+## 四、契约约束与正确调用方式（接口类必写）
+
+### ✅ 正确 / ❌ 错误用法对照
+
+| 场景 | ✅ 正确 | ❌ 错误 |
+|---|---|---|
+| 判断「够不够」 | 后端已给结论：`warned` / `warnings` 是否为空 | 前端自己用 `seatTotal >= headcount` 重算 |
+| 展示缺口 | 直接展示 `gap`，或展示 `headcount − passengerSeatTotal` | 用 `headcount − seatTotal` 现算（会少 1×车数） |
+| 展示运力 | `passengerSeatTotal`（可载客）与 `seatTotal`（车辆座位规格）分开显示 | 把 `seatTotal` 当成可载客数展示 |
+| 文案 | 直接展示后端 `message` | 按旧文案做字符串匹配/替换 |
+
+### 切换状态时的必要动作
+
+无。本接口是只读 GET，不改变任何状态，也不触发重算。
+
+---
+
+## 五、数据库行为（涉及写操作时必写）
+
+无写入。判据全部基于既有列在读取时现算（活跃配车行 × 车辆座位数 × 需求逐日人数），**不落库、不新增列、无迁移**。
+
+---
+
+## 六、边界行为
+
+| 边界 | 行为 |
+|---|---|
+| `headcount = 0` | 不报（`0 >= 0`） |
+| 座位数取不到（车软删 / 未录） | 该车按 0 计，缺口如实报出 |
+| 座位数为 0 或 1 | 可载客数 0，不出现负数 |
+| 恰好坐满（可载客数 == 人数） | 不报（取等号判「够」） |
+| 该日没有排车 | 该日可载客数 0；整组没排车由硬拦 `BLOCK_GROUP_MISSING` 承接 |
+| 需求已 DONE | 仍返回 `ready=true`（DONE 比 CONFIRMED/DISPATCHED 更靠后） |
+
+---
+
+## 六.5、枚举 / 数据字典（接口出现枚举时必写）
+
+`warnings[].code` 取值不变，仍为两档：
+
+| 取值 | 含义 | 相关字段 |
+|---|---|---|
+| `WARN_SEAT_SHORTAGE` | 该日该组可载客数不足 | `tripDate` / `groupCode` / `seatTotal` / `passengerSeatTotal` / `headcount` / `gap` |
+| `WARN_DRIVER_MISSING` | 配车行未排司机（消息带车牌） | `tripDate` / `groupCode` / `dispatchId`，其余为 `null` |
+
+**无新增错误码。**
+
+---
+
+## 六.6、修改前后对比（修改/删除类接口必写，新增跳过）
+
+### 字段级对比（`warnings[]` 中 `WARN_SEAT_SHORTAGE` 条目）
+
+| 字段 | 修改前 | 修改后 |
+|---|---|---|
+| `seatTotal` | 座位合计（含司机座） | **不变**（同值同义） |
+| `passengerSeatTotal` | 不存在 | **新增**，`Σ max(0, seats − 1)` |
+| `gap` | `headcount − seatTotal` | `headcount − passengerSeatTotal` |
+| `message` | `{日期} 分组 {组} 座位合计 {N}，该日用车人数 {M}，缺 {K} 座` | `{日期} 分组 {组} 座位合计 {N} 座（含司机座），已扣司机座后可载客 {P} 人，该日用车人数 {M}，缺 {G} 座` |
+
+### 行为级对比
+
+| 行为 | 修改前 | 修改后 |
+|---|---|---|
+| 1 辆 20 座车 / 该日 20 人 | 不报（20 ≥ 20） | **报，缺 1 座** |
+| 1 辆 20 座车 / 该日 19 人 | 不报 | 不报（可载客 19 ≥ 19） |
+| 2 辆 20 座车 / 该日 39 人 | 不报（40 ≥ 39） | **报，缺 1 座**（可载客 38） |
+| 1 辆 7 座车 / 该日 40 人 | 报，`seatTotal=7`、`gap=33` | 报，`seatTotal=7`、`passengerSeatTotal=6`、`gap=34` |
+| 座位数为 0 / 取不到 | 报，`seatTotal=0`、`gap=人数` | 报，`passengerSeatTotal=0`、`gap=人数`（不为负） |
+| `ready` | 不受本档影响 | **不变**（仍只提醒） |
+
+---
+
+## 六.7、影响评估（修改/删除类必写）
+
+- **变宽**：`座位合计 ≥ 用车人数 > 可载客数合计` 这个区间由「不报」变「报」。区间宽度恰是「该日排的车数」（每车多算 1 个司机座），所以车越多、越容易落进来。
+- **不变**：`gap` 的**值**在「座位取不到」和「原本就严重不足」的场景里可能不变；但在「刚好卡边界」的场景会 +1×车数。任何拿 `gap` 做阈值判断的前端逻辑都要复核。
+- **后端消费方**：`getSeatTotal()` / `getGap()` 在 HL 全仓（Java）生产代码中消费方为 **0**（只有测试引用），本接口的消费方是管理后台前端。
+- **存量数据不重算**：不落库，下一次读取即按新口径；测试服现有 116 条活跃配车行、34 个团期中，**没有**落在新增黄牌区间（`用车人数 == 座位合计`）的活跃分组，本次口径变更对既有数据的可见影响为 0。
+- 前置依赖：本单与 #8278 是同一口径的第三处收口，**不改变** 809116、子订单级校验、候选容量的任何行为。
+
+---
+
+## 七、不影响范围（显式声明, 帮前端/QA 缩小排查面）
+
+- `blockers[]` 三档与 `ready` 的判定逻辑：**零改动**。
+- `groups[]`、`shareGroupCount`、`planVersion`、`requirementVersion` 等字段：**零改动**。
+- 同一控制器的其余端点（`/pending-batches`、`/batches/{id}/overview`、`/resource-schedule`）：**零改动**。
+- 配车写口（提交 / 确认 / 改派 / 删除）与 `coverage`：**零改动**。
+- 单车派车的预检告警、候选容量、候选页 `passengerCapacity` 字段：**行为零改动**（只把内部重复实现收口到一份工具方法）。
+- 团级用车需求 809116（#8278 已交付）与 order-v3：**行为零改动**（仅同步了两处已失效的注释）。
+- 数据库：无迁移、无新列。
+
+---
+
+## 八、测试环境已验证
+
+- **定向测试**：`mvn -o -pl hl-fleet-service -am test -Dtest='GroupDispatchReadinessServiceTest*,VehicleSeatCapacityTest*,AssignmentCandidateServiceTest*,AssignmentServiceTest*,AssignmentServiceNoVehicleDeclarationTest*,AssignmentServicePickupDropoffTest*,AssignmentServiceClearCancelledOccupancyTest*,AssignmentServiceResolveExceptionTest*,FleetRedLineArchTest' -DfailIfNoTests=false -Dhl.surefire.failIfNoTests=false` → **778 / 0 / 0，BUILD SUCCESS**（逐类核对 `Tests run`，报告文件时间均晚于本轮起跑）。
+- **分辨力**：把判据临时还原为旧口径后 3 个用例转红（含「20 座车 20 人应报缺 1 座」），恢复后 30/0/0 转绿。
+- **网关验证**：`GET https://api.test.1814.love/admin/fleet/group-dispatch/batches/{groupBatchId}/readiness`（fleet dev-v3 @ `2a3b9df59`，09:52 实测）——团期 `2101514348969226242` 返回 `WARN_SEAT_SHORTAGE`（`seatTotal=7`、`passengerSeatTotal=6`、`headcount=40`、`gap=34`）；团期 `2102066067272826881` 座位合计 0 时 `passengerSeatTotal=0`；团期 `2101997326354862082`（5/4/4）与 `2101690789438570497`（7/6/6）`warned=false`。全程只读 GET。
+- **兼容性结论**：`seatTotal` 语义与数值不变，新增字段为增量、老前端不会因缺字段崩溃；但**任何用 `seatTotal` 反算缺口的旧逻辑会差 1×车数**，必须改读 `passengerSeatTotal`（或直接用 `gap`）。
+
+---
+
+## 十、相关文档
+
+- 接口契约：`hl-fleet-service/src/main/java/com/hulalv/fleet/dispatch/controller/GroupDispatchQueryController.java`
+- 响应结构：`hl-fleet-service/src/main/java/com/hulalv/fleet/dispatch/vo/GroupDispatchReadinessItemVO.java`
+- 口径工具：`hl-fleet-service/src/main/java/com/hulalv/fleet/common/util/VehicleSeatCapacity.java`
+- 同口径前置单：#8278 / PR #8296（团级 809116 扣司机座），本单是其 `changelogs-v2/2026-09/23_8278_团级用车分组座位校验扣司机座-修改接口-管理后台.md` 里声明的「fleet 团级就绪检查仍不扣座、由 #8294 跟踪」的收口。
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8294](https://git.1814.love/wx/HL/issues/8294)
+- **PR**: [#8305](https://git.1814.love/wx/HL/pulls/8305)
+- **Merge commit**: [2a3b9df59](https://git.1814.love/wx/HL/commit/2a3b9df591255be691694023812b3878debfb70e)
+
+### 联系人
+
+- **后端负责人**: @wx
@@ -0,0 +1,293 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8301"
+title: "车务看板带日期筛选时，单条 requirement_id 为空的派车行不再清空整个日期窗"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "not_required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "前端 2026-09-24 核验 not_required:接口契约零变化(路径/参数/字段/错误码全不变),纯后端行为修正——带日期筛选时 requirement_id 空脏行由整窗失败关闭返空改为跳过+WARN,同窗其余订单照常返回。grep 实证:看板列表前端只渲染 records,无对「整窗空」的特殊分支/依赖;fleet/board 前端 requirementId 唯一消费点在 useNoVehicleDeclaration(读详情 /orders/{orderId} 查无车声明),与看板列表日期分支无关。后端修正让数据更完整,前端天然受益零改动。"
+updated_at: "2026-09-24"
+base: "dev-v3"
+---
+
+# fleet: 看板日期筛选分支的脏行失败关闭收窄为跳过单行
+
+> **存放目录**: `changelogs-v2/2026-09/`
+>
+> **服务**: hl-fleet-service
+> **PR**: #8310
+> **Issue**: #8301
+> **日期**: 2026-09-24
+> **影响范围**: 管理后台「车务看板」订单列表/网格视图（带日期筛选时）
+
+---
+
+## ⚠️ 关键变化
+
+**带日期筛选时，单条脏数据不再清空整个日期窗。** 此前只要日期窗里存在任意一条 `requirement_id` 为空的派车行，`GET /admin/fleet/board/orders`（带 `startDate/endDate` 或 `startDayFrom/startDayTo`）就整页返回 `records=[]`、`total=0`、`code=200`，**不报错**——页面上看到的是「这几天没有订单」而不是任何异常。现在这条行被**跳过并记 WARN**（WARN 里带 `orderId`/`assignmentId`/`assignmentGroupId`），同一日期窗内其余订单**照常返回**，与不带日期筛选时的既有口径一致。
+
+**接口契约零变化**：路径、参数、字段、类型、必填性、枚举、错误码全部不变，只修正日期分支的行为。
+
+---
+
+## 一、背景
+
+车务看板带日期筛选时走一条独立的「当前主单日期候选」扫描分支。该分支原本把四类候选行异常合并成一个失败关闭条件，其中一类是「派车行的 `requirement_id` 为空」——这是历史数据迁移、手工修数或未来写路径缺陷可能留下的占位行。这类行本身匹配不上任何用车需求，在不带日期的路径里只是被跳过并记一条汇总 WARN；但在日期分支里，它会让**同页全部订单**的候选一起作废，表现为整窗静默返回空。
+
+本次把该条件按成因拆开：真正影响槽位聚合正确性的三类结构性畸形（行对象缺失、主单 ID 缺失、派车组 ID 与派车 ID 同时缺失）以及重复槽位键**仍然失败关闭**，只是各自补一条带定位信息的 WARN；`requirement_id` 为空的行改为逐行剔除并记 WARN。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 看板订单列表 | GET | `/admin/fleet/board/orders` | 行为变更（契约不变） | 带日期筛选时，`requirement_id` 为空的派车行由「整窗失败关闭」改为「跳过该行 + WARN」 |
+
+---
+
+## 三、接口详情
+
+### 1. 看板订单列表 `GET /admin/fleet/board/orders`
+
+**VO**: `BoardOrderPageReqVO → BoardOrderPageRespVO`（`records: BoardOrderRecordVO[]`）
+
+#### 使用场景
+
+管理后台「车务看板」订单列表/网格视图（`variant=list|grid`）。车务人员按状态、日期、团号、车型等条件筛出待派/已派订单卡片，逐卡执行改派、派车、查看行程等操作。本次改动只影响**带日期筛选**时该列表返回的记录集合。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| startDate | Query | LocalDate | ❌ | `yyyy-MM-dd` | 行程日期窗起（`startDayFrom` 的兼容别名） |
+| endDate | Query | LocalDate | ❌ | `yyyy-MM-dd` | 行程日期窗止（`startDayTo` 的兼容别名） |
+| startDayFrom | Query | LocalDate | ❌ | `yyyy-MM-dd` | 行程日期窗起；为空时回落到 `startDate` |
+| startDayTo | Query | LocalDate | ❌ | `yyyy-MM-dd` | 行程日期窗止；为空时回落到 `endDate` |
+| statuses / status | Query | String[] / String | ❌ | 枚举：unassigned/unassigned_urgent/holding/holding_urgent/assigned/canceled/completed | 状态筛选，可多选；`status` 为单值兼容别名 |
+| vehicleTypeKeys / typeKeys | Query | String[] | ❌ | 车型大类字典值 | 车型多选筛选 |
+| keyword / driverName / contactName / teamNo / plannerName | Query | String | ❌ | - | 关键字、司机、联系人、团号、定制师等模糊搜索 |
+| groupBatchId | Query | Long | ❌ | 等值匹配 | 运营团期 ID |
+| consultantId | Query | Long | ❌ | - | 定制师 ID 精确筛选 |
+| variant | Query | String | ❌ | `list`/`grid` | 视图口径 |
+| page（或 pageNo） | Query | Integer | ❌ | ≥1，缺省 1 | 页码 |
+| pageSize | Query | Integer | ❌ | 1-100 | 每页条数 |
+
+> 本单不新增、不删除、不改任何参数的类型与必填性；上表只为把「受影响的日期参数」放进完整上下文。
+
+#### 出参 `Result<BoardOrderPageRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| records | BoardOrderRecordVO[] | 本页看板卡片；本次改动只影响带日期筛选时该数组的内容 |
+| total | Long | 命中总数；带日期筛选时不再被单条脏行清零 |
+| page | Integer | 当前页码 |
+| pageSize | Integer | 每页条数 |
+| records[].id | Long | 派车行/虚拟条目主键 |
+| records[].orderId / orderNo / teamNo | Long / String / String | 子订单 ID、订单编号、团号 |
+| records[].assignmentId / assignmentGroupId / requirementId | Long | 派车行 ID、派车分组 ID、当前用车需求 ID |
+| records[].assignmentStatus | String | 派单状态码 |
+| records[].virtualPending | Boolean | 虚拟待派卡标记（真实记录恒为 `false`） |
+| records[].groupVehicleCovered | Boolean | 团车整段接管标记（详见 #8235 交接件） |
+| records[].urgentBadge / canAssign / dispatchReadOnly | String / Boolean / Boolean | 加急标签、可派车、只读 |
+| records[].startDate / endDate | LocalDate | 行程起止日期 |
+| records[].currentVehiclePlate / currentDriverName | String | 当前车辆车牌 / 司机姓名 |
+
+#### 请求示例
+
+```http
+GET /admin/fleet/board/orders?startDate=2026-11-01&endDate=2026-11-10&variant=list&pageNo=1&pageSize=20
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "records": [
+      {
+        "id": 7330843067599549,
+        "orderId": 2101014943313670001,
+        "orderNo": "HL20261106000001",
+        "teamNo": null,
+        "assignmentId": 7330843067599549,
+        "assignmentGroupId": 7330843067599549,
+        "requirementId": 2101014943313670100,
+        "assignmentStatus": "holding",
+        "virtualPending": false,
+        "groupVehicleCovered": null,
+        "urgentBadge": null,
+        "canAssign": true,
+        "dispatchReadOnly": false,
+        "startDate": "2026-11-06",
+        "endDate": "2026-11-07",
+        "currentVehiclePlate": null,
+        "currentDriverName": null
+      }
+    ],
+    "total": 1,
+    "page": 1,
+    "pageSize": 20
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+无匹配记录时返回空数组与 `total=0`，不报错：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": { "records": [], "total": 0, "page": 1, "pageSize": 20 },
+  "success": true
+}
+```
+
+带日期筛选时的空列表**仍不等同于**「该日期窗确实无单」：日期候选扫描取数失败、结果集缺失、候选行结构畸形（行对象缺失 / 主单 ID 缺失 / 派车组 ID 与派车 ID 同时为空）或槽位键重复时，本页仍按既有 fail-closed 口径整体返回空，但每一种成因现在都会在 `hl-fleet-service` 日志里留下一条可区分的 WARN。不带日期筛选的查询不走这条分支。
+
+#### 错误响应
+
+```json
+{
+  "code": 401,
+  "message": "未登录或登录已过期",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- 只影响**带日期筛选**的分支。不带日期的查询、车辆矩阵接口、看板汇总接口的口径与本次改动前完全一致。
+- `requirement_id` 为空的派车行会被剔除：该行原本在不带日期的路径里也匹配不上任何用车需求、不可能出现在看板上，因此剔除它不会让**本该展示**的卡片消失。
+- 若某订单在日期窗内**只有**这一条脏行，该订单在带日期的视图里看不到——这与它不带日期时的既有表现一致；让它可见需要的是数据修复，不是看板放行。
+- 日期候选结果集本身取到空（无订单上下文）时不查派车行，正常返回空页。
+- 鉴权：管理后台登录态，未登录 401（网关拦截）。
+
+---
+
+## 四、契约约束与正确调用方式
+
+### ✅ 正确 / ❌ 错误用法对照
+
+| 场景 | 说明 |
+|------|------|
+| ✅ 直接使用 `total` 与 `records` | 结构与字段均未变，前端无需做任何解析适配 |
+| ✅ 把带日期筛选返回的空列表理解为「结构性异常或确实无单」 | 本次改动后，单条 `requirement_id` 为空的脏行不再制造这种空结果；剩余会制造空结果的是结构性畸形（行缺失、主单 ID 缺失、槽位键缺失或重复），均会在服务端留 WARN |
+| ❌ 为「带日期筛选可能返回空」保留前端兜底或本地缓存回填 | 本次改动后不再是必需；保留也不会出错，但会把真实的结构性畸形空结果一并掩盖 |
+| ❌ 依赖后端 WARN 的具体文案做前端逻辑 | WARN 只面向排障，文案不是契约 |
+
+### 切换状态时的必要动作
+
+无。本接口是只读 GET，跳过脏行的判定完全由后端在读取时完成，不接受前端传参覆盖，也不需要前端在请求前做任何字段准备。
+
+---
+
+## 六、边界行为
+
+- 未登录 → 401（网关拦截）
+- 无匹配记录 → 200 + 空数组、`total=0`，不报错
+- 日期候选行含 `requirement_id` 为空的行 → 200，该行被跳过并记 WARN，其余订单照常返回（本次改动）
+- 日期候选行结构畸形（行对象缺失 / 主单 ID 缺失 / 派车组 ID 与派车 ID 同时缺失）或槽位键重复 → 200 + 整页空（既有 fail-closed 口径保留），并新增带定位信息的 WARN
+- order-v3 日期候选页取数失败、超过单次一致性快照上限或上下文畸形 → 200 + 整页空（既有 fail-closed 口径保留）
+- 虚拟待派候选层不可用（开关关闭或远端候选不可用）→ 只丢虚拟条目，真实派车行照常返回
+
+---
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 | 变化说明 |
+|------|------|------|----------|
+| 请求 / 响应字段 | 无变化 | 无变化 | 本次为纯行为修正，不新增、不删除、不改类型 |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 | 影响 |
+|------|------|------|------|
+| 日期窗内某订单存在一条 `requirement_id` 为空的派车行 | **整窗**返回 `records=[]`、`total=0`、`code=200`，服务端无日志 | 只**跳过该行**并记 WARN，同窗其余订单正常返回 | 带日期筛选的列表不再被单条脏数据清空 |
+| 同一数据**不带日期**查询 | 该行被跳过 + 一条汇总 WARN | 不变 | 无 |
+| 日期候选出现重复槽位键 | 整页失败关闭，无日志 | 整页失败关闭（不变），新增带重复键样本的 WARN | 排障可定位 |
+| 日期候选行结构畸形（行缺失 / 主单 ID 缺失 / 槽位键全缺） | 整页失败关闭，无日志 | 整页失败关闭（不变），新增带成因与定位字段的 WARN | 排障可定位 |
+
+---
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 否。请求参数、响应结构、字段类型与错误码全部不变，仅带日期筛选时的记录集合与 `total` 不再被单条脏数据清零。
+- **前端是否必须同步上线**: 否。前端无需修改即可受益。
+- **前端 workaround 清理点**: 若前端此前针对「带日期筛选偶发返回空」做过兜底或本地回填，可以在确认后移除；保留不影响功能。
+
+---
+
+## 七、不影响范围
+
+- **仅影响**：管理后台「车务看板」订单列表/网格视图（`/admin/fleet/board/orders`）在**带日期筛选**时的记录集合与 `total`。
+- **零影响**：
+  - 不带日期筛选的看板订单列表口径
+  - 车辆矩阵未派清单、网格与月度统计（`/admin/fleet/matrix/**`，不走日期候选扫描分支）
+  - 看板汇总与统计接口
+  - 派车、改派、确认等写接口
+  - 用车需求与派车行的数据结构、状态机与任何表结构
+
+---
+
+## 八、测试环境已验证
+
+测试服部署（`deploy:test` 单写租约）：`hl-fleet-service` 2026-09-24 10:49:54 滚动部署到 `dev-v3 @ cc70c9ba3`（该提交是本次 squash 合并 `48c755fd1` 的后代），实例 8187 / 8087 均 UP 且健康检查通过。
+
+网关实测（`https://api.test.1814.love`，管理后台登录态切到车务角色）：
+
+| # | 请求 | 修复前 `total` | 修复后 `total` |
+|---|------|----------------|----------------|
+| 1 | `GET /admin/fleet/board/orders`（不带日期） | 243 | 243（对照组，未变）✓ |
+| 2 | `...&startDate=2026-11-01&endDate=2026-11-10`（窗内含脏行） | **0** | **8** ✓ |
+| 3 | `...&startDayFrom=2026-11-01&startDayTo=2026-11-10`（同窗别名参数） | **0** | **8** ✓ |
+| 4 | `...&startDate=2026-09-24&endDate=2026-11-04`（窗内不含脏行） | 71 | 71（对照组，未变）✓ |
+| 5 | `...&startDate=2026-11-06&endDate=2026-11-06`（脏行当天） | **0** | **6** ✓ |
+| 6 | `...&startDate=2026-11-05&endDate=2026-11-07` | **0** | **6** ✓ |
+
+服务端逐行 WARN（两个实例各两条，与上表实测同刻，原始行）：
+
+```text
+2026-09-24 10:50:56.063 [http-nio-8087-exec-1] WARN c.h.f.b.service.BoardCandidateSource - 车务看板列表日期候选剔除无用车需求ID的派单行（本行不参与候选）: orderId=2101014943313670146 assignmentId=7330843067599548 assignmentGroupId=7330843067599548
+2026-09-24 10:50:56.556 [http-nio-8187-exec-2] WARN c.h.f.b.service.BoardCandidateSource - 车务看板列表日期候选剔除无用车需求ID的派单行（本行不参与候选）: orderId=2101014943313670146 assignmentId=7330843067599548 assignmentGroupId=7330843067599548
+```
+
+那条脏行（`assignment_id=7330843067599548`，`order_id=2101014943313670146`，行程日期 2026-11-06）本身不再出现在任何日期窗结果里——它匹配不上任何用车需求，本就无法在看板渲染；关键变化是它不再让同窗其余订单一起消失。
+
+本地验证：定向 42/42 绿、看板与矩阵影响面回归 379/379 绿、`spotless:check` 与 `mvn -o -pl hl-fleet-service -am verify` 均 BUILD SUCCESS（该模块 4766 个用例 0 失败 0 错误 6 跳过）。
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#8301](https://git.1814.love/wx/HL/issues/8301)
+- 关联 PR: [wx/HL#8310](https://git.1814.love/wx/HL/pulls/8310)
+- 同一接口的上一份交接件（#8235，看板订单记录新增 `groupVehicleCovered`），其中「带日期筛选的既有 fail-closed 口径」一条由本文件取代
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8301](https://git.1814.love/wx/HL/issues/8301)
+- **PR**: [#8310](https://git.1814.love/wx/HL/pulls/8310)
+- **Merge commit**: [48c755fd1](https://git.1814.love/wx/HL/commit/48c755fd1feff715f9ec946b55f77207f23dc942)
+
+### 联系人
+
+- **后端负责人**: @wx
+- **前端负责人**: @mmg
@@ -0,0 +1,518 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8311"
+title: "团期正式用车需求分组座位数改由车队字典档位下拉选择（可选可改），新增 809124 档位校验与汇总座位兜底诊断"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "debb0bc2e22be878243ea8ffe89dd0b9091656a1"
+target_release: "v2.1"
+verified_at: "2026-09-24"
+status_note: "PR #8324 squash 合并 dev-v3（1638faf08）。部署：hl-order-service-v3 dev-v3 @ 1638faf08，2026-09-24 12:06:26 滚动部署两实例，deploy-status 读数 BEHIND=0/N STATE=ok；请求路径上 hl-gateway 与 hl-fleet-service 同为 ok、BEHIND 右侧 N。测试服网关真实 PUT 实测（groupBatchId=2102692937584513025，BUS 16座/SUV 5座 DRAFT）：BUS 13 座 → code=809124「第 BUS 组的座位数 13 不在车型 bus 的可选档位 [12, 15, 16, 19] 内，请从下拉项中选择」；SUV 6 座 → code=809124「…不在车型 suv 的可选档位 [5, 7] 内…」；两次拒绝后回读 version 与 seats 均未变（零写入）；原值（BUS 16/SUV 5）→ code=200 且落库一致。aggregate-draft 实测回 seatOptionAdjusted=[]（当前测试团期没有非法档位子订单）与 draft BUS=16/SUV=5。定向测试 14 个类全绿（SaveTest 31 / DraftAggregatorTest 24 / AggregateDraftTest 12 / ConfirmCheckTest 19 等）。809123 已被同日并入的 #8219 占用，本单让号到 809124。 | 2026-09-24 mmg 交付:编辑弹窗座位数手输改档位下拉(选项取字典 seatOptions 按 typeKey,存量非法值合成占位回显 rule 前置拦,档位不可得不拦),切车型联动清空座位,既有组/汇总灌入组号只读(手增空白组仍可填),汇总诊断四数组改五数组 seatOptionAdjusted 按三种 reason 分文案带 [groupCode] 定位;809124 无按码分支拦截器透报文(带组号+档位列表)即引导;spec 44 例全绿(3 新例+既有下标适配)"
+updated_at: "2026-09-24"
+base: "dev-v3"
+---
+
+# order-v3 团期需求: 分组座位数改为字典档位可选 + 809124 档位校验
+
+> **存放目录**: 二期(v3) → `changelogs-v2/2026-09/`
+>
+> **服务**: hl-order-service-v3（团期需求域，groupbatch 包）
+> **PR**: 待建
+> **Issue**: #8311
+> **日期**: 2026-09-24
+> **影响范围**: 管理后台「团期详情 → 查看需求」Tab 的正式用车需求编辑弹窗（含「自动汇总」）
+
+---
+
+## ⚠️ 关键变化（非必须,本版与上版行为不同 / 纠错 / 撤销时必写）
+
+- **新增错误码 809124**：`PUT .../vehicle-requirement` 现在会校验「该组的 `seats` 必须落在该组 `vehicleType` 在车队车型字典里的可选座位档位（seatOptions）内」，不在档位内整份提交被拒。
+- **本条与子订单级早已存在的同款校验对齐**：子订单用车需求的 `fleet[].seats` 一直有这条（错误码 **582024**「座位数不在该车型大类可选座位数中，请检查车型库」）；团级此前只校验「半填 809118」与「容量不足 809116」，收任意 ≥1 的座位数。本单把团级补齐到同一口径。
+- **前端交互随之改变**：座位数不再是自由输入框，改为下拉，选项取自 `GET /admin/fleet/vehicle-types/list` 里该 `typeKey` 的 `seatOptions`。**这条校验是硬约束，不是提示**——手输/绕过下拉提交字典外档位会被 809124 拒绝。
+- **`aggregate-draft` 的 `draft.groups[].seats` 语义变更**：#8220 时它取「组内子订单报的最大单车座位」；现在取**该车型大类档位内的值**（子订单报的值在档位内就取组内最大，不在档位内或没报则兜底到该大类**最大档**），被兜底调整的户逐条列在新字段 `seatOptionAdjusted`。**前端必须展示该字段**，否则「子订单报 13 座、草稿变成 19 座」这件事在页面上不可见。
+- **组号（`groupCode`）仍由后端生成**（车型大写 + 同车型拆组序号：`BUS`、`BUS2`…），表单不应提供输入框；同车型被拆成多组时，`seatOptionAdjusted[]` 里带 `groupCode` 用于定位是哪一组。
+
+---
+
+## 一、背景（选填）
+
+wx 2026-09-24 定案：正式用车需求编辑弹窗里「单车座位数」应由手输改为**按车队字典档位下拉选择（可选、可改）**。落地时发现团级缺少子订单级早就有的「座位数必须在 seatOptions 内」校验：不补这条，下拉只是页面上的自觉，直接调接口仍能把车队没有的档位（如大巴 13 座）写进正式需求，车务排车时对不上型号。本单同时把「自动汇总」的座位默认值改为落在档位内，并对被调整的户出诊断，避免静默改数。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 保存团期正式用车需求 | PUT | `/v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement` | 新增校验 + 新错误码 | 新增 809124（座位数不在该组车型大类可选档位内）；档位不可得复用 809120 |
+| 2 | 自动汇总正式用车需求草稿 | GET | `/v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement/aggregate-draft` | 响应新增字段 + 既有字段语义变更 | 新增 `seatOptionAdjusted[]`；`draft.groups[].seats` 改为档位内的值 |
+| 3 | 车型大类全量列表（复用，不改） | — | — | 复用不改 | 座位下拉数据源（`seatOptions`）仍走 `GET /admin/fleet/vehicle-types/list`，本单未改它；契约见第八节说明 |
+
+---
+
+## 三、接口详情
+
+### 1. 保存团期正式用车需求 `PUT /v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement`
+
+**VO**: `GroupVehicleRequirementSaveReqVO → GroupVehicleRequirementRespVO`
+
+#### 使用场景
+
+团期详情「查看需求 → 团级正式用车需求」编辑弹窗点保存。语义仍是**整份全量替换**：未出现在本次提交里的分组会被移出当前版本。请求体与响应体结构均不变，本次只新增一条校验与一个错误码。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long | ✅ | - | 团期聚合主键 |
+| version | Body | Integer | ❌ | 首次保存传 null，其后回传上次拿到的值 | 乐观锁；不一致抛 809102 |
+| remark | Body | String | ❌ | ≤500 | 整份需求备注 |
+| groups | Body | Array | ✅ | 可以是空数组 | 全部乘车分组；有在团需车户却零分组抛 809103 |
+| groups[].groupId | Body | Long | ❌ | 新增分组传 null | 带上它即声明「这就是库里那一组」，此时 groupCode 不得变更（否则 809104） |
+| groups[].groupCode | Body | String | ✅ | ≤32，同一份内不得重复 | 直接作为车费 alloc_group；**表单不应给输入框，用后端生成的只读值** |
+| groups[].vehicleType | Body | String | ✅ | ≤64，取值见 `/admin/fleet/vehicle-types/list` | 车型大类；不在字典内抛 809119 |
+| groups[].serviceStartDate | Body | LocalDate | ✅ | `yyyy-MM-dd` | 本组服务开始日 |
+| groups[].serviceEndDate | Body | LocalDate | ✅ | 不早于开始日 | 本组服务结束日 |
+| groups[].seats | Body | Integer | ❌ | `@Min(1)`；与 count 同填或同空；**本次起必须落在该车型大类的 seatOptions 内** | 单车座位数（含驾驶位）；下拉取值见 `GET /admin/fleet/vehicle-types/list` 的 `seatOptions`；存量分组（seats 与 count 皆 null）整条跳过本校验 |
+| groups[].count | Body | Integer | ❌ | `@Min(1)`；与 seats 同填或同空 | 车辆数量；只填一半抛 809118 |
+| groups[].specialTags | Body | Array&lt;String&gt; | ❌ | 取值须在字典 `vehicle_special_demand` 内 | 特殊诉求标签编码数组；字典外编码整份拒绝（809117） |
+| groups[].remark | Body | String | ❌ | ≤500 | 该组备注 / 其他诉求 |
+| groups[].days | Body | Array | ✅ | 非空，且正好铺满本组服务日范围 | 逐日用车人数与成员 |
+| groups[].days[].tripDate | Body | LocalDate | ✅ | 落在本组服务日范围内、不重复、不缺日 | 越界或重复抛 809105，缺日抛 809106 |
+| groups[].days[].headcount | Body | Integer | ✅ | `@Min(1)`，且 ≥ 当日成员户数 | 该组该日乘车人数 |
+| groups[].days[].memberOrderIds | Body | Array&lt;Long&gt; | ✅ | 非空，须全属本团在团户 | 该组该日实际乘车的子订单集合 |
+
+#### 出参 `Result<GroupVehicleRequirementRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| requirementId | String | 正式需求主键（Long 序列化为字符串） |
+| groupBatchId | String | 团期聚合主键 |
+| status | String | DRAFT / CONFIRMED / DISPATCHED / DONE / PENDING_RECONFIRM / CANCELLED；PUT 后为 DRAFT |
+| version | Integer | 版本号，下次提交须回传 |
+| remark | String | 整份备注 |
+| confirmedBy / confirmedAt | String / LocalDateTime | 整份确认人/时间；DRAFT 时为 null |
+| groups | Array | 全部乘车分组；整团免车态为空数组 |
+| groups[].groupCode | String | 分组键 = 车费 alloc_group（后端生成，前端只读回显） |
+| groups[].vehicleType / vehicleTypeName | String | 车型大类 key / 中文名 |
+| groups[].seats | Integer | 单车座位数（含驾驶位）；存量分组为 null |
+| groups[].count | Integer | 车辆数量；存量分组为 null |
+| groups[].totalSeatCount | Integer | 总座位数 = seats × count；缺一即 null |
+| groups[].maxHeadcount | Integer | 该组 days 里的最大用车人数 |
+| groups[].remainingPassengerSeats | Integer | 余座 = 扣司机座后的可乘座位 − maxHeadcount；**可为负**，是缺口展示值，**不得据此拦截提交**（见 22_8152） |
+| groups[].days[] | Array | 逐日行程与成员（tripDate / headcount / memberOrderIds / memberOrderCount） |
+
+#### 请求示例
+
+```json
+{
+  "version": 3,
+  "remark": "9/24 换 19 座",
+  "groups": [
+    {
+      "groupId": null,
+      "groupCode": "BUS",
+      "vehicleType": "bus",
+      "serviceStartDate": "2026-10-08",
+      "serviceEndDate": "2026-10-10",
+      "seats": 19,
+      "count": 1,
+      "specialTags": [],
+      "remark": "含高速费",
+      "days": [
+        { "tripDate": "2026-10-08", "headcount": 9, "memberOrderIds": ["2102692937378992129"] },
+        { "tripDate": "2026-10-09", "headcount": 9, "memberOrderIds": ["2102692937378992129"] },
+        { "tripDate": "2026-10-10", "headcount": 9, "memberOrderIds": ["2102692937378992129"] }
+      ]
+    }
+  ]
+}
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "requirementId": "2102750063359135746",
+    "groupBatchId": "2102749115823919105",
+    "status": "DRAFT",
+    "version": 4,
+    "remark": "9/24 换 19 座",
+    "confirmedBy": null,
+    "confirmedAt": null,
+    "groups": [
+      {
+        "groupId": "2102750063363330049",
+        "groupCode": "BUS",
+        "vehicleType": "bus",
+        "vehicleTypeName": "大巴系列",
+        "serviceStartDate": "2026-10-08",
+        "serviceEndDate": "2026-10-10",
+        "seats": 19,
+        "count": 1,
+        "specialTags": [],
+        "remark": "含高速费",
+        "totalSeatCount": 19,
+        "maxHeadcount": 9,
+        "remainingPassengerSeats": 9,
+        "days": [
+          { "tripDate": "2026-10-08", "headcount": 9, "memberOrderIds": ["2102692937378992129"], "memberOrderCount": 1 }
+        ]
+      }
+    ]
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+- 整团没有在团需车户时 `groups: []` 是合法提交，响应 `groups` 为空数组。
+- 车队车型字典（含座位档位）取不到时，**保存口 fail-closed**：抛 809120「车队车型字典暂不可用，无法校验车型，请稍后重试」，本次提交零写入。
+- `vehicleTypeName` 仍可降级为 null（只影响展示），不影响本单校验。
+
+```json
+{ "code": 200, "message": "成功", "data": { "groups": [] }, "success": true }
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 809124,
+  "message": "第 BUS 组的座位数 13 不在车型 bus 的可选档位 [12, 15, 16, 19] 内，请从下拉项中选择",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- **报文字段**：{0}=组号（`groupCode`，不是序号）、{1}=本次提交的座位数、{2}=车型大类 key、{3}=该大类的可选档位（升序、方括号包裹）。一次只抛一条，按校验遍历顺序收集。
+- **校验顺序**：座位档位（809124 / 809120）→ 半填（809118）→ 容量不足（809116）。**档位不可得（报 809120）时不会吞掉同组的半填与容量判据**，仍会继续判下去，避免「先提示稍后重试、补完车辆数才被告知半填」的来回。
+- **存量分组（seats 与 count 皆 null）整条跳过**：不查字典、不报 809124/809120/809116。这是为了让「不带 fleet 结构再 PUT 一次」的历史团期不会被一刀拦死。
+- **只填了车辆数（seats 为 null）时不判档位**：交给 809118 报半填，不会编出一条「座位数不在档位内」。
+- **该车型大类在车队没有任何型号**（`seatOptions` 为空）按「档位不可得」处理 → 809120，需先去车务补型号。
+- **注意与子订单级错误码不同**：子订单级同一件事是 582024，团级是 809124；两条链路的报文与码值刻意分开（团级报文必须带组号，一份十几组的整份提交被拒后要能定位是哪一组）。
+
+---
+
+### 2. 自动汇总正式用车需求草稿 `GET /v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement/aggregate-draft`
+
+**VO**: `GroupVehicleAggregateDraftRespVO`
+
+#### 使用场景
+
+编辑弹窗点「自动汇总」时调用，拿到 `draft` 灌进表单、原样或编辑后 PUT 保存；四个（本次起为五个）诊断字段必须一并展示。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long | ✅ | - | 团期聚合主键（不是产品班期 ID） |
+
+#### 出参 `Result<GroupVehicleAggregateDraftRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| groupBatchId | String | 团期聚合主键 |
+| currentStatus | String | 当前正式需求状态；未形成时为 null。只有 null 或 DRAFT 能保存 |
+| draft | Object | 与保存请求体同形，可原样 PUT；`groupId` 恒为 null |
+| draft.groups[].groupCode | String | 后端生成的组号（车型大写 + 拆组序号：BUS、BUS2…），**前端只读展示，不要给输入框** |
+| draft.groups[].vehicleType | String | 归一后的车型大类 key（suv2 → suv） |
+| draft.groups[].seats | Integer | **本次起为档位内的值**：子订单报的座位在档位内取组内最大，不在档位内或没报则兜底该大类最大档；档位不可得时退回旧规则（取子订单报的最大值） |
+| draft.groups[].count | Integer | `ceil(本组最忙那天的人数 / (seats − 1))`，已扣司机座；seats < 2 时与 seats 一起为 null |
+| draft.groups[].days[] | Array | 逐日明细，正好铺满本组首日到末日（headcount 为该日实时人数之和） |
+| droppedFleetItems[] | Array | 没进草稿的车型项（多车型户只进主车型）；**必须提示** |
+| staleHeadcountOrders[] | Array | 实时人数 ≠ 子订单冻结人数的户 |
+| paddedOrderDays[] | Array | 为过 809109 补进分组的日期 |
+| **seatOptionAdjusted[]** | Array | **本次新增**：座位档被兜底调整的户，见下 |
+| seatOptionAdjusted[].groupCode | String | 该户所在的草稿分组编码（同户同车型被拆成 BUS/BUS2 时用它区分） |
+| seatOptionAdjusted[].orderId / orderNo | String / String | 所属子订单（雪花 ID 按字符串处理） |
+| seatOptionAdjusted[].vehicleType | String | 车型大类（草稿里该组的 vehicleType） |
+| seatOptionAdjusted[].originalSeats | Integer / null | 子订单报的单车座位数；没报时为 null |
+| seatOptionAdjusted[].adoptedSeats | Integer | 草稿实际采用的座位数（该组档位内的值） |
+| seatOptionAdjusted[].seatOptions | Integer[] | 该大类的可选档位（升序） |
+| seatOptionAdjusted[].reason | String | `SEATS_NOT_IN_OPTIONS` / `SEATS_MISSING` / `SEATS_MISSING_ADOPTED_GROUP_VALUE` |
+| violations[] | Array | 草稿预检违规（与保存同一份校验内核）：code / reason / detail / groupCode / tripDate / orderId |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch/2102749115823919105/vehicle-requirement/aggregate-draft
+Authorization: Bearer <admin token>
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "groupBatchId": "2102749115823919105",
+    "currentStatus": null,
+    "draft": {
+      "version": null,
+      "remark": null,
+      "groups": [
+        {
+          "groupId": null,
+          "groupCode": "BUS",
+          "vehicleType": "bus",
+          "serviceStartDate": "2026-10-08",
+          "serviceEndDate": "2026-10-10",
+          "seats": 19,
+          "count": 1,
+          "specialTags": [],
+          "remark": "HL20260924001: 备注原文",
+          "days": [
+            { "tripDate": "2026-10-08", "headcount": 9, "memberOrderIds": ["2102692937378992129"] }
+          ]
+        }
+      ]
+    },
+    "droppedFleetItems": [],
+    "staleHeadcountOrders": [],
+    "paddedOrderDays": [],
+    "seatOptionAdjusted": [
+      {
+        "groupCode": "BUS",
+        "orderId": "2102692937378992129",
+        "orderNo": "HL20260924001",
+        "vehicleType": "bus",
+        "originalSeats": 13,
+        "adoptedSeats": 19,
+        "seatOptions": [12, 15, 16, 19],
+        "reason": "SEATS_NOT_IN_OPTIONS"
+      }
+    ],
+    "violations": []
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+- 草稿没有可汇总内容时 `draft.groups` 为空数组，`seatOptionAdjusted` 为空数组，接口仍 200。
+- 有需车户还没提交行程用车需求时报 809121 并逐户列出（不是空草稿）。
+- **某车型大类在车队没有型号时，汇总口不 fail-closed**：退回旧规则（取子订单报的座位）、不出 `seatOptionAdjusted`，同时在 `violations` 里给出 809120，让页面能提示「这类车型还没在车务建档」。整张字典不可用（Feign 降级）仍直接抛 809120。**保存口对同一情形是 fail-closed**——这条差异是有意的：汇总是只读草稿，卡住它等于管理员连看都看不到。
+
+```json
+{ "code": 200, "message": "成功", "data": { "draft": { "groups": [] }, "seatOptionAdjusted": [], "violations": [] }, "success": true }
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 809121,
+  "message": "团期 2102749115823919105 有 2 户缺少可汇总的行程用车需求，暂不能自动汇总：HL20260924001(2102692937378992129)：未提交行程用车需求、HL20260924002(2102692937378992130)：车型均不在车型字典内",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- `reason` 的三种取值对前端提示语不同：`SEATS_NOT_IN_OPTIONS` = 「你报的 N 座这台车没有，已改用 M 座」；`SEATS_MISSING` = 「这户没报座位，跟字典最大档 M 座走」；`SEATS_MISSING_ADOPTED_GROUP_VALUE` = 「这户没报座位，采用的值 M 来自同组其它户报的合法档位（不是字典最大档）」。**不要把后两者渲染成「系统按字典给你选了 M 座」**。
+- 座位是**单车**属性，多户报的值不相加（沿用 #8220）。
+- 拆组逻辑不变：同车型按连续日期段拆组，第二段起组号加序号；诊断行按所属组带 `groupCode`。
+- `draft.groups[].seats` 即使已被兜底到档位内，**保存时仍会按新校验复核**（同一条 809124）；本端点不替代保存侧校验。
+
+---
+
+## 四、契约约束与正确调用方式（接口类必写）
+
+- 座位下拉的数据源是 `GET /admin/fleet/vehicle-types/list` 返回项里的 `seatOptions`（该大类下型号 `seats` 去重升序），**按 `typeKey` 取**（SUV 这类在库里的 typeKey 可能是 `suv2`，返回的 `vehicleType` 是归一后的 `suv`，见 23_8221）。**不要在前端写死档位枚举**。
+- 切换车型时必须同步换档位并清空旧值，否则旧档位会带着新车型一起提交 → 809124。
+
+### ✅ 正确 / ❌ 错误 payload 对照（分组元素）
+
+```json
+// ✅ 大巴档位 12/15/16/19 中取值，seats 与 count 成对
+{ "groupCode": "BUS", "vehicleType": "bus", "seats": 19, "count": 1 }
+
+// ❌ 13 不在大巴档位内 → 809124
+{ "groupCode": "BUS", "vehicleType": "bus", "seats": 13, "count": 1 }
+
+// ❌ 只填座位数、车辆数漏填 → 809118（不是 809124）
+{ "groupCode": "BUS", "vehicleType": "bus", "seats": 19 }
+
+// ✅ 存量分组形态：两列都不传，整条跳过档位与容量校验
+{ "groupCode": "BUS", "vehicleType": "bus" }
+```
+
+### 切换状态时的必要动作
+
+- 保存成功后响应 `version` 会 +1，下次保存必须回传新值，否则 809102。
+- 「自动汇总」会整份覆盖当前编辑内容，前端须二次确认后再灌入。
+
+---
+
+## 五、数据库行为（涉及写操作时必写）
+
+- 无表结构变更、无 Flyway。
+- 809124 / 809120 都在写库之前抛出：**整份零写入**（校验失败时响应 `data` 为 null，可回读同一份数据确认未变）。
+
+---
+
+## 六、边界行为
+
+- 存量分组不批量重算、不迁移：只有它下次出现在某次 PUT 的 `groups` 数组里才会按新校验复核（两列皆 null 时仍整条跳过）。
+- 同一份提交里多个组同车型时，字典只查一次（不是每组一次 Feign）。
+- 车队车型字典服务超时/降级：保存口 fail-closed 报 809120；汇总口退回旧座位规则并在 `violations` 里报 809120。
+
+---
+
+## 六.5、枚举 / 数据字典（接口出现枚举时必写）
+
+### 错误码
+
+| 码 | 触发 | 报文 |
+|---|---|---|
+| 809124 | 该组 `seats` 不在该组 `vehicleType` 的可选档位内 | 第 {0} 组的座位数 {1} 不在车型 {2} 的可选档位 {3} 内，请从下拉项中选择 |
+| 809120（复用） | 车队车型字典不可用 / 该大类在车队没有型号（档位不可得） | 车队车型字典暂不可用，无法校验车型，请稍后重试 |
+| 809118（不变） | `seats` 与 `count` 只填了一个 | 第 {0} 组的座位数与车辆数必须同时填写，或同时留空 |
+| 809116（不变） | 扣司机座后可载客座位少于该组最大单日人数 | 第 {0} 组座位数不足：{1} 座 × {2} 辆，扣除 {3} 个司机座后可载客 {4} 人，少于该组最大乘车人数 {5} 人 |
+
+### seatOptionAdjusted[].reason
+
+| 取值 | 含义 | 建议提示语 |
+|---|---|---|
+| `SEATS_NOT_IN_OPTIONS` | 子订单报了座位但不在该大类档位内 | 该户报的 {originalSeats} 座本车型没有，草稿改用 {adoptedSeats} 座（可选 {seatOptions}） |
+| `SEATS_MISSING` | 子订单没报座位，草稿按字典最大档兜底 | 该户没报座位，草稿按 {adoptedSeats} 座（字典最大档）计 |
+| `SEATS_MISSING_ADOPTED_GROUP_VALUE` | 子订单没报座位，草稿采用的值来自同组其它户报的合法档位 | 该户没报座位，草稿跟随本组 {adoptedSeats} 座计 |
+
+---
+
+## 六.6、修改前后对比（修改/删除类接口必写，新增跳过）
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 |
+|------|------|------|
+| 保存接口请求/响应字段 | — | 无新增、无删除，结构不变 |
+| `aggregate-draft` 响应 | 无 `seatOptionAdjusted` | 新增 `seatOptionAdjusted[]`（8 个子字段） |
+| `draft.groups[].seats` | 组内子订单报的最大单车座位 | 该大类档位内的值（在档位内取组内最大、否则兜底最大档；档位不可得退回旧规则） |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| 提交字典内档位（如 bus 19 座） | 放行 | 放行（不变） |
+| 提交字典外档位（如 bus 13 座） | **放行** | **809124 拒绝** |
+| 提交座位数但车型大类在车队没有型号 | 放行 | 809120 拒绝（保存口）；汇总口退回旧规则 + violations 里报 809120 |
+| 存量分组（seats/count 皆 null）整份再提交 | 跳过座位相关校验 | 不变，仍整条跳过 |
+| 预检/整团确认侧 | 不校档位 | 不变（该入口读的是库里已存值，且被 `doConfirm` 在事务内调用，见「七、不影响范围」） |
+
+---
+
+## 六.7、影响评估（修改/删除类必写）
+
+- **是否破坏向后兼容**：请求/响应结构不变，但**同一份 payload 可能从 200 变成 809124** —— 凡是座位数不在该大类档位内的提交（含手输、含车型切换后未更新座位数）都会被拒。809124 是 HTTP 200 下的业务失败。
+- **前端是否必须同步上线**：**必须**。座位数必须改成档位下拉（否则运营按老习惯手输就会撞 809124）；`seatOptionAdjusted` 必须展示（否则草稿改座位这件事不可见）；组号输入框应改成只读展示。
+- **存量数据影响**：不批量重算、不迁移。库里的历史非法档位只会在下一次保存/汇总时暴露：保存被 809124 拒（需管理员改成档位内值）；预检与整团确认口**不**重判档位，不会把已确认流程卡死。
+
+---
+
+## 七、不影响范围（显式声明, 帮前端/QA 缩小排查面）
+
+- **仅影响**：`PUT .../vehicle-requirement` 的座位档位校验（新增 809124）；`GET .../vehicle-requirement/aggregate-draft` 的 `seats` 取值与新增 `seatOptionAdjusted`。
+- **零影响**：
+  - 两个接口的请求/响应字段结构（除新增 `seatOptionAdjusted`）。
+  - 既有错误码 809116 / 809118 / 809117 / 809119 / 809120 / 809121 / 809102 等其余判据与报文。
+  - `GET .../vehicle-requirement`（读取回显）不触发校验，原样返回库里已落值。
+  - **整团确认预检（`GET .../requirement/confirm-check`）与 `confirm` 写口不重判座位档位**：它们读的是库里已存值，且确认链路在事务内，不在那里调字典 Feign。即「历史非法档位不会卡住确认」，只会在下次编辑保存时要求修正。
+  - `GET .../requirement/vehicle-households`、`GET .../requirement-summary` 未改动。
+  - 子订单级用车需求（582024 那条）未改动。
+  - fleet 服务与网关：零改动（`/admin/fleet/vehicle-types/list` 复用既有只读端点）。
+  - 数据库：无表变更、无 Flyway。
+
+---
+
+## 八、测试环境已验证
+
+**部署读数**（测试服 `deploy-status.sh`，2026-09-24 12:07 读取）：
+
+```text
+SERVICE                  BRANCH    COMMIT     BEHIND   DEPLOYED_AT          STATE
+hl-order-service-v3      dev-v3    1638faf08  0/N      2026-09-24 12:06:26  ok
+hl-gateway               dev-v3    c238f38c3  182/Y    2026-09-21 14:44:55  ok
+hl-fleet-service         dev-v3    cc70c9ba3  6/N      2026-09-24 10:49:54  ok
+```
+
+被测服务 `BEHIND=0/N STATE=ok`；请求路径上的 `hl-gateway` 与断言依赖的 `hl-fleet-service` 同为 `ok`，两行的 BEHIND 右侧字母均为 `N`（落后提交未触及这两个服务本身）。
+
+**网关真实请求与响应**（`https://api.test.1814.love`，`groupBatchId=2102692937584513025`，当前 DRAFT v3：BUS 16 座 ×1、SUV 5 座 ×1）：
+
+```text
+① 原值提交 BUS 16 座 / SUV 5 座（均在档位内）
+   PUT /v3/admin/order/group-batch/2102692937584513025/vehicle-requirement
+   → http 200, code=200, message=成功；回读 version 2→3，seats 仍为 16/5 ✓
+
+② BUS 提交 13 座（bus 档位 12/15/16/19）
+   → http 200, code=809124
+     message=第 BUS 组的座位数 13 不在车型 bus 的可选档位 [12, 15, 16, 19] 内，请从下拉项中选择 ✓
+   拒绝后回读：version 仍为 3、seats 仍为 16/5、remark 未变（整份零写入）✓
+
+③ SUV 提交 6 座（suv 档位 5/7）
+   → http 200, code=809124
+     message=第 SUV 组的座位数 6 不在车型 suv 的可选档位 [5, 7] 内，请从下拉项中选择 ✓
+
+④ GET /v3/admin/order/group-batch/2102692937584513025/vehicle-requirement/aggregate-draft
+   → code=200；draft.groups = BUS(bus, 16 座, 1 辆, 3 天) + SUV(suv, 5 座, 1 辆, 3 天)
+     seatOptionAdjusted = []（该团期子订单报的座位都合法，无兜底调整）
+     violations = []；droppedFleetItems 1 条、stale/padded 0 条 ✓
+```
+
+**定向测试逐类读数**（`mvn -o -pl hl-order-service-v3 -am test -Dtest='…' -DfailIfNoTests=false -Dhl.surefire.failIfNoTests=false`，14 个类合计 0 failures / 0 errors / 0 skipped，BUILD SUCCESS）：
+
+| 测试类 | Tests run |
+|---|---|
+| GroupVehicleRequirementSaveTest | 31 |
+| GroupVehicleDraftAggregatorTest | 24 |
+| GroupVehicleRequirementAggregateDraftTest | 12 |
+| GroupVehicleRequirementConfirmCheckTest | 19 |
+| GroupVehicleRequirementLockContractTest | 3 |
+| GroupBatchRequirementServiceTest | 73 |
+| GroupBatchRequirementServiceConfirmVehicleTest | 17 |
+| GroupBatchRequirementServiceCheckVehicleTest | 17 |
+| GroupBatchRequirementConfirmReflectionGuardTest | 4 |
+| FleetVehicleTypeNameLoaderTest | 9 |
+| TransactionalRemoteCallArchTest | 1 |
+| ErrorCodeUniquenessGuardTest | 3 |
+| RequirementGroupBatchErrorCodeRangeTest | 4 |
+| ErrorCodeTemplateNumberFormattingTest | 1 |
+
+---
+
+## 十、相关文档
+
+- 自动汇总草稿端点：#8220 → `changelogs-v2/2026-09/23_8220_团期正式行程用车需求自动汇总草稿-新增接口-管理后台.md`
+- 车辆规格四字段（seats/count/specialTags/remark）：#8152 → `changelogs-v2/2026-09/22_8152_团期用车需求补车辆规格与接送机汇总-修改接口-管理后台.md`
+- 座位充足性校验扣司机座（809116）：#8278 → `changelogs-v2/2026-09/23_8278_团级用车分组座位校验扣司机座-修改接口-管理后台.md`
+- 座位数下拉先例（子订单级）：#4856 / #4871 → `changelogs-v2/2026-07/50_4856_订单调整用车座位数按车型型号下拉-管理后台.md`
+- 车型大类字典与 SUV 回显归一：#8202 / #8221 → `changelogs-v2/2026-09/`
+
+---
+
+## 关联 / 联系人
+
+### 链接
+
+- Issue: https://git.1814.love/wx/HL/issues/8311
+- 后端 PR: 待建
+
+### 联系人
+
+- 后端: jw / wx
@@ -0,0 +1,445 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8320"
+title: "调整订单：团期子订单未录大交通时提交用车需求须显式确认「不用接送机」（新错误码 587044）"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "f8c389c1a1230316163bac80079675fb3c1a26ad"
+target_release: "v2.1"
+verified_at: "2026-09-24"
+status_note: "已合 dev-v3（PR #8326，bc197bc07）并部署测试服，deploy-status.sh 回读 hl-order-service-v3=bc197bc07、BEHIND 0/N、STATE ok。网关实测五组全过：①无大交通不带声明提交团期单车辆需求 → 587044 且整笔零写入（order_main/需求/调整记录/状态日志前后快照逐项相等）②两方向声明 true + 同一份 vehicleRequirement → 200，order_main 两列置 1，snapshot 回显 transferDeclaration=true/true、transferTransportPresent=false/false ③该方向补大交通批次后声明不生效，车务读侧仍 required=true/READY＜接客信息已齐＞ ④同一张单同一时刻：已声明不用且无批次的方向 required=false/NOT_REQUIRED/＜无需送客＞，未声明且无批次的方向 required=true/MISSING/＜待补接客信息＞（阴性对照）⑤接机有批次、送机无批次时提交非空 transferRequirement 未声明送机 → 587044＜不用送机＞且零写入；散客单同 payload 不带声明 → 200 正常落库（口径 4 成立）。定向单测 14 类 386 例全绿 + ArchUnit/错误码门禁绿。 | 2026-09-24 mmg 交付:调整订单车辆安排页新增「接送机确认」卡(仅团期子订单+该方向无大交通渲染不用接机/送机必选确认,有批次不渲染),snapshot 回显声明+基线已声明无批次锁定禁撤销,前置闸报文与 587044 逐字一致本地拦,提交整份回传 transferDeclaration 自动弃快捷写口走统一提交;FunItemAdjustModal spec 46 例全绿(新增 6 例)"
+updated_at: "2026-09-24"
+base: "dev-v3"
+---
+
+# 调整订单：团期子订单未录大交通时提交用车需求须显式确认「不用接送机」
+
+> **服务**: hl-order-service-v3
+> **PR**: #8326 ｜ **Issue**: #8320 ｜ **合并提交**: `bc197bc07`
+> **日期**: 2026-09-24
+> **影响范围**: 管理后台「订单详情 → 调整订单 → 车辆安排」。**仅团期子订单**受影响，散客单行为完全不变。
+
+---
+
+## ⚠️ 关键变化
+
+**接送机那一槽多了一条硬闸，前端不做就会撞 587044 整笔提交失败。**
+
+1. **团期子订单**（下单时带 `productBatchId` 的订单）在「车辆安排」页提交时，如果**某个方向一条大交通批次都没有**，该方向就必须在提交体里显式确认「不用接送机」（`true`），否则整笔被拒，返回 **587044**，**一个字都不落库**。有批次的方向不需要确认（沿用大交通，声明对它无效）。两个方向**各自判定**。
+2. 确认之后，**车务侧那一格的文案会变**：该方向由「待补接客信息 / 待补送客信息」变成「**无需接客 / 无需送客**」。不确认则维持「待补」——这是有意的，不要把「客人还没填大交通」读成「不用接送机」。
+3. **要接送机的路径没有变**：需要接送机就必须先把大交通录进去（接送机用车需求的服务日只能从大交通航班日派生）。本次没有新增「需要但航班未定」这种第三态。
+
+---
+
+## 一、背景
+
+「车辆安排」页的接送机用车槽，服务日由服务端从大交通批次派生。客人没录大交通时：
+
+- 订单侧算出来的接送要求是「未知」，车务侧按「需要」处理，于是看板/配车页**恒显示「待补接客信息 / 待补送客信息」**；
+- 而车务侧的接送机状态里本来就有「无需接客 / 无需送客」这一档，**订单侧却没有任何入口能把它置上**。
+
+结果是「客人还没填大交通」与「这单就是不用接送机」在数据上完全一样，接送机缺口永远关不掉。本版增加一个**订单级的显式声明**来承载「就是不用」这个语义，并在提交侧设闸，逼定制师傅表态。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|---|---|---|---|---|
+| 1 | 调整订单预填快照查询 | GET | `/v3/admin/order/{id}/adjustment/snapshot` | 修改接口 | 出参新增 `transferDeclaration` 与 `transferTransportPresent` |
+| 2 | 调整订单统一提交 | POST | `/v3/admin/order/{id}/adjustment/submit` | 修改接口 | `updates` 新增 `transferDeclaration`；某方向无大交通未表态时返回新码 **587044** |
+
+读侧（车务看板 / 团期配车）**路径与响应结构均未变**，只有接送机那一档的取值会随声明变化，见「六.6、修改前后对比」。
+
+---
+
+## 三、接口详情
+
+### 1. 调整订单预填快照查询 `GET /v3/admin/order/{id}/adjustment/snapshot`
+
+**VO**: `AdjustmentSnapshotRespVO`（入参为 path 变量 + query，无独立 ReqVO）
+
+#### 使用场景
+
+管理后台打开「调整订单」弹窗时调用一次，一次性拉取各子领域当前值用于回显。本次相关的是「车辆安排」页：需要知道（a）接送机不用声明的当前值，（b）两个方向**是否已有大交通批次**——后者决定前端要不要渲染「不用接送机」的必选确认。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| id | Path | Long | ✅ | 订单雪花 ID（**字符串传输，别转 Number**） | 订单 ID |
+| scope | Query | String | ❌ | 逗号分隔：`BASIC`/`PEOPLE`/`SCHEDULE`/`ITINERARY`/`HOTEL_REQ`/`VEHICLE_REQ`；任一 token 非法返 587003 | 限定返回子领域；不传返全部。**传了但不含 `VEHICLE_REQ` 时，本次两个新字段不返回** |
+
+#### 出参 `Result<AdjustmentSnapshotRespVO>`
+
+本次**新增**字段（其余字段结构与取值规则一律不变）：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `transferDeclaration.pickupNotRequired` | Boolean | **新增**。接机方向是否已声明「本单不用接机」。**未声明返回 `false`**（不是 null） |
+| `transferDeclaration.dropoffNotRequired` | Boolean | **新增**。送机方向是否已声明「本单不用送机」。未声明返回 `false` |
+| `transferTransportPresent.pickup` | Boolean | **新增**。接机方向**是否已存在大交通批次**。`true` 时该方向不需要「不用接送机」确认，且声明对它不生效 |
+| `transferTransportPresent.dropoff` | Boolean | **新增**。送机方向是否已存在大交通批次 |
+
+其余字段（`vehicleRequirement` / `transferRequirement` / `vehicleTransportSummary` / `basic` 等）**结构与取值均未变**。
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/2101219133700952066/adjustment/snapshot?scope=VEHICLE_REQ
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "vehicleRequirement": { "...": "结构未变，略" },
+    "transferRequirement": null,
+    "vehicleTransportSummary": {
+      "hasPickupTime": false,
+      "displayText": null,
+      "emptyText": "暂无接送机时间",
+      "arrivals": [],
+      "departures": []
+    },
+    "transferDeclaration": { "pickupNotRequired": false, "dropoffNotRequired": false },
+    "transferTransportPresent": { "pickup": false, "dropoff": false }
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+- 订单没有大交通批次：`vehicleTransportSummary.hasPickupTime=false`、`emptyText="暂无接送机时间"`、`arrivals/departures` 均为 `[]`；`transferTransportPresent` 两个方向都是 `false`。**这是正常态，不是降级**。
+- 订单从未表过态：`transferDeclaration` 两个字段都是 `false`（表示「未声明」，不是「声明了需要」）。
+- **老订单 / 存量数据**：两列默认 0，读出来与「从未表态」完全一致，不会异常。
+- `scope` 不含 `VEHICLE_REQ`：本组三个字段（含本次两个）整体不返回。
+
+#### 错误响应
+
+```json
+{ "code": 587003, "message": "调整范围取值非法", "data": null, "success": false }
+```
+
+#### 业务边界
+
+- 只读接口，无副作用；不因订单状态（已出行、已结算）而拒绝。
+- `transferTransportPresent` 判的是「该方向有没有大交通批次」，**不看**批次的 `pickupRequired`；与提交闸、车务读侧回落同一句判据。
+- 订单 ID 传错/不存在 → 既有 581007「订单不存在」，本次未改。
+
+---
+
+### 2. 调整订单统一提交 `POST /v3/admin/order/{id}/adjustment/submit`
+
+**VO**: `AdjustmentSubmitReqVO` → `AdjustmentSubmitRespVO`
+
+#### 使用场景
+
+「调整订单」弹窗内收集齐所有子领域改动后一次性提交；「车辆安排」页保存行程用车 / 接送机用车需求、以及本次新增的接送机不用声明，都走这一个入口。单事务原子应用：任一步失败整笔回滚。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| id | Path | Long | ✅ | 订单雪花 ID | 订单 ID |
+| `updates` | Body | Object | ✅ | 各子领域容器，不可全 null | 未改的子领域置 null |
+| `updates.transferDeclaration` | Body | Object | ❌ | **本次新增** | 接送机不用声明，见下 |
+| `updates.transferDeclaration.pickupNotRequired` | Body | Boolean | ❌ | `true`=本单不用接机；`false`=需要（或撤销声明） | 接机方向表态 |
+| `updates.transferDeclaration.dropoffNotRequired` | Body | Boolean | ❌ | `true`=本单不用送机 | 送机方向表态 |
+| `updates.vehicleRequirement` | Body | Object | ❌ | 结构未变（`fleet` 为空数组按「未提交」处理） | 行程用车需求 |
+| `updates.transferRequirement` | Body | Object | ❌ | 结构未变；服务日由服务端派生 | 接送机用车需求 |
+| 其余 `updates.*` | Body | Object | ❌ | 全部未变 | 出行人 / 改期 / 行程 / 房需求 |
+
+#### 出参 `Result<AdjustmentSubmitRespVO>`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `success` | Boolean | 恒 `true`（失败走错误码） |
+
+结构未变。
+
+#### 请求示例
+
+无大交通、只提交行程用车、**不带声明**（会被拒，用于说明闸的位置）：
+
+```json
+{
+  "updates": {
+    "vehicleRequirement": {
+      "specialTags": [],
+      "remark": "按原方案",
+      "fleet": [ { "vehicleType": "SUV系列", "seats": 5, "count": 1 } ]
+    }
+  }
+}
+```
+
+两个方向都确认「不用」：**这是无大交通时唯一能被接受的形态**
+
+```json
+{
+  "updates": {
+    "vehicleRequirement": {
+      "specialTags": [],
+      "remark": "按原方案",
+      "fleet": [ { "vehicleType": "SUV系列", "seats": 5, "count": 1 } ]
+    },
+    "transferDeclaration": { "pickupNotRequired": true, "dropoffNotRequired": true }
+  }
+}
+```
+
+只改声明、不动其他子领域（有效提交，不会被 587033 拦）：
+
+```json
+{ "updates": { "transferDeclaration": { "pickupNotRequired": true, "dropoffNotRequired": false } } }
+```
+
+#### 响应示例
+
+```json
+{ "code": 0, "message": "success", "data": { "success": true }, "success": true }
+```
+
+#### 空数据 / 降级响应
+
+- `updates.transferDeclaration` 传空对象 `{}`（两个字段都 null）或整体不传：按「本次没对车辆子领域表态」处理，**不触发 587044**。
+- 散客单（无 `productBatchId`）传了 `transferDeclaration`：**不写入、不报错**，静默忽略。
+- 该方向已有大交通批次时传了声明：**不写入、不报错**，接送要求仍按批次 `pickupRequired` 判。
+
+#### 错误响应
+
+```json
+{ "code": 587044, "message": "本单未录入大交通，请先确认「不用接机」，或先在大交通模块录入行程后再提交", "data": null, "success": false }
+```
+
+（方向占位符取「接机」或「送机」，两个方向各自判定，只报先撞上的那一个。）
+
+```json
+{ "code": 587033, "message": "未检测到有效变更，无需提交", "data": null, "success": false }
+```
+
+#### 业务边界
+
+- **只对团期子订单生效**：散客单行为与本次之前逐字相同。
+- **只在本次提交真的带了车辆子领域有效载荷时判定**：非空 `fleet`、或 `transferDeclaration` 任一方向非 null。改房务、改行程、加出行人、改期这些提交**不会被 587044 拦**。
+- **整笔零写入**：587044 与其它守卫一样在任何 DB 写之前抛出，不存在「声明写了、需求没写」的半截状态。
+- **覆盖写 + 值级 no-op**：字段为 null 表示「本次不动这个方向」；两个方向的值与现值都相同时不写库、不产调整记录项。
+- **两个方向独立**：可以只声明接机不用、送机照旧（送机若已补录大交通则不受影响）。
+- 幂等/并发：沿用本接口既有的订单级锁与「提交期间订单被改」守卫（587043），本次未改。
+
+---
+
+## 四、契约约束与正确调用方式
+
+> 本节只写**后端接受 / 拒绝 payload 的规则**。
+
+### ✅ 正确 / ❌ 错误 payload 对照
+
+前提：订单是**团期子订单**，且两个方向**都没有大交通批次**。
+
+| 场景 | payload | 结果 |
+|---|---|---|
+| ✅ 只提交行程用车 + 两个方向都确认不用 | `{"updates":{"vehicleRequirement":{"fleet":[{"vehicleType":"SUV系列","seats":5,"count":1}]},"transferDeclaration":{"pickupNotRequired":true,"dropoffNotRequired":true}}}` | 200 |
+| ✅ 只提交声明（不动车辆） | `{"updates":{"transferDeclaration":{"pickupNotRequired":true,"dropoffNotRequired":true}}}` | 200 |
+| ❌ 只提交行程用车、不带声明 | `{"updates":{"vehicleRequirement":{"fleet":[...]}}}` | **587044** |
+| ❌ 只声明了一个方向（另一个方向无批次） | `{"updates":{"vehicleRequirement":{"fleet":[...]},"transferDeclaration":{"pickupNotRequired":true,"dropoffNotRequired":null}}}` | **587044**（报「送机」） |
+| ✅ 改房务 / 改行程 / 改期（**完全不带车辆子领域字段**） | `{"updates":{"hotelRequirement":{...}}}` | 200（不判 587044） |
+| ⚠️ 混方向：接机**有**批次、送机**没有** | `{"updates":{"transferRequirement":{"fleet":[...]}}}`（未声明送机） | **587044**——即便接送机需求能派生出服务日也一样拦，防「带着没表过态的方向落库」 |
+| ✅ 散客单不带声明 | `{"updates":{"vehicleRequirement":{"fleet":[...]}}}` | 200（散客单不判） |
+| ✅ 该方向已有大交通批次 | 传或不传声明 | 200，声明不生效 |
+
+### 切换状态时的必要动作
+
+- `transferDeclaration` 是**逐方向覆盖写**：只传想动的方向，另一个方向传 `null` 或干脆不传（**不要**因为「表单里没这个控件」就传 `false`，那会被当成「本方向需要接送机」，在无批次时被 587044 拒绝）。
+- **未进入 / 未编辑「车辆安排」页时，整个 `transferDeclaration` 都不要回传**（连空对象也建议不传）——只要出现 `true`/`false` 就视为对车辆子领域表态。
+- 需要接送机时不要试图用声明绕过：接送机用车需求的服务日只能来自大交通，先录大交通。
+- **判据只看本次请求体，不回看库里已存的声明**：某方向无大交通时，本次提交**必须带上该方向的表态**。前端如果只回传「变化过的字段」（例如只带 `transferRequirement`），即使客人此前已勾过「不用接送机」也会被 587044 挡住。**正确做法：车辆安排页每次提交都把 `transferDeclaration` 按当前控件状态整份回传。**
+
+---
+
+## 五、数据库行为
+
+涉及写操作：`order_main` 新增两列，语义为「该方向**已显式声明不用接送机**」。
+
+| 前端提交 `updates.transferDeclaration` | `pickup_not_required` 列 | `dropoff_not_required` 列 |
+|---|---|---|
+| `{"pickupNotRequired":true,"dropoffNotRequired":true}` | `1` | `1` |
+| `{"pickupNotRequired":true,"dropoffNotRequired":null}` | `1` | 保持原值（不动） |
+| `{"pickupNotRequired":false,"dropoffNotRequired":false}` | `0` | `0` |
+| 不传 / 空对象 | 保持原值 | 保持原值 |
+
+- 列类型 `TINYINT(1) NOT NULL DEFAULT 0`；**存量数据不做任何回填**，全部为 0（未声明）。
+- 该方向**已有大交通批次**时即使传了 `true` 也**不写库**（声明对该方向不生效）。
+- 提交成功时同时写一条调整记录项（类型为车辆需求类，文案「接送机不用声明已更新」，带方向的中文前后值）。
+
+---
+
+## 六、边界行为
+
+- 未登录 / 无权限 → 网关拦截（401/403），本次未改。
+- 订单不存在 → 既有 581007。
+- 订单已是终态 → 既有 587002「订单已是终态，不可调整」。
+- 提交期间订单被并发改动 → 既有 587043，重新拉取后重试。
+- 老前端（不认识这两个新字段、也不回传 `transferDeclaration`）：**团期子订单只要提交车辆子领域就会被 587044 拦住**——这是有意的硬闸，前端必须同步上线。
+- 老数据兼容：存量订单两列为 0，读侧与「从未表态」一致；车务侧该方向仍显示「待补」，不会被静默读成「无需接送」。
+- 大交通批次 `direction` 为空的历史行：与订单侧既有的方向切分口径一致（该行不归入任何方向）。
+
+---
+
+## 六.5、枚举 / 数据字典
+
+### 接送机 readiness（车务读侧）
+
+**所属字段**: 车务看板 / 配车页 `readiness.statusCode`（本次**未改路径与结构**，仅取值可能变化）
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `NOT_REQUIRED` | 无需接客 / 无需送客 | 该方向**有**大交通批次且批次 `pickupRequired=false`，**或**该方向无批次但订单已声明「不用接送机」 |
+| `MISSING` | 待补接客信息 / 待补送客信息 | 该方向需要接送但信息不齐；**无大交通且未声明也算这一档**（fail-closed） |
+| `PARTIAL` | 接客/送客信息部分缺失 | 有多条批次，部分缺时刻或站点 |
+| `READY` | 接客/送客信息已齐 | 全部批次时刻与站点齐全 |
+| `SOURCE_UNAVAILABLE` | 订单信息暂不可用 | 订单上下文取数失败（降级态） |
+
+---
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 |
+|---|---|---|
+| snapshot 出参 `transferDeclaration` | 不存在 | `{pickupNotRequired:Boolean, dropoffNotRequired:Boolean}`，未声明为 `false` |
+| snapshot 出参 `transferTransportPresent` | 不存在 | `{pickup:Boolean, dropoff:Boolean}` |
+| submit 入参 `updates.transferDeclaration` | 不存在 | 新增，两个方向可选 |
+| `updates` 其余字段 / 出参结构 | - | 未变 |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|---|---|---|
+| 团期子订单无大交通、只提交行程用车 | 200，接送机不留任何结论 | **587044**，整笔零写入 |
+| 团期子订单无大交通、确认两个方向不用后提交 | 无此路径 | 200，订单落两列声明 |
+| 车务侧某方向（无大交通） | 恒「待补接客信息 / 待补送客信息」 | 已声明 ⇒「无需接客 / 无需送客」；未声明仍「待补」 |
+| 车务侧某方向（有大交通批次） | 按批次 `pickupRequired` 判 | **不变** |
+| 散客单 | - | **完全不变** |
+| 809002 / 809009 | 接送机用车需求的服务日与开关校验 | **触发条件均未改**（但无大交通且未表态时，会先撞 587044） |
+
+---
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 否（纯新增字段；但**行为上对团期子订单是硬闸**——老前端提交车辆子领域会撞 587044）
+- **前端是否必须同步上线**: **是**（团期子订单的「车辆安排」页必须按 `transferTransportPresent` 渲染必选确认并回传 `transferDeclaration`）
+- **前端 workaround 清理点**: 无
+
+---
+
+## 六.8、已知约束（实测确认，非缺陷，但前端要知道）
+
+1. **声明的撤销只在「该方向已有大交通批次」时可达**。该方向一条批次都没有时，把声明清回 `false` 会被 587044 拒绝（实测：两方向都清 `false` → 587044「不用接机」；只清送机、接机留 `true` → 587044「不用送机」）。要改回「需要接送机」，先录该方向的大交通——这也是接送机服务能落地的必经步骤。
+2. **团期子订单的用车需求提交后是「待审核」，不即时进车务池**：需由团期管理员执行提交车务动作后才会出现在车务看板。这不是本版引入的行为，但会影响「提交完立刻看车务看板」的验收动作。
+3. 大交通批次新增接口有 3 秒幂等窗口，同一订单连续两次新增会返回 100502「大交通批次新增处理中」，与本次改动无关。
+
+---
+
+## 七、不影响范围
+
+- **仅影响**: 管理后台「订单详情 → 调整订单 → 车辆安排」的团期子订单提交路径；以及车务侧接送机 readiness 的取值。
+- **零影响**:
+  - 散客单（无 `productBatchId`）的一切调整行为
+  - 「调整订单」的其余 tab（出行人 / 改期 / 行程 / 房需求）
+  - 接送机用车需求（TRANSFER）的服务日派生、提交开关、809002 / 809009 的触发条件
+  - 大交通模块自身的读写接口
+  - 行程单 / H5 / 小程序
+  - 网关路由（无新增，均在既有 `/v3/admin/**` 通配下）
+  - 历史数据（存量两列为 0，不迁移）
+
+---
+
+## 八、测试环境已验证
+
+被测服务 `hl-order-service-v3`：`dev-v3 @ bc197bc07`，`deploy-status.sh` 回读 `BEHIND 0/N`、`STATE ok`。
+
+```
+被测服务部署：`hl-order-service-v3` = `dev-v3 @ bc197bc07`，`BEHIND 0/N`、`STATE ok`。
+网关 `hl-gateway` 本次无路由改动；`hl-fleet-service` 现网版本虽落后若干提交，但落后的提交全是 order-v3 的、
+未触及 fleet 代码，其接送就绪态判据与本次工作树逐字相同，故车务读口读数有效。
+
+实测用**自建的团期子订单测试单**（客户备注带 `HLTEST[8320]` 标记，未碰任何真实订单）：
+
+```text
+① 无大交通 + 不带 transferDeclaration 提交行程用车
+   POST /v3/admin/order/{orderId}/adjustment/submit → HTTP 200，code=587044
+   "本单未录入大交通，请先确认「不用接机」，或先在大交通模块录入行程后再提交"          ✓
+   零写入核对（提交前后同一次 SQL 快照逐项相等）：
+     order_main 两列仍为 0 / order_vehicle_requirement 无新版本 /
+     order_transport_plan 无变化 / order_adjustment_record 空 / order_status_log 计数不变 ✓
+
+② 同一 payload + transferDeclaration={pickupNotRequired:true,dropoffNotRequired:true}
+   POST .../adjustment/submit → {"code":200,"data":{"success":true}}                     ✓
+   GET  .../adjustment/snapshot?scope=VEHICLE_REQ
+     "transferDeclaration":{"pickupNotRequired":true,"dropoffNotRequired":true}
+     "transferTransportPresent":{"pickup":false,"dropoff":false}                         ✓
+   order_main: pickup_not_required=1 dropoff_not_required=1                              ✓
+   order_adjustment_record: label="接送机不用声明已更新"
+     before="接机：需要接送，送机：需要接送" after="接机：不用接送，送机：不用接送"        ✓
+
+③ 给该方向补一条 ARRIVAL 大交通批次后再提交（仍带声明 true）
+     snapshot "transferTransportPresent":{"pickup":true,"dropoff":false}                 ✓
+     车务读侧 pickupSummary: required=true, statusCode=READY, "接客信息已齐"             ✓（声明不覆盖批次）
+
+④ 车务读侧阳性 + 阴性对照（同一张单、同一时刻，两个方向都没有批次）
+     pickupSummary  : 未声明(0)     → required=true,  statusCode=MISSING,       "待补接客信息" ✓
+     dropoffSummary : 已声明不用(1) → required=false, statusCode=NOT_REQUIRED,  "无需送客"     ✓
+
+⑤ 混方向：接机有批次、送机无批次，提交非空 transferRequirement 且不声明送机
+   → code=587044 "…请先确认「不用送机」…"，整笔零写入                                  ✓
+
+⑥ 散客单（productBatchId=null）不带声明提交同一份用车需求
+   → {"code":200,"data":{"success":true}}，正常落库；snapshot transferDeclaration={false,false} ✓
+```
+
+（车务读侧入口：管理端 `GET /admin/fleet/board/orders`——fleet 管理端路径**没有 `/v3` 前缀**；
+`/v3/internal/**` 经网关直连返 403 属设计内，未作为证据。）
+```
+
+---
+
+## 九、相关历史 PR
+
+| PR | Issue | 说明 | 是否仍有效 |
+|----|-------|------|------------|
+| #8024 | #7443 | 调整订单车辆安排页同页提交行程用车 + 接送机用车两类需求 | ✅ 有效，本版在其上加闸 |
+| #7439 | #7439 | 用车需求分家（TRAVEL / TRANSFER），接送机服务日由大交通派生 | ✅ 有效 |
+| #8153 | #8153 | 声明了接送机却无 TRANSFER 需求行的户在确认预检里报出 | ✅ 有效 |
+| **本 PR #8326** | **#8320** | 补「不需要接送机」这一侧的显式声明 + 提交闸 | ✅ 最新 |
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#8320](https://git.1814.love/wx/HL/issues/8320)
+- 关联 PR: [wx/HL#8326](https://git.1814.love/wx/HL/pulls/8326)
+- 团期车务实施单: `HL-v3/docs/group/实施单/06-团期车务.html`（接送机 readiness 口径本次补了一句）
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8320](https://git.1814.love/wx/HL/issues/8320)
+- **PR**: [#8326](https://git.1814.love/wx/HL/pulls/8326)
+- **Merge commit**: [bc197bc07](https://git.1814.love/wx/HL/commit/bc197bc07)
+
+### 联系人
+
+- **后端负责人**: @wx
@@ -0,0 +1,338 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8322"
+title: "团期预支核单前均可发起（放开招募中）+ 领款人限定为本团主报账人（新码 589557）；一并补 #8270 放宽说明"
+consumer: "admin"
+author: "jw(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "0ba1a2732022c800b2cee0711f1ed052b5e19dad"
+target_release: "v2.1"
+verified_at: "2026-09-24"
+status_note: "jw 2026-09-24 定两条口径：① 只要在核单前都可以发起团期预支，允许状态在 #8270（资源准备中起）基础上补招募中；② 团期预支由主报账人申领，领款人限定为本团 reporter_rank=PRIMARY 的那一人，在本团但不是主报账人（含本团未设主报账人）返新码 589557，不在本团仍 585007；领款人候选接口只返回主报账人一条，未设主报账人返回空列表。#8270（2026-09-23 合入，资源准备中放开、四项配齐门 589542 不再返回）当时未推 changelog，本条一并说明。PR #8323 已合 dev-v3（980429ac2）并部署 TEST，2026-09-24 11:47~11:49 经真实网关实测：招募中团期主报账人提交 200/SUBMITTED 落库 1 行；普通人员、次报账人、未设主报账人三种情况各返 589557 且零写入；不在本团返 585007；招募中超池返 585004；核单中、已流团团期各返 589541；候选接口部署前同一团返回 2 人、部署后只返回主报账人。前端侧：候选下拉条数变为 0 或 1，招募中与资源准备中的预支按钮若按旧规则置灰需放开，589557 需给出文案，故 frontend_status 记 pending。 | 2026-09-24 mmg 交付:FinanceTab 阶段门白名单 3 态放宽到 6 态(RECRUITING~TRIP_FINISHED,核单中/已结算/流团置灰+tooltip),GroupAdvanceModal 空候选引导改「请先在团期人员配置中设置主报账人」(提交必然 589557 故禁用),589557 无按码分支拦截器透后端文案即引导;JSDoc/注释按 #8322+#7154 订正(589538/589539→589541,589542 删除);FinanceTab spec 11 例+新建 GroupAdvanceModal spec 2 例全绿"
+updated_at: "2026-09-24"
+base: "dev-v3"
+---
+
+# 团期预支：核单前均可发起 + 领款人限定为主报账人（管理后台）
+
+> **服务**: hl-order-service-v3（端口 8086/8186）
+> **PR**: #8323（本单）、#8272（#8270，一并补说明）
+> **Issue**: #8322、#8270
+> **日期**: 2026-09-24
+> **影响范围**: 管理后台团期详情页「财务」tab 的「发起预支」弹窗（领款人下拉、提交按钮可用状态、错误提示）
+
+---
+
+## ⚠️ 关键变化
+
+本次是**行为变更**，三条都与前端此前的预期不同：
+
+1. **可发起预支的团期状态扩大**。#8270 之前只有物料准备中至出行完毕可提，且要求房 / 车 / 导 / 摄四项配齐；#8270 起资源准备中可提、四项配齐门删除；**本单起招募中也可提**。现在的规则是：**进入核单之前都可以发起**，核单中 / 已结算 / 已流团仍返 `589541`。
+2. **领款人只能是本团主报账人**。以前本团任一已配人员都能当领款人；现在在本团但不是主报账人的（次报账人、普通人员、本团还没设主报账人）一律返新码 **`589557`**。不在本团仍是 `585007`。
+3. **领款人候选只返回主报账人一条**。以前返回本团全部人员、主报账人排首；现在只返回主报账人，**本团未设主报账人时返回空列表**。前端下拉要能处理 0 条（提示去团期人员配置里设主报账人）。
+
+---
+
+## 一、背景
+
+团期预支复用订单预支 `order_advance`（#7154，`scope=GROUP_BATCH`）。本期 wx 在做团期主报账人功能，由主报账人发起预支申领，jw 2026-09-24 据此定：领款人限定为本团主报账人；同时预支入口前移到招募中，只要团期还没进核单都可以发起。
+
+主报账人在团期人员配置里设置（`PUT /v3/admin/group-batch/{productBatchId}/staff/{staffId}/reporter-rank`），招募中、资源准备中可设，确认后锁定（#8231 / #8269）。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|---|---|---|---|---|
+| 1 | 发起团期预支（GB-ADM-042） | POST | `/v3/admin/order/group-batch/{groupBatchId}/advance` | 修改 | 允许状态补招募中；领款人须为本团主报账人，否则新码 589557；#8270 起资源准备中可提、589542 不再返回 |
+| 2 | 团期预支领款人候选 | GET | `/v3/admin/order/group-batch/{groupBatchId}/advance/payee-candidates` | 修改 | 只返回主报账人一条；未设主报账人返回空列表 |
+
+---
+
+## 三、接口详情
+
+### 1. 发起团期预支 `POST /v3/admin/order/group-batch/{groupBatchId}/advance`
+
+**VO**: `CreateGroupBatchAdvanceReqVO` → `OrderAdvanceRespVO`
+
+#### 使用场景
+
+团期详情页「财务」tab 点「发起预支」，选领款人（主报账人）、借款类型、金额后提交，创建一条团期级预支单，直接进入站内财务待审批（`SUBMITTED`）。入参与出参结构均未改，变的是允许状态与领款人校验。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| groupBatchId | path | Long | 是 | 运营团期 ID | 订单侧团期 ID |
+| payeeStaffId | body | Long | 是 | **须为本团主报账人的 staffId** | 取候选接口返回的 `id`；非主报账人返 589557 |
+| advanceType | body | String | 是 | 字典 `advance_type` | 借款类型，如 `TICKET` |
+| amount | body | BigDecimal | 是 | ≥ 0.01，且 ≤ 团期统一池可用余额 | 超额返 585004 |
+| purpose | body | String | 否 | ≤ 255 字 | 用途说明 |
+| voucherUrl | body | String | 否 | ≤ 512 字符 | 凭证 URL |
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | Long(String) | 预支单 ID |
+| orderId | Long | 团期级预支恒为 null |
+| payeeStaffId | Long(String) | 领款人 staffId（即主报账人） |
+| payeeName | String | 领款人姓名快照 |
+| payeeRole / payeeRoleText | String | 领款人角色及中文 |
+| advanceType | String | 借款类型 |
+| amount | BigDecimal | 预支金额 |
+| purpose | String | 用途说明 |
+| status / statusText | String | 创建后恒为 `SUBMITTED` / 「待审批」 |
+| createdByName | String | 发起人 |
+| createTime / submittedAt | String | 创建 / 提交时间 |
+
+#### 请求示例
+
+```http
+POST /v3/admin/order/group-batch/2102967993891979266/advance
+Authorization: Bearer <admin token>
+Content-Type: application/json
+
+{
+  "payeeStaffId": 1002,
+  "advanceType": "TICKET",
+  "amount": 100,
+  "purpose": "门票备用金"
+}
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "id": "2102968264214872066",
+    "orderId": null,
+    "payeeStaffId": "1002",
+    "payeeName": "李雪梅",
+    "payeeRole": "GUIDE",
+    "payeeRoleText": "GUIDE",
+    "advanceType": "TICKET",
+    "amount": 100,
+    "purpose": "门票备用金",
+    "voucherUrl": null,
+    "status": "SUBMITTED",
+    "statusText": "待审批",
+    "rejectReason": null,
+    "createdByName": "admin",
+    "createTime": "2026-09-24 11:48:00",
+    "submittedAt": "2026-09-24 11:48:00",
+    "approvedAt": null,
+    "approvedBy": null
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+写接口，无空数据形态。校验不通过时不落库，返回下方错误码之一。
+
+#### 错误响应
+
+| code | 触发条件 | 前端建议 |
+|---|---|---|
+| `589557` | **新增**。领款人在本团，但不是主报账人（次报账人 / 普通人员），或本团还没设主报账人 | 提示「请先在团期人员配置中设置主报账人」，引导去配人 |
+| `585007` | 领款人不在本团人员名单里 | 同前，刷新候选 |
+| `589541` | 团期处于核单中 / 已结算 / 已流团；**文案改为「当前团期状态不可发起预支（进入核单后关闭）」** | 隐藏或置灰「发起预支」 |
+| `585004` | 金额超过团期统一池可用余额 | 提示可用余额（财务面板 `advanceAvailable`） |
+| `589542` | **#8270 起不再返回**（四项配齐门已删除，码位保留不复用） | 前端若有针对它的分支可删除 |
+
+```json
+{
+  "code": 589557,
+  "message": "领款人须为本团主报账人，请先在团期人员配置中设置主报账人",
+  "data": null,
+  "success": false
+}
+```
+
+#### 业务边界
+
+- 允许状态：招募中、资源准备中、物料准备中、待出发、出行中、出行完毕；核单中 / 已结算 / 已流团拒绝。
+- 校验顺序：团期状态（589541）→ 领款人在本团（585007）→ 领款人是主报账人（589557）→ 借款类型 → 金额上限（585004）。
+- 上限规则不变：团期级与各子订单级预支共用一个团期尾款池。
+- 只影响团期级预支；订单级预支（`POST /v3/admin/order/{orderId}/advance`）的领款人规则不变。
+
+### 2. 团期预支领款人候选 `GET /v3/admin/order/group-batch/{groupBatchId}/advance/payee-candidates`
+
+**VO**: `List<AdvancePayeeCandidateVO>`
+
+#### 使用场景
+
+「发起预支」弹窗打开时拉取领款人下拉。本单起只会返回主报账人一条，前端可直接默认选中；返回空列表说明本团还没设主报账人。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| groupBatchId | path | Long | 是 | 运营团期 ID | 订单侧团期 ID，服务端内部换算产品侧排期 |
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | Long(String) | 资源域 staffId，即发起预支的 `payeeStaffId` |
+| staffName | String | 姓名 |
+| staffRole / staffRoleText | String | 角色及中文 |
+| reporterRank | String | 恒为 `PRIMARY` |
+| isDefault | Boolean | 恒为 `true` |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch/2102967993891979266/advance/payee-candidates
+Authorization: Bearer <admin token>
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": [
+    {
+      "id": "1002",
+      "staffName": "李雪梅",
+      "staffRole": "GUIDE",
+      "staffRoleText": "GUIDE",
+      "reporterRank": "PRIMARY",
+      "isDefault": true
+    }
+  ],
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+本团未配人员，或配了人但没设主报账人，返回空列表：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": [],
+  "success": true
+}
+```
+
+#### 错误响应
+
+判权与团期存在性校验未改动。
+
+```json
+{
+  "code": 589500,
+  "message": "团期不存在",
+  "data": null,
+  "success": false
+}
+```
+
+#### 业务边界
+
+- 条数只会是 0 或 1；不再返回次报账人与普通人员，也不再排序。
+- 字段结构不变，前端按字段取值的代码不用改。
+
+---
+
+## 四、契约约束与正确调用方式
+
+- 发起预支的 `payeeStaffId` 一律取候选接口返回的那一条，不要从团期人员列表里自己挑。
+- 候选为空时不要让用户提交（必然 589557），提示去团期人员配置里设置主报账人。
+- 「发起预支」按钮的可用状态按团期状态判断：进入核单（`REVIEWING`）之前都可用，不再要求四项资源配齐。
+
+---
+
+## 五、数据库行为
+
+- 零表结构变更、零迁移脚本。
+- 发起预支成功时照旧向 `order_advance` 写一行（`scope=GROUP_BATCH`、`order_id=NULL`、`payee_ref_type=BATCH_STAFF`）；任何校验失败零写入（TEST 实测前后计数一致）。
+- 主报账人读自团期人员配置 `order_batch_staff.reporter_rank`，只读不写。
+
+---
+
+## 六、边界行为
+
+- 主报账人在确认后锁定；取消成团（资源准备中 → 招募中）会回收导摄配置，主报账人可能随之被清掉，此时候选为空、发起预支返 589557，需重新配置。
+- 已发起的预支保存领款人快照，事后主报账人变更不影响已有单据。
+
+---
+
+## 六.6、修改前后对比
+
+| 项 | #8270 之前 | #8270（09-23） | 本单（09-24） |
+|---|---|---|---|
+| 可发起状态 | 物料准备中 ~ 出行完毕 | 资源准备中 ~ 出行完毕 | **招募中 ~ 出行完毕** |
+| 四项配齐门 | 要求，否则 589542 | 删除，589542 不再返回 | 同 #8270 |
+| 领款人 | 本团任一已配人员 | 同左 | **仅本团主报账人，否则 589557** |
+| 候选接口 | 本团全部人员，主报账人排首 | 同左 | **仅主报账人一条 / 空列表** |
+| 589541 文案 | 列出允许状态区间 | 同左 | 「当前团期状态不可发起预支（进入核单后关闭）」 |
+
+---
+
+## 六.7、影响评估
+
+- 前端：候选下拉要处理 0 条；「发起预支」按钮若仍按旧规则（四项配齐 / 物料准备中起）置灰，需放开到核单前；新增 589557 文案。不改的话，功能按旧规则被前端挡住，但后端不会出错。
+- 已有数据：不回填、不改存量预支单。
+- 订单级预支、审批中心、结算核单均不受影响。
+
+---
+
+## 七、不影响范围
+
+- 订单级预支 6 个端点（`/v3/admin/order/{orderId}/advance*`、审批中心列表、通过 / 驳回）。
+- 团期财务总览 `GET /v3/admin/order/group-batch/{groupBatchId}/finance`、团期预支记录 `GET .../advances`。
+- 团期人员配置与报账人等级接口。
+
+---
+
+## 八、测试环境已验证
+
+部署 dev-v3 @ `980429ac2`（含 PR #8323）到 TEST 后，2026-09-24 11:47~11:49 经真实网关 `https://api.test.1814.love` 实测（自造招募中团期 `2102967993891979266`，四项资源全未配，主报账人 1002、另配摄影 1003）：
+
+| 用例 | 期望 | 实测 |
+|---|---|---|
+| 构建身份：样本团 `2100509904627191810` 候选接口 | 部署前 2 人 → 部署后仅主报账人 | 部署前 `[1002, 1003]`，部署后 6 次均 `[1002]` |
+| 候选接口（有主报账人） | 仅 1002，`isDefault=true` | 通过 |
+| 招募中 + 主报账人 1002 提交 100 | 200，`SUBMITTED`，落库 1 行 | 通过，`order_advance` 0→1 |
+| 领款人 1003（普通人员） | 589557，零写入 | 通过 |
+| 领款人 1003（设为次报账人后） | 589557，零写入 | 通过 |
+| 撤掉主报账人后候选 / 提交 | 候选 `[]`；提交 589557 | 通过 |
+| 领款人 1005（不在本团） | 585007 | 通过 |
+| 招募中提交 6000（池 5400） | 585004 | 通过 |
+| 核单中团期 `2100891433836675073` | 589541（新文案） | 通过 |
+| 已流团团期 `2102949787102076929` | 589541 | 通过 |
+| 不带 token | 401 | 通过 |
+
+造数已清理：预支单驳回、订单取消、产品侧班期取消。
+
+---
+
+## 十、相关文档
+
+- Issue #8322、PR #8323；#8270 / PR #8272
+- 团期预支复用订单预支：`changelogs-v2/2026-09/06_7154_团期财务总览与预支复用订单预支-新增接口-管理后台.md`
+- 报账人等级：`changelogs-v2/2026-09/23_8231_配导游配摄影物资放开到出行前四态-修改接口-管理后台.md`
+
+---
+
+## 关联 / 联系人
+
+- 后端：jw
+- 前端：mmg
+- 团期主报账人功能：wx
--- a/显示更多
+++ b/显示更多