hl-api-changelog/changelogs-v2/2026-06/18_订单详情概览overview字段说明-接口说明-管理后台.md

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

{
  "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