d4dbe654d3
GET /v3/admin/order/{id} 概览 overview 字段说明(非契约变更):
customerInfo(联系人/电话/商户/定制师/创建时间/人数)+remarkInfo(4备注)+travelers字段路径类型含义；
特别标注可能为 null 的字段(商户软删/无定制师/未填备注/儿童婴儿未填手机等)。
116 行
6.1 KiB
Markdown
116 行
6.1 KiB
Markdown
# 【接口说明·管理后台】订单详情概览 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
|