---
schema: "hl-changelog/v2"
ticket: "7816"
title: "团期子订单需求审核状态中文名修复房车各一套文案"
consumer: "admin"
author: "wx(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "not_required"
frontend_status: "not_required"
frontend_owner: "mmg"
frontend_ref: ""
target_release: ""
verified_at: "2026-09-16"
status_note: "GB-ADM-003 出参 hotelRequirementStatusName / vehicleRequirementStatusName 的取值修正：改前 6 个枚举值中有 5 个翻不出、原样吐英文码（TEST 取样 47 条子订单有 43 条），改后补全 6 值且房车各一套文案。字段名与结构不变，仅取值可观测变化。PR #7823（合并提交 18cfe3e21）已部署 TEST 并逐条取证；字段注释补丁 PR #7826（1e57d7437）为纯文档。前端(2026-09-16 mmg):not_required——grep 实证前端无需求审核码自建映射,RosterTable 需求审核列本就 Name 优先、原码兜底直显,*Name 修复即自动生效;顺带 chore 刷新 orderV2GroupBatch.js 过时注释(hl-admin v2.1 06af23e3)。"
updated_at: "2026-09-16"
base: "dev-v3"
---

# 团期子订单需求审核状态中文名修复房车各一套文案（修改接口）

> **服务**: hl-order-service-v3
> **PR**: #7823、#7826（注释补丁）
> **Issue**: #7816
> **日期**: 2026-09-16
> **影响范围**: 一个既有 GET 读接口的两个出参字段取值修正；字段名与结构不变、无新端点、无路由变化、无 DDL、无新增错误码

---

## ⚠️ 关键变化

🔴 **改前这两个字段在现网大量取值上原样返回英文码。** 前端「需求审核」列会直接显示 `DONE`、`PENDING_REVIEW`、`PROCESSING`。

改后 6 个枚举值全部翻出中文，且**房需求与车需求各一套文案**——车需求不再显示「配房完成」这类房务侧措辞。

---

## 二、变更接口清单

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|---|---|---|---|---|
| 1 | 团期下子订单列表 | GET | `/v3/admin/order/group-batch/{groupBatchId}/orders` | 修改接口 | 出参 `hotelRequirementStatusName` / `vehicleRequirementStatusName` 取值修正 |

---

## 三、接口详情

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

**VO**: `GroupBatchOrderItemRespVO`

#### 使用场景

团期列表页展开子订单、团期详情页「整团名单速览」与「子订单」页签。本次修正的两个字段供「需求审核」列展示。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| groupBatchId | path | string | 是 | 雪花 ID | 团期 ID |
| page | query | integer | 否 | ≥1，缺省 1 | 页码 |
| pageSize | query | integer | 否 | 缺省 20，>200 截断 | 每页条数 |
| includeNeeds | query | boolean | 否 | 缺省 true | 是否附房数/房型/特殊需求 |
| includeCancelled | query | boolean | 否 | 缺省 false | 是否含已取消子订单 |

> 入参本次**无任何变化**。

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| hotelRequirementStatusName | string | **取值修正**。房需求状态中文名；`hotelRequirementStatus` 为 null 时为 null |
| vehicleRequirementStatusName | string | **取值修正**。车需求状态中文名；接单/处理/完成三态措辞与房需求不同 |

完整取值对照：

| 状态码 | 房需求 Name | 车需求 Name |
|---|---|---|
| `PENDING` | 待房务配 | 待车队配 |
| `PROCESSING` | 配房中 | 配车中 |
| `DONE` | 配房完成 | 配车完成 |
| `PENDING_REVIEW` | 待审核 | 待审核 |
| `REJECTED_TO_CONSULTANT` | 已驳回定制师 | 已驳回定制师 |
| `REJECTED_TO_ADMIN` | 已驳回管理员 | 已驳回管理员 |

#### 请求示例

```http
GET /v3/admin/order/group-batch/2100132795706691585/orders?pageSize=200
Authorization: Bearer <admin token>
```

#### 响应示例

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "records": [
      {
        "orderNo": "HL20260916160051664",
        "hotelRequirementStatus": "DONE",
        "hotelRequirementStatusName": "配房完成",
        "vehicleRequirementStatus": "DONE",
        "vehicleRequirementStatusName": "配车完成"
      }
    ],
    "total": 1
  },
  "success": true
}
```

#### 空数据 / 降级响应

团期无子订单时返回空列表，两个字段不出现在任何行上。

```json
{ "code": 200, "message": "成功", "data": { "records": [], "total": 0 }, "success": true }
```

#### 错误响应

```json
{ "code": 401, "message": "Token 无效", "data": null, "success": false }
```

#### 业务边界

- 状态码为 null 时 Name 同样为 null，**不兜底成空串**。
- 枚举外的未知码**回落原 code**，与本接口其它 `*Name` 字段一致；前端直显即可，不要自建映射。
- 缺需求行时服务端把状态回落为 `PENDING`，故房显「待房务配」、车显「待车队配」。
- 房、车共用同一套状态码，但**展示文案按资源域分开**，前端不要把两个字段当同一套文案处理。

---

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

- 字段名、类型、是否可空**均未变化**，只是取值从「部分英文码」变为「全中文」。
- 前端若此前为绕开英文码自建了映射表，现在应**删除**，直显后端 `*Name`。
- 判断逻辑一律用 `*Status` 原码，不要用 `*StatusName`。

---

## 六、边界行为

- `null` → `null`；未知码 → 原样回落（如历史脏值 `SUBMITTED`、`REJECTED`）。
- 同一条子订单的房、车两个字段相互独立，可一个有值一个为 null。

---

## 六.6、修改前后对比

TEST 同一批数据（20 个团期 / 47 条子订单）改动前后对照：

| 状态码 | 改前 Name | 改后 Name（房 / 车） | 改前未翻译条数 | 改后重扫条数（房+车） |
|---|---|---|---|---|
| `PENDING` | 未提报 | 待房务配 / 待车队配 | 0 | 18 + 32 |
| `DONE` | **`DONE`**（英文码） | 配房完成 / 配车完成 | 25 | 19 + 6 |
| `PENDING_REVIEW` | **`PENDING_REVIEW`**（英文码） | 待审核 / 待审核 | 14 | 10 + 4 |
| `PROCESSING` | **`PROCESSING`**（英文码） | 配房中 / 配车中 | 4 | 0 + 5 |

改前 **43 条**原样吐英文，改后 **0 条**。`PROCESSING` 改前 4、改后 5：两次采集之间有子订单推进了状态，不影响结论。`PENDING` 的文案也变了（「未提报」→「待房务配 / 待车队配」），因为改前那个词与枚举语义不对应。

---

## 六.7、影响评估

- **前端**：需求审核列可直接接入；若已有绕开英文码的临时映射应删除。
- **后端**：纯映射方法改造，无新查询、无新远程调用。
- **数据**：无表变更、无 Flyway、无写链路。
- **兼容性**：字段名/类型/可空性零变化；仅 `*Name` 取值变化，属可观测契约变更故以「修改接口」声明。

---

## 七、不影响范围

- `hotelRequirementStatus` / `vehicleRequirementStatus` 两个**原码字段取值完全不变**。
- 本接口其余字段（`tierName`、`paidAmount`、`orderStatusName` 等）均未改动。
- 团期列表 GB-ADM-001、详情 GB-ADM-002、统计条 GB-ADM-009 未改动。
- 小程序端零影响。

---

## 八、测试环境已验证

**部署**：dev-v3 @ `18cfe3e21`（PR #7823 合并提交），2026-09-16 16:34:03~16:35:03 滚动部署双实例成功。注释补丁 #7826 为纯文档，未单独部署。

**验证方式**：部署前先采集改动前基线（20 个团期 / 47 条子订单），部署后用同一批 `groupBatchId` + `orderNo` 逐条回核。

### 5 条可复现样本前后对照

| 域 | 状态码 | groupBatchId | orderNo | 改前 Name | 改后 Name |
|---|---|---|---|---|---|
| 房 | `DONE` | 2100132795706691585 | HL20260916160051664 | `DONE` | 配房完成 ✅ |
| 房 | `PENDING_REVIEW` | 2100128616850317313 | HL20260916154415355 | `PENDING_REVIEW` | 待审核 ✅ |
| 车 | `DONE` | 2100132795706691585 | HL20260916160051664 | `DONE` | 配车完成 ✅ |
| 车 | `PENDING_REVIEW` | 2100126874498703362 | HL20260916153719950 | `PENDING_REVIEW` | 待审核 ✅ |
| 车 | `PROCESSING` | 2100129334617362434 | HL20260916154706861 | `PROCESSING` | 配车中 ✅ |

**5/5 全部由英文码变为中文。**

### 全量重扫

20 个团期 / **47 条子订单**，`Name == code`（未翻译）的字段数：**0** ✅

```
房需求: DONE→配房完成 x19 | PENDING→待房务配 x18 | PENDING_REVIEW→待审核 x10
车需求: PENDING→待车队配 x32 | DONE→配车完成 x6 | PROCESSING→配车中 x5 | PENDING_REVIEW→待审核 x4
```

车需求的 `PROCESSING` 显示「配车中」而非「配房中」，验证了房车分措辞的必要性。

### 单测与全量

- 定向单测 `GroupBatchConverterTest*`：**104 / 0 / 0 / 0**（新增 5 例：房 6 值、车 6 值、房车三态措辞不同、null 与未知码回落、现网高频码回归守卫）
- order-v3 全量 `com.hulalv.order.**`：**Tests run: 7560, Failures: 0, Errors: 0, Skipped: 0，BUILD SUCCESS**，0 次 OOM、0 次容器启动失败
- #7826 注释补丁：相关三个测试类 181 / 0 / 0 / 0

---

## 十、相关文档

- 差异来源：`需求分析/团期测试.md`「前台问题 团期-整团总览」
- 枚举定义：`hl-order-service-v3/.../requirement/enums/RequirementStatus.java`

## 关联 / 联系人

- 后端：wx
- 前端：mmg