1365 行
57 KiB
Markdown
1365 行
57 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "7441"
|
||
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: "2026-09-16"
|
||
status_note: "本单（#7441 PR-2d + PR-2e）已由 PR #7778 squash 合入 dev-v3（合并提交 f0277a14f），测试服 order-v3 于 2026-09-16 01:21 部署该提交。确认行程清单（户丙残留需求+撤回对照）、确认行程、取消成团（589502 豁免）、成团（vehicleReady 回填）四个端点经真实 waive 声明取证；团期详情/手工复判物料门/手工复判出发门②/团期合同保险面板/发起预支五项，本轮用 fleet 真实回调置位（非 waive 声明）验证同一份 vehicleReady 读取口径生效，未单独用『已声明免车』的团复测这五个端点。分页查询我的订单待办、手动开合同/保险、团期看板、fleet 待配车清单、内部候选查询共 5 个端点本轮未经网关实测，按源码核对列示。第八节已逐条标注覆盖边界。mmg 2026-09-16 核实：14 个端点契约结构全不变、仅返回值随免车声明联动；vehicleReady 字段在 hl-admin 全仓零消费（团期详情/看板均未渲染该字段），不存在「vehicleReady=fleet 已配车」的强假设渲染；待办/清单消失重现是服务端数据行为。前端零改动，判 not_required。"
|
||
updated_at: "2026-09-16"
|
||
base: "dev-v3"
|
||
---
|
||
|
||
# order-v3: 团期整团免车认户级与团级门禁联动
|
||
|
||
> **存放目录**: `changelogs-v2/{YYYY-MM}/`（管理后台，二期 order-v3；含一个 `/admin/fleet/**` 端点与一个 `/v3/internal/**` 端点，按仓规范例外同样归本目录）
|
||
>
|
||
> **服务**: hl-order-service-v3 (端口 8083) + hl-fleet-service (端口 8085，仅消费方，代码不改)
|
||
> **PR**: [#7778](https://git.1814.love:8443/wx/HL/pulls/7778)（squash 合入 dev-v3，合并提交 `f0277a14f`，同批含 PR-4，另有一份 changelog 覆盖）
|
||
> **Issue**: #7441
|
||
> **日期**: 2026-09-16
|
||
> **影响范围**: 「本团无需用车」声明（`waive`，已上线）从此不再是一个只写车需求表的孤立动作——14 个既有管理后台/车管后台/内部端点的响应值会随之联动变化，全部契约（方法/路径/参数/响应结构/错误码）不变，只是返回的**值**不同
|
||
|
||
---
|
||
|
||
## ⚠️ 关键变化（本版与上版行为不同，必读）
|
||
|
||
1. **免车团从此在多个页面「表现为已就绪」，而改前只有车需求页知道**。声明「本团无需用车」（`waive`）改前只写车需求表本身，本单起同一次调用会连带让下面 14 个既有端点的返回值发生变化——**这些端点自身的契约（方法/路径/参数/响应结构/错误码）一个字节都没改**，变的只是数据。
|
||
2. **`vehicleReady` 字段语义扩大**：团期详情 `GET .../group-batch/{groupBatchId}` 与看板 `GET .../group-batch/board` 的 `vehicleReady` 字段，改前只表示「fleet 真配车就绪」，本单起表示「fleet 真就绪 **或** 已声明整团免车」。字段名、类型、路径**都不变**，前端如果把这个字段渲染成「已配车」而不是更准确的「车侧无阻塞」，含义会跟着变化。
|
||
3. **确认行程清单 `VEHICLE_DONE` 项对免车团的户直接判通过**，哪怕该户从没提交过用车需求、或提交后还卡在草稿/待审核。
|
||
4. **「用车需求 · 待提交」待办对免车团的户不再挂起**，`waive` 成功后会自动完成；撤回免车（`withdraw`）后按原规则重新挂起。
|
||
5. **物资门、出发门②、合同出具、预支、fleet 待配车清单全部随 `vehicleReady` 联动**——免车团会像「已配车」一样打开这些门，不再单独卡在车侧。
|
||
6. **操作顺序有硬约束：先撤回免车、再配车**。若在「已声明免车」期间 fleet 又真的按团期 ID 配了车，之后撤回免车会把 `vehicle_ready` 清成 `false`，即使 fleet 那边已经就绪，团会重新卡门直到 fleet 再回调一次——这是已知缺口（见「业务边界」），不是本单交付范围（`#7442` 收口）。
|
||
7. **撤回免车（`withdraw`）不回退团期状态**：已经因免车推进到物资准备中及之后阶段的团，撤回免车后团期阶段本身不回退，但会被下游门（出发门②等）重新拦住。
|
||
|
||
---
|
||
|
||
## 一、背景
|
||
|
||
「本团无需用车」声明（`POST /v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement/waive`）与撤回（`POST .../vehicle-requirement/withdraw`）两个端点已上线（`#7441` 更早的 PR）。声明免车此前只在车需求表里落一条零分组的已确认记录，**下游所有读口都不认它**：确认行程清单里车侧项恒判不通过、待办永远挂着「用车需求 · 待提交」、团级 `vehicle_ready` 恒为 `false`，导致物资准备、出发门②、合同出具、预支、fleet 待配车清单全部把免车团当成「车没配好」卡住——管理员点了免车却什么都没打开。
|
||
|
||
本单（`#7441` PR-2d + PR-2e）让这些既有读口都认整团免车声明：PR-2d 补户级（确认行程清单、待办、订单状态流转），PR-2e 补团级（`vehicle_ready` 本身及其下游七道门）。**新增一个只读判定服务作为唯一真源**，结算闸（`#7441` PR-3，已上线）、本单新增的户级/团级判定共用同一份「是否已声明整团免车」的判断，不各自重写一份。
|
||
|
||
---
|
||
|
||
## 二、变更接口清单
|
||
|
||
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|
||
|---|------|------|------|----------|------|
|
||
| 1 | 5 项 checklist 校验（确认订单前置） | GET | `/v3/admin/order/{id}/confirm-checklist` | 返回值变化 | `items[code=VEHICLE_DONE]` 对免车团的户直接判通过 |
|
||
| 2 | 确认行程 | POST | `/v3/admin/order/{id}/confirm-itinerary` | 返回值变化 | 免车团的户不再因车侧未就绪报 581036 |
|
||
| 3 | 分页查询我的订单待办 | GET | `/v3/admin/order-todos/my/page` | 返回值变化 | 免车团的户「用车需求 · 待提交」待办自动完成，撤回后重开 |
|
||
| 4 | 取消成团 | POST | `/v3/admin/order/group-batch/{groupBatchId}/cancel-group` | 返回值变化 | 免车团不再因车项被判「已派单资源」而拦 589502 |
|
||
| 5 | 成团 | POST | `/v3/admin/order/group-batch/{groupBatchId}/group` | 返回值变化 | 免车声明仍有效时成团同时置 `vehicleReady=true` |
|
||
| 6 | 手工复判物料门 | POST | `/v3/admin/order/group-batch/{groupBatchId}/recheck-material-gate` | 返回值变化 | 免车团车项视为已过，`blockedGate` 不再落在车侧 |
|
||
| 7 | 手工复判进入待出发硬门 | POST | `/v3/admin/order/group-batch/{groupBatchId}/recheck-departure-gate` | 返回值变化 | 门②（房车导摄四项配齐）对免车团通过 |
|
||
| 8 | 团期合同保险面板 | GET | `/v3/admin/order/group-batch/{groupBatchId}/contracts` | 返回值变化 | 免车团 `issuable` 不再被车项卡住 |
|
||
| 9 | 手动开合同/保险 | POST | `/v3/admin/order/group-batch/{groupBatchId}/contracts/issue` | 返回值变化 | 免车团不再因车项报 589548 |
|
||
| 10 | 发起团期预支 | POST | `/v3/admin/order/group-batch/{groupBatchId}/advance` | 返回值变化 | 免车团不再因车项报 589542 |
|
||
| 11 | 团期详情 | GET | `/v3/admin/order/group-batch/{groupBatchId}` | 字段语义变化 | `vehicleReady` 含义扩大为「配车完成或整团免车」 |
|
||
| 12 | 团期看板 | GET | `/v3/admin/order/group-batch/board` | 字段语义变化 | 同上 |
|
||
| 13 | 团期待配车候选查询（内部） | POST | `/v3/internal/group-batch/vehicle-dispatch-candidates` | 返回值变化 | 免车团不再落在候选集合里；仅限 fleet Feign 调用 |
|
||
| 14 | 待配车团期清单（车管后台） | GET | `/admin/fleet/group-dispatch/pending-batches` | 返回值变化 | 免车团从清单中消失，撤回免车后重新出现；经「13」间接取数 |
|
||
|
||
---
|
||
|
||
## 三、接口详情
|
||
|
||
### 1. 5 项 checklist 校验（确认订单前置） `GET /v3/admin/order/{id}/confirm-checklist`
|
||
|
||
**VO**: `无请求体 → Result<ConfirmChecklistRespVO>`
|
||
|
||
#### 使用场景
|
||
|
||
订单详情页点「确认订单」前调用，展示 5 项前置检查（出行人信息/支付/住宿/用车/合同模板）的通过情况，用于决定弹出确认预览还是逐项报错清单。本单只影响 `code=VEHICLE_DONE` 这一项，其余 4 项不变。
|
||
|
||
#### 入参字段表
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|------|------|------|------|------|------|
|
||
| id | Path | Long | 是 | - | 订单 ID（不变） |
|
||
|
||
#### 出参字段表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| allPassed | Boolean | 是否全部通过（唯一开关）：true 时 items=null、preview 有值；false 时 items 有值、preview=null（不变） |
|
||
| items | List<ChecklistItemVO> | 5 项详细结果（仅 allPassed=false 时返回）：code/checkName/passed/failReason（结构不变） |
|
||
| preview | PreviewVO | 确认弹框预览数据（仅 allPassed=true 时返回，结构不变，本单未改） |
|
||
|
||
`items[]` 中 `code=VEHICLE_DONE` 一项：改前 `needsVehicle=true` 时要求订单镜像与当前用车需求同时为 DONE 才 passed=true；本单起在这之前新增一次判断——若该订单所在团已声明整团免车，直接 passed=true，不再检查需求行状态。
|
||
|
||
#### 请求示例
|
||
|
||
```http
|
||
GET /v3/admin/order/2098979230573330434/confirm-checklist HTTP/1.1
|
||
Authorization: Bearer {token}
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
免车团的户（其余 4 项均已满足）：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"success": true,
|
||
"data": {
|
||
"allPassed": true,
|
||
"items": null,
|
||
"preview": {
|
||
"departureDate": "2026-09-20",
|
||
"totalPeopleCount": 4,
|
||
"driverName": null,
|
||
"driverPhoneMasked": null,
|
||
"hotels": [],
|
||
"staffs": [],
|
||
"contractAutoAction": null,
|
||
"insuranceAutoAction": null
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
对照：同一户在撤回免车后、且用车需求仍未完成时：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"success": true,
|
||
"data": {
|
||
"allPassed": false,
|
||
"items": [
|
||
{
|
||
"code": "VEHICLE_DONE",
|
||
"checkName": "用车安排",
|
||
"passed": false,
|
||
"failReason": "用车需求尚未完成"
|
||
}
|
||
],
|
||
"preview": null
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
本端点全程同步内存/DB 读取，不经 Feign/MQ，不产生降级分支；`items`/`preview` 互斥由 `allPassed` 决定，两者不会同时为空或同时有值。
|
||
|
||
```json
|
||
{ "code": 200, "success": true, "data": { "allPassed": true, "items": null } }
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
本单不新增错误码，沿用既有：
|
||
|
||
```json
|
||
{
|
||
"code": 404,
|
||
"message": "订单不存在",
|
||
"success": false,
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
#### 业务边界
|
||
|
||
- 免车判定读的是「该户所在团是否已声明整团免车」（经统一判团门面解析，不读订单自身的团期 ID 冗余列），与本单其余端点共用同一份只读判定，不会出现「这个端点认免车、那个端点不认」的分叉。
|
||
- 判定顺序：`needsVehicle=false` 时最先短路（不查库）；免车判定其次；仍不通过才走原有的需求状态/完成来源三分支校验。
|
||
- 非免车团、或免车团但 `needsVehicle=false` 的户，行为与改前逐字节一致。
|
||
|
||
---
|
||
|
||
### 2. 确认行程 `POST /v3/admin/order/{id}/confirm-itinerary`
|
||
|
||
**VO**: `ConfirmItineraryReqVO（可空）→ Result<OrderTransitionRespVO>`
|
||
|
||
#### 使用场景
|
||
|
||
订单详情页「确认订单」按钮，把订单从定制阶段推进到下一阶段。内部先跑与上条相同的 5 项 checklist，`allPassed=false` 时拒绝推进并报 581036。本单不改该端点的调用方式，只是 `VEHICLE_DONE` 判定结果变化会连带影响它是否报错。
|
||
|
||
#### 入参字段表
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|------|------|------|------|------|------|
|
||
| id | Path | Long | 是 | - | 订单 ID（不变） |
|
||
|
||
（请求体可空，字段本单未改，不重复列出。）
|
||
|
||
#### 出参字段表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| data | OrderTransitionRespVO | 结构不变，本单未改 |
|
||
|
||
#### 请求示例
|
||
|
||
```http
|
||
POST /v3/admin/order/2098979230573330434/confirm-itinerary HTTP/1.1
|
||
Authorization: Bearer {token}
|
||
Content-Type: application/json
|
||
|
||
{}
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"success": true,
|
||
"data": { "orderId": "2098979230573330434", "orderStatus": "CONFIRMED" }
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
不涉及空态；失败直接返错误码。
|
||
|
||
```json
|
||
{ "code": 200, "success": true, "data": {} }
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
| 码 | 符号 | 触发 | 本单 |
|
||
|----|------|------|------|
|
||
| 581036 | ORDER_CONFIRM_CHECKLIST_NOT_PASSED | 5 项 checklist 任一未通过 | 不变（码本身不变），触发条件因 VEHICLE_DONE 判定变化而收窄——免车团的户不再单独因车侧报这个码 |
|
||
|
||
```json
|
||
{
|
||
"code": 581036,
|
||
"message": "确认订单前置校验未通过，请查看具体缺失项",
|
||
"success": false,
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
#### 业务边界
|
||
|
||
- 免车团的户此前恒因 VEHICLE_DONE=false 报 581036，本单起不再因车侧报错，其余 4 项照常校验，任一不满足仍会报 581036。
|
||
- 判权、事务边界、幂等策略本单未改。
|
||
|
||
---
|
||
|
||
### 3. 分页查询我的订单待办 `GET /v3/admin/order-todos/my/page`
|
||
|
||
**VO**: `OrderTodoPageReqVO（Query）→ Result<PageResult<OrderTodoRespVO>>`
|
||
|
||
#### 使用场景
|
||
|
||
定制师工作台「我的待办」列表，`todoType=ASSIGN_VEHICLE` 是其中一类（房型需求 `ASSIGN_ROOM` 同构）。本单只影响该类待办对免车团的户是否出现在「待处理」筛选下。
|
||
|
||
#### 入参字段表
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|------|------|------|------|------|------|
|
||
| status | Query | String | 否 | PENDING/COMPLETED/CANCELLED | 待办状态（不变） |
|
||
| todoSource | Query | String | 否 | SYSTEM/MANUAL | 待办来源（不变） |
|
||
| orderId | Query | Long | 否 | - | 订单 ID（不变） |
|
||
| fromDate | Query | LocalDate | 否 | - | 开始日期（不变） |
|
||
| toDate | Query | LocalDate | 否 | - | 结束日期（不变） |
|
||
| keyword | Query | String | 否 | - | 标题/订单号关键词（不变） |
|
||
| pageNo/pageSize | Query | Integer | 否 | 分页参数继承 PageParam | 不变 |
|
||
|
||
#### 出参字段表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| records[].todoType | String | 待办类型，如 ASSIGN_VEHICLE（不变） |
|
||
| records[].todoLabel | String | 标题，如「用车需求 · 待提交」（不变） |
|
||
| records[].status | String | PENDING/COMPLETED/CANCELLED（本单：免车团户级 ASSIGN_VEHICLE 待办自动转 COMPLETED） |
|
||
| records[].completedAt | LocalDateTime | 完成时间（本单：免车声明成立时自动写入） |
|
||
| （其余字段结构不变，见既有字段集合） | - | - |
|
||
|
||
#### 请求示例
|
||
|
||
```http
|
||
GET /v3/admin/order-todos/my/page?status=PENDING&pageNo=1&pageSize=20 HTTP/1.1
|
||
Authorization: Bearer {token}
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
免车团声明成立后，该户的 ASSIGN_VEHICLE 待办不再出现在 `status=PENDING` 筛选结果里（因为已自动完成）：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"success": true,
|
||
"data": {
|
||
"records": [],
|
||
"total": 0,
|
||
"page": 1,
|
||
"pageSize": 20
|
||
}
|
||
}
|
||
```
|
||
|
||
撤回免车后同一户重新出现：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"success": true,
|
||
"data": {
|
||
"records": [
|
||
{
|
||
"todoId": "1900000000000000099",
|
||
"orderId": "2098979230573330434",
|
||
"orderNo": "HL202609200001",
|
||
"todoType": "ASSIGN_VEHICLE",
|
||
"todoTypeName": "用车需求",
|
||
"todoLabel": "用车需求 · 待提交",
|
||
"status": "PENDING",
|
||
"statusName": "待处理"
|
||
}
|
||
],
|
||
"total": 1,
|
||
"page": 1,
|
||
"pageSize": 20
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
无匹配待办时 `records` 为空数组，`total=0`，不是错误。
|
||
|
||
```json
|
||
{ "code": 200, "success": true, "data": { "records": [], "total": 0, "page": 1, "pageSize": 20 } }
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
本单不新增错误码。
|
||
|
||
```json
|
||
{ "code": 401, "message": "未登录或登录已过期", "success": false, "data": null }
|
||
```
|
||
|
||
#### 业务边界
|
||
|
||
- 只在待办当前处于「需要定制师动作」（空白或被打回）状态时才查一次免车判定，镜像状态已是「完成」/「已放行」时不受影响，不会为每次对账都多查一次。
|
||
- 免车判定与「订单是否需要用车」（`needsVehicle`）是与的关系：`needsVehicle=false` 的户本来就不挂车侧待办，免车判定不改变这类户的行为。
|
||
- 撤回免车（`withdraw`）后，对账逻辑会按原规则重新判断是否需要挂起该待办，不是立即强制重开——若该户此时用车需求确实还未完成，会重新出现。
|
||
|
||
---
|
||
|
||
### 4. 取消成团 `POST /v3/admin/order/group-batch/{groupBatchId}/cancel-group`
|
||
|
||
**VO**: `无请求体 → Result<Void>`
|
||
|
||
#### 使用场景
|
||
|
||
团期详情页「取消成团」按钮，把已成团（RESOURCE_PREPARING）的团期打回招募中（RECRUITING）。判权（`group-batch:manage`）与灰度开关见 `#7608` changelog，本单不改。R10 守卫要求「无已确认子订单 且 无已派单资源」，四项资源里车项此前恒读 `vehicle_ready` 原值；本单起对车项额外剥离「因整团免车而置位」的情形。
|
||
|
||
#### 入参字段表
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|------|------|------|------|------|------|
|
||
| groupBatchId | Path | Long | 是 | - | 团期主订单 ID（不变） |
|
||
|
||
（无请求体。）
|
||
|
||
#### 出参字段表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| data | null | 结构不变，Result<Void> |
|
||
|
||
#### 请求示例
|
||
|
||
```http
|
||
POST /v3/admin/order/group-batch/1867000000002/cancel-group HTTP/1.1
|
||
Authorization: Bearer {token}
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"data": null,
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
无列表/分页语义，不存在空数据形态。灰度开关降级说明见 `#7608` changelog，本单未改。
|
||
|
||
```json
|
||
{ "code": 200, "success": true, "data": null }
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
| 码 | 符号 | 触发 | 本单 |
|
||
|----|------|------|------|
|
||
| 589507 | GROUP_BATCH_PERMISSION_DENIED | 无 group-batch:manage 权限（灰度开关开时） | 不变，见 #7608 |
|
||
| 589500 | GROUP_BATCH_NOT_FOUND | 团期不存在 | 不变 |
|
||
| 589501 | GROUP_BATCH_STATUS_INVALID | 团期不在 RESOURCE_PREPARING | 不变 |
|
||
| 589502 | GROUP_BATCH_CANCEL_GROUP_BLOCKED | 有已确认子订单，或住宿/导游/摄影任一已派单，或车项已派单（免车团不计入车项） | 本单起：免车团不再仅因车项被拦 |
|
||
|
||
```json
|
||
{
|
||
"code": 589502,
|
||
"message": "取消成团被阻塞（有已确认子订单或已派单资源）",
|
||
"data": null,
|
||
"success": false
|
||
}
|
||
```
|
||
|
||
#### 业务边界
|
||
|
||
- 免车团（已声明整团免车、`vehicle_ready=true` 系因此置位）取消成团时，车项不计入「已派单资源」判断；若住宿/导游/摄影三项及已确认子订单数也满足，本次改动后可以取消成团，改前恒被拦。
|
||
- 判定只在 `vehicle_ready=true` 时才去查是否为免车置位（false 时车项本就不算已派单，查了也不改结论），不额外增加常态开销。
|
||
- 取消成团后免车声明本身**不会**被清除（只有整团流团才会关闭正式需求）；`vehicle_ready` 随取消成团一并清零，若免车团再次成团，见下条第 5 项。
|
||
- 若团期是「fleet 真配了车、车项 ready=true 且并非免车声明置位」，本单行为与改前完全一致，仍会被拦。
|
||
|
||
---
|
||
|
||
### 5. 成团 `POST /v3/admin/order/group-batch/{groupBatchId}/group`
|
||
|
||
**VO**: `GroupBatchFormReqVO（可空）→ Result<Void>`
|
||
|
||
#### 使用场景
|
||
|
||
团期从招募中（RECRUITING）人工/自动推进到资源准备中（RESOURCE_PREPARING）。改前对导游/摄影两项按 `needs=false` 免闸置位；本单起对车项同样按「该团是否仍有有效的整团免车声明」做免闸置位——这只在「取消成团 → 再成团」这条路径上才有意义（免车只能在成团之后声明）。
|
||
|
||
#### 入参字段表
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|------|------|------|------|------|------|
|
||
| groupBatchId | Path | Long | 是 | - | 团期主订单 ID（不变） |
|
||
|
||
（请求体字段本单未改，不重复列出。）
|
||
|
||
#### 出参字段表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| data | null | 结构不变，Result<Void> |
|
||
|
||
#### 请求示例
|
||
|
||
```http
|
||
POST /v3/admin/order/group-batch/1867000000002/group HTTP/1.1
|
||
Authorization: Bearer {token}
|
||
Content-Type: application/json
|
||
|
||
{}
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"data": null,
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
不涉及空态。
|
||
|
||
```json
|
||
{ "code": 200, "success": true, "data": null }
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
本单不新增错误码，沿用既有团期状态类错误码（未改）。
|
||
|
||
```json
|
||
{
|
||
"code": 589501,
|
||
"message": "团期状态不允许当前操作",
|
||
"data": null,
|
||
"success": false
|
||
}
|
||
```
|
||
|
||
#### 业务边界
|
||
|
||
- 只在「该团存在未被关闭的整团免车声明」时才会在成团事务内额外置 `vehicle_ready=true`；首次成团（此前从未声明过免车）不受影响。
|
||
- 这一步是「取消成团 → 再成团」闭环的必要补丁：改前若不补这一步，免车团被取消成团后再次成团，`vehicle_ready` 会永远停在 false，物资准备等门会被重新卡住，即使免车声明本身还在。
|
||
- 与导摄免闸置位（`needs=false` 场景）同一次事务、同一份实现风格，互不影响。
|
||
|
||
---
|
||
|
||
### 6. 手工复判物料门 `POST /v3/admin/order/group-batch/{groupBatchId}/recheck-material-gate`
|
||
|
||
**VO**: `无请求体 → Result<GroupBatchMaterialGateRespVO>`
|
||
|
||
#### 使用场景
|
||
|
||
运维/管理员定点解卡用，手工复判「资源准备中 → 物料准备中」四项资源就绪门（住宿/车/导游/摄影），不必等 5 分钟一次的兜底扫描任务。判权 `group-batch:manage`。本单起「车」这一项读的是联动后的 `vehicle_ready`，免车团视为该项已过。
|
||
|
||
#### 入参字段表
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|------|------|------|------|------|------|
|
||
| groupBatchId | Path | Long | 是 | - | 团期主订单 ID（不变） |
|
||
|
||
（无请求体。）
|
||
|
||
#### 出参字段表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| advanced | Boolean | 本次调用是否把团期推进到了物料准备中（结构不变） |
|
||
| currentStatus | String | 复判后团期状态码（结构不变） |
|
||
| currentStatusName | String | 复判后团期状态中文名（结构不变） |
|
||
| blockedGate | String | 未推进时挡住的门：RESOURCE_NOT_READY=房车导摄四项未齐 / CONTRACT_INSURANCE_NOT_READY=合同或保险未出齐；已推进或被并发推进时为 null（本单：免车团不会因车项落在 RESOURCE_NOT_READY） |
|
||
| blockedOrderId | Long（String） | blockedGate=CONTRACT_INSURANCE_NOT_READY 时第一个挡住的子订单 ID（结构不变） |
|
||
|
||
#### 请求示例
|
||
|
||
```http
|
||
POST /v3/admin/order/group-batch/1867000000002/recheck-material-gate HTTP/1.1
|
||
Authorization: Bearer {token}
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
免车团、住宿导摄也齐、合同保险未齐：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"success": true,
|
||
"data": {
|
||
"advanced": false,
|
||
"currentStatus": "RESOURCE_PREPARING",
|
||
"currentStatusName": "资源准备中",
|
||
"blockedGate": "CONTRACT_INSURANCE_NOT_READY",
|
||
"blockedOrderId": "2098979230573330434"
|
||
}
|
||
}
|
||
```
|
||
|
||
对照：同一团合同保险也齐全：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"success": true,
|
||
"data": {
|
||
"advanced": true,
|
||
"currentStatus": "MATERIAL_PREPARING",
|
||
"currentStatusName": "物料准备中",
|
||
"blockedGate": null,
|
||
"blockedOrderId": null
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
幂等设计：重复调用第二次因状态已变，`advanced=false`、`blockedGate` 按当前实际状态给出，不是错误。
|
||
|
||
```json
|
||
{ "code": 200, "success": true, "data": { "advanced": false, "blockedGate": null } }
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
本单不新增错误码。
|
||
|
||
```json
|
||
{
|
||
"code": 401,
|
||
"message": "未登录或登录已过期",
|
||
"success": false,
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
#### 业务边界
|
||
|
||
- 车项判断委托给与「三、11/12」团期详情/看板同一份 `vehicleReady` 读取（配车完成或整团免车），本节不重复实现一份判断。
|
||
- 免车团若住宿/导游/摄影任一未齐，仍会报 `blockedGate=RESOURCE_NOT_READY`，只是车项本身不再是卡点。
|
||
|
||
---
|
||
|
||
### 7. 手工复判进入待出发硬门 `POST /v3/admin/order/group-batch/{groupBatchId}/recheck-departure-gate`
|
||
|
||
**VO**: `无请求体 → Result<GroupBatchDepartureGateRecheckRespVO>`
|
||
|
||
#### 使用场景
|
||
|
||
运维/管理员定点解卡用，手工复判「物资准备中 → 待出发」七项硬门（团期已成团/房车导摄四项配齐/物资已确认/子订单已确认/出行人证件完整/合同保险全齐/主报账人已设）。判权 `group-batch:manage`。本单只影响门②「房车导摄四项配齐」（`gateCode=RESOURCE_READY`）对免车团的判定。
|
||
|
||
#### 入参字段表
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|------|------|------|------|------|------|
|
||
| groupBatchId | Path | Long | 是 | - | 团期主订单 ID（不变） |
|
||
|
||
（无请求体。）
|
||
|
||
#### 出参字段表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| advanced | Boolean | 本次是否推进到「待出发」（结构不变） |
|
||
| notApplicable | Boolean | 团期不存在或当前状态不是「物资准备中」时为 true，此时 gates 为空数组（结构不变） |
|
||
| currentStatus | String | 复判时刻团期状态码（结构不变） |
|
||
| currentStatusName | String | 复判时刻团期状态中文名（结构不变） |
|
||
| blockedGateNames | String | 未通过的门中文名逗号串；全通过或未求值时为空串（本单：免车团不会再含「房车导摄四项配齐」） |
|
||
| gates[] | List<GroupBatchDepartureGateVO> | 七项硬门逐项结果，字段 gateCode/gateName/passed/failReason/blockedOrderId（结构不变） |
|
||
|
||
`gates[]` 中 `gateCode=RESOURCE_READY`（门②）一项：改前读四项资源 ready 位原值；本单起车项同导摄免闸位同口径——免车团该子判定视为已过。
|
||
|
||
#### 请求示例
|
||
|
||
```http
|
||
POST /v3/admin/order/group-batch/1867000000002/recheck-departure-gate HTTP/1.1
|
||
Authorization: Bearer {token}
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
免车团、门②之外还有一门未过（如合同保险）：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"success": true,
|
||
"data": {
|
||
"advanced": false,
|
||
"notApplicable": false,
|
||
"currentStatus": "MATERIAL_PREPARING",
|
||
"currentStatusName": "物资准备中",
|
||
"blockedGateNames": "合同保险全齐",
|
||
"gates": [
|
||
{ "gateCode": "RESOURCE_READY", "gateName": "房车导摄四项配齐", "passed": true, "failReason": null, "blockedOrderId": null },
|
||
{ "gateCode": "CONTRACT_INSURANCE", "gateName": "合同保险全齐", "passed": false, "failReason": "子订单 2098979230573330434 合同状态 未出具（需 SIGNED）", "blockedOrderId": "2098979230573330434" }
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
对照：撤回免车后同一团重新调用，门②失败：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"success": true,
|
||
"data": {
|
||
"advanced": false,
|
||
"notApplicable": false,
|
||
"currentStatus": "MATERIAL_PREPARING",
|
||
"currentStatusName": "物资准备中",
|
||
"blockedGateNames": "房车导摄四项配齐",
|
||
"gates": [
|
||
{ "gateCode": "RESOURCE_READY", "gateName": "房车导摄四项配齐", "passed": false, "failReason": null, "blockedOrderId": null }
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
团期不存在或不在「物资准备中」时 `notApplicable=true`、`gates` 为空数组，不是错误。
|
||
|
||
```json
|
||
{ "code": 200, "success": true, "data": { "notApplicable": true, "gates": [] } }
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
本单**零新增错误码**（沿用既有设计：状态不符返回回执而非抛错）。
|
||
|
||
```json
|
||
{
|
||
"code": 401,
|
||
"message": "未登录或登录已过期",
|
||
"success": false,
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
#### 业务边界
|
||
|
||
- 门②委托给与「三、6」同一份四项资源就绪判定，车项同样认整团免车。
|
||
- 七门全部通过会真的把团期推进到「待出发」，取证/联调时若不希望真推进，需确保至少一门未过。
|
||
- 撤回免车后，门②对该团重新按 `vehicle_ready=false` 判定不通过，直到重新免车或 fleet 真配车。
|
||
|
||
---
|
||
|
||
### 8. 团期合同保险面板 `GET /v3/admin/order/group-batch/{groupBatchId}/contracts`
|
||
|
||
**VO**: `无请求体 → Result<GroupBatchContractBoardVO>`
|
||
|
||
#### 使用场景
|
||
|
||
团期详情页「合同保险」Tab 面板，展示顶部三格统计与逐户明细，`issuable` 控制「手动开合同/保险」按钮是否可用。判权 `group-batch:view`（读，未改）。本单只影响 `issuable` 对免车团的取值。
|
||
|
||
#### 入参字段表
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|------|------|------|------|------|------|
|
||
| groupBatchId | Path | Long | 是 | - | 团期主订单 ID（不变） |
|
||
|
||
（无请求体。）
|
||
|
||
#### 出参字段表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| issuable | Boolean | 是否可以出具合同/保险（本单：免车团车项不再单独卡住该值） |
|
||
| currentStatus | String | 团期状态存储值（issuable=false 时前端可据此提示还差什么，结构不变） |
|
||
| （其余逐户明细字段） | - | 结构不变，本单未改 |
|
||
|
||
#### 请求示例
|
||
|
||
```http
|
||
GET /v3/admin/order/group-batch/1867000000002/contracts HTTP/1.1
|
||
Authorization: Bearer {token}
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
免车团、房导摄三项也齐：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"success": true,
|
||
"data": {
|
||
"issuable": true,
|
||
"currentStatus": "RESOURCE_PREPARING"
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
不涉及空态；团期不存在直接报错误码。
|
||
|
||
```json
|
||
{ "code": 200, "success": true, "data": { "issuable": false, "currentStatus": "RESOURCE_PREPARING" } }
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
本单不新增错误码。
|
||
|
||
```json
|
||
{
|
||
"code": 589500,
|
||
"message": "团期不存在",
|
||
"success": false,
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
#### 业务边界
|
||
|
||
- `issuable` 的四项资源判定与「三、6/7」同一份实现委托，车项同口径认整团免车。
|
||
|
||
---
|
||
|
||
### 9. 手动开合同/保险 `POST /v3/admin/order/group-batch/{groupBatchId}/contracts/issue`
|
||
|
||
**VO**: `GroupBatchContractIssueReqVO → Result<GroupBatchIssueResultVO>`
|
||
|
||
#### 使用场景
|
||
|
||
团期详情页「合同保险」Tab 逐户手动开具，已出具的户自动跳过。判权 `group-batch:contract:issue`（未改）。本单只影响四项资源就绪前置（`589548`）对免车团的车项判断。
|
||
|
||
#### 入参字段表
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|------|------|------|------|------|------|
|
||
| groupBatchId | Path | Long | 是 | - | 团期主订单 ID（不变） |
|
||
| orderIds | Body | List\<Long\> | 否 | 为空表示全部尚未出具的户 | 不变 |
|
||
| target | Body | String | 是 | CONTRACT/INSURANCE/BOTH | 出具目标（不变） |
|
||
|
||
#### 出参字段表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| data | GroupBatchIssueResultVO | 结构不变，本单未改 |
|
||
|
||
#### 请求示例
|
||
|
||
```json
|
||
{ "orderIds": [2098979230573330434], "target": "CONTRACT" }
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"success": true,
|
||
"data": { "successCount": 1, "skippedCount": 0, "failedCount": 0 }
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
不涉及空态。
|
||
|
||
```json
|
||
{ "code": 200, "success": true, "data": { "successCount": 0, "skippedCount": 0, "failedCount": 0 } }
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
| 码 | 符号 | 触发 | 本单 |
|
||
|----|------|------|------|
|
||
| 589548 | 字面量码（团期未达四项配齐门） | 房/车/导/摄四项未配齐 | 免车团不再因车项报这个码 |
|
||
|
||
```json
|
||
{
|
||
"code": 589548,
|
||
"message": "房/车/导/摄四项配齐后才能出具合同与保险",
|
||
"success": false,
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
#### 业务边界
|
||
|
||
- 前置判定与「三、6/7/8」同一份四项资源就绪委托，车项同口径认整团免车。
|
||
- 作废重开端点 `POST .../contracts/reissue` 复用同一份服务实现，行为同构（本清单未单列，契约与本条一致）。
|
||
|
||
---
|
||
|
||
### 10. 发起团期预支 `POST /v3/admin/order/group-batch/{groupBatchId}/advance`
|
||
|
||
**VO**: `CreateGroupBatchAdvanceReqVO → Result<OrderAdvanceRespVO>`
|
||
|
||
#### 使用场景
|
||
|
||
团期详情页发起团期级预支，创建一条待站内财务审批的预支单。判权 `group-batch:finance:advance`（未改）。双前置闸门：团期状态门（589541，未改）+ 四项资源就绪门（589542）。本单只影响后者对免车团车项的判断。
|
||
|
||
#### 入参字段表
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|------|------|------|------|------|------|
|
||
| groupBatchId | Path | Long | 是 | - | 团期主订单 ID（不变） |
|
||
| （请求体五字段） | Body | - | - | 与订单级预支一致 | 结构不变，本单未改 |
|
||
|
||
#### 出参字段表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| advanceId | Long（String） | 预支单 ID（结构不变） |
|
||
| status | String | 预支单状态（结构不变） |
|
||
|
||
#### 请求示例
|
||
|
||
```json
|
||
{ "amount": 5000.00, "borrowerType": "DRIVER", "voucherUrls": [] }
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"success": true,
|
||
"data": { "advanceId": "1900000000000000123", "status": "PENDING_APPROVAL" }
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
不涉及空态。
|
||
|
||
```json
|
||
{ "code": 200, "success": true, "data": { "advanceId": null } }
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
| 码 | 符号 | 触发 | 本单 |
|
||
|----|------|------|------|
|
||
| 589541 | 字面量码（团期阶段门） | 团期不在物料准备中/待出发/出行中 | 不变 |
|
||
| 589542 | 字面量码（四项资源就绪门） | 房/车/导/摄四项未全就绪 | 免车团不再因车项报这个码 |
|
||
|
||
```json
|
||
{
|
||
"code": 589542,
|
||
"message": "房 / 车 / 导 / 摄四项配齐后才能预支",
|
||
"success": false,
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
#### 业务边界
|
||
|
||
- 前置判定与「三、6/7/8/9」同一份四项资源就绪委托，车项同口径认整团免车。
|
||
- 金额上限走团期统一池（团期级与子订单级共扣一池），本单未改。
|
||
|
||
---
|
||
|
||
### 11. 团期详情 `GET /v3/admin/order/group-batch/{groupBatchId}`
|
||
|
||
**VO**: `无请求体 → Result<GroupBatchDetailRespVO>`
|
||
|
||
#### 使用场景
|
||
|
||
团期详情页整页数据源，`vehicleReady` 是「四项资源就绪」展示区块的一个字段。本单只改这一个字段的**含义**，字段名/类型/路径不变。
|
||
|
||
#### 入参字段表
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|------|------|------|------|------|------|
|
||
| groupBatchId | Path | Long | 是 | - | 团期主订单 ID（不变） |
|
||
|
||
（无请求体。）
|
||
|
||
#### 出参字段表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| hotelReady | Boolean | 配房完成标志（不变） |
|
||
| vehicleReady | Boolean | **语义扩大**：改前=「fleet 团级配车就绪」；改后=「配车完成或整团免车」，字段名/类型/路径均不变 |
|
||
| guideReady | Boolean | 导游完成标志（不变） |
|
||
| photographerReady | Boolean | 摄影完成标志（不变） |
|
||
| （其余团期详情字段） | - | 结构不变，本单未改 |
|
||
|
||
#### 请求示例
|
||
|
||
```http
|
||
GET /v3/admin/order/group-batch/1867000000002 HTTP/1.1
|
||
Authorization: Bearer {token}
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
免车团（未经 fleet 真配车，仅声明免车）：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"success": true,
|
||
"data": {
|
||
"groupBatchId": "1867000000002",
|
||
"hotelReady": true,
|
||
"vehicleReady": true,
|
||
"guideReady": true,
|
||
"photographerReady": true
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
不涉及空态；团期不存在报 589500。
|
||
|
||
```json
|
||
{ "code": 589500, "success": false, "data": null }
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
本单不新增错误码。
|
||
|
||
```json
|
||
{
|
||
"code": 589500,
|
||
"message": "团期不存在",
|
||
"success": false,
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
#### 业务边界
|
||
|
||
- `vehicleReady=true` **不能**再简单等同于「fleet 已经排好车」——它现在是「车侧不再阻塞下游门」的合并信号。若前端页面需要精确区分「真配车」与「声明免车」两种情况分别展示不同图标/文案，本单不提供额外字段，需要的话应在另一张单里新增专用字段（本单只按既定契约扩大既有字段含义，不新增字段）。
|
||
- 撤回免车后该字段随之回落为 fleet 侧真实状态（若 fleet 尚未真配车则为 false）。
|
||
|
||
---
|
||
|
||
### 12. 团期看板 `GET /v3/admin/order/group-batch/board`
|
||
|
||
**VO**: `无请求体（Query: productId 必填, scope 可选）→ Result<List<GroupBatchBoardItemRespVO>>`
|
||
|
||
#### 使用场景
|
||
|
||
团期管理看板，按产品维度列出各团期的资源就绪概览。`vehicleReady` 字段含义变化与「三、11」完全一致，只是这里是列表形态。
|
||
|
||
#### 入参字段表
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|------|------|------|------|------|------|
|
||
| productId | Query | Long | 是 | - | 产品 ID（不变） |
|
||
| scope | Query | String | 否 | - | 范围过滤（不变） |
|
||
|
||
#### 出参字段表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| [].hotelReady | Boolean | 配房完成标志（不变） |
|
||
| [].vehicleReady | Boolean | **语义扩大**：同「三、11」，配车完成或整团免车 |
|
||
| [].guideReady | Boolean | 导游就绪标志（不变） |
|
||
| （其余看板项字段） | - | 结构不变，本单未改 |
|
||
|
||
#### 请求示例
|
||
|
||
```http
|
||
GET /v3/admin/order/group-batch/board?productId=2045390643479412737 HTTP/1.1
|
||
Authorization: Bearer {token}
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"success": true,
|
||
"data": [
|
||
{ "groupBatchId": "1867000000002", "hotelReady": true, "vehicleReady": true, "guideReady": true, "photographerReady": true }
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
该产品无团期时返回空数组，不是错误。
|
||
|
||
```json
|
||
{ "code": 200, "success": true, "data": [] }
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
本单不新增错误码。
|
||
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"message": "productId 不能为空",
|
||
"success": false,
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
#### 业务边界
|
||
|
||
- 同「三、11」的边界说明：`vehicleReady=true` 不再等同「真配车」，前端如需区分请勿在本字段上做强假设。
|
||
|
||
---
|
||
|
||
### 13. 团期待配车候选查询（内部） `POST /v3/internal/group-batch/vehicle-dispatch-candidates`
|
||
|
||
**VO**: `GroupBatchVehicleDispatchCandidateReqDTO（hl-common，Body）→ Result<PageResult<GroupBatchVehicleDispatchCandidateDTO>>`
|
||
|
||
#### 使用场景
|
||
|
||
hl-fleet-service 经内部 Feign 调用，查询「需求已确认但车未就绪」的团期候选，供车管后台「待配车」清单（见下条「14」）间接消费。仅限内部 Feign 调用，不经网关暴露给前端；本单不改请求体、响应结构、错误码，只改过滤条件命中的团期集合——免车团声明成立后不再落在候选集合里。
|
||
|
||
#### 入参字段表
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|------|------|------|------|------|------|
|
||
| requirementConfirmed | Body | Boolean | 否 | - | 过滤「整团需求是否已确认」（不变） |
|
||
| vehicleReady | Body | Boolean | 否 | - | 过滤「配车是否已就绪」；取值来源已随本单变化——免车团声明成立后该值联动为已就绪（参数本身不变） |
|
||
| （其余分页/日期过滤字段） | Body | - | - | 结构不变 | 本单未改 |
|
||
|
||
#### 出参字段表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| records[].groupBatchId | Long | 团期主订单 ID（不变） |
|
||
| records[].vehicleReady | Boolean | 联动后的配车/免车就绪值（字段不变，取值随本单变化） |
|
||
| （其余候选字段） | - | 结构不变，本单未改 |
|
||
|
||
#### 请求示例
|
||
|
||
```json
|
||
{ "requirementConfirmed": true, "vehicleReady": false, "page": 1, "pageSize": 50 }
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
免车团声明成立前出现在候选里，成立后同一次查询消失（撤回免车后重新出现）：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"success": true,
|
||
"data": { "records": [ { "groupBatchId": 1867000000003, "vehicleReady": false } ], "total": 1 }
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
无匹配候选时 `records` 为空数组，不是错误。
|
||
|
||
```json
|
||
{ "code": 200, "success": true, "data": { "records": [], "total": 0 } }
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
本单不新增错误码，沿用既有内部校验错误码。
|
||
|
||
```json
|
||
{ "code": 809401, "message": "请求参数非法", "success": false, "data": null }
|
||
```
|
||
|
||
#### 业务边界
|
||
|
||
- 本端点自身代码零改动，过滤条件 `vehicleReady` 读取的列值来源已随本单变化（见「⚠️ 关键变化」第 2 条）；免车团声明成立后不落在候选集合里，与「14、待配车团期清单（车管后台）」的表现联动一致（该清单经本端点间接取数）。
|
||
- 仅限内部 Feign 调用，不经网关暴露；调用方为 `hl-fleet-service`。
|
||
- 本单本轮未对本端点单独做网关/直连取证（内部 Feign 端点），行为按源码核对（过滤条件复用既有查询实现，仅联动字段来源变化）与「14」端点车管后台侧的间接观测印证，见第八节说明。
|
||
|
||
---
|
||
|
||
### 14. 待配车团期清单（车管后台） `GET /admin/fleet/group-dispatch/pending-batches`
|
||
|
||
**VO**: `GroupDispatchPendingBatchPageReqVO（Query）→ Result<PageResult<GroupDispatchPendingBatchRespVO>>`
|
||
|
||
> 服务：hl-fleet-service（本单车管后台自身代码零改动，清单变化是因为它查询的团期主数据固定按 `requirementConfirmed=true 且 vehicleReady=false` 过滤，而 `vehicleReady` 的取值来源已随本单变化——见 `#7440` changelog 获取该端点完整字段与错误码定义，本节只描述本单带来的**数据**变化）。
|
||
|
||
#### 使用场景
|
||
|
||
车务后台「待配车」列表，展示需求已确认但车还没配好的团期。判权/网关路由本单未改（沿用 `/admin/fleet/**` → `hl-fleet-service` 既有路由）。
|
||
|
||
#### 入参字段表
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|------|------|------|------|------|------|
|
||
| departDateFrom | Query | LocalDate | 否 | 出发日下界 | 不变 |
|
||
| departDateTo | Query | LocalDate | 否 | 出发日上界 | 不变 |
|
||
| keyword | Query | String | 否 | 团号/团名模糊，≤50 字符 | 不变 |
|
||
| dispatchProgress | Query | String | 否 | NOT_STARTED/PARTIAL/FULL | 不变 |
|
||
| page | Query | Integer | 否 | 默认 1 | 不变 |
|
||
| pageSize | Query | Integer | 否 | 默认 20，1-100 | 不变 |
|
||
|
||
#### 出参字段表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| records[].groupBatchId | Long（String） | 团期主订单 ID（不变） |
|
||
| records[].requirementConfirmed | Boolean | 整团需求是否已确认（不变，本单不改这一维过滤条件） |
|
||
| records[].vehicleReady | Boolean | 配车是否已就绪（不变；但清单本身的过滤条件用的是同一个联动后的值，免车团不会出现在这里） |
|
||
| （其余字段：batchNo/batchName/departDate/dispatchProgress 等） | - | 结构不变，本单未改 |
|
||
|
||
#### 请求示例
|
||
|
||
```http
|
||
GET /admin/fleet/group-dispatch/pending-batches?page=1&pageSize=20 HTTP/1.1
|
||
Authorization: Bearer {token}
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
免车团在声明免车之前出现在清单里；声明免车后同一次分页查询里该团消失（`vehicleReady` 过滤条件命中，不再满足「未就绪」）：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"success": true,
|
||
"data": {
|
||
"records": [
|
||
{ "groupBatchId": "1867000000003", "batchNo": "GB-26-0920-01", "requirementConfirmed": true, "vehicleReady": false, "dispatchProgress": "NOT_STARTED" }
|
||
],
|
||
"total": 1,
|
||
"page": 1,
|
||
"pageSize": 20
|
||
}
|
||
}
|
||
```
|
||
|
||
撤回免车后该团重新出现在清单里。
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
无匹配团期时 `records` 为空数组；order-v3 团期基线不可达时返回 600012 而非静默空列表（不变，见 `#7440` changelog）。
|
||
|
||
```json
|
||
{ "code": 200, "success": true, "data": { "records": [], "total": 0 } }
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
| 码 | 符号 | 触发 | 本单 |
|
||
|----|------|------|------|
|
||
| 600012 | 字面量码（团期配车基线不可达） | order-v3 降级或返错 | 不变，见 #7440 |
|
||
| 600013 | 字面量码（排班查询参数非法） | 日期倒置/分页越界/关键词超长/进度枚举非法 | 不变 |
|
||
| 401 | 未登录 | 网关拦截 | 不变 |
|
||
|
||
```json
|
||
{
|
||
"code": 600012,
|
||
"message": "团期配车基线不可达，请稍后重试",
|
||
"success": false,
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
#### 业务边界
|
||
|
||
- 本端点自身逻辑与判权一个字都没改，「免车团消失/重现」是团期主数据源头（`vehicleReady`）联动的结果，不是本端点新增的过滤规则。
|
||
- 车务侧若之前依赖「这份清单里没有的团=不用管」的假设，需要知道免车团现在也会从这份清单里消失，但**不代表该团不需要任何车侧关注**（结算侧仍按免车声明整户跳过车侧结算，业务上是自洽的）。
|
||
- 单团配车总览 `GET .../batches/{groupBatchId}/overview` 与资源排班 `GET .../resource-schedule` 两个同 Controller 端点，本单未改，不受影响。
|
||
|
||
---
|
||
|
||
## 四、契约约束与正确调用方式
|
||
|
||
### 正确 / 错误 调用结果对照
|
||
|
||
| 场景 | 结果 |
|
||
|------|------|
|
||
| 前端按「`vehicleReady=true` 就是 fleet 已经排好车」渲染专属「已排车」图标（错误） | 本单起该字段也会因整团免车而为 true，按此假设渲染会误导用户 |
|
||
| 前端把「免车团从 fleet 待配车清单消失」当成「该团车务侧完全不需要关注」（错误） | 清单过滤只是不再要求配车，业务上团仍然是「免车」而非「未处理」，不应被解读为异常 |
|
||
| 先撤回免车、再让 fleet 配车（正确） | `vehicleReady` 由撤回复位为 false，之后 fleet 回调真实置位，两者不冲突 |
|
||
| 免车期间先让 fleet 按团期 ID 配车、之后再撤回免车（不推荐，已知缺口） | 撤回会把 `vehicle_ready` 清成 false，即使 fleet 已真就绪，团会重新卡门直到 fleet 再回调一次；见「业务边界」 |
|
||
|
||
### 切换状态时的必要动作
|
||
|
||
前端不需要为本单改动任何请求参数——14 个端点的入参/路径全部不变，只是响应值会随团期是否声明免车而不同。前端唯一需要做的是**不要对 `vehicleReady`（及其下游门的通过/拦截结果）做「必然等于 fleet 已配车」的强假设**。
|
||
|
||
---
|
||
|
||
## 五、数据库行为
|
||
|
||
免车声明（`waive`）与撤回（`withdraw`）本身的写操作在此前的 changelog 已交代，本单不改这两个端点的请求/响应契约。本单新增的外部可观察写行为是：
|
||
|
||
- 声明整团免车成功后，同一次调用内团级「配车/免车就绪」标志被置为已就绪，随之在同一把团期锁内尝试推进团期到「物料准备中」（推进失败只记日志，不影响本次调用的成功返回，由既有兜底扫描任务补推）；同时对在团户逐一核对「是否只差车」，满足的户从「资源准备中」推进到「待确认」，对应的「用车需求 · 待提交」待办同步标记完成。
|
||
- 撤回整团免车成功后，团级「配车/免车就绪」标志被复位（不影响团期主状态本身，团期不会因此回退阶段）；对满足条件（未确认行程、且车侧确实未完成）的在团户，逐一从「待确认」回退到「资源准备中」，对应待办重新挂起；已经确认行程的户不回退（结算环节仍会因车侧未就绪而拦截）。
|
||
- fleet 团级配车清零回调（既有端点，本单不改契约）若发生在「免车声明仍然有效」期间，本单起会在同一次回调里把团级就绪标志重新置回已就绪（免车声明优先于清零），避免团被误伤打回。
|
||
- 以上写行为均随各自既有事务提交，不额外引入 Feign/MQ 同步写。
|
||
|
||
---
|
||
|
||
## 六、边界行为
|
||
|
||
- 未登录 → 401（网关拦截，14 个端点均未改）
|
||
- 无权限 → 各端点沿用既有判权码，未改
|
||
- 团期/订单不存在 → 各端点沿用既有错误码，未改
|
||
- 免车团 → 见上文逐条端点的「本单」列
|
||
- 非免车团 → 14 个端点行为与改前逐字节一致
|
||
- 撤回免车后仍处于阻塞窗口（fleet 真配车发生在免车声明期间、之后又撤回）→ 已知缺口，见「业务边界」，须待 `#7442` 收口
|
||
- 老数据兼容：存量团期若从未使用过 `waive`/`withdraw`，14 个端点行为完全不受影响
|
||
|
||
---
|
||
|
||
## 六.6、修改前后对比
|
||
|
||
### 字段级对比
|
||
|
||
| 字段 | 改前 | 改后 |
|
||
|------|------|------|
|
||
| `GET .../group-batch/{groupBatchId}` 与 `board` 的 `vehicleReady` | 语义：fleet 团级配车就绪 | 语义：配车完成或整团免车（字段名/类型/路径不变） |
|
||
| `confirm-checklist` 的 `items[VEHICLE_DONE].passed` | 免车团的户恒 false（除非需求行也 DONE） | 免车团的户直接 true |
|
||
| `order-todos` 的 `ASSIGN_VEHICLE` 待办 | 免车团的户恒挂起 | 免车团的户自动完成，撤回后重开 |
|
||
|
||
### 行为级对比
|
||
|
||
| 行为 | 改前 | 改后 |
|
||
|------|------|------|
|
||
| 免车团取消成团（R10 守卫） | 车项恒计入「已派单资源」，常被拦 589502 | 车项不计入（若住宿/导游/摄影/已确认子订单也满足，可以取消） |
|
||
| 免车团再次成团 | `vehicleReady` 停在 false | 免车声明仍有效时同步置 true |
|
||
| 免车团手工复判物料门 | `blockedGate` 常落在 RESOURCE_NOT_READY（车项未过） | 车项不再是卡点 |
|
||
| 免车团出发门②（房车导摄四项配齐） | 恒 fail | 通过（其余三项齐备时） |
|
||
| 免车团合同出具/预支 | 恒因四项未齐报错 | 车项不再单独卡住 |
|
||
| 免车团出现在 fleet 待配车清单 | 恒出现 | 消失（撤回免车后重现） |
|
||
|
||
---
|
||
|
||
## 六.7、影响评估
|
||
|
||
- **是否破坏向后兼容**: 是。14 个既有端点的**返回值**在「团期已声明整团免车」这一数据条件下会发生变化（契约结构不变）。这是本单的设计目的：让「本团无需用车」声明真正在各处生效，而不是只写一张孤立的表。
|
||
- **前端是否必须同步上线**: 视情况。若前端此前对这些字段/门禁结果没有做「必然等于 fleet 真配车」的强假设，代码可以零改动；若做了这类假设（例如按 `vehicleReady` 渲染专属「已排车」图标、或把 fleet 待配车清单当成车务全量待办清单），需要同步调整文案/图标含义。
|
||
- **前端 workaround 清理点**: 若前端此前因为「免车团车侧四项门永远打不开」而对这几个页面做过特殊跳过逻辑（例如手动提示运营去走流团），本单合并部署后可以清理——四项门本身会随免车声明正常打开。
|
||
|
||
---
|
||
|
||
## 七、不影响范围
|
||
|
||
- **仅影响**: 上述 14 个端点在「该团已声明整团免车」这一数据条件下的返回**值**；14 个端点自身的方法/路径/参数/响应结构/错误码码值与文案**全部不变**。
|
||
- **零影响**:
|
||
- 非免车团在全部 14 个端点上的行为——完全不变。
|
||
- `POST .../vehicle-requirement/waive`、`POST .../vehicle-requirement/withdraw` 自身的请求/响应契约——本单不改，只是它们产生的结果被下游读口消费。
|
||
- `#7441` PR-4（整团确认接车侧，`confirm-check`/`confirm`）——另一份独立 changelog 覆盖，与本单是并列关系，PR-4 需先于本单合并。
|
||
- `#7441` PR-3 已上线的结算闸（`584131`/`584100`）与户级团车完成回写（PR-2/2b/2c 已上线）——本单不改其契约，只是新增了一个共用的只读免车判定服务，供本单与既有结算闸共同使用。
|
||
- `hl-common-*`、`hl-gateway` 路由——本单只改 `hl-order-service-v3`，`hl-fleet-service` 零代码改动（仅消费方数据变化）；`/v3/admin/**`、`/admin/fleet/**` 路由沿用既有通配，未新增路由配置。
|
||
- 权限点——未新增。
|
||
|
||
---
|
||
|
||
## 八、测试环境已验证
|
||
|
||
**取证环境**：order-v3 = dev-v3 `f0277a14f`（2026-09-16 01:21 部署，含 PR-4 与本单 PR-2d/2e 全部改动），经 `hl-gateway` 网关真实调用。
|
||
|
||
**已声明整团免车的团，经真实 `waive` 调用后取证（本单核心新增联动，见工单 #7441 验收评论 54939（AC-29c）与 54942（AC-36e / AC-36g / AC-36h / AC-36i）**：
|
||
|
||
1. `GET /v3/admin/order/{id}/confirm-checklist`：免车团某户残留一条 `PENDING_REVIEW` 用车需求时，`items[code=VEHICLE_DONE].passed=true`；撤回免车（`withdraw`）后对同一订单发起同一请求，变为 `passed=false`，`failReason="用车需求未完成（镜像: PENDING_REVIEW，当前需求: PENDING_REVIEW）"`——两次调用是同一订单、同一路径的真实前后对照。
|
||
2. `POST /v3/admin/order/{id}/confirm-itinerary`：免车团内两户分别调用均成功（`code=200`），实际响应字段为 `{success, oldStatus, newStatus, oldFlowStatus, newFlowStatus, triggeredEvents}`（例：`oldStatus=CUSTOMIZING` → `newStatus=PENDING_DEPARTURE`，`triggeredEvents=["ASYNC_CONTRACT_GENERATE","ASYNC_INSURANCE_ISSUE"]`），未报 581036。
|
||
3. `POST /v3/admin/order/group-batch/{groupBatchId}/cancel-group`：免车团（活跃 `waive` 声明仍在）调用成功（`code=200`）；对照同一批次里非免车团（车侧经 fleet 真实回调就绪）调用同一端点，返回 `code=589502`，`message="取消成团被阻塞（有已确认子订单或已派单资源）"`——两次调用坐实「免车团车项不计入已派单资源」。
|
||
4. `POST /v3/admin/order/group-batch/{groupBatchId}/group`：免车团取消成团后（`waive` 声明仍在）再次成团，`code=200`；紧接 `SELECT batch_status, vehicle_ready FROM order_group_batch` 显示 `vehicle_ready` 由取消成团时的 `0` 回填为 `1`，坐实「免车声明仍有效时成团同步置位」。
|
||
|
||
**`vehicleReady` 联动读取机制经真实数据验证，但本轮取证用的是 fleet 真实回调置位而非 `waive` 声明——同一字段来源，未针对『已声明免车』这一具体数据源单独复测以下 5 个端点**：
|
||
|
||
5. `GET /v3/admin/order/group-batch/{groupBatchId}`：fleet 回调前 `vehicleReady=false`，回调后同一团 `vehicleReady=true`，其余字段不变；免车团路径本身未经该端点单独复测。
|
||
6. `POST .../recheck-material-gate`：`blockedReason` 文案由「车=未配置」变为「车=已配置」，`blockedGate` 仍因房未配齐落在 `RESOURCE_NOT_READY`——证明车项判断已跟随联动字段，未取得车项放行后 `blockedGate` 变为合同保险门的完整对照（该团房侧全程未配置）。
|
||
7. `POST .../recheck-departure-gate`：该团尚未进入「物资准备中」，两次调用均 `notApplicable=true`、`gates=[]`，未取得门②真实通过/拦截的对照样本。
|
||
8. `GET .../contracts`：`issuable` 在车项就绪前后均为 `false`（该团房侧未配置，`issuable` 由四项资源共同决定），未取得车项单独放行到 `issuable=true` 的样本。
|
||
9. `POST .../advance`：调用返回 `589541`（团期阶段门，该团仍在 `RESOURCE_PREPARING`，未到「物料准备中」），车项四项资源门（`589542`）未被触发到，本轮未取得该错误码退场的直接对照。
|
||
|
||
**本轮未经网关实测，按源码核对列示（仅代码核对）**：`GET /v3/admin/order-todos/my/page`（待办自动完成/重开）、`POST .../contracts/issue`（手动开具豁免 589548）、`GET /v3/admin/order/group-batch/board`（看板字段语义）、`POST /v3/internal/group-batch/vehicle-dispatch-candidates`（内部候选过滤，见「三、13」业务边界）、`GET /admin/fleet/group-dispatch/pending-batches`（车管后台清单，见「三、14」业务边界）——以上 5 个端点的字段与行为已按源码逐一核对（见各自「出参字段表」），示例响应仍是按源码拼装的合理构造，不是实测原文。
|
||
|
||
---
|
||
|
||
## 十、相关文档
|
||
|
||
- 关联 Issue: [wx/HL#7441](https://git.1814.love:8443/wx/HL/issues/7441)
|
||
- 关联 PR: [#7778](https://git.1814.love:8443/wx/HL/pulls/7778)（squash 合入 dev-v3，合并提交 `f0277a14f`）
|
||
- 前置依赖：`#7441` PR-4（整团确认接车侧，同一个 PR #7778 内，另一份 changelog 覆盖）、`#7441` PR-1/PR-2/PR-2b/PR-2c/PR-3（免车声明端点、结算闸，均已合并 dev-v3）、`#7608`（取消成团判权改造，本单未改判权逻辑）、`#7440`（车管后台待配车团期清单首次交付，本单只改其过滤结果，不改其契约）
|
||
- 后续计划：`#7442`（团期配车写口通电）需收口「免车期间 fleet 真配车、之后撤回免车导致重新卡门」这一已知缺口（见「⚠️ 关键变化」第 6 条）
|
||
- **验收口径边界**：页面完成状态单独跟踪（前端归 mmg），不计入 #7441 验收；#7441 验收范围 = API 契约 + 状态流转 + 占用账本 + changelog 交接件。
|
||
|
||
## 关联 / 联系人
|
||
|
||
### 链接
|
||
|
||
- **Issue**: [#7441](https://git.1814.love:8443/wx/HL/issues/7441)
|
||
- **PR**: [#7778](https://git.1814.love:8443/wx/HL/pulls/7778)
|
||
- **Merge commit**: `f0277a14f`
|
||
|
||
### 联系人
|
||
|
||
- **后端负责人**: @wx
|
||
- **前端负责人（收件人）**: @mmg
|
||
|