hl-api-changelog/changelogs-v2/2026-09/14_7561_12301合同申请补装配v3回调地址-修复-管理后台.md

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	7561	12301 合同申请补装配 v3 回调地址：签署完成回调终于能打回 v3	admin	jw(GIT)	修复	deployed	verified	not_required					not_required：不改任何 HL 接口的请求/响应结构、不新增错误码、不改路由，无 Flyway。改的是 order-v3 发往外部平台（12301/Tourage）的请求体里多带一个 callbackURL 字段。前端无触点——但业务侧可观察到的变化是：新建合同签署完成后 contract.status 会真的从 GENERATED 推进到 SIGNED，而此前只能靠运维手工订正。	2026-09-14	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 自身所有接口的请求/响应结构、错误码、路由均无变化。