232 行
9.2 KiB
Markdown
232 行
9.2 KiB
Markdown
---
|
||
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
|