From 165cbcb69a636dbea2884fdb3c91936e236a8d46 Mon Sep 17 00:00:00 2001 From: jw Date: Tue, 22 Sep 2026 16:57:39 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20=E5=9B=A2=E6=9C=9F=E4=B8=89?= =?UTF-8?q?=E5=BC=A0=E5=AD=90=E8=AE=A2=E5=8D=95=E8=A1=A8=E7=9A=84=E5=89=8D?= =?UTF-8?q?=E7=AB=AF=E6=B8=B2=E6=9F=93=E7=BC=BA=E9=99=B7=E4=B8=A4=E4=BB=BD?= =?UTF-8?q?=E4=BA=A4=E6=8E=A5=E4=BB=B6=EF=BC=88GB-ADM-003=20=E5=90=8E?= =?UTF-8?q?=E7=AB=AF=E9=9B=B6=E6=94=B9=E5=8A=A8=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 整团名单速览、子订单、查看需求三张表吃同一个接口 GB-ADM-003 GET /v3/admin/order/group-batch/{groupBatchId}/orders，同源所以同病： - 22_frontend_整团名单速览与子订单表…：联系人列显示占位符「—」应取 customerName； 房型列显示英文枚举码（KING）应取 roomTypeName（豪华大床）。 - 22_frontend_查看需求Tab子订单表…：同样两处取值问题，外加只有 5 列、 要补齐到子订单表的列集（团号/房型·间数/状态/需求审核/联系电话/应收/游客/资料）。 后端零改动，两份均已回填测试服活体实测读数：团期 2101506167098511362 全量 12 户， customerName 12/12 有值、roomType→roomTypeName 12/12 翻译正常（KING→豪华大床）； 图示那一行的 12 列逐列与实测值逐字吻合。附排查提示：travelers 12/12 为空数组且 travelerInfoComplete 恒 false，联系人若从出行人明细推导即会恒显「—」。 Co-Authored-By: Claude Opus 5 (1M context) --- ...订单表联系人与房型列取值订正-前端缺陷-管理后台.md | 149 ++++++++++++++++ ...表补齐列并订正联系人与房型-前端缺陷-管理后台.md | 161 ++++++++++++++++++ 2 files changed, 310 insertions(+) create mode 100644 changelogs-v2/2026-09/22_frontend_整团名单速览与子订单表联系人与房型列取值订正-前端缺陷-管理后台.md create mode 100644 changelogs-v2/2026-09/22_frontend_查看需求Tab子订单表补齐列并订正联系人与房型-前端缺陷-管理后台.md diff --git a/changelogs-v2/2026-09/22_frontend_整团名单速览与子订单表联系人与房型列取值订正-前端缺陷-管理后台.md b/changelogs-v2/2026-09/22_frontend_整团名单速览与子订单表联系人与房型列取值订正-前端缺陷-管理后台.md new file mode 100644 index 00000000..237eacf3 --- /dev/null +++ b/changelogs-v2/2026-09/22_frontend_整团名单速览与子订单表联系人与房型列取值订正-前端缺陷-管理后台.md @@ -0,0 +1,149 @@ +--- +schema: hl-changelog/v2 +ticket: "frontend" +title: "整团名单速览与子订单两张表：联系人列取 customerName、房型列取 roomTypeName" +consumer: admin +author: "jw(GIT)" +change_type: "前端缺陷" +backend_status: "not_required" +gateway_status: "not_required" +frontend_status: "pending" +frontend_owner: "" +frontend_ref: "" +target_release: "" +verified_at: "" +status_note: "2026-09-22 页面核对：团期详情的「整团名单速览」与「子订单」两张表存在同样两处显示问题——①「子订单 / 联系人」列的联系人行显示占位符「—」；②「房型 / 间数」列的房型显示英文枚举码（如 KING）。两张表吃的是同一个后端接口 GB-ADM-003 GET /v3/admin/order/group-batch/{groupBatchId}/orders，同源所以同病。后端零改动：同日 TEST 实测团期 2101506167098511362 全量 12 户，customerName 12/12 有值（张三/王五/李玉/张德发/王芳/阿宾等），roomType 与 roomTypeName 12/12 均有值且翻译正常（KING → 豪华大床）。前端把联系人列对齐到 customerName、房型列对齐到 roomTypeName 即可。排查提示：同一响应里 travelers 12/12 为空数组、travelerInfoComplete 12/12 为 false，若联系人是从出行人明细推导的，出行人未填时就会恒显「—」，而 customerName 与出行人资料无关、一直有值。" +updated_at: "2026-09-22" +base: dev-v3 +--- + +# 整团名单速览 / 子订单: 联系人列与房型列取值订正 + +> **服务**: hl-order-service-v3（**后端零改动**） +> **页面**: 管理后台 → 团期订单 → 团期详情 → 「整团总览」Tab 的整团名单速览 与 「子订单」Tab 的子订单表 +> **接口**: `GET /v3/admin/order/group-batch/{groupBatchId}/orders`（GB-ADM-003 / A3） +> **日期**: 2026-09-22 +> **影响范围**: 仅前台渲染取值；无端点、无出入参、无路由、无 DDL 变化 + +--- + +## ⚠️ 关键变化 + +- **两张表是同一个接口**，所以同一个毛病出现两次：整团名单速览与子订单表都消费 GB-ADM-003，改的时候两处一起改，别只改一处。 +- **后端不需要任何改动**。这两个字段一直都在返回，且 2026-09-22 TEST 实测**全量有值**——问题在前端取了别的字段。 + +--- + +## 一、两处问题 + +| # | 列 | 页面现在显示 | 应该显示 | 接口字段 | +|---|---|---|---|---| +| 1 | 子订单 / 联系人（第二行的联系人） | `—`（占位符） | 客户姓名，如 `张三` | `customerName` | +| 2 | 房型 / 间数 里的「房型」 | 英文枚举码，如 `KING` | 中文房型名，如 `豪华大床` | `roomTypeName`（当前多半取了 `roomType`） | + +--- + +## 二、实测证据 + +TEST 环境 `api.test.1814.love:9443`，2026-09-22，团期 `2101506167098511362`（jw测试产品 · 第1期 jw测试1期），`GET /v3/admin/order/group-batch/2101506167098511362/orders?pageSize=200`，`total=12`： + +``` +customerName 为空的户数: 0 / 12 +roomTypeName 为空的户数: 0 / 12 +roomType 为空的户数: 0 / 12 + +roomType -> roomTypeName 取值分布: + 'KING' -> '豪华大床' x12 （翻译正常，没有回落英文的情况） +``` + +单户原始响应片段： + +```json +{ + "orderId": "2101506167043985410", + "orderNo": "HL20260920105808925", + "teamNo": "26-3627", + "customerName": "张三", + "participantCount": 6, + "tierCode": "2A2C2Y", + "tierName": "2成人2儿童2幼童", + "roomCount": 2, + "roomType": "KING", + "roomTypeName": "豪华大床", + "contactPhone": "133****2212", + "travelerInfoComplete": false, + "travelers": [] +} +``` + +前 6 户逐户对照（联系人全部有值，与页面上的 `—` 直接矛盾）： + +``` +HL20260920105808925 联系人='张三' roomCount=2 roomType='KING' roomTypeName='豪华大床' +HL20260920110233355 联系人='王五' roomCount=2 roomType='KING' roomTypeName='豪华大床' +HL20260920110625528 联系人='李玉' roomCount=2 roomType='KING' roomTypeName='豪华大床' +HL20260921160904989 联系人='张德发' roomCount=2 roomType='KING' roomTypeName='豪华大床' +HL20260921161004158 联系人='王芳' roomCount=2 roomType='KING' roomTypeName='豪华大床' +HL20260921161039050 联系人='阿宾' roomCount=2 roomType='KING' roomTypeName='豪华大床' +``` + +--- + +## 三、排查提示: 联系人为什么会恒显「—」 + +同一次响应里还有两个数：**`travelers` 12/12 都是空数组**，**`travelerInfoComplete` 12/12 都是 `false`**（这个团的出行人资料还没填）。 + +如果联系人这一行是从出行人明细里推导的（例如取 `travelers[0]` 的姓名），那么只要该户出行人没录，页面就会恒显 `—`，与客户姓名有没有值无关。而 `customerName` 取的是订单主表的客户姓名，**与出行人资料完全无关**，本团 12/12 都有值。 + +接口里没有名为 `contact` / `linkman` 之类的字段，**联系人就是 `customerName`**。同一行若要显示联系方式，用 `contactPhone`（已脱敏，前3后4，本团 12/12 有值）。 + +--- + +## 四、房型列的两个限定 + +1. **要用 `roomTypeName`，不要自建映射。** `roomTypeName` 是后端把 `roomType` 按「、」逐段走 `room_category` 字典翻译后拼回的结果（多段房型会返回成 `标间、大床房` 这样）。字典不可达时它会**回落成原始英文码**——此时前端直显即可，不要另建一套前端映射表兜底（沿用 `16_frontend_前台整团名单速览补状态与需求审核列` 定下的口径：中文名一律由后端给，前端不自建映射）。 + +2. **房型三字段受 `includeNeeds` 开关控制。** `includeNeeds` **缺省为 `true`**，此时才返回 `roomCount` / `roomType` / `roomTypeName` / `specialNeeds`。同日实测显式传 `includeNeeds=false` 时，这四个字段全部为 `null`，而 `customerName` 仍有值： + +``` +includeNeeds=false 时： + roomCount = None roomType = None roomTypeName = None specialNeeds = None + customerName = '张三' +``` + +所以「房型列整列为空」与「房型列显示英文码」是两回事：前者去看请求有没有显式传 `includeNeeds=false`，后者才是本条说的取值取错。间数列用 `roomCount`（来源需求里的逐段房数，缺需求行时回落 `ceil(人数/2)`）。 + +--- + +## 五、改完后这两张表的完整字段对照 + +| 列 | 字段 | 备注 | +|---|---|---| +| 子订单编号 | `orderNo` | 另有团号 `teamNo`（订金支付成功后才生成，未付订金为 `null`） | +| 联系人 | `customerName` | 本条订正项 | +| 联系方式 | `contactPhone` | 脱敏，前3后4 | +| 套餐 / 档位 | `tierName` | 码为 `tierCode` | +| 人数 | `participantCount` | 成人+儿童+幼童+婴儿 | +| 房型 | `roomTypeName` | 本条订正项，需 `includeNeeds=true`（缺省即是） | +| 间数 | `roomCount` | 需 `includeNeeds=true` | +| 特殊需求 | `specialNeeds` | 需 `includeNeeds=true` | +| 状态 | `orderStatusName` | 枚举外回落 `orderStatus` | +| 需求审核（房 / 车） | `hotelRequirementStatusName` / `vehicleRequirementStatusName` | 取值：待房务配 / 配房中 / 配房完成 / 待审核 / 驳回 | +| 定制师 | `consultantName` | — | +| 金额 | `totalPrice` / `paidAmount` / `balanceAmount` | 字符串两位小数 | + +--- + +## 六、不影响范围 + +- 后端无需发版：GB-ADM-003 的路径、入参、出参、返回值一个都没变，其它调用方不受影响。 +- 不涉及权限码、错误码、字典、DDL。 +- 团期详情其它 Tab、子订单详情页、定制师待办、抢单池均不受影响。 + +--- + +## 关联 / 联系人 + +- 后端: jw +- 前端: 待认领（`frontend_status: pending`） +- 同接口的前序交接件: `changelogs-v2/2026-09/16_frontend_前台整团名单速览补状态与需求审核列-前端优化-管理后台.md`（该条已确认「联系人 `customerName`」「房型 `roomTypeName` / `roomCount`」是原型要求的列与字段） diff --git a/changelogs-v2/2026-09/22_frontend_查看需求Tab子订单表补齐列并订正联系人与房型-前端缺陷-管理后台.md b/changelogs-v2/2026-09/22_frontend_查看需求Tab子订单表补齐列并订正联系人与房型-前端缺陷-管理后台.md new file mode 100644 index 00000000..e9b52e9a --- /dev/null +++ b/changelogs-v2/2026-09/22_frontend_查看需求Tab子订单表补齐列并订正联系人与房型-前端缺陷-管理后台.md @@ -0,0 +1,161 @@ +--- +schema: hl-changelog/v2 +ticket: "frontend" +title: "查看需求 Tab 的子订单表：补齐到子订单表的列集，并订正联系人与房型两列取值" +consumer: admin +author: "jw(GIT)" +change_type: "前端缺陷" +backend_status: "not_required" +gateway_status: "not_required" +frontend_status: "pending" +frontend_owner: "" +frontend_ref: "" +target_release: "" +verified_at: "" +status_note: "2026-09-22 页面核对：团期详情「查看需求」Tab 的子订单表有三处问题——①「子订单 / 联系人」列的联系人行显示占位符「—」，应显示 customerName；②「房型 · 间数」的房型显示英文枚举码（如 KING），应显示中文 roomTypeName；③展示数据不全，只有 子订单/联系人、套餐、人数、需求状态、操作 五列，要补齐到「子订单」表的列集（团号、房型·间数、状态、需求审核、联系电话、应收、游客、资料）。后端零改动：这张表与「子订单」表、「整团名单速览」吃的是同一个接口 GB-ADM-003 GET /v3/admin/order/group-batch/{groupBatchId}/orders，要补的列全部已在该接口返回。同日 TEST 实测团期 2101506167098511362 全量 12 户，逐列与「子订单」表现有渲染逐字吻合（团号 26-3627、应收 25920.00、游客 0 人、资料 待补 等），customerName 12/12 有值、roomTypeName 12/12 有值且翻译正常（KING → 豪华大床）。" +updated_at: "2026-09-22" +base: dev-v3 +--- + +# 查看需求 Tab 子订单表: 补齐列集 + 联系人与房型取值订正 + +> **服务**: hl-order-service-v3（**后端零改动**） +> **页面**: 管理后台 → 团期订单 → 团期详情 → 「查看需求」Tab → 顶部操作条下方的子订单表 +> **接口**: `GET /v3/admin/order/group-batch/{groupBatchId}/orders`（GB-ADM-003 / A3） +> **日期**: 2026-09-22 +> **影响范围**: 仅前台渲染；无端点、无出入参、无路由、无 DDL 变化 + +--- + +## ⚠️ 关键变化 + +- **三张表同一个接口**：「查看需求」Tab 的子订单表、「子订单」Tab 的子订单表、「整团总览」Tab 的整团名单速览，都消费 GB-ADM-003。所以「子订单」表已经渲染出来的列，「查看需求」这张表**不需要后端加任何字段就能补上**。 +- **后端不需要任何改动**。要补的列、要订正的两个字段，2026-09-22 TEST 实测**全部已在返回且有值**。 +- 本条包含三处改动：两处取值订正 + 一处补列，见下。 + +--- + +## 一、三个问题 + +| # | 问题 | 页面现在 | 应该 | 接口字段 | +|---|---|---|---|---| +| 1 | 联系人不显示 | `—`（占位符） | 客户姓名，如 `张三` | `customerName` | +| 2 | 房型显示英文码 | `KING` | `豪华大床` | `roomTypeName`（当前多半取了 `roomType`） | +| 3 | 列不全 | 只有 5 列 | 补齐到「子订单」表的列集 | 见第二节 | + +--- + +## 二、目标列集与字段映射 + +以「子订单」Tab 的子订单表为准。下表的「TEST 实测值」取自同一次响应的第一户 `HL20260920105808925`，与「子订单」表页面上的渲染逐字吻合： + +| 列 | 接口字段 | TEST 实测值 | 「查看需求」表现状 | +|---|---|---|---| +| 子订单 / 联系人 | `orderNo` / `customerName` | `HL20260920105808925` / `张三` | 订单号有，**联系人缺**（问题 1） | +| 团号 | `teamNo` | `26-3627` | **缺** | +| 套餐 | `tierName` | `2成人2儿童2幼童` | 有 | +| 人数 | `participantCount` | `6` | 有 | +| 房型 · 间数 | `roomTypeName` · `roomCount` | `豪华大床` · `2` 间 | **缺**（补列时直接用 `roomTypeName`，别用 `roomType`，见问题 2） | +| 状态 | `orderStatusName` | `定制中` | **缺** | +| 需求审核 | `hotelRequirementStatusName` / `vehicleRequirementStatusName` | 房 `待审核` / 车 `待车队配` | **缺** | +| 联系电话 | `contactPhone` | `133****2212` | **缺** | +| 应收 | `totalPrice` | `25920.00` | **缺** | +| 游客 | `travelers` 的条数 | `0` 人 | **缺** | +| 资料 | `travelerInfoComplete` | `false` → 橙标「待补」 | **缺** | + +补列不需要新接口、不需要新参数：上面每一个字段都在「查看需求」这张表**当前已经在调**的那次 GB-ADM-003 响应里。 + +--- + +## 三、实测证据 + +TEST 环境 `api.test.1814.love:9443`，2026-09-22，团期 `2101506167098511362`（jw测试产品 · 第1期 jw测试1期），`GET /v3/admin/order/group-batch/2101506167098511362/orders`，`total=12`。 + +逐列取值（第一户）： + +``` +子订单/联系人 orderNo + customerName = HL20260920105808925 / '张三' +团号 teamNo = 26-3627 +套餐 tierName = 2成人2儿童2幼童 +人数 participantCount = 6 +房型·间数 roomTypeName + roomCount = '豪华大床' · 2 间 (roomType='KING') +状态 orderStatusName = 定制中 +需求审核·房 hotelRequirementStatusName = 待审核 +需求审核·车 vehicleRequirementStatusName = 待车队配 +联系电话 contactPhone = 133****2212 +应收 totalPrice = 25920.00 +游客 travelers 条数 = 0 +资料 travelerInfoComplete = False +``` + +全量 12 户的两个订正项： + +``` +customerName 为空的户数: 0 / 12 +roomTypeName 为空的户数: 0 / 12 +roomType -> roomTypeName 取值分布: 'KING' -> '豪华大床' x12 （翻译正常，无回落英文） +``` + +前 6 户联系人：`张三` / `王五` / `李玉` / `张德发` / `王芳` / `阿宾` —— 与页面上的 `—` 直接矛盾。 + +--- + +## 四、排查提示: 联系人为什么会恒显「—」 + +同一次响应里还有两个数：**`travelers` 12/12 都是空数组**，**`travelerInfoComplete` 12/12 都是 `false`**（这个团的出行人资料还没录，所以「游客」列是 `0 人`、「资料」列是橙标 `待补`）。 + +如果联系人这一行是从出行人明细推导的（例如取 `travelers[0]` 的姓名），那么只要该户出行人没录，页面就恒显 `—`，与客户姓名有没有值无关。`customerName` 取的是订单主表客户姓名，**与出行人资料无关**，本团 12/12 都有值。 + +接口里没有名为 `contact` / `linkman` 之类的字段，**联系人就是 `customerName`**；联系方式用 `contactPhone`（已脱敏，前3后4）。 + +--- + +## 五、两个查询开关（补列前先确认请求怎么发的） + +| 开关 | 缺省 | 管的字段 | +|---|---|---| +| `includeNeeds` | `true` | `roomCount` / `roomType` / `roomTypeName` / `specialNeeds` | +| `includeTravelers` | `true` | `travelers[]`（「游客」列的条数从这里来） | + +两个缺省都是 `true`，前端不传即可。同日实测：显式传 `includeNeeds=false` 时 `roomCount` / `roomType` / `roomTypeName` / `specialNeeds` **四个字段全部为 `null`**，而 `customerName` 仍有值。 + +所以「房型列整列空白」与「房型列显示英文码」是两回事：前者去看请求是不是显式传了 `includeNeeds=false`，后者才是本条问题 2 说的取值取错。 + +另外 `roomTypeName` 是后端把 `roomType` 按「、」逐段走 `room_category` 字典翻译后拼回的（多段房型形如 `标间、大床房`）；字典不可达时它会**回落成原始英文码**，此时前端直显即可，**不要自建映射表兜底**（沿用 `16_frontend_前台整团名单速览补状态与需求审核列` 定下的口径：中文名一律由后端给）。 + +--- + +## 六、「需求状态」与新增的「需求审核」是两个不同的东西 + +「查看需求」这张表现有的「需求状态」列（绿标 `已齐备`）**不是后端字段**——后端 `RequirementStatus` 的五个展示名是 `待房务配 / 配房中 / 配房完成 / 待审核 / 驳回`，没有「已齐备」。它是前端按预检结果自算的派生状态（该户没出现在 `GET .../requirement/confirm-check` 的 `missing` / `vehicleMissing` 清单里即判为齐备）。 + +补进来的「需求审核」列则是后端的真实状态（房 `hotelRequirementStatusName` / 车 `vehicleRequirementStatusName`）。两者语义不同：前者回答「这户还缺不缺东西、挡不挡整团确认」，后者回答「这户的房/车需求流转到哪一步了」。 + +补列后两列会并排出现。是两列都留，还是只留一列，由产品定——**后端两种都支持，字段都在，不需要改动**。 + +--- + +## 七、这张表特有的元素照旧保留 + +补列不影响「查看需求」Tab 该有的交互： + +- 首列复选框 + 顶部「打回选中户」：打回接口 `POST /v3/admin/order/group-batch/{groupBatchId}/requirement/reject`，必填 `orderIds`（1~200 户，服务端去重）与 `reason`（≤500 字），可选 `resourceType`（`HOTEL` / `VEHICLE` / `ALL`，缺省 `ALL`）。每行的 `orderId` 就在同一份响应里。 +- 操作列「联系定制师」「进入」：`consultantName` 与 `orderId` 均在响应里；未读角标用 `groupChatUnreadCount`（user-service 不可达时降级为 0，不阻断名单主数据）。 +- 顶部预检、`刷新预检`、`整团确认需求` 走 `GET .../requirement/confirm-check` 与 `POST .../requirement/confirm`，与本条无关，不动。 + +--- + +## 八、不影响范围 + +- 后端无需发版：GB-ADM-003 的路径、入参、出参、返回值一个都没变，其它调用方不受影响。 +- 不涉及权限码、错误码、字典、DDL。 +- 「子订单」Tab 与「整团名单速览」的联系人、房型两列有同样的毛病，另见同日交接件 `22_frontend_整团名单速览与子订单表联系人与房型列取值订正`；本条只管「查看需求」Tab 这一张表。 +- 团期详情其它 Tab、子订单详情页、定制师待办、抢单池均不受影响。 + +--- + +## 关联 / 联系人 + +- 后端: jw +- 前端: 待认领（`frontend_status: pending`） +- 同接口的前序交接件: `changelogs-v2/2026-09/16_frontend_前台整团名单速览补状态与需求审核列-前端优化-管理后台.md`