1102 行
42 KiB
Markdown
1102 行
42 KiB
Markdown
# 订单列表 + 订单详情 + 懒加载 Tab 接口契约清单（管理后台）
|
||
|
||
> 端类型：**管理后台**（v3）｜变更类型：**修改接口**（多 PR 累积契约整理 + 1 个新增 Tab）
|
||
> 服务：hl-order-service-v3 ｜ Controller 前缀：`/v3/admin/order` ｜ 基线 commit：`f95757df7`｜日期：2026-06-05
|
||
|
||
## 通用约定
|
||
|
||
- 响应包装 `Result<T>`（`code=200` 成功）；列表为 `PageResult<T>`；HTTP 状态恒 200，前端判 `code`/`success`。
|
||
- 所有 Long 主键序列化为**字符串**（防 JS 精度丢失），前端按 string 接收。
|
||
- 鉴权：`Authorization: Bearer <token>`。时间 `yyyy-MM-dd HH:mm:ss`，日期 `yyyy-MM-dd`。
|
||
- 错误码：`581007 订单不存在`（接口 2~10 传入不存在订单 ID 时返回）。
|
||
- 枚举字段统一见文末 **附录 A 枚举字典**；3 处枚举口径差异见 **附录 B**（务必按字符串容错）。
|
||
|
||
## 接口总览
|
||
|
||
| # | 接口 | 地址 | 本次 |
|
||
|---|---|---|---|
|
||
| 1 | 订单列表 | `GET /v3/admin/order` | 无字段变更 |
|
||
| 2 | 订单详情（主） | `GET /v3/admin/order/{id}` | overview 重构 + 出行人明文 + 主接口瘦身 |
|
||
| 3 | 财务 Tab | `GET /v3/admin/order/{id}/finance` | 删 surchargeType |
|
||
| 4 | 合同保险 Tab | `GET /v3/admin/order/{id}/contract-insurance` | events 真实化 |
|
||
| 5 | 发票 Tab | `GET /v3/admin/order/{id}/invoices` | **新增接口** |
|
||
| 6 | 行程 Tab | `GET /v3/admin/order/{id}/itinerary` | 删 days + requirement 真实化 |
|
||
| 7 | 大交通 Tab | `GET /v3/admin/order/{id}/transport-plans` | 主接口移出转懒加载 |
|
||
| 8 | 状态时间线 Tab | `GET /v3/admin/order/{id}/status-log` | 无字段变更 |
|
||
| 9 | 退款 Tab | `GET /v3/admin/order/{id}/refund` | 无字段变更 |
|
||
| 10 | 服务标准 Tab | `GET /v3/admin/order/{id}/service-standard` | 重构一站式聚合 |
|
||
|
||
> 懒加载 Tab = #3~#10 共 8 个：进入详情页先调 #2 拿头部 + 状态徽标，各 Tab 点开时再各自拉取。
|
||
|
||
---
|
||
|
||
## 1. 订单列表
|
||
|
||
**接口地址**：`GET /v3/admin/order`
|
||
**接口介绍**：管理后台订单列表，支持状态/标签/关键字/出发日期/来源/定制师等多条件过滤，分页返回。
|
||
**本次修改点**：无字段变更（沿用现状，列表项含 6 步 flowStep 步骤条字段）。
|
||
|
||
**入参**（query 参数）
|
||
|
||
| 字段 | 类型 | 必填 | 含义 | 示例 |
|
||
|---|---|---|---|---|
|
||
| page | Integer | 否 | 页码（默认 1） | 1 |
|
||
| pageSize | Integer | 否 | 每页条数（默认 10） | 10 |
|
||
| orderStatus | String | 否 | 粗状态过滤（多值逗号分隔） | CUSTOMIZING |
|
||
| flowStatus | String | 否 | 细状态过滤 | RESOURCE_PREPARING |
|
||
| tagNames | List\<String\> | 否 | 标签过滤（多标签 AND） | ["二次复购"] |
|
||
| keyword | String | 否 | 团号/客户名/产品名/订单号 LIKE | 张三 |
|
||
| departureDateFrom | LocalDate | 否 | 出发日期范围起始 | 2026-06-01 |
|
||
| departureDateTo | LocalDate | 否 | 出发日期范围结束 | 2026-06-30 |
|
||
| createSource | String | 否 | 来源过滤 | CONSULTANT |
|
||
| cancelled | Boolean | 否 | 是否含已取消（默认 false） | false |
|
||
| consultantName | String | 否 | 定制师姓名 LIKE | 李定制 |
|
||
|
||
**入参示例**
|
||
```
|
||
GET /v3/admin/order?page=1&pageSize=10&orderStatus=CUSTOMIZING&keyword=张三
|
||
```
|
||
|
||
**出参**：`PageResult<OrderListItemRespVO>`，外层 `records`（数组）+ `total`/`current`/`size` 分页字段。
|
||
|
||
单条 `OrderListItemRespVO`（35 字段）：
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| id | String | 订单 ID |
|
||
| orderNo | String | 订单号（永不变） |
|
||
| teamNo | String | 团号（订金支付成功生成，创单 null） |
|
||
| displayOrderNo | String | 展示订单号 |
|
||
| productName | String | 产品名（快照） |
|
||
| productCoverImg | String | 产品封面 |
|
||
| tierName | String | 档位名 |
|
||
| customerName | String | 客户姓名 |
|
||
| customerPhoneMasked | String | 客户手机（脱敏） |
|
||
| peopleSummary | String | 人数摘要 |
|
||
| departureDate | LocalDate | 出发日（未定 null） |
|
||
| tripDays | Integer | 行程天数 |
|
||
| orderStatus | String | 粗状态值（附录 A） |
|
||
| orderStatusName | String | 粗状态中文 |
|
||
| flowStatus | String | 细状态值（附录 A） |
|
||
| flowStatusName | String | 细状态中文 |
|
||
| flowStep | Integer | 6 步当前步序号（0=待支付，1-6，null=已取消） |
|
||
| flowStepTotal | Integer | 总步数（6） |
|
||
| flowStepCode | String | 当前步英文码（附录 A） |
|
||
| currentSubFlows | List\<SubFlowVO\> | 当前步子流程（仅 RESOURCE 步非 null） |
|
||
| totalAmount | BigDecimal | 订单金额 |
|
||
| paidAmount | BigDecimal | 实付金额 |
|
||
| balanceAmount | BigDecimal | 待付金额 |
|
||
| consultantName | String | 定制师姓名 |
|
||
| createSource | String | 来源值（附录 A） |
|
||
| createSourceLabel | String | 来源中文 |
|
||
| tags | List\<TagVO\> | 标签列表 |
|
||
| createdAt | LocalDateTime | 创单时间 |
|
||
| depositAmount | BigDecimal | 订金额（FULL 为 null） |
|
||
| depositRatio | Integer | 订金比例%（FULL 为 null） |
|
||
| paymentMode | String | DEPOSIT/FULL |
|
||
| singleRoomSurcharge | BigDecimal | 单房差（未触发 null） |
|
||
| agencyId | String | 旅行社主体 ID |
|
||
| refundPolicyId | String | 退款政策 ID |
|
||
| productSubtitle | String | 产品副标题 |
|
||
|
||
`SubFlowVO`（子流程）
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| code | String | 子流程英文码 HOTEL/VEHICLE/GUIDE/PHOTOGRAPHER |
|
||
| name | String | 子流程名称 |
|
||
| status | String | DONE/PROCESSING/WAITING |
|
||
| label | String | 显示标签（如"待配"） |
|
||
|
||
`TagVO`（标签）
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| name | String | 标签名 |
|
||
| type | String | SYSTEM/MANUAL |
|
||
| color | String | 十六进制色 #RRGGBB |
|
||
| creator | String | 标签创建人姓名 |
|
||
|
||
**出参示例**
|
||
```jsonc
|
||
{
|
||
"code": 200, "message": "成功", "success": true,
|
||
"data": {
|
||
"total": 1, "current": 1, "size": 10,
|
||
"records": [{
|
||
"id": "1900000000000903", "orderNo": "TEST-RESOURCE-903", "teamNo": null,
|
||
"displayOrderNo": "TEST-RESOURCE-903", "productName": "长白山3日私家定制游",
|
||
"tierName": "标准档", "customerName": "测试客户", "customerPhoneMasked": "138****8001",
|
||
"peopleSummary": "2 大", "departureDate": "2026-07-01", "tripDays": 5,
|
||
"orderStatus": "CUSTOMIZING", "orderStatusName": "定制中",
|
||
"flowStatus": "RESOURCE_PREPARING", "flowStatusName": "资源准备",
|
||
"flowStep": 2, "flowStepTotal": 6, "flowStepCode": "RESOURCE",
|
||
"currentSubFlows": [
|
||
{"code": "HOTEL", "name": "配房", "status": "PROCESSING", "label": "待配"},
|
||
{"code": "VEHICLE", "name": "配车", "status": "PROCESSING", "label": "处理中"}
|
||
],
|
||
"totalAmount": 9800.00, "paidAmount": 0.00, "balanceAmount": 9800.00,
|
||
"consultantName": "李定制", "createSource": "CONSULTANT", "createSourceLabel": "定制师创建",
|
||
"tags": [], "createdAt": "2026-06-04 18:49:39",
|
||
"depositAmount": null, "depositRatio": null, "paymentMode": "FULL",
|
||
"singleRoomSurcharge": null, "agencyId": "8000000000000001",
|
||
"refundPolicyId": "7000000000000001", "productSubtitle": "私家小团·专车专导"
|
||
}]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 订单详情（主接口）
|
||
|
||
**接口地址**：`GET /v3/admin/order/{id}`
|
||
**接口介绍**：订单详情页头部聚合接口，返回主单信息(main) + 标签(tags) + 概览(overview，含客户信息与备注)。其余明细已拆为懒加载 Tab。
|
||
**本次修改点**：
|
||
- 主接口**瘦身**：原 `transportPlans` / `itinerary` 全量字段已移出，改为独立懒加载接口（#3385）。
|
||
- `overview` **重构**为 `customerInfo` + `remarkInfo` 两分类（原扁平字段，#3488）。
|
||
- overview 出行人/联系电话/证件号改**明文**返回（idCard/phone/emergencyPhone 不脱敏，#3509）。
|
||
|
||
**入参**
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 含义 |
|
||
|---|---|---|---|---|
|
||
| id | path | Long | 是 | 订单 ID |
|
||
|
||
**入参示例**
|
||
```
|
||
GET /v3/admin/order/1900000000000903
|
||
```
|
||
|
||
**出参**：`OrderDetailRespVO`
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| main | OrderMainVO | 主单 + Tab 状态徽标 + 进度管道 |
|
||
| tags | List\<TagVO\> | 标签区（结构同 §1 TagVO） |
|
||
| overview | OverviewVO | 概览（客户信息 + 备注） |
|
||
|
||
`main`（OrderMainVO，47 字段）
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| id | String | 订单 ID |
|
||
| orderNo | String | 订单号（永不变） |
|
||
| teamNo | String | 团号（未成团 null） |
|
||
| displayOrderNo | String | 展示订单号 |
|
||
| productName | String | 产品名 |
|
||
| tierName | String | 档位名 |
|
||
| productSubtitle | String | 产品副标题 |
|
||
| orderStatus | String | 粗状态值（附录 A） |
|
||
| orderStatusName | String | 粗状态中文 |
|
||
| flowStatus | String | 细状态值（附录 A） |
|
||
| flowStatusName | String | 细状态中文 |
|
||
| flowStep | Integer | 6 步当前步序号（0/1-6/null） |
|
||
| flowStepTotal | Integer | 总步数（6） |
|
||
| flowDisplayText | String | 步骤展示文案（纯中文，不带 "X/6 ·"） |
|
||
| flowStepCode | String | 当前步英文码（CANCELLED/待支付为 null） |
|
||
| flowStepStatus | String | 当前步状态（PROCESSING=进行中） |
|
||
| totalAmount | BigDecimal | 订单金额 |
|
||
| paidAmount | BigDecimal | 实付金额 |
|
||
| balanceAmount | BigDecimal | 待付金额 |
|
||
| departureDate | LocalDate | 出发日期 |
|
||
| returnDate | LocalDate | 返回日期 |
|
||
| tripDays | Integer | 行程天数 |
|
||
| tripNights | Integer | 行程夜数 |
|
||
| createSource | String | 来源值（附录 A） |
|
||
| createSourceLabel | String | 来源中文 |
|
||
| confirmedAt | LocalDateTime | 确认订单时间 |
|
||
| progressStepper | List\<PipelineNodeVO\> | 6 主节点进度管道（已取消返空数组） |
|
||
| contractStatus | String | [Tab 徽标]合同状态（按字符串容错，附录 B） |
|
||
| insuranceStatus | String | [Tab 徽标]保险状态（附录 B） |
|
||
| refundStatus | String | [Tab 徽标]退款状态 NONE/PROCESSING/COMPLETED |
|
||
| hasRefund | Boolean | 是否有退款记录 |
|
||
| hasServiceStandard | Boolean | 是否有服务标准快照 |
|
||
| hasFinanceDetail | Boolean | 是否有财务明细（discount/surcharge>0） |
|
||
| depositAmount | BigDecimal | 订金额（FULL 为 null） |
|
||
| depositRatio | Integer | 订金比例%（FULL 为 null） |
|
||
| paymentMode | String | DEPOSIT/FULL |
|
||
| payStatus | String | 支付状态 UNPAID/DEPOSIT_PAID/FULLY_PAID |
|
||
| singleRoomSurcharge | BigDecimal | 单房差（未触发 null） |
|
||
| agencyId | String | 旅行社主体 ID |
|
||
| refundPolicyId | String | 退款政策 ID |
|
||
|
||
`PipelineNodeVO`（进度节点）
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| step | Integer | 步序号 1-6 |
|
||
| code | String | 节点码 PROFILE/RESOURCE/CONFIRM/DEPART/REVIEW/SETTLE |
|
||
| name | String | 节点名称 |
|
||
| status | String | DONE/PROCESSING/WAITING |
|
||
| label | String | 显示标签 |
|
||
| isCurrent | Boolean | 是否当前步 |
|
||
| subFlows | List\<SubFlowVO\> | 子流程（仅 RESOURCE 节点非 null，结构同 §1） |
|
||
|
||
`overview`（OverviewVO）
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| customerInfo | CustomerInfoVO | 客户信息分类 |
|
||
| remarkInfo | RemarkInfoVO | 备注分类 |
|
||
|
||
`CustomerInfoVO`（客户信息）
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| contactName | String | 联系人姓名 |
|
||
| contactPhone | String | 联系电话（**admin 明文**） |
|
||
| agencyName | String | 商户名（不存在为 null） |
|
||
| consultantName | String | 定制师姓名 |
|
||
| peopleSummary | String | 人数摘要 |
|
||
| adultCount | Integer | 成人数 |
|
||
| childCount | Integer | 儿童数 |
|
||
| youngChildCount | Integer | 小童数 |
|
||
| babyCount | Integer | 婴儿数 |
|
||
| createTime | LocalDateTime | 创建时间 |
|
||
| emergencyContactName | String | 紧急联系人姓名 |
|
||
| emergencyContactPhone | String | 紧急联系人手机（**明文**） |
|
||
| travelers | List\<TravelerPlainVO\> | 出行人集合（明文） |
|
||
|
||
`TravelerPlainVO`（出行人，明文 #3509）
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| id | String | 出行人 ID |
|
||
| orderId | String | 订单 ID |
|
||
| travelerType | String | ADULT/CHILD/YOUNG_CHILD/BABY |
|
||
| name | String | 姓名（占位行为 null） |
|
||
| gender | String | 1=男 / 2=女 / 0=未知 |
|
||
| birthday | LocalDate | 出生日期 |
|
||
| idType | String | ID_CARD/PASSPORT/BIRTH_CERT |
|
||
| idCard | String | 证件号（**明文**） |
|
||
| nationality | String | 国籍（默认中国） |
|
||
| race | String | 民族（默认汉族） |
|
||
| phone | String | 出行人手机（**明文**） |
|
||
| emergencyContact | String | 紧急联系人姓名 |
|
||
| emergencyPhone | String | 紧急联系人电话（**明文**） |
|
||
| roomGroupNo | Integer | 同住分组号 |
|
||
| profileStatus | String | 资料完善 PENDING/COMPLETED |
|
||
| transportPlanIds | List\<String\> | 关联大交通批次 ID 列表 |
|
||
|
||
`RemarkInfoVO`（备注）
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| customerRemark | String | 用户备注（只读） |
|
||
| consultantRemark | String | 定制师备注 |
|
||
| hotelRemark | String | 用房备注（无需求 null） |
|
||
| vehicleRemark | String | 用车备注（无需求 null） |
|
||
|
||
**出参示例**
|
||
```jsonc
|
||
{
|
||
"code": 200, "message": "成功", "success": true,
|
||
"data": {
|
||
"main": {
|
||
"id": "1900000000000903", "orderNo": "TEST-RESOURCE-903", "teamNo": null,
|
||
"displayOrderNo": "TEST-RESOURCE-903", "productName": "长白山3日私家定制游", "tierName": "标准档",
|
||
"productSubtitle": "私家小团·专车专导",
|
||
"orderStatus": "CUSTOMIZING", "orderStatusName": "定制中",
|
||
"flowStatus": "RESOURCE_PREPARING", "flowStatusName": "资源准备",
|
||
"flowStep": 2, "flowStepTotal": 6, "flowDisplayText": "资源准备",
|
||
"flowStepCode": "RESOURCE", "flowStepStatus": "PROCESSING",
|
||
"totalAmount": 9800.00, "paidAmount": 0.00, "balanceAmount": 9800.00,
|
||
"departureDate": "2026-07-01", "returnDate": "2026-07-05", "tripDays": 5, "tripNights": 4,
|
||
"createSource": "CONSULTANT", "createSourceLabel": "定制师创建", "confirmedAt": null,
|
||
"progressStepper": [
|
||
{"step": 1, "code": "PROFILE", "name": "补全信息", "status": "DONE", "label": null, "isCurrent": false, "subFlows": null},
|
||
{"step": 2, "code": "RESOURCE", "name": "资源准备", "status": "PROCESSING", "label": null, "isCurrent": true,
|
||
"subFlows": [{"code": "HOTEL", "name": "配房", "status": "PROCESSING", "label": "待配"}]}
|
||
],
|
||
"contractStatus": "NONE", "insuranceStatus": "NONE", "refundStatus": "NONE",
|
||
"hasRefund": false, "hasServiceStandard": true, "hasFinanceDetail": false,
|
||
"depositAmount": null, "depositRatio": null, "paymentMode": "FULL", "payStatus": "UNPAID",
|
||
"singleRoomSurcharge": null, "agencyId": "8000000000000001", "refundPolicyId": "7000000000000001"
|
||
},
|
||
"tags": [],
|
||
"overview": {
|
||
"customerInfo": {
|
||
"contactName": "测试客户", "contactPhone": "13800138001", "agencyName": "呼籁旅行",
|
||
"consultantName": "李定制", "peopleSummary": "2 大", "adultCount": 2, "childCount": 0,
|
||
"youngChildCount": 0, "babyCount": 0, "createTime": "2026-06-04 18:49:39",
|
||
"emergencyContactName": "王五", "emergencyContactPhone": "13900139000",
|
||
"travelers": [{
|
||
"id": "1910000000000001", "orderId": "1900000000000903", "travelerType": "ADULT",
|
||
"name": "张三", "gender": "1", "birthday": "1990-01-01", "idType": "ID_CARD",
|
||
"idCard": "220101199001010011", "nationality": "中国", "race": "汉族",
|
||
"phone": "13800138001", "emergencyContact": "王五", "emergencyPhone": "13900139000",
|
||
"roomGroupNo": 1, "profileStatus": "COMPLETED", "transportPlanIds": []
|
||
}]
|
||
},
|
||
"remarkInfo": {
|
||
"customerRemark": "希望安排靠窗座位", "consultantRemark": "VIP 客户，重点跟进",
|
||
"hotelRemark": null, "vehicleRemark": null
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 财务 Tab
|
||
|
||
**接口地址**：`GET /v3/admin/order/{id}/finance`
|
||
**接口介绍**：订单财务明细，含金额汇总、支付/优惠/附加费三类明细列表。
|
||
**本次修改点**：`SurchargeVO` **删除 `surchargeType` 字段**（恒 null 无数据源，#3523）——破坏性，前端引用处需移除。
|
||
|
||
**入参**
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 含义 |
|
||
|---|---|---|---|---|
|
||
| id | path | Long | 是 | 订单 ID |
|
||
|
||
**入参示例**
|
||
```
|
||
GET /v3/admin/order/1900000000000903/finance
|
||
```
|
||
|
||
**出参**：`FinanceVO`
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| totalAmount | BigDecimal | 订单总额 |
|
||
| paidAmount | BigDecimal | 实付金额 |
|
||
| balanceAmount | BigDecimal | 待付金额 |
|
||
| discountAmount | BigDecimal | 优惠金额汇总 |
|
||
| surchargeAmount | BigDecimal | 附加费汇总 |
|
||
| refundAmount | BigDecimal | 退款金额汇总 |
|
||
| payments | List\<PaymentVO\> | 支付明细 |
|
||
| discounts | List\<DiscountVO\> | 优惠明细 |
|
||
| surcharges | List\<SurchargeVO\> | 附加费用 |
|
||
|
||
`PaymentVO`
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| id | String | 支付记录 ID |
|
||
| payType | String | DEPOSIT/BALANCE |
|
||
| amount | BigDecimal | 支付金额 |
|
||
| paidAt | LocalDateTime | 支付时间 |
|
||
| status | String | SUCCESS/PENDING/FAIL |
|
||
|
||
`DiscountVO`
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| id | String | 优惠 ID |
|
||
| name | String | 优惠名称 |
|
||
| amount | BigDecimal | 优惠金额 |
|
||
| type | String | EARLY_BIRD/VIP/… |
|
||
| source | String | MANUAL/AUTO |
|
||
| createdAt | LocalDateTime | 创建时间 |
|
||
|
||
`SurchargeVO`（已删 `surchargeType`）
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| id | String | 附加费 ID |
|
||
| name | String | 附加费名称 |
|
||
| amount | BigDecimal | 金额 |
|
||
| source | String | HOTEL_ASSIGN/VEHICLE_ASSIGN/… |
|
||
| createdAt | LocalDateTime | 创建时间 |
|
||
|
||
**出参示例**
|
||
```jsonc
|
||
{
|
||
"code": 200, "message": "成功", "success": true,
|
||
"data": {
|
||
"totalAmount": 9800.00, "paidAmount": 5000.00, "balanceAmount": 4800.00,
|
||
"discountAmount": 200.00, "surchargeAmount": 300.00, "refundAmount": 0.00,
|
||
"payments": [
|
||
{"id": "2001", "payType": "DEPOSIT", "amount": 5000.00, "paidAt": "2026-06-04 19:00:00", "status": "SUCCESS"}
|
||
],
|
||
"discounts": [
|
||
{"id": "3001", "name": "早鸟优惠", "amount": 200.00, "type": "EARLY_BIRD", "source": "AUTO", "createdAt": "2026-06-04 18:50:00"}
|
||
],
|
||
"surcharges": [
|
||
{"id": "4001", "name": "单房差", "amount": 300.00, "source": "HOTEL_ASSIGN", "createdAt": "2026-06-04 18:55:00"}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
> 无数据时各 list 返回 `[]`（非 null）。
|
||
|
||
---
|
||
|
||
## 4. 合同保险 Tab
|
||
|
||
**接口地址**：`GET /v3/admin/order/{id}/contract-insurance`
|
||
**接口介绍**：订单合同与保险状态 + 事件时间线。
|
||
**本次修改点**：`events` **真实化**——来自 status_log / insurance_status_log，不再恒空（#3514）。
|
||
|
||
**入参**
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 含义 |
|
||
|---|---|---|---|---|
|
||
| id | path | Long | 是 | 订单 ID |
|
||
|
||
**入参示例**
|
||
```
|
||
GET /v3/admin/order/1900000000000903/contract-insurance
|
||
```
|
||
|
||
**出参**：`ContractInsuranceVO`
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| contract | ContractVO | 合同子对象 |
|
||
| insurance | InsuranceVO | 保险子对象 |
|
||
|
||
`ContractVO`
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| contractStatus | String | 合同状态（附录 B） |
|
||
| contractSignedAt | LocalDateTime | 签约时间 |
|
||
| contractFileUrl | String | 合同文件 URL |
|
||
| events | List\<EventVO\> | 合同事件时间线 |
|
||
|
||
`InsuranceVO`
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| insuranceStatus | String | 保险状态（附录 B） |
|
||
| insurancePolicyNo | String | 保单号 |
|
||
| insurancePremium | BigDecimal | 保费 |
|
||
| events | List\<EventVO\> | 保险事件时间线 |
|
||
|
||
`EventVO`
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| eventType | String | 事件类型 GENERATE/SIGN/ISSUE/… |
|
||
| occurredAt | LocalDateTime | 发生时间 |
|
||
|
||
**出参示例**
|
||
```jsonc
|
||
{
|
||
"code": 200, "message": "成功", "success": true,
|
||
"data": {
|
||
"contract": {
|
||
"contractStatus": "SIGNED", "contractSignedAt": "2026-06-05 10:00:00",
|
||
"contractFileUrl": "https://oss.example.com/contracts/903.pdf",
|
||
"events": [
|
||
{"eventType": "GENERATE", "occurredAt": "2026-06-05 09:30:00"},
|
||
{"eventType": "SIGN", "occurredAt": "2026-06-05 10:00:00"}
|
||
]
|
||
},
|
||
"insurance": {
|
||
"insuranceStatus": "INSURED", "insurancePolicyNo": "PICC2026070100123",
|
||
"insurancePremium": 60.00,
|
||
"events": [{"eventType": "ISSUE", "occurredAt": "2026-06-05 10:05:00"}]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 发票 Tab 〔新增接口〕
|
||
|
||
**接口地址**：`GET /v3/admin/order/{id}/invoices`
|
||
**接口介绍**：返回该订单**全部**发票（含已作废 VOIDED），按 applyAt 倒序。
|
||
**本次修改点**：**新增接口**（#3517 / #3521）。无发票返回 `data:[]`。
|
||
|
||
**入参**
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 含义 |
|
||
|---|---|---|---|---|
|
||
| id | path | Long | 是 | 订单 ID |
|
||
|
||
**入参示例**
|
||
```
|
||
GET /v3/admin/order/1900000000000903/invoices
|
||
```
|
||
|
||
**出参**：`List<InvoiceVO>`（每条 23 字段）
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| id | String | 发票 ID |
|
||
| orderId | String | 订单 ID |
|
||
| invoiceType | String | 类型值（附录 A） |
|
||
| invoiceTypeText | String | 类型文案 |
|
||
| titleType | String | 抬头类型 COMPANY/PERSONAL |
|
||
| titleName | String | 抬头名称 |
|
||
| taxNo | String | 税号（公司抬头/专票必填） |
|
||
| amount | BigDecimal | 开票金额（元） |
|
||
| status | String | 状态值（附录 A） |
|
||
| statusText | String | 状态文案 |
|
||
| auditStatus | String | 机审 PENDING/APPROVED/MANUAL_REVIEW/REJECTED |
|
||
| applyReason | String | 申请说明 |
|
||
| applyAt | LocalDateTime | 申请时间 |
|
||
| fileUrl | String | 发票文件 OSS 链接（UPLOADED 后有值） |
|
||
| uploader | String | 上传人 |
|
||
| uploadedAt | LocalDateTime | 上传时间 |
|
||
| deliveredAt | LocalDateTime | 送达时间（DELIVERED 时有值） |
|
||
| voidReason | String | 作废原因（VOIDED 时有值） |
|
||
| email | String | 邮箱（电子发票） |
|
||
| mailAddress | String | 邮寄地址（纸质发票） |
|
||
| bankName | String | 开户行（专票） |
|
||
| bankAccount | String | 开户账号（专票） |
|
||
| registAddress | String | 注册地址（专票） |
|
||
| registPhone | String | 注册电话（专票） |
|
||
|
||
**出参示例**
|
||
```jsonc
|
||
{
|
||
"code": 200, "message": "成功", "success": true,
|
||
"data": [{
|
||
"id": "5001", "orderId": "1900000000000903",
|
||
"invoiceType": "ELECTRONIC", "invoiceTypeText": "电子普通发票",
|
||
"titleType": "PERSONAL", "titleName": "张三", "taxNo": null,
|
||
"amount": 9800.00, "status": "ISSUED", "statusText": "已开票",
|
||
"auditStatus": "APPROVED", "applyReason": "报销", "applyAt": "2026-06-05 11:00:00",
|
||
"fileUrl": null, "uploader": null, "uploadedAt": null, "deliveredAt": null, "voidReason": null,
|
||
"email": "zhangsan@example.com", "mailAddress": null,
|
||
"bankName": null, "bankAccount": null, "registAddress": null, "registPhone": null
|
||
}]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 行程 Tab
|
||
|
||
**接口地址**：`GET /v3/admin/order/{id}/itinerary`
|
||
**接口介绍**：订单配房/配车的需求(requirement) + 实配(assignments)。
|
||
**本次修改点**：
|
||
- 删顶层 MOCK `days`（逐天行程改走 `/itinerary/full`，#3502）——破坏性。
|
||
- `hotelGroup`/`vehicleGroup`.requirement **真实化**（#3385/#3493）；assignment 增 `requirementId`。
|
||
- `HotelAssignmentVO`（实配酒店）当前**恒返空**，待 house 域接通，前端按空处理勿报错。
|
||
|
||
**入参**
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 含义 |
|
||
|---|---|---|---|---|
|
||
| id | path | Long | 是 | 订单 ID |
|
||
|
||
**入参示例**
|
||
```
|
||
GET /v3/admin/order/1900000000000903/itinerary
|
||
```
|
||
|
||
**出参**：`ItineraryVO`
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| hotelGroup | HotelGroupVO | 配房需求 + 实配 |
|
||
| vehicleGroup | VehicleGroupVO | 配车需求 + 实配 |
|
||
|
||
`HotelGroupVO`（配房组）
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| requirement | HotelRequirementBriefVO | 配房需求（客户/定制师提交的用房要求） |
|
||
| assignments | List\<HotelAssignmentVO\> | 实配酒店列表（当前恒空，待 house 域接通） |
|
||
|
||
`VehicleGroupVO`（配车组）
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| requirement | VehicleRequirementBriefVO | 配车需求（客户/定制师提交的用车要求） |
|
||
| assignments | List\<VehicleAssignmentVO\> | 实配车辆列表（实际派车 + 司机） |
|
||
|
||
`HotelRequirementBriefVO`（配房需求）
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| requirementId | String | 需求 ID |
|
||
| version | Integer | 版本号 |
|
||
| status | String | PENDING/PROCESSING/DONE |
|
||
| submittedAt | LocalDateTime | 提交时间 |
|
||
| totalRoomCount | Integer | 合计间数 |
|
||
| roomTypeSummary | String | 房型摘要（双床房×4 / 大床房×2） |
|
||
| specialTags | List\<String\> | 特殊诉求标签 |
|
||
| remark | String | 备注 |
|
||
| claimerName | String | 房控接单人姓名 |
|
||
| days | List\<RequirementDayVO\> | 按天结构化需求 |
|
||
|
||
`RequirementDayVO`（按天需求）
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| dayNumber | Integer | 第几天 |
|
||
| stayDate | LocalDate | 入住日（派生） |
|
||
| remark | String | 当天备注 |
|
||
| hotels | List\<RequirementHotelVO\> | 当天房型明细 |
|
||
|
||
`RequirementHotelVO`（房型明细）
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| hotelId | String | 目标酒店 ID（可 null） |
|
||
| roomCategory | String | 房型字典 code TWIN/DOUBLE_BED |
|
||
| roomCategoryLabel | String | 房型中文标签 |
|
||
| roomCount | Integer | 间数 |
|
||
| budget | BigDecimal | 预算/间（可 null） |
|
||
|
||
`HotelAssignmentVO`（实配酒店，**当前恒返空**）
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| assignmentId | String | 实配 ID |
|
||
| requirementId | String | 关联配房需求 ID |
|
||
| familyIndex | Integer | 家庭序号 |
|
||
| dayNumber | Integer | 第几天 |
|
||
| stayDate | LocalDate | 入住日 |
|
||
| hotelName | String | 酒店名 |
|
||
| roomType | String | 房型中文名 |
|
||
| plannedCost | BigDecimal | 单价（元/间·晚） |
|
||
| remark | String | 备注 |
|
||
|
||
`VehicleRequirementBriefVO`（配车需求）
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| requirementId | String | 需求 ID |
|
||
| version | Integer | 版本号 |
|
||
| status | String | PENDING/PROCESSING/DONE |
|
||
| submittedAt | LocalDateTime | 提交时间 |
|
||
| vehicleTypeSummary | String | 车型摘要 |
|
||
| specialTags | List\<String\> | 特殊诉求标签 |
|
||
| remark | String | 备注 |
|
||
|
||
`VehicleAssignmentVO`（实配车辆）
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| assignmentId | String | 实配 ID |
|
||
| vehicleType | String | 车型 |
|
||
| vehicleCount | Integer | 车辆数 |
|
||
| licensePlate | String | 车牌 |
|
||
| brand | String | 品牌 |
|
||
| seats | Integer | 座位数 |
|
||
| plannedDailyFee | BigDecimal | 计划日单价 |
|
||
| driverName | String | 司机姓名 |
|
||
| driverPhoneMasked | String | 司机手机（脱敏） |
|
||
| remark | String | 备注 |
|
||
|
||
**出参示例**
|
||
```jsonc
|
||
{
|
||
"code": 200, "message": "成功", "success": true,
|
||
"data": {
|
||
"hotelGroup": {
|
||
"requirement": {
|
||
"requirementId": "6001", "version": 1, "status": "PROCESSING",
|
||
"submittedAt": "2026-06-04 20:00:00", "totalRoomCount": 2,
|
||
"roomTypeSummary": "双床房×1 / 大床房×1", "specialTags": ["无烟房", "高楼层"],
|
||
"remark": "尽量安排连号房", "claimerName": "房控小赵",
|
||
"days": [{
|
||
"dayNumber": 1, "stayDate": "2026-07-01", "remark": null,
|
||
"hotels": [{"hotelId": null, "roomCategory": "TWIN", "roomCategoryLabel": "双床房", "roomCount": 1, "budget": 400.00}]
|
||
}]
|
||
},
|
||
"assignments": []
|
||
},
|
||
"vehicleGroup": {
|
||
"requirement": {
|
||
"requirementId": "6101", "version": 1, "status": "PROCESSING",
|
||
"submittedAt": "2026-06-04 20:05:00", "vehicleTypeSummary": "7 座商务车×1",
|
||
"specialTags": ["儿童座椅"], "remark": "全程同一司机"
|
||
},
|
||
"assignments": [{
|
||
"assignmentId": "6201", "vehicleType": "7座商务车", "vehicleCount": 1,
|
||
"licensePlate": "吉A·12345", "brand": "别克GL8", "seats": 7,
|
||
"plannedDailyFee": 800.00, "driverName": "李师傅", "driverPhoneMasked": "138****0000", "remark": null
|
||
}]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 大交通批次 Tab
|
||
|
||
**接口地址**：`GET /v3/admin/order/{id}/transport-plans`
|
||
**接口介绍**：订单大交通（抵达/返程）批次安排，含航班/车次/自驾、接送、关联出行人。
|
||
**本次修改点**：原在详情主接口内，#3385 起拆为独立懒加载接口（字段不变）。无批次返回 `data:[]`。
|
||
|
||
**入参**
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 含义 |
|
||
|---|---|---|---|---|
|
||
| id | path | Long | 是 | 订单 ID |
|
||
|
||
**入参示例**
|
||
```
|
||
GET /v3/admin/order/1900000000000903/transport-plans
|
||
```
|
||
|
||
**出参**：`List<TransportPlanVO>`（每条 17 字段）
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| id | String | 批次 ID |
|
||
| orderId | String | 订单 ID |
|
||
| direction | String | 方向 ARRIVAL/DEPARTURE |
|
||
| mode | String | TOGETHER(一起)/SEPARATE(分批) |
|
||
| transportType | String | FLIGHT/TRAIN/SELF_DRIVE |
|
||
| transportNo | String | 航班号/车次号 |
|
||
| carrier | String | 航司/铁路公司 |
|
||
| departStation | String | 出发站 |
|
||
| arriveStation | String | 到达站 |
|
||
| departTime | LocalDateTime | 出发时间 |
|
||
| arriveTime | LocalDateTime | 到达时间 |
|
||
| selfDrivePeriod | String | 自驾时段 MORNING/AFTERNOON/EVENING |
|
||
| selfDriveEta | LocalDateTime | 自驾预计到达时间 |
|
||
| pickupRequired | Boolean | 是否需要接送 |
|
||
| pickupRemark | String | 接送备注 |
|
||
| travelers | List\<TravelerRef\> | 关联出行人 |
|
||
| remark | String | 备注 |
|
||
|
||
`TravelerRef`（关联出行人）
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| id | String | 出行人 ID |
|
||
| name | String | 出行人姓名 |
|
||
|
||
**出参示例**
|
||
```jsonc
|
||
{
|
||
"code": 200, "message": "成功", "success": true,
|
||
"data": [{
|
||
"id": "7001", "orderId": "1900000000000903", "direction": "ARRIVAL",
|
||
"mode": "TOGETHER", "transportType": "FLIGHT", "transportNo": "CA1234", "carrier": "中国国航",
|
||
"departStation": "北京首都T3", "arriveStation": "长春龙嘉",
|
||
"departTime": "2026-07-01 08:00:00", "arriveTime": "2026-07-01 10:00:00",
|
||
"selfDrivePeriod": null, "selfDriveEta": null,
|
||
"pickupRequired": true, "pickupRemark": "出站口接机举牌",
|
||
"travelers": [{"id": "1910000000000001", "name": "张三"}],
|
||
"remark": null
|
||
}]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 状态记录时间线 Tab
|
||
|
||
**接口地址**：`GET /v3/admin/order/{id}/status-log`
|
||
**接口介绍**：订单全生命周期状态/操作流水时间线。
|
||
**本次修改点**：无字段变更。无记录返回 `data:[]`。
|
||
|
||
**入参**
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 含义 |
|
||
|---|---|---|---|---|
|
||
| id | path | Long | 是 | 订单 ID |
|
||
|
||
**入参示例**
|
||
```
|
||
GET /v3/admin/order/1900000000000903/status-log
|
||
```
|
||
|
||
**出参**：`List<LogTimelineVO>`
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| occurredAt | LocalDateTime | 发生时间 |
|
||
| operator | String | 操作人 |
|
||
| action | String | 操作描述 |
|
||
| fromStatus | String | 变更前状态（有状态变更时有值） |
|
||
| toStatus | String | 变更后状态（有状态变更时有值） |
|
||
| amount | BigDecimal | 涉及金额（支付/退款时有值） |
|
||
|
||
**出参示例**
|
||
```jsonc
|
||
{
|
||
"code": 200, "message": "成功", "success": true,
|
||
"data": [
|
||
{"occurredAt": "2026-06-04 18:49:39", "operator": "李定制", "action": "创建订单", "fromStatus": null, "toStatus": "CUSTOMIZING", "amount": null},
|
||
{"occurredAt": "2026-06-04 19:00:00", "operator": "测试客户", "action": "支付订金", "fromStatus": null, "toStatus": null, "amount": 5000.00}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 退款明细 Tab
|
||
|
||
**接口地址**：`GET /v3/admin/order/{id}/refund`
|
||
**接口介绍**：订单退款申请明细（可多笔），含审批/到账进度时间线。
|
||
**本次修改点**：无字段变更。**无退款申请时整节返回 `data:null`**（前端需与"订单不存在 581007"区分）。
|
||
|
||
**入参**
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 含义 |
|
||
|---|---|---|---|---|
|
||
| id | path | Long | 是 | 订单 ID |
|
||
|
||
**入参示例**
|
||
```
|
||
GET /v3/admin/order/1900000000000903/refund
|
||
```
|
||
|
||
**出参**：`RefundDetailVO`
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| totalRefundAmount | BigDecimal | 合计退款金额 |
|
||
| applications | List\<RefundApplicationVO\> | 多笔退款申请 |
|
||
|
||
`RefundApplicationVO`
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| applicationId | String | 申请 ID |
|
||
| status | String | 状态（附录 B） |
|
||
| statusText | String | 状态描述文案 |
|
||
| refundAmount | BigDecimal | 退款金额 |
|
||
| refundChannel | String | 退款渠道 |
|
||
| approverName | String | 审批人 |
|
||
| approvedAt | LocalDateTime | 审批时间 |
|
||
| estimatedArriveDate | LocalDate | 预计到账日期 |
|
||
| actualArriveDate | LocalDate | 实际到账日期（未到账 null） |
|
||
| progress | List\<ProgressStepVO\> | 4 步进度时间线 |
|
||
| items | List\<RefundItemVO\> | 退款明细行 |
|
||
|
||
`ProgressStepVO`
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| step | String | APPLY/APPROVE/PAYOUT/ARRIVED |
|
||
| label | String | 展示标签 |
|
||
| status | String | DONE/ACTIVE/PENDING |
|
||
| occurredAt | LocalDateTime | 发生时间（PENDING 时 null） |
|
||
|
||
`RefundItemVO`
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| itemName | String | 项目名称 |
|
||
| reason | String | 退款原因 |
|
||
| appliedAt | LocalDateTime | 申请时间 |
|
||
| amount | BigDecimal | 退款金额（负数） |
|
||
|
||
**出参示例**
|
||
```jsonc
|
||
// 空态（无退款）
|
||
{"code": 200, "message": "成功", "success": true, "data": null}
|
||
|
||
// 有退款
|
||
{
|
||
"code": 200, "message": "成功", "success": true,
|
||
"data": {
|
||
"totalRefundAmount": 1000.00,
|
||
"applications": [{
|
||
"applicationId": "8001", "status": "PENDING_PAYOUT", "statusText": "待打款",
|
||
"refundAmount": 1000.00, "refundChannel": "原路退回", "approverName": "财务老王",
|
||
"approvedAt": "2026-06-05 14:00:00", "estimatedArriveDate": "2026-06-08", "actualArriveDate": null,
|
||
"progress": [
|
||
{"step": "APPLY", "label": "提交申请", "status": "DONE", "occurredAt": "2026-06-05 13:00:00"},
|
||
{"step": "APPROVE", "label": "审批通过", "status": "DONE", "occurredAt": "2026-06-05 14:00:00"},
|
||
{"step": "PAYOUT", "label": "打款", "status": "ACTIVE", "occurredAt": null},
|
||
{"step": "ARRIVED", "label": "到账", "status": "PENDING", "occurredAt": null}
|
||
],
|
||
"items": [{"itemName": "酒店退订", "reason": "行程缩短", "appliedAt": "2026-06-05 13:00:00", "amount": -1000.00}]
|
||
}]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 10. 服务标准 Tab
|
||
|
||
**接口地址**：`GET /v3/admin/order/{id}/service-standard`
|
||
**接口介绍**：订单服务标准（出团承诺 + 逐天行程 + 退费说明），数据源为产品侧预置并冻入订单快照的成品。
|
||
**本次修改点**：**重构为一站式聚合**（#3340/#3351）——原 itinerary/notice/refundPolicy/serviceStandard/dayTips 五字段全部替换为本套 ServiceStandardVO 结构；读快照预置成品。**产品快照缺失时返回 `data:null`**。
|
||
|
||
**入参**
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 含义 |
|
||
|---|---|---|---|---|
|
||
| id | path | Long | 是 | 订单 ID |
|
||
|
||
**入参示例**
|
||
```
|
||
GET /v3/admin/order/1900000000000903/service-standard
|
||
```
|
||
|
||
**出参**：`ServiceStandardVO`
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| title | String | 标题（"出团服务标准·"+产品名；name 空时退化为"出团服务标准"） |
|
||
| subtitle | String | 副标题（固定常量） |
|
||
| intro | String | 服务标准简介（无结构 null） |
|
||
| notices | List\<NoticeItem\> | 服务承诺条目扁平列表（无结构空列表） |
|
||
| itinerary | List\<DayVO\> | 行程逐天列表 |
|
||
| refundNotes | List\<RefundNoteGroup\> | 退费说明聚合列表（无退费说明空列表） |
|
||
|
||
`NoticeItem`（服务承诺条目）
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| title | String | 主文案标题 |
|
||
| content | String | 正文 |
|
||
| remark | String | 灰色二级说明（可选） |
|
||
| color | String | 文案颜色 #RRGGBB（可选） |
|
||
| contactName | String | 联系人（可选） |
|
||
| phone | String | 手机号（可选） |
|
||
|
||
`DayVO`（行程天）
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| dayNumber | Integer | 天序号 |
|
||
| dayTitle | String | 天标题 |
|
||
| remark | String | 当天备注（恒 null） |
|
||
| itineraryNode | List\<ItineraryNode\> | 当天点位列表 |
|
||
|
||
`ItineraryNode`（行程点位）
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| nodeName | String | 点位名称 |
|
||
| description | String | 点位描述 |
|
||
| contactName | String | 联系人（占位，恒 null） |
|
||
| phone | String | 手机号（占位，恒 null） |
|
||
|
||
`RefundNoteGroup`（退费说明分组）
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| sourceName | String | 来源点位名称 |
|
||
| intro | String | 退费说明备注 |
|
||
| items | List\<RefundItem\> | 退费明细列表 |
|
||
|
||
`RefundItem`（退费明细）
|
||
|
||
| 字段 | 类型 | 含义 |
|
||
|---|---|---|
|
||
| title | String | 展示标题 |
|
||
| amount | BigDecimal | 退费金额（赠送为 0） |
|
||
| unitLabel | String | 展示文案 /人 /团 /辆 |
|
||
| settleScope | String | 结算粒度 PER_PERSON/PER_TEAM/PER_VEHICLE |
|
||
| settleScopeLabel | String | 结算粒度中文 |
|
||
| remark | String | 备注 |
|
||
| effectiveFrom | LocalDate | 生效起日（null=无限制） |
|
||
| effectiveTo | LocalDate | 生效止日（null=无限制） |
|
||
|
||
**出参示例**（取自测试服 903 真实返回）
|
||
```jsonc
|
||
{
|
||
"code": 200, "message": "成功", "success": true,
|
||
"data": {
|
||
"title": "出团服务标准·长白山3日私家定制游",
|
||
"subtitle": "领队/师傅/运营 共同遵守·配合合同执行",
|
||
"intro": "我们承诺全程提供贴心服务保障，专车专导，确保旅途安心舒适。",
|
||
"notices": [
|
||
{"title": "接送站服务", "content": "司机持有 A1 驾照，8 年以上驾龄，提供机场/高铁站免费接送",
|
||
"remark": "仅限指定时段（08:00-20:00）", "color": "#FF6600", "contactName": "李师傅", "phone": "13800000000"},
|
||
{"title": "用餐标准", "content": "每日含早餐，正餐按行程安排当地特色餐",
|
||
"remark": "忌口请提前告知", "color": null, "contactName": null, "phone": null}
|
||
],
|
||
"itinerary": [{
|
||
"dayNumber": 1, "dayTitle": "抵达长春-接机入住", "remark": null,
|
||
"itineraryNode": [
|
||
{"nodeName": "长春龙嘉国际机场", "description": "专车接机，送往酒店休息", "contactName": null, "phone": null},
|
||
{"nodeName": "入住酒店", "description": "长春市区四星酒店，自由活动", "contactName": null, "phone": null}
|
||
]
|
||
}],
|
||
"refundNotes": [{
|
||
"sourceName": "长白山天池", "intro": "景区门票及区间车费用，按下列规则退费",
|
||
"items": [
|
||
{"title": "成人未参加", "amount": 125, "unitLabel": "/人", "settleScope": "PER_PERSON",
|
||
"settleScopeLabel": "按人", "remark": "含门票105+环保车20", "effectiveFrom": null, "effectiveTo": null}
|
||
]
|
||
}]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 附录 A 枚举字典
|
||
|
||
### OrderStatus（订单粗状态）
|
||
|
||
| 值 | 中文 |
|
||
|---|---|
|
||
| PENDING_PAY | 待支付 |
|
||
| CUSTOMIZING | 定制中 |
|
||
| PENDING_DEPARTURE | 待出行 |
|
||
| TRAVELLING | 出行中 |
|
||
| COMPLETED | 已完成 |
|
||
| CANCELLED | 已取消 |
|
||
|
||
### OrderFlowStatus（订单细状态，12 态）
|
||
|
||
| 值 | 中文 |
|
||
|---|---|
|
||
| AWAITING_PAY | 待支付 |
|
||
| AWAITING_PROFILE | 待补全信息 |
|
||
| RESOURCE_PREPARING | 资源准备 |
|
||
| PENDING_CONFIRM | 待确认 |
|
||
| PENDING_DEPARTURE | 待出行 |
|
||
| TRAVELLING | 出行中 |
|
||
| PENDING_REVIEW | 待核单 |
|
||
| REVIEWING | 核单中 |
|
||
| PENDING_SETTLE | 待结算 |
|
||
| SETTLED | 已结算 |
|
||
| COMPLETED | 已完成 |
|
||
| CANCELLED | 已取消 |
|
||
|
||
### OrderFlowMainStep（6 主步，flowStepCode / progressStepper）
|
||
|
||
| code | step | 中文 |
|
||
|---|---|---|
|
||
| PROFILE | 1 | 补全信息 |
|
||
| RESOURCE | 2 | 资源准备 |
|
||
| CONFIRM | 3 | 确认 |
|
||
| DEPART | 4 | 出行 |
|
||
| REVIEW | 5 | 核单 |
|
||
| SETTLE | 6 | 结算 |
|
||
|
||
> flowStep=0 表示"待支付"（步骤条未开始）；CANCELLED 终态 flowStep=null、flowStepCode=null。
|
||
|
||
### 其他枚举
|
||
|
||
| 枚举字段 | 值 | 中文 |
|
||
|---|---|---|
|
||
| createSource | CONSULTANT / CUSTOMER | 定制师创建（默认/兜底） / C端客户自下单 |
|
||
| payStatus | UNPAID / DEPOSIT_PAID / FULLY_PAID | 未支付 / 订金已付 / 全款已付 |
|
||
| paymentMode | DEPOSIT / FULL | 订金模式 / 全款模式 |
|
||
| refundStatus(main 徽标) | NONE / PROCESSING / COMPLETED | 无退款 / 退款中 / 已完成 |
|
||
| invoiceType | VAT_NORMAL / VAT_SPECIAL / ELECTRONIC | 增值税普票 / 增值税专票 / 电子普票 |
|
||
| invoice status | APPLIED / ISSUED / UPLOADED / DELIVERED / VOIDED | 已申请 / 已开票 / 已上传 / 已送达 / 已作废 |
|
||
| invoice auditStatus | PENDING / APPROVED / MANUAL_REVIEW / REJECTED | 待审 / 通过 / 转人工 / 拒绝 |
|
||
| titleType | COMPANY / PERSONAL | 公司 / 个人 |
|
||
| transportType | FLIGHT / TRAIN / SELF_DRIVE | 飞机 / 火车 / 自驾 |
|
||
| direction | ARRIVAL / DEPARTURE | 抵达 / 返程 |
|
||
| settleScope | PER_PERSON / PER_TEAM / PER_VEHICLE | 按人 / 按团 / 按辆 |
|
||
| travelerType | ADULT / CHILD / YOUNG_CHILD / BABY | 成人 / 儿童 / 小童 / 婴儿 |
|
||
| idType | ID_CARD / PASSPORT / BIRTH_CERT | 身份证 / 护照 / 出生证 |
|
||
| 通用 status | DONE / PROCESSING / WAITING | 完成 / 处理中 / 等待 |
|
||
|
||
## 附录 B 枚举口径差异（⚠️ 按字符串容错，配合 statusText）
|
||
|
||
| 字段 | 底层枚举类取值 | VO 文案口径 |
|
||
|---|---|---|
|
||
| contractStatus | PENDING/GENERATED/REPORTED/UPLOADED/SIGNING/SIGNED/VOIDING/VOIDED | NONE/GENERATING/GENERATED/SIGNED/VOIDED/RESIGNING |
|
||
| insuranceStatus | PENDING/INSURING/INSURED/CANCELLED/FAILED | NONE/INSURED/CANCELLED/FAILED |
|
||
| refund status | PENDING/APPROVED/REJECTED/REFUNDING/REFUNDED/CANCELLED/ABNORMAL | PENDING_APPROVE/PENDING_PAYOUT/PENDING_ARRIVAL/COMPLETED/REJECTED |
|
||
|
||
> 上述由 Converter 映射，前端**勿硬编码全集**，按接口实际返回字符串渲染 + 用 `statusText` 展示文案。
|
||
|
||
---
|
||
|
||
## 关联 / 联系人
|
||
|
||
- Issue：[#3517](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）
|
||
```
|