hl-api-changelog/changelogs-v2/2026-09/16_7816_团期子订单需求审核状态中文名修复房车各一套文案-修改接口-管理后台.md

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	7816	团期子订单需求审核状态中文名修复房车各一套文案	admin	wx(GIT)	修改接口	deployed	not_required	not_required	mmg			2026-09-16	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)。	2026-09-16	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	已驳回管理员	已驳回管理员

请求示例

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

响应示例

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

空数据 / 降级响应

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

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

错误响应

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