yaosutu ab3770f9f9 docs(changelog): 订单列表+详情+懒加载接口契约清单改按接口纵切重写(管理后台)

重构文档结构: 从按维度横切(入参/出参/示例分节)改为按接口纵切，每个接口自成一节，含 接口地址/接口介绍/本次修改点/入参/出参/JSON示例 6 块。

10 个接口逐个: 列表/详情/财务/合同保险/发票(新增)/行程/大交通/状态时间线/退款/服务标准。公共枚举抽到附录A，枚举口径差异抽到附录B。每个接口补完整 JSON 请求+响应示例(903 真实数据 + 合理构造)。

2026-06-05 16:57:13 +08:00

32 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	李定制

出参：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 / orderStatusName	String	粗状态值 / 中文（附录 A）
flowStatus / flowStatusName	String	细状态值 / 中文（附录 A）
flowStep	Integer	6 步当前步序号（0=待支付，1-6，null=已取消）
flowStepTotal	Integer	总步数（6）
flowStepCode	String	当前步英文码（附录 A）
currentSubFlows	List<SubFlowVO>	当前步子流程（仅 RESOURCE 步非 null）
totalAmount / paidAmount / balanceAmount	BigDecimal	金额 / 实付 / 待付
consultantName	String	定制师姓名
createSource / createSourceLabel	String	来源值 / 中文
tags	List<TagVO>	标签列表
createdAt	LocalDateTime	创单时间
depositAmount / depositRatio	BigDecimal/Integer	订金额 / 比例%（FULL 为 null）
paymentMode	String	DEPOSIT/FULL
singleRoomSurcharge	BigDecimal	单房差（未触发 null）
agencyId / refundPolicyId	String	旅行社 / 退款政策 ID
productSubtitle	String	产品副标题

SubFlowVO：code(HOTEL/VEHICLE/GUIDE/PHOTOGRAPHER)、name、status(DONE/PROCESSING/WAITING)、label。 TagVO：name、type(SYSTEM/MANUAL)、color(#RRGGBB)、creator。

JSON 示例

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

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

入参：path id（Long，必填）。

出参：OrderDetailRespVO = main(OrderMainVO) + tags(List<TagVO>) + overview(OverviewVO)。

main（OrderMainVO，47 字段）核心：

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

PipelineNodeVO：step(1-6)、code(PROFILE/RESOURCE/CONFIRM/DEPART/REVIEW/SETTLE)、name、status(DONE/PROCESSING/WAITING)、label、isCurrent(Boolean)、subFlows(仅 RESOURCE 非 null)。

overview（OverviewVO）= customerInfo + remarkInfo：

CustomerInfoVO：contactName、contactPhone(明文)、agencyName、consultantName、peopleSummary、adultCount、childCount、youngChildCount、babyCount、createTime、emergencyContactName、emergencyContactPhone(明文)、travelers(List<TravelerPlainVO>)。
TravelerPlainVO（明文出行人）：id、orderId、travelerType(ADULT/CHILD/YOUNG_CHILD/BABY)、name、gender(1男/2女/0未知)、birthday、idType(ID_CARD/PASSPORT/BIRTH_CERT)、idCard(明文)、nationality、race、phone(明文)、emergencyContact、emergencyPhone(明文)、roomGroupNo、profileStatus(PENDING/COMPLETED)、transportPlanIds(List<String>)。
RemarkInfoVO：customerRemark(只读)、consultantRemark、hotelRemark(无需求 null)、vehicleRemark(无需求 null)。

JSON 示例

GET /v3/admin/order/1900000000000903

{
  "code": 200, "message": "成功", "success": true,
  "data": {
    "main": {
      "id": "1900000000000903", "orderNo": "TEST-RESOURCE-903", "teamNo": null,
      "displayOrderNo": "TEST-RESOURCE-903", "productName": "长白山3日私家定制游", "tierName": "标准档",
      "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",
      "productSubtitle": "私家小团·专车专导"
    },
    "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）——破坏性，前端引用处需移除。

入参：path id（Long，必填）。

出参：FinanceVO

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

PaymentVO：id、payType(DEPOSIT/BALANCE)、amount、paidAt、status(SUCCESS/PENDING/FAIL)。 DiscountVO：id、name、amount、type(EARLY_BIRD/VIP/…)、source(MANUAL/AUTO)、createdAt。 SurchargeVO：id、name、amount、source(HOTEL_ASSIGN/VEHICLE_ASSIGN/…)、createdAt。〔已删 surchargeType〕

JSON 示例

GET /v3/admin/order/1900000000000903/finance

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

入参：path id（Long，必填）。

出参：ContractInsuranceVO = contract + insurance

ContractVO：contractStatus(附录 B)、contractSignedAt、contractFileUrl、events(List<EventVO>)。
InsuranceVO：insuranceStatus(附录 B)、insurancePolicyNo、insurancePremium、events(List<EventVO>)。
EventVO：eventType(GENERATE/SIGN/ISSUE/…)、occurredAt。

JSON 示例

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

{
  "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:[]。

入参：path id（Long，必填）。

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

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

JSON 示例

GET /v3/admin/order/1900000000000903/invoices

{
  "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 域接通，前端按空处理勿报错。

入参：path id（Long，必填）。

出参：ItineraryVO = hotelGroup + vehicleGroup

HotelGroupVO：requirement(HotelRequirementBriefVO) + assignments(List<HotelAssignmentVO>)。
VehicleGroupVO：requirement(VehicleRequirementBriefVO) + assignments(List<VehicleAssignmentVO>)。

HotelRequirementBriefVO：requirementId、version、status(PENDING/PROCESSING/DONE)、submittedAt、totalRoomCount、roomTypeSummary、specialTags(List<String>)、remark、claimerName、days(List<RequirementDayVO>)。　└ RequirementDayVO：dayNumber、stayDate、remark、hotels(List<RequirementHotelVO>)。　　└ RequirementHotelVO：hotelId(可 null)、roomCategory(TWIN/DOUBLE_BED)、roomCategoryLabel、roomCount、budget(可 null)。 HotelAssignmentVO（恒空）：assignmentId、requirementId、familyIndex、dayNumber、stayDate、hotelName、roomType、plannedCost、remark。 VehicleRequirementBriefVO：requirementId、version、status、submittedAt、vehicleTypeSummary、specialTags、remark。 VehicleAssignmentVO：assignmentId、vehicleType、vehicleCount、licensePlate、brand、seats、plannedDailyFee、driverName、driverPhoneMasked(脱敏)、remark。

JSON 示例

GET /v3/admin/order/1900000000000903/itinerary

{
  "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:[]。

入参：path id（Long，必填）。

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

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

JSON 示例

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

{
  "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:[]。

入参：path id（Long，必填）。

出参：List<LogTimelineVO>

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

JSON 示例

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

{
  "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"区分）。

入参：path id（Long，必填）。

出参：RefundDetailVO = totalRefundAmount + applications(List<RefundApplicationVO>) RefundApplicationVO：applicationId、status(附录 B)、statusText、refundAmount、refundChannel、approverName、approvedAt、estimatedArriveDate、actualArriveDate(未到账 null)、progress(List<ProgressStepVO>)、items(List<RefundItemVO>)。 ProgressStepVO：step(APPLY/APPROVE/PAYOUT/ARRIVED)、label、status(DONE/ACTIVE/PENDING)、occurredAt(PENDING 时 null)。 RefundItemVO：itemName、reason、appliedAt、amount(负数)。

JSON 示例

// 空态（无退款）
GET /v3/admin/order/1900000000000903/refund
{"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。

入参：path id（Long，必填）。

出参：ServiceStandardVO：title、subtitle、intro(无结构 null)、notices(List<NoticeItem>)、itinerary(List<DayVO>)、refundNotes(List<RefundNoteGroup>)。 NoticeItem：title、content、remark、color(#RRGGBB)、contactName、phone（后 4 项可选）。 DayVO：dayNumber、dayTitle、remark(恒 null)、itineraryNode(List<ItineraryNode>)。　└ ItineraryNode：nodeName、description、contactName(恒 null)、phone(恒 null)。 RefundNoteGroup：sourceName、intro、items(List<RefundItem>)。　└ RefundItem：title、amount(赠送为 0)、unitLabel(/人 /团 /辆)、settleScope(PER_PERSON/PER_TEAM/PER_VEHICLE)、settleScopeLabel、remark、effectiveFrom(null=无限制)、effectiveTo(null=无限制)。

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

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

{
  "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 主步，code→step）：PROFILE 1 补全信息 / RESOURCE 2 资源准备 / CONFIRM 3 确认 / DEPART 4 出行 / REVIEW 5 核单 / SETTLE 6 结算。flowStep=0 待支付（未进步骤条）；CANCELLED flowStep/flowStepCode=null
OrderCreateSource：CONSULTANT 定制师创建（默认/兜底） / CUSTOMER C端客户自下单
payStatus：UNPAID 未支付 / DEPOSIT_PAID 订金已付 / FULLY_PAID 全款已付
paymentMode：DEPOSIT 订金模式 / FULL 全款模式
refundStatus（main 徽标）：NONE 无退款 / PROCESSING 退款中 / COMPLETED 已完成
发票 invoiceType：VAT_NORMAL 增值税普票 / VAT_SPECIAL 增值税专票 / ELECTRONIC 电子普票
发票 status：APPLIED 已申请 / ISSUED 已开票 / UPLOADED 已上传 / DELIVERED 已送达 / VOIDED 已作废

附录 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）

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

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

通用约定

接口总览

1. 订单列表

2. 订单详情（主接口）

3. 财务 Tab

4. 合同保险 Tab

5. 发票 Tab 〔新增接口〕

6. 行程 Tab

7. 大交通批次 Tab

8. 状态记录时间线 Tab

9. 退款明细 Tab

10. 服务标准 Tab

附录 A 枚举字典

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

关联 / 联系人

32 KiB

原始文件 Blame 文件历史