From dbd1eba658bf840550672b6a846133d11d914658 Mon Sep 17 00:00:00 2001 From: jw Date: Mon, 14 Sep 2026 10:31:50 +0800 Subject: [PATCH] =?UTF-8?q?changelog(7561):=2012301=20=E5=90=88=E5=90=8C?= =?UTF-8?q?=E7=94=B3=E8=AF=B7=E8=A1=A5=E8=A3=85=E9=85=8D=20v3=20=E5=9B=9E?= =?UTF-8?q?=E8=B0=83=E5=9C=B0=E5=9D=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Refs #7561 / PR HL#7672（dev-v3 fee1faf2c） Co-Authored-By: Claude Opus 5 (1M context) --- ...1合同申请补装配v3回调地址-修复-管理后台.md | 76 +++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 changelogs-v2/2026-09/14_7561_12301合同申请补装配v3回调地址-修复-管理后台.md diff --git a/changelogs-v2/2026-09/14_7561_12301合同申请补装配v3回调地址-修复-管理后台.md b/changelogs-v2/2026-09/14_7561_12301合同申请补装配v3回调地址-修复-管理后台.md new file mode 100644 index 00000000..5444c726 --- /dev/null +++ b/changelogs-v2/2026-09/14_7561_12301合同申请补装配v3回调地址-修复-管理后台.md @@ -0,0 +1,76 @@ +--- +schema: "hl-changelog/v2" +ticket: "7561" +title: "12301 合同申请补装配 v3 回调地址：签署完成回调终于能打回 v3" +consumer: "admin" +author: "jw(GIT)" +change_type: "修复" +backend_status: "deployed" +gateway_status: "verified" +frontend_status: "not_required" +frontend_owner: "" +frontend_ref: "" +target_release: "" +verified_at: "" +status_note: "not_required：不改任何 HL 接口的请求/响应结构、不新增错误码、不改路由，无 Flyway。改的是 order-v3 发往外部平台（12301/Tourage）的请求体里多带一个 callbackURL 字段。前端无触点——但业务侧可观察到的变化是：新建合同签署完成后 contract.status 会真的从 GENERATED 推进到 SIGNED，而此前只能靠运维手工订正。" +updated_at: "2026-09-14" +base: "dev-v3" +--- + +# 12301 合同申请补装配 v3 回调地址（修复） + +> **服务**: hl-order-service-v3（`ContractCreateService`） +> **PR**: #7672 +> **Issue**: #7561 +> **日期**: 2026-09-14 +> **影响范围**: 发往 12301(Tourage) 的**合同申请报文**多一个 `callbackURL` 字段；**不涉及** HL 自身任何接口的请求/响应结构、错误码、路由与数据库 + +--- + +## ⚠️ 关键变化 + +v3 从 2026-05-13 的迁移（#2185）起，就**没有任何地方调过** `param.setCallbackUrl()`： + +| 环节 | 状态 | +|---|---| +| `ContractApplyParam.callbackUrl` 字段 | 在 | +| `TourageRequestBuilder` 把它写成 `callbackURL` | 在 | +| **中间那一步（装配）** | **空的** | + +于是发往 12301 的报文从来不带 `callbackURL`，平台只能沿用它那边登记的历史地址（多半还是 v2 的）。**结果：v3 创建的合同签完收不到回调，`contract.status` 永远停在 `GENERATED`，`order_main.contract_status` 镜像跟着停住。** + +本次补上装配，路径为 `/v3/contract/callback/12301`（对齐 `ContractCallbackController`，**不是** v2 的 `/contract/callback/12301`——那条在网关上指向 v2 服务）。 + +网关那一半（路由 + JWT 白名单）已由 #7563 / PR #7567 先行合入，两半齐了链路才通。 + +--- + +## 业务侧能观察到什么 + +- **新建的 12301 合同**：出行人在平台签完后，v3 会收到回调，`contract.status` 自动推进 `GENERATED → SIGNING → SIGNED`。此前这一步只能靠运维手工订正。 +- **本次修复之前创建的存量合同**：报文当时就没带回调地址，平台不会因为我方改了代码而补发回调。**存量合同仍需手工订正**，本单不做数据修复。 +- **合同状态是团期「资源准备中 → 物料准备中」第三道门的判据之一**（#7023 / #7526），这条链路此前是断的。 + +--- + +## 运维须知 + +回调地址的 origin 取自 nacos 的 `contract.platform.callback-base-url`。 + +**TEST 上该值是 `https://web.test.1814.love`（前端域名），看着像配错，实测是通的**——那台反代到同一后端，`GET /v3/contract/callback/12301` 返回 `405 请求方法不支持`（已路由到只收 POST 的端点），同前缀不存在路径返回 `404 接口不存在`。**不要照着「域名和 tencent-esign 那条不一样」就去改 nacos**；真要动，先用这两发探针确认新值可达。 + +**生产侧本单无核对通道**。若该 key 缺失或只剩斜杠，代码不会报错，而是**不下发 `callbackURL`**（比下发一个错地址安全），并打一条可 grep 的告警： + +``` +[#7561] contract.platform.callback-base-url 取不到可用 origin（原值=...），本次 12301 合同申请不下发 callbackURL… +``` + +这条日志是**真实平台链路上唯一的观测点**——失败模式是「什么都不发生」，报文少一个字段、平台照常受理、签完不回调，现场只看得到 status 停在 `GENERATED`，离根因很远。**上线后若日志里出现它，说明生产的 `callback-base-url` 没配，回调依旧不会来。** + +--- + +## 不受影响的部分 + +- **合同报备（同步模式）报文逐字节不变**：报备按约定不带回调地址，装配点刻意放在 `buildApplyParam` 而非两条链路共用的 `buildApplyParamInto`，并有护栏测试钉死。 +- **腾讯电子签合同不受影响**：按平台分流，非 12301 不装配；腾讯走自己的 `TencentEsignProperties.callbackBaseUrl`。 +- **HL 自身所有接口**的请求/响应结构、错误码、路由均无变化。