hl-api-changelog/changelogs-v2/2026-05/18_§1_订单核心模块-新增接口-管理后台.md

【新增接口·管理后台】v3 订单核心模块 §1 core

更新时间: 2026-05-18 端类型: 管理后台 设计文档版本: v5.49（API-SPEC / SRS / DETAIL-DESIGN / DATABASE-SCHEMA 4 份 HTML 同步）

---

0. 模块全貌

子模块	含接口	接口数	推送状态
§1A 订单 CRUD + 详情	§1.1 创建 / §1.2 列表 / §1.3.1 详情主聚合 / §1.3.2~§1.3.7 6 Tab 子接口 / §1.4 修改	10	✅ 本次推送
§1B 取消订单	§1.5.0 预览 / §1.5.1 出行前 / §1.5.2 出行中	3	📝 待补
§1C 状态机 + 锁单	§1.7 transition / §1.8 confirm-checklist	2	📝 待补

📌 本文件为 §1 模块累计 changelog，后续 §1B / §1C 落地时通过追加 commit 扩充同一文件。

---

1. 接口背景

订单服务 v3（hl-order-service-v3 全新二期）的订单核心模块 §1 core 提供订单管理基础能力，覆盖定制师 B 端代下单 / 多维度筛选列表 / 订单详情（首屏主聚合 + 6 个 Tab 独立懒加载）/ 非关键字段修改。

本次（§1A）推送 10 个接口，对应管理后台原型 F8-F20（订单列表+创建+详情主体）、F22-F26（详情各 Tab 单刷新）、F37（修改订单字段）。

---

2. 变更清单

#	§	接口名	方法	路径
1	1.1	创建订单	POST	/v3/admin/order
2	1.2	订单列表	GET	/v3/admin/order
3	1.3.1	订单详情主聚合	GET	/v3/admin/order/{id}
4	1.3.2	财务 Tab	GET	/v3/admin/order/{id}/finance
5	1.3.3	合同保险 Tab	GET	/v3/admin/order/{id}/contract-insurance
6	1.3.4	行程安排 Tab ⚠️Mock	GET	/v3/admin/order/{id}/itinerary
7	1.3.5	状态记录 Tab	GET	/v3/admin/order/{id}/status-log
8	1.3.6	退款明细 Tab	GET	/v3/admin/order/{id}/refund
9	1.3.7	服务标准 Tab	GET	/v3/admin/order/{id}/service-standard
10	1.4	修改订单字段	PUT	/v3/admin/order/{id}

---

3. 接口详情

每个接口自包含：使用场景 / 入参 / 出参 / 错误码 / 业务边界 / 示例（请求 + 响应）。 跨接口共享枚举集中在 §6；模块整体影响评估在 §11。

---

3.1 §1.1 创建订单

路径：POST /v3/admin/order 使用场景：定制师 B 端代下单（电话 / 微信 / 线下渠道）。客户自助下单走 mp 端不在本模块。 认证：JWT（admin 角色） | 幂等性：否 | 限流：无

入参（OrderCreateReqVO，13 字段）

字段	类型	必填	说明	校验规则
productId	Long	✅	产品 ID	@NotNull
tierSeq	Integer	✅	档位序号	@NotNull
departureDate	LocalDate	✅	出发日期	@NotNull
adultCount	Integer	✅	成人数	@NotNull @Min(1)
childCount	Integer	❌	儿童数	@Min(0)，默认 0
youngChildCount	Integer	❌	幼儿数	@Min(0)，默认 0
babyCount	Integer	❌	婴儿数	@Min(0)，默认 0
customerName	String	✅	客户姓名	@NotBlank
customerPhone	String	✅	客户手机（明文传，11 位数字）	@NotBlank
customerRemark	String	❌	客户备注	@Size(max=500)
createSource	String	❌	创建来源（不传默认 CONSULTANT）	枚举见 §6.1
groupBatchId	Long	❌	拼团批次 ID（自由出团传空）	—
roomCount	Integer	❌	房间数	@Min(1)
tags	List<String>	❌	订单标签名列表	—

出参（Result<OrderCreateRespVO>，20 字段）

字段	类型	说明
id	String	订单主键
orderNo	String	订单号，格式 HL{yyyyMMddHHmmss}{3 位序号}
displayOrderNo	String	展示订单号 = orderNo + teamNo；teamNo 为空时等同 orderNo
orderStatus	String	创单后固定 待支付（枚举见 §6.2）
flowStatus	String	创单后固定 待支付订金（枚举见 §6.3）
consultantId	String	实际绑定的定制师 ID
consultantSource	String	定制师来源（枚举见 §6.4）
tags	List<String>	标签列表（含入参 tags + 系统自动标签）
createdAt	LocalDateTime	创单时间
productName	String	产品名称
tierName	String	档位名
groupBatchName	String?	拼团批次名（自由出团时 null）
departureDate	LocalDate	出发日
returnDate	LocalDate	返团日
totalAmount	BigDecimal	订单总价（元，2 位小数）
depositAmount	BigDecimal	建议定金金额
depositRatio	Integer	定金比例百分比（DEPOSIT 模式有值；FULL 模式恒为 100）
paymentMode	String	支付模式（枚举见 §6.5）
expiryMinutes	Integer	支付时限分钟数，默认 1440
payUrl	String	支付页绝对 URL
customerName	String	客户姓名（回显）

错误码

code	含义
510101	产品不存在 / 已下架
510102	档位不存在
510103	出发日期早于今天
510104	出发日期超过报名截止
510105	拼团批次不存在 / 已满员
510106	总人数 = 0
510107	createSource 枚举非法
510108	客户手机格式非法
510109	系统未配置默认定制师
581013	定制师 ID 缺失（admin 端 JWT adminId 缺失）
581014	产品域 Feign 调用失败
581015	产品域返回产品不存在
581020	MQ 事件发布失败（非主路径，记审计）
581021	跨公司访问被拒（公司隔离）

业务边界

• ✅ 适用：产品上架；档位有效；出发日期 ≥ 今天；总人数 ≥ 1；客户手机合法
• ❌ 拒绝：产品下架 / 出发日期过期 / 总人数 0 / 拼团满员 / 客户手机非 11 位
• ⚠️ 可选字段省略：不传 createSource 用默认 CONSULTANT / 不传 roomCount 返 null / 不传 tags 仅含系统自动标签

示例

典型成功 - 请求：

POST /v3/admin/order
Authorization: Bearer {admin_jwt}
Content-Type: application/json

{
  "productId": 30001234567,
  "tierSeq": 1,
  "departureDate": "2026-06-01",
  "adultCount": 2,
  "childCount": 1,
  "customerName": "张三",
  "customerPhone": "13800002046",
  "customerRemark": "希望住朝阳房",
  "createSource": "CONSULTANT",
  "groupBatchId": 80001234567890,
  "roomCount": 2,
  "tags": ["VIP 客户"]
}

典型成功 - 响应：

{
  "code": 200,
  "data": {
    "id": "60123456789012",
    "orderNo": "HL20260518220000001",
    "displayOrderNo": "HL20260518220000001",
    "orderStatus": "待支付",
    "flowStatus": "待支付订金",
    "consultantId": "50001234567890",
    "consultantSource": "DEFAULT_ASSIGNED",
    "tags": ["VIP 客户", "含儿童"],
    "createdAt": "2026-05-18T22:00:00",
    "productName": "长白山天池3日深度游",
    "tierName": "经典档",
    "groupBatchName": "第 2 期",
    "departureDate": "2026-06-01",
    "returnDate": "2026-06-03",
    "totalAmount": 8580.00,
    "depositAmount": 2574.00,
    "depositRatio": 30,
    "paymentMode": "DEPOSIT",
    "expiryMinutes": 1440,
    "payUrl": "https://pay.hulalv.com/pay/HL20260518220000001",
    "customerName": "张三"
  },
  "msg": "success"
}

异常（拼团满员 510105） - 请求：（同上，但 groupBatchId 指向已满批次）

异常 - 响应：

{ "code": 510105, "data": null, "msg": "拼团批次不存在或已满员" }

---

3.2 §1.2 订单列表

路径：GET /v3/admin/order 使用场景：定制师 / 主管 / 客服多维度筛选订单 认证：JWT（admin 角色） | 分页：继承 PageParam

入参（OrderListReqVO extends PageParam）

字段	类型	必填	说明
page	Integer	❌	页码，默认 1
pageSize	Integer	❌	每页条数，默认 10
orderStatus	String	❌	粗状态过滤（多值用逗号）
flowStatus	String	❌	细状态过滤
tagNames	List<String>	❌	按标签过滤（多标签为 AND）
keyword	String	❌	关键字（LIKE 团号 / 客户姓名 / 产品名 / 订单号 任一）
departureDateFrom	LocalDate	❌	出发日期范围起始
departureDateTo	LocalDate	❌	出发日期范围结束
createSource	String	❌	来源过滤（枚举见 §6.1）
cancelled	Boolean	❌	是否含已取消（默认 false）

出参（Result<PageResult<OrderListItemRespVO>>）

PageResult 字段：list: List<OrderListItemRespVO> / total: Long / page / pageSize

OrderListItemRespVO（17 字段）：

字段	类型	说明
id	String	订单 ID
orderNo	String	订单号
displayOrderNo	String	完整展示订单号
productName	String	产品名（快照）
productCoverImg	String	产品封面 URL
tierName	String	档位名（快照）
customerName	String	客户姓名
customerPhoneMasked	String	客户手机（脱敏 138****2046）
peopleSummary	String	人数摘要（"2 大 1 小"）
departureDate	LocalDate?	出发日（未定时 null）
tripDays	Integer	行程天数
orderStatus	String	粗状态（枚举见 §6.2）
flowStatus	String	细状态（枚举见 §6.3）
totalAmount	BigDecimal	订单金额
paidAmount	BigDecimal	实付金额
balanceAmount	BigDecimal	待付金额
consultantName	String	定制师姓名
tags	List<String>	标签列表
createdAt	LocalDateTime	创单时间

错误码

参数格式错误走全局 400，无业务错误码。

业务边界

• ✅ 默认行为：cancelled 不传 = 不含已取消订单
• ⚠️ 关键字：keyword 同时 LIKE 4 字段（团号 / 客户姓名 / 产品名 / 订单号）任一命中
• ⚠️ 标签过滤：tagNames 多值是 AND（订单必须含全部标签才命中），不是 OR

示例

典型 - 请求：

GET /v3/admin/order?page=1&pageSize=10&orderStatus=待出行&tagNames=VIP%20%E5%AE%A2%E6%88%B7
Authorization: Bearer {admin_jwt}

典型 - 响应：

{
  "code": 200,
  "data": {
    "list": [
      {
        "id": "60123456789012",
        "orderNo": "HL20260510143025001",
        "displayOrderNo": "HL20260510143025001-T20260601A",
        "productName": "长白山天池3日深度游",
        "productCoverImg": "https://oss.hulalv.com/p/changbai-cover.jpg",
        "tierName": "经典档",
        "customerName": "张三",
        "customerPhoneMasked": "138****2046",
        "peopleSummary": "2 大 1 小",
        "departureDate": "2026-06-01",
        "tripDays": 3,
        "orderStatus": "待出行",
        "flowStatus": "待出行",
        "totalAmount": 8580.00,
        "paidAmount": 8580.00,
        "balanceAmount": 0.00,
        "consultantName": "李定制",
        "tags": ["VIP 客户", "二次复购"],
        "createdAt": "2026-05-10T14:30:25"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 10
  },
  "msg": "success"
}

---

3.3 §1.3.1 订单详情主聚合

路径：GET /v3/admin/order/{id} 使用场景：详情页首屏加载——一次请求拿到主单 + 标签 + 概览（出行人 / 备注 / 紧急联系人）；Tab 详情按需懒加载（§1.3.2 ~ §1.3.7） 认证：JWT + 公司隔离 | 响应规模：精简，不含 6 Tab 子接口数据

📌 本接口只返回 main / tags / overview 3 个顶层字段。原 v5.48 设计的"一次返 9 Tab 全部数据"已拆分：finance / itinerary / contractInsurance / serviceStandard / statusLog / refund 移到 §1.3.2 ~ §1.3.7 独立懒加载接口。

入参

字段	类型	必填	说明
id	Long	✅	订单 ID（path）

出参（Result<OrderDetailRespVO>，3 顶层字段）

字段	类型	说明
main	OrderMainVO	订单主单 + 异常态横条 + progressStepper 步骤进度条
tags	List<TagVO>	标签列表
overview	OverviewVO	Tab 1 概览（出行人 + 备注 + 紧急联系人）

OrderMainVO 关键字段：

字段	类型	说明
id	String	订单 ID
displayOrderNo	String	完整展示订单号
productName / tierName	String	产品名 / 档位名（快照）
orderStatus	String	粗状态（枚举见 §6.2）
flowStatus	String	细状态（枚举见 §6.3）
totalAmount / paidAmount / balanceAmount	BigDecimal	金额三件套
departureDate / returnDate	LocalDate	出发日 / 返团日
tripDays / tripNights	Integer	行程天数 / 晚数
adultCount / childCount / youngChildCount / babyCount	Integer	4 类人数
customerName / customerPhone	String	客户姓名 / 手机（admin 明文）
consultantName	String	定制师姓名
confirmedAt	LocalDateTime?	确认锁单时间
exceptionBadges	Object	异常态横条 9 类标识（见下方）
progressStepper	Object	步骤进度条（见下方）

exceptionBadges 9 类布尔字段（全 false 表示无异常）：contractFail / insuranceFail / refundAbnormal / grabTimeout / hotelPending / vehiclePending / travelerIncomplete / longUnpaid / awaitingCustomerConfirm

progressStepper：currentStage (String) + nodes 数组，每节点 {key, label, status, subItems?}

• 节点 key 枚举：INFO_COMPLETE / ASSIGN_PARALLEL / CONFIRM / DEPARTED / RETURNED / REVIEW / SETTLED
• 节点 status：DONE / ACTIVE / PENDING
• ASSIGN_PARALLEL 含 subItems：HOTEL / VEHICLE / LEADER / PHOTOGRAPHER 子项

TagVO：name / type（枚举见 §6.15） / color

OverviewVO 关键字段：

字段	类型	说明
travelers	List<TravelerVO>	出行人完整集合（复用 traveler 模块 TravelerVO，含证件 / 性别 / 生日 / 民族 / 手机 / 紧急联系人 / 同住分组等，admin 明文）
customerRemark	String?	客户备注
consultantRemark	String?	定制师备注
emergencyContactName	String?	紧急联系人姓名
emergencyContactPhone	String?	紧急联系人手机

TravelerVO 字段口径详见 traveler 模块 §2.1 出行人列表 changelog。

错误码

code	含义
581020	订单不存在
581021	无权访问该订单（公司隔离）

业务边界

• ✅ 首屏一次请求拿全 main + tags + overview
• ⚠️ 6 Tab 数据不在本响应，按需调 §1.3.2 ~ §1.3.7 子接口
• ⚠️ 跨公司访问 → 581021

示例

典型 - 请求：

GET /v3/admin/order/60123456789012
Authorization: Bearer {admin_jwt}

典型 - 响应：

{
  "code": 200,
  "data": {
    "main": {
      "id": "60123456789012",
      "displayOrderNo": "HL20260510143025001-T20260601A",
      "productName": "长白山天池3日深度游",
      "tierName": "经典档",
      "orderStatus": "待出行",
      "flowStatus": "待出行",
      "totalAmount": 8580.00,
      "paidAmount": 8580.00,
      "balanceAmount": 0.00,
      "departureDate": "2026-06-01",
      "returnDate": "2026-06-03",
      "tripDays": 3,
      "tripNights": 2,
      "adultCount": 2,
      "childCount": 1,
      "youngChildCount": 0,
      "babyCount": 0,
      "customerName": "张三",
      "customerPhone": "13800002046",
      "consultantName": "李定制",
      "confirmedAt": "2026-05-12T10:25:00",
      "exceptionBadges": {
        "contractFail": false, "insuranceFail": false, "refundAbnormal": false,
        "grabTimeout": false, "hotelPending": false, "vehiclePending": false,
        "travelerIncomplete": false, "longUnpaid": false, "awaitingCustomerConfirm": false
      },
      "progressStepper": {
        "currentStage": "RETURNED",
        "nodes": [
          {"key": "INFO_COMPLETE", "label": "补全信息", "status": "DONE"},
          {"key": "ASSIGN_PARALLEL", "label": null, "status": "DONE", "subItems": [
            {"key": "HOTEL", "label": "配房", "subStatus": "DONE", "applicable": true},
            {"key": "VEHICLE", "label": "配车", "subStatus": "DONE", "applicable": true},
            {"key": "LEADER", "label": "配领队", "subStatus": "DONE", "applicable": true},
            {"key": "PHOTOGRAPHER", "label": "配摄影", "subStatus": "DONE", "applicable": true}
          ]},
          {"key": "CONFIRM",  "label": "确认", "status": "DONE"},
          {"key": "DEPARTED", "label": "出行", "status": "DONE"},
          {"key": "RETURNED", "label": "返团", "status": "ACTIVE"},
          {"key": "REVIEW",   "label": "核单", "status": "PENDING"},
          {"key": "SETTLED",  "label": "结算", "status": "PENDING"}
        ]
      }
    },
    "tags": [
      {"name": "二次复购", "type": "SYSTEM", "color": "#52C41A"},
      {"name": "VIP 客户", "type": "PERSONAL", "color": "#FAAD14"}
    ],
    "overview": {
      "travelers": [
        {
          "id": "70123456789012",
          "orderId": "60123456789012",
          "travelerType": "ADULT",
          "name": "张三",
          "gender": "MALE",
          "birthday": "1985-08-12",
          "idType": "ID_CARD",
          "idNo": "220103198508121234",
          "nationality": "中国",
          "race": "汉族",
          "phone": "13800002046",
          "emergencyContact": "李四",
          "emergencyPhone": "13900008888",
          "roomGroupNo": 1,
          "profileStatus": "COMPLETED",
          "transportPlanIds": ["80012345"]
        }
      ],
      "customerRemark": "希望住朝阳房",
      "consultantRemark": "VIP 客户,已沟通到达接机",
      "emergencyContactName": "李四",
      "emergencyContactPhone": "13900008888"
    }
  },
  "msg": "success"
}

异常（跨公司访问 581021） - 请求：（admin JWT 不属于订单所属公司）

GET /v3/admin/order/60999999999999
Authorization: Bearer {admin_jwt}

异常 - 响应：

{ "code": 581021, "data": null, "msg": "无权访问该订单" }

---

3.4 §1.3.2 财务 Tab（懒加载）

路径：GET /v3/admin/order/{id}/finance 使用场景：详情页财务 Tab 单独刷新（如优惠 / 退款操作完后刷新） 认证：JWT + 公司隔离

入参

id (path, Long) — 订单 ID

出参（Result<FinanceVO>）

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

PaymentVO：id / payType（枚举见 §6.6） / amount / paidAt / status（枚举见 §6.7） DiscountVO：id / name / amount / type（枚举见 §6.8） / source（枚举见 §6.9） / createdAt SurchargeVO：id / name / amount / type / source / createdAt

错误码

code	含义
581020	订单不存在
581021	无权访问该订单

示例

典型 - 请求：

GET /v3/admin/order/60123456789012/finance
Authorization: Bearer {admin_jwt}

典型 - 响应：

{
  "code": 200,
  "data": {
    "totalAmount": 8580.00,
    "paidAmount": 8580.00,
    "balanceAmount": 0.00,
    "discountAmount": 200.00,
    "surchargeAmount": 0.00,
    "refundAmount": 0.00,
    "payments": [
      {"id": 90011, "payType": "DEPOSIT", "amount": 2000.00, "paidAt": "2026-05-10T15:00:00", "status": "SUCCESS"},
      {"id": 90012, "payType": "BALANCE", "amount": 6580.00, "paidAt": "2026-05-15T09:30:00", "status": "SUCCESS"}
    ],
    "discounts": [
      {"id": 95001, "name": "早鸟优惠", "amount": 200.00, "type": "EARLY_BIRD", "source": "MANUAL", "createdAt": "2026-05-10T14:30:00"}
    ],
    "surcharges": []
  },
  "msg": "success"
}

---

3.5 §1.3.3 合同保险 Tab（懒加载）

路径：GET /v3/admin/order/{id}/contract-insurance 使用场景：合同重签 / 保险重投后单独刷新该 Tab 响应结构：contract / insurance 两个并列子对象（前端 Tab 内上下两栏布局）

入参

id (path, Long) — 订单 ID

出参（Result<ContractInsuranceVO>）

字段	类型	说明
contract.contractStatus	String	合同状态（枚举见 §6.10）
contract.contractSignedAt	LocalDateTime?	签约时间
contract.contractFileUrl	String?	合同文件 URL
contract.events[].eventType	String	合同事件类型（枚举见 §6.11）
contract.events[].occurredAt	LocalDateTime	事件发生时间
insurance.insuranceStatus	String	保险状态（枚举见 §6.12）
insurance.insurancePolicyNo	String?	保单号
insurance.insurancePremium	BigDecimal?	保费
insurance.events[].eventType	String	保险事件类型（枚举见 §6.11）
insurance.events[].occurredAt	LocalDateTime	事件发生时间

错误码

code	含义
581020	订单不存在
581021	无权访问该订单

示例

典型 - 请求：

GET /v3/admin/order/60123456789012/contract-insurance
Authorization: Bearer {admin_jwt}

典型 - 响应：

{
  "code": 200,
  "data": {
    "contract": {
      "contractStatus": "SIGNED",
      "contractSignedAt": "2026-05-12T11:00:00",
      "contractFileUrl": "https://oss.hulalv.com/contract/HL20260510143025001.pdf",
      "events": [
        {"eventType": "GENERATE", "occurredAt": "2026-05-12T10:55:00"},
        {"eventType": "SIGN", "occurredAt": "2026-05-12T11:00:00"}
      ]
    },
    "insurance": {
      "insuranceStatus": "ACTIVE",
      "insurancePolicyNo": "PICC2026060100123",
      "insurancePremium": 88.00,
      "events": [
        {"eventType": "ISSUE", "occurredAt": "2026-05-12T11:05:00"}
      ]
    }
  },
  "msg": "success"
}

---

3.6 §1.3.4 行程安排 Tab（懒加载）⚠️ Mock

路径：GET /v3/admin/order/{id}/itinerary 使用场景：调整行程节点 / 房车配置后单独刷新

⚠️ 当前数据 Mock：行程节点 + 房车需求&实配为 Mock 数据，真实化进度见 follow-up Issue。前端可先按字段结构对接，真实化后无需改字段口径。

入参

id (path, Long) — 订单 ID

出参（Result<ItineraryVO>）

字段	类型	说明
days[].dayIndex	Integer	天序
days[].dayDate	String	日期（yyyy-MM-dd）
days[].title	String	标题
days[].nodes	List<Object>	节点列表（结构见 itinerary 模块 §5）
hotelGroup.requirement	Object	配房需求（requirementId / status / roomTypeSummary / claimedBy 等）
hotelGroup.assignments	List<Object>	实际配房（hotelName / stayDate / roomType / roomCount / unitPrice / subtotal）
vehicleGroup.requirement	Object	配车需求（requirementId / status / vehicleTypeSummary / claimedBy）
vehicleGroup.assignments	List<Object>	实际配车（vehicleType / plate / driverName / dailyFee / totalFee）

错误码

code	含义
581020	订单不存在
581021	无权访问该订单

示例

典型 - 请求：

GET /v3/admin/order/60123456789012/itinerary
Authorization: Bearer {admin_jwt}

典型 - 响应（Mock 数据示意）：

{
  "code": 200,
  "data": {
    "days": [
      {
        "dayIndex": 1,
        "dayDate": "2026-06-01",
        "title": "抵达长春-接机",
        "nodes": [
          {"nodeType": "TRANSPORT", "title": "接机", "startTime": "10:30"},
          {"nodeType": "HOTEL", "title": "入住凯悦酒店", "actualResourceName": "长春凯悦酒店"}
        ]
      }
    ],
    "hotelGroup": {
      "requirement": {
        "requirementId": "70011", "status": "DONE", "version": 2,
        "roomTypeSummary": "1 大床房×2 + 1 标间×1",
        "remark": "希望朝阳房,带浴缸优先",
        "budgetRange": "500-800/晚",
        "claimedBy": "房控-王芳", "claimedAt": "2026-05-11T14:20:00"
      },
      "assignments": [
        {"id": "80011", "hotelName": "长春凯悦酒店", "stayDate": "2026-06-01", "roomType": "大床房", "roomCount": 2, "roomGroupNo": 1, "unitPrice": 680, "subtotal": 1360}
      ]
    },
    "vehicleGroup": {
      "requirement": {
        "requirementId": "70021", "status": "DONE", "version": 1,
        "vehicleTypeSummary": "9 座商务车×1",
        "claimedBy": "车控-李强", "claimedAt": "2026-05-11T15:00:00"
      },
      "assignments": [
        {"id": "80021", "vehicleType": "MPV", "plate": "吉A·888XX", "driverName": "王师傅", "driverPhone": "138****1234", "dailyFee": 1100, "totalDays": 3, "totalFee": 3300}
      ]
    }
  },
  "msg": "success"
}

---

3.7 §1.3.5 状态记录 Tab（懒加载）

路径：GET /v3/admin/order/{id}/status-log 使用场景：执行状态变更后刷新时间线 数据来源：5 张审计表联合（status_log / payment / refund / contract_event / insurance_event）按 occurredAt desc 倒序

入参

id (path, Long) — 订单 ID

出参（Result<List<LogTimelineVO>>）

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

错误码

code	含义
581020	订单不存在
581021	无权访问该订单

示例

典型 - 请求：

GET /v3/admin/order/60123456789012/status-log
Authorization: Bearer {admin_jwt}

典型 - 响应：

{
  "code": 200,
  "data": [
    {"occurredAt": "2026-05-12T10:25:00", "operator": "李定制", "action": "确认锁单", "fromStatus": "定制中", "toStatus": "待出行"},
    {"occurredAt": "2026-05-10T15:00:00", "operator": "张三", "action": "支付订金", "amount": 2000.00},
    {"occurredAt": "2026-05-10T14:30:25", "operator": "李定制", "action": "创建订单"}
  ],
  "msg": "success"
}

---

3.8 §1.3.6 退款明细 Tab（懒加载，条件显示）

路径：GET /v3/admin/order/{id}/refund 使用场景：退款流程节点变更后刷新；前端轮询等待退款到账 空值约定：无退款时 data=null（前端据此判断是否渲染该 Tab）

入参

id (path, Long) — 订单 ID

出参（Result<RefundDetailVO> 或 Result<null>）

字段	类型	说明
totalRefundAmount	BigDecimal	合计退款金额（= finance.refundAmount）
applications[].applicationId	Long	申请 ID
applications[].status	String	进度状态（枚举见 §6.13）
applications[].statusText	String	状态描述文案
applications[].refundAmount	BigDecimal	退款金额
applications[].refundChannel	String	退款渠道（"原路退回(支付宝)"）
applications[].approverName	String?	审批人
applications[].approvedAt	LocalDateTime?	审批时间
applications[].estimatedArriveDate	LocalDate?	预计到账日期
applications[].actualArriveDate	LocalDate?	实际到账日期
applications[].progress[].step	String	步骤（枚举见 §6.14）
applications[].progress[].label	String	步骤展示标签
applications[].progress[].status	String	步骤状态（DONE / ACTIVE / PENDING）
applications[].progress[].occurredAt	LocalDateTime?	步骤发生时间
applications[].items[].itemName	String	项目名称
applications[].items[].reason	String	退款原因
applications[].items[].appliedAt	LocalDateTime	申请时间
applications[].items[].amount	BigDecimal	退款金额（负数）

错误码

code	含义
581020	订单不存在
581021	无权访问该订单

示例

典型（有退款） - 请求：

GET /v3/admin/order/60123456789012/refund
Authorization: Bearer {admin_jwt}

典型（有退款） - 响应：

{
  "code": 200,
  "data": {
    "totalRefundAmount": 4800.00,
    "applications": [
      {
        "applicationId": 60101,
        "status": "PENDING_PAYOUT",
        "statusText": "财务已审批,等待打款",
        "refundAmount": 4800.00,
        "refundChannel": "原路退回(支付宝)",
        "approverName": "财务 · 周经理",
        "approvedAt": "2026-04-25T14:20:00",
        "estimatedArriveDate": "2026-04-30",
        "actualArriveDate": null,
        "progress": [
          {"step": "APPLY",   "label": "退款申请", "status": "DONE",    "occurredAt": "2026-04-25T11:30:00"},
          {"step": "APPROVE", "label": "财务审批", "status": "DONE",    "occurredAt": "2026-04-25T14:20:00"},
          {"step": "PAYOUT",  "label": "退款打款", "status": "ACTIVE",  "occurredAt": null},
          {"step": "ARRIVED", "label": "到账确认", "status": "PENDING", "occurredAt": null}
        ],
        "items": [
          {"itemName": "主行程退款(同行小孩临时不能出行)", "reason": "同行儿童突发感冒,不参与本次出行", "appliedAt": "2026-04-25T11:30:00", "amount": -4800.00}
        ]
      }
    ]
  },
  "msg": "success"
}

边界（无退款） - 请求：（同上路径）

边界 - 响应：

{ "code": 200, "data": null, "msg": "success" }

---

3.9 §1.3.7 服务标准 Tab（懒加载，条件显示）

路径：GET /v3/admin/order/{id}/service-standard 使用场景：服务标准 Tab 单独刷新 数据来源：产品快照冻结（永不变） 空值约定：快照缺失时 data=null

入参

id (path, Long) — 订单 ID

出参（Result<ServiceStandardVO> 或 Result<null>）

字段	类型	说明
itinerary	List<String>	行程天纲（产品快照）
notice.title	String	出团注意事项标题
notice.content	String	出团注意事项内容（Markdown）
refundPolicy.policyId	Long	退改政策 ID
refundPolicy.policyName	String	退改政策名称
refundPolicy.tiers[].minDays	Integer	出发前最小天数
refundPolicy.tiers[].refundRatio	Integer	退款比例（百分比 0-100）
refundPolicy.tiers[].label	String	展示文案

错误码

code	含义
581020	订单不存在
581021	无权访问该订单

示例

典型 - 请求：

GET /v3/admin/order/60123456789012/service-standard
Authorization: Bearer {admin_jwt}

典型 - 响应：

{
  "code": 200,
  "data": {
    "itinerary": ["Day1 抵达长春-接机入住", "Day2 长白山天池1日游", "Day3 返程"],
    "notice": {
      "title": "长白山天池 3 日深度游 - 出团注意事项",
      "content": "# 出团必读\n\n1. 高原反应：海拔 2691m，请提前服用红景天\n2. 天气：山顶常年低于 0℃，请备厚外套\n..."
    },
    "refundPolicy": {
      "policyId": 50001,
      "policyName": "标准退改政策",
      "tiers": [
        {"minDays": 15, "refundRatio": 100, "label": "出发前 15 天 100%退"},
        {"minDays": 7, "refundRatio": 80, "label": "出发前 7-14 天 80%退"},
        {"minDays": 3, "refundRatio": 50, "label": "出发前 3-6 天 50%退"},
        {"minDays": 0, "refundRatio": 0, "label": "出发前 2 天内不退"}
      ]
    }
  },
  "msg": "success"
}

---

3.10 §1.4 修改订单字段

路径：PUT /v3/admin/order/{id} 使用场景：修改订单非关键字段（备注 / 紧急联系人 / 客户信息 / 转单），不触发状态机 关键字段约定：订单金额 / 状态等不允许在此接口改，需走专用接口 语义：PATCH（传哪个改哪个） 审计：每次修改写 1 行 order_status_log（即使状态未变也记录"字段被改"）

入参（OrderUpdateReqVO，PATCH 语义）

字段	类型	必填	说明
customerName	String	❌	客户姓名
customerPhone	String	❌	客户手机
emergencyContactName	String	❌	紧急联系人姓名
emergencyContactPhone	String	❌	紧急联系人电话
customerRemark	String	❌	客户备注
consultantRemark	String	❌	定制师备注
targetConsultantId	Long	❌	转单目标定制师 ID（仅主管 / 客服角色可传）
transferReason	String	❌	转单原因（传 targetConsultantId 时必填）

出参（Result<Boolean>）

返回 true 表示成功，false 表示无字段实际变化。

错误码

code	含义
581020	订单不存在
581021	无权访问该订单
581030	转单目标定制师不存在
581031	转单原因为空（传 targetConsultantId 时）
581032	当前角色无转单权限（仅主管 / 客服可转单）

业务边界

• ✅ 可改字段：备注 / 紧急联系人 / 客户信息 / 转单（仅主管 / 客服角色）
• ❌ 不可改字段：订单金额 / 订单状态 / 出发日期 / 出行人数 / 拼团批次 → 需走专用接口
• ⚠️ 转单约束：传 targetConsultantId 必须同时传 transferReason
• ⚠️ PATCH 语义：不传 = 不改；传空字符串 = 改成空（区分两者）

示例

典型（转单） - 请求：

PUT /v3/admin/order/60123456789012
Authorization: Bearer {admin_jwt}
Content-Type: application/json

{
  "targetConsultantId": 50009876543210,
  "transferReason": "客户主动申请更换定制师",
  "consultantRemark": "已联系新定制师"
}

典型 - 响应：

{ "code": 200, "data": true, "msg": "success" }

异常（转单缺原因 581031） - 请求：

PUT /v3/admin/order/60123456789012
Authorization: Bearer {admin_jwt}
Content-Type: application/json

{
  "targetConsultantId": 50009876543210
}

异常 - 响应：

{ "code": 581031, "data": null, "msg": "转单原因为空" }

---

6. 枚举 / 数据字典

跨接口共享枚举集中列出，按字段分组，标注「使用字段在哪里」。

6.1 createSource（订单创建来源）

使用字段：§3.1 入参 createSource / §3.2 入参 createSource 过滤

值	中文	说明
CUSTOMER	客户自助	客户在小程序自助下单
CONSULTANT	定制师代下单	默认值
OTA	OTA 渠道	携程 / 美团等 OTA 引流
WALK_IN	门店步入	线下门店现场下单
B2B	B2B 渠道	旅行社代下单
VIP_REPURCHASE	VIP 复购	—
REFERRAL	老客户转介绍	—
PROMOTION	营销活动	—
INTERNAL	内部测试	不计入业绩

6.2 orderStatus（订单粗状态）

使用字段：§3.1 出参 / §3.2 出参 / §3.3 main / §3.2 入参过滤

值	说明
待支付	创单后默认
待完善	订金到账后进入
定制中	出行人 + 房车齐后
已确认	—
出行中	—
已完成	—
已取消	—

6.3 flowStatus（订单细状态）

使用字段：§3.1 出参 / §3.2 出参 / §3.3 main / §3.2 入参过滤

值	说明
待支付订金	创单后默认细状态
待支付尾款	—
待补全信息	订金到账后
待提交房型	—
待抢房	—
配房中	—
待提交用车	—
车控处理中	—
待确认	房车齐后
待出行	确认锁单后
出行中	—
已完成	—
已取消	—

完整 flowStatus 枚举见订单状态机文档（§1C 推送时补全）。

6.4 consultantSource（定制师分配来源）

使用字段：§3.1 出参 / §3.3 main

值	说明
DEFAULT_ASSIGNED	系统默认分配（轮询）
LINK_BOUND	链接绑定（客户扫定制师专属码）
MANUAL	手动指定

6.5 paymentMode（支付模式）

使用字段：§3.1 出参

值	说明
DEPOSIT	定金模式（30% 定金 + 余款）
FULL	全款模式（100% 一次付清）

6.6 payType（支付类型）

使用字段：§3.4 出参 payments[].payType

值	说明
DEPOSIT	定金
BALANCE	尾款

6.7 payment status（支付记录状态）

使用字段：§3.4 出参 payments[].status

值	说明
SUCCESS	成功
PENDING	处理中
FAIL	失败

6.8 discount type（优惠类型）

使用字段：§3.4 出参 discounts[].type

值	说明
EARLY_BIRD	早鸟优惠
VIP	VIP 优惠
COUPON	优惠券
PROMOTION	营销活动优惠

6.9 discount source（优惠 / 附加费来源）

使用字段：§3.4 出参 discounts[].source / surcharges[].source

值	说明
MANUAL	手动添加（定制师人工）
AUTO	系统自动
HOTEL_ASSIGN	配房环节产生（仅 surcharge）
VEHICLE_ASSIGN	配车环节产生（仅 surcharge）

6.10 contractStatus（合同状态）

使用字段：§3.5 出参 contract.contractStatus

值	说明
PENDING	待生成
GENERATED	已生成待签
SIGNED	已签约
VOIDED	已作废

6.11 event type（合同 / 保险事件类型）

使用字段：§3.5 出参 contract.events[].eventType / insurance.events[].eventType

值	说明
GENERATE	合同生成
SIGN	合同签约
VOID	合同作废
REOPEN	合同重开
ISSUE	保险出单
CANCEL	保险退保

6.12 insuranceStatus（保险状态）

使用字段：§3.5 出参 insurance.insuranceStatus

值	说明
PENDING	待出单
ACTIVE	已生效
FAILED	出单失败
CANCELLED	已退保

6.13 refund application status（退款申请状态）

使用字段：§3.8 出参 applications[].status

值	说明
PENDING_APPROVE	待审批
PENDING_PAYOUT	财务已审批，待打款
PENDING_ARRIVAL	已打款，待到账
COMPLETED	退款完成（已到账）
REJECTED	已拒绝

6.14 refund progress step（退款进度步骤）

使用字段：§3.8 出参 applications[].progress[].step

值	说明
APPLY	退款申请
APPROVE	财务审批
PAYOUT	退款打款
ARRIVED	到账确认

6.15 tag type（标签类型）

使用字段：§3.3 出参 tags[].type

值	说明
SYSTEM	系统自动打的标签
PERSONAL	定制师手动打的标签
MANUAL	主管手动打的标签

6.16 traveler & exception badge（出行人 / 异常态字段）

OverviewVO.travelers[] 的 travelerType / idType / profileStatus 等枚举详见 traveler 模块 §2.1 出行人列表 changelog。

OrderMainVO.exceptionBadges 9 类布尔标识 / progressStepper.nodes[].key / progressStepper.nodes[].status 字段含义已在 §3.3 出参说明中列出。

---

11. 影响评估

• 是否破坏向后兼容：否（v3 全新二期，前端 v3 项目仓库首次消费）
• 前端是否必须同步上线：是
• 本次推送范围：§1A 10 接口；§1B 取消订单 / §1C 状态机后续 commit 追加

---

12. 注意事项

• §3.6 itinerary 子接口数据 Mock：当前返回占位数据，前端按字段结构对接即可，真实化后无需改字段口径
• §3.8 / §3.9 条件显示：data=null 时前端不渲染对应 Tab
• 首屏 vs 单 Tab 刷新：详情页打开用 §3.3 主聚合（一次拿 main + tags + overview）；Tab 切换 / 单 Tab 操作完按需调 §3.4 ~ §3.9
• 公司隔离 581021：所有 §1 接口均带跨公司隔离校验，前端无需自行过滤

---

13. 关联

• API 设计文档: docs/order-v3/api/API-SPEC-V5.49.html §1.1 ~ §1.4
• SRS 业务规格: docs/order-v3/srs/order-cloud-v3-srs-v5.49.html §F1 创单 / §1.0i 模型 / §1.3 创单流程
• 数据库 Schema: docs/order-v3/database/DATABASE-SCHEMA-V5.49.html §1.1 order_main / §1.2 order_tag
• 后端负责人: @yaosutu

---

📝 §1B / §1C 推送计划

• §1B 取消订单（§1.5.0 + §1.5.1 + §1.5.2）：业务联调通过后 commit 追加本文件
• §1C 状态机 + 锁单（§1.7 + §1.8）：状态机完整测试通过后 commit 追加