# 【接口说明·管理后台】订单详情概览 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