From 87fd82c56df391231ad421a9321d51f1608ee07c Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Mon, 18 May 2026 16:17:59 +0800 Subject: [PATCH] =?UTF-8?q?docs(order-v3):=20=C2=A71=20core=20=E6=A8=A1?= =?UTF-8?q?=E5=9D=97=E9=A6=96=E6=8E=A8=20=C2=A71A=EF=BC=8810=20=E6=8E=A5?= =?UTF-8?q?=E5=8F=A3=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 订单核心模块全新二期首推，含订单 CRUD + 详情主聚合 + 6 Tab 子接口 + 修改字段： §1.1 POST /v3/admin/order 创建订单 §1.2 GET /v3/admin/order 订单列表 §1.3.1 GET /v3/admin/order/{id} 详情主聚合 §1.3.2 GET .../finance 财务 Tab §1.3.3 GET .../contract-insurance 合同保险 Tab §1.3.4 GET .../itinerary 行程 Tab（⚠️ Mock） §1.3.5 GET .../status-log 状态记录 Tab §1.3.6 GET .../refund 退款明细 Tab §1.3.7 GET .../service-standard 服务标准 Tab §1.4 PUT /v3/admin/order/{id} 修改订单字段 883 行 / 13 节齐全 / 15 枚举按使用字段分组 / 8 组示例（典型+边界+异常）。 §1B 取消订单 / §1C 状态机后续 commit 追加同一文件。 设计文档同步升 v5.49（API/SRS/DETAIL/DB 4 份 HTML）。 --- .../18_§1_订单核心模块-新增接口-管理后台.md | 883 ++++++++++++++++++ 1 file changed, 883 insertions(+) create mode 100644 changelogs-v2/2026-05/18_§1_订单核心模块-新增接口-管理后台.md diff --git a/changelogs-v2/2026-05/18_§1_订单核心模块-新增接口-管理后台.md b/changelogs-v2/2026-05/18_§1_订单核心模块-新增接口-管理后台.md new file mode 100644 index 0000000..e063323 --- /dev/null +++ b/changelogs-v2/2026-05/18_§1_订单核心模块-新增接口-管理后台.md @@ -0,0 +1,883 @@ +# 【新增接口·管理后台】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. 接口详情 + +### 3.1 创建订单（§1.1） + +- **使用场景**：定制师代下单（电话 / 微信 / 线下渠道）。客户自助下单走 mp 端不在本模块。 +- **认证**：JWT（admin 角色） +- **幂等性**：否 +- **限流**：无 + +### 3.2 订单列表（§1.2） + +- **使用场景**：定制师 / 主管 / 客服多维度筛选订单 +- **认证**：JWT（admin 角色） +- **支持过滤**：粗状态 / 细状态 / 标签（AND） / 关键字 / 出发日期范围 / 来源 / 是否含已取消 +- **分页**：继承 PageParam（`page` / `pageSize`） + +### 3.3 订单详情主聚合（§1.3.1） + +- **使用场景**：详情页**首屏加载**——一次请求拿全订单 + 9 Tab 数据 +- **认证**：JWT（admin 角色 + 公司隔离校验） +- **公司隔离**：调用方 adminId 跨公司访问返 `581021` + +### 3.4 财务 Tab 子接口（§1.3.2） + +- **使用场景**：详情页**单 Tab 刷新**——财务 Tab 内操作（优惠/退款）后单独刷此 Tab，避免重拉整页 +- **认证**：JWT + 公司隔离 + +### 3.5 合同保险 Tab 子接口（§1.3.3） + +- **使用场景**：合同重签 / 保险重投后单独刷新这个 Tab +- **响应结构**：`contract` / `insurance` 两个并列子对象，前端在 Tab 内上下两栏布局 + +### 3.6 行程安排 Tab 子接口（§1.3.4） + +- **使用场景**：调整行程节点 / 房车配置后单独刷新 +- **⚠️ 当前数据 Mock**：行程节点 + 房车需求&实配为 Mock 数据，真实化进度见后端 follow-up Issue + +### 3.7 状态记录 Tab 子接口（§1.3.5） + +- **使用场景**：执行 transition 等状态变更后刷新时间线 +- **数据来源**：5 张审计表联合（status_log / payment / refund / contract_event / insurance_event）按 `occurredAt desc` 倒序 + +### 3.8 退款明细 Tab 子接口（§1.3.6） + +- **使用场景**：退款流程节点变更后刷新 +- **空值约定**：无退款时 `data=null`（前端据此判断是否显示 Tab） + +### 3.9 服务标准 Tab 子接口（§1.3.7） + +- **使用场景**：详情页"服务标准" Tab 单独刷新 +- **数据来源**：产品快照冻结（永不变） +- **空值约定**：快照缺失时 `data=null` + +### 3.10 修改订单字段（§1.4） + +- **使用场景**：修改订单**非关键字段**（备注 / 紧急联系人 / 客户信息 / 转单等），不触发状态机 +- **关键字段约定**：订单金额 / 状态等不允许在此接口改，需走专用接口 +- **审计**：每次修改写 1 行 `order_status_log`（即使状态未变也记录"字段被改"） + +--- + +## 4. 接口入参 + +### 4.1 §1.1 创建订单（`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`） | `@Size(max=20)`，枚举见 §6.1 | +| `groupBatchId` | Long | ❌ | 拼团批次 ID（自由出团传空） | — | +| `roomCount` | Integer | ❌ | 房间数 | `@Min(1)` | +| `tags` | List\ | ❌ | 订单标签名列表 | — | + +### 4.2 §1.2 订单列表（`OrderListReqVO extends PageParam`） + +| 字段 | 类型 | 必填 | 说明 | +|------|------|:----:|------| +| `page` | Integer | ❌ | 页码，默认 1（继承 PageParam） | +| `pageSize` | Integer | ❌ | 每页条数，默认 10（继承 PageParam） | +| `orderStatus` | String | ❌ | 粗状态过滤（多值用逗号） | +| `flowStatus` | String | ❌ | 细状态过滤 | +| `tagNames` | List\ | ❌ | 按标签过滤（多标签为 AND） | +| `keyword` | String | ❌ | 搜索关键字（匹配 团号 / 客户姓名 / 产品名 / 订单号 任一字段 LIKE） | +| `departureDateFrom` | LocalDate | ❌ | 出发日期范围起始 | +| `departureDateTo` | LocalDate | ❌ | 出发日期范围结束 | +| `createSource` | String | ❌ | 来源过滤（枚举见 §6.1） | +| `cancelled` | Boolean | ❌ | 是否含已取消（默认 false） | + +### 4.3 §1.3.1 ~ §1.3.7 详情主聚合 + 6 Tab 子接口 + +**全部统一入参**：`id` (path, Long) — 订单 ID + +### 4.4 §1.4 修改订单字段（`OrderUpdateReqVO`，PATCH 语义） + +| 字段 | 类型 | 必填 | 说明 | +|------|------|:----:|------| +| `customerName` | String | ❌ | 客户姓名 | +| `customerPhone` | String | ❌ | 客户手机 | +| `emergencyContactName` | String | ❌ | 紧急联系人姓名 | +| `emergencyContactPhone` | String | ❌ | 紧急联系人电话 | +| `customerRemark` | String | ❌ | 客户备注 | +| `consultantRemark` | String | ❌ | 定制师备注 | +| `targetConsultantId` | Long | ❌ | 转单目标定制师 ID（仅主管 / 客服角色可传） | +| `transferReason` | String | ❌ | 转单原因（传 `targetConsultantId` 时必填） | + +> 所有字段可空，传哪个改哪个（PATCH 语义）。 + +--- + +## 5. 出参 + +### 5.1 §1.1 创建订单（`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\ | 标签列表（含入参 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 | 客户姓名（回显） | + +### 5.2 §1.2 订单列表（`Result>`） + +`PageResult` 字段：`list: List` / `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\ | 标签列表 | +| `createdAt` | LocalDateTime | 创单时间 | + +### 5.3 §1.3.1 订单详情主聚合（`Result`） + +包含 9 个顶层字段： + +| 字段 | 类型 | 说明 | +|------|------|------| +| `main` | OrderMainVO | 订单主单 + 异常态横条 9 类标识 + `progressStepper` 步骤进度条 | +| `tags` | List\ | 标签列表（`name` / `type` / `color`） | +| `overview` | OverviewVO | Tab 1 概览（含 travelers[] 出行人完整集合，详见 traveler 模块文档 §2.1） | +| `finance` | FinanceVO | Tab 4 财务（结构同 §5.4） | +| `itinerary` | ItineraryVO | Tab 2 行程（结构同 §5.6） | +| `contractInsurance` | ContractInsuranceVO | Tab 3 合同保险（结构同 §5.5） | +| `serviceStandard` | ServiceVO | Tab 5 服务标准（结构同 §5.9） | +| `statusLog` | List\ | Tab 7 记录（结构同 §5.7） | +| `refund` | RefundDetailVO? | Tab 9 退款明细（无退款时 null，结构同 §5.8） | + +`OrderMainVO.exceptionBadges`（异常态横条 9 类标识）：`contractFail / insuranceFail / refundAbnormal / grabTimeout / hotelPending / vehiclePending / travelerIncomplete / longUnpaid / awaitingCustomerConfirm`（全 false 表示无异常） + +`OrderMainVO.progressStepper`（步骤进度条）：`currentStage` + `nodes: [{key, label, status, subItems?}]`，节点 key 枚举：`INFO_COMPLETE / ASSIGN_PARALLEL / CONFIRM / DEPARTED / RETURNED / REVIEW / SETTLED`；节点 status：`DONE / ACTIVE / PENDING` + +### 5.4 §1.3.2 财务 Tab（`Result`） + +| 字段 | 类型 | 说明 | +|------|------|------| +| `totalAmount` | BigDecimal | 订单总额 | +| `paidAmount` | BigDecimal | 实付金额 | +| `balanceAmount` | BigDecimal | 待付金额 | +| `discountAmount` | BigDecimal | 优惠金额汇总 | +| `surchargeAmount` | BigDecimal | 附加费用汇总 | +| `refundAmount` | BigDecimal | 退款金额汇总 | +| `payments` | List\ | 支付明细 | +| `discounts` | List\ | 优惠明细 | +| `surcharges` | List\ | 附加费用 | + +`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`（`MANUAL` / `AUTO`） / `source`（`HOTEL_ASSIGN` / `VEHICLE_ASSIGN` / ...） / `createdAt` + +### 5.5 §1.3.3 合同保险 Tab（`Result`） + +| 字段 | 类型 | 说明 | +|------|------|------| +| `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 | 事件发生时间 | + +### 5.6 §1.3.4 行程安排 Tab（`Result`）⚠️ Mock + +| 字段 | 类型 | 说明 | +|------|------|------| +| `days[].dayIndex` | Integer | 天序 | +| `days[].dayDate` | String | 日期（`yyyy-MM-dd`） | +| `days[].title` | String | 标题 | +| `days[].nodes` | List\ | 节点列表（结构见 itinerary 模块 §5） | +| `hotelGroup.requirement` | Object | 配房需求（`requirementId / status / roomTypeSummary / claimedBy` 等） | +| `hotelGroup.assignments` | List\ | 实际配房（`hotelName / stayDate / roomType / roomCount / unitPrice / subtotal`） | +| `vehicleGroup.requirement` | Object | 配车需求（`requirementId / status / vehicleTypeSummary / claimedBy`） | +| `vehicleGroup.assignments` | List\ | 实际配车（`vehicleType / plate / driverName / dailyFee / totalFee`） | + +### 5.7 §1.3.5 状态记录 Tab（`Result>`） + +| 字段 | 类型 | 说明 | +|------|------|------| +| `occurredAt` | LocalDateTime | 发生时间 | +| `operator` | String | 操作人 | +| `action` | String | 操作描述 | +| `fromStatus` | String? | 变更前状态（有状态变更时有值） | +| `toStatus` | String? | 变更后状态 | +| `amount` | BigDecimal? | 涉及金额（支付/退款时有值） | + +按 `occurredAt desc` 倒序。 + +### 5.8 §1.3.6 退款明细 Tab（`Result` 或 `data=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 | 退款金额（负数） | + +### 5.9 §1.3.7 服务标准 Tab（`Result` 或 `data=null`） + +| 字段 | 类型 | 说明 | +|------|------|------| +| `itinerary` | List\ | 行程天纲（产品快照） | +| `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 | 展示文案 | + +### 5.10 §1.4 修改订单字段（`Result`） + +返回 `true` 表示成功，`false` 表示无字段实际变化。 + +--- + +## 6. 枚举 / 数据字典 + +### 6.1 createSource（订单创建来源） + +**使用字段**：入参 §4.1 `createSource` / 入参 §4.2 `createSource` 过滤 + +| 值 | 中文 | 说明 | +|----|------|------| +| `CUSTOMER` | 客户自助 | 客户在小程序自助下单 | +| `CONSULTANT` | 定制师代下单 | 默认值 | +| `OTA` | OTA 渠道 | 携程 / 美团等 OTA 引流 | +| `WALK_IN` | 门店步入 | 线下门店现场下单 | +| `B2B` | B2B 渠道 | 旅行社代下单 | +| `VIP_REPURCHASE` | VIP 复购 | — | +| `REFERRAL` | 老客户转介绍 | — | +| `PROMOTION` | 营销活动 | — | +| `INTERNAL` | 内部测试 | 不计入业绩 | + +### 6.2 orderStatus（订单粗状态） + +**使用字段**：出参 §5.1 / §5.2 / §5.3 main / 入参 §4.2 过滤 + +| 值 | 说明 | +|----|------| +| `待支付` | 创单后默认 | +| `待完善` | 订金到账后进入 | +| `定制中` | 出行人 + 房车齐后 | +| `已确认` | — | +| `出行中` | — | +| `已完成` | — | +| `已取消` | — | + +### 6.3 flowStatus（订单细状态） + +**使用字段**：出参 §5.1 / §5.2 / §5.3 main / 入参 §4.2 过滤 + +| 值 | 说明 | +|----|------| +| `待支付订金` | 创单后默认细状态 | +| `待支付尾款` | — | +| `待补全信息` | 订金到账后 | +| `待提交房型` | — | +| `待抢房` | — | +| `配房中` | — | +| `待提交用车` | — | +| `车控处理中` | — | +| `待确认` | 房车齐后 | +| `待出行` | 确认锁单后 | +| `出行中` | — | +| `已完成` | — | +| `已取消` | — | + +> 完整 flowStatus 枚举详见订单状态机文档（§1C 推送时补全）。 + +### 6.4 consultantSource（定制师分配来源） + +**使用字段**：出参 §5.1 / §5.3 main + +| 值 | 说明 | +|----|------| +| `DEFAULT_ASSIGNED` | 系统默认分配（轮询） | +| `LINK_BOUND` | 链接绑定（客户扫定制师专属码） | +| `MANUAL` | 手动指定 | + +### 6.5 paymentMode（支付模式） + +**使用字段**：出参 §5.1 + +| 值 | 说明 | +|----|------| +| `DEPOSIT` | 定金模式（30% 定金 + 余款） | +| `FULL` | 全款模式（100% 一次付清） | + +### 6.6 payType（支付类型） + +**使用字段**：出参 §5.4 `payments[].payType` + +| 值 | 说明 | +|----|------| +| `DEPOSIT` | 定金 | +| `BALANCE` | 尾款 | + +### 6.7 payment status（支付记录状态） + +**使用字段**：出参 §5.4 `payments[].status` + +| 值 | 说明 | +|----|------| +| `SUCCESS` | 成功 | +| `PENDING` | 处理中 | +| `FAIL` | 失败 | + +### 6.8 discount type（优惠类型） + +**使用字段**：出参 §5.4 `discounts[].type` + +| 值 | 说明 | +|----|------| +| `EARLY_BIRD` | 早鸟优惠 | +| `VIP` | VIP 优惠 | +| `COUPON` | 优惠券 | +| `PROMOTION` | 营销活动优惠 | + +### 6.9 discount source（优惠来源） + +**使用字段**：出参 §5.4 `discounts[].source` / `surcharges[].source` + +| 值 | 说明 | +|----|------| +| `MANUAL` | 手动添加（定制师人工） | +| `AUTO` | 系统自动 | +| `HOTEL_ASSIGN` | 配房环节产生（仅 surcharge） | +| `VEHICLE_ASSIGN` | 配车环节产生（仅 surcharge） | + +### 6.10 contractStatus（合同状态） + +**使用字段**：出参 §5.5 `contract.contractStatus` + +| 值 | 说明 | +|----|------| +| `PENDING` | 待生成 | +| `GENERATED` | 已生成待签 | +| `SIGNED` | 已签约 | +| `VOIDED` | 已作废 | + +### 6.11 event type（合同 / 保险事件类型） + +**使用字段**：出参 §5.5 `contract.events[].eventType` / `insurance.events[].eventType` + +| 值 | 说明 | +|----|------| +| `GENERATE` | 合同生成 | +| `SIGN` | 合同签约 | +| `VOID` | 合同作废 | +| `REOPEN` | 合同重开 | +| `ISSUE` | 保险出单 | +| `CANCEL` | 保险退保 | + +### 6.12 insuranceStatus（保险状态） + +**使用字段**：出参 §5.5 `insurance.insuranceStatus` + +| 值 | 说明 | +|----|------| +| `PENDING` | 待出单 | +| `ACTIVE` | 已生效 | +| `FAILED` | 出单失败 | +| `CANCELLED` | 已退保 | + +### 6.13 refund application status（退款申请状态） + +**使用字段**：出参 §5.8 `applications[].status` + +| 值 | 说明 | +|----|------| +| `PENDING_APPROVE` | 待审批 | +| `PENDING_PAYOUT` | 财务已审批，待打款 | +| `PENDING_ARRIVAL` | 已打款，待到账 | +| `COMPLETED` | 退款完成（已到账） | +| `REJECTED` | 已拒绝 | + +### 6.14 refund progress step（退款进度步骤） + +**使用字段**：出参 §5.8 `applications[].progress[].step` + +| 值 | 说明 | +|----|------| +| `APPLY` | 退款申请 | +| `APPROVE` | 财务审批 | +| `PAYOUT` | 退款打款 | +| `ARRIVED` | 到账确认 | + +### 6.15 tag type（标签类型） + +**使用字段**：出参 §5.3 main `tags[].type` + +| 值 | 说明 | +|----|------| +| `SYSTEM` | 系统自动打的标签 | +| `PERSONAL` | 定制师手动打的标签 | +| `MANUAL` | 主管手动打的标签 | + +--- + +## 7. 错误码 + +### 7.1 §1.1 创建订单（5101xx 段） + +| code | 含义 | +|------|------| +| `510101` | 产品不存在 / 已下架 | +| `510102` | 档位不存在 | +| `510103` | 出发日期早于今天 | +| `510104` | 出发日期超过报名截止 | +| `510105` | 拼团批次不存在 / 已满员 | +| `510106` | 总人数 = 0 | +| `510107` | `createSource` 枚举非法 | +| `510108` | 客户手机格式非法 | +| `510109` | 系统未配置默认定制师（DEFAULT_ASSIGNED 时轮询池为空） | +| `581013` | 定制师 ID 缺失（admin 端 JWT adminId 缺失） | +| `581014` | 产品域 Feign 调用失败 | +| `581015` | 产品域返回产品不存在 | +| `581020` | MQ 事件发布失败（非主路径，记审计） | +| `581021` | 跨公司访问被拒（公司隔离） | + +### 7.2 §1.2 订单列表 + +| code | 含义 | +|------|------| +| 无业务错误码 | 参数格式错误走全局 400 | + +### 7.3 §1.3.x 详情主聚合 + 6 Tab 子接口 + +**全部 7 接口共享**： +| code | 含义 | +|------|------| +| `581020` | 订单不存在 | +| `581021` | 无权访问该订单（公司隔离） | + +### 7.4 §1.4 修改订单字段 + +| code | 含义 | +|------|------| +| `581020` | 订单不存在 | +| `581021` | 无权访问该订单 | +| `581030` | 转单目标定制师不存在 | +| `581031` | 转单原因为空（传 targetConsultantId 时） | +| `581032` | 当前角色无转单权限（仅主管 / 客服可转单） | + +--- + +## 8. 示例 + +### 8.1 §1.1 创建订单 - 典型成功 + +**请求**： +```http +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 客户"] +} +``` + +**响应**： +```json +{ + "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" +} +``` + +### 8.2 §1.2 订单列表 - 典型 + +**请求**： +```http +GET /v3/admin/order?page=1&pageSize=10&orderStatus=待出行&tagNames=VIP%20%E5%AE%A2%E6%88%B7 +``` + +**响应**： +```json +{ + "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" +} +``` + +### 8.3 §1.3.1 详情主聚合 - 典型（精简：每 Tab 仅示范 1-2 字段） + +**请求**： +```http +GET /v3/admin/order/60123456789012 +``` + +**响应**： +```json +{ + "code": 200, + "data": { + "main": { + "id": "60123456789012", + "displayOrderNo": "HL20260510143025001-T20260601A", + "orderStatus": "待出行", + "flowStatus": "待出行", + "totalAmount": 8580.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"} + ]}, + {"key": "RETURNED", "label": "返团", "status": "ACTIVE"} + ] + } + }, + "tags": [{"name": "二次复购", "type": "SYSTEM", "color": "#52C41A"}], + "overview": { "travelers": [/* TravelerVO 完整字段，见 traveler 模块文档 §2.1 */] }, + "finance": { "totalAmount": 8580.00, "paidAmount": 8580.00, "payments": [/* ... */] }, + "itinerary": { "days": [/* Mock 中 */], "hotelGroup": {/*...*/}, "vehicleGroup": {/*...*/} }, + "contractInsurance": { + "contract": {"contractStatus": "SIGNED", "events": [{"eventType": "SIGN", "occurredAt": "2026-05-12T11:00:00"}]}, + "insurance": {"insuranceStatus": "ACTIVE", "insurancePolicyNo": "PICC2026060100123"} + }, + "serviceStandard": { "itinerary": ["Day1 抵达长春-接机入住"], "notice": {/*...*/}, "refundPolicy": {/*...*/} }, + "statusLog": [{"occurredAt": "2026-05-12T10:25:00", "operator": "李定制", "action": "确认锁单"}], + "refund": null + }, + "msg": "success" +} +``` + +### 8.4 §1.3.2 财务 Tab 单刷 - 典型 + +**请求**： +```http +GET /v3/admin/order/60123456789012/finance +``` + +**响应**： +```json +{ + "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" +} +``` + +### 8.5 §1.3.6 退款明细 Tab - 无退款（data=null） + +**请求**： +```http +GET /v3/admin/order/60123456789012/refund +``` + +**响应**： +```json +{ "code": 200, "data": null, "msg": "success" } +``` + +### 8.6 §1.4 修改订单字段 - 典型（转单） + +**请求**： +```http +PUT /v3/admin/order/60123456789012 +Content-Type: application/json + +{ + "targetConsultantId": 50009876543210, + "transferReason": "客户主动申请更换定制师", + "consultantRemark": "已联系新定制师" +} +``` + +**响应**： +```json +{ "code": 200, "data": true, "msg": "success" } +``` + +### 8.7 §1.1 创建订单 - 异常（拼团满员） + +**请求**：（同 8.1，但 `groupBatchId` 满员） + +**响应**： +```json +{ "code": 510105, "data": null, "msg": "拼团批次不存在或已满员" } +``` + +### 8.8 §1.3.1 详情主聚合 - 异常（跨公司访问） + +**请求**：（用户 adminId 不属于订单所属公司） +```http +GET /v3/admin/order/60999999999999 +``` + +**响应**： +```json +{ "code": 581021, "data": null, "msg": "无权访问该订单" } +``` + +--- + +## 9. 业务边界 + +### 9.1 创建订单（§1.1） + +- ✅ **适用**：产品上架；档位有效；出发日期 ≥ 今天；总人数 ≥ 1；客户手机合法 +- ❌ **拒绝**：产品下架 / 出发日期过期 / 总人数 0 / 拼团满员 / 客户手机非 11 位 +- ⚠️ **可选字段省略行为**： + - 不传 `createSource` → 接受，使用默认 `CONSULTANT` + - 不传 `roomCount` → 接受，返回订单 `roomCount` 为 null + - 不传 `tags` → 接受，仅含系统自动标签 + +### 9.2 订单列表（§1.2） + +- ✅ **默认行为**：`cancelled` 不传 = 不含已取消订单 +- ⚠️ **关键字搜索**：`keyword` 同时 LIKE 团号 / 客户姓名 / 产品名 / 订单号 任一字段 +- ⚠️ **标签过滤**：`tagNames` 多值是 **AND**（订单必须含全部标签才命中），不是 OR + +### 9.3 详情主聚合 vs 子接口（§1.3.x） + +| 场景 | 用哪个 | +|---|---| +| 详情页首次打开 | §1.3.1 主聚合（1 次拉全） | +| 单个 Tab 操作完后刷新 | §1.3.2 ~ §1.3.7 对应 Tab 子接口 | +| 状态变更后整页刷新 | §1.3.1 主聚合 | +| 高频轮询单 Tab（如等待退款到账） | §1.3.6 退款 Tab 子接口 | + +- ⚠️ **`itinerary` 子接口数据为 Mock**：行程节点 + 房车需求&实配为占位数据，待 follow-up issue 真实化 +- ⚠️ **退款 Tab 条件显示**：`refund` 字段无退款时为 null，前端据此判断是否渲染该 Tab +- ⚠️ **服务标准 Tab 条件显示**：`serviceStandard` 字段产品快照缺失时为 null + +### 9.4 修改订单字段（§1.4） + +- ✅ **可改字段**：备注 / 紧急联系人 / 客户信息 / 转单（仅主管 / 客服角色） +- ❌ **不可改字段**：订单金额 / 订单状态 / 出发日期 / 出行人数 / 拼团批次 → 需走专用接口 +- ⚠️ **转单约束**：传 `targetConsultantId` 必须同时传 `transferReason` +- ⚠️ **PATCH 语义**：不传 = 不改；传空字符串 = 改成空（区分两者） + +--- + +## 10. 修改前后对比 + +> 不适用 - 新增接口跳过本节 + +--- + +## 11. 影响评估 + +- **是否破坏向后兼容**：否（v3 全新二期，前端 v3 项目仓库首次消费） +- **前端是否必须同步上线**：是 +- **本次推送范围**：§1A 10 接口；§1B 取消订单 / §1C 状态机后续 commit 追加 + +--- + +## 12. 注意事项 + +- **§1.3.4 itinerary 子接口数据 Mock**：当前返回占位数据，前端可先按字段结构对接，真实化后无需改字段口径 +- **§1.3.6 / §1.3.7 条件显示**：前端拿到 `data=null` 时不渲染对应 Tab +- **主聚合 vs 子接口性能取舍**：首屏用主聚合（1 次请求拿全）；单 Tab 刷新用子接口（响应更小） +- **公司隔离 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 追加