yaosutu f38c79e150 docs(changelog): 行程Tab补 HotelGroupVO/VehicleGroupVO 中间层表格(管理后台)

补齐遗漏: 配房组/配车组两个中间层对象由行内 = a + b 写法改为字段表格，全文对象结构表格化一致。

2026-06-05 17:08:12 +08:00

42 KiB

原始文件 Blame 文件历史

订单列表 + 订单详情 + 懒加载 Tab 接口契约清单（管理后台）

端类型：管理后台（v3）｜变更类型：修改接口（多 PR 累积契约整理 + 1 个新增 Tab）服务：hl-order-service-v3 ｜ Controller 前缀：/v3/admin/order ｜基线 commit：f95757df7｜日期：2026-06-05

通用约定

响应包装 Result<T>（code=200 成功）；列表为 PageResult<T>；HTTP 状态恒 200，前端判 code/success。
所有 Long 主键序列化为字符串（防 JS 精度丢失），前端按 string 接收。
鉴权：Authorization: Bearer <token>。时间 yyyy-MM-dd HH:mm:ss，日期 yyyy-MM-dd。
错误码：581007 订单不存在（接口 2~10 传入不存在订单 ID 时返回）。
枚举字段统一见文末 附录 A 枚举字典；3 处枚举口径差异见 附录 B（务必按字符串容错）。

接口总览

#	接口	地址	本次
1	订单列表	`GET /v3/admin/order`	无字段变更
2	订单详情（主）	`GET /v3/admin/order/{id}`	overview 重构 + 出行人明文 + 主接口瘦身
3	财务 Tab	`GET /v3/admin/order/{id}/finance`	删 surchargeType
4	合同保险 Tab	`GET /v3/admin/order/{id}/contract-insurance`	events 真实化
5	发票 Tab	`GET /v3/admin/order/{id}/invoices`	新增接口
6	行程 Tab	`GET /v3/admin/order/{id}/itinerary`	删 days + requirement 真实化
7	大交通 Tab	`GET /v3/admin/order/{id}/transport-plans`	主接口移出转懒加载
8	状态时间线 Tab	`GET /v3/admin/order/{id}/status-log`	无字段变更
9	退款 Tab	`GET /v3/admin/order/{id}/refund`	无字段变更
10	服务标准 Tab	`GET /v3/admin/order/{id}/service-standard`	重构一站式聚合

懒加载 Tab = #3~#10 共 8 个：进入详情页先调 #2 拿头部 + 状态徽标，各 Tab 点开时再各自拉取。

1. 订单列表

接口地址：GET /v3/admin/order 接口介绍：管理后台订单列表，支持状态/标签/关键字/出发日期/来源/定制师等多条件过滤，分页返回。 本次修改点：无字段变更（沿用现状，列表项含 6 步 flowStep 步骤条字段）。

入参（query 参数）

字段	类型	必填	含义	示例
page	Integer	否	页码（默认 1）	1
pageSize	Integer	否	每页条数（默认 10）	10
orderStatus	String	否	粗状态过滤（多值逗号分隔）	CUSTOMIZING
flowStatus	String	否	细状态过滤	RESOURCE_PREPARING
tagNames	List<String>	否	标签过滤（多标签 AND）	["二次复购"]
keyword	String	否	团号/客户名/产品名/订单号 LIKE	张三
departureDateFrom	LocalDate	否	出发日期范围起始	2026-06-01
departureDateTo	LocalDate	否	出发日期范围结束	2026-06-30
createSource	String	否	来源过滤	CONSULTANT
cancelled	Boolean	否	是否含已取消（默认 false）	false
consultantName	String	否	定制师姓名 LIKE	李定制

入参示例

GET /v3/admin/order?page=1&pageSize=10&orderStatus=CUSTOMIZING&keyword=张三

出参：PageResult<OrderListItemRespVO>，外层 records（数组）+ total/current/size 分页字段。

单条 OrderListItemRespVO（35 字段）：

字段	类型	含义
id	String	订单 ID
orderNo	String	订单号（永不变）
teamNo	String	团号（订金支付成功生成，创单 null）
displayOrderNo	String	展示订单号
productName	String	产品名（快照）
productCoverImg	String	产品封面
tierName	String	档位名
customerName	String	客户姓名
customerPhoneMasked	String	客户手机（脱敏）
peopleSummary	String	人数摘要
departureDate	LocalDate	出发日（未定 null）
tripDays	Integer	行程天数
orderStatus	String	粗状态值（附录 A）
orderStatusName	String	粗状态中文
flowStatus	String	细状态值（附录 A）
flowStatusName	String	细状态中文
flowStep	Integer	6 步当前步序号（0=待支付，1-6，null=已取消）
flowStepTotal	Integer	总步数（6）
flowStepCode	String	当前步英文码（附录 A）
currentSubFlows	List<SubFlowVO>	当前步子流程（仅 RESOURCE 步非 null）
totalAmount	BigDecimal	订单金额
paidAmount	BigDecimal	实付金额
balanceAmount	BigDecimal	待付金额
consultantName	String	定制师姓名
createSource	String	来源值（附录 A）
createSourceLabel	String	来源中文
tags	List<TagVO>	标签列表
createdAt	LocalDateTime	创单时间
depositAmount	BigDecimal	订金额（FULL 为 null）
depositRatio	Integer	订金比例%（FULL 为 null）
paymentMode	String	DEPOSIT/FULL
singleRoomSurcharge	BigDecimal	单房差（未触发 null）
agencyId	String	旅行社主体 ID
refundPolicyId	String	退款政策 ID
productSubtitle	String	产品副标题

SubFlowVO（子流程）

字段	类型	含义
code	String	子流程英文码 HOTEL/VEHICLE/GUIDE/PHOTOGRAPHER
name	String	子流程名称
status	String	DONE/PROCESSING/WAITING
label	String	显示标签（如"待配"）

TagVO（标签）

字段	类型	含义
name	String	标签名
type	String	SYSTEM/MANUAL
color	String	十六进制色 #RRGGBB
creator	String	标签创建人姓名

出参示例

{
  "code": 200, "message": "成功", "success": true,
  "data": {
    "total": 1, "current": 1, "size": 10,
    "records": [{
      "id": "1900000000000903", "orderNo": "TEST-RESOURCE-903", "teamNo": null,
      "displayOrderNo": "TEST-RESOURCE-903", "productName": "长白山3日私家定制游",
      "tierName": "标准档", "customerName": "测试客户", "customerPhoneMasked": "138****8001",
      "peopleSummary": "2 大", "departureDate": "2026-07-01", "tripDays": 5,
      "orderStatus": "CUSTOMIZING", "orderStatusName": "定制中",
      "flowStatus": "RESOURCE_PREPARING", "flowStatusName": "资源准备",
      "flowStep": 2, "flowStepTotal": 6, "flowStepCode": "RESOURCE",
      "currentSubFlows": [
        {"code": "HOTEL", "name": "配房", "status": "PROCESSING", "label": "待配"},
        {"code": "VEHICLE", "name": "配车", "status": "PROCESSING", "label": "处理中"}
      ],
      "totalAmount": 9800.00, "paidAmount": 0.00, "balanceAmount": 9800.00,
      "consultantName": "李定制", "createSource": "CONSULTANT", "createSourceLabel": "定制师创建",
      "tags": [], "createdAt": "2026-06-04 18:49:39",
      "depositAmount": null, "depositRatio": null, "paymentMode": "FULL",
      "singleRoomSurcharge": null, "agencyId": "8000000000000001",
      "refundPolicyId": "7000000000000001", "productSubtitle": "私家小团·专车专导"
    }]
  }
}

2. 订单详情（主接口）

接口地址：GET /v3/admin/order/{id} 接口介绍：订单详情页头部聚合接口，返回主单信息(main) + 标签(tags) + 概览(overview，含客户信息与备注)。其余明细已拆为懒加载 Tab。 本次修改点：

主接口瘦身：原 transportPlans / itinerary 全量字段已移出，改为独立懒加载接口（#3385）。
overview 重构为 customerInfo + remarkInfo 两分类（原扁平字段，#3488）。
overview 出行人/联系电话/证件号改明文返回（idCard/phone/emergencyPhone 不脱敏，#3509）。

入参

字段	位置	类型	必填	含义
id	path	Long	是	订单 ID

入参示例

GET /v3/admin/order/1900000000000903

出参：OrderDetailRespVO

字段	类型	含义
main	OrderMainVO	主单 + Tab 状态徽标 + 进度管道
tags	List<TagVO>	标签区（结构同 §1 TagVO）
overview	OverviewVO	概览（客户信息 + 备注）

main（OrderMainVO，47 字段）

字段	类型	含义
id	String	订单 ID
orderNo	String	订单号（永不变）
teamNo	String	团号（未成团 null）
displayOrderNo	String	展示订单号
productName	String	产品名
tierName	String	档位名
productSubtitle	String	产品副标题
orderStatus	String	粗状态值（附录 A）
orderStatusName	String	粗状态中文
flowStatus	String	细状态值（附录 A）
flowStatusName	String	细状态中文
flowStep	Integer	6 步当前步序号（0/1-6/null）
flowStepTotal	Integer	总步数（6）
flowDisplayText	String	步骤展示文案（纯中文，不带 "X/6 ·"）
flowStepCode	String	当前步英文码（CANCELLED/待支付为 null）
flowStepStatus	String	当前步状态（PROCESSING=进行中）
totalAmount	BigDecimal	订单金额
paidAmount	BigDecimal	实付金额
balanceAmount	BigDecimal	待付金额
departureDate	LocalDate	出发日期
returnDate	LocalDate	返回日期
tripDays	Integer	行程天数
tripNights	Integer	行程夜数
createSource	String	来源值（附录 A）
createSourceLabel	String	来源中文
confirmedAt	LocalDateTime	确认订单时间
progressStepper	List<PipelineNodeVO>	6 主节点进度管道（已取消返空数组）
contractStatus	String	[Tab 徽标]合同状态（按字符串容错，附录 B）
insuranceStatus	String	[Tab 徽标]保险状态（附录 B）
refundStatus	String	[Tab 徽标]退款状态 NONE/PROCESSING/COMPLETED
hasRefund	Boolean	是否有退款记录
hasServiceStandard	Boolean	是否有服务标准快照
hasFinanceDetail	Boolean	是否有财务明细（discount/surcharge>0）
depositAmount	BigDecimal	订金额（FULL 为 null）
depositRatio	Integer	订金比例%（FULL 为 null）
paymentMode	String	DEPOSIT/FULL
payStatus	String	支付状态 UNPAID/DEPOSIT_PAID/FULLY_PAID
singleRoomSurcharge	BigDecimal	单房差（未触发 null）
agencyId	String	旅行社主体 ID
refundPolicyId	String	退款政策 ID

PipelineNodeVO（进度节点）

字段	类型	含义
step	Integer	步序号 1-6
code	String	节点码 PROFILE/RESOURCE/CONFIRM/DEPART/REVIEW/SETTLE
name	String	节点名称
status	String	DONE/PROCESSING/WAITING
label	String	显示标签
isCurrent	Boolean	是否当前步
subFlows	List<SubFlowVO>	子流程（仅 RESOURCE 节点非 null，结构同 §1）

overview（OverviewVO）

字段	类型	含义
customerInfo	CustomerInfoVO	客户信息分类
remarkInfo	RemarkInfoVO	备注分类

CustomerInfoVO（客户信息）

字段	类型	含义
contactName	String	联系人姓名
contactPhone	String	联系电话（admin 明文）
agencyName	String	商户名（不存在为 null）
consultantName	String	定制师姓名
peopleSummary	String	人数摘要
adultCount	Integer	成人数
childCount	Integer	儿童数
youngChildCount	Integer	小童数
babyCount	Integer	婴儿数
createTime	LocalDateTime	创建时间
emergencyContactName	String	紧急联系人姓名
emergencyContactPhone	String	紧急联系人手机（明文）
travelers	List<TravelerPlainVO>	出行人集合（明文）

TravelerPlainVO（出行人，明文 #3509）

字段	类型	含义
id	String	出行人 ID
orderId	String	订单 ID
travelerType	String	ADULT/CHILD/YOUNG_CHILD/BABY
name	String	姓名（占位行为 null）
gender	String	1=男 / 2=女 / 0=未知
birthday	LocalDate	出生日期
idType	String	ID_CARD/PASSPORT/BIRTH_CERT
idCard	String	证件号（明文）
nationality	String	国籍（默认中国）
race	String	民族（默认汉族）
phone	String	出行人手机（明文）
emergencyContact	String	紧急联系人姓名
emergencyPhone	String	紧急联系人电话（明文）
roomGroupNo	Integer	同住分组号
profileStatus	String	资料完善 PENDING/COMPLETED
transportPlanIds	List<String>	关联大交通批次 ID 列表

RemarkInfoVO（备注）

字段	类型	含义
customerRemark	String	用户备注（只读）
consultantRemark	String	定制师备注
hotelRemark	String	用房备注（无需求 null）
vehicleRemark	String	用车备注（无需求 null）

出参示例

{
  "code": 200, "message": "成功", "success": true,
  "data": {
    "main": {
      "id": "1900000000000903", "orderNo": "TEST-RESOURCE-903", "teamNo": null,
      "displayOrderNo": "TEST-RESOURCE-903", "productName": "长白山3日私家定制游", "tierName": "标准档",
      "productSubtitle": "私家小团·专车专导",
      "orderStatus": "CUSTOMIZING", "orderStatusName": "定制中",
      "flowStatus": "RESOURCE_PREPARING", "flowStatusName": "资源准备",
      "flowStep": 2, "flowStepTotal": 6, "flowDisplayText": "资源准备",
      "flowStepCode": "RESOURCE", "flowStepStatus": "PROCESSING",
      "totalAmount": 9800.00, "paidAmount": 0.00, "balanceAmount": 9800.00,
      "departureDate": "2026-07-01", "returnDate": "2026-07-05", "tripDays": 5, "tripNights": 4,
      "createSource": "CONSULTANT", "createSourceLabel": "定制师创建", "confirmedAt": null,
      "progressStepper": [
        {"step": 1, "code": "PROFILE", "name": "补全信息", "status": "DONE", "label": null, "isCurrent": false, "subFlows": null},
        {"step": 2, "code": "RESOURCE", "name": "资源准备", "status": "PROCESSING", "label": null, "isCurrent": true,
         "subFlows": [{"code": "HOTEL", "name": "配房", "status": "PROCESSING", "label": "待配"}]}
      ],
      "contractStatus": "NONE", "insuranceStatus": "NONE", "refundStatus": "NONE",
      "hasRefund": false, "hasServiceStandard": true, "hasFinanceDetail": false,
      "depositAmount": null, "depositRatio": null, "paymentMode": "FULL", "payStatus": "UNPAID",
      "singleRoomSurcharge": null, "agencyId": "8000000000000001", "refundPolicyId": "7000000000000001"
    },
    "tags": [],
    "overview": {
      "customerInfo": {
        "contactName": "测试客户", "contactPhone": "13800138001", "agencyName": "呼籁旅行",
        "consultantName": "李定制", "peopleSummary": "2 大", "adultCount": 2, "childCount": 0,
        "youngChildCount": 0, "babyCount": 0, "createTime": "2026-06-04 18:49:39",
        "emergencyContactName": "王五", "emergencyContactPhone": "13900139000",
        "travelers": [{
          "id": "1910000000000001", "orderId": "1900000000000903", "travelerType": "ADULT",
          "name": "张三", "gender": "1", "birthday": "1990-01-01", "idType": "ID_CARD",
          "idCard": "220101199001010011", "nationality": "中国", "race": "汉族",
          "phone": "13800138001", "emergencyContact": "王五", "emergencyPhone": "13900139000",
          "roomGroupNo": 1, "profileStatus": "COMPLETED", "transportPlanIds": []
        }]
      },
      "remarkInfo": {
        "customerRemark": "希望安排靠窗座位", "consultantRemark": "VIP 客户，重点跟进",
        "hotelRemark": null, "vehicleRemark": null
      }
    }
  }
}

3. 财务 Tab

接口地址：GET /v3/admin/order/{id}/finance 接口介绍：订单财务明细，含金额汇总、支付/优惠/附加费三类明细列表。 本次修改点：SurchargeVO 删除 surchargeType 字段（恒 null 无数据源，#3523）——破坏性，前端引用处需移除。

入参

字段	位置	类型	必填	含义
id	path	Long	是	订单 ID

入参示例

GET /v3/admin/order/1900000000000903/finance

出参：FinanceVO

字段	类型	含义
totalAmount	BigDecimal	订单总额
paidAmount	BigDecimal	实付金额
balanceAmount	BigDecimal	待付金额
discountAmount	BigDecimal	优惠金额汇总
surchargeAmount	BigDecimal	附加费汇总
refundAmount	BigDecimal	退款金额汇总
payments	List<PaymentVO>	支付明细
discounts	List<DiscountVO>	优惠明细
surcharges	List<SurchargeVO>	附加费用

PaymentVO

字段	类型	含义
id	String	支付记录 ID
payType	String	DEPOSIT/BALANCE
amount	BigDecimal	支付金额
paidAt	LocalDateTime	支付时间
status	String	SUCCESS/PENDING/FAIL

DiscountVO

字段	类型	含义
id	String	优惠 ID
name	String	优惠名称
amount	BigDecimal	优惠金额
type	String	EARLY_BIRD/VIP/…
source	String	MANUAL/AUTO
createdAt	LocalDateTime	创建时间

SurchargeVO（已删 surchargeType）

字段	类型	含义
id	String	附加费 ID
name	String	附加费名称
amount	BigDecimal	金额
source	String	HOTEL_ASSIGN/VEHICLE_ASSIGN/…
createdAt	LocalDateTime	创建时间

出参示例

{
  "code": 200, "message": "成功", "success": true,
  "data": {
    "totalAmount": 9800.00, "paidAmount": 5000.00, "balanceAmount": 4800.00,
    "discountAmount": 200.00, "surchargeAmount": 300.00, "refundAmount": 0.00,
    "payments": [
      {"id": "2001", "payType": "DEPOSIT", "amount": 5000.00, "paidAt": "2026-06-04 19:00:00", "status": "SUCCESS"}
    ],
    "discounts": [
      {"id": "3001", "name": "早鸟优惠", "amount": 200.00, "type": "EARLY_BIRD", "source": "AUTO", "createdAt": "2026-06-04 18:50:00"}
    ],
    "surcharges": [
      {"id": "4001", "name": "单房差", "amount": 300.00, "source": "HOTEL_ASSIGN", "createdAt": "2026-06-04 18:55:00"}
    ]
  }
}

无数据时各 list 返回 []（非 null）。

4. 合同保险 Tab

接口地址：GET /v3/admin/order/{id}/contract-insurance 接口介绍：订单合同与保险状态 + 事件时间线。 本次修改点：events 真实化——来自 status_log / insurance_status_log，不再恒空（#3514）。

入参

字段	位置	类型	必填	含义
id	path	Long	是	订单 ID

入参示例

GET /v3/admin/order/1900000000000903/contract-insurance

出参：ContractInsuranceVO

字段	类型	含义
contract	ContractVO	合同子对象
insurance	InsuranceVO	保险子对象

ContractVO

字段	类型	含义
contractStatus	String	合同状态（附录 B）
contractSignedAt	LocalDateTime	签约时间
contractFileUrl	String	合同文件 URL
events	List<EventVO>	合同事件时间线

InsuranceVO

字段	类型	含义
insuranceStatus	String	保险状态（附录 B）
insurancePolicyNo	String	保单号
insurancePremium	BigDecimal	保费
events	List<EventVO>	保险事件时间线

EventVO

字段	类型	含义
eventType	String	事件类型 GENERATE/SIGN/ISSUE/…
occurredAt	LocalDateTime	发生时间

出参示例

{
  "code": 200, "message": "成功", "success": true,
  "data": {
    "contract": {
      "contractStatus": "SIGNED", "contractSignedAt": "2026-06-05 10:00:00",
      "contractFileUrl": "https://oss.example.com/contracts/903.pdf",
      "events": [
        {"eventType": "GENERATE", "occurredAt": "2026-06-05 09:30:00"},
        {"eventType": "SIGN", "occurredAt": "2026-06-05 10:00:00"}
      ]
    },
    "insurance": {
      "insuranceStatus": "INSURED", "insurancePolicyNo": "PICC2026070100123",
      "insurancePremium": 60.00,
      "events": [{"eventType": "ISSUE", "occurredAt": "2026-06-05 10:05:00"}]
    }
  }
}

5. 发票 Tab 〔新增接口〕

接口地址：GET /v3/admin/order/{id}/invoices 接口介绍：返回该订单全部发票（含已作废 VOIDED），按 applyAt 倒序。 本次修改点：新增接口（#3517 / #3521）。无发票返回 data:[]。

入参

字段	位置	类型	必填	含义
id	path	Long	是	订单 ID

入参示例

GET /v3/admin/order/1900000000000903/invoices

出参：List<InvoiceVO>（每条 23 字段）

字段	类型	含义
id	String	发票 ID
orderId	String	订单 ID
invoiceType	String	类型值（附录 A）
invoiceTypeText	String	类型文案
titleType	String	抬头类型 COMPANY/PERSONAL
titleName	String	抬头名称
taxNo	String	税号（公司抬头/专票必填）
amount	BigDecimal	开票金额（元）
status	String	状态值（附录 A）
statusText	String	状态文案
auditStatus	String	机审 PENDING/APPROVED/MANUAL_REVIEW/REJECTED
applyReason	String	申请说明
applyAt	LocalDateTime	申请时间
fileUrl	String	发票文件 OSS 链接（UPLOADED 后有值）
uploader	String	上传人
uploadedAt	LocalDateTime	上传时间
deliveredAt	LocalDateTime	送达时间（DELIVERED 时有值）
voidReason	String	作废原因（VOIDED 时有值）
email	String	邮箱（电子发票）
mailAddress	String	邮寄地址（纸质发票）
bankName	String	开户行（专票）
bankAccount	String	开户账号（专票）
registAddress	String	注册地址（专票）
registPhone	String	注册电话（专票）

出参示例

{
  "code": 200, "message": "成功", "success": true,
  "data": [{
    "id": "5001", "orderId": "1900000000000903",
    "invoiceType": "ELECTRONIC", "invoiceTypeText": "电子普通发票",
    "titleType": "PERSONAL", "titleName": "张三", "taxNo": null,
    "amount": 9800.00, "status": "ISSUED", "statusText": "已开票",
    "auditStatus": "APPROVED", "applyReason": "报销", "applyAt": "2026-06-05 11:00:00",
    "fileUrl": null, "uploader": null, "uploadedAt": null, "deliveredAt": null, "voidReason": null,
    "email": "zhangsan@example.com", "mailAddress": null,
    "bankName": null, "bankAccount": null, "registAddress": null, "registPhone": null
  }]
}

6. 行程 Tab

接口地址：GET /v3/admin/order/{id}/itinerary 接口介绍：订单配房/配车的需求(requirement) + 实配(assignments)。 本次修改点：

删顶层 MOCK days（逐天行程改走 /itinerary/full，#3502）——破坏性。
hotelGroup/vehicleGroup.requirement 真实化（#3385/#3493）；assignment 增 requirementId。
HotelAssignmentVO（实配酒店）当前恒返空，待 house 域接通，前端按空处理勿报错。

入参

字段	位置	类型	必填	含义
id	path	Long	是	订单 ID

入参示例

GET /v3/admin/order/1900000000000903/itinerary

出参：ItineraryVO

字段	类型	含义
hotelGroup	HotelGroupVO	配房需求 + 实配
vehicleGroup	VehicleGroupVO	配车需求 + 实配

HotelGroupVO（配房组）

字段	类型	含义
requirement	HotelRequirementBriefVO	配房需求（客户/定制师提交的用房要求）
assignments	List<HotelAssignmentVO>	实配酒店列表（当前恒空，待 house 域接通）

VehicleGroupVO（配车组）

字段	类型	含义
requirement	VehicleRequirementBriefVO	配车需求（客户/定制师提交的用车要求）
assignments	List<VehicleAssignmentVO>	实配车辆列表（实际派车 + 司机）

HotelRequirementBriefVO（配房需求）

字段	类型	含义
requirementId	String	需求 ID
version	Integer	版本号
status	String	PENDING/PROCESSING/DONE
submittedAt	LocalDateTime	提交时间
totalRoomCount	Integer	合计间数
roomTypeSummary	String	房型摘要（双床房×4 / 大床房×2）
specialTags	List<String>	特殊诉求标签
remark	String	备注
claimerName	String	房控接单人姓名
days	List<RequirementDayVO>	按天结构化需求

RequirementDayVO（按天需求）

字段	类型	含义
dayNumber	Integer	第几天
stayDate	LocalDate	入住日（派生）
remark	String	当天备注
hotels	List<RequirementHotelVO>	当天房型明细

RequirementHotelVO（房型明细）

字段	类型	含义
hotelId	String	目标酒店 ID（可 null）
roomCategory	String	房型字典 code TWIN/DOUBLE_BED
roomCategoryLabel	String	房型中文标签
roomCount	Integer	间数
budget	BigDecimal	预算/间（可 null）

HotelAssignmentVO（实配酒店，当前恒返空）

字段	类型	含义
assignmentId	String	实配 ID
requirementId	String	关联配房需求 ID
familyIndex	Integer	家庭序号
dayNumber	Integer	第几天
stayDate	LocalDate	入住日
hotelName	String	酒店名
roomType	String	房型中文名
plannedCost	BigDecimal	单价（元/间·晚）
remark	String	备注

VehicleRequirementBriefVO（配车需求）

字段	类型	含义
requirementId	String	需求 ID
version	Integer	版本号
status	String	PENDING/PROCESSING/DONE
submittedAt	LocalDateTime	提交时间
vehicleTypeSummary	String	车型摘要
specialTags	List<String>	特殊诉求标签
remark	String	备注

VehicleAssignmentVO（实配车辆）

字段	类型	含义
assignmentId	String	实配 ID
vehicleType	String	车型
vehicleCount	Integer	车辆数
licensePlate	String	车牌
brand	String	品牌
seats	Integer	座位数
plannedDailyFee	BigDecimal	计划日单价
driverName	String	司机姓名
driverPhoneMasked	String	司机手机（脱敏）
remark	String	备注

出参示例

{
  "code": 200, "message": "成功", "success": true,
  "data": {
    "hotelGroup": {
      "requirement": {
        "requirementId": "6001", "version": 1, "status": "PROCESSING",
        "submittedAt": "2026-06-04 20:00:00", "totalRoomCount": 2,
        "roomTypeSummary": "双床房×1 / 大床房×1", "specialTags": ["无烟房", "高楼层"],
        "remark": "尽量安排连号房", "claimerName": "房控小赵",
        "days": [{
          "dayNumber": 1, "stayDate": "2026-07-01", "remark": null,
          "hotels": [{"hotelId": null, "roomCategory": "TWIN", "roomCategoryLabel": "双床房", "roomCount": 1, "budget": 400.00}]
        }]
      },
      "assignments": []
    },
    "vehicleGroup": {
      "requirement": {
        "requirementId": "6101", "version": 1, "status": "PROCESSING",
        "submittedAt": "2026-06-04 20:05:00", "vehicleTypeSummary": "7 座商务车×1",
        "specialTags": ["儿童座椅"], "remark": "全程同一司机"
      },
      "assignments": [{
        "assignmentId": "6201", "vehicleType": "7座商务车", "vehicleCount": 1,
        "licensePlate": "吉A·12345", "brand": "别克GL8", "seats": 7,
        "plannedDailyFee": 800.00, "driverName": "李师傅", "driverPhoneMasked": "138****0000", "remark": null
      }]
    }
  }
}

7. 大交通批次 Tab

接口地址：GET /v3/admin/order/{id}/transport-plans 接口介绍：订单大交通（抵达/返程）批次安排，含航班/车次/自驾、接送、关联出行人。 本次修改点：原在详情主接口内，#3385 起拆为独立懒加载接口（字段不变）。无批次返回 data:[]。

入参

字段	位置	类型	必填	含义
id	path	Long	是	订单 ID

入参示例

GET /v3/admin/order/1900000000000903/transport-plans

出参：List<TransportPlanVO>（每条 17 字段）

字段	类型	含义
id	String	批次 ID
orderId	String	订单 ID
direction	String	方向 ARRIVAL/DEPARTURE
mode	String	TOGETHER(一起)/SEPARATE(分批)
transportType	String	FLIGHT/TRAIN/SELF_DRIVE
transportNo	String	航班号/车次号
carrier	String	航司/铁路公司
departStation	String	出发站
arriveStation	String	到达站
departTime	LocalDateTime	出发时间
arriveTime	LocalDateTime	到达时间
selfDrivePeriod	String	自驾时段 MORNING/AFTERNOON/EVENING
selfDriveEta	LocalDateTime	自驾预计到达时间
pickupRequired	Boolean	是否需要接送
pickupRemark	String	接送备注
travelers	List<TravelerRef>	关联出行人
remark	String	备注

TravelerRef（关联出行人）

字段	类型	含义
id	String	出行人 ID
name	String	出行人姓名

出参示例

{
  "code": 200, "message": "成功", "success": true,
  "data": [{
    "id": "7001", "orderId": "1900000000000903", "direction": "ARRIVAL",
    "mode": "TOGETHER", "transportType": "FLIGHT", "transportNo": "CA1234", "carrier": "中国国航",
    "departStation": "北京首都T3", "arriveStation": "长春龙嘉",
    "departTime": "2026-07-01 08:00:00", "arriveTime": "2026-07-01 10:00:00",
    "selfDrivePeriod": null, "selfDriveEta": null,
    "pickupRequired": true, "pickupRemark": "出站口接机举牌",
    "travelers": [{"id": "1910000000000001", "name": "张三"}],
    "remark": null
  }]
}

8. 状态记录时间线 Tab

接口地址：GET /v3/admin/order/{id}/status-log 接口介绍：订单全生命周期状态/操作流水时间线。 本次修改点：无字段变更。无记录返回 data:[]。

入参

字段	位置	类型	必填	含义
id	path	Long	是	订单 ID

入参示例

GET /v3/admin/order/1900000000000903/status-log

出参：List<LogTimelineVO>

字段	类型	含义
occurredAt	LocalDateTime	发生时间
operator	String	操作人
action	String	操作描述
fromStatus	String	变更前状态（有状态变更时有值）
toStatus	String	变更后状态（有状态变更时有值）
amount	BigDecimal	涉及金额（支付/退款时有值）

出参示例

{
  "code": 200, "message": "成功", "success": true,
  "data": [
    {"occurredAt": "2026-06-04 18:49:39", "operator": "李定制", "action": "创建订单", "fromStatus": null, "toStatus": "CUSTOMIZING", "amount": null},
    {"occurredAt": "2026-06-04 19:00:00", "operator": "测试客户", "action": "支付订金", "fromStatus": null, "toStatus": null, "amount": 5000.00}
  ]
}

9. 退款明细 Tab

接口地址：GET /v3/admin/order/{id}/refund 接口介绍：订单退款申请明细（可多笔），含审批/到账进度时间线。 本次修改点：无字段变更。无退款申请时整节返回 data:null（前端需与"订单不存在 581007"区分）。

入参

字段	位置	类型	必填	含义
id	path	Long	是	订单 ID

入参示例

GET /v3/admin/order/1900000000000903/refund

出参：RefundDetailVO

字段	类型	含义
totalRefundAmount	BigDecimal	合计退款金额
applications	List<RefundApplicationVO>	多笔退款申请

RefundApplicationVO

字段	类型	含义
applicationId	String	申请 ID
status	String	状态（附录 B）
statusText	String	状态描述文案
refundAmount	BigDecimal	退款金额
refundChannel	String	退款渠道
approverName	String	审批人
approvedAt	LocalDateTime	审批时间
estimatedArriveDate	LocalDate	预计到账日期
actualArriveDate	LocalDate	实际到账日期（未到账 null）
progress	List<ProgressStepVO>	4 步进度时间线
items	List<RefundItemVO>	退款明细行

ProgressStepVO

字段	类型	含义
step	String	APPLY/APPROVE/PAYOUT/ARRIVED
label	String	展示标签
status	String	DONE/ACTIVE/PENDING
occurredAt	LocalDateTime	发生时间（PENDING 时 null）

RefundItemVO

字段	类型	含义
itemName	String	项目名称
reason	String	退款原因
appliedAt	LocalDateTime	申请时间
amount	BigDecimal	退款金额（负数）

出参示例

// 空态（无退款）
{"code": 200, "message": "成功", "success": true, "data": null}

// 有退款
{
  "code": 200, "message": "成功", "success": true,
  "data": {
    "totalRefundAmount": 1000.00,
    "applications": [{
      "applicationId": "8001", "status": "PENDING_PAYOUT", "statusText": "待打款",
      "refundAmount": 1000.00, "refundChannel": "原路退回", "approverName": "财务老王",
      "approvedAt": "2026-06-05 14:00:00", "estimatedArriveDate": "2026-06-08", "actualArriveDate": null,
      "progress": [
        {"step": "APPLY", "label": "提交申请", "status": "DONE", "occurredAt": "2026-06-05 13:00:00"},
        {"step": "APPROVE", "label": "审批通过", "status": "DONE", "occurredAt": "2026-06-05 14:00:00"},
        {"step": "PAYOUT", "label": "打款", "status": "ACTIVE", "occurredAt": null},
        {"step": "ARRIVED", "label": "到账", "status": "PENDING", "occurredAt": null}
      ],
      "items": [{"itemName": "酒店退订", "reason": "行程缩短", "appliedAt": "2026-06-05 13:00:00", "amount": -1000.00}]
    }]
  }
}

10. 服务标准 Tab

接口地址：GET /v3/admin/order/{id}/service-standard 接口介绍：订单服务标准（出团承诺 + 逐天行程 + 退费说明），数据源为产品侧预置并冻入订单快照的成品。 本次修改点：重构为一站式聚合（#3340/#3351）——原 itinerary/notice/refundPolicy/serviceStandard/dayTips 五字段全部替换为本套 ServiceStandardVO 结构；读快照预置成品。产品快照缺失时返回 data:null。

入参

字段	位置	类型	必填	含义
id	path	Long	是	订单 ID

入参示例

GET /v3/admin/order/1900000000000903/service-standard

出参：ServiceStandardVO

字段	类型	含义
title	String	标题（"出团服务标准·"+产品名；name 空时退化为"出团服务标准"）
subtitle	String	副标题（固定常量）
intro	String	服务标准简介（无结构 null）
notices	List<NoticeItem>	服务承诺条目扁平列表（无结构空列表）
itinerary	List<DayVO>	行程逐天列表
refundNotes	List<RefundNoteGroup>	退费说明聚合列表（无退费说明空列表）

NoticeItem（服务承诺条目）

字段	类型	含义
title	String	主文案标题
content	String	正文
remark	String	灰色二级说明（可选）
color	String	文案颜色 #RRGGBB（可选）
contactName	String	联系人（可选）
phone	String	手机号（可选）

DayVO（行程天）

字段	类型	含义
dayNumber	Integer	天序号
dayTitle	String	天标题
remark	String	当天备注（恒 null）
itineraryNode	List<ItineraryNode>	当天点位列表

ItineraryNode（行程点位）

字段	类型	含义
nodeName	String	点位名称
description	String	点位描述
contactName	String	联系人（占位，恒 null）
phone	String	手机号（占位，恒 null）

RefundNoteGroup（退费说明分组）

字段	类型	含义
sourceName	String	来源点位名称
intro	String	退费说明备注
items	List<RefundItem>	退费明细列表

RefundItem（退费明细）

字段	类型	含义
title	String	展示标题
amount	BigDecimal	退费金额（赠送为 0）
unitLabel	String	展示文案 /人 /团 /辆
settleScope	String	结算粒度 PER_PERSON/PER_TEAM/PER_VEHICLE
settleScopeLabel	String	结算粒度中文
remark	String	备注
effectiveFrom	LocalDate	生效起日（null=无限制）
effectiveTo	LocalDate	生效止日（null=无限制）

出参示例（取自测试服 903 真实返回）

{
  "code": 200, "message": "成功", "success": true,
  "data": {
    "title": "出团服务标准·长白山3日私家定制游",
    "subtitle": "领队/师傅/运营 共同遵守·配合合同执行",
    "intro": "我们承诺全程提供贴心服务保障，专车专导，确保旅途安心舒适。",
    "notices": [
      {"title": "接送站服务", "content": "司机持有 A1 驾照，8 年以上驾龄，提供机场/高铁站免费接送",
       "remark": "仅限指定时段（08:00-20:00）", "color": "#FF6600", "contactName": "李师傅", "phone": "13800000000"},
      {"title": "用餐标准", "content": "每日含早餐，正餐按行程安排当地特色餐",
       "remark": "忌口请提前告知", "color": null, "contactName": null, "phone": null}
    ],
    "itinerary": [{
      "dayNumber": 1, "dayTitle": "抵达长春-接机入住", "remark": null,
      "itineraryNode": [
        {"nodeName": "长春龙嘉国际机场", "description": "专车接机，送往酒店休息", "contactName": null, "phone": null},
        {"nodeName": "入住酒店", "description": "长春市区四星酒店，自由活动", "contactName": null, "phone": null}
      ]
    }],
    "refundNotes": [{
      "sourceName": "长白山天池", "intro": "景区门票及区间车费用，按下列规则退费",
      "items": [
        {"title": "成人未参加", "amount": 125, "unitLabel": "/人", "settleScope": "PER_PERSON",
         "settleScopeLabel": "按人", "remark": "含门票105+环保车20", "effectiveFrom": null, "effectiveTo": null}
      ]
    }]
  }
}

附录 A 枚举字典

OrderStatus（订单粗状态）

值	中文
PENDING_PAY	待支付
CUSTOMIZING	定制中
PENDING_DEPARTURE	待出行
TRAVELLING	出行中
COMPLETED	已完成
CANCELLED	已取消

OrderFlowStatus（订单细状态，12 态）

值	中文
AWAITING_PAY	待支付
AWAITING_PROFILE	待补全信息
RESOURCE_PREPARING	资源准备
PENDING_CONFIRM	待确认
PENDING_DEPARTURE	待出行
TRAVELLING	出行中
PENDING_REVIEW	待核单
REVIEWING	核单中
PENDING_SETTLE	待结算
SETTLED	已结算
COMPLETED	已完成
CANCELLED	已取消

OrderFlowMainStep（6 主步，flowStepCode / progressStepper）

code	step	中文
PROFILE	1	补全信息
RESOURCE	2	资源准备
CONFIRM	3	确认
DEPART	4	出行
REVIEW	5	核单
SETTLE	6	结算

flowStep=0 表示"待支付"（步骤条未开始）；CANCELLED 终态 flowStep=null、flowStepCode=null。

其他枚举

枚举字段	值	中文
createSource	CONSULTANT / CUSTOMER	定制师创建（默认/兜底） / C端客户自下单
payStatus	UNPAID / DEPOSIT_PAID / FULLY_PAID	未支付 / 订金已付 / 全款已付
paymentMode	DEPOSIT / FULL	订金模式 / 全款模式
refundStatus(main 徽标)	NONE / PROCESSING / COMPLETED	无退款 / 退款中 / 已完成
invoiceType	VAT_NORMAL / VAT_SPECIAL / ELECTRONIC	增值税普票 / 增值税专票 / 电子普票
invoice status	APPLIED / ISSUED / UPLOADED / DELIVERED / VOIDED	已申请 / 已开票 / 已上传 / 已送达 / 已作废
invoice auditStatus	PENDING / APPROVED / MANUAL_REVIEW / REJECTED	待审 / 通过 / 转人工 / 拒绝
titleType	COMPANY / PERSONAL	公司 / 个人
transportType	FLIGHT / TRAIN / SELF_DRIVE	飞机 / 火车 / 自驾
direction	ARRIVAL / DEPARTURE	抵达 / 返程
settleScope	PER_PERSON / PER_TEAM / PER_VEHICLE	按人 / 按团 / 按辆
travelerType	ADULT / CHILD / YOUNG_CHILD / BABY	成人 / 儿童 / 小童 / 婴儿
idType	ID_CARD / PASSPORT / BIRTH_CERT	身份证 / 护照 / 出生证
通用 status	DONE / PROCESSING / WAITING	完成 / 处理中 / 等待

附录 B 枚举口径差异（⚠️ 按字符串容错，配合 statusText）

字段	底层枚举类取值	VO 文案口径
contractStatus	PENDING/GENERATED/REPORTED/UPLOADED/SIGNING/SIGNED/VOIDING/VOIDED	NONE/GENERATING/GENERATED/SIGNED/VOIDED/RESIGNING
insuranceStatus	PENDING/INSURING/INSURED/CANCELLED/FAILED	NONE/INSURED/CANCELLED/FAILED
refund status	PENDING/APPROVED/REJECTED/REFUNDING/REFUNDED/CANCELLED/ABNORMAL	PENDING_APPROVE/PENDING_PAYOUT/PENDING_ARRIVAL/COMPLETED/REJECTED

上述由 Converter 映射，前端勿硬编码全集，按接口实际返回字符串渲染 + 用 statusText 展示文案。

关联 / 联系人

Issue：#3517 #3514 #3509 #3502 #3500 #3493 #3488 #3385 #3340 #3523
PR：#3521 #3524 #3510 #3388
基线 commit：f95757df7 ｜后端负责人：腰苏图（订单 v3）

42 KiB 原始文件 Blame 文件历史 Unescape Escape

订单列表 + 订单详情 + 懒加载 Tab 接口契约清单（管理后台）

通用约定

接口总览

1. 订单列表

2. 订单详情（主接口）

3. 财务 Tab

4. 合同保险 Tab

5. 发票 Tab 〔新增接口〕

6. 行程 Tab

7. 大交通批次 Tab

8. 状态记录时间线 Tab

9. 退款明细 Tab

10. 服务标准 Tab

附录 A 枚举字典

OrderStatus（订单粗状态）

OrderFlowStatus（订单细状态，12 态）

OrderFlowMainStep（6 主步，flowStepCode / progressStepper）

其他枚举

附录 B 枚举口径差异（⚠️ 按字符串容错，配合 statusText）

关联 / 联系人

42 KiB

原始文件 Blame 文件历史