From d4dbe654d3ec6763737438bbd3f085e352e69363 Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Thu, 18 Jun 2026 18:24:07 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20=E8=AE=A2=E5=8D=95=E8=AF=A6?= =?UTF-8?q?=E6=83=85=E6=A6=82=E8=A7=88=20overview=20=E5=AD=97=E6=AE=B5?= =?UTF-8?q?=E5=AF=B9=E6=8E=A5=E8=AF=B4=E6=98=8E=EF=BC=88=E5=90=AB=20nullab?= =?UTF-8?q?le=20+=20=E5=A4=87=E6=B3=A8=E5=AD=97=E6=AE=B5=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit GET /v3/admin/order/{id} 概览 overview 字段说明(非契约变更): customerInfo(联系人/电话/商户/定制师/创建时间/人数)+remarkInfo(4备注)+travelers字段路径类型含义； 特别标注可能为 null 的字段(商户软删/无定制师/未填备注/儿童婴儿未填手机等)。 --- ...情概览overview字段说明-接口说明-管理后台.md | 115 ++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 changelogs-v2/2026-06/18_订单详情概览overview字段说明-接口说明-管理后台.md diff --git a/changelogs-v2/2026-06/18_订单详情概览overview字段说明-接口说明-管理后台.md b/changelogs-v2/2026-06/18_订单详情概览overview字段说明-接口说明-管理后台.md new file mode 100644 index 0000000..3a25bac --- /dev/null +++ b/changelogs-v2/2026-06/18_订单详情概览overview字段说明-接口说明-管理后台.md @@ -0,0 +1,115 @@ +# 【接口说明·管理后台】订单详情概览 overview 字段说明（联系人/商户/定制师/备注 + 可空字段） + +> **接口**: GET /v3/admin/order/{id} | **服务**: hl-order-service-v3 | **更新时间**: 2026-06-18 +> 📌 本文为**字段对接说明（非契约变更）**：这些字段一直存在，本次澄清其路径/类型/含义，以及**哪些字段可能为 null**，便于前端对接。 + +## 1. 接口背景 + +订单详情主接口 `GET /v3/admin/order/{id}`，返回 `data` 含三块： +- `main`：订单主信息（订单号/状态/创建来源/agencyId 等） +- `tags`：订单标签数组 +- `overview`：概览 Tab 数据（客户信息 customerInfo + 备注 remarkInfo） + +本文聚焦 `overview` 块（概览 Tab 的客户信息与备注）。 + +## 2. overview.customerInfo（概览—客户信息） + +| 字段 | 类型 | 可空 | 说明 | +|------|------|------|------| +| contactName | String | 否 | 联系人姓名 | +| contactPhone | String | 否 | 联系人电话 | +| agencyName | String | **是** | 商户名称；商户记录被软删/不存在时为 null（见 §5）| +| consultantName | String | **是** | 定制师姓名；订单无定制师时为 null | +| createTime | String | 否 | 订单创建时间（`yyyy-MM-dd HH:mm:ss`）| +| peopleSummary | String | 否 | 人数概要文案，如「2 大 1 小 1 幼」| +| adultCount | Integer | 否 | 成人数 | +| childCount | Integer | 否 | 儿童数 | +| youngChildCount | Integer | 否 | 小童数 | +| babyCount | Integer | 否 | 幼童数 | +| emergencyContactName | String | **是** | 订单级紧急联系人姓名；未填为 null | +| emergencyContactPhone | String | **是** | 订单级紧急联系人电话；未填为 null | +| travelers | Array | 否 | 出行人列表（明文），元素字段见 §4 | + +## 3. overview.remarkInfo（概览—备注） + +| 字段 | 类型 | 可空 | 说明 | +|------|------|------|------| +| customerRemark | String | **是** | 客户备注；未填为 null | +| consultantRemark | String | **是** | 定制师备注；未填为 null | +| hotelRemark | String | **是** | 用房备注；无用房需求或未填为 null | +| vehicleRemark | String | **是** | 用车备注；无用车需求或未填为 null | + +## 4. overview.customerInfo.travelers[]（出行人，明文） + +| 字段 | 类型 | 可空 | 说明 | +|------|------|------|------| +| id | String | 否 | 出行人 ID | +| travelerType / travelerTypeName | String | 否 | 出行人类型码 / 中文名（成人/儿童/小童/幼童）| +| name | String | 是 | 姓名（占位行可能为 null）| +| gender | String | 是 | 性别：1 男 / 2 女 / 0 未知 | +| birthday | String | 是 | 出生日期 | +| idType / idTypeName | String | 是 | 证件类型码 / 中文名（取值见数据字典 id_card_type）| +| idCard | String | 是 | 证件号（明文，#3509）| +| nationality / race | String | 是 | 国籍 / 民族 | +| phone | String | **是** | 出行人手机；儿童/婴幼儿常未填为 null | +| emergencyContact | String | **是** | 紧急联系人姓名；常未填为 null | +| emergencyPhone | String | **是** | 紧急联系人电话；常未填为 null | +| roomGroupNo | Integer | **是** | 同住分组号；未分房为 null | +| profileStatus | String | 否 | 资料完善状态：PENDING / COMPLETED | +| transportPlanIds | Array | 否 | 关联大交通批次 ID 列表；无则空数组 | + +## 5. ⚠️ 可能为 null 的字段（nullable 汇总） + +| 字段路径 | 何时为 null | +|---|---| +| overview.customerInfo.agencyName | 该订单商户记录被软删 / 不存在（商户实时查询，已删商户查不到名称）| +| overview.customerInfo.consultantName | 订单无定制师 | +| overview.customerInfo.emergencyContactName / emergencyContactPhone | 订单级紧急联系人未填 | +| overview.remarkInfo.customerRemark / consultantRemark / hotelRemark / vehicleRemark | 对应备注未填 / 无对应需求 | +| overview.customerInfo.travelers[].phone / emergencyContact / emergencyPhone | 该出行人（多为儿童/婴幼儿）未填 | +| overview.customerInfo.travelers[].roomGroupNo | 该出行人未分配同住分组 | +| overview.customerInfo.travelers[].name / idCard / birthday 等 | 出行人资料未完善（profileStatus=PENDING）| + +> 联系人 contactName、电话 contactPhone、创建时间 createTime、人数统计为**必有值**字段。 + +## 6. 完整示例（节选 overview） + +```json +{ + "code": 200, + "data": { + "main": { "orderNo": "HL20260618095826571", "agencyId": "2051922156798779394", "createSource": "CONSULTANT", "createSourceLabel": "定制师创建" }, + "tags": [], + "overview": { + "customerInfo": { + "contactName": "类型名验证", + "contactPhone": "13800138000", + "agencyName": "内蒙古呼籁国际旅行社有限公司", + "consultantName": "腰苏图", + "createTime": "2026-06-18 09:58:28", + "peopleSummary": "2 大 1 小 1 幼", + "adultCount": 2, "childCount": 1, "youngChildCount": 1, "babyCount": 0, + "emergencyContactName": null, + "emergencyContactPhone": null, + "travelers": [ + { "id": "...", "travelerType": "ADULT", "travelerTypeName": "成人", "name": "张伟", "idType": "ID_CARD", "idTypeName": "身份证", "idCard": "1101...", "phone": "13810000013", "emergencyContact": "应急李娜", "roomGroupNo": null, "profileStatus": "COMPLETED" }, + { "id": "...", "travelerType": "CHILD", "travelerTypeName": "儿童", "name": "小宝", "idType": "ID_CARD", "idTypeName": "身份证", "phone": null, "emergencyContact": null, "emergencyPhone": null, "roomGroupNo": null, "profileStatus": "COMPLETED" } + ] + }, + "remarkInfo": { + "customerRemark": "示例备注", + "consultantRemark": null, + "hotelRemark": null, + "vehicleRemark": null + } + } + }, + "success": true +} +``` + +## 7. 关联 + +- **接口**: GET /v3/admin/order/{id} +- **说明**: 本文为字段对接说明，非契约变更。本次排查确认联系人/电话/商户/定制师/创建时间均正常返回（路径 `overview.customerInfo.*`）；商户 agencyName 曾因关联商户被误软删返回 null，数据已修复。 +- **后端负责人**: @yaosutu