wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 工作流 软件包 项目 发布 百科 活动

docs(changelog): #8218 行程用车需求 PENDING_REVIEW 文案按 kind 分叉

浏览代码 
两个出口同步调整中文文案：
- 行程用车（TRAVEL）的 PENDING_REVIEW 改为「待提交车务」（等团期管理员整团放行，无逐户审核）
- 接送机（TRANSFER）的 PENDING_REVIEW 仍是「待审核」（有逐户审核动作）

变更接口 2 个，均为查询端点，无新增参数。
后端已部署（dev-v3 commit 7738668b8），前端待改。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
这个提交包含在：
API Changelog Bot
2026-09-23 13:47:33 +08:00
共同撰写人 Claude Opus 5
父节点 d149813991
当前提交 7c56f43ca1
共修改 1 个文件，包含 483 行新增和 0 行删除
下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件
changelogs-v2/2026-09/23_8218_行程用车状态文案按kind分叉-修改接口-admin.md
+483
查看文件
@@ -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: "pending"
frontend_owner: ""
frontend_ref: ""
target_release: ""
verified_at: ""
status_note: ""
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