docs(order-v3): 打印签单出参重制为自包含通知单+字段中文化 (#4549/#4566/#4584)

GET /v3/admin/order/{id}/sign-voucher 出参三轮变更合并一份:删 header 概要/FROM 下沉到 entry、新增司机/导游/经办人/付款方式、房型/结算/付款 code 转中文。前端必改:原读 header 改读 entries[]。

changelogs-v2/2026-06/29_4549_打印签单出参重制为自包含通知单与字段中文化-修改接口-管理后台.md

@@ -0,0 +1,249 @@
+# 打印签单出参重制（自包含通知单 + 字段全中文化）
+
+> 变更类型：**修改接口** ｜ 端类型：**管理后台** ｜ 接口：`GET /v3/admin/order/{id}/sign-voucher`
+> 合并自 3 个 PR：#4549（FROM 下沉 + 付款方式 + 经办人）、#4566（订单概要下沉 + 司机/导游）、#4584（房型/结算/付款方式中文化）
+> 原始接口见 #4505。本文给出**最终出参契约**，前端按此对接即可。
+
+---
+
+## ① 接口背景
+
+订单详情「打印签单」功能，后端组装「酒店预订通知单 + 景点门票预订通知单」（A4 横向传真单）数据。原型每张单独立打印，发给不同供应商。本次按验收反馈把出参重制为「每张通知单完全自包含」，并把所有字典 code 后端翻成中文。
+
+---
+
+## ② 变更清单
+
+1. **删除共享 `header`**：原 `data.header`（订单概要 + FROM 抬头）整体删除，所有字段下沉到每个 `entries[]`，每条自成一张可独立打印的 A4 单。
+2. **订单概要下沉**：`teamNo` / `productName` / `dateRange` / `paxSummary` 移到每个 entry。
+3. **FROM 抬头下沉 + 新增经办人**：`fromCompany` / `taxId` 移到每个 entry，新增 `operatorName`（经办人/发件人=订单定制师）。
+4. **新增司机/导游**：每个 entry 加 `driverName` / `driverPhone` / `guideName` / `guidePhone`（电话为内网明文，供应商可联系；无则空串）。
+5. **新增付款方式**：每个 entry 加 `settleType`（结算方式）/ `paymentMode`（付款方式）。
+6. **字段全中文化**：`items[].name`（房型）、`settleType`、`paymentMode` 由原本返字典 code 改为**后端翻好的中文**，前端不再接触机器码。
+
+---
+
+## ③ 接口详情
+
+| 项 | 值 |
+|---|---|
+| 方法 | GET |
+| 路径 | `/v3/admin/order/{id}/sign-voucher` |
+| 鉴权 | 管理后台登录态（Gateway JWT） |
+| 返回 | `Result<SignVoucherRespVO>` |
+
+---
+
+## ④ 入参
+
+| 参数 | 位置 | 类型 | 必填 | 说明 |
+|---|---|---|---|---|
+| `id` | path | Long | 是 | 订单 ID |
+| `showAmount` | query | Boolean | 否 | 是否展示金额，默认 `false`。`false`=脱敏（所有 unitPrice/amount/totalAmount 置 null，前端渲染 `***` 防成本价外泄给供应商）；`true`=展示金额 |
+
+> 入参无变化（与原始接口一致）。
+
+---
+
+## ⑤ 出参
+
+**顶层**（注意：**已无 `header`**，只有 `entries`）
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `entries` | array | 预订通知单列表（每条完全自包含一张 A4 单） |
+
+**`entries[]`（每张预订通知单）**
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `entryId` | string | 条目唯一 ID，酒店 `H{assignmentId}` / 景点 `S{assignmentId}`，前端勾选用 |
+| `type` | string | `HOTEL` / `SCENIC` |
+| `title` | string | "酒店预订通知单" / "景点门票预订通知单" |
+| `teamNo` | string | 团号（订单概要，下沉） |
+| `productName` | string | 产品名 |
+| `dateRange` | string | 出行日期范围 `depart→return`（任一为空返空串） |
+| `paxSummary` | string | 人数摘要，如 "2大1小"（成人=大，儿童+幼童=小） |
+| `driverName` | string | 司机姓名（无司机返空串 `""`） |
+| `driverPhone` | string | 司机电话（内网明文，无则空串） |
+| `guideName` | string | 导游姓名（无导游返空串） |
+| `guidePhone` | string | 导游电话（内网明文，无则空串） |
+| `fromCompany` | string | FROM 本社名（下沉，每条自带） |
+| `taxId` | string | 纳税人识别号（统一社会信用代码） |
+| `operatorName` | string | 经办人/发件人（订单定制师 consultant_name） |
+| `supplierName` | string | TO 供应商名（酒店名 / 景点名） |
+| `contactPerson` | string | 联系人/收件人（取不到返空串） |
+| `contactPhone` | string | 联系电话（取不到返空串） |
+| `fax` | string | 传真（本期恒 null） |
+| `settleType` | string | **结算方式中文**（酒店：现付/签单/公司付款；景点：恒空串） |
+| `paymentMode` | string | **付款方式中文**（酒店：预付款/现结/月结；景点：恒空串） |
+| `items` | array | 明细行 |
+| `totalAmount` | string(可空) | 合计金额（`showAmount=false` 时 null；BigDecimal 序列化为字符串防精度丢失） |
+
+**`entries[].items[]`（明细行）**
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `name` | string | **中文名**：酒店=房型中文（大床房/标间…，未知房型回退「其他房型」）；景点=固定"门票" |
+| `date` | string(date) | 日期，如 `2026-07-01` |
+| `qty` | int | 数量：酒店=房间数；景点=订单总人数（成人+儿童，婴幼儿不计） |
+| `unit` | string | "间夜" / "张" |
+| `unitPrice` | string(可空) | 单价（`showAmount=false` 时 null） |
+| `amount` | string(可空) | 金额（`showAmount=false` 时 null） |
+| `remark` | string | 备注（酒店取配房备注；景点恒 null） |
+
+> 金额字段（unitPrice/amount/totalAmount）均为 BigDecimal，经 ToStringSerializer 序列化为**字符串**。
+
+---
+
+## ⑥ 枚举 / 数据字典
+
+**`settleType`（结算方式，后端已翻中文，前端直接展示）**
+
+| 后端返回（中文） | 含义 |
+|---|---|
+| 现付 | 现场付款 |
+| 签单 | 签单挂账 |
+| 公司付款 | 公司统一付款 |
+
+**`paymentMode`（付款方式，后端已翻中文）**
+
+| 后端返回（中文） | 含义 |
+|---|---|
+| 预付款 | 预付 |
+| 现结 | 现场结算 |
+| 月结 | 按月结算 |
+
+**`items[].name`（房型，后端已翻中文）**：标间 / 单人间 / 双床房 / 大床房 / 豪华大床 / 套房 / 家庭房 / 蒙古包 / 特色房 / 亲子房 …；字典未命中回退「其他房型」。
+
+> ⚠️ 前端**不再收到** `sign` / `prepay` / `BIG_BED` 等机器码，settleType/paymentMode/房型一律为中文。景点的 settleType/paymentMode 本期恒空串（景点资源未建结算字段）。
+
+---
+
+## ⑦ 错误码
+
+| 场景 | code | 说明 |
+|---|---|---|
+| 订单不存在 | 581007 | ORDER_NOT_FOUND |
+| 未登录 | 401 | 网关鉴权 |
+
+> 无新增业务错误码。
+
+---
+
+## ⑧ 示例
+
+**典型（`showAmount=false`，1 酒店 + 1 景点）**
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "entries": [
+      {
+        "entryId": "H2070758427717525506",
+        "type": "HOTEL",
+        "title": "酒店预订通知单",
+        "teamNo": "26-1590",
+        "productName": "呼伦贝尔7日游",
+        "dateRange": "2026-07-01→2026-07-07",
+        "paxSummary": "2大1小",
+        "driverName": "全广存",
+        "driverPhone": "18614805444",
+        "guideName": "",
+        "guidePhone": "",
+        "fromCompany": "内蒙古呼籁国际旅行社有限公司",
+        "taxId": "91150702MACYFE851R",
+        "operatorName": "张定制",
+        "supplierName": "呼伦贝尔香格里拉大酒店",
+        "contactPerson": "王经理",
+        "contactPhone": "0470-8888888",
+        "fax": null,
+        "settleType": "签单",
+        "paymentMode": "预付款",
+        "items": [
+          { "name": "大床房", "date": "2026-07-01", "qty": 1, "unit": "间夜", "unitPrice": null, "amount": null, "remark": "含双早" }
+        ],
+        "totalAmount": null
+      },
+      {
+        "entryId": "S2071200000000000001",
+        "type": "SCENIC",
+        "title": "景点门票预订通知单",
+        "teamNo": "26-1590",
+        "productName": "呼伦贝尔7日游",
+        "dateRange": "2026-07-01→2026-07-07",
+        "paxSummary": "2大1小",
+        "driverName": "全广存", "driverPhone": "18614805444",
+        "guideName": "", "guidePhone": "",
+        "fromCompany": "内蒙古呼籁国际旅行社有限公司",
+        "taxId": "91150702MACYFE851R",
+        "operatorName": "张定制",
+        "supplierName": "呼和诺尔草原旅游区",
+        "contactPerson": "", "contactPhone": "", "fax": null,
+        "settleType": "", "paymentMode": "",
+        "items": [
+          { "name": "门票", "date": "2026-07-03", "qty": 2, "unit": "张", "unitPrice": null, "amount": null, "remark": null }
+        ],
+        "totalAmount": null
+      }
+    ]
+  }
+}
+```
+
+**边界（无酒店无景点）**：`data.entries` = `[]`（空数组）。
+
+**异常（订单不存在）**：
+
+```json
+{ "code": 581007, "message": "订单不存在", "data": null }
+```
+
+---
+
+## ⑨ 业务边界
+
+- 一个订单一个本社：所有 entry 的 `fromCompany`/`taxId`/`operatorName` 相同（同一定制师/本社）。
+- 司机/导游各取本单首条 DRIVER/GUIDE 角色人员；未配则四字段空串。
+- 酒店按 `hotelId` 分组，每酒店一张通知单（多晚合为一组多条 item）；每条景点一张通知单。
+- 自定义景点（无 scenicId）联系人留空。
+- `showAmount=false`（默认）下所有金额 null，前端渲染 `***`。
+
+---
+
+## ⑩ 修改前后对比
+
+| 维度 | 改前 | 改后 |
+|---|---|---|
+| 结构 | `data.header`（共享概要+FROM）+ `data.entries[]` | **只有 `data.entries[]`**，header 删除，所有字段下沉 |
+| FROM | header 一份 | 每个 entry 自带 fromCompany/taxId/**operatorName(新增)** |
+| 订单概要 | header 里 | 每个 entry 里 teamNo/productName/dateRange/paxSummary |
+| 司机/导游 | 无（header.driverName 恒 null） | 每个 entry driverName/driverPhone/guideName/guidePhone |
+| 付款方式 | 无 | 每个 entry settleType/paymentMode |
+| settleType/paymentMode/房型 | 返字典 code（sign/prepay/BIG_BED） | 返中文（签单/预付款/大床房） |
+
+---
+
+## ⑪ 影响评估 / 回滚
+
+- **前端必改**：原读 `data.header.xxx` 的代码全部改读 `data.entries[i].xxx`（header 已删，读 header 会拿到 undefined）。
+- settleType/paymentMode/房型原本若前端自己做 code→中文映射，可删除该映射逻辑（后端已翻好）。
+- 回滚：接口为纯读组装，无 DDL、无状态写入，回滚仅需后端版本回退。
+
+---
+
+## ⑫ 注意事项
+
+- 司机/导游电话为**内网明文全号**（供应商需联系司机/导游，与酒店联系人电话同口径），前端按需展示。
+- 景点 `settleType`/`paymentMode` 本期恒空串（景点资源侧未建结算字段，待后续）。
+- 房型/结算/付款中文依赖数据字典（`room_category`/`hotel_settle_type`/`hotel_payment_mode`），字典缺值时：房型回退「其他房型」，结算/付款回退空串——前端做空值兜底即可。
+
+---
+
+## ⑬ 关联 / 联系人
+
+- Issue：[#4549](https://git.1814.love:8443/wx/HL/issues/4549) / [#4566](https://git.1814.love:8443/wx/HL/issues/4566) / [#4582](https://git.1814.love:8443/wx/HL/issues/4582)（原始 [#4505](https://git.1814.love:8443/wx/HL/issues/4505)）
+- PR：[#4550](https://git.1814.love:8443/wx/HL/pulls/4550) / [#4567](https://git.1814.love:8443/wx/HL/pulls/4567) / [#4584](https://git.1814.love:8443/wx/HL/pulls/4584)
+- 负责人：腰苏图（后端）