diff --git a/changelogs-v2/2026-09/23_8218_行程用车状态文案按kind分叉-修改接口-mmg.md b/changelogs-v2/2026-09/23_8218_行程用车状态文案按kind分叉-修改接口-mmg.md deleted file mode 100644 index 160e6dde..00000000 --- a/changelogs-v2/2026-09/23_8218_行程用车状态文案按kind分叉-修改接口-mmg.md +++ /dev/null @@ -1,483 +0,0 @@ ---- -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` - -#### 使用场景 - -管理后台「团期详情」页面的「客户清单」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 | 是否含已取消子订单 | - -#### 出参 `Result>` - -| 字段 | 类型 | 说明 | -|------|------|------| -| 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；不传则两类都返 | 需求类别过滤 | - -#### 出参 `Result` - -| 字段 | 类型 | 说明 | -|------|------|------| -| 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