diff --git a/changelogs-v2/2026-09/23_8218_行程用车状态文案按kind分叉-修改接口-admin.md b/changelogs-v2/2026-09/23_8218_行程用车状态文案按kind分叉-修改接口-admin.md new file mode 100644 index 00000000..9569012e --- /dev/null +++ b/changelogs-v2/2026-09/23_8218_行程用车状态文案按kind分叉-修改接口-admin.md @@ -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` + +#### 使用场景 + +管理后台「团期详情」页面的「客户清单」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