hl-api-changelog/changelogs/2026-05/07_fix_refund_appeal_oa_submission.md

fix(refund): 退款申诉补企微 OA 提交

PR: #1774 Issue: #1773 合并: 2026-05-07

通知对象: 无前端配合(后端纯内部修复 + 运维补 nacos)

---

后端修了什么

mp 端「申诉(appeal)」/「直接申诉(directAppeal)」之前只写 DB status=APPEALING,完全没调企微 OA 提交,审批人永远收不到通知,DB 永久卡死。

回调侧(ApprovalEventHandler:155 按 template-id 路由)+ DTO 字段 + user-service buildRefundAppealControls 出口控件构建 + nacos 配置 key 全已就绪,只缺 order-service 出口侧调用闭环。

PR #1774 补的:

• RefundApplyService.submitAppealOa(app) — 申诉模板 7 字段渲染 + Feign 提交,失败抛 RuntimeException 让 LocalEvent 兜底重试
• RefundAppealService.appeal/directAppeal afterCommit 调 + 失败 publish RETRY_SUBMIT_REFUND_APPEAL_OA LocalEvent
• RetrySubmitRefundAppealOaHandler — 复用 RetrySubmitRefundOaHandler 模式,幂等跳过(status≠APPEALING 或 approvalNo 非空)
• RefundAppealBackfillJob — @EventListener(ApplicationReadyEvent) 启动一次性扫 + 补发卡死的「僵尸申诉」(分布式锁 + 单条失败不阻塞)

前端无需改动

/internal/mp/order/refund/{applicationId}/appeal 和 /internal/mp/order/{orderId}/direct-appeal 接口签名 / VO / 字段 0 改动。前端 UI 不变。

部署依赖(运维侧 nacos 配置)

P0 - 必须补齐才能生效(配置缺失时 submitAppealOa 静默 return 不阻塞业务):

approval:
  refund-appeal:
    template-id: 3WNge6AGZK2Pq4JwoCAkRXYwaTidZkrXCs9DsiSz
    control-ids:
      customer-name:    <从企微管理端「订单退款申诉」模板编辑页拿>
      customizer-name:  <同上>
      product-type:     <同上>
      order-no:         <同上>
      order-date:       <同上>
      departure-date:   <同上>
      reason:           <同上>

三套 namespace 都要补:dev / test / prod。

历史卡死单处理

服务重启时 RefundAppealBackfillJob 会自动扫 status=APPEALING AND approval_no IS NULL 的"僵尸申诉",逐条调 submitAppealOa 补发到企微 — 用户无感,运营不需要让用户重新点申诉按钮。

测试

• 单测 22 个新增,4 个测试文件 51/51 全绿(RefundApplyServiceTest +6 / RefundAppealServiceTest +3 / RetrySubmitRefundAppealOaHandlerTest 7 / RefundAppealBackfillJobTest 6)
• 本地 round-trip 兜底(4 服务联动 + 外部企微回调 30min 不可达,走「单测全绿 + 测试服真实 round-trip」路径)
• 测试服 round-trip 待 nacos 配置补齐后由管理者完成