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

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

2026-06-29 10:09:16 +08:00

11 KiB

原始文件 Blame 文件历史

打印签单出参重制（自包含通知单 + 字段全中文化）

变更类型：修改接口 ｜端类型：管理后台 ｜接口：GET /v3/admin/order/{id}/sign-voucher 合并自 3 个 PR：#4549（FROM 下沉 + 付款方式 + 经办人）、#4566（订单概要下沉 + 司机/导游）、#4584（房型/结算/付款方式中文化）原始接口见 #4505。本文给出最终出参契约，前端按此对接即可。

① 接口背景

订单详情「打印签单」功能，后端组装「酒店预订通知单 + 景点门票预订通知单」（A4 横向传真单）数据。原型每张单独立打印，发给不同供应商。本次按验收反馈把出参重制为「每张通知单完全自包含」，并把所有字典 code 后端翻成中文。

② 变更清单

删除共享 header：原 data.header（订单概要 + FROM 抬头）整体删除，所有字段下沉到每个 entries[]，每条自成一张可独立打印的 A4 单。
订单概要下沉：teamNo / productName / dateRange / paxSummary 移到每个 entry。
FROM 抬头下沉 + 新增经办人：fromCompany / taxId 移到每个 entry，新增 operatorName（经办人/发件人=订单定制师）。
新增司机/导游：每个 entry 加 driverName / driverPhone / guideName / guidePhone（电话为内网明文，供应商可联系；无则空串）。
新增付款方式：每个 entry 加 settleType（结算方式）/ paymentMode（付款方式）。
字段全中文化：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 景点）

{
  "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 = []（空数组）。

异常（订单不存在）：

{ "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 / #4566 / #4582（原始 #4505）
PR：#4550 / #4567 / #4584
负责人：腰苏图（后端）

11 KiB 原始文件 Blame 文件历史 Unescape Escape