--- schema: "hl-changelog/v2" ticket: "8408" title: "订单管理后台响应体补团号字段" consumer: "admin" author: "wx(GIT)" change_type: "修改接口" backend_status: "deployed" gateway_status: "verified" frontend_status: "not_required" frontend_owner: "" frontend_ref: "" target_release: "" verified_at: "" status_note: "PR #8439（合并提交 69046568c）与 #8447（合并提交 97b9754f2）已合入 dev-v3，order-v3 已按 97b9754f2 部署测试环境。网关实测：团期户列表 50/50、首页看板 5/5、房务详情 2/2 的 teamNo 与库一致；管理端新建订单后登记首笔线下收款，响应 teamNo 为本次生成的团号，与库一致。其余接口由单测和响应字段门禁 TeamNoResponseFieldGateTest 覆盖，未逐个走网关。 前端实证(mmg 2026-09-28):纯增只读 teamNo,无「按订单ID另查团号」workaround(teamNo 已在退款/财务/车务/房务等直读响应字段),唯一具体消费(房务户级团号列)已由独立件 e3f8de23 交付;前端无需同步,判 not_required。" 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