From 4f91e2ff4e819fb8993630fc66b65b5b2feeefc5 Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Fri, 5 Jun 2026 16:49:38 +0800 Subject: [PATCH 1/4] =?UTF-8?q?docs(changelog):=20=E8=AE=A2=E5=8D=95?= =?UTF-8?q?=E5=88=97=E8=A1=A8+=E8=AF=A6=E6=83=85+=E6=87=92=E5=8A=A0?= =?UTF-8?q?=E8=BD=BDTab=E6=8E=A5=E5=8F=A3=E5=A5=91=E7=BA=A6=E6=B8=85?= =?UTF-8?q?=E5=8D=95(=E7=AE=A1=E7=90=86=E5=90=8E=E5=8F=B0)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 整理 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。 --- ...与详情懒加载接口契约清单-修改接口-管理后台.md | 398 ++++++++++++++++++ 1 file changed, 398 insertions(+) create mode 100644 changelogs-v2/2026-06/05_订单列表与详情懒加载接口契约清单-修改接口-管理后台.md diff --git a/changelogs-v2/2026-06/05_订单列表与详情懒加载接口契约清单-修改接口-管理后台.md b/changelogs-v2/2026-06/05_订单列表与详情懒加载接口契约清单-修改接口-管理后台.md new file mode 100644 index 0000000..c0c11c6 --- /dev/null +++ b/changelogs-v2/2026-06/05_订单列表与详情懒加载接口契约清单-修改接口-管理后台.md @@ -0,0 +1,398 @@ +# 订单列表 + 订单详情 + 懒加载 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`（`code=200` 为成功）；列表为 `PageResult`。 +- 所有 Long 主键经 `ToStringSerializer` 序列化为**字符串**，前端按字符串接收，勿用 number。 +- 鉴权：管理后台 JWT，请求头 `Authorization: Bearer `。 +- 时间字段为 `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` | 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` | data=[] | +| 6 | `/v3/admin/order/{id}/itinerary` | GET | `ItineraryVO` | assignment 当前恒空 | +| 7 | `/v3/admin/order/{id}/transport-plans` | GET | `List` | data=[] | +| 8 | `/v3/admin/order/{id}/status-log` | GET | `List` | 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\ | 否 | 按标签过滤（多标签 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\ | 当前步子流程（仅 RESOURCE 步非 null） | +| totalAmount | BigDecimal | 订单金额 | +| paidAmount | BigDecimal | 实付金额 | +| balanceAmount | BigDecimal | 待付金额 | +| consultantName | String | 定制师姓名 | +| createSource | String(枚举) | 来源值 CONSULTANT/CUSTOMER | +| createSourceLabel | String | 来源中文（字典缺失为 null） | +| tags | List\ | 标签列表 | +| 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\) + `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\ | 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\，仅 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（出行人，明文 #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\)。 + +**RemarkInfoVO**：`customerRemark`(用户备注，只读)、`consultantRemark`(定制师备注)、`hotelRemark`(无需求 null)、`vehicleRemark`(无需求 null)。 + +### 接口 3 — FinanceVO（财务 Tab） + +| 字段 | 类型 | 含义 | +|---|---|---| +| totalAmount / paidAmount / balanceAmount | BigDecimal | 总额 / 实付 / 待付 | +| discountAmount / surchargeAmount / refundAmount | BigDecimal | 优惠 / 附加费 / 退款 汇总 | +| payments | List\ | 支付明细 | +| discounts | List\ | 优惠明细 | +| surcharges | List\ | 附加费用 | + +**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\，#3514 真实化)。 +**InsuranceVO**：`insuranceStatus`、`insurancePolicyNo`、`insurancePremium`、`events`(List\)。 +**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 时有值） | +| email | 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\)。 +**VehicleGroupVO**：`requirement`(VehicleRequirementBriefVO) + `assignments`(List\)。 + +**HotelRequirementBriefVO**：`requirementId`、`version`、`status`(PENDING/PROCESSING/DONE)、`submittedAt`、`totalRoomCount`、`roomTypeSummary`(双床房×4)、`specialTags`(List\)、`remark`、`claimerName`(房控接单人)、`days`(List\)。 +- **RequirementDayVO**：`dayNumber`、`stayDate`、`remark`、`hotels`(List\)。 +- **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\{id,name})、`remark`。 + +### 接口 8 — LogTimelineVO（状态时间线 Tab，List） + +`occurredAt`、`operator`、`action`、`fromStatus`、`toStatus`、`amount`(支付/退款时有值)。 + +### 接口 9 — RefundDetailVO（退款 Tab，无退款 data=null） + +`totalRefundAmount` + `applications`(List\)。 +**RefundApplicationVO**：`applicationId`、`status`(枚举见 ⑥)、`statusText`、`refundAmount`、`refundChannel`、`approverName`、`approvedAt`、`estimatedArriveDate`、`actualArriveDate`(未到账 null)、`progress`(List\)、`items`(List\)。 +**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\)、`itinerary`(List\)、`refundNotes`(List\)。 +**NoticeItem**：`title`、`content`、`remark`(可选)、`color`(#RRGGBB 可选)、`contactName`(可选)、`phone`(可选)。 +**DayVO**：`dayNumber`、`dayTitle`、`remark`(恒 null)、`itineraryNode`(List\)。 +**ItineraryNode**：`nodeName`、`description`、`contactName`(恒 null)、`phone`(恒 null)。 +**RefundNoteGroup**：`sourceName`、`intro`、`items`(List\)。 +**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 + +{"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 为准；前端可保留旧字段读取的容错（取不到按空处理）平滑过渡。 + +--- + +## ⑫ 注意事项 + +1. 所有 Long ID（含 transportPlanIds 元素、travelers.id）按**字符串**接收。 +2. `contractStatus`/`insuranceStatus`/`refund status` 三处枚举**按字符串容错 + 配合 statusText 展示**，勿硬编码全集。 +3. `refund` / `service-standard` 的 `data:null` 是正常空态，需与"订单不存在(581007)"区分。 +4. 其余 Tab 空态返回空列表 `[]` 或空对象，非 null。 +5. 时间 `yyyy-MM-dd HH:mm:ss`，日期 `yyyy-MM-dd`。 + +--- + +## ⑬ 关联 / 联系人 + +- 相关 Issue：[#3517](https://git.1814.love:8443/wx/HL/issues/3517)（发票 Tab）、[#3514](https://git.1814.love:8443/wx/HL/issues/3514)（合同保险真实化）、[#3509](https://git.1814.love:8443/wx/HL/issues/3509)（出行人明文）、[#3502](https://git.1814.love:8443/wx/HL/issues/3502)、[#3500](https://git.1814.love:8443/wx/HL/issues/3500)、[#3493](https://git.1814.love:8443/wx/HL/issues/3493)、[#3488](https://git.1814.love:8443/wx/HL/issues/3488)、[#3385](https://git.1814.love:8443/wx/HL/issues/3385)、[#3340](https://git.1814.love:8443/wx/HL/issues/3340)、[#3523](https://git.1814.love:8443/wx/HL/issues/3523) +- 相关 PR：[#3521](https://git.1814.love:8443/wx/HL/pulls/3521)、[#3524](https://git.1814.love:8443/wx/HL/pulls/3524)、[#3510](https://git.1814.love:8443/wx/HL/pulls/3510)、[#3388](https://git.1814.love:8443/wx/HL/pulls/3388) +- 基线 commit：`f95757df7` +- 后端负责人：腰苏图（订单 v3） From ab3770f9f991bfe2db21a0ed3a114519a9cf68ea Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Fri, 5 Jun 2026 16:57:13 +0800 Subject: [PATCH 2/4] =?UTF-8?q?docs(changelog):=20=E8=AE=A2=E5=8D=95?= =?UTF-8?q?=E5=88=97=E8=A1=A8+=E8=AF=A6=E6=83=85+=E6=87=92=E5=8A=A0?= =?UTF-8?q?=E8=BD=BD=E6=8E=A5=E5=8F=A3=E5=A5=91=E7=BA=A6=E6=B8=85=E5=8D=95?= =?UTF-8?q?=E6=94=B9=E6=8C=89=E6=8E=A5=E5=8F=A3=E7=BA=B5=E5=88=87=E9=87=8D?= =?UTF-8?q?=E5=86=99(=E7=AE=A1=E7=90=86=E5=90=8E=E5=8F=B0)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 重构文档结构: 从按维度横切(入参/出参/示例分节)改为按接口纵切，每个接口自成一节，含 接口地址/接口介绍/本次修改点/入参/出参/JSON示例 6 块。 10 个接口逐个: 列表/详情/财务/合同保险/发票(新增)/行程/大交通/状态时间线/退款/服务标准。公共枚举抽到附录A，枚举口径差异抽到附录B。每个接口补完整 JSON 请求+响应示例(903 真实数据 + 合理构造)。 --- ...与详情懒加载接口契约清单-修改接口-管理后台.md | 807 +++++++++++------- 1 file changed, 512 insertions(+), 295 deletions(-) diff --git a/changelogs-v2/2026-06/05_订单列表与详情懒加载接口契约清单-修改接口-管理后台.md b/changelogs-v2/2026-06/05_订单列表与详情懒加载接口契约清单-修改接口-管理后台.md index c0c11c6..e42c4d5 100644 --- a/changelogs-v2/2026-06/05_订单列表与详情懒加载接口契约清单-修改接口-管理后台.md +++ b/changelogs-v2/2026-06/05_订单列表与详情懒加载接口契约清单-修改接口-管理后台.md @@ -1,62 +1,42 @@ # 订单列表 + 订单详情 + 懒加载 Tab 接口契约清单（管理后台） -> 端类型：**管理后台**（v3） -> 变更类型：**修改接口**（近期多 PR 累积的订单详情系列契约最新版整理，含 1 个新增 Tab） -> 服务：hl-order-service-v3 ｜ Controller：`OrderController`（前缀 `/v3/admin/order`） -> 提取基线 commit：`f95757df7`（dev-v3）｜日期：2026-06-05 +> 端类型：**管理后台**（v3）｜变更类型：**修改接口**（多 PR 累积契约整理 + 1 个新增 Tab） +> 服务：hl-order-service-v3 ｜ Controller 前缀：`/v3/admin/order` ｜ 基线 commit：`f95757df7`｜日期：2026-06-05 + +## 通用约定 + +- 响应包装 `Result`（`code=200` 成功）；列表为 `PageResult`；HTTP 状态恒 200，前端判 `code`/`success`。 +- 所有 Long 主键序列化为**字符串**（防 JS 精度丢失），前端按 string 接收。 +- 鉴权：`Authorization: Bearer `。时间 `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. 订单列表 -订单详情页采用「主接口 + 懒加载 Tab」架构：进入详情页先调主接口拿头部信息与状态徽标，各 Tab 点开时再各自拉取（#3385 主接口瘦身落地）。本文整理订单**列表**、**详情主接口**、**8 个懒加载 Tab** 共 **10 个查询接口**的完整契约，供前端订单模块对接对齐。 +**接口地址**：`GET /v3/admin/order` +**接口介绍**：管理后台订单列表，支持状态/标签/关键字/出发日期/来源/定制师等多条件过滤，分页返回。 +**本次修改点**：无字段变更（沿用现状，列表项含 6 步 flowStep 步骤条字段）。 -近期这批接口经历多轮重构（overview 重构、出行人明文、行程/配房真实化、服务标准一站式聚合、新增发票 Tab、删冗余字段等），本文为各接口**当前最新契约**，前端请以本文为准更新。 - -统一约定： -- 响应包装 `Result`（`code=200` 为成功）；列表为 `PageResult`。 -- 所有 Long 主键经 `ToStringSerializer` 序列化为**字符串**，前端按字符串接收，勿用 number。 -- 鉴权：管理后台 JWT，请求头 `Authorization: Bearer `。 -- 时间字段为 `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` | 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` | data=[] | -| 6 | `/v3/admin/order/{id}/itinerary` | GET | `ItineraryVO` | assignment 当前恒空 | -| 7 | `/v3/admin/order/{id}/transport-plans` | GET | `List` | data=[] | -| 8 | `/v3/admin/order/{id}/status-log` | GET | `List` | 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 参数） +**入参**（query） | 字段 | 类型 | 必填 | 含义 | 示例 | |---|---|---|---|---| @@ -64,118 +44,190 @@ | pageSize | Integer | 否 | 每页条数（默认 10） | 10 | | orderStatus | String | 否 | 粗状态过滤（多值逗号分隔） | CUSTOMIZING | | flowStatus | String | 否 | 细状态过滤 | RESOURCE_PREPARING | -| tagNames | List\ | 否 | 按标签过滤（多标签 AND） | ["二次复购"] | -| keyword | String | 否 | 团号/客户姓名/产品名/订单号 任一 LIKE | 张三 | +| tagNames | List\ | 否 | 标签过滤（多标签 AND） | ["二次复购"] | +| keyword | String | 否 | 团号/客户名/产品名/订单号 LIKE | 张三 | | departureDateFrom | LocalDate | 否 | 出发日期范围起始 | 2026-06-01 | | departureDateTo | LocalDate | 否 | 出发日期范围结束 | 2026-06-30 | | createSource | String | 否 | 来源过滤 | CONSULTANT | | cancelled | Boolean | 否 | 是否含已取消（默认 false） | false | -| consultantName | String | 否 | 定制师姓名（LIKE） | 李定制 | +| consultantName | String | 否 | 定制师姓名 LIKE | 李定制 | -### 接口 2~10 +**出参**：`PageResult`，外层 `records`（数组）+ `total`/`current`/`size` 等分页字段。单条 `OrderListItemRespVO`（35 字段）： -| 字段 | 位置 | 类型 | 必填 | 含义 | -|---|---|---|---|---| -| id | path | Long | 是 | 订单 ID | +| 字段 | 类型 | 含义 | +|---|---|---| +| 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\ | 当前步子流程（仅 RESOURCE 步非 null） | +| totalAmount / paidAmount / balanceAmount | BigDecimal | 金额 / 实付 / 待付 | +| consultantName | String | 定制师姓名 | +| createSource / createSourceLabel | String | 来源值 / 中文 | +| tags | List\ | 标签列表 | +| 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 示例** +```jsonc +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. 订单详情（主接口） -### 接口 1 — OrderListItemRespVO（单条，35 字段） +**接口地址**：`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\) + `overview`(OverviewVO)。 + +`main`（OrderMainVO，47 字段）核心： | 字段 | 类型 | 含义 | |---|---|---| -| 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\ | 当前步子流程（仅 RESOURCE 步非 null） | -| totalAmount | BigDecimal | 订单金额 | -| paidAmount | BigDecimal | 实付金额 | -| balanceAmount | BigDecimal | 待付金额 | -| consultantName | String | 定制师姓名 | -| createSource | String(枚举) | 来源值 CONSULTANT/CUSTOMER | -| createSourceLabel | String | 来源中文（字典缺失为 null） | -| tags | List\ | 标签列表 | -| 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\) + `overview`(OverviewVO)。 - -**main（OrderMainVO，47 字段）** - -| 字段 | 类型 | 含义 | -|---|---|---| -| id | String | 订单 ID | -| orderNo | String | 订单号 | -| teamNo | String | 团号（未成团 null） | -| displayOrderNo | String | 展示订单号 | -| productName | String | 产品名 | -| tierName | String | 档位名 | +| id / orderNo / teamNo / displayOrderNo | String | ID / 订单号 / 团号 / 展示号 | +| productName / tierName / productSubtitle | String | 产品名 / 档位 / 副标题 | | orderStatus / orderStatusName | String | 粗状态值 / 中文 | | flowStatus / flowStatusName | String | 细状态值 / 中文 | -| flowStep | Integer | 6 步当前步序号（0/1-6/null） | -| flowStepTotal | Integer | 总步数（6） | +| flowStep / flowStepTotal | Integer | 6 步序号(0/1-6/null) / 总步(6) | | flowDisplayText | String | 步骤展示文案（纯中文，不带 "X/6 ·"） | -| flowStepCode | String(枚举) | 当前步英文码（CANCELLED/待支付为 null） | -| flowStepStatus | String | 当前步状态（PROCESSING=进行中） | -| totalAmount / paidAmount / balanceAmount | BigDecimal | 金额三件套 | +| flowStepCode / flowStepStatus | String | 当前步英文码 / 状态(PROCESSING) | +| totalAmount / paidAmount / balanceAmount | BigDecimal | 金额 / 实付 / 待付 | | departureDate / returnDate | LocalDate | 出发 / 返回日期 | | tripDays / tripNights | Integer | 行程天 / 夜数 | | createSource / createSourceLabel | String | 来源值 / 中文 | | confirmedAt | LocalDateTime | 确认订单时间 | -| progressStepper | List\ | 6 主节点进度管道（RESOURCE 含 subFlows，已取消返空数组） | -| contractStatus | String(枚举) | [Tab 徽标] 合同状态（取值见 ⑥，按字符串容错） | -| insuranceStatus | String(枚举) | [Tab 徽标] 保险状态 | -| refundStatus | String(枚举) | [Tab 徽标] 退款状态 NONE/PROCESSING/COMPLETED | -| hasRefund | Boolean | 是否有退款记录 | -| hasServiceStandard | Boolean | 是否有服务标准快照 | -| hasFinanceDetail | Boolean | 是否有财务明细（discount/surcharge>0） | +| progressStepper | List\ | 6 主节点进度管道（已取消返空数组） | +| contractStatus / insuranceStatus / refundStatus | String | [Tab 徽标]合同/保险/退款状态（按字符串容错，附录 B） | +| hasRefund / hasServiceStandard / hasFinanceDetail | Boolean | [Tab 徽标]是否有 退款/服务标准/财务明细 | | depositAmount / depositRatio | BigDecimal/Integer | 订金（FULL 为 null） | -| paymentMode | String(枚举) | DEPOSIT/FULL | +| paymentMode / payStatus | String | DEPOSIT/FULL ; UNPAID/DEPOSIT_PAID/FULLY_PAID | | 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\，仅 RESOURCE 节点非 null)。 +`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`(CustomerInfoVO) + `remarkInfo`(RemarkInfoVO)。 +`overview`（OverviewVO）= `customerInfo` + `remarkInfo`： +- **CustomerInfoVO**：`contactName`、`contactPhone`(**明文**)、`agencyName`、`consultantName`、`peopleSummary`、`adultCount`、`childCount`、`youngChildCount`、`babyCount`、`createTime`、`emergencyContactName`、`emergencyContactPhone`(**明文**)、`travelers`(List\)。 +- **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\)。 +- **RemarkInfoVO**：`customerRemark`(只读)、`consultantRemark`、`hotelRemark`(无需求 null)、`vehicleRemark`(无需求 null)。 -**CustomerInfoVO**：`contactName`、`contactPhone`(**admin 明文**)、`agencyName`、`consultantName`、`peopleSummary`、`adultCount`、`childCount`、`youngChildCount`、`babyCount`、`createTime`、`emergencyContactName`、`emergencyContactPhone`(**明文**)、`travelers`(List\)。 +**JSON 示例** +```jsonc +GET /v3/admin/order/1900000000000903 -**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\)。 +{ + "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 + } + } + } +} +``` -**RemarkInfoVO**：`customerRemark`(用户备注，只读)、`consultantRemark`(定制师备注)、`hotelRemark`(无需求 null)、`vehicleRemark`(无需求 null)。 +--- -### 接口 3 — FinanceVO（财务 Tab） +## 3. 财务 Tab + +**接口地址**：`GET /v3/admin/order/{id}/finance` +**接口介绍**：订单财务明细，含金额汇总、支付/优惠/附加费三类明细列表。 +**本次修改点**：`SurchargeVO` **删除 `surchargeType` 字段**（恒 null 无数据源，#3523）——破坏性，前端引用处需移除。 + +**入参**：path `id`（Long，必填）。 + +**出参**：`FinanceVO` | 字段 | 类型 | 含义 | |---|---|---| @@ -185,214 +237,379 @@ | discounts | List\ | 优惠明细 | | surcharges | List\ | 附加费用 | -**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`〕 +`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`〕 -### 接口 4 — ContractInsuranceVO（合同保险 Tab） +**JSON 示例** +```jsonc +GET /v3/admin/order/1900000000000903/finance -`contract`(ContractVO) + `insurance`(InsuranceVO)。 -**ContractVO**：`contractStatus`、`contractSignedAt`、`contractFileUrl`、`events`(List\，#3514 真实化)。 -**InsuranceVO**：`insuranceStatus`、`insurancePolicyNo`、`insurancePremium`、`events`(List\)。 -**EventVO**：`eventType`(GENERATE/SIGN/ISSUE/…)、`occurredAt`。 +{ + "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）。 -### 接口 5 — InvoiceVO（发票 Tab，#3521 新增，23 字段） +--- -返回该订单全部发票（含 VOIDED），按 applyAt 倒序；无发票 `data=[]`。 +## 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\)。 +- `InsuranceVO`：`insuranceStatus`(附录 B)、`insurancePolicyNo`、`insurancePremium`、`events`(List\)。 +- `EventVO`：`eventType`(GENERATE/SIGN/ISSUE/…)、`occurredAt`。 + +**JSON 示例** +```jsonc +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`（每条 23 字段） | 字段 | 类型 | 含义 | |---|---|---| -| id | String | 发票 ID | -| orderId | String | 订单 ID | -| invoiceType | String(枚举) | VAT_NORMAL/VAT_SPECIAL/ELECTRONIC | -| invoiceTypeText | String | 类型文案（增值税普通/专用发票、电子普通发票） | -| titleType | String(枚举) | 抬头类型 COMPANY/PERSONAL | -| titleName | String | 抬头名称 | +| id / orderId | String | 发票 ID / 订单 ID | +| invoiceType / invoiceTypeText | String | 类型值(附录 A) / 文案 | +| titleType / titleName | String | 抬头类型(COMPANY/PERSONAL) / 名称 | | taxNo | String | 税号（公司抬头/专票必填） | | amount | BigDecimal | 开票金额（元） | -| status | String(枚举) | APPLIED/ISSUED/UPLOADED/DELIVERED/VOIDED | -| statusText | String | 状态文案（已申请/已开票/已上传/已送达/已作废） | -| auditStatus | String(枚举) | 内容安全机审 PENDING/APPROVED/MANUAL_REVIEW/REJECTED | -| applyReason | String | 申请说明 | -| applyAt | LocalDateTime | 申请时间 | +| status / statusText | String | 状态值(附录 A) / 文案 | +| auditStatus | String | 内容安全机审(PENDING/APPROVED/MANUAL_REVIEW/REJECTED) | +| applyReason / applyAt | String/LocalDateTime | 申请说明 / 申请时间 | | fileUrl | String | 发票文件 OSS 链接（UPLOADED 后有值） | -| uploader | String | 上传人 | -| uploadedAt | LocalDateTime | 上传时间 | +| uploader / uploadedAt | String/LocalDateTime | 上传人 / 上传时间 | | deliveredAt | LocalDateTime | 送达时间（DELIVERED 时有值） | | voidReason | String | 作废原因（VOIDED 时有值） | -| email | String | 邮箱（电子发票） | -| mailAddress | String | 邮寄地址（纸质发票） | -| bankName | String | 开户行（专票） | -| bankAccount | String | 开户账号（专票） | -| registAddress | String | 注册地址（专票） | -| registPhone | String | 注册电话（专票） | +| email / mailAddress | String | 邮箱(电子票) / 邮寄地址(纸质) | +| bankName / bankAccount / registAddress / registPhone | String | 专票开户行/账号/注册地址/电话 | -### 接口 6 — ItineraryVO（行程 Tab） +**JSON 示例** +```jsonc +GET /v3/admin/order/1900000000000903/invoices -`hotelGroup`(HotelGroupVO) + `vehicleGroup`(VehicleGroupVO)。〔#3502 已删顶层 `days`，逐天行程走 `/itinerary/full`〕 - -**HotelGroupVO**：`requirement`(HotelRequirementBriefVO) + `assignments`(List\)。 -**VehicleGroupVO**：`requirement`(VehicleRequirementBriefVO) + `assignments`(List\)。 - -**HotelRequirementBriefVO**：`requirementId`、`version`、`status`(PENDING/PROCESSING/DONE)、`submittedAt`、`totalRoomCount`、`roomTypeSummary`(双床房×4)、`specialTags`(List\)、`remark`、`claimerName`(房控接单人)、`days`(List\)。 -- **RequirementDayVO**：`dayNumber`、`stayDate`、`remark`、`hotels`(List\)。 -- **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\{id,name})、`remark`。 - -### 接口 8 — LogTimelineVO（状态时间线 Tab，List） - -`occurredAt`、`operator`、`action`、`fromStatus`、`toStatus`、`amount`(支付/退款时有值)。 - -### 接口 9 — RefundDetailVO（退款 Tab，无退款 data=null） - -`totalRefundAmount` + `applications`(List\)。 -**RefundApplicationVO**：`applicationId`、`status`(枚举见 ⑥)、`statusText`、`refundAmount`、`refundChannel`、`approverName`、`approvedAt`、`estimatedArriveDate`、`actualArriveDate`(未到账 null)、`progress`(List\)、`items`(List\)。 -**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\)、`itinerary`(List\)、`refundNotes`(List\)。 -**NoticeItem**：`title`、`content`、`remark`(可选)、`color`(#RRGGBB 可选)、`contactName`(可选)、`phone`(可选)。 -**DayVO**：`dayNumber`、`dayTitle`、`remark`(恒 null)、`itineraryNode`(List\)。 -**ItineraryNode**：`nodeName`、`description`、`contactName`(恒 null)、`phone`(恒 null)。 -**RefundNoteGroup**：`sourceName`、`intro`、`items`(List\)。 -**RefundItem**：`title`、`amount`(赠送为 0)、`unitLabel`(/人 /团 /辆)、`settleScope`(PER_PERSON/PER_TEAM/PER_VEHICLE)、`settleScopeLabel`(中文)、`remark`、`effectiveFrom`(null=无限制)、`effectiveTo`(null=无限制)。 +{ + "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 -**OrderStatus（粗状态，6 态）**：PENDING_PAY 待支付 / CUSTOMIZING 定制中 / PENDING_DEPARTURE 待出行 / TRAVELLING 出行中 / COMPLETED 已完成 / CANCELLED 已取消。 +**接口地址**：`GET /v3/admin/order/{id}/itinerary` +**接口介绍**：订单配房/配车的需求(requirement) + 实配(assignments)。 +**本次修改点**： +- 删顶层 MOCK `days`（逐天行程改走 `/itinerary/full`，#3502）——破坏性。 +- `hotelGroup`/`vehicleGroup`.requirement **真实化**（#3385/#3493）；assignment 增 `requirementId`。 +- `HotelAssignmentVO`（实配酒店）当前**恒返空**，待 house 域接通，前端按空处理勿报错。 -**OrderFlowStatus（细状态，12 态）**：AWAITING_PAY 待支付 / AWAITING_PROFILE 待补全信息 / RESOURCE_PREPARING 资源准备 / PENDING_CONFIRM 待确认 / PENDING_DEPARTURE 待出行 / TRAVELLING 出行中 / PENDING_REVIEW 待核单 / REVIEWING 核单中 / PENDING_SETTLE 待结算 / SETTLED 已结算 / COMPLETED 已完成 / CANCELLED 已取消。 +**入参**：path `id`（Long，必填）。 -**OrderFlowMainStep（6 主步，progressStepper/flowStepCode）**：PROFILE(1) 补全信息 / RESOURCE(2) 资源准备 / CONFIRM(3) 确认 / DEPART(4) 出行 / REVIEW(5) 核单 / SETTLE(6) 结算。 -> flowStep=0 表示"待支付"（步骤条未开始）；CANCELLED 终态 flowStep=null、flowStepCode=null。 +**出参**：`ItineraryVO` = `hotelGroup` + `vehicleGroup` +- `HotelGroupVO`：`requirement`(HotelRequirementBriefVO) + `assignments`(List\)。 +- `VehicleGroupVO`：`requirement`(VehicleRequirementBriefVO) + `assignments`(List\)。 -**OrderCreateSource**：CONSULTANT 定制师创建（默认/兜底） / CUSTOMER C端客户自下单。 -**OrderMainRefundStatus（main.refundStatus）**：NONE 无退款 / PROCESSING 退款中 / COMPLETED 已完成。 -**payStatus**：UNPAID 未支付 / DEPOSIT_PAID 订金已付 / FULLY_PAID 全款已付。 -**paymentMode**：DEPOSIT 订金模式 / FULL 全款模式。 +`HotelRequirementBriefVO`：`requirementId`、`version`、`status`(PENDING/PROCESSING/DONE)、`submittedAt`、`totalRoomCount`、`roomTypeSummary`、`specialTags`(List\)、`remark`、`claimerName`、`days`(List\)。 +　└ `RequirementDayVO`：`dayNumber`、`stayDate`、`remark`、`hotels`(List\)。 +　　└ `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`。 -**发票 invoiceType**：VAT_NORMAL 增值税普票 / VAT_SPECIAL 增值税专票 / ELECTRONIC 电子普票。 -**发票 status**：APPLIED 已申请 / ISSUED 已开票 / UPLOADED 已上传 / DELIVERED 已送达 / VOIDED 已作废。 -**发票 auditStatus**：PENDING / APPROVED / MANUAL_REVIEW / REJECTED。 -**发票 titleType**：COMPANY 公司 / PERSONAL 个人。 +**JSON 示例** +```jsonc +GET /v3/admin/order/1900000000000903/itinerary -> ⚠️ **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": 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 -| code | message | 触发 | +**接口地址**：`GET /v3/admin/order/{id}/transport-plans` +**接口介绍**：订单大交通（抵达/返程）批次安排，含航班/车次/自驾、接送、关联出行人。 +**本次修改点**：原在详情主接口内，#3385 起拆为独立懒加载接口（字段不变）。无批次返回 `data:[]`。 + +**入参**：path `id`（Long，必填）。 + +**出参**：`List`（每条 17 字段） + +| 字段 | 类型 | 含义 | |---|---|---| -| 200 | 成功 | 正常 | -| 581007 | 订单不存在 | 接口 2~10 传入不存在的订单 ID（订单域段位错误码） | +| 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\ | 关联出行人（{id,name}） | +| remark | String | 备注 | -> 错误以 `Result` 包装，HTTP 状态恒 200，前端判 `success` / `code`。`refund`、`service-standard` 的 `data:null` 是**正常空态**，不是错误。 +**JSON 示例** +```jsonc +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/1900000000000903 -Authorization: Bearer +**接口地址**：`GET /v3/admin/order/{id}/status-log` +**接口介绍**：订单全生命周期状态/操作流水时间线。 +**本次修改点**：无字段变更。无记录返回 `data:[]`。 -{"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} +**入参**：path `id`（Long，必填）。 + +**出参**：`List` + +| 字段 | 类型 | 含义 | +|---|---|---| +| occurredAt | LocalDateTime | 发生时间 | +| operator | String | 操作人 | +| action | String | 操作描述 | +| fromStatus / toStatus | String | 变更前 / 后状态（有状态变更时有值） | +| amount | BigDecimal | 涉及金额（支付/退款时有值） | + +**JSON 示例** +```jsonc +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} + ] +} ``` -**典型（服务标准 Tab，已填充）** +--- + +## 9. 退款明细 Tab + +**接口地址**：`GET /v3/admin/order/{id}/refund` +**接口介绍**：订单退款申请明细（可多笔），含审批/到账进度时间线。 +**本次修改点**：无字段变更。**无退款申请时整节返回 `data:null`**（前端需与"订单不存在 581007"区分）。 + +**入参**：path `id`（Long，必填）。 + +**出参**：`RefundDetailVO` = `totalRefundAmount` + `applications`(List\) +`RefundApplicationVO`：`applicationId`、`status`(附录 B)、`statusText`、`refundAmount`、`refundChannel`、`approverName`、`approvedAt`、`estimatedArriveDate`、`actualArriveDate`(未到账 null)、`progress`(List\)、`items`(List\)。 +`ProgressStepVO`：`step`(APPLY/APPROVE/PAYOUT/ARRIVED)、`label`、`status`(DONE/ACTIVE/PENDING)、`occurredAt`(PENDING 时 null)。 +`RefundItemVO`：`itemName`、`reason`、`appliedAt`、`amount`(负数)。 + +**JSON 示例** +```jsonc +// 空态（无退款） +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\)、`itinerary`(List\)、`refundNotes`(List\)。 +`NoticeItem`：`title`、`content`、`remark`、`color`(#RRGGBB)、`contactName`、`phone`（后 4 项可选）。 +`DayVO`：`dayNumber`、`dayTitle`、`remark`(恒 null)、`itineraryNode`(List\)。 +　└ `ItineraryNode`：`nodeName`、`description`、`contactName`(恒 null)、`phone`(恒 null)。 +`RefundNoteGroup`：`sourceName`、`intro`、`items`(List\)。 +　└ `RefundItem`：`title`、`amount`(赠送为 0)、`unitLabel`(/人 /团 /辆)、`settleScope`(PER_PERSON/PER_TEAM/PER_VEHICLE)、`settleScopeLabel`、`remark`、`effectiveFrom`(null=无限制)、`effectiveTo`(null=无限制)。 + +**JSON 示例**（取自测试服 903 真实返回） +```jsonc 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} +{ + "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 枚举字典 -- 列表 `flowStep`：0=待支付未进入步骤条；1-6=进行中；null=已取消终态。前端步骤条按此渲染。 -- `currentSubFlows` / `progressStepper[].subFlows` 仅在 RESOURCE（资源准备）步非空。 -- overview 出行人 / 联系电话 / 证件号在 admin 端**明文返回**（#3509），前端如需展示脱敏由前端处理；日志侧后端已脱敏。 -- itinerary 的 `HotelAssignmentVO`（实配酒店）当前**恒返空**，待 house 域接通；前端先按空处理，勿报错。 -- 发票 Tab 返回**全部**发票含已作废（VOIDED），前端按 `status` 区分展示。 +- **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 文案口径 | |---|---|---| -| 详情主接口 | 含 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） | +| 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` 展示文案。 --- -## ⑪ 影响评估 / 回滚 +## 关联 / 联系人 -- **影响面**：管理后台订单详情页全部 Tab + 订单列表页。前端需按本文更新字段映射，重点处理：overview 两分类结构、出行人明文、itinerary 删 days、finance 删 surchargeType、新增发票 Tab。 -- **兼容性**：删除字段（surchargeType、itinerary.days）为**破坏性**，前端引用处需同步删除/改造，否则取值为 undefined。 -- **回滚**：各变更已分别 PR 合入 dev-v3，回滚以对应 PR revert 为准；前端可保留旧字段读取的容错（取不到按空处理）平滑过渡。 - ---- - -## ⑫ 注意事项 - -1. 所有 Long ID（含 transportPlanIds 元素、travelers.id）按**字符串**接收。 -2. `contractStatus`/`insuranceStatus`/`refund status` 三处枚举**按字符串容错 + 配合 statusText 展示**，勿硬编码全集。 -3. `refund` / `service-standard` 的 `data:null` 是正常空态，需与"订单不存在(581007)"区分。 -4. 其余 Tab 空态返回空列表 `[]` 或空对象，非 null。 -5. 时间 `yyyy-MM-dd HH:mm:ss`，日期 `yyyy-MM-dd`。 - ---- - -## ⑬ 关联 / 联系人 - -- 相关 Issue：[#3517](https://git.1814.love:8443/wx/HL/issues/3517)（发票 Tab）、[#3514](https://git.1814.love:8443/wx/HL/issues/3514)（合同保险真实化）、[#3509](https://git.1814.love:8443/wx/HL/issues/3509)（出行人明文）、[#3502](https://git.1814.love:8443/wx/HL/issues/3502)、[#3500](https://git.1814.love:8443/wx/HL/issues/3500)、[#3493](https://git.1814.love:8443/wx/HL/issues/3493)、[#3488](https://git.1814.love:8443/wx/HL/issues/3488)、[#3385](https://git.1814.love:8443/wx/HL/issues/3385)、[#3340](https://git.1814.love:8443/wx/HL/issues/3340)、[#3523](https://git.1814.love:8443/wx/HL/issues/3523) -- 相关 PR：[#3521](https://git.1814.love:8443/wx/HL/pulls/3521)、[#3524](https://git.1814.love:8443/wx/HL/pulls/3524)、[#3510](https://git.1814.love:8443/wx/HL/pulls/3510)、[#3388](https://git.1814.love:8443/wx/HL/pulls/3388) -- 基线 commit：`f95757df7` -- 后端负责人：腰苏图（订单 v3） +- Issue：[#3517](https://git.1814.love:8443/wx/HL/issues/3517) [#3514](https://git.1814.love:8443/wx/HL/issues/3514) [#3509](https://git.1814.love:8443/wx/HL/issues/3509) [#3502](https://git.1814.love:8443/wx/HL/issues/3502) [#3500](https://git.1814.love:8443/wx/HL/issues/3500) [#3493](https://git.1814.love:8443/wx/HL/issues/3493) [#3488](https://git.1814.love:8443/wx/HL/issues/3488) [#3385](https://git.1814.love:8443/wx/HL/issues/3385) [#3340](https://git.1814.love:8443/wx/HL/issues/3340) [#3523](https://git.1814.love:8443/wx/HL/issues/3523) +- PR：[#3521](https://git.1814.love:8443/wx/HL/pulls/3521) [#3524](https://git.1814.love:8443/wx/HL/pulls/3524) [#3510](https://git.1814.love:8443/wx/HL/pulls/3510) [#3388](https://git.1814.love:8443/wx/HL/pulls/3388) +- 基线 commit：`f95757df7` ｜ 后端负责人：腰苏图（订单 v3） From a0946839d89b2b468b3635d996fef43f4342d96f Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Fri, 5 Jun 2026 17:04:29 +0800 Subject: [PATCH 3/4] =?UTF-8?q?docs(changelog):=20=E8=AE=A2=E5=8D=95?= =?UTF-8?q?=E6=8E=A5=E5=8F=A3=E5=A5=91=E7=BA=A6=E6=B8=85=E5=8D=95=E5=85=A8?= =?UTF-8?q?=E6=96=87=E8=A1=A8=E6=A0=BC=E5=8C=96(=E7=AE=A1=E7=90=86?= =?UTF-8?q?=E5=90=8E=E5=8F=B0)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 格式统一: 所有嵌套 VO 子类(SubFlowVO/TravelerPlainVO/ServiceStandardVO 子结构等 20+)由行内顿号改为 字段|类型|含义 三列表格; 每个接口补入参示例; 附录A枚举字典改表格展示。 --- ...与详情懒加载接口契约清单-修改接口-管理后台.md | 723 +++++++++++++++--- 1 file changed, 599 insertions(+), 124 deletions(-) diff --git a/changelogs-v2/2026-06/05_订单列表与详情懒加载接口契约清单-修改接口-管理后台.md b/changelogs-v2/2026-06/05_订单列表与详情懒加载接口契约清单-修改接口-管理后台.md index e42c4d5..3815f8a 100644 --- a/changelogs-v2/2026-06/05_订单列表与详情懒加载接口契约清单-修改接口-管理后台.md +++ b/changelogs-v2/2026-06/05_订单列表与详情懒加载接口契约清单-修改接口-管理后台.md @@ -36,7 +36,7 @@ **接口介绍**：管理后台订单列表，支持状态/标签/关键字/出发日期/来源/定制师等多条件过滤，分页返回。 **本次修改点**：无字段变更（沿用现状，列表项含 6 步 flowStep 步骤条字段）。 -**入参**（query） +**入参**（query 参数） | 字段 | 类型 | 必填 | 含义 | 示例 | |---|---|---|---|---| @@ -52,7 +52,14 @@ | cancelled | Boolean | 否 | 是否含已取消（默认 false） | false | | consultantName | String | 否 | 定制师姓名 LIKE | 李定制 | -**出参**：`PageResult`，外层 `records`（数组）+ `total`/`current`/`size` 等分页字段。单条 `OrderListItemRespVO`（35 字段）： +**入参示例** +``` +GET /v3/admin/order?page=1&pageSize=10&orderStatus=CUSTOMIZING&keyword=张三 +``` + +**出参**：`PageResult`，外层 `records`（数组）+ `total`/`current`/`size` 分页字段。 + +单条 `OrderListItemRespVO`（35 字段）： | 字段 | 类型 | 含义 | |---|---|---| @@ -68,30 +75,50 @@ | peopleSummary | String | 人数摘要 | | departureDate | LocalDate | 出发日（未定 null） | | tripDays | Integer | 行程天数 | -| orderStatus / orderStatusName | String | 粗状态值 / 中文（附录 A） | -| flowStatus / flowStatusName | String | 细状态值 / 中文（附录 A） | +| 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\ | 当前步子流程（仅 RESOURCE 步非 null） | -| totalAmount / paidAmount / balanceAmount | BigDecimal | 金额 / 实付 / 待付 | +| totalAmount | BigDecimal | 订单金额 | +| paidAmount | BigDecimal | 实付金额 | +| balanceAmount | BigDecimal | 待付金额 | | consultantName | String | 定制师姓名 | -| createSource / createSourceLabel | String | 来源值 / 中文 | +| createSource | String | 来源值（附录 A） | +| createSourceLabel | String | 来源中文 | | tags | List\ | 标签列表 | | createdAt | LocalDateTime | 创单时间 | -| depositAmount / depositRatio | BigDecimal/Integer | 订金额 / 比例%（FULL 为 null） | +| depositAmount | BigDecimal | 订金额（FULL 为 null） | +| depositRatio | Integer | 订金比例%（FULL 为 null） | | paymentMode | String | DEPOSIT/FULL | | singleRoomSurcharge | BigDecimal | 单房差（未触发 null） | -| agencyId / refundPolicyId | String | 旅行社 / 退款政策 ID | +| 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`。 +`SubFlowVO`（子流程） -**JSON 示例** +| 字段 | 类型 | 含义 | +|---|---|---| +| 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 | 标签创建人姓名 | + +**出参示例** ```jsonc -GET /v3/admin/order?page=1&pageSize=10&orderStatus=CUSTOMIZING - { "code": 200, "message": "成功", "success": true, "data": { @@ -130,51 +157,146 @@ GET /v3/admin/order?page=1&pageSize=10&orderStatus=CUSTOMIZING - `overview` **重构**为 `customerInfo` + `remarkInfo` 两分类（原扁平字段，#3488）。 - overview 出行人/联系电话/证件号改**明文**返回（idCard/phone/emergencyPhone 不脱敏，#3509）。 -**入参**：path `id`（Long，必填）。 +**入参** -**出参**：`OrderDetailRespVO` = `main`(OrderMainVO) + `tags`(List\) + `overview`(OverviewVO)。 +| 字段 | 位置 | 类型 | 必填 | 含义 | +|---|---|---|---|---| +| id | path | Long | 是 | 订单 ID | -`main`（OrderMainVO，47 字段）核心： +**入参示例** +``` +GET /v3/admin/order/1900000000000903 +``` + +**出参**：`OrderDetailRespVO` | 字段 | 类型 | 含义 | |---|---|---| -| 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) | +| main | OrderMainVO | 主单 + Tab 状态徽标 + 进度管道 | +| tags | List\ | 标签区（结构同 §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 / flowStepStatus | String | 当前步英文码 / 状态(PROCESSING) | -| totalAmount / paidAmount / balanceAmount | BigDecimal | 金额 / 实付 / 待付 | -| departureDate / returnDate | LocalDate | 出发 / 返回日期 | -| tripDays / tripNights | Integer | 行程天 / 夜数 | -| createSource / createSourceLabel | String | 来源值 / 中文 | +| 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\ | 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 | +| 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 / refundPolicyId | String | 旅行社 / 退款政策 ID | +| agencyId | String | 旅行社主体 ID | +| 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)。 +`PipelineNodeVO`（进度节点） -`overview`（OverviewVO）= `customerInfo` + `remarkInfo`： -- **CustomerInfoVO**：`contactName`、`contactPhone`(**明文**)、`agencyName`、`consultantName`、`peopleSummary`、`adultCount`、`childCount`、`youngChildCount`、`babyCount`、`createTime`、`emergencyContactName`、`emergencyContactPhone`(**明文**)、`travelers`(List\)。 -- **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\)。 -- **RemarkInfoVO**：`customerRemark`(只读)、`consultantRemark`、`hotelRemark`(无需求 null)、`vehicleRemark`(无需求 null)。 +| 字段 | 类型 | 含义 | +|---|---|---| +| 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\ | 子流程（仅 RESOURCE 节点非 null，结构同 §1） | -**JSON 示例** +`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`（出行人，明文 #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\ | 关联大交通批次 ID 列表 | + +`RemarkInfoVO`（备注） + +| 字段 | 类型 | 含义 | +|---|---|---| +| customerRemark | String | 用户备注（只读） | +| consultantRemark | String | 定制师备注 | +| hotelRemark | String | 用房备注（无需求 null） | +| vehicleRemark | String | 用车备注（无需求 null） | + +**出参示例** ```jsonc -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": "标准档", + "productSubtitle": "私家小团·专车专导", "orderStatus": "CUSTOMIZING", "orderStatusName": "定制中", "flowStatus": "RESOURCE_PREPARING", "flowStatusName": "资源准备", "flowStep": 2, "flowStepTotal": 6, "flowDisplayText": "资源准备", @@ -190,8 +312,7 @@ GET /v3/admin/order/1900000000000903 "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": "私家小团·专车专导" + "singleRoomSurcharge": null, "agencyId": "8000000000000001", "refundPolicyId": "7000000000000001" }, "tags": [], "overview": { @@ -225,26 +346,64 @@ GET /v3/admin/order/1900000000000903 **接口介绍**：订单财务明细，含金额汇总、支付/优惠/附加费三类明细列表。 **本次修改点**：`SurchargeVO` **删除 `surchargeType` 字段**（恒 null 无数据源，#3523）——破坏性，前端引用处需移除。 -**入参**：path `id`（Long，必填）。 +**入参** + +| 字段 | 位置 | 类型 | 必填 | 含义 | +|---|---|---|---|---| +| id | path | Long | 是 | 订单 ID | + +**入参示例** +``` +GET /v3/admin/order/1900000000000903/finance +``` **出参**：`FinanceVO` | 字段 | 类型 | 含义 | |---|---|---| -| totalAmount / paidAmount / balanceAmount | BigDecimal | 总额 / 实付 / 待付 | -| discountAmount / surchargeAmount / refundAmount | BigDecimal | 优惠 / 附加费 / 退款 汇总 | +| totalAmount | BigDecimal | 订单总额 | +| paidAmount | BigDecimal | 实付金额 | +| balanceAmount | BigDecimal | 待付金额 | +| discountAmount | BigDecimal | 优惠金额汇总 | +| surchargeAmount | BigDecimal | 附加费汇总 | +| refundAmount | BigDecimal | 退款金额汇总 | | payments | List\ | 支付明细 | | discounts | List\ | 优惠明细 | | surcharges | List\ | 附加费用 | -`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`〕 +`PaymentVO` -**JSON 示例** +| 字段 | 类型 | 含义 | +|---|---|---| +| 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 | 创建时间 | + +**出参示例** ```jsonc -GET /v3/admin/order/1900000000000903/finance - { "code": 200, "message": "成功", "success": true, "data": { @@ -272,17 +431,51 @@ GET /v3/admin/order/1900000000000903/finance **接口介绍**：订单合同与保险状态 + 事件时间线。 **本次修改点**：`events` **真实化**——来自 status_log / insurance_status_log，不再恒空（#3514）。 -**入参**：path `id`（Long，必填）。 +**入参** -**出参**：`ContractInsuranceVO` = `contract` + `insurance` -- `ContractVO`：`contractStatus`(附录 B)、`contractSignedAt`、`contractFileUrl`、`events`(List\)。 -- `InsuranceVO`：`insuranceStatus`(附录 B)、`insurancePolicyNo`、`insurancePremium`、`events`(List\)。 -- `EventVO`：`eventType`(GENERATE/SIGN/ISSUE/…)、`occurredAt`。 +| 字段 | 位置 | 类型 | 必填 | 含义 | +|---|---|---|---|---| +| id | path | Long | 是 | 订单 ID | -**JSON 示例** -```jsonc +**入参示例** +``` GET /v3/admin/order/1900000000000903/contract-insurance +``` +**出参**：`ContractInsuranceVO` + +| 字段 | 类型 | 含义 | +|---|---|---| +| contract | ContractVO | 合同子对象 | +| insurance | InsuranceVO | 保险子对象 | + +`ContractVO` + +| 字段 | 类型 | 含义 | +|---|---|---| +| contractStatus | String | 合同状态（附录 B） | +| contractSignedAt | LocalDateTime | 签约时间 | +| contractFileUrl | String | 合同文件 URL | +| events | List\ | 合同事件时间线 | + +`InsuranceVO` + +| 字段 | 类型 | 含义 | +|---|---|---| +| insuranceStatus | String | 保险状态（附录 B） | +| insurancePolicyNo | String | 保单号 | +| insurancePremium | BigDecimal | 保费 | +| events | List\ | 保险事件时间线 | + +`EventVO` + +| 字段 | 类型 | 含义 | +|---|---|---| +| eventType | String | 事件类型 GENERATE/SIGN/ISSUE/… | +| occurredAt | LocalDateTime | 发生时间 | + +**出参示例** +```jsonc { "code": 200, "message": "成功", "success": true, "data": { @@ -311,31 +504,48 @@ GET /v3/admin/order/1900000000000903/contract-insurance **接口介绍**：返回该订单**全部**发票（含已作废 VOIDED），按 applyAt 倒序。 **本次修改点**：**新增接口**（#3517 / #3521）。无发票返回 `data:[]`。 -**入参**：path `id`（Long，必填）。 +**入参** + +| 字段 | 位置 | 类型 | 必填 | 含义 | +|---|---|---|---|---| +| id | path | Long | 是 | 订单 ID | + +**入参示例** +``` +GET /v3/admin/order/1900000000000903/invoices +``` **出参**：`List`（每条 23 字段） | 字段 | 类型 | 含义 | |---|---|---| -| id / orderId | String | 发票 ID / 订单 ID | -| invoiceType / invoiceTypeText | String | 类型值(附录 A) / 文案 | -| titleType / titleName | String | 抬头类型(COMPANY/PERSONAL) / 名称 | +| id | String | 发票 ID | +| orderId | String | 订单 ID | +| invoiceType | String | 类型值（附录 A） | +| invoiceTypeText | String | 类型文案 | +| titleType | String | 抬头类型 COMPANY/PERSONAL | +| titleName | String | 抬头名称 | | taxNo | String | 税号（公司抬头/专票必填） | | amount | BigDecimal | 开票金额（元） | -| status / statusText | String | 状态值(附录 A) / 文案 | -| auditStatus | String | 内容安全机审(PENDING/APPROVED/MANUAL_REVIEW/REJECTED) | -| applyReason / applyAt | String/LocalDateTime | 申请说明 / 申请时间 | +| status | String | 状态值（附录 A） | +| statusText | String | 状态文案 | +| auditStatus | String | 机审 PENDING/APPROVED/MANUAL_REVIEW/REJECTED | +| applyReason | String | 申请说明 | +| applyAt | LocalDateTime | 申请时间 | | fileUrl | String | 发票文件 OSS 链接（UPLOADED 后有值） | -| uploader / uploadedAt | String/LocalDateTime | 上传人 / 上传时间 | +| uploader | String | 上传人 | +| uploadedAt | LocalDateTime | 上传时间 | | deliveredAt | LocalDateTime | 送达时间（DELIVERED 时有值） | | voidReason | String | 作废原因（VOIDED 时有值） | -| email / mailAddress | String | 邮箱(电子票) / 邮寄地址(纸质) | -| bankName / bankAccount / registAddress / registPhone | String | 专票开户行/账号/注册地址/电话 | +| email | String | 邮箱（电子发票） | +| mailAddress | String | 邮寄地址（纸质发票） | +| bankName | String | 开户行（专票） | +| bankAccount | String | 开户账号（专票） | +| registAddress | String | 注册地址（专票） | +| registPhone | String | 注册电话（专票） | -**JSON 示例** +**出参示例** ```jsonc -GET /v3/admin/order/1900000000000903/invoices - { "code": 200, "message": "成功", "success": true, "data": [{ @@ -362,23 +572,104 @@ GET /v3/admin/order/1900000000000903/invoices - `hotelGroup`/`vehicleGroup`.requirement **真实化**（#3385/#3493）；assignment 增 `requirementId`。 - `HotelAssignmentVO`（实配酒店）当前**恒返空**，待 house 域接通，前端按空处理勿报错。 -**入参**：path `id`（Long，必填）。 +**入参** -**出参**：`ItineraryVO` = `hotelGroup` + `vehicleGroup` -- `HotelGroupVO`：`requirement`(HotelRequirementBriefVO) + `assignments`(List\)。 -- `VehicleGroupVO`：`requirement`(VehicleRequirementBriefVO) + `assignments`(List\)。 +| 字段 | 位置 | 类型 | 必填 | 含义 | +|---|---|---|---|---| +| id | path | Long | 是 | 订单 ID | -`HotelRequirementBriefVO`：`requirementId`、`version`、`status`(PENDING/PROCESSING/DONE)、`submittedAt`、`totalRoomCount`、`roomTypeSummary`、`specialTags`(List\)、`remark`、`claimerName`、`days`(List\)。 -　└ `RequirementDayVO`：`dayNumber`、`stayDate`、`remark`、`hotels`(List\)。 -　　└ `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 示例** -```jsonc +**入参示例** +``` GET /v3/admin/order/1900000000000903/itinerary +``` +**出参**：`ItineraryVO` + +| 字段 | 类型 | 含义 | +|---|---|---| +| hotelGroup | HotelGroupVO | 配房需求 + 实配 | +| vehicleGroup | VehicleGroupVO | 配车需求 + 实配 | + +`HotelGroupVO` = `requirement`(HotelRequirementBriefVO) + `assignments`(List\) +`VehicleGroupVO` = `requirement`(VehicleRequirementBriefVO) + `assignments`(List\) + +`HotelRequirementBriefVO`（配房需求） + +| 字段 | 类型 | 含义 | +|---|---|---| +| requirementId | String | 需求 ID | +| version | Integer | 版本号 | +| status | String | PENDING/PROCESSING/DONE | +| submittedAt | LocalDateTime | 提交时间 | +| totalRoomCount | Integer | 合计间数 | +| roomTypeSummary | String | 房型摘要（双床房×4 / 大床房×2） | +| specialTags | List\ | 特殊诉求标签 | +| remark | String | 备注 | +| claimerName | String | 房控接单人姓名 | +| days | List\ | 按天结构化需求 | + +`RequirementDayVO`（按天需求） + +| 字段 | 类型 | 含义 | +|---|---|---| +| dayNumber | Integer | 第几天 | +| stayDate | LocalDate | 入住日（派生） | +| remark | String | 当天备注 | +| hotels | List\ | 当天房型明细 | + +`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\ | 特殊诉求标签 | +| remark | String | 备注 | + +`VehicleAssignmentVO`（实配车辆） + +| 字段 | 类型 | 含义 | +|---|---|---| +| assignmentId | String | 实配 ID | +| vehicleType | String | 车型 | +| vehicleCount | Integer | 车辆数 | +| licensePlate | String | 车牌 | +| brand | String | 品牌 | +| seats | Integer | 座位数 | +| plannedDailyFee | BigDecimal | 计划日单价 | +| driverName | String | 司机姓名 | +| driverPhoneMasked | String | 司机手机（脱敏） | +| remark | String | 备注 | + +**出参示例** +```jsonc { "code": 200, "message": "成功", "success": true, "data": { @@ -419,28 +710,48 @@ GET /v3/admin/order/1900000000000903/itinerary **接口介绍**：订单大交通（抵达/返程）批次安排，含航班/车次/自驾、接送、关联出行人。 **本次修改点**：原在详情主接口内，#3385 起拆为独立懒加载接口（字段不变）。无批次返回 `data:[]`。 -**入参**：path `id`（Long，必填）。 +**入参** + +| 字段 | 位置 | 类型 | 必填 | 含义 | +|---|---|---|---|---| +| id | path | Long | 是 | 订单 ID | + +**入参示例** +``` +GET /v3/admin/order/1900000000000903/transport-plans +``` **出参**：`List`（每条 17 字段） | 字段 | 类型 | 含义 | |---|---|---| -| id / orderId | String | 批次 ID / 订单 ID | +| id | String | 批次 ID | +| orderId | String | 订单 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\ | 关联出行人（{id,name}） | +| 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\ | 关联出行人 | | remark | String | 备注 | -**JSON 示例** -```jsonc -GET /v3/admin/order/1900000000000903/transport-plans +`TravelerRef`（关联出行人） +| 字段 | 类型 | 含义 | +|---|---|---| +| id | String | 出行人 ID | +| name | String | 出行人姓名 | + +**出参示例** +```jsonc { "code": 200, "message": "成功", "success": true, "data": [{ @@ -464,7 +775,16 @@ GET /v3/admin/order/1900000000000903/transport-plans **接口介绍**：订单全生命周期状态/操作流水时间线。 **本次修改点**：无字段变更。无记录返回 `data:[]`。 -**入参**：path `id`（Long，必填）。 +**入参** + +| 字段 | 位置 | 类型 | 必填 | 含义 | +|---|---|---|---|---| +| id | path | Long | 是 | 订单 ID | + +**入参示例** +``` +GET /v3/admin/order/1900000000000903/status-log +``` **出参**：`List` @@ -473,13 +793,12 @@ GET /v3/admin/order/1900000000000903/transport-plans | occurredAt | LocalDateTime | 发生时间 | | operator | String | 操作人 | | action | String | 操作描述 | -| fromStatus / toStatus | String | 变更前 / 后状态（有状态变更时有值） | +| fromStatus | String | 变更前状态（有状态变更时有值） | +| toStatus | String | 变更后状态（有状态变更时有值） | | amount | BigDecimal | 涉及金额（支付/退款时有值） | -**JSON 示例** +**出参示例** ```jsonc -GET /v3/admin/order/1900000000000903/status-log - { "code": 200, "message": "成功", "success": true, "data": [ @@ -497,17 +816,61 @@ GET /v3/admin/order/1900000000000903/status-log **接口介绍**：订单退款申请明细（可多笔），含审批/到账进度时间线。 **本次修改点**：无字段变更。**无退款申请时整节返回 `data:null`**（前端需与"订单不存在 581007"区分）。 -**入参**：path `id`（Long，必填）。 +**入参** -**出参**：`RefundDetailVO` = `totalRefundAmount` + `applications`(List\) -`RefundApplicationVO`：`applicationId`、`status`(附录 B)、`statusText`、`refundAmount`、`refundChannel`、`approverName`、`approvedAt`、`estimatedArriveDate`、`actualArriveDate`(未到账 null)、`progress`(List\)、`items`(List\)。 -`ProgressStepVO`：`step`(APPLY/APPROVE/PAYOUT/ARRIVED)、`label`、`status`(DONE/ACTIVE/PENDING)、`occurredAt`(PENDING 时 null)。 -`RefundItemVO`：`itemName`、`reason`、`appliedAt`、`amount`(负数)。 +| 字段 | 位置 | 类型 | 必填 | 含义 | +|---|---|---|---|---| +| id | path | Long | 是 | 订单 ID | -**JSON 示例** +**入参示例** +``` +GET /v3/admin/order/1900000000000903/refund +``` + +**出参**：`RefundDetailVO` + +| 字段 | 类型 | 含义 | +|---|---|---| +| totalRefundAmount | BigDecimal | 合计退款金额 | +| applications | List\ | 多笔退款申请 | + +`RefundApplicationVO` + +| 字段 | 类型 | 含义 | +|---|---|---| +| applicationId | String | 申请 ID | +| status | String | 状态（附录 B） | +| statusText | String | 状态描述文案 | +| refundAmount | BigDecimal | 退款金额 | +| refundChannel | String | 退款渠道 | +| approverName | String | 审批人 | +| approvedAt | LocalDateTime | 审批时间 | +| estimatedArriveDate | LocalDate | 预计到账日期 | +| actualArriveDate | LocalDate | 实际到账日期（未到账 null） | +| progress | List\ | 4 步进度时间线 | +| items | List\ | 退款明细行 | + +`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 | 退款金额（负数） | + +**出参示例** ```jsonc // 空态（无退款） -GET /v3/admin/order/1900000000000903/refund {"code": 200, "message": "成功", "success": true, "data": null} // 有退款 @@ -539,19 +902,80 @@ GET /v3/admin/order/1900000000000903/refund **接口介绍**：订单服务标准（出团承诺 + 逐天行程 + 退费说明），数据源为产品侧预置并冻入订单快照的成品。 **本次修改点**：**重构为一站式聚合**（#3340/#3351）——原 itinerary/notice/refundPolicy/serviceStandard/dayTips 五字段全部替换为本套 ServiceStandardVO 结构；读快照预置成品。**产品快照缺失时返回 `data:null`**。 -**入参**：path `id`（Long，必填）。 +**入参** -**出参**：`ServiceStandardVO`：`title`、`subtitle`、`intro`(无结构 null)、`notices`(List\)、`itinerary`(List\)、`refundNotes`(List\)。 -`NoticeItem`：`title`、`content`、`remark`、`color`(#RRGGBB)、`contactName`、`phone`（后 4 项可选）。 -`DayVO`：`dayNumber`、`dayTitle`、`remark`(恒 null)、`itineraryNode`(List\)。 -　└ `ItineraryNode`：`nodeName`、`description`、`contactName`(恒 null)、`phone`(恒 null)。 -`RefundNoteGroup`：`sourceName`、`intro`、`items`(List\)。 -　└ `RefundItem`：`title`、`amount`(赠送为 0)、`unitLabel`(/人 /团 /辆)、`settleScope`(PER_PERSON/PER_TEAM/PER_VEHICLE)、`settleScopeLabel`、`remark`、`effectiveFrom`(null=无限制)、`effectiveTo`(null=无限制)。 +| 字段 | 位置 | 类型 | 必填 | 含义 | +|---|---|---|---|---| +| id | path | Long | 是 | 订单 ID | -**JSON 示例**（取自测试服 903 真实返回） -```jsonc +**入参示例** +``` GET /v3/admin/order/1900000000000903/service-standard +``` +**出参**：`ServiceStandardVO` + +| 字段 | 类型 | 含义 | +|---|---|---| +| title | String | 标题（"出团服务标准·"+产品名；name 空时退化为"出团服务标准"） | +| subtitle | String | 副标题（固定常量） | +| intro | String | 服务标准简介（无结构 null） | +| notices | List\ | 服务承诺条目扁平列表（无结构空列表） | +| itinerary | List\ | 行程逐天列表 | +| refundNotes | List\ | 退费说明聚合列表（无退费说明空列表） | + +`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`（行程点位） + +| 字段 | 类型 | 含义 | +|---|---|---| +| nodeName | String | 点位名称 | +| description | String | 点位描述 | +| contactName | String | 联系人（占位，恒 null） | +| phone | String | 手机号（占位，恒 null） | + +`RefundNoteGroup`（退费说明分组） + +| 字段 | 类型 | 含义 | +|---|---|---| +| sourceName | String | 来源点位名称 | +| intro | String | 退费说明备注 | +| items | List\ | 退费明细列表 | + +`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 真实返回） +```jsonc { "code": 200, "message": "成功", "success": true, "data": { @@ -586,15 +1010,65 @@ GET /v3/admin/order/1900000000000903/service-standard ## 附录 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 已作废 +### 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） @@ -613,3 +1087,4 @@ GET /v3/admin/order/1900000000000903/service-standard - Issue：[#3517](https://git.1814.love:8443/wx/HL/issues/3517) [#3514](https://git.1814.love:8443/wx/HL/issues/3514) [#3509](https://git.1814.love:8443/wx/HL/issues/3509) [#3502](https://git.1814.love:8443/wx/HL/issues/3502) [#3500](https://git.1814.love:8443/wx/HL/issues/3500) [#3493](https://git.1814.love:8443/wx/HL/issues/3493) [#3488](https://git.1814.love:8443/wx/HL/issues/3488) [#3385](https://git.1814.love:8443/wx/HL/issues/3385) [#3340](https://git.1814.love:8443/wx/HL/issues/3340) [#3523](https://git.1814.love:8443/wx/HL/issues/3523) - PR：[#3521](https://git.1814.love:8443/wx/HL/pulls/3521) [#3524](https://git.1814.love:8443/wx/HL/pulls/3524) [#3510](https://git.1814.love:8443/wx/HL/pulls/3510) [#3388](https://git.1814.love:8443/wx/HL/pulls/3388) - 基线 commit：`f95757df7` ｜ 后端负责人：腰苏图（订单 v3） +``` From f38c79e15012de979dfde6d4ed95f33ccb4cf509 Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Fri, 5 Jun 2026 17:08:12 +0800 Subject: [PATCH 4/4] =?UTF-8?q?docs(changelog):=20=E8=A1=8C=E7=A8=8BTab?= =?UTF-8?q?=E8=A1=A5=20HotelGroupVO/VehicleGroupVO=20=E4=B8=AD=E9=97=B4?= =?UTF-8?q?=E5=B1=82=E8=A1=A8=E6=A0=BC(=E7=AE=A1=E7=90=86=E5=90=8E?= =?UTF-8?q?=E5=8F=B0)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 补齐遗漏: 配房组/配车组两个中间层对象由行内 = a + b 写法改为字段表格，全文对象结构表格化一致。 --- ...表与详情懒加载接口契约清单-修改接口-管理后台.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/changelogs-v2/2026-06/05_订单列表与详情懒加载接口契约清单-修改接口-管理后台.md b/changelogs-v2/2026-06/05_订单列表与详情懒加载接口契约清单-修改接口-管理后台.md index 3815f8a..cc65230 100644 --- a/changelogs-v2/2026-06/05_订单列表与详情懒加载接口契约清单-修改接口-管理后台.md +++ b/changelogs-v2/2026-06/05_订单列表与详情懒加载接口契约清单-修改接口-管理后台.md @@ -590,8 +590,19 @@ GET /v3/admin/order/1900000000000903/itinerary | hotelGroup | HotelGroupVO | 配房需求 + 实配 | | vehicleGroup | VehicleGroupVO | 配车需求 + 实配 | -`HotelGroupVO` = `requirement`(HotelRequirementBriefVO) + `assignments`(List\) -`VehicleGroupVO` = `requirement`(VehicleRequirementBriefVO) + `assignments`(List\) +`HotelGroupVO`（配房组） + +| 字段 | 类型 | 含义 | +|---|---|---| +| requirement | HotelRequirementBriefVO | 配房需求（客户/定制师提交的用房要求） | +| assignments | List\ | 实配酒店列表（当前恒空，待 house 域接通） | + +`VehicleGroupVO`（配车组） + +| 字段 | 类型 | 含义 | +|---|---|---| +| requirement | VehicleRequirementBriefVO | 配车需求（客户/定制师提交的用车要求） | +| assignments | List\ | 实配车辆列表（实际派车 + 司机） | `HotelRequirementBriefVO`（配房需求）