changelog(7561): 12301 合同申请补装配 v3 回调地址

Refs #7561 / PR HL#7672（dev-v3 fee1faf2c）

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

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 自身所有接口**的请求/响应结构、错误码、路由均无变化。