yaosutu f1d36b8522 docs(changelog-v2): 签单 sign-voucher 金额改取协议成本价修改接口通知

GET /v3/admin/order/{id}/sign-voucher 出参 unitPrice/amount/totalAmount 取值来源
从客户成交价(sell_price)改为协议成本价(景点 node.unit_price / 酒店 house.proto_price)，
字段名与结构不变。关联 HL #4722 / PR #4724。

2026-07-02 14:51:07 +08:00

5.3 KiB

原始文件 Blame 文件历史

签单 sign-voucher 金额改取「协议成本价」（原取客户成交价，取错字段）

接口路径：GET /v3/admin/order/{id}/sign-voucher 服务：hl-order-service-v3 PR：#4724｜ Issue：#4722｜前序：#4716（移除服务/接送单）/ #4072（house 协议价）｜ 合并至：dev-v3 变更类型：修改接口（出参金额取值来源变更，字段名不变）

1. 接口背景

签单（预订通知单）接口给供应商核对成本用。此前 entries[].items[].unitPrice/amount 与 entries[].totalAmount 取的是「客户成交价」，与"供应商核成本"语义不符，属取错字段。本次改为取「协议成本价」。入参不变，出参结构与字段名均不变，仅金额取值来源变。

2. 变更清单

位置	变更
景点单价	取值来源 `node.sell_price`（成交价）→ `node.unit_price`（协议价）
酒店单价	取值来源 `house.sell_price`（成交价）→ `house.proto_price`（协议价）
合计金额	= 协议单价 × 数量（景点按人数、酒店按间数），后端现算

入参无变化，出参 JSON 结构 / 字段名无变化，无 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[] 结构不变，受影响金额字段：

字段	类型	说明（变更后语义）
`entries[].items[].unitPrice`	BigDecimal	单价 = 协议成本价（景点 node.unit_price / 酒店 house.proto_price）
`entries[].items[].amount`	BigDecimal	明细金额 = 协议单价 × 数量
`entries[].totalAmount`	BigDecimal	该通知单合计 = 协议单价 × 数量

showAmount=false 时上述金额字段均为 null（脱敏，行为不变）。

6. 枚举 / 数据字典

无枚举变更。

7. 错误码

无新增错误码。房务角色返 581045；订单不存在返 581007。

8. 示例

8.1 典型成功（酒店有协议价 320、景点协议价 0）

请求：

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

响应片段：

{
  "code": 200,
  "data": {
    "entries": [
      {"type": "HOTEL", "supplierName": "呼伦贝尔香格里拉大酒店", "totalAmount": "1280.00",
        "items": [{"name": "大床房", "qty": 4, "unitPrice": "320.00", "amount": "1280.00"}]},
      {"type": "SCENIC", "supplierName": "呼和诺尔草原旅游区", "totalAmount": "0.00",
        "items": [{"name": "门票", "qty": 10, "unitPrice": "0.00", "amount": "0.00"}]}
    ]
  }
}

说明：单价取协议价——酒店 proto_price=320；景点 unit_price=0（该订单资源价格日历未配景点协议价，故为 0）。

8.2 边界（showAmount=false，脱敏）

{ "type": "HOTEL", "totalAmount": null, "items": [{"unitPrice": null, "amount": null}] }

8.3 协议价缺失

协议价字段 NULL → 对应 unitPrice/amount 为 null（前端展示空）；协议价为 0 → 展示 0.00。

9. 业务边界

签单金额自此代表给供应商的协议成本价，不再是客户成交价。
景点协议价来源 = 创单固化时从资源价格日历写入 order_itinerary_node.unit_price；酒店协议价来源 = 房务维护的 house_hotel_assignment.proto_price（resource 单源，#4072）。
协议价未配置的资源，签单金额会显示 0 或空，属数据源（价格日历/房务协议价）未维护，非接口问题。

10. 修改前后对比

条目	修改前 unitPrice	修改后 unitPrice
景点	node.sell_price（客户成交价）	node.unit_price（协议成本价）
酒店	house.sell_price（客户成交价）	house.proto_price（协议成本价）

出参 JSON 结构、字段名不变，仅数值来源与语义变化。

11. 影响评估 / 回滚

取值语义变更（前端需知晓）：签单展示的金额从「客户成交价」变为「协议成本价」。字段名不变，前端渲染代码无需改，但若页面上有"成交价"文案标注需同步为"协议价/成本价"。

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

12. 注意事项

已部署测试服并行为验证：酒店 unitPrice=proto_price（320）、景点 unitPrice=unit_price（0.00，原取 sell_price 时为 null，现为 0.00，证明已切协议价来源）；showAmount=false 金额全 null。
协议价数据未维护的订单签单会显示 0/空，与本次改动无关。

13. 关联 / 联系人

Issue：#4722
PR：#4724
前序：#4716 / #4072
负责人：腰苏图（yst）

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