wx/hl-api-changelog

派生 0

文件

T

API Changelog Bot和Claude Opus 5 0d44436def

changelog-filename-gate / validate (push) Failing after 2s

详情

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>

2026-09-23 13:49:23 +08:00

19 KiB

原始文件 Blame 文件历史

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	8218	行程用车需求 PENDING_REVIEW 文案按 kind 分叉：TRAVEL「待提交车务」/ TRANSFER「待审核」	admin	wx(GIT)	修改接口	deployed	verified	pending						2026-09-23	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 下发「待提交车务」而非「待审核」；无需求行回落「待车队配」

请求示例

GET /v3/admin/order/group-batch/2101506167098511362/orders?page=1&pageSize=20

响应示例

{
  "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
}

空数据 / 降级响应

{
  "code": 200,
  "message": "成功",
  "data": {
    "records": [],
    "pageNumber": 1,
    "pageSize": 20,
    "totalCount": 0
  },
  "success": true
}

错误响应

{
  "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=待审核）

请求示例

GET /v3/admin/order/group-batch/2101506167098511362/requirement/vehicle-households?kind=TRAVEL

响应示例

{
  "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
}

空数据 / 降级响应

{
  "code": 200,
  "message": "成功",
  "data": {
    "groupBatchId": 2101506167098511362,
    "householdCount": 0,
    "vehicleRowCount": 0,
    "countedHouseholdCount": 0,
    "households": []
  },
  "success": true
}

错误响应

{
  "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
后续计划: 前端改动由 mmg 团队负责

关联 / 联系人

链接

Issue: #8218
PR: #8218
后端 commit: 7738668b8

联系人

后端负责人: @wx
前端负责人: @mmg

19 KiB 原始文件 Blame 文件历史 Unescape Escape

order-v3: 行程用车需求状态文案分叉

⚠️ 关键变化

一、背景

二、变更接口清单

三、接口详情

1. 团期下子订单列表 GET /v3/admin/order/group-batch/{groupBatchId}/orders

使用场景

入参字段表

出参字段表

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

2. 团期子订单用车需求记录 GET /v3/admin/order/group-batch/{groupBatchId}/requirement/vehicle-households

使用场景

入参字段表

出参字段表

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

四、契约约束与正确调用方式

状态码与文案的对应关系

调用顺序建议

五、数据库行为

六、边界行为

六.5、枚举 / 数据字典

vehicleRequirementStatus / status（需求状态）

kind（需求类别）

六.6、修改前后对比

字段级对比

行为级对比

六.7、影响评估

七、不影响范围

八、测试环境已验证

十、相关文档

关联 / 联系人

链接

联系人

19 KiB

原始文件 Blame 文件历史

1. 团期下子订单列表 `GET /v3/admin/order/group-batch/{groupBatchId}/orders`

2. 团期子订单用车需求记录 `GET /v3/admin/order/group-batch/{groupBatchId}/requirement/vehicle-households`