docs(2026-05-07): refund 申诉补企微 OA 提交 (PR #1774)

后端纯内部修复,前端无配合,运维补 nacos 三套 + 7 控件 ID。 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-07 10:27:01 +08:00
@@ -0,0 +1,54 @@
+# fix(refund): 退款申诉补企微 OA 提交
+
+**PR**: [#1774](https://git.1814.love:8443/wx/HL/pulls/1774) **Issue**: [#1773](https://git.1814.love:8443/wx/HL/issues/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 不阻塞业务):
+
+```yaml
+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 配置补齐后由管理者完成