diff --git a/changelogs-v2/2026-06/30_4644_打印行程单接口-新增接口-管理后台.md b/changelogs-v2/2026-06/30_4644_打印行程单接口-新增接口-管理后台.md new file mode 100644 index 0000000..3bb848d --- /dev/null +++ b/changelogs-v2/2026-06/30_4644_打印行程单接口-新增接口-管理后台.md @@ -0,0 +1,630 @@ +# 打印行程单接口（出团行程单·Driver Copy） + +**接口路径**：`GET /v3/admin/order/{id}/print-itinerary` +**服务**：hl-order-service-v3 +**PR**：[#4650](https://git.1814.love:8443/wx/HL/pulls/4650) ｜ **Issue**：[#4644](https://git.1814.love:8443/wx/HL/issues/4644) ｜ **合并至**：dev-v3 +**变更类型**：✨ 新增接口 + +--- + +## 1. 接口背景 + +出团前，管理后台定制师（或运营人员）需打印一份完整的出团行程单（俗称"Driver Copy"）交给司机/导游/领队，供出行全程参考。本次在订单详情页新增该打印端点，后端聚合 **11 个功能区块**（大交通、客人信息、费用明细、全程住宿、应急联系人、每日行程、注意事项、退费规则、交接确认、代收款回执、备注）一次性返回，前端按 A4 纵向布局渲染并提供打印/PDF 下载入口。 + +同源先例：`GET /v3/admin/order/{id}/sign-voucher`（签单 PDF）。 + +--- + +## 2. 变更清单 + +| 类型 | 接口 | 说明 | +|------|------|------| +| ✨ 新增 | `GET /v3/admin/order/{id}/print-itinerary` | 打印行程单 11 区块全量聚合接口 | + +--- + +## 3. 接口详情 + +| 项 | 说明 | +|----|------| +| **方法 + 路径** | `GET /v3/admin/order/{id}/print-itinerary` | +| **接口名** | 打印行程单（出团行程单·Driver Copy） | +| **功能描述** | 聚合订单 11 个打印区块，供前端渲染 A4 行程单并打印 / 导出 PDF | +| **认证** | 需携带管理后台 JWT（`Authorization: Bearer `） | +| **权限** | 已登录的管理后台用户，无额外角色限制 | +| **幂等性** | 只读查询，天然幂等 | +| **限流** | 无特殊限流（走网关通用限流） | +| **响应格式** | `application/json; charset=utf-8` | +| **包装类型** | `Result` | + +--- + +## 4. 接口入参 + +### 4.1 路径参数 + +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| `id` | Long（JSON 序列化为 String，防 JS 精度丢失） | 是 | 订单 ID（雪花 ID，前端应作为字符串透传，不要转 number） | + +### 4.2 请求体 + +本接口无请求体（GET 请求）。 + +--- + +## 5. 出参字段 + +响应结构：`Result`，`code=200` 时 `data` 为完整行程单对象。 + +### 5.1 根字段（header 区块 + 顶层区块引用） + +| 字段名 | 类型 | 说明 | +|--------|------|------| +| `agencyName` | String | 本社名称，如「呼籁旅行有限公司」 | +| `printTime` | String | 打印时间，ISO-8601 格式，如 `2026-06-29T10:30:00` | +| `teamNo` | String | 团号，如 `HLA2026060001` | +| `productName` | String | 产品名 | +| `dateRange` | String | 出行日期范围，格式 `YYYY-MM-DD→YYYY-MM-DD` | +| `paxSummary` | String | 人数摘要，如 `2大1小` | +| `driverName` | String | 司机姓名；未配置则为空串 | +| `driverPhone` | String | 司机电话（内部明文，仅内网打印场景）；未配置则为空串 | +| `guideName` | String | 导游姓名；未配置则为空串 | +| `guidePhone` | String | 导游电话；未配置则为空串 | +| `leaderName` | String | 领队姓名；未配置则为空串 | +| `leaderPhone` | String | 领队电话；未配置则为空串 | +| `consultantName` | String | 定制师 / 经办人姓名 | +| `transports` | `TransportVO[]` | 01 区块：大交通批次列表，按方向升序（ARRIVAL 在前） | +| `customerOverview` | `CustomerOverviewVO` | 02 区块：客人信息速览 | +| `feeDetail` | `FeeDetailVO` 或 `null` | 03 区块：费用明细；product-v2 Feign 失败时为 `null`，前端应降级展示「暂无」 | +| `hotels` | `HotelVO[]` | 04 区块：全程住宿逐晚列表 | +| `emergencyContacts` | `EmergencyContactVO[]` | 05 区块：应急兜底联系人（配房房务 claimer） | +| `days` | `DayVO[]` | 06 区块：每日行程（来自固化行程表） | +| `notices` | `NoticesVO` | 07 区块：注意事项（固定文案，见 §8 示例） | +| `refundNotes` | `RefundNoteGroup[]` | 08 区块：退费规则（来自产品快照）；无退费说明时为空数组 | +| `handoverChecklist` | `String[]` | 09 区块：师傅领队交接确认 checklist（固定条目，前端在每项右侧留签字栏） | +| `collectReceipt` | `CollectReceiptVO` | 10 区块：代收款签收回执 | +| `remark` | String 或 `null` | 11 区块：备注（来自订单内部备注字段 `consultantRemark`） | + +--- + +### 5.2 TransportVO（01 大交通批次） + +| 字段名 | 类型 | 说明 | +|--------|------|------| +| `direction` | String | 方向枚举值：`ARRIVAL`（到达）/ `DEPARTURE`（出发） | +| `transportType` | String | 交通方式枚举值：`FLIGHT`（航班）/ `TRAIN`（火车）/ `SELF_DRIVE`（自驾） | +| `transportNo` | String | 航班号 / 车次号；`SELF_DRIVE` 时为空串 | +| `carrier` | String | 航司 / 铁路公司名称 | +| `departStation` | String | 出发站 / 机场全称 | +| `arriveStation` | String | 到达站 / 机场全称 | +| `departTime` | String（LocalDateTime） | 出发时间，格式 `YYYY-MM-DDTHH:mm:ss` | +| `arriveTime` | String（LocalDateTime） | 到达时间，格式 `YYYY-MM-DDTHH:mm:ss` | +| `selfDrivePeriod` | String 或 `null` | 自驾时段，仅 `SELF_DRIVE` 时有值：`MORNING` / `AFTERNOON` / `EVENING` | +| `selfDriveEta` | String（LocalDateTime）或 `null` | 自驾预计到达时间，仅 `SELF_DRIVE` 时有值 | +| `pickupRequired` | Boolean | 是否需要平台接送 | +| `pickupRemark` | String 或 `null` | 接送备注 | +| `remark` | String 或 `null` | 本段交通备注 | + +--- + +### 5.3 CustomerOverviewVO（02 客人信息速览） + +| 字段名 | 类型 | 说明 | +|--------|------|------| +| `customerName` | String | 主联系人姓名 | +| `customerPhone` | String | 主联系人手机（已脱敏，格式 `138****5678`） | +| `adultCount` | Integer | 成人数 | +| `childCount` | Integer | 儿童数（6–12 岁） | +| `youngChildCount` | Integer | 幼童数（2–6 岁） | +| `babyCount` | Integer | 婴儿数（0–2 岁） | +| `tripDays` | Integer | 行程天数 | +| `customerType` | String 或 `null` | 客人类型（运营字段，当前后端恒为 `null`，前端按空值处理） | +| `createSource` | String | 客源枚举值（见 §6 枚举表） | +| `customerRemark` | String 或 `null` | 客户备注（特殊需求 / 忌口 / 纪念日等） | + +--- + +### 5.4 FeeDetailVO（03 费用明细） + +**整体可为 `null`**（product-v2 Feign 失败时降级），前端应展示「暂无」而不报错。 + +| 字段名 | 类型 | 说明 | +|--------|------|------| +| `items` | `FeeLineItemVO[]` | 费用行项列表（仅含数量 > 0 的人群类型） | +| `singleRoomSurcharge` | String（BigDecimal）或 `null` | 单房差加价；无单间需求时为 `null` | +| `grandTotal` | String（BigDecimal） | 合计金额 | +| `onsiteBalance` | String（BigDecimal）或 `null` | 代收款（现场实收尾款）；未录入时为 `null` | + +**FeeLineItemVO（费用行项）**： + +| 字段名 | 类型 | 说明 | +|--------|------|------| +| `name` | String | 行项名称，如 `成人包价` / `儿童包价` / `幼童包价` / `婴儿包价` | +| `unitPrice` | String（BigDecimal） | 单价 | +| `qty` | Integer | 数量 | +| `subtotal` | String（BigDecimal） | 小计（= 单价 × 数量） | + +> 注意：BigDecimal 字段均序列化为 **JSON String**（防 JS 精度丢失），前端渲染时直接使用，**不需要** `parseFloat()` 转换。 + +--- + +### 5.5 HotelVO（04 全程住宿，逐晚） + +| 字段名 | 类型 | 说明 | +|--------|------|------| +| `dayNumber` | Integer | 天序号（1-based，第一晚 = 1） | +| `stayDate` | String（LocalDate） | 入住日期，格式 `YYYY-MM-DD` | +| `hotelName` | String | 酒店名称 | +| `city` | String | 所在城市（通过 resource-service Feign 取；Feign 失败时为空串） | +| `roomCategory` | String | 房型（中文，查字典 `room_category`；未命中则回退 `其他房型`） | +| `roomCount` | Integer | 房间数 | +| `contactPerson` | String | 酒店联系人（Feign 取；失败时为空串） | +| `contactPhone` | String | 联系电话（Feign 取；失败时为空串） | +| `settleType` | String | 结算方式（中文，查字典 `settle_type`；失败时为空串） | +| `paymentMode` | String | 付款方式（中文，查字典 `payment_mode`；失败时为空串） | +| `checkInTime` | String 或 `null` | 入住时间，格式 `HH:mm` | +| `checkOutTime` | String 或 `null` | 退房时间，格式 `HH:mm` | + +--- + +### 5.6 EmergencyContactVO（05 应急兜底联系人） + +| 字段名 | 类型 | 说明 | +|--------|------|------| +| `contactName` | String | 姓名（来自配房 claimer_name 快照） | +| `contactPhone` | String | 电话（通过 user-service Feign 取 admin_user.mobile；失败或未维护时为空串） | +| `role` | String | 角色说明，固定为 `房务` | + +--- + +### 5.7 DayVO（06 每日行程） + +| 字段名 | 类型 | 说明 | +|--------|------|------| +| `dayNumber` | Integer | 天序号（1-based） | +| `dayDate` | String（LocalDate） | 实际日期，格式 `YYYY-MM-DD` | +| `dayTitle` | String | 当日标题 | +| `description` | String 或 `null` | 当日描述 | +| `breakfast` | String 或 `null` | 早餐安排枚举值（见 §6） | +| `lunch` | String 或 `null` | 午餐安排枚举值 | +| `dinner` | String 或 `null` | 晚餐安排枚举值 | +| `diningRemark` | String 或 `null` | 餐饮备注 | +| `gatherPlace` | String 或 `null` | 集合地点（POI JSON 字符串，前端按需解析展示名称） | +| `dismissalPlace` | String 或 `null` | 解散地点（POI JSON 字符串） | +| `dailyMileage` | String（BigDecimal）或 `null` | 当日里程（km） | +| `nodes` | `NodeVO[]` | 当日点位列表，按 sort_order 升序 | + +**NodeVO（06 子项：行程点位）**： + +| 字段名 | 类型 | 说明 | +|--------|------|------| +| `nodeName` | String | 点位名称（优先取 node 自定义名，回退资源名） | +| `nodeType` | String | 节点类型枚举值（见 §6） | +| `startTime` | String 或 `null` | 开始时间，格式 `HH:mm` | +| `timePeriod` | String 或 `null` | 时段（`上午` / `下午` / `全天`） | +| `supplierPhone` | String 或 `null` | 供应商电话；无则空串 | +| `remark` | String 或 `null` | 操作备注（作司机 / 导游话术） | + +--- + +### 5.8 NoticesVO（07 注意事项） + +| 字段名 | 类型 | 说明 | +|--------|------|------| +| `forbidden` | `String[]` | 严禁项目（固定文案，见 §8 典型示例） | +| `warning` | `String[]` | 警示项目（固定文案） | +| `standard` | `String[]` | 流程标准项目（固定文案） | + +> 三组均为后端硬编码固定文案，每次响应内容相同，前端直接渲染即可。 + +--- + +### 5.9 RefundNoteGroup（08 退费规则） + +`refundNotes` 为 `RefundNoteGroup[]`，每个元素对应一个行程节点的退费说明。 + +**RefundNoteGroup**： + +| 字段名 | 类型 | 说明 | +|--------|------|------| +| `sourceName` | String | 来源点位名称，如 `呼伦湖景区` | +| `intro` | String 或 `null` | 退费说明总体备注 | +| `items` | `RefundItem[]` | 退费明细列表 | + +**RefundItem**： + +| 字段名 | 类型 | 说明 | +|--------|------|------| +| `title` | String | 展示标题，如 `成人未参加` | +| `amount` | String（BigDecimal） | 退费金额（赠送项目为 `0`） | +| `unitLabel` | String | 展示单位文案，如 `/人` / `/团` / `/辆` | +| `settleScope` | String | 结算粒度枚举值（见 §6） | +| `settleScopeLabel` | String | 结算粒度中文，如 `按人` | +| `remark` | String 或 `null` | 备注 | +| `effectiveFrom` | String（LocalDate）或 `null` | 规则生效起日；`null` 表示无限制 | +| `effectiveTo` | String（LocalDate）或 `null` | 规则生效止日；`null` 表示无限制 | + +--- + +### 5.10 handoverChecklist（09 师傅领队交接确认） + +`String[]`，后端返回以下 5 条固定条目，前端在每项右侧留签字栏： + +1. `出行群已建立并拉入全部出行人` +2. `签单核对完毕（日期/人数/酒店/景点无误）` +3. `车辆及座位安排已确认` +4. `特殊需求已告知（忌口/纪念日/老幼残）` +5. `代收款金额已当面清点确认` + +--- + +### 5.11 CollectReceiptVO（10 代收款签收回执） + +| 字段名 | 类型 | 说明 | +|--------|------|------| +| `collectAmount` | String（BigDecimal）或 `null` | 代收金额（来自 `order_main.onsiteBalance`）；未录入时为 `null` | + +--- + +## 6. 枚举 / 数据字典 + +### 6.1 direction（大交通方向） + +| 枚举值 | 说明 | +|--------|------| +| `ARRIVAL` | 到达（进藏 / 进目的地） | +| `DEPARTURE` | 出发（离开目的地返程） | + +### 6.2 transportType（交通方式） + +| 枚举值 | 说明 | +|--------|------| +| `FLIGHT` | 航班 | +| `TRAIN` | 火车 | +| `SELF_DRIVE` | 自驾 | + +### 6.3 selfDrivePeriod（自驾时段，仅 SELF_DRIVE） + +| 枚举值 | 说明 | +|--------|------| +| `MORNING` | 上午 | +| `AFTERNOON` | 下午 | +| `EVENING` | 晚上 | + +### 6.4 createSource（客源渠道） + +| 枚举值 | 常见含义（展示名由字典 order_create_source 翻译） | +|--------|------------------------------------------------| +| `OTA` | 马蜂窝 / 携程等平台 | +| `CUSTOMER` | 老客户 / 回头客 | +| `B2B` | 同业 | +| `REFERRAL` | 转介绍 | +| `MINI_PROGRAM` | 小程序直询 | + +> 字典值以实际 order_create_source 字典表为准，可能随运营配置增减。 + +### 6.5 nodeType（行程点位类型） + +| 枚举值 | 说明 | +|--------|------| +| `SCENIC` | 景区 | +| `RESTAURANT` | 餐厅 | +| `ACTIVITY` | 活动 | +| `SERVICE` | 服务项 | +| `CUSTOM` | 自定义 | + +### 6.6 餐食安排（breakfast / lunch / dinner） + +| 枚举值 | 说明 | +|--------|------| +| `HOTEL` | 酒店早餐 / 含在住宿中 | +| `CAMP` | 营地餐 | +| `SPECIAL` | 特色餐（安排饭店） | +| `SELF` | 自理 | + +### 6.7 settleScope（退费结算粒度） + +| 枚举值 | 说明 | +|--------|------| +| `PER_PERSON` | 按人结算（`/人`） | +| `PER_TEAM` | 按团结算（`/团`） | +| `PER_VEHICLE` | 按车结算（`/辆`） | + +### 6.8 字典翻译字段 + +以下字段值来自数据字典，前端**不需要**自己翻译枚举，后端已翻译为中文： + +| 字段 | 字典表 key | 说明 | +|------|-----------|------| +| `hotels[].roomCategory` | `room_category` | 房型中文名；未命中回退「其他房型」 | +| `hotels[].settleType` | `settle_type` | 结算方式中文 | +| `hotels[].paymentMode` | `payment_mode` | 付款方式中文 | + +--- + +## 7. 错误码 + +| 错误码 | HTTP 状态 | message | 触发场景 | +|--------|-----------|---------|----------| +| `581007` | 200（Result 业务码） | 订单不存在 | 路径参数 `id` 对应订单不存在或已软删除 | +| `401` | 401 | Unauthorized | JWT 未携带 / 已过期 | +| `403` | 403 | Forbidden | 无访问权限 | + +> 其余 Feign 软依赖（product-v2 费用 / resource 城市 / user 应急电话）失败时**不报错**，对应字段降级为 `null` / 空串，不影响接口正常返回。 + +--- + +## 8. 示例 + +### 8.1 典型成功（完整 2 大 1 小 7 日游订单） + +**请求**： + +```http +GET /v3/admin/order/1914050000000001/print-itinerary +Authorization: Bearer eyJhbGci... +``` + +**响应**（节选关键区块，实际字段更多）： + +```json +{ + "code": 200, + "data": { + "agencyName": "呼籁旅行有限公司", + "printTime": "2026-06-30T09:15:00", + "teamNo": "HLA2026070001", + "productName": "呼伦贝尔7日私家定制游", + "dateRange": "2026-07-01→2026-07-07", + "paxSummary": "2大1小", + "driverName": "全广存", + "driverPhone": "18614805444", + "guideName": "", + "guidePhone": "", + "leaderName": "扎西", + "leaderPhone": "13812345678", + "consultantName": "张定制", + "transports": [ + { + "direction": "ARRIVAL", + "transportType": "FLIGHT", + "transportNo": "CA4167", + "carrier": "中国国航", + "departStation": "北京首都国际机场T3", + "arriveStation": "海拉尔东山机场", + "departTime": "2026-07-01T08:00:00", + "arriveTime": "2026-07-01T11:30:00", + "selfDrivePeriod": null, + "selfDriveEta": null, + "pickupRequired": true, + "pickupRemark": "到达T2出口等候", + "remark": null + } + ], + "customerOverview": { + "customerName": "张三", + "customerPhone": "138****5678", + "adultCount": 2, + "childCount": 1, + "youngChildCount": 0, + "babyCount": 0, + "tripDays": 7, + "customerType": null, + "createSource": "CUSTOMER", + "customerRemark": "小孩对海鲜过敏，全程忌口" + }, + "feeDetail": { + "items": [ + {"name": "成人包价", "unitPrice": "4500.00", "qty": 2, "subtotal": "9000.00"}, + {"name": "儿童包价", "unitPrice": "3000.00", "qty": 1, "subtotal": "3000.00"} + ], + "singleRoomSurcharge": null, + "grandTotal": "12000.00", + "onsiteBalance": "5000.00" + }, + "hotels": [{ + "dayNumber": 1, + "stayDate": "2026-07-01", + "hotelName": "伯爵大酒店", + "city": "海拉尔", + "roomCategory": "标准双床间", + "roomCount": 2, + "contactPerson": "张经理", + "contactPhone": "0470-12345678", + "settleType": "签单", + "paymentMode": "月结", + "checkInTime": "14:00", + "checkOutTime": "12:00" + }], + "emergencyContacts": [{"contactName": "李房务", "contactPhone": "13900000001", "role": "房务"}], + "days": [{ + "dayNumber": 1, + "dayDate": "2026-07-01", + "dayTitle": "抵达海拉尔·入住休整", + "description": "抵达海拉尔后接机，送至酒店休整", + "breakfast": null, + "lunch": "SELF", + "dinner": "SPECIAL", + "diningRemark": "晚餐安排烤全羊", + "gatherPlace": null, + "dismissalPlace": null, + "dailyMileage": "45.00", + "nodes": [{ + "nodeName": "海拉尔东山机场", + "nodeType": "SERVICE", + "startTime": "11:30", + "timePeriod": "上午", + "supplierPhone": "0470-88880001", + "remark": "接机后直接送酒店，行李搬运到房间" + }] + }], + "notices": { + "forbidden": ["严禁向客人推荐自费项目、带客进购物店；违者扣除本行程全部车费，且永不录用"], + "warning": ["送站时间不得早于出发时间前 2 小时", "景区半价票差价须由领队自行承担，不得转嫁客人", "行程如有任何变更须经书面确认后方可执行"], + "standard": ["出发前须核实全程住宿安排（联系酒店确认房态）", "在出行群内发出行提示及完整大交通信息", "妥善保管签单，行程结束后当日归还公司", "每次入住后须检查房间设施并拍照留存", "司机出发前主动向客人自我介绍并说明全程安排"] + }, + "refundNotes": [{ + "sourceName": "呼伦湖景区", + "intro": "苔藓步道为赠送项目，不退费", + "items": [{"title": "成人未参加", "amount": "44.00", "unitLabel": "/人", "settleScope": "PER_PERSON", "settleScopeLabel": "按人", "remark": null, "effectiveFrom": null, "effectiveTo": null}] + }], + "handoverChecklist": ["出行群已建立并拉入全部出行人", "签单核对完毕（日期/人数/酒店/景点无误）", "车辆及座位安排已确认", "特殊需求已告知（忌口/纪念日/老幼残）", "代收款金额已当面清点确认"], + "collectReceipt": {"collectAmount": "5000.00"}, + "remark": "客人全程需要轮椅通道，联系景区提前安排" + } +} +``` + +--- + +### 8.2 边界情况（人员未配置 + feeDetail 降级 + 无退费规则） + +模拟 product-v2 Feign 失败时 `feeDetail` 返回 `null`，司机/导游/领队均未配置，`refundNotes` 为空数组： + +```json +{ + "code": 200, + "data": { + "agencyName": "呼籁旅行有限公司", + "printTime": "2026-06-30T09:16:00", + "teamNo": "HLA2026070002", + "productName": "张家界3日游", + "dateRange": "2026-07-10→2026-07-12", + "paxSummary": "1大", + "driverName": "", + "driverPhone": "", + "guideName": "", + "guidePhone": "", + "leaderName": "", + "leaderPhone": "", + "consultantName": "李运营", + "transports": [], + "customerOverview": { + "customerName": "王五", + "customerPhone": "139****0000", + "adultCount": 1, + "childCount": 0, + "youngChildCount": 0, + "babyCount": 0, + "tripDays": 3, + "customerType": null, + "createSource": "OTA", + "customerRemark": null + }, + "feeDetail": null, + "hotels": [], + "emergencyContacts": [], + "days": [], + "notices": { + "forbidden": ["严禁向客人推荐自费项目、带客进购物店；违者扣除本行程全部车费，且永不录用"], + "warning": ["送站时间不得早于出发时间前 2 小时", "景区半价票差价须由领队自行承担，不得转嫁客人", "行程如有任何变更须经书面确认后方可执行"], + "standard": ["出发前须核实全程住宿安排（联系酒店确认房态）", "在出行群内发出行提示及完整大交通信息", "妥善保管签单，行程结束后当日归还公司", "每次入住后须检查房间设施并拍照留存", "司机出发前主动向客人自我介绍并说明全程安排"] + }, + "refundNotes": [], + "handoverChecklist": ["出行群已建立并拉入全部出行人", "签单核对完毕（日期/人数/酒店/景点无误）", "车辆及座位安排已确认", "特殊需求已告知（忌口/纪念日/老幼残）", "代收款金额已当面清点确认"], + "collectReceipt": {"collectAmount": null}, + "remark": null + } +} +``` + +> **前端处理建议**： +> - `feeDetail === null` 时，整个费用区块显示「暂无（系统获取失败）」 +> - 人员字段（`driverName` 等）为空串时，对应展示行可隐藏或显示「-」 +> - `collectReceipt.collectAmount === null` 时，代收款回执区块显示「代收款金额待确认」 + +--- + +### 8.3 业务失败（订单不存在） + +**请求**： + +```http +GET /v3/admin/order/9999999999999/print-itinerary +Authorization: Bearer eyJhbGci... +``` + +**响应**： + +```json +{ + "code": 581007, + "message": "订单不存在", + "data": null +} +``` + +--- + +## 9. 业务边界 + +### 适用场景 + +- 订单状态为任意状态均可查询（只读，不限状态） +- 出团前 1–3 天由定制师打印交出行人员 +- 支持 A4 纵向排版，前端按 A4 规格渲染后提供打印 / PDF 导出 + +### 不适用场景 + +- 本接口**不替代**签单 PDF（`GET /v3/admin/order/{id}/sign-voucher`） +- 本接口**不是**小程序端行程查看接口，只给管理后台打印用 + +### 特殊边界 + +| 情况 | 行为 | +|------|------| +| 订单行程未固化（`days` 为空） | 正常返回，`days` 为空数组 | +| product-v2 Feign 超时 / 熔断 | `feeDetail` 降级为 `null`，接口正常 200 返回 | +| resource-service Feign 失败 | `hotels[].city` / `contactPerson` / `contactPhone` 降级为空串 | +| user-service Feign 失败 | `emergencyContacts[].contactPhone` 降级为空串 | +| 费用快照与订单当前金额不一致 | 以产品快照（`feeDetail`）为准，非实时联动；若前端需要实时金额，读订单金额字段 | + +--- + +## 10. 修改前后对比 + +本次为**新增接口**，无历史版本，跳过此节。 + +--- + +## 11. 影响评估 / 回滚 + +本次为**新增接口**（纯加量），不影响任何已有接口。 + +- **前端是否需要同步上线**：是（仅新增打印入口，不强制） +- **回滚方案**：后端可随时下架接口，前端调用报 404 时隐藏打印按钮即可 +- **破坏兼容性**：无 + +--- + +## 12. 注意事项 + +1. **BigDecimal 均为 String**：`grandTotal` / `unitPrice` / `subtotal` / `singleRoomSurcharge` / `onsiteBalance` / `dailyMileage` / `collectAmount` / `amount` 均序列化为 JSON String，前端**直接展示**即可，不需要 `parseFloat` 转换。 + +2. **feeDetail 可为 null**：费用区块来自 product-v2 Feign，不保证一定有值，前端**必须**做 null 判断，展示兜底文案「暂无」。 + +3. **电话号码三级降级**： + - 司机/导游/领队电话：来自订单人员分配，未分配时为空串（不为 null） + - 酒店联系人/电话：来自 resource-service Feign，失败时为空串 + - 应急联系人电话：来自 user-service Feign 取 admin_user.mobile，失败时为空串 + - 三种情况均不报错，前端按空串处理即可（显示「-」或隐藏） + +4. **主联系人手机已脱敏**：`customerOverview.customerPhone` 格式为 `138****5678`，用于打印展示，安全无需二次处理。 + +5. **注意事项固定文案**：`notices` 三组内容为后端常量（`PrintItineraryConstants`），不走数据库，修改文案需后端发版。 + +6. **费用与实际金额可能不同步**：`feeDetail` 来自产品快照，当产品价格调整但订单快照未更新时，打印金额可能与最新报价不一致，属预期行为（以签单时快照为准）。 + +--- + +## 13. 关联 / 联系人 + +| 项 | 链接 / 信息 | +|----|------------| +| **Issue** | [#4644 打印行程单接口（出团行程单·Driver Copy）](https://git.1814.love:8443/wx/HL/issues/4644) | +| **PR** | [#4650 feat(order-v3): 打印行程单 11 区块聚合接口](https://git.1814.love:8443/wx/HL/pulls/4650) | +| **Merge Commit** | [8e2b02f56](https://git.1814.love:8443/wx/HL/commit/8e2b02f56) | +| **Feature Commit** | [187169daf](https://git.1814.love:8443/wx/HL/commit/187169daf) | +| **后端负责人** | yaosutu | +| **影响服务** | hl-order-service-v3（端口 8086） |