:docs: 更新HCS审批同步推送说明

doc/docs/hcs合同/2026-10-09-项目立项与合同HCS前端接入设计.md

@@ -263,14 +263,16 @@ export const applyContractSpec = data =>
 位置 `org.springblade.transport.support.hcs`，职责只有一个：**事务提交后异步触发一次单条推送**。
 
 ```java
-public void pushProjectAfterCommit(Long id)   // 项目 C102
-public void pushContractAfterCommit(Long id)  // 合同 C103
+public void pushProjectAfterCommit(Long id)   // 项目 C102（MK 回调路径，异步）
+public void pushContractAfterCommit(Long id)  // 合同 C103（MK 回调路径，异步）
+public void pushProjectAndWait(Long id)       // 项目 C102（本地"通过"按钮，Controller 同步调用）
+public void pushContractAndWait(Long id)      // 合同 C103（本地"通过"按钮，Controller 同步调用）
 ```
 
 执行模型：
 
 1. **afterCommit 触发**：审批方法在事务内调用本组件 → `TransactionSynchronizationManager.registerSynchronization` 注册 afterCommit 回调，审批事务回滚则不推送。MK 回调路径若未包事务（单条 updateById 自动提交）则直接提交异步，语义等价。
-2. **异步执行**：自建 2 线程 daemon 池（线程名 `hcs-immediate-push`，`@PreDestroy` 释放）。工程未启用 `@EnableAsync`，不为此新增全局配置；HCS 推送含风险校验+附件转传+起草可达 20s+，绝不能阻塞审批响应。
+2. **异步执行**：自建 2 线程 daemon 池（线程名 `hcs-immediate-push`，`@PreDestroy` 释放）。工程未启用 `@EnableAsync`，不为此新增全局配置；HCS 推送含风险校验+附件转传+起草可达 20s+，绝不能阻塞审批响应（例外：本地「通过」按钮走 `pushProjectAndWait/pushContractAndWait`，事务提交后同步执行，失败原因回传前端）。
 3. **执行体**（与 HcsPushTask 同线程模型，无租户上下文，与定时扫描行为一致）：
    - 开关：`thirdParty.hcs.push.immediate-enabled`（默认 false，灰度打开）
    - 短路：查库 `approvalStatus ∉ {approved, change_approved}` 或 `hcs_sync_status = synced` → 跳过（已被扫描/人工重推处理过）
@@ -281,8 +283,8 @@ public void pushContractAfterCommit(Long id)  // 合同 C103
 
 | 入口 | 位置 | 触发调用 |
 |---|---|---|
-| 本地审批 | `ProjectApplyServiceImpl.approve()`（事务内，含变更通过，现有置 unsynced 行之后） | `pushProjectAfterCommit(id)` |
-| 本地审批 | `ContractManageServiceImpl.approve()`（事务内，含变更通过 + 履约行置 add，`updateById` 之后） | `pushContractAfterCommit(id)` |
+| 本地审批 | `ProjectApplyController.approve()`（审批事务返回后同步推送） | `pushProjectAndWait(id)`，失败原因经 `pollSyncFailure()` 以 `data=false` 回传前端 |
+| 本地审批 | `ContractManageController.approve()`（审批事务返回后同步推送） | `pushContractAndWait(id)`，失败原因同上 |
 | MK 回调 | `MkProcessBizHandlers.ProjectHandler.approveFromProcess()`（`updateById` 返回 true 后） | `pushProjectAfterCommit(id)` |
 | MK 回调 | `MkProcessBizHandlers.ContractHandler.approveFromProcess()`（同上） | `pushContractAfterCommit(id)` |
 

doc/docs/hcs合同/2026-10-12-合同特批与结算付款特批流程梳理.md

@@ -71,13 +71,14 @@ need（存量遗留，2026-10-13 起不再产生；重推时自愈：报文带
 
 ### 2.3 阶段 B：审批通过 → 推送（报文带特批标记）→ 挂起
 
-审批通过：`POST /contract-manage/approve` → `ContractManageServiceImpl#approve`：置 `hcsSyncStatus=unsynced`（推送零埋点 ADR-0001）→ `hcsImmediatePushSupport.pushContractAfterCommit(id)`。
+审批通过：`POST /contract-manage/approve` → `ContractManageServiceImpl#approve`：置 `hcsSyncStatus=unsynced`（推送零埋点 ADR-0001）；审批事务提交返回后由 `ContractManageController#approve` 同步调用 `hcsImmediatePushSupport.pushContractAndWait(id)`，失败原因经 `pollSyncFailure()` 以警告文案（`data=false`）回传前端。
 
 合同推送共 3 个入口，收敛到 `HcsContractSyncSupport#pushContract`：
 
 | 入口 | 位置 | 说明 |
 | --- | --- | --- |
 | 即时推送 | `HcsImmediatePushSupport#pushContractAfterCommit` | afterCommit 异步（2 线程 daemon 池），开关 `push.immediate-enabled` 默认 false；`pushContractNow` 对特批挂起中（processing）短路跳过 |
+| 审批按钮同步推送 | `ContractManageController#approve` → `HcsImmediatePushSupport#pushContractAndWait` | 审批事务提交返回后同步推送（响应等待附件转传 + HCS 调用），失败原因经 `pollSyncFailure()` 拼入响应 `data=false` |
 | 定时扫描 | `HcsPushTask#pushHcsContract`（cron 默认 `0 1/5 * * * ?`） | `pushUnsyncedContracts`：`approvalStatus ∈ {approved, change_approved}` 且 `hcs_sync_status ∈ {unsynced, failed}` 且重试未超限；同轮附带特批结果查询兜底（见 §2.5） |
 | 手动重推 | `HcsSyncController POST /hcs/sync/contract/{id}` → `repushContract` | 特批审核中（processing）不可推 |