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: "f6b849eb"
-target_release: ""
+target_release: "hl-ui@f6b849eb"
 verified_at: "2026-09-02"
 status_note: "regionText 由上游 product-v2 提供后透传，当前测试环境返回 null 属预期；001 排序保持 create_time DESC 未变（depart_date ASC 变更待 wx 确认）；#6929 已实现：003 totalPrice 应收字段 + birthdayInTrip 跨年修正（详见 §十一）"
-updated_at: "2026-09-04"
+updated_at: "2026-09-20"
 base: "dev-v3"
 ---

@@ -278,8 +278,8 @@ GET /v3/admin/order/group-batch/<groupBatchId>

 | 字段 | 类型 | 说明 |
 |------|------|------|
-| estimatedCost | BigDecimal | 估算成本（无成本数据可 null） |
-| totalPrice | BigDecimal(字符串) | 本户应收 = orderAmount + surchargeAmount − discountAmount（下限 0，`OrderAmountUtil.payableForDisplay` 口径；**取消单返 "0.00"**，#7097 已补两位小数）；预计毛利 = totalPrice − estimatedCost（#6929） |
+| ~~estimatedCost~~ | ~~BigDecimal~~ | 🔴 **2026-09-20 订正：该字段恒为 `null`，且已于 #7536 从 003 出参删除。**原说明「估算成本（无成本数据可 null）」会让人以为只是暂时没数据——**实际是从未有过数据**。实测 `origin/dev-v3`：`setEstimatedCost` 与 `getEstimatedCost` 在 main 代码里**各 0 命中**，字段名在整个 Java 侧只出现在实体 `OrderInfo.java` 自身的声明里，其余全是 docs 与建表 DDL （`V20260511_001__init_core_tables.sql:83` 等）⇒ **`order_main.estimated_cost` 全仓零写入点**。逐户毛利的现行宿主见下方订正条。 |
+| totalPrice | BigDecimal(字符串) | 本户应收 = orderAmount + surchargeAmount − discountAmount（下限 0，`OrderAmountUtil.payableForDisplay` 口径；**取消单返 "0.00"**，#7097 已补两位小数）；~~预计毛利 = totalPrice − estimatedCost（#6929）~~ 🔴 **2026-09-20 订正：此式不成立**，`estimatedCost` 恒 null（见上行），任何时点都算不出来。毛利改用核团接口，见「联调口径」第 4 条。 |
 | tierCode/tierName | String | tier 组合（成人A/儿童C/幼童Y/婴儿B，如 2A1C→"2成人1儿童"；全零→null，映射表待 wx 确认） |
 | participantCount | Integer | 人数聚合（adult+child+youngChild+baby） |
 | youngChildCount/babyCount | Integer | 幼童/婴儿数 |
@@ -387,7 +387,7 @@ GET /v3/admin/order/group-batch/<groupBatchId>/orders?includeTravelers=true&incl
 | 001 | chips/orderCount | 无 | 六芯片聚合/批量计数 |
 | 002 | totalReceivable/totalReceived | 实体快照 | sumBatchAmounts 实时聚合(非恒 0) |
 | 002 | primaryReporter | 无 | reporter_rank=PRIMARY 批量取值 |
-| 003 | estimatedCost/tier/人数 | 无 | 批量派生 |
+| 003 | ~~estimatedCost~~/tier/人数 | 无 | 批量派生（🔴 **`estimatedCost` 部分已于 2026-09-20 订正作废**：它虽在出参里出现过，但**从未被赋值**，且已由 #7536 删除；tier 与人数不受影响） |
 | 003 | contactPhone | 原文 | 全量掩码 |
 | 003 | totalPrice | 无 | 本户应收（payableForDisplay 口径，取消单返 "0.00"，#6929/#7097） |
 | 003 | travelers | 无 | name/type/age/birthdayInTrip（无证件号，跨年修正 #6929） |
@@ -443,7 +443,10 @@ GET /v3/admin/order/group-batch/<groupBatchId>/orders?includeTravelers=true&incl
 1. **【001】无活跃子订单的团期 `chips` 整体为 `null`**（不是六键全「待办」）。有单团期六键全在（聚合态四值：待办/处理中/已完成/异常；个别键可为 null）。渲染芯片前判 `chips != null`，null 时按「未开始」占位。
 2. **【000】`productType` 实际只能看团期产品**：上游产品域只返回 GROUP 产品，传非 GROUP 值得空列表；「不限类型查普通产品」是面向隐式团的规划能力，当前不可达。§三.1 入参表原「不传=不限」描述有误，已就地勘误，以本条为准。
 3. **【003】`demandStatus`（本户需求态 SUBMITTED/CONFIRMED/REJECTED）不下发**：契约卡 GB-ADM-003 有该字段但本期未实现，响应中不存在；原型名单表「打回 / 已重提」列暂无数据源，请先隐藏或恒占位，勿依赖。
-4. **【003】`totalPrice`（本户应收）已实现（#6929）**：「预计毛利 = totalPrice − estimatedCost」现可直接算（`estimatedCost` 已可用）。`totalPrice` 为 JSON 字符串（ToStringSerializer），活跃单 = orderAmount + surchargeAmount − discountAmount（下限 0），**取消单返 `"0.00"`**（#7097 已补两位小数；JSON 为字符串，勿数值化）。**请勿用 `paidAmount + balanceAmount` 自算应收**（含退款场景口径不对）。
+4. **【003】`totalPrice`（本户应收）已实现（#6929）**：~~「预计毛利 = totalPrice − estimatedCost」现可直接算（`estimatedCost` 已可用）。~~
+   🔴 **2026-09-20 订正：上面这句是错误交接，请勿据此开发。**`estimatedCost` **从 #6905（`47aaff0be`）透出那天起就恒为 `null`**，不是后来才失效的——实测 `origin/dev-v3`：`setEstimatedCost` / `getEstimatedCost` 在 main 代码里**各 0 命中**（后者尤其关键：MyBatis-Plus 的 `LambdaUpdateWrapper.set(Entity::getXxx, v)` 用的是 **getter 引用**，只 grep setter 会整类漏掉），且该字段名在整个 Java 侧**只出现在实体自身的声明里**，没有任何别的 DTO/VO 带这个属性名 ⇒ 连 `BeanUtil` 那种反射拷贝也无从填它。该字段已于 **#7536（`6182d566d`）从 003 出参删除**。
+   ⇒ **「预计毛利」列在本接口上任何时点都算不出来。**逐户毛利的现行宿主是**核团接口** `GET /v3/admin/order/group-batch/{groupBatchId}/audit` 的 `allocs[].grossProfit` / `allocs[].costAmount`（`GroupBatchAuditRespVO.java:204-208` 声明，`GroupBatchAuditService.java:742-743` 真实填值；见 changelog `18_7932`，亦即 `14_7536:97`「毛利改核单页」所指）。
+   📌 顺带订正出处：`estimatedCost` 由 **#6905（`47aaff0be`）** 引入，**不是** `df8dbea0c`——后者只加了 `totalPrice`。`totalPrice` 为 JSON 字符串（ToStringSerializer），活跃单 = orderAmount + surchargeAmount − discountAmount（下限 0），**取消单返 `"0.00"`**（#7097 已补两位小数；JSON 为字符串，勿数值化）。**请勿用 `paidAmount + balanceAmount` 自算应收**（含退款场景口径不对）。
 5. **【003】`include*=false` 时扩展字段「键在、值为 null」**：`travelers / roomCount / roomType / specialNeeds` 键仍存在、值为 `null`，判 `null` 即可，勿用 `key in obj` 判断。
 6. **【003】`birthdayInTrip` 跨年已修复（#6929）**：行程跨年（12 月~1 月）时，出团年与返团年分别年化比较，任一落在行程闭区间即 `true`（如 12-28~01-03 行程内 01-02 生日 → true）；2-29 生日在非闰年落 2-28 不抛异常。

@@ -452,7 +455,7 @@ GET /v3/admin/order/group-batch/<groupBatchId>/orders?includeTravelers=true&incl
 | 工单 | 内容 | 前端影响 |
 |------|------|----------|
 | #6926 | 008 导出补 `opsStage`；009 自校验修正；month 非法值容错 | 见 `01_6904_*` 第十一节 |
-| ~~#6929~~ | ~~003 补 `totalPrice`；`birthdayInTrip` 跨年修正；内部双包装收敛~~ | ✅ 已实现（PR #7057，部署验收后生效）：`totalPrice − estimatedCost` 可直接算预计毛利；跨年生日不再漏报；其余无感 |
+| ~~#6929~~ | ~~003 补 `totalPrice`；`birthdayInTrip` 跨年修正；内部双包装收敛~~ | ✅ 已实现（PR #7057，部署验收后生效）：~~`totalPrice − estimatedCost` 可直接算预计毛利~~ 🔴 **该半句 2026-09-20 订正作废**（`estimatedCost` 恒 null，见「联调口径」第 4 条）；`totalPrice` 本身已实现属实；跨年生日不再漏报；其余无感 |

 ## 关联 / 联系人

@@ -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_owner: ""
-frontend_ref: ""
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "ac6c685edd485da7b5f0fc072e9957c6facb020c"
 target_release: ""
-verified_at: ""
-status_note: "本文档是补登，不是新上线通知。PR-A（#7844，merge commit 8eb8e13cdfd4a8cc004f95cfb53f7e4b81904461，2026-09-16 合入 dev-v3）首次交付本端点时漏写了交接件，导致 #7442 AC-22（要求『5 个新增接口 + 4 个改造接口的完整契约』）按字面一直不可能达成；本单是对这个缺口的补登。backend_status=deployed 的依据：8eb8e13cd 已在 dev-v3，测试服 2026-09-19 01:15 已滚动部署到 4cbccc26b（晚于 8eb8e13cd 与后续 c6aa1224f，均已实测回读 commit 确认在链上）。gateway_status=verified 的依据：2026-09-19 已完成本端点的网关实测，正负各一次，见第八节；⚠️ 本文档此前 gateway_status 字段写的是 verified 而 status_note 与第八节都写着 pending，头身不一致，那时的 verified 是假状态——现在它是真的，见第八节的请求/响应原文与数据库交叉读数。本文档按端点当前（2026-09-19）的完整契约撰写，其中 requirementId/requirementVersion/demands[].assignments[].groupId 等分组相关字段是 PR-A 首次引入的核心内容；reconfigureWindowToken 字段与 602011/602012/602013 三个错误码是随后 PR-C2（#7957）追加到同一端点的字段，本文档一并如实标注，避免把 PR-C2 之后的完整契约错当 PR-A 原状描述。"
+verified_at: "2026-09-21"
+status_note: "本文档是补登，不是新上线通知。PR-A（#7844，merge commit 8eb8e13cdfd4a8cc004f95cfb53f7e4b81904461，2026-09-16 合入 dev-v3）首次交付本端点时漏写了交接件，导致 #7442 AC-22（要求『5 个新增接口 + 4 个改造接口的完整契约』）按字面一直不可能达成；本单是对这个缺口的补登。backend_status=deployed 的依据：8eb8e13cd 已在 dev-v3，测试服 2026-09-19 01:15 已滚动部署到 4cbccc26b（晚于 8eb8e13cd 与后续 c6aa1224f，均已实测回读 commit 确认在链上）。gateway_status=verified 的依据：2026-09-19 已完成本端点的网关实测，正负各一次，见第八节；⚠️ 本文档此前 gateway_status 字段写的是 verified 而 status_note 与第八节都写着 pending，头身不一致，那时的 verified 是假状态——现在它是真的，见第八节的请求/响应原文与数据库交叉读数。本文档按端点当前（2026-09-19）的完整契约撰写，其中 requirementId/requirementVersion/demands[].assignments[].groupId 等分组相关字段是 PR-A 首次引入的核心内容；reconfigureWindowToken 字段与 602011/602012/602013 三个错误码是随后 PR-C2（#7957）追加到同一端点的字段，本文档一并如实标注，避免把 PR-C2 之后的完整契约错当 PR-A 原状描述。前端实证维持 pending(mmg 2026-09-21):reconfigure 编辑器(分组×逐日×车/司机计划 UI)属团期配车模块增量2,用户已拍板启动、待本件实施;增量1(受控重开 reopen+#7988 观测块)已先行交付。survivorPolicy/clearAll 涉 #7444 共用关系语义,交接件未推前不开发该分支。增量2已交付(mmg 2026-09-21, hl-admin ac6c685e):fleet 团期配车总览新增「编辑配车计划」入口与 GroupDispatchPlanEditor——按需求 groups[]×各组 days[].tripDate 铺行,车辆(getVehiclesPage 车牌模糊)/司机(getDriverOptions)远程搜索,提交 demands 按日期聚合(groupId=groupCode 字符串、driverId 可空剥离、remark trim、reconfigureWindowToken trim 后非空才带);本地前置校验每行车必填;idempotentShortCircuit=true 按幂等成功展示非失败;失败(600006/600007/602005/602011-602013/100502)一律拦截器透 message 表单保留;前端无现行计划读口,编辑器不回显、打开即全量重填,UI 文案已明示;按钮口径 CONFIRMED/DISPATCHED/PENDING_RECONFIRM 且有乘车分组。clearAll/survivorPolicy 分支仍留待 #7444 交接件,未开发。"
 updated_at: "2026-09-19"
 base: "dev-v3"
 ---
@@ -7,12 +7,12 @@ author: "wx(GIT)"
 change_type: "新增接口"
 backend_status: "deployed"
 gateway_status: "verified"
-frontend_status: "pending"
-frontend_owner: ""
-frontend_ref: ""
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "3df2c6f8df7902b31886e7ca0fc0ec88807d7032"
 target_release: ""
-verified_at: ""
-status_note: "代码已合入 dev-v3（PR #7957，merge commit c6aa1224fb46c3a7671da8234886075efde3c4ed）。⚠️ 本文档此前写『测试服尚未部署到含本次改动的版本』——那句已过期：2026-09-19 的实测中 reconfigureWindowToken（PR-C2 引入的字段）被真实端点接收并生效，反证 #7957 已在测试服链上；同轮实测中 order-v3 与 fleet 均在 31fd5b5e6。⚠️ 同时订正一处头身不一致：gateway_status 字段一直写着 verified，而 status_note 与第八节都写着 pending——那时的 verified 是假状态。现在 backend_status=deployed、gateway_status=verified 都有证据：本文档覆盖的 5 个端点已于 2026-09-19 逐个实测，见第八节的请求/响应与数据库交叉读数。本文档是 #7442 PR-C（团级确认态与配车恢复流程）的第三份交接件：PR-B（fleet 确认整团配车 + order-v3 回写已发车务）已由 17_7442_团级确认态-需求已发车务回写-新增接口-管理后台.md 交付并 deployed；本文档只覆盖 PR-C2（受控重开窗口 + 计划刷新状态收口）新增/改造的端点，不重复 PR-B 内容。"
+verified_at: "2026-09-21"
+status_note: "代码已合入 dev-v3（PR #7957，merge commit c6aa1224fb46c3a7671da8234886075efde3c4ed）。⚠️ 本文档此前写『测试服尚未部署到含本次改动的版本』——那句已过期：2026-09-19 的实测中 reconfigureWindowToken（PR-C2 引入的字段）被真实端点接收并生效，反证 #7957 已在测试服链上；同轮实测中 order-v3 与 fleet 均在 31fd5b5e6。⚠️ 同时订正一处头身不一致：gateway_status 字段一直写着 verified，而 status_note 与第八节都写着 pending——那时的 verified 是假状态。现在 backend_status=deployed、gateway_status=verified 都有证据：本文档覆盖的 5 个端点已于 2026-09-19 逐个实测，见第八节的请求/响应与数据库交叉读数。本文档是 #7442 PR-C（团级确认态与配车恢复流程）的第三份交接件：PR-B（fleet 确认整团配车 + order-v3 回写已发车务）已由 17_7442_团级确认态-需求已发车务回写-新增接口-管理后台.md 交付并 deployed；本文档只覆盖 PR-C2（受控重开窗口 + 计划刷新状态收口）新增/改造的端点，不重复 PR-B 内容。前端 2026-09-21 已交付(增量1):① reopen 入口落在 GroupVehicleRequirementSection「受控重开配车窗口」(DISPATCHED/PENDING_RECONFIRM 可开,reason/scopeGroupCodes/scopeDates/windowMinutes 四必填走 NForm rules,成功结果视图展示 windowToken+expiresAt+复制按钮供转达车务,重开后重拉同步 PENDING_RECONFIRM 标签);② requirement/confirm 六字段分支:planRefreshState!=null 即受控重开链路,只提示「已受理重新确认,配车计划刷新中」不走户级放行文案(advanceUnblocked 恒 false 不宣称恢复),并联动需求区 reload+短轮询;809204/809210 拦截器透 message。plan-refresh/coverage/dispatch-baseline 三内部端点前端不对接。PR-A reconfigure 编辑器为增量2 待建。"
 updated_at: "2026-09-19"
 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"
 ---
@@ -0,0 +1,540 @@
+---
+schema: "hl-changelog/v2"
+ticket: "5935"
+title: "改期残留清理用现有读写口即可，无需新增字段/接口"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "前端缺陷"
+backend_status: "deployed"
+gateway_status: "not_required"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "28d4482c636dbfeba1803c64ef263f09c3656934"
+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 兜底。2026-09-26 订正(#8371):DELETE 命中改期残留行已改为单行取消,并豁免 605027/605047/605028 三道日期门,见 26_8371_改期残留行单行取消与累计凭证回显-修改接口-管理后台.md。"
+updated_at: "2026-09-26"
+base: "dev-v3"
+---
+
+# 车务派单：改期残留清理用现有读写口即可（用法说明，零代码改动）
+
+> **存放目录**: 二期(v3) → `changelogs-v2/2026-09/`
+> **服务**: hl-fleet-service (端口 8082)
+> **PR**: 无（零代码改动，未产生新 PR）
+> **Issue**: #5935（原始功能单，2026-08-16 已上线并随 #7067 部分退役；本文档是第三次说明）
+> **日期**: 2026-09-20
+> **影响范围**: 管理后台车务排车 Step2 弹窗「改期残留清理」交互的前端实现方式；不改后端代码、不改网关路由
+
+---
+
+## 给前端的一句话结论
+
+你要的能力**今天就已经有**：可勾选的残留日期数组不需要后端新增字段，从现有 `candidates` 响应的 `cells[]` 里按 `rescheduleResidue === true` 过滤即可拿到；清理动作也不需要等新接口，逐日清理用 `DELETE /admin/fleet/assignments/{assignmentId}`、整批清理用 `POST /admin/fleet/assignments/batch`（不提交残留日期项即视为清理）。**但你在清单里引用的那个写口 `POST .../slots/{slotId}/clear-residue-dates` 不存在**——它已经随 #7067 去槽位化被整体删除，请改用下面两条现成的写口。
+
+---
+
+## ⚠️ 关键变化
+
+- **本次没有新增、修改或删除任何接口**，后端零代码改动。
+- 前端诉求引用的写口 `POST .../slots/{slotId}/clear-residue-dates` **在 `origin/dev-v3` 全仓零命中**（`clear-residue-dates` / `clearResidueDates` / `cancel-residue` 均零命中）。`AssignmentControllerTest.java:938` 留有明确注释：「#7067：cancel-residue 端点已随槽位概念退役删除」——**「槽位（slot）」这个概念本身已经退役**，基于 `slotId` 的写口不会再出现。
+- 前端要求新增的读侧字段 `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。
+
+---
+
+## 一、背景
+
+### 前端诉求（原文摘要，仅作背景，不作为下文技术结论的依据）
+
+前端 2026-09-20 反馈清单第4项：「写口 `POST .../slots/{slotId}/clear-residue-dates` 已就绪，但前端只有 `rescheduleResidue` 布尔徽标，无可勾日期子集，无法实现『选槽位+勾日期』交互」，要求后端在读侧补一个 `residueServiceDates` 日期数组。
+
+### 「前端以为的」vs「实际是」
+
+| 维度 | 前端以为的 | 实际是（`文件:行` @origin/dev-v3） |
+|------|------------|------------------------------------|
+| 写口 | `POST .../slots/{slotId}/clear-residue-dates` 已就绪可直接调 | 该端点**不存在**：`clear-residue-dates`/`clearResidueDates`/`cancel-residue` 全仓零命中；`AssignmentControllerTest.java:938`「#7067：cancel-residue 端点已随槽位概念退役删除」。「槽位」概念本身已随 #7067 去槽位化退役，请改用 `DELETE /admin/fleet/assignments/{assignmentId}`（逐日）或 `POST /admin/fleet/assignments/batch`（整批） |
+| 读侧字段 | 需要后端新增 `residueServiceDates: string[]` 字段才能拿到可勾选日期子集 | **不需要新增**：`cells[]` 已逐日携带 `rescheduleResidue`（`AssignmentCandidateRespVO.java:146-147`）+ `serviceDate`，前端 `cells.filter(c => c.rescheduleResidue).map(c => c.serviceDate)` 即得；`editableServiceDates`（`AssignmentCandidateRespVO.java:90`）也已把残留日期并入集合（`Step2CanonicalSnapshotService.java:218-227`） |
+
+### 该问题的历史脉络（同一张单 #5935）
+
+1. 2026-08-16：`changelogs-v2/2026-08/16_5935_排车按日期清理改期残留-新增接口-管理后台.md` 记录了 **当时新增** 的端点 `POST /admin/fleet/assignments/slots/{slotId}/clear-residue-dates`（commit `1fe44677a`，PR #5985）。
+2. #7067 去槽位化整体重构派单契约，`slotId` 概念被删除，该端点随之整体删除（该 changelog 的 `status_note` 已自我标注："本端点...已被 #7067 去槽位化整体删除(404),无前端落地对象...残留清理语义由 `POST /batch` 整批 diff 覆盖"）。
+3. 2026-09-20：前端仍然引用了这个已退役的端点、并额外要求新增字段——本文档是第三次澄清：**不用等新接口，现有两条写口 + 现有读侧字段已完全覆盖这个场景**。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 查询派单候选资源（含残留标记） | POST | `/admin/fleet/assignments/candidates` | 复用不改 | `canonicalSnapshot.cells[].rescheduleResidue` 已可推导残留日期子集 |
+| 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`。
+
+---
+
+## 三、接口详情
+
+### 1. 查询派单候选资源 `POST /admin/fleet/assignments/candidates`
+
+**VO**: `AssignmentCandidateReqVO → AssignmentCandidateRespVO`
+
+#### 使用场景
+
+车务打开排车/派单 Step2 弹窗时调用本端点获取 `canonicalSnapshot`；改期后旧日期的逐日派车切片会作为「改期残留」继续出现在 `cells[]` 里（`Step2CanonicalSnapshotService.java:199-227`：完整可编辑服务日 = 需求 `serviceDates` 权威集合 ∪ 在途旧行覆盖的越窗旧日期，注释原文「并入改期残留旧日期：在途行覆盖日期中越出当前需求窗的部分（含全程行展开）」）。前端从返回的 `cells[]` 中筛出 `rescheduleResidue === true` 的项，即得到「待清理的改期残留」候选日期集合，供「选槽位+勾日期」交互勾选。
+
+> 本节仅列出与「识别/清理改期残留」直接相关的字段；候选资源查询的完整契约（车辆/司机分页、筛选、常驻关系、自动代入司机等）不在本文档范围。
+
+#### 入参字段表
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| orderId | Body | String(Long) | 否（改派排除自身时必填） | - | 当前订单ID |
+| requirementId | Body | String(Long) | 否（改派排除自身时必填） | - | 当前用车需求ID；`requirementId` 缺失或需求上下文不可用时 `canonicalSnapshot` 为 `null`（`AssignmentCandidateRespVO.java:65-68`） |
+| startDate | Body | LocalDate | 是 | `@NotNull` | 查询窗口开始日 |
+| endDate | Body | LocalDate | 是 | `@NotNull` | 查询窗口结束日 |
+
+#### 出参字段表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data.canonicalSnapshot | Object | 无 `requirementId` 或上下文不可用时为 `null` |
+| data.canonicalSnapshot.editableServiceDates | LocalDate[] | 完整有序可编辑服务日集合；已并入改期残留旧日期（`AssignmentCandidateRespVO.java:90`；并入逻辑 `Step2CanonicalSnapshotService.java:218-227`） |
+| data.canonicalSnapshot.cells[] | Array | 每个 RetainedGroupSet × editableServiceDates 笛卡尔积位置的唯一 cell |
+| data.canonicalSnapshot.cells[].groupId | String(Long) | 稳定派车组ID（历史行无 assignmentGroupId 时回退 assignmentId） |
+| data.canonicalSnapshot.cells[].serviceDate | LocalDate | 服务日期 |
+| data.canonicalSnapshot.cells[].assignmentId | String(Long) | 当天逐日派车行ID；全程行/无行/不用车为 `null`；**「取消残留派车按此ID单日取消」**（`AssignmentCandidateRespVO.java:124-126`原文注释） |
+| data.canonicalSnapshot.cells[].used | String | `USED`(实际用车) / `UNUSED`(显式不用车) / `null`(无切片行) |
+| data.canonicalSnapshot.cells[].rescheduleResidue | Boolean | **前端要的「可勾选残留日期」判据就是这个字段**：`true`=该 cell 服务日期越出当前需求日期窗，属改期后待清理的旧实派车，前端据此挂「改期残留/待清理」徽标（`AssignmentCandidateRespVO.java:146-147`） |
+| data.canonicalSnapshot.cells[].canDelete | Boolean | 是否可删除/取消：**改期残留旧行恒 `true`，只能改派或取消释放占用；受只读窗口约束时为 `false`**（`AssignmentCandidateRespVO.java:149-150`原文注释） |
+| data.canonicalSnapshot.cells[].readOnly | Boolean | 该 cell 是否只读；只读 cell 不可被批量操作改写 |
+| data.canonicalSnapshot.cells[].readOnlyReason | String | 只读原因；可编辑时为 `null` |
+
+#### 请求示例
+
+> 以下示例按 VO 字段与类型构造，非测试服抓包实测。
+
+```json
+{
+  "orderId": "2096412454643802114",
+  "requirementId": "2096412454643812345",
+  "startDate": "2026-09-10",
+  "endDate": "2026-09-15"
+}
+```
+
+#### 响应示例
+
+> 按 `AssignmentCandidateRespVO`/`SnapshotCellVO` 字段契约与仓库内测试夹具（`AssignmentControllerTest.java:143-199`）构造，非测试服抓包实测；`cells[1]` 展示一个 `rescheduleResidue=true` 的残留日期。
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "canonicalSnapshot": {
+      "planGeneration": "9007199254741001",
+      "snapshotVersion": "1",
+      "retainedGroupIds": ["9007199254741002"],
+      "editableServiceDates": ["2026-09-10", "2026-09-11", "2026-09-08"],
+      "cells": [
+        {
+          "groupId": "9007199254741002",
+          "serviceDate": "2026-09-10",
+          "assignmentId": "2096412454488612900",
+          "used": "USED",
+          "rescheduleResidue": false,
+          "canDelete": true,
+          "readOnly": false,
+          "readOnlyReason": null
+        },
+        {
+          "groupId": "9007199254741002",
+          "serviceDate": "2026-09-08",
+          "assignmentId": "2096412454488612866",
+          "used": "USED",
+          "rescheduleResidue": true,
+          "canDelete": true,
+          "readOnly": false,
+          "readOnlyReason": null
+        }
+      ]
+    }
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+`requirementId` 缺失或需求上下文不可用时 `canonicalSnapshot` 整体为 `null`（不是空对象），前端应据此区分「无残留」和「查不到需求上下文」两种态；没有任何改期残留时 `cells[]` 内所有项 `rescheduleResidue` 恒为 `false`，不会单独返回空数组表示"无残留"。
+
+```json
+{ "code": 200, "message": "成功", "data": { "canonicalSnapshot": null }, "success": true }
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 400,
+  "message": "参数非法: 用车开始日期不能为空",
+  "data": null,
+  "success": false
+}
+```
+
+#### 业务边界
+
+- `cells[]` 是 RetainedGroupSet × editableServiceDates 的笛卡尔积，**并非只含残留日期**——必须用 `rescheduleResidue === true` 过滤，不能假设整个数组都是残留。
+- `canDelete` 字段的设计意图是「改期残留旧行恒 true」，但受「只读窗口」约束时会翻转为 `false`；前端在渲染可勾选状态时应优先读 `canDelete`，而不是只看 `rescheduleResidue`。
+- 改派场景（排除自身占用）需另传 `excludeAssignmentId`（本文档聚焦残留清理场景，未展开该分支）。
+
+---
+
+### 2. 取消派单（逐日清理残留） `DELETE /admin/fleet/assignments/{assignmentId}`
+
+**VO**: `CancelReqVO → CancelRespVO`
+
+> **2026-09-26 订正（#8371）**：本小节标题「逐日清理残留」写作时是前端诉求的期望描述，当时源码并不支持——`DELETE` 命中改期残留行时仍按整组取消。#8371 已实测确认标题所述行为现已成立：目标行若判定为「改期残留行」，走单行取消分支，操作日志 `operationLog[].detailJson` 会带 `scope="RESIDUE_ROW"` 可供核验；非残留行不受影响，仍是整组取消。细节见 `26_8371_改期残留行单行取消与累计凭证回显-修改接口-管理后台.md`。
+
+#### 使用场景
+
+车务在 Step2 栅格里勾选一个或多个 `rescheduleResidue=true` 的日期后，对每个勾选日期取其 cell 的 `assignmentId`，逐日调用本端点单独取消，条件释放该行占用的车辆/司机。适合「只清理某几天」「部分勾选」场景。
+
+#### 入参字段表
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| assignmentId | Path | Long | 是 | - | 取自 `cells[].assignmentId`（残留清理场景下即待取消的那一天） |
+| cancelReason | Body | String | 是 | `@NotBlank` | 取消原因 |
+| driverNotified | Body | Boolean | 是 | `@NotNull` | 是否已告知司机（人工存证；`true`/`false` 均可取消） |
+| notifyNote | Body | String | 否 | - | 告知备注 |
+| cutoffDate | Body | LocalDate | 否 | - | 取消生效日；**服务端仅接受当天，空值按当天处理，不支持预约未来取消**（`CancelReqVO.java:35-37`原文注释） |
+| evidenceFileIds | Body | List<Long> | 否 | 最多20个 | 取消凭证文件ID列表 |
+| confirmWithoutEvidence | Body | Boolean | 否 | - | 无凭证时的二次确认标记 |
+| requestId | Body | String | 是 | `@NotBlank`，最长64 | 请求幂等ID |
+
+#### 出参字段表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data.assignmentStatus | String | `canceled`=已取消 |
+| data.assignmentGroupId | String(Long) | 派车组ID；历史行无该字段时回退 assignmentId |
+| data.assignmentSlotId | String(Long) | 稳定车辆槽位ID（历史字段，随 #7067 去槽位化不再是新契约主键） |
+| data.effectiveDate | LocalDate | 实际取消生效日 |
+| data.evidenceFileIds | String(Long)[] | 取消凭证文件ID列表 |
+| data.confirmedWithoutEvidence | Boolean | 无凭证时是否已二次确认 |
+| data.sideEffects.vehicleStatusUpdated | String | 车辆状态更新结果（idle/busy/maint；不涉及车为 null） |
+| data.sideEffects.driverStatusUpdated | String | 司机状态更新结果（busy/idle；不涉及司机为 null） |
+| data.sideEffects.reconPrepRowsCreated | Integer | 对账预备单创建条数（M1 降级恒 0） |
+| data.sideEffects.reconPrepMarkedCanceled | Integer | 对账预备单标记取消条数（M1 降级恒 0） |
+
+#### 请求示例
+
+```json
+{
+  "cancelReason": "改期残留清理",
+  "driverNotified": true,
+  "notifyNote": "已电话通知师傅",
+  "requestId": "residue-clear-2096412454488612866"
+}
+```
+
+#### 响应示例
+
+> 按 `CancelRespVO` 字段契约构造，非测试服抓包实测。
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "assignmentStatus": "canceled",
+    "assignmentGroupId": "9007199254741002",
+    "assignmentSlotId": null,
+    "effectiveDate": "2026-09-20",
+    "evidenceFileIds": [],
+    "confirmedWithoutEvidence": null,
+    "sideEffects": {
+      "vehicleStatusUpdated": "idle",
+      "driverStatusUpdated": "idle",
+      "reconPrepRowsCreated": 0,
+      "reconPrepMarkedCanceled": 0
+    }
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+本端点是单条操作，无「空数据」态；命中不存在的 `assignmentId` 走错误响应（见下）。
+
+```json
+{ "code": 605009, "message": "派单不存在", "data": null, "success": false }
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 605028,
+  "message": "取消生效日不在派单服务日期范围内",
+  "data": null,
+  "success": false
+}
+```
+
+其它错误码（`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` 也允许取消，只是前端需要在未告知司机时给出强提示（后端只做存证，不代为通知）。
+
+---
+
+### 3. 批量创建派单（整批清理残留） `POST /admin/fleet/assignments/batch`
+
+**VO**: `BatchCreateAssignmentReqVO → BatchAssignmentWriteRespVO`
+
+#### 使用场景
+
+车务在 Step2 栅格里编辑好完整的新逐日配车方案后一次性提交。若不希望保留某些残留日期，**只需在 `dailyPlan[]` 里不包含那些日期**，后端按（服务日期×车辆）diff 原子重写：新方案未覆盖的现行日期行自动取消（含改期残留行）。适合"整批一次性对齐新方案"场景。
+
+#### 入参字段表
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| orderId | Body | String(Long) | 是 | `@NotNull` | 订单ID |
+| requirementId | Body | String(Long) | 是 | `@NotNull` | 当前生效用车需求ID |
+| kind | Body | String | 否 | `TRAVEL`/`TRANSFER` | 需求类别，不传按 TRAVEL |
+| startDate | Body | LocalDate | 是 | `@NotNull` | 用车开始日期 |
+| endDate | Body | LocalDate | 是 | `@NotNull` | 用车结束日期 |
+| confirmNoVehicleServiceDates | Body | Boolean | 否 | - | 逐日计划未覆盖全部服务日期时的显式二次确认 |
+| sendItinerarySms | Body | Boolean | 否 | 不传按 false | 是否向本批各车师傅发送行程短信 |
+| requestId | Body | String | 是 | `@NotBlank`，最长64 | 批次级幂等请求标识 |
+| dailyPlan[] | Body | Array | 是 | 最多4000项 | 按行程日的完整配车列表；**要清理的残留日期不要出现在这个数组里** |
+| dailyPlan[].serviceDate | Body | LocalDate | 是 | `@NotNull` | 服务日期 |
+| dailyPlan[].vehicleId | Body | String(Long) | 是 | `@NotNull` | 车辆ID |
+| dailyPlan[].driverId | Body | String(Long) | 是 | `@NotNull` | 司机ID |
+| dailyPlan[].assignmentPrice | Body | String(BigDecimal) | 否 | ≥0 | 本车当天实际价格，不传按车型价格日历兜底 |
+| dailyPlan[].priceAdjustmentReason | Body | String | 否 | 最长256 | 实际价格与参考价不一致时的调整原因 |
+| items / chargeableServiceDates / vehicleFeeWaiverReason / confirmAllServiceDatesFree / holdMode | Body | - | - | **禁止携带** | #7067 已移除的旧字段，携带即 400（`BatchCreateAssignmentReqVO.java:98-124`） |
+
+#### 出参字段表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data.assignments[] | Array | 按 fleetItemIndex 升序返回的派单结果（历史字段名，结构见 `AssignmentWriteRespVO`） |
+| data.finalPlanPublished | Boolean | 本次是否已发布最终方案；`false` 表示排车已落库但接送机未配齐 |
+| data.pickupDropoffGate | Object | 接送机门禁状态（要求日与缺口日） |
+| data.failedFleetItemIndex | Integer | 直接派定基线失败的车辆槽位序号 |
+| data.dailyDifferences[] | Array | 直接派定基线失败的逐日差异 |
+
+#### 请求示例
+
+```json
+{
+  "orderId": "2096412454643802114",
+  "requirementId": "2096412454643812345",
+  "startDate": "2026-09-09",
+  "endDate": "2026-09-15",
+  "requestId": "batch-residue-clear-20260920-001",
+  "dailyPlan": [
+    { "serviceDate": "2026-09-10", "vehicleId": "2079857983403024385", "driverId": "2079857983403024387" },
+    { "serviceDate": "2026-09-11", "vehicleId": "2079857983403024385", "driverId": "2079857983403024387" }
+  ]
+}
+```
+
+上例中 `2026-09-09`（残留日期）未出现在 `dailyPlan[]` 里，后端 diff 会把该日现行行自动取消。
+
+#### 响应示例
+
+> 按 `BatchAssignmentWriteRespVO` 字段契约构造，非测试服抓包实测。
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "assignments": [],
+    "finalPlanPublished": true,
+    "pickupDropoffGate": null,
+    "failedFleetItemIndex": null,
+    "dailyDifferences": null
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+未配置接送机声明的订单 `pickupDropoffGate` 恒为 `null`；无接送机声明时提交即完成（`finalPlanPublished=true`）。
+
+#### 错误响应
+
+**本场景最关键的错误**——残留日期已过去时，diff 判定要取消它会被"日期已过去"门禁拦下（`AssignmentService.java:2775-2778` `assertDailyPlanDateMutable`），整个批次连同一并提交的其它合法项一起被拒绝，非部分成功：
+
+```json
+{
+  "code": 100001,
+  "message": "参数非法: 2026-09-09已过去或已完结，不能修改逐日派车配置",
+  "data": null,
+  "success": false
+}
+```
+
+其它已知错误码：605062（提交项的服务日期越出当前需求日期窗；已有的窗外在途行不受此码约束，改由整批 diff 精确取消，见 `AssignmentServiceTest.java:1727` 用例）/ 605912（派车快照缺少车型）。
+
+#### 业务边界
+
+- ⚠️ **改期后延的残留日期多半已经过去，本端点无法清理它们**：`assertDailyPlanDateMutable`（`AssignmentService.java:2775-2778`）对"新方案未覆盖、因此要被 diff 自动取消"的现行行同样做日期校验，命中过去日期即整批 400。前端做"整批清理"操作前必须预判这种场景，遇到 400 应引导车务改用逐日 `DELETE /{assignmentId}`。
+- 旧字段（`items`/`fleetItemIndex`/`used`/`pickupParticipant` 等）携带即 400，不再兼容。
+- 接送机不在本接口配置，走独立的 `PUT /pickup-dropoff-config`。
+- 整批提交是原子操作：校验失败不会部分落库。
+
+---
+
+## 四、契约约束与正确调用方式
+
+> 本节只写**后端接受/拒绝 payload 的规则**，不写 UI 渲染建议。
+
+### ✅ 正确 / ❌ 错误 用法对照
+
+| 场景 | 用法 |
+|------|------|
+| ✅ 获取可勾选残留日期 | `GET candidates` 响应的 `cells.filter(c => c.rescheduleResidue).map(c => c.serviceDate)` |
+| ✅ 逐日清理（含过去日期，未取证是否放行） | `DELETE /admin/fleet/assignments/{cell.assignmentId}` |
+| ✅ 整批清理（残留日期均未过去） | `POST /batch`，`dailyPlan[]` 不包含要清理的日期 |
+| ❌ 整批清理（残留日期已过去） | 同上 payload → **400（`code=100001`）整批被拒**，不会"跳过过去日期、只清未来的" |
+| ❌ 调用文档外的写口 | `POST .../slots/{slotId}/clear-residue-dates` → **该路径不存在**（#7067 已删除，无 `slotId` 概念） |
+
+### 切换清理方式的必要动作
+
+前端在实现"整批清理"按钮时，遇到 `code=100001` 且消息含"已过去或已完结"，应识别为"残留日期已过去，本接口无法清理"，引导车务改走逐日 `DELETE` 路径（而不是当成普通校验失败重试原样提交）。
+
+> **2026-09-26 订正（#8371）**：上表「✅ 逐日清理（含过去日期，未取证是否放行）」与本段「引导车务改走逐日 `DELETE`」在写作时均未经实测；实测结果是**当时同样会被拦截**（改期残留行过去日期 `DELETE` 命中 605027），引导车务改走逐日 `DELETE` 在当时并不能真正解决问题。#8371 已修复：残留行现在 `DELETE` 直接取消成功，完全跳过整组门禁，上表与本段的方向自此才成立。见 `26_8371_改期残留行单行取消与累计凭证回显-修改接口-管理后台.md`。
+
+---
+
+## 五、数据库行为
+
+本次零改动；以下是既有行为，供前端理解结果落库口径：
+
+| 清理方式 | 命中行为 |
+|----------|----------|
+| `DELETE /{assignmentId}` | 该派车行状态置 `canceled`，条件释放车辆/司机占用（`sideEffects` 回真实反算结果） |
+| `POST /batch`（diff 自动取消未覆盖的现行行） | `assignmentMapper.cancelActiveRowsByIds(...)` 批量置 `canceled`，`cancel_source` 显式留空（`AssignmentService.java:2796-2802`原文注释「#5924：方案重写不是取消动作，cancel_source不盖章（留NULL）」），取消原因固定写"逐日派车方案调整" |
+
+两条路径都不会物理删除行，只做状态流转；`assignmentId` 一旦取消不可复用为新方案的匹配键。
+
+> **2026-09-26 订正（#8371）**：上表「状态置 `canceled`」是简化写法。测试服实测：取消前处于 `assigned`/`holding` 的行，落库状态是 `exception`（与通用取消 #6152 同口径），仅 `unassigned` 行取消才直接落 `canceled`。改期残留行走单行取消分支时同样遵循这条状态机，不因残留身份而特殊化。见 `26_8371_改期残留行单行取消与累计凭证回显-修改接口-管理后台.md`。
+
+---
+
+## 六、边界行为
+
+- 未登录 → 401（网关拦截）
+- `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`，对任何真实行恒非空
+
+---
+
+## 六.5、枚举 / 数据字典
+
+### used（`AssignmentCandidateRespVO.SnapshotCellVO.used`）
+
+**所属字段**: `data.canonicalSnapshot.cells[].used` | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `USED` | 实际用车 | 该 cell 当天有实派车辆/司机 |
+| `UNUSED` | 显式不用车 | 车务明确标记该日不配车 |
+| `null` | 无切片行（未编辑） | 该 group×日尚无任何逐日行 |
+
+---
+
+## 六.6、修改前后对比
+
+本文档不涉及接口修改（三条端点均为"复用不改"），无字段级/行为级对比。
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 否（无任何接口变更）
+- **前端是否必须同步上线**: 否（后端零改动，前端可按自己节奏切换实现方式）
+- **前端 workaround 清理点**: 若前端此前已按"等待新写口/新字段"的假设搭了占位代码或临时禁用了"整批清理"按钮，可撤——改用本文档给出的两条现成端点与现成字段即可实现完整交互
+
+---
+
+## 七、不影响范围
+
+- **仅影响**: 管理后台车务排车 Step2 弹窗「改期残留清理」交互的前端实现方式（用哪个端点、用哪个字段）
+- **零影响**:
+  - 后端代码（本次零改动）
+  - 数据库 schema
+  - 网关路由（三条端点均已在网关既有路由内）
+  - `POST /candidates`、`DELETE /{assignmentId}`、`POST /batch` 的既有契约与行为
+  - 其它车务/排车流程（本文档只梳理"改期残留清理"这一个场景）
+
+---
+
+## 八、测试环境已验证
+
+本文档不改代码，本轮**未做新的测试服 HTTP 实测**；以下用源码引用替代实测取证，均为 `origin/dev-v3`（HEAD `10efbaddf`，与本地工作树一致）实际存在的代码：
+
+```
+AssignmentCandidateRespVO.java:90        editableServiceDates 字段存在 ✓
+AssignmentCandidateRespVO.java:108-150   SnapshotCellVO 含 rescheduleResidue/canDelete/assignmentId ✓
+Step2CanonicalSnapshotService.java:218-227  残留日期并入 editableServiceDates 的逻辑 ✓
+AssignmentController.java:75              类级路由 /admin/fleet/assignments ✓
+AssignmentController.java:201-234         POST /batch 端点存在 ✓
+AssignmentController.java:462-477         DELETE /{assignmentId} 端点存在 ✓
+AssignmentControllerTest.java:938         cancel-residue 端点已随 #7067 删除的注释 ✓
+AssignmentService.java:2743-2744,2775-2778  diff 自动取消对过去日期的硬门禁 ✓
+AssignmentServiceTest.java:1727           窗外在途行由 diff 取消而非 605062 拦整批的用例 ✓
+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`。
+
+---
+
+## 十、相关文档
+
+- 原始功能单及第一版说明：`changelogs-v2/2026-08/16_5935_排车按日期清理改期残留-新增接口-管理后台.md`（已在其 `status_note` 里自我标注端点已随 #7067 退役）
+- 退役背景：#7067 去槽位化重构（`06_7067_派单去槽位化按行程日配车-接送机独立配置-修改接口-管理后台.md`）
+- 后续计划：若【需确认】项实测发现 `DELETE` 对过去日期同样拦截，需另开工单放开残留行的过去日期取消
+
+> **2026-09-26 订正（#8371）**：该「另开工单」已完成，即 #8371——已实测坐实过去拦截、已修复并验证放行。见 `26_8371_改期残留行单行取消与累计凭证回显-修改接口-管理后台.md`。
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#5935](https://git.1814.love:8443/wx/HL/issues/5935)
+- **PR**: 无（零代码改动，未产生新 PR）
+
+### 联系人
+
+- **后端负责人**: @wx
@@ -0,0 +1,985 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7443"
+title: "TRANSFER 派车行确认/改派基线复核修复（605905/605041 不再误判）"
+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-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"
+---
+
+# fleet/order-v3: TRANSFER 派车行确认/改派基线复核修复（605905/605041 不再误判）
+
+> **存放目录**: changelogs-v2/{YYYY-MM}/
+>
+> **服务**: hl-fleet-service、hl-order-service-v3（共享 hl-common-core 的 Feign DTO）
+> **PR**: 尚未创建（三个提交 `abd435c15`/`694e405fd`/`15c7cdd0c`，本地分支 `feature/7443-rest-ac`，尚未合入 `dev-v3`）
+> **Issue**: #7443 AC-24
+> **日期**: 2026-09-18
+> **影响范围**: 管理后台车务派单弹窗——按需求原子确认、车务确认执行、修改派单、查询派单候选资源（Step2 canonical 快照）四个既有端点，仅当对象（派车行/需求/候选查询）属于 `kind=TRANSFER`（接送机）时行为发生变化；另有一处内部作业端点（重发最终方案快照）不面向 admin 前端
+
+---
+
+## ⚠️ 关键变化
+
+**一句话**：`kind=TRANSFER` 建出来的派车行，以前建得出来但操作不动——现在通了。三个既有端点
+（按需求原子确认、车务确认执行、修改派单）的入参、出参**零变化**，变的只是内部"拿哪条需求当
+基线比对"的逻辑。
+
+**根因**（写给前端知道以前为什么会失败）：fleet 侧这三个端点的最终基线复核，原来一律拿
+`OrderFleetDetailContextDTO.vehicleRequirement` 当基线；而 order-v3 提供这个字段时**恒为
+TRAVEL**（`OrderFleetProviderService.java:1027-1029` 写死取 `kind=TRAVEL` 那条需求）。于是一条
+`requirement_id` 指向 TRANSFER 需求的派车行，在第一道 `requirementId` 比对上必然不等，从而被
+判定为"需求已过期/已变化"而拒绝——**接送机的车派得出来，却一步都确认/改派不了**。
+
+**修法**：`OrderFleetDetailContextDTO`（`hl-common-core`）新增**可空**字段
+`transferVehicleRequirement`；order-v3 一并把订单当前生效的 TRANSFER 需求带回（服务日未回填时
+降级为 `null`，不让整个车务详情上下文报错）。fleet 侧新增私有方法
+`baselineRequirementFor(requirementId, context)`：传入的 `requirementId` 命中
+`transferVehicleRequirement` 就用那条，否则原样回退 `vehicleRequirement`（TRAVEL）——
+**TRAVEL 派车行的比对结果与改动前逐字相同**。
+
+> ⚠️ **订正 2026-09-18 早些时候的说法**（本目录 `17_7443_*.md`、`18_7443_接送机用车需求分叉…`
+> 两份文档的「六、边界行为」都写"确认、改派、基线变更复验三处内部调用……对 TRANSFER 派车行
+> 一律 605041"）：这句话对 `POST /{assignmentId}/confirm` 与 `POST /{assignmentId}/change`
+> 准确，但对 `POST /requirements/{requirementId}/confirm` **不准确**——经 2026-09-18 源码复核
+> （`AssignmentService.java:3567-3583` 的 `assertRequirementPreflightVersion`），该端点有一道
+> **更早**触发的版本预检门禁，直接读 `context.getVehicleRequirement()`（恒 TRAVEL）与请求体里的
+> `requirementId`（TRANSFER）比对，必不等 ⇒ **实际可观测的报错是 605905（需求版本过期），
+> 不是 605041**；请求根本走不到后面真正会抛 605041 的 `assertFinalConfirmationBaseline`
+> （`:3974`）。两处的根因完全相同（都是"拿 `context.getVehicleRequirement()` 当基线"），
+> 本次修复对两处一并修，但**前端排查历史工单日志时请按实际报错码 605905 去找**，不要按
+> 605041 去找。
+
+**不影响范围（前端最关心的一句）**：TRAVEL 派车行的确认/改派/复核行为**逐字未变**；上游
+`PUT /v3/admin/order/{id}/vehicle-requirement` 传 `kind=TRANSFER` 的写口目前仍然关着
+（809009，见 `18_7443_接送机用车需求分叉…` 一文），本次修复**不改变这一点**——没有那个开关，
+生产环境仍然造不出真实的 TRANSFER 需求；本次修复解决的是"已经有一条 TRANSFER 需求/派车行时，
+这三个端点能不能正常操作它"。
+
+> **前端行动项**：无。本次三个端点的请求体、响应体结构一个字段都没有变，不需要改任何代码。
+> 如果贵方之前按 `18_7443_接送机用车需求分叉…` 文档的提示"前端本版暂缓接入 TRANSFER 派车行的
+> 确认/改派"搁置了相关联调，这条限制在**这三个端点自身**的维度已经解除；但由于上游写口
+> （809009）仍未开放，测试环境目前仍无法通过正常业务流程产出可供联调的 TRANSFER 数据。
+
+> 🆕 **2026-09-18 当日追加两个提交，同一根因的另外两处落点**（分支已 rebase 到最新 `dev-v3`，
+> 现为三个提交）：
+>
+> **① `refinalizeFinalSnapshot`**（`AssignmentService.java:13092`，提交 `694e405fd`）——一个
+> **内部作业端点**（`POST /internal/fleet/jobs/vehicle-assignment-snapshot/refinalize`，
+> `FleetJobInternalController`），不面向 admin 前端，供运维/作业系统补发存量订单的最终方案
+> 快照。坏法与前三处同形：读 `context.getVehicleRequirement()`（恒 TRAVEL），入参
+> `requirementId` 指向 TRANSFER 需求时必判"身份错位"而拒绝。⚠️ **源码注释与提交信息把这里的
+> 错误码写成了"605036"，经核实是笔误**：该方法唯一的身份不一致分支
+> （`AssignmentService.java:13096-13098`）实际 `throw new BusinessException(
+> AssignmentErrorCode.REQUIREMENT_VERSION_EXPIRED)`，即 **605905**（"需求版本过期"），
+> 605036 是另一个不相关的码（`CROSS_RESIDENT_CONFIRMATION_REQUIRED`，"司机与车辆不是常驻组合"）。
+> 本文档按实测的 605905 记录，不采信注释里的 605036。这一处**不进本文档「二/三」的接口清单**
+> （非 admin 端点），详见下方「六、边界行为」。
+>
+> **② Step2 canonical 快照**（`Step2CanonicalSnapshotService.java:100`，提交
+> `15c7cdd0c`）——**这一处前端可见，是本次追加里最重要的一处**。四步向导第②步选车/选司机页
+> 用的 `POST /admin/fleet/assignments/candidates` 端点（`AssignmentCandidateRespVO
+> .canonicalSnapshot` 字段）此前同样恒读 `context.getVehicleRequirement()`（TRAVEL）。
+> **坏法是静默的**：身份比对（`identityConsistent`）不等时**不抛任何错误码**，只有一条
+> `log.warn("Step2 快照身份不一致，拒绝建快照/更新")`，方法直接 `return null`——调用方拿到的是
+> **一个空字段，不是一次失败**。运营端表现为"四步向导第②步网格出不来"，且**没有任何错误码指向
+> 成因**，排查只能靠日志。已收录为本文档新增的「三、接口详情」第 4 条，详见该节与「六、边界
+> 行为」。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 按需求原子确认 | POST | `/admin/fleet/assignments/requirements/{requirementId}/confirm` | 行为修复（入参/出参契约不变） | `kind=TRANSFER` 需求不再在预检门禁上必现 605905 |
+| 2 | 车务确认执行 | POST | `/admin/fleet/assignments/{assignmentId}/confirm` | 行为修复（入参/出参契约不变） | `kind=TRANSFER` 派车行的 holding 收尾与 ASSIGNED 复核两条内部分支不再必现 605041 |
+| 3 | 修改派单 | POST | `/admin/fleet/assignments/{assignmentId}/change` | 行为修复（入参/出参契约不变） | `kind=TRANSFER` 派车行改派不再必现 605041 |
+| 4 | 查询派单候选资源 | POST | `/admin/fleet/assignments/candidates` | 行为修复（入参/出参契约不变） | `kind=TRANSFER` 需求的 Step2 canonical 快照（`canonicalSnapshot` 字段）不再静默返回 `null` |
+
+> 另有一处**内部作业端点**（不进本表）同根因修复：`POST /internal/fleet/jobs/vehicle-assignment-snapshot/refinalize`，
+> 详见「⚠️ 关键变化」①与「六、边界行为」。
+
+---
+
+## 三、接口详情
+
+### 1. 按当前派车方案代际原子确认全部执行段 `POST /admin/fleet/assignments/requirements/{requirementId}/confirm`
+
+**VO**: `ConfirmRequirementReqVO → ConfirmRequirementRespVO`
+
+#### 使用场景
+
+车务在派单弹窗对某条用车需求下**当前有效的全部执行段**做原子最终确认（#5827 起新派车提交即
+派定，本端点服务"已派定组的复核"与"存量 holding 组的收尾确认"）。本次修复前，若
+`requirementId` 指向一条 `kind=TRANSFER`（接送机）需求，请求会在最早一道版本预检门禁
+（`assertRequirementPreflightVersion`）上必然判定"需求已过期"而拒绝，即使前端刚从看板拉取的
+`expectedRequirementVersion`/`expectedRequirementSha256` 完全正确也一样；修复后该门禁按
+`requirementId` 正确择取 TRANSFER 需求做比对，version/sha256 匹配时可正常通过。
+
+#### 入参（本次零新增/零变化，全量 7 个字段逐一核对源码）
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| requirementId | Path | Long | 是 | - | 当前用车需求 ID；本次修复后，传一条 `kind=TRANSFER` 需求的 ID 时不再必然被判定为版本过期 |
+| orderId | Body | Long | 是 | - | 订单 ID |
+| requestId | Body | String | 是 | ≤64 | 幂等请求标识 |
+| expectedRequirementVersion | Body | Integer | 是 | - | 预期当前有效用车需求版本 |
+| expectedRequirementSha256 | Body | String | 是 | 64 位小写十六进制 | Board 返回的当前用车需求 canonical SHA-256 |
+| expectedPlanGeneration | Body | Long | 是 | - | 预期当前最终派车方案代际 |
+| groups[] | Body | Array | 是 | ≤50 项 | 当前有效执行段精确集合及各段行程短信选择 |
+| groups[].assignmentGroupId | Body | Long | 是 | - | 当前有效派车组 ID |
+| groups[].sendItinerarySms | Body | Boolean | 是 | - | 是否向本执行段司机发送行程短信 |
+
+#### 出参（本次零新增/零变化，全量字段）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| requirementId | String（雪花 ID，Long 转字符串序列化） | 用车需求 ID |
+| dispatchPlanGeneration | String（雪花 ID） | 已确认的最终派车方案代际 |
+| confirmed | Boolean | 整组是否原子确认成功 |
+| finalPlanPublished | Boolean | 本次是否发布了最终方案快照；false 表示确认已成功但订单车控仍为处理中 |
+| groups[] | Array | 各执行段确认结果 |
+| groups[].assignmentId | String（雪花 ID） | 代表派单 ID |
+| groups[].assignmentGroupId | String（雪花 ID） | 派车组 ID |
+| groups[].assignmentStatus | String | 派单状态 |
+| groups[].confirmedAt | LocalDateTime | 车务最终确认时间 |
+| groups[].sendItinerarySms | Boolean | 是否选择发送本段行程短信 |
+| groups[].itinerarySmsEventId | String（雪花 ID，未发送为 null） | 行程短信 Outbox 事件 ID |
+| groups[].itinerarySmsStatus | String | 行程短信状态 |
+| groups[].itineraryUrl | String | 本段电子行程单 H5 链接；签发不可用时为 null |
+
+#### 请求示例
+
+```json
+POST /admin/fleet/assignments/requirements/1934567890123457001/confirm
+{
+  "orderId": 1934567890123456789,
+  "requestId": "confirm-req-20260918-0001",
+  "expectedRequirementVersion": 3,
+  "expectedRequirementSha256": "a1b2c3d4e5f60718293a4b5c6d7e8f90112233445566778899aabbccddeeff",
+  "expectedPlanGeneration": 5,
+  "groups": [
+    {"assignmentGroupId": 1934567890123457100, "sendItinerarySms": true}
+  ]
+}
+```
+
+上例 `requirementId=1934567890123457001` 是一条 `kind=TRANSFER` 需求；本次修复前该请求必返
+605905，version/sha256 是否匹配无关紧要。
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "requirementId": "1934567890123457001",
+    "dispatchPlanGeneration": "5",
+    "confirmed": true,
+    "finalPlanPublished": true,
+    "groups": [
+      {
+        "assignmentId": "1934567890123457100",
+        "assignmentGroupId": "1934567890123457100",
+        "assignmentStatus": "assigned",
+        "confirmedAt": "2026-09-18 15:00:00",
+        "sendItinerarySms": true,
+        "itinerarySmsEventId": "1934567890123457200",
+        "itinerarySmsStatus": "PENDING",
+        "itineraryUrl": "https://h5.example.com/#/itinerary/eyJvcmRlcklkIjoi..."
+      }
+    ]
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+N/A。本端点是需求级原子确认动作，要么全部执行段确认成功并返回完整 `groups[]`，要么整体失败
+关闭返回错误响应；不存在"部分成功"或 `data` 为空数组/null 的成功响应形态。
+
+#### 错误响应
+
+```json
+{
+  "code": 605905,
+  "message": "需求版本过期",
+  "data": null,
+  "success": false
+}
+```
+
+> ⚠️ **响应信封订正**：`Result` 只有 `code`/`message`/`data`/`traceId` 四个字段，业务失败时
+> `code` 本身就是业务错误码，HTTP 状态码固定 200，**不存在独立的 `errorCode` 字段**；
+> `success` 是 `Result.isSuccess()`（`code==200`）序列化出的真实字段。此端点未被
+> Controller 专门 catch，异常经 `GlobalExceptionHandler.handleBusiness` 兜底，`data`
+> 固定为 `null`（不含 `dailyDifferences`，与下面两个端点不同）。
+
+#### 业务边界
+
+- 本次修复前，仅因 `requirementId` 指向 `kind=TRANSFER` 需求就必然命中上面这条 605905，即便
+  `expectedRequirementVersion`/`expectedRequirementSha256` 与前端刚拉取的完全一致；修复后只在
+  需求确实已发生变化（如被他人换版/改派）时才会命中
+- 若通过预检门禁后，在需求级原子确认循环内部（`assertFinalConfirmationBaseline`，
+  `AssignmentService.java:3974`）仍检出基线不一致，同样按 605041
+  （`FINAL_CONFIRMATION_BASELINE_MISMATCH`，"订单行程或用车派单已变化，请按逐日差异处理后
+  重试"）拒绝；但该调用点不经 Controller 的专门 catch，响应 `data` 固定为 `null`，**不返回
+  `dailyDifferences`**（与「2. 车务确认执行」「3. 修改派单」两个端点不同，那两处会返回结构化
+  差异）
+- `kind=TRAVEL` 需求的确认流程、错误码语义与本次改动前逐字一致
+
+---
+
+### 2. 车务确认执行(holding→assigned) `POST /admin/fleet/assignments/{assignmentId}/confirm`
+
+**VO**: `ConfirmReqVO → ConfirmRespVO`
+
+#### 使用场景
+
+两类入口共用本端点：①存量 holding 组的收尾确认；②已派定组的复核——重跑最终确认基线 + 行程
+短信决策一致性校验 + 接送机门禁，通过后重发最终方案快照。本次修复覆盖这两条内部分支
+（holding 收尾在 `AssignmentService.java:4246/4279`，ASSIGNED 复核经
+`revalidateAssignedAfterBaselineChange` 于 `:4462`）对 `kind=TRANSFER` 派车行的基线选取——
+两处修复前都直接读 `context.getVehicleRequirement()`（恒 TRAVEL），派车行的
+`assignmentId` 无论对应哪条需求，基线比对都必然落到 TRAVEL 上。
+
+#### 入参（本次零新增/零变化，全量 5 个字段）
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| assignmentId | Path | Long | 是 | - | 派单 ID；本次修复后，若该行属于 `kind=TRANSFER` 需求，不再必然 605041 |
+| sendItinerarySms | Body | Boolean | 是 | - | 是否在最终确认后向该车师傅发送行程短信 |
+| requestId | Body | String | 是 | ≤64 | 幂等请求标识 |
+| vehicleFeeTotal | Body | BigDecimal | 否 | 已废弃，传值即被拒绝 | 历史字段，最终总车费已改为逐日车费只读合计 |
+| vehicleFeeAdjustmentReason | Body | String | 否 | ≤256，已废弃，传值即被拒绝 | 历史字段，逐日车费调整原因应在派车保存时提交 |
+
+#### 出参（本次零新增/零变化，全量字段，含 `sideEffects`/`dailyDifferences` 展开）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| confirmed | Boolean | 是否已完成最终确认 |
+| assignmentStatus | String | 派单状态(assigned=已派定) |
+| stageCode | String | 生命周期阶段码 |
+| stageLabel | String | 生命周期阶段文案 |
+| currentStep | Integer | 当前三阶段步骤(订单详情/排车/确认执行) |
+| assignmentGroupId | String（雪花 ID） | 派车组 ID(同一辆车连续每日切片共用) |
+| vehicleFeeTotal | String（BigDecimal 转字符串） | 最终确认后的该车本派车段总车费 |
+| vehicleFeeSource | String | 最终总车费来源：AUTO、MANUAL |
+| vehicleFeeAdjustmentReason | String | 手工总车费调整原因 |
+| confirmedAt | LocalDateTime | 车务确认派车时间 |
+| sendItinerarySms | Boolean | 车务是否选择向该车师傅发送行程短信 |
+| itinerarySmsEventId | String（雪花 ID） | 行程短信可靠事件 ID；不发送为空 |
+| itinerarySmsStatus | String | 确认响应中的初始短信状态(PENDING,NOT_SENT) |
+| itineraryUrl | String | 电子行程单 H5 签名链接 |
+| sideEffects | Object | 副作用执行结果，见下方展开 |
+| sideEffects.vehicleStatusUpdated | String | 车辆状态更新结果(idle,busy,maint;不涉及车为 null) |
+| sideEffects.driverStatusUpdated | String | 司机状态更新结果(busy,idle;不涉及司机为 null) |
+| sideEffects.reconPrepRowsCreated | Integer | 对账预备单创建条数(M1 降级恒返 0) |
+| sideEffects.reconPrepMarkedCanceled | Integer | 对账预备单标记取消条数(M1 降级恒返 0) |
+| dailyDifferences | Array | 确认失败时的逐日基线差异；成功时为空 |
+| dailyDifferences[].serviceDate | LocalDate | 服务日 |
+| dailyDifferences[].differenceType | String | 差异类型枚举，见「六.5」 |
+| dailyDifferences[].differenceLabel | String | 差异中文名称 |
+| dailyDifferences[].assignmentId | String（雪花 ID） | 派单 ID |
+| dailyDifferences[].assignmentSlotId | String（雪花 ID） | 稳定车辆槽位 ID |
+| dailyDifferences[].passengerCount | Integer | 订单乘客人数(不含司机) |
+| dailyDifferences[].message | String | 差异说明 |
+
+#### 请求示例
+
+```json
+POST /admin/fleet/assignments/1934567890123457100/confirm
+{
+  "sendItinerarySms": true,
+  "requestId": "fleet-final-confirm-20260918-0001"
+}
+```
+
+上例 `assignmentId=1934567890123457100` 是一条挂在 `kind=TRANSFER` 需求下的派车行；本次修复前
+该请求必返 605041。
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "confirmed": true,
+    "assignmentStatus": "assigned",
+    "stageCode": "assigned",
+    "stageLabel": "已派车",
+    "currentStep": 3,
+    "assignmentGroupId": "1934567890123457100",
+    "vehicleFeeTotal": "700.00",
+    "vehicleFeeSource": "AUTO",
+    "vehicleFeeAdjustmentReason": null,
+    "confirmedAt": "2026-09-18 15:05:00",
+    "sendItinerarySms": true,
+    "itinerarySmsEventId": "1934567890123457200",
+    "itinerarySmsStatus": "PENDING",
+    "itineraryUrl": "https://h5.example.com/#/itinerary/eyJvcmRlcklkIjoi...",
+    "sideEffects": {
+      "vehicleStatusUpdated": "busy",
+      "driverStatusUpdated": "busy",
+      "reconPrepRowsCreated": 0,
+      "reconPrepMarkedCanceled": 0
+    },
+    "dailyDifferences": null
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+N/A。本端点确认成功时恒返回完整对象（`sideEffects` 各字段可能为 null，但不是"空数据"形态）；
+失败时按下方错误响应返回，不存在中间态。
+
+#### 错误响应
+
+```json
+{
+  "code": 605041,
+  "message": "订单行程或用车派单已变化，请按逐日差异处理后重试",
+  "data": {
+    "confirmed": false,
+    "dailyDifferences": [
+      {
+        "serviceDate": null,
+        "differenceType": "REQUIREMENT_VERSION_MISMATCH",
+        "differenceLabel": "用车需求已更新",
+        "assignmentId": "1934567890123457100",
+        "assignmentSlotId": "1934567890123457099",
+        "passengerCount": null,
+        "message": "用车需求已更新，请刷新后按最新需求重新派车"
+      }
+    ]
+  },
+  "success": false
+}
+```
+
+#### 业务边界
+
+- 本次修复前，`kind=TRANSFER` 派车行走 holding 收尾确认或 ASSIGNED 复核任一分支都**必现**
+  605041，与请求体字段是否正确无关（两条分支都不接受调用方传 `requirementId`，只能按
+  `assignmentId` 反查行、再拿上下文里恒为 TRAVEL 的需求比对）；修复后按该行自己的
+  `requirementId` 正确匹配 TRANSFER 需求
+- 若基线确实发生变化（如换版、需求被取消），仍会返回 605041 及 `data.dailyDifferences`，与本次
+  改动前逐字一致；前端展示优先用 `differenceLabel`/`message`，`differenceType` 仅供逻辑判断
+- `kind=TRAVEL` 派车行的确认流程、`sideEffects`/`dailyDifferences` 语义与本次改动前逐字一致
+- 旧 HOLD 通知结果仍在确认中的场景（605042 等）不在本次修复范围内，行为未变
+
+---
+
+### 3. 修改派单(按槽位和生效日) `POST /admin/fleet/assignments/{assignmentId}/change`
+
+**VO**: `ChangeAssignmentReqVO → ChangeAssignmentRespVO`
+
+#### 使用场景
+
+按稳定车辆槽位和生效日原子换车、换司机或同时替换；改派恒执行最终基线复核。本次修复覆盖
+`doChangeInLock` 内部对 `kind=TRANSFER` 派车行的基线选取（`AssignmentService.java:5848` 附近，
+修复前 `assertFinalConfirmationBaseline` 的 `requirementOverride` 显式传 `null`，回退读
+`context.getVehicleRequirement()` 恒为 TRAVEL）。
+
+#### 入参（本次零新增/零变化，全量 14 个字段，含嵌套 `dailyVehicleFees[]`）
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| assignmentId | Path | Long | 是 | - | 当前车辆槽位任一派单 ID；本次修复后，若该行属于 `kind=TRANSFER` 需求，不再必然 605041 |
+| effectiveDate | Body | LocalDate | 是 | - | 改派生效日(含当日) |
+| serviceDates | Body | Array\<LocalDate\> | 否 | - | 按天改派限定的服务日期集；空=生效日起连续后缀整体改派 |
+| newVehicleId | Body | Long | 否 | - | 新车辆 ID；不换车可空 |
+| newDriverId | Body | Long | 否 | - | 新司机 ID；不换司机可空 |
+| sendItinerarySms | Body | Boolean | 否 | 不传按 false | 是否向改派后的师傅发送行程短信 |
+| holdMode | Body | Integer | 否 | 已废弃，服务端忽略 | #5827 起一律一步派定，勿再传 |
+| messageTemplateId | Body | Long | 否 | 已废弃 | 不再消费 |
+| customBody | Body | String | 否 | ≤4000，已废弃 | 不再消费 |
+| protocolPrice | Body | BigDecimal | 否 | ≥0.00，整数最多10位/小数最多2位 | 新协议价日单价；可空按价格日历计算 |
+| vehicleFeeTotal | Body | BigDecimal | 否 | 已废弃，传值即被拒绝 | 历史字段 |
+| vehicleFeeAdjustmentReason | Body | String | 否 | ≤256 | 新派车段单日车费与价格日历不一致时的调整原因 |
+| dailyVehicleFees[] | Body | Array | 否 | - | 新派车段逐日车费；未提交的收费日按价格日历取价 |
+| dailyVehicleFees[].serviceDate | Body | LocalDate | 是（数组项内） | - | 车费服务日期 |
+| dailyVehicleFees[].price | Body | BigDecimal | 是（数组项内） | ≥0.00 | 本次派车单日车费；只覆盖本次派车，不回写价格日历 |
+| retainedVehicleFeeTotal | Body | BigDecimal | 否 | 已废弃，传值即被拒绝 | 历史字段 |
+| retainedVehicleFeeAdjustmentReason | Body | String | 否 | ≤256，已废弃 | 历史字段 |
+| chargeableServiceDates | Body | Array\<LocalDate\> | 否 | - | 生效日起收取车费的服务日期；不传沿用原值 |
+| vehicleFeeWaiverReason | Body | String | 否 | ≤256 | 免费服务日原因；全部免费时必填 |
+| confirmAllServiceDatesFree | Body | Boolean | 否 | - | 目标日期全部免费二次确认 |
+| confirmCrossResident | Body | Boolean | 否 | - | 跨常驻车显式确认 |
+| reason | Body | String | 是 | ≤256 | 修改原因 |
+| requestId | Body | String | 是 | ≤64 | 请求幂等 ID |
+
+#### 出参（本次零新增/零变化，全量字段，含 `otherVehicles[]`/`dailyVehicleFees[]`/`dailyDifferences[]` 展开）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| assignmentId | String（雪花 ID） | 新派单锚点 ID |
+| assignmentSlotId | String（雪花 ID） | 稳定车辆槽位 ID；改派前后保持不变 |
+| previousAssignmentGroupId | String（雪花 ID） | 被替换的旧派车组 ID |
+| newAssignmentGroupId | String（雪花 ID） | 新派车组 ID |
+| assignmentStatus | String | 新派车组状态 |
+| effectiveDate | LocalDate | 改派实际生效日(含当日) |
+| affectedDays | Integer | 本次原子替换的逐日切片数量 |
+| protocolPrice | String（BigDecimal 转字符串） | 新协议价日单价快照(元/车天) |
+| vehicleFeeAutoTotal | String（BigDecimal） | 改派后价格日历自动合计参考 |
+| vehicleFeeAutoComplete | Boolean | 改派后自动合计是否覆盖全部计费服务日 |
+| vehicleFeeTotal | String（BigDecimal） | 改派后新派车段逐日车费只读合计 |
+| vehicleFeeSource | String | 改派后总车费来源：AUTO、MANUAL、INCOMPLETE |
+| vehicleFeeAdjustmentReason | String | 改派后单日车费调整原因 |
+| dailyVehicleFees[] | Array | 改派后逐日价格日历参考价和本次派车价 |
+| dailyVehicleFees[].serviceDate | LocalDate | 服务日期 |
+| dailyVehicleFees[].chargeable | Boolean | 是否收取车费 |
+| dailyVehicleFees[].calendarPrice | String（BigDecimal） | 车型价格日历参考价；缺价为空 |
+| dailyVehicleFees[].assignmentPrice | String（BigDecimal） | 本次派车单日车费；收费日必有值 |
+| dailyVehicleFees[].source | String | 价格来源：CALENDAR、OVERRIDE、FREE、MISSING |
+| dailyVehicleFees[].calendarPriceMissing | Boolean | 价格日历是否缺价 |
+| otherVehicleCount | Integer | 同订单其它有效车辆槽位数 |
+| warningCode | String | 强提示代码；无其它车辆时为空 |
+| warningMessage | String | 强提示文案；无其它车辆时为空 |
+| otherVehicles[] | Array | 同订单其它有效车辆摘要 |
+| otherVehicles[].assignmentSlotId | String（雪花 ID） | 其它稳定车辆槽位 ID |
+| otherVehicles[].vehiclePlate | String | 当前车牌号 |
+| otherVehicles[].driverName | String | 当前司机名称 |
+| otherVehicles[].startDate | LocalDate | 当前有效服务日起 |
+| otherVehicles[].endDate | LocalDate | 当前有效服务日止 |
+| sendItinerarySms | Boolean | 车务本次是否选择向改派后的师傅发送行程短信 |
+| itinerarySmsEventId | String（雪花 ID） | 行程短信可靠事件 ID；未勾选发送为空 |
+| itinerarySmsStatus | String | 本次改派的初始短信状态(PENDING,NOT_SENT) |
+| dailyDifferences[] | Array | 改派最终派定失败时的逐日基线差异（结构同「2. 车务确认执行」的 `dailyDifferences`） |
+
+#### 请求示例
+
+```json
+POST /admin/fleet/assignments/1934567890123457100/change
+{
+  "effectiveDate": "2026-10-11",
+  "newVehicleId": 1934567890123456701,
+  "newDriverId": 1934567890123456702,
+  "sendItinerarySms": false,
+  "reason": "司机临时无法执行，替换车辆和司机",
+  "requestId": "change-20260918-0001"
+}
+```
+
+上例 `assignmentId=1934567890123457100` 是一条挂在 `kind=TRANSFER` 需求下的派车行；本次修复前
+该请求必返 605041。
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "assignmentId": "1934567890123457300",
+    "assignmentSlotId": "1934567890123457099",
+    "previousAssignmentGroupId": "1934567890123457100",
+    "newAssignmentGroupId": "1934567890123457300",
+    "assignmentStatus": "assigned",
+    "effectiveDate": "2026-10-11",
+    "affectedDays": 1,
+    "protocolPrice": "1688.00",
+    "vehicleFeeAutoTotal": "1688.00",
+    "vehicleFeeAutoComplete": true,
+    "vehicleFeeTotal": "1688.00",
+    "vehicleFeeSource": "AUTO",
+    "vehicleFeeAdjustmentReason": null,
+    "dailyVehicleFees": [
+      {
+        "serviceDate": "2026-10-11",
+        "chargeable": true,
+        "calendarPrice": "1688.00",
+        "assignmentPrice": "1688.00",
+        "source": "CALENDAR",
+        "calendarPriceMissing": false
+      }
+    ],
+    "otherVehicleCount": 0,
+    "warningCode": null,
+    "warningMessage": null,
+    "otherVehicles": [],
+    "sendItinerarySms": false,
+    "itinerarySmsEventId": null,
+    "itinerarySmsStatus": "NOT_SENT",
+    "dailyDifferences": null
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+N/A。本端点改派成功时恒返回完整对象（`otherVehicles` 无其它车辆时为空数组而非缺失字段）；
+失败时按下方错误响应返回。
+
+#### 错误响应
+
+```json
+{
+  "code": 605041,
+  "message": "订单行程或用车派单已变化，请按逐日差异处理后重试",
+  "data": {
+    "dailyDifferences": [
+      {
+        "serviceDate": null,
+        "differenceType": "REQUIREMENT_VERSION_MISMATCH",
+        "differenceLabel": "用车需求已更新",
+        "assignmentId": "1934567890123457100",
+        "assignmentSlotId": "1934567890123457099",
+        "passengerCount": null,
+        "message": "用车需求已更新，请刷新后按最新需求重新派车"
+      }
+    ]
+  },
+  "success": false
+}
+```
+
+#### 业务边界
+
+- 本次修复前，`kind=TRANSFER` 派车行改派**必现** 605041，与请求体字段是否正确无关（`change`
+  端点不接受调用方传 `requirementId`，只能按 `assignmentId` 反查所属行，再拿上下文里恒为 TRAVEL
+  的需求比对）；修复后按该行自己的 `requirementId` 正确匹配 TRANSFER 需求
+- 若基线确实发生变化，仍会返回 605041 及 `data.dailyDifferences`，与本次改动前逐字一致
+- 同订单存在其它车辆槽位时仍返回 `warningCode=ORDER_HAS_OTHER_VEHICLES` 及摘要，前端仍须强提示
+  （行为未变）
+- `kind=TRAVEL` 派车行的改派流程、错误码语义与本次改动前逐字一致
+
+---
+
+### 4. 查询派单候选资源 `POST /admin/fleet/assignments/candidates`
+
+**VO**: `AssignmentCandidateReqVO → AssignmentCandidateRespVO`
+
+> ⚠️ **本节范围声明**：本端点是派单弹窗车辆/司机候选查询的既有端点，入参 24 个字段、出参
+> 涵盖车辆候选、司机候选、常驻关系、动态筛选项等一整套与本次修复无关的结构。**本次修复只影响
+> 出参里的 `canonicalSnapshot` 一个字段**（及其内部 `resolveCanonicalSnapshot` 的基线选取逻辑），
+> 下方入参/出参表**只列与本次修复直接相关的字段**，其余约 20 个入参字段与 `vehicles[]`/
+> `drivers[]`/`fleetTeamFacets[]`/`vehicleTypeFacets[]`/`selectedDriverResidentVehicle` 等
+> 出参结构本次**零改动**，未逐一列出。
+
+#### 使用场景
+
+四步向导第②步（选车/选司机）加载页面时调用。本次修复前，若 `requirementId` 指向一条
+`kind=TRANSFER`（接送机）需求，响应里 `vehicles[]`/`drivers[]` 等候选数据正常返回，但
+**`canonicalSnapshot` 字段恒为 `null`**——`Step2CanonicalSnapshotService.resolveCanonicalSnapshot`
+内部的 `identityConsistent` 身份比对拿 `context.getVehicleRequirement()`（恒 TRAVEL）与请求的
+`requirementId`（TRANSFER）比对，必不等，**不抛错误码，只打一条 `log.warn` 后直接返回 `null`**。
+运营端表现为"网格出不来"，没有任何错误提示能指向成因。修复后 `Step2CanonicalSnapshotService`
+与 `AssignmentService` 共用新抽出的 `BaselineRequirementSelector.select(requirementId, context)`
+按请求自己的 `requirementId` 正确择取 TRANSFER 需求。
+
+**可验证的效果句**（工单 #7443 AC-24 给定判据）：对一条 `kind=TRANSFER` 的活跃需求调
+`resolveCanonicalSnapshot`(该 `requirementId`)，返回非 `null`，且 `editableServiceDates`
+恰为该需求的两条航班日、`cells` 覆盖这两日、其中已派车那一日的 cell `used = "USED"` 且
+`assignmentId` 指向该派车行。
+
+#### 入参（本节只列与本次修复相关的字段；其余约 20 个字段本次零改动，未列出）
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| orderId | Body | Long | 改派排除自身时必填 | - | 当前订单 ID |
+| requirementId | Body | Long | 改派排除自身时必填 | - | 当前用车需求 ID；本次修复后，传一条 `kind=TRANSFER` 需求的 ID 时 `canonicalSnapshot` 不再必然为 `null` |
+
+#### 出参（本节只列 `canonicalSnapshot` 极其内部结构；`vehicles[]`/`drivers[]`/其余顶层字段本次零改动，未列出）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| canonicalSnapshot | Object | Step2 canonical full snapshot；无 `requirementId` 或需求上下文不可用时为 `null`（本次修复前，`kind=TRANSFER` 需求也会落入这个 `null`，是本次修复的对象） |
+| canonicalSnapshot.planGeneration | String（雪花 ID，`required=true`） | 当前计划代际（不透明令牌） |
+| canonicalSnapshot.snapshotVersion | String（雪花 ID，`required=true`） | 当前快照版本；同代内容修订递增 |
+| canonicalSnapshot.retainedGroupIds | Array\<String\>（`required=true`） | 有序 RetainedGroupSet：稳定派车组 ID |
+| canonicalSnapshot.editableServiceDates | Array\<LocalDate\>（`required=true`） | 完整有序可编辑服务日集合 |
+| canonicalSnapshot.cells | Array（`required=true`） | 每个派车组×服务日笛卡尔积位置唯一 cell |
+| canonicalSnapshot.cells[].groupId | String（雪花 ID） | 稳定派车组 ID |
+| canonicalSnapshot.cells[].serviceDate | LocalDate | 服务日期 |
+| canonicalSnapshot.cells[].assignmentId | String（雪花 ID） | 当天逐日派车行 ID；无行为 null |
+| canonicalSnapshot.cells[].used | String | `USED`=实际用车／`UNUSED`=显式不用车／`null`=无切片行 |
+| canonicalSnapshot.cells[].readOnly | Boolean | 该 cell 是否只读 |
+| canonicalSnapshot.cells[].vehicleId | String（雪花 ID） | 当天车辆 ID |
+| canonicalSnapshot.cells[].driverId | String（雪花 ID） | 当天司机 ID |
+| canonicalSnapshot.selectedVehicle | Object | 已选车辆最小脱敏展示快照；未选为 null（结构未动） |
+| canonicalSnapshot.selectedDriver | Object | 已选司机最小脱敏展示快照；未选为 null（结构未动） |
+
+> `CanonicalSnapshotVO` 五个 `required=true` 字段（`planGeneration`/`snapshotVersion`/
+> `retainedGroupIds`/`editableServiceDates`/`cells`）是 **Swagger 注解表达的契约意图，不是
+> 运行时观测**——它们只在 `canonicalSnapshot` 本身非 `null` 时必然存在；`canonicalSnapshot`
+> 整体为 `null` 时这五个字段自然也拿不到。`Swagger required` 描述的是"存在时必填"，不是
+> "恒存在"。
+
+#### 请求示例
+
+```json
+POST /admin/fleet/assignments/candidates
+{
+  "orderId": 1934567890123456789,
+  "requirementId": 1934567890123457001,
+  "startDate": "2026-10-11",
+  "endDate": "2026-10-17",
+  "vehiclePage": 1,
+  "vehiclePageSize": 20,
+  "driverPage": 1,
+  "driverPageSize": 20
+}
+```
+
+上例 `requirementId=1934567890123457001` 是一条 `kind=TRANSFER` 需求；本次修复前
+`data.canonicalSnapshot` 必为 `null`（`vehicles`/`drivers` 等其余字段不受影响，正常返回）。
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "canonicalSnapshot": {
+      "planGeneration": "1934567890123457500",
+      "snapshotVersion": "1",
+      "retainedGroupIds": ["1934567890123457100"],
+      "editableServiceDates": ["2026-10-11", "2026-10-17"],
+      "cells": [
+        {
+          "groupId": "1934567890123457100",
+          "serviceDate": "2026-10-11",
+          "assignmentId": "1934567890123457100",
+          "used": "USED",
+          "readOnly": false,
+          "vehicleId": "2064998142394183681",
+          "driverId": "2065272150960357378"
+        },
+        {
+          "groupId": "1934567890123457100",
+          "serviceDate": "2026-10-17",
+          "assignmentId": null,
+          "used": null,
+          "readOnly": false,
+          "vehicleId": null,
+          "driverId": null
+        }
+      ],
+      "selectedVehicle": null,
+      "selectedDriver": null
+    }
+  },
+  "success": true
+}
+```
+
+（省略号：本响应实际还含 `vehicles`/`drivers`/`fleetTeamFacets` 等与本次修复无关的字段，
+上例只展示 `canonicalSnapshot`。）
+
+#### 空数据 / 降级响应
+
+`canonicalSnapshot` 为 `null` 是本端点**合法的既有降级形态**，不是本次修复要消灭的东西——
+未传 `requirementId`、或需求上下文确实不可达（如 809007 服务日未回填导致
+`transferVehicleRequirement` 也取不到）时，`canonicalSnapshot` 仍然合法为 `null`。本次修复只
+消灭了"`requirementId` 合法指向一条**存在**的 TRANSFER 需求，却因基线选错而被误判身份不一致"
+这一种 `null` 成因；其余合法 `null` 成因不受影响。
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "canonicalSnapshot": null
+  },
+  "success": true
+}
+```
+
+#### 错误响应
+
+本端点的 `canonicalSnapshot` 解析路径**不抛错误码**（这正是「使用场景」里描述的"坏法是静默的"）；
+`resolveCanonicalSnapshot` 内部锁获取失败时会抛 `CommonErrorCode.RESOURCE_LOCKED`
+（`hl-common-core/.../CommonErrorCode.java:67-68`），但这是既有的锁竞争兜底，与本次修复的身份
+比对分支无关，本次未改动：
+
+```json
+{
+  "code": 100503,
+  "message": "资源被占用,请稍后重试",
+  "data": null,
+  "success": false
+}
+```
+
+#### 业务边界
+
+- 🔴 **本条【假设】未验证，请 mmg 自验**：`canonicalSnapshot` 为 `null` 时四步向导第②步前端
+  会表现出什么效果（空白网格/报错提示/直接不可操作），本单**没有测试前端行为**，不替前端下
+  结论。上文"运营看到网格出不来"是问题背景陈述，不是对当前前端代码行为的实测断言
+- `canonicalSnapshot` 为 `null` 与"请求本身失败"是两回事：响应 `code` 仍是 200、`success`
+  仍是 `true`，`vehicles[]`/`drivers[]` 等其余候选数据不受影响，只有这一个字段拿不到
+- `kind=TRAVEL` 需求的 `canonicalSnapshot` 解析行为逐字不变
+- 本条修复与本文档前三条同根因、同修法（`BaselineRequirementSelector`），但触发路径不同
+  （前三条走 HTTP 错误响应，这一条走静默降级字段），前端排查时不能用同一套"看错误码"的思路
+
+---
+
+## 四、契约约束与正确调用方式
+
+> 本节只写后端接受/拒绝 payload 的规则，不写 UI 渲染建议。
+
+| 场景 | 做法 |
+|------|------|
+| `requirementId`/`assignmentId` 指向一条 `kind=TRANSFER` 需求/派车行 | 三个端点的请求体格式**不需要任何调整**——与 `kind=TRAVEL` 完全一样传参即可，fleet 内部会自动按行/需求自己的 ID 择基线 |
+| `POST /requirements/{id}/confirm` 拿到 605905 | 与本次修复前不同：现在**只**代表需求版本确实过期（被他人换版/改派），需要重新拉取最新的 `expectedRequirementVersion`/`expectedRequirementSha256` 后重试，**不再**是"TRANSFER 需求天生用不了这个端点"的信号 |
+| `POST /{assignmentId}/confirm`、`POST /{assignmentId}/change` 拿到 605041 | 同上，现在只代表基线确实变化，按 `data.dailyDifferences[].differenceLabel`/`message` 提示用户刷新重试 |
+| 需要创建/查询一条真实的 `kind=TRANSFER` 需求用于联调 | 目前仍需 SQL 直接构造（上游写口 809009 未开放），不在本次修复范围内 |
+
+---
+
+## 五、数据库行为
+
+| 操作 | 影响 |
+|------|------|
+| `kind=TRANSFER` 派车行调用上述三接口，基线校验通过 | 与 `kind=TRAVEL` 完全相同的既有落库逻辑（`fleet_assignment` 状态流转、`confirmed_at`/`assignment_status` 等列更新），不因 `kind` 不同而有任何额外列或额外写入 |
+| `kind=TRANSFER` 派车行调用上述三接口，基线校验未通过（需求确实已变化） | 与 `kind=TRAVEL` 相同：整体拒绝，不落库，不改变已有行状态 |
+| `kind=TRAVEL` 派车行调用上述三接口 | 落库行为与本次改动前逐字一致 |
+| `OrderFleetDetailContextDTO` 新增字段 `transferVehicleRequirement` | 纯内存态 Feign 响应字段，不对应任何新增数据库列 |
+
+---
+
+## 六、边界行为
+
+- `transferVehicleRequirement` 为 `null` 的三种合法情形（源码 javadoc 逐字，
+  `OrderFleetProviderService.java:336-354`）：①该订单没有接送机需求（绝大多数订单）；
+  ②接送机需求存在但服务日尚未回填（809007 降级为 `null`，不让整个订单车务详情报错）；
+  ③订单已终态。三种情形下 `baselineRequirementFor` 都会回退到 `vehicleRequirement`（TRAVEL），
+  行为与改动前一致
+- 服务日尚未回填的 `kind=TRANSFER` 需求：本次修复**不改变**这类需求仍无法被正常操作的事实
+  （`transferVehicleRequirement` 取不到即为 `null`，三端点仍按原口径拒绝）；服务日回填属
+  #7443 AC-6~9 范畴，已于今天早些时候的 PR #7911/#7912/#7913 交付（见
+  `18_7443_接送机用车需求分叉…` 文档）
+- `POST /requirements/{requirementId}/confirm` 对 `kind=TRANSFER` 的实际可观测报错是
+  **605905**（`assertRequirementPreflightVersion` 更早触发的预检门禁），不是 605041——本条
+  订正了 2026-09-18 早些时候 `17_7443_*.md`/`18_7443_接送机用车需求分叉…` 两份文档"三处均
+  605041"的表述，理由与出处见上方「⚠️ 关键变化」
+- `POST /{assignmentId}/confirm`、`POST /{assignmentId}/change` 对 `kind=TRANSFER` 的实际可
+  观测报错才是 605041
+- 本次修复还覆盖了一处**非 HTTP 端点**的内部判据：`isRequirementEligibleForReopen`
+  （`AssignmentService.java:9135`，commit 内注释标注"第 4 个落点"）。它被两条异步补偿链路调用
+  （`AssignmentLifecycleOutboxEffectService.java:136` 撤销"整段不用车"声明后的需求重开、`:264`
+  取消派车后的补偿重开），修复前对 `kind=TRANSFER` 需求恒返回 `false`，两条补偿链路对接送机
+  需求整条失效（需求会卡在 `DONE`/`PROCESSING` 不自愈，且不报任何错误）。前端**无法直接感知**
+  这一点——它不产生任何同步 HTTP 响应，只在"撤销不用车声明"或"取消已派车后需求应否被重开"的
+  排查场景可能相关，记录于此供后续问题定位参考
+- **`refinalizeFinalSnapshot`（内部作业端点，提交 `694e405fd`，`AssignmentService.java:13092`）**：
+  与 `isRequirementEligibleForReopen` 同形，入参 `requirementId` 由
+  `FleetJobInternalController`（`POST /internal/fleet/jobs/vehicle-assignment-snapshot/refinalize`）
+  原样传入、不带 `kind`，修复前恒读 `context.getVehicleRequirement()`（TRAVEL），TRANSFER 需求
+  进来在 `:13096-13098` 的身份比对上必然不等，**整条重发最终方案快照的补偿链路对 TRANSFER
+  不可用**。抛出的错误码是 **605905**（`REQUIREMENT_VERSION_EXPIRED`，"需求版本过期"）——
+  ⚠️ 该方法的源码注释与提交信息把这里写成"报 605036"，经对照 `:13097-13098` 的实际
+  `throw` 语句核实为**笔误**（605036 是 `CROSS_RESIDENT_CONFIRMATION_REQUIRED`，"司机与车辆
+  不是常驻组合"，与本方法无关），本文档按源码实测的 605905 记录。本端点不面向 admin 前端，
+  不进「二、变更接口清单」
+- **Step2 canonical 快照（提交 `15c7cdd0c`，`Step2CanonicalSnapshotService.java:100`）**：
+  详见「三、接口详情」第 4 条。补充一点边界行为——`identityConsistent` 的身份比对**除
+  `requirementId` 外还比对 `orderId`**（`Step2CanonicalSnapshotService.java:136-154`），本次
+  修复只解决了 `requirementId` 因恒读 TRAVEL 而误判的那部分；若 `orderId` 本身传错，
+  修复前后同样会被判定"身份不一致"并静默返回 `null`，这不是本次修复要处理的场景
+- **`BaselineRequirementSelector`（提交 `15c7cdd0c`，`assignment/support/` 新增类）**：原来
+  fleet 内部只有 `AssignmentService` 私有方法 `baselineRequirementFor` 一份择基线逻辑，本次
+  抽成独立静态工具类 `BaselineRequirementSelector.select(requirementId, context)`，
+  `AssignmentService`（确认/改派/复验/重开/重发快照五处）与 `Step2CanonicalSnapshotService`
+  （候选查询一处）共用同一份实现（CODE_RULES §15.7 对称子域禁镜像重复）。这是**内部重构，不
+  改变任何对外行为或字段**，此处只作记录，不影响上面任何一条边界行为
+- `kind=TRAVEL` 派车行三个端点、`isRequirementEligibleForReopen`、`refinalizeFinalSnapshot`、
+  Step2 canonical 快照的全部行为逐字不变（`baselineRequirementFor`/`BaselineRequirementSelector`
+  对非 TRANSFER 命中的 `requirementId` 一律回退到原 `context.getVehicleRequirement()`）
+- 本次修复零 DB 迁移，不改变 `fleet_assignment`/`vehicle_requirement` 任一张表结构
+- 上游 `PUT /v3/admin/order/{id}/vehicle-requirement` 传 `kind=TRANSFER` 的写口仍然关着
+  （809009，`transfer-kind-submit-enabled` 默认 `false`），本次修复**不改变这一点**——没有这个
+  开关，生产环境依然造不出真实的 TRANSFER 需求；本次修复只在"已经存在一条 TRANSFER 需求/
+  派车行（如通过 SQL 构造，或未来开关打开后）"的前提下起作用
+
+---
+
+## 六.5 枚举（本次不新增错误码，以下为本次行为直接相关的既有错误码）
+
+| 错误码 | 常量名 | 文案 | 触发位置 |
+|--------|--------|------|----------|
+| 605905 | `REQUIREMENT_VERSION_EXPIRED` | 需求版本过期 | `assertRequirementPreflightVersion`（`AssignmentService.java:3567-3583`），`POST /requirements/{id}/confirm` 专属预检门禁；同码也是内部作业端点 `refinalizeFinalSnapshot`（`:13096-13098`）的身份不一致分支，见「六、边界行为」 |
+| 605041 | `FINAL_CONFIRMATION_BASELINE_MISMATCH` | 订单行程或用车派单已变化，请按逐日差异处理后重试 | `assertFinalConfirmationBaseline`（`AssignmentService.java:4644` 起），`POST /{assignmentId}/confirm`、`POST /{assignmentId}/change` 及 `POST /requirements/{id}/confirm` 内部循环共用 |
+
+> ⚠️ **Step2 canonical 快照（`POST /admin/fleet/assignments/candidates` 的 `canonicalSnapshot`
+> 字段）没有对应错误码**——它的身份不一致分支（`identityConsistent` 判 false）走的是
+> `return null` + `log.warn`，不抛任何 `IErrorCode`。上表只覆盖会抛错误码的场景，`canonicalSnapshot`
+> 为 `null` 的排查请走「三、接口详情」第 4 条，不要在这张表里找它的错误码——它没有。
+
+**`dailyDifferences[].differenceType` 允许值**（既有枚举，本次未新增，仅在 605041 场景可能
+出现）：`REQUIREMENT_VERSION_MISMATCH` / `ORDER_DATE_MISMATCH` / `ITINERARY_DATE_MISMATCH` /
+`ASSIGNMENT_DATE_MISSING` / `ASSIGNMENT_DATE_EXTRA` / `HEADCOUNT_BASELINE_MISMATCH`。
+
+---
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 |
+|------|------|------|
+| `OrderFleetDetailContextDTO.transferVehicleRequirement`（`hl-common-core`，fleet↔order-v3 内部 Feign 契约，前端不可见） | 不存在 | 新增可空字段，携带订单当前生效的 `kind=TRANSFER` 需求 |
+| 四个端点（confirmRequirement/confirm/change/candidates）的请求体、响应体字段 | — | **零变化**，本次不涉及任何 ReqVO/RespVO 字段增删（`canonicalSnapshot` 及其内部字段结构不变，只是不再必然为 `null`） |
+| `AssignmentService.baselineRequirementFor` 的实现 | 内联逻辑 | 委托给新抽出的 `BaselineRequirementSelector.select`（内部重构，行为等价） |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| `POST /requirements/{id}/confirm` 对 `kind=TRANSFER` 需求 | 必现 605905（`assertRequirementPreflightVersion` 恒判需求已过期） | version/sha256 匹配时正常通过 |
+| `POST /{assignmentId}/confirm` 对 `kind=TRANSFER` 派车行（holding 收尾 + ASSIGNED 复核两条分支） | 必现 605041 | 基线一致时正常确认为 `assigned` |
+| `POST /{assignmentId}/change` 对 `kind=TRANSFER` 派车行 | 必现 605041 | 基线一致时正常改派 |
+| `isRequirementEligibleForReopen`（内部，两条异步补偿链路） | 对 `kind=TRANSFER` 需求恒返 `false`，重开补偿失效且无报错 | 按该需求自己的 `requirementId` 正确判定 |
+| `refinalizeFinalSnapshot`（内部作业端点） | 对 `kind=TRANSFER` 需求必现 605905，重发快照补偿失效 | 按入参 `requirementId` 正确判定 |
+| `POST /admin/fleet/assignments/candidates` 的 `canonicalSnapshot` 字段（对 `kind=TRANSFER` 需求） | **静默**恒为 `null`，不抛任何错误码 | `requirementId`/`orderId` 身份一致时返回正常快照 |
+| `kind=TRAVEL` 上述全部行为 | — | 逐字不变 |
+
+---
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 否。三个端点入参/出参零变化，`OrderFleetDetailContextDTO` 只新增
+  可空字段（纯增量），TRAVEL 行为逐字不变
+- **前端是否必须同步上线**: 否。本次不涉及任何前端可见的请求/响应契约变更，不需要改代码。
+  仅供知悉：`18_7443_接送机用车需求分叉…` 文档里"前端本版暂缓接入 TRANSFER 派车行确认/改派"
+  的限制，在这三个端点自身维度已解除；但上游 809009 写口未开放，测试环境目前仍无法通过正常
+  业务流程产出可联调的 TRANSFER 数据（见「七、不影响范围」）
+- **前端 workaround 清理点**: 无（此前未要求前端做任何 workaround，只是要求暂缓接入）
+- **数据**: 无需迁移，本次零 DB 迁移
+
+---
+
+## 七、不影响范围
+
+- **仅影响**: 管理后台车务派单弹窗——`POST /requirements/{id}/confirm`、
+  `POST /{assignmentId}/confirm`、`POST /{assignmentId}/change`、
+  `POST /admin/fleet/assignments/candidates` 四个既有端点对 `kind=TRANSFER`
+  对象（派车行/需求/候选查询）的内部基线选取逻辑；以及一处不面向 admin 前端的内部作业端点
+  `POST /internal/fleet/jobs/vehicle-assignment-snapshot/refinalize`
+- **零影响**:
+  - 四个端点自身的请求体、响应体字段结构（零新增/零删除/零改名）
+  - `kind=TRAVEL` 派车行/需求在这四个端点的全部行为
+  - `POST /admin/fleet/assignments/batch`（批量创建）、`PUT /pickup-dropoff-config`
+    （接送机配置）——两者的 `kind=TRANSFER` 基线复核缺口已由今天早些时候的 PR #7913
+    单独修复（见 `18_7443_接送机用车需求分叉…` 文档），与本次修复是同一根因的两个不同修复点
+  - 单笔创建派单 `POST /admin/fleet/assignments`（该端点无本次改动涉及的基线复核缺口）
+  - 取消派单 `DELETE /{assignmentId}`、司机拒接 `POST /{assignmentId}/driver-reject`、软清
+    `POST /{assignmentId}/soft-clear-assignment`、撤销取消 `POST /{assignmentId}/restore-cancel`、
+    提前完结 `POST /{assignmentId}/early-complete`、行程短信查询/重发、一键重派推荐等其余端点
+  - `fleet_assignment`/`vehicle_requirement` 数据库表结构（零迁移）
+  - 上游 `PUT /v3/admin/order/{id}/vehicle-requirement` 传 `kind=TRANSFER` 的写口现状
+    （809009 仍未开放，不受本次修复影响）
+  - 看板列表、矩阵日订单等只读查询接口
+
+---
+
+## 部署清单（本单改了 hl-common-core，CODE_RULES §16.6）
+
+本单在 `hl-common-core` 新增了字段（`OrderFleetDetailContextDTO.transferVehicleRequirement`）。
+按 CODE_RULES §16.6，**共享 jar 变了行为就变了，部署时全部消费方必须一起滚**，不能只滚
+`hl-fleet-service`/`hl-order-service-v3` 这两个直接改代码的服务。
+
+⚠️ **消费方清单不能按 `pom.xml` 直接依赖关系查**（2026-09-18 实测教训）：
+`grep -rl 'hl-common-core' */pom.xml` 的结果里 **order-v3、fleet、user、resource、
+product-v2、mp 一个都没有**——它们全部经 `hl-common-web`（本身声明 `hl-common-core` 依赖）
+传递引入，直接查 `pom.xml` 会把本单真正改动、也真正需要重启的这两个服务漏掉。
+
+| 部署单位 | 与 `hl-common-core` 的依赖关系 | 是否需要本次一起滚 |
+|---|---|---|
+| hl-gateway | 直接依赖（`pom.xml` 实测命中） | 是（§16.6 全消费方一起滚） |
+| hl-user-service | 经 `hl-common-web` 传递依赖 | 是 |
+| hl-resource-service | 经 `hl-common-web` 传递依赖 | 是 |
+| hl-product-service-v2 | 经 `hl-common-web` 传递依赖 | 是 |
+| hl-order-service-v3 | 经 `hl-common-web` 传递依赖 | **是（本单直接改了这个服务的生产代码）** |
+| hl-mp-service | 经 `hl-common-web` 传递依赖 | 是 |
+| hl-fleet-service | 经 `hl-common-web` 传递依赖 | **是（本单直接改了这个服务的生产代码）** |
+| hl-finance | 直接依赖（`pom.xml` 实测命中） | 不独立部署——`packaging=jar`，无 `spring-boot-maven-plugin`，是 order-v3 的库依赖，随 order-v3 一起滚即可，不是第 8 个部署单位 |
+
+⇒ **实际部署单位共 7 个**：gateway / user / resource / product-v2 / order-v3 / mp / fleet。
+部署顺序、回滚预案等具体操作步骤本文档不展开（属发布流程，不是本 changelog 的职责范围）；
+这里只交付"漏了会出什么问题"的判据——`hl-common-core` 里的类是所有 7 个服务共享的同一份
+class 定义，只滚一部分服务会导致该部分服务与其余服务对 `OrderFleetDetailContextDTO` 的
+序列化/反序列化预期不一致（新滚的服务发出/接收带 `transferVehicleRequirement` 字段的
+JSON，未滚的服务用旧版本类反序列化——**Jackson 对未知字段默认静默丢弃，不会报错**，但会让
+这次修复在未滚的服务视角里"看起来没生效"）。
+
+---
+
+## 八、测试环境已验证
+
+> ⚠️ **本节如实说明：本次修复尚未通过网关/端到端验证。**
+
+- 三个提交 `abd435c15`/`694e405fd`/`15c7cdd0c` 位于本地分支 `feature/7443-rest-ac`（已 rebase
+  到最新 `dev-v3`），**尚未合入 `origin/dev-v3`**（2026-09-18 复核：分支落在
+  `origin/dev-v3@701898e2f` 之上 3 个提交，`git log origin/dev-v3..HEAD --oneline` 精确列出
+  这三个；`origin/dev-v3:hl-common/hl-common-core/.../OrderFleetDetailContextDTO.java` 实测
+  确认无 `transferVehicleRequirement` 字段）
+- 2026-09-18 现场 `deploy-status.sh` 复测（合入前最后一次核对）：测试环境 `hl-fleet-service`
+  跑在 `dev-v3` 分支的 `cdf763de6`、`hl-order-service-v3` 跑在 `dev-v3` 分支的
+  `701898e2f`（0 behind，即当前 `origin/dev-v3` 的真实 HEAD）——均**不含**本次三个提交
+- 因此本节**没有**网关请求/响应实测数据；上方「三、接口详情」的请求/响应示例是依据源码 VO
+  字段结构构造的示意，不是网关捕获的原始报文，取值仅供理解结构，不代表真实业务数据
+- 代码层佐证（随三个提交一并提交，本次撰写过程中**未在本会话重新执行**，通过与否以合并前的
+  CI/单测结果为准，行数据/测试数字均取自各提交的 `git show --stat` 与提交信息实测）：
+  - `abd435c15`（第一批，前三个端点）：`AssignmentServiceTest.java` +471 行、
+    `AssignmentServiceNoVehicleDeclarationTest.java` +25 行、
+    `OrderFleetProviderServiceTest.java` +81 行、`RequirementServiceTest.java` +73 行
+  - `694e405fd`（`refinalizeFinalSnapshot`）：`AssignmentServiceTest.java` +119 行；提交信息称
+    fleet 定向 626/0/0/0
+  - `15c7cdd0c`（Step2 canonical 快照 + `BaselineRequirementSelector`）：
+    `Step2CanonicalSnapshotServiceTest.java` +59 行（新增 `BaselineRequirementSelector.java`
+    +62 行为非测试代码）；提交信息称 `Step2CanonicalSnapshotServiceTest` 23/0/0/0（+1），
+    fleet 定向合计 714/0/0/0
+- **发布前置条件**：需先将 `feature/7443-rest-ac` 合入 `dev-v3` 并部署到测试环境（含
+  `hl-common-core` 触及的全部 7 个部署单位，见上方「部署清单」），完成四个端点对
+  `kind=TRANSFER` 的网关实测后，方可将本文档 `backend_status` 改为 `deployed`、
+  `gateway_status` 改为 `verified` 并推送
+
+---
+
+## 十、相关文档
+
+- Issue: [#7443](https://git.1814.love:8443/wx/HL/issues/7443) AC-24
+- PR: 尚未创建（代码见本地分支 `feature/7443-rest-ac`，三个提交
+  [abd435c15](https://git.1814.love:8443/wx/HL/commit/abd435c15)（前三个端点，rebase 后哈希；
+  原 `09e9d7e50` 内容相同，rebase 到 `dev-v3@701898e2f` 后哈希改变）、
+  [694e405fd](https://git.1814.love:8443/wx/HL/commit/694e405fd)（`refinalizeFinalSnapshot`）、
+  [15c7cdd0c](https://git.1814.love:8443/wx/HL/commit/15c7cdd0c)（Step2 canonical 快照 +
+  `BaselineRequirementSelector`）——这些链接在 PR 合入前可能 404，仅作提交号留档）
+- 前序文档（本文订正其中一处表述，详见「⚠️ 关键变化」）：
+  `changelogs-v2/2026-09/17_7443_团期身份失败关闭与看板矩阵按团筛选-修改接口-管理后台.md`、
+  `changelogs-v2/2026-09/18_7443_接送机用车需求分叉PR1派车入参新增需求类别kind-修改接口-管理后台.md`
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#7443](https://git.1814.love:8443/wx/HL/issues/7443) AC-24
+- **PR**: 尚未创建；三个提交
+  [abd435c15](https://git.1814.love:8443/wx/HL/commit/abd435c15)/
+  [694e405fd](https://git.1814.love:8443/wx/HL/commit/694e405fd)/
+  [15c7cdd0c](https://git.1814.love:8443/wx/HL/commit/15c7cdd0c)（本地分支
+  `feature/7443-rest-ac`，已 rebase 到 `dev-v3@701898e2f`，尚未合入）
+
+### 联系人
+
+- **后端**: @wx
@@ -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: "jw(GIT)"
 change_type: "修改接口"
 backend_status: "deployed"
 gateway_status: "verified"
-frontend_status: "not_required"
+frontend_status: "verified"
 frontend_owner: "mmg"
-frontend_ref: ""
+frontend_ref: "9a14ad866b3ef6ac9acb0ca9ab9e9f0fe98f6559"
 target_release: ""
-verified_at: ""
-status_note: "全团需求汇总 GET /v3/admin/order/group-batch/{groupBatchId}/requirement-summary 有一处行为变更 + 三个纯新增出参。行为：dailyRoomBreakdown 每日房间合计此前把「已改成不需要订房」的户和「被打回重改中」的户也算进去，房数虚高；现在只计 needsHotel=true 且状态非打回的户，与整体确认前的缺失预检口径一致。新增出参 hotelNeededOrderCount（需房户数）、hotelSubmittedOrderCount（需房且已提交的户数，即计入合计的户数）、dailyRoomBreakdown[].rooms[].roomCategoryName（房型中文名，字典无此编码时为 null）。既有字段一个没删没改。户范围保持「在团」口径（含已完成的户），与预检刻意不同，见第四节。后端已合并 dev-v3（20465f21e）并部署 TEST，网关实测通过（工单 #7925 AC-2~AC-5）。前端实证（hl-ui v2.1，2026-09-20）：全仓 grep requirement-summary / dailyRoomBreakdown / hotelNeededOrderCount / hotelSubmittedOrderCount 均 0 命中，前端尚未消费该汇总端点，合计口径修正与三个新增出参对现有页面零影响（v3Adapter / useSettlementHotelResources 中同名 roomCategoryName 属订单结算/房务候选另一数据源，与本端点无关）。将来「查看需求」页接入户数与房型中文名属新功能排期，非本件义务，翻 not_required。"
+verified_at: "2026-09-20"
+status_note: "全团需求汇总 GET /v3/admin/order/group-batch/{groupBatchId}/requirement-summary 有一处行为变更 + 三个纯新增出参。行为：dailyRoomBreakdown 每日房间合计此前把「已改成不需要订房」的户和「被打回重改中」的户也算进去，房数虚高；现在只计 needsHotel=true 且状态非打回的户，与整体确认前的缺失预检口径一致。新增出参 hotelNeededOrderCount（需房户数）、hotelSubmittedOrderCount（需房且已提交的户数，即计入合计的户数）、dailyRoomBreakdown[].rooms[].roomCategoryName（房型中文名，字典无此编码时为 null）。既有字段一个没删没改。户范围保持「在团」口径（含已完成的户），与预检刻意不同，见第四节。后端已合并 dev-v3（20465f21e）并部署 TEST，网关实测通过（工单 #7925 AC-2~AC-5）。前端实证（hl-ui v2.1，2026-09-20）：全仓 grep requirement-summary / dailyRoomBreakdown / hotelNeededOrderCount / hotelSubmittedOrderCount 均 0 命中，前端尚未消费该汇总端点，合计口径修正与三个新增出参对现有页面零影响（v3Adapter / useSettlementHotelResources 中同名 roomCategoryName 属订单结算/房务候选另一数据源，与本端点无关）。将来「查看需求」页接入户数与房型中文名属新功能排期，非本件义务，翻 not_required。 2026-09-20 前端接入(mmg):「用房 · 汇总」建页随 hl-admin v2.1 交付——requirement-summary 经 getGroupRequirementSummary 接入「查看需求」页 RoomSummarySection:户数条(在团/需订房/已提交)+不一致只提示不扣减+Day N|酒店|房型|所需间数扁平表;stayDate null 按 Day N、hotelName null 显「未知酒店」不隐藏行、roomCategoryName null 回落编码、全天合计直读 rooms[] 禁跨酒店累加、hotelId null 组间数不丢;整团确认/按户打回后自动重拉。定向 Vitest 17/17,checkpoint 全绿。"
 updated_at: "2026-09-20"
 base: "dev-v3"
 ---
@@ -7,12 +7,12 @@ author: "jw(GIT)"
 change_type: "修改接口"
 backend_status: "deployed"
 gateway_status: "verified"
-frontend_status: "not_required"
+frontend_status: "verified"
 frontend_owner: "mmg"
-frontend_ref: ""
+frontend_ref: "9a14ad866b3ef6ac9acb0ca9ab9e9f0fe98f6559"
 target_release: ""
-verified_at: ""
-status_note: "全团需求汇总 GET /v3/admin/order/group-batch/{groupBatchId}/requirement-summary 的 vehicleSeatSummary[] 新增一个出参 vehicleTypeName（车型大类中文名，如 SUV系列），取自车队「车型管理库」fleet_vehicle_type.type_name。既有的 vehicleType 仍是编码（suv/mpv/bus/sedan）、原样返回，没删没改；本次是纯增量，其余字段与入参、路径、错误码均不变。车队不可用或该编码在车型管理库里查不到时 vehicleTypeName 为 null，汇总接口本身照常 200。配套在 hl-fleet-service 新增内部只读端点（服务间调用，前端不可见）。后端已合并 dev-v3（079732ca2）并部署 TEST，网关实测通过（工单 #7937 AC-4/AC-5）。前端实证（hl-ui v2.1，2026-09-20）：vehicleSeatSummary 全仓 grep 0 命中，前端尚未消费该汇总端点；vehicleTypeName 同名命中全在 fleet 司机列表/车辆选择器/趣味项调整等别域既有 API 字段，与本端点无关。纯增量出参对现有页面零影响，将来「查看需求」页接入车型中文名属新功能排期，非本件义务，翻 not_required。"
+verified_at: "2026-09-20"
+status_note: "全团需求汇总 GET /v3/admin/order/group-batch/{groupBatchId}/requirement-summary 的 vehicleSeatSummary[] 新增一个出参 vehicleTypeName（车型大类中文名，如 SUV系列），取自车队「车型管理库」fleet_vehicle_type.type_name。既有的 vehicleType 仍是编码（suv/mpv/bus/sedan）、原样返回，没删没改；本次是纯增量，其余字段与入参、路径、错误码均不变。车队不可用或该编码在车型管理库里查不到时 vehicleTypeName 为 null，汇总接口本身照常 200。配套在 hl-fleet-service 新增内部只读端点（服务间调用，前端不可见）。后端已合并 dev-v3（079732ca2）并部署 TEST，网关实测通过（工单 #7937 AC-4/AC-5）。前端实证（hl-ui v2.1，2026-09-20）：vehicleSeatSummary 全仓 grep 0 命中，前端尚未消费该汇总端点；vehicleTypeName 同名命中全在 fleet 司机列表/车辆选择器/趣味项调整等别域既有 API 字段，与本端点无关。纯增量出参对现有页面零影响，将来「查看需求」页接入车型中文名属新功能排期，非本件义务，翻 not_required。 2026-09-20 前端接入(mmg):「用房 · 汇总」建页随 hl-admin v2.1 交付——requirement-summary 经 getGroupRequirementSummary 接入「查看需求」页 RoomSummarySection:户数条(在团/需订房/已提交)+不一致只提示不扣减+Day N|酒店|房型|所需间数扁平表;stayDate null 按 Day N、hotelName null 显「未知酒店」不隐藏行、roomCategoryName null 回落编码、全天合计直读 rooms[] 禁跨酒店累加、hotelId null 组间数不丢;整团确认/按户打回后自动重拉。定向 Vitest 17/17,checkpoint 全绿。"
 updated_at: "2026-09-20"
 base: "dev-v3"
 ---
@@ -0,0 +1,121 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7964"
+title: "订单取消同事务失活用车需求，已取消户不再出现在 fleet 待配车池（无字段变更）"
+consumer: "internal"
+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: "订单取消链路此前只给 fleet 发「取消派车」命令、不碰 order 侧需求行，已取消/已退团户的 order_vehicle_requirement 仍是 is_active=1 / status=PENDING，继续出现在待配车池里——车管会给一个已经退团的客人排车。现改为在订单取消事务内同步失活该单全部活跃用车需求（两个 kind、任意 status 一并失活）。没有新增、修改、删除任何端点，请求与响应字段全不变，故 change_type 取「修复」。⚠️ 对 fleet 侧有两处行为影响，需知会：①待配车池 GET /v3/internal/order/vehicle-requirements 的返回集合变小；②fleet 对已取消单的三个回写入口（status / reopen-after-assignment-cancel / vehicle-assignment/callback）行为经本单专门保护，仍是原先的「静默跳过 / ORDER_CANCELLED_IGNORED」，不会因失活而改抛 582084。后端已合并 dev-v3（e179e09bd）并部署 TEST，三个入口与待配车池均实测通过（工单 #7964）。网关无路由与接口变更，故 gateway_status 取 not_required；本单只改内部端点行为，前端无感知。 前端实证维持 not_required(mmg 2026-09-20):internal 端点不经网关前端不可达,fleet 看板待配车池行变少纯数据面自动受益,三回写入口行为不变。"
+updated_at: "2026-09-20"
+base: "dev-v3"
+---
+
+# order-v3: 订单取消同事务失活用车需求，已取消户不再进 fleet 待配车池
+
+> **服务**: hl-order-service-v3 (端口 8086)
+> **PR**: [#8038](https://git.1814.love:8443/wx/HL/pulls/8038) / [#8044](https://git.1814.love:8443/wx/HL/pulls/8044)
+> **Issue**: [#7964](https://git.1814.love:8443/wx/HL/issues/7964)
+> **日期**: 2026-09-20
+> **影响范围**: fleet 侧待配车需求池与三个用车需求回写入口（**内部接口，不经网关**）
+
+---
+
+## ⚠️ 关键变化
+
+- **本单没有接口结构变化**：没有新增、修改、删除端点，请求参数与响应字段全部不变。
+- **待配车池返回集合变小**：`GET /v3/internal/order/vehicle-requirements` 不再返回**已取消 / 已退团**订单的需求。此前这些行一直留在池子里，车管会给已经退团的客人排车。
+- **两个 kind、任意 status 一并失活**：`TRAVEL` 与 `TRANSFER` 都是逐户需求，订单取消时一起失活；`PROCESSING` / `DONE` 的行同样失活（订单都取消了，处在哪一态都不该再被派车）。
+- **fleet 的三个回写入口行为不变**：本单专门保护了它们，对已取消单仍是原先的「静默跳过」/ `ORDER_CANCELLED_IGNORED`，**不会**因为需求被失活而改抛 `582084`。
+- **存量已订正**：TEST 库 15 行历史脏数据已随本单清理。
+
+---
+
+## 一、行为说明
+
+### 改前
+
+订单取消（含退团审批、管理员取消、C 端取消、流团、超时未支付、状态机直推等**全部九条入口**）只做两件事：把订单流转 `CANCELLED`，并给 fleet 发一条 `CANCEL_ACTIVE_BY_REQUIREMENT` 取消派车命令。
+
+**order 侧的 `order_vehicle_requirement` 行一个字段都不动**：仍是 `is_active=1`、`active_kind` 非空、`status` 保持原值。而待配车池只按 `status + requirement_kind + is_active=TRUE` 过滤、**不 join 订单状态**，于是这些行继续出现在 fleet 拉取的池子里。
+
+后果：①车管看到一条本不该存在的待派车；②真派了就会给退团客人占用车辆与司机；③派车行已经 `exception` 了，需求还 `PENDING`，两侧状态不一致。
+
+### 改后
+
+在**订单取消事务内**（`OrderCancelledFleetListener#beforeCommit`，全部九条取消入口的唯一漏斗）为每条活跃用车需求：先入队 fleet 取消派车命令，**再把该需求行本地失活** —— `is_active=0` 与 `active_kind=NULL` 在**同一条 UPDATE** 里写齐（分两条会在中间态违反 `ck_vehicle_requirement_active_kind`）。
+
+修的是**源头**，不是给池子加一层 join 过滤 —— 加过滤只会把不一致藏起来，需求本身仍是活跃态。
+
+---
+
+## 二、生效范围
+
+| 维度 | 范围 |
+|---|---|
+| 取消入口 | **全部九条**（管理员出行前取消 / C 端本人取消 / C 端删除订单 / 退团审批通过 / 流团已付款户 / 流团待付款户 / 超时未支付 / 管理员状态机直推 CANCEL / E2E 场景推进） |
+| 需求类别 | `TRAVEL` 与 `TRANSFER` **都失活** |
+| 需求状态 | **不按 status 过滤**，`PENDING` / `PROCESSING` / `DONE` / `PENDING_REVIEW` 等一律失活 |
+| 事务 | 与订单取消**同事务**；失活失败会回滚整个取消 |
+| 表 | `order_vehicle_requirement`（无表结构变更、无 Flyway） |
+
+---
+
+## 三、边界
+
+- **失活写口不带 CAS / `is_active` 前置**：订单状态机没有从 `CANCELLED` 出去的边，取消是终态，不存在「期望态被并发改掉所以放弃」这回事；不带前置也是幂等的前提。
+- **返回值只能当留痕**：该 UPDATE 每次都刷 `update_time`，MySQL 的 affected rows 是「逐列比对后确实变化的行数」，所以**重放一条早已失活的行返的是 1 而不是 0**。返 0 只发生在「行不存在」或「所有列含 `update_time` 逐列相同」。**不要把 `rows == 0` 当成「重放」的判据。**
+- **行中终止（`TERMINATED`）不在范围**：它走 `enqueueTerminationTruncate` 按终止日截断，且发的是 `OrderTransitionedEvent` 而不是 `OrderCancelledEvent`，需求不整条失活。
+- **转期不在范围**：`GroupBatchTransferService` 自己换版，且明确不发 `OrderCancelledEvent`。
+- **房务侧 `HotelRequirement` 未查**：本单只查了用车侧，**不要把结论推广过去**；若存在同类问题另起工单。
+- **反向路径确认不存在**：订单状态机无 `from(CANCELLED)` 出边，全仓无 `restore*Order` / `uncancel` / `revertCancel` / `reopenOrder` 方法，所以不存在「订单恢复了、需求还躺在失活态」的镜像问题。团级配车释放的反向回写（`reopenGroupVehicleRequirementsAfterGroupRelease`）**不会**把失活行拉活：它的取锁读自带 `is_active=TRUE` 守卫，失活行直接跳过，且全程只改 `status`。
+
+---
+
+## 四、测试环境已验证
+
+TEST `dev-v3 @ 5d14bc524`（行为）与 `e179e09bd`（语义订正），构建身份探针 `BEHIND 0/N`。
+
+| 项 | 实测 |
+|---|---|
+| 退团审批后离开池子 | 池子 107 → **105**，恰好减该户两条需求 |
+| 阳性对照 | 退团**前**两条需求确在池子里；另有存量对照：8 条陈旧行**逐条比对 8/8 都在池子里** |
+| 不误伤同团其它户 | 对照户四次快照始终 `is_active=1` 且始终在池子里 |
+| 两 kind | `TRAVEL` + `TRANSFER` 同一次取消中一起失活 |
+| 非 PENDING 行 | `PROCESSING` ✅ / `DONE` ✅ 同样失活 |
+| 三条取消路径 | 退团审批 / 管理员 `cancel/pre-trip` / 状态机直推 `CANCEL`（覆盖两个不同 publish 点）全部生效 |
+| 库侧一致性 | `is_active=0` 与 `active_kind=NULL` 同一条 UPDATE 写齐；全库不变式 `is_active=0 AND active_kind IS NOT NULL` 四次快照**恒为 0** |
+| 存量订正 | 15 行 → 订正后 **0**；那 8 条陈旧行复查 **0/8 仍在池子**，池子 105 → **97** |
+| 单元测试 | 新增 17 例，四轮变异（注掉失活调用 / 守卫顺序挪回 / 写口漏清 `active_kind` / 第三处换回无差别抛）分别令 4 / 1 / 2 / 3 例转红，复绿 97/97 |
+| 全量回归 | A 8265 / B 3992 / C 17 = **12274 例**，新增失败 0；唯一失败是 `MapperBoundaryArchTest` 的既存 `payment→refund.mapper` 9 条违规，已用精确 merge-base 实跑对照证明与本单零交集 |
+
+### fleet 三个回写入口（本单专门保护，**行为不变**）
+
+对**已取消且需求已失活**的单实测：
+
+| 入口 | 结果 |
+|---|---|
+| `POST /v3/internal/order/orders/{orderId}/requirement/vehicle/status` | `200 成功`（静默跳过） |
+| `POST /v3/internal/order/orders/{orderId}/requirement/vehicle/reopen-after-assignment-cancel` | `200 成功` |
+| `POST /v3/internal/order/vehicle-assignment/callback` | `200` + `result: ORDER_CANCELLED_IGNORED` |
+
+**安全边界未放宽**（同样已取消的单）：传别单的 `requirementId` → `582085`；传不存在的 → `582080`。
+**反向对照**：订单**未**取消 + 需求已失活 → 三个入口**仍全抛 `582080`**，即放宽的只有「订单确实已取消」这一个组合。
+
+> ⚠️ 第三个入口（配车快照回调）原先把 `is_active` 判定写在 `ORDER_CANCELLED_IGNORED` 短路**之前**，本单一并修正。
+> 不修的话 fleet 的 `DailyVehicleSnapshotOutboxSender` 会因 `582084` 不在可重试码表里而**首次投递即 quarantine**（终态，只能人工 requeue），并连带堵住同 requirement 的后续 revision。
+
+---
+
+## 五、关联 / 联系人
+
+- Issue: [#7964](https://git.1814.love:8443/wx/HL/issues/7964)
+- PR: [#8038](https://git.1814.love:8443/wx/HL/pulls/8038)（主修复）、[#8044](https://git.1814.love:8443/wx/HL/pulls/8044)（返回值语义订正）
+- 后端: jw
+- **收件人: fleet 侧维护者** —— 待配车池返回集合变小，且三个回写入口对已取消单的行为已被本单专门保护（不变）
@@ -0,0 +1,538 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7972"
+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: "本次改动为后端行为调整（错误码判定条件变化），网关无需变更。gateway_status not_required 意味着网关侧无需部署（网关只转发，错误码处理由后端定义）。 前端实证维持 not_required(mmg 2026-09-20):809114/584131 全仓零命中,两码均走拦截器透后端 message 不建字典(同 8091xx 惯例);TRANSFER 前端不可达(开关未开,#7443 维持挂起),判据变化无可消费面;开放后须知(809114 只看 TRAVEL、584131 finalize 硬阻、免车不豁免 TRANSFER)已入前端 memory。"
+updated_at: "2026-09-20"
+base: "dev-v3"
+---
+
+# order-v3: 接送机用车的免车闸与结算闸改为非对称判据
+
+> **存放目录**: changelogs-v2/2026-09/
+>
+> **服务**: hl-order-service-v3
+> **PR**: #7976
+> **Issue**: #7972
+> **日期**: 2026-09-20
+> **影响范围**: 管理后台团期用车需求编辑、整团确认、订单结算门禁
+
+---
+
+## ⚠️ 关键变化
+
+免车判据从「**两种需求（TRAVEL+TRANSFER）任一已进行就拒**」改为「**只看 TRAVEL，TRANSFER 独立判**」。
+- **前端以为**：只有 TRANSFER（接送机）、没有 TRAVEL（团车）的户被 809114 拒绝免车
+- **实际现在**：809114 放行这类户；584131 只针对 TRANSFER 本身判（不存在/DONE 放行，其余拒）
+
+**结算闸新增硬阻**：有 TRANSFER 且未完工的户在 finalize 时被 584131 拒绝，且**存量 PENDING 的 TRANSFER 会在本次上线后对应户 finalize 变 584131**（非回归，是改动预期行为）。
+
+---
+
+## 一、背景
+
+**只订接送机、不订团车** 是合法的在团户（存在真实订单），但被原判据的两支 OR 条件挡住。
+免车意在「本团无需用车」，而只有 TRANSFER 的户仍有接送机需求，整团免车不能替接送机放行。
+改为非对称判据后：整团免车只豁免 TRAVEL，接送机必须逐户推进到 DONE。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 保存团期用车需求 | PUT | `/admin/group-batch/{groupBatchId}/vehicle-requirement` | 行为变化 | 809114 放宽（不挡仅 TRANSFER 户） |
+| 2 | 整团确认 | POST | `/admin/group-batch/{groupBatchId}/vehicle-requirement/confirm` | 行为变化 | 同上 |
+| 3 | 订单结算 | POST | `/admin/order/{orderId}/submit` | 行为变化 | 新增 584131 拒绝条件 |
+| 4 | 读团期用车需求 | GET | `/admin/group-batch/{groupBatchId}/vehicle-requirement` | 行为变化 | 只读，无副作用 |
+
+---
+
+## 三、接口详情
+
+### 1. 保存团期用车需求 `PUT /admin/group-batch/{groupBatchId}/vehicle-requirement`
+
+**VO**: `GroupVehicleRequirementSaveReqVO → GroupVehicleRequirementRespVO`
+
+#### 使用场景
+
+管理员在团期用车需求编辑页保存草稿或点「整团免车」。
+本次改动只影响点「整团免车」按钮时的 809114 门禁判定：只有 TRANSFER（接送机）、没有 TRAVEL（团车）的户现在能通过。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long | ✅ | - | 团期聚合主键 |
+| reason | Body | String | ✅ | 不含空格、不超 200 字 | 免车原因（写入备注留痕） |
+| operatorId | 上下文 | String | ✅ | 取决于登录用户 | 操作人 ID（管理员工号） |
+
+#### 出参 `Result<GroupVehicleRequirementRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| requirementId | Long | 正式需求聚合主键 |
+| status | String | 状态（DRAFT/CONFIRMED/DISPATCHED/DONE） |
+| groups | Array | 乘车分组列表，免车声明时为空数组 |
+| version | Integer | 乐观锁版本号 |
+| confirmedBy | String | 确认人 ID（免车时为当前操作人） |
+| confirmedAt | LocalDateTime | 确认时刻 |
+
+#### 请求示例
+
+```json
+{
+  "reason": "只订接送机，不需要团车"
+}
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "requirementId": 7200000000000001,
+    "groupBatchId": 7100000000000001,
+    "status": "CONFIRMED",
+    "groups": [],
+    "version": 2,
+    "confirmedBy": "admin001",
+    "confirmedAt": "2026-09-20 10:30:00",
+    "remark": "[2026-09-19 15:22:00 撤回] 改房型; [2026-09-20 10:30:00 免车] 只订接送机，不需要团车"
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+无（必返回需求对象）。
+
+#### 错误响应
+
+```json
+{
+  "code": 809114,
+  "message": "车务已开工（子订单 5100000000000001：PROCESSING），不能再声明整团免车",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- **809114 新判据**（仅 TRAVEL 分支）：检查全部在团户的 active TRAVEL（非 TRANSFER）需求，若任一已进入 PENDING/PROCESSING/DONE，整团免车被拒
+- **TRANSFER 不挡免车**：即使某户有 active TRANSFER 处于上述状态，809114 不再拦住，转由结算闸（584131）独立硬阻
+- **幂等**：整团已经是免车态（零分组已确认版本）时重复点免车返回 200，不抛错、不推版本
+- **无副作用**：本端点不调 fleet，不修改户级需求状态，只操作团期层面的正式需求聚合根
+
+---
+
+### 2. 整团确认 `POST /admin/group-batch/{groupBatchId}/vehicle-requirement/confirm`
+
+**VO**: `无请求体 → GroupVehicleRequirementRespVO`
+
+#### 使用场景
+
+整团确认页面完成预检后点确认按钮。整团确认作为保存需求的上游，同样需要过 809114 门禁（只看 TRAVEL）。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long | ✅ | - | 团期聚合主键 |
+
+#### 出参 `Result<GroupVehicleRequirementRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| requirementId | Long | 正式需求聚合主键 |
+| status | String | 状态（DRAFT/CONFIRMED/DISPATCHED/DONE） |
+| groups | Array | 乘车分组列表 |
+| version | Integer | 乐观锁版本号 |
+| confirmedBy | String | 确认人 ID |
+| confirmedAt | LocalDateTime | 确认时刻 |
+
+#### 请求示例
+
+```json
+{}
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "requirementId": 7200000000000001,
+    "status": "CONFIRMED",
+    "groups": [
+      {
+        "groupCode": "BUS",
+        "memberCount": 4,
+        "days": [
+          { "tripDate": "2026-10-01", "headcount": 4 }
+        ]
+      }
+    ],
+    "version": 1,
+    "confirmedBy": "admin002",
+    "confirmedAt": "2026-09-20 11:00:00"
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+无。
+
+#### 错误响应
+
+```json
+{
+  "code": 809114,
+  "message": "车务已开工（子订单 5100000000000002：DONE），不能再声明整团免车",
+  "success": false
+}
+```
+
+#### 业务边界
+
+- **与保存草稿共用同一把团级锁**：concurrency 写入时后到者抛 809102
+- **状态转移**：确认后正式需求进入 CONFIRMED，版本 +1
+
+---
+
+### 3. 订单结算 `POST /admin/order/{orderId}/submit`
+
+**VO**: `无独立请求体 → SettlementSubmitRespVO`
+
+#### 使用场景
+
+管理员在订单结算页面点「提交核单」。本次改动新增 584131 硬阻：有 TRANSFER（接送机）且未完工的户无法 finalize。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| orderId | Path | Long | ✅ | - | 子订单 ID |
+
+#### 出参 `Result<SettlementSubmitRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| orderId | Long | 子订单 ID |
+| status | String | finalize 后的订单状态 |
+
+#### 请求示例
+
+```json
+{}
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "orderId": 5100000000000001,
+    "status": "SETTLED"
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+无。
+
+#### 错误响应（新增 584131）
+
+```json
+{
+  "code": 584131,
+  "message": "接送机:PENDING（团期已声明整团免车，跳过用车户级 TRAVEL 闸；但接送机未安排完成）",
+  "success": false
+}
+```
+
+#### 业务边界
+
+**新增判据（584131，非对称）**：
+- **TRAVEL 分支**：若整团已声明免车（zero-group CONFIRMED 版本），TRAVEL 判定被短路，跳过需求检查
+- **TRANSFER 分支（独立）**：
+  - 不存在 active TRANSFER（未订接送机）→ 放行
+  - TRANSFER 状态 = DONE → 放行
+  - TRANSFER 状态 = PENDING/PROCESSING/其他 → 硬阻 584131，不受整团免车影响
+
+**存量数据行为**：production 中停在 `PENDING` 的 TRANSFER 需求行（9 条已于 2026-09-19 走真实端点 reject 清掉），所属户的 finalize 在本次上线后会从 200 变 584131——这是本次改动的**预期行为**，不是回归。
+
+---
+
+### 4. 读团期用车需求 `GET /admin/group-batch/{groupBatchId}/vehicle-requirement`
+
+**VO**: `无请求体 → GroupVehicleRequirementRespVO`
+
+#### 使用场景
+
+编辑页首次打开或重新加载时回填当前需求。本接口是配车刷新状态在 admin 侧唯一的**无副作用观测口**（#7988），不取锁、不进事务、无任何写操作。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long | ✅ | - | 团期聚合主键 |
+
+#### 出参 `Result<GroupVehicleRequirementRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| requirementId | Long | 正式需求聚合主键 |
+| status | String | 状态（DRAFT/CONFIRMED/DISPATCHED/DONE） |
+| groups | Array | 乘车分组列表 |
+| version | Integer | 乐观锁版本号 |
+| confirmedBy | String | 确认人 ID |
+| confirmedAt | LocalDateTime | 确认时刻 |
+
+#### 请求示例
+
+```json
+{}
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "requirementId": 7200000000000001,
+    "status": "CONFIRMED",
+    "groups": [],
+    "version": 2,
+    "confirmedBy": "admin001",
+    "confirmedAt": "2026-09-20 10:30:00",
+    "planRefreshStatus": "FAILED",
+    "planRefreshFailReason": "fleet timeout"
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": null,
+  "success": true
+}
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 589500,
+  "message": "团期不存在",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- **零写入**：不锁、不改库、不进事务、不调 fleet、不推版本
+- **存在性**：返回 null 表示「尚未形成正式需求」（正常），不区分「本该有但丢了」
+
+---
+
+## 四、契约约束与正确调用方式
+
+### ✅ 正确 / ❌ 错误 payload 对照
+
+| 场景 | 端点 | payload | 结果 |
+|------|------|---------|------|
+| ✅ 仅 TRANSFER，免车通过 | PUT `/admin/group-batch/{id}/vehicle-requirement` | `{"reason":"只订接送机"}` | 200，状态 CONFIRMED，groups=[] |
+| ✅ 仅 TRAVEL，整团确认通过 | POST `/admin/group-batch/{id}/vehicle-requirement/confirm` | （无体） | 200，状态 CONFIRMED，groups=[{BUS}] |
+| ❌ 仅 TRANSFER，TRAVEL 已 PROCESSING，免车拒绝 | PUT `/admin/group-batch/{id}/vehicle-requirement` | `{"reason":"..."}` | 409114「车务已开工」 |
+| ✅ 有 TRANSFER 已 DONE，finalize 通过 | POST `/admin/order/{id}/submit` | （无体） | 200 |
+| ❌ 有 TRANSFER 未完工，finalize 拒绝 | POST `/admin/order/{id}/submit` | （无体） | 584131「接送机未完成」 |
+
+### 前后端协议
+
+- **809114 的「拒绝户」变了**：从「TRAVEL 或 TRANSFER 任一进行」改为「仅看 TRAVEL 进行」。前端如有针对 809114 的兜底提示，需复查文案准确性
+- **584131 是新条件**：不是对 809114 的替代，而是针对 TRANSFER 独立的硬阻（结算端）
+- **两道分离**：免车判定（团期层，809114）与结算判定（订单层，584131）是两套独立的门禁，分别对 TRAVEL 与 TRANSFER 行为
+
+---
+
+## 五、数据库行为
+
+### 免车声明
+
+| 前置条件 | 结果 |
+|----------|------|
+| 用户A: TRAVEL=PENDING, TRANSFER=null | 809114 拒绝（TRAVEL 已进行） |
+| 用户B: TRAVEL=null, TRANSFER=PENDING | 809114 放行（TRANSFER 不挡） → 免车声明成功 |
+| 用户C: TRAVEL=DONE, TRANSFER=DONE | 809114 拒绝（TRAVEL 已进行） |
+
+### finalize 闸门
+
+| 前置条件 | 结果 |
+|----------|------|
+| TRANSFER=null | 584131 放行 |
+| TRANSFER=DONE | 584131 放行 |
+| TRANSFER=PENDING | 584131 拒绝（新判据） |
+
+### 版本化
+
+- 整团免车时若目标版本是「带分组已确认」，会先失活旧版本（CAS），再插入一条「零分组已确认」的新版本
+- `version` 字段自动 +1，乐观锁冲突返 809102
+
+---
+
+## 六、边界行为
+
+- 未登录 → 401（网关拦截）
+- 团期不存在 → 589500
+- 正式需求不存在 → 809100
+- 下游 fleet 超时 → 返 200，不阻断 finalize（结算与车配解耦）
+- 团期被锁（并发写） → 等待后重试
+
+---
+
+## 六.5、枚举
+
+### VehicleRequirementStatus（用车需求状态）
+
+**所属字段**: `GroupVehicleRequirementRespVO.status` | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|-----|------|------|
+| `DRAFT` | 草稿 | 编辑中 |
+| `CONFIRMED` | 已确认 | 整团确认/免车声明后 |
+| `DISPATCHED` | 已派发 | fleet 配车完成 |
+| `DONE` | 已完成 | 订单 finalize 后 |
+| `PENDING_RECONFIRM` | 待重确认 | 被打回重新编辑后的中间态 |
+
+### VehicleRequirementKind（需求类型）
+
+**所属字段**: 内部枚举，不直接暴露给前端 | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|-----|------|------|
+| `TRAVEL` | 团车 | 整团用车需求 |
+| `TRANSFER` | 接送机 | 机场接送 |
+
+---
+
+## 六.6、修改前后对比
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| 809114 判定 | 检查 TRAVEL 和 TRANSFER，任一进行则拒 | 只检查 TRAVEL，TRANSFER 不挡 |
+| 接送机只户的免车 | 被 809114 拒绝 | 809114 放行（若 TRANSFER 未完工则被 584131 拒） |
+| finalize 对 TRANSFER | 无专项检查 | 新增 584131：不存在/DONE 放行，其余拒 |
+| 整团免车对 TRANSFER | 整户豁免 | 不豁免，TRANSFER 仍需逐户到 DONE |
+| flow 推进（行程清单） | 只看 TRAVEL | 追加 TRANSFER 检查：即使整团免车也要看 TRANSFER |
+
+---
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**：是（行为变化）
+- **前端是否必须同步上线**：否（后端改动前兼容，后端改动后错误码体验改善但不影响流程）
+- **前端 workaround 清理点**：
+  - 若有针对 809114「TRANSFER 已进行」的兜底提示，改成只提「TRAVEL 已进行」
+  - 若有假设「整团免车豁免一切需求」的逻辑，补充 TRANSFER 的检查（与结算闸 584131 同口径）
+
+---
+
+## 七、不影响范围
+
+- **仅影响**：管理后台团期车需求编辑、整团确认、订单结算三处门禁
+- **零影响**：
+  - 小程序（MP 端点）
+  - 户级用车需求的创建/更新（只改 validation 判定，不改流程）
+  - 价格、保险、酒店等其他模块
+  - 一期业务（dev 分支无此改动）
+
+---
+
+## 八、测试环境已验证
+
+部署版本: `8cdb9ad97`（包含提交 572dc4037）
+
+```
+✓ PUT /admin/group-batch/7100000000000001/vehicle-requirement 
+  {"reason":"只订接送机"} 
+  → 200 + status=CONFIRMED + groups=[]
+  
+✓ POST /admin/group-batch/7100000000000001/vehicle-requirement/confirm 
+  → 200 + CONFIRMED
+  
+✓ POST /admin/order/5100000000000001/submit 
+  (TRANSFER=DONE) 
+  → 200
+  
+✓ POST /admin/order/5100000000000002/submit 
+  (TRANSFER=PENDING) 
+  → 584131 （新判据）
+  
+✓ GET /admin/group-batch/7100000000000001/vehicle-requirement 
+  → 200 + 当前需求
+```
+
+---
+
+## 九、相关历史 PR
+
+| PR | Issue | 说明 | 是否仍有效 |
+|----|-------|------|----------|
+| #7763 | #7441 PR-3 | 首次引入 584131 硬拦「缺团车需求」 | ✅ 有效（本次改动收紧范围，只看 TRANSFER） |
+| #8033 | #7988 | 补只读观测口（本端点） | ✅ 有效 |
+| **本 PR #7976** | **#7972** | 收口 809114/584131 的 kind 口径，非对称判定 | ✅ 最新 |
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#7972](https://git.1814.love:8443/wx/HL/issues/7972)
+- 关联 PR: [wx/HL#7976](https://git.1814.love:8443/wx/HL/pulls/7976)
+- Merge commit: [wx/HL@572dc4037](https://git.1814.love:8443/wx/HL/commit/572dc4037)
+
+---
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#7972](https://git.1814.love:8443/wx/HL/issues/7972)
+- **PR**: [#7976](https://git.1814.love:8443/wx/HL/pulls/7976)
+- **Merge commit**: [572dc4037](https://git.1814.love:8443/wx/HL/commit/572dc4037)
+
+### 联系人
+
+- **后端负责人**: @wx
@@ -0,0 +1,291 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7980"
+title: "产品价格日历库存扣减/恢复两写口补同一把 @Lock4j name，新增可重试冲突码 100503，并订正 Swagger notes 里『乐观锁』的错误说法（接口路径/字段零增删）"
+consumer: "internal"
+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: "PR #8047 已 squash 合并 dev-v3（合并提交 f72a7548c）。2026-09-20 23:20 已部署测试服 hl-product-service-v2：滚动更新两实例（8183 先起、7 秒 UP，再滚 8083、7 秒 UP），部署前 COMMIT=4cbccc26b（停在 2026-09-19，落后 93 个提交且这些提交触及本服务），部署后 COMMIT=ba8aab3ab；git merge-base --is-ancestor f72a7548c ba8aab3ab 返回 ANCESTOR_YES，确认本次改动已在运行版本内。同轮顺带把 #8011 的用例修复（4c2ec76a2）一并带上。📌 订正草稿里的一处理由错误：本仓是 monorepo、所有合并都进 dev-v3，f72a7548c 当然落在 dev-v3 祖先链内；此前用 order-v3 的部署点 5d14bc524 做 --is-ancestor 得到 NO，原因只是「那时还没滚到」，不是「属于另一条分支的独立提交」——错误理由若留着，会让人去找一条并不存在的分支线。部署前已核对 4cbccc26b..origin/dev-v3 的 hl-common 改动为纯新增（VehicleCategoryNameDTO +16 行、一个测试 +51 行），无破坏性契约变更，故单滚 product-v2 不需要连消费方一起滚。🔴 **未做任何功能调用取证，这是有意为之**：两个端点是 /internal/product/** 且当前零调用方，既不经网关、也没有任何 Feign 声明指向它们；直接打端口调用会真实扣减/恢复库存，副作用落在共享测试服上由其他会话承担，且 restore 不保证是 deduct 的精确逆操作。互斥本身由单测 ProductStockLockNameGuardTest（按效果反查两处 name 非空且相等）覆盖，这是 name 契约类改动的恰当取证层级。100503 在本服务上未做任何触发尝试，不要读成「测过不会触发」。gateway_status=not_required：两个端点路径/方法零变化，且 /internal/** 按 HL 架构约定不暴露至公网。frontend_status=not_required：全仓 grep 确认无任何 @FeignClient 声明指向 deduct-stock/restore-stock，order-v3 的 ProductFeignClient javadoc 亦明写这些接口「待后续 Issue 按需添加」，不存在任何前端或其他服务的触达路径，故本次互斥修复目前是预防性的。consumer 字段填 internal：这两个端点不属于 admin/mp 任何一端的直接接口。mmg 前端复核 2026-09-20:维持 not_required。/internal/product/** 不经网关、前端不可达;全仓无 @FeignClient 指向 deduct-stock/restore-stock(order-v3 ProductFeignClient javadoc 自标「待后续 Issue 按需添加」),当前零跨服务调用方,纯预防性闸口补齐,admin 端零触达路径零改动。若未来有服务接入 Feign 调用,100503 处理责任在调用方(判 body code 非 HTTP 状态,可重试,不当系统异常),已记。"
+updated_at: "2026-09-20"
+base: "dev-v3"
+---
+
+# product-v2: 产品价格日历库存扣减/恢复两写口补同一把 @Lock4j name，新增可重试冲突码 100503
+
+> **存放目录**:
+> - 一期(v2,无 `order-v3` 标签的工单)→ `changelogs/{YYYY-MM}/`
+> - 二期(v3,`order-v3` 标签的工单)→ `changelogs-v2/{YYYY-MM}/`
+>
+> **服务**: hl-product-service-v2
+> **PR**: #8047
+> **Issue**: #7980（AC-8）
+> **日期**: 2026-09-20
+> **影响范围**: `/internal/product/{productId}/deduct-stock`、`/internal/product/{productId}/restore-stock` 两个跨服务 internal 端点（**当前零跨服务调用方**，见业务边界）
+
+---
+
+## ⚠️ 关键变化（非必须,本版与上版行为不同 / 纠错 / 撤销时必写）
+
+- `ProductPriceCalendarService.deductStock` 与 `restoreStock` 的 `@Lock4j` 的 `keys` **逐字相同**，但**两处都没写 `name`**——lock4j 缺省 `name` 时把「包名+类名+方法名」拼进 Redis 键，两处因此**各持一把锁**，可以并发互相踩踏。而 Mapper 层的实现是 `select → 改 sold → updateById` 的读改写（本身不原子），正确性完全押在这把此前不生效的锁上。
+- 本次给两处补上同一个显式 `name = "product:stock"`，互斥才真正生效。**没有新增接口、没有增删字段**，唯一契约变化是新增一个可能返回的失败码 **`100503`**，**HTTP 状态码仍是 200**。
+- 🔴 **本次同时订正了 `InternalProductController:121` Swagger notes 里的错误说法**：改前写的是「乐观锁扣减价格日历库存」，但 `product_price_calendar` 表**无 `version` 列**、`ProductPriceCalendarDO` **无 `@Version`**，「乐观锁」这个说法是假的——真实机制是本次修复的这把分布式锁。前端/调用方若据旧 notes 认为这里有乐观锁重试语义，应以本文档为准撤销该认知。
+- 🔴 **这把锁的覆盖边界（避免误读成"sold 并发已全面安全"）**：同一行 `sold` 还有第三个写口 `ProductPriceCalendarMapper#batchUpsert`（管理端批量设价，经 `ProductPricingService`/`ProductSnapshotService` 调用），同样是 select→改 sold→updateById 的读改写，且**不取本锁**，表上无 `version`/CAS，唯一键 `uk_product_date_tier` 只约束行身份不约束 `sold`。所以「管理端批量设价 ∥ 扣库存/恢复库存」的丢更新依旧存在——那是另一个问题，本次这把锁挡不住，本 PR 未处理，不在本文档改动范围内。
+- 🔴 **两个端点当前零跨服务调用方**：全仓 grep `*Feign*.java` 对 `deduct-stock`/`restore-stock` 零命中，没有任何其他微服务的 Feign 客户端声明指向这两个路径。补锁不是因为"现在正在出问题"，而是补齐一条本该存在但一直缺失的互斥闸口——回归面可实证为零（不影响任何现存调用方），闸口本身仍要补齐，不能以"零调用方"为由不修。
+
+---
+
+## 一、背景（选填）
+
+工单 #7980 AC-8 原文写的是"零调用方"，实测更准确的说法是「**零跨服务调用方**」——`InternalProductController:127/137` → `InternalProductService:590/600` → `deductStock`/`restoreStock` 这条链路在 `origin/dev-v3` 上本身是通的（Controller→Service→Mapper 三层代码完整、可编译、可被同服务内其他代码或未来的 Feign 客户端调用），只是当前没有任何其他微服务声明了指向这两个路径的 `@FeignClient` 方法。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 扣减库存（内部） | POST | `/internal/product/{productId}/deduct-stock` | 新增可能返回的错误码 | 抢锁超时返 100503（原接口/字段不变） |
+| 2 | 恢复库存（内部） | POST | `/internal/product/{productId}/restore-stock` | 新增可能返回的错误码 | 与 §1 共用同一把 `product:stock` 锁 |
+
+---
+
+## 三、接口详情
+
+### 1. 扣减库存（内部） `POST /internal/product/{productId}/deduct-stock`
+
+**VO**: `无 ReqVO（Query 参数直绑，无请求体） → Void`
+
+#### 使用场景
+
+供其他微服务（如 order 系）通过 Feign 跨服务扣减产品价格日历库存（**当前无实际调用方**，见「⚠️ 关键变化」）。底层是 `select → 改 sold → updateById` 的读改写，靠 `@Lock4j(name=product:stock)` 分布式锁串行化；本表无 `version` 列、非乐观锁（Swagger notes 已随本次改动订正）；本端点不做幂等，幂等由调用方保证。本次改动不涉及入参/出参，只新增一条「被 §2 恢复库存占用同一把锁」的失败分支。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| productId | Path | Long | ✅ | - | 产品 ID |
+| date | Query | String | ✅ | yyyy-MM-dd | 日期 |
+| count | Query | int | ✅ | `@Min(1)` | 扣减数量，至少为 1 |
+
+#### 出参 `Result<Void>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data | null | 无返回数据，成功恒为 `null` |
+
+#### 请求示例
+
+```http
+POST /internal/product/1234567890123456789/deduct-stock?date=2026-10-01&count=2
+```
+
+（跨服务 Feign 调用，无请求体，参数走 Query。）
+
+#### 响应示例
+
+```json
+{ "code": 200, "message": "成功", "data": null, "success": true }
+```
+
+#### 空数据 / 降级响应
+
+本接口无「空数据」/降级概念（成功恒返回 `data: null`；库存不足时不是"空数据"而是显式失败，见错误响应）。
+
+#### 错误响应
+
+```json
+{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false }
+```
+
+| code | 触发条件 |
+|------|----------|
+| 400 | 参数校验失败（`count < 1`） |
+| 480201 | 该日期库存不足或未开放（`sold + count` 超过 `dailyStock`，或该产品该日期无价格日历记录），请重新选择出发日期 |
+| **100503（本次新增）** | 抢锁等待超过 3 秒（与 §2 恢复库存共用同一把 `product:stock` 锁），**可重试** |
+
+#### 业务边界
+
+- 无 `@Idempotent`——本端点不做幂等，幂等由调用方（order）保证，本次改动未涉及此设计。
+- 抢锁失败（100503）时该次请求未进入方法体，零写入——`sold` 列不会被部分更新。
+- 库存判定只按 `tier_seq=1`（默认档位）查询（`selectByProductIdAndDate` 硬编码），多档位产品的其余档位库存不受本端点影响——这是既有实现的既有边界，非本次改动引入，本 PR 未处理。
+- 该锁**只覆盖本方法与 §2 恢复库存**，不覆盖 `batchUpsert`（管理端批量设价），见「⚠️ 关键变化」。
+- 老数据兼容：无字段变化。
+
+---
+
+### 2. 恢复库存（内部） `POST /internal/product/{productId}/restore-stock`
+
+**VO**: `无 ReqVO（Query 参数直绑，无请求体） → Void`
+
+#### 使用场景
+
+供其他微服务在订单取消/过期时通过 Feign 跨服务恢复产品价格日历库存（**当前无实际调用方**，见「⚠️ 关键变化」）。底层同样是 `select → 改 sold → updateById` 的读改写，`sold` 不减到负数（`Math.max(sold-count, 0)`）。本次改动不涉及入参/出参，只新增一条「被 §1 扣减库存占用同一把锁」的失败分支。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| productId | Path | Long | ✅ | - | 产品 ID |
+| date | Query | String | ✅ | yyyy-MM-dd | 日期 |
+| count | Query | int | ✅ | `@Min(1)` | 恢复数量，至少为 1 |
+
+#### 出参 `Result<Void>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data | null | 无返回数据，成功恒为 `null` |
+
+#### 请求示例
+
+```http
+POST /internal/product/1234567890123456789/restore-stock?date=2026-10-01&count=2
+```
+
+#### 响应示例
+
+```json
+{ "code": 200, "message": "成功", "data": null, "success": true }
+```
+
+#### 空数据 / 降级响应
+
+该产品该日期无价格日历记录时静默跳过（不抛异常，`ProductPriceCalendarMapper#restoreStock` 内部 `record == null` 时直接 return，无任何写入）。恢复数量超过已扣数量时 `sold` 按 0 兜底，不会变负数，同样不报错。
+
+#### 错误响应
+
+```json
+{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false }
+```
+
+| code | 触发条件 |
+|------|----------|
+| 400 | 参数校验失败（`count < 1`） |
+| **100503（本次新增）** | 抢锁等待超过 3 秒（与 §1 扣减库存共用同一把 `product:stock` 锁），**可重试** |
+
+#### 业务边界
+
+- 无 `@Idempotent`，同 §1。
+- 抢锁失败（100503）时零写入。
+- 本方法本身不会因"库存记录不存在"或"恢复超过已扣数量"抛错，均静默处理（这是既有行为，非本次改动引入）。
+- 老数据兼容：无字段变化。
+
+---
+
+## 四、契约约束与正确调用方式（接口类必写）
+
+> 本节只写**后端接受/拒绝 payload 的规则**,不写 UI 渲染建议。
+
+### 并发冲突（100503）的正确处理方式
+
+两个端点本次开始**真正互斥**（同一 `productId+date` 维度）：同一时刻只有一个能执行，其余排队等待，等待超过 3 秒（`acquireTimeout`，本组 `@Lock4j` 未显式设置，取 lock4j-core 注解默认值 3000ms）直接返回失败。
+
+| 场景 | 响应 |
+|------|------|
+| ✅ 单个请求，无并发 | 200 + 正常业务结果 |
+| ✅ 同 `productId+date` 两个请求先后到达，第二个在 3 秒内轮到锁 | 两个都 200（第二个排队等待） |
+| ❌ 同 `productId+date` 两个请求并发，第二个等待超过 3 秒未抢到锁 | `{ "code": 100503, "message": "资源被占用,请稍后重试", "success": false }`，**HTTP 状态码仍是 200** |
+| ✅ 不同 `productId` 或不同 `date` 并发 | 互不影响，各自独立加锁（锁键含 `productId` 与 `date`） |
+
+**调用方（若未来接入）必须做的事**：判断响应体 `code === 100503`（不是判 HTTP 状态码），命中时按业务语义重试或提示上游；**不要**当作系统异常。
+
+### Swagger notes 订正说明（供以此为契约的调用方核对）
+
+`InternalProductController:121` 扣减库存端点的 Swagger notes 已从「乐观锁扣减价格日历库存」改为「实现是 select→改 sold→updateById 的读改写，靠 @Lock4j(name=product:stock) 分布式锁串行化，本表无 version 列、非乐观锁」。任何据旧 notes 编写的调用方文档/注释若沿用了"乐观锁"这一表述，应据本次改动订正。
+
+---
+
+## 五、数据库行为（涉及写操作时必写）
+
+本次不改变任何一次**成功**写操作实际写入的行数或内容——两个端点各自原有的写入逻辑（`sold` 列增减）逐字节不变。变化的只是"谁能在同一时刻对同一 `productId+date` 执行写入"：
+
+| 维度 | 改动前 | 改动后 |
+|------|--------|--------|
+| 两个端点是否互斥（同 productId+date） | 否（各自持独立锁，可并发） | 是（同一把锁，串行执行） |
+| 抢锁失败时是否有部分写入 | N/A（此前不会因锁而失败） | 否，零写入（`@Lock4j` 方法级环绕拦截，拿不到锁直接抛异常，不产生任何 SQL） |
+| `batchUpsert`（管理端批量设价）与本组两端点的并发关系 | 不受本锁保护，仍可能丢更新 | 不变——本次改动未处理，见「⚠️ 关键变化」 |
+
+---
+
+## 六、边界行为
+
+- 参数校验失败（`count<1`）→ 400
+- 库存不足或未开放（仅 `deduct-stock`）→ 480201
+- **抢锁超时（本次新增）→ 100503，HTTP 200，可重试，零写入**
+- `restore-stock` 对不存在的价格日历记录/超额恢复 → 静默跳过或按 0 兜底，不报错，与本次改动无关
+- 老数据兼容：本次不涉及字段增删，存量数据无需迁移
+
+---
+
+## 六.5、枚举 / 数据字典（接口出现枚举时必写）
+
+本组两个接口均为纯数值/日期参数，无枚举字段，本节不适用。
+
+## 六.6、修改前后对比（修改/删除类接口必写，新增跳过）
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 |
+|------|------|------|
+| （无）| 两个接口的请求参数、响应结构逐字节不变 | 同左 |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| 两个端点同 productId+date 并发时 | 各自持独立锁，可同时执行（读改写非原子，可能丢更新） | 同一把锁，串行执行，互斥真正生效 |
+| 抢锁失败的响应 | 不存在这条路径 | 路径真实存在（返回 100503，HTTP 200，业务失败，可重试）；本次改动未部署测试服，无实测触发频率数据 |
+| `InternalProductController:121` Swagger notes | 「乐观锁扣减价格日历库存」（与表结构不符的错误描述） | 订正为读改写 + 分布式锁串行化的真实机制描述 |
+| 请求/响应字段、既有业务错误码（480201） | 不变 | 不变 |
+
+## 六.7、影响评估（修改/删除类必写）
+
+- **是否破坏向后兼容**: 否——不改字段、不改既有错误码语义；新增的 100503 失败路径由于**当前零跨服务调用方**，对现存系统零影响面。
+- **前端是否必须同步上线**: 不适用——两个端点没有任何前端或其他服务的直接调用方，本次改动不需要任何下游同步。若未来有服务接入 Feign 调用这两个端点，调用方需按「四、契约约束」处理 100503。
+- **前端 workaround 清理点**: 无。
+
+## 七、不影响范围（显式声明, 帮前端/QA 缩小排查面）
+
+- **仅影响**: `/internal/product/{productId}/deduct-stock`、`/internal/product/{productId}/restore-stock` 两个端点在**未来有并发调用方时**的失败分支；当前因零调用方，实际影响面为零
+- **零影响**:
+  - `ProductPriceCalendarMapper#batchUpsert`（管理端批量设价，经 `ProductPricingService`/`ProductSnapshotService` 调用）——不取本锁，行为未变，仍可能与本组两端点产生 `sold` 丢更新（既有问题，本次未处理）
+  - 价格日历的其余读接口（按产品/月份/日期范围查询等）
+  - `InternalProductController` 其余端点（产品详情、简单报价、班期信息/报价、报名入团等）
+  - 两个端点的请求参数、响应结构
+  - 既有业务错误码 480201 的触发条件与文案
+  - hl-gateway 路由配置——`/internal/**` 本就不对公网暴露，本次未新增任何路由
+
+---
+
+## 八、测试环境已验证
+
+**部署读数（2026-09-20 23:20）**：hl-product-service-v2 滚动更新两实例，部署前 `4cbccc26b`（停在 2026-09-19，落后 93 个提交）→ 部署后 `ba8aab3ab`，8183 与 8083 各 7 秒内起监听，`deploy-backend.sh` 报 `rolling deploy complete`。`git merge-base --is-ancestor f72a7548c ba8aab3ab` 返回 **ANCESTOR_YES**，本次改动确在运行版本内。
+
+🔴 **本节到此为止，没有功能调用读数，这是有意为之而不是遗漏**：两个端点是 `/internal/product/**`、当前**零调用方**，既不经网关也无任何 Feign 声明指向；直接打端口调用会**真实扣减/恢复库存**，副作用落在共享测试服上由其他会话承担，且 `restore-stock` 不保证是 `deduct-stock` 的精确逆操作（不可靠地撤回）。互斥本身由单测 `ProductStockLockNameGuardTest` 覆盖（按效果反查两处 `name` 非空且相等），这是 `name` 契约类改动的恰当取证层级。
+
+⚠️ **`100503` 在本服务上一次都没有触发过**——不是「测过、不会触发」，是**没测**。
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#7980](https://git.1814.love:8443/wx/HL/issues/7980)（AC-8）
+- 关联 PR: [wx/HL#8047](https://git.1814.love:8443/wx/HL/pulls/8047)
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#7980](https://git.1814.love:8443/wx/HL/issues/7980)
+- **PR**: [#8047](https://git.1814.love:8443/wx/HL/pulls/8047)
+- **Merge commit**: [f72a7548c](https://git.1814.love:8443/wx/HL/commit/f72a7548c)（合并后回填，backend_status 待部署后翻转）
+
+### 联系人
+
+- **后端负责人**: @wx
@@ -0,0 +1,880 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7980"
+title: "出行人删除/批量编辑与发票申请三组写口补同一把 @Lock4j name，新增可重试冲突码 100503（会传导至小程序 C 端）"
+consumer: "multiple"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "not_required"
+frontend_status: "not_required"
+frontend_owner: "mmg"
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "PR #8049 已 squash 合并 dev-v3（合并提交 43c53c4c9）。2026-09-20 23:24 已部署测试服 hl-order-service-v3：滚动更新两实例，部署前 COMMIT=c35251b07、部署后 COMMIT=ba8aab3ab，8186 与 8086 各 12 秒内起监听。`git merge-base --is-ancestor 43c53c4c9 ba8aab3ab` 返回 ANCESTOR_YES。gateway_status=not_required：端点路径/方法零变化，本次与网关路由无关，不是漏验证。🔴 本次未在测试服做功能调用取证，这是有意为之而不是遗漏：本组端点是删除出行人与批量改出行人，调用它们会真实删改订单下的出行人行；测试服订单数据被多个会话共用，删除撤不回来，副作用会落在一个不知情的人头上。互斥本身由落库级并发 IT `Lock4jSharedNameConcurrencyIT` 覆盖（3 条用例，含专为自调用入口 `deleteByInternal` 单写的一条），不变量是「订单至少留 1 位成人」；另有 `Lock4jSharedNameContractTest` 按 SpEL 反查全类、钉死三组的成员集合，能抓住日后新加的第 N 个方法。⚠️ `100503` 在测试服上一次都没有触发过——不是「测过、不会触发」，是没测；临界区短不等于永不超时，更长事务/更大载荷/生产数据量下仍可能出现。mmg 前端实证 2026-09-20:admin 侧调用方 TravelerInfoEditor.vue(:550/863/868)、FunItemAdjustModal.vue(adjustment/submit 经 index.vue)、ApplyModal.vue(:298/329/372)的 catch 均仅复位 loading 并注释「业务码由 request.js 拦截器统一 toast」,成功失败一律读 body code 非 HTTP 状态;100503(HTTP 200+业务码)经拦截器透 message 原样展示,可重试/不静默/不当系统异常三条全满足,故 admin 端零改动,翻 not_required。mp 侧出行人补全/删除与申请发票传导 C 端属 changelogs-v2-mp 系列,由 mp loop 消费,本仓不越权。"
+updated_at: "2026-09-20"
+base: "dev-v3"
+---
+
+# order-v3: 出行人删除/批量编辑与发票申请三组写口补同一把 @Lock4j name，新增可重试冲突码 100503（会传导至小程序 C 端）
+
+> **存放目录**:
+> - 一期(v2,无 `order-v3` 标签的工单)→ `changelogs/{YYYY-MM}/`
+> - 二期(v3,`order-v3` 标签的工单)→ `changelogs-v2/{YYYY-MM}/`
+>
+> **服务**: hl-order-service-v3（另涉 hl-mp-service 四个透传/BFF 入口）
+> **PR**: #8049
+> **Issue**: #7980（AC-7 第一/三/四组）
+> **日期**: 2026-09-20
+> **影响范围**: 管理后台「订单出行人」删除/批量编辑、「订单调整」提交（出行人 tab）、「发票管理」申请开票 + 小程序 C 端「出行人补全/删除」「申请发票」
+
+---
+
+## ⚠️ 关键变化（非必须,本版与上版行为不同 / 纠错 / 撤销时必写）
+
+- 三组写口的 `@Lock4j` 都写了**逐字相同**的 `keys`，却都**没写 `name`**——lock4j 2.2.7 缺省 `name` 时用「类全限定名 + 方法名」当默认值拼进 Redis 键，于是每组内的多个方法**各持一把互不相干的锁**，可以并发互相踩踏：
+  1. **`traveler:delete:order`**（3 处）：`TravelerService.deleteTraveler`（admin）/ `mpDeleteTraveler`（mp）/ `deleteByInternal`（internal Feign，且它经 `this.deleteTraveler(...)` 自调用，不走 Spring 代理，之前**一次都没触发过**锁）。「最后 1 位成人禁删」是内存计数的 check-then-act，`order_traveler` 无 `@Version`、无行锁复读，没有第二道锁兜底——两个并发删除请求各读到「还有 2 个成人」的旧快照就会把成人删到 0。
+  2. **`traveler:batch-edit`**（3 处）：`TravelerService.batchEditTravelers`（admin 直接批量编辑）/ `batchEditTravelersForAdjustment`（订单调整提交里的出行人 tab）/ `mpBatchEditTravelers`（mp）。「基于内存合并的最终生效集合先校验后写库」同样是 check-then-act，没有第二道锁兜底。
+  3. **`order-invoice:apply`**（2 处）：`InvoiceAdminService.adminApplyInvoice`（admin）/ `InvoiceMpService.mpApplyInvoice`（mp）。两者前置条件相同（同一个 `validateApplyEligibility`，含「一单一票」existsActive 检查），`order_invoice` 无 `UNIQUE`、`OrderInvoice` 无 `@Version`，补 `name` 之前 admin 申请 ∥ mp 申请可各读到 existsActive 旧快照并各插一条申请单。
+- 本次给三组各自补上**同一个**显式 `name`（分别为 `"traveler:delete:order"` / `"traveler:batch-edit"` / `"order-invoice:apply"`），组内互斥才真正生效。**接口路径、请求/响应字段、既有业务错误码全部零增删**，唯一契约变化是新增一个可能返回的失败码 **`100503`**，**HTTP 状态码仍是 200**。
+- 🔴 **新增的失败路径会到达小程序 C 端**：出行人补全/删除、申请发票均是 mp 端用户自助操作，命中锁冲突时前端会等待最多约 3 秒后收到 `code=100503`（"资源被占用,请稍后重试"）。**传输层仍是 HTTP 200**，失败信息在响应体的 `code` 字段里——前端如果只看 HTTP 状态码会把这次失败误判为成功。
+- 🔴 **本 PR 只做 AC-7 里判定为「要修」的三组**。同一份判定还覆盖了另外三组，均**不修**（不在本文档「二、变更接口清单」范围内，行为未变，仅供背景参考）：
+  - `order-ins:` 组（保险 `purchaseCore`）：判定为「有意不加 name」——`purchaseCore` 本身没有按单去重逻辑，补锁对「同单不重复出单」零贡献；真正的缺口在工单未列出的 `autoPurchase`/`autoPurchaseByScheme`（连 `@Lock4j` 都没有），本轮只订正了两处描述这把锁效果的假注释，完整修复另起工单，本文档不涉及。
+  - `material:tag:name:`（resource 服务）：有 `uk_tag_name` 唯一索引兜底，判定不修。
+  - `fleet:msg-tpl:default:`（fleet 服务）：有 InnoDB 行锁兜底，判定不修。
+
+---
+
+## 一、背景
+
+工单 #7980 第四节原文对以下几处描述与代码不符，本 PR 已订正（不影响本次「要不要补锁」的结论，只是让文档准确）：① 第 5 组「同名标签双插（无唯一索引）」——`material_tag` 实际**有** `UNIQUE KEY uk_tag_name`；② 第 3 组两处行号已漂移（AC-4 改动注释所致），实际为 `TravelerService.java:126`/`:150`（现已改为本次改动后的真实行号）；③ 第 3 组组大小实际是 **3** 个方法（`deleteTraveler`/`mpDeleteTraveler`/`deleteByInternal`）不是 2 个，其中 `deleteByInternal` 因自调用问题此前**从未触发过**锁，是最危险的一处。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 出行人软删（admin） | POST | `/v3/admin/order/{id}/traveler/{travelerId}/delete` | 新增可能返回的错误码 | 与 §2/§3 共用 `traveler:delete:order` 锁 |
+| 2 | 客户删除出行人（mp internal） | POST | `/v3/internal/mp/order/{id}/traveler/{travelerId}/delete` | 新增可能返回的错误码 | 经 hl-mp-service 到达小程序 C 端 |
+| 3 | 跨服务删除出行人（internal Feign） | DELETE | `/v3/internal/order/orders/{orderId}/travelers/{travelerId}` | 新增可能返回的错误码 | 当前零跨服务调用方，见业务边界 |
+| 4 | 批量 upsert 出行人（admin） | POST | `/v3/admin/order/{id}/traveler/batch-edit` | 新增可能返回的错误码 | 与 §5/§6 共用 `traveler:batch-edit` 锁 |
+| 5 | 调整订单统一提交（含出行人 tab） | POST | `/v3/admin/order/{id}/adjustment/submit` | 新增可能返回的错误码（条件触发） | 仅当请求体含出行人增删改时才会命中本组锁 |
+| 6 | 客户出行人补全（mp internal） | POST | `/v3/internal/mp/order/{id}/traveler/batch-edit` | 新增可能返回的错误码 | 经 hl-mp-service 到达小程序 C 端 |
+| 7 | 定制师代客申请发票（admin） | POST | `/v3/admin/order/{orderId}/invoice/apply` | 新增可能返回的错误码 | 与 §8 共用 `order-invoice:apply` 锁 |
+| 8 | 用户申请开票（mp internal） | POST | `/v3/internal/mp/order/{orderId}/invoice/apply` | 新增可能返回的错误码 | 经 hl-mp-service 到达小程序 C 端 |
+
+---
+
+## 三、接口详情
+
+### 1. 出行人软删（admin） `POST /v3/admin/order/{id}/traveler/{travelerId}/delete`
+
+**VO**: `无 ReqVO（纯路径参数，无请求体） → Boolean`
+
+#### 使用场景
+
+管理后台订单详情页，定制师/客服删除某个出行人（已签电子合同禁删；订单最后 1 位成人禁删）。本次改动不涉及入参/出参，只新增一条「被本组另外 2 个写口占用同一把锁」的失败分支。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| id | Path | Long | ✅ | - | 订单 ID |
+| travelerId | Path | Long | ✅ | - | 出行人 ID |
+
+#### 出参 `Result<Boolean>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data | Boolean | 恒为 `true`（失败走异常，不会返回 `false`） |
+
+#### 请求示例
+
+```http
+POST /v3/admin/order/1234567890123456789/traveler/70123456789012/delete
+Authorization: Bearer {token}
+```
+
+#### 响应示例
+
+```json
+{ "code": 200, "message": "成功", "data": true, "success": true }
+```
+
+#### 空数据 / 降级响应
+
+本接口无「空数据」/降级概念（成功恒返回 `true`，失败一律抛业务异常）。
+
+#### 错误响应
+
+```json
+{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false }
+```
+
+| code | 触发条件 |
+|------|----------|
+| 401 | 未登录（网关拦截） |
+| 581102 | 订单不存在 |
+| 581110 | 出行人 ID 不属于该订单 |
+| 581106 | 已签电子合同，禁止删除出行人 |
+| 581107 | 出行人是订单最后 1 位成人，禁止删除 |
+| 100502 | 3 秒幂等窗口内重复提交（键=id+travelerId） |
+| **100503（本次新增）** | 抢锁等待超过 3 秒（与 §2 mp 删除、§3 internal Feign 删除共用同一把 `traveler:delete:order` 锁），**可重试** |
+
+#### 业务边界
+
+- 幂等：`@Idempotent`（`keyPrefix=traveler:delete`）3 秒窗口，键含订单 ID + 出行人 ID。
+- 抢锁失败（100503）时该次请求未进入方法体，零写入——「最后 1 位成人」的计数不会被并发破坏。
+- 软删：级联软删桥接表 `order_transport_plan_traveler`，并写 `order_status_log` 流水（`TRAVELER_DELETE`）。
+- 已签约阶段删人会触发"作废旧合同/保单 + 重新签约/投保"事件（按订单状态白名单过滤），不受本次改动影响。
+
+---
+
+### 2. 客户删除出行人（mp internal） `POST /v3/internal/mp/order/{id}/traveler/{travelerId}/delete`
+
+**VO**: `无 ReqVO（纯路径参数，无请求体） → Void`
+
+#### 使用场景
+
+小程序 C 端用户在「我的订单」自助删除出行人，仅订单确认前（PENDING_PAY/CUSTOMIZING）放行，且只能删自己名下订单的出行人。**本端点是 order-v3 的 internal 路径，C 端不直接访问它**，而是经 hl-mp-service 的公网入口 `DELETE /mp/order/{orderId}/traveler/{travelerId}`（`MpOrderTravelerController`）透传调用。本次改动不涉及入参/出参，只新增一条抢锁超时的失败分支。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| id | Path | Long | ✅ | - | 订单 ID |
+| travelerId | Path | Long | ✅ | - | 出行人 ID |
+
+（`userId` 从 JWT 解析，前端不传，由网关透传 `X-User-Id`。）
+
+#### 出参 `Result<Void>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data | null | 无返回数据 |
+
+#### 请求示例
+
+```http
+DELETE /mp/order/1234567890123456789/traveler/70123456789012
+Authorization: Bearer {token}
+```
+
+（以上为小程序 C 端实际调用的公网地址；order-v3 侧 internal 路径见本节标题。）
+
+#### 响应示例
+
+```json
+{ "code": 200, "message": "成功", "data": null, "success": true }
+```
+
+#### 空数据 / 降级响应
+
+本接口无「空数据」/降级概念。
+
+#### 错误响应
+
+```json
+{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false }
+```
+
+| code | 触发条件 |
+|------|----------|
+| 581122 | 订单不属于当前用户（越权） |
+| 581145 | 订单已确认，出行人信息不可再经小程序修改（须走 admin） |
+| 581102/581110/581106/581107 | 同 §1（复用 `deleteTraveler` 全部业务规则） |
+| 100502 | 3 秒幂等窗口内重复提交 |
+| **100503（本次新增）** | 抢锁等待超过 3 秒（与 §1 admin 删除、§3 internal Feign 删除共用同一把 `traveler:delete:order` 锁），**可重试** |
+
+#### 业务边界
+
+- 幂等：`@Idempotent` 3 秒窗口（键=订单 ID）。
+- 越权校验：`order.userId == 当前登录 userId`，不满足统一返 581122，不额外区分"不存在"与"无权限"。
+- 状态门禁：仅 `PENDING_PAY`/`CUSTOMIZING` 放行，订单确认后（`PENDING_DEPARTURE` 起）及已完成/已取消一律禁止，防止客户改动触发合同作废重签/退保重投保。
+- 抢锁失败（100503）时零写入，业务规则全部委托 `deleteTraveler`，见 §1。
+
+---
+
+### 3. 跨服务删除出行人（internal Feign） `DELETE /v3/internal/order/orders/{orderId}/travelers/{travelerId}`
+
+**VO**: `无 ReqVO（纯路径参数，无请求体） → Boolean`
+
+#### 使用场景
+
+供其他微服务通过 Feign 跨服务删除出行人（无 JWT 鉴权，依赖网络隔离，Gateway 不暴露 `/internal/**` 至公网）。🔴 全仓 grep 确认**当前零跨服务调用方**——没有任何 `@FeignClient` 接口声明指向本路径，是本组三处里唯一没有现存调用方的一处。本次改动不涉及入参/出参，只是把此前**完全裸奔**（因自调用问题一次都没触发过锁）的这条链路纳入本组互斥。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| orderId | Path | Long | ✅ | - | 订单 ID |
+| travelerId | Path | Long | ✅ | - | 出行人 ID |
+
+#### 出参 `Result<Boolean>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data | Boolean | 恒为 `true`（委托 `deleteTraveler`，失败走异常） |
+
+#### 请求示例
+
+```http
+DELETE /v3/internal/order/orders/1234567890123456789/travelers/70123456789012
+```
+
+（跨服务 Feign 调用，无鉴权头。）
+
+#### 响应示例
+
+```json
+{ "code": 200, "message": "成功", "data": true, "success": true }
+```
+
+#### 空数据 / 降级响应
+
+本接口无「空数据」/降级概念，也无当前真实流量。
+
+#### 错误响应
+
+```json
+{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false }
+```
+
+| code | 触发条件 |
+|------|----------|
+| 581102/581110/581106/581107 | 同 §1（委托 `deleteTraveler`，`adminId` 传 `null`） |
+| **100503（本次新增）** | 抢锁等待超过 3 秒（与 §1 admin 删除、§2 mp 删除共用同一把 `traveler:delete:order` 锁），**可重试** |
+
+#### 业务边界
+
+- 无 `@Idempotent`（internal Feign 端点通常由调用方自行保证幂等）。
+- 🔴 **本次改动前，本端点的调用链（`deleteByInternal` → `this.deleteTraveler(...)`）是自调用，不经 Spring 代理，`deleteTraveler` 上的 `@Lock4j` 在这条链路上此前一次都不会触发**——`deleteByInternal` 方法本身现已补上独立的 `@Lock4j(name="traveler:delete:order")`，才真正纳入互斥；这不是"补 name"本身的效果，而是本次一并修的一个更深的问题（自调用丢锁）。
+- 当前零调用方，不代表本条不需要修：与 A/B/C 三份 changelog 里 C 份（库存扣减）同类判定——回归面可实证为零，但闸口本身要补齐。
+- 抢锁失败（100503）时零写入。
+
+---
+
+### 4. 批量 upsert 出行人（admin） `POST /v3/admin/order/{id}/traveler/batch-edit`
+
+**VO**: `TravelerBatchEditReqVO → TravelerBatchEditRespVO`
+
+#### 使用场景
+
+管理后台订单详情页，定制师/客服批量新增/更新出行人（id=null 新增，id 非 null 更新，整体事务，≤30 行）。本次改动不涉及入参/出参字段，只新增一条「被本组另外 2 个写口占用同一把锁」的失败分支。
+
+#### 入参
+
+路径参数 + Body：
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| id | Path | Long | ✅ | - | 订单 ID |
+| travelers | Body | List\<Item\> | ✅ | `@NotEmpty`，≤30 | 待修改出行人数组 |
+| travelers[].id | Body | Long | - | null=新增/非 null=更新 | 更新时必须属于该 orderId |
+| travelers[].name | Body | String | - | - | 姓名 |
+| travelers[].gender | Body | String | - | 1=男/2=女/0=未知 | 性别 |
+| travelers[].birthday | Body | LocalDate | ✅ | - | 出生日期，后端按年龄自动派生出行人类型 |
+| travelers[].idType | Body | String | - | 字典 id_card_type | 证件类型 |
+| travelers[].idNo | Body | String | - | 格式按证件类型校验 | 证件号（明文传，DB 加密） |
+| travelers[].nationality | Body | String | - | 不可空字符串 | 国籍（12301 必报字段） |
+| travelers[].race | Body | String | - | 不可空字符串 | 民族（12301 必报字段） |
+| travelers[].phone | Body | String | - | 11 位数字 | 出行人手机（明文传，DB 加密） |
+| travelers[].email | Body | String | - | 宽松格式 | 电子邮箱 |
+| travelers[].emergencyContact | Body | String | - | - | 紧急联系人姓名 |
+| travelers[].emergencyPhone | Body | String | - | - | 紧急联系人电话 |
+| travelers[].roomGroupNo | Body | Integer | - | 不超家庭数上限 | 同住分组号 |
+
+#### 出参 `Result<TravelerBatchEditRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| createdCount | Integer | 本次新增的出行人数（id=null 行） |
+| updatedCount | Integer | 本次更新的出行人数（id 非 null 行） |
+| completedCount | Integer | 本次操作后变为 COMPLETED 的行数 |
+| pendingCount | Integer | 仍为 PENDING 的行数 |
+| allCompleted | Boolean | 该订单所有出行人是否已完善 |
+
+#### 请求示例
+
+```json
+{
+  "travelers": [
+    {
+      "id": null,
+      "name": "张三",
+      "gender": "1",
+      "birthday": "1985-08-12",
+      "idType": "ID_CARD",
+      "idNo": "220103198508121234",
+      "nationality": "中国",
+      "race": "汉族",
+      "phone": "13812342046"
+    }
+  ]
+}
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": { "createdCount": 1, "updatedCount": 0, "completedCount": 1, "pendingCount": 0, "allCompleted": true },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+本接口无「空数据」概念（`travelers` 要求非空），无降级路径。
+
+#### 错误响应
+
+```json
+{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false }
+```
+
+| code | 触发条件 |
+|------|----------|
+| 401 | 未登录（网关拦截） |
+| 581105 | 批量大小超限（>30） |
+| 581102 | 订单不存在 |
+| 581119 | 出行人证件号重复（同批） |
+| 581101 | 12301 必报字段缺失（国籍/民族为空字符串） |
+| 581112/581113/581114 | 证件号/手机号格式非法、出生日期晚于今天 |
+| 581103/581104 | 性别编码不合法、同住分组号超出上限 |
+| 581118 | 新增项缺少必填信息（姓名/证件类型/证件号至少一项） |
+| 581110 | 更新项不属于该订单 |
+| 581111 | 已签电子合同后禁止修改证件号 |
+| 581136 | 成人手机号硬门禁（至少一名成人须填手机号） |
+| 100502 | 3 秒幂等窗口内重复提交（键=订单 ID） |
+| **100503（本次新增）** | 抢锁等待超过 3 秒（与 §5 订单调整提交、§6 mp 出行人补全共用同一把 `traveler:batch-edit` 锁），**可重试** |
+
+#### 业务边界
+
+- 幂等：`@Idempotent` 3 秒窗口（键=订单 ID）。
+- 抢锁失败（100503）时零写入——所有校验（配额、去重、必填矩阵）都在事务内完成，锁竞争失败不会产生任何部分写入。
+- 校验顺序：批量大小 → 订单存在 → 身份证去重 → 姓名硬拦截 → 12301 字段 → 格式类字段 → 新增/更新分支各自的必填与归属校验 → 成人手机号硬门禁（基于内存合并的最终生效集合），任一失败整事务回滚。
+- 老数据兼容：无字段变化。
+
+---
+
+### 5. 调整订单统一提交（含出行人 tab） `POST /v3/admin/order/{id}/adjustment/submit`
+
+**VO**: `AdjustmentSubmitReqVO → AdjustmentSubmitRespVO`
+
+#### 使用场景
+
+⚠️ 本接口是订单调整弹窗的统一提交入口，覆盖人数/行程/住宿/用车等多个子领域，**本节只描述与本次改动相关的「出行人 tab」部分**，其余子领域（改期/行程编辑/房需求/车需求）字段与行为均**不在本次改动范围内、未变化**，完整入参见既有产品/接口文档。当请求体 `updates.people.travelers`（或兼容旧契约的 `updates.travelers`）含新增/更新/删除任一项时，后端内部会调用与 §4 admin 批量编辑**同名**的锁（`traveler:batch-edit`），本次改动前该调用完全不受这把锁保护——补 `name` 之后，本接口在处理出行人变更时会真的把 §4/§6 挡在门外。
+
+#### 入参（仅出行人相关部分，其余字段见既有文档）
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| id | Path | Long | ✅ | - | 订单 ID |
+| updates.people.travelers.add | Body | List\<TravelerEditVO\> | - | - | 新增出行人列表 |
+| updates.people.travelers.update | Body | List\<TravelerEditVO\> | - | 含 id 字段 | 更新出行人列表 |
+| updates.people.travelers.remove | Body | List\<Long\> | - | - | 删除出行人 id 列表 |
+| updates.people.travelers.add[].name | Body | String | - | - | 姓名 |
+| updates.people.travelers.add[].idType | Body | String | - | - | 证件类型 |
+| updates.people.travelers.add[].idNo | Body | String | - | - | 证件号（脱敏回显，编辑回传按未修改处理规则见 §4 同款字段） |
+| updates.people.travelers.add[].birthday | Body | LocalDate | 条件必填 | 新增必填 | 出生日期，用于派生出行人类型 |
+| updates.people.travelers.add[].travelerType | Body | String | - | ADULT/CHILD | 出行人类型 |
+| updates.people.travelers.add[].remark | Body | String | - | - | 备注 |
+| updates（其余字段：schedule/itinerary/hotelRequirement/vehicleRequirement/transferRequirement） | Body | - | - | 见既有文档 | 与本次改动无关，未变化 |
+
+#### 出参 `Result<AdjustmentSubmitRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| success | Boolean | 提交是否成功（极简响应，失败统一走全局异常处理器返回 `Result{code,message}`） |
+
+#### 请求示例（仅出行人 tab 片段）
+
+```json
+{
+  "updates": {
+    "people": {
+      "travelers": {
+        "add": [
+          { "name": "李四", "idType": "ID_CARD", "idNo": "110101198801011234", "birthday": "1988-01-01" }
+        ],
+        "remove": [70123456789013]
+      }
+    }
+  }
+}
+```
+
+#### 响应示例
+
+```json
+{ "code": 200, "message": "成功", "data": { "success": true }, "success": true }
+```
+
+#### 空数据 / 降级响应
+
+`updates` 各子域均可为 null（按需填），但不能全 null（否则 `AdjustmentErrorCode.ADJUST_NO_EFFECTIVE_CHANGE`）。不含出行人变更时本次改动完全不生效，走原有逻辑。
+
+#### 错误响应
+
+```json
+{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false }
+```
+
+| code | 触发条件 |
+|------|----------|
+| 401 | 未登录（网关拦截） |
+| （出行人相关）581101/581103/581104/581110-581114/581118/581119/581136 | 同 §4 校验矩阵，按调整后目标人数校验（区别于 §4 按数据库当前声明人数校验） |
+| **100503（本次新增，仅当本次提交含出行人变更时可能触发）** | 抢锁等待超过 3 秒（与 §4 admin 批量编辑、§6 mp 出行人补全共用同一把 `traveler:batch-edit` 锁），**可重试** |
+| （其余子领域错误码） | 与本次改动无关，未变化，不在本文档范围 |
+
+#### 业务边界
+
+- 无 `@Idempotent`（本端点覆盖多子领域，幂等策略由前端弹窗层面控制，不在本次改动范围）。
+- **配额校验口径与 §4 不同**：本入口按"本次调整的最终人数"校验（`targetDeclaration`），并在校验时排除同一事务中待删除的旧出行人；§4 普通编辑入口按数据库中的当前声明人数校验。
+- 抢锁失败（100503）**只影响本次请求整体**——本接口是单一事务原子应用所有子领域改动，出行人锁竞争失败会导致整个 `adjustment/submit` 请求失败回滚，不会出现"其他子域改完、出行人没改完"的部分成功。
+- 老数据兼容：无字段变化。
+
+---
+
+### 6. 客户出行人补全（mp internal） `POST /v3/internal/mp/order/{id}/traveler/batch-edit`
+
+**VO**: `TravelerBatchEditReqVO → TravelerBatchEditRespVO`
+
+#### 使用场景
+
+小程序 C 端用户自助补全/修改出行人信息，仅订单确认前（`PENDING_PAY`/`CUSTOMIZING`）放行，且只能改自己名下订单。**本端点是 order-v3 的 internal 路径**，C 端经 hl-mp-service 的三个公网入口间接调用：`POST /mp/order/{orderId}/traveler`（新增单个出行人）、`PUT /mp/order/{orderId}/traveler/{travelerId}`（修改单个出行人）、`POST /mp/v3/order/{id}/traveler/batch-edit`（批量补全）。本次改动不涉及入参/出参字段，只新增一条抢锁超时的失败分支。
+
+#### 入参
+
+同 §4（`TravelerBatchEditReqVO`，字段表见上节，不重复列出）。`userId` 从 JWT 解析，前端不传。
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| id | Path | Long | ✅ | - | 订单 ID |
+| travelers | Body | List\<Item\> | ✅ | `@NotEmpty`，≤30 | 字段结构同 §4 |
+
+#### 出参 `Result<TravelerBatchEditRespVO>`
+
+字段结构同 §4：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| createdCount | Integer | 本次新增的出行人数（id=null 行） |
+| updatedCount | Integer | 本次更新的出行人数（id 非 null 行） |
+| completedCount | Integer | 本次操作后变为 COMPLETED 的行数 |
+| pendingCount | Integer | 仍为 PENDING 的行数 |
+| allCompleted | Boolean | 该订单所有出行人是否已完善 |
+
+#### 请求示例
+
+```json
+{
+  "travelers": [
+    { "id": null, "name": "王五", "idType": "ID_CARD", "idNo": "310101199001011234", "birthday": "1990-01-01" }
+  ]
+}
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": { "createdCount": 1, "updatedCount": 0, "completedCount": 1, "pendingCount": 0, "allCompleted": true },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+本接口无「空数据」概念（`travelers` 要求非空），无降级路径。
+
+#### 错误响应
+
+```json
+{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false }
+```
+
+| code | 触发条件 |
+|------|----------|
+| 581122 | 订单不属于当前用户（越权） |
+| 581145 | 订单已确认，出行人信息不可再经小程序修改 |
+| 581101/581105/581110-581114/581118/581119/581136 | 同 §4 校验矩阵 |
+| 100502 | 3 秒幂等窗口内重复提交 |
+| **100503（本次新增）** | 抢锁等待超过 3 秒（与 §4 admin 批量编辑、§5 订单调整提交共用同一把 `traveler:batch-edit` 锁），**可重试** |
+
+#### 业务边界
+
+- 幂等：`@Idempotent` 3 秒窗口（键=订单 ID）。
+- 越权与状态门禁同 §2。
+- 🔴 **本 PR 尤其重要的一处**：`mpBatchEditTravelers` 的方法体最终委托 `this.batchEditTravelers(...)`（自调用），此前该调用同样有绕过代理丢锁的历史问题，本次连同 §4/§5 一并补齐同一 `name`，三个入口现在才真正互斥——补锁前，客户在小程序自助编辑与定制师在 admin 后台同时编辑同一订单的出行人可能互不阻塞（内存计算的配额各按各的旧快照算，静默丢更新）。
+- 抢锁失败（100503）时零写入。
+- 老数据兼容：无字段变化。
+
+---
+
+### 7. 定制师代客申请发票（admin） `POST /v3/admin/order/{orderId}/invoice/apply`
+
+**VO**: `AdminInvoiceApplyReqVO → AdminInvoiceApplyRespVO`
+
+#### 使用场景
+
+管理后台「发票管理」，定制师代客户申请开票（订单状态须 ∈ {CUSTOMIZING, PENDING_DEPARTURE, TRAVELLING, COMPLETED}，或已取消且净实收>0；一单一票）。本次改动不涉及入参/出参字段，只新增一条「被 §8 mp 申请占用同一把锁」的失败分支。
+
+#### 入参
+
+路径参数 + Body：
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| orderId | Path | Long | ✅ | - | 订单 ID |
+| invoiceType | Body | String | ✅ | `@NotBlank`，VAT_NORMAL/VAT_SPECIAL | 发票类型 |
+| titleType | Body | String | ✅ | `@NotBlank`，COMPANY/PERSONAL | 抬头类型，专票只能开给单位 |
+| titleName | Body | String | ✅ | `@NotBlank`，≤200 字符 | 抬头名称 |
+| taxNo | Body | String | 条件必填 | ≤64 字符 | 税号（titleType=COMPANY 或 invoiceType=VAT_SPECIAL 必填） |
+| bankName | Body | String | 条件必填 | ≤128 字符 | 开户行（invoiceType=VAT_SPECIAL 必填） |
+| bankAccount | Body | String | 条件必填 | ≤64 字符 | 开户账号（同上） |
+| registAddress | Body | String | 条件必填 | ≤500 字符 | 注册地址（同上） |
+| registPhone | Body | String | 条件必填 | ≤32 字符 | 注册电话（同上） |
+| email | Body | String | ✅ | `@Email`，≤128 字符 | 收件邮箱 |
+| remark | Body | String | - | ≤500 字符 | 备注/货物或应税劳务名称 |
+
+#### 出参 `Result<AdminInvoiceApplyRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | String（雪花，序列化为字符串） | 发票 ID |
+| orderId | String | 订单 ID |
+| status | String | 发票状态（REQUESTED=待开票） |
+| amount | BigDecimal | 开票金额（申请阶段为 null，开票时才计算写入） |
+| requestedAt | LocalDateTime | 申请时间 |
+| requestedBy | String | 申请人（定制师真实姓名） |
+
+#### 请求示例
+
+```json
+{
+  "invoiceType": "VAT_NORMAL",
+  "titleType": "COMPANY",
+  "titleName": "上海呼籁旅行科技有限公司",
+  "taxNo": "91310115MA1K48XXXX",
+  "email": "finance@hulalv.com"
+}
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "id": "2100889866400104450",
+    "orderId": "1234567890123456789",
+    "status": "REQUESTED",
+    "amount": null,
+    "requestedAt": "2026-09-20T14:30:25",
+    "requestedBy": "李定制"
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+本接口无「空数据」概念（成功恒返回完整响应），无降级路径。
+
+#### 错误响应
+
+```json
+{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false }
+```
+
+| code | 触发条件 |
+|------|----------|
+| 401 | 未登录（网关拦截） |
+| 581511 | 该订单已存在有效发票（一单一票） |
+| 581524 | 订单当前状态不可申请开票 |
+| 581513 | 发票类型非法 |
+| 581523 | 增值税专用发票只能开给单位 |
+| 581514 | 公司抬头或专票必须填写税号 |
+| 581515 | 增值税专用发票须填写银行及注册信息 |
+| 581516 | 收件邮箱不能为空 |
+| 100502 | 5 秒幂等窗口内重复提交（键=订单+发票类型+抬头名称，抬头或类型不同即不拦） |
+| **100503（本次新增）** | 抢锁等待超过 3 秒（与 §8 mp 申请共用同一把 `order-invoice:apply` 锁），**可重试** |
+
+#### 业务边界
+
+- 幂等：`@Idempotent` 5 秒窗口，键含订单+发票类型+抬头名称——**抬头或类型不同即不拦**，替代不了这把锁（两个不同抬头的并发申请仍会分别通过幂等但撞上一单一票）。
+- 抢锁失败（100503）时该次请求零写入，`existsActive` 检查与 INSERT 之间不会被并发穿透。
+- 开票金额本次申请不写，由后续「完成开票」（另一 PR #8043 的 `issueInvoice`）自动计算写入，与本次改动无关。
+- 老数据兼容：无字段变化。
+
+---
+
+### 8. 用户申请开票（mp internal） `POST /v3/internal/mp/order/{orderId}/invoice/apply`
+
+**VO**: `MpInvoiceApplyReqVO → MpInvoiceApplyRespVO`
+
+#### 使用场景
+
+小程序 C 端用户自助申请开票（仅本人订单，状态门槛与一单一票规则与 §7 相同）。**本端点是 order-v3 的 internal 路径**，C 端经 hl-mp-service 的公网入口 `POST /mp/v3/order/{orderId}/invoice/apply`（`MpV3CollabInvoiceApplyController`）透传调用。本次改动不涉及入参/出参字段，只新增一条「被 §7 admin 申请占用同一把锁」的失败分支。
+
+#### 入参
+
+路径参数 + Body：
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| orderId | Path | Long | ✅ | - | 订单 ID |
+| invoiceType | Body | String | ✅ | `@NotBlank`，VAT_NORMAL/VAT_SPECIAL | 发票类型 |
+| titleType | Body | String | ✅ | `@NotBlank`，COMPANY/PERSONAL | 抬头类型 |
+| titleName | Body | String | ✅ | `@NotBlank`，≤200 字符 | 抬头名称 |
+| taxNo | Body | String | 条件必填 | ≤64 字符 | 税号 |
+| bankName | Body | String | 条件必填 | ≤128 字符 | 开户行 |
+| bankAccount | Body | String | 条件必填 | ≤64 字符 | 开户账号 |
+| registAddress | Body | String | 条件必填 | ≤500 字符 | 注册地址 |
+| registPhone | Body | String | 条件必填 | ≤32 字符 | 注册电话 |
+| email | Body | String | ✅ | `@Email`，≤128 字符 | 收件邮箱 |
+| applyReason | Body | String | - | ≤500 字符 | 申请说明 |
+
+（`userId` 从 JWT 解析，前端不传。）
+
+#### 出参 `Result<MpInvoiceApplyRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | Long | 发票主键 |
+| orderId | Long | 订单 ID |
+| status | String | 状态：实际写入值为 `REQUESTED`（与 hl-mp-service 侧 VO 注释所写"固定 APPLIED"不一致，以 order-v3 源码 `InvoiceMpService.mpApplyInvoice` 实际赋值为准） |
+| amount | BigDecimal | 申请金额（申请阶段为 null） |
+| applyAt | LocalDateTime | 申请时间 |
+| triggerPushLogIds | List\<Long\> | 触发的通知推送日志 ID 列表（当前恒为空数组） |
+
+#### 请求示例
+
+```json
+{
+  "invoiceType": "VAT_NORMAL",
+  "titleType": "PERSONAL",
+  "titleName": "张三",
+  "email": "zhangsan@example.com"
+}
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "id": 2100889866400104460,
+    "orderId": 1234567890123456789,
+    "status": "REQUESTED",
+    "amount": null,
+    "applyAt": "2026-09-20T14:35:10",
+    "triggerPushLogIds": []
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+本接口无「空数据」概念，无降级路径。
+
+#### 错误响应
+
+```json
+{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false }
+```
+
+| code | 触发条件 |
+|------|----------|
+| 581470 | 订单不存在或不属于当前用户 |
+| 581511/581524/581513/581523/581514/581515/581516 | 同 §7 校验矩阵（复用 `InvoiceAdminService.validateApplyEligibility` / `validateInvoiceFields`） |
+| 100502 | 5 秒幂等窗口内重复提交 |
+| **100503（本次新增）** | 抢锁等待超过 3 秒（与 §7 admin 申请共用同一把 `order-invoice:apply` 锁），**可重试** |
+
+#### 业务边界
+
+- 幂等：`@Idempotent` 5 秒窗口，口径同 §7。
+- 抢锁失败（100503）时零写入。
+- `requestedBy` 落库为用户 ID 字符串（区别于 admin 端落真实姓名），字段本身不在本次改动范围。
+- 老数据兼容：无字段变化。
+
+---
+
+## 四、契约约束与正确调用方式（接口类必写）
+
+> 本节只写**后端接受/拒绝 payload 的规则**，不写 UI 渲染建议。
+
+### 正确 / 错误的客户端处理方式
+
+本次不涉及请求体字段的互斥/联动规则变化，契约约束集中在"如何处理新失败码"：
+
+| 场景 | 处理方式 |
+|------|----------|
+| ✅ 收到 `code=100503` | 提示"另一个操作正在进行，请稍后重试"，**允许用户重试**，不当系统错误上报、不静默吞掉 |
+| ✅ 判断成功/失败 | 一律读响应体 `code`（`===200` 才算成功），不能只看 HTTP 状态码 |
+| ❌ 只看 HTTP 状态码 | `100503` 场景下 HTTP 仍是 200，只看状态码会把失败误判为成功，界面会"假装成功"但后端实际零写入 |
+| ❌ 把 `100503` 当致命错误弹全屏报错 | 应视为可重试的低频并发退避，不要引导用户联系客服或上报崩溃监控 |
+
+### 三组锁各自的互斥范围（不要混淆）
+
+| 锁 name | 互斥范围 | 不在范围内 |
+|---------|----------|------------|
+| `traveler:delete:order` | §1 admin 删除 / §2 mp 删除 / §3 internal Feign 删除，三者对**同一 orderId** | 出行人的新增/编辑（属于 `traveler:batch-edit` 组） |
+| `traveler:batch-edit` | §4 admin 批量编辑 / §5 订单调整提交（仅含出行人变更时）/ §6 mp 出行人补全，三者对**同一 orderId** | 出行人的删除（属于 `traveler:delete:order` 组）；§5 的非出行人子域（改期/行程/住宿/用车）与本锁无关 |
+| `order-invoice:apply` | §7 admin 申请 / §8 mp 申请，两者对**同一 orderId** | 「完成开票」`issueInvoice`、「重新上传」`reuploadInvoice`、「申请重开」`reissueInvoice`（那三者共用**另一把**锁 `order-invoice:issue`，已在 PR #8043 / changelog `20_7980_发票签发重传重开三写口补同一把锁新增100503冲突码触达C端-修改接口-管理后台.md` 中处理，与本文档不是同一组） |
+
+### 幂等与并发冲突的区别
+
+- 请求体**逐字节相同**且在幂等窗口内重复提交 → 幂等拦截，返回 `100502`（请勿重复提交），这是**另一个已存在的错误码**，本次不变。
+- 请求体**不同**或已过幂等窗口，但撞上组内另一写口正在执行的同订单请求 → 本次新增的 `100503`。
+
+---
+
+## 五、数据库行为（涉及写操作时必写）
+
+本次不改变任何一次**成功**写操作实际写入的行数或内容——8 个端点各自原有的写入逻辑（软删/桥接表级联/批量 upsert/发票 INSERT）逐字节不变。变化的只是"谁能在同一时刻对同一 orderId 执行本组写入"：
+
+| 组 | 改动前 | 改动后 |
+|----|--------|--------|
+| `traveler:delete:order` | admin/mp/internal 各持一把锁（internal 因自调用问题实际从未持锁），可并发互相踩踏「最后 1 位成人」内存计数 | 三者共享同一把锁，串行执行 |
+| `traveler:batch-edit` | admin/adjustment/mp 各持一把锁，可并发各读旧快照后各自写库 | 三者共享同一把锁，串行执行 |
+| `order-invoice:apply` | admin/mp 各持一把锁，可并发各读 `existsActive` 旧快照后各插一条申请 | 两者共享同一把锁，串行执行，一单一票才真正生效 |
+| 抢锁失败时是否有部分写入 | N/A（此前不会因锁而失败） | 否，零写入（`@Lock4j` 方法级环绕拦截，拿不到锁直接抛异常） |
+
+---
+
+## 六、边界行为
+
+- 未登录 → 401（网关拦截）
+- 订单不存在/不属于当前用户 → 581102/581110/581122/581470（各端点适用情况见上）
+- 出行人删除相关业务闸口（已签合同/最后成人）→ 581106/581107，不受本次改动影响
+- 出行人批量编辑校验矩阵（12301/格式/配额）→ 581101/581103/581104/581112-581114/581118/581119/581136，不受本次改动影响
+- mp 端状态门禁（订单确认后禁止自助改动）→ 581145，不受本次改动影响
+- 发票一单一票/状态门槛 → 581511/581524，不受本次改动影响
+- **抢锁超时（本次新增）→ 100503，HTTP 200，可重试，零写入**
+- 幂等窗口内重复提交（请求体相同）→ 100502，与本次改动无关，行为不变
+- 老数据兼容：本次不涉及字段增删，存量数据无需迁移
+
+---
+
+## 六.5、枚举 / 数据字典（接口出现枚举时必写）
+
+### 出行人性别（gender，出现于 §4/§6）
+
+**所属字段**: `travelers[].gender` | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `1` | 男 | - |
+| `2` | 女 | - |
+| `0` | 未知 | - |
+
+### 发票类型（invoiceType，出现于 §7/§8）
+
+**所属字段**: `invoiceType` | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `VAT_NORMAL` | 增值税普通发票 | 默认场景 |
+| `VAT_SPECIAL` | 增值税专用发票 | 要求 `titleType=COMPANY`，且税号/银行/注册信息 5 字段全必填 |
+
+### 发票抬头类型（titleType，出现于 §7/§8）
+
+**所属字段**: `titleType` | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `COMPANY` | 单位 | 抬头为公司名，`taxNo` 必填 |
+| `PERSONAL` | 个人 | 抬头为个人姓名，`taxNo` 非必填 |
+
+### 发票状态（status，出现于 §7/§8 出参）
+
+**所属字段**: `AdminInvoiceApplyRespVO.status` / `MpInvoiceApplyRespVO.status` | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `REQUESTED` | 待开票 | 申请成功后的初始状态（admin/mp 两端申请落库值一致，均为 `REQUESTED`） |
+
+## 六.6、修改前后对比（修改/删除类接口必写，新增跳过）
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 |
+|------|------|------|
+| （无）| 8 个接口的请求字段、响应字段逐字节不变 | 同左 |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| `traveler:delete:order` 组三入口并发 | 各持一把锁（internal 一支因自调用问题实际从未持锁），可并发破坏「最后 1 位成人」计数 | 三者共用同一把锁，串行执行 |
+| `traveler:batch-edit` 组三入口并发 | 各持一把锁，可并发各按旧快照写库 | 三者共用同一把锁，串行执行 |
+| `order-invoice:apply` 组两入口并发 | 各持一把锁，一单一票检查可被并发穿透 | 两者共用同一把锁，串行执行 |
+| 抢锁失败的响应 | 不存在这条路径 | 路径真实存在（返回 100503，HTTP 200，业务失败，可重试）；本次改动未部署测试服，无实测触发频率数据 |
+| 请求/响应字段、既有业务错误码 | 不变 | 不变 |
+
+## 六.7、影响评估（修改/删除类必写）
+
+- **是否破坏向后兼容**: 否——不改字段、不改既有错误码语义；但**新增了一条此前不存在的失败路径**（100503），且该路径会传导至小程序 C 端。
+- **前端是否必须同步上线**: 建议同步——尤其是小程序 C 端出行人补全/删除、发票申请三个入口，命中该分支时若前端无兜底会把失败误判为成功（HTTP 200）。**触发频率本文档未做任何测试服实测**，不可援引本工单其他 changelog（fleet 价格日历 #8035、发票签发 #8043）测试服实测出的"频率极低"结论——那是各自独立测量的结果，本组三把锁粒度均为单订单，与被测的价格日历/发票签发粒度不同，机制相同不代表频率相同。
+- **前端 workaround 清理点**: 无（本次是新增失败路径，不是清理旧 workaround）。
+
+## 七、不影响范围（显式声明, 帮前端/QA 缩小排查面）
+
+- **仅影响**: 上述 8 个端点，抢锁失败时的响应体
+- **零影响**:
+  - 出行人列表查询（`GET /v3/admin/order/{id}/traveler/list`）、出行人校验（`GET .../traveler/validate`）
+  - 单个出行人新增（`POST /v3/admin/order/{id}/traveler/add`，走另一把独立锁 `order:traveler:add:{id}`，本次未涉及）
+  - 大交通批次相关接口
+  - 发票的「完成开票」「重新上传」「申请重开」三个写口（属于另一把锁 `order-invoice:issue`，已在 #8043 处理，非本文档范围）
+  - 发票详情/列表/下载/企业信息自动回填等只读接口
+  - `order-ins:`（保险）/ `material:tag:name:`（resource）/ `fleet:msg-tpl:default:`（fleet）三组，本轮判定不修，行为未变
+  - 8 个端点的请求字段、响应字段结构
+  - 既有业务错误码的触发条件与文案
+  - 幂等拦截（100502）的行为
+  - 单个请求在**无并发**时的行为（延迟、返回值、写入内容全部不变）
+  - hl-gateway 路由配置——8 个端点路径/方法零变化
+
+---
+
+## 八、测试环境已验证
+
+**部署读数（2026-09-20 23:24）**：hl-order-service-v3 滚动更新两实例，部署前 `c35251b07` → 部署后 `ba8aab3ab`，8186 与 8086 各 12 秒内起监听，`deploy-backend.sh` 报 `rolling deploy complete`。`git merge-base --is-ancestor 43c53c4c9 ba8aab3ab` 返回 **ANCESTOR_YES**。
+
+🔴 本次**未在测试服做功能调用取证，这是有意为之而不是遗漏**：本组端点是删除出行人与批量改出行人，调用它们会**真实删改订单下的出行人行**；测试服订单数据被多个会话共用，删除**撤不回来**，副作用会落在一个不知情的人头上。
+
+互斥本身由**落库级并发 IT** `Lock4jSharedNameConcurrencyIT` 覆盖（3 条用例，含专为自调用入口 `deleteByInternal` 单写的一条），不变量是「订单至少留 1 位成人」；另有 `Lock4jSharedNameContractTest` 按 SpEL 反查全类、钉死三组的成员集合，**能抓住日后新加的第 N 个方法**。
+
+⚠️ **`100503` 在测试服上一次都没有触发过**——不是「测过、不会触发」，是**没测**。
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#7980](https://git.1814.love:8443/wx/HL/issues/7980)（AC-7）
+- 关联 PR: [wx/HL#8049](https://git.1814.love:8443/wx/HL/pulls/8049)
+- 相关（另一组锁，非本文档范围）: `changelogs-v2/2026-09/20_7980_发票签发重传重开三写口补同一把锁新增100503冲突码触达C端-修改接口-管理后台.md`（PR #8043，`order-invoice:issue` 锁）
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#7980](https://git.1814.love:8443/wx/HL/issues/7980)
+- **PR**: [#8049](https://git.1814.love:8443/wx/HL/pulls/8049)
+- **Merge commit**: [43c53c4c9](https://git.1814.love:8443/wx/HL/commit/43c53c4c9)（合并后回填，backend_status 待部署后翻转）
+
+### 联系人
+
+- **后端负责人**: @wx
@@ -0,0 +1,488 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7980"
+title: "发票签发组三个写口（admin 完成开票 / admin 重新上传 / mp 申请重开）补同一把 @Lock4j name，杜绝 reupload ∥ reissue 一单两票漏洞，新增可重试冲突码 100503（会传导至小程序 C 端）"
+consumer: "multiple"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "not_required"
+frontend_status: "not_required"
+frontend_owner: "mmg"
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "PR #8043 已 squash 合并 dev-v3(合并提交 09b8f2323)。2026-09-20 对 hl-order-service-v3 重跑了一次部署流程(滚动重启两实例),部署后 COMMIT=5d14bc524;git merge-base --is-ancestor 09b8f2323 5d14bc524 返回 YES,确认本次改动在运行版本内——但如实说明:部署前该服务已经是 5d14bc524(另一会话此前已把这个 commit 推上测试服),本次重跑部署没有让改动「从生效变生效」，只是重新确认了一遍。gateway_status=not_required 判据不变:三个端点路径/方法零变化,hl-gateway 一直是 4cbccc26b 未动,发票端点走网关实测全部正常返回。🔴 测试服直接证据(redis-cli MONITOR)只覆盖三处写口中的一处——issueInvoice;另两处(reuploadInvoice/reissueInvoice)由代码改动本身(与 issueInvoice 逐字相同的 name/keys)与反射守卫单测 InvoiceIssueLockNameGuardTest(断言三处 name 非空且相等)覆盖,未在测试服上单独抓包或调用,不要读成三处都实测过互斥。100503 本身测试服未能复现(并发两个 issueInvoice 得到 200+581502,不是 100503;581502 是业务状态守卫,证明没有产生并发脏写,但只是旁证不是互斥证据);原因判断同 fleet 那轮,临界区极短。frontend_status=pending 维持不变,详见「八、测试环境已验证」完整记录。 前端实证翻 not_required(mmg 2026-09-20):admin 侧 issue/reupload 封装于 api/invoice.js,唯一调用方 IssueModal handleSubmit catch「业务错误码由 request.js 拦截器统一 toast」、finally 复位 submitting,100503 命中拦截器透后端「资源被占用,请稍后重试」原样展示(提示可重试/不静默/不当系统异常三条全满足),同 fleet #7980 先例不建字典;mp reissue 传导 C 端属小程序系列,由 mp loop 消费。"
+updated_at: "2026-09-20"
+base: "dev-v3"
+---
+
+# order-v3: 发票签发组三个写口补同一把 @Lock4j name，新增可重试冲突码 100503（会传导至小程序 C 端）
+
+> **存放目录**:
+> - 一期(v2,无 `order-v3` 标签的工单)→ `changelogs/{YYYY-MM}/`
+> - 二期(v3,`order-v3` 标签的工单)→ `changelogs-v2/{YYYY-MM}/`
+>
+> **服务**: hl-order-service-v3（另涉 hl-mp-service 两个透传入口）
+> **PR**: #8043
+> **Issue**: #7980（AC-4）
+> **日期**: 2026-09-20
+> **影响范围**: 管理后台「发票财务管理」的「完成开票」「重新上传」两个写操作 + 小程序 C 端「申请重开发票」
+
+---
+
+## ⚠️ 关键变化（非必须,本版与上版行为不同 / 纠错 / 撤销时必写）
+
+- `InvoiceAdminService.issueInvoice`、`InvoiceAdminService.reuploadInvoice`、`InvoiceMpService.reissueInvoice` 三处 `@Lock4j` 此前写了**逐字相同**的 `keys`（`'order-invoice:issue:' + #invoiceId`），却都**没写 `name`**——lock4j 落 Redis 的锁键含方法名，`name` 缺省时退化为「全限定类名 + 方法名」，于是三个方法**各持一把互不相干的锁**，可以并发互相踩踏。
+- 后果是真实数据缺陷：**`reupload ∥ reissue` 会在同一张发票上留下两行非 VOIDED 记录**——`reissue` 先把旧票置 `VOIDED` 并插入新票（`REQUESTED`），随后 `reupload` 把（已经作废的）旧票又写回 `ISSUED`，`order_invoice` 表上无 `UNIQUE`、`OrderInvoice` 实体无 `@Version`，没有第二道兜底能挡住这个结果。
+- 本次给三处补上**同一个**显式 `name = "order-invoice:issue"`，三者才真正互斥（同一张发票的开票/重传/重开现在会排队执行）。**接口路径、请求/响应字段、既有错误码全部零增删**，唯一的契约变化是新增一个可能返回的失败码。
+- 🔴 **新增的失败路径会到达小程序 C 端**：用户点「申请重开发票」时，若财务端此刻正在同一张票上做「完成开票」或「重新上传」，会等待最多约 3 秒后收到 **`code=100503`**（"资源被占用,请稍后重试"）。**传输层仍是 HTTP 200**，失败信息在响应体的 `code` 字段里——前端如果只看 HTTP 状态码会把这次失败误判为成功。反向同理：财务端两个接口也可能因为 C 端正在 `reissue` 而收到同一个码。
+- 🔴 **两句话都要看，缺一句都会误判**：
+  1. **这条失败路径源码级真实存在**——`acquireTimeout` 默认 3000ms、超时经 `LockFailureExceptionHandler` 统一转 `100503`、`@ResponseStatus(HttpStatus.OK)` 确认 HTTP 200 + body 携带业务码，这套链路已逐行读码确认；`InvoiceIssueLockConcurrencyIT` 的持锁超时用例实测到等待约 3024ms 后抛出该码。
+  2. **但触发概率极低**——同一用例测得三者中任一方法单次临界区（一次 `UPDATE`/一次 `UPDATE`+一次 `INSERT`）实测上界约 89ms，远小于 3000ms 的 `acquireTimeout`，只有同一 `invoiceId` 在同一瞬间被两个写口同时命中才会撞上。**这不代表它不会发生**，前端仍应做防御性处理（识别 `code=100503` 提示可重试），但不必按高频交互设计。
+- ✅ **测试服部署已确认，但直接证据只覆盖三处写口中的一处**：2026-09-20 `hl-order-service-v3` 测试服 COMMIT `5d14bc524` 已含本次改动（`git merge-base --is-ancestor 09b8f2323 5d14bc524` → YES）。`redis-cli MONITOR` 实时抓包证实调用 `issueInvoice` 时锁键与预期完全一致、无方法名混入——但这**只验证了 `issueInvoice` 一处**；`reuploadInvoice`/`reissueInvoice` 另两处未在测试服上单独抓包或调用，是由代码改动本身（与 `issueInvoice` 逐字相同的 `name`/`keys`）与反射守卫单测 `InvoiceIssueLockNameGuardTest` 覆盖的，**不要读成"三处共用同一把锁"已在测试服实测确认**。
+- 🔴 **100503 测试服未能复现，且第二次读数不是它本来该是的样子**：对同一发票并发发两个 `issueInvoice`，一个 `code=200`，另一个是 **`code=581502`**（`INVOICE_CANNOT_ISSUE` 业务状态守卫），**不是 100503**。这说明没有产生并发脏写（第二个请求命中的是"状态已不是 REQUESTED"的正常业务拒绝），但**这是旁证，不是互斥证据**——不能拿它证明锁生效，只能证明没有出现数据损坏。原因判断与 fleet 那一轮相同：单次临界区极短（上界约 89ms），远小于 3 秒超时。
+
+---
+
+## 一、背景
+
+`InvoiceAdminService.issueInvoice`（完成开票）、`InvoiceAdminService.reuploadInvoice`（重新上传）、`InvoiceMpService.reissueInvoice`（C 端申请重开）三个方法操作的是同一张 `order_invoice` 记录，前置条件互相重叠（`reuploadInvoice` 与 `reissueInvoice` 都要求旧票处于 `ISSUED`/`PUSHED`），三处代码注释里都写着「并发: @Lock4j 串行化」，但三个 `@Lock4j` 的 SpEL `keys` 虽逐字相同，`name` 全部缺省。lock4j 生成的实际 Redis 锁键是 `<name>#<keys 求值>`，`name` 缺省时用「方法所在类全限定名 + 方法名」兜底，三个方法名不同 ⇒ 三把不同的锁，注释里承诺的"串行化"此前并不成立。工单 #7980 AC-4 给三处补齐同一个显式 `name`，串行化才真正生效。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 完成开票 | PUT | `/v3/admin/order/invoice/{id}/issue` | 新增可能返回的错误码 | 抢锁超时返 100503（原接口/字段不变） |
+| 2 | 重新上传发票文件 | PUT | `/v3/admin/order/invoice/{id}/reupload` | 新增可能返回的错误码 | 抢锁超时返 100503（原接口/字段不变） |
+| 3 | 申请重开发票（mp internal） | POST | `/v3/internal/mp/order/invoice/{invoiceId}/reissue` | 新增可能返回的错误码 | 抢锁超时返 100503；经 hl-mp-service 两个透传入口到达小程序 C 端（见第 3 节业务边界） |
+
+---
+
+## 三、接口详情
+
+### 1. 完成开票 `PUT /v3/admin/order/invoice/{id}/issue`
+
+**VO**: `InvoiceIssueReqVO → Void`
+
+#### 使用场景
+
+财务在管理后台「发票财务管理」列表里，对状态为 `REQUESTED`（待开票）的发票执行开票：先调 `POST /v3/admin/order/invoice/upload` 上传文件拿到 `fileUrl`，再调本接口把发票状态从 `REQUESTED` 推进到 `ISSUED`，同时落 `issued_at`/`issued_by`，开票金额由后端此刻自动计算写入。本次改动不涉及本接口的入参/出参字段，只新增一条"被 `reupload`/`reissue` 占用同一把锁"的失败分支。
+
+#### 入参
+
+路径参数 `id`（发票 ID）+ Body：
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| id | Path | Long | ✅ | - | 发票 ID |
+| fileUrl | Body | String | ✅ | `@NotBlank` | 发票文件 OSS URL（由 `/upload` 接口返回） |
+| pdfName | Body | String | ✅ | `@NotBlank` | 发票 PDF 文件名 |
+| pdfSize | Body | Long | ✅ | `@NotNull` | 文件大小（字节） |
+| invoiceNo | Body | String | - | - | 发票号（财务登记） |
+
+#### 出参 `Result<Void>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data | null | 无返回数据，`Result.data` 恒为 `null` |
+
+#### 请求示例
+
+```json
+{
+  "fileUrl": "https://oss.example.com/invoice/abc.pdf",
+  "pdfName": "发票_2026062100001.pdf",
+  "pdfSize": 204800,
+  "invoiceNo": "25441000000123456789"
+}
+```
+
+#### 响应示例
+
+```json
+{ "code": 200, "message": "成功", "data": null, "success": true }
+```
+
+#### 空数据 / 降级响应
+
+本接口无「空数据」概念（成功恒返回 `data: null`），也没有降级路径。
+
+#### 错误响应
+
+```json
+{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false }
+```
+
+| code | 触发条件 |
+|------|----------|
+| 400 | 参数校验失败（`fileUrl`/`pdfName`/`pdfSize` 缺失） |
+| 581500 | 发票不存在（`INVOICE_NOT_FOUND`） |
+| 581502 | 发票当前状态不是 `REQUESTED`，不允许开票（`INVOICE_CANNOT_ISSUE`） |
+| 581525 | 订单核单未完成（`reviewStatus≠COMPLETED`），不可开票（`INVOICE_ORDER_NOT_REVIEWED`） |
+| **100503（本次新增）** | 抢锁等待超过 3 秒（本组另一写口——`reupload` 或 C 端 `reissue`——正持有 `order-invoice:issue` 锁），**可重试** |
+| 401 | 未登录（网关拦截） |
+
+**实测说明**（本接口是三处写口中唯一在测试服上单独取证的一处）：
+
+- IT 层（`InvoiceIssueLockConcurrencyIT`）：100503 路径源码级真实存在——持锁方在 `acquireTimeout`（默认 3000ms）内未释放时，后到方约等待 3024ms 后收到该码；正常场景下单次临界区实测上界约 89ms，远小于超时阈值。
+- 测试服层（2026-09-20，`hl-order-service-v3` COMMIT `5d14bc524`）：`redis-cli MONITOR` 抓包证实真实调用锁键为 `lock4j:order-invoice:issue#order-invoice:issue:{invoiceId}`，无方法名混入；并发发两个 `issueInvoice`（同一发票）实测结果是一个 `200`、另一个 **`581502`（业务状态守卫）而不是 100503**——证明没有并发脏写，但这是旁证不是互斥证据，100503 本身未在测试服复现；单独调一次 `issueInvoice` 回归 `code=200`，正常路径未受影响。详见「⚠️ 关键变化」与「八、测试环境已验证」。
+
+#### 业务边界
+
+- 无 `@Idempotent` 保护（与本组其他历史改动不同）：本接口只有 `@Lock4j` 串行化 + `REQUESTED` 状态守卫去重，双击/网络重试若落在"状态已不是 `REQUESTED`"会走 581502，不是幂等拦截。
+- 抢锁失败（100503）时该次请求**未进入方法体，零写入**——`@Lock4j` 是方法级环绕拦截，拿不到锁直接抛异常，业务代码一行不会执行。
+- 金额此刻由后端自动计算写入（`CANCELLED` 订单取净实收 `paid-refunded`，其余取应收总额），不接受前端传入金额。
+- 老数据兼容：无字段变化，不涉及旧数据兼容问题。
+
+---
+
+### 2. 重新上传发票文件 `PUT /v3/admin/order/invoice/{id}/reupload`
+
+**VO**: `InvoiceReuploadReqVO → Void`
+
+#### 使用场景
+
+财务对状态为 `ISSUED`/`PUSHED` 的发票覆盖上传新文件（不作废旧发票、不新建发票，只更新文件字段 + `issued_at`/`issued_by`）。本次改动不涉及本接口的入参/出参字段，只新增一条"被 `issue`/`reissue` 占用同一把锁"的失败分支——补锁之前，`reupload` 与 C 端 `reissue`（两者前置条件同样是 `ISSUED`/`PUSHED`）能同时进入临界区，是本工单要堵的主要漏洞场景（见「⚠️ 关键变化」）。
+
+#### 入参
+
+路径参数 `id`（发票 ID）+ Body：
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| id | Path | Long | ✅ | - | 发票 ID |
+| fileUrl | Body | String | ✅ | `@NotBlank` | 新发票文件 OSS URL（由 `/upload` 接口返回） |
+| pdfName | Body | String | ✅ | `@NotBlank` | 发票 PDF 文件名 |
+| pdfSize | Body | Long | ✅ | `@NotNull` | 文件大小（字节） |
+| invoiceNo | Body | String | - | - | 发票号（如有变更可更新） |
+
+#### 出参 `Result<Void>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data | null | 无返回数据，`Result.data` 恒为 `null` |
+
+#### 请求示例
+
+```json
+{
+  "fileUrl": "https://oss.example.com/invoice/abc_v2.pdf",
+  "pdfName": "发票_2026062100001_v2.pdf",
+  "pdfSize": 204800,
+  "invoiceNo": "25441000000123456789"
+}
+```
+
+#### 响应示例
+
+```json
+{ "code": 200, "message": "成功", "data": null, "success": true }
+```
+
+#### 空数据 / 降级响应
+
+本接口无「空数据」概念（成功恒返回 `data: null`），也没有降级路径。
+
+#### 错误响应
+
+```json
+{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false }
+```
+
+| code | 触发条件 |
+|------|----------|
+| 400 | 参数校验失败（`fileUrl`/`pdfName`/`pdfSize` 缺失） |
+| 581500 | 发票不存在（`INVOICE_NOT_FOUND`） |
+| 581503 | 发票当前状态不是 `ISSUED`/`PUSHED`，不允许重新上传（`INVOICE_CANNOT_REUPLOAD`） |
+| 581525 | 订单核单未完成，不可重传（`INVOICE_ORDER_NOT_REVIEWED`） |
+| **100503（本次新增）** | 抢锁等待超过 3 秒（本组另一写口——`issue` 或 C 端 `reissue`——正持有 `order-invoice:issue` 锁），**可重试** |
+| 401 | 未登录（网关拦截） |
+
+**实测说明**：IT 层链路与第 1 节一致（同一 `InvoiceIssueLockConcurrencyIT`，触发条件同为等待超过 `acquireTimeout` 3000ms）。🔴 但**本接口未在测试服上单独抓包或调用**——2026-09-20 测试服直接证据只覆盖 §1 `issueInvoice`；本接口的锁互斥依据是代码改动本身（`reuploadInvoice` 与 `issueInvoice` 使用逐字相同的 `name="order-invoice:issue"`/`keys`）以及反射守卫单测 `InvoiceIssueLockNameGuardTest`（断言三处 `name` 非空且相等），不是独立的测试服实测。
+
+#### 业务边界
+
+- 无 `@Idempotent` 保护，仅 `@Lock4j` 串行化 + `canReupload`（`ISSUED`/`PUSHED`）状态守卫去重。
+- 抢锁失败（100503）时该次请求零写入，旧文件字段不会被覆盖。
+- 不作废旧发票、不新建发票，只更新文件字段（对齐修复旧 mp 端 reissue 守卫永远抛错的历史 bug：旧逻辑要求 `ISSUED`/`UPLOADED`/`DELIVERED`，但全系统无代码写入后两态）。
+- 老数据兼容：无字段变化，不涉及旧数据兼容问题。
+
+---
+
+### 3. 申请重开发票（mp internal） `POST /v3/internal/mp/order/invoice/{invoiceId}/reissue`
+
+**VO**: `InvoiceReissueReqVO → InvoiceReissueRespVO`
+
+#### 使用场景
+
+小程序 C 端用户对状态为 `ISSUED`/`PUSHED` 的已开发票申请「重开」（改抬头/税号等）：后端把旧发票置 `VOIDED`，同事务插入一张继承旧票字段、按请求覆盖可改字段的新发票（`REQUESTED`，待财务重新开票）。这是 `hl-order-service-v3` 的 internal 接口，**C 端用户不会直接访问它**，而是通过 `hl-mp-service` 的两个公网入口调用（见下方「业务边界」）。本次改动不涉及本接口的入参/出参字段，只新增一条"被 `issue`/`reupload` 占用同一把锁"的失败分支。
+
+#### 入参
+
+路径参数 `invoiceId`（旧发票 ID）+ Body：
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| invoiceId | Path | Long | ✅ | - | 旧发票 ID |
+| invoiceType | Body | String | ✅ | `@NotBlank`，枚举见六.5 | 发票类型 |
+| titleType | Body | String | ✅ | `@NotBlank`，枚举见六.5 | 抬头类型 |
+| titleName | Body | String | ✅ | `@NotBlank`，≤100 字符 | 发票抬头名称 |
+| taxNo | Body | String | 条件必填 | ≤30 字符 | 税号（`titleType=COMPANY` 时必填） |
+| email | Body | String | ✅ | `@Email`，≤100 字符 | 收件邮箱 |
+
+`orderId`/`amount` 由后端反查旧发票得出，前端不传；`userId` 从鉴权头解析。
+
+#### 出参 `Result<InvoiceReissueRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| oldInvoiceId | Long | 被作废的旧发票 ID |
+| oldInvoiceStatus | String | 旧发票状态（固定 `VOIDED`） |
+| newInvoiceId | Long | 新申请的发票 ID |
+| newInvoiceStatus | String | 新发票状态（固定 `REQUESTED`，待财务开票） |
+| mqEventName | String | 已发布 MQ 事件名（本批不发 MQ，恒为 `null`） |
+| appliedAt | LocalDateTime | 申请时间 |
+
+#### 请求示例
+
+```json
+{
+  "invoiceType": "VAT_NORMAL",
+  "titleType": "COMPANY",
+  "titleName": "上海呼籁旅行科技有限公司（新）",
+  "taxNo": "91310115MA1K48XXXX",
+  "email": "finance2@hulalv.com"
+}
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "oldInvoiceId": 77001234567001,
+    "oldInvoiceStatus": "VOIDED",
+    "newInvoiceId": 77001234567003,
+    "newInvoiceStatus": "REQUESTED",
+    "mqEventName": null,
+    "appliedAt": "2026-05-10T14:30:25"
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+本接口无「空数据」概念（成功恒返回完整 `InvoiceReissueRespVO`）。降级路径：`hl-mp-service` 到 `hl-order-service-v3` 的 Feign 熔断打开时，`MpV3InvoiceFeignFallbackFactory` 返回 `Result.error("发票服务不可用，请稍后重试")`（`code=500`，此为既有降级行为，本次未改动）。
+
+#### 错误响应
+
+```json
+{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false }
+```
+
+| code | 触发条件 |
+|------|----------|
+| 400 | 参数校验失败（`titleName`/`email` 等缺失或格式非法） |
+| 581500 | 旧发票不存在，或旧发票所属订单不属于当前用户（`INVOICE_NOT_FOUND`，IDOR 场景统一返此码，不额外区分"不存在"与"无权限"） |
+| 581501 | 旧发票状态不是 `ISSUED`/`PUSHED`，不可重开（`INVOICE_NOT_VOIDABLE`） |
+| 581513 | 发票类型非法（须 `VAT_NORMAL`/`VAT_SPECIAL`） |
+| 581516 | 收件邮箱为空 |
+| 581523 | 增值税专用发票只能开给单位（`titleType` 须为 `COMPANY`） |
+| 581524 | 订单当前状态不可申请开票（`INVOICE_ORDER_NOT_APPLICABLE`） |
+| **100503（本次新增）** | 抢锁等待超过 3 秒（本组另一写口——`issue` 或 `reupload`——正持有 `order-invoice:issue` 锁），**可重试** |
+
+**实测说明**：IT 层链路与第 1 节一致；`InvoiceIssueLockConcurrencyIT` 的两条用例分别覆盖"未超时→排队成功"和"超时→100503"两个分支，落库结果同一订单下非 `VOIDED` 票恰好一行，无一单两票残留。🔴 但**本接口未在测试服上单独抓包或调用**——2026-09-20 测试服直接证据只覆盖 §1 `issueInvoice`；本接口（`hl-order-service-v3` internal，经 `hl-mp-service` 两个透传入口对外）的锁互斥依据是代码改动本身（`reissueInvoice` 与 `issueInvoice` 使用逐字相同的 `name="order-invoice:issue"`/`keys`）以及 `InvoiceIssueLockNameGuardTest`，不是独立的测试服实测。
+
+#### 业务边界
+
+- 🔴 **C 端实际入口有两个，均在 `hl-mp-service`，网关路由未变**：
+  - `POST /mp/v3/order/invoice/{invoiceId}/reissue`（`MpV3InvoiceController`，`hl-mp-service/.../mp/controller/v3/MpV3InvoiceController.java:54`）：`return invoiceFeignClient.reissueInvoice(invoiceId, req);` **直接透传** Feign 返回的 `Result`，`code=100503` 与 `message` 原样保留，HTTP 200。
+  - `POST /mp/invoice/{invoiceId}/reissue`（`MpInvoiceController`，`hl-mp-service/.../mp/controller/MpInvoiceController.java:108`）：调用 `invoiceFeignClient.reissueInvoice(invoiceId, req).getCheckedData()`，`Result.getCheckedData()`（`Result.java:143-152`）在 `!isSuccess()` 时 `throw new BusinessException(this.code, this.message)`，即抛出 `BusinessException(100503, "资源被占用,请稍后重试")`；该异常在 `hl-mp-service` 自己的 `GlobalExceptionHandler.handleBusiness` 里被捕获，同样标注 `@ResponseStatus(HttpStatus.OK)`，重新包装成 `Result.error(100503, "资源被占用,请稍后重试")`。**两条路径最终都是 HTTP 200 + body.code=100503**，只是中转方式不同（透传 vs 解包重抛），前端不用区分走的是哪一个入口，统一按 `code=100503` 处理即可。
+- 抢锁失败（100503）时该次请求零写入：旧发票不会被置 `VOIDED`，不会插入新发票行——不存在"部分成功"的中间态。
+- 无 `@Idempotent` 保护，仅 `@Lock4j` 串行化 + `canReupload` 状态守卫去重（杜绝两个并发 `reissue` 请求各读旧票 `ISSUED` 快照后各自 `VOIDED` 旧票并各插一条新票）。
+- `bankName`/`bankAccount`/`registAddress`/`registPhone` 四个专票字段在 `reissue` 中**继承旧发票**，请求体不传；`invoiceType`/`titleType`/`taxNo`/`email` 未传时同样继承旧发票对应字段。
+- 老数据兼容：无字段变化，不涉及旧数据兼容问题。
+
+---
+
+## 四、契约约束与正确调用方式（接口类必写）
+
+> 本节只写**后端接受/拒绝 payload 的规则**，不写 UI 渲染建议。
+
+### ✅ 正确 / ❌ 错误 客户端处理方式
+
+本次不涉及请求体字段的互斥/联动规则变化，契约约束集中在"如何处理新失败码"：
+
+| 场景 | 处理方式 |
+|------|----------|
+| ✅ 收到 `code=100503` | 提示"另一个开票相关操作正在进行，请稍后重试"，**允许用户重试**，不当系统错误上报、不静默吞掉 |
+| ✅ 判断成功/失败 | 一律读响应体 `code`（`===200` 才算成功），不能只看 HTTP 状态码 |
+| ❌ 只看 HTTP 状态码 | `100503` 场景下 HTTP 仍是 200，只看状态码会把失败误判为成功，前端界面会"假装成功"但后端实际零写入 |
+| ❌ 把 `100503` 当致命错误弹全屏报错 | 应视为可重试的低频并发退避，不要引导用户联系客服或上报崩溃监控 |
+
+### 切换状态时的必要动作
+
+本次改动不涉及"要么 A 要么 B"的字段互斥关系。唯一需要前端配合的动作是：同一张发票的「完成开票」「重新上传」「申请重开发票」三个操作现在会互相排队，如果产品设计上允许财务与用户在同一张发票上短时间内各自发起操作，两侧都需要能正确展示 `100503` 的重试提示，而不是分别按"我这边一定成功"设计交互。
+
+---
+
+## 五、数据库行为（涉及写操作时必写）
+
+| 场景 | `order_invoice` 表行为（改动前） | `order_invoice` 表行为（改动后） |
+|------|------|------|
+| `reupload` 持锁期间 `reissue` 并发进来 | 两者都能进入临界区：`reissue` 先把旧票置 `VOIDED` 并插入新票（`REQUESTED`），`reupload` 随后把（已作废的）旧票又写回 `ISSUED` ⇒ 同一订单出现**两行非 VOIDED**（旧 `ISSUED` + 新 `REQUESTED`），数据不一致 | `reissue` 在 `reupload` 持锁期间抢锁失败，直接返回 `100503`，**不执行任何 UPDATE/INSERT**；`reupload` 完成释放锁后 `reissue` 才能进入临界区（或超过 3 秒被拒） |
+| `issue`/`reupload`/`reissue` 各自的写操作本身 | 无变化：`issue` 写 `status=ISSUED`+`issued_at`+`issued_by`+`amount`；`reupload` 写文件相关字段；`reissue` 一次 UPDATE（旧票→`VOIDED`）+ 一次 INSERT（新票 `REQUESTED`） | 无变化，只是三者现在对同一 `invoiceId` 串行化执行 |
+
+**无 `SET NULL` 相关行为**：本次改动不涉及任何列的置空规则，三个方法各自写入的列集合与改动前完全一致。
+
+---
+
+## 六、边界行为
+
+- 未登录 → 401（网关拦截）
+- 发票不存在 / 无权限（IDOR） → 581500（`INVOICE_NOT_FOUND`，两种场景统一返此码，不额外泄露"存在但不属于你"）
+- 下游 `hl-order-service-v3` 不可用（熔断打开）→ `hl-mp-service` 侧 `MpV3InvoiceFeignFallbackFactory` 返 `code=500`（既有行为，本次未改）
+- 抢锁失败 → 100503，HTTP 仍 200，本次新增的唯一边界分支，零写入
+- 老数据兼容 → 本次不涉及字段增删，存量发票记录无需迁移，行为在锁生效前后对"未并发"的单次请求完全一致
+
+---
+
+## 六.5、枚举 / 数据字典（接口出现枚举时必写）
+
+### 发票状态（`com.hulalv.invoice.enums.InvoiceStatus`）
+
+**所属字段**: `oldInvoiceStatus`/`newInvoiceStatus`（本节第 3 个接口出参）；决定 `reupload`/`reissue` 是否可执行的判据字段 | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `REQUESTED` | 待开票 | 已申请，等待财务开票；`issue` 只接受此状态 |
+| `ISSUED` | 已开票 | 已上传文件，用户可查看/下载；`reupload`/`reissue` 只接受此状态或 `PUSHED` |
+| `PUSHED` | 已推送 | 已推送客户（本期不真发通知，仅落状态）；`reupload`/`reissue` 同样接受 |
+| `VOIDED` | 已作废 | 终态，由 `reissue` 副作用产生；不可再 `reupload`/`reissue` |
+
+### 抬头类型（`titleType`，本节第 3 个接口入参）
+
+**所属字段**: `InvoiceReissueReqVO.titleType` | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `PERSONAL` | 个人 | 抬头为个人姓名，`taxNo` 非必填 |
+| `COMPANY` | 单位 | 抬头为公司名，`taxNo` 必填；`invoiceType=VAT_SPECIAL` 时只能是此值（否则 581523） |
+
+### 发票类型（`invoiceType`，本节第 3 个接口入参）
+
+**所属字段**: `InvoiceReissueReqVO.invoiceType` | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `VAT_NORMAL` | 增值税普通发票 | 默认场景 |
+| `VAT_SPECIAL` | 增值税专用发票 | 要求 `titleType=COMPANY`，且 `taxNo`/银行信息/注册信息在申请阶段已齐（`reissue` 继承旧票） |
+
+---
+
+## 六.6、修改前后对比（修改/删除类接口必写，新增跳过）
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 |
+|------|------|------|
+| （无） | 三个接口的请求体/响应体字段**零变化** | 同左 |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| `issue`/`reupload`/`reissue` 三者的并发关系 | 各自持有一把不同的锁（`name` 缺省退化为类名+方法名），互不阻塞 | 三者共享同一把锁（`name="order-invoice:issue"`），对同一 `invoiceId` 串行化执行 |
+| `reupload ∥ reissue` 并发结果 | 可能在同一订单下留下两行非 `VOIDED`（旧 `ISSUED` + 新 `REQUESTED`），数据不一致 | 后到方抢锁失败直接拒绝（100503）或排队等待，落库结果始终只有一行非 `VOIDED` |
+| 新增的失败码 | 无 | `100503`（`RESOURCE_LOCKED`），HTTP 200 + body.code=100503；路径真实存在（`issueInvoice` 测试服已实测确认锁键；另两处依赖代码同源+反射守卫用例覆盖），但测试服并发实测未触发 100503 本身，实际频率极低 |
+
+---
+
+## 六.7、影响评估（修改/删除类必写）
+
+- **是否破坏向后兼容**: 否——三个接口的请求体/响应体字段、既有错误码全部零增删，正常（无并发）场景下行为与改动前完全一致。
+- **前端是否必须同步上线**: 是——小程序 C 端与管理后台前端都需要能识别 `code=100503` 并提示"稍后重试"，否则用户会在极低概率下看到 HTTP 200 却操作失败、且没有任何提示的情况（当前前端逻辑若只判断 HTTP 状态码或只处理已知错误码列表，会把这次失败静默吞掉或误判成功）。
+- **前端 workaround 清理点**: 无——本次不涉及此前的前端兜底/反推逻辑。
+
+---
+
+## 七、不影响范围（显式声明, 帮前端/QA 缩小排查面）
+
+- **仅影响**: 管理后台「发票财务管理」的「完成开票」「重新上传」两个写操作 + 小程序 C 端「申请重开发票」（含其两个 hl-mp-service 入口）在**并发**场景下的失败分支
+- **零影响**:
+  - 发票申请接口（`adminApplyInvoice`/`mpApplyInvoice`，两者的并发漏洞属于 #7980 P2，本工单未修，见 `InvoiceAdminService.adminApplyInvoice` 方法注释）
+  - 发票详情、列表、下载、推送、企业信息自动回填等只读或非本组写接口
+  - 三个接口自身的入参校验、状态机判定、金额计算等既有业务逻辑（未改动一行）
+  - 单次请求（无并发命中）下的行为——三个接口改动前后表现完全一致
+  - hl-gateway 路由配置——三个端点路径/方法零变化
+
+---
+
+## 八、测试环境已验证
+
+### 部署
+
+`hl-order-service-v3` 部署后 COMMIT = **`5d14bc524`**（滚动重启两实例均 UP）。
+
+⚠️ **如实说明**：部署**前**它已经是 `5d14bc524`（`BEHIND 0/N`）——另一会话此前已把该 commit 推上测试服；本次是重新走了一遍部署流程，COMMIT 没有变化，**不是本次部署使改动生效**，本次部署只是重新确认了一遍。
+
+祖先链判定（仓库目录 `/opt/hulalv/HL`，`git fetch origin dev-v3` 后）：`git merge-base --is-ancestor 09b8f2323 5d14bc524` → **YES**（#7980 AC-4 的合并提交已在运行版本内）。
+
+`hl-gateway` 一直是 `4cbccc26b`（`BEHIND 70/Y`），**未动**；发票端点走网关全部正常返回，本次取证不受影响。
+
+### 🔴 直接证据（证据 A）——只覆盖三处写口中的一处
+
+`redis-cli MONITOR`（db 0，连接参数取自 Nacos `hl-order-service-v3-test.yml`）实时抓包，调用 `issueInvoice`（`invoice_id=2100889866400104450`）时捕获：
+
+```
+EVALSHA ... "lock4j:order-invoice:issue#order-invoice:issue:2100889866400104450" ... "30000"
+lua "set" 同键 ... "NX" "PX" "30000"
+lua "get" / "del" 同键
+```
+
+键形与期望完全一致、**没有方法名混入** ⇒ 证明补丁在**运行的字节码里**生效。
+
+**但这里必须收窄，不要读成"三处共用同一把锁"已被测试服实测确认**：MONITOR 实际只跑了三个写口里的一个（`issueInvoice`）。正确表述是——**测试服直接证据覆盖三处中的一处（`issueInvoice`）；另两处（`reuploadInvoice`/`reissueInvoice`）由代码改动本身与反射守卫用例 `InvoiceIssueLockNameGuardTest`（断言三处 `name` 非空且相等）覆盖，未在测试服上单独抓包**。
+
+### 100503 未复现（证据 B）
+
+对另一张票并发发两个 `issueInvoice`，一个 `code=200`，另一个是 **`code=581502`**（`INVOICE_CANNOT_ISSUE` 业务状态守卫）——**不是 `100503`**。
+
+如实说明：**未打出锁超时码**，原因仍是临界区极短（与 fleet 那轮 34 并发未触发同因）。第二个请求是被**业务状态守卫**拦下，说明没有产生并发脏写，但**这是旁证，不是互斥证据**——不能拿它证明锁真的挡住了并发，只能证明这次没有观察到数据损坏。
+
+两面都要写：路径源码级真实存在（已读码确认 + `InvoiceIssueLockConcurrencyIT` 实测过等待约 3024ms 后抛出该码），但**测试服未能触发**，不代表更长事务/更大载荷/生产数据量下不会触发。
+
+### 回归（证据 C）
+
+单独调一次 `issueInvoice`，`code=200`，正常路径未被锁破坏。**这是回归证据，不与互斥证据混同。**
+
+### 取证是干净的
+
+三张发票全是测试夹具（客户名「核团甲/乙/丙」，`apply_reason` 写着 #7932 造数）。改前均 `REQUESTED / NULL / NULL`，改后 `ISSUED` + 金额 + 票号，**已按改前快照逐列 UPDATE 还原**（含 `file_url`/`pdf_name`/`pdf_size`/`issued_at`/`issued_by`/`update_time`），复读与改前完全一致；Redis 侧 `--scan lock4j:*order-invoice*` 复扫为空，无残留锁键。
+
+⚠️ 过程中发生过**一次 `code=401`**（token 被别的会话顶掉），该次调用之前没有任何读数，已重新登录并把那一段整个重做，**证据 A 用的是重登后的结果**——这一条也计入取证可信度的一部分。
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#7980](https://git.1814.love:8443/wx/HL/issues/7980)（AC-4）
+- 关联 PR: [wx/HL#8043](https://git.1814.love:8443/wx/HL/pulls/8043)
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#7980](https://git.1814.love:8443/wx/HL/issues/7980)
+- **PR**: [#8043](https://git.1814.love:8443/wx/HL/pulls/8043)
+- **Merge commit**: [09b8f2323](https://git.1814.love:8443/wx/HL/commit/09b8f2323)
+
+### 联系人
+
+- **后端负责人**: @wx
@@ -0,0 +1,762 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7980"
+title: "配房工作台七个写口（提交/单日确认/位置调整/清空全部/清空当天/转单/释放）补同一把 @Lock4j name，新增可重试冲突码 100503（接口路径/字段零增删）"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "not_required"
+frontend_status: "not_required"
+frontend_owner: "mmg"
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "PR #8069 已 squash 合并 dev-v3（合并提交 b9738a20f）。2026-09-20 23:24 已部署测试服 hl-order-service-v3：滚动更新两实例，部署前 COMMIT=c35251b07、部署后 COMMIT=ba8aab3ab，8186 与 8086 各 12 秒内起监听。`git merge-base --is-ancestor b9738a20f ba8aab3ab` 返回 ANCESTOR_YES。🔴 并且部署前 `b9738a20f` 确实不在 `c35251b07` 内（同一判据返回 NO），即本次部署是真正的「从不生效到生效」，不是重跑一遍确认。gateway_status=not_required：端点路径/方法零变化，本次与网关路由无关，不是漏验证。🔴 本次未在测试服做功能调用取证，这是有意为之而不是遗漏：这 7 个端点全是写口（`submit` / `confirmDay` / `updatePlacement` / `clearAssignments` / `clearAssignmentsByDay` / `transfer` / `release`），调用它们会真实改动配房行与库存记账，而测试服的房务数据被多个会话共用，`clear` 与 `release` 造成的后果撤不回来——副作用会落在一个不知情的人头上。互斥本身由落库级并发 IT `HouseRequirementWriteLockConcurrencyIT` 覆盖：绿轮 `house_hotel_assignment(active)=[]`、`house_dual_deduction_log(持有中)=[]`，submit 挂起 1109ms、锁键只有一把；变异轮（拆掉 7 处 `name`）留下 1 行孤儿 + 库存未释放，submit 只挂 213ms、两个键且其中一个带方法名。这比任何测试服抓包都更直接。⚠️ `100503` 在测试服上一次都没有触发过——不是「测过、不会触发」，是没测；临界区短不等于永不超时，更长事务/更大载荷/生产数据量下仍可能出现。mmg 前端实证 2026-09-20:七写口封装于 api/housekeeper/assignment.js(submit/update/placement/delete/clearAll/clearDay/confirmDay)与 api/housekeeper/grab-pool.js(transfer/release);调用方 OrderDetailModal.vue(catch{}+finally:1116 复位)与 housekeeper/orders/index.vue(:683-684 注释「业务错误已由 request.js 拦截器统一弹 message」、:829-830「808021 等由拦截器弹出;保持弹窗供重试」)均为拦截器透 message 模式。100503(HTTP 200+业务码)命中 request.js 拦截器统一 toast「资源被占用,请稍后重试」原样展示——可重试/不静默/不当系统异常三条全满足,不建前端业务码字典(同发票 AC-4 先例),故前端零改动,翻 not_required。"
+updated_at: "2026-09-20"
+base: "dev-v3"
+---
+
+# order-v3: 配房工作台七个写口补同一把 @Lock4j name，新增可重试冲突码 100503
+
+> **存放目录**:
+> - 一期(v2,无 `order-v3` 标签的工单)→ `changelogs/{YYYY-MM}/`
+> - 二期(v3,`order-v3` 标签的工单)→ `changelogs-v2/{YYYY-MM}/`
+>
+> **服务**: hl-order-service-v3
+> **PR**: #8069
+> **Issue**: #7980（AC-5）
+> **日期**: 2026-09-20
+> **影响范围**: 管理后台「房务配房工作台」§2.2 提交配房、单日确认、§2.3b 位置调整、§2.4b/§2.4c 清空配房、§1.3 转单、§1.4 释放共 7 个写操作，在**并发命中同一需求**时的失败分支
+
+---
+
+## ⚠️ 关键变化（非必须,本版与上版行为不同 / 纠错 / 撤销时必写）
+
+- 这 7 个写口分散在 `HouseAssignmentAdminController`（5 个）与 `HouseGrabAdminController`（2 个）两个类上，`@Lock4j` 的 `keys` 逐字相同（`'house:req:write:' + #requirementId`），代码注释里一直写着「统一需求级写锁 house:req:write:reqId」，但**补 `name` 之前这句话是假的**：lock4j 2.2.7 缺省 `name` 时用「类全限定名 + 方法名」当默认值拼进 Redis 键，7 个方法名不同 ⇒ 拿到的是 **7 把互不相干的锁**，可以互相踩踏（比如 `submit` 还没插完候选，`clearAssignments` 就把它软删了）。
+- 本次给 7 处补上同一个显式 `name = HouseRequirementLockConstants.REQUIREMENT_WRITE_LOCK_NAME`（值 `"house:req:write"`），互斥才真正生效。**没有新增接口、没有增删字段**，唯一契约变化是新增一个可能返回的失败码 **`100503`**，**HTTP 状态码仍是 200**。
+- 🔴 **本 PR 覆盖边界（避免误读成「房务写已全部串行」）**：同一张 `house_hotel_assignment` 表上仍有三类写口**不在这把锁内**，本次未处理：① `HouseAssignmentAdminController` 的 `update`（`PUT /v3/admin/order/assignments/{id}`）与 `delete`（`DELETE /v3/admin/order/assignments/{id}`）完全无锁；② `HouseGroupBatchAssignmentService`（团期整团重配）走另一个键空间；③ 订单域直写路径。这三类不在本文档「二、变更接口清单」内，行为未变。
+- 🔴 **本组已确认无 mp / C 端**：7 个 Service 方法各只有一个调用方（对应各自的 admin Controller 方法），路径全部落在 `/v3/admin/order/...`，新增的 `100503` 只会到达 hl-ui 房务工作台，不经过小程序。
+
+---
+
+## 一、背景（选填）
+
+`HouseHotelAssignmentDO` **确有** `@Version` 字段（`:116`），项目也**确实注册了** `OptimisticLockerInnerInterceptor`（`SlowSqlConfiguration:40`），但对这 7 个写口的并发场景乐观锁**不生效**，原因有三层：① `submit`/`clear*` 走的是 `insert`/`deleteById`，两者都绕过 `@Version`（乐观锁只拦 `updateById`）；② `confirmDay` 的最小补丁 SQL 不携带版本字段；③ `submit` 内部的 `updateById` 调用**从不检查返回值**，版本冲突会静默退化成空操作。三层叠加下唯一能兜住这组写口互斥的就是这把分布式锁，而它在补 `name` 之前并不生效。
+
+变异证明（管理者第一手复跑）：拆掉 7 处 `name` 后，集成测试 `submitParallelClearAssignments_leavesNoOrphanRowNorHeldInventory` 转红——`submit` 还没插完候选，`clearAssignments` 已把该需求下的旧配房行软删，两者没有被同一把锁挡住。落库读数对照：
+
+| 维度 | 变异轮（缺 name，坏形态） | 复绿轮（补齐 name） |
+|------|------|------|
+| `house_hotel_assignment(active)` 孤儿行 | 1 行孤儿 | `[]`（无孤儿） |
+| `house_dual_deduction_log(持有中)` | 库存未释放 | `[]`（已释放） |
+| `submit` 实际挂起耗时 | 213ms | 1109ms（真正排队等锁） |
+| 在途可见锁键数 | 2 把（其中一把带方法名） | 1 把 |
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 提交配房方案 | POST | `/v3/admin/order/hotel-requirements/{requirementId}/assignments` | 新增可能返回的错误码 | 抢锁超时返 100503（原接口/字段不变） |
+| 2 | 单日确认配房 | POST | `/v3/admin/order/hotel-requirements/{requirementId}/assignments/days/{dayNumber}/confirm` | 新增可能返回的错误码 | 与 §1 共用同一把需求级锁 |
+| 3 | 调整单条配房位置与资源 | PUT | `/v3/admin/order/hotel-requirements/{requirementId}/assignments/{id}/placement` | 新增可能返回的错误码 | 与 §1 共用同一把需求级锁 |
+| 4 | 清空当前需求全部配房 | DELETE | `/v3/admin/order/hotel-requirements/{requirementId}/assignments` | 新增可能返回的错误码 | 与 §1 共用同一把需求级锁 |
+| 5 | 清空当前需求某一天配房 | DELETE | `/v3/admin/order/hotel-requirements/{requirementId}/assignments/days/{dayNumber}` | 新增可能返回的错误码 | 与 §1 共用同一把需求级锁 |
+| 6 | 转单 / 超管强制指派 | POST | `/v3/admin/order/hotel-requirements/{requirementId}/transfer` | 新增可能返回的错误码 | 与 §1 共用同一把需求级锁 |
+| 7 | 释放回抢单池 | POST | `/v3/admin/order/hotel-requirements/{requirementId}/release` | 新增可能返回的错误码 | 与 §1 共用同一把需求级锁 |
+
+---
+
+## 三、接口详情
+
+### 1. 提交配房方案 `POST /v3/admin/order/hotel-requirements/{requirementId}/assignments`
+
+**VO**: `AssignmentSubmitReqVO → AssignmentSubmitRespVO`
+
+#### 使用场景
+
+房务在配房工作台对某个已抢到手的住宿需求批量提交候选方案（一次可提交多晚 × 多家庭，每项对应一晚一组房间）。本次改动不涉及本接口的入参/出参字段，只新增一条「被本组另外 6 个写口占用同一把需求级锁」的失败分支。
+
+#### 入参
+
+路径参数 `requirementId`（住宿需求 ID）+ Body：
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| requirementId | Path | Long | ✅ | - | 需求 ID（逻辑 FK → order_hotel_requirement.id） |
+| items | Body | List\<Item\> | ✅ | `@NotEmpty` | 配房项列表（批量），每项一晚一组房间 |
+| items[].dayNumber | Body | Integer | ✅ | ≥1 | 第几天（1=Day1） |
+| items[].hotelId | Body | Long | ✅ | - | 酒店 ID |
+| items[].roomTypeId | Body | Long | ✅ | - | 房型 ID，须归属该 hotelId（否则 808112） |
+| items[].roomCategory | Body | String | ✅ | `@NotBlank` | 房型字典 code |
+| items[].roomCount | Body | Integer | ✅ | ≥1 | 间数 |
+| items[].protoPrice | Body | BigDecimal | - | ≥0 | 协议价快照，不传按当日资源协议价兜底 |
+| items[].settlementPrice | Body | BigDecimal | - | ≥0 | 结算价快照，不传按当日资源结算价兜底，再兜底协议价 |
+| items[].settleType | Body | String | - | `cash\|sign\|company` | 支付方式快照，不传取酒店资源配置 |
+| items[].deductInventory | Body | Boolean | ✅ | - | 是否扣减资源酒店房型库存 |
+| items[].syncProtocolPrice | Body | Boolean | - | 默认 false | 是否把协议价同步写回 resource 价格日历 |
+| items[].syncSettlementPrice | Body | Boolean | - | 默认 false | 是否把结算价同步写回 resource 价格日历 |
+| items[].syncSettleType | Body | Boolean | - | 默认 false | 是否把支付方式同步写回酒店资源 |
+| items[].remark | Body | String | - | - | 备注 |
+| items[].replaceReason | Body | String | - | ≤256 字符 | 替换原因（仅该天旧行被本项替换时落库） |
+
+#### 出参 `Result<AssignmentSubmitRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| successCount | Integer | 成功条数 |
+| failCount | Integer | 失败条数 |
+| items | List\<Item\> | 每条配房结果 |
+| items[].dayNumber | Integer | 第几天 |
+| items[].assignmentId | String（雪花，序列化为字符串） | 配房 ID |
+| items[].arrange | String | 配房状态：pending / waiting / confirmed / problem |
+| items[].deductInventory | Boolean | 本次配房是否扣减了资源库存 |
+
+#### 请求示例
+
+```json
+{
+  "items": [
+    {
+      "dayNumber": 1,
+      "hotelId": 200001,
+      "roomTypeId": 300001,
+      "roomCategory": "STANDARD",
+      "roomCount": 2,
+      "protoPrice": 320.00,
+      "settlementPrice": 300.00,
+      "settleType": "cash",
+      "deductInventory": true,
+      "syncProtocolPrice": false,
+      "syncSettlementPrice": false,
+      "syncSettleType": false,
+      "remark": "已电话确认"
+    }
+  ]
+}
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "successCount": 1,
+    "failCount": 0,
+    "items": [
+      { "dayNumber": 1, "assignmentId": "70200", "arrange": "waiting", "deductInventory": true }
+    ]
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+本接口无「空数据」概念（成功恒返回统计 + 明细数组，items 不会为空数组，因为入参 items 本身要求非空）。无降级路径。
+
+#### 错误响应
+
+```json
+{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false }
+```
+
+| code | 触发条件 |
+|------|----------|
+| 400 | 参数校验失败（items 为空等） |
+| 401 | 未登录（网关拦截） |
+| 808090/808091 | 未登录或非房务角色 / 房务组长只读监督，无权提交配房 |
+| 808100 | 需求不存在 |
+| 808113 | 需求已作废（is_active=0），不可提交配房 |
+| 808110 | 需求不属于当前用户（被他人抢到） |
+| 808116 | 需求未被任何人抢单，须先抢单再配房 |
+| 808119 | 订单已取消或异常处置中，不可新增配房 |
+| 808102 | 任一 item 的 dayNumber 超出该需求应配晚数 |
+| 808111 | items 为空（禁止保存空方案清空已有配置） |
+| 808112 | 房型不属于所选酒店 |
+| 808117 | 同一次提交内同天同酒店同房型重复 |
+| 808124 | 是否扣减资源库存（deductInventory）必选 |
+| 589552/589553 | 团期子订单：团期尚未成团 / 班期尚未建团（未成团不得占用资源） |
+| 100502 | 3 秒幂等窗口内重复提交（键=requirementId） |
+| **100503（本次新增）** | 抢锁等待超过 3 秒（本组另外 6 个写口之一正持有 `house:req:write` 锁），**可重试** |
+
+#### 业务边界
+
+- 幂等：`@Idempotent` 3 秒窗口（键=requirementId），窗口内重复提交直接拒绝，不会走到锁竞争这一步。
+- 抢锁失败（100503）时该次请求**未进入方法体，零写入**——`@HouseWriteGuarded` 拦截器先于 `@Lock4j`/`@Idempotent` 执行角色门（先拦非房务角色），角色门通过后 `@Lock4j` 拿不到锁直接抛异常，业务代码一行不会执行，不产生任何 SQL。
+- `deductInventory=true` 的项在提交阶段即占用库存（防超卖），但计入「已配房」仍以 `CONFIRMED` 为准（`INQUIRING` 不计入 finalize 闸口判定）。
+- 房型归属越权校验在任何插入/扣减之前执行：`roomTypeId` 不属于所传 `hotelId` 时整个 submit 拒绝，不部分写入。
+- 老数据兼容：本次不涉及字段增删，存量配房记录无需迁移。
+
+---
+
+### 2. 单日确认配房 `POST /v3/admin/order/hotel-requirements/{requirementId}/assignments/days/{dayNumber}/confirm`
+
+**VO**: `AssignmentDayConfirmReqVO（请求体可选，可为 null） → Void`
+
+#### 使用场景
+
+房务对某一天点「确认」：从该天询房中（INQUIRING）候选行里挑选要保留的（可多家），被挑中的翻 `CONFIRMED` 并此刻扣减库存，落选的软删并按需还原库存。本次改动不涉及入参/出参字段，只新增一条抢锁超时的失败分支。
+
+#### 入参
+
+路径参数 + 可选 Body：
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| requirementId | Path | Long | ✅ | - | 需求 ID |
+| dayNumber | Path | Integer | ✅ | ≥1 | 第几天（从 1 开始） |
+| keepAssignmentIds | Body | List\<Long\>（JSON 传字符串数组） | - | 省略/空=该天全部候选都保留确认 | 该天要保留并确认的配房行 ID 列表（可多家） |
+
+#### 出参 `Result<Void>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data | null | 无返回数据，`Result.data` 恒为 `null` |
+
+#### 请求示例
+
+```json
+{ "keepAssignmentIds": ["1234567890"] }
+```
+
+（`keepAssignmentIds` 省略或不传 body 时按「该天全部候选都保留」处理。）
+
+#### 响应示例
+
+```json
+{ "code": 200, "message": "成功", "data": null, "success": true }
+```
+
+#### 空数据 / 降级响应
+
+本接口无「空数据」概念（成功恒返回 `data: null`），无降级路径。
+
+#### 错误响应
+
+```json
+{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false }
+```
+
+| code | 触发条件 |
+|------|----------|
+| 401 | 未登录（网关拦截） |
+| 808090/808091 | 未登录或非房务角色 / 房务组长只读监督，无权确认 |
+| 808100 | 需求不存在 |
+| 808113 | 需求已作废 |
+| 808110 | 需求不属于当前用户 |
+| 808116 | 需求未被任何人抢单 |
+| 808119 | 订单已取消或异常处置中 |
+| 808102 | dayNumber 超出该需求应配晚数 |
+| 808118 | 该天无询房中（INQUIRING）候选可确认 |
+| 808123 | `keepAssignmentIds` 中存在不属于该天候选集的 ID（可能配房已更新，需刷新后重试） |
+| 589552/589553 | 团期子订单未成团 / 班期未建团 |
+| 100502 | 3 秒幂等窗口内重复确认（键=requirementId+dayNumber） |
+| **100503（本次新增）** | 抢锁等待超过 3 秒（与本组另外 6 个写口共用同一把 `house:req:write` 锁），**可重试** |
+
+#### 业务边界
+
+- 幂等：`@Idempotent` 3 秒窗口（键=requirementId+dayNumber）。
+- 抢锁失败（100503）时零写入，逻辑同 §1；候选行状态不会被部分翻转。
+- 单日确认不再重复扣库存——扣减动作已在 submit 阶段发生，本接口只做状态翻转（保留→CONFIRMED）与落选软删/还原。
+- 老数据兼容：无字段变化。
+
+---
+
+### 3. 调整单条配房位置与资源 `PUT /v3/admin/order/hotel-requirements/{requirementId}/assignments/{id}/placement`
+
+**VO**: `AssignmentPlacementUpdateReqVO → Void`
+
+#### 使用场景
+
+房务对已存在的单条配房行原子调整目标晚次、酒店、房型和房间数（前端只传目标 dayNumber，入住日期由后端按当前订单行程推导）。涉及扣库存时先预占目标库存，本地事务提交后再释放原库存。本次改动不涉及入参/出参字段，只新增一条抢锁超时的失败分支。
+
+#### 入参
+
+路径参数 + Body：
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| requirementId | Path | Long | ✅ | - | 当前生效住宿需求 ID |
+| id | Path | Long | ✅ | - | house_hotel_assignment 主键 |
+| dayNumber | Body | Integer | ✅ | ≥1 | 目标晚次（1=第1晚） |
+| hotelId | Body | Long | ✅ | - | 目标酒店 ID |
+| roomTypeId | Body | Long | ✅ | - | 目标房型 ID，须归属该 hotelId |
+| roomCategory | Body | String | ✅ | `@NotBlank` | 目标房型字典 code |
+| roomCount | Body | Integer | ✅ | ≥1 | 目标房间数 |
+| protoPrice | Body | BigDecimal | - | ≥0 | 协议价快照，不传按目标房型和目标入住日读取资源价格日历 |
+| settlementPrice | Body | BigDecimal | - | ≥0 | 结算价快照，不传同上兜底 |
+| settleType | Body | String | - | `cash\|sign\|company` | 支付方式快照 |
+| deductInventory | Body | Boolean | ✅ | - | 是否扣减资源库存 |
+| syncProtocolPrice | Body | Boolean | - | 默认 false | 是否同步协议价到目标房型目标日期价格日历 |
+| syncSettlementPrice | Body | Boolean | - | 默认 false | 是否同步结算价 |
+| syncSettleType | Body | Boolean | - | 默认 false | 是否同步支付方式到目标酒店资源 |
+| remark | Body | String | - | - | 备注，不传保留原备注 |
+
+#### 出参 `Result<Void>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data | null | 无返回数据 |
+
+#### 请求示例
+
+```json
+{
+  "dayNumber": 2,
+  "hotelId": 200001,
+  "roomTypeId": 300001,
+  "roomCategory": "STANDARD",
+  "roomCount": 2,
+  "protoPrice": 320.00,
+  "settlementPrice": 280.00,
+  "settleType": "cash",
+  "deductInventory": true,
+  "syncProtocolPrice": false,
+  "syncSettlementPrice": false,
+  "syncSettleType": false,
+  "remark": "改期后重新询房"
+}
+```
+
+#### 响应示例
+
+```json
+{ "code": 200, "message": "成功", "data": null, "success": true }
+```
+
+#### 空数据 / 降级响应
+
+本接口无「空数据」概念，无降级路径。
+
+#### 错误响应
+
+```json
+{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false }
+```
+
+| code | 触发条件 |
+|------|----------|
+| 401 | 未登录（网关拦截） |
+| 808090/808091 | 角色门 |
+| 808124 | deductInventory 未传 |
+| 808120 | 配房行不存在，或 requirementId 与该行实际归属需求不一致 |
+| 808100/808113 | 需求不存在 / 已作废 |
+| 808110/808116 | 需求不属于当前用户 / 未被抢单 |
+| 808119 | 订单已取消或异常处置中 |
+| 808102 | 目标 dayNumber 超出应配晚数 |
+| 808112 | 目标房型不属于目标酒店 |
+| 808126 | 涉及库存迁移但原配房缺少可释放的持有日志（禁止继续迁移造成双扣） |
+| 589552/589553 | 团期子订单未成团 / 班期未建团 |
+| **100503（本次新增）** | 抢锁等待超过 3 秒（与本组另外 6 个写口共用同一把 `house:req:write` 锁），**可重试** |
+
+#### 业务边界
+
+- 本接口无 `@Idempotent`，仅靠 `@Lock4j` 串行化 + 库存迁移前置校验去重。
+- 事务外编排：目标库存先预占并标 PENDING，本地事务内原子更新配房与扣减日志；任一阶段失败精确释放新预占，原配房与原库存保持不变。抢锁失败（100503）属于最早期失败，同样零写入。
+- 改期前旧日期的只读配房行不可经本接口调整（会抛只读相关错误码，非本次新增范围）。
+- 老数据兼容：无字段变化。
+
+---
+
+### 4. 清空当前需求全部配房 `DELETE /v3/admin/order/hotel-requirements/{requirementId}/assignments`
+
+**VO**: `无 ReqVO（纯路径参数，无请求体） → AssignmentClearRespVO`
+
+#### 使用场景
+
+房务在已配房后先清空当前需求下全部 active 配房行（软删 + 按需释放库存），用于驳回需求或重新配房。不释放抢单人、不回抢单池。本次改动不涉及出参字段，只新增一条抢锁超时的失败分支。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| requirementId | Path | Long | ✅ | - | 需求 ID |
+
+#### 出参 `Result<AssignmentClearRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| clearedCount | Integer | 本次清空的 active 配房行数 |
+
+#### 请求示例
+
+```http
+DELETE /v3/admin/order/hotel-requirements/1234567890123456789/assignments
+Authorization: Bearer {token}
+```
+
+#### 响应示例
+
+```json
+{ "code": 200, "message": "成功", "data": { "clearedCount": 2 }, "success": true }
+```
+
+#### 空数据 / 降级响应
+
+该需求下没有任何 active 配房行时同样返回 200 成功，`clearedCount=0`，不报错。无降级路径。
+
+#### 错误响应
+
+```json
+{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false }
+```
+
+| code | 触发条件 |
+|------|----------|
+| 401 | 未登录（网关拦截） |
+| 808090/808091 | 角色门 |
+| 808100/808113 | 需求不存在 / 已作废 |
+| 808110/808116 | 需求不属于当前用户 / 未被抢单 |
+| 589552/589553 | 团期子订单未成团 / 班期未建团 |
+| **100503（本次新增）** | 抢锁等待超过 3 秒（与本组另外 6 个写口共用同一把 `house:req:write` 锁），**可重试** |
+
+#### 业务边界
+
+- 无 `@Idempotent`，仅靠 `@Lock4j` 串行化。
+- 抢锁失败（100503）时零写入，`clearedCount` 不会出现"清了一半"的中间态。
+- 只清空当前生效需求下 active 配房行，不影响历史已作废需求下的行。
+- 老数据兼容：无字段变化。
+
+---
+
+### 5. 清空当前需求某一天配房 `DELETE /v3/admin/order/hotel-requirements/{requirementId}/assignments/days/{dayNumber}`
+
+**VO**: `无 ReqVO（纯路径参数，无请求体） → AssignmentClearRespVO`
+
+#### 使用场景
+
+房务在每个行程日行内点「清空」，只清空该天配房，不影响其他天、不释放抢单人、不回抢单池。本次改动不涉及出参字段，只新增一条抢锁超时的失败分支。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| requirementId | Path | Long | ✅ | - | 需求 ID |
+| dayNumber | Path | Integer | ✅ | ≥1 | 第几天 |
+
+#### 出参 `Result<AssignmentClearRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| clearedCount | Integer | 本次清空的 active 配房行数 |
+
+#### 请求示例
+
+```http
+DELETE /v3/admin/order/hotel-requirements/1234567890123456789/assignments/days/2
+Authorization: Bearer {token}
+```
+
+#### 响应示例
+
+```json
+{ "code": 200, "message": "成功", "data": { "clearedCount": 1 }, "success": true }
+```
+
+#### 空数据 / 降级响应
+
+该天没有 active 配房行时同样返回 200 成功，`clearedCount=0`。无降级路径。
+
+#### 错误响应
+
+```json
+{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false }
+```
+
+| code | 触发条件 |
+|------|----------|
+| 401 | 未登录（网关拦截） |
+| 808090/808091 | 角色门 |
+| 808102 | dayNumber < 1 |
+| 808100/808113 | 需求不存在 / 已作废 |
+| 808110/808116 | 需求不属于当前用户 / 未被抢单 |
+| 589552/589553 | 团期子订单未成团 / 班期未建团 |
+| **100503（本次新增）** | 抢锁等待超过 3 秒（与本组另外 6 个写口共用同一把 `house:req:write` 锁），**可重试** |
+
+#### 业务边界
+
+- 无 `@Idempotent`，仅靠 `@Lock4j` 串行化。
+- 抢锁失败零写入，逻辑同 §4；仅影响本 dayNumber 行，不波及其他天。
+- 老数据兼容：无字段变化。
+
+---
+
+### 6. 转单 / 超管强制指派 `POST /v3/admin/order/hotel-requirements/{requirementId}/transfer`
+
+**VO**: `HouseTransferReqVO → Void`
+
+#### 使用场景
+
+普通房务把手上的需求转给另一位房务，或超管强制指派。后端按 JWT 身份分流：普通房务必须是当前 claimer，`reason` 可选；超管不要求是当前 claimer，`reason` 须 ≥10 字。**只能转「已经被某个房务抢到」的需求**（`status=PROCESSING`），未认领的需求恒返 808001；团期子订单永远到不了 `PROCESSING`（逐户抢单对团单无条件拒），归属改由整团认领端点建立，本接口对团单不适用。本次改动不涉及入参/出参字段，只新增一条抢锁超时的失败分支。
+
+#### 入参
+
+路径参数 + Body：
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| requirementId | Path | Long | ✅ | - | 需求 ID |
+| toUserId | Body | Long（JSON 传字符串） | ✅ | `@NotNull` | 接收人房务 ID |
+| reason | Body | String | - | ≤200 字符；超管指派须 ≥10 字（Service 层校验） | 转单/指派原因 |
+| skipUpperLimit | Body | Boolean | - | 默认 false，历史字段（单量上限已下线） | 仅审计留痕用，不影响结果 |
+
+#### 出参 `Result<Void>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data | null | 无返回数据 |
+
+#### 请求示例
+
+```json
+{ "toUserId": "1003", "reason": "我今天临时请假，转给小图接手" }
+```
+
+#### 响应示例
+
+```json
+{ "code": 200, "message": "成功", "data": null, "success": true }
+```
+
+#### 空数据 / 降级响应
+
+本接口无「空数据」概念，无降级路径。
+
+#### 错误响应
+
+```json
+{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false }
+```
+
+| code | 触发条件 |
+|------|----------|
+| 401 | 未登录（网关拦截） |
+| 808090/808091 | 角色门 |
+| 808001 | 需求未认领（status≠PROCESSING），普通转单/超管指派均不适用 |
+| 808002 | 需求已不存在（已取消/已配完） |
+| 808010 | 普通房务调用且非当前 claimer |
+| 808011 | 接收人不存在或已离职 |
+| 808012 | 转单/指派原因不能为空（普通转单在需要时） |
+| 808013 | 一单转单次数达上限（3 次，仅普通房务触发） |
+| 808014 | 接收人就是当前归属人 |
+| 808016 | 超管指派原因长度不足 10 字 |
+| **100503（本次新增）** | 抢锁等待超过 3 秒（与本组另外 6 个写口共用同一把 `house:req:write` 锁），**可重试** |
+
+#### 业务边界
+
+- 无 `@Idempotent`，仅靠 `@Lock4j` 串行化，与 submit/confirmDay/release 互斥（防转单改 claimer 与配房写口并发，授权过期仍写）。
+- 抢锁失败零写入，claimer 不会被部分改写。
+- 底层 CAS 前置是 `status='PROCESSING'`，该状态只由抢单端点写入；团期子订单永远到不了这个状态，需改用团级整团认领入口。
+- 老数据兼容：无字段变化。
+
+---
+
+### 7. 释放回抢单池 `POST /v3/admin/order/hotel-requirements/{requirementId}/release`
+
+**VO**: `HouseReleaseReqVO（请求体可选） → Void`
+
+#### 使用场景
+
+房务把手上的需求释放回抢单池（例如客人改行程暂时无法配房）。已有 `CONFIRMED` 配房时禁止释放（须先删除配房）。本次改动不涉及入参/出参字段，只新增一条抢锁超时的失败分支。
+
+#### 入参
+
+路径参数 + 可选 Body：
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| requirementId | Path | Long | ✅ | - | 需求 ID |
+| reason | Body | String | - | ≤200 字符 | 释放原因，前端「确认释放」弹窗可能整个不传 body |
+
+#### 出参 `Result<Void>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data | null | 无返回数据 |
+
+#### 请求示例
+
+```json
+{ "reason": "客人改行程,暂时无法配房" }
+```
+
+（`reason` 及整个请求体均可省略。）
+
+#### 响应示例
+
+```json
+{ "code": 200, "message": "成功", "data": null, "success": true }
+```
+
+#### 空数据 / 降级响应
+
+本接口无「空数据」概念，无降级路径。
+
+#### 错误响应
+
+```json
+{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false }
+```
+
+| code | 触发条件 |
+|------|----------|
+| 401 | 未登录（网关拦截） |
+| 808090/808091 | 角色门 |
+| 808020 | 需求不属于当前用户 |
+| 808021 | 已有 CONFIRMED 配房，无法释放（须先删除配房） |
+| **100503（本次新增）** | 抢锁等待超过 3 秒（与本组另外 6 个写口共用同一把 `house:req:write` 锁），**可重试** |
+
+#### 业务边界
+
+- 无 `@Idempotent`，仅靠 `@Lock4j` 串行化，与 confirmDay/submit/transfer 互斥（根治 release 的 countConfirmed 检查与 confirmDay 插 CONFIRMED 行的竞态）。
+- 抢锁失败零写入，claimer 字段不会被部分清空。
+- 释放后写 `op_type=RELEASE` 留痕（不受本次改动影响）。
+- 老数据兼容：无字段变化。
+
+---
+
+## 四、契约约束与正确调用方式（接口类必写）
+
+> 本节只写**后端接受/拒绝 payload 的规则**,不写 UI 渲染建议。
+
+### 并发冲突（100503）的正确处理方式
+
+7 个写口本次开始**真正共用同一把需求级锁**：同一 `requirementId` 上任一时刻只有一个能执行，其余排队等待，等待超过 3 秒（`acquireTimeout`，本组 `@Lock4j` 均未显式设置，取 lock4j-core 注解默认值 3000ms）直接返回失败，不会无限排队。
+
+| 场景 | 响应 |
+|------|------|
+| ✅ 单个请求，无并发 | 200 + 正常业务结果 |
+| ✅ 同需求两个请求先后到达，第二个在 3 秒内轮到锁 | 两个都 200（第二个排队等待，非立即失败） |
+| ❌ 同需求两个请求并发，第二个等待超过 3 秒未抢到锁 | `{ "code": 100503, "message": "资源被占用,请稍后重试", "success": false }`，**HTTP 状态码仍是 200** |
+| ✅ 不同 requirementId 并发 | 互不影响，各自独立加锁 |
+
+**前端必须做的事**：判断响应体 `code === 100503`（不是判 HTTP 状态码），命中时提示"另一个配房操作正在进行，请稍后重试"并允许用户重新提交；**不要**当作系统异常、**不要**静默吞掉不提示。
+
+### 角色门与锁/幂等的执行顺序
+
+`@HouseWriteGuarded` 拦截器（`HandlerInterceptor.preHandle`）执行在所有 Controller 方法级 AOP（`@Idempotent`/`@Lock4j`）**之前**——非房务角色（如组长）会先被 808090/808091 拒绝，不会消耗幂等令牌或进入锁排队；只有通过角色门的合法请求才会走到本次新增的 100503 分支。
+
+---
+
+## 五、数据库行为（涉及写操作时必写）
+
+本次不改变任何一次**成功**写操作实际写入的行数或内容——7 个端点各自原有的写入逻辑（insert 候选行 / 状态翻转 / 软删 / 库存记账）逐字节不变。变化的只是"谁能在同一时刻对同一需求执行写入"：
+
+| 维度 | 改动前 | 改动后 |
+|------|--------|--------|
+| 7 个写口是否互斥（同 requirementId） | 否（各自持独立锁，可并发） | 是（同一把锁，串行执行） |
+| 抢锁失败时是否有部分写入 | N/A（此前不会因锁而失败） | 否，零写入（`@Lock4j` 方法级环绕拦截，拿不到锁直接抛异常，业务方法体不会被调用，不产生任何 SQL） |
+| `submit ∥ clearAssignments` 并发结果（变异证明实测） | 可能留 1 行孤儿配房 + 库存持有日志不释放 | 干净排队，无孤儿行、无未释放库存 |
+
+---
+
+## 六、边界行为
+
+- 未登录 → 401（网关拦截）
+- 非房务角色 / 房务组长只读监督 → 808090/808091（`@HouseWriteGuarded` 拦截器先于锁/幂等执行）
+- 需求不存在/已作废/未认领/不属于当前用户 → 808100/808113/808116/808110（各端点适用情况见上）
+- 团期子订单未成团 → 589552/589553（未成团不得占用资源）
+- **抢锁超时（本次新增）→ 100503，HTTP 200，可重试，零写入**
+- 幂等窗口内重复提交（submit/confirmDay，请求相同）→ 100502，与本次改动无关，行为不变
+- 老数据兼容：本次不涉及字段增删，存量数据无需迁移
+
+---
+
+## 六.5、枚举 / 数据字典（接口出现枚举时必写）
+
+以下枚举在本组接口中均**未变化**，仅为方便前端自包含联调随本次改动一并列出。
+
+### settleType（支付方式，出现于 §1/§3）
+
+**所属字段**: `items[].settleType` / `settleType` | **类型**: `String`（正则约束 `cash|sign|company`）
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `cash` | 现付 | 结算方式，不传取酒店资源配置 |
+| `sign` | 签单 | 结算方式 |
+| `company` | 公司结 | 结算方式 |
+
+### arrange（配房状态，出现于 §1 出参 `items[].arrange`）
+
+**所属字段**: `AssignmentSubmitRespVO.Item.arrange` | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `pending` | 待处理 | 配房行初始态 |
+| `waiting` | 询房中 | 对应库内 `confirm_status=INQUIRING` |
+| `confirmed` | 已确认 | 对应库内 `confirm_status=CONFIRMED` |
+| `problem` | 异常 | 配房异常 |
+
+## 六.6、修改前后对比（修改/删除类接口必写，新增跳过）
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 |
+|------|------|------|
+| （无）| 7 个接口的请求字段、响应字段逐字节不变 | 同左 |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| 7 个写口同需求并发时 | 各自持独立锁，可同时执行（注释宣称"统一需求级写锁"，实际不成立） | 同一把锁，串行执行，互斥真正生效 |
+| `submit ∥ clearAssignments`（变异证明实测） | 可留 1 行孤儿配房 + 库存持有日志不释放 | 干净排队，无孤儿行 |
+| 抢锁失败的响应 | 不存在这条路径 | 路径真实存在（返回 100503，HTTP 200，业务失败，可重试）；本次改动未部署测试服，无实测触发频率数据 |
+| 接口文档"7 个写口全互斥"这句话 | 写在代码注释里但**不成立** | 写在代码注释里且**成立** |
+| 请求/响应字段、既有业务错误码 | 不变 | 不变 |
+
+## 六.7、影响评估（修改/删除类必写）
+
+- **是否破坏向后兼容**: 否——不改字段、不改既有错误码语义；但**新增了一条此前不存在的失败路径**（100503），前端若没有处理未知业务码的兜底逻辑，可能会把这次失败展示成不友好的提示（而不是"请重试"）。
+- **前端是否必须同步上线**: 建议同步（识别 `code=100503` 并提示可重试），但**触发频率本文档未做任何测试服实测**，无法给出"高频/低频"的判断依据，不可援引本工单另外两份（fleet 价格日历、发票签发）测试服实测的"频率极低"结论——那两份是各自独立测量的结果，机制相同不代表频率相同（本组是需求级锁，锁粒度 = 单个住宿需求，与价格日历/发票的锁粒度不同）。
+- **前端 workaround 清理点**: 无（本次是新增失败路径，不是清理旧 workaround）。
+
+## 七、不影响范围（显式声明, 帮前端/QA 缩小排查面）
+
+- **仅影响**: 房务配房工作台上述 7 个写操作，抢锁失败时的响应体
+- **零影响**:
+  - `update`（`PUT /v3/admin/order/assignments/{id}`）/ `delete`（`DELETE /v3/admin/order/assignments/{id}`）——本次未处理，仍无锁
+  - §2.1 候选源查询（`GET .../candidates`）、§2.5 房间分配查询/写入、§1.1/§1.2/§1.5 抢单池列表/抢单/我的接单
+  - §2.7 最终确认、回执上传/查询
+  - 团期整团重配（`HouseGroupBatchAssignmentService`，走另一个键空间）
+  - 7 个写口的请求字段、响应字段结构
+  - 既有业务错误码（808xxx / 589552 / 589553）的触发条件与文案
+  - 幂等拦截（100502）的行为
+  - 单个请求在**无并发**时的行为（延迟、返回值、写入内容全部不变）
+  - hl-gateway 路由配置——7 个端点路径/方法零变化
+
+---
+
+## 八、测试环境已验证
+
+**部署读数（2026-09-20 23:24）**：hl-order-service-v3 滚动更新两实例，部署前 `c35251b07` → 部署后 `ba8aab3ab`，8186 与 8086 各 12 秒内起监听，`deploy-backend.sh` 报 `rolling deploy complete`。`git merge-base --is-ancestor b9738a20f ba8aab3ab` 返回 **ANCESTOR_YES**。🔴 **并且部署前 `b9738a20f` 确实不在 `c35251b07` 内**（同一判据返回 NO），即本次部署是真正的「从不生效到生效」，不是重跑一遍确认。
+
+🔴 本次**未在测试服做功能调用取证，这是有意为之而不是遗漏**：这 7 个端点全是写口（`submit` / `confirmDay` / `updatePlacement` / `clearAssignments` / `clearAssignmentsByDay` / `transfer` / `release`），调用它们会**真实改动配房行与库存记账**，而测试服的房务数据被多个会话共用，`clear` 与 `release` 造成的后果**撤不回来**——副作用会落在一个不知情的人头上。
+
+互斥本身由**落库级并发 IT** `HouseRequirementWriteLockConcurrencyIT` 覆盖：绿轮 `house_hotel_assignment(active)=[]`、`house_dual_deduction_log(持有中)=[]`，submit 挂起 1109ms、锁键只有一把；**变异轮**（拆掉 7 处 `name`）留下 1 行孤儿 + 库存未释放，submit 只挂 213ms、**两个键且其中一个带方法名**。这比任何测试服抓包都更直接。
+
+⚠️ **`100503` 在测试服上一次都没有触发过**——不是「测过、不会触发」，是**没测**。
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#7980](https://git.1814.love:8443/wx/HL/issues/7980)（AC-5）
+- 关联 PR: [wx/HL#8069](https://git.1814.love:8443/wx/HL/pulls/8069)
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#7980](https://git.1814.love:8443/wx/HL/issues/7980)
+- **PR**: [#8069](https://git.1814.love:8443/wx/HL/pulls/8069)
+- **Merge commit**: [b9738a20f](https://git.1814.love:8443/wx/HL/commit/b9738a20f)（合并后回填，backend_status 待部署后翻转）
+
+### 联系人
+
+- **后端负责人**: @wx
@@ -0,0 +1,498 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7987"
+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 清空 frontend_owner/frontend_ref：按 BACKEND_CHANGELOG_DELIVERY_GUIDE，not_required 条目**任何人（含前端）不得回写** frontend_owner / frontend_ref / target_release / verified_at——这 4 个是「前端需要动作」的认领标记，填了会被发布门禁 E_FRONTEND 残留校验拦下（2026-08-19 #6077 就是这么被拦的）。前端表达「已知悉」用评论/口头即可，不动 frontmatter。本文件能推上去是因为门禁**只扫新增路径**，不是因为合规。mmg 的实证本身保留在下文。 gateway_status=verified 的依据：2026-09-20 18:22-18:46 经网关 https://api.test.1814.love:9443 实测（账号 cw_test_7444）。GET /v3/admin/order/group-batch/{id}/status-logs 在两个批次上分别取到 BATCH_VEHICLE_REQUIREMENT_REOPENED（开窗，extra 含 windowMinutes/blockedStage/expiresAt/scopeGroupCodes/scopeDates 五项齐全）与 BATCH_VEHICLE_DISPATCH_RECONFIGURED（重配），eventType/eventTypeName/changeType=DATA/extra 各字段逐一对照一致。⚠️ 本次实测发现并已订正一处契约偏差：重配事件的 operatorId 原写字符串 SYSTEM，实测为 null（与库里其它 SYSTEM 类事件惯例一致），判为文档写错而非实现错，已在字段表/字段值/JSON 示例/注意事项共 5 处改完。前端若按原文档判空会得到相反预期，故这条订正与发布同一批。 前端实证翻 not_required(mmg 2026-09-20):前端无自建 eventType 映射表,StatusLogsPanel 渲染 `eventTypeName || eventType || '事件'`(后端直供中文名+原码兜底),operatorType=SYSTEM 时 operatorId=null/operatorName「系统」是该面板注释钉住的既有口径,两类新事件与 operatorId 订正均自动正常显示,零改动。 【上一轮原注】backend_status=deployed 的判据（2026-09-20 18:35 复核）：hl-order-service-v3 测试服部署点 e179e09bd（2026-09-20 17:55:02 发布），`git merge-base --is-ancestor ab92377c7 e179e09bd` = true，故本篇端点的代码确已在测试服运行的字节里。⚠️ 这是一次**时点读数**：测试服由多会话共用，随时可能被滚到别的提交；origin/dev-v3 在本次复核时已前进到 f56692a51，落后的是部署点不是本篇。 gateway_status 保持 pending——本会话未对本篇端点做任何真实网关调用，正文示例值的来源已在各小节逐处标注（单元测试字面量 / @ApiModelProperty example 声明），不是抓包。待网关复验后再置 verified，**不得为了让门禁变绿改这个位**。"
+updated_at: "2026-09-20"
+base: "dev-v3"
+---
+
+# order-v3: 团期时间线新增开窗与重配两类事件
+
+> **存放目录**: 二期(v3) → `changelogs-v2/{YYYY-MM}/`
+>
+> **服务**: hl-order-v3 (端口 8021)
+> **PR**: #8039
+> **Issue**: #7987
+> **日期**: 2026-09-20
+> **影响范围**: 管理后台 - 团期详情页 - 状态流水/时间线
+
+---
+
+## ⚠️ 关键变化
+
+后端在团期时间线（`group_batch_status_log` 表）新增两种事件记录：
+- **BATCH_VEHICLE_REQUIREMENT_REOPENED**（开窗事件）—— 管理员显式开启受控重配窗口时写入
+- **BATCH_VEHICLE_DISPATCH_RECONFIGURED**（重配事件）—— fleet 回调确认重配生效时写入
+
+~~**前端必须新增这两个 event_type 值的渲染分支**，否则这两类事件在管理后台团期时间线上将无法正常显示其标签名（见下文「③ 前端渲染缺口」）。~~
+
+✅ **2026-09-20 mmg 实证推翻了上面这句，前端零改动**（原句划掉保留接 grep）：`StatusLogsPanel` 渲染的是 `eventTypeName || eventType || '事件'`，**后端直供中文名 + 原码兜底**，前端**没有**自建 eventType 映射表 ⇒ 两类新事件与 `operatorId` 那处订正都会自动正常显示。
+📌 下文「③ 前端渲染缺口」一节同样按这条实证作废——**它描述的缺口在当前前端实现里不存在**。⚠️ 但这个结论依赖「后端继续直供 `eventTypeName`」：哪天后端让该字段返回 null（正文「注意事项」里写的历史脏值场景就是一例），前端会退化成显示原始 code，那时这条渲染缺口会重新成立。
+
+---
+
+## 一、背景
+
+#7987 实施"受控重配窗口"机制：管理员可在团期进入待出发后仍显式开一个时间限制的窗口，允许车务在此期间重新排车。此前这两件事的事实只落在需求行的三个字段（`reconfigure_reason` / `reconfigure_opened_by` / `reconfigure_opened_at`），但运营打开团期详情页时看不到这些列，无法追溯窗口何时开过。
+
+本次变更补上团期时间线的留痕，让管理员在团期详情页就能看到「谁在何时以什么原因开了重配窗口」与「窗口内换车是否生效」。
+
+---
+
+## 二、变更接口清单
+
+既存接口（#7304 落地）返回值扩展：
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 团期状态流水查询 | GET | `/v3/admin/order/group-batch/{id}/status-logs` | 响应新增 event_type 值 | 新增两种事件类型 |
+
+---
+
+## 三、接口详情
+
+### 1. 团期状态流水查询 `GET /v3/admin/order/group-batch/{id}/status-logs`
+
+**VO**: `GroupBatchStatusLogItemVO` （既存响应 VO，新增 eventTypeName 映射值）
+
+#### 使用场景
+
+管理后台团期详情页的状态流水/时间线面板，用于向运营展示该团期的历史状态变化与重要操作记录。本次变更使该时间线新增两类事件的可见性。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| id | Path | Long | ✅ | - | 团期主订单 ID |
+
+#### 出参 `Result<List<GroupBatchStatusLogItemVO>>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| logId | String | 流水记录 ID |
+| groupBatchId | Long | 团期主订单 ID |
+| changeType | String | 变更类型：STATUS（状态流转） / DATA（数据变更） |
+| eventType | String | 事件类型代码（如 BATCH_VEHICLE_REQUIREMENT_REOPENED） |
+| eventTypeName | String | 事件类型中文名（**新增两种**：团车受控重开·已开配车窗口 / 团车受控重配·车辆安排已变更） |
+| fromStatus | String | 状态前值代码（如 PENDING_DEPARTURE） |
+| fromStatusName | String | 状态前值中文名 |
+| toStatus | String | 状态后值代码 |
+| toStatusName | String | 状态后值中文名 |
+| content | String | 事件文本内容（前端直接渲染） |
+| reason | String | 事件原因/备注（可为 null） |
+| operatorType | String | 操作人类型：ADMIN / SYSTEM / MQ |
+| operatorId | String | 操作人 ID。⚠️ **2026-09-20 网关实测订正**：**`operatorType=SYSTEM` 时本字段是 `null`，不是字符串 `"SYSTEM"`**（与库里其它 SYSTEM 类事件如 `BATCH_VEHICLE_REQUIREMENT_DONE` 的惯例一致）。前端判空请按 `null` 处理 |
+| operatorName | String | 操作人名称 |
+| extra | Map<String, Object> | 结构化附加数据，字段随事件类型变化（见下文"新增事件详解"） |
+| changedAt | String | 事件发生时刻（ISO 8601） |
+
+#### 新增事件类型详解
+
+**BATCH_VEHICLE_REQUIREMENT_REOPENED 事件**
+- `eventType`: `"BATCH_VEHICLE_REQUIREMENT_REOPENED"`
+- `eventTypeName`: `"团车受控重开·已开配车窗口"`
+- `changeType`: `"DATA"` （状态内数据变更，fromStatus = toStatus）
+- `operatorType`: `"ADMIN"`
+- `operatorId`: 开窗管理员 ID
+- `operatorName`: 开窗管理员真名
+- `content`: "开启受控重配窗口：允许车务在 X 分钟内重新安排本团车辆（授权 N 个乘车分组 / M 个行程日，2026-09-20 10:30:00 前有效）。此前团期已进入「待出发」，正常不可再配车。"
+- `reason`: 管理员必填的开窗原因（如"团期特殊变更"）
+- `extra`: 结构化数据
+  ```json
+  {
+    "requirementId": "需求行主键（字符串）",
+    "requirementVersion": 需求行版本号（整数）,
+    "blockedStage": "PENDING_DEPARTURE",
+    "windowMinutes": 120,
+    "expiresAt": "2026-09-20T12:30:00",
+    "scopeGroupCodes": ["乘车分组编号数组"],
+    "scopeDates": ["2026-09-21", "2026-09-22"]
+  }
+  ```
+
+**BATCH_VEHICLE_DISPATCH_RECONFIGURED 事件**
+- `eventType`: `"BATCH_VEHICLE_DISPATCH_RECONFIGURED"`
+- `eventTypeName`: `"团车受控重配·车辆安排已变更"`
+- `changeType`: `"DATA"` （状态内数据变更，fromStatus = toStatus）
+- `operatorType`: `"SYSTEM"`
+- `operatorId`: **`null`**（⚠️ **2026-09-20 网关实测订正**：原写 `"SYSTEM"`，实测为 `null`）
+- `operatorName`: `"系统"`
+- `content`: "本团车辆安排已被重新排定：车务在受控重配窗口内完成换车，新的配车计划（版本 20260920_v1）已生效，原计划作废。开窗授权人：张三；具体经办人见车务配车记录。"
+- `reason`: 开窗时管理员填写的原因（沿用窗口的 reason，非重配操作人的备注）
+- `extra`: 结构化数据
+  ```json
+  {
+    "requirementId": "需求行主键（字符串）",
+    "requirementVersion": 需求行版本号（整数）,
+    "planVersion": "fleet 配车计划版本号（字符串）",
+    "reconfigureOpenedBy": "开窗管理员 ID（与前一条事件的 operatorId 对应）",
+    "reconfigureOpenedAt": "2026-09-20T10:15:30"
+  }
+  ```
+
+#### 请求示例
+
+```json
+GET /v3/admin/order/group-batch/8000001/status-logs
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": [
+    {
+      "logId": "12345",
+      "groupBatchId": "8000001",
+      "changeType": "DATA",
+      "eventType": "BATCH_VEHICLE_REQUIREMENT_REOPENED",
+      "eventTypeName": "团车受控重开·已开配车窗口",
+      "fromStatus": "PENDING_DEPARTURE",
+      "fromStatusName": "待出发",
+      "toStatus": "PENDING_DEPARTURE",
+      "toStatusName": "待出发",
+      "content": "开启受控重配窗口：允许车务在 120 分钟内重新安排本团车辆（授权 2 个乘车分组 / 3 个行程日，2026-09-20T12:30:00 前有效）。此前团期已进入「待出发」，正常不可再配车。",
+      "reason": "临时增加3人，需调整座位分组与用车方案",
+      "operatorType": "ADMIN",
+      "operatorId": "1001",
+      "operatorName": "李四",
+      "extra": {
+        "requirementId": "7000001",
+        "requirementVersion": 2,
+        "blockedStage": "PENDING_DEPARTURE",
+        "windowMinutes": 120,
+        "expiresAt": "2026-09-20T12:30:00",
+        "scopeGroupCodes": ["GRP001", "GRP002"],
+        "scopeDates": ["2026-09-21", "2026-09-22", "2026-09-23"]
+      },
+      "changedAt": "2026-09-20T10:30:00"
+    },
+    {
+      "logId": "12346",
+      "groupBatchId": "8000001",
+      "changeType": "DATA",
+      "eventType": "BATCH_VEHICLE_DISPATCH_RECONFIGURED",
+      "eventTypeName": "团车受控重配·车辆安排已变更",
+      "fromStatus": "PENDING_DEPARTURE",
+      "fromStatusName": "待出发",
+      "toStatus": "PENDING_DEPARTURE",
+      "toStatusName": "待出发",
+      "content": "本团车辆安排已被重新排定：车务在受控重配窗口内完成换车，新的配车计划（版本 20260920_v1）已生效，原计划作废。开窗授权人：李四；具体经办人见车务配车记录。",
+      "reason": "临时增加3人，需调整座位分组与用车方案",
+      "operatorType": "SYSTEM",
+      "operatorId": null,
+      "operatorName": "系统",
+      "extra": {
+        "requirementId": "7000001",
+        "requirementVersion": 2,
+        "planVersion": "20260920_v1",
+        "reconfigureOpenedBy": "1001",
+        "reconfigureOpenedAt": "2026-09-20T10:30:00"
+      },
+      "changedAt": "2026-09-20T11:45:00"
+    }
+  ],
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+```json
+{
+  "code": 200,
+  "data": [],
+  "success": true
+}
+```
+
+#### 错误响应
+
+```json
+{
+  "code": 589500,
+  "message": "团期不存在",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- 接口返回的时间线按 `changedAt` 升序排列（从最早到最新）
+- 两个新事件都属于 `DATA` 类（状态内数据变更），不涉及团期主状态 `batch_status` 变化
+- 库里若有历史脏值或未知 event_type，后端 eventTypeLabel 返回 null，前端需兜底显示原始 code 值
+
+---
+
+## 四、契约约束与正确调用方式
+
+> 本节说明后端接受请求、返回响应的规则。
+
+### ✅ 正确 / ❌ 错误请求对照
+
+| 场景 | 请求示例 | 结果 |
+|------|---------|------|
+| ✅ 查询既存团期的时间线 | `GET /v3/admin/order/group-batch/8000001/status-logs` | 200 + 时间线列表 |
+| ✅ 无流水时返回空列表 | `GET /v3/admin/order/group-batch/9999999/status-logs`（不存在团期） | 200 + `data: []` |
+| ❌ 团期 ID 非数字 | `GET /v3/admin/order/group-batch/abc/status-logs` | 400 |
+
+### 字段约束与兼容性规则
+
+- **eventType 兼容性**：库里可能存在本版本未定义的历史 event_type 值 → 后端 eventTypeLabel 返回 null → 前端应兜底显示原始 code 值，而不是报错
+- **extra 字段**：根据 eventType 不同而变化（见下文详解）；前端需根据 eventType 判断应读取哪些 extra 字段，勿假设所有事件的 extra 结构相同
+- **operatorType 非 ADMIN 时**：⚠️ **2026-09-20 网关实测订正**：**`operatorId` 是 `null`、`operatorName` 是 `"系统"`——两个字段形态不同，不要当成同一回事**（原文把它们合并描述成「可能不是真实人名」，会让前端以为 `operatorId` 也有值） → 前端应按类型判断如何渲染，勿硬编码为"管理员"
+- **reason 字段**：可为 null（仅新增事件强制填写，既有历史事件可能无此字段） → 前端应做 null check
+
+---
+
+## 六.5、枚举：新增事件类型
+
+### eventType（GroupBatchLogEventType）
+
+**所属字段**: `GroupBatchStatusLogItemVO.eventType` | **类型**: `String` | **枚举类**: `com.hulalv.order.groupbatch.enums.GroupBatchLogEventType`
+
+新增两个枚举值（共有 N+2 个值）：
+
+| 值 | 中文名 | 说明 | changeType | 何时写入 |
+|----|------|------|-----------|---------|
+| `BATCH_VEHICLE_REQUIREMENT_REOPENED` | 团车受控重开·已开配车窗口 | 管理员显式开启受控重配窗口，允许车务在时间限制内重新排车 | DATA | 调用 POST `/v3/admin/order/group-batch/{id}/vehicle-requirement/reopen` 时 |
+| `BATCH_VEHICLE_DISPATCH_RECONFIGURED` | 团车受控重配·车辆安排已变更 | fleet 就绪回调确认重配生效，新车辆计划已应用，原计划作废 | DATA | fleet Outbox 回调解除受控重开阻断时 |
+
+### operatorType（操作人类型）
+
+**所属字段**: `GroupBatchStatusLogItemVO.operatorType` | **类型**: `String`
+
+既有三种值，新增事件涉及的分别是：
+
+| 值 | 中文名 | 说明 | 示例事件 |
+|----|------|------|---------|
+| `ADMIN` | 管理员 | 真实的管理后台登录用户 | BATCH_VEHICLE_REQUIREMENT_REOPENED |
+| `SYSTEM` | 系统 | 无 HTTP 请求上下文的自动操作（MQ / 定时任务 / 回调） | BATCH_VEHICLE_DISPATCH_RECONFIGURED |
+| `MQ` | MQ 事件 | MQ 消费触发（如支付/退款回调） | 既有其他事件 |
+
+---
+
+## 四、前端需求与缺口说明
+
+### ① eventTypeLabel 映射（前端渲染分支）
+
+**后端实现**（`GroupBatchStatusLogService.java:237-248`）：
+```java
+private String eventTypeLabel(String value) {
+    if (value == null) {
+        return null;
+    }
+    for (GroupBatchLogEventType type : GroupBatchLogEventType.values()) {
+        if (type.getValue().equals(value)) {
+            return type.getLabel();
+        }
+    }
+    return null;  // 未知值返回 null
+}
+```
+
+**当前状况**：
+- 后端遍历枚举查找 event_type，找到则返回 label，否则返回 null
+- 前端收到的 eventTypeName 字段值为 null 时，该行事件在时间线上**显示为空白**（既不报错、也不显示原始值，这是现状）
+
+**前端必须新增的映射**：
+```typescript
+// 示例伪码
+const eventTypeLabels = {
+  "BATCH_VEHICLE_REQUIREMENT_REOPENED": "团车受控重开·已开配车窗口",
+  "BATCH_VEHICLE_DISPATCH_RECONFIGURED": "团车受控重配·车辆安排已变更",
+  // ... 既有其他 event_type ...
+};
+```
+
+**不加分支的后果**：这两类事件在管理后台团期时间线上无法显示其事件名称，运营只看得到时刻/操作人/备注，但看不出"这是什么事件"，影响运营追溯。
+
+### ② 重配事件的操作人恒为 SYSTEM（不能拿 extra 字段顶替）
+
+**源码事实**（`GroupBatchService.java:1089-1118`，recordReconfigureTrail 方法）：
+```java
+// 就绪回调中，无 HTTP 请求上下文，operatorResolver.resolve() 返回 SYSTEM
+Operator operator = operatorResolver.resolve();  // → Operator.system()
+groupBatchStatusLogService.recordDataChange(groupBatchId,
+        GroupBatchLogEventType.BATCH_VEHICLE_DISPATCH_RECONFIGURED,
+        batch == null ? null : GroupBatchStatus.fromCode(batch.getBatchStatus()),
+        content, window.reason(), extra);
+```
+
+**重配事件的字段值**：
+- `operatorType`: `"SYSTEM"`
+- `operatorId`: **`null`**（⚠️ **2026-09-20 网关实测订正**：原写 `"SYSTEM"`，实测为 `null`）  
+- `operatorName`: `"系统"`
+- `extra.reconfigureOpenedBy`: 开窗管理员 ID（**不是**重配操作人）
+- `extra.reconfigureOpenedAt`: 开窗时刻（**不是**重配时刻，重配时刻在 changedAt）
+
+**这不是 bug，是设计**：
+- 重配的真实经办人（谁在车务后台点的"重配"按钮）只存在于 fleet 侧的 `fleet_group_dispatch.updated_by`
+- order-v3 是接收者，fleet 回调进来时没有经办人载荷
+- `extra.reconfigureOpenedBy` 答的是"**谁授权开的窗**"（过去的管理动作），与"**谁换的车**"（当前的车务动作）是两个不同的人、不同的时刻
+
+**前端若把 `extra.reconfigureOpenedBy` 显示成"经办人"，就是把一个错误的责任人写到审计页面上**。
+- ✅ 正确做法：operatorName 显示"系统"，content 或 extra.reconfigureOpenedBy 里可补充说明"开窗人是谁"
+- ❌ 错误做法：拿 extra.reconfigureOpenedBy 冒充 operatorId/operatorName 展示成经办人
+
+### ③ 开窗事件的操作人是真实人（与重配事件不同）
+
+**源码事实**（`GroupVehicleRequirementService.java:2305-2347`，recordReopenTrail 方法）：
+```java
+public GroupVehicleReopenRespVO doReopen(Long groupBatchId, 
+                                         GroupVehicleRequirementReopenReqVO req,
+                                         String operatorId) {
+    // ... 业务逻辑 ...
+    recordReopenTrail(groupBatchId, batch, active, req, windowMinutes, expiresAt);
+}
+
+private void recordReopenTrail(...) {
+    // recordDataChange 内部调 operatorResolver.resolve()，因为这是 HTTP 请求上下文
+    // 会从 AdminAuthInterceptor 注入的 AdminContext 里取当前登录管理员
+    groupBatchStatusLogService.recordDataChange(groupBatchId,
+            GroupBatchLogEventType.BATCH_VEHICLE_REQUIREMENT_REOPENED,
+            GroupBatchStatus.fromCode(batch.getBatchStatus()), content, req.getReason(), extra);
+}
+```
+
+**开窗事件的操作人**：
+- `operatorType`: `"ADMIN"`（不是 SYSTEM）
+- `operatorId`: 调用 reopen 端点的管理员 ID（真实人）
+- `operatorName`: 管理员真名
+
+**两个事件的操作人不同的原因**：
+- 开窗：用户通过管理后台 HTTP 端点主动触发 → 上下文有 AdminContext → operatorResolver 返回真实人
+- 重配：fleet 异步回调 → 无 HTTP 请求上下文 → operatorResolver 返回 SYSTEM
+
+**前端不能混淆**：别以为所有时间线事件的 operatorName 都是真实人，重配这条特殊。
+
+---
+
+## 五、数据库行为
+
+新增行落在 `group_batch_status_log` 表：
+
+| 事件 | 写入时机 | from_status | to_status | change_type | 示例 |
+|------|----------|------------|-----------|-------------|------|
+| BATCH_VEHICLE_REQUIREMENT_REOPENED | 调用 POST `/v3/admin/order/group-batch/{id}/vehicle-requirement/reopen` 时 | PENDING_DEPARTURE | PENDING_DEPARTURE | DATA | 管理员张三在 2026-09-20 10:30 开窗 |
+| BATCH_VEHICLE_DISPATCH_RECONFIGURED | fleet 就绪回调解除受控重开阻断时 | PENDING_DEPARTURE | PENDING_DEPARTURE | DATA | fleet 确认换车后在 2026-09-20 11:45 生效 |
+
+**关键**：两个事件都不改变团期 batch_status，`from_status` 与 `to_status` 相同。
+
+---
+
+## 六、边界行为
+
+- **库里存在历史脏值** → 后端 eventTypeLabel 返回 null → 前端时间线该行显示空白或兜底处理
+- **并发写入** → 开窗事务与重配事务独立，都跟随各自的外层事务（不丢失）
+- **幂等性** → 开窗已有生效窗口时幂等返回既有令牌（不重复写库）；普通首配回调、常规刷新回调若无受控重开阻断时 → CAS 0 行返回 → 不落本事件（常态）
+
+---
+
+## 六.6、修改前后对比
+
+### 接口行为对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| 时间线中开窗操作的可见性 | 三个字段存库但页面不展示 | 新增一条 DATA 类事件，时间线上可见 |
+| 时间线中重配操作的可见性 | 无记录 | 新增一条 DATA 类事件，标明"车已换、谁开的窗、老计划作废" |
+| 事件类型枚举 | 共 N 种 | 新增 2 种，共 N+2 种 |
+| 前端事件渲染 | 既有 N 种 event_type 的映射 | 需新增 BATCH_VEHICLE_REQUIREMENT_REOPENED / BATCH_VEHICLE_DISPATCH_RECONFIGURED 两条映射 |
+
+---
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 否。既存接口返回值扩展，老 event_type 不变
+- **前端是否必须同步上线**: **是**。不新增渲染映射会导致新增两类事件在时间线上显示为空白
+- **前端 workaround 清理点**: 
+  - 若前端已有"event_type 未知时显示原始 code"的兜底逻辑，可临时显示 `BATCH_VEHICLE_REQUIREMENT_REOPENED` 等原始值
+  - 但正式上线必须使用中文标签，不能长期显示原始值（运营不认识）
+
+---
+
+## 七、不影响范围
+
+- **仅影响**: 管理后台 - 团期详情页 - 状态流水/时间线面板（新增两类事件的渲染）
+- **零影响**:
+  - 团期主状态推进（batch_status 机制不变）
+  - 用车需求状态机（需求行读写逻辑不变）
+  - 订单详情、C 端行程页面（无此数据源）
+  - 旧团期数据（存量团期的时间线不会补充新事件）
+
+---
+
+## 八、测试环境已验证
+
+后端逻辑验证（提交 ab92377c7）：
+
+```
+POST /v3/admin/order/group-batch/8000001/vehicle-requirement/reopen
+  请求体: { "scopeGroupCodes": ["GRP001"], "scopeDates": ["2026-09-21"], "reason": "test reason" }
+  → 200, group_batch_status_log 新增 1 行 BATCH_VEHICLE_REQUIREMENT_REOPENED ✓
+
+fleet 就绪回调（模拟）
+  request: {"groupBatchId": 8000001, "requirementId": 7000001, "requirementVersion": 2, "planVersion": "v1"}
+  → 200, group_batch_status_log 新增 1 行 BATCH_VEHICLE_DISPATCH_RECONFIGURED ✓
+
+GET /v3/admin/order/group-batch/8000001/status-logs
+  → 200, 返回值中 eventTypeName 正确映射（后端已验证） ✓
+
+前端渲染验证：**待前端补充映射后联调**
+```
+
+---
+
+## 九、相关历史 PR
+
+| PR | Issue | 说明 | 是否仍有效 |
+|-------|-------|------|---------|
+| #7986 | #7986 | 受控重配窗口核心机制（团车需求侧） | ✅ 有效 |
+| #8039 | #7987 | 本 PR - 补团期时间线留痕 | ✅ 最新 |
+
+---
+
+## 十、相关文档
+
+- **后端枚举定义**: [`hl-order-service-v3/src/main/java/com/hulalv/order/groupbatch/enums/GroupBatchLogEventType.java`](https://git.1814.love:8443/wx/HL/blob/dev-v3/hl-order-service-v3/src/main/java/com/hulalv/order/groupbatch/enums/GroupBatchLogEventType.java)
+  - BATCH_VEHICLE_REQUIREMENT_REOPENED 定义：第 314-344 行
+  - BATCH_VEHICLE_DISPATCH_RECONFIGURED 定义：第 347-376 行
+
+- **时间线服务**: [`hl-order-service-v3/src/main/java/com/hulalv/order/groupbatch/service/GroupBatchStatusLogService.java`](https://git.1814.love:8443/wx/HL/blob/dev-v3/hl-order-service-v3/src/main/java/com/hulalv/order/groupbatch/service/GroupBatchStatusLogService.java)
+  - eventTypeLabel 实现：第 237-248 行
+
+- **开窗留痕**: [`hl-order-service-v3/src/main/java/com/hulalv/order/groupbatch/service/GroupVehicleRequirementService.java`](https://git.1814.love:8443/wx/HL/blob/dev-v3/hl-order-service-v3/src/main/java/com/hulalv/order/groupbatch/service/GroupVehicleRequirementService.java)
+  - recordReopenTrail 方法：第 2329-2387 行
+
+- **重配留痕**: [`hl-order-service-v3/src/main/java/com/hulalv/order/groupbatch/service/GroupBatchService.java`](https://git.1814.love:8443/wx/HL/blob/dev-v3/hl-order-service-v3/src/main/java/com/hulalv/order/groupbatch/service/GroupBatchService.java)
+  - recordReconfigureTrail 方法：第 1089-1118 行
+
+---
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#7987](https://git.1814.love:8443/wx/HL/issues/7987)
+- **PR**: [#8039](https://git.1814.love:8443/wx/HL/pulls/8039)
+- **Merge commit**: [ab92377c7](https://git.1814.love:8443/wx/HL/commit/ab92377c7)
+
+### 联系人
+
+- **后端负责人**: @wx
+- **前端对接人**: @mmg（hl-ui 仓库，需新增 eventTypeLabel 映射）
@@ -0,0 +1,380 @@
+---
+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: ""
+verified_at: "2026-09-21"
+status_note: "gateway_status=verified 的依据：2026-09-20 18:22-18:46 经网关实测（账号 cw_test_7444）GET /v3/admin/order/group-batch/2101524283048263681/vehicle-requirement，code=200，本篇登记的七个只读观测字段全部出现且字段名/类型与正文一字对应：planRefreshState=null / planRefreshReplayCount=0 / blockedStage=RESOURCE_PREPARING / planRefreshStalled=false / planRefreshStalledReason=null / planRefreshTimeoutAt=null / planRefreshReplayExhausted=false。逐字段对照无出入。⚠️ 正文示例值原来取自单元测试常量，现已有这组真实取值作为实测错开对照。 【上一轮原注】backend_status=deployed 的判据（2026-09-20 18:35 复核）：hl-order-service-v3 测试服部署点 e179e09bd（2026-09-20 17:55:02 发布），`git merge-base --is-ancestor 587af48cd e179e09bd` = true，故本篇端点的代码确已在测试服运行的字节里。⚠️ 这是一次**时点读数**：测试服由多会话共用，随时可能被滚到别的提交；origin/dev-v3 在本次复核时已前进到 f56692a51，落后的是部署点不是本篇。 gateway_status 保持 pending——本会话未对本篇端点做任何真实网关调用，正文示例值的来源已在各小节逐处标注（单元测试字面量 / @ApiModelProperty example 声明），不是抓包。待网关复验后再置 verified，**不得为了让门禁变绿改这个位**。 【本轮之前的原注，保留供追溯口径变化】代码已合入 dev-v3（PR #8033，squash 提交 587af48cd，经 git log origin/dev-v3 --oneline | grep 7988 核实存在于 origin/dev-v3）。backend_status 刻意保持 pending——hl-order-service-v3 尚未部署测试服到该提交，未做任何真实网关调用；gateway_status 同样保持 pending。正文请求/响应示例的具体数值来自随 PR 一起合入的单元测试常量（GroupVehicleRequirementPlanRefreshObservationTest：groupBatchId=7201、requirementId=92001、blockedStage=PENDING_DEPARTURE、windowMinutes=120 等）与源码 @ApiModelProperty(example=...) 声明，逐一对源码核实过字段名/类型，但不是测试服网关抓包，具体取值以复验后实测为准。待管理者安排部署 + 网关复验后再把 backend_status/gateway_status 置 deployed/verified 并推送本文件；发布前不许为了过校验改状态位。 前端实证维持 pending(mmg 2026-09-20):planRefresh*/blockedStage 全仓零命中,前端从未为读刷新状态调 confirm(无 workaround 可撤),纯新增只读字段不接入零影响;停滞告警渲染(planRefreshStalled 判据/ReplayExhausted 文案分叉)属团期配车编辑页 #7442+#7444 挂起域,随配车排期一并接入。前端 2026-09-21 已交付:GroupVehicleRequirementSection 渲染观测块——行动判据只看 planRefreshStalled(stalled 未耗尽 warning 引导去上方「整团确认需求」重投、replayExhausted error「请联系后台排查」、stalled=false 且 PENDING info「刷新中,预计 planRefreshTimeoutAt 前出结果」+6s×5 短轮询、null/DONE 不显提示条);PUT/withdraw/waive 后本组件本就重新 GET,同源覆盖;从未为读 FAILED 调 confirm,无 workaround 可撤。定向 spec 覆盖三分支+轮询。"
+updated_at: "2026-09-20"
+base: "dev-v3"
+---
+
+# order-v3: 团期配车刷新状态补只读观测口（工单 #7988）
+
+> **存放目录**: 二期（order-v3 标签工单）→ `changelogs-v2/2026-09/`
+>
+> **服务**: hl-order-service-v3
+> **PR**: #8033 ｜ **Issue**: #7988 ｜ **合并提交**: `587af48cd`
+> **日期**: 2026-09-20
+> **影响范围**: 管理后台「团期配车」编辑页，读团期正式用车需求响应体新增七个只读字段（配车刷新状态观测块）
+
+---
+
+## ⚠️ 关键变化
+
+改动前，"配车刷新到底死没死"这件事**只能通过写口的响应看到**——`requirement/confirm` 与 `vehicle-requirement/reopen` 两个写口的响应体里带着 `planRefreshState` 等状态列，而**只读**的 `GET .../vehicle-requirement` 没有。于是运营/车务要看一眼"刷新是不是卡住了"，唯一手段就是去调 `confirm`；而 `confirm` 一旦走到受控重投分支，会**顺手把状态从 `FAILED` 改回 `PENDING`**——查看这个动作本身把现场改掉了，`FAILED` 因此在管理后台侧根本读不到。
+
+本次在只读的 `GET .../vehicle-requirement` 响应体上补了七个只读字段，**全程不产生任何写**（已有单测 `get_stalledRequirement_performsNoWrite` 与反射断言 `get_declaredShape_carriesNoLockOrTransaction` 钉住这一点）。
+
+🔴 **前端渲染口径必须看 `planRefreshStalled`，不能看 `planRefreshState`**：`planRefreshState=PENDING` 对应**三种互不相同的现实**（正常在途 / 命令已终态失败但状态列没回写 / 已超过时限卡死），三者在 `planRefreshState` 这一个字段上**逐字相同**，无法用它自己区分。详见「四、契约约束与正确调用方式」。
+
+---
+
+## 一、背景
+
+团期正式用车需求上挂着一条"照这份需求刷新 fleet 配车计划"的异步链路（#7442 PR-C2 引入），状态机三态 `NONE`（列值 NULL）/`PENDING`/`DONE`/`FAILED`，配套 `blocked_stage`（阻断阶段快照）、`plan_refresh_replay_count`（人工受控重投次数，上限 5）等库列。这些库列此前只在两个**写口**的响应里露出：
+
+- `POST .../requirement/confirm`（确认整份需求，会顺手触发一次受控重投）
+- `POST .../vehicle-requirement/reopen`（重新开窗）
+
+运营想知道"这个团的配车刷新到底怎么样了"，只能调 `confirm`——而 `confirm` 会把 `FAILED` 重新入队成 `PENDING`。这意味着：**只要有人查看过一次，`FAILED` 这个最需要被看到的终态就从管理后台侧消失了**。本单在唯一的无副作用观测口——读团期正式用车需求——上补齐这七个字段，让"查一下"这个动作不再改变现场。
+
+| 维度 | 改前 | 改后 |
+|------|------|------|
+| 看配车刷新状态的入口 | 只能调写口 `confirm`/`reopen` | 新增只读入口 `GET .../vehicle-requirement`（以及共用同一响应体的 `PUT`/`withdraw`/`waive`） |
+| 查看动作是否会改变现场 | 会（`confirm` 顺手重投，`FAILED → PENDING`） | 不会（读口全程零写，含反射断言钉住方法上无 `@Lock4j`/`@Transactional`/`@Idempotent`） |
+| `PENDING` 的三种现实是否可区分 | 无对应字段，读原值也分不开 | `planRefreshStalled`/`planRefreshStalledReason` 把三种现实拆开 |
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 读团期正式用车需求 | GET | `/v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement` | 修改接口 | 响应体新增 7 个只读字段（配车刷新观测块） |
+
+⚠️ **该响应体 `GroupVehicleRequirementRespVO` 同时被 `PUT`/`withdraw`/`waive` 三个写口共用**（源码 javadoc 明确标注"四个端点共用这一个响应体"），所以这 7 个字段同样会出现在：
+
+- `PUT /v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement`（保存草稿）
+- `POST /v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement/withdraw`（整份撤回）
+- `POST /v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement/waive`（声明整团免车）
+
+这三个写口的字段值语义与 `GET` 完全相同（都是"该次写入后的现场"只读投影），本次未改动这三个端点自身的请求契约或业务逻辑，故不在上表单独列出，只在这里明确提示；三节共用「接口 1」的「六.5 枚举」「六.6 对比」解释。
+
+`POST .../requirement/confirm` 与 `POST .../vehicle-requirement/reopen` 两个写口**一字未改**——它们的响应体分别是 `GroupBatchRequirementConfirmRespVO` 与 `GroupVehicleReopenRespVO`，是两个独立的 VO，本次未触碰。
+
+---
+
+## 三、接口详情
+
+### 1. 读团期正式用车需求 `GET /v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement`
+
+**VO**: `(PathVariable groupBatchId, 无请求体) → GroupVehicleRequirementRespVO`
+
+（源码核对：`GroupBatchRequirementController.java:180-192`、`GroupVehicleRequirementRespVO.java`、`GroupVehicleRequirementService.java:2480-2545` `fillPlanRefreshObservation`/`resolvePlanRefreshStalledReason`、`GroupVehiclePlanRefreshStalledReason.java`）
+
+#### 使用场景
+
+团期配车管理员编辑页打开时调用，回填该团当前正式用车需求（分组/逐日行/整份状态）。本次改动后，它**同时是"配车刷新死没死"在 admin 侧唯一的无副作用观测口**：页面可以在不触发任何写操作的前提下，展示"这个团的配车刷新是否需要人工介入、卡在哪一步、还能不能自己点确认重试"。该团期尚未形成正式需求时，`data` 整体为 `null`（这不是新行为，改动前就是如此），此时七个新字段自然也不存在。
+
+#### 入参字段表
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long | ✅ | - | 团期聚合主键 |
+
+（本端点无请求体、无 Query 参数；本次改动未新增任何入参）
+
+#### 出参字段表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| requirementId | String | 正式需求主键（雪花） |
+| groupBatchId | String | 团期聚合主键 |
+| 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`=命令已发出等 fleet 回来/`DONE`=本轮刷新已闭环/`FAILED`=刷新已被判死。⚠️ 单看本字段判不了"要不要处置"，看 `planRefreshStalled` |
+| **planRefreshReplayCount** | Integer | **【本次新增】** 人工受控重投累计次数（管理员点确认触发的，不含自动重试）；上限 5；从未重投过为 `0` 或 `null` |
+| **blockedStage** | String | **【本次新增】** 团期阻断阶段快照：`null`=未阻断；非空（`RESOURCE_PREPARING`/`MATERIAL_PREPARING`/`PENDING_DEPARTURE`）表示该团正卡在这一步等重新配车。展示口径，不是门禁输入——真正挡住团期推进的是 `order_group_batch.vehicle_ready=false` |
+| **planRefreshStalled** | Boolean | **【本次新增，本块的行动判据，恒非 null】** `true`=刷新不会自愈、必须有人处置（该团出不了团）；`false`=无需动作（含从未登记刷新/正常在途/已闭环）。**判"要不要现在找人"看本字段，不要看 `planRefreshState`** |
+| **planRefreshStalledReason** | String | **【本次新增】** 停滞归因：`STATE_FAILED`=刷新已被判死（自动重试耗尽或被 fleet 判定性终结）/`COMMAND_FAILED`=命令行已失败但状态列没回写（同样是死了）/`TIMEOUT`=超过本轮窗口时限仍无结果。`planRefreshStalled=false` 时恒为 `null` |
+| **planRefreshTimeoutAt** | LocalDateTime | **【本次新增】** 本轮刷新的"再等就没意义"时刻 = 发起时刻 + 本轮窗口时长（管理员重开时自定，缺省 120 分钟）。仅 `planRefreshState=PENDING` 且已登记发起时刻时有值，其余为 `null` |
+| **planRefreshReplayExhausted** | Boolean | **【本次新增，恒非 null】** 人工重投额度是否已耗尽：`true`=已达 5 次上限，再点确认只会收到 `809210`，提示应改为"联系后台排查"；`false`=停滞时仍可由管理员重新确认触发一次重投。只在 `planRefreshStalled=true` 时才有行动意义 |
+| groups[] | Array | 全部乘车分组（整团免车态为空数组）；本次未改动 |
+| groups[].groupId / groupCode / vehicleType / serviceStartDate / serviceEndDate / days[] | - | 分组回显字段，本次未改动 |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch/7201/vehicle-requirement
+```
+
+#### 响应示例
+
+数值取自单元测试常量（`GroupVehicleRequirementPlanRefreshObservationTest`，非网关抓包，见 frontmatter `status_note`），展示 `FAILED` 停滞态（`get_planRefreshFailed_projectsStateFailedStalled` 用例覆盖的场景）：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "requirementId": "92001",
+    "groupBatchId": "7201",
+    "status": "CONFIRMED",
+    "version": 3,
+    "remark": null,
+    "confirmedBy": "10086",
+    "confirmedAt": "2026-09-18 09:00:00",
+    "planRefreshState": "FAILED",
+    "planRefreshReplayCount": 1,
+    "blockedStage": "PENDING_DEPARTURE",
+    "planRefreshStalled": true,
+    "planRefreshStalledReason": "STATE_FAILED",
+    "planRefreshTimeoutAt": null,
+    "planRefreshReplayExhausted": false,
+    "groups": []
+  },
+  "success": true
+}
+```
+
+补充第二种取值组合——`PENDING` 且未超时（`get_pendingWithinWindow_projectsNotStalled` 用例），只摘录七个新字段：
+
+```json
+{
+  "planRefreshState": "PENDING",
+  "planRefreshReplayCount": 0,
+  "blockedStage": "PENDING_DEPARTURE",
+  "planRefreshStalled": false,
+  "planRefreshStalledReason": null,
+  "planRefreshTimeoutAt": "2026-09-20 13:20:00",
+  "planRefreshReplayExhausted": false
+}
+```
+
+⚠️ 与上一个响应对比：**`planRefreshState` 都可能是 `PENDING`（本例）或 `FAILED`（上例），但同为 `PENDING` 时 `planRefreshStalled` 还可能是 `true`**（命令已终态失败但状态列没回写、或已超时）——这正是本次改动要解决的"单看原值分不清三种现实"的问题，务必配合下面「四、契约约束」一起读。
+
+#### 空数据 / 降级响应
+
+该团期尚未形成正式需求时，`data` 整体为 `null`（改动前既有行为，本次未改动）。**从未登记过任何刷新的团期**（多数团期的正常态）响应形如：
+
+```json
+{
+  "code": 200,
+  "data": {
+    "requirementId": "92001",
+    "groupBatchId": "7201",
+    "planRefreshState": null,
+    "planRefreshReplayCount": null,
+    "blockedStage": null,
+    "planRefreshStalled": false,
+    "planRefreshStalledReason": null,
+    "planRefreshTimeoutAt": null,
+    "planRefreshReplayExhausted": false
+  },
+  "success": true
+}
+```
+
+⚠️ **`planRefreshState=null` 不是异常、不是数据缺失**，是状态机里的 `NONE`（列值 NULL），没走过受控重开的团期恒为此态，前端不应画成异常/报错样式。本端点无下游依赖，不存在降级路径（全程只读本地 DB，`planRefreshOutboxId` 非空时最多额外读一次 outbox 命令状态，见「业务边界」）。
+
+#### 错误响应
+
+```json
+{
+  "code": 589500,
+  "message": "团期不存在",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- **鉴权**：`permissionGuard.require(..., PERMISSION_DEMAND_CONFIRM)`，与 `PUT`/`withdraw`/`waive` 同一权限码，本次未改动。
+- **全程只读，零写**：本次改动新增的装配逻辑 `fillPlanRefreshObservation` 只做 `select`（团期存在性 + 需求主表 + 分组/逐日行 + 至多一次按 `planRefreshOutboxId` 读命令状态），不写任何表、不入队、不触发重投、不取锁、不开事务——已有单测 `get_stalledRequirement_performsNoWrite`（`verifyNoMoreInteractions` 钉死"该发生的读之外一次交互都不许有"）与反射断言 `get_declaredShape_carriesNoLockOrTransaction`（`get` 方法上没有 `@Lock4j`/`@Transactional`/`@Idempotent`）双重覆盖。
+- **命令状态查询是有条件的**：只有 `planRefreshOutboxId != null` 且当前不是已知终态（非 `NONE`/`DONE`）时才会去查一次 `order_fleet_command_outbox` 的命令状态；从未登记过刷新（`NONE`）或已闭环（`DONE`）时**不会**多发这次查询——`verifyNoInteractions(orderFleetCommandOutboxService)` 在两种场景下都被单测钉住，避免在存量团期上放大成全表的额外查询。
+- **`NONE`/`DONE` 一律不判停滞，哪怕 `planRefreshOutboxId` 指向一行已失败的旧命令**：`reopen` 把状态归零时并不清 `planRefreshOutboxId` 这一列，如果直接套用"命令终态失败即停滞"的判据，会把一个刚刚重开、还没登记新刷新的团期误报成"已死"，而那正是最不该报警的时刻。
+- **`planRefreshTimeoutAt` 与受控重开守卫（`809209`）共用同一份阈值计算**：两处各算一遍会出现"页面说已超时、重开却报 809209 不让开"的自相矛盾，本次改动把阈值计算抽成同一个私有方法复用。
+- **`reconfigureScope` 解析失败时兜底 120 分钟**，不会因为一条脏 JSON 让团期在页面上永远显示"还在跑"。
+
+---
+
+## 四、契约约束与正确调用方式
+
+> 本节只写响应字段的正确解读方式，不写 UI 渲染建议之外的后端行为规则（本端点无写操作，没有 payload 校验规则可写）。
+
+### 🔴 判"要不要现在找人"只看 `planRefreshStalled`，不要看 `planRefreshState`
+
+`planRefreshState=PENDING` 对应三种互不相同的现实，在这一个字段上**逐字相同**：
+
+| 现实 | `planRefreshState` | `planRefreshStalled` | `planRefreshStalledReason` |
+|---|---|---|---|
+| 正常在途，等 fleet 回调 | `PENDING` | `false` | `null` |
+| 命令已终态失败，但状态列没回写（回写钩子没落成） | `PENDING` | `true` | `COMMAND_FAILED` |
+| 超过本轮窗口时限仍无结果 | `PENDING` | `true` | `TIMEOUT` |
+| 已被判死（自动重试耗尽或被 fleet 终结，状态列已回写） | `FAILED` | `true` | `STATE_FAILED` |
+
+只读 `planRefreshState` 拿到的 `PENDING` 无法区分前三行——这正是本单要解决的问题。前端渲染逻辑必须以 `planRefreshStalled` 作为唯一的"要不要报警"判据。
+
+### 渲染口径
+
+- `planRefreshStalled=true` 必须是**显式告警态**（不是静默）：
+  - `planRefreshReplayExhausted=false` → 引导文案「重新确认」
+  - `planRefreshReplayExhausted=true` → 文案改为「联系后台排查」，**别让运营继续点确认**（再点只会收到 `809210`）
+- `planRefreshStalled=false` 且 `planRefreshState=PENDING` → 展示「刷新中，预计 `planRefreshTimeoutAt` 前出结果」
+- `planRefreshState=null` → 不展示刷新相关的任何提示条（这是多数团期的正常态，不是"缺数据"）
+- `planRefreshState=DONE` → 不展示告警，可选展示"已完成"的静态标记
+
+### 无新增错误码
+
+本端点是纯读口，本次改动不引入任何新错误码；`809210`/`809209` 是既有错误码（`#7442`/`#7442 PR-C2` 已定义），仅在前端引导用户点击**其他写口**（`confirm`/`reopen`）时才可能命中，本端点自身不会抛出它们。
+
+---
+
+## 六、边界行为
+
+- 未登录/网关未透传角色 → 401（网关拦截），既有行为
+- 团期不存在 → `589500`，既有行为
+- 该团期尚未形成正式需求 → `data=null`，既有行为，本次未改动
+- 老数据兼容：改动前落库的存量需求行 `plan_refresh_state`/`plan_refresh_replay_count`/`blocked_stage` 三列均可能是 `NULL`（未登记过刷新），响应对应投影为 `planRefreshState=null`/`planRefreshReplayCount=null`/`blockedStage=null`、`planRefreshStalled=false`、`planRefreshReplayExhausted=false`，**不是异常**
+- `reconfigure_scope` 解析失败（脏 JSON）时，超时窗口按默认 120 分钟兜底计算，不影响响应本身返回成功
+
+---
+
+## 六.5、枚举 / 数据字典
+
+### `planRefreshState`（`GroupVehicleRequirementRespVO.planRefreshState`，源码 `GroupVehiclePlanRefreshState` 状态机枚举，列值 NULL 对应 `NONE`）
+
+**所属字段**: `planRefreshState` | **类型**: `String`（可空）
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `null` | 未登记 | 状态机 `NONE`，尚未登记过任何刷新；多数团期的正常态 |
+| `PENDING` | 刷新中 | 刷新命令已登记，等 fleet 刷完并把就绪意图投回来；需结合 `planRefreshStalled` 判断是否正常 |
+| `DONE` | 已闭环 | 就绪回调已通过两级判定并应用，本轮刷新完成 |
+| `FAILED` | 已判死 | 刷新已耗尽重试预算或被 fleet 判定性终结；不放行团期，出团门②持续拒绝 |
+
+### `planRefreshStalledReason`（`GroupVehicleRequirementRespVO.planRefreshStalledReason`，源码 `GroupVehiclePlanRefreshStalledReason` 枚举，仅在读口投影中使用，不落库）
+
+**所属字段**: `planRefreshStalledReason` | **类型**: `String`（可空，`planRefreshStalled=false` 时恒为 `null`）
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `STATE_FAILED` | 状态已判死 | `planRefreshState=FAILED`；去查 fleet 为什么刷不动 |
+| `COMMAND_FAILED` | 命令已死未回写 | 状态列仍 `PENDING`，但命令行已终态失败；去查回写状态的终态钩子为什么没落成 |
+| `TIMEOUT` | 已超时 | 状态列仍 `PENDING`，命令未终态失败，但已超过本轮窗口时限；去查命令是否卡在队列里 |
+
+⚠️ 本枚举**只进响应，不进库、不进 `WHERE`**——它是三条既有判据（状态列/命令行状态/超时）在读的那一刻算出来的结论，不是持久化状态。
+
+### `blockedStage`（`GroupVehicleRequirementRespVO.blockedStage`，值域同团期状态机的阶段码）
+
+**所属字段**: `blockedStage` | **类型**: `String`（可空）
+
+| 值 | 说明 |
+|----|------|
+| `null` | 未阻断 |
+| `RESOURCE_PREPARING` | 团期阶段：资源准备中 |
+| `MATERIAL_PREPARING` | 团期阶段：物资准备中 |
+| `PENDING_DEPARTURE` | 团期阶段：待出团 |
+
+⚠️ 本字段是**展示口径**，不是门禁输入：真正挡住团期推进的是 `order_group_batch.vehicle_ready=false`，本字段只是"卡在哪一步"的留痕快照。
+
+---
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 |
+|------|------|------|
+| `GET .../vehicle-requirement` 响应 `planRefreshState` | 不存在（只在 `confirm`/`reopen` 两个写口的响应里有） | **新增**只读投影 |
+| 同响应 `planRefreshReplayCount` | 不存在 | **新增** |
+| 同响应 `blockedStage` | 不存在 | **新增** |
+| 同响应 `planRefreshStalled` | 不存在（任何端点都没有这个派生结论） | **新增**，全站唯一来源 |
+| 同响应 `planRefreshStalledReason` | 不存在 | **新增**，全站唯一来源 |
+| 同响应 `planRefreshTimeoutAt` | 不存在 | **新增**，全站唯一来源 |
+| 同响应 `planRefreshReplayExhausted` | 不存在 | **新增**，全站唯一来源 |
+| `PUT`/`withdraw`/`waive` 三个写口的响应（共用同一 VO） | 同样没有这七个字段 | 同样新增（值 = 该次写入后的现场） |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| 查看配车刷新是否卡住 | 只能调 `confirm`，而它会顺手做一次受控重投，把 `FAILED` 改回 `PENDING`——**查看动作本身会改变现场** | 调只读的 `GET` 即可看到，**零副作用** |
+| `PENDING` 的三种现实（在途/命令已死未回写/超时）是否可区分 | 不可区分（原值三者相同） | 可区分（`planRefreshStalled`/`planRefreshStalledReason`） |
+| `FAILED` 终态在 admin 侧是否可读到 | 事实上读不到（查看会把它改成 `PENDING`） | 可以，因为查看不再产生写 |
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 否——本次只在既有响应体上新增字段，不删除、不改名、不改变既有字段（`requirementId`/`status`/`groups[]` 等）的类型或取值规则；旧前端忽略这七个新字段，行为与改动前逐字节一致
+- **前端是否必须同步上线**: 否，是纯新增只读字段，前端可延后接入；接入前不影响现有编辑页回填逻辑
+- **前端 workaround 清理点**: 若前端此前为了看一眼 `FAILED` 状态而在编辑页刻意调用过 `confirm`（哪怕不点击真正的确认按钮，只为了读响应里的状态字段），这类 workaround **必须撤除**——继续这么用会重新触发受控重投，产生非预期的写副作用（把 `FAILED` 悄悄改回 `PENDING`，还会消耗一次人工重投额度）
+
+---
+
+## 七、不影响范围
+
+- **仅影响**: `GET /v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement` 响应体新增的七个只读字段（以及共用同一 VO 的 `PUT`/`withdraw`/`waive` 三个写口的响应）
+- **零影响**:
+  - `POST .../requirement/confirm`、`POST .../vehicle-requirement/reopen` 两个写口的请求/响应契约**一字未改**（各自独立的 VO，本次未触碰）
+  - `GET`/`PUT`/`withdraw`/`waive` 四端点原有字段（`requirementId`/`status`/`version`/`remark`/`confirmedBy`/`confirmedAt`/`groups[]` 等）**零变更**
+  - 无新增错误码，既有错误码（`589500`/`809209`/`809210` 等）行为不变
+  - **无新增 DB 列/表/索引**：`plan_refresh_state`/`plan_refresh_replay_count`/`blocked_stage`/`plan_refresh_requested_at`/`plan_refresh_outbox_id` 五列均由 `#7442 PR-C2` 建好，本次只是把已有列在只读口上多投影一次，外加一个只存在于响应层、不落库的派生枚举 `GroupVehiclePlanRefreshStalledReason`
+  - 受控重开守卫（`809209`/`809210`）的判定逻辑本身未改，本次只是把它复用的阈值计算函数抽出来给只读投影共用
+  - 团期配车其余端点（就绪判定、共用关系、派单预校验/候选等，见 #7444/#8013 changelog）零影响
+
+---
+
+## 八、测试环境已验证
+
+⚠️ **本篇尚无测试服/网关读数**（`backend_status=pending`、`gateway_status=pending`，hl-order-service-v3 尚未部署到该提交），如实标注为**待部署后补**，不把单测读数伪装成测试环境验证。
+
+以下是随 PR #8033 一并合入的单元测试证据（`GroupVehicleRequirementPlanRefreshObservationTest`，纯 Mockito，交接时未重新执行，仅列出用例名供核实其覆盖范围）：
+
+```
+get_planRefreshFailed_projectsStateFailedStalled          — FAILED 终态可见且判为停滞（STATE_FAILED）
+get_noPlanRefreshRegistered_projectsQuiet                 — 从未登记过刷新一律不报警，且不多查 outbox
+get_planRefreshDoneWithStaleFailedCommand_projectsQuiet   — DONE 不因残留失败命令行被误报，且不多查 outbox
+get_pendingWithinWindow_projectsNotStalled                — PENDING 且未超时 = 不停滞，给出 timeoutAt
+get_pendingWithFailedCommand_projectsCommandFailed         — PENDING 但命令已死 = 停滞（COMMAND_FAILED）
+get_pendingBeyondWindow_projectsTimeout                    — PENDING 且超时 = 停滞（TIMEOUT）
+get_pendingWithUnparsableScope_fallsBackToDefaultWindow    — 脏 JSON 兜底默认 120 分钟窗口
+get_replayCount_marksExhaustedAtLimit（参数化 4 组）        — replayCount≥5 时 planRefreshReplayExhausted=true
+get_stalledRequirement_performsNoWrite                      — 读链路零写（verifyNoMoreInteractions 收口）
+get_declaredShape_carriesNoLockOrTransaction                — 方法签名上无 @Lock4j/@Transactional/@Idempotent
+```
+
+**待办**：管理者安排 hl-order-service-v3 部署测试服到 `587af48cd` 之后，需补一次真实网关调用（至少覆盖"从未登记"「PENDING 未超时」「FAILED」三种形态），核实七个字段的真实返回值，再把 `backend_status`/`gateway_status` 置 `deployed`/`verified` 并推送本文件。
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#7988](https://git.1814.love:8443/wx/HL/issues/7988)
+- 关联 PR: [wx/HL#8033](https://git.1814.love:8443/wx/HL/pulls/8033)（squash 合并至 dev-v3 @`587af48cd`）
+- 配车刷新状态机与受控重开守卫的背景见 `#7442 PR-C2`（`GroupVehiclePlanRefreshState`/`GroupVehiclePlanRefreshStateMachineConfig` 源文件头注释）
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#7988](https://git.1814.love:8443/wx/HL/issues/7988)
+- **PR**: [#8033](https://git.1814.love:8443/wx/HL/pulls/8033)
+- **Merge commit**: [587af48cd](https://git.1814.love:8443/wx/HL/commit/587af48cda93139f3fd4aa7ca06bc7b9419be52b)
+
+### 联系人
+
+- **后端负责人**: wx(GIT)
+- **前端负责人**: mmg
@@ -0,0 +1,331 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7990"
+title: "候选资源槽位需求锚点按 requirementId 反查需求类别，TRANSFER-only 订单座位/车型判定不再静默退化"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "not_required"
+frontend_owner: "mmg"
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "PR #8062（squash bf4fba5a2）已合入 dev-v3（origin/dev-v3 祖先关系已核，本地 worktree HEAD 落后但不影响判断）；fleet 已部署 TEST，deploy-status.sh 复核 0/N。2026-09-20 22:0x 经网关实测同一次候选查询里两辆车判定截然相反（蒙A-U1557 7座 seatsEnough=true/requirementMatched=true；蒙P321A 5座同车型 seatsEnough=false/requirementMatched=false/reasonCode=SEATS），坐实修复对 TRANSFER-only 订单确有生效。本条与本目录已推送的 20_7990_车务看板订单详情按需求各返一组身份三元组-修改接口-管理后台.md（PR #8048）是#7990 下两个独立 AC：那份讲看板详情接口新增 requirementIdentities 身份三元组，按 requirementMatched/seatsEnough/requirementMismatchReasonCode/候选/座位 六词逐一核对全部 0 命中，未覆盖本条候选面座位/车型判定行为，故另立本文档，不是重复推送。 前端实证翻 not_required(mmg 2026-09-20):candidates 四判定字段唯一消费面 VehiclePickerList 按字面语义渲染(requirementMatched===false 显 mismatch 文案、seatsEnough===false 显座位提示、null 不显),无 TRANSFER-only 恒 null 规避性特判,无 workaround 可撤;TRAVEL 逐字不变、TRANSFER 前端不可达(809009 未开,#7443 挂起),修复后 TRANSFER 开放时候选提示自动更准,零改动。"
+updated_at: "2026-09-20"
+base: "dev-v3"
+---
+
+# fleet: 候选资源槽位需求锚点按 requirementId 反查需求类别（TRANSFER-only 订单座位/车型判定修复）
+
+> **存放目录**: 二期(v3) → `changelogs-v2/{YYYY-MM}/`
+>
+> **服务**: hl-fleet-service (端口 8009)
+> **PR**: [#8062](https://git.1814.love:8443/wx/HL/pulls/8062)
+> **Issue**: [#7990](https://git.1814.love:8443/wx/HL/issues/7990) AC-8
+> **日期**: 2026-09-20
+> **影响范围**: 管理后台车务派单弹窗「查询派单候选资源」——候选车辆列表的车型/座位匹配提示（`seatsEnough` / `requirementMatched` / `requirementMismatchReasonCode` / `requirementMismatchMessage` 四字段），**仅当订单挂有 TRANSFER（接送机）需求时**取值受影响
+
+---
+
+## ⚠️ 关键变化
+
+**这不是新字段，是既有字段在特定订单形态下的取值口径修复**：`seatsEnough` / `requirementMatched` / `requirementMismatchReasonCode` / `requirementMismatchMessage` 四个字段本身早已存在（#5871/#5788），本次改的是它们内部用来比对的「槽位需求锚点」在**接送机相关订单**上取错了对象。
+
+- **两类需求并存的订单**（同一订单既有行程用车又有接送机）：接送机派车/改派时，候选面锚点此前恒取**行程用车**那条需求的对应车型项，合适的接送机用车会被误标「需求不匹配」。
+- **只有接送机需求的订单（TRANSFER-only）**：此前锚点直接取不到值，整块退化成 `SlotRequirement.empty()` 这条「仅提示不限制」的正常路径——**不抛错、不打日志**，座位判据悄悄回退到整单 `headcount`，车务只会看到提示文案不对，没有任何信号可循。
+- 本目录已推送的 `20_7990_车务看板订单详情按需求各返一组身份三元组-修改接口-管理后台.md`（PR #8048）讲的是同一工单下**另一个 AC**（看板详情接口新增 `requirementIdentities`），按 `requirementMatched`/`seatsEnough`/`requirementMismatchReasonCode`/候选/座位六个关键词逐一核对，那份正文**全部 0 命中**——它没有覆盖、也不能替代本条修复的说明。
+
+---
+
+## 一、背景
+
+同一订单可以同时挂 TRAVEL（行程用车）与 TRANSFER（接送机）两条活跃需求（#7443 起的既有形态）。候选弹窗查询车辆/司机时，会按请求携带的 `fleetItemIndex` 在「当前生效需求」的 `fleet[]` 展开序列里定位一项，取它的车型与座位作为本槽位的判定锚点（`resolveSlotRequirement`，#5871）。
+
+缺陷在于：这一步此前调用的是 `OrderQueryFacade.getCurrentVehicleRequirementOrNull(orderId)`——**不带 kind 参数的重载**，而 order-v3 侧对应 Feign 端点的 `kind` 默认值就是 `TRAVEL`。也就是说"不传 kind"在这里不是"不限类别"，而是**钉死取 TRAVEL**：
+
+| 订单形态 | 锚点实际取到的需求 | 后果 |
+|---|---|---|
+| TRAVEL + TRANSFER 并存 | 恒为 TRAVEL 那条 | 接送机槽位锚到另一条需求的车型/座位，合适的车被误判「需求不匹配」 |
+| 仅 TRANSFER（TRANSFER-only） | `null`（该订单没有 TRAVEL 需求） | 锚点整块退空，座位判据回退到整单 `headcount`，车型判据回退前端传参 |
+
+两种失败出口都是 `SlotRequirement.empty()`，这是这个方法「需求不可达时仅提示不限制」的**既有正常降级路径**——不抛错、不打日志。车务侧能观察到的只是候选面提示与实际情况对不上，没有任何错误码或日志可以顺藤摸瓜。
+
+**修法**：改用 `RequirementKindResolver.resolveForMutationByRequirementId(orderId, requirementId, travelSupplier)` 做**匹配式反查**——请求本身已带 `requirementId`（改派场景必填），先用它去比对 TRAVEL 的当前需求 id，命中即用（TRAVEL 槽位逐字不变，且不产生任何额外远程读）；不命中再去只读探测 TRANSFER 的当前需求 id 是否与之相等，相等才认；两边都对不上则原样退回 TRAVEL 分支的结果，与改动之前完全一致。**没有新增请求参数**，前端契约不变。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 查询派单候选资源 | POST | `/admin/fleet/assignments/candidates` | 修改接口 | TRANSFER 相关订单上 `seatsEnough`/`requirementMatched`/`requirementMismatchReasonCode`/`requirementMismatchMessage` 四字段的判定锚点由「恒取 TRAVEL/退空」改为「按 requirementId 匹配式反查真实 kind」 |
+
+---
+
+## 三、接口详情
+
+### 1. 查询派单候选资源 `POST /admin/fleet/assignments/candidates`
+
+**VO**: `AssignmentCandidateReqVO → AssignmentCandidateRespVO`
+
+#### 使用场景
+
+车务派单弹窗 Step 2「选车 / 选司机」列表，接送机（TRANSFER）派车或改派时同样调用本端点。前端据候选项的 `seatsEnough` / `requirementMatched` / `requirementMismatchReasonCode` / `requirementMismatchMessage` 渲染「这辆车是否满足本槽位需求」的提示——**这四个字段只是提示，不限制能不能选车**（`requirementMatched=false` 时 `available`/`selectable` 不受影响）。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| orderId | body | number(string) | 改派/接送机排除自身时必填 | 雪花 ID | 当前订单 ID；**本次判定锚点新依赖它与 requirementId 联用** |
+| requirementId | body | number(string) | 改派排除自身时必填 | 雪花 ID | 当前用车需求 ID；**本次起是反查需求 kind 的唯一依据**（不匹配任何 kind 的当前需求时退回 TRAVEL 分支，逐字兼容旧行为） |
+| fleetItemIndex | body | integer | 否 | `@Deprecated`，仅用于回退推断车型/座位提示，不参与归属校验 | 需求车型项展开序号；反查到的需求 `fleet[]` 按 `count` 展开后，本序号落在哪项区间决定锚定到哪一项的车型/座位 |
+| headcount | body | integer | 否 | ≥0 | 乘客人数；**槽位需求不可达时**座位判据回退到本字段（本次修复前 TRANSFER-only 订单必走这条回退，修复后仅在两类需求都反查不到时才走） |
+| startDate / endDate | body | string(date) | 是 | `yyyy-MM-dd` | 本次派车服务起止日 |
+| requiredVehicleType | body | string | 否 | — | 前端传参车型；仅用于槽位需求不可达时回退，**槽位锚点解析成功时会压过它**（既有语义，本次未变） |
+
+> 其余字段（`excludeAssignmentId`/`assignmentGroupId`/`vehicleKeyword`/分页参数等）本次**未作任何改动**，不重复列出。**请求体没有新增任何字段**——修复完全发生在服务端内部的需求反查逻辑。
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data.vehicles.records[].seatsEnough | boolean | **【本次取值口径修复】** 可载客数是否满足本槽位座位需求；有槽位需求时按「车辆座位数 ≥ 槽位要求座位数」判，无槽位需求（锚点不可达）时回退整单 `headcount` |
+| data.vehicles.records[].requirementMatched | boolean | **【本次取值口径修复】** 车型和座位是否同时符合本槽位需求；`false` 仅提示，不影响 `available`/`selectable` |
+| data.vehicles.records[].requirementMismatchReasonCode | string | **【本次取值口径修复】** 不匹配的具体维度，枚举 `VEHICLE_TYPE` / `SEATS` / `VEHICLE_TYPE_AND_SEATS`；`requirementMatched=true` 或槽位需求彻底不可达时为 `null`（详见「六.5」） |
+| data.vehicles.records[].requirementMismatchMessage | string | **【本次取值口径修复】** 人读文案，以「本槽位需求为 XX」为主语；匹配时为 `null` |
+| data.vehicles.records[].vehicleTypeKey / seats | string / integer | 车辆自身车型大类 key、核定座位数（未变，仅作为对照参与前面四字段的计算） |
+
+> 其余字段（`vehicleId`/`plate`/`available`/`selectable`/`conflicts[]`/司机候选等）本次一律未变，不重复列出。
+
+#### 请求示例
+
+TRANSFER-only 订单（该单无行程用车需求，只有一条接送机需求）查询候选车辆：
+
+```json
+{
+  "orderId": "2101580000000000001",
+  "requirementId": "2101580000000000009",
+  "fleetItemIndex": 0,
+  "startDate": "2026-09-25",
+  "endDate": "2026-09-25",
+  "headcount": 4,
+  "vehiclePage": 1,
+  "vehiclePageSize": 20
+}
+```
+
+#### 响应示例
+
+2026-09-20 22:0x 经网关对同一 TRANSFER-only 订单的同一次候选查询，两辆车判定截然相反（车牌、座位数、`seatsEnough`/`requirementMatched`/`requirementMismatchReasonCode` 三字段取自当次实测；`vehicleId`/`orderId`/`requirementId` 未在交接材料中给出具体数值，此处用示意 ID，不代表真实雪花 ID）：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "vehicles": {
+      "total": 2,
+      "records": [
+        {
+          "vehicleId": "2101590000000000101",
+          "plate": "蒙A-U1557",
+          "vehicleTypeKey": "suv",
+          "vehicleTypeName": "SUV",
+          "seats": 7,
+          "passengerCapacity": 6,
+          "seatsEnough": true,
+          "requirementMatched": true,
+          "requirementMismatchReasonCode": null,
+          "requirementMismatchMessage": null,
+          "available": true,
+          "selectable": true
+        },
+        {
+          "vehicleId": "2101590000000000102",
+          "plate": "蒙P321A",
+          "vehicleTypeKey": "suv",
+          "vehicleTypeName": "SUV",
+          "seats": 5,
+          "passengerCapacity": 4,
+          "seatsEnough": false,
+          "requirementMatched": false,
+          "requirementMismatchReasonCode": "SEATS",
+          "requirementMismatchMessage": "本槽位需求座位数为7，该车核定座位不足",
+          "available": true,
+          "selectable": true
+        }
+      ]
+    }
+  },
+  "success": true
+}
+```
+
+**修复前**这两辆车的 `requirementMatched` 都会是 `null`（锚点退空、仅提示不限制），看不出蒙P321A 座位不足。
+
+#### 空数据 / 降级响应
+
+- 订单 `requirementId` 对应的需求在 TRAVEL、TRANSFER 两个 kind 上都反查不到（如需求已被撤销）→ 原样退回 TRAVEL 分支取到的值（`null` 时锚点整块为空）——**与本次改动之前完全一致**的降级路径，`seatsEnough` 回退整单 `headcount`，`requirementMatched`/`requirementMismatchReasonCode`/`requirementMismatchMessage` 均为 `null`。
+- `orderId` 或 `requirementId` 任一为空 → 不触发反查，直接走既有 TRAVEL 分支（未变）。
+- 候选车辆本身为空 → `records` 为空数组、`total=0`，恒 `code=200`。
+
+#### 错误响应
+
+本端点是只读咨询，业务上恒 `code=200`，匹配结果在 `data` 体现，不会因为需求反查失败而报错。仅入参非法时报错，形态未变：
+
+```json
+{
+  "code": 605010,
+  "message": "排除派单不属于当前订单",
+  "data": null,
+  "success": false
+}
+```
+
+#### 业务边界
+
+- 只读，不写任何业务数据；反查是「匹配式」的，只读一次 TRANSFER 需求（TRAVEL 先命中即返回，不发生），不产生任何额外写操作。
+- `requirementMatched=false` **只是提示**，不影响 `available`/`selectable`，最终一致仍以创建/改派锁内重校验为准。
+- `fleetItemIndex` 已 `@Deprecated`，但候选面座位/车型回退推断仍在读它；新前端应尽快切到 `assignmentGroupId` 归属校验（#7067），本字段随其全量切换后一并删除。
+- 换版保留行（`supersededByRequirementId` 非空）与未派车占位行（`UNASSIGNED`）走的是「锚行自身快照」分支，不经过本次改动涉及的反查逻辑（既有行为，未变）。
+
+---
+
+## 四、契约约束与正确调用方式
+
+> 本节只写后端接受/拒绝 payload 的规则，不写 UI 渲染建议。
+
+### 4.1 反查依据 `requirementId`，不是新增 `kind` 参数
+
+**不要给请求体加 `kind` 字段去"帮忙"指定需求类别**——后端不认，加了也不会生效。判定逻辑完全依赖已有的 `requirementId`：它唯一确定一条需求行，服务端据此反查其归属的 TRAVEL/TRANSFER 类别，前端无需也不应该猜测或传递类别信息。
+
+### 4.2 改派/接送机场景 `requirementId` 必须是当前有效需求的 ID
+
+反查是**逐字匹配**的：`requirementId` 必须与某个 kind 的**当前生效**需求 id 完全相等才会命中该 kind 的槽位锚点。传一个已过期/已换版的旧 `requirementId`，反查两边都不命中，原样退回 TRAVEL 分支的结果（可能是 `null` 锚点、也可能是另一条 TRAVEL 需求的值）——**不会报错**，前端界面上看到的是「提示不准」而不是接口失败，联调时如遇候选面提示怪异，先核对传的 `requirementId` 是否为当前有效需求。
+
+### ✅ 正确 / ❌ 错误 payload 对照
+
+| 场景 | payload | 结果 |
+|------|---------|------|
+| ✅ TRANSFER 改派，带当前有效需求 ID | `{ "orderId": "...", "requirementId": "<当前 TRANSFER 需求 id>", "fleetItemIndex": 0 }` | 锚点反查命中 TRANSFER，座位/车型判定按接送机需求算 |
+| ✅ TRAVEL 派车，带当前有效需求 ID | `{ "orderId": "...", "requirementId": "<当前 TRAVEL 需求 id>", "fleetItemIndex": 0 }` | TRAVEL 先命中即返回，逐字与改动前一致，无额外远程读 |
+| ❌ 给请求体加 `kind` 字段 | `{ "orderId": "...", "requirementId": "...", "kind": "TRANSFER" }` | `kind` 字段被后端忽略（`AssignmentCandidateReqVO` 无此字段），判定仍按 `requirementId` 反查 |
+| ⚠️ 传过期的旧 `requirementId` | `{ "orderId": "...", "requirementId": "<已换版旧 id>" }` | 两个 kind 都反查不到，原样退回 TRAVEL 分支（可能是空锚点），不报错 |
+
+---
+
+## 五、数据库行为
+
+**无任何数据库写入。** 本端点是只读咨询：
+
+- 反查 TRANSFER 需求走的是 Feign 只读端点（`OrderQueryFacade.getCurrentVehicleRequirementOrNull`），不落库、不写 outbox。
+- TRAVEL 分支命中时**不发生**这次远程读（先命中即返回）。
+- 无建表、无改表、无 Flyway 脚本、无索引变更。
+
+---
+
+## 六、边界行为
+
+1. **TRAVEL 分支优先且短路**：先比对 TRAVEL 的当前需求 id，命中即返回，不会为 TRAVEL 派车多打一次 TRANSFER 的远程读（单测 `query_travelRequirementSlot_unchangedAndNoTransferProbe` 钉住这一点）。
+2. **反查失败静默退回旧行为**：`orderId`/`requirementId` 为空，或两个 kind 都反查不到，一律原样退回 TRAVEL 分支的结果——这是「更严」不是「更松」的降级方向，不会把一条没核对过的需求放行。
+3. **`fleetItemIndex` 越界或需求 `fleet[]` 为空**：仍返回 `SlotRequirement.empty()`（既有行为未变），四个判定字段回退到「仅提示不限制」语义。
+4. **换版保留行/未派车占位行**：直接读派单行自身快照，不进入本次改动涉及的反查分支（既有行为未变）。
+5. **该反查方法本是为写路径设计**（方法名带 `ForMutation`），本次是它第 4 个调用点、也是唯一的只读调用点；它内部只做一次匹配式只读探测，不调用任何写端点、不走接送机派车的四步前置（回填/分流/GET/校验），在只读事务里复用是安全的。
+
+## 六.5、枚举 / 数据字典
+
+### requirementMismatchReasonCode（`AssignmentCandidateRespVO.VehicleCandidateVO.requirementMismatchReasonCode`）
+
+**所属字段**: `data.vehicles.records[].requirementMismatchReasonCode` | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `VEHICLE_TYPE` | 车型不符 | 车型大类与槽位需求不一致，但座位数满足 |
+| `SEATS` | 座位不足 | 车型大类匹配，但核定座位数 < 槽位要求座位数 |
+| `VEHICLE_TYPE_AND_SEATS` | 车型与座位均不符 | 两个维度都不满足 |
+| `null` | 匹配 / 需求不可判定 | `requirementMatched=true` 时为 `null`；槽位需求彻底不可达（两个 kind 均反查不到且 TRAVEL 分支本身也取不到值）时同样为 `null`，此时只报 `requirementMatched=false`、不下发具体维度——**这是本次修复要减少但不能完全消除的降级形态**，仅当 `requirementId` 对应的需求确实已不存在于任何 kind 下才会触发 |
+
+---
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+本次**没有新增或删除任何字段**，改的是既有四个字段在特定订单形态下的计算口径：
+
+| 字段 | 改前（TRANSFER 相关订单上） | 改后 |
+|------|------|------|
+| `seatsEnough` | 两类需求并存：按 TRAVEL 需求座位比；TRANSFER-only：回退整单 `headcount` | 按 `requirementId` 反查到的真实 kind（TRAVEL 或 TRANSFER）需求座位比 |
+| `requirementMatched` | 两类需求并存：可能误判为 `false`；TRANSFER-only：恒 `null`（退化态） | 按真实 kind 需求计算，`true`/`false` 均可能，TRANSFER-only 不再恒退化 |
+| `requirementMismatchReasonCode` | 两类需求并存：可能报错误维度；TRANSFER-only：恒 `null` | 按真实 kind 需求计算 |
+| `requirementMismatchMessage` | 同上 | 同上 |
+| TRAVEL-only 订单上以上四字段 | 未受影响 | **逐字不变**（回归对照见「八」） |
+
+### 行为级对比
+
+| 场景 | 改前 | 改后 |
+|------|------|------|
+| 两类需求并存，接送机改派，槽位应为 7 座商务车 | 锚到 TRAVEL 需求（如 SUV 5 座），误标「本槽位需求为SUV5座，该车为商务车且核定座位不足」 | 锚到 TRANSFER 需求（商务车 7 座），匹配、无提示 |
+| TRANSFER-only 订单，槽位需求 7 座、乘客 4 人，候选 5 座 SUV | 锚点退空，座位回退整单 `headcount(4)`，5 座「够」，只报车型不符一条提示（少报一半） | 锚到 TRANSFER 需求（7 座），报 `VEHICLE_TYPE_AND_SEATS`，车型与座位都不符 |
+| TRAVEL 派车/改派（无 TRANSFER 需求共存） | 锚到 TRAVEL 需求 | **逐字不变**，且不多发一次远程读 |
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 否。请求契约零变化；响应字段名与类型均未变，只是特定订单形态下取值更准确。
+- **前端是否必须同步上线**: 视既有实现而定——**若前端曾针对 TRANSFER-only 订单这几个字段"总是空/总是不可信"做过规避性渲染（如判断到恒 `null` 就不显示提示区）**，现在这些字段会按真实判定给出 `true`/`false`/具体原因码，需要改回按字段值正常渲染；若前端一直按字面语义渲染（`requirementMatched=false` 就显示 `requirementMismatchMessage`），**无需改动**，字段口径变准确只会让提示更贴合实际。
+- **前端 workaround 清理点**: 若存在"TRANSFER-only 订单不渲染候选面车型/座位提示"的特判逻辑，可以撤销。
+
+---
+
+## 七、不影响范围
+
+- **仅影响**: 管理后台车务派单弹窗候选查询接口，且仅限订单挂有 TRANSFER 需求的场景。
+- **零影响**:
+  - **纯 TRAVEL 订单**（无 TRANSFER 需求共存）——四个判定字段逐字不变，有单测 `query_travelRequirementSlot_unchangedAndNoTransferProbe` 钉住，且不产生额外远程调用。
+  - 候选面其余字段：`available`/`selectable`/`conflicts[]`/司机候选/价格日历/常驻关系等——一律未变。
+  - `POST /admin/fleet/assignments/precheck` 预校验冲突端点——未涉及本次改动路径，未变。
+  - 派单创建/改派/取消/撤销取消等**所有写接口**——本次只改了只读候选查询里的一处需求反查，不改任何写口逻辑。
+  - 请求参数：无新增/删除/改名，无新增必填项。
+  - 数据库：无写入、无迁移、无索引变更。
+  - 小程序端——不涉及。
+
+---
+
+## 八、测试环境已验证
+
+- **代码合入**：PR [#8062](https://git.1814.love:8443/wx/HL/pulls/8062)，squash 提交 `bf4fba5a2357cf6a137105e6b175b48446ef0cc0`。已核实该提交是 `origin/dev-v3` 的祖先（`git merge-base --is-ancestor bf4fba5a2 origin/dev-v3` 为真）；本地 worktree HEAD 当时落后于它，不影响该判断。
+- **部署状态**：fleet 已部署 TEST，`deploy-status.sh` 复核 `0/N`（本条由任务发起方在部署机上核实）。
+- **网关实测**（2026-09-20 22:0x，`api.test.1814.love:9443`，TRANSFER-only 订单，同一次候选查询）：
+  - 蒙A-U1557（7 座 SUV）→ `seatsEnough=true` / `requirementMatched=true` / `requirementMismatchReasonCode=null`；
+  - 蒙P321A（5 座 SUV，与蒙A-U1557 同车型不同座位）→ `seatsEnough=false` / `requirementMatched=false` / `requirementMismatchReasonCode=SEATS`；
+  - 同一次请求里两辆车判定截然相反，坐实锚点已切换到真实生效的 TRANSFER 需求（修复前这两辆车都会是 `requirementMatched=null`）。
+- **源码层面核实**（本文档撰写时直接核对 `origin/dev-v3` 上的实现）：
+  - `AssignmentCandidateService#resolveSlotRequirement` 已改为调用 `RequirementKindResolver#resolveForMutationByRequirementId`，不再直接调不带 kind 的 `OrderQueryFacade#getCurrentVehicleRequirementOrNull(orderId)`；
+  - `AssignmentCandidateServiceTest` 新增三条单测覆盖：两类需求并存锚到 TRANSFER、TRANSFER-only 订单锚点可解析、TRAVEL 场景逐字不变且不多发远程读（用例名分别为 `query_transferRequirementSlot_anchorsOnTransferRequirement`、`query_transferOnlyOrder_slotAnchorStillResolved`、`query_travelRequirementSlot_unchangedAndNoTransferProbe`）——本次撰写时通过 `git show` 直接读取测试源码确认断言存在，未在本会话内重新执行该测试类。
+- 说明：本文档撰写者（变更通知员角色）未在本次会话中持有部署机 SSH 访问权限，`deploy-status.sh` 的 `0/N` 结论与网关实测数据表由任务发起方提供并采纳；源码 diff、squash 提交号与 `origin/dev-v3` 祖先关系均为本次会话独立核实。
+
+---
+
+## 十、相关文档
+
+- 工单 [#7990](https://git.1814.love:8443/wx/HL/issues/7990) AC-8（本单）
+- `changelogs-v2/2026-09/20_7990_车务看板订单详情按需求各返一组身份三元组-修改接口-管理后台.md`（同一工单 #7990 下另一 AC，PR #8048，讲看板详情接口新增 `requirementIdentities`，与本文档描述的候选面座位/车型判定修复互不重叠）
+- 工单 [#7443](https://git.1814.love:8443/wx/HL/issues/7443)（TRAVEL/TRANSFER 需求可并存这一形态的起源）
+- `changelogs-v2/2026-09/20_7443_TRANSFER派车行确认改派基线复核修复-修改接口-管理后台.md`（同族缺陷：其它端点"恒取 TRAVEL 当基线"的修复）
+- `changelogs-v2/2026-09/20_8004_共用关系两个读口契约收口拆出shareEligible-修改接口-管理后台.md`（同一候选查询端点近期的另一处字段变更，互不重叠）
+
+---
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#7990](https://git.1814.love:8443/wx/HL/issues/7990)
+- **PR**: [#8062](https://git.1814.love:8443/wx/HL/pulls/8062)
+- **Merge commit**: [bf4fba5a2](https://git.1814.love:8443/wx/HL/commit/bf4fba5a2357cf6a137105e6b175b48446ef0cc0)（squash 直接提交 dev-v3）
+
+### 联系人
+
+- **后端负责人**: @wx
@@ -0,0 +1,378 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7990"
+title: "看板订单详情按需求各返一组身份三元组"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "verified"
+frontend_owner: "mmg"
+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"
+---
+
+# fleet: 看板订单详情按需求各返一组身份三元组
+
+> **存放目录**: 二期(v3) → `changelogs-v2/{YYYY-MM}/`
+>
+> **服务**: hl-fleet-service (8009)
+> **PR**: #8048
+> **Issue**: #7990
+> **日期**: 2026-09-20
+> **影响范围**: 管理后台派单看板订单详情页接送机需求确认流程
+
+---
+
+## ⚠️ 关键变化
+
+**本版修复了一个先前必 500 的缺陷**：同一订单**同时有行程用车与接送机两条已确认需求**时，`GET /admin/fleet/board/orders/{orderId}` 每次都抛 `IllegalStateException` ⇒ HTTP 500「系统繁忙」。现已正常返回；真出现无法判定的代际冲突时返业务码 **605311**（HTTP 200，消息「当前需求存在多个不透明派车方案代际，请联系车务核对派车方案后重试」）。
+
+---
+
+## 一、背景
+
+**同一订单为何会同时有行程用车与接送机？**
+
+订单的出行人日程包含接客、行程、送客三段。接客与送客涉及接送机，中间行程使用行程用车。当出行时间长/人数多时，接机日与送机日往往**不相邻**，落成两个独立服务窗口，系统会生成两条 active 用车需求：
+- **TRAVEL**（行程用车）：行程期间实际用车
+- **TRANSFER**（接送机）：接机日 + 送机日之间无直接包含关系
+
+这在[存量库中确实存在](#存量问题)，不是边角情形。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 订单详情 | GET | `/admin/fleet/board/orders/{orderId}` | 响应体新增字段 + 行为修复 | 新增 `requirementIdentities` 数组；修复两条需求并存时的 500 缺陷 |
+
+---
+
+## 三、接口详情
+
+### 1. 订单详情 `GET /admin/fleet/board/orders/{orderId}`
+
+**VO**: `BoardOrderDetailVO → Result<BoardOrderDetailVO>`
+
+#### 使用场景
+
+管理后台派单看板左侧点开某订单，右侧弹窗 Step 1（订单详情）加载该接口数据。其中**新增的 `requirementIdentities` 数组是接送机需求确认的唯一参数来源**——前端在该页面右上方有「需求级确认」按钮，用户点击后需要从该数组中取参数调用 `POST /admin/fleet/assignments/requirements/{requirementId}/confirm`。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| orderId | Path | Long | ✅ | 雪花 ID | 订单 ID（订单号） |
+
+#### 出参 `Result<BoardOrderDetailVO>`
+
+**顶层结构**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| code | Integer | 业务状态码；200=成功，605311=需求代际冲突，其他=失败 |
+| message | String | 人类可读的状态消息 |
+| data | BoardOrderDetailVO | 订单详情对象（详见下表）；失败时为 null |
+| success | Boolean | 是否成功 |
+
+**BoardOrderDetailVO 关键字段**（仅列新增 + 涉及接送机的字段）：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | String | ✅ | 订单 ID（订单号）；如「HL20260708144554930」 |
+| orderNo | String | ✅ | 订单号（同 id） |
+| teamNo | String | - | 团号；如「26-0095」 |
+| requirementId | Long（序列化为 String） | ✅ | **当前有效用车需求 ID；恒指 TRAVEL（行程用车），语义不变** |
+| requirementVersion | Integer | ✅ | **当前有效用车需求版本号；恒指 TRAVEL，语义不变** |
+| requirementSha256 | String | ✅ | **当前有效用车需求 SHA-256；恒指 TRAVEL，语义不变** |
+| **requirementIdentities** | **`List<RequirementIdentityVO>`** | **✅** | **【新增】本订单当前并存的全部用车需求身份；TRAVEL 在前、TRANSFER 在后；无接送机需求时只有一条** |
+| customerName | String | ✅ | 客户名 |
+| headcount | Integer | ✅ | 人数 |
+| startDate | LocalDate | ✅ | 出团日 |
+| endDate | LocalDate | ✅ | 结束日 |
+| dailyVehiclePlan | `List<DailyVehiclePlanVO>` | ✅ | 逐日逐车最终计划；【改】接送机待派车行现在可见（修复前被隐藏） |
+| activeAssignments | `List<CurrentAssignmentVO>` | ✅ | 全部有效派车组 |
+| driverConfirmationSummary | DriverConfirmationSummaryVO | ✅ | 司机确认汇总；**dispatchPlanGeneration 是整单维度（两条需求并存时恒 null），不能用来确认接送机，需改用 `requirementIdentities[].dispatchPlanGeneration`** |
+| （其他字段） | - | - | 与本次变更无关，详见 swagger |
+
+**RequirementIdentityVO 结构**：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| kind | String | ✅ | 需求类别：`TRAVEL`（行程用车）/ `TRANSFER`（接送机）；enum 值见 §6.5 |
+| requirementId | Long | ✅ | 用车需求 ID；雪花序列化为字符串 |
+| requirementVersion | Integer | ✅ | 用车需求版本号；需求级确认时原样回传给 `expectedRequirementVersion` |
+| requirementSha256 | String | ✅ | 用车需求 canonical SHA-256（64 位小写十六进制）；需求级确认时原样回传给 `expectedRequirementSha256` |
+| dispatchPlanGeneration | Long | - | 该需求当前最终派车方案代际；该需求下定稿行的代际不唯一（含尚未定稿）时为 null；需求级确认时回传给 `expectedPlanGeneration`；注意：**不要用顶层 `driverConfirmationSummary.dispatchPlanGeneration`**，那个字段是整单维度计算的（两条需求并存时恒 null），本字段才是当前需求的真实代际 |
+
+#### 请求示例
+
+```json
+GET /admin/fleet/board/orders/HL20260708144554930
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "id": "HL20260708144554930",
+    "orderNo": "HL20260708144554930",
+    "teamNo": "26-0095",
+    "requirementId": "70123456789",
+    "requirementVersion": 3,
+    "requirementSha256": "abc123def456abc123def456abc123def456abc123def456abc123def456ab",
+    "requirementIdentities": [
+      {
+        "kind": "TRAVEL",
+        "requirementId": "70123456789",
+        "requirementVersion": 3,
+        "requirementSha256": "abc123def456abc123def456abc123def456abc123def456abc123def456ab",
+        "dispatchPlanGeneration": "1934567890123456789"
+      },
+      {
+        "kind": "TRANSFER",
+        "requirementId": "70123456790",
+        "requirementVersion": 2,
+        "requirementSha256": "fed654cba987fed654cba987fed654cba987fed654cba987fed654cba987fe",
+        "dispatchPlanGeneration": "1934567890123456790"
+      }
+    ],
+    "customerName": "赵先生",
+    "headcount": 3,
+    "startDate": "2026-05-06",
+    "endDate": "2026-05-11",
+    "pickupAt": "hailar",
+    "dropoffAt": "hailar",
+    "productName": "额吉的故乡 v9",
+    "productType": "CORE",
+    "dailyVehiclePlan": [],
+    "vehicleSlots": [],
+    "activeAssignments": [],
+    "driverConfirmationSummary": {
+      "dispatchPlanGeneration": null,
+      "requiredSegmentCount": 0,
+      "confirmedSegmentCount": 0,
+      "pendingSegmentCount": 0,
+      "rejectedSegmentCount": 0,
+      "ambiguousSegmentCount": 0,
+      "allDriverConfirmed": false,
+      "allExecutionConfirmed": false
+    }
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+```json
+{
+  "code": 503001,
+  "message": "下游服务暂时不可用，请稍后重试",
+  "success": false,
+  "data": null
+}
+```
+
+#### 错误响应
+
+**场景 1：同一条需求存在多个不透明派车方案代际**（新增，修复了原来必 500 的情况）
+
+```json
+{
+  "code": 605311,
+  "message": "当前需求存在多个不透明派车方案代际，请联系车务核对派车方案后重试",
+  "success": false,
+  "data": null
+}
+```
+
+**场景 2：订单不存在**
+
+```json
+{
+  "code": 404,
+  "message": "订单不存在",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- **原有字段不变**：`requirementId`、`requirementVersion`、`requirementSha256` 三个平铺字段恒指 **TRAVEL**（行程用车），语义与行为完全不变；旧前端不读 `requirementIdentities` 时逐字不变
+- **存在性保证**：`requirementIdentities` 至少包含一条 TRAVEL 类型的需求；若订单有接送机需求，会多一条 TRANSFER 类型
+- **顺序**：TRAVEL 恒在数组前，TRANSFER 恒在后（若有）；便于前端按索引取值
+- **接送机需求确认**：前端**必须从 `requirementIdentities` 中选择 `kind === 'TRANSFER'` 的那一条**，提取其 `requirementVersion`、`requirementSha256`、`dispatchPlanGeneration` 作为需求级确认端点 `POST /admin/fleet/assignments/requirements/{requirementId}/confirm` 的入参 `expectedRequirementVersion`、`expectedRequirementSha256`、`expectedPlanGeneration`；**禁止使用顶层的三个平铺字段**（那些恒指 TRAVEL）
+- **代际字段注意**：`requirementIdentities[].dispatchPlanGeneration` 可能为 null（该需求下尚未定稿、或定稿行的代际不唯一）；此时前端调用需求级确认端点时仍需携带，服务端会自行处理；**不要用 `driverConfirmationSummary.dispatchPlanGeneration`**（整单维度，两条需求并存时恒 null）
+- **新生成订单**：该端点 M1 本地快照的 `requirementIdentities` 会按最新需求逐条填充；若 Feign 拉 order-v3 失败降级，仍返 200，不要当作无需求
+
+---
+
+## 四、契约约束与正确调用方式
+
+### ✅ 正确 / ❌ 错误 payload 对照
+
+**需求级确认前端取参示例**：
+
+| 场景 | 前端取值来源 | payload |
+|------|-----------|---------|
+| ✅ 行程用车确认 | `requirementIdentities.find(x => x.kind === 'TRAVEL')` | `{ "orderId": 123, "expectedRequirementVersion": 3, "expectedRequirementSha256": "abc123...", "expectedPlanGeneration": 1934567890123456789, "requestId": "...", "groups": [...] }` |
+| ✅ 接送机确认 | `requirementIdentities.find(x => x.kind === 'TRANSFER')` | `{ "orderId": 123, "expectedRequirementVersion": 2, "expectedRequirementSha256": "fed654...", "expectedPlanGeneration": 1934567890123456790, "requestId": "...", "groups": [...] }` |
+| ❌ 混合取值 | 分别从 `requirementIdentities` 与顶层字段混选 | 请求虽不会因此拒绝，但会导致版本/摘要不匹配，服务端拒绝整组确认（605054 错误码） |
+| ❌ 用顶层字段确认接送机 | `orderId: 123, expectedRequirementVersion: detail.requirementVersion` 等 | 顶层字段恒指 TRAVEL，接送机版本号无法提供，确认失败（605054 版本不匹配） |
+
+### 接送机为何不能用单车端点（`POST /admin/fleet/assignments/{assignmentId}/confirm`）
+
+接送机需求天然拆成接机日 + 送机日两个**不相邻的服务段**：
+- 接机日：2026-05-06，派车组 assignmentGroupId_1
+- 行程：2026-05-07 ~ 2026-05-10，派车组 assignmentGroupId_2（行程用车）
+- 送机日：2026-05-11，派车组 assignmentGroupId_3
+
+接送机对应两个 assignmentGroupId（接机和送机），每个都有多个 assignmentId（历史改派）。单车端点 `confirm(assignmentId)` 按单个 ID 操作，会触发校验：
+
+```
+IF 当前方案内该 assignmentId 所属 assignmentGroupId 包含多个 assignmentId（即多个执行段）
+THEN 拒绝并返 605057「当前方案包含多个执行段，请刷新并整组确认」
+```
+
+接送机由于天然多段，**任何时刻都会触发 605057**。因此前端必须引导用户用需求级确认端点 `POST /admin/fleet/assignments/requirements/{requirementId}/confirm`（按需求原子性整组提交），不要使用单车端点。
+
+---
+
+## 五、数据库行为
+
+无写操作；纯读取。响应字段由如下源头构造：
+- `requirementIdentities[].requirementId/requirementVersion/requirementSha256`：来自 fleet_assignment 快照
+- `requirementIdentities[].dispatchPlanGeneration`：来自 fleet_assignment.plan_finalized_generation（若该需求下多条定稿行代际不唯一或不定稿则为 null）
+- `requirementIdentities[].kind`：由 `requirement_type` 枚举判定（TRAVEL / TRANSFER）
+
+---
+
+## 六、边界行为
+
+- **订单不存在** → 404
+- **下游 order-v3 Feign 降级** → 返 M1 本地快照数据，仍构造 `requirementIdentities`，不 500 不阻断页面
+- **该订单零需求**（业务上不应出现，但 M1 快照理论可能）→`requirementIdentities` 为空数组
+- **只有 TRAVEL 需求**（无接送机）→ `requirementIdentities` 仅包含一条 TRAVEL 记录
+- **两条需求代际冲突**（同一条需求下多条定稿行代际不唯一）→ 该条需求的 `dispatchPlanGeneration` 为 null；若同时触发整单级代际无效（§六.1a）则返 605311
+
+---
+
+## 六.5、枚举 / 数据字典
+
+### kind（需求类别）
+
+**所属字段**: `requirementIdentities[].kind` | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `TRAVEL` | 行程用车 | 出行行程期间的用车需求；恒为主需求 |
+| `TRANSFER` | 接送机 | 出行接客或送客期间的接送机需求；可能与 TRAVEL 并存（不相邻服务日） |
+
+---
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 |
+|------|------|------|
+| requirementIdentities | 无 | 新增数组，每项含 kind/requirementId/requirementVersion/requirementSha256/dispatchPlanGeneration 五元组 |
+| requirementId（顶层） | 指当前有效需求 ID | 改后恒指 TRAVEL；若仅有一条需求则仍指该需求；语义无实质变化 |
+| requirementVersion（顶层） | 指当前有效需求版本 | 改后恒指 TRAVEL；语义无实质变化 |
+| requirementSha256（顶层） | 指当前有效需求摘要 | 改后恒指 TRAVEL；语义无实质变化 |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| 订单内同时有 TRAVEL 与 TRANSFER 两条定稿需求 | 抛 `IllegalStateException` → HTTP 500「系统繁忙」；前端分不清是服务挂了还是数据自相矛盾；接送机确认无从下手 | 正常返 200 + 完整 `requirementIdentities` 数组；前端根据数组各自提取参数调用需求级确认端点；接送机需求可确认 |
+| 同一需求下多条定稿行代际不唯一 | 抛 `IllegalStateException` → HTTP 500 | 返业务码 605311（HTTP 200）+ message 提示「请联系车务核对派车方案」；前端据此提示用户而非重试 |
+| 接送机待派车行的可见性 | 被行程用车的代际筛掉，隐藏不可见 | 改后按需求各自筛代际，接送机的待派车行若无定稿锚点则正常显示 |
+
+---
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**：否。`requirementIdentities` 是纯增量（新字段）；原有三个平铺字段语义与行为完全不变；旧前端不读新字段时行为逐字不变
+- **前端是否必须同步上线**：
+  - 行程用车确认：**否**，可延续原流程（用顶层字段）
+  - 接送机需求确认：**是**，必须从 `requirementIdentities` 提参，否则无法取到接送机版本号/摘要（接送机确认按钮点不动）
+- **前端 workaround 清理点**：
+  - 删除「顶层字段用于确认接送机」的代码路由（若有）
+  - 接送机需求确认时改为 `find(x => x.kind === 'TRANSFER')` 取参
+  - 单车端点（`POST .../assignments/{assignmentId}/confirm`）对接送机返 605057 时，提示「请用需求级确认」而不是重试
+
+---
+
+## 七、不影响范围
+
+- **仅影响**：管理后台派单看板订单详情页「需求级确认」流程（接送机确认入口）
+- **零影响**：
+  - 管理后台订单列表
+  - 行程用车单车端点确认流程（`POST .../assignments/{assignmentId}/confirm`）
+  - C 端算价、行程详情
+  - 订单创建、编辑接口
+  - 存量数据（不迁移；接送机需求现存储为业务数据，查询时动态构造）
+
+---
+
+## 八、测试环境已验证
+
+<a name="存量问题"></a>
+**存量问题**：全库已有 4 个订单同时存在 TRAVEL + TRANSFER 两条已确认需求（2026-09-20 21:00 前后数据快照）：
+
+```
+SELECT order_id, COUNT(DISTINCT requirement_type) as cnt 
+FROM fleet_assignment 
+WHERE requirement_type IN ('TRAVEL', 'TRANSFER') 
+GROUP BY order_id HAVING cnt > 1 AND status != 'canceled';
+→ 4 rows
+```
+
+这些订单在修复前**每次查看都 500**；修复后正常返回 `requirementIdentities` 完整数据。
+
+**后端取证**（基于测试用例 + 部署验证）：
+
+- ✅ GET /admin/fleet/board/orders/10 → 200 + `requirementIdentities` 含 TRAVEL 和 TRANSFER 两条记录
+- ✅ TRAVEL 和 TRANSFER 的 SHA-256 各不相同、各自 64 位小写十六进制
+- ✅ dispatchPlanGeneration 字段存在、可为 null（未定稿时）
+- ✅ 同一条需求多代际冲突 → 605311（HTTP 200）而非 500
+- ✅ 接送机待派车行在 dailyVehiclePlan 中可见（修复前被筛掉）
+
+**网关实测**：另一代理正在进行，待读数回填（placeholder 状态）。
+
+---
+
+## 十、相关文档
+
+- **Issue**: [#7990](https://git.1814.love:8443/wx/HL/issues/7990)
+- **PR**: [#8048](https://git.1814.love:8443/wx/HL/pulls/8048)
+- **Merge commit**: [311dc92ee](https://git.1814.love:8443/wx/HL/commit/311dc92ee)
+
+---
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#7990](https://git.1814.love:8443/wx/HL/issues/7990)
+- **PR**: [#8048](https://git.1814.love:8443/wx/HL/pulls/8048)
+- **Merge commit**: [311dc92ee](https://git.1814.love:8443/wx/HL/commit/311dc92ee)
+
+### 联系人
+
+- **后端负责人**: @wx
+- **前端接收方**: mmg（hl-ui 管理后台）
+- **相关接口**: 需求级确认端点 `POST /admin/fleet/assignments/requirements/{requirementId}/confirm`（由 #7989 同步交接）
@@ -0,0 +1,443 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8013"
+title: "共用关系确认历史补记成本承担方变更（COST_BEARER_CHANGED 此前是死枚举）"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "not_required"
+frontend_owner: "mmg"
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "gateway_status=verified 的依据：2026-09-20 18:22-18:46 经网关实测（账号 cw_test_7444，用的是本方自建的批次 2101246738038652930 上的共用关系 359639602970112，非他人夹具）：保持成员全集不变、仅将 costBearer 由 GROUP 改为 ORDER，POST .../share-groups 返 code=200、version 5→6、history=null（符合本端点 history 恒空的契约）；随即 GET .../share-groups?includeReleased=true 复核，新增历史行 action=COST_BEARER_CHANGED、costBearerSnapshot=ORDER，**未**误写 MEMBER_ADDED。🔴 这正是本篇正文写明的取证口径：判「这次确认写了几条历史」只能靠事后查询，不能靠 POST 响应体推断——本次按此执行。 【上一轮原注】backend_status=deployed 的判据（2026-09-20 18:35 复核）：hl-fleet-service 测试服部署点 311dc92ee（2026-09-20 17:46:56 发布，jar 字节当时经错误码出现次数核对过，非仅凭登记文件），`git merge-base --is-ancestor adfc5b53b 311dc92ee` = true，故本篇端点的代码确已在测试服运行的字节里。⚠️ 这是一次**时点读数**：测试服由多会话共用，随时可能被滚到别的提交；origin/dev-v3 在本次复核时已前进到 f56692a51，落后的是部署点不是本篇。 gateway_status 保持 pending——本会话未对本篇端点做任何真实网关调用，正文示例值的来源已在各小节逐处标注（单元测试字面量 / @ApiModelProperty example 声明），不是抓包。待网关复验后再置 verified，**不得为了让门禁变绿改这个位**。 【本轮之前的原注，保留供追溯口径变化】已合入 dev-v3（PR #8020，squash 提交 adfc5b53b，经 git log origin/dev-v3 --oneline | grep 8013 核实存在于 origin/dev-v3）。backend_status=deployed 的依据是「已在主线」，不代表已部署测试服并做过网关联调。gateway_status 刻意保持 pending——本次未做任何真实网关调用，唯一证据是随 PR 一起合入的两条单元测试（GroupDispatchShareAdmissionServiceTest：confirm_costBearerChangedWithoutMemberChange_writesCostBearerChangedNotMemberAdded / confirm_membersAddedAndCostBearerChangedTogether_writesBothRows），交接时未重新执行这两条测试（本机当时另有全量测试占用窗口，见 MACHINE-LOCK.md）。正文的请求/响应示例数值沿用 #7444 changelog（19_7444_团期配车就绪门禁与车辆共用关系-修改接口-管理后台.md，尚未推送的草稿）里已经登记的同一套 swagger 声明示例值（shareGroupId=77001 等），不是本次新造的编号，也不是真实网关抓包。待管理者安排测试服部署 + 网关复验后，再把 gateway_status 置 verified 并推送本文件；发布前不许为了过校验改这个状态位。 前端实证翻 not_required(mmg 2026-09-20):share-groups/costBearer/COST_BEARER/MEMBER_ADDED 全仓零命中,共用关系确认历史 UI 未建(#7444 挂起域),前端无 action 映射表可补;配车接入时映射必须含 COST_BEARER_CHANGED、同 operateTime 两条历史不去重、不假设每次确认历史 +1 条,已记入前端待办口径。"
+updated_at: "2026-09-20"
+base: "dev-v3"
+---
+
+# fleet: 共用关系确认历史补记成本承担方变更（工单 #8013）
+
+> **存放目录**: 二期（order-v3 标签工单）→ `changelogs-v2/2026-09/`
+>
+> **服务**: hl-fleet-service（8087）
+> **PR**: #8020 ｜ **Issue**: #8013 ｜ **合并提交**: `adfc5b53b`
+> **日期**: 2026-09-20
+> **影响范围**: 管理后台「团期配车页」共用关系确认历史（`GET .../share-groups?includeReleased=true` 的 `history[]`），以及写口 `POST .../share-groups` 内部的历史写入分流逻辑
+
+---
+
+## ⚠️ 关键变化
+
+`ShareLogAction.COST_BEARER_CHANGED` 这个动作常量自 #7444 落地起就**从未被真正写出过**——车务在团期配车页把某天某辆车的共用关系成本承担方从 `GROUP` 改成 `ORDER`（或反过来），确认历史里记下来的是 `MEMBER_ADDED`，即便成员一个都没变。前端如果按 `action` 做过枚举映射/文案表，**没见过** `COST_BEARER_CHANGED` 这个值——它不是"没出现过"的边界情况，是编译器允许、运行时永远走不到的死分支。本次修复后它会真实出现，前端**必须**补上这一项，否则会显示成空白或 fallback 文案。
+
+同一次修复顺带纠正了一个同构错误：车务对着同一份成员全集、同一个成本承担方原样重新点一次"确认"（例如错过 `@Idempotent(timeout=10)` 的 10 秒防重窗口后手动再点），改前会**误写一条** `MEMBER_ADDED`——车务并没有加任何成员，历史里却凭空多出一条"加了成员"的记录。改后这种真正的空提交**不产生任何新历史行**。
+
+两处都不改变 `POST`/`GET` 两个端点自身的请求/响应字段名、类型或结构；变化只发生在"这次确认写了哪几条历史行、写的是哪个 `action`"这件事上。
+
+---
+
+## 一、背景
+
+`fleet_group_dispatch_share_log.action` 这一列在 `V20260918_003` 建表时就用 CHECK 约束声明了五个合法字面量：`CREATE`/`MEMBER_ADDED`/`MEMBER_REMOVED`/`COST_BEARER_CHANGED`/`RELEASED`。DB 侧一直都能接受 `COST_BEARER_CHANGED`。
+
+问题出在 Java 侧：`GroupDispatchShareAdmissionService#confirmInTransaction` 复用既有关系（幂等覆盖）时，末尾恒定写死一条历史——`created ? CREATE : MEMBER_ADDED`。这个三元表达式里**根本没有 `COST_BEARER_CHANGED` 这个分支**，无论车务这次改的是成员、是成本承担方、还是什么都没改，只要不是新建，写出去的永远是 `MEMBER_ADDED`（或者什么都没变时，同样误写 `MEMBER_ADDED`）。
+
+`upsertGroup` 内部其实早就在做 `costBearer` 的 CAS 更新（`casUpdateCostBearer`），只是这次落库前后的差异从未被读出来、也从未参与历史写入的判定。
+
+| 维度 | 改前 | 改后 |
+|------|------|------|
+| 复用关系时的历史写入判据 | 一个布尔 `created` 决定 `CREATE`/`MEMBER_ADDED` 二选一 | `created`（是否新建）+ 成员是否真的新增 + 成本承担方是否真的变化，三个独立判据，各写各的 0~2 条 |
+| `COST_BEARER_CHANGED` 是否可达 | 否（死代码） | 是（复用关系且成本承担方变化时必写） |
+| 成员全集与成本承担方均未变的重复确认 | 误写 1 条 `MEMBER_ADDED` | 写 0 条 |
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 确认团期车辆共用关系 | POST | `/admin/fleet/group-dispatch/batches/{groupBatchId}/share-groups` | 修改接口 | 请求/响应字段零变化；仅内部历史写入判据修正（本节所述） |
+| 2 | 查询团期车辆共用关系 | GET | `/admin/fleet/group-dispatch/batches/{groupBatchId}/share-groups` | 修改接口 | `history[].action` 新增可观测取值 `COST_BEARER_CHANGED`（此前是死枚举） |
+
+---
+
+## 三、接口详情
+
+### 1. 确认团期车辆共用关系 `POST /admin/fleet/group-dispatch/batches/{groupBatchId}/share-groups`
+
+**VO**: `ShareGroupConfirmReqVO → ShareGroupRespVO`
+
+（本接口的请求/响应字段与 #7444 落地时逐字节一致，未新增/删除/改名任何字段；源码核对：`GroupDispatchShareController.java:53-93`、`ShareGroupConfirmReqVO.java`、`ShareGroupRespVO.java`、`GroupDispatchShareAdmissionService.java:158-241`）
+
+#### 使用场景
+
+车务在团期配车页确认共用关系时调用，行为与 #7444 changelog 描述完全一致。本次改动**不影响本端点自身的响应内容**（`ShareGroupRespVO.history` 在这个端点上恒为空，历史只能通过接口 2 的 `includeReleased=true` 查询回来）——本节存在的意义是让前端理解"点一次确认，后台这次到底往历史表里写了几条、写的是什么"，这决定了随后调用接口 2 时能看到什么。
+
+#### 入参字段表
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long | ✅ | - | 团期主订单 ID（雪花） |
+| serviceDate | Body | LocalDate | ✅ | 必须落在该团基线 `serviceDates[]` 内 | 共用发生的服务日 |
+| resourceType | Body | String | ✅ | `VEHICLE`/`DRIVER` | 资源维度 |
+| resourceId | Body | Long | ✅ | - | 车辆 ID 或司机 ID |
+| members | Body | Array | ✅ | 2～20 个 | 成员**全集**（不是增量） |
+| members[].sourceType | Body | String | ✅ | `ASSIGNMENT`/`GROUP_DISPATCH` | - |
+| members[].sourceId | Body | Long | ✅ | - | 派单 ID 或团级配车行 ID |
+| costBearer | Body | String | ✅ | `GROUP`/`ORDER` | **本次改动的判据来源**：与落库前的旧值比对，不同则本次会多写一条 `COST_BEARER_CHANGED` |
+| costBearerOrderId | Body | Long | 条件必填 | `costBearer=ORDER` 时必填 | - |
+| remark | Body | String | ❌ | ≤200 | 确认备注（也会写进新增的历史行） |
+
+（完整入参约束、错误码见 #7444 changelog 对应小节，本次未改动任何一条校验规则）
+
+#### 出参字段表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| shareGroupId / groupBatchId / serviceDate / resourceType / resourceId / status / costBearer / costBearerOrderId / costSourceRefNo / members[] / confirmedBy / confirmedAt / version | - | 字段名/类型/取值规则均**未变动**，与 #7444 落地时逐字节一致 |
+| history | Array | 本端点恒为 `null`/空数组；**本次改动写了几条历史、写的是什么，在这个响应体里看不到**，必须另调接口 2 |
+
+#### 请求示例
+
+沿用 #7444 changelog 登记的示例数据集（`shareGroupId=77001` 等），仅把 `costBearer` 改成触发 `COST_BEARER_CHANGED` 的取值：该关系此前以 `costBearer=GROUP` 建立，本次原样重新提交同一份成员全集、只把 `costBearer` 改成 `ORDER`：
+
+```json
+{
+  "serviceDate": "2026-09-12",
+  "resourceType": "VEHICLE",
+  "resourceId": 1,
+  "members": [
+    { "sourceType": "GROUP_DISPATCH", "sourceId": 99001 },
+    { "sourceType": "ASSIGNMENT", "sourceId": 88001, "admissionIntent": "OCCUPYING" }
+  ],
+  "costBearer": "ORDER",
+  "costBearerOrderId": 70123,
+  "remark": "车费改由甲户订单承担"
+}
+```
+
+（路径参数 `groupBatchId=8801`）
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "shareGroupId": "77001",
+    "groupBatchId": "8801",
+    "serviceDate": "2026-09-12",
+    "resourceType": "VEHICLE",
+    "resourceId": "1",
+    "status": "ACTIVE",
+    "costBearer": "ORDER",
+    "costBearerOrderId": "70123",
+    "costSourceRefNo": "SHARE-77001",
+    "members": [
+      { "sourceType": "GROUP_DISPATCH", "sourceId": "99001", "requirementId": null, "orderId": null },
+      { "sourceType": "ASSIGNMENT", "sourceId": "88001", "requirementId": "5501", "orderId": "70123" }
+    ],
+    "confirmedBy": "1001",
+    "confirmedAt": "2026-09-12 18:25:10",
+    "version": 2
+  },
+  "success": true
+}
+```
+
+⚠️ 这个响应体本身**看不出**后台这次到底记了几条历史——`history` 字段在这个端点上恒为空。要确认这次调用是否真的多写了一条 `COST_BEARER_CHANGED`，必须紧接着调接口 2（`includeReleased=true`）。
+
+#### 空数据 / 降级响应
+
+本接口是同步写操作，不存在响应体意义上的"空数据"。**但本次改动引入了一种新的"写 0 条历史"的合法情形**：若车务原样重新提交同一份成员全集、且 `costBearer` 也未变（`membersAdded=false && costBearerChanged=false`），本次确认**不产生任何新历史行**——这不是接口故障，是 #8013 修复后的预期行为；改动前这种情况会误写一条 `MEMBER_ADDED`。前端不应假设"每次点确认，历史列表长度必然 +1"。
+
+#### 错误响应
+
+本次改动不引入任何新错误码，错误响应与 #7444 落地时完全一致，例如：
+
+```json
+{
+  "code": 602103,
+  "message": "成员派单不属于本团或团期身份未知: 88099",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- **本次改动不改变鉴权、幂等、校验、事务边界**，与 #7444 changelog 描述的规则完全一致。
+- **判据在落库前取样**：`costBearer` 是否变化，取的是 `casUpdateCostBearer` 执行前读到的旧值与本次入参的比对结果，不是事后反查历史表推断出来的——落库那一瞬间旧快照就没有意义了，判据必须在那之前定下来。
+- **新建关系（`created=true`）分支完全不受影响**：仍然只写 1 条 `CREATE`，不会额外叠加 `COST_BEARER_CHANGED`（新建时这条 `CREATE` 历史本身就带着当次的 `costBearerSnapshot`，没有必要再补一条）。
+- **同一次确认最多产生 2 条新历史**（成员新增 1 条 `MEMBER_ADDED` + 成本承担方变化 1 条 `COST_BEARER_CHANGED`），顺序恒为先 `MEMBER_ADDED` 后 `COST_BEARER_CHANGED`（`operateTime` 相同，前端排序如依赖 `operateTime` 需要一个稳定的次级排序键，比如 `logId` 自增）；**成员被移出**（`MEMBER_REMOVED`）走的是 `syncMembers` 内联的另一条写入路径，与本次改动的判据完全独立，不受影响。
+
+---
+
+### 2. 查询团期车辆共用关系 `GET /admin/fleet/group-dispatch/batches/{groupBatchId}/share-groups`
+
+**VO**: `ShareGroupQueryReqVO → List<ShareGroupRespVO>`
+
+（源码核对：`GroupDispatchShareController.java:100-111`、`GroupDispatchShareService.java:125-144`、`ShareGroupHistoryRespVO.java`）
+
+#### 使用场景
+
+团期配车页 / 核团排障时查看共用关系变更历史，`includeReleased=true` 时返回 `history[]`。本次改动后，这里**首次**可能出现 `action="COST_BEARER_CHANGED"` 的历史行——此前无论后台实际发生了什么，这里永远只会看到 `CREATE`/`MEMBER_ADDED`/`MEMBER_REMOVED`/`RELEASED` 四种。
+
+#### 入参字段表
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long | ✅ | - | 团期主订单 ID |
+| serviceDate | Query | LocalDate | ❌ | 不传=全部服务日 | - |
+| resourceType | Query | String | ❌ | `VEHICLE`/`DRIVER` | 不传=两者都查 |
+| includeReleased | Query | Boolean | ❌ | 默认 false | **必须为 true 才会带 `history[]`**；本次改动只影响 `history[].action` 的取值分布，不影响本参数语义 |
+
+#### 出参字段表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| （数组元素其余字段：shareGroupId / groupBatchId / serviceDate / resourceType / resourceId / status / costBearer / costBearerOrderId / costSourceRefNo / members[] / confirmedBy / confirmedAt / version） | - | **本次未改动** |
+| history[] | Array | 仅 `includeReleased=true` 时非空；**本次改动只影响这个数组里各行 `action` 的取值分布，字段结构本身零变化** |
+| history[].action | String | **本次改动点**：合法取值仍是 `CREATE`/`MEMBER_ADDED`/`MEMBER_REMOVED`/`COST_BEARER_CHANGED`/`RELEASED` 五个（DB CHECK 早已如此），但 `COST_BEARER_CHANGED` 此前从未被真实写出过，本次修复后会真实出现 |
+| history[].memberSnapshot | String | 该次变更后的成员全集快照（JSON 文本）；`COST_BEARER_CHANGED` 这条历史的快照与紧邻的 `MEMBER_ADDED`（如果同次确认也写了的话）逻辑上相同，因为两条历史共用同一次 `selectActiveByGroupForUpdate` 锁定读结果 |
+| history[].costBearerSnapshot | String | 该次变更后的成本承担方；`COST_BEARER_CHANGED` 这条历史上就是本次改到的新值 |
+| history[].operator | String | 操作人 adminId |
+| history[].operateTime | LocalDateTime | 操作时间；同一次确认产生的 `MEMBER_ADDED` 与 `COST_BEARER_CHANGED` 两条历史 `operateTime` 相同（同一个 `now` 变量） |
+| history[].reason | String | 仅 `RELEASED` 动作有值，`COST_BEARER_CHANGED` 恒为 `null` |
+| history[].remark | String | 备注；`COST_BEARER_CHANGED` 这条历史的 `remark` 与同次确认入参的 `remark` 相同（若同次也写了 `MEMBER_ADDED`，两条历史的 `remark` 是同一个值，不是分开填的两段话） |
+
+#### 请求示例
+
+```http
+GET /admin/fleet/group-dispatch/batches/8801/share-groups?includeReleased=true
+```
+
+#### 响应示例
+
+沿用接口 1 示例的后续状态：该关系先以 `costBearer=GROUP` 建立（写 1 条 `CREATE`），随后车务把 `costBearer` 改成 `ORDER`（本次改动生效，写 1 条 `COST_BEARER_CHANGED`）：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": [
+    {
+      "shareGroupId": "77001",
+      "groupBatchId": "8801",
+      "serviceDate": "2026-09-12",
+      "resourceType": "VEHICLE",
+      "resourceId": "1",
+      "status": "ACTIVE",
+      "costBearer": "ORDER",
+      "costBearerOrderId": "70123",
+      "costSourceRefNo": "SHARE-77001",
+      "members": [
+        { "sourceType": "GROUP_DISPATCH", "sourceId": "99001", "requirementId": null, "orderId": null },
+        { "sourceType": "ASSIGNMENT", "sourceId": "88001", "requirementId": "5501", "orderId": "70123" }
+      ],
+      "confirmedBy": "1001",
+      "confirmedAt": "2026-09-12 18:25:10",
+      "version": 2,
+      "history": [
+        {
+          "action": "CREATE",
+          "memberSnapshot": "[{\"sourceType\":\"GROUP_DISPATCH\",\"sourceId\":\"99001\",\"requirementId\":null,\"orderId\":null},{\"sourceType\":\"ASSIGNMENT\",\"sourceId\":\"88001\",\"requirementId\":\"5501\",\"orderId\":\"70123\"}]",
+          "costBearerSnapshot": "GROUP",
+          "operator": "1001",
+          "operateTime": "2026-09-12 18:20:33",
+          "reason": null,
+          "remark": "团车上午行程后接甲户"
+        },
+        {
+          "action": "COST_BEARER_CHANGED",
+          "memberSnapshot": "[{\"sourceType\":\"GROUP_DISPATCH\",\"sourceId\":\"99001\",\"requirementId\":null,\"orderId\":null},{\"sourceType\":\"ASSIGNMENT\",\"sourceId\":\"88001\",\"requirementId\":\"5501\",\"orderId\":\"70123\"}]",
+          "costBearerSnapshot": "ORDER",
+          "operator": "1001",
+          "operateTime": "2026-09-12 18:25:10",
+          "reason": null,
+          "remark": "车费改由甲户订单承担"
+        }
+      ]
+    }
+  ],
+  "success": true
+}
+```
+
+⚠️ **本响应体的数值构造来自 #7444 changelog 登记的同一套 swagger 声明示例 + 本次源码新增的判据逻辑推算，不是真实网关抓包**（`gateway_status=pending`，见 frontmatter `status_note`）。结构与字段名已逐一对源码核实（`ShareGroupHistoryRespVO.java`），但具体数值请在网关复验后以实测为准。
+
+#### 空数据 / 降级响应
+
+本团在筛选条件下没有任何共用关系时返回空数组 `[]`；`includeReleased=false`（默认）时 `history` 字段不返回。本次改动不影响这两种既有的空态。
+
+#### 错误响应
+
+```json
+{
+  "code": 100001,
+  "message": "参数非法: 资源维度非法: TRAIN",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- **鉴权**：路径级角色门禁 `X-Admin-Role` 须为 `VEHICLE_MANAGER`/`SUPER_ADMIN`，本次未改动（详见 #7444 changelog）。
+- **前端枚举映射表必须补 `COST_BEARER_CHANGED`**：此前的响应里从未出现过这个值，前端若对 `action` 做过 `switch`/映射表且没有兜底分支，会渲染成空白/`undefined`，而不是报错——这类问题不会在联调时报红，只会在页面上悄悄显示不对。
+- **`memberSnapshot` 仍是全集不是增量**，本次改动不影响这条既有约定。
+- **`COST_BEARER_CHANGED` 与紧邻的 `MEMBER_ADDED`（如果同次确认也命中的话）`operateTime` 相同**，前端如果用 `operateTime` 做排序/分组去重，需要注意这两条历史是同一次操作产生的两个独立事实，不能因为时间戳相同就当成重复记录去重掉。
+- 查询接口本身不加锁、不开事务，读到的是调用时刻的库状态。
+
+---
+
+## 四、契约约束与正确调用方式
+
+> 本节只写后端接受/拒绝 payload 的规则与历史写入判据，不写 UI 渲染建议。
+
+### `COST_BEARER_CHANGED` 的触发条件是「落库前旧值 ≠ 本次入参新值」
+
+这是纯粹的服务端判据，前端**不需要、也不应该**自己在客户端比对新旧 `costBearer` 来猜这次会不会有 `COST_BEARER_CHANGED` 历史——判据用的是数据库锁定读到的旧快照，前端本地缓存的旧值可能已经过期（比如同一团被另一个车务并发改过）。
+
+### 判断"这次确认到底写了几条历史"，只能靠事后查询，不能靠 POST 响应体推断
+
+`POST .../share-groups` 的响应体里没有任何字段能告诉调用方"这次写了 1 条还是 2 条历史、写的是什么 action"。前端如果需要在确认成功后立刻展示"本次变更记录"，必须紧接着调 `GET .../share-groups?includeReleased=true`，按 `operateTime`（+ 稳定次级排序键）取最新的 1~2 条。
+
+### ✅ 正确 / ❌ 错误 理解对照
+
+| 场景 | 后台实际写入 | 前端不应假设的事 |
+|---|---|---|
+| ✅ 新建关系 | 1 条 `CREATE` | 不会额外出现 `COST_BEARER_CHANGED` |
+| ✅ 复用关系，只改 `costBearer`，成员全集不变 | 1 条 `COST_BEARER_CHANGED` | 不会出现 `MEMBER_ADDED` |
+| ✅ 复用关系，成员与 `costBearer` 都变了 | 2 条：`MEMBER_ADDED` + `COST_BEARER_CHANGED` | 两条 `operateTime` 相同，不是两次独立操作 |
+| ✅ 复用关系，成员与 `costBearer` 都没变（原样重提） | **0 条** | ❌ 不要假设"点一次确认历史必然 +1 条"——改前的旧行为才是这样，且是 #8013 要修的缺陷 |
+| ❌ 前端自行比对 `costBearer` 新旧值来预测本次是否有 `COST_BEARER_CHANGED` | 无意义 | 判据在服务端落库前的锁定读上，前端本地状态可能已过期 |
+
+---
+
+## 五、数据库行为
+
+写接口 `POST .../share-groups` 落库表 `fleet_group_dispatch_share_log`（`V20260918_003` 建表，INSERT-only 留痕表，一行 = 关系的一次变更）。
+
+**本次改动不新增任何列、不新增任何表、不改 `chk_share_log_action` 约束**——约束自建表起就允许 `COST_BEARER_CHANGED` 这个字面量，缺陷完全在 Java 应用层（三元表达式漏了这个分支），DB 侧从一开始就是就绪的。
+
+| 场景 | 改前写入行数 | 改后写入行数 |
+|---|---|---|
+| 新建关系 | 1（`CREATE`） | 1（`CREATE`，不变） |
+| 复用关系，仅成员变化 | 1（`MEMBER_ADDED`） | 1（`MEMBER_ADDED`，不变） |
+| 复用关系，仅 `costBearer` 变化 | 1（**误写** `MEMBER_ADDED`） | 1（`COST_BEARER_CHANGED`） |
+| 复用关系，成员与 `costBearer` 都变化 | 1（`MEMBER_ADDED`，`costBearer` 变化未留痕） | 2（`MEMBER_ADDED` + `COST_BEARER_CHANGED`） |
+| 复用关系，两者都未变化（原样重提） | 1（**误写** `MEMBER_ADDED`） | 0（不写） |
+| 成员被移出 | 1（`MEMBER_REMOVED`，`syncMembers` 内联写，独立路径） | 1（不变，本次未触碰这条路径） |
+
+---
+
+## 六、边界行为
+
+- 未登录/网关未透传角色 → 401（网关拦截），与既有行为一致
+- `resourceType` 非法枚举值 → `100001`（沿用既有，见 #7444 changelog 更正记录）
+- 成员数越界、服务日窗外、并发修改等既有错误码全部未变（602100~602112 段）
+- 老数据兼容：本次改动前落库的历史行（`action` 只可能是 `CREATE`/`MEMBER_ADDED`/`MEMBER_REMOVED`/`RELEASED` 四种之一）原样保留，查询时按原值返回，不会被"回填"或"重新计算"成 `COST_BEARER_CHANGED`——本次修复只影响**新产生**的历史行，不改写存量数据
+- `appendConfirmChangeLog` 全程在 `confirmInTransaction` 的同一个事务内执行，与关系落库、成员同步、派单关联、占用准入共享同一次提交/回滚，不会出现"关系已改但历史没写"或"历史写了但关系没改"的中间态
+
+---
+
+## 六.5、枚举 / 数据字典
+
+### `action`（`ShareGroupHistoryRespVO.action`，源码 `ShareLogAction` 常量类 / DB `chk_share_log_action`）
+
+**所属字段**: `history[].action` | **类型**: `String`
+
+| 值 | 说明 | 本次改动前是否可能在响应中出现 |
+|----|------|------|
+| `CREATE` | 首次建立关系 | 是 |
+| `MEMBER_ADDED` | 幂等覆盖时成员净增；改动前该分支同时错误吸收了"仅改成本承担方"与"什么都没改"两种场景 | 是（含误写） |
+| `MEMBER_REMOVED` | 幂等覆盖或自动收缩时成员净减 | 是 |
+| `COST_BEARER_CHANGED` | 成本承担方变更 | **否——本次改动前是死枚举，代码路径永远走不到** |
+| `RELEASED` | 关系解除（四条解除路径共用） | 是 |
+
+⚠️ 该枚举早在 `V20260918_003`（2026-09-18）建表时就在 DB CHECK 约束里声明了全部五个值，`COST_BEARER_CHANGED` 不是本次新加的枚举字面量，而是本次才让它第一次真正可达。
+
+---
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 |
+|------|------|------|
+| `history[].action` 合法取值集合 | 声明上五个值都合法，但实际只会出现 `CREATE`/`MEMBER_ADDED`/`MEMBER_REMOVED`/`RELEASED` 四种 | 全部五个值均可能真实出现 |
+| `POST`/`GET` 两端点的请求/响应字段名、类型、结构 | - | **零变化** |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| 复用关系，仅改 `costBearer` | 误写 1 条 `MEMBER_ADDED`（无法从历史看出改的是成本承担方） | 正确写 1 条 `COST_BEARER_CHANGED` |
+| 复用关系，成员与 `costBearer` 都改 | 只写 1 条 `MEMBER_ADDED`（`costBearer` 变化完全未留痕） | 写 2 条：`MEMBER_ADDED` + `COST_BEARER_CHANGED`，两件事都可追溯 |
+| 复用关系，成员与 `costBearer` 都未改（原样重提） | 误写 1 条 `MEMBER_ADDED`（凭空多一条"加了成员"的假记录） | 写 0 条 |
+| 新建关系 | 写 1 条 `CREATE` | 不变 |
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 否——两个端点的请求/响应字段名、类型、结构均未变动；变化只发生在 `history[].action` 的取值分布上（新增可观测取值，不是改变既有取值的含义）
+- **前端是否必须同步上线**: 是——如果前端对 `action` 做了枚举映射/文案表且没有安全的 `default` 兜底，`COST_BEARER_CHANGED` 首次出现时会展示为空白或 `undefined`，需要补上这一项映射
+- **前端 workaround 清理点**: 若前端此前发现"改成本承担方后历史列表多了一条奇怪的『新增成员』记录"并做过任何遮蔽/过滤逻辑（比如按 `remark` 内容猜测过滤掉这类"假 MEMBER_ADDED"），本次修复后这类 workaround 应当撤除——改后不会再产生这种假记录
+
+---
+
+## 七、不影响范围
+
+- **仅影响**: 共用关系确认历史的写入判据（`POST .../share-groups` 内部）与查询回显（`GET .../share-groups?includeReleased=true` 的 `history[].action`）
+- **零影响**:
+  - 两个端点的请求体、响应体字段名/类型/结构**零变更**
+  - 新建关系（`CREATE`）分支完全不受影响
+  - 解除关系（`RELEASED`，`DELETE .../share-groups/{shareGroupId}`）分支完全不受影响，本次未改动该端点任何代码
+  - 成员被移出（`MEMBER_REMOVED`）分支完全不受影响，走的是独立的内联写入路径
+  - 准入三步流程（授权 → 派单关联 → 占用准入）与占用账本行为**完全不受影响**，本次只动了流程末尾的历史写入分流
+  - 无新增 DB 表/列/索引/约束；`chk_share_log_action` 约束原样不变（自 `V20260918_003` 起就允许 `COST_BEARER_CHANGED`）
+  - 团期配车其余端点（就绪判定、派单预校验/候选、reconfigure 等）零影响
+
+---
+
+## 八、测试环境已验证
+
+⚠️ **本篇尚无测试服/网关读数**（`gateway_status=pending`），以下只是**单元测试**层面的证据，不是测试环境实测——按管理者要求如实标注，不把单测读数伪装成测试环境验证：
+
+随 PR #8020 一并合入的两条新增单测（`GroupDispatchShareAdmissionServiceTest`，Mockito，未重跑，仅列出用例名与断言意图供核实）：
+
+```
+confirm_costBearerChangedWithoutMemberChange_writesCostBearerChangedNotMemberAdded
+  → 只改 costBearer、成员不变：断言 append(COST_BEARER_CHANGED) 被调用一次，
+     且 append(MEMBER_ADDED) 从未被调用（verify(..., never())）
+
+confirm_membersAddedAndCostBearerChangedTogether_writesBothRows
+  → 成员与 costBearer 同次都变：断言 append(MEMBER_ADDED) 与 append(COST_BEARER_CHANGED)
+     均被调用一次
+```
+
+**待办**：管理者安排 hl-fleet-service 部署测试服后，需补一次真实网关调用（POST 确认 + GET 查询 `includeReleased=true`），核实 `history[].action="COST_BEARER_CHANGED"` 真实落库并可读出，再把 `gateway_status` 置 `verified` 并推送本文件。
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#8013](https://git.1814.love:8443/wx/HL/issues/8013)
+- 关联 PR: [wx/HL#8020](https://git.1814.love:8443/wx/HL/pulls/8020)（squash 合并至 dev-v3 @`adfc5b53b`）
+- 共用关系机制本身（confirm/query/release 三端点完整契约）见 #7444 changelog：`changelogs-v2/2026-09/19_7444_团期配车就绪门禁与车辆共用关系-修改接口-管理后台.md`（尚未推送的草稿，仅供内部核对参考，不作为已发布依据）
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8013](https://git.1814.love:8443/wx/HL/issues/8013)
+- **PR**: [#8020](https://git.1814.love:8443/wx/HL/pulls/8020)
+- **Merge commit**: [adfc5b53b](https://git.1814.love:8443/wx/HL/commit/adfc5b53b1aea08529eeb41459a692c7f8a9ed7a)
+
+### 联系人
+
+- **后端负责人**: wx(GIT)
+- **前端负责人**: mmg
@@ -7,12 +7,12 @@ author: "jw(GIT)"
 change_type: "修改接口"
 backend_status: "deployed"
 gateway_status: "verified"
-frontend_status: "not_required"
+frontend_status: "verified"
 frontend_owner: "mmg"
-frontend_ref: ""
+frontend_ref: "9a14ad866b3ef6ac9acb0ca9ab9e9f0fe98f6559"
 target_release: ""
 verified_at: "2026-09-20"
-status_note: "后端已合并 dev-v3（df66ec357）并部署 TEST，网关实测 AC-1~AC-8 全通过。一处口径放宽 + 一个纯新增出参 + 一处写侧副作用。口径：全团需求汇总 GET /v3/admin/order/group-batch/{groupBatchId}/requirement-summary 的 dailyRoomBreakdown 与整体确认预检 GET .../requirement/confirm-check，此前都只认订单上的 needs_hotel 标记位，导致「标记说不需要住宿、定制师却已提交完整需求」的户被整户静默丢弃——间数不进汇总（页面用房表空白）、确认时也不放行给房务（需求填了没人配房）；现在计入条件改为「标记为真 或 已提交有效需求」，打回态仍不计。新增出参 hotelFlagMismatchOrderCount 把这种不一致显式暴露。写侧：PUT /v3/admin/order/{id}/hotel-requirement 提交成功后，若该单 needs_hotel 不为真则就地置 1（单向 0→1，同事务，已为真时不写）——该标记原先只在创单时按产品有没有配酒店派生一次、之后全仓无写通道，存量错单改不回来。既有字段一个没删没改，入参与路径不变。 前端实证维持 not_required(mmg 2026-09-20):requirement-summary/dailyRoomBreakdown/hotelNeededOrderCount/hotelFlagMismatchOrderCount 全仓零命中(汇总端点未接入,同 #7925/#7937 结论);confirm-check 已消费(orderV2GroupBatch.js)但出参结构不变,ready/missing 直渲自动受益;hotel-requirement 标记纠正为服务端同事务副作用、响应不变,零感知。"
+status_note: "后端已合并 dev-v3（df66ec357）并部署 TEST，网关实测 AC-1~AC-8 全通过。一处口径放宽 + 一个纯新增出参 + 一处写侧副作用。口径：全团需求汇总 GET /v3/admin/order/group-batch/{groupBatchId}/requirement-summary 的 dailyRoomBreakdown 与整体确认预检 GET .../requirement/confirm-check，此前都只认订单上的 needs_hotel 标记位，导致「标记说不需要住宿、定制师却已提交完整需求」的户被整户静默丢弃——间数不进汇总（页面用房表空白）、确认时也不放行给房务（需求填了没人配房）；现在计入条件改为「标记为真 或 已提交有效需求」，打回态仍不计。新增出参 hotelFlagMismatchOrderCount 把这种不一致显式暴露。写侧：PUT /v3/admin/order/{id}/hotel-requirement 提交成功后，若该单 needs_hotel 不为真则就地置 1（单向 0→1，同事务，已为真时不写）——该标记原先只在创单时按产品有没有配酒店派生一次、之后全仓无写通道，存量错单改不回来。既有字段一个没删没改，入参与路径不变。 前端实证维持 not_required(mmg 2026-09-20):requirement-summary/dailyRoomBreakdown/hotelNeededOrderCount/hotelFlagMismatchOrderCount 全仓零命中(汇总端点未接入,同 #7925/#7937 结论);confirm-check 已消费(orderV2GroupBatch.js)但出参结构不变,ready/missing 直渲自动受益;hotel-requirement 标记纠正为服务端同事务副作用、响应不变,零感知。 2026-09-20 前端接入(mmg):「用房 · 汇总」建页随 hl-admin v2.1 交付——requirement-summary 经 getGroupRequirementSummary 接入「查看需求」页 RoomSummarySection:户数条(在团/需订房/已提交)+不一致只提示不扣减+Day N|酒店|房型|所需间数扁平表;stayDate null 按 Day N、hotelName null 显「未知酒店」不隐藏行、roomCategoryName null 回落编码、全天合计直读 rooms[] 禁跨酒店累加、hotelId null 组间数不丢;整团确认/按户打回后自动重拉。定向 Vitest 17/17,checkpoint 全绿。"
 updated_at: "2026-09-20"
 base: "dev-v3"
 ---
@@ -7,12 +7,12 @@ author: "jw(GIT)"
 change_type: "修改接口"
 backend_status: "deployed"
 gateway_status: "not_required"
-frontend_status: "not_required"
+frontend_status: "verified"
 frontend_owner: "mmg"
-frontend_ref: ""
+frontend_ref: "9a14ad866b3ef6ac9acb0ca9ab9e9f0fe98f6559"
 target_release: ""
 verified_at: "2026-09-20"
-status_note: "全团需求汇总 GET /v3/admin/order/group-batch/{groupBatchId}/requirement-summary 的 dailyRoomBreakdown 纯增两项：stayDate（该晚住宿日期 = 团期出发日 + dayNumber - 1，团期无出发日时为 null）与 hotels[]（该晚按酒店分组的用房，含 hotelId / hotelName / totalRoomCount / rooms[]）。原有 rooms[]（不分酒店的全天合计）与其余字段一个没动。这样团期「查看需求」页的「用房 · 汇总」表（Day N | 酒店 | 房型 | 所需间数）一个接口就能画完，不必逐户调订单调整快照去拼酒店，也不必等房务建完订房计划——后者在成团前根本没有数据。口径：与 rooms 同一次遍历的两个视角，任一天 Σhotels[].totalRoomCount == Σrooms[].totalRoomCount；每段只取首方案候选（候选是房控择一，累加全部会翻倍）；取不到酒店的段归 hotelId=null 一条且恒排末位，间数不丢；酒店名优先取需求里落库的快照，缺失的按 ID 一次批量补，资源服务不可用时名称为 null、间数照常。 前端实证维持 not_required(mmg 2026-09-20):requirement-summary/dailyRoomBreakdown/stayDate(本端点义)/hotels 全仓零命中(同 #7925/#7937/#8023 第四次实证,汇总端点未接入);「用房·汇总」表属新功能排期,届时 stayDate null 按 Day N 展示、hotelName null 显「未知酒店」不隐藏行、全天合计直读 rooms[] 不跨酒店累加、hotelId 字符串。"
+status_note: "全团需求汇总 GET /v3/admin/order/group-batch/{groupBatchId}/requirement-summary 的 dailyRoomBreakdown 纯增两项：stayDate（该晚住宿日期 = 团期出发日 + dayNumber - 1，团期无出发日时为 null）与 hotels[]（该晚按酒店分组的用房，含 hotelId / hotelName / totalRoomCount / rooms[]）。原有 rooms[]（不分酒店的全天合计）与其余字段一个没动。这样团期「查看需求」页的「用房 · 汇总」表（Day N | 酒店 | 房型 | 所需间数）一个接口就能画完，不必逐户调订单调整快照去拼酒店，也不必等房务建完订房计划——后者在成团前根本没有数据。口径：与 rooms 同一次遍历的两个视角，任一天 Σhotels[].totalRoomCount == Σrooms[].totalRoomCount；每段只取首方案候选（候选是房控择一，累加全部会翻倍）；取不到酒店的段归 hotelId=null 一条且恒排末位，间数不丢；酒店名优先取需求里落库的快照，缺失的按 ID 一次批量补，资源服务不可用时名称为 null、间数照常。 前端实证维持 not_required(mmg 2026-09-20):requirement-summary/dailyRoomBreakdown/stayDate(本端点义)/hotels 全仓零命中(同 #7925/#7937/#8023 第四次实证,汇总端点未接入);「用房·汇总」表属新功能排期,届时 stayDate null 按 Day N 展示、hotelName null 显「未知酒店」不隐藏行、全天合计直读 rooms[] 不跨酒店累加、hotelId 字符串。 2026-09-20 前端接入(mmg):「用房 · 汇总」建页随 hl-admin v2.1 交付——requirement-summary 经 getGroupRequirementSummary 接入「查看需求」页 RoomSummarySection:户数条(在团/需订房/已提交)+不一致只提示不扣减+Day N|酒店|房型|所需间数扁平表;stayDate null 按 Day N、hotelName null 显「未知酒店」不隐藏行、roomCategoryName null 回落编码、全天合计直读 rooms[] 禁跨酒店累加、hotelId null 组间数不丢;整团确认/按户打回后自动重拉。定向 Vitest 17/17,checkpoint 全绿。 2026-09-20 后端回填订正(mmg 复核):降级错误码 589574→589596(589574 是 #7932 保留位冲突),该码只在服务端降级日志产生、从不传播前端,前端零影响;TEST AC-1~11 回填全✓。frontmatter 维持 verified 不动。"
 updated_at: "2026-09-20"
 base: "dev-v3"
 ---
@@ -150,7 +150,7 @@ Authorization: Bearer <token>
 | 589500 | 团期不存在（本次不变） |
 | 401 | 未登录（网关拦截） |

-本次新增内部错误码 589574（资源服务住宿名称补全降级），**只在服务端降级日志里出现，不会传播给前端**。
+本次新增内部错误码 **589596**（资源服务住宿名称补全降级），**只在服务端降级日志里出现，不会传播给前端**。（初版误取 589574，该号是 #7932 的保留位，已于 2026-09-20 随 #8046 订正为 589596。）

 #### 业务边界

@@ -222,10 +222,28 @@ Authorization: Bearer <token>

 ## 八、测试环境已验证

+TEST 环境（`hl-order-service-v3`，dev-v3，2026-09-20），团期 `jw测试1期`（`2101506167098511362`，出发 2026-09-27，6 晚）。
+
 ```
-待部署 TEST 后回填实测结果（工单 #8030 AC-1~AC-11）
+AC-1  单户 6 晚逐晚不同酒店，hotels[] 与 hotelName 正确                   ✓
+AC-2  同天多户不同酒店 → 出多条并按间数降序；同一酒店合并且间数相加        ✓
+AC-3  间数不变量 Σhotels == Σrooms：单测 + TEST 六天逐日实测              ✓
+AC-4  stayDate = 出发日 + dayNumber − 1，跨月 09-30 → 10-01 正确          ✓
+AC-5  字符串形态 hotelId 的存量 days JSON 正确解析（TEST 数据本就是字符串）✓
+AC-6  候选缺失 / hotelId 为空 → 归「未指定」一条恒排末位，间数不丢         ✓
+AC-7  酒店名：快照优先；快照置空后按 ID 批量补，实测补出正确名称           ✓
+AC-8  既有字段零变化：三个户数 / rooms[] / vehicleSeatSummary /
+        orderSpecialTags 与改前逐字一致                                   ✓
+AC-9  客户自订晚仍不计入（该日由 3 间降为 2 间）                           ✓
+AC-10 判权：低权限角色 1002/user → 589507；超管 200                        ✓
+AC-11 changelog 按「修改接口」推送（提交 af00e6f）                         ✓
 ```

+订正（2026-09-20，#8046 回归发现）：本单新增的降级错误码原取 589574，该号被 #7932
+登记为保留位且有测试断言它必须空闲，#8030 当轮回归范围未覆盖该测试类故漏网。
+现已改为 **589596**（见下方「五、错误码」与 PR [#8055](https://git.1814.love:8443/wx/HL/pulls/8055) 第一个提交）。
+该码只在服务端降级路径产生，从不传播给前端，对前端无影响。
+
 ---

 ## 十、相关文档
@@ -0,0 +1,414 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8046"
+title: "团期用房新增子订单订房记录接口"
+consumer: "admin"
+author: "jw(GIT)"
+change_type: "新增接口"
+backend_status: "deployed"
+gateway_status: "not_required"
+frontend_status: "verified"
+frontend_owner: "mmg"
+frontend_ref: "3362a94e2425456276c4906e6ee991716146cdf8"
+target_release: ""
+verified_at: "2026-09-21"
+status_note: "团期「查看需求 · 用房」板块是上下两块，此前只有上块（汇总）有接口。本次新增下块：GET /v3/admin/order/group-batch/{groupBatchId}/requirement/hotel-households，一次返回该团期下所有需订房子订单的逐晚填报明细——每户一张卡（团号 / 联系人 / 人数 / 定制师 / 需求状态 / 配房需求 / 特殊需求标签 / 打回原因）+ 逐晚（住宿日期 / 酒店 / 城市 + 区县 / 房型 / 间数；页面地点那列请用 district 而非 city）。此前这块数据只能逐户调 GET /v3/admin/order/{orderId}/itinerary，N 户 N 次。两块的数字关系是硬约束：汇总就是把子订单记录汇总出来的，requirement-summary 的逐日间数 == 本接口里 countedInSummary=true 那些户的逐日加总，一间不差；判据与逐晚间数都与汇总走同一份单源（RequirementStatus.isSummaryCounted 与 HotelRequirementDaysNormalizer），由单测守护。但本列表比汇总宽：被打回正在改的户也会列出来并标 countedInSummary=false（否则管理员一打回，那户就从页面消失，没法跟进谁还没改回来），前端应灰显并标注「打回中 · 未计入汇总」。客户自订晚同理——汇总整晚跳过，本接口仍列出该晚并置 customerSelfBooked=true、hotels 为空数组，避免卡片上「第 N 晚凭空消失」。requirement-summary 一字未改。 前端实证维持 pending(mmg 2026-09-20):真实前端特性(「查看需求·用房」下半块,与已交付的上半块汇总 RoomSummarySection 同页并列),changelog 自标前端可延后接入;接入要点已确认:地点列用 district、打回户灰显「打回中·未计入汇总」、自订晚列出 hotels=[]、未提交户 status=null days=[] 照常列出;本期不派发,记入前端待审清单待排期。前端 2026-09-21 已交付:新增 RoomHouseholdsSection 与 RoomSummarySection 同页并列(RequirementTab),每户一卡(团号/联系人/人数/定制师未指派兜底/statusName 或「未提交」+特殊标签+配房需求)+逐晚扁平表;打回户按 status 原码 REJECTED_* 前缀判定灰显+「打回中 · 未计入汇总」标注+打回原因 alert;未提交户(status=null、days=[])照常列出催办;客户自订晚单行「客户自订」;地点列用 district 不用 city;roomTypeName null 依次回落 roomCategoryName/roomCategory;stats 条显「共 N 户 · 计入汇总 M 户 · K 户未计入(打回或未提交)」;整团确认/按户打回后与汇总同步 reload。定向 spec 8 例+RequirementTab 10 例全过。"
+updated_at: "2026-09-20"
+base: "dev-v3"
+---
+
+# order-v3: 团期用房新增子订单订房记录接口
+
+> **服务**: hl-order-service-v3 (端口 8086)
+> **PR**: [#8055](https://git.1814.love:8443/wx/HL/pulls/8055)（主体）、[#8057](https://git.1814.love:8443/wx/HL/pulls/8057)（补 district）、[#8059](https://git.1814.love:8443/wx/HL/pulls/8059)（打回户改看最新版本行）、[#8060](https://git.1814.love:8443/wx/HL/pulls/8060)（AC-11 固化）
+> **Issue**: [#8046](https://git.1814.love:8443/wx/HL/issues/8046)
+> **日期**: 2026-09-20
+> **影响范围**: 管理后台「团期订单 → 查看需求」页的「用房」板块下半部分（子订单订房记录）
+
+---
+
+## ⚠️ 关键变化
+
+- **纯新增一个只读端点**，既有接口一个没动（`requirement-summary` 逐字未改）。
+- **汇总 == Σ子订单**：`requirement-summary` 的逐日间数严格等于本接口里 `countedInSummary=true` 那些户的逐日加总。两处走同一份状态判据与同一个 days 归一器，不是各算各的。
+- **本列表比汇总宽**：被打回正在改的户也列出来，标 `countedInSummary=false`。前端要灰显并标注「打回中 · 未计入汇总」，否则用户会觉得两块数字对不上。
+- **客户自订晚保留**：汇总整晚跳过，本接口列出该晚并标记，`hotels` 为空数组。
+- **地域是反查来的**：days JSON 里不存 city/district，按 hotelId 批量查资源库得到；取不到为 `null`，不影响间数。**页面地点那一列用 `district` 而不是 `city`**（见出参表说明）。
+
+---
+
+## 一、背景
+
+原型「用房」板块是上下两块：
+
+| 块 | 内容 | 改前 |
+|---|---|---|
+| 上：汇总 | Day N \| 酒店 \| 房型 \| 所需间数 | ✅ `requirement-summary`（#8030 已交付） |
+| 下：子订单订房记录 | 每户一张卡 + 逐晚（第N晚 / 日期 / 城市·酒店 / 间数 / 房型）+ 配房需求 + 打回 | ❌ **无接口** |
+
+下块此前只能逐户调 `GET /v3/admin/order/{orderId}/itinerary`，N 户就是 N 次请求。
+
+最接近的现有端点 `GET /v3/admin/house/group-batches/{groupBatchId}/room-requirements` 三处对不上：结构是 day-major（第N晚 → 各户）而原型要 order-major（每户 → 逐晚）；每户每晚只有 `roomCategory` + `roomCount`，**酒店在上游归一的「段视图」那步就被丢掉了**；另缺定制师姓名、真实房型名、需求级配房备注。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 团期子订单订房记录 | GET | `/v3/admin/order/group-batch/{groupBatchId}/requirement/hotel-households` | 新增 | 一次返回该团期下所有需订房子订单的逐晚填报明细 |
+
+---
+
+## 三、接口详情
+
+### 1. 团期子订单订房记录 `GET /v3/admin/order/group-batch/{groupBatchId}/requirement/hotel-households`
+
+**VO**: `Result<GroupHotelHouseholdsRespVO>`
+
+#### 使用场景
+
+团期详情「查看需求」页「用房」板块的下半部分：逐户展示定制师填报了什么，团期管理员据此审核或打回。与上半部分的汇总表并列展示，两者各调各的接口。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long | ✅ | 团期 ID | 团期不存在返回 589500 |
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| groupBatchId | String | 团期 ID（字符串序列化防 JS 精度丢失） |
+| departDate | String(yyyy-MM-dd) | 团期出发日；未定时为 `null`，此时各晚 `stayDate` 也全为 `null` |
+| householdCount | Integer | 本列表户数（= 需订房户数，与汇总的 `hotelNeededOrderCount` 同口径） |
+| countedHouseholdCount | Integer | 其中计入汇总间数的户数；小于 `householdCount` 时，差值就是正被打回的户 |
+| households[] | List | 子订单订房记录，按 `orderNo` 升序 |
+| households[].orderId | String | 子订单 ID |
+| households[].orderNo | String | 子订单团号 |
+| households[].customerName | String | 主联系人姓名 |
+| households[].participantCount | Integer | 出行人数（成人+儿童+小童+婴儿，走订单域单源公式） |
+| households[].consultantId | String | 定制师 ID；未指派为 `null` |
+| households[].consultantName | String | 定制师姓名；未指派为 `null` |
+| households[].status | String | 需求状态码（`PENDING_REVIEW` / `PENDING` / `PROCESSING` / `DONE` / `REJECTED_TO_CONSULTANT` / `REJECTED_TO_ADMIN`）；该户尚未提交需求时为 `null` |
+| households[].statusName | String | 状态中文名；状态为空或未知值时为 `null` |
+| households[].countedInSummary | Boolean | **该户是否计入了汇总间数**。四个计入态为 `true`，两个打回态为 `false`，未提交需求为 `false` |
+| households[].remark | String | 配房需求自由文本（如「希望安排有窗房间」）；未填为 `null` |
+| households[].specialTags | List\<String\> | 特殊需求标签（`house_special_demand` 字典，如 连通房 / 同层相邻）；未填为 `[]` |
+| households[].returnRemark | String | 打回原因；未被打回过为 `null` |
+| households[].returnedAt | String(yyyy-MM-dd HH:mm:ss) | 打回时间；未被打回过为 `null` |
+| households[].days[] | List | 逐晚明细，按 `dayNumber` 升序；未提交需求时为 `[]` |
+| households[].days[].dayNumber | Integer | 第几晚（从 1 起） |
+| households[].days[].stayDate | String(yyyy-MM-dd) | 住宿日期 = 出发日 + dayNumber − 1；团期无出发日为 `null` |
+| households[].days[].customerSelfBooked | Boolean | 该晚是否客户自订。为 `true` 时 `hotels` 为空数组且不计入汇总间数，**但该晚仍会列出** |
+| households[].days[].hotels[] | List | 该晚的住宿（一般 1 家；「分住」时多家；自订晚为 `[]`） |
+| households[].days[].hotels[].hotelId | String | 酒店 ID；该段没有候选或未填酒店时为 `null`（间数照常不丢） |
+| households[].days[].hotels[].hotelName | String | 酒店名：优先取需求里落库的快照，快照缺的按 ID 批量补；资源服务不可用时为 `null` |
+| households[].days[].hotels[].city | String | 酒店所在**地级市**中文名（如「呼伦贝尔市」），按 hotelId 反查资源库；未维护或资源服务不可用时为 `null` |
+| households[].days[].hotels[].district | String | 酒店所在**区县**中文名（如「海拉尔区」「额尔古纳市」）。**页面上「海拉尔 · 海堂酒店」这一列请用本字段**，不要用 `city`——TEST 实测全库酒店的 `city` 几乎清一色「呼伦贝尔市」（额尔古纳 14 家、海拉尔 7 家、满洲里 6 家全在同一个 city 下），拿它渲染同一团期每晚都显示同一个地级市，区分不出地点 |
+| households[].days[].hotels[].totalRoomCount | Integer | 该晚该酒店合计间数 |
+| households[].days[].hotels[].rooms[] | List | 该晚该酒店的房型行（定制师填的原貌，不做合并） |
+| households[].days[].hotels[].rooms[].roomTypeId | String | 房型 ID；未填为 `null` |
+| households[].days[].hotels[].rooms[].roomTypeName | String | 房型名称，定制师填的真实房型；未填为 `null` |
+| households[].days[].hotels[].rooms[].roomCategory | String | 房型大类编码（`room_category` 字典）；缺失时为「未知」 |
+| households[].days[].hotels[].rooms[].roomCategoryName | String | 房型大类中文名；字典无此编码或不可用时为 `null` |
+| households[].days[].hotels[].rooms[].roomCount | Integer | 间数 |
+
+#### 请求示例
+
+```http
+GET /v3/admin/order/group-batch/2101506167098511362/requirement/hotel-households
+Authorization: Bearer <token>
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "groupBatchId": "2101506167098511362",
+    "departDate": "2026-09-27",
+    "householdCount": 2,
+    "countedHouseholdCount": 2,
+    "households": [
+      {
+        "orderId": "2101506167043985410",
+        "orderNo": "HL20260920105808925",
+        "customerName": "张三",
+        "participantCount": 6,
+        "consultantId": "2083457702519873537",
+        "consultantName": "金卫",
+        "status": "PENDING_REVIEW",
+        "statusName": "待审核",
+        "countedInSummary": true,
+        "remark": "",
+        "specialTags": [],
+        "returnRemark": null,
+        "returnedAt": null,
+        "days": [
+          {
+            "dayNumber": 1,
+            "stayDate": "2026-09-27",
+            "customerSelfBooked": false,
+            "hotels": [
+              {
+                "hotelId": "2023714929877450753",
+                "hotelName": "呼伦贝尔香格里拉大酒店",
+                "city": "呼伦贝尔市",
+                "district": "满洲里市",
+                "totalRoomCount": 2,
+                "rooms": [
+                  {
+                    "roomTypeId": "3002000000000000013",
+                    "roomTypeName": "大床房",
+                    "roomCategory": "KING",
+                    "roomCategoryName": "豪华大床",
+                    "roomCount": 1
+                  },
+                  {
+                    "roomTypeId": "3002000000000000013",
+                    "roomTypeName": "大床房",
+                    "roomCategory": "KING",
+                    "roomCategoryName": "豪华大床",
+                    "roomCount": 1
+                  }
+                ]
+              }
+            ]
+          },
+          {
+            "dayNumber": 2,
+            "stayDate": "2026-09-28",
+            "customerSelfBooked": false,
+            "hotels": [
+              {
+                "hotelId": "3001000000000000005",
+                "hotelName": "额尔古纳白桦大酒店",
+                "city": "呼伦贝尔市",
+                "district": "额尔古纳市",
+                "totalRoomCount": 2,
+                "rooms": [
+                  {
+                    "roomTypeId": "3002000000000000005",
+                    "roomTypeName": "主题标间",
+                    "roomCategory": "STANDARD",
+                    "roomCategoryName": "标间",
+                    "roomCount": 1
+                  },
+                  {
+                    "roomTypeId": "3002000000000000005",
+                    "roomTypeName": "主题标间",
+                    "roomCategory": "KING",
+                    "roomCategoryName": "豪华大床",
+                    "roomCount": 1
+                  }
+                ]
+              }
+            ]
+          }
+        ]
+      },
+      {
+        "orderId": "2101507276118626306",
+        "orderNo": "HL20260920110233355",
+        "customerName": "王五",
+        "participantCount": 2,
+        "consultantId": "2083457702519873537",
+        "consultantName": "金卫",
+        "status": "PENDING_REVIEW",
+        "statusName": "待审核",
+        "countedInSummary": true,
+        "remark": null,
+        "specialTags": [],
+        "returnRemark": null,
+        "returnedAt": null,
+        "days": [
+          {
+            "dayNumber": 1,
+            "stayDate": "2026-09-27",
+            "customerSelfBooked": false,
+            "hotels": [
+              {
+                "hotelId": "3001000000000000005",
+                "hotelName": "额尔古纳白桦大酒店",
+                "city": "呼伦贝尔市",
+                "district": "额尔古纳市",
+                "totalRoomCount": 1,
+                "rooms": [
+                  {
+                    "roomTypeId": "3002000000000000005",
+                    "roomTypeName": "主题标间",
+                    "roomCategory": "STANDARD",
+                    "roomCategoryName": "标间",
+                    "roomCount": 1
+                  }
+                ]
+              }
+            ]
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+> 上面是 TEST 环境 2026-09-20 的真实读数（团期 `jw测试1期`），为控制篇幅只保留了每户前 1–2 晚。
+
+#### 空数据 / 降级响应
+
+团期下没有需订房子订单时：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "groupBatchId": "2101506167098511362",
+    "departDate": "2026-09-27",
+    "householdCount": 0,
+    "countedHouseholdCount": 0,
+    "households": []
+  }
+}
+```
+
+资源服务不可用时**不报错**：`hotelName` 回落到需求里的快照名（快照也没有才为 `null`）、`city` 与 `district` 为 `null`，间数与酒店 ID 照常返回。字典不可用时 `roomCategoryName` 为 `null`，`roomCategory` 编码与间数照常。某户 days JSON 损坏时该户 `days` 为 `[]`，**其它户不受影响**。
+
+#### 错误响应
+
+```json
+{
+  "code": 589507,
+  "message": "无操作权限（当前角色未授予团期权限，或该团期不在您名下）",
+  "data": null
+}
+```
+
+| code | 触发条件 |
+|---|---|
+| 589507 | 当前角色没有 `group-batch:view` |
+| 589500 | 团期不存在 |
+| 401 | 未登录（网关拦截） |
+
+#### 业务边界
+
+- **汇总 == Σ子订单（硬约束）**：`requirement-summary` 的 `dailyRoomBreakdown[].rooms[].totalRoomCount` 逐天等于本接口 `countedInSummary=true` 各户该晚各酒店 `rooms[].roomCount` 之和。两处用同一个状态判据（`RequirementStatus.isSummaryCounted`）和同一个 days 归一器，单测有「明细聚合回去必等于汇总视角」的不变量守护。
+- **列表比汇总宽**：被打回（`REJECTED_TO_CONSULTANT` / `REJECTED_TO_ADMIN`）的户仍出现在 `households[]`，`countedInSummary=false`。这是刻意的——汇总排除打回态是因为作废草稿的间数会让「全团要几间」随一份正在改的需求浮动（#7925）；而明细若也排除，管理员一打回那户就从页面消失，没法跟进。
+- **打回户的 `status` / `returnRemark` / `days` 照常返回**：打回是*原地把需求行改成 `REJECTED_*` 并失活*，该户此时**没有任何 active 行**。本端点对这种户回退到最新一版历史记录取展示信息，所以前端能拿到「被谁打回、什么原因、原先填的是哪几晚」。而 `countedInSummary` 仍只认 active 行，与汇总严格同源。
+- **打回户与从未提交户可区分**：前者 `status=REJECTED_*` 且 `days` 非空，后者 `status=null` 且 `days` 为 `[]`。
+- **哪些户进列表**：`needsHotel=true` 的户 ∪ 已提交有效需求的户（#8023 同口径）。标记为需订房但一份需求都没提交的户**也会列出**，`status` 为 `null`、`days` 为 `[]`——这正是管理员要催的人。
+- **只取首方案**：一段有多个候选酒店时只取 `candidates[0]`，与汇总同口径（候选是房控择一，累加全部会翻倍）。
+- **分住**：同一晚拆多段住多家时 `hotels[]` 出多条；多段指向同一家酒店会合并成一条。
+- **排序**：`households[]` 按 `orderNo` 升序（`orderNo` 为空的排最后）；`days[]` 按 `dayNumber` 升序。
+- **上限**：单次最多返回 500 户，超出截断并打 warn。团期正常几十户，超过说明数据异常。
+- **性能**：房型中文名与酒店名/城市都对整份结果**一次性批量**补齐，不在逐户逐晚的循环里打字典或 Feign。
+
+---
+
+## 四、契约约束与正确调用方式
+
+- 本接口与 `requirement-summary` **并列调用**，不要用其中一个推算另一个：汇总不含逐户信息，本接口不含车辆/特殊需求全景。
+- 前端渲染两块时，若发现数字对不上，先看 `householdCount` 与 `countedHouseholdCount` 的差值——差值就是被打回的户数，属预期行为而非 bug。
+- `orderId` / `consultantId` / `groupBatchId` / `hotelId` 均为字符串序列化，**不要**当数字解析。
+- 打回动作仍走既有端点（`POST /v3/admin/order/{id}/hotel-requirement/reject` 单户、`POST .../group-batch/{id}/requirement/reject` 批量），本次未改。
+
+---
+
+## 六、边界行为
+
+| 场景 | 行为 |
+|---|---|
+| 户被打回 | 仍在列表里，`countedInSummary=false`，带出 `status=REJECTED_*` / `returnRemark` / `returnedAt`，以及原先填的逐晚明细 |
+| 户被打回后重新提交 | 回到 `countedInSummary=true`，打回痕迹清空（TEST 实测） |
+| 户标记需订房但未提交需求 | 仍在列表里，`status` 为 null、`days` 为 `[]`、`countedInSummary=false` |
+| 户 needsHotel=false 但已提交有效需求 | 在列表里（#8023 口径），`countedInSummary=true` |
+| 户既没标记也没有效需求 | 不进列表 |
+| 客户自订晚 | 该晚仍列出，`customerSelfBooked=true`、`hotels` 为 `[]` |
+| 同一晚分住多家 | `hotels[]` 出多条，间数不丢 |
+| 同一晚多段同一家 | 合并成一条 |
+| 段未填酒店 | `hotelId` 为 `null` 的一条，间数不丢 |
+| 团期无出发日 | 所有 `stayDate` 为 `null`，不推算 |
+| 资源服务不可用 | `city` / `district` 为 `null`，`hotelName` 回落快照名 |
+| 字典不可用 | `roomCategoryName` 为 `null`，编码与间数照常 |
+| 某户 days JSON 损坏 | 该户 `days` 为 `[]`，其它户不受影响 |
+| 团期下无在团子订单 | `households` 为 `[]`，不发起需求与资源服务调用 |
+
+---
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 纯新增端点，无任何既有接口改动。
+- **前端是否必须同步上线**: 否。不接入则「用房」板块保持现状（只有汇总表）。
+- **回滚**: 回滚本 PR 即可，只读接口、无数据变更、无表结构变更。
+
+---
+
+## 七、不影响范围
+
+- `GET .../requirement-summary`（汇总）**一字未改**，既有字段与数值逐字不变。
+- `room-plans` / `allocations`（房务订房计划与分房结果）未动。
+- 住宿需求提交契约未动（**没有**往 days JSON 加 city 字段，城市一律由 hotelId 反查）。
+- 未改 hl-resource-service。
+- 打回 / 审核 / 确认相关端点未动。
+- 无数据库表结构变更，无 Flyway 迁移。
+
+---
+
+## 八、测试环境已验证
+
+TEST 环境（`hl-order-service-v3`，dev-v3，2026-09-20），团期 `jw测试1期`（`2101506167098511362`，出发 2026-09-27，6 晚，3 个子订单 / 2 户需订房）。
+
+```
+AC-1  单户多晚多酒店：张三 6 晚跨 3 家酒店，逐晚 hotels[] 与 rooms[] 正确    ✓
+AC-2  多户 + orderNo 升序 + 联系人/人数/定制师(金卫) 与订单表一致            ✓
+AC-3  交叉对账（程序化，非目测）：
+        逐日总数   Day1-6  汇总 3/3/3/3/3/3 == Σ子订单 3/3/3/3/3/3          ✓
+        逐日×酒店×大类 三级全等                                            ✓
+AC-4  打回王五后四件事同时成立：
+        ① 仍在列表里；② status=REJECTED_TO_CONSULTANT / statusName=驳回；
+        ③ returnRemark 与 returnedAt 带出，原填 6 晚明细仍可见；
+        ④ 汇总 Day1-6 由 3 降为 2，且降后 AC-3 等式仍全等                   ✓
+      打回后重新提交 → countedInSummary 回到 true，打回痕迹清空            ✓
+AC-5  客户自订晚：第5晚仍列出、customerSelfBooked=true、hotels=[]，
+        汇总该日由 3 降为 2                                                ✓
+AC-6  未填酒店的段：hotelId=null 一条，间数不丢，不变量仍成立               ✓
+AC-7  酒店名：快照优先；快照缺名的按 ID 批量补出正确名称                    ✓
+AC-8  stayDate = 出发日 + dayNumber − 1，跨月 09-30 → 10-01 正确            ✓
+AC-9  房型：roomTypeName（大床房/主题标间）与 roomCategoryName（豪华大床/
+        标间）均正确译出，单测显式打桩避免空洞断言                          ✓
+AC-10 判权：低权限角色 1002/user → 589507 被拦；超管 200                    ✓
+AC-11 批量加载：整份结果字典与资源服务各只调一次，去重后仅传 3 个 hotelId   ✓
+```
+
+地域字段实测：`city` 全部是「呼伦贝尔市」，`district` 分别是「满洲里市 / 额尔古纳市 / 海拉尔区」——**页面地点那一列必须用 `district`**。
+
+单测：`GroupBatchHotelHouseholdServiceTest` 19/19、`HotelRequirementDaysNormalizerTest` 76/76（含「明细聚合回去必等于汇总视角」不变量）、相关回归 194/194。order-v3 全量 A 组 8334 用例 / B 组 3995 用例，3 个失败均非本次引入并逐个做过基线对照（`FinanceFeignContextMockInventoryTest` 基线同样红、`GroupBatchAuditVersionCasMySqlIT` 并发 flaky 单跑 10/10 绿、`MapperBoundaryArchTest` 已知基线红 #7989）。
+
+---
+
+## 十、相关文档
+
+- 工单 [#8046](https://git.1814.love:8443/wx/HL/issues/8046)
+- [#8030](https://git.1814.love:8443/wx/HL/issues/8030) 用房汇总（本接口的姊妹接口，同一板块的上半部分）
+- [#8023](https://git.1814.love:8443/wx/HL/issues/8023) 需订房户判据（本接口沿用同一套 `countsTowardHotel` 口径）
+- [#7925](https://git.1814.love:8443/wx/HL/issues/7925) 汇总计入状态集合（本次收口为 `RequirementStatus.isSummaryCounted` 单源）
+- [#7316](https://git.1814.love:8443/wx/HL/issues/7316) `requirement-summary` 判权接 `group-batch:view`（本接口沿用）
+- [#7324](https://git.1814.love:8443/wx/HL/issues/7324) 「团期看板要看全部版本而不是 active 行」——打回后无 active 行这一条的出处
+
+---
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8046](https://git.1814.love:8443/wx/HL/issues/8046)
+- **PR**: [#8055](https://git.1814.love:8443/wx/HL/pulls/8055)、[#8057](https://git.1814.love:8443/wx/HL/pulls/8057)、[#8059](https://git.1814.love:8443/wx/HL/pulls/8059)、[#8060](https://git.1814.love:8443/wx/HL/pulls/8060)
+
+### 联系人
+
+- **后端负责人**: @jw
+- **前端负责人**: @mmg
@@ -0,0 +1,309 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8051"
+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-20 20:3x 状态位升级，依据如下（不是为了让门禁变绿）。 backend_status=deployed：代码经 PR #8058 squash 为 ac9efb735 合入 dev-v3；fleet 测试服部署点 c35251b07（2026-09-20 18:58，STATE=ok），git merge-base --is-ancestor ac9efb735 c35251b07 = 真；并用 jar 字节**正负两向**自证——新类 AssignmentOccupancyDayScope **部署前不在 jar 里、部署后在**（只查后一次没有分辨力）。 gateway_status=verified：2026-09-20 20:0x-20:2x 经网关 api.test.1814.love:9443 **两轮独立实测** DELETE /admin/fleet/group-dispatch/share-groups/{id}?survivorPolicy=RELEASE，均在自建测试团 2101524283048263681 上，同一辆车 2065329519232720897。 🔴 两半边都取了，缺一半这条证据就没有分辨力：（阳性对照）本服务日那张确实被处理——目标 ASSIGNMENT 360022177073991680 由 vehicle=G/assigned 转为 vehicle=NULL/unassigned，且出现在 releasedSourceIds 里；（负对照）跨日的 2026-12-15 独立派单三字段逐一不变，跨日+跨团的原 6 行受害者所在三个团七个服务日的 7 行 fleet_group_dispatch 释放前后逐字段完全一致。 ⚠️ 另订正一条执行者自己的假设：本次修复**只改了 ASSIGNMENT 侧**，GROUP_DISPATCH 侧此前就是按 trip_date 精确过滤的、从未有跨日 bug。 ⚠️ 仍未解决且不在本篇范围：同一资源**同一服务日**上的**非成员**在途行 仍会被 RELEASE 一并软清（releaseClaims 不引用 members），已另立工单 #8061 待产品口径。 【上一轮原注】backend_status 与 gateway_status 刻意保持 pending：本篇写于工单 #8051 的修复分支上，代码尚未合入 dev-v3、更未部署测试服，本会话**没有做过任何一次真实网关调用**。正文里的所有事实分两类并已逐处标注：①【实测·库+日志】—— 2026-09-20 测试服 hl_fleet_service 库与 /opt/hulalv/HL/logs/hl-fleet-service.log 的一手读数；②【源码】—— 修复分支工作树的源码。请求/响应示例的字段名与类型来自 ShareGroupReleaseRespVO 的 @ApiModelProperty 声明，不是抓包。⛔ 合并 + 部署 + 网关复验之前，不得为了让门禁变绿把这两个状态位改成 deployed/verified。frontend_status=not_required 的判据：本次不改请求/响应形状、不增删字段、不新增错误码，管理后台无需改代码；但本篇仍是给 mmg 的知会件——「解除共用关系」这个动作的**影响范围**变了，看板上此前莫名变成「待派车」的那些户，原因在此。 前端实证维持 not_required(mmg 2026-09-20):survivorPolicy/share-groups/shareGroup 全仓零命中,共用关系前端未接入(#7444 挂起域),行为收窄纯数据面受益;知会点已收:存量 6 行误清不做 SQL 回滚须走正常改派写口恢复,同日非成员在途行仍被 RELEASE 软清另立 #8061 待产品口径。"
+updated_at: "2026-09-20"
+base: "dev-v3"
+---
+
+# fleet: 解除共用关系不再跨服务日、跨团误清在途派车行（工单 #8051）
+
+> **存放目录**: 二期（order-v3 标签工单）→ `changelogs-v2/2026-09/`
+>
+> **服务**: hl-fleet-service
+> **PR**: #8058（squash `ac9efb735`，已合入 dev-v3） ｜ **Issue**: #8051
+> **日期**: 2026-09-20
+> **影响范围**: 管理后台「团期配车 / 车务看板」，解除车辆或司机共用关系这一个动作的副作用范围
+
+---
+
+## ⚠️ 关键变化
+
+**改动前**：解除某一个共用关系，会把**同一辆车（或同一名司机）上所有服务日、所有团**的在途派车行一起软清成「待派车」，并清空车辆与司机。
+**改动后**：只处置**该关系自己那一个「资源 + 服务日」槽**上的在途派车行，其它服务日、其它团的行一律不动。
+
+🔴 **这个误清此前是完全静默的**：软清不抛异常、不返错误码，解除请求本身返 200；被误伤的户在车务看板上显示「待派车」，与「本来就没派过」**外观完全相同**，运营侧没有任何信号能把两者分开。
+
+⚠️ **接口形状没有任何变化**——路径、方法、入参、响应体字段、错误码全部不变。变的只是这个动作**碰到多少行**。前端无需改代码。
+
+---
+
+## 一、背景
+
+### 1. 一次解除误伤了 6 张跨日跨团的派车行【实测·日志 + 库，2026-09-20 测试服】
+
+`/opt/hulalv/HL/logs/hl-fleet-service.log`，2026-09-20 14:04:12：解除共用关系 `359915397639704576`（服务日 **2026-10-03**、团 `2101524283048263681`、VEHICLE `2065329519232720897`、策略 RELEASE），日志里 `释放=[...7 个派单 ID...]`。
+
+对这 7 行逐一回库核对 `service_date` 与 `group_batch_id`：
+
+| 派单 ID | 服务日 | 团 | 判定 |
+|---|---|---|---|
+| 359887954036002816 | 2026-10-18 | 2101496576453275649 | **跨日跨团误清** |
+| 359887954396712960 | 2026-10-18 | 2101496576453275649 | **跨日跨团误清** |
+| 359888468400279552 | 2026-10-25 | 2101498606508994561 | **跨日跨团误清** |
+| 359888468916178944 | 2026-10-25 | 2101498606508994561 | **跨日跨团误清** |
+| 359888884127109120 | 2026-10-25 | 2101498606508994561 | **跨日跨团误清** |
+| 359896486663819264 | 2026-11-20 | 2099073597908647938 | **跨日跨团误清** |
+| 359915650245857280 | 2026-10-03 | 2101524283048263681 | 同日同槽，RELEASE 策略下属预期范围 |
+
+⇒ **6 行是误清**，横跨 3 个其它服务日、3 个其它团；7 行现状全部 `assignment_status=unassigned`、`vehicle_id`/`driver_id` 置 NULL、`update_time=14:04:12`。
+
+### 2. 误清没有在任何一张业务表里留下痕迹【实测·库】
+
+这 6 行在 `fleet_assignment_operation_log` 里**没有 14:04 的任何一条记录**（它们最后一条记录是当天上午 10:26–11:00 的 `change_completed`）。⇒ 事后想从库里把「谁在什么时候把它清掉的」查出来，唯一线索是应用日志。
+
+### 3. 根因【源码】
+
+占用取数口径 `selectActiveResourceClaimsForUpdate` 是**资源级**的（它还刻意补齐同派车组的其余切片，好让组区间可以重建），`serviceDate` 参数不参与过滤。占用账本那一侧的消费方在拿到结果后自己按日收窄了，共用关系解除这一侧没有——于是同一份返回集被两个消费方按两种口径使用。本次把「资源日」口径收成一个具名的公共读口，两侧不再各抄一份过滤。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 解除团期车辆/司机共用关系 | DELETE | `/admin/fleet/group-dispatch/share-groups/{shareGroupId}` | **行为修复**（契约不变） | 处置范围从「该资源上全部在途行」收窄为「该资源 + 该服务日」 |
+
+---
+
+## 三、接口详情
+
+### 1. 解除团期车辆/司机共用关系 `DELETE /admin/fleet/group-dispatch/share-groups/{shareGroupId}`
+
+**VO**: `ShareGroupReleaseRespVO`（**字段无增删改**）
+
+#### 使用场景
+
+管理后台「团期配车」页，车务点「解除共用」。解除同时要在同一事务内完成幸存占用的实际处置，`survivorPolicy` 决定怎么处置。
+
+#### 入参（**本次无变化**）
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| shareGroupId | Path | Long | ✅ | - | 共用关系 ID |
+| survivorPolicy | Query | String | 业务必填 | `KEEP_LEGAL` / `REASSIGN` / `RELEASE` | 幸存占用处置策略；不传返业务码 `602110`（框架层刻意声明为非必填，否则缺参会被挡成 400，`602110` 永远抛不出来） |
+
+#### 出参（**本次无变化**，字段来源：`ShareGroupReleaseRespVO` 的 `@ApiModelProperty` 声明）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| shareGroupId | String | 共用关系 ID（雪花 ID，`@JsonSerialize(ToStringSerializer)` 按字符串序列化，避免前端精度丢失） |
+| status | String | 固定 `RELEASED` |
+| survivorPolicy | String | 本次采用的处置策略 |
+| keptSourceIds | List\<String\> | 保留占用的来源 ID（雪花 ID，按字符串序列化） |
+| releasedSourceIds | List\<String\> | 已释放占用的来源 ID（雪花 ID，按字符串序列化） |
+| pendingReassignSourceIds | List\<String\> | 需人工改派的来源 ID（占用已真实释放、派单已置待改派；雪花 ID，按字符串序列化） |
+
+#### 请求示例
+
+DELETE 无请求体，路径参数 + 查询参数即完整请求。`{shareGroupId}` 为待解除的共用关系 ID（路径参数占位写法，与本文档路径参数约定一致，不代表某个固定值）：
+
+```http
+DELETE /admin/fleet/group-dispatch/share-groups/{shareGroupId}?survivorPolicy=RELEASE HTTP/1.1
+Host: api.test.1814.love:9443
+Authorization: Bearer {token}
+```
+
+#### 响应示例
+
+以下为 2026-09-20 20:0x-20:2x 网关实测（测试团 `2101524283048263681`、车辆 `2065329519232720897`，`survivorPolicy=RELEASE`）的真实取值；`shareGroupId` 与请求路径参数回显一致，示例中用占位符表示：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "shareGroupId": "{shareGroupId}",
+    "status": "RELEASED",
+    "survivorPolicy": "RELEASE",
+    "keptSourceIds": ["2101524548279238658"],
+    "releasedSourceIds": ["360022177073991680"],
+    "pendingReassignSourceIds": []
+  },
+  "success": true
+}
+```
+
+库内复核：目标 ASSIGNMENT `360022177073991680` 由 `vehicle=G/assigned` 转为 `vehicle=NULL/unassigned`；`keptSourceIds` 里的 `2101524548279238658` 是同槽的 GROUP_DISPATCH 成员，内部按既有设计被 `continue` 跳过、从不软清。
+
+#### 空数据 / 降级响应
+
+该资源日上仅剩 0-1 个存活 claim 时（例如另一侧的占用已提前被释放），`keptSourceIds` / `releasedSourceIds` / `pendingReassignSourceIds` 三个清单都可能是空数组 `[]`——这是正常终态，不是异常。本接口是单次同步写操作，不查 Feign、不查 MQ，没有"下游降级"的响应形态。
+
+#### 错误响应
+
+以下为 2026-09-20 20:0x-20:2x 网关实测（同一测试团/车辆，`survivorPolicy=KEEP_LEGAL` 命中冲突）的真实响应；该请求**整体回滚**，共用关系仍为 `ACTIVE`：
+
+```json
+{
+  "code": 602111,
+  "message": "保留合法共用失败，幸存成员之间不满足衔接规则: GROUP_DISPATCH#2101524548279238658 ↔ ASSIGNMENT#360022539151478784",
+  "data": null,
+  "success": false
+}
+```
+
+#### 业务边界
+
+- 鉴权：需管理后台已登录且具备 `fleet:group-dispatch:write` 权限点，未登录/无权限按网关与全局鉴权统一规则处理（见"六、边界行为"）。
+- 幂等性：关系一旦解除即置 `RELEASED`；对同一 `shareGroupId` 重复发起 DELETE 不是幂等成功，会直接拿到 602108（共用关系不存在或已解除）。
+- 失败零写入：`KEEP_LEGAL` 冲突（602111）与收口断言不成立（602112）都在同一个事务内回滚——关系不会被标记为已解除，占用状态不会有任何变化。
+- `survivorPolicy` 在框架层刻意声明为非必填（业务上必填），不传会拿到业务码 602110，不是 400；完整的正确/错误 payload 对照见"四、契约约束与正确调用方式"。
+- 🔴 已知未覆盖边界（**不在本次修复范围**）：同一资源**同一服务日**上的**非成员**在途行仍会被 `RELEASE` 一并软清，且同样静默——处置逻辑不区分"共用关系的成员"与"路过的其它派车行"；最典型场景是接送机的接、送一对。已另立工单 **#8061** 待产品口径。
+
+#### 错误码（**本次不新增、不改语义**）
+
+| code | 含义 |
+|------|------|
+| 602108 | 共用关系不存在或已解除 |
+| 602110 | 未指定处置策略 |
+| 602111 | `KEEP_LEGAL` 下剩余 claim 存在非法组合（fail-closed，整请求回滚） |
+| 602112 | 收口断言不成立：处置后账本里仍有非法组合（回滚） |
+
+---
+
+## 四、契约约束与正确调用方式
+
+> 本节只写后端接受/拒绝 payload 的规则，不写 UI 渲染建议。接口本身**没有变化**——本节写的是既有契约，帮消费方确认自己一直调对了。
+
+### ✅ 正确 / ❌ 错误 payload 对照
+
+| 场景 | payload | 结果 |
+|------|---------|------|
+| ✅ 释放全部幸存占用 | `DELETE .../share-groups/{shareGroupId}?survivorPolicy=RELEASE` | 200，幸存 claim 全部释放 |
+| ✅ 仅在两两合法时整槽保留 | `DELETE .../share-groups/{shareGroupId}?survivorPolicy=KEEP_LEGAL` | 有冲突时 602111 并点名冲突对，整请求回滚 |
+| ✅ 真释放冲突成员并标记待改派 | `DELETE .../share-groups/{shareGroupId}?survivorPolicy=REASSIGN` | 200，`releasedSourceIds` 与 `pendingReassignSourceIds` 相同 |
+| ❌ 不传 `survivorPolicy` | `DELETE .../share-groups/{shareGroupId}`（无查询参数） | 602110，不是 400（框架层刻意声明为非必填，见下） |
+| ❌ `shareGroupId` 指向不存在或已解除的关系 | 任意 `survivorPolicy` | 602108 |
+
+### 切换状态时的必要动作
+
+- `survivorPolicy` 在框架层被声明为非必填，但业务上**必须**传值；不传等于让后端替你决定处置策略——唯一后果是拿到 602110，服务端不会静默退化为某个默认策略。
+- ⚠️ **该字段目前是裸字符串比对，不是枚举反序列化**：只有 `RELEASE` / `KEEP_LEGAL` / `REASSIGN` 三个大写字面量被识别；传入其它任意字符串（含大小写拼写错误）不会报 400，而是落进"仅释放冲突子集、不标记待改派"这条隐式默认分支（等同 `KEEP_LEGAL` 的释放动作但不校验合法性、也不回滚）。前端必须原样传三选一的大写字面量，不要自行拼接或做大小写转换。
+
+---
+
+## 五、数据库行为
+
+- **本服务日范围内**：解除共用关系后，该关系名下、在**这一个服务日**上仍存活的派车行会被置为「待派车」，车辆与司机一并清空（`RELEASE` / `REASSIGN` 都会触发；`KEEP_LEGAL` 冲突时整请求回滚，不落任何写）。
+- **修复点（本次变化）**：**其它服务日、其它团**的派车行不再受这次解除影响——即便它们挂在同一辆车/同一名司机上。
+- 🔴 **该动作不产生操作日志记录**：软清不写入任何"操作记录"轨道，事后无法从操作日志追溯"谁在什么时候把它清掉的"；唯一线索是应用运行日志（后端可查，前端/运营界面查不到）。
+
+---
+
+## 六、边界行为
+
+- 未登录 → 401（网关拦截）
+- 无 `fleet:group-dispatch:write` 权限 → 403
+- `shareGroupId` 不存在或已解除 → 602108（不是 404）
+- 未传 `survivorPolicy` → 602110（不是 400；见"四、契约约束与正确调用方式"）
+- `survivorPolicy` 不是三个合法字面量之一 → 不报错，落入隐式默认分支（见"四、契约约束与正确调用方式"）
+- 本接口不依赖外部服务（不查 Feign、不查 MQ），没有"下游降级"路径
+- 🔴 本次修复范围之外的已知缺陷（**#8061**）：同一资源同一服务日上的**非成员**在途行仍会被 `RELEASE` 一并软清且同样静默，典型场景是接送机接、送一对，产品口径待定，本次不改
+
+---
+
+## 六.5、枚举 / 数据字典
+
+### survivorPolicy（`ShareSurvivorPolicy`）
+
+**所属字段**: `survivorPolicy`（Query 入参）| **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `RELEASE` | 全部释放 | 释放该资源日上全部幸存 claim 的占用，全部置「待派车」 |
+| `KEEP_LEGAL` | 仅合法保留 | 仅当幸存 claim 两两全合法（无冲突）时整槽保留；有冲突则 602111 拒绝并回滚 |
+| `REASSIGN` | 释放并待改派 | 真释放冲突成员的占用，派单置「待改派」，`releasedSourceIds` 与 `pendingReassignSourceIds` 相同 |
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 |
+|------|------|------|
+| （无）请求 / 响应字段 | 不变 | 不变——本次未增删改任何字段 |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| 被处置的派车行范围 | 该车/该司机上**全部**在途行（跨服务日、跨团） | 仅该车/该司机 **在该关系的服务日上** 的在途行 |
+| `releasedSourceIds` 里可能出现别的服务日的派单 ID | 会 | 不会 |
+| 别的团的在途派车行是否会被清成「待派车」 | 会，且无任何信号 | 不会 |
+| 请求/响应字段、错误码 | — | 完全不变 |
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 否——请求/响应字段、错误码全部不变。
+- **前端是否必须同步上线**: 否——管理后台无需改任何代码。
+- **前端 workaround 清理点**: 无新增 workaround；但请转告使用方——测试环境里 2026-09-20 14:04 之后出现的、跨服务日/跨团突然变成「待派车」的户，原因就是本缺陷，不是运营误操作、也不是前端展示 bug。这 6 行的清单见"一、背景"的表格。
+- 🔴 **给 mmg 的知会重点**：「解除共用关系」这个动作的**影响范围**变了——以前它可能波及别的服务日/别的团的在途派车行，现在只影响它自己那一个「资源 + 服务日」槽。看板上此前莫名变成「待派车」的那些户，原因就在此。
+- **存量处理**：测试库里因本缺陷产生的 6 行误清**不做 SQL 回滚**——软清把 `vehicle_id`/`driver_id` 都置了 NULL，而这 6 行当时的**司机**在库里已无处可查（它们上午那次改派只改了车辆维度，`fleet_assignment_operation_log` 里没有清空前的司机值），直接改库只能还原一半，会造出「有车无司机的已派车行」这种新的非法态。正确的恢复方式是走正常改派写口重新派。
+
+---
+
+## 七、不影响范围
+
+- **仅影响**: 管理后台「团期配车」页解除车辆/司机共用关系这一个动作的副作用范围（波及多少张派车行）
+- **零影响**:
+  - 请求/响应字段结构、错误码（全部不变，前端无需改代码）
+  - 团级配车行（GROUP_DISPATCH）侧的处置口径（本就按服务日精确过滤，从无此 bug）
+  - 确认共用关系 `POST .../batches/{groupBatchId}/share-groups`、查询共用关系 `GET .../batches/{groupBatchId}/share-groups` 两个端点（本次未改动）
+  - 同一资源同一服务日上**非成员**在途行的处置口径（仍是旧行为，见"六、边界行为"，已另立 #8061）
+
+---
+
+## 八、测试环境已验证
+
+真实接口调用 + DBeaver 回库核对，带 ✓ 标记（2026-09-20 20:0x-20:2x，网关 `api.test.1814.love:9443`，测试团 `2101524283048263681`，车辆 `2065329519232720897`）：
+
+```
+DELETE /admin/fleet/group-dispatch/share-groups/{shareGroupId}?survivorPolicy=RELEASE
+  → 200，releasedSourceIds=["360022177073991680"]，keptSourceIds=["2101524548279238658"] ✓
+  → 库内复核：目标 ASSIGNMENT 360022177073991680 由 vehicle=G/assigned 转为 vehicle=NULL/unassigned ✓
+
+DELETE /admin/fleet/group-dispatch/share-groups/{shareGroupId}?survivorPolicy=KEEP_LEGAL
+  → 602111，消息点名冲突对 GROUP_DISPATCH#2101524548279238658 ↔ ASSIGNMENT#360022539151478784 ✓
+  → 整请求回滚：该 share_group 行仍 ACTIVE ✓
+
+DELETE /admin/fleet/group-dispatch/share-groups/{shareGroupId}?survivorPolicy=REASSIGN
+  → 200，releasedSourceIds = pendingReassignSourceIds = ["360022539151478784"] ✓
+  → 库内复核：该 assignment 的车辆与司机已清空、状态回到待派车（真释放 + 待改派） ✓
+
+（负对照，证修复生效）
+跨日 2026-12-15 的独立派单三字段逐一不变 ✓
+跨日+跨团的原 6 行受害者所在三个团七个服务日的 7 行团级配车行释放前后逐字段完全一致 ✓
+```
+
+部署点 `c35251b07`（2026-09-20 18:58，STATE=ok）；`git merge-base --is-ancestor ac9efb735 c35251b07` = 真，确认该部署点已包含本次修复。
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#8051](https://git.1814.love:8443/wx/HL/issues/8051)
+- 关联 PR: [wx/HL#8058](https://git.1814.love:8443/wx/HL/pulls/8058)
+- 关联后续工单（同一缺陷模式下未覆盖的分支，待产品口径，本次不改）: [wx/HL#8061](https://git.1814.love:8443/wx/HL/issues/8061)
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8051](https://git.1814.love:8443/wx/HL/issues/8051)
+- **PR**: [#8058](https://git.1814.love:8443/wx/HL/pulls/8058)
+- **Merge commit**: [ac9efb735](https://git.1814.love:8443/wx/HL/commit/ac9efb735ab858fef45c4af433023099faef0b2f)
+
+### 联系人
+
+- **后端负责人**: @wx
@@ -0,0 +1,371 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8061"
+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: "backend_status=deployed：PR #8067 squash 为 00930f5d6，2026-09-20 22:42 已部署到测试服 192.168.100.236，deploy-status.sh 复核落点 = 00930f5d6，Nacos 两实例（8087/8187）healthy=true。gateway_status=verified：2026-09-21 在测试服网关上以全新三户夹具（团期 2101690789438570497、服务日 2026-10-30）取得阳性与阴性两条对照——阳性：releasedSourceIds 恰为两个成员且库内真变 unassigned；阴性：非成员 C 的 assignment_status/vehicle_id/driver_id 解除前后逐一相等。两条缺一不可：只有阳性的话，「C 没变」与「解除没跑起来」观测相同，且阳性在修复前同样成立。详见正文「八、测试环境已验证」。（📌 gateway_status 这个字段记的是「网关验证有没有做过」，不是「网关路由要不要改」——先例见 2026-08 #5405/#5407：『测试环境部署和网关验证尚未执行，因此 backend_status、gateway_status 保持 pending』。本次不新增端点、不改路由形状，但那不构成填 not_required 的理由，填 verified 的理由是上面那次真实调用。）frontend_status：后端起初填 pending，理由是——请求/响应字段确实零增删，但派车操作日志时间线新增了 operation_type 取值 share_release_cleared——前端若按 operation_type 白名单过滤，这条会被静默丢掉，用户就看不到『车和司机是被哪次共用关系解除清掉的』，而那正是本次补留痕要解决的问题。⇒ 前端至少需要确认自己有没有这层过滤、必要时加上，这是动作不是知会，故 pending。另按指南，not_required 会禁止 mmg 回写 frontend_owner 等认领字段，填错反而挡住认领。mmg 前端实证 2026-09-20:fleet 操作日志读口 getOrderOperationLog(api/fleet/board.js:58)在全仓零调用方,src/views/fleet 无 operationType 命中——后端担心的「时间线按 operation_type 白名单过滤会静默丢 share_release_cleared」过滤层在前端不存在(该时间线 UI 尚未建),故前端零改动,翻 not_required。后续接入操作日志时间线时 operation_type 渲染必须包含 share_release_cleared(detail_json 全字段字符串 ID 透传)。share-groups 解除入口前端未接入,属 #7444 挂起域,同 #8051 口径。"
+updated_at: "2026-09-20"
+base: "dev-v3"
+---
+
+# fleet: 解除共用关系只处置本关系的成员，同槽非成员行保留（工单 #8061 + #8051 衍生）
+
+> **存放目录**: 二期（order-v3 标签工单）→ `changelogs-v2/2026-09/`
+>
+> **服务**: hl-fleet-service
+> **PR**: #8067（squash `00930f5d6`，已合入 dev-v3） ｜ **Issue**: #8061
+> **日期**: 2026-09-20
+> **影响范围**: 管理后台「团期配车」页解除车辆或司机共用关系这一个动作，及其对派车账本的影响
+
+---
+
+## ⚠️ 关键变化
+
+**三个可观测行为都变了，前端必须知道：**
+
+### ① 处置范围收窄
+
+改动前：解除某一个共用关系，会把该车/该司机**在整个资源日槽上的全部在途派车行**一起软清成「待派车」，同槽的**非成员行也被清**。
+改动后：只处置**该关系的成员占用**。同一车/同一司机、**同一服务日**上那些**从不属于本关系**的在途派车行，**一行不动**。
+
+⇒ 响应里的 `releasedSourceIds` / `pendingReassignSourceIds` 会比以前短。同一个服务日、同一辆车上那些**与本关系无关**的在途派单，不再被连带清空。
+
+**典型场景**：接送机的接、送一对。它们本来就该在同一天占同一辆车，但不一定属于同一个共用关系；现在解除一个关系不再误伤另一对。
+
+### ② 错误码触发条件变了
+
+- **602111**（`KEEP_LEGAL` 下仍有非法组合）与 **602112**（收口断言）现在只在「**至少一侧是本关系成员**」的组合上触发。
+- ⇒ 以前会因为两条**互不相干的第三方派单**存量冲突而整单失败的情况，**现在不会再失败了**。前端若有「解除失败请联系管理员」这类兜底文案，触发频率会下降。
+
+### ③ 🔴 派单操作日志时间线新增 `share_release_cleared` 记录
+
+新增操作类型值 `share_release_cleared`，中文标签「共用关系解除释放占用」。`detail_json` 包含以下字段（所有 ID 都是**字符串**，防雪花 ID 过 JS 掉精度）：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| shareGroupId | String | 被解除的共用关系 ID |
+| groupBatchId | String | 团 ID |
+| serviceDate | String | 服务日期（YYYY-MM-DD） |
+| resourceType | String | 资源维度：`VEHICLE` 或 `DRIVER` |
+| resourceId | String | 车辆或司机 ID |
+| releaseReason | String | 解除原因 |
+| survivorPolicy | String | 本次采用的处置策略（`RELEASE` / `REASSIGN` / `KEEP_LEGAL`） |
+| vehicleIdBefore | String | 派单清之前挂的车辆 ID（解除后被清成 NULL）|
+| driverIdBefore | String | 派单清之前挂的司机 ID（解除后被清成 NULL） |
+
+**⚠️ 关键警告**：如果前端在时间线上按 `operation_type` 白名单过滤，这条新记录会被静默丢掉。用户就看不到「车和司机是被哪次共用关系解除清掉的」——而这正是本次补留痕要解决的问题。
+
+---
+
+## 一、背景
+
+### 原 #8051 与本单的关系
+
+#8051 修了「解除共用关系会**跨服务日、跨团**软清在途派车行」这个 bug，已由 PR #8058（`ac9efb735`）修复并部署。
+
+本单从 #8051 分出，因为在修复过程中又发现了一个**同一服务日**范围内的残留问题：`RELEASE` 策略清的是该资源日槽上**全部在途 claim**，与"是否属于本关系的成员"之间没有任何约束。结果：同槽上的非成员行也被一起清了，且同样静默。
+
+### 两处文档说了对的话，实现没跟上
+
+- `ShareSurvivorPolicy.RELEASE` 的 javadoc：释放**本关系的成员**的占用
+- `GroupDispatchShareController` 的 `@ApiOperation.notes`：同样说释放**本关系的成员**
+
+两处独立写成同一个意思——这代表**意图**，而不是"实现当前的行为"。现状不是「文档没跟上实现」，是**实现从来没有对齐过契约**。
+
+### 实测误清 6 行真实数据
+
+2026-09-20 14:04:12 解除共用关系 `359915397639704576`（服务日 2026-10-03、车辆 `2065329519232720897`）时，日志记的是 `释放=[7 个派单 ID]`，经库内逐行核对：
+
+| 派单 ID | 服务日 | 团 | 是否成员 | 预期 | 实际 |
+|---|---|---|---|---|---|
+| 359887954036002816 | 2026-10-18 | 2101496576453275649 | ❌ | 不该动 | 被清 |
+| 359887954396712960 | 2026-10-18 | 2101496576453275649 | ❌ | 不该动 | 被清 |
+| 359888468400279552 | 2026-10-25 | 2101498606508994561 | ❌ | 不该动 | 被清 |
+| 359888468916178944 | 2026-10-25 | 2101498606508994561 | ❌ | 不该动 | 被清 |
+| 359888884127109120 | 2026-10-25 | 2101498606508994561 | ❌ | 不该动 | 被清 |
+| 359896486663819264 | 2026-11-20 | 2099073597908647938 | ❌ | 不该动 | 被清 |
+| 359915650245857280 | 2026-10-03 | 2101524283048263681 | ✅ | 该清 | 被清 |
+
+**6 行误清**：横跨 3 个其它服务日、3 个其它团；现状全部 `assignment_status=unassigned`、`vehicle_id`/`driver_id` 置 NULL。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 解除团期车辆/司机共用关系 | DELETE | `/admin/fleet/group-dispatch/share-groups/{shareGroupId}` | **行为修复**（字段、错误码、网关路由均不变） | 处置范围从「整个资源日槽」收窄为「本关系的成员」；错误码触发条件同步收窄 |
+| 2 | — | — | — | **日志侧新增** | 派单操作日志新增 `share_release_cleared` 记录类型 |
+
+---
+
+## 三、接口详情
+
+### 1. 解除团期车辆/司机共用关系 `DELETE /admin/fleet/group-dispatch/share-groups/{shareGroupId}`
+
+**VO**: `ShareGroupReleaseRespVO`（**字段零增删改**）
+
+#### 使用场景
+
+管理后台「团期配车」页，车务点「解除共用」。解除同时要在同一事务内完成幸存占用的实际处置，`survivorPolicy` 决定怎么处置。
+
+#### 入参（**本次无变化**）
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| shareGroupId | Path | Long | ✅ | — | 共用关系 ID |
+| survivorPolicy | Query | String | 业务必填 | `KEEP_LEGAL` / `REASSIGN` / `RELEASE` | 幸存占用处置策略；不传返业务码 `602110` |
+
+#### 出参（**本次无变化**）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| shareGroupId | String | 共用关系 ID（雪花 ID，按字符串序列化） |
+| status | String | 固定 `RELEASED` |
+| survivorPolicy | String | 本次采用的处置策略 |
+| keptSourceIds | List\<String\> | 保留占用的来源 ID（本关系成员中被保留的） |
+| releasedSourceIds | List\<String\> | **已释放占用的来源 ID**（**仅本关系成员，不含非成员**） |
+| pendingReassignSourceIds | List\<String\> | 需人工改派的来源 ID（仅本关系成员） |
+
+#### 请求示例
+
+```http
+DELETE /admin/fleet/group-dispatch/share-groups/{shareGroupId}?survivorPolicy=RELEASE HTTP/1.1
+Host: api.test.1814.love:9443
+Authorization: Bearer {token}
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "shareGroupId": "{shareGroupId}",
+    "status": "RELEASED",
+    "survivorPolicy": "RELEASE",
+    "keptSourceIds": ["2101524548279238658"],
+    "releasedSourceIds": ["360022177073991680"],
+    "pendingReassignSourceIds": []
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+该资源日上仅剩 0-1 个存活 claim 时，三个清单都可能是空数组 `[]`——这是正常终态，不是异常。
+
+#### 错误响应
+
+```json
+{
+  "code": 602111,
+  "message": "保留合法共用失败，幸存成员之间不满足衔接规则: GROUP_DISPATCH#2101524548279238658 ↔ ASSIGNMENT#360022539151478784",
+  "data": null,
+  "success": false
+}
+```
+
+#### 业务边界
+
+- 鉴权：需管理后台已登录且具备 `fleet:group-dispatch:write` 权限，未登录/无权限按网关与全局鉴权规则处理。
+- 幂等性：关系一旦解除即置 `RELEASED`；重复发起 DELETE 会拿到 602108。
+- 失败零写入：602111 / 602112 都在同一事务内回滚——关系不标 RELEASED，占用状态不变。
+- `survivorPolicy` 必须传值；不传返 602110，不是 400。
+- 🔴 已知未覆盖边界（**不在本次修复范围**）：同一资源同一服务日上的**非成员**在途行仍会被 `RELEASE` 一并软清且同样静默——处置逻辑不区分"共用关系的成员"与"路过的其它派车行"；最典型场景是接送机的接、送一对。已在工单 #8061 本单纳入。
+
+#### 错误码（**本次不新增、语义不改**）
+
+| code | 含义 |
+|------|------|
+| 602108 | 共用关系不存在或已解除 |
+| 602110 | 未指定处置策略 |
+| 602111 | `KEEP_LEGAL` 下**本关系的幸存成员**之间存在非法组合；整请求回滚 |
+| 602112 | 收口断言不成立：处置后账本里**至少一侧是本关系成员的组合**中仍有非法；回滚 |
+
+---
+
+## 四、契约约束与正确调用方式
+
+> 本节只写后端接受/拒绝 payload 的规则。接口契约本身**没有变化**——本节写的是既有契约，帮消费方确认自己一直调对了。
+
+### ✅ 正确 / ❌ 错误 payload 对照
+
+| 场景 | payload | 结果 |
+|------|---------|------|
+| ✅ 释放本关系全部幸存成员占用 | `DELETE .../share-groups/{id}?survivorPolicy=RELEASE` | 200，成员占用全释，同槽非成员不动 |
+| ✅ 仅在成员间两两合法时整槽保留 | `DELETE .../share-groups/{id}?survivorPolicy=KEEP_LEGAL` | 成员间有冲突时 602111 拒绝，整请求回滚 |
+| ✅ 真释放冲突成员并标记待改派 | `DELETE .../share-groups/{id}?survivorPolicy=REASSIGN` | 200，释放冲突成员；成员与非成员冲突时成员让位 |
+| ❌ 不传 `survivorPolicy` | `DELETE .../share-groups/{id}`（无查询参数） | 602110，不是 400 |
+| ❌ `shareGroupId` 指向不存在或已解除的关系 | 任意 `survivorPolicy` | 602108 |
+
+### 切换状态时的必要动作
+
+- `survivorPolicy` 必须始终传值——不传拿到 602110，前端应按此逻辑引导用户补选。
+- 若修改派单分配方案，必须显式传递三选一的大写字面量，不要自行拼接或做大小写转换。
+
+---
+
+## 五、数据库行为
+
+- **本服务日范围内**：解除共用关系后，该关系名下、在**这一个服务日**上仍存活的**成员派车行**会被置为「待派车」，车辆与司机清空（`RELEASE` / `REASSIGN` 都触发；`KEEP_LEGAL` 冲突时整请求回滚）。
+- **修复点（本次变化）**：**同一资源、同一服务日上那些**不属于本关系****的派车行不再受影响——即便它们挂在同一辆车/同一名司机上。
+- **新增操作日志**：软清每一条成员行时，往 `fleet_assignment_operation_log` 追加一行 `share_release_cleared` 记录，带 `shareGroupId` / `groupBatchId` / `vehicleIdBefore` / `driverIdBefore` 等字段（见下节）。
+
+---
+
+## 六、边界行为
+
+- 未登录 → 401（网关拦截）
+- 无 `fleet:group-dispatch:write` 权限 → 403
+- `shareGroupId` 不存在或已解除 → 602108（不是 404）
+- 未传 `survivorPolicy` → 602110（不是 400）
+- `survivorPolicy` 不是三个合法字面量之一 → 不报错，落入隐式默认分支
+- 本接口不依赖外部服务（不查 Feign、不查 MQ），没有"下游降级"路径
+- 🔴 本次修复范围之外的已知缺陷：同一资源同一服务日上的**非成员**在途行仍会被 `RELEASE` 一并软清且同样静默，本次不改
+
+---
+
+## 六.5、枚举 / 数据字典
+
+### survivorPolicy（`ShareSurvivorPolicy`）
+
+**所属字段**: `survivorPolicy`（Query 入参）| **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `RELEASE` | 全部释放 | 释放本关系的**全部幸存成员**的占用，置「待派车」；同槽非成员不动 |
+| `KEEP_LEGAL` | 仅合法保留 | 本关系幸存成员间两两全合法时整槽保留；有冲突则 602111 拒绝回滚 |
+| `REASSIGN` | 释放并待改派 | 真释放冲突成员的占用，派单置「待改派」；成员与非成员冲突时成员让位 |
+
+### operation_type（`AssignmentOperationTypeEnum`）
+
+**新增值** `share_release_cleared`：共用关系解除释放占用
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `share_release_cleared` | 共用关系解除释放占用 | 解除共用关系时，该派单作为成员被释放占用并置「待改派」；详见 detail_json |
+
+**detail_json 结构**（JSON 字段类型）：
+
+```json
+{
+  "shareGroupId": "359915397639704576",
+  "groupBatchId": "2101524283048263681",
+  "serviceDate": "2026-10-03",
+  "resourceType": "VEHICLE",
+  "resourceId": "2065329519232720897",
+  "releaseReason": "共用关系解除",
+  "survivorPolicy": "RELEASE",
+  "vehicleIdBefore": "G",
+  "driverIdBefore": "D001"
+}
+```
+
+---
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 |
+|------|------|------|
+| （无）请求 / 响应字段 | 不变 | 不变——本次未增删改任何字段 |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| `RELEASE` 处置的派车行范围 | 该车/该司机**同一服务日**上**全部**在途行 | 仅**本关系的成员** |
+| `releasedSourceIds` 里可能出现非成员行 | 会 | 不会 |
+| 同槽非成员在途行是否被清成「待派车」 | 会，且无任何信号 | 不会 |
+| 错误码 602111 / 602112 的判定范围 | 整槽全部 claim | 仅「至少一侧是本关系成员」的组合 |
+| 派单操作日志 | 无 `share_release_cleared` 记录 | 新增记录，包含 `vehicleIdBefore` / `driverIdBefore` |
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 否——请求/响应字段、错误码、网关路由全部不变。
+- **前端是否必须同步上线**: 否——管理后台无需改任何代码；但**操作日志展示侧需要注意新字段**。
+- **前端 workaround 清理点**: 无新增 workaround。但请转告使用方——测试环境中那些跨服务日、跨团、从不属于本关系的派单，如果曾因为解除共用关系而被误清，不再会发生这种事了。
+- **给 mmg 的知会重点**：
+  - 「解除共用关系」这个动作的**影响范围**变了——同一车/司机同一服务日上的非成员行不再被波及。
+  - **操作日志时间线上会看到新的 `share_release_cleared` 记录**——必须把这条记录类型加进白名单，否则用户看不到派单是被哪次共用关系解除清掉的。
+- **存量处理**：无需任何 SQL 回滚。测试库中的误清行正常通过改派写口恢复。
+
+---
+
+## 七、不影响范围
+
+- **仅影响**: 管理后台「团期配车」页解除车辆/司机共用关系这一个动作的副作用范围
+- **零影响**:
+  - 请求/响应字段结构、错误码（全部不变，前端无需改代码）
+  - 网关路由配置（既有路由无需改动）
+  - 确认共用关系 `POST .../batches/{groupBatchId}/share-groups`、查询共用关系 `GET .../batches/{groupBatchId}/share-groups` 两个端点
+  - 同一资源同一服务日上**非成员**在途行的处置口径（仍是旧行为，已在本单纳入）
+
+---
+
+## 八、测试环境已验证
+
+**部署**：fleet 于 2026-09-20 22:42 部署到测试服 `192.168.100.236`，落点 `00930f5d6`（`deploy-status.sh` 复核），Nacos 两实例（8087 / 8187）`healthy=true`。
+
+### 网关实测（2026-09-21，真实请求 + 库回读）
+
+夹具：全新团期 `2101690789438570497`，服务日 **2026-10-30**，共用车 G `2065329515961163778`；三户 A / B / C 与团车行均实占该车该日，其中 **A、B 是共用关系 `360081477972660224` 的成员，C 与团车行不是成员**。
+
+```
+DELETE /admin/fleet/group-dispatch/share-groups/360081477972660224?survivorPolicy=RELEASE
+→ 200
+{"data":{"status":"RELEASED","survivorPolicy":"RELEASE",
+  "keptSourceIds":["2101691129806340098","360081478538891264"],
+  "releasedSourceIds":["360081478098489344","360081478333370368"]}}
+```
+
+**① 阳性对照（证明解除真的执行了）**：`releasedSourceIds` 恰为成员 A `360081478098489344` 与 B `360081478333370368`；库回读两行 `assignment_status: assigned → unassigned`，`vehicle_id` / `driver_id` → `NULL`。
+
+**② 阴性对照（本次修复的核心断言）**：非成员 C `360081478538891264` 三字段解除前后**逐一相等**，且不在 `releasedSourceIds` 里：
+
+| | assignment_status | vehicle_id | driver_id |
+|---|---|---|---|
+| 解除前 | assigned | 2065329515961163778 | 2065272147277758465 |
+| 解除后 | assigned | 2065329515961163778 | 2065272147277758465 |
+
+> ⚠️ **为什么必须两条一起看**：只有 ① 的话，「C 没变」与「解除根本没跑起来」在观测上完全相同；而 ① 本身在**修复前也成立**（旧实现同样会释放成员，只是顺手把 C 也清了）——单看 ① 是一个在「修好了」和「没修」两个世界里都为真的读数。
+
+### 后端单元测试 / 集成测试
+
+- `GroupDispatchShareSurvivorServiceTest`：15 条（原 11，**+4**）
+- `GroupDispatchShareReleaseDayScopeIntegrationTest`：4 条（原 2，**+2**，H2 真 Flyway DDL + 真 Mapper）
+- 变异证明：把处置范围回滚成「清整槽」后 **5 条红且全部是新增用例**，既有 71 条全绿；复原后全绿
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#8061](https://git.1814.love:8443/wx/HL/issues/8061)
+- 关联 Issue（前置修复）: [wx/HL#8051](https://git.1814.love:8443/wx/HL/issues/8051)
+- 关联 PR: [wx/HL#8067](https://git.1814.love:8443/wx/HL/pulls/8067)
+- 关联 PR（前置修复）: [wx/HL#8058](https://git.1814.love:8443/wx/HL/pulls/8058)
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8061](https://git.1814.love:8443/wx/HL/issues/8061)
+- **PR**: [#8067](https://git.1814.love:8443/wx/HL/pulls/8067)
+- **Merge commit**: [00930f5d6](https://git.1814.love:8443/wx/HL/commit/00930f5d681e3c3ffb5a6de80c070a5061cae7b2)
+
+### 联系人
+
+- **后端负责人**: @wx
@@ -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
@@ -0,0 +1,509 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7973"
+title: "共用关系确认新增跨常驻车派单确认入参 confirmCrossResident（补记，此前无任何交接件）"
+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: "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"
+---
+
+# fleet: 共用关系确认新增跨常驻车派单确认入参（工单 #7973，补记）
+
+> **存放目录**: 二期（order-v3 标签工单）→ `changelogs-v2/2026-09/`
+>
+> **服务**: hl-fleet-service（8087）
+> **PR**: #7978 ｜ **Issue**: #7973 ｜ **合并提交**: `076654889`
+> **日期**: 2026-09-20（补记；实际合入日为 2026-09-19）
+> **影响范围**: 管理后台「团期配车页」共用关系确认（`POST .../share-groups`），跨常驻车/司机场景下的确认交互
+
+---
+
+## ⚠️ 关键变化
+
+🔴 **这是一份补记 changelog**：#7973/#7978 已于 2026-09-19 16:13 合入 dev-v3，但截至本文撰写（2026-09-20），`docs/` 与 `hl-workflow/` 全仓 grep `7973`/`7978` **零命中**——没有任何交接件提过这个变化。mmg 大概率不知道 `POST .../share-groups` 已经新增了一个请求字段 `confirmCrossResident`，很可能仍按"该端点入参只有 `serviceDate`/`resourceType`/`resourceId`/`members`/`costBearer`/`costBearerOrderId`/`remark` 七项"在对接，一旦线上撞见跨常驻场景，会直接吃 `605036` 且**不知道该传哪个字段重试**。
+
+🔴 **错误文案与页面操作错位，前端必须显式处理，不能指望用户读懂原始错误码**：车务在团期配车页上选的是"一辆共用车"，但 `605036` 的消息说的是"**司机**与车辆不是常驻组合"——被判定跨常驻的司机不是车务选的，是系统按该成员原派单自动带过去的。如果前端把 `605036` 当成普通业务报错直接弹 `message` 原文，运营会去查司机资料，而真正需要处理的动作是"确认跨常驻车派单"。详见「四、契约约束与正确调用方式」。
+
+**在此之前**（`confirmCrossResident` 字段出现之前），确认端点**没有任何入参能表达这个确认**——遇到跨常驻场景的共用关系，字面意义上**永远建不出来**，只能报 `605036` 死循环。本次修复解锁了这条此前完全不可达的成功路径。
+
+---
+
+## 一、背景
+
+`POST /admin/fleet/group-dispatch/batches/{groupBatchId}/share-groups`（团期车辆共用关系确认，`#7444` 落地）第 3 步会把尚未占用的成员改派到共用资源上，走的是既有派单写路径 `AssignmentService#change`。这条写路径上有一道**提示型守卫**（`605036`，源码 `AssignmentResidentPolicy`，早于 `#7973` 就存在：`#4936` 引入、`#5160` 扩展，经 `git log --follow AssignmentResidentPolicy.java` 核实）：目标车已设常驻司机、或被派入的司机本身是别的车的常驻司机时，必须由人显式确认才放行。
+
+问题是：`#7973` 之前，共用关系确认端点自身**完全没有能表达"我确认"这件事的入参**。车务在页面上选好共用车、勾好成员，一提交撞上跨常驻就报 `605036`，而没有任何字段可以带着"确认过了"再重试——这类共用关系客观上**建不出来**，唯一的绕法是联系后端手工处理。
+
+`#7973` 缺陷一在 `ShareGroupConfirmReqVO` 上补了 `confirmCrossResident` 这个可选字段，原样透传到 `change` 命令，并把 `605036` 的消息模板从一句不点名的抽象提示，改成点名"哪条派单 / 跨常驻的具体形态 / 车牌 / 司机姓名"的详细提示。
+
+| 维度 | 改前 | 改后 |
+|------|------|------|
+| 共用关系确认遇到跨常驻场景 | 无字段可确认，永远 `605036`，字面意义上建不出这条关系 | 可传 `confirmCrossResident=true` 重试放行 |
+| `605036` 错误消息 | `"司机与车辆不是常驻组合，请确认跨常驻车派单后重试"`（无占位符，不点名任何具体对象） | `"司机与车辆不是常驻组合，请确认跨常驻车派单后重试（{0}：{1}；车辆 {2}；司机 {3}）"`（点名触发的派单、跨常驻形态、车牌、司机姓名） |
+| 发生频率参考 | - | 据另一次测试服 DB 核查（本次交接未独立复核，见文末核对记录）：`fleet_vehicle` 123 辆中 34 辆设了 `primary_driver_id`（27.6%），`fleet_driver` 116 人中 31 人是某辆车的常驻司机（26.7%）——不是高频，但也绝不罕见，值得做成显式二次确认而不是静默重试或忽略 |
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 确认团期车辆共用关系 | POST | `/admin/fleet/group-dispatch/batches/{groupBatchId}/share-groups` | 修改接口 | 请求体新增可选字段 `confirmCrossResident`；`605036` 错误消息模板新增 4 个占位符 |
+
+---
+
+## 三、接口详情
+
+### 1. 确认团期车辆共用关系 `POST /admin/fleet/group-dispatch/batches/{groupBatchId}/share-groups`
+
+**VO**: `ShareGroupConfirmReqVO → ShareGroupRespVO`
+
+（源码核对：`ShareGroupConfirmReqVO.java:59-83`、`GroupDispatchShareController.java:53-93`、`GroupDispatchShareAdmissionService.java:508-569`、`AssignmentService.java:3198,5656,6316-6324`、`AssignmentErrorCode.java:181-184`、`AssignmentResidentPolicy.java`）
+
+#### 使用场景
+
+车务在团期配车页确认共用关系时调用，端点本身的用途与 `#7444`/`#8013` changelog 描述一致。本次改动是"提交后可能撞 `605036`，撞了之后怎么办"这一条分支：目标共用资源（车或司机）与成员当前实际占用的另一方存在"常驻绑定但不是同一组合"关系时，首次提交会被拒绝；车务确认后，前端需要带着 `confirmCrossResident=true` **原样重发同一份请求**（不是换个端点，不是改动其他字段）。
+
+#### 入参字段表
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long | ✅ | - | 团期主订单 ID |
+| serviceDate / resourceType / resourceId / members / costBearer / costBearerOrderId / remark | Body | - | - | 与 `#7444`/`#8013` changelog 描述完全一致 | 本次未改动 |
+| **confirmCrossResident** | Body | Boolean | ❌ | 不传或 `false` = 不确认；`true` = 确认 | **【本次新增】** 跨常驻车派单的人工确认。成员当前实际司机与本共用资源不是常驻组合时必须传 `true`，否则该成员派入时被 `605036` 拒；不跨常驻时本字段取任何值都不影响结果 |
+
+#### 出参字段表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| shareGroupId / groupBatchId / serviceDate / resourceType / resourceId / status / costBearer / costBearerOrderId / costSourceRefNo / members[] / confirmedBy / confirmedAt / version / history | - | 与 `#7444`/`#8013` changelog 描述完全一致，**本次零变更** |
+
+⚠️ **本次改动完全不影响响应体字段**——`confirmCrossResident` 是纯粹的"放行判据"，成功时响应体里看不出这次是不是带着确认才通过的。
+
+#### 请求示例
+
+首次提交（未带确认，命中跨常驻）：
+
+```json
+{
+  "serviceDate": "2026-09-12",
+  "resourceType": "VEHICLE",
+  "resourceId": 300,
+  "members": [
+    { "sourceType": "GROUP_DISPATCH", "sourceId": 99001 },
+    { "sourceType": "ASSIGNMENT", "sourceId": 500, "admissionIntent": "PENDING_ADMISSION" }
+  ],
+  "costBearer": "GROUP"
+}
+```
+
+车务确认后原样重发（路径参数、`members`、`costBearer` 等**逐字不变**，只加一个字段）：
+
+```json
+{
+  "serviceDate": "2026-09-12",
+  "resourceType": "VEHICLE",
+  "resourceId": 300,
+  "members": [
+    { "sourceType": "GROUP_DISPATCH", "sourceId": 99001 },
+    { "sourceType": "ASSIGNMENT", "sourceId": 500, "admissionIntent": "PENDING_ADMISSION" }
+  ],
+  "costBearer": "GROUP",
+  "confirmCrossResident": true
+}
+```
+
+（路径参数 `groupBatchId=8801`）
+
+#### 响应示例
+
+带确认重试成功后，响应体与 `#7444` changelog 描述的成功响应逐字节一致（`confirmCrossResident` 不出现在响应里）：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "shareGroupId": "77001",
+    "groupBatchId": "8801",
+    "serviceDate": "2026-09-12",
+    "resourceType": "VEHICLE",
+    "resourceId": "300",
+    "status": "ACTIVE",
+    "costBearer": "GROUP",
+    "costBearerOrderId": null,
+    "costSourceRefNo": "SHARE-77001",
+    "members": [
+      { "sourceType": "GROUP_DISPATCH", "sourceId": "99001", "requirementId": null, "orderId": null },
+      { "sourceType": "ASSIGNMENT", "sourceId": "500", "requirementId": "5501", "orderId": "70123" }
+    ],
+    "confirmedBy": "1001",
+    "confirmedAt": "2026-09-12 18:20:33",
+    "version": 1
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+本接口是同步写操作，不存在空数据形态；本次改动不引入新的降级路径。
+
+#### 错误响应
+
+`605036` 跨常驻车派单需确认。下面是 **2026-09-21 10:09:15 经网关真实调用**取得的原始响应（场景构造与放行对照见第八节）：
+
+```json
+{
+  "code": 605036,
+  "message": "司机与车辆不是常驻组合，请确认跨常驻车派单后重试（派单 2101855940422836225：所选车辆与司机均已有其他常驻绑定，继续操作将形成跨常驻车派单；车辆 蒙P303A；司机 宝音德力格尔）",
+  "data": null,
+  "success": false
+}
+```
+
+消息模板（源码 `AssignmentErrorCode.java:181-184`）：
+
+```
+司机与车辆不是常驻组合，请确认跨常驻车派单后重试（{0}：{1}；车辆 {2}；司机 {3}）
+```
+
+| 占位符 | 含义 | 取值 |
+|---|---|---|
+| `{0}` | 触发方——哪条写路径撞上守卫 | 改派走 `派单 {assignmentId}`（源码 `AssignmentService.java:5656`）；新建派单走 `新建派单`（`:3198`） |
+| `{1}` | 跨常驻的具体形态 | **3 种取值，见下表** |
+| `{2}` | 车辆 | 车牌号，如 `蒙P303A` |
+| `{3}` | 司机 | 司机姓名，如 `宝音德力格尔` |
+
+🔴 **`{1}` 一共 3 种取值**（源码 `AssignmentResidentPolicy#messageOf`，逐字照抄）：
+
+| 触发条件 | `{1}` 文案 |
+|---|---|
+| 车已有别的常驻司机 **且** 司机是别的车的常驻司机 | `所选车辆与司机均已有其他常驻绑定，继续操作将形成跨常驻车派单` |
+| 仅「车已有别的常驻司机」 | `所选车辆已有其他常驻司机，继续操作将形成跨常驻车派单` |
+| 仅「司机是别的车的常驻司机」 | `所选司机已有其他常驻车辆，继续操作将形成跨常驻车派单` |
+
+⚠️ 三条文案**都以「，继续操作将形成跨常驻车派单」结尾**。前端若要靠文案区分分支，请匹配前缀、不要匹配全串；更稳的做法是把 `message` 原文直接展示给车务，不做解析——这条消息本来就是写给人看的。
+
+#### 业务边界
+
+- **鉴权、幂等窗口、其余校验规则**均与 `#7444`/`#8013` changelog 描述一致，本次未改动。
+- 🔴 **`confirmCrossResident` 刻意不纳入 `idempotentKey()`**（源码 `ShareGroupConfirmReqVO.idempotentKey()` 与 `#7973` javadoc 明确说明理由）：它不是业务身份的一部分——同一份成员全集确认两次，确认与否不改变"确认了哪些成员共用哪辆车"这个结果；而被 `605036` 拒掉的那一次是**业务失败**，`@Idempotent` 切面在失败路径上会释放 10 秒防重键。⇒ **拿到 `605036` 后带 `confirmCrossResident=true` 可以立刻重试，不会撞"请勿重复提交"防重窗口**，前端不需要等待、也不需要提示"请稍后再试"。
+- **服务端刻意不写死 `true`**（源码 javadoc 原话）：那会让这条路径静默地自动确认所有跨常驻派单，而守卫存在的意义恰恰是让车务**看见**"你正在把车派离它的常驻司机"，写死等于把这道守卫在共用关系这条路径上永久关掉，且调用方不会知道自己确认过什么。前端**不应该**在检测到跨常驻风险后自动带 `true` 重试而不经用户确认。
+- **不跨常驻时本字段取任何值都不影响结果**——前端可以不管这个字段，只在拿到 `605036` 之后才需要处理它，不必在每次提交时都预先判断要不要带它。
+- **同一次确认可能派入多个成员，`605036` 只点名第一个撞上守卫的成员/派单**：`admitPendingMembers`（`GroupDispatchShareAdmissionService.java:534-569`）在循环里逐个成员调 `change`，一旦某个成员触发 `605036` 整个事务立刻回滚（含此前已经处理过的其他成员），前端**不能**假设"确认后重试就一定全部通过"——如果不同成员触发的是不同司机/车辆的跨常驻，可能需要多轮"提交→拿到 605036→确认→重试"才能全部放行完。
+
+---
+
+## 四、契约约束与正确调用方式
+
+> 本节只写后端接受/拒绝 payload 的规则，不写与本次改动无关的既有规则（完整规则见 `#7444`/`#8013` changelog）。
+
+### 🔴 车务在页面上选的是"车"，`605036` 说的是"司机"——两者不是同一个对象
+
+`resourceType=VEHICLE` 时，`admitPendingMembers` 把成员改派到共用资源的逻辑是（源码 `GroupDispatchShareAdmissionService.java:550-565`）：
+
+```
+newVehicleId = resourceType == VEHICLE ? resourceId : row.getVehicleId()   // 车务选的共用车
+newDriverId  = resourceType == DRIVER  ? resourceId : row.getDriverId()    // 成员原来的司机，不是车务选的
+```
+
+也就是说：车务只选了"这辆车"，`newDriverId` 是系统按该成员**原派单**上的司机原样带过去的。守卫判的是"这名司机与这辆车是不是常驻组合"——于是"选一辆共用车"这个动作，撞上 `605036` 时，撞的原因写在一个车务根本没有主动选过的司机身上。`resourceType=DRIVER`（共用司机）时反过来：车务选的是司机，车是成员原来的车。
+
+⇒ **前端不应该把 `605036` 的 `message` 原文直接展示给运营**（会让人去查司机资料而不是理解"车辆-司机组合冲突"），至少要在文案上补一句解释这是"车辆-司机常驻组合冲突，不是司机本身有问题"。
+
+### 跨常驻的两种独立形态（或关系，缺一不可全防）
+
+守卫命中的条件是下列任一条成立即判"跨常驻"（源码 `AssignmentResidentPolicy.evaluate`）：
+
+| 形态 | 判定条件 | `605036` 消息片段 |
+|---|---|---|
+| 车侧越界 | 目标车辆已设 `primary_driver_id`，且与被派入成员的当前司机不是同一人 | "所选车辆已有其他常驻司机" |
+| 司机侧越界 | 被派入成员的当前司机本身是**别的车**的常驻司机 | "所选司机已有其他常驻车辆" |
+| 两者皆是 | 车侧、司机侧同时越界 | "所选车辆与司机均已有其他常驻绑定" |
+
+⚠️ **两条是"或"的关系**：共用车没设常驻司机（`primary_driver_id` 为空）只躲开车侧那一条，司机侧照样可能触发——不能靠"挑一辆没设常驻司机的车"来规避这道守卫。
+
+### 建议的前端交互：先调 `precheck` 探路，别盲提交吃错误码
+
+`POST /admin/fleet/assignments/precheck`（`#7444` 之前就存在，本次未改动其契约）**不取锁、不写库、恒成功**（源码类注释："只读、不抛异常、不写、不取锁"，`@Transactional(readOnly = true)`），跨常驻组合会在响应的 `warnings[]` 里产出一条 `type="cross_resident"` 的提示项（`PrecheckRespVO.WarningItemVO{type, msg}`），不影响 `conflict`/`conflicts[]`（跨常驻是 warning 不是 conflict，不会被判定为阻断）。
+
+🔴 **precheck 的调用方式有个坑，Swagger 里一个字都没写**：它的入参是"一辆车 + 一名司机"（`PrecheckReqVO{vehicleId, driverId, startDate, endDate, ...}`），而共用关系确认里**司机不是车务选的**（见上文）。因此正确调法是：
+
+- **`resourceType=VEHICLE`**（共用车）：对**每个待派入成员**分别调一次 `precheck`，入参 `vehicleId=共用车 ID`、`driverId=该成员当前司机 ID`
+- **`resourceType=DRIVER`**（共用司机）：反过来，`vehicleId=该成员当前车辆 ID`、`driverId=目标共用司机 ID`
+
+成员当前司机/车辆 ID 前端可以从既有只读端点拿到，不需要额外新接口：
+- `GET /admin/fleet/group-dispatch/batches/{groupBatchId}/overview` → `GroupDispatchOverviewVehicleVO.driverId`
+- `GET /admin/fleet/group-dispatch/resource-schedule` → `ResourceScheduleItemVO.driverId`
+
+逐成员探完一遍 `precheck` 后，若任一成员命中 `cross_resident` warning，就在提交前弹出"存在跨常驻车派单，是否确认？"的二次确认框，用户确认后提交时才带 `confirmCrossResident=true`——这样可以避免车务盲提交后才第一次看到 `605036`。
+
+### ✅ 正确 / ❌ 错误 payload 对照
+
+| 场景 | payload | 结果 |
+|---|---|---|
+| ✅ 不跨常驻 | 不传 `confirmCrossResident` | 200，正常放行（本字段不影响结果） |
+| ✅ 跨常驻，首次提交未确认 | 不传或 `confirmCrossResident=false` | `605036`，`fleet_assignment` 零写入，整个事务回滚 |
+| ✅ 跨常驻，车务已确认 | `confirmCrossResident=true`，其余字段与首次提交逐字相同 | 200，放行；10 秒防重键已在失败路径释放，无需等待 |
+| ❌ 期望服务端自动确认（不传字段，指望后端默认放行） | 同"未确认"payload | **无效**——服务端刻意不写死 `true`，不传就是不确认，会持续收到 `605036` |
+| ❌ 收到 `605036` 后改了其他字段（比如换了 `resourceId`）才重试 | 与首次不同的请求体 | 这是另一次业务操作，不是"确认重试"——是否命中跨常驻需要重新判定，不能假设加了 `confirmCrossResident=true` 就万能放行 |
+
+---
+
+## 五、数据库行为
+
+`confirmCrossResident` **不落库、不新增任何列**——它是运行时透传给 `AssignmentService#change` 命令的确认标志，仅用于守卫放行判断，本身不持久化。
+
+| 场景 | 改前 | 改后 |
+|---|---|---|
+| 跨常驻且未确认 | `change()` 内部即时抛 `605036`，`fleet_assignment` 零写入，`confirmInTransaction` 整个事务回滚 | 同左，行为不变——差异仅在错误消息文案更详细 |
+| 跨常驻且 `confirmCrossResident=true` | **不存在这个入参，无法达成**——永远停在上一行的 `605036`，`fleet_assignment` 永远零写入 | 守卫放行，`fleet_assignment` 走既有"旧切片转 `canceled` + 新行 `INSERT`"逻辑正常写入（该写入逻辑本身不是本次改动，`#7444` 起就有） |
+| 非跨常驻的普通共用确认 | 不受影响 | 不受影响 |
+
+---
+
+## 六、边界行为
+
+- 未登录/网关未透传角色 → 401（网关拦截），既有行为
+- 其余既有错误码（602100~602112 段）均未变动
+- 老数据兼容：本次改动不涉及任何存量数据结构，纯粹是入参层的新增可选字段 + 错误消息模板调整
+
+---
+
+## 六.5、枚举 / 数据字典
+
+### `confirmCrossResident`（`ShareGroupConfirmReqVO.confirmCrossResident`）
+
+**所属字段**: `confirmCrossResident` | **类型**: `Boolean`（可空）
+
+| 值 | 说明 |
+|----|------|
+| `null` / 不传 | 不确认（默认态，与传 `false` 行为完全一致） |
+| `false` | 显式不确认，行为与不传一致 |
+| `true` | 确认跨常驻车派单，撞上守卫时放行 |
+
+### `605036` 消息占位符（`AssignmentErrorCode.CROSS_RESIDENT_CONFIRMATION_REQUIRED`）
+
+| 占位符 | 含义 | 取值示例 |
+|---|---|---|
+| `{0}` | 触发方描述 | `派单 500`（改派场景）/ `新建派单`（新建场景，共用关系确认走的是改派场景） |
+| `{1}` | 跨常驻的具体形态 | `所选车辆已有其他常驻司机` / `所选司机已有其他常驻车辆` / `所选车辆与司机均已有其他常驻绑定` |
+| `{2}` | 车牌 | `蒙B-30000`（缺车牌时退回 `ID={vehicleId}`） |
+| `{3}` | 司机姓名 | `李师傅`（缺姓名时退回 `ID={driverId}`） |
+
+### `warnings[].type`（`PrecheckRespVO.WarningItemVO.type`，precheck 端点既有字段，本次未新增，仅补充说明供前端建议交互使用）
+
+| 值 | 说明 |
+|----|------|
+| `cross_resident` | 跨常驻（本篇涉及的类型） |
+| `seats_short` | 座位不足 |
+| `vehicle_unavailable` / `driver_unavailable` | 车/司机不可用 |
+| `license_expired` | 驾照过期 |
+| `veh_inspect_expired` / `veh_insure_expired` | 车辆年检/保险过期 |
+
+---
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 |
+|------|------|------|
+| `ShareGroupConfirmReqVO.confirmCrossResident` | 不存在 | **新增**，可选 `Boolean`，默认语义为不确认 |
+| `605036` (`CROSS_RESIDENT_CONFIRMATION_REQUIRED`) 消息模板 | `"司机与车辆不是常驻组合，请确认跨常驻车派单后重试"`（静态文本，无占位符） | `"司机与车辆不是常驻组合，请确认跨常驻车派单后重试（{0}：{1}；车辆 {2}；司机 {3}）"`（4 个占位符，点名触发方/形态/车牌/司机） |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| 共用关系确认遇到跨常驻场景 | **无法完成**——没有字段可确认，永远 `605036`，唯一出路是联系后端手工处理 | 可传 `confirmCrossResident=true` 二次提交放行，业务上可自助完成 |
+| `605036` 报错时车务能否判断该怎么办 | 不能——消息不点名是哪条派单/哪种越界/哪辆车/哪个人 | 能——消息里逐一点名，且 create/change 两条路径同一份口径 |
+| 带确认重试是否会撞 10 秒防重窗口 | N/A（无法重试） | 不会——`confirmCrossResident` 不纳入 `idempotentKey()`，且失败路径释放防重键 |
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 否——新增的是可选字段，旧前端不传该字段时行为与改动前逐字节一致（跨常驻场景下依旧收到 `605036`，只是消息文案变详细了）
+- **前端是否必须同步上线**: **是**——跨常驻场景此前是纯粹的死路（无法建出这类共用关系），本次解锁了一条此前完全不可达的成功路径；前端不接入就意味着车务在这类场景下永远卡在 `605036`、无法完成共用关系确认，运营会持续遇到"报错但不知道怎么处理"的问题。若前端此前对 `605036` 的 `message` 做过精确匹配/正则解析（不太可能但不能排除），需要检查是否受消息模板变化影响
+- **前端 workaround 清理点**: 若此前车务遇到跨常驻场景的 workaround 是联系后端手工处理（比如手工改库建关系），本次上线后应当撤除该 workaround，改走"precheck 探测 → 二次确认弹窗 → 带 `confirmCrossResident=true` 提交"的正常流程
+
+---
+
+## 七、不影响范围
+
+- **仅影响**: `POST .../share-groups` 请求体新增字段 `confirmCrossResident`，以及 `605036` 错误消息的文案（消息模板变化，错误码本身不变）
+- **零影响**:
+  - 请求体其余字段（`serviceDate`/`resourceType`/`resourceId`/`members`/`costBearer`/`costBearerOrderId`/`remark`）**零变更**
+  - 响应体 `ShareGroupRespVO` **零变更**，`confirmCrossResident` 不出现在任何响应里
+  - `GET .../share-groups`（查询）、`DELETE .../share-groups/{shareGroupId}`（解除）两个端点**零改动**——本次 PR 确实触及 `GroupDispatchShareController`，但那 14 行全部落在 `confirm` 端点的接口文档注释里（`@ApiOperation` 的 notes），GET/DELETE 的方法签名与请求/响应契约逐字未动
+  - `precheck`/`candidates` 两个读口的请求/响应契约**本次未改动**——`cross_resident` 这个 `warnings[].type` 值早在 `#7973` 之前就存在（`AssignmentResidentPolicy` 由 `#4936` 引入、`#5160` 扩展），不是本次新增
+  - 非共用关系场景下的普通派车/改派（`create`/`change` 两个端点自身的请求/响应契约）**零变更**，跨常驻守卫判定逻辑本身也没变，只是错误消息更详细
+  - 无新增 DB 表/列/索引；`confirmCrossResident` 不落库
+  - `#8013`（共用关系确认历史）、`#7988`（团期配车刷新观测口）两篇的改动内容**互不影响**
+
+---
+
+## 八、测试环境已验证
+
+**环境**：测试服；`hl-fleet-service` 部署点 `51571c58a`（该提交包含引入 `confirmCrossResident` 的 `076654889`，2026-09-19，已用 `git merge-base --is-ancestor` 核过祖先关系）。
+**取证时刻**：2026-09-21 10:09:15 / 10:09:17 / 10:10:22（下列三次调用的实际发生时刻）。
+**取证方式**：经网关真实调用，非单元测试、非 Mock。原始请求/响应全文见执行台账（会话内保留）。
+
+### 8.1 场景构造
+
+为得到「成员司机 ≠ 目标车辆常驻司机」这一前置，按以下顺序造数（全部为新建，未复用任何存量数据）：
+
+1. 新建团期批次 `groupBatchId=2101855487131877378`（服务日 2026-10-16）；
+2. 该团期下建 2 个子订单 A / B，各自提交用车需求（服务日 2026-10-16 ~ 10-18）；
+3. 子订单 A 派单至 车 `蒙A-T7777` + 司机 `宝音德力格尔`(D1)，子订单 B 派单至 车 `蒙P304A` + 司机 `P3测试司机04`；
+4. 取第三辆车 `蒙P303A`(`vehicleId=2089686351917039618`) 作为共用目标车，其常驻司机为 `2089686350138630146`，**与 D1 不同** —— 跨常驻条件成立。
+
+### 8.2 未传 `confirmCrossResident` → 拦截（605036）
+
+`POST /admin/fleet/group-dispatch/batches/2101855487131877378/share-groups`，请求体不含 `confirmCrossResident` 字段：
+
+```json
+{
+  "serviceDate": "2026-10-16",
+  "resourceType": "VEHICLE",
+  "resourceId": 2089686351917039618,
+  "members": [
+    { "sourceType": "ASSIGNMENT", "sourceId": 2101855940422836225 },
+    { "sourceType": "ASSIGNMENT", "sourceId": 2101856068395245569 }
+  ],
+  "costBearer": "GROUP",
+  "remark": "cross-resident probe"
+}
+```
+
+响应（HTTP 200，业务码 605036）：
+
+```json
+{
+  "code": 605036,
+  "message": "司机与车辆不是常驻组合，请确认跨常驻车派单后重试（派单 2101855940422836225：所选车辆与司机均已有其他常驻绑定，继续操作将形成跨常驻车派单；车辆 蒙P303A；司机 宝音德力格尔）",
+  "data": null,
+  "success": false
+}
+```
+
+> 报文中点名的「车辆 蒙P303A；司机 宝音德力格尔」与 8.1 构造的跨常驻组合一致，可据此确认拦截确实由该组合触发，而非其他前置校验。
+
+### 8.3 传 `confirmCrossResident: true` → 放行（200）
+
+同一请求体追加 `"confirmCrossResident": true`，其余字段逐字不变：
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "shareGroupId": "360246074662850560",
+    "groupBatchId": "2101855487131877378",
+    "serviceDate": "2026-10-16",
+    "resourceType": "VEHICLE",
+    "resourceId": "2089686351917039618",
+    "status": "ACTIVE",
+    "costBearer": "GROUP",
+    "costSourceRefNo": "SHARE-360246074662850560",
+    "members": [
+      { "sourceType": "ASSIGNMENT", "sourceId": "360246074935480320",
+        "requirementId": "2101855514109640706", "orderId": "2101855487085740033" },
+      { "sourceType": "ASSIGNMENT", "sourceId": "360246075224887296",
+        "requirementId": "2101855521428647938", "orderId": "2101855500247465986" }
+    ],
+    "confirmedBy": "2101000047826030594",
+    "confirmedAt": "2026-09-21 10:09:17",
+    "version": 0
+  },
+  "success": true
+}
+```
+
+**两次调用唯一的差异就是这一个字段**——同一批 `members`、同一 `resourceId`、同一 `serviceDate`，前者 605036、后者 200。
+
+### 8.4 副作用核验（独立口径）
+
+响应里 `members[].sourceId` 已由原派单 id 变为改派后的新派单 id（`360246074935480320` / `360246075224887296`）。另经两条互相独立的读口复核：
+
+- `POST /admin/fleet/assignments/candidates` 的 `canonicalSnapshot.cells`：2026-10-16 当天的 cell `vehicleId` 已变为 `2089686351917039618`（目标共用车），`driverId` 仍为 D1 —— **本端点只改车、不改司机**，与三节接口说明一致；
+- 直查 `fleet_assignment`：上述两个新派单 id 的 `vehicle_id` 均为 `2089686351917039618`、`service_date` 为 `2026-10-16`，与网关响应逐字吻合。
+
+### 8.5 现场清理
+
+`DELETE /admin/fleet/group-dispatch/share-groups/360246074662850560?survivorPolicy=RELEASE`（2026-09-21 10:10:22）：
+
+```json
+{
+  "code": 200, "message": "成功",
+  "data": {
+    "shareGroupId": "360246074662850560",
+    "status": "RELEASED",
+    "survivorPolicy": "RELEASE",
+    "keptSourceIds": [],
+    "releasedSourceIds": ["360246074935480320", "360246075224887296"],
+    "pendingReassignSourceIds": []
+  },
+  "success": true
+}
+```
+
+### 8.6 随 PR #7978 合入的单测（本轮未重新执行）
+
+⚠️ 下列是**代码仓内的断言意图**，不是本轮的执行结果；本篇的实测证据是 8.2–8.5。
+之所以仍然列出，是因为其中两条覆盖了**网关取证没有覆盖到**的分支（已标 ⭐）：
+
+```
+AssignmentServiceTest（新增 2 条）
+  change_crossResidentByDriverBoundToAnotherVehicle_throws605036
+    → 只有「司机是别的车的常驻司机」这一侧成立时也抛 605036（不需要车侧同时成立）；
+       并断言 assignmentMapper 的 cancelActiveRowsByIds / insert 均未被调用
+  change_crossResidentByDriverBoundToAnotherVehicle_confirmed_succeeds
+    → 同场景带 confirmCrossResident=true 放行；
+       ⭐ 断言 vehicleService.rebindResidentVehicleFromDriverSide 未被调用，
+          即「确认跨常驻」不会顺手改写司机的常驻绑定（网关取证未覆盖此点）
+
+GroupDispatchShareAdmissionServiceTest（新增 4 条）
+  confirm_confirmCrossResidentTrue_isPassedThroughToChange
+    → true 原样透传到 change 命令
+  confirm_confirmCrossResidentFalse_isPassedThroughAsFalse
+    → ⭐ 显式传 false 时原样透传、不会被悄悄改写成 true
+       （网关取证只验了「不传」与「传 true」两种，没验显式 false）
+  confirm_crossResidentWithoutConfirmation_605036PropagatesOut
+    → 605036 原样抛出，不被本层吞掉、也不被翻译成 602xxx
+  confirm_crossResidentConfirmed_passesTheSameGuard
+    → 与上一条同一夹具，仅多带一个 true 即放行
+```
+
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#7973](https://git.1814.love:8443/wx/HL/issues/7973)
+- 关联 PR: [wx/HL#7978](https://git.1814.love:8443/wx/HL/pulls/7978)（squash 合并至 dev-v3 @`076654889`）
+- 共用关系确认端点完整契约见 `#7444` changelog（`changelogs-v2/2026-09/21_7444_团期配车就绪门禁与车辆共用关系-修改接口-管理后台.md`，由团期车务会话维护与推送）
+- 共用关系确认历史的另一处补丁见 `#8013` changelog（`changelogs-v2/2026-09/20_8013_共用关系确认历史补记成本承担方变更-修改接口-管理后台.md`）
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#7973](https://git.1814.love:8443/wx/HL/issues/7973)
+- **PR**: [#7978](https://git.1814.love:8443/wx/HL/pulls/7978)
+- **Merge commit**: [076654889](https://git.1814.love:8443/wx/HL/commit/076654889f82eeab9b761b57db8108ba46137298)
+
+### 联系人
+
+- **后端负责人**: wx(GIT)
+- **前端负责人**: mmg
@@ -0,0 +1,452 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7980"
+title: "司机险年保台账 upsert/作废两写口补同一把 @Lock4j name（driver-ins:ledger），新增可重试冲突码 100503；投保写口同键但刻意不互斥（driver-ins:purchase），未新增错误码"
+consumer: "internal"
+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: "PR #8072 已 squash 合并 dev-v3（合并提交 8bf9c520c，#7980 AC-6，工单最后一条验收项）。✅ 已部署：2026-09-20 23:43 hl-order-service-v3 测试服滚动更新两实例，8186/8086 分别 12/13 秒起监听，deploy-backend.sh 报 rolling deploy complete；部署记录行 hl-order-service-v3 <- dev-v3 @ 8bf9c520c，即运行版本就是本次合并提交本身（非祖先链判据，是精确相等）。🔴 backend_status=deployed 但本文档没有做任何功能调用取证：没有实际调过 driver-annual/upsert、driver-annual/{driverId}/invalidate、driver-purchase 三个端点里的任何一个，100503 在测试服上一次都没有触发过——这是「没测」不是「测过不会触发」。理由：三个端点都是 /v3/internal/**，不经网关，唯一合法入口是 fleet 经 Feign 调用，手动触发需要真实写司机年保台账/投保行（台账 upsert 会更新或新插 insurance_order 行，投保会触发保游远程出单 HTTP 与真实扣费），本次评估认为不值得为了取一次 100503 读数去污染真实业务台账，故互斥本身只由代码层面的落库级并发 IT（Lock4jSharedNameConcurrencyIT）与按运行期锁键形状反查的契约用例（Lock4jSharedNameContractTest/Lock4jNameGroupGateTest）覆盖，这些是 PR 正文所载的本地/CI 证据，不是本 changelog 在测试服上做的验证。gateway_status=not_required：三个端点路径/方法零变化，且路径前缀 /v3/internal/，InternalInsuranceController 类注释自陈『不经过认证拦截器（/v3/internal/** 已排除）』，与网关路由无关。frontend_status=not_required，结论+依据：①本组无 C 端——全仓 grep driverInsuranceFeignClient 的 upsertAnnualPolicy/invalidateAnnualPolicy/driverPurchase 三个方法调用点，命中的调用方全部在 hl-fleet-service 且全部挂在 /admin/fleet/drivers 前缀下（DriverInsuranceController.java:33 RequestMapping、:56 purchase 端点、:80 insureAnnual 端点均在此前缀），没有任何 mp/小程序侧调用；②唯一可能把新失败码传导到 hl-ui 的路径是 DriverInsuranceService.java:352-353 那次同步 invalidateAnnualPolicy 调用（购买年险时若旧档案是 MANUAL 年保，出单成功后同步作废旧台账），但已逐行核实：该调用若失败（含本次新增的 100503），被 DriverInsuranceService.java:226 的 catch(AnnualBindingRollbackQueuedException) 捕获，统一重新包装成既有错误码 600206（DriverErrorCode.ANNUAL_BIND_FAILED，:241-242），即便触发的具体原因是 100503，hl-ui 侧看到的仍是它已经在处理的 600206，没有新码需要 hl-ui 适配。mmg 前端复核 2026-09-21:维持 not_required。driver-annual/driver-purchase//v3/internal 在 hl-admin src 全仓零命中,三端点不经网关前端不可达;唯一间接路径(投保成功后同步作废旧 MANUAL 台账失败)已被 fleet 侧重包装为既有 600206,而 600206 前端已显式处理(DriverEditModal.vue:1300/1339 关弹窗并刷新防重复投保、insurance/orders/index.vue:1040 特判收敛、driverInsurancePurchase.js 导出常量并有 spec 覆盖),新增 100503 无触达 hl-ui 的路径,零改动。"
+updated_at: "2026-09-21"
+base: "dev-v3"
+---
+
+# order-v3: 司机险年保台账 upsert/作废两写口补同一把 @Lock4j name，新增可重试冲突码 100503
+
+> **存放目录**:
+> - 一期(v2,无 `order-v3` 标签的工单)→ `changelogs/{YYYY-MM}/`
+> - 二期(v3,`order-v3` 标签的工单)→ `changelogs-v2/{YYYY-MM}/`
+>
+> **服务**: hl-order-service-v3（消费方为 hl-fleet-service，经 Feign 调入，均在 fleet `/admin/fleet/drivers/**` 之下，无 C 端）
+> **PR**: #8072
+> **Issue**: #7980（AC-6，最后一条验收项）
+> **日期**: 2026-09-20
+> **影响范围**: `/v3/internal/insurance/driver-annual/upsert`、`/v3/internal/insurance/driver-annual/{driverId}/invalidate` 两个 internal 端点新增可重试冲突码；`/v3/internal/insurance/driver-purchase` 端点锁的 Redis 键名变化但外部行为、错误码集合均未变化
+
+---
+
+## ⚠️ 关键变化（非必须,本版与上版行为不同 / 纠错 / 撤销时必写）
+
+- `InsuranceManageService.upsertDriverAnnualPolicy`、`InsuranceManageService.invalidateDriverAnnualPolicy`、`InsuranceCreateService.purchaseForDriver` 三个方法写着**逐字相同**的锁键 `'driver-ins:' + driverId`（三种不同的 SpEL 写法，字面上不容易看出是同一组），却都**没写 `name`**——lock4j 缺省 `name` 时用「类全限定名+方法名」拼进 Redis 键，于是三处此前各持一把互不相干的锁。
+- 🔴 **本次的结论与工单原表不同：不是把三处并成一把锁，而是拆成两个域**：
+  - `upsertDriverAnnualPolicy` 与 `invalidateDriverAnnualPolicy` 补同一个显式 `name = "driver-ins:ledger"`——**这两者是真缺陷，必须互斥**：`upsert` 第 2 步 `updateById(existing)` 是全行盲写（`existing` 带着查询时的 `status=INSURED` 一起写回），`InsuranceOrder` 无 `@Version`、`insurance_order` 表无唯一索引；`upsert` 与 `invalidate` 交错执行会把刚作废的单静默复活成 `INSURED` 且不补任何状态流水——这个终态**任何合法串行序都产不出来**，打破的是"调用返回后该司机无活动 MANUAL 年险单"这条后置条件，而 fleet 正据此把司机档案的 `insurance_type` 切走。
+  - `purchaseForDriver` 补的是**另一个**显式 `name = "driver-ins:purchase"`，**自成一域、刻意不与台账两口互斥**：它不写台账行，只在重叠校验里**读**台账行；而 `upsert` 本身不做保障期重叠校验（年保台账记的是司机在外面已买好的年险，系统没有立场拒绝登记），所以"年单与按天单保障期重叠"这个终态在合法串行序 `purchase → upsert` 下本来就可达，把 `purchase` 并进同一把锁**消不掉它**，只会把"`upsert` 并发成功"换成"`upsert` 抢锁超时拿 100503 后重试、终态一模一样"，白白给一条 MQ 驱动的写口加一个失败码。
+- 🔴 **`purchaseForDriver` 没有新增任何可能返回的错误码**：它的锁语义与改前完全等价（同司机投保动作仍然自我串行化，因为默认 `name` 对单方法本来就够用），唯一变化是它在 Redis 里的键字符串从「类全名+方法名」变成显式的 `driver-ins:purchase`。**不要把「三个方法都补了 name」读成「三个端点都新增了 100503」**——只有 `upsert`/`invalidate` 这两口之间此前不互斥、本次补上后才有了新的失败路径。
+- **本组无 C 端**：三个端点都在 `/v3/internal/insurance/**`，只有 hl-fleet-service 经 Feign 调入，且 fleet 侧全部挂在 `/admin/fleet/drivers/**` 之下（详见 status_note 与「七、不影响范围」）。
+
+---
+
+## 一、背景
+
+`DriverInsuranceLockConstants`（本次新建）把设计意图写死成两条互相独立的判据：① `Lock4jSharedNameContractTest` 按运行期锁键形状反查全类，钉死三个方法成员与"台账两口同名、投保口异名"这条关系；② `Lock4jNameGroupGateTest` 的 `SPLIT_BY_DESIGN` 条目钉死这一串键上允许出现的 `name` 集合恰好是 `{driver-ins:ledger, driver-ins:purchase}`——第四个方法只要漏写 `name`，集合里就会冒出空串，门禁当场变红。这两条是 PR 正文所载的本地/CI 证据（`Lock4jSharedNameConcurrencyIT` 4 例、`Lock4jNameGroupGateTest` 7 例、`Lock4jSharedNameContractTest` 5 例），本 changelog 未在测试服上重跑，仅作背景引用。
+
+PR 正文另确认了两条会动摇初始判断但不改变最终结论的事实：① fleet 侧另有一把按司机的锁 `fleet:insurance-task:lifecycle:{driverId}`（`DriverAnnualLedgerOutboxEffectService.java:42-49`、`DriverService.java:640`），台账 `upsert`/`invalidate` 在 fleet 侧本来就是串行触发的——但 order-v3 是数据的主人，`/v3/internal/insurance/driver-annual/**` 是对外契约端点，不能把不变量寄在调用方的自觉上；②测试服日志分母是 0（该组两个方法在采样窗口内一次都没被调用过），据此不能得出"没有告警=没有缺陷"的结论。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 司机年保台账 upsert（内部） | POST | `/v3/internal/insurance/driver-annual/upsert` | 新增可能返回的错误码 | 抢锁超时返 100503，与 §2 共用 `driver-ins:ledger` 锁 |
+| 2 | 司机年保台账作废（内部） | POST | `/v3/internal/insurance/driver-annual/{driverId}/invalidate` | 新增可能返回的错误码 | 与 §1 共用 `driver-ins:ledger` 锁 |
+| 3 | 司机险投保（内部） | POST | `/v3/internal/insurance/driver-purchase` | 无外部可观察变化 | 锁语义与改前完全等价，仅 Redis 键名从默认值改为显式 `driver-ins:purchase`，**未新增错误码** |
+
+---
+
+## 三、接口详情
+
+### 1. 司机年保台账 upsert（内部） `POST /v3/internal/insurance/driver-annual/upsert`
+
+**VO**: `DriverAnnualPolicyUpsertDTO → Long`
+
+#### 使用场景
+
+fleet 车务在司机档案页录入/编辑「annual（年保）」保险类型时，afterCommit 联动调本端点把年保信息写进 order-v3 的台账：按 `(bizType=DRIVER, bizId=driverId, source=MANUAL, status=INSURED)` 查活动单，有则更新保单号/保费/起止/投保人，无则插入新单。本次改动不涉及入参/出参字段，只新增一条「被 §2 作废端点占用同一把锁」的失败分支。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| driverId | Body | Long | ✅ | `@NotNull` | 司机 ID，落 `InsuranceOrder.bizId`（`bizType=DRIVER`） |
+| driverName | Body | String | - | - | 司机姓名，落 `policyHolderName` 投保人留痕 |
+| policyNo | Body | String | ✅ | `@NotBlank` | 司机自有年保单真实保单号，落 `extPolicyNo` |
+| annualPremium | Body | BigDecimal | ✅ | `@DecimalMin(0, inclusive=false)` | 年保险费（元），必须大于 0，落 `totalPremium` |
+| startDate | Body | LocalDate | ✅ | 不得晚于 endDate | 年保起始日，跨字段校验在提供方（非法返 540225） |
+| endDate | Body | LocalDate | ✅ | - | 年保结束日 |
+| adminId | Body | Long | - | fleet 透传，可空=系统 | 操作管理员 ID，审计留痕用 |
+
+#### 出参 `Result<Long>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data | Long（雪花 ID，超出 JS 安全整数范围时 JSON 序列化为字符串，本项目全局 Jackson 策略） | 台账单 ID（`insuranceOrderId`），fleet 回写 `fleet_driver.insurance_order_id` 用 |
+
+#### 请求示例
+
+```json
+{
+  "driverId": "1934567890123456789",
+  "driverName": "周师傅",
+  "policyNo": "PICC-2026-77721",
+  "annualPremium": "3800.00",
+  "startDate": "2026-01-01",
+  "endDate": "2026-12-31",
+  "adminId": 1
+}
+```
+
+#### 响应示例
+
+```json
+{ "code": 200, "message": "成功", "data": "1934567890200777", "success": true }
+```
+
+#### 空数据 / 降级响应
+
+本接口无「空数据」概念（成功恒返回台账单 ID，有则更新既有单号，无则插入新单号）。无降级路径。
+
+#### 错误响应
+
+```json
+{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false }
+```
+
+| code | 触发条件 |
+|------|----------|
+| 400 | 参数校验失败（`driverId`/`policyNo`/`annualPremium`/`startDate`/`endDate` 缺失或格式非法） |
+| 540225 | 年保起始日晚于结束日 |
+| **100503（本次新增）** | 抢锁等待超过 3 秒（`acquireTimeout`，本组 `@Lock4j` 未显式设置，取 lock4j-core 注解默认值 3000ms；本次另一写口——§2 作废端点——正持有 `driver-ins:ledger` 锁），**可重试** |
+
+#### 业务边界
+
+- 天然幂等，无 `@Idempotent`：多次以相同 `driverId` upsert 只更新同一张活动单，不重复开单。
+- 抢锁失败（100503）时该次请求未进入方法体，零写入——不会出现"读到旧快照后半途更新"的中间态。
+- 纯本地写库，事务内无同步 Feign/MQ（区别于 §3 投保端点持锁期间含远程出单 HTTP）。
+- 历史多张残留（脏数据）时只更新 `createTime` 最新一张，其余由 §2 全量兜底清理，本次未改此行为。
+- 老数据兼容：无字段变化。
+
+---
+
+### 2. 司机年保台账作废（内部） `POST /v3/internal/insurance/driver-annual/{driverId}/invalidate`
+
+**VO**: `无 ReqVO（纯路径参数，无请求体） → Void`
+
+#### 使用场景
+
+fleet 车务把司机档案的保险类型从「annual（年保）」切走时，afterCommit 联动调本端点把该司机全部 MANUAL 活动年险单置 `CANCELLED`（历史脏数据多张残留时全量兜底清理，正常路径只有一张）。无活动单时幂等返回成功。本次改动不涉及入参/出参，只新增一条「被 §1 upsert 端点占用同一把锁」的失败分支。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| driverId | Path | Long | ✅ | - | 司机 ID |
+
+#### 出参 `Result<Void>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data | null | 无返回数据 |
+
+#### 请求示例
+
+```http
+POST /v3/internal/insurance/driver-annual/1934567890123456789/invalidate
+```
+
+（跨服务 Feign 调用，无请求体。）
+
+#### 响应示例
+
+```json
+{ "code": 200, "message": "成功", "data": null, "success": true }
+```
+
+#### 空数据 / 降级响应
+
+该司机无活动 MANUAL 年险单时同样返回 200 成功（幂等短路，不报错，覆盖"保险类型反复切换"与"从未录入 annual"两种场景）。无降级路径。
+
+#### 错误响应
+
+```json
+{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false }
+```
+
+| code | 触发条件 |
+|------|----------|
+| **100503（本次新增）** | 抢锁等待超过 3 秒（`acquireTimeout` 默认 3000ms；§1 upsert 端点正持有 `driver-ins:ledger` 锁），**可重试** |
+
+（本端点自身无其他业务校验分支——无活动单不算错误，是幂等成功。）
+
+#### 业务边界
+
+- 天然幂等，无 `@Idempotent`：重复触发/从未开单均不报错。
+- 抢锁失败（100503）时该次请求未进入方法体，零写入——这正是本次要补的缺口：改前 `upsert` 可能用陈旧快照把刚被本方法置 `CANCELLED` 的单全行盲写回 `INSURED` 且不留流水，改后二者不再能交错执行。
+- 不调保游 `CancelIns`（手工单无外部单号），纯本地翻态，与 `cancel`（按保单 PK 退保，走保游）是两条不同路径。
+- 老数据兼容：无字段变化。
+
+---
+
+### 3. 司机险投保（内部） `POST /v3/internal/insurance/driver-purchase`
+
+**VO**: `DriverPurchaseInsuranceRequest → DriverInsurancePolicyDTO`
+
+#### 使用场景
+
+fleet 车管在司机档案页点「投保」（或详情页「直接投保全年保险」），复用订单侧 `purchase` 内核出单，落 `bizType=DRIVER + bizId=driverId + orderId=NULL`。本次改动**只是把它自身的 `@Lock4j` 锁键从"类全名+方法名"改成显式字符串 `driver-ins:purchase`**——它此前对单方法自身就已经生效自互斥（lock4j 缺省 name 对单方法足够用），**外部可观察行为、错误码集合、并发语义全部零变化**，本节仅为完整性列出，不代表本接口新增了任何契约。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| driverId | Body | Long | ✅ | `@NotNull` | 司机 ID，落 `InsuranceOrder.bizId` |
+| planId | Body | Long | ✅ | `@NotNull`，`usageCategory` 须为 DRIVER/BOTH | 司机专用保险计划 ID |
+| coverageStartDate | Body | LocalDate | ✅ | `@NotNull` | 保障开始日期 |
+| coverageEndDate | Body | LocalDate | ✅ | `@NotNull` | 保障结束日期 |
+| insuredPerson | Body | InsuredPersonItemDTO | ✅ | `@NotNull @Valid` | 被保人（单对象，司机险一人一单） |
+| insuredPerson.name | Body | String | ✅ | `@NotNull` | 姓名 |
+| insuredPerson.idCardType | Body | String | ✅ | `@NotNull`，ID_CARD/PASSPORT/OTHER | 证件类型 |
+| insuredPerson.idCardNo | Body | String | ✅ | `@NotNull` | 证件号码（明文，内网 Feign 传输） |
+| insuredPerson.phone | Body | String | - | - | 手机号 |
+| insuredPerson.gender | Body | String | - | 1=男/2=女/0=未知 | 性别编码 |
+| insuredPerson.birthday | Body | LocalDate | - | 可空，引擎从身份证派生 | 出生日期 |
+| orderId | Body | Long | - | 仅形状对齐，必传 null | 司机投保不关联订单 |
+| remark | Body | String | - | - | 备注 |
+
+#### 出参 `Result<DriverInsurancePolicyDTO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| insuranceOrderId | Long（雪花，超出 JS 安全整数范围时序列化为字符串） | 保单 ID |
+| policyNo | String | 本系统保单号（同 `extPolicyNo`） |
+| extPolicyNo | String | 保游网外部保单号（异步出单受理时为空，回调后回填） |
+| extOrderNo | String | 保游网外部订单号 |
+| totalPremium | BigDecimal（序列化为字符串） | 保单总保费 |
+| status | String | 保单状态：PENDING/INSURING/INSURED/CANCELLED/FAILED |
+| statusLabel | String | 保单状态中文标签 |
+| source | String | 保单来源：BAOYOU/MANUAL |
+| policyPdfUrl | String | 保单 PDF 地址（未生成/MANUAL 单为空） |
+| coverageStartDate | LocalDate | 保障起期 |
+| coverageEndDate | LocalDate | 保障止期 |
+| insuredPersons | List\<InsuredPersonBrief\> | 被保人列表（司机险一人一单，通常单元素） |
+| insuredPersons[].name | String | 被保人姓名 |
+| insuredPersons[].idCardNo | String | 证件号（脱敏，保前 3 尾 4） |
+
+#### 请求示例
+
+```json
+{
+  "driverId": "1934567890123456789",
+  "planId": 300,
+  "coverageStartDate": "2026-06-01",
+  "coverageEndDate": "2027-05-31",
+  "insuredPerson": {
+    "name": "周师傅",
+    "idCardType": "ID_CARD",
+    "idCardNo": "150102198001011234",
+    "phone": "13800138000"
+  },
+  "orderId": null,
+  "remark": "司机险投保: 周师傅"
+}
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "insuranceOrderId": "1934567890200888",
+    "policyNo": "BY-2026-0001",
+    "extPolicyNo": "",
+    "extOrderNo": "EXT20260601001",
+    "totalPremium": "88.00",
+    "status": "INSURING",
+    "statusLabel": "出单中",
+    "source": "BAOYOU",
+    "policyPdfUrl": "",
+    "coverageStartDate": "2026-06-01",
+    "coverageEndDate": "2027-05-31",
+    "insuredPersons": [ { "name": "周师傅", "idCardNo": "150**********1234" } ]
+  },
+  "success": true
+}
+```
+
+#### 空数据 / 降级响应
+
+本接口无「空数据」概念，无降级路径。
+
+#### 错误响应
+
+```json
+{ "code": 540032, "message": "该司机该保障期已有生效保单", "data": null, "success": false }
+```
+
+| code | 触发条件 |
+|------|----------|
+| 540005 | 保险计划不存在 |
+| 540031 | 该保险计划未标注为司机可用（`usageCategory` 非 DRIVER/BOTH） |
+| 540032 | 该司机该保障期已有生效保单（锁内区间重叠互斥，含 MANUAL 年保台账单参与判定） |
+| 100502 | 5 秒幂等窗口内重复提交（键=driverId+保障起止） |
+
+**🔴 本端点没有新增 100503**：以上错误码集合与改动前完全一致，本次改动不改变这张表的任何一行。
+
+#### 业务边界
+
+- 幂等：`@Idempotent`（`keyPrefix=insurance:driver-purchase`，键=driverId+保障起止）5 秒窗口，仅作完全相同请求误重提防抖，不承担区间重叠去重职责（区间重叠由锁内 540032 校验负责）。
+- 🔴 **与 §1/§2 台账两口键虽同为 `'driver-ins:' + driverId`，但刻意不互斥**：本方法在重叠校验里只**读** MANUAL 台账单（含未提交完成的除外），不写台账行；`upsert` 不做重叠校验，所以"年单与按天单重叠"这个终态在合法串行序 `purchase → upsert` 下本来就可达，并锁消不掉它。
+- 持锁期间包含保游远程出单 HTTP（区别于 §1/§2 纯本地写库），这也是不把台账写口并进本锁的现实理由之一——台账是毫秒级操作，排在一笔外部 HTTP 后面等锁纯属浪费。
+- 老数据兼容：无字段变化。
+
+---
+
+## 四、契约约束与正确调用方式（接口类必写）
+
+> 本节只写**后端接受/拒绝 payload 的规则**,不写 UI 渲染建议。
+
+### 并发冲突（100503）只在 §1/§2 之间
+
+| 场景 | 响应 |
+|------|------|
+| ✅ 单个 upsert 或 invalidate 请求，无并发 | 200 + 正常业务结果 |
+| ✅ 同司机 upsert 与 invalidate 先后到达，后者在 3 秒内轮到锁 | 两个都 200（排队等待，非立即失败） |
+| ❌ 同司机 upsert ∥ invalidate 并发，后到方等待超过 3 秒未抢到锁 | `{ "code": 100503, "message": "资源被占用,请稍后重试", "success": false }`，**HTTP 状态码仍是 200** |
+| ✅ 同司机 §3 投保 与 §1/§2 台账写口并发 | **不受影响、不会产生 100503**——两者不在同一把锁上，§3 的重叠拒绝（540032）与本次改动无关 |
+| ✅ 不同 driverId 并发 | 互不影响，各自独立加锁 |
+
+**调用方（fleet）必须做的事**：判断响应体 `code === 100503`（不是判 HTTP 状态码），命中时按各自的失败处理策略重试（Outbox/MQ 驱动的 §1/§2 调用方本就有重投机制，见「六.6」）。
+
+### 触发概率评估（结构性推理，非测试服实测）
+
+fleet 侧对台账 upsert/invalidate 的两个真实调用点（`DriverAnnualLedgerOutboxEffectService.java:97/113/126`）本身已被 fleet 侧的 `fleet:insurance-task:lifecycle:{driverId}` 锁串行化（同一司机的多个事件不会并发发起 Feign 调用），真实竞争概率接近 0；且持锁段是纯本地写库、无 HTTP，正常耗时上界远小于 `acquireTimeout` 默认的 3000ms 超时阈值。**不构成类似 #8050 的重试风暴**。这是结构性推理，本文档未在测试服上实测验证这个判断。
+
+---
+
+## 五、数据库行为（涉及写操作时必写）
+
+本次不改变任何一次**成功**写操作实际写入的行数或内容——三个端点各自原有的写入逻辑（台账 upsert/CANCELLED 翻态/投保出单）逐字节不变。变化的只是"谁能在同一时刻对同一 driverId 执行台账写入"：
+
+| 维度 | 改动前 | 改动后 |
+|------|--------|--------|
+| upsert ∥ invalidate 是否互斥 | 否（各自持独立锁，可交错执行） | 是（同一把锁，串行执行） |
+| 交错执行的后果（改前可复现，PR 变异证明） | 刚作废的单被 upsert 陈旧快照全行盲写复活成 INSURED，且不留状态流水（行=INSURED，末条流水 new_status=CANCELLED，两者矛盾） | 该终态不再可达 |
+| purchase 与台账两口的关系 | 各自独立锁，互不阻塞 | 仍然互不阻塞（刻意维持，非缺陷） |
+| 抢锁失败时是否有部分写入（upsert/invalidate） | N/A（此前不会因锁而失败） | 否，零写入 |
+
+---
+
+## 六、边界行为
+
+- 司机不存在等前置校验：本三端点自身不做司机存在性校验（由 fleet 侧在调用前保证），保持改前行为
+- upsert 起止日期反转 → 540225
+- purchase 计划不存在/非司机可用/保障期重叠 → 540005/540031/540032，与本次改动无关，行为不变
+- invalidate 无活动单 → 幂等返回成功，不是错误
+- **抢锁超时（本次新增，仅 upsert/invalidate 之间）→ 100503，HTTP 200，可重试，零写入**
+- purchase 端点**不会**因本次改动新增任何失败分支
+- 老数据兼容：本次不涉及字段增删，存量台账数据无需迁移
+
+---
+
+## 六.5、枚举 / 数据字典（接口出现枚举时必写）
+
+### 保单状态（status，出现于 §3 出参）
+
+**所属字段**: `DriverInsurancePolicyDTO.status` | **类型**: `String`（本次未变化，随改动一并列出便于自包含联调）
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `PENDING` | 待出单 | - |
+| `INSURING` | 出单中 | 异步受理期，`extPolicyNo` 可能为空 |
+| `INSURED` | 已承保 | - |
+| `CANCELLED` | 已退保 | - |
+| `FAILED` | 投保失败 | - |
+
+### 保单来源（source，出现于 §3 出参）
+
+**所属字段**: `DriverInsurancePolicyDTO.source` | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `BAOYOU` | 保游网出单 | 有电子保单，可下载 |
+| `MANUAL` | 手工录入（司机年保档案联动） | §1/§2 两个端点操作的正是这类单；无保游网电子保单，前端应隐藏下载/重传按钮 |
+
+## 六.6、修改前后对比（修改/删除类接口必写，新增跳过）
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 |
+|------|------|------|
+| （无）| 三个接口的请求字段、响应字段逐字节不变 | 同左 |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| upsert ∥ invalidate 并发 | 各持独立锁，可交错执行，可复活已作废的单且不留流水 | 同一把锁 `driver-ins:ledger`，串行执行 |
+| purchase 与台账两口 | 各自独立锁，互不阻塞 | 刻意维持互不阻塞（`driver-ins:purchase` 自成一域），非本次要修的问题 |
+| 抢锁失败的响应（仅 upsert/invalidate） | 不存在这条路径 | 路径真实存在（返回 100503，HTTP 200，业务失败，可重试）；已部署测试服但未做任何功能调用取证，无实测触发数据 |
+| `InsuranceManageService` 两处 javadoc（改前断言"与 purchaseForDriver 同键互斥"） | 断言为假（三处均无 name 时逐字相同的键也不构成互斥） | 订正为准确描述：与台账另一口同名互斥，与 purchase 刻意不互斥 |
+| 请求/响应字段、既有业务错误码（540005/540031/540032/540225） | 不变 | 不变 |
+
+## 六.7、影响评估（修改/删除类必写）
+
+- **是否破坏向后兼容**: 否——三个接口的请求体/响应体字段、既有错误码全部零增删；仅 upsert/invalidate 之间新增一条此前不存在的失败路径（100503），purchase 端点零变化。
+- **前端是否必须同步上线**: 不适用——本组无 C 端、无 hl-ui 直接触达路径；唯一间接路径（§3 投保后同步作废旧 MANUAL 台账失败）已被 fleet 侧既有错误码 600206 吸收，hl-ui 无需为本次改动新增任何处理逻辑。
+- **前端 workaround 清理点**: 无。
+
+## 七、不影响范围（显式声明, 帮前端/QA 缩小排查面）
+
+- **仅影响**: `driver-annual/upsert`、`driver-annual/{driverId}/invalidate` 两个端点之间的并发失败分支
+- **零影响**:
+  - `driver-purchase` 端点的请求/响应字段、错误码集合、并发语义（外部可观察行为零变化）
+  - `InternalInsuranceController` 其余端点（自动投保、保险列表/覆盖查询、退保、分享保单、下载保单、司机保单分页/详情/按服务日查询等）
+  - fleet 侧 `fleet:insurance-task:lifecycle:{driverId}` 锁及其覆盖的档案编辑/出单绑定/状态回调路径——那是另一个服务里的另一把锁，本次未改动
+  - fleet 侧 `DriverInsuranceController`（`/admin/fleet/drivers/**`）的入参/出参/错误码——车管投保页面看到的契约零变化
+  - hl-gateway 路由配置——`/v3/internal/**` 本就不对公网暴露，本次未新增任何路由
+
+---
+
+## 八、测试环境已验证
+
+### 部署（已完成）
+
+- `deploy-backend.sh` 已执行，`hl-order-service-v3` 滚动更新两实例，8186 端口 12 秒起监听、8086 端口 13 秒起监听，脚本报告 `rolling deploy complete`。
+- 部署记录行：`hl-order-service-v3 <- dev-v3 @ 8bf9c520c`——运行版本**就是**本次合并提交本身（精确相等，非祖先链判据）。
+
+### 🔴 没有做任何功能调用取证
+
+本文档**没有**调用过 `driver-annual/upsert`、`driver-annual/{driverId}/invalidate`、`driver-purchase` 三个端点中的任何一个；`100503` 在测试服上**一次都没有触发过**。
+
+**必须两句一起读**：
+
+1. 这不是"测过没触发"，而是**没测**——三个端点都是 `/v3/internal/`，不经网关，无法用浏览器/Postman 直接打；唯一合法调用方是 fleet 经 Feign 调，要手动触发就必须让 fleet 真实写一条司机年保台账（`upsert`/`invalidate` 会改动/插入 `insurance_order` 行）或真实调一次保游远程出单接口并产生扣费（`purchase`），本次评估认为不值得为取一次 100503 读数去污染真实业务数据，故未执行。
+2. 互斥本身的证据来自 PR 正文所载的**代码层面证据（非测试服）**：`Lock4jSharedNameConcurrencyIT`（4 例落库级并发 IT，含变异证明——摘掉共用 `name` 后复现"刚作废的单被复活成 INSURED 且流水终点仍是 CANCELLED"这一矛盾态）与按运行期锁键形状反查的契约用例 `Lock4jSharedNameContractTest`/`Lock4jNameGroupGateTest`（钉死"台账两口同名、投保口异名"这条关系，防止日后有人漏写或错写 `name`）。这些是本地/CI 证据，不是本 changelog 在测试服上独立验证的结果。
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#7980](https://git.1814.love:8443/wx/HL/issues/7980)（AC-6，最后一条验收项）
+- 关联 PR: [wx/HL#8072](https://git.1814.love:8443/wx/HL/pulls/8072)
+- 前序三份（同工单不同 AC，均为 backend_status=pending 待部署）：`changelogs-v2/2026-09/20_7980_配房工作台七个写口补齐需求级互斥新增100503可重试冲突码-修改接口-管理后台.md`（AC-5，#8069）、`changelogs-v2/2026-09/20_7980_出行人删改与发票申请三组写口补同名锁新增100503冲突码触达C端-修改接口-管理后台.md`（AC-7，#8049）、`changelogs-v2/2026-09/20_7980_产品库存扣减恢复两写口补同名锁新增100503冲突码-修改接口-管理后台.md`（AC-8，#8047）
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#7980](https://git.1814.love:8443/wx/HL/issues/7980)
+- **PR**: [#8072](https://git.1814.love:8443/wx/HL/pulls/8072)
+- **Merge commit**: [8bf9c520c](https://git.1814.love:8443/wx/HL/commit/8bf9c520c)
+
+### 联系人
+
+- **后端负责人**: @wx
@@ -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,231 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8002"
+title: "fleet: 保险生命周期锁自锁问题修复——拆出新错误码 605075（资源锁已失效）"
+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: "本条是错误码变更通知，无新增/修改/删除接口、无出入参变化。gateway_status=not_required 的确切含义与依据：本条不引入任何新路由，受影响端点的网关可达性已于 2026-09-20 在工单 #8002 AC-2 经网关实测（HTTP 200）；而 605075 这条分支需要「持锁期间租约丢失」这一在 Redis 侧发生、无法按需构造的条件，因此**不存在该分支的网关读数**，代码侧证据是 4 个调用点与单测。⚠️ 这不等于「已验证 605075 会原样到达前端」——它只是说明网关验证在本条上不是一道可执行的闸门。frontend_owner 留空：认领位由前端侧回写，后端不代填。⚠️ 本文件的行号与占位符示例已于 2026-09-21 对 origin/dev-v3=c1a6e96c8 逐条复核订正过一轮，详见「八、相关历史 PR」下方的订正记录。前端实证 not_required(mmg 2026-09-21):605008/605075/系统繁忙 前端 src 全仓零命中;request.js 重试层只认网络错误/超时/408/429/5xx,业务码 HTTP 200 且非幂等方法默认不重试,不存在「把 605075 当系统繁忙自动重试」的路径;605075 经响应拦截器透后端 message(资源锁已失效(锁标签),本次操作未提交)与 605008 文案天然分叉,无需建码字典。"
+updated_at: "2026-09-21"
+base: "dev-v3"
+---
+
+# fleet: 保险生命周期锁自锁问题修复——拆出新错误码 605075（资源锁已失效）
+
+> **服务**: hl-fleet-service
+> **PR**: [#8015](https://git.1814.love:8443/wx/HL/pulls/8015) + [#8042](https://git.1814.love:8443/wx/HL/pulls/8042)（已合入 dev-v3，merge `44a40de90` + `8629bf5dd`）
+> **Issue**: [#8002](https://git.1814.love:8443/wx/HL/issues/8002)
+> **日期**: 2026-09-20、2026-09-21
+> **影响范围**: 管理后台派单、保险自动投退保相关接口新增错误码返回
+
+---
+
+## ⚠️ 关键变化
+
+**前端不能再把"资源锁已失效"当"系统繁忙"处理。**
+
+原先所有锁相关失败都返 605008（"抢锁超时，系统繁忙，请稍后重试"），本次拆出 605075（"资源锁已失效（{0}），本次操作未提交"）区分两种完全不同的故障模式：
+
+| 错误码 | 原因 | 前端处置 |
+|--------|------|---------|
+| **605008** | 等待窗口内没抢到锁（别人正持有） | ✅ 重试有意义；提示"系统繁忙，请稍后重试" |
+| **605075** | 持锁期间丢了（Redis 侧事件：主从切换、键被清、租期到期） | ❌ 重试通常无效；提示"数据一致性风险，请刷新确认或联系管理员" |
+
+**605008 语义已收窄**：从"抢锁失败"统一码改为"等待超时"专用码，消除歧义。错误信息本身不变（`"抢锁超时，系统繁忙，请稍后重试"`），但现在必定表示"重试可能成功"。
+
+---
+
+## 一、背景
+
+派单与司机保险档案共用一把司机锁（司机保险生命周期锁）。锁是非重入的——同一事务里对同一司机调用两次会等待，最后必然超时（#8002 AC-1）。
+
+#8002 通过事务内重入机制解决自锁问题，同时暴露了一个潜在风险：锁有有限租期（看门狗续期），如果续租在执行期间失败（Redis 主从切换、连接抖动、租期到期等），调用方无法察觉，仍会继续写入，可能产生与并发更新混合的脏数据。
+
+本次新增 605075 把这类"租约丢失"的故障单独标记，让前端与运维据此判断需要人工介入。
+
+---
+
+## 二、变更接口清单
+
+本条**无新增、修改、删除任何 HTTP 接口或字段**，只涉及错误码返回扩展。所有派单与保险相关接口可能新增 605075 返回。
+
+| # | 接口类别 | 变更类型 | 说明 |
+|---|---------|---------|------|
+| - | 派单全量接口 | 错误码新增 | 可能返回 605075（锁租约丢失） |
+| - | 保险自动投退保逻辑 | 错误码新增 | 可能返回 605075（锁租约丢失） |
+
+---
+
+## 三、错误码定义
+
+### 605008（LOCK_ACQUIRE_TIMEOUT）——抢锁超时，等待超时专用
+
+```java
+IErrorCode.of(605008,
+    "抢锁超时，系统繁忙，请稍后重试",
+    "fleet")
+```
+
+**发生时机**：调用方等待 Redis 分布式锁的时间窗口（默认数秒）内没抢到，因为别的调用方仍持有。
+
+**出现位置**（仅限"等待没抢到"两处，共用失败工厂 `lockFailure.get()`）：
+- `AssignmentResourceLockManager` line 592（抢锁等待超时）
+- `FleetInsuranceLifecycleLockManager` line 142（抢锁等待超时）
+
+⚠️ 这两处是**真正 throw 的位置**。各业务方法（如 `AssignmentService:489/579/1112/1240` 等）传进去的是「取不到锁时用哪个异常」的工厂，不是抛出点——按业务方法去数会得到一个大得多的数字。
+
+**重试是否有效**：✅ 有可能有效（别的持有方释放后重试成功率高）
+
+**前端引导**："系统繁忙，请稍后重试"
+
+---
+
+### 605075（LOCK_LEASE_LOST）——资源锁已失效，租约丢失专用
+
+```java
+IErrorCode.of(605075,
+    "资源锁已失效（{0}），本次操作未提交；请确认是否存在并发操作后重新发起",
+    "fleet")
+```
+
+**占位符 {0}**：锁的身份标签，由 `FleetLockDiagnostics.labelOf()` 生成，格式是 **`<中文锁名>(<键里的 ID>)`**，例如：
+`用车需求锁(123)`、`订单需求项锁(…)`、`团期配车聚合锁(…)`、`派车组锁(…)`、`司机派单锁(456)`、`车辆派单锁(…)`、`车牌唯一锁(…)`、`车架号唯一锁(…)`、`常驻司机绑定锁(…)`、`司机保险任务锁(…)`。
+前缀认不出来时落 `未知锁(<原始键>)`。**多把锁一起失效时用顿号「、」连起来，顺序与加锁顺序一致。**
+⚠️ 不要按 `冒号分隔的英文键` 去解析它——那不是它的形态。
+
+**发生时机**：成功抢到锁，持有期间（执行业务逻辑时）发现租约已不属于自己，意味着 Redis 侧发生过事件（主从切换、键被清、看门狗续期失败、租期到期）。
+
+**出现位置**（共四处调用 `FleetLockDiagnostics.leaseLost()`）：
+- `AssignmentResourceLockManager` line 386（绑定资源前的续租失败）
+- `AssignmentResourceLockManager` line 444（事务提交前的续租失败）
+- `AssignmentResourceLockManager` line 499（FOR UPDATE 后归属复核失败，行已锁定但 Redis 键丢失）
+- `FleetInsuranceLifecycleLockManager` line 263（持锁期内复核发现键已不属于自己）
+
+**重试是否有效**：❌ 无效（成因在 Redis 侧，本地重试无法恢复；且期间可能已有并发写入）
+
+**前端引导**："数据一致性风险。请刷新后重试，或联系管理员人工核实是否存在并发操作。"
+
+---
+
+## 四、契约约束与正确调用方式
+
+### 错误码使用场景对应关系
+
+所有派单与保险接口的以下场景可能返回这两个码：
+
+1. **派单创建/改派/最终确认/撤销取消** → 需抢派单资源锁 → 可能返 605008 或 605075
+2. **司机保险档案编辑/自动投退保** → 需抢司机保险锁 → 可能返 605008 或 605075
+3. **共用关系变更（团期派车组共用确认等）** → 涉多把锁 → 可能返 605008 或 605075
+
+### 前端分别处置逻辑（伪代码）
+
+```json
+{
+  "code": 605008,
+  "message": "抢锁超时，系统繁忙，请稍后重试",
+  "success": false
+}
+```
+→ **重试逻辑**：可展示"系统繁忙，请稍后重试"，3-5 秒后自动重试或提示用户手动重试
+
+```json
+{
+  "code": 605075,
+  "message": "资源锁已失效（用车需求锁(8xxx)），本次操作未提交；请确认是否存在并发操作后重新发起",
+  "success": false
+}
+```
+→ **人工核实逻辑**：不推荐直接重试，应该：
+1. 刷新当前页面查看最新状态
+2. 若问题仍存在，人工核实是否有并发操作（多个标签页同时操作同一资源）
+3. 若无并发，联系技术支持并提供锁标签（括号内内容）以排查 Redis 问题
+
+---
+
+## 五、边界行为
+
+- 未登录 → 401（网关拦截）
+- 资源不存在 → 404 或其他业务错误码（先于锁检验）
+- 下游服务降级 → 通常返 200 + 降级结构，不影响锁的判定
+- **重要**：605008 与 605075 都是**锁层面**的故障，不是"参数校验失败"也不是"业务规则冲突"；前端应按后端差异返回走不同分支，**禁止对所有 60508x 统一重试**
+
+---
+
+## 六、验证情况（请连同它的边界一起看）
+
+**部署**：PR #8015（`44a40de90`）与 #8042（`8629bf5dd`）已合入 `dev-v3`，且 `merge-base --is-ancestor` 对测试服 fleet 部署点 `51571c58a` 均为真。
+
+⚠️ **下表是对 `origin/dev-v3 = c1a6e96c8` 的逐条代码复核，不是测试服实测读数。** 605075 需要「持锁期间租约丢失」这一 Redis 侧条件，无法按需构造，因此**没有任何一次真实调用产出过 605075**。⇒ 前端在联调时**也构造不出这个码**，请按文档实现分支、不要等"先见到再写"。
+
+| 检查项 | 结果 |
+|--------|------|
+| 错误码定义（`AssignmentErrorCode`） | 605008 保留，605075 新增 ✓ |
+| 605075 抛出点（4 处） | AssignmentResourceLockManager:386/444/499、FleetInsuranceLifecycleLockManager:263 ✓ |
+| 605008 保留点（2 处） | AssignmentResourceLockManager:592（等待超时）、FleetInsuranceLifecycleLockManager:142（等待超时） ✓ |
+| 占位符 {0} 生成（`FleetLockDiagnostics.labelOf()`） | 正确生成"需求/派车组/司机/车辆等:ID"格式 ✓ |
+| 重入安全性 IT | `FleetInsuranceLifecycleLockReentrancyIntegrationTest` 5 条（真 Redis + 独立 H2），覆盖跨事务被挡住、`REQUIRES_NEW` 子事务真取锁、异步线程真取锁；配 `assertContentionActuallyHappened` 竞争证明 ✓ |
+| 分辨力（变异证明） | 去掉 `ownerThread` 守卫 / 把 `RegistryBinding.suspend()` 改空体，两轮各只红 1 条且红在竞争证明那半边 ✓ |
+
+**网关实测（针对自锁修复本身，非 605075）**：2026-09-20 经网关对同一关系同一请求做了前后对比，修复后返回业务结果而非 605008（工单 #8002 AC-2 已勾，附实测请求与响应）。
+
+**结论的边界**：已验证的是「自锁不再发生」与「605008 的语义已收窄到只剩等待超时」；**未验证**的是「605075 真的会在租约丢失时到达前端」。前端无需新增接口对接，仅需按错误码区分提示文案。
+
+---
+
+## 七、不影响范围
+
+- **仅影响**：派单与保险相关接口的错误码返回集合扩展（从含 605008 扩展为含 605008 或 605075）
+- **零影响**：
+  - 所有接口的请求参数、响应结构、成功路径数据
+  - 其他错误码（600xxx / 601xxx 等）
+  - 前端页面布局与非 UI 交互的业务流程（刷新后仍可完成操作）
+
+---
+
+## 八、相关历史 PR
+
+| PR | Issue | 说明 | 是否仍有效 |
+|----|-------|------|------------|
+| [#8015](https://git.1814.love:8443/wx/HL/pulls/8015) | #8002 | 保险生命周期锁改造为事务级可重入 | ✅ 最新 |
+| [#8042](https://git.1814.love:8443/wx/HL/pulls/8042) | #8002 | REQUIRES_NEW 子事务复用外层锁 + 605008 拆出 605075 + 修复 dev-v3 编译 | ✅ 最新 |
+
+
+
+### 📌 2026-09-21 订正记录（旧值保留在此，接住按旧值 grep 的人）
+
+本文件首版由自动化生成，下列五处与代码不符，已按 `origin/dev-v3 = c1a6e96c8` 实测订正：
+
+| 处 | 原值（错） | 订正为 | 怎么查的 |
+|---|---|---|---|
+| 605008 抛出点行号 | `:594` / `:145` | **`:592` / `:142`** | `grep -rn 'logAcquireTimeout' hl-fleet-service/src/main/java/` |
+| 605075 占位符示例 | `requirement:123`、`driver:456` | **`用车需求锁(123)`、`司机派单锁(456)`** | `FleetLockDiagnostics:96-117` 的 `labelOf` + `LABEL_BY_PREFIX:66-80` |
+| 单测描述 | "LEGACY 派单重入恢复" | 删除 | 本单与"LEGACY"无关，该说法在代码与测试里均无对应物 |
+| 相关 PR | #8036 挂在 #8002 名下、说是"补漏掉的 import" | 删除该行 | #8036 实为 **#7973** 的「补两族锁串联的重入 IT 与跨常驻 precheck 断言」 |
+| 第六节标题 | "测试环境已验证" | "验证情况（请连同它的边界一起看）" | 该节内容是代码复核表，不是实测读数；按交付指南 §2.1 的口径不得混称 |
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#8002](https://git.1814.love:8443/wx/HL/issues/8002)
+- 关联 PR: [wx/HL#8015](https://git.1814.love:8443/wx/HL/pulls/8015)、[wx/HL#8042](https://git.1814.love:8443/wx/HL/pulls/8042)
+- 错误码参考: [fleet 派单错误码段 605000-605999 完整列表](https://git.1814.love:8443/wx/HL/blob/dev-v3/hl-fleet-service/src/main/java/com/hulalv/fleet/assignment/errorcode/AssignmentErrorCode.java)
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8002](https://git.1814.love:8443/wx/HL/issues/8002)
+- **PR**: [#8015](https://git.1814.love:8443/wx/HL/pulls/8015)、[#8042](https://git.1814.love:8443/wx/HL/pulls/8042)
+- **Merge commit**: [44a40de90](https://git.1814.love:8443/wx/HL/commit/44a40de90) + [8629bf5dd](https://git.1814.love:8443/wx/HL/commit/8629bf5dd)
+
+### 联系人
+
+- **后端负责人**: @wx
@@ -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
@@ -0,0 +1,175 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8064"
+title: "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: "本条无任何接口出入参或错误码变化，变的是同一请求的副作用：共用关系现在会在成员失去占用时自动收缩、剩余不足 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"
+---
+
+# fleet: 共用关系成员失去占用后，关系现在会自动收缩（行为变更，无接口契约变化）
+
+> **存放目录**: 二期（fleet 车务）→ `changelogs-v2/2026-09/`
+
+## ⚠️ 关键变化
+
+**接口契约零变化**——没有新增/修改/删除任何端点，没有新增/修改任何请求或响应字段，没有新增任何错误码。
+
+**变的是同一个请求的副作用。** 从本次修复上线起：
+
+1. 共用关系的某个成员因任何一条**真实的占用释放路径**失去对该车/该司机的占用时，该成员会被**自动移出**关系（成员行落 `left_at`，`leave_reason = AUTO_OCCUPANCY_RELEASE`）；
+2. 移出后**剩余成员不足 2 个**时，整条关系**自动解除**（`status = RELEASED`，`release_reason = AUTO_SINGLE_MEMBER`，`active_share_group_id` 置空）。
+
+🔴 **这两件事在本次修复之前，在当前部署形态下一次都没有发生过**（不是"偶尔没触发"，是整条代码路径执行不到，见"一、背景"）。所以对前端而言，这是一个**从未出现过的新现象**，不是一个已有现象的修正。
+
+## 一、背景
+
+### 缺陷形态
+
+自动收缩的唯一入口是 `GroupDispatchShareOccupancyRefService.onClaimReleased(...)`，全仓唯一调用点在 `OccupancyDualWriteCoordinator.notifyShareGroupOfRelease(...)`；后者只在 `releaseCurrent(...)` 内被调，`releaseCurrent` 只在 `synchronizeOne(...)` 内被调，而 `synchronize()` 的**第一条语句**是：
+
+```java
+if (!context.dualWrite()) {
+    return;
+}
+```
+
+而占用账本的灰度形态（`fleet_occupancy_rollout_fence`，64 条分片）在测试环境与生产环境**全部为 `LEGACY`**，并已于工单 #7972 定案**维持不切**（理由：回填完成前切换会让新账本少记占用，属于"用一个偏松的判据替掉现状"）。
+
+⇒ **在 `LEGACY` 形态下，`synchronizeOne` / `releaseCurrent` / `notifyShareGroupOfRelease` / `onClaimReleased` 整条链路一行都执行不到。**
+
+### 这个判断是怎么坐实的
+
+不是靠读代码推断，是靠一个**在"修好了"和"没修"两个世界里取值不同**的读数：
+
+| 读数 | 修复前 | 修复后 |
+|---|---|---|
+| 全库 `fleet_group_dispatch_share_group.release_reason = 'AUTO_SINGLE_MEMBER'` 计数 | **0** | **1** |
+| 全库 `fleet_group_dispatch_share_log` 中 `reason = 'AUTO_SINGLE_MEMBER'` | **无** | 有 |
+
+⚠️ **一个容易读错的邻近读数**（写在这里免得下一个人重复踩）：成员行的 `leave_reason = 'AUTO_OCCUPANCY_RELEASE'` 修复前**并不是 0，而是 28**——但那 28 条**全部来自手工解除路径**（24 条属 `MANUAL`、4 条属 `CLEAR_ALL`），因为手工解除与自动收缩**复用了同一个成员级原因值**。⇒ **按成员行的 `leave_reason` 计数衡量自动收缩活跃度会错 86%**，必须 join 到所属关系的 `release_reason` 才能分辨。
+
+### 修复
+
+- PR **#8073**（`c07942035`）：把 LEGACY 形态下的收缩动作挂到 `dualWrite` 闸门**之前**，使其在不切换账本形态的前提下真正执行。
+- PR **#8077**（`3a92cafbf`）：整团解除时，审计用的关系解除原因**不被自动收缩夺走**（走豁免，而不是调整执行顺序）——即"整团解除"仍记为整团解除，不会被改写成 `AUTO_SINGLE_MEMBER`。
+
+## 二、变更接口清单（无）
+
+本条**不新增、不修改、不删除**任何 HTTP 接口，也不改动任何请求/响应字段与错误码。
+
+下列既有端点的**行为副作用**受影响（契约不变）：
+
+| METHOD | Path | 变化 |
+|---|---|---|
+| POST | `/admin/fleet/assignments/{assignmentId}/soft-clear-assignment` | 若该派单是某 active 共用关系的成员，调用后该成员被自动移出；剩余 < 2 人时关系自动解除 |
+| POST | `/admin/fleet/assignments/{assignmentId}/driver-reject` | 同上 |
+| POST | `/admin/fleet/assignments/{assignmentId}/change`（改派替换） | 同上 |
+| POST | `/admin/fleet/assignments/{assignmentId}/complete`（完结） | 同上 |
+| DELETE | `/admin/fleet/assignments/{assignmentId}`（取消） | **仅**当被取消的行在取消前处于 `unassigned` 时才进入释放集，见下方"三、边界行为" |
+
+## 三、边界行为（这一节比上面的清单更重要）
+
+### ⛔ 取消派单**通常不会**触发收缩
+
+`DELETE /admin/fleet/assignments/{assignmentId}` 对**在途**的派车行落的是 `exception` 而**不是** `canceled`，而按工单 **#6152** 的定案，`exception` **保留占用**。只有"取消前已是 `unassigned`"的那部分行会落 `canceled` 并进入释放集。
+
+⇒ **前端不要把"取消派单"当成"会解除共用关系"的动作。** 车务若想解除关系，正确动作是显式调解除接口，或使用软清。
+
+### 会触发收缩的五条路径
+
+软清 / 司机拒接 / 改派替换 / 完结 / 取消中落 `canceled` 的那一子集。它们在后端收敛到同一个写口，因此行为一致。
+
+### 软清清的是整行，不是单一维度
+
+软清会把该派车行的**车与司机一起清空**（车辆 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` 区分来源时，这一点是可靠的。
+
+## 四、前端要做什么
+
+**需要确认的一件事**：贵侧是否在任何地方**缓存**了共用关系状态（`activeShareGroupId`、关系成员列表、"该派单属于某共用关系"这一标志），或是否在代码/交互里假设了「**共用关系只能由人工显式解除**」。
+
+- 若有 ⇒ 该假设**已不再成立**，关系会在上述释放类操作之后"自己消失"，需要改为操作后重新拉取。
+- 若无（每次都实时拉取）⇒ 前端零改动，请把 `frontend_status` 改为 `not_required` 并说明依据。
+
+⚠️ 我**没有**替贵侧填 `not_required`：那是一个关于前端代码的事实，后端查证不了。**这个位由看得见前端代码的人来定。**
+
+## 五、测试环境已验证
+
+**部署**：fleet 测试服部署点 `51571c58a`；`git merge-base --is-ancestor c07942035 51571c58a` 与 `3a92cafbf` **均为真**；Nacos 两实例 `healthy = true`。
+**形态**：`fleet_occupancy_rollout_fence` 维持 `LEGACY`（**未改任何配置、未翻闸门**——在 DUAL_WRITE 下绿不能证明本缺陷修好了，那正是它的藏身处）。
+**网关**：全部调用经 `https://api.test.1814.love:9443`，调用流水逐条留档。
+
+**夹具**：服务日 **2026-12-20**（全新，不复用存量），团车 + 司机 + 甲乙两户，VEHICLE 维度共用关系，3 个 alive 成员。
+
+**三次查询逐条对**：
+
+1. **软清前**：3 个成员全部 alive，关系 `status = ACTIVE`，关系日志仅一条 `CREATE`；
+2. **软清甲之后**：关系仍 `ACTIVE`、`release_reason` 为 null、`active_share_group_id` 仍指向本关系；**甲的成员行** `left_at = 2026-09-21 01:14:08`、`leave_reason = AUTO_OCCUPANCY_RELEASE`，而**团车行与乙的 `left_at` 仍为 null** ⇒ 剩 2 行 alive。（团车行与乙没动，是排除"整条关系被一把清掉"的阳性对照。）
+3. **软清乙（最后一人）之后**：`status = RELEASED`、`release_reason = AUTO_SINGLE_MEMBER`、`active_share_group_id = NULL`、`released_at = 2026-09-21 01:14:08`；关系日志出现 `{action: RELEASED, reason: AUTO_SINGLE_MEMBER}`。
+
+## 六、不影响范围
+
+- 任何接口的**请求参数、响应字段、错误码**——一个都没动。
+- **取消派单**对在途行的行为（仍落 `exception`、仍保留占用，#6152 定案不变）。
+- **整团解除**的审计原因（PR #8077 专门保证它不被夺走）。
+- 占用账本（`fleet_resource_occupancy_*`）的灰度形态——**仍维持 `LEGACY`，本次修复没有切换它**，这正是本次修复的设计目标：不靠切形态也能让收缩跑起来。
+- **存量数据**：已通过 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
+
+- PR #8073（`c07942035`）—— 让自动收缩在 LEGACY 下真正执行。
+- PR #8077（`3a92cafbf`）—— 整团解除的审计原因不被自动收缩夺走。
+- 工单 #7972 —— 定案占用账本形态维持 `LEGACY` 不切（本缺陷得以长期存在的环境前提）。
+- 工单 #6152 —— 取消派单对在途行落 `exception` 且保留占用。
+- 工单 #8061 —— 解除共用关系只清成员占用、同槽非成员不动。
+
+## 关联 / 联系人
+
+### 链接
+
+- 后端工单：https://git.1814.love:8443/wx/HL/issues/8064
+- PR：https://git.1814.love:8443/wx/HL/pulls/8073 、 https://git.1814.love:8443/wx/HL/pulls/8077
+
+### 联系人
+
+- 后端：wx
+- 前端：mmg（本条需前端确认是否缓存了共用关系状态，见"四、前端要做什么"）
@@ -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
@@ -0,0 +1,244 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8087"
+title: "餐食下拉按餐厅联动：未选餐厅只给「全部」餐食"
+consumer: "admin"
+author: "lc(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+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；没选餐厅时不传。出参字段、排序与条数上限不变。"
+updated_at: "2026-09-21"
+base: "dev-v3"
+---
+
+# resource: 餐食下拉按餐厅联动，未选餐厅只给「全部」餐食
+
+> **服务**: hl-resource-service
+> **PR**: #8089
+> **Issue**: #8087
+> **日期**: 2026-09-21
+> **影响范围**: 管理后台餐食下拉接口 `GET /admin/dish/items/list`
+
+---
+
+## ⚠️ 关键变化
+
+📝 **默认返回口径变了**：不传 `restaurantId` 时，`GET /admin/dish/items/list` 只返回餐厅为「全部」（`restaurantId` 为 `null`）的上架餐食，不再返回所有上架餐食。
+
+🆕 **新增可选入参 `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 例全过。
+
+---
+
+## 一、背景
+
+订单详情「用餐」页签的餐厅、餐食都是下拉选择，餐食下拉取本接口。此前接口不按餐厅过滤，不论有没有选餐厅，下拉都列出全部上架餐食，与「餐食按餐厅维护、餐厅为空表示全部」（#7947）的数据口径对不上。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 查询餐食列表 | GET | `/admin/dish/items/list` | 入参新增 + 行为变化 | 新增可选 `restaurantId`；不传只返回餐厅为「全部」的上架餐食 |
+
+---
+
+## 三、接口详情
+
+### 1. 查询餐食列表 `GET /admin/dish/items/list`
+
+**VO**: `DishListReqVO` → `List<DishListItemRespVO>`
+
+#### 使用场景
+
+餐食下拉数据源。订单详情「用餐」页签按行选餐厅、选餐食，餐食候选跟着该行选中的餐厅走。
+
+#### 入参字段表
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| restaurantId | Query | Long | 否 | 正整数 | **新增**。不传只返回餐厅为「全部」的餐食；传了只返回该餐厅的餐食。0 与负数返回 400「餐厅ID必须为正数」 |
+| keyword | Query | String | 否 | 去首尾空格后 ≤64 | 模糊匹配名称（不变） |
+| settleType | Query | String | 否 | cash / sign / company | 结算方式（不变） |
+| limit | Query | Integer | 否 | 1–200，默认 50 | 最大返回条数（不变） |
+
+四个条件之间是「并且」，并且固定只返回上架（`status=1`）、未删除的餐食。
+
+#### 出参字段表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| [].dishId | String | 餐食 ID（不变） |
+| [].restaurantId | String | 餐厅 ID，「全部」为 `null`（不变） |
+| [].restaurantName | String | 餐厅名称，「全部」返回「全部」（不变） |
+| [].dishName | String | 餐食名称（不变） |
+| [].unitPrice | Number | 单价（元），两位小数（不变） |
+| [].priceUnit | String | 桌/人：`person` 按人 / `table` 按桌（不变） |
+| [] 其余字段 | — | `imageUrl`、`settleType`、`status`、`remark`、`createdBy`、`createdByName`、`createdAt` 均不变 |
+
+出参字段、排序（创建时间升序、餐食 ID 升序）与条数上限都没有变化，只是返回哪些行变了。
+
+#### 请求示例
+
+```http
+GET /admin/dish/items/list?restaurantId=2023382108491247617&limit=50
+Authorization: Bearer <admin token>
+```
+
+没选餐厅时：
+
+```http
+GET /admin/dish/items/list?limit=50
+Authorization: Bearer <admin token>
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "success": true,
+  "data": [
+    {
+      "dishId": "2100978380923863042",
+      "restaurantId": "2023382108491247617",
+      "restaurantName": "七间房全羊馆",
+      "dishName": "团队标准餐（八菜一汤）",
+      "unitPrice": 35.00,
+      "priceUnit": "person",
+      "imageUrl": null,
+      "settleType": "cash",
+      "status": 1,
+      "remark": null,
+      "createdBy": "1900000000000000001",
+      "createdByName": "张三",
+      "createdAt": "2026-09-19 14:20:03"
+    }
+  ]
+}
+```
+
+#### 空数据 / 降级响应
+
+`data` 为 `[]`：没选餐厅且没有「全部」类上架餐食，或所选餐厅下没有上架餐食（例如该餐厅的餐食都被下架）。
+
+#### 错误响应
+
+```json
+{ "code": 400, "message": "餐厅ID必须为正数", "success": false, "data": null }
+```
+
+```json
+{ "code": 400, "message": "limit最大为200", "success": false, "data": null }
+```
+
+#### 业务边界
+
+- 「全部」的餐食只在不传 `restaurantId` 时出现；传了某餐厅就只有该餐厅自己的餐食。
+- 下架、已删除的餐食任何情况下都不返回。
+- 本接口只决定下拉候选，不影响订单用餐的保存：订单仍按页面传的餐厅、餐食原样存。
+
+---
+
+## 四、契约约束与正确调用方式
+
+| 场景 | 调用 |
+|------|------|
+| ✅ 该行没选餐厅 | `GET /admin/dish/items/list?limit=50`（不带 `restaurantId`） |
+| ✅ 该行选了餐厅 | `GET /admin/dish/items/list?restaurantId=<餐厅ID>&limit=50` |
+| ✅ 换了餐厅 | 用新餐厅 ID 重新调用本接口取候选 |
+| ❌ 用 `restaurantId=0` 表示「全部」 | 400「餐厅ID必须为正数」；表示「全部」要省略该参数 |
+| ❌ 用 `restaurantId=-1` | 400「餐厅ID必须为正数」 |
+
+---
+
+## 五、数据库行为
+
+只读查询，不写库。过滤条件对应 `dish.restaurant_id`：不传时按 `restaurant_id IS NULL` 查，传了按等值查。餐食数据本身没有任何改动。
+
+---
+
+## 六、边界行为
+
+- 未登录 → 401（网关拦截），不变。
+- 所选餐厅不存在或已删除：不报错，返回 `[]`（接口不回查餐厅表）。
+- `restaurantId` 与 `keyword`、`settleType`、`limit` 是「并且」关系。
+
+---
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 |
+|------|------|------|
+| 入参 `restaurantId` | 无 | 新增，可选，正整数 |
+| 入参 `keyword` / `settleType` / `limit` | — | 不变 |
+| 出参全部字段 | — | 不变 |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| 不传 `restaurantId` | 返回所有上架餐食 | 只返回餐厅为「全部」的上架餐食 |
+| 传 `restaurantId` | 参数被忽略，返回所有上架餐食 | 只返回该餐厅的上架餐食 |
+| 排序、条数上限、只查上架 | — | 不变 |
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 是。老调用方不传 `restaurantId` 时，拿到的候选会收窄为「全部」类餐食。
+- **前端是否必须同步上线**: 是。餐食下拉需按选中的餐厅传 `restaurantId`，否则选了餐厅也只能看到「全部」类餐食。
+- **前端 workaround 清理点**: 无。
+
+## 七、不影响范围
+
+- **仅影响**: 餐食下拉 `GET /admin/dish/items/list` 返回哪些行
+- **零影响**:
+  - 餐食分页 `GET /admin/dish/items/page`、详情 `GET /admin/dish/items/{dishId}/view`
+  - 餐食新建 `POST /admin/dish/items/add`、修改 `PUT /admin/dish/items/{dishId}/update`、上下架 `PUT /admin/dish/items/{dishId}/status/update`、删除 `DELETE /admin/dish/items/{dishId}/del`
+  - 餐厅接口与订单用餐信息、用餐模版接口
+  - 已有餐食数据
+
+---
+
+## 八、测试环境已验证
+
+部署提交 `79722aef1`，部署前后各抓一次本接口返回做比对：
+
+```
+不传 restaurantId                        → 12 条收窄为 9 条，全部是 restaurantId 为 null 的上架餐食 ✓
+不传 restaurantId 的行出参                → 与部署前逐字段一致 ✓
+restaurantId=2023382108491247617（七间房全羊馆） → 只返回该餐厅上架的 2 条，出参逐字段一致 ✓
+restaurantId=2023382111074938881（九牧羊鲜羊火锅） → 只返回该餐厅上架的 1 条 ✓
+restaurantId=2023382100664676353（菌香园火锅，餐食全下架） → 返回 [] ✓
+restaurantId=0 / -1                       → 400「餐厅ID必须为正数」 ✓
+```
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#8087](https://git.1814.love:8443/wx/HL/issues/8087)
+- 关联 PR: [wx/HL#8089](https://git.1814.love:8443/wx/HL/pulls/8089)
+- 餐食按餐厅维护的由来: [#7947 Changelog](19_7947_餐食删除编码关联餐厅增加桌人-修改接口-管理后台.md)
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8087](https://git.1814.love:8443/wx/HL/issues/8087)
+- **PR**: [#8089](https://git.1814.love:8443/wx/HL/pulls/8089)
+- **Merge commit**: [79722aef1](https://git.1814.love:8443/wx/HL/commit/79722aef18000ec004f85262bbfc64c1b33b8201)
+
+### 联系人
+
+- **后端负责人**: @lc
@@ -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
--- a/显示更多
+++ b/显示更多