yaosutu 55944610fb docs(changelog-v2): 签单 sign-voucher 移除服务/接送预订单修改接口通知

GET /v3/admin/order/{id}/sign-voucher 出参 entries 不再返回 type=SERVICE 的
服务/接送预订通知单，只保留 HOTEL 酒店 + SCENIC 景点两类。关联 HL #4715 / PR #4716。

2026-07-02 11:50:18 +08:00

5.5 KiB

原始文件 Blame 文件历史

签单 sign-voucher 移除「服务/接送预订单」，只保留酒店 + 景点

接口路径：GET /v3/admin/order/{id}/sign-voucher 服务：hl-order-service-v3 PR：#4716｜ Issue：#4715｜关联：#4642（服务/接送单初建）｜ 合并至：dev-v3 变更类型：修改接口（出参：移除一类 entry，破坏性变更）

1. 接口背景

签单（预订通知单）接口 GET /v3/admin/order/{id}/sign-voucher 给供应商核对资源，原组装三类通知单：酒店预订单 + 景点门票预订单 + 服务/接送预订单（服务/接送单是 #4642 加的）。

业务反馈：签单只需给供应商核对酒店 + 景点，服务/接送不需要出签单。本次移除服务/接送这类 entry。入参不变，无 DDL。

2. 变更清单

类型	位置	变更说明
破坏性变更	出参 `entries[]`	不再返回 `type=SERVICE` 的 entry（服务/接送预订通知单）。仅保留 `type=HOTEL` + `type=SCENIC`
说明变更	出参 `entries[].type`	枚举说明由 `HOTEL/SCENIC/SERVICE` 收敛为 `HOTEL/SCENIC`
无变化	入参 / 其余出参字段	完全不变

入参无变化，无 DDL，无新依赖。

3. 接口详情

方法：GET ｜路径：/v3/admin/order/{id}/sign-voucher ｜鉴权：管理后台 JWT（房务角色无权，返 581045）
响应：Result<SignVoucherRespVO>

4. 入参

位置	字段	类型	必填	说明
Path	`id`	Long	是	订单 ID
Query	`showAmount`	Boolean	否	是否展示金额（false=脱敏成 null，默认 false）

本次入参无变化。

5. 出参

SignVoucherRespVO.entries[]（VoucherEntryVO 数组）结构不变，仅不再包含 type=SERVICE 的元素。

字段	类型	说明	变化
`entries[].type`	String	条目类型：`HOTEL`=酒店 / `SCENIC`=景点门票	枚举去掉 `SERVICE`
`entries[].entryId`	String	条目唯一 ID（`H{id}` 酒店 / `S{id}` 景点）	`SV{id}` 服务前缀不再出现
`entries[].title`	String	通知单标题（酒店预订通知单 / 景点门票预订通知单）	「服务/接送预订通知单」不再出现
其余字段	——	supplierName / contactPerson / items / totalAmount 等均不变	无

6. 枚举 / 数据字典

entries[].type 取值收敛：

取值	含义	状态
`HOTEL`	酒店预订通知单	保留
`SCENIC`	景点门票预订通知单	保留
~~`SERVICE`~~	~~服务/接送预订通知单~~	已移除

7. 错误码

无新增错误码。房务角色调用仍返 581045 房务角色无权查看订单详情；订单不存在返 581007。

8. 示例

8.1 典型成功（某订单含服务节点 + 景点节点，无配房）

请求：

GET /v3/admin/order/2072527122097750017/sign-voucher?showAmount=true

响应（只返回景点单，无服务/接送单）：

{
  "code": 200,
  "message": "成功",
  "data": {
    "entries": [
      {"type": "SCENIC", "title": "景点门票预订通知单", "supplierName": "呼和诺尔草原旅游区"},
      {"type": "SCENIC", "title": "景点门票预订通知单", "supplierName": "恩和俄罗斯民族乡"},
      {"type": "SCENIC", "title": "景点门票预订通知单", "supplierName": "套娃景区"},
      {"type": "SCENIC", "title": "景点门票预订通知单", "supplierName": "蓝房子（乌苏浪子湖）"}
    ]
  }
}

8.2 边界（酒店 + 景点都有）

entries 含 type=HOTEL 与 type=SCENIC 两类，无 SERVICE。

8.3 异常（房务角色）

{ "code": 581045, "message": "房务角色无权查看订单详情，房务仅可配房", "success": false }

9. 业务边界

签单仅面向供应商核对酒店 + 景点两类资源。
订单即使配置了服务/接送节点（order_itinerary_node SERVICE/TRANSPORT），签单也不再为其出通知单。
showAmount 逻辑不变：金额取自资源成本价字段，底层为 NULL 时展示为空（与本次变更无关）。

10. 修改前后对比

场景	修改前 entries	修改后 entries
有 N 个服务/接送节点	生成 N 个 `type=SERVICE` entry	不生成
酒店 / 景点	照常生成 `HOTEL` / `SCENIC`	不变

以某含 2 服务节点 + 4 景点节点订单实测：修改前 6 个 entry（2 SERVICE + 4 SCENIC），修改后 4 个 entry（全 SCENIC）。

11. 影响评估 / 回滚

破坏性变更（前端需同步）：签单打印页若渲染过「服务/接送预订通知单」（type=SERVICE），需移除该渲染分支。酒店 / 景点单不受影响。

回滚：接口层回退到 PR #4716 之前版本即恢复。零 DDL，无数据迁移。

12. 注意事项

已部署测试服并行为验证：含服务节点的真实订单实调，entries 只返回景点单、SERVICE 数为 0；实时 OpenAPI 文档 type 说明已收敛为 HOTEL/SCENIC。
entryId 前缀 SV（服务）不再出现，前端若按前缀分组请同步。

13. 关联 / 联系人

Issue：#4715
PR：#4716
关联：#4642（服务/接送单初建，本次移除）
负责人：腰苏图（yst）

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