整理 order-v3 订单核心 10 个查询接口最新契约:列表 + 详情主接口 + 8 个懒加载 Tab(finance/contract-insurance/invoices/itinerary/transport-plans/status-log/refund/service-standard)。 含 13 节自包含文档:全字段出参(含嵌套)、16 类枚举、错误码 581007、典型/边界/异常示例、修改前后对比。 纳入近期变更:#3521 新增发票 Tab、#3514 合同保险真实化、#3523 删 surchargeType、#3509 出行人明文、#3502 删 itinerary days、#3488 overview 重构、#3385 主接口瘦身、#3340 服务标准聚合。 基线 commit f95757df7。
25 KiB
订单列表 + 订单详情 + 懒加载 Tab 接口契约清单(管理后台)
端类型:管理后台(v3) 变更类型:修改接口(近期多 PR 累积的订单详情系列契约最新版整理,含 1 个新增 Tab) 服务:hl-order-service-v3 | Controller:
OrderController(前缀/v3/admin/order) 提取基线 commit:f95757df7(dev-v3)|日期:2026-06-05
① 接口背景
订单详情页采用「主接口 + 懒加载 Tab」架构:进入详情页先调主接口拿头部信息与状态徽标,各 Tab 点开时再各自拉取(#3385 主接口瘦身落地)。本文整理订单列表、详情主接口、8 个懒加载 Tab 共 10 个查询接口的完整契约,供前端订单模块对接对齐。
近期这批接口经历多轮重构(overview 重构、出行人明文、行程/配房真实化、服务标准一站式聚合、新增发票 Tab、删冗余字段等),本文为各接口当前最新契约,前端请以本文为准更新。
统一约定:
- 响应包装
Result<T>(code=200为成功);列表为PageResult<T>。 - 所有 Long 主键经
ToStringSerializer序列化为字符串,前端按字符串接收,勿用 number。 - 鉴权:管理后台 JWT,请求头
Authorization: Bearer <token>。 - 时间字段为
yyyy-MM-dd HH:mm:ss,日期字段为yyyy-MM-dd。
② 变更清单
| 接口 | 本次状态 | 关联 |
|---|---|---|
GET /v3/admin/order/{id}/invoices |
新增 发票 Tab | #3517 / #3521 |
GET /v3/admin/order/{id}/contract-insurance |
events 真实化(来自 status_log / insurance_status_log,不再恒空) | #3514 |
GET /v3/admin/order/{id}/finance |
SurchargeVO 删除 surchargeType 字段(恒 null 无数据源) |
#3523 |
GET /v3/admin/order/{id} (overview) |
出行人改明文返回(idCard/phone/emergencyPhone 不脱敏);overview 重构为 customerInfo + remarkInfo 两分类 | #3488 / #3509 |
GET /v3/admin/order/{id}/itinerary |
删顶层 MOCK days;hotelGroup/vehicleGroup.requirement 真实化;assignment 增 requirementId |
#3385 / #3493 / #3500 / #3502 |
GET /v3/admin/order/{id} (main) |
主接口瘦身:transportPlans / itinerary 移出主接口,改独立懒加载 | #3385 |
GET /v3/admin/order/{id}/service-standard |
重构为一站式聚合,读产品快照预置 serviceStandard 成品 | #3340 / #3351 |
③ 接口详情(10 个)
| # | 接口 | Method | 出参类型 | 空态 |
|---|---|---|---|---|
| 1 | /v3/admin/order |
GET | PageResult<OrderListItemRespVO> |
list=[] |
| 2 | /v3/admin/order/{id} |
GET | OrderDetailRespVO |
订单不存在抛 581007 |
| 3 | /v3/admin/order/{id}/finance |
GET | FinanceVO |
子列表空(非 null) |
| 4 | /v3/admin/order/{id}/contract-insurance |
GET | ContractInsuranceVO |
events 空列表 |
| 5 | /v3/admin/order/{id}/invoices |
GET | List<InvoiceVO> |
data=[] |
| 6 | /v3/admin/order/{id}/itinerary |
GET | ItineraryVO |
assignment 当前恒空 |
| 7 | /v3/admin/order/{id}/transport-plans |
GET | List<TransportPlanVO> |
data=[] |
| 8 | /v3/admin/order/{id}/status-log |
GET | List<LogTimelineVO> |
data=[] |
| 9 | /v3/admin/order/{id}/refund |
GET | RefundDetailVO |
data=null |
| 10 | /v3/admin/order/{id}/service-standard |
GET | ServiceStandardVO |
data=null(快照缺失) |
懒加载 Tab = #3~#10 共 8 个。
refund与service-standard无数据时整节返回data:null,其余 Tab 返回空列表/空对象,请前端区分处理。
④ 入参
接口 1 列表(OrderListReqVO,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) | 李定制 |
接口 2~10
| 字段 | 位置 | 类型 | 必填 | 含义 |
|---|---|---|---|---|
| id | path | Long | 是 | 订单 ID |
⑤ 出参
接口 1 — OrderListItemRespVO(单条,35 字段)
| 字段 | 类型 | 含义 |
|---|---|---|
| id | String | 订单 ID |
| orderNo | String | 订单号(创单生成,永不变) |
| teamNo | String | 团号(订金支付成功时生成,创单为 null) |
| displayOrderNo | String | 展示订单号(orderNo+teamNo) |
| productName | String | 产品名(快照) |
| productCoverImg | String | 产品封面 |
| tierName | String | 档位名(快照) |
| customerName | String | 客户姓名 |
| customerPhoneMasked | String | 客户手机(脱敏) |
| peopleSummary | String | 人数摘要("2 大 1 小") |
| departureDate | LocalDate | 出发日(未定为 null) |
| tripDays | Integer | 行程天数 |
| orderStatus | String(枚举) | 粗状态值(见 OrderStatus) |
| orderStatusName | String | 粗状态中文 |
| flowStatus | String(枚举) | 细状态值(见 OrderFlowStatus) |
| flowStatusName | String | 细状态中文 |
| flowStep | Integer | 6 步当前步序号(0=待支付,1-6,null=已取消) |
| flowStepTotal | Integer | 总步数(固定 6) |
| flowStepCode | String(枚举) | 当前步英文码(见 OrderFlowMainStep) |
| currentSubFlows | List<SubFlowVO> | 当前步子流程(仅 RESOURCE 步非 null) |
| totalAmount | BigDecimal | 订单金额 |
| paidAmount | BigDecimal | 实付金额 |
| balanceAmount | BigDecimal | 待付金额 |
| consultantName | String | 定制师姓名 |
| createSource | String(枚举) | 来源值 CONSULTANT/CUSTOMER |
| createSourceLabel | String | 来源中文(字典缺失为 null) |
| 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(HOTEL/VEHICLE/GUIDE/PHOTOGRAPHER)、name、status(DONE/PROCESSING/WAITING)、label。
TagVO:name、type(SYSTEM/MANUAL)、color(#RRGGBB)、creator(创建人姓名)。
接口 2 — OrderDetailRespVO
顶层:main(OrderMainVO) + tags(List<TagVO>) + overview(OverviewVO)。
main(OrderMainVO,47 字段)
| 字段 | 类型 | 含义 |
|---|---|---|
| id | String | 订单 ID |
| orderNo | String | 订单号 |
| teamNo | String | 团号(未成团 null) |
| displayOrderNo | String | 展示订单号 |
| productName | String | 产品名 |
| tierName | String | 档位名 |
| orderStatus / orderStatusName | String | 粗状态值 / 中文 |
| flowStatus / flowStatusName | String | 细状态值 / 中文 |
| flowStep | Integer | 6 步当前步序号(0/1-6/null) |
| flowStepTotal | Integer | 总步数(6) |
| flowDisplayText | String | 步骤展示文案(纯中文,不带 "X/6 ·") |
| flowStepCode | String(枚举) | 当前步英文码(CANCELLED/待支付为 null) |
| flowStepStatus | String | 当前步状态(PROCESSING=进行中) |
| totalAmount / paidAmount / balanceAmount | BigDecimal | 金额三件套 |
| departureDate / returnDate | LocalDate | 出发 / 返回日期 |
| tripDays / tripNights | Integer | 行程天 / 夜数 |
| createSource / createSourceLabel | String | 来源值 / 中文 |
| confirmedAt | LocalDateTime | 确认订单时间 |
| progressStepper | List<PipelineNodeVO> | 6 主节点进度管道(RESOURCE 含 subFlows,已取消返空数组) |
| contractStatus | String(枚举) | [Tab 徽标] 合同状态(取值见 ⑥,按字符串容错) |
| insuranceStatus | String(枚举) | [Tab 徽标] 保险状态 |
| refundStatus | String(枚举) | [Tab 徽标] 退款状态 NONE/PROCESSING/COMPLETED |
| hasRefund | Boolean | 是否有退款记录 |
| hasServiceStandard | Boolean | 是否有服务标准快照 |
| hasFinanceDetail | Boolean | 是否有财务明细(discount/surcharge>0) |
| depositAmount / depositRatio | BigDecimal/Integer | 订金(FULL 为 null) |
| paymentMode | String(枚举) | DEPOSIT/FULL |
| singleRoomSurcharge | BigDecimal | 单房差(未触发 null) |
| agencyId / refundPolicyId | String | 旅行社 / 退款政策 ID |
| productSubtitle | String | 产品副标题 |
| payStatus | String(枚举) | 支付状态 UNPAID/DEPOSIT_PAID/FULLY_PAID |
PipelineNodeVO:step(1-6)、code(PROFILE/RESOURCE/CONFIRM/DEPART/REVIEW/SETTLE)、name、status(DONE/PROCESSING/WAITING)、label、isCurrent(Boolean)、subFlows(List<SubFlowVO>,仅 RESOURCE 节点非 null)。
overview(OverviewVO):customerInfo(CustomerInfoVO) + remarkInfo(RemarkInfoVO)。
CustomerInfoVO:contactName、contactPhone(admin 明文)、agencyName、consultantName、peopleSummary、adultCount、childCount、youngChildCount、babyCount、createTime、emergencyContactName、emergencyContactPhone(明文)、travelers(List<TravelerPlainVO>)。
TravelerPlainVO(出行人,明文 #3509):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<Long>)。
RemarkInfoVO:customerRemark(用户备注,只读)、consultantRemark(定制师备注)、hotelRemark(无需求 null)、vehicleRemark(无需求 null)。
接口 3 — FinanceVO(财务 Tab)
| 字段 | 类型 | 含义 |
|---|---|---|
| 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。〔#3523 已删 surchargeType〕
接口 4 — ContractInsuranceVO(合同保险 Tab)
contract(ContractVO) + insurance(InsuranceVO)。
ContractVO:contractStatus、contractSignedAt、contractFileUrl、events(List<EventVO>,#3514 真实化)。
InsuranceVO:insuranceStatus、insurancePolicyNo、insurancePremium、events(List<EventVO>)。
EventVO:eventType(GENERATE/SIGN/ISSUE/…)、occurredAt。
接口 5 — InvoiceVO(发票 Tab,#3521 新增,23 字段)
返回该订单全部发票(含 VOIDED),按 applyAt 倒序;无发票 data=[]。
| 字段 | 类型 | 含义 |
|---|---|---|
| id | String | 发票 ID |
| orderId | String | 订单 ID |
| invoiceType | String(枚举) | VAT_NORMAL/VAT_SPECIAL/ELECTRONIC |
| invoiceTypeText | String | 类型文案(增值税普通/专用发票、电子普通发票) |
| titleType | String(枚举) | 抬头类型 COMPANY/PERSONAL |
| titleName | String | 抬头名称 |
| taxNo | String | 税号(公司抬头/专票必填) |
| amount | BigDecimal | 开票金额(元) |
| status | String(枚举) | APPLIED/ISSUED/UPLOADED/DELIVERED/VOIDED |
| 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 时有值) |
| String | 邮箱(电子发票) | |
| mailAddress | String | 邮寄地址(纸质发票) |
| bankName | String | 开户行(专票) |
| bankAccount | String | 开户账号(专票) |
| registAddress | String | 注册地址(专票) |
| registPhone | String | 注册电话(专票) |
接口 6 — ItineraryVO(行程 Tab)
hotelGroup(HotelGroupVO) + vehicleGroup(VehicleGroupVO)。〔#3502 已删顶层 days,逐天行程走 /itinerary/full〕
HotelGroupVO:requirement(HotelRequirementBriefVO) + assignments(List<HotelAssignmentVO>)。
VehicleGroupVO:requirement(VehicleRequirementBriefVO) + assignments(List<VehicleAssignmentVO>)。
HotelRequirementBriefVO:requirementId、version、status(PENDING/PROCESSING/DONE)、submittedAt、totalRoomCount、roomTypeSummary(双床房×4)、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(当前恒返空,待接 house 域):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。
接口 7 — TransportPlanVO(大交通 Tab,List,17 字段)
id、orderId、direction(ARRIVAL/DEPARTURE)、mode(TOGETHER/SEPARATE)、transportType(FLIGHT/TRAIN/SELF_DRIVE)、transportNo、carrier、departStation、arriveStation、departTime、arriveTime、selfDrivePeriod(MORNING/AFTERNOON/EVENING)、selfDriveEta、pickupRequired(Boolean)、pickupRemark、travelers(List<TravelerRef>{id,name})、remark。
接口 8 — LogTimelineVO(状态时间线 Tab,List)
occurredAt、operator、action、fromStatus、toStatus、amount(支付/退款时有值)。
接口 9 — RefundDetailVO(退款 Tab,无退款 data=null)
totalRefundAmount + applications(List<RefundApplicationVO>)。
RefundApplicationVO:applicationId、status(枚举见 ⑥)、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(负数)。
接口 10 — ServiceStandardVO(服务标准 Tab,快照缺失 data=null)
title、subtitle、intro(无结构 null)、notices(List<NoticeItem>)、itinerary(List<DayVO>)、refundNotes(List<RefundNoteGroup>)。
NoticeItem:title、content、remark(可选)、color(#RRGGBB 可选)、contactName(可选)、phone(可选)。
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=无限制)。
⑥ 枚举 / 数据字典
OrderStatus(粗状态,6 态):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 主步,progressStepper/flowStepCode):PROFILE(1) 补全信息 / RESOURCE(2) 资源准备 / CONFIRM(3) 确认 / DEPART(4) 出行 / REVIEW(5) 核单 / SETTLE(6) 结算。
flowStep=0 表示"待支付"(步骤条未开始);CANCELLED 终态 flowStep=null、flowStepCode=null。
OrderCreateSource:CONSULTANT 定制师创建(默认/兜底) / CUSTOMER C端客户自下单。 OrderMainRefundStatus(main.refundStatus):NONE 无退款 / PROCESSING 退款中 / COMPLETED 已完成。 payStatus:UNPAID 未支付 / DEPOSIT_PAID 订金已付 / FULLY_PAID 全款已付。 paymentMode:DEPOSIT 订金模式 / FULL 全款模式。
发票 invoiceType:VAT_NORMAL 增值税普票 / VAT_SPECIAL 增值税专票 / ELECTRONIC 电子普票。 发票 status:APPLIED 已申请 / ISSUED 已开票 / UPLOADED 已上传 / DELIVERED 已送达 / VOIDED 已作废。 发票 auditStatus:PENDING / APPROVED / MANUAL_REVIEW / REJECTED。 发票 titleType:COMPANY 公司 / PERSONAL 个人。
⚠️ 3 处枚举口径差异(VO 文案 vs 底层枚举类,由 Converter 映射,前端一律按接口实际返回的字符串容错处理,不要硬编码全集):
contractStatus:底层 ContractStatus = PENDING/GENERATED/REPORTED/UPLOADED/SIGNING/SIGNED/VOIDING/VOIDED;VO 文案口径 NONE/GENERATING/GENERATED/SIGNED/VOIDED/RESIGNING。insuranceStatus:底层 InsuranceOrderStatus = PENDING/INSURING/INSURED/CANCELLED/FAILED;VO 文案口径 NONE/INSURED/CANCELLED/FAILED。refund status(RefundApplicationVO.status):底层 RefundApplicationStatus = PENDING/APPROVED/REJECTED/REFUNDING/REFUNDED/CANCELLED/ABNORMAL;VO 进度展示口径 PENDING_APPROVE/PENDING_PAYOUT/PENDING_ARRIVAL/COMPLETED/REJECTED。请配合statusText字段展示。
⑦ 错误码
| code | message | 触发 |
|---|---|---|
| 200 | 成功 | 正常 |
| 581007 | 订单不存在 | 接口 2~10 传入不存在的订单 ID(订单域段位错误码) |
错误以
Result包装,HTTP 状态恒 200,前端判success/code。refund、service-standard的data:null是正常空态,不是错误。
⑧ 示例
典型(详情主接口,列表/详情)
GET /v3/admin/order/1900000000000903
Authorization: Bearer <token>
{"code":200,"message":"成功","data":{
"main":{"id":"1900000000000903","orderNo":"TEST-RESOURCE-903","orderStatus":"CUSTOMIZING","orderStatusName":"定制中","flowStatus":"RESOURCE_PREPARING","flowStatusName":"资源准备","flowStep":2,"flowStepTotal":6,"flowStepCode":"RESOURCE","totalAmount":9800.00,"paidAmount":0.00,"contractStatus":"NONE","insuranceStatus":"NONE","refundStatus":"NONE","payStatus":"UNPAID","paymentMode":"FULL", "...":"…"},
"tags":[],
"overview":{"customerInfo":{"contactName":"测试客户","contactPhone":"13800138001","travelers":[]},"remarkInfo":{}}
},"success":true}
典型(服务标准 Tab,已填充)
GET /v3/admin/order/1900000000000903/service-standard
{"code":200,"message":"成功","data":{
"title":"出团服务标准·长白山3日私家定制游",
"subtitle":"领队/师傅/运营 共同遵守·配合合同执行",
"intro":"我们承诺全程提供贴心服务保障…",
"notices":[{"title":"接送站服务","content":"司机持有 A1 驾照…","color":"#FF6600","contactName":"李师傅","phone":"13800000000"}],
"itinerary":[{"dayNumber":1,"dayTitle":"抵达长春-接机入住","itineraryNode":[{"nodeName":"长春龙嘉国际机场","description":"专车接机…"}]}],
"refundNotes":[{"sourceName":"长白山天池","intro":"按下列规则退费","items":[{"title":"成人未参加","amount":125,"unitLabel":"/人","settleScope":"PER_PERSON","settleScopeLabel":"按人"}]}]
},"success":true}
边界(退款/服务标准 空态)
GET /v3/admin/order/{id}/refund
{"code":200,"message":"成功","data":null,"success":true}
异常(订单不存在)
GET /v3/admin/order/999999/finance
{"code":581007,"message":"订单不存在","data":null,"success":false}
⑨ 业务边界
- 列表
flowStep:0=待支付未进入步骤条;1-6=进行中;null=已取消终态。前端步骤条按此渲染。 currentSubFlows/progressStepper[].subFlows仅在 RESOURCE(资源准备)步非空。- overview 出行人 / 联系电话 / 证件号在 admin 端明文返回(#3509),前端如需展示脱敏由前端处理;日志侧后端已脱敏。
- itinerary 的
HotelAssignmentVO(实配酒店)当前恒返空,待 house 域接通;前端先按空处理,勿报错。 - 发票 Tab 返回全部发票含已作废(VOIDED),前端按
status区分展示。
⑩ 修改前后对比(相对前端手上旧契约)
| 点 | 旧 | 新 |
|---|---|---|
| 详情主接口 | 含 transportPlans / itinerary 全量 | 已移出,改独立懒加载接口(#3385) |
| overview | 扁平字段 | 重构为 customerInfo + remarkInfo 两分类(#3488) |
| 出行人 idCard/phone/emergencyPhone | 脱敏 | 明文(#3509) |
| itinerary 顶层 days | MOCK 行程数组 | 已删,逐天走 /itinerary/full(#3502) |
| itinerary requirement | MOCK | 真实需求数据 + assignment 增 requirementId(#3385/#3493/#3502) |
| finance SurchargeVO | 含 surchargeType |
已删该字段(#3523) |
| contract-insurance events | 恒空 list | 真实化(status_log / insurance_status_log,#3514) |
| 发票 Tab | 无 | 新增 GET /{id}/invoices(#3521) |
| service-standard | 五字段(itinerary/notice/refundPolicy/serviceStandard/dayTips) | 一站式聚合 ServiceStandardVO(#3340/#3351) |
⑪ 影响评估 / 回滚
- 影响面:管理后台订单详情页全部 Tab + 订单列表页。前端需按本文更新字段映射,重点处理:overview 两分类结构、出行人明文、itinerary 删 days、finance 删 surchargeType、新增发票 Tab。
- 兼容性:删除字段(surchargeType、itinerary.days)为破坏性,前端引用处需同步删除/改造,否则取值为 undefined。
- 回滚:各变更已分别 PR 合入 dev-v3,回滚以对应 PR revert 为准;前端可保留旧字段读取的容错(取不到按空处理)平滑过渡。
⑫ 注意事项
- 所有 Long ID(含 transportPlanIds 元素、travelers.id)按字符串接收。
contractStatus/insuranceStatus/refund status三处枚举按字符串容错 + 配合 statusText 展示,勿硬编码全集。refund/service-standard的data:null是正常空态,需与"订单不存在(581007)"区分。- 其余 Tab 空态返回空列表
[]或空对象,非 null。 - 时间
yyyy-MM-dd HH:mm:ss,日期yyyy-MM-dd。