From ec2426eda718135c71ece0ccfa49d28a8c659f63 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Sun, 27 Sep 2026 19:00:23 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20#8408=20PR-2=20order-v3=20?= =?UTF-8?q?=E7=AE=A1=E7=90=86=E5=90=8E=E5=8F=B0=20109=20=E4=B8=AA=E6=8E=A5?= =?UTF-8?q?=E5=8F=A3=E5=93=8D=E5=BA=94=E8=A1=A5=E5=9B=A2=E5=8F=B7=20teamNo?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - PR #8439（69046568c）+ #8447（97b9754f2）已合 dev-v3 并部署测试环境 - 网关实测：团期户列表 50/50、首页看板 5/5、房务详情 2/2、线下收款首笔登记响应团号与库一致 - 20 个写后出口团号查询降级为 null 已逐个标注；空白团号统一返回 null Co-Authored-By: Claude Opus 5.5 (1M context) --- ...7_8408_订单响应补团号-修改接口-管理后台.md | 9568 +++++++++++++++++ 1 file changed, 9568 insertions(+) create mode 100644 changelogs-v2/2026-09/27_8408_订单响应补团号-修改接口-管理后台.md diff --git a/changelogs-v2/2026-09/27_8408_订单响应补团号-修改接口-管理后台.md b/changelogs-v2/2026-09/27_8408_订单响应补团号-修改接口-管理后台.md new file mode 100644 index 00000000..c584a4c9 --- /dev/null +++ b/changelogs-v2/2026-09/27_8408_订单响应补团号-修改接口-管理后台.md @@ -0,0 +1,9568 @@ +--- +schema: "hl-changelog/v2" +ticket: "8408" +title: "订单管理后台响应体补团号字段" +consumer: "admin" +author: "wx(GIT)" +change_type: "修改接口" +backend_status: "deployed" +gateway_status: "verified" +frontend_status: "pending" +frontend_owner: "" +frontend_ref: "" +target_release: "" +verified_at: "2026-09-27" +status_note: "PR #8439（合并提交 69046568c）与 #8447（合并提交 97b9754f2）已合入 dev-v3，order-v3 已按 97b9754f2 部署测试环境。网关实测：团期户列表 50/50、首页看板 5/5、房务详情 2/2 的 teamNo 与库一致；管理端新建订单后登记首笔线下收款，响应 teamNo 为本次生成的团号，与库一致。其余接口由单测和响应字段门禁 TeamNoResponseFieldGateTest 覆盖，未逐个走网关。" +updated_at: "2026-09-27" +base: "dev-v3" +--- + +# 订单服务(order-v3): 管理后台响应体批量补团号(teamNo)字段 + +> **存放目录**: +> - 一期(v2,无 `order-v3` 标签的工单)→ `changelogs/{YYYY-MM}/` +> - 二期(v3,`order-v3` 标签的工单)→ `changelogs-v2/{YYYY-MM}/` +> +> **服务**: hl-order-service-v3 (端口 8083) + hl-user-service(仅出口透传,零改动) +> **PR**: #8439(字段主体) + #8447(线下收款首笔登记响应取写后团号、空白团号归一为 null) +> **Issue**: #8408 +> **日期**: 2026-09-27 +> **影响范围**: 管理后台(admin) 109 个接口(107 个 order-v3 + 2 个 user-service 工作台出口)的响应体补充只读字段 `teamNo`(团号) + +--- + +## ⚠️ 关键变化 / 一、背景 + +本工单(#8408)的字段侧按端拆开交付:车务(fleet)侧由 PR #8419 交付(见 `27_8408_车务响应补团号-修改接口-管理后台.md`);小程序(mp)端接口不在本文范围;本文(PR #8439 + #8447)覆盖 order-v3 管理后台侧 107 个接口 + user-service 工作台的 2 个出口(仪表盘「即将出行」列表,字段透传自 order-v3,user-service 本身零改动)。 + +**本次是纯新增字段的向后兼容改动**:上述 109 个接口的响应体新增只读字段 `teamNo`(团号),不删除、不重命名、不改变类型任何既有字段,不新增任何入参、不改变任何现有校验/错误码/鉴权规则。**前端不改代码也不会报错**——新增消费该字段是可选的。 + +`teamNo` 语义: +- 格式固定为 `yy-NNNN`(如 `26-0480`),来源于订单主表 `team_no` 列。 +- 订单**首次付款入账时生成**:线上支付成功、管理端登记首笔线下收款、订单状态干预推进到已付款,三条路径口径相同。已有团号的订单再次付款(如补尾款)时原样保留,不换号。 +- **未付款的订单没有团号**,`teamNo` 为 `null`。团号为空白时同样返回 `null`:不返回空串,也不用订单号顶替。 +- 登记首笔线下收款(`POST /v3/admin/order/{orderId}/payment/manual-receipt`)的响应里,`teamNo` 就是本次登记生成的团号,与之后查询订单拿到的一致(#8447)。 +- 另有 3 处接口原本就返回 `teamNo`,本次只改了一点:空白团号统一返回 `null`,字段和类型都不变(#8447)。这 3 处不在下方接口清单内: + - 评价列表 `GET /v3/admin/review/list` + - 评价详情 `GET /v3/admin/review/{reviewId}` + - 退款申请分页 `GET /v3/admin/refund/application/page` + - 另外,退款申请详情里 `orderInfo.teamNo` 也按同一口径处理。 +- 保险详情有两个入口:`GET .../insurance/orders/{id}`(纯读)走严格查询,团号查失败会直接报错,不返回 `null`;`sync-status`/`cancel` 等写后出口走降级查询,查失败时 `teamNo` 为 `null`,不影响其余字段。 + +--- + + +## 二、变更接口清单 + +| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | +|---|------|------|------|----------|------| +| 1 | §2.7 查询最终确认回执列表 | GET | `/admin/house/assignments/requirements/{requirementId}/receipts` | 新增字段 | `teamNo` | +| 2 | §2.7 上传最终确认回执(multipart, 可选凭证) | POST | `/admin/house/assignments/requirements/{requirementId}/receipts` | 新增字段 | `teamNo` | +| 3 | §2.6 日历某天下钻明细(date + scope=mine/all + status 多选, 按团折叠) | GET | `/admin/house/calendar/day` | 新增字段 | `teamNo` | +| 4 | §2.0b 需求历史完整列表(N 版独立数据 + diff + 退回信息) | GET | `/admin/house/orders/{orderId}/requirement-history` | 新增字段 | `teamNo` | +| 5 | 投诉分页列表(只读) | GET | `/v3/admin/complaint/page` | 新增字段 | `teamNo` | +| 6 | 投诉详情(只读) | GET | `/v3/admin/complaint/{id}` | 新增字段 | `teamNo` | +| 7 | 团期配房详情 | GET | `/v3/admin/house/group-batches/{groupBatchId}` | 新增字段 | `teamNo` | +| 8 | 团期分房总览（只读） | GET | `/v3/admin/house/group-batches/{groupBatchId}/allocations` | 新增字段 | `teamNo` | +| 9 | 人工微调分房 | POST | `/v3/admin/house/group-batches/{groupBatchId}/allocations` | 新增字段 | `teamNo` | +| 10 | 重算分房 | POST | `/v3/admin/house/group-batches/{groupBatchId}/allocations/rebuild` | 新增字段 | `teamNo` | +| 11 | 整团确认订房 | POST | `/v3/admin/house/group-batches/{groupBatchId}/room-plans/confirm` | 新增字段 | `teamNo` | +| 12 | 订房确认预检（只读） | GET | `/v3/admin/house/group-batches/{groupBatchId}/room-plans/confirm-check` | 新增字段 | `teamNo` | +| 13 | 按日确认订房 | POST | `/v3/admin/house/group-batches/{groupBatchId}/room-plans/days/{stayDate}/confirm` | 新增字段 | `teamNo` | +| 14 | 团期逐日用房需求明细 | GET | `/v3/admin/house/group-batches/{groupBatchId}/room-requirements` | 新增字段 | `teamNo` | +| 15 | §6.5 酒店维度操作日志(P2 候用, 接口设计完整保留) | GET | `/v3/admin/house/hotels/{hotelId}/operation-log` | 新增字段 | `teamNo` | +| 16 | 退保 | POST | `/v3/admin/insurance/cancel/{id}` | 新增字段 | `teamNo` | +| 17 | 订单保障状态 | GET | `/v3/admin/insurance/coverage/{orderId}` | 新增字段 | `teamNo` | +| 18 | 保险订单列表 | GET | `/v3/admin/insurance/list` | 新增字段 | `teamNo` | +| 19 | 添加出行人保险备注 | POST | `/v3/admin/insurance/order/{orderId}/traveler-note` | 新增字段 | `teamNo` | +| 20 | 保险订单列表 | GET | `/v3/admin/insurance/orders` | 新增字段 | `teamNo` | +| 21 | 按订单查保险列表 | GET | `/v3/admin/insurance/orders/by-order/{orderId}` | 新增字段 | `teamNo` | +| 22 | 保险订单列表 | GET | `/v3/admin/insurance/orders/{id}` | 新增字段 | `teamNo` | +| 23 | 刷新/同步保险订单出单状态 | POST | `/v3/admin/insurance/orders/{id}/sync-status` | 新增字段 | `teamNo` | +| 24 | 手动投保 | POST | `/v3/admin/insurance/purchase` | 新增字段 | `teamNo` | +| 25 | 创建订单 | POST | `/v3/admin/order` | 新增字段 | `teamNo` | +| 26 | 财务审批通过（SUBMITTED→APPROVED） | PUT | `/v3/admin/order/advance/{advanceId}/approve` | 新增字段 | `teamNo` | +| 27 | 财务审批驳回（SUBMITTED→REJECTED） | PUT | `/v3/admin/order/advance/{advanceId}/reject` | 新增字段 | `teamNo` | +| 28 | GB-ADM-061 团期审批中心列表（流团 + 退单户） | GET | `/v3/admin/order/group-batch/approvals/page` | 新增字段 | `teamNo` | +| 29 | GB-ADM-072 退单审批分页列表（管理员） | GET | `/v3/admin/order/group-batch/withdraw/page` | 新增字段 | `teamNo` | +| 30 | A2 团期详情 | GET | `/v3/admin/order/group-batch/{groupBatchId}` | 新增字段 | `teamNo` | +| 31 | GB-ADM-042 发起团期预支（创建即待审批） | POST | `/v3/admin/order/group-batch/{groupBatchId}/advance` | 新增字段 | `teamNo` | +| 32 | 核单面板（GB-ADM-050） | GET | `/v3/admin/order/group-batch/{groupBatchId}/audit` | 新增字段 | `teamNo` | +| 33 | 保存核单录入（GB-ADM-051） | PUT | `/v3/admin/order/group-batch/{groupBatchId}/audit` | 新增字段 | `teamNo` | +| 34 | 提交核算（GB-ADM-052） | POST | `/v3/admin/order/group-batch/{groupBatchId}/audit/allocate` | 新增字段 | `teamNo` | +| 35 | 团期确认预检(只读，配置 → 确认) | GET | `/v3/admin/order/group-batch/{groupBatchId}/confirm-check` | 新增字段 | `teamNo` | +| 36 | GB-ADM-031 手动开合同/保险 | POST | `/v3/admin/order/group-batch/{groupBatchId}/contracts/issue` | 新增字段 | `teamNo` | +| 37 | GB-ADM-031 作废重开合同/保险 | POST | `/v3/admin/order/group-batch/{groupBatchId}/contracts/reissue` | 新增字段 | `teamNo` | +| 38 | 批量催签合同 | POST | `/v3/admin/order/group-batch/{groupBatchId}/contracts/remind-sign` | 新增字段 | `teamNo` | +| 39 | A5 团期行程逐日汇总（GB-ADM-018） | GET | `/v3/admin/order/group-batch/{groupBatchId}/itinerary` | 新增字段 | `teamNo` | +| 40 | A6 团期行程某项逐户下钻（GB-ADM-019） | GET | `/v3/admin/order/group-batch/{groupBatchId}/itinerary/nodes/{nodeKey}` | 新增字段 | `teamNo` | +| 41 | 出具团级行程单（只排版全团一致项，差异项标「按户另见」） | GET | `/v3/admin/order/group-batch/{groupBatchId}/print-itinerary` | 新增字段 | `teamNo` | +| 42 | 手工复判进入待出发硬门(物资准备中 → 待出发) | POST | `/v3/admin/order/group-batch/{groupBatchId}/recheck-departure-gate` | 新增字段 | `teamNo` | +| 43 | 全团需求汇总 | GET | `/v3/admin/order/group-batch/{groupBatchId}/requirement-summary` | 新增字段 | `teamNo` | +| 44 | 整体确认需求缺失预检（只读） | GET | `/v3/admin/order/group-batch/{groupBatchId}/requirement/confirm-check` | 新增字段 | `teamNo` | +| 45 | 按户打回需求（退回定制师重提） | POST | `/v3/admin/order/group-batch/{groupBatchId}/requirement/reject` | 新增字段 | `teamNo` | +| 46 | 批量确认接送机需求（允许部分成功） | POST | `/v3/admin/order/group-batch/{groupBatchId}/requirement/transfer/batch-confirm` | 新增字段 | `teamNo` | +| 47 | 团期配房明细（只读） | GET | `/v3/admin/order/group-batch/{groupBatchId}/room-plans` | 新增字段 | `teamNo` | +| 48 | 核单按行程节点逐户下钻（GB-ADM-056） | POST | `/v3/admin/order/group-batch/{groupBatchId}/settlement/node-lines` | 新增字段 | `teamNo` | +| 49 | 转订单（子订单跨期转入） | POST | `/v3/admin/order/group-batch/{groupBatchId}/sub-order/{orderId}/transfer-in` | 新增字段 | `teamNo` | +| 50 | 转订单候选子订单列表 | GET | `/v3/admin/order/group-batch/{groupBatchId}/transfer-candidates` | 新增字段 | `teamNo` | +| 51 | 读团期正式用车需求（未形成时返回 null；带配车刷新状态只读投影） | GET | `/v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement` | 新增字段 | `teamNo` | +| 52 | 保存团期正式用车需求（全量替换） | PUT | `/v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement` | 新增字段 | `teamNo` | +| 53 | 自动汇总正式用车需求草稿（只读；草稿可原样 PUT） | GET | `/v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement/aggregate-draft` | 新增字段 | `teamNo` | +| 54 | 声明整团无需用车（零分组已确认，撤销走 withdraw） | POST | `/v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement/waive` | 新增字段 | `teamNo` | +| 55 | 整份撤回正式用车需求（退回草稿，已配车辆不动） | POST | `/v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement/withdraw` | 新增字段 | `teamNo` | +| 56 | 发票详情(完整申请明细，供上传弹窗/详情页) | GET | `/v3/admin/order/invoice/{id}` | 新增字段 | `teamNo` | +| 57 | 生成用餐信息（按订单产品快照生成空行，已有行不重复生成） | POST | `/v3/admin/order/meal-info/generate` | 新增字段 | `teamNo` | +| 58 | 查询用餐信息列表（按订单 / 团期 / 未挂归属） | GET | `/v3/admin/order/meal-info/list` | 新增字段 | `teamNo` | +| 59 | 重置用餐信息（删掉全部行后按快照重新生成空行） | POST | `/v3/admin/order/meal-info/reset` | 新增字段 | `teamNo` | +| 60 | 保存用餐信息（整单一次保存：带行ID覆盖、不带新增、没传上来的软删） | POST | `/v3/admin/order/meal-info/save` | 新增字段 | `teamNo` | +| 61 | 套用用餐模版（返回订单现有行 + 模版套出来的行，模版行接在后面，不改库） | POST | `/v3/admin/order/meal-template/apply` | 新增字段 | `teamNo` | +| 62 | §2.5 房间分配查询(按家庭分组) | GET | `/v3/admin/order/orders/{orderId}/rooms` | 新增字段 | `teamNo` | +| 63 | 受控推进单个订单状态（走状态机+写日志+联动房车日期，幂等） | POST | `/v3/admin/order/{id}/advance-state` | 新增字段 | `teamNo` | +| 64 | 订单详情 - 发票 Tab | GET | `/v3/admin/order/{id}/invoices` | 新增字段 | `teamNo` | +| 65 | 查询 staff 配置列表 | GET | `/v3/admin/order/{id}/staff` | 新增字段 | `teamNo` | +| 66 | 新增 staff 配置 | POST | `/v3/admin/order/{id}/staff` | 新增字段 | `teamNo` | +| 67 | 编辑 staff 配置 | PUT | `/v3/admin/order/{id}/staff/{staffAssignmentId}` | 新增字段 | `teamNo` | +| 68 | 设置 staff 报账人等级（核心订单） | PUT | `/v3/admin/order/{id}/staff/{staffAssignmentId}/reporter-rank` | 新增字段 | `teamNo` | +| 69 | 终止行程·退款预览（出行中） | POST | `/v3/admin/order/{id}/terminate/refund-preview` | 新增字段 | `teamNo` | +| 70 | 大交通批次新增 | POST | `/v3/admin/order/{id}/transport-plan/add` | 新增字段 | `teamNo` | +| 71 | 大交通批次批量替换 | POST | `/v3/admin/order/{id}/transport-plan/batch` | 新增字段 | `teamNo` | +| 72 | 大交通批次列表 | GET | `/v3/admin/order/{id}/transport-plan/list` | 新增字段 | `teamNo` | +| 73 | 大交通批次编辑 | POST | `/v3/admin/order/{id}/transport-plan/{planId}/edit` | 新增字段 | `teamNo` | +| 74 | 单个出行人新增 | POST | `/v3/admin/order/{id}/traveler/add` | 新增字段 | `teamNo` | +| 75 | 出行人列表 | GET | `/v3/admin/order/{id}/traveler/list` | 新增字段 | `teamNo` | +| 76 | 订单增减项（统一端点，按 direction 分流） | POST | `/v3/admin/order/{orderId}/adjustment` | 新增字段 | `teamNo` | +| 77 | 创建预支（创建即待审批） | POST | `/v3/admin/order/{orderId}/advance` | 新增字段 | `teamNo` | +| 78 | 分页查询本单预支列表 | GET | `/v3/admin/order/{orderId}/advances` | 新增字段 | `teamNo` | +| 79 | 查询订单优惠+附加费清单 | GET | `/v3/admin/order/{orderId}/discount-surcharge/list` | 新增字段 | `teamNo` | +| 80 | 新增订单优惠（已废弃，改调 /adjustment） | POST | `/v3/admin/order/{orderId}/discounts` | 新增字段 | `teamNo` | +| 81 | 定制师代客申请发票（须订单已完成） | POST | `/v3/admin/order/{orderId}/invoice/apply` | 新增字段 | `teamNo` | +| 82 | 生成电子行程单数据（对客） | GET | `/v3/admin/order/{orderId}/itinerary-document` | 新增字段 | `teamNo` | +| 83 | 查询订单完整行程（含全部实配嵌套，已真实化 Issue #2471） | GET | `/v3/admin/order/{orderId}/itinerary/full` | 新增字段 | `teamNo` | +| 84 | 查询订单线下收款列表（含已撤销行，审计溯源用） | GET | `/v3/admin/order/{orderId}/payment/manual-receipt` | 新增字段 | `teamNo` | +| 85 | 登记线下收款（报账人收款/对公转账/定制师代收），同事务推进 paid_amount | POST | `/v3/admin/order/{orderId}/payment/manual-receipt` | 新增字段 | `teamNo` | +| 86 | 撤销线下收款（同事务回退 paid_amount，行保留可追溯） | DELETE | `/v3/admin/order/{orderId}/payment/manual-receipt/{receiptId}` | 新增字段 | `teamNo` | +| 87 | 财务复核确认结算 | POST | `/v3/admin/order/{orderId}/settlement/confirm` | 新增字段 | `teamNo` | +| 88 | 管理员反确认核单终态快照 | POST | `/v3/admin/order/{orderId}/settlement/final-snapshots/reopen` | 新增字段 | `teamNo` | +| 89 | 完成核单 | POST | `/v3/admin/order/{orderId}/settlement/finalize` | 新增字段 | `teamNo` | +| 90 | 查询核单操作日志 | GET | `/v3/admin/order/{orderId}/settlement/logs` | 新增字段 | `teamNo` | +| 91 | 查询车辆核单草稿 | GET | `/v3/admin/order/{orderId}/settlement/step3/vehicles` | 新增字段 | `teamNo` | +| 92 | 全量保存车辆核单草稿 | PUT | `/v3/admin/order/{orderId}/settlement/step3/vehicles` | 新增字段 | `teamNo` | +| 93 | 查核单汇总快照 | GET | `/v3/admin/order/{orderId}/settlement/summary` | 新增字段 | `teamNo` | +| 94 | 新增订单附加费（已废弃，改调 /adjustment） | POST | `/v3/admin/order/{orderId}/surcharges` | 新增字段 | `teamNo` | +| 95 | 增订单标签 | POST | `/v3/admin/order/{orderId}/tag` | 新增字段 | `teamNo` | +| 96 | 分页查询退款申诉 | GET | `/v3/admin/refund/appeal/page` | 新增字段 | `teamNo` | +| 97 | 查询申诉详情（管理端） | GET | `/v3/admin/refund/appeal/{id}` | 新增字段 | `teamNo` | +| 98 | 客服代下退款申请 | POST | `/v3/admin/refund/application` | 新增字段 | `teamNo` | +| 99 | 手动完成退款 | PUT | `/v3/admin/refund/application/{applicationId}/complete` | 新增字段 | `teamNo` | +| 100 | 退款申请详情 | GET | `/v3/admin/refund/application/{id}` | 新增字段 | `teamNo` | +| 101 | 触发实退 | POST | `/v3/admin/refund/execute/{appId}` | 新增字段 | `teamNo` | +| 102 | 提交审核 | POST | `/v3/admin/refund/review` | 新增字段 | `teamNo` | +| 103 | 取消团队 | POST | `/v3/admin/team-report/cancel` | 新增字段 | `teamNo` | +| 104 | 暂存表单 | POST | `/v3/admin/team-report/save` | 新增字段 | `teamNo` | +| 105 | 查询审核状态 | GET | `/v3/admin/team-report/status/{orderId}` | 新增字段 | `teamNo` | +| 106 | 提交到12301平台 | POST | `/v3/admin/team-report/submit` | 新增字段 | `teamNo` | +| 107 | 获取上报记录 | GET | `/v3/admin/team-report/{orderId}` | 新增字段 | `teamNo` | +| 108 | 工作台仪表盘（角色分发，支持时间范围） | GET | `/admin/profile/dashboard` | 新增字段 | `data.upcomingTrips[].teamNo` | +| 109 | 工作台概览（已废弃） | GET | `/admin/designer/dashboard` | 新增字段 | `data.upcomingTrips[].teamNo` | + +--- + +## 三、接口详情 + +### 1. §2.7 查询最终确认回执列表 `GET /admin/house/assignments/requirements/{requirementId}/receipts` + +**VO**: `HouseFinalizeReceiptRespVO` + +#### 使用场景 + +§2.7 查询最终确认回执列表。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| requirementId | Path | Long | ✅ | 正整数 | 需求主键 requirement_id | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单 ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /admin/house/assignments/requirements/1934567890123456701/receipts +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": [] +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 2. §2.7 上传最终确认回执(multipart, 可选凭证) `POST /admin/house/assignments/requirements/{requirementId}/receipts` + +**VO**: `HouseFinalizeReceiptRespVO` + +#### 使用场景 + +§2.7 上传最终确认回执(multipart, 可选凭证)。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| requirementId | Path | Long | ✅ | 正整数 | 需求主键 requirement_id | +| file | Body(multipart) | File | ✅ | — | 上传文件 | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单 ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +POST /admin/house/assignments/requirements/{requirementId}/receipts +Content-Type: multipart/form-data; boundary=... + +(file 字段为二进制流,略) +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +查询失败静默降为 `null`，不影响其余字段、不回滚已提交的写操作；未付款/未生成团号同样为 `null`。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": null + } +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 +- 本端点团号查询走静默降级：查失败不影响其余字段返回、不回滚已提交的写操作。 + +--- + +### 3. §2.6 日历某天下钻明细(date + scope=mine/all + status 多选, 按团折叠) `GET /admin/house/calendar/day` + +**VO**: `DayTourItemVO` + +#### 使用场景 + +§2.6 日历某天下钻明细(date + scope=mine/all + status 多选, 按团折叠)。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| date | Query | LocalDate | — | — | date | +| scope | Query | String | — | — | scope | +| status | Query | String | — | — | 状态点筛选:inProgress/inquiry/pending/exception,支持多选逗号分隔;不填 = 全部 | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | orderId（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /admin/house/calendar/day?date=2026-09-27&scope=scope&status=inProgress +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": [] +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 4. §2.0b 需求历史完整列表(N 版独立数据 + diff + 退回信息) `GET /admin/house/orders/{orderId}/requirement-history` + +**VO**: `RequirementHistoryRespVO` + +#### 使用场景 + +§2.0b 需求历史完整列表(N 版独立数据 + diff + 退回信息)。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Path | Long | ✅ | 正整数 | 订单 ID | +| includeDiff | Query | Boolean | — | — | includeDiff | +| onlyReturned | Query | Boolean | — | — | onlyReturned | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | orderId（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /admin/house/orders/{orderId}/requirement-history?includeDiff=True&onlyReturned=True +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 5. 投诉分页列表(只读) `GET /v3/admin/complaint/page` + +**VO**: `ComplaintRespVO` + +#### 使用场景 + +投诉分页列表(只读)。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| page | Query | Integer | — | — | 页码 | +| pageSize | Query | Integer | — | — | 每页条数 | +| keyword | Query | String | — | — | keyword | +| orderNo | Query | String | — | — | 订单号精确匹配 | +| groupCode | Query | String | — | — | 团号精确匹配 | +| customizerNickname | Query | String | — | — | 定制师昵称模糊 | +| types | Query | List | — | — | types | +| isResolved | Query | Boolean | — | — | isResolved | +| dateFrom | Query | LocalDate | — | — | dateFrom | +| dateTo | Query | LocalDate | — | — | dateTo | +| dayScope | Query | String | — | — | dayScope | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.records[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/complaint/page?page=1&pageSize=20&keyword=keyword&orderNo=HL202604220001&groupCode=A001&customizerNickname=张 +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "records": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "records": [] + } +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 6. 投诉详情(只读) `GET /v3/admin/complaint/{id}` + +**VO**: `ComplaintRespVO` + +#### 使用场景 + +投诉详情(只读)。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| id | Path | Long | ✅ | 正整数 | id | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/complaint/1934567890123456701 +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 7. 团期配房详情 `GET /v3/admin/house/group-batches/{groupBatchId}` + +**VO**: `HouseGroupBatchBoardRespVO` + +#### 使用场景 + +团期配房详情。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| groupBatchId | Path | Long | ✅ | 正整数 | 团期主订单 ID | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.outOfRangeHouseholds[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 子订单 ID（同层级对照） | +| data.outOfRangeHouseholds | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | +| data.specialTags[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| data.specialTags | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/house/group-batches/1934567890123456701 +``` + +#### 响应示例 + +共 2 处新增 `teamNo`（路径见出参表），此处仅展示其一，其余同构。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "outOfRangeHouseholds": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 8. 团期分房总览（只读） `GET /v3/admin/house/group-batches/{groupBatchId}/allocations` + +**VO**: `GroupBatchRoomAllocationOverviewRespVO` + +#### 使用场景 + +团期分房总览（只读）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| groupBatchId | Path | Long | ✅ | 正整数 | 团期主订单 ID | +| stayDate | Query | LocalDate | — | — | 只看某一入住日；不传 = 全部有计划行或有需求的日 | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.days[].plans[].allocations[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 分给哪一户（同层级对照） | +| data.days[].plans[].allocations | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | +| data.days[].households[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| data.days[].households | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | +| data.blockedHouseholds[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| data.blockedHouseholds | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/house/group-batches/{groupBatchId}/allocations?stayDate=2026-06-12 +``` + +#### 响应示例 + +共 3 处新增 `teamNo`（路径见出参表），此处仅展示其一，其余同构。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "days": [ + { + "plans": [ + { + "allocations": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } + ] + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 9. 人工微调分房 `POST /v3/admin/house/group-batches/{groupBatchId}/allocations` + +**VO**: `GroupBatchRoomAllocationRebuildRespVO` + +#### 使用场景 + +人工微调分房。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| groupBatchId | Path | Long | ✅ | 正整数 | 团期主订单 ID | +| items | Body | List | — | — | 人工分房行，与 clearPlanIds 至少一个非空；最多 500 行 | +| clearPlanIds | Body | List | — | — | 这些计划行下的人工分房全部软删（回到纯自动分房），最多 200 条 | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.days[].shortage[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 子订单 ID（同层级对照） | +| data.days[].shortage | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | +| data.days[].manualConflicts[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| data.days[].manualConflicts | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | +| data.days[].outOfRange[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| data.days[].outOfRange | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | +| data.warnings[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| data.warnings | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "items": [ + { + "planId": "1934567890123456701", + "orderId": "1934567890123456701", + "roomCount": 1, + "roomGroupNo": "F1", + "travelerCount": 2, + "bedType": "twin", + "remark": "备注，≤256 字" + } + ], + "clearPlanIds": [] +} +``` + +#### 响应示例 + +共 4 处新增 `teamNo`（路径见出参表），此处仅展示其一，其余同构。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "days": [ + { + "shortage": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 10. 重算分房 `POST /v3/admin/house/group-batches/{groupBatchId}/allocations/rebuild` + +**VO**: `GroupBatchRoomAllocationRebuildRespVO` + +#### 使用场景 + +重算分房。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| groupBatchId | Path | Long | ✅ | 正整数 | 团期主订单 ID | +| force | Body | Boolean | — | — | 是否先重置全部人工分房；默认 false | +| stayDate | Body | LocalDate | — | — | 只重算某一入住日；不传 = 整团全部已确认日 | +| reason | Body | String | — | — | 重置原因，force=true 时必填（≤256 字），写进团级时间线 | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.days[].shortage[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 子订单 ID（同层级对照） | +| data.days[].shortage | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | +| data.days[].manualConflicts[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| data.days[].manualConflicts | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | +| data.days[].outOfRange[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| data.days[].outOfRange | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | +| data.warnings[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| data.warnings | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "force": "false", + "stayDate": "2026-06-12", + "reason": "重置原因，force=true 时必填" +} +``` + +#### 响应示例 + +共 4 处新增 `teamNo`（路径见出参表），此处仅展示其一，其余同构。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "days": [ + { + "shortage": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 11. 整团确认订房 `POST /v3/admin/house/group-batches/{groupBatchId}/room-plans/confirm` + +**VO**: `GroupBatchRoomConfirmAllRespVO` + +#### 使用场景 + +整团确认订房。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| groupBatchId | Path | Long | ✅ | 正整数 | 团期主订单 ID | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.warnings[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 相关子订单 ID，无具体户时为空（同层级对照） | +| data.warnings | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +POST /v3/admin/house/group-batches/1934567890123456701/room-plans/confirm +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "warnings": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +查询失败静默降为 `null`，不影响其余字段、不回滚已提交的写操作；未付款/未生成团号同样为 `null`。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "warnings": [ + { + "orderId": "1934567890123456701", + "teamNo": null + } + ] + } +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 +- 本端点团号查询走静默降级：查失败不影响其余字段返回、不回滚已提交的写操作。 + +--- + +### 12. 订房确认预检（只读） `GET /v3/admin/house/group-batches/{groupBatchId}/room-plans/confirm-check` + +**VO**: `GroupBatchRoomConfirmCheckRespVO` + +#### 使用场景 + +订房确认预检（只读）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| groupBatchId | Path | Long | ✅ | 正整数 | 团期主订单 ID | +| stayDate | Query | LocalDate | — | — | 入住日，不传则返回全部相关日 | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.noBaselineOrders[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 子订单 ID（同层级对照） | +| data.noBaselineOrders | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | +| data.outOfRangeOrders[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| data.outOfRangeOrders | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/house/group-batches/{groupBatchId}/room-plans/confirm-check?stayDate=2026-06-12 +``` + +#### 响应示例 + +共 2 处新增 `teamNo`（路径见出参表），此处仅展示其一，其余同构。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "noBaselineOrders": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 13. 按日确认订房 `POST /v3/admin/house/group-batches/{groupBatchId}/room-plans/days/{stayDate}/confirm` + +**VO**: `GroupBatchRoomDayConfirmRespVO` + +#### 使用场景 + +按日确认订房。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| groupBatchId | Path | Long | ✅ | 正整数 | 团期主订单 ID | +| stayDate | Path | LocalDate | ✅ | — | 入住日 yyyy-MM-dd | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.warnings[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 相关子订单 ID，无具体户时为空（同层级对照） | +| data.warnings | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +POST /v3/admin/house/group-batches/1934567890123456701/room-plans/days/2026-09-27/confirm +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "warnings": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +查询失败静默降为 `null`，不影响其余字段、不回滚已提交的写操作；未付款/未生成团号同样为 `null`。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "warnings": [ + { + "orderId": "1934567890123456701", + "teamNo": null + } + ] + } +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 +- 本端点团号查询走静默降级：查失败不影响其余字段返回、不回滚已提交的写操作。 + +--- + +### 14. 团期逐日用房需求明细 `GET /v3/admin/house/group-batches/{groupBatchId}/room-requirements` + +**VO**: `HouseGroupBatchRoomRequirementRespVO` + +#### 使用场景 + +团期逐日用房需求明细。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| groupBatchId | Path | Long | ✅ | 正整数 | 团期主订单 ID | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.days[].households[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 子订单 ID（同层级对照） | +| data.days[].households | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | +| data.householdsWithoutBasis[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| data.householdsWithoutBasis | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | +| data.outOfRangeHouseholds[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| data.outOfRangeHouseholds | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/house/group-batches/1934567890123456701/room-requirements +``` + +#### 响应示例 + +共 3 处新增 `teamNo`（路径见出参表），此处仅展示其一，其余同构。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "days": [ + { + "households": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 15. §6.5 酒店维度操作日志(P2 候用, 接口设计完整保留) `GET /v3/admin/house/hotels/{hotelId}/operation-log` + +**VO**: `HouseOperationLogItemVO` + +#### 使用场景 + +§6.5 酒店维度操作日志(P2 候用, 接口设计完整保留)。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| hotelId | Path | Long | ✅ | 正整数 | hotelId | +| opType | Query | String | — | — | opType | +| source | Query | String | — | — | source | +| operatorId | Query | Long | — | — | 操作人房务 ID | +| keyword | Query | String | — | — | keyword | +| startDate | Query | LocalDateTime | — | — | startDate | +| endDate | Query | LocalDateTime | — | — | 结束时间 | +| sortBy | Query | String | — | — | sortBy | +| page | Query | Long | — | — | 页码 | +| pageSize | Query | Long | — | — | pageSize | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.records[].detail.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单 ID（同层级对照） | +| data.records[].detail | OperationDetailVO | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/house/hotels/{hotelId}/operation-log?opType=opType&source=source&operatorId=1001&keyword=keyword&startDate=2026-09-27T10:00:00&endDate=2026-05-31T23:59:59 +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "records": [ + { + "detail": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "records": [] + } +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 16. 退保 `POST /v3/admin/insurance/cancel/{id}` + +**VO**: `InsuranceOrderDetailVO` + +#### 使用场景 + +退保。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| insuranceOrderId | Path | Long | ✅ | 正整数 | insuranceOrderId | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 关联业务订单ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +POST /v3/admin/insurance/cancel/{id} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +查询失败静默降为 `null`，不影响其余字段、不回滚已提交的写操作；未付款/未生成团号同样为 `null`。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": null + } +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 +- 本端点团号查询走静默降级：查失败不影响其余字段返回、不回滚已提交的写操作。 + +--- + +### 17. 订单保障状态 `GET /v3/admin/insurance/coverage/{orderId}` + +**VO**: `OrderInsuranceCoverageVO` + +#### 使用场景 + +订单保障状态。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Path | Long | ✅ | 正整数 | orderId | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 旅行订单ID（同层级对照） | +| data.insuranceOrders[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| data.insuranceOrders | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/insurance/coverage/1934567890123456701 +``` + +#### 响应示例 + +共 2 处新增 `teamNo`（路径见出参表），此处仅展示其一，其余同构。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 18. 保险订单列表 `GET /v3/admin/insurance/list` + +**VO**: `InsuranceOrderVO` + +#### 使用场景 + +保险订单列表。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| page | Query | Integer | — | — | 页码 | +| pageSize | Query | Integer | — | — | 每页条数 | +| orderId | Query | Long | — | — | 关联订单ID | +| policyNo | Query | String | — | — | 保单号 | +| status | Query | String | — | — | status | +| insuredName | Query | String | — | — | 被保人姓名 | +| insuranceProductId | Query | Long | — | — | 保险产品ID | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.records[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 关联业务订单ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/insurance/list?page=1&pageSize=20&orderId=1234567890&policyNo=POL202605010001&status=status&insuredName=张三 +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "records": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "records": [] + } +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 19. 添加出行人保险备注 `POST /v3/admin/insurance/order/{orderId}/traveler-note` + +**VO**: `InsuranceTravelerNoteVO` + +#### 使用场景 + +添加出行人保险备注。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Path | Long | ✅ | 正整数 | orderId | +| travelerId | Body | Long | — | — | 出行人ID | +| travelerName | Body | String | — | — | 出行人姓名 | +| noteType | Body | String | — | — | noteType | +| remark | Body | String | — | — | 备注说明 | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "travelerId": "1001", + "travelerName": "张三", + "noteType": "noteType", + "remark": "已通过线下渠道购买保险" +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +查询失败静默降为 `null`，不影响其余字段、不回滚已提交的写操作；未付款/未生成团号同样为 `null`。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": null + } +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 +- 本端点团号查询走静默降级：查失败不影响其余字段返回、不回滚已提交的写操作。 + +--- + +### 20. 保险订单列表 `GET /v3/admin/insurance/orders` + +**VO**: `InsuranceOrderVO` + +#### 使用场景 + +保险订单列表。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| page | Query | Integer | — | — | 页码 | +| pageSize | Query | Integer | — | — | 每页条数 | +| orderId | Query | Long | — | — | 关联订单ID | +| policyNo | Query | String | — | — | 保单号 | +| status | Query | String | — | — | status | +| insuredName | Query | String | — | — | 被保人姓名 | +| insuranceProductId | Query | Long | — | — | 保险产品ID | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.records[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 关联业务订单ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/insurance/orders?page=1&pageSize=20&orderId=1234567890&policyNo=POL202605010001&status=status&insuredName=张三 +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "records": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "records": [] + } +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 21. 按订单查保险列表 `GET /v3/admin/insurance/orders/by-order/{orderId}` + +**VO**: `InsuranceOrderVO` + +#### 使用场景 + +按订单查保险列表。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Path | Long | ✅ | 正整数 | orderId | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 关联业务订单ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/insurance/orders/by-order/1934567890123456701 +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": [] +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 22. 保险订单列表 `GET /v3/admin/insurance/orders/{id}` + +**VO**: `InsuranceOrderDetailVO` + +#### 使用场景 + +保险订单列表。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| insuranceOrderId | Path | Long | ✅ | 正整数 | insuranceOrderId | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 关联业务订单ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/insurance/orders/{id} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 23. 刷新/同步保险订单出单状态 `POST /v3/admin/insurance/orders/{id}/sync-status` + +**VO**: `InsuranceOrderDetailVO` + +#### 使用场景 + +刷新/同步保险订单出单状态。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| insuranceOrderId | Path | Long | ✅ | 正整数 | insuranceOrderId | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 关联业务订单ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +POST /v3/admin/insurance/orders/{id}/sync-status +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +查询失败静默降为 `null`，不影响其余字段、不回滚已提交的写操作；未付款/未生成团号同样为 `null`。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": null + } +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 +- 本端点团号查询走静默降级：查失败不影响其余字段返回、不回滚已提交的写操作。 + +--- + +### 24. 手动投保 `POST /v3/admin/insurance/purchase` + +**VO**: `InsuranceOrderDetailVO` + +#### 使用场景 + +手动投保。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Body | Long | — | — | 订单ID | +| schemeId | Body | Long | — | — | schemeId | +| insuranceProductId | Body | Long | — | — | insuranceProductId | +| planId | Body | Long | — | — | planId | +| coverageStartDate | Body | LocalDate | — | — | 保障开始日期（为空时后端按订单 startDate 自动填充） | +| coverageEndDate | Body | LocalDate | — | — | 保障结束日期（为空时后端按订单 endDate 自动填充） | +| insuredPersons | Body | List | — | — | 被保人列表（为空时后端按订单出行人自动填充；传了则以传入为准） | +| remark | Body | String | — | — | 备注 | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 关联业务订单ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "orderId": "1234567890", + "schemeId": "1934567890123456701", + "insuranceProductId": "1934567890123456701", + "planId": "1934567890123456701", + "coverageStartDate": "2026-05-01", + "coverageEndDate": "2026-05-07", + "insuredPersons": [ + { + "name": "张三", + "idCardType": "idCardType", + "idCardNo": "110101199001011234", + "birthday": "1990-01-01", + "phone": "13800138000" + } + ], + "remark": "备注" +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] +} +``` + +#### 空数据 / 降级响应 + +查询失败静默降为 `null`，不影响其余字段、不回滚已提交的写操作；未付款/未生成团号同样为 `null`。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": [ + { + "orderId": "1934567890123456701", + "teamNo": null + } + ] +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 +- 本端点团号查询走静默降级：查失败不影响其余字段返回、不回滚已提交的写操作。 + +--- + +### 25. 创建订单 `POST /v3/admin/order` + +**VO**: `OrderCreateRespVO` + +#### 使用场景 + +创建订单。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| productId | Body | Long | — | — | 产品 ID | +| tierSeq | Body | Integer | — | — | 档位序号 | +| departureDate | Body | LocalDate | — | — | 出发日期（v4.9 改必填） | +| adultCount | Body | Integer | — | — | 成人数（≥1） | +| childCount | Body | Integer | — | — | 儿童数（6-12岁；默认 0） | +| youngChildCount | Body | Integer | — | — | 幼童数（2-5岁，占座不占床；默认 0） | +| babyCount | Body | Integer | — | — | 婴儿数（0-1岁，不占座不占床；默认 0） | +| customerName | Body | String | — | — | 客户姓名 | +| customerPhone | Body | String | — | — | 客户手机（明文传，DB 层 AES） | +| customerRemark | Body | String | — | — | 客户备注（≤500） | +| createSource | Body | String | — | — | 创建来源（v5.17，非必填，不传默认 CONSULTANT）。 | +| productBatchId | Body | Long | — | — | 团期 ID（product 侧班期 batchId，v5.17，非必填；GROUP 产品必传，自由出团为空） | +| roomCount | Body | Integer | — | — | 房间数（v5.17，非必填，写入 order_main.room_count） | +| tags | Body | List | — | — | 订单标签名列表（v5.17，非必填，写入 order_tag） | +| sharerOpenid | Body | String | — | — | 分享人 openid（C 端裂变追踪/佣金归属，非必填） | +| customizerId | Body | Long | — | — | 分享归因 customizerId（C 端从分享链接带，非必填） | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| id | Long | 订单主键（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +此处仅示例前 10 个字段，完整字段见入参表。 + +```json +{ + "productId": "30001234567", + "tierSeq": 1, + "departureDate": "2026-06-01", + "adultCount": 2, + "childCount": 1, + "youngChildCount": 0, + "babyCount": 0, + "customerName": "张三", + "customerPhone": "13800002046", + "customerRemark": "希望住朝阳房" +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "id": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 26. 财务审批通过（SUBMITTED→APPROVED） `PUT /v3/admin/order/advance/{advanceId}/approve` + +**VO**: `OrderAdvanceRespVO` + +#### 使用场景 + +财务审批通过（SUBMITTED→APPROVED）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| advanceId | Path | Long | ✅ | 正整数 | 预支ID | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +PUT /v3/admin/order/advance/1934567890123456701/approve +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 27. 财务审批驳回（SUBMITTED→REJECTED） `PUT /v3/admin/order/advance/{advanceId}/reject` + +**VO**: `OrderAdvanceRespVO` + +#### 使用场景 + +财务审批驳回（SUBMITTED→REJECTED）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| advanceId | Path | Long | ✅ | 正整数 | 预支ID | +| reason | Body | String | — | — | 驳回原因（必填） | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "reason": "驳回原因" +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +查询失败静默降为 `null`，不影响其余字段、不回滚已提交的写操作；未付款/未生成团号同样为 `null`。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": null + } +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 +- 本端点团号查询走静默降级：查失败不影响其余字段返回、不回滚已提交的写操作。 + +--- + +### 28. GB-ADM-061 团期审批中心列表（流团 + 退单户） `GET /v3/admin/order/group-batch/approvals/page` + +**VO**: `GroupBatchApprovalItemRespVO` + +#### 使用场景 + +GB-ADM-061 团期审批中心列表（流团 + 退单户）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| bizType | Query | String | — | — | 业务类型筛选：DISBAND 流团 / WITHDRAW 退单户；不传 = 两类都要 | +| approvalStatus | Query | String | — | — | 审批状态筛选：PENDING / APPROVED / REJECTED；不传 = 全部 | +| groupBatchId | Query | Long | — | — | 团期 ID 筛选；不传 = 全部 | +| batchName | Query | String | — | — | 团期名称模糊搜索（#8253）：包含匹配 batchName；输入「第N期」/「N」时另按期号精确匹配 | +| pageNum | Query | Integer | — | — | 页码，从 1 开始 | +| pageSize | Query | Integer | — | — | 每页条数，1-100 | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.records[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 被退子订单 ID（WITHDRAW 有值，DISBAND 为 null）（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/order/group-batch/approvals/page?bizType=DISBAND&approvalStatus=PENDING&groupBatchId=90211&batchName=jw测试&pageNum=1&pageSize=20 +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "records": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "records": [] + } +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 29. GB-ADM-072 退单审批分页列表（管理员） `GET /v3/admin/order/group-batch/withdraw/page` + +**VO**: `WithdrawApprovalItemRespVO` + +#### 使用场景 + +GB-ADM-072 退单审批分页列表（管理员）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| approvalStatus | Query | String | — | — | 审批状态（PENDING/APPROVED/REJECTED；缺省 PENDING，传 ALL 查全部） | +| groupBatchId | Query | Long | — | — | 按团期筛选（可选） | +| keyword | Query | String | — | — | 客户姓名 / 订单号模糊关键词（可选） | +| createdFrom | Query | String | — | — | 提交时间起（yyyy-MM-dd，可选） | +| createdTo | Query | String | — | — | 提交时间止（yyyy-MM-dd，含当日，可选） | +| pageNo | Query | Integer | — | — | 页码，从 1 开始 | +| pageSize | Query | Integer | — | — | 每页条数，默认 20，最大 100 | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.records[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 子订单ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/order/group-batch/withdraw/page?approvalStatus=PENDING&groupBatchId=800001&keyword=林婉清&createdFrom=2026-09-01&createdTo=2026-09-30&pageNo=1 +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "records": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "records": [] + } +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 30. A2 团期详情 `GET /v3/admin/order/group-batch/{groupBatchId}` + +**VO**: `GroupBatchDetailRespVO` + +#### 使用场景 + +A2 团期详情。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| groupBatchId | Path | Long | ✅ | 正整数 | 团期ID | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.departureGates[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| blockedOrderId | Long | 卡在哪一户（仅出行人证件 / 合同保险两门可能有值，其余为 null）；（同层级对照） | +| data.departureGates | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/order/group-batch/1934567890123456701 +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "departureGates": [ + { + "blockedOrderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 31. GB-ADM-042 发起团期预支（创建即待审批） `POST /v3/admin/order/group-batch/{groupBatchId}/advance` + +**VO**: `OrderAdvanceRespVO` + +#### 使用场景 + +GB-ADM-042 发起团期预支（创建即待审批）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| groupBatchId | Path | Long | ✅ | 正整数 | 团期ID | +| payeeStaffId | Body | Long | — | — | 借款对象（资源域 staff.staff_id，取自本团领款人候选下拉项的 id） | +| advanceType | Body | String | — | — | 借款类型（数据字典 advance_type 的 dictValue） | +| amount | Body | BigDecimal | — | — | 预支金额，> 0 且不超过可支取余额（团期统一池） | +| purpose | Body | String | — | — | 用途说明（选填） | +| voucherUrl | Body | String | — | — | 凭证文件 URL（选填，前端上传后回传） | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "payeeStaffId": "88102", + "advanceType": "住宿押金", + "amount": "3000.00", + "purpose": "沿途住宿押金", + "voucherUrl": "凭证文件 URL" +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 32. 核单面板（GB-ADM-050） `GET /v3/admin/order/group-batch/{groupBatchId}/audit` + +**VO**: `GroupBatchAuditRespVO` + +#### 使用场景 + +核单面板（GB-ADM-050）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| groupBatchId | Path | Long | ✅ | 正整数 | 团期ID | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.details[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 子订单 ID（同层级对照） | +| data.details | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | +| data.allocs[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| data.allocs | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | +| data.warnings[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| data.warnings | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | +| data.staffSettlements[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| data.staffSettlements | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/order/group-batch/1934567890123456701/audit +``` + +#### 响应示例 + +共 4 处新增 `teamNo`（路径见出参表），此处仅展示其一，其余同构。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "details": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 33. 保存核单录入（GB-ADM-051） `PUT /v3/admin/order/group-batch/{groupBatchId}/audit` + +**VO**: `GroupBatchAuditWriteRespVO` + +#### 使用场景 + +保存核单录入（GB-ADM-051）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| groupBatchId | Path | Long | ✅ | 正整数 | 团期ID | +| items | Body | List | — | — | 科目行全集（与 details 同事务对账保存，未提交的既有行软删） | +| details | Body | List | — | — | 逐户用量全集（按 itemId + orderId 对账） | +| expectedVersion | Body | Integer | — | — | 乐观锁版本，取自 GB-ADM-050 返回的 version | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.warnings[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 关联子订单 ID（同层级对照） | +| data.warnings | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "items": [ + { + "itemId": "1934567890123456790", + "category": "科目", + "itemName": "D2 图嘎营地蒙古包", + "dayNo": 2, + "unitPrice": "380.00", + "totalAmount": "4800.00", + "changeReason": "司机加班费已与车队确认", + "allocRule": "分摊口径", + "allocGroup": "BUS", + "seq": 1 + } + ], + "details": [ + { + "itemId": "1934567890123456790", + "orderId": "1934567890123450001", + "quantity": "2", + "participated": "true", + "allocGroup": "BUS", + "note": "D3 提前离团" + } + ], + "expectedVersion": 3 +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "warnings": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +查询失败静默降为 `null`，不影响其余字段、不回滚已提交的写操作；未付款/未生成团号同样为 `null`。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "warnings": [ + { + "orderId": "1934567890123456701", + "teamNo": null + } + ] + } +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 +- 本端点团号查询走静默降级：查失败不影响其余字段返回、不回滚已提交的写操作。 + +--- + +### 34. 提交核算（GB-ADM-052） `POST /v3/admin/order/group-batch/{groupBatchId}/audit/allocate` + +**VO**: `GroupBatchAuditAllocateRespVO` + +#### 使用场景 + +提交核算（GB-ADM-052）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| groupBatchId | Path | Long | ✅ | 正整数 | 团期ID | +| expectedVersion | Body | Integer | — | — | 乐观锁版本，取自 GB-ADM-050 / 上一次写接口返回的 version | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.allocs[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 子订单 ID（同层级对照） | +| data.allocs | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "expectedVersion": 3 +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "allocs": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +查询失败静默降为 `null`，不影响其余字段、不回滚已提交的写操作；未付款/未生成团号同样为 `null`。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "allocs": [ + { + "orderId": "1934567890123456701", + "teamNo": null + } + ] + } +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 +- 本端点团号查询走静默降级：查失败不影响其余字段返回、不回滚已提交的写操作。 + +--- + +### 35. 团期确认预检(只读，配置 → 确认) `GET /v3/admin/order/group-batch/{groupBatchId}/confirm-check` + +**VO**: `GroupBatchConfirmCheckRespVO` + +#### 使用场景 + +团期确认预检(只读，配置 → 确认)。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| groupBatchId | Path | Long | ✅ | 正整数 | 团期ID | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.unmetHouseholds[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 子订单 ID（同层级对照） | +| data.unmetHouseholds | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/order/group-batch/1934567890123456701/confirm-check +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "unmetHouseholds": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 36. GB-ADM-031 手动开合同/保险 `POST /v3/admin/order/group-batch/{groupBatchId}/contracts/issue` + +**VO**: `GroupBatchIssueResultVO` + +#### 使用场景 + +GB-ADM-031 手动开合同/保险。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| groupBatchId | Path | Long | ✅ | 正整数 | 团期ID | +| orderIds | Body | List | — | — | 要出具的子订单 ID 列表；为空表示本期全部尚未出具的户。 | +| target | Body | String | — | — | 出具目标：CONTRACT 只开合同 / INSURANCE 只开保险 / BOTH 两者都开。 | +| reason | Body | String | — | — | 作废重开时的作废原因（仅 reissue 端点使用，可空） | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.results[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 子订单 ID（同层级对照） | +| data.results | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "orderIds": [], + "target": "CONTRACT", + "reason": "方案选错" +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "results": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 37. GB-ADM-031 作废重开合同/保险 `POST /v3/admin/order/group-batch/{groupBatchId}/contracts/reissue` + +**VO**: `GroupBatchIssueResultVO` + +#### 使用场景 + +GB-ADM-031 作废重开合同/保险。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| groupBatchId | Path | Long | ✅ | 正整数 | 团期ID | +| orderIds | Body | List | — | — | 要出具的子订单 ID 列表；为空表示本期全部尚未出具的户。 | +| target | Body | String | — | — | 出具目标：CONTRACT 只开合同 / INSURANCE 只开保险 / BOTH 两者都开。 | +| reason | Body | String | — | — | 作废重开时的作废原因（仅 reissue 端点使用，可空） | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.results[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 子订单 ID（同层级对照） | +| data.results | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "orderIds": [], + "target": "CONTRACT", + "reason": "方案选错" +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "results": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 38. 批量催签合同 `POST /v3/admin/order/group-batch/{groupBatchId}/contracts/remind-sign` + +**VO**: `GroupBatchIssueResultVO` + +#### 使用场景 + +批量催签合同。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| groupBatchId | Path | Long | ✅ | 正整数 | 团期ID | +| orderIds | Body | List | — | — | 要催签的子订单 ID 列表；为空表示本期全部「合同已出但未签」的户。 | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.results[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 子订单 ID（同层级对照） | +| data.results | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "orderIds": [] +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "results": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 39. A5 团期行程逐日汇总（GB-ADM-018） `GET /v3/admin/order/group-batch/{groupBatchId}/itinerary` + +**VO**: `GroupBatchItineraryRespVO` + +#### 使用场景 + +A5 团期行程逐日汇总（GB-ADM-018）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| groupBatchId | Path | Long | ✅ | 正整数 | 团期ID | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.dayCountOutliers[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 子订单 ID（同层级对照） | +| data.dayCountOutliers | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/order/group-batch/1934567890123456701/itinerary +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "dayCountOutliers": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 40. A6 团期行程某项逐户下钻（GB-ADM-019） `GET /v3/admin/order/group-batch/{groupBatchId}/itinerary/nodes/{nodeKey}` + +**VO**: `GroupBatchItineraryNodeDetailVO` + +#### 使用场景 + +A6 团期行程某项逐户下钻（GB-ADM-019）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| groupBatchId | Path | Long | ✅ | 正整数 | 团期ID | +| nodeKey | Path | String | ✅ | — | 归组键，取自 A5 响应 | +| dayNumber | Query | Integer | — | — | 只看第几天，取自 A5 该卡片所在天；不传=跨天全看 | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.items[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 子订单 ID（同层级对照） | +| data.items | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/order/group-batch/1934567890123456701/itinerary/nodes/归组键，取自 A5 响应?dayNumber=1 +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "items": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 41. 出具团级行程单（只排版全团一致项，差异项标「按户另见」） `GET /v3/admin/order/group-batch/{groupBatchId}/print-itinerary` + +**VO**: `GroupPrintItineraryRespVO` + +#### 使用场景 + +出具团级行程单（只排版全团一致项，差异项标「按户另见」）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| groupBatchId | Path | Long | ✅ | 正整数 | 团期 ID | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.dayCountOutliers[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 子订单 ID（同层级对照） | +| data.dayCountOutliers | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | +| data.roster[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| data.roster | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/order/group-batch/1934567890123456701/print-itinerary +``` + +#### 响应示例 + +共 2 处新增 `teamNo`（路径见出参表），此处仅展示其一，其余同构。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "dayCountOutliers": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 42. 手工复判进入待出发硬门(物资准备中 → 待出发) `POST /v3/admin/order/group-batch/{groupBatchId}/recheck-departure-gate` + +**VO**: `GroupBatchDepartureGateRecheckRespVO` + +#### 使用场景 + +手工复判进入待出发硬门(物资准备中 → 待出发)。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| groupBatchId | Path | Long | ✅ | 正整数 | 团期ID | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.gates[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| blockedOrderId | Long | 卡在哪一户（仅出行人证件 / 合同保险两门可能有值，其余为 null）；（同层级对照） | +| data.gates | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +POST /v3/admin/order/group-batch/1934567890123456701/recheck-departure-gate +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "gates": [ + { + "blockedOrderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +查询失败静默降为 `null`，不影响其余字段、不回滚已提交的写操作；未付款/未生成团号同样为 `null`。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "gates": [ + { + "blockedOrderId": "1934567890123456701", + "teamNo": null + } + ] + } +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 +- 本端点团号查询走静默降级：查失败不影响其余字段返回、不回滚已提交的写操作。 + +--- + +### 43. 全团需求汇总 `GET /v3/admin/order/group-batch/{groupBatchId}/requirement-summary` + +**VO**: `GroupRequirementSummaryRespVO` + +#### 使用场景 + +全团需求汇总。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| groupBatchId | Path | Long | ✅ | 正整数 | 团期ID | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.orderSpecialTags[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 子订单 ID（同层级对照） | +| data.orderSpecialTags | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/order/group-batch/1934567890123456701/requirement-summary +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderSpecialTags": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 44. 整体确认需求缺失预检（只读） `GET /v3/admin/order/group-batch/{groupBatchId}/requirement/confirm-check` + +**VO**: `GroupBatchRequirementCheckRespVO` + +#### 使用场景 + +整体确认需求缺失预检（只读）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| groupBatchId | Path | Long | ✅ | 正整数 | 团期ID | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.missing[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 子订单 ID（同层级对照） | +| data.missing | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | +| data.vehicleMissing[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| data.vehicleMissing | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | +| data.vehicleExemptHouseholds[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| data.vehicleExemptHouseholds | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | +| data.transferDeclaredWithoutRequirement[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| data.transferDeclaredWithoutRequirement | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/order/group-batch/1934567890123456701/requirement/confirm-check +``` + +#### 响应示例 + +共 4 处新增 `teamNo`（路径见出参表），此处仅展示其一，其余同构。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "missing": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 45. 按户打回需求（退回定制师重提） `POST /v3/admin/order/group-batch/{groupBatchId}/requirement/reject` + +**VO**: `GroupBatchRequirementRejectRespVO` + +#### 使用场景 + +按户打回需求（退回定制师重提）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| groupBatchId | Path | Long | ✅ | 正整数 | 团期ID | +| orderIds | Body | List | — | — | 被打回的子订单 ID 列表（必填，1~200 户，服务端去重） | +| reason | Body | String | — | — | 打回原因（必填，≤500 字） | +| resourceType | Body | String | — | — | 资源类型：HOTEL / VEHICLE / ALL（默认 ALL）。 | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.rejected[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 子订单 ID（同层级对照） | +| data.rejected | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "orderIds": [], + "reason": "房间需求与套餐不匹配，请重新填写", + "resourceType": "ALL" +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "rejected": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 46. 批量确认接送机需求（允许部分成功） `POST /v3/admin/order/group-batch/{groupBatchId}/requirement/transfer/batch-confirm` + +**VO**: `TransferBatchConfirmRespVO` + +#### 使用场景 + +批量确认接送机需求（允许部分成功）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| groupBatchId | Path | Long | ✅ | 正整数 | 团期ID | +| orderIds | Body | List | — | — | 待确认的子订单 ID 列表（必填，1~200 户，服务端去重） | +| dispatchRemark | Body | String | — | — | 确认备注（选填，≤500 字；整批共用，提供给车队） | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.failed[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 子订单 ID（同层级对照） | +| data.failed | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "orderIds": [], + "dispatchRemark": "航班信息已核对，请安排接送" +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "failed": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 47. 团期配房明细（只读） `GET /v3/admin/order/group-batch/{groupBatchId}/room-plans` + +**VO**: `GroupBatchRoomPlanDetailRespVO` + +#### 使用场景 + +团期配房明细（只读）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| groupBatchId | Path | Long | ✅ | 正整数 | 团期主订单 ID | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.days[].plans[].allocations[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 分给哪一户（同层级对照） | +| data.days[].plans[].allocations | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/order/group-batch/1934567890123456701/room-plans +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "days": [ + { + "plans": [ + { + "allocations": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } + ] + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 48. 核单按行程节点逐户下钻（GB-ADM-056） `POST /v3/admin/order/group-batch/{groupBatchId}/settlement/node-lines` + +**VO**: `GroupBatchSettlementNodeLinesVO` + +#### 使用场景 + +核单按行程节点逐户下钻（GB-ADM-056）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| groupBatchId | Path | Long | ✅ | 正整数 | 团期ID | +| nodeIds | Body | List | — | — | 行程节点 ID 列表，原样取自团期行程汇总 `days[].nodes[].nodeIds`（雪花，传 String）； | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.rows[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 子订单 ID（同层级对照） | +| data.rows | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "nodeIds": [] +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "rows": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 49. 转订单（子订单跨期转入） `POST /v3/admin/order/group-batch/{groupBatchId}/sub-order/{orderId}/transfer-in` + +**VO**: `TransferSubOrderRespVO` + +#### 使用场景 + +转订单（子订单跨期转入）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| groupBatchId | Path | Long | ✅ | 正整数 | 转入期（本期）团期ID | +| orderId | Path | Long | ✅ | 正整数 | 待转入的子订单ID | +| fromGroupBatchId | Body | Long | — | — | 源期团期主订单 ID（该子订单当前所在期） | +| reason | Body | String | — | — | 转期原因（选填，≤512 字） | +| notify | Body | Boolean | — | — | 转入后是否通知客户（默认 true） | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 被转子订单 ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "fromGroupBatchId": "1932847562341", + "reason": "客户改期，转到第 7 期", + "notify": "true" +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 50. 转订单候选子订单列表 `GET /v3/admin/order/group-batch/{groupBatchId}/transfer-candidates` + +**VO**: `TransferCandidateVO` + +#### 使用场景 + +转订单候选子订单列表。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| groupBatchId | Path | Long | ✅ | 正整数 | 转入期（本期）团期ID | +| keyword | Query | String | — | — | 订单号 / 客户名 / 期号 / 手机号（手机号须整串） | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 子订单 ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/order/group-batch/1934567890123456701/transfer-candidates?keyword=订单号 / 客户名 / 期号 / 手机号 +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": [] +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 51. 读团期正式用车需求（未形成时返回 null；带配车刷新状态只读投影） `GET /v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement` + +**VO**: `GroupVehicleRequirementRespVO` + +#### 使用场景 + +读团期正式用车需求（未形成时返回 null；带配车刷新状态只读投影）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| groupBatchId | Path | Long | ✅ | 正整数 | 团期ID | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.exemptHouseholds[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 子订单ID（同层级对照） | +| data.exemptHouseholds | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/order/group-batch/1934567890123456701/vehicle-requirement +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "exemptHouseholds": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 52. 保存团期正式用车需求（全量替换） `PUT /v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement` + +**VO**: `GroupVehicleRequirementRespVO` + +#### 使用场景 + +保存团期正式用车需求（全量替换）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| groupBatchId | Path | Long | ✅ | 正整数 | 团期ID | +| version | Body | Integer | — | — | 乐观锁版本号，首次保存传 null | +| remark | Body | String | — | — | 整份需求备注 | +| groups | Body | List | — | — | 全部乘车分组（全量替换，未出现在本次提交里的分组会被移出当前版本） | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.exemptHouseholds[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 子订单ID（同层级对照） | +| data.exemptHouseholds | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "version": 3, + "remark": "9/13 起换大巴", + "groups": [ + { + "groupId": "1867000000009", + "groupCode": "BUS", + "vehicleType": "bus", + "serviceStartDate": "2026-09-12", + "serviceEndDate": "2026-09-16", + "seats": 19, + "count": 2, + "specialTags": [], + "remark": "含高速费", + "days": [ + { + "dayId": "1934567890123456701", + "dayNumber": 1, + "dayTitle": "天标题", + "description": "天描述/简介", + "nodes": [], + "hotels": [], + "coverUrl": "当日封面图URL, 来自 product", + "gatherPlace": null, + "dismissalPlace": null, + "routePoints": [], + "dailyMileage": "1000.00", + "serviceTips": [] + } + ] + } + ] +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "exemptHouseholds": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 53. 自动汇总正式用车需求草稿（只读；草稿可原样 PUT） `GET /v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement/aggregate-draft` + +**VO**: `GroupVehicleAggregateDraftRespVO` + +#### 使用场景 + +自动汇总正式用车需求草稿（只读；草稿可原样 PUT）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| groupBatchId | Path | Long | ✅ | 正整数 | 团期ID | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.droppedFleetItems[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 子订单ID（同层级对照） | +| data.droppedFleetItems | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | +| data.staleHeadcountOrders[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| data.staleHeadcountOrders | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | +| data.paddedOrderDays[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| data.paddedOrderDays | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | +| data.seatOptionAdjusted[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| data.seatOptionAdjusted | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | +| data.violations[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| data.violations | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | +| data.exemptHouseholds[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| data.exemptHouseholds | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/order/group-batch/1934567890123456701/vehicle-requirement/aggregate-draft +``` + +#### 响应示例 + +共 6 处新增 `teamNo`（路径见出参表），此处仅展示其一，其余同构。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "droppedFleetItems": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 54. 声明整团无需用车（零分组已确认，撤销走 withdraw） `POST /v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement/waive` + +**VO**: `GroupVehicleRequirementRespVO` + +#### 使用场景 + +声明整团无需用车（零分组已确认，撤销走 withdraw）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| groupBatchId | Path | Long | ✅ | 正整数 | 团期ID | +| reason | Body | String | — | — | 免车原因（追加进整份备注留痕） | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.exemptHouseholds[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 子订单ID（同层级对照） | +| data.exemptHouseholds | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "reason": "纯自驾团，客户自理交通" +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "exemptHouseholds": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 55. 整份撤回正式用车需求（退回草稿，已配车辆不动） `POST /v3/admin/order/group-batch/{groupBatchId}/vehicle-requirement/withdraw` + +**VO**: `GroupVehicleRequirementRespVO` + +#### 使用场景 + +整份撤回正式用车需求（退回草稿，已配车辆不动）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| groupBatchId | Path | Long | ✅ | 正整数 | 团期ID | +| reason | Body | String | — | — | 撤回原因（写入整份备注留痕） | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.exemptHouseholds[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 子订单ID（同层级对照） | +| data.exemptHouseholds | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "reason": "人数有变，重新汇总" +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "exemptHouseholds": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 56. 发票详情(完整申请明细，供上传弹窗/详情页) `GET /v3/admin/order/invoice/{id}` + +**VO**: `AdminInvoiceDetailRespVO` + +#### 使用场景 + +发票详情(完整申请明细，供上传弹窗/详情页)。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| id | Path | Long | ✅ | 正整数 | 发票 ID | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单 ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/order/invoice/1934567890123456701 +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 57. 生成用餐信息（按订单产品快照生成空行，已有行不重复生成） `POST /v3/admin/order/meal-info/generate` + +**VO**: `OrderMealInfoListRespVO` + +#### 使用场景 + +生成用餐信息（按订单产品快照生成空行，已有行不重复生成）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Body | Long | — | — | 订单ID；正数；与 groupBatchId 必须且只能传一个 | +| groupBatchId | Body | Long | — | — | 团期ID；正数；与 orderId 必须且只能传一个 | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 入参订单ID，没传为 null（同层级对照） | +| data.items[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| data.items | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "orderId": "1934567890123456701", + "groupBatchId": "1934567890123456701" +} +``` + +#### 响应示例 + +共 2 处新增 `teamNo`（路径见出参表），此处仅展示其一，其余同构。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 58. 查询用餐信息列表（按订单 / 团期 / 未挂归属） `GET /v3/admin/order/meal-info/list` + +**VO**: `OrderMealInfoListRespVO` + +#### 使用场景 + +查询用餐信息列表（按订单 / 团期 / 未挂归属）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Query | Long | — | — | 订单ID；正数；与 groupBatchId 必须且只能传一个 | +| groupBatchId | Query | Long | — | — | 团期ID；正数；与 orderId 必须且只能传一个 | +| batchNo | Query | String | — | — | 团期编号精确匹配；最多 64 字符 | +| mealType | Query | String | — | — | 类别 | +| mealDateStart | Query | LocalDate | — | — | 用餐日期起（含），yyyy-MM-dd | +| mealDateEnd | Query | LocalDate | — | — | 用餐日期止（含），yyyy-MM-dd；同时传时须 ≥ mealDateStart | +| dayNumber | Query | Integer | — | — | 第几天；≥ 1 | +| settleType | Query | String | — | — | 付款方式 | +| keyword | Query | String | — | — | 关键字，最多 64 字符；模糊匹配餐厅名称、餐食名称 | +| limit | Query | Integer | — | — | 最大返回条数，默认 200；1–500 | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 入参订单ID，没传为 null（同层级对照） | +| data.items[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| data.items | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/order/meal-info/list?orderId=1934567890123456701&groupBatchId=1934567890123456701&batchNo=团期编号精确匹配；最多 64 字符&mealType=类别&mealDateStart=2026-07-05&mealDateEnd=2026-07-07 +``` + +#### 响应示例 + +共 2 处新增 `teamNo`（路径见出参表），此处仅展示其一，其余同构。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 59. 重置用餐信息（删掉全部行后按快照重新生成空行） `POST /v3/admin/order/meal-info/reset` + +**VO**: `OrderMealInfoListRespVO` + +#### 使用场景 + +重置用餐信息（删掉全部行后按快照重新生成空行）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Body | Long | — | — | 订单ID；正数；与 groupBatchId 必须且只能传一个 | +| groupBatchId | Body | Long | — | — | 团期ID；正数；与 orderId 必须且只能传一个 | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 入参订单ID，没传为 null（同层级对照） | +| data.items[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| data.items | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "orderId": "1934567890123456701", + "groupBatchId": "1934567890123456701" +} +``` + +#### 响应示例 + +共 2 处新增 `teamNo`（路径见出参表），此处仅展示其一，其余同构。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 60. 保存用餐信息（整单一次保存：带行ID覆盖、不带新增、没传上来的软删） `POST /v3/admin/order/meal-info/save` + +**VO**: `OrderMealInfoListRespVO` + +#### 使用场景 + +保存用餐信息（整单一次保存：带行ID覆盖、不带新增、没传上来的软删）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Body | Long | — | — | 订单ID；正数；与 groupBatchId 必须且只能传一个 | +| groupBatchId | Body | Long | — | — | 团期ID；正数；与 orderId 必须且只能传一个 | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 入参订单ID，没传为 null（同层级对照） | +| data.items[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| data.items | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "orderId": "1934567890123456701", + "groupBatchId": "1934567890123456701" +} +``` + +#### 响应示例 + +共 2 处新增 `teamNo`（路径见出参表），此处仅展示其一，其余同构。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 61. 套用用餐模版（返回订单现有行 + 模版套出来的行，模版行接在后面，不改库） `POST /v3/admin/order/meal-template/apply` + +**VO**: `OrderMealInfoListRespVO` + +#### 使用场景 + +套用用餐模版（返回订单现有行 + 模版套出来的行，模版行接在后面，不改库）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Body | Long | — | — | 订单ID；正数；与 groupBatchId 必须且只能传一个 | +| groupBatchId | Body | Long | — | — | 团期ID；正数；与 orderId 必须且只能传一个 | +| templateId | Body | Long | — | — | 要套用的模版ID | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 入参订单ID，没传为 null（同层级对照） | +| data.items[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| data.items | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "orderId": "1934567890123456701", + "groupBatchId": "1934567890123456701", + "templateId": "1934567890123456701" +} +``` + +#### 响应示例 + +共 2 处新增 `teamNo`（路径见出参表），此处仅展示其一，其余同构。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 62. §2.5 房间分配查询(按家庭分组) `GET /v3/admin/order/orders/{orderId}/rooms` + +**VO**: `OrderRoomsRespVO` + +#### 使用场景 + +§2.5 房间分配查询(按家庭分组)。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Path | Long | ✅ | 正整数 | 订单 ID | +| dayNumber | Query | Integer | — | — | dayNumber | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单 ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/order/orders/1934567890123456701/rooms?dayNumber=1 +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 63. 受控推进单个订单状态（走状态机+写日志+联动房车日期，幂等） `POST /v3/admin/order/{id}/advance-state` + +**VO**: `OrderAdvanceStateRespVO` + +#### 使用场景 + +受控推进单个订单状态（走状态机+写日志+联动房车日期，幂等）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| id | Path | Long | ✅ | 正整数 | id | +| targetStatus | Body | String | — | — | 目标粗状态（TRAVELLING / COMPLETED） | +| departDate | Body | LocalDate | — | — | 新出发日（与 returnDate 必须成对提供；不传则沿用订单现有日期做联动） | +| returnDate | Body | LocalDate | — | — | 新返程日（与 departDate 必须成对提供；tripDays 由两端日期派生） | +| normalizeAssignmentDates | Body | Boolean | — | — | 是否联动归一房/车派行日期到订单窗口（默认 true；false 时仅车侧做窗口校验、出窗直接报错，房侧完全跳过不动） | +| reason | Body | String | — | — | 操作原因（写入状态日志） | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单 ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "targetStatus": "TRAVELLING", + "departDate": "2026-08-18", + "returnDate": "2026-08-20", + "normalizeAssignmentDates": "true", + "reason": "行程中终止测试前推进订单到出行中" +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 64. 订单详情 - 发票 Tab `GET /v3/admin/order/{id}/invoices` + +**VO**: `InvoiceVO` + +#### 使用场景 + +订单详情 - 发票 Tab。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| id | Path | Long | ✅ | 正整数 | 订单 ID | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单 ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/order/1934567890123456701/invoices +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": [] +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 65. 查询 staff 配置列表 `GET /v3/admin/order/{id}/staff` + +**VO**: `StaffAssignmentVO` + +#### 使用场景 + +查询 staff 配置列表。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| id | Path | Long | ✅ | 正整数 | 订单 ID | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单 ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/order/1934567890123456701/staff +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": [] +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 66. 新增 staff 配置 `POST /v3/admin/order/{id}/staff` + +**VO**: `StaffAssignmentVO` + +#### 使用场景 + +新增 staff 配置。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| id | Path | Long | ✅ | 正整数 | 订单 ID | +| staffId | Body | Long | — | — | 用户域员工 ID | +| staffRole | Body | String | — | — | 员工角色（LEADER / DRIVER / PHOTOGRAPHER / OTHER） | +| sortOrder | Body | Integer | — | — | 展示排序（默认 0） | +| remark | Body | String | — | — | 备注（≤500） | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单 ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "staffId": "40001", + "staffRole": "LEADER", + "sortOrder": 0, + "remark": "首席领队，10 年经验" +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +查询失败静默降为 `null`，不影响其余字段、不回滚已提交的写操作；未付款/未生成团号同样为 `null`。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": null + } +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 +- 本端点团号查询走静默降级：查失败不影响其余字段返回、不回滚已提交的写操作。 + +--- + +### 67. 编辑 staff 配置 `PUT /v3/admin/order/{id}/staff/{staffAssignmentId}` + +**VO**: `StaffAssignmentVO` + +#### 使用场景 + +编辑 staff 配置。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| id | Path | Long | ✅ | 正整数 | 订单 ID | +| staffAssignmentId | Path | Long | ✅ | 正整数 | staff_assignment ID | +| staffId | Body | Long | — | — | 用户域员工 ID | +| staffRole | Body | String | — | — | 员工角色（LEADER / DRIVER / PHOTOGRAPHER / OTHER） | +| sortOrder | Body | Integer | — | — | 展示排序（默认 0） | +| remark | Body | String | — | — | 备注（≤500） | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单 ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "staffId": "40001", + "staffRole": "LEADER", + "sortOrder": 0, + "remark": "首席领队，10 年经验" +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +查询失败静默降为 `null`，不影响其余字段、不回滚已提交的写操作；未付款/未生成团号同样为 `null`。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": null + } +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 +- 本端点团号查询走静默降级：查失败不影响其余字段返回、不回滚已提交的写操作。 + +--- + +### 68. 设置 staff 报账人等级（核心订单） `PUT /v3/admin/order/{id}/staff/{staffAssignmentId}/reporter-rank` + +**VO**: `StaffAssignmentVO` + +#### 使用场景 + +设置 staff 报账人等级（核心订单）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| id | Path | Long | ✅ | 正整数 | 订单 ID | +| staffAssignmentId | Path | Long | ✅ | 正整数 | staff_assignment ID | +| reporterRank | Body | ReporterRank | — | — | 报账人等级（PRIMARY=主报账人 / SECONDARY=次报账人 / NONE=非报账人） | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单 ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "reporterRank": null +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 69. 终止行程·退款预览（出行中） `POST /v3/admin/order/{id}/terminate/refund-preview` + +**VO**: `OrderTerminateRefundPreviewRespVO` + +#### 使用场景 + +终止行程·退款预览（出行中）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| id | Path | Long | ✅ | 正整数 | 订单 ID | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderNo | String | 订单号（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +POST /v3/admin/order/1934567890123456701/terminate/refund-preview +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderNo": "订单号", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 70. 大交通批次新增 `POST /v3/admin/order/{id}/transport-plan/add` + +**VO**: `TransportPlanVO` + +#### 使用场景 + +大交通批次新增。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| id | Path | Long | ✅ | 正整数 | 订单 ID | +| direction | Body | String | — | — | 方向：ARRIVAL / DEPARTURE | +| transportType | Body | String | — | — | 交通类型：FLIGHT / TRAIN / SELF_DRIVE | +| transportNo | Body | String | — | — | 航班号 / 车次号；SELF_DRIVE 时为空 | +| carrier | Body | String | — | — | 航司 / 铁路公司 | +| departStation | Body | String | — | — | 出发站 | +| arriveStation | Body | String | — | — | 到达站 | +| departTime | Body | LocalDateTime | — | — | 出发时间（FLIGHT/TRAIN 必填） | +| arriveTime | Body | LocalDateTime | — | — | 到达时间（FLIGHT/TRAIN 必填） | +| selfDrivePeriod | Body | String | — | — | 自驾时段（仅 SELF_DRIVE）：MORNING / AFTERNOON / EVENING | +| selfDriveEta | Body | LocalDateTime | — | — | 自驾预计到达时间（仅 SELF_DRIVE 可选） | +| travelerIds | Body | List | — | — | 关联出行人 ID（至少 1 个） | +| pickupRequired | Body | Boolean | — | — | 是否需要接送；新增缺省为 true，编辑缺省保留原值 | +| pickupRemark | Body | String | — | — | 接送备注 | +| remark | Body | String | — | — | 备注（≤500） | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单 ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +此处仅示例前 10 个字段，完整字段见入参表。 + +```json +{ + "direction": "ARRIVAL", + "transportType": "FLIGHT", + "transportNo": "CA1234", + "carrier": "中国国际航空", + "departStation": "北京首都T3", + "arriveStation": "长春龙嘉", + "departTime": "2026-06-01T08:30:00", + "arriveTime": "2026-06-01T10:15:00", + "selfDrivePeriod": "AFTERNOON", + "selfDriveEta": "2026-06-05T15:00:00" +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +查询失败静默降为 `null`，不影响其余字段、不回滚已提交的写操作；未付款/未生成团号同样为 `null`。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": null + } +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 +- 本端点团号查询走静默降级：查失败不影响其余字段返回、不回滚已提交的写操作。 + +--- + +### 71. 大交通批次批量替换 `POST /v3/admin/order/{id}/transport-plan/batch` + +**VO**: `TransportPlanBatchRespVO` + +#### 使用场景 + +大交通批次批量替换。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| id | Path | Long | ✅ | 正整数 | 订单 ID | +| plans | Body | List | — | — | 交通批次列表（全量覆盖订单已有批次） | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.plans[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单 ID（同层级对照） | +| data.plans | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "plans": [ + { + "direction": "ARRIVAL", + "transportType": "FLIGHT", + "transportNo": "CA1234", + "carrier": "中国国际航空", + "departStation": "北京首都T3", + "arriveStation": "长春龙嘉", + "departTime": "2026-06-01T08:30:00", + "arriveTime": "2026-06-01T10:15:00", + "selfDrivePeriod": "AFTERNOON", + "selfDriveEta": "2026-06-05T15:00:00", + "travelerIds": [], + "pickupRequired": "true", + "pickupRemark": "需在 T3 出口举牌接机", + "remark": "需要接机举牌" + } + ] +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "plans": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +查询失败静默降为 `null`，不影响其余字段、不回滚已提交的写操作；未付款/未生成团号同样为 `null`。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "plans": [ + { + "orderId": "1934567890123456701", + "teamNo": null + } + ] + } +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 +- 本端点团号查询走静默降级：查失败不影响其余字段返回、不回滚已提交的写操作。 + +--- + +### 72. 大交通批次列表 `GET /v3/admin/order/{id}/transport-plan/list` + +**VO**: `TransportPlanListRespVO` + +#### 使用场景 + +大交通批次列表。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| id | Path | Long | ✅ | 正整数 | 订单 ID | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单 ID（同层级对照） | +| data.arrivals[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| data.arrivals | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | +| data.departures[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| data.departures | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/order/1934567890123456701/transport-plan/list +``` + +#### 响应示例 + +共 3 处新增 `teamNo`（路径见出参表），此处仅展示其一，其余同构。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 73. 大交通批次编辑 `POST /v3/admin/order/{id}/transport-plan/{planId}/edit` + +**VO**: `TransportPlanVO` + +#### 使用场景 + +大交通批次编辑。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| id | Path | Long | ✅ | 正整数 | 订单 ID | +| planId | Path | Long | ✅ | 正整数 | 批次 ID | +| direction | Body | String | — | — | 方向：ARRIVAL / DEPARTURE | +| transportType | Body | String | — | — | 交通类型：FLIGHT / TRAIN / SELF_DRIVE | +| transportNo | Body | String | — | — | 航班号 / 车次号；SELF_DRIVE 时为空 | +| carrier | Body | String | — | — | 航司 / 铁路公司 | +| departStation | Body | String | — | — | 出发站 | +| arriveStation | Body | String | — | — | 到达站 | +| departTime | Body | LocalDateTime | — | — | 出发时间（FLIGHT/TRAIN 必填） | +| arriveTime | Body | LocalDateTime | — | — | 到达时间（FLIGHT/TRAIN 必填） | +| selfDrivePeriod | Body | String | — | — | 自驾时段（仅 SELF_DRIVE）：MORNING / AFTERNOON / EVENING | +| selfDriveEta | Body | LocalDateTime | — | — | 自驾预计到达时间（仅 SELF_DRIVE 可选） | +| travelerIds | Body | List | — | — | 关联出行人 ID（至少 1 个） | +| pickupRequired | Body | Boolean | — | — | 是否需要接送；新增缺省为 true，编辑缺省保留原值 | +| pickupRemark | Body | String | — | — | 接送备注 | +| remark | Body | String | — | — | 备注（≤500） | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单 ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +此处仅示例前 10 个字段，完整字段见入参表。 + +```json +{ + "direction": "ARRIVAL", + "transportType": "FLIGHT", + "transportNo": "CA1234", + "carrier": "中国国际航空", + "departStation": "北京首都T3", + "arriveStation": "长春龙嘉", + "departTime": "2026-06-01T08:30:00", + "arriveTime": "2026-06-01T10:15:00", + "selfDrivePeriod": "AFTERNOON", + "selfDriveEta": "2026-06-05T15:00:00" +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +查询失败静默降为 `null`，不影响其余字段、不回滚已提交的写操作；未付款/未生成团号同样为 `null`。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": null + } +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 +- 本端点团号查询走静默降级：查失败不影响其余字段返回、不回滚已提交的写操作。 + +--- + +### 74. 单个出行人新增 `POST /v3/admin/order/{id}/traveler/add` + +**VO**: `TravelerVO` + +#### 使用场景 + +单个出行人新增。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| id | Path | Long | ✅ | 正整数 | 订单 ID | +| name | Body | String | — | — | 姓名（可后填） | +| gender | Body | String | — | — | 性别：1=男 / 2=女 / 0=未知 | +| birthday | Body | LocalDate | — | — | 出生日期（必填，后端按年龄分段自动派生出行人类型） | +| idType | Body | String | — | — | 证件类型（取值见数据字典 id_card_type） | +| idNo | Body | String | — | — | 证件号（明文传，DB 加密） | +| nationality | Body | String | — | — | 国籍（默认中国） | +| race | Body | String | — | — | 民族（默认汉族） | +| phone | Body | String | — | — | 出行人手机（明文传，DB 加密） | +| emergencyContact | Body | String | — | — | 紧急联系人姓名 | +| emergencyPhone | Body | String | — | — | 紧急联系人电话（明文传） | +| roomGroupNo | Body | Integer | — | — | 同住分组号 | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单 ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +此处仅示例前 10 个字段，完整字段见入参表。 + +```json +{ + "name": "王小明", + "gender": "1", + "birthday": "2018-06-20", + "idType": "ID_CARD", + "idNo": "220103201806201234", + "nationality": "中国", + "race": "汉族", + "phone": "13812342046", + "emergencyContact": "王大明", + "emergencyPhone": "13988888888" +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 75. 出行人列表 `GET /v3/admin/order/{id}/traveler/list` + +**VO**: `TravelerVO` + +#### 使用场景 + +出行人列表。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| id | Path | Long | ✅ | 正整数 | 订单 ID | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单 ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/order/1934567890123456701/traveler/list +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": [] +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 76. 订单增减项（统一端点，按 direction 分流） `POST /v3/admin/order/{orderId}/adjustment` + +**VO**: `OrderAdjustmentRespVO` + +#### 使用场景 + +订单增减项（统一端点，按 direction 分流）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Path | Long | ✅ | 正整数 | 订单 ID | +| direction | Body | AdjustmentDirection | — | — | 增减方向：REDUCE=减项/优惠，ADD=增项/附加费 | +| itemCode | Body | String | — | — | 项目 itemCode：REDUCE 时取 order_discount_item 字典 value，ADD 时取 order_surcharge_item 字典 value | +| amount | Body | BigDecimal | — | — | 金额（元），必须 > 0 | +| remark | Body | String | — | — | 备注（≤500 字） | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单 ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "direction": null, + "itemCode": "OLD_CUSTOMER", + "amount": "200.00", + "remark": "春节活动老客户优惠" +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 77. 创建预支（创建即待审批） `POST /v3/admin/order/{orderId}/advance` + +**VO**: `OrderAdvanceRespVO` + +#### 使用场景 + +创建预支（创建即待审批）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Path | Long | ✅ | 正整数 | 订单ID | +| payeeStaffId | Body | Long | — | — | 借款对象（必填，取候选下拉的 id=assignmentId） | +| advanceType | Body | String | — | — | 预支借款类型（必填，取字典 advance_type 的 dictValue） | +| amount | Body | BigDecimal | — | — | 预支金额（必填，必须大于0） | +| purpose | Body | String | — | — | 用途说明（可选） | +| voucherUrl | Body | String | — | — | 凭证文件URL（可选） | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "payeeStaffId": "1934567890123456701", + "advanceType": "预支借款类型", + "amount": "1000.00", + "purpose": "用途说明", + "voucherUrl": "凭证文件URL" +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 78. 分页查询本单预支列表 `GET /v3/admin/order/{orderId}/advances` + +**VO**: `OrderAdvanceRespVO` + +#### 使用场景 + +分页查询本单预支列表。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Path | Long | ✅ | 正整数 | 订单ID | +| page | Query | Integer | — | 默认 1 | 页码 | +| pageSize | Query | Integer | — | 默认 20 | 每页条数 | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.records[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/order/1934567890123456701/advances?page=1&pageSize=1 +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "records": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "records": [] + } +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 79. 查询订单优惠+附加费清单 `GET /v3/admin/order/{orderId}/discount-surcharge/list` + +**VO**: `OrderDiscountSurchargeListRespVO` + +#### 使用场景 + +查询订单优惠+附加费清单。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Path | Long | ✅ | 正整数 | 订单 ID | +| includeReversed | Query | Boolean | — | — | includeReversed | +| category | Query | String | — | — | category | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单 ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/order/1934567890123456701/discount-surcharge/list?includeReversed=True&category=category +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 80. 新增订单优惠（已废弃，改调 /adjustment） `POST /v3/admin/order/{orderId}/discounts` + +**VO**: `OrderDiscountRespVO` + +#### 使用场景 + +新增订单优惠（已废弃，改调 /adjustment）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Path | Long | ✅ | 正整数 | 订单 ID | +| discountType | Body | String | — | — | 优惠类型（EARLY_BIRD/VIP/MANUAL/ROOM_DOWNGRADE/VEHICLE_DOWNGRADE/OTHER，REVERSAL 禁手填） | +| discountName | Body | String | — | — | 优惠描述（前端展示用，≤128 字） | +| discountAmount | Body | BigDecimal | — | — | 优惠金额，单位元，必须 > 0 | +| sourceType | Body | String | — | — | 来源类型（MANUAL/ROOM_ASSIGN/VEHICLE_ASSIGN/ITINERARY_EDIT/EARLY_BIRD_PLAN，默认 MANUAL） | +| sourceRefId | Body | Long | — | — | 来源关联 ID（MANUAL 时为 null，其他类型必填） | +| remark | Body | String | — | — | 备注（≤500 字） | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单 ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "discountType": "MANUAL", + "discountName": "老客户回馈减免 200", + "discountAmount": "200.00", + "sourceType": "MANUAL", + "sourceRefId": "null", + "remark": "备注" +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 81. 定制师代客申请发票（须订单已完成） `POST /v3/admin/order/{orderId}/invoice/apply` + +**VO**: `AdminInvoiceApplyRespVO` + +#### 使用场景 + +定制师代客申请发票（须订单已完成）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Path | Long | ✅ | 正整数 | 订单 ID | +| invoiceType | Body | String | — | — | 发票类型：VAT_NORMAL（增值税普通发票）/ VAT_SPECIAL（增值税专用发票）。增值税专用发票只能开给单位（COMPANY） | +| titleType | Body | String | — | — | 抬头类型：COMPANY / PERSONAL。增值税专用发票只能开给单位（COMPANY） | +| titleName | Body | String | — | — | 抬头名称（公司全称或个人姓名） | +| taxNo | Body | String | — | — | 税号（titleType=COMPANY 必填；invoiceType=VAT_SPECIAL 必填） | +| bankName | Body | String | — | — | 开户行（invoiceType=VAT_SPECIAL 必填） | +| bankAccount | Body | String | — | — | 开户账号（invoiceType=VAT_SPECIAL 必填） | +| registAddress | Body | String | — | — | 注册地址（invoiceType=VAT_SPECIAL 必填） | +| registPhone | Body | String | — | — | 注册电话（invoiceType=VAT_SPECIAL 必填） | +| email | Body | String | — | — | 收件邮箱（必填） | +| remark | Body | String | — | — | 备注 / 货物或应税劳务名称（可选） | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单 ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "invoiceType": "COMPANY", + "titleType": "COMPANY", + "titleName": "抬头名称", + "taxNo": "税号", + "bankName": "开户行", + "bankAccount": "开户账号", + "registAddress": "注册地址", + "registPhone": "注册电话", + "email": "收件邮箱", + "remark": "备注 / 货物或应税劳务名称" +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 82. 生成电子行程单数据（对客） `GET /v3/admin/order/{orderId}/itinerary-document` + +**VO**: `OrderItineraryDocumentVO` + +#### 使用场景 + +生成电子行程单数据（对客）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Path | Long | ✅ | 正整数 | 订单 ID | +| documentType | Query | String | ✅ | — | 文档类型（对客视角）：CUSTOMER / CUSTOMER_PRINT / CUSTOMER_QUOTE | +| includeResourceDetail | Query | Boolean | — | — | includeResourceDetail | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.header.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderNo | String | 订单号（同层级对照） | +| data.header | HeaderVO | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/order/1934567890123456701/itinerary-document?documentType=文档类型&includeResourceDetail=True +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "header": { + "orderNo": "订单号", + "teamNo": "26-0480" + } + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 83. 查询订单完整行程（含全部实配嵌套，已真实化 Issue #2471） `GET /v3/admin/order/{orderId}/itinerary/full` + +**VO**: `OrderItineraryRespVO` + +#### 使用场景 + +查询订单完整行程（含全部实配嵌套，已真实化 Issue #2471）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Path | Long | ✅ | 正整数 | 订单 ID | +| dayNumber | Query | Integer | — | — | 仅返回指定某天（不传=全返） | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单 ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/order/1934567890123456701/itinerary/full?dayNumber=1 +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 84. 查询订单线下收款列表（含已撤销行，审计溯源用） `GET /v3/admin/order/{orderId}/payment/manual-receipt` + +**VO**: `ManualReceiptVO` + +#### 使用场景 + +查询订单线下收款列表（含已撤销行，审计溯源用）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Path | Long | ✅ | 正整数 | orderId | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单 ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/order/1934567890123456701/payment/manual-receipt +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": [] +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 85. 登记线下收款（报账人收款/对公转账/定制师代收），同事务推进 paid_amount `POST /v3/admin/order/{orderId}/payment/manual-receipt` + +**VO**: `ManualReceiptVO` + +#### 使用场景 + +登记线下收款（报账人收款/对公转账/定制师代收），同事务推进 paid_amount。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Path | Long | ✅ | 正整数 | orderId | +| channel | Body | String | — | — | 收款渠道 DRIVER_CASH/BANK_TRANSFER/CONSULTANT_COLLECTION | +| payType | Body | String | — | — | 款项类型 DEPOSIT/BALANCE/FULL | +| amount | Body | BigDecimal | — | — | 收款金额（> 0） | +| receivedAt | Body | LocalDateTime | — | — | 收款时间（可为过去时间，不传默认当前时间） | +| transferRef | Body | String | — | — | 对公转账流水号（BANK_TRANSFER 渠道必填） | +| receiptMethod | Body | String | — | — | 收款方式（可选，字典 manual_receipt_method，当前暂不校验） | +| collectorStaffId | Body | Long | — | — | 代收人 assignmentId（DRIVER_CASH 必填，属本单报账人） | +| collectorType | Body | String | — | — | 实际代收人类型 ORDER_STAFF/CONSULTANT/COMPANY_ACCOUNT；不传时按 channel 兼容推导 | +| voucherUrls | Body | List | — | — | 凭证图片 URL 列表 | +| remark | Body | String | — | — | 备注（最长 500 字） | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单 ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "channel": "DRIVER_CASH", + "payType": "BALANCE", + "amount": "5000.00", + "receivedAt": "2026-07-05T14:30:00", + "transferRef": "GZL20260705001", + "receiptMethod": "WECHAT_TRANSFER", + "collectorStaffId": "123456789", + "collectorType": "ORDER_STAFF", + "voucherUrls": [], + "remark": "客户现场支付尾款" +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 86. 撤销线下收款（同事务回退 paid_amount，行保留可追溯） `DELETE /v3/admin/order/{orderId}/payment/manual-receipt/{receiptId}` + +**VO**: `ManualReceiptVO` + +#### 使用场景 + +撤销线下收款（同事务回退 paid_amount，行保留可追溯）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Path | Long | ✅ | 正整数 | orderId | +| receiptId | Path | Long | ✅ | 正整数 | receiptId | +| voidReason | Body | String | — | — | 撤销原因（建议填写） | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单 ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "voidReason": "客户实际未支付，误录" +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 87. 财务复核确认结算 `POST /v3/admin/order/{orderId}/settlement/confirm` + +**VO**: `ConfirmSettlementRespVO` + +#### 使用场景 + +财务复核确认结算。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Path | Long | ✅ | 正整数 | 订单 ID | +| confirmRemark | Body | String | — | — | 复核备注（可选） | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单 ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "confirmRemark": "核对无误，确认结算" +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 88. 管理员反确认核单终态快照 `POST /v3/admin/order/{orderId}/settlement/final-snapshots/reopen` + +**VO**: `SettlementReopenRespVO` + +#### 使用场景 + +管理员反确认核单终态快照。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Path | Long | ✅ | 正整数 | orderId | +| expectedSnapshotId | Body | Long | — | — | 前端当前看到的终态快照 ID | +| expectedVersionNo | Body | Integer | — | — | 前端当前看到的终态快照版本号 | +| reason | Body | String | — | — | 反确认原因 | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单 ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "expectedSnapshotId": "9600000000001", + "expectedVersionNo": 1, + "reason": "补录车辆费用凭证" +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 89. 完成核单 `POST /v3/admin/order/{orderId}/settlement/finalize` + +**VO**: `SettlementSubmitRespVO` + +#### 使用场景 + +完成核单。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Path | Long | ✅ | 正整数 | orderId | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单 ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +POST /v3/admin/order/1934567890123456701/settlement/finalize +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 90. 查询核单操作日志 `GET /v3/admin/order/{orderId}/settlement/logs` + +**VO**: `RecordVO` + +#### 使用场景 + +查询核单操作日志。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Path | Long | ✅ | 正整数 | 订单 ID | +| page | Query | Integer | — | — | 页码 | +| pageSize | Query | Integer | — | — | 每页条数 | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.records[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/order/{orderId}/settlement/logs?page=1&pageSize=20 +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "records": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "records": [] + } +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 91. 查询车辆核单草稿 `GET /v3/admin/order/{orderId}/settlement/step3/vehicles` + +**VO**: `SettlementVehicleFeesRespVO` + +#### 使用场景 + +查询车辆核单草稿。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Path | Long | ✅ | 正整数 | orderId | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单ID；JSON按字符串序列化，避免JavaScript精度丢失（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/order/1934567890123456701/settlement/step3/vehicles +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 92. 全量保存车辆核单草稿 `PUT /v3/admin/order/{orderId}/settlement/step3/vehicles` + +**VO**: `SettlementVehicleFeesRespVO` + +#### 使用场景 + +全量保存车辆核单草稿。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Path | Long | ✅ | 正整数 | orderId | +| items | Body | List | — | — | 全量明细 | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单ID；JSON按字符串序列化，避免JavaScript精度丢失（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "items": [ + { + "id": "1934567890123456701", + "sourceType": "sourceType", + "requirementKind": "需求归属类别", + "serviceDate": "2026-09-27", + "vehicleId": "1934567890123456701", + "vehiclePlate": "vehiclePlate", + "vehicleModelId": "1934567890123456701", + "vehicleModelName": "vehicleModelName", + "driverId": "1934567890123456701", + "driverName": "driverName", + "amount": "1000.00", + "paymentMethod": "paymentMethod", + "settlementConfirmStatus": "settlementConfirmStatus", + "remark": "remark" + } + ] +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 93. 查核单汇总快照 `GET /v3/admin/order/{orderId}/settlement/summary` + +**VO**: `SettlementSummaryRespVO` + +#### 使用场景 + +查核单汇总快照。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Path | Long | ✅ | 正整数 | 订单 ID | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单 ID（同层级对照） | +| data.advanceSummary.records[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| data.advanceSummary.records | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/order/1934567890123456701/settlement/summary +``` + +#### 响应示例 + +共 2 处新增 `teamNo`（路径见出参表），此处仅展示其一，其余同构。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 94. 新增订单附加费（已废弃，改调 /adjustment） `POST /v3/admin/order/{orderId}/surcharges` + +**VO**: `OrderSurchargeRespVO` + +#### 使用场景 + +新增订单附加费（已废弃，改调 /adjustment）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Path | Long | ✅ | 正整数 | 订单 ID | +| surchargeName | Body | String | — | — | 附加费描述（≤128 字） | +| surchargeAmount | Body | BigDecimal | — | — | 附加费金额，单位元，必须 > 0 | +| sourceType | Body | String | — | — | 来源类型（MANUAL/ROOM_ASSIGN/VEHICLE_ASSIGN/ITINERARY_EDIT/SCENIC_ASSIGNMENT/ACTIVITY_ASSIGNMENT，REVERSAL 禁手填） | +| sourceRefId | Body | Long | — | — | 来源关联 ID（MANUAL 时为 null，其他类型必填） | +| remark | Body | String | — | — | 备注（≤500 字） | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单 ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "surchargeName": "加项景点：羊卓雍措一日游", + "surchargeAmount": "240.00", + "sourceType": "ITINERARY_EDIT", + "sourceRefId": "6601234567905", + "remark": "备注" +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 95. 增订单标签 `POST /v3/admin/order/{orderId}/tag` + +**VO**: `OrderTagVO` + +#### 使用场景 + +增订单标签。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Path | Long | ✅ | 正整数 | 订单 ID | +| tagName | Body | String | — | — | 标签名（≤50 字，禁前后空格/禁特殊符号） | +| tagColor | Body | String | — | — | 前端展示色值，如 #FF6B6B；不传走系统默认色 #5B8FF9 | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 关联订单 ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "tagName": "标签名", + "tagColor": "前端展示色值，如 #FF6B6B；不传走" +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 96. 分页查询退款申诉 `GET /v3/admin/refund/appeal/page` + +**VO**: `AppealAdminRespVO` + +#### 使用场景 + +分页查询退款申诉。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| page | Query | Integer | — | — | 页码（从1开始） | +| pageSize | Query | Integer | — | — | 每页条数 | +| orderId | Query | Long | — | — | 订单ID精确匹配 | +| appealType | Query | String | — | — | 申诉类型（REFUND_REJECTED/REFUND_AMOUNT_DISPUTE） | +| appealStatus | Query | String | — | — | 申诉状态（PENDING/REJECTED/REFUNDED/WITHDRAWN） | +| applicantName | Query | String | — | — | 申请人姓名（模糊匹配） | +| createTimeStart | Query | LocalDateTime | — | — | 创建时间起 | +| createTimeEnd | Query | LocalDateTime | — | — | 创建时间止 | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.records[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/refund/appeal/page?page=1&pageSize=1&orderId=1934567890123456701&appealType=REFUND_REJECTED&appealStatus=PENDING&applicantName=申请人姓名 +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "records": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "records": [] + } +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 97. 查询申诉详情（管理端） `GET /v3/admin/refund/appeal/{id}` + +**VO**: `AppealAdminRespVO` + +#### 使用场景 + +查询申诉详情（管理端）。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| id | Path | Long | ✅ | 正整数 | id | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 订单ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/refund/appeal/1934567890123456701 +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 98. 客服代下退款申请 `POST /v3/admin/refund/application` + +**VO**: `RefundApplicationDetailRespVO` + +#### 使用场景 + +客服代下退款申请。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Body | Long | — | — | 订单ID | +| refundType | Body | String | — | — | 退款类型：FULL/PARTIAL（默认 FULL） | +| reasonId | Body | Long | — | — | 退款原因ID | +| reasonText | Body | String | — | — | 退款原因文本（当选择了原因ID时自动填充） | +| reasonDetail | Body | String | — | — | 退款原因详情/备注 | +| policyId | Body | Long | — | — | 退款政策ID（NULL=不按政策） | +| departureDate | Body | LocalDate | — | — | 出发日期（按政策计算时必填） | +| paidAmount | Body | BigDecimal | — | — | 已付金额（快照） | +| requestedAmount | Body | BigDecimal | — | — | 申请退款金额（PARTIAL 必填） | +| mediaTraceIds | Body | java.util.List | — | — | 媒体 traceIds（wx 内容安全机审用） | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.records[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| refundId | Long | 退款记录ID（同层级对照） | +| data.records | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "orderId": "1234567890123456789", + "refundType": "FULL", + "reasonId": "1934567890123456701", + "reasonText": "退款原因文本", + "reasonDetail": "退款原因详情/备注", + "policyId": "1934567890123456701", + "departureDate": "2026-07-01", + "paidAmount": "1000.00", + "requestedAmount": "500.00", + "mediaTraceIds": null +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "records": [ + { + "refundId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 99. 手动完成退款 `PUT /v3/admin/refund/application/{applicationId}/complete` + +**VO**: `RefundApplicationDetailRespVO` + +#### 使用场景 + +手动完成退款。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| applicationId | Path | Long | ✅ | 正整数 | applicationId | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.records[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| refundId | Long | 退款记录ID（同层级对照） | +| data.records | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +PUT /v3/admin/refund/application/1934567890123456701/complete +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "records": [ + { + "refundId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 100. 退款申请详情 `GET /v3/admin/refund/application/{id}` + +**VO**: `RefundApplicationDetailRespVO` + +#### 使用场景 + +退款申请详情。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| id | Path | Long | ✅ | 正整数 | id | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.records[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| refundId | Long | 退款记录ID（同层级对照） | +| data.records | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/refund/application/1934567890123456701 +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "records": [ + { + "refundId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 101. 触发实退 `POST /v3/admin/refund/execute/{appId}` + +**VO**: `RefundApplicationDetailRespVO` + +#### 使用场景 + +触发实退。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| appId | Path | Long | ✅ | 正整数 | appId | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.records[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| refundId | Long | 退款记录ID（同层级对照） | +| data.records | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +POST /v3/admin/refund/execute/1934567890123456701 +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "records": [ + { + "refundId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 102. 提交审核 `POST /v3/admin/refund/review` + +**VO**: `RefundApplicationDetailRespVO` + +#### 使用场景 + +提交审核。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| applicationId | Body | Long | — | — | 退款申请ID | +| decision | Body | String | — | — | 决议：APPROVED/REJECTED/PARTIAL | +| approvedAmount | Body | BigDecimal | — | — | 同意退款金额（PARTIAL 决议时必填，APPROVED 时选填） | +| remark | Body | String | — | — | 审核备注/驳回原因（REJECTED 时必填） | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.records[].teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| refundId | Long | 退款记录ID（同层级对照） | +| data.records | List | 容器字段，结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "applicationId": "1234567890123456789", + "decision": "APPROVED", + "approvedAmount": "800.00", + "remark": "审核备注/驳回原因" +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "records": [ + { + "refundId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 103. 取消团队 `POST /v3/admin/team-report/cancel` + +**VO**: `TeamReportRespVO` + +#### 使用场景 + +取消团队。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Body | Long | — | — | 订单ID | +| cancelType | Body | Integer | — | — | 取消类别 0=游客个人原因 1=旅行社原因 2=不可抗因素 3=其他 | +| cancelDesc | Body | String | — | — | 取消原因说明 | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 关联订单ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```json +{ + "orderId": "1934567890123456701", + "cancelType": 1, + "cancelDesc": "取消原因说明" +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +查询失败静默降为 `null`，不影响其余字段、不回滚已提交的写操作；未付款/未生成团号同样为 `null`。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": null + } +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 +- 本端点团号查询走静默降级：查失败不影响其余字段返回、不回滚已提交的写操作。 + +--- + +### 104. 暂存表单 `POST /v3/admin/team-report/save` + +**VO**: `TeamReportRespVO` + +#### 使用场景 + +暂存表单。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Body | Long | — | — | 订单ID | +| agencyCode | Body | String | — | — | 旅行社编码 hulai/qianshou/hulai-wenlu | +| businessType | Body | Integer | — | — | 业务类型 2=国内游组团 6=入境接待 7=国内接待 | +| agencyName | Body | String | — | — | 旅行社名称 | +| agencyLicense | Body | String | — | — | 经营许可证号 | +| itineraryName | Body | String | — | — | 线路名称 | +| teamId | Body | String | — | — | 团号 | +| dateGo | Body | String | — | — | 出发日期 yyyy-MM-dd | +| timeGoHour | Body | String | — | — | 出发时间 HH | +| timeGoMinute | Body | String | — | — | 出发时间 mm | +| dateBack | Body | String | — | — | 返回日期 yyyy-MM-dd | +| timeBackHour | Body | String | — | — | 返回时间 HH | +| timeBackMinute | Body | String | — | — | 返回时间 mm | +| sourceCity | Body | String | — | — | 出发城市 | +| sourceProvince | Body | String | — | — | 出发省份 | +| destinationCity | Body | String | — | — | 前往城市 | +| destinationProvince | Body | String | — | — | 前往省份 | +| itineraryDay | Body | Integer | — | — | 天数 | +| vehicle | Body | Integer | — | — | 出发交通 1=飞机 2=火车 3=轮船 4=汽车 5=其它 | +| vehicleIn | Body | Integer | — | — | 返回交通 1=飞机 2=火车 3=轮船 4=汽车 5=其它 | +| vehicleOutNums | Body | String | — | — | 出发班次/车次 | +| vehicleInNums | Body | String | — | — | 返回班次/车次 | +| nativeTravelAgency | Body | String | — | — | 地接社名称 | +| teamType | Body | Integer | — | — | 团队类型 1=自组自接 2=包机 3=专列 4=其他 | +| peopleNums | Body | Integer | — | — | 团队人数 | +| childNums | Body | Integer | — | — | 儿童人数 | +| journeyDesc | Body | String | — | — | 行程总描述 | +| applicantName | Body | String | — | — | 申请人姓名 | +| applicantPhone | Body | String | — | — | 申请人电话 | +| guides | Body | List | — | — | 导游列表 | +| busInfo | Body | List | — | — | 车队列表 | +| itineraryList | Body | List | — | — | 行程列表（按天按站点） | +| touristList | Body | List | — | — | 游客列表 | +| agencyOptions | Body | List | — | — | agencyOptions | +| businessTypeOptions | Body | List | — | — | businessTypeOptions | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 关联订单ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +此处仅示例前 10 个字段，完整字段见入参表。 + +```json +{ + "orderId": "1934567890123456701", + "agencyCode": "旅行社编码 hulai/qianshou", + "businessType": 1, + "agencyName": "旅行社名称", + "agencyLicense": "经营许可证号", + "itineraryName": "线路名称", + "teamId": "团号", + "dateGo": "出发日期 yyyy-MM-dd", + "timeGoHour": "出发时间 HH", + "timeGoMinute": "出发时间 mm" +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +查询失败静默降为 `null`，不影响其余字段、不回滚已提交的写操作；未付款/未生成团号同样为 `null`。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": null + } +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 +- 本端点团号查询走静默降级：查失败不影响其余字段返回、不回滚已提交的写操作。 + +--- + +### 105. 查询审核状态 `GET /v3/admin/team-report/status/{orderId}` + +**VO**: `TeamReportRespVO` + +#### 使用场景 + +查询审核状态。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Path | Long | ✅ | 正整数 | orderId | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 关联订单ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/team-report/status/1934567890123456701 +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +查询失败静默降为 `null`，不影响其余字段、不回滚已提交的写操作；未付款/未生成团号同样为 `null`。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": null + } +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 +- 本端点团号查询走静默降级：查失败不影响其余字段返回、不回滚已提交的写操作。 + +--- + +### 106. 提交到12301平台 `POST /v3/admin/team-report/submit` + +**VO**: `TeamReportRespVO` + +#### 使用场景 + +提交到12301平台。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Body | Long | — | — | 订单ID | +| agencyCode | Body | String | — | — | 旅行社编码 hulai/qianshou/hulai-wenlu | +| businessType | Body | Integer | — | — | 业务类型 2=国内游组团 6=入境接待 7=国内接待 | +| agencyName | Body | String | — | — | 旅行社名称 | +| agencyLicense | Body | String | — | — | 经营许可证号 | +| itineraryName | Body | String | — | — | 线路名称 | +| teamId | Body | String | — | — | 团号 | +| dateGo | Body | String | — | — | 出发日期 yyyy-MM-dd | +| timeGoHour | Body | String | — | — | 出发时间 HH | +| timeGoMinute | Body | String | — | — | 出发时间 mm | +| dateBack | Body | String | — | — | 返回日期 yyyy-MM-dd | +| timeBackHour | Body | String | — | — | 返回时间 HH | +| timeBackMinute | Body | String | — | — | 返回时间 mm | +| sourceCity | Body | String | — | — | 出发城市 | +| sourceProvince | Body | String | — | — | 出发省份 | +| destinationCity | Body | String | — | — | 前往城市 | +| destinationProvince | Body | String | — | — | 前往省份 | +| itineraryDay | Body | Integer | — | — | 天数 | +| vehicle | Body | Integer | — | — | 出发交通 1=飞机 2=火车 3=轮船 4=汽车 5=其它 | +| vehicleIn | Body | Integer | — | — | 返回交通 1=飞机 2=火车 3=轮船 4=汽车 5=其它 | +| vehicleOutNums | Body | String | — | — | 出发班次/车次 | +| vehicleInNums | Body | String | — | — | 返回班次/车次 | +| nativeTravelAgency | Body | String | — | — | 地接社名称 | +| teamType | Body | Integer | — | — | 团队类型 1=自组自接 2=包机 3=专列 4=其他 | +| peopleNums | Body | Integer | — | — | 团队人数 | +| childNums | Body | Integer | — | — | 儿童人数 | +| journeyDesc | Body | String | — | — | 行程总描述 | +| applicantName | Body | String | — | — | 申请人姓名 | +| applicantPhone | Body | String | — | — | 申请人电话 | +| guides | Body | List | — | — | 导游列表 | +| busInfo | Body | List | — | — | 车队列表 | +| itineraryList | Body | List | — | — | 行程列表（按天按站点） | +| touristList | Body | List | — | — | 游客列表 | +| agencyOptions | Body | List | — | — | agencyOptions | +| businessTypeOptions | Body | List | — | — | businessTypeOptions | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 关联订单ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +此处仅示例前 10 个字段，完整字段见入参表。 + +```json +{ + "orderId": "1934567890123456701", + "agencyCode": "旅行社编码 hulai/qianshou", + "businessType": 1, + "agencyName": "旅行社名称", + "agencyLicense": "经营许可证号", + "itineraryName": "线路名称", + "teamId": "团号", + "dateGo": "出发日期 yyyy-MM-dd", + "timeGoHour": "出发时间 HH", + "timeGoMinute": "出发时间 mm" +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +查询失败静默降为 `null`，不影响其余字段、不回滚已提交的写操作；未付款/未生成团号同样为 `null`。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": null + } +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 +- 本端点团号查询走静默降级：查失败不影响其余字段返回、不回滚已提交的写操作。 + +--- + +### 107. 获取上报记录 `GET /v3/admin/team-report/{orderId}` + +**VO**: `TeamReportRespVO` + +#### 使用场景 + +获取上报记录。响应新增只读字段 `teamNo`（团号），前端可直接展示，无需再查。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Path | Long | ✅ | 正整数 | orderId | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.teamNo | String | **新增**：团号（为 `null` 见「降级响应」） | +| orderId | Long | 关联订单ID（同层级对照） | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /v3/admin/team-report/1934567890123456701 +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } +} +``` + +#### 空数据 / 降级响应 + +未付款/未生成团号时为 `null`；严格查询，失败直接报错（不吞掉），不影响其余字段返回。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": null +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- `teamNo` 格式 `yy-NNNN`（如 `26-0480`），订单确认生成团号后写入一次，之后不再变更。 +- `teamNo` 为只读字段，本次改动不新增入参、不改变校验/错误码/鉴权规则。 + +--- + +### 108. 工作台仪表盘（角色分发，支持时间范围） `GET /admin/profile/dashboard` + +**VO**: `DashboardRoleRespVO` + +#### 使用场景 + +根据当前管理员角色返回不同的仪表盘数据（SUPER_ADMIN/ADMIN/未知角色走全局概览，CUSTOMIZER 走定制师工作台）。本次改动：仪表盘中的「即将出行」列表新增 `teamNo`（团号）只读字段，来源于 order-v3。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| period | Query | String | — | 默认 `today` | 时间范围：today/week/month | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.upcomingTrips[].teamNo | String | **新增**：团号（格式 `yy-NNNN`，未生成团号时为 `null`） | +| data.upcomingTrips[].orderId | Long | 订单 ID（对照，供前端按同层级关联 teamNo 与订单） | +| data.upcomingTrips | List\ | teamNo 所在的容器字段，内部结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /admin/profile/dashboard?period=today +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "upcomingTrips": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +订单未付款、尚未生成团号时 `teamNo` 为 `null`；user-service 本次零改动，该字段透传自 order-v3 内部接口 `GET /internal/order/dashboard/upcoming-trips`，其降级语义见该接口所在的 changelog。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "upcomingTrips": [ + { + "orderId": "1934567890123456701", + "teamNo": null + } + ] + } +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- 只有 SUPER_ADMIN、ADMIN、default 分支（走 `AdminDashboardService`）以及 CUSTOMIZER（走 `DesignerDashboardService`）的响应会带 `upcomingTrips`；ROOM_MANAGER、VEHICLE_MANAGER、FINANCE、MATERIAL_ADMIN 走的是其他数据源，响应体中不含该字段。 +- `data.upcomingTrips[].teamNo` 字段早已存在于契约中，本次只是开始有值（改前恒为 `null`）。 +- user-service 本身零改动，该值随 order-v3 单独滚动部署即生效。 + +--- + +### 109. 工作台概览（已废弃，请使用 /admin/profile/dashboard） `GET /admin/designer/dashboard` + +**VO**: `DesignerDashboardVO` + +#### 使用场景 + +已废弃接口，行为固定按 CUSTOMIZER 角色、period=today 返回。本次改动：仪表盘中的「即将出行」列表新增 `teamNo`（团号）只读字段，来源于 order-v3。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| （无） | — | — | — | — | 本接口无入参，角色/时间范围固定 | + +#### 出参 + +| 字段 | 类型 | 说明 | +|------|------|------| +| data.upcomingTrips[].teamNo | String | **新增**：团号（格式 `yy-NNNN`，未生成团号时为 `null`） | +| data.upcomingTrips[].orderId | Long | 订单 ID（对照，供前端按同层级关联 teamNo 与订单） | +| data.upcomingTrips | List\ | teamNo 所在的容器字段，内部结构不变，新增元素见上方 teamNo 行 | + +其余字段不变，见原接口文档。 + +#### 请求示例 + +```http +GET /admin/designer/dashboard +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "upcomingTrips": [ + { + "orderId": "1934567890123456701", + "teamNo": "26-0480" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +订单未付款、尚未生成团号时 `teamNo` 为 `null`；user-service 本身零改动，该字段透传自 order-v3。 + +```json +{ + "code": 200, + "message": "成功", + "success": true, + "data": { + "upcomingTrips": [ + { + "orderId": "1934567890123456701", + "teamNo": null + } + ] + } +} +``` + +#### 错误响应 + +```json +{ + "code": 500, + "message": "系统繁忙，请稍后重试或联系客服", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- 本端点已废弃（`@Deprecated`），建议统一改用 `GET /admin/profile/dashboard`；两者行为一致，本字段无差异。 +- `data.upcomingTrips[].teamNo` 字段早已存在于契约中，本次只是开始有值（改前恒为 `null`）。 + +--- + +## 四、契约约束与正确调用方式 + +> 本节只写**后端接受/拒绝 payload 的规则**,不写 UI 渲染建议。 + +- 本次改动**不引入任何新的入参字段**,所有请求体/路径/查询参数与改动前完全一致;调用方无需修改任何现有请求代码即可获得新字段。 +- `teamNo` 是**只读**字段,后端忽略请求体中任何同名字段(本次也未在任何请求 VO 上新增该字段,前端传了也不会被读取)。 +- `teamNo` 不参与任何现有排序/过滤逻辑;本次改动的 109 个接口没有新增按团号筛选的能力。 + +### ✅ 正确 / ❌ 错误 payload 对照 + +| 场景 | payload | +|------|---------| +| ✅ 请求体/参数保持改动前原样 | 与改动前完全一致 | +| ❌ 假设可通过请求体传入/覆盖 `teamNo` | 后端不读取,该字段始终由后端按订单团号计算得出 | + +### 切换状态时的必要动作 + +无需任何前端联动动作;`teamNo` 是纯展示字段,不驱动任何状态切换逻辑。 + +--- + + +## 五、数据库行为 + +本次改动**不新增、不修改任何数据库表结构**,`team_no` 列本身已存在于订单主表。109 个接口中的写操作(新增/驳回/确认/审核/结算等)本次改动**只在响应体组装阶段取团号**:手里已有订单的直接读,否则按订单 ID 批量查一次。不改变原有写入 SQL、不改变事务边界、不改变任何已有列的写入值。user-service 的 2 个出口零改动,字段随 order-v3 一起滚动即生效。 + +--- + + +## 六、边界行为 + +- 未登录 → 401(网关拦截),与改动前一致。 +- 资源不存在 → 与改动前相同的业务错误码。 +- 订单未付款、尚未生成团号 → `teamNo` 为 `null`,不 500、不阻断页面渲染。 +- 团号为空白 → `teamNo` 为 `null`,不返回空串,也不用订单号顶替。 +- 老数据兼容:历史订单没有团号 → `teamNo` 为 `null`,不异常。 +- 20 个写后出口(见各自「空数据 / 降级响应」标注)团号查询失败静默降级为 `null`,不回滚已提交的写操作;其余需要单独查团号的接口走严格查询,查询本身失败会如实报错,不会静默返回 `null`。 + +--- + + +## 六.6、修改前后对比 + +### 字段级对比 + +| 字段 | 改前 | 改后 | +|------|------|------| +| `teamNo` | 不存在(user-service 2 个出口除外——那里字段早已声明,此前 order-v3 未填值) | 新增/开始有值,`String`,团号(格式 `yy-NNNN`),订单未生成团号时为 `null` | + +### 行为级对比 + +| 行为 | 改前 | 改后 | +|------|------|------| +| 管理后台查看订单/房务/保险/团期相关详情或列表、工作台「即将出行」 | 无法直接拿到团号(或字段恒为 `null`) | 响应体直接携带有效 `teamNo`,无需额外查询 | + +--- + + +## 六.7、影响评估 + +- **是否破坏向后兼容**: 否——纯新增/纯赋值字段,不删除/不重命名/不改变既有字段类型。 +- **前端是否必须同步上线**: 否——`teamNo` 是可选消费字段,不消费不影响现有页面功能;如需在页面展示团号才需要前端改动。 +- **前端 workaround 清理点**: 若有页面此前按订单 ID 另查团号,可改为直接读响应里的 `teamNo`。 + +--- + + +## 七、不影响范围 + +- **仅影响**: 管理后台(admin)上述 109 个接口的响应体,新增/补值只读字段 `teamNo`。 +- **零影响**: + - 所有接口的入参、校验规则、错误码、鉴权规则 + - C 端(mp)、内部(internal)接口(不在本文范围) + - 数据库表结构、既有列的写入逻辑 + - 历史数据(存量订单无团号时字段为 `null`,不触发迁移/补数) + - user-service 自身代码(2 个出口零改动,字段透传自 order-v3) + +--- + + +## 八、测试环境已验证 + +- 部署：order-v3 以合并提交 `97b9754f2` 部署测试环境。 +- 网关实测(2026-09-27),以下读数均与数据库 `order_main.team_no` 逐条比对: + - 团期户列表:50/50 一致。 + - 首页看板:5/5 一致。 + - 房务详情:2/2 一致。 + - 管理端新建订单时 `team_no` 为 NULL;登记首笔线下收款后,响应 `teamNo` 为本次生成的团号,与库一致;收款列表中同一行也一致。 +- 覆盖边界:其余接口由单测和响应字段门禁 `TeamNoResponseFieldGateTest` 覆盖,未逐个走网关。 + +--- + + +## 十、相关文档 + +- 关联 Issue: [wx/HL#8408](https://git.1814.love:8443/wx/HL/issues/8408) +- 关联 PR: [wx/HL#8439](https://git.1814.love:8443/wx/HL/pulls/8439)、[wx/HL#8447](https://git.1814.love:8443/wx/HL/pulls/8447) +- 关联 changelog(PR #8419,fleet 侧同工单): `changelogs-v2/2026-09/27_8408_车务响应补团号-修改接口-管理后台.md` + +## 关联 / 联系人 + +### 链接 + +- **Issue**: [#8408](https://git.1814.love:8443/wx/HL/issues/8408) +- **PR**: [#8439](https://git.1814.love:8443/wx/HL/pulls/8439)、[#8447](https://git.1814.love:8443/wx/HL/pulls/8447) +- **Merge commit**: [69046568c](https://git.1814.love:8443/wx/HL/commit/69046568c)、[97b9754f2](https://git.1814.love:8443/wx/HL/commit/97b9754f2) + +### 联系人 + +- **后端负责人**: @wx