feat(退款): AUG26-006 退款方式选择与原路退款

按 PRD 2.3/2.4/2.5 落地套餐退款的方式矩阵与原路渠道退款： - 退款申请派生并冻结权威实收金额（线上取原成功支付记录，钱包/线下取订单实际收款），提交人不可填写或修改；按来源支付方式生成可选方式矩阵并在创建、提交、执行前重复校验。 - 审批切换为「每次提交一条不可变审批尝试记录 + 独立企业微信审批实例」，业务标识取尝试记录主键；终态消费按尝试记录优先、退款申请兜底双读，兼容存量无实例与已关联实例申请。新增活动退款部分唯一索引 (order_id) WHERE status IN (1,5,6)。 - 本地人工终审保持既有开关，补齐通过入口的 approval_instance_id IS NULL 守卫，使三个入口一致拒绝已关联审批实例的申请；重提按尝试模式重写（仅已拒绝/已退回/原路失败且无异常）。 - 权益时点：企微通过事务写退款终态、按方式确定的订单态、钱包回款、员工账单冲销与可靠失效事实；套餐失效/接续/停机仍由既有可靠机制最终一致执行，不把外部调用放入资金事务。订单支付状态按方式置位：凭证退款与退回原钱包在企微通过时置已退款，原路须渠道明确成功。 - 按官方契约实现微信直连 v3、微信 v2（双向证书）、富友（/commonRefund 与 /refundQuery）、支付宝四类原路退款；能力只由服务商类型与退款必需凭证完整性决定，无人工开关。渠道请求号在提交时冻结到尝试记录，并以 channel_submitted_at 条件认领保证资金动作至多提交一次（重复投递只查询不二次提交）；不向任何渠道传递退款结果通知地址。 - 新增 refund:channel:recovery 恢复任务只查询回填；本地查询窗口超期（富友 72 小时、微信 v2 7 天）转原路退款失败、渠道状态已失败、分类超时未知并置异常转人工，不放行自动重提以避免重复退款。 - 同步退款 DTO/导出/审计资源与审计查询关联、商户凭证文档，并修正 fuiou 集成契约文档。迁移 000218（退款尝试与渠道退款事实）、000219（微信 v2 客户端证书凭证）成对提供，未修改既有迁移；测试库 junhong_cmp_test 完成 up/down/up 与行为核对，未调用真实渠道。
2026-09-14 11:55:16 +08:00
parent 48c85a4916
commit ba0855d9eb
51 changed files with 5995 additions and 986 deletions
--- a/pkg/constants/audit.go
+++ b/pkg/constants/audit.go
@@ -361,6 +361,18 @@ const (
 	AuditActionRefundCommissionInvalidated = "refund.invalidate_commission"
 	// AuditActionRefundAssetProcessed 表示退款后的套餐与资产处理已完成。
 	AuditActionRefundAssetProcessed = "refund.process_asset"
+	// AuditActionRefundAttemptSubmitted 表示提交或重提退款审批尝试并创建独立审批实例。
+	AuditActionRefundAttemptSubmitted = "refund.attempt_submit"
+	// AuditActionRefundAttemptApproved 表示企业微信终审通过退款审批尝试。
+	AuditActionRefundAttemptApproved = "refund.attempt_approve"
+	// AuditActionRefundAttemptClosed 表示企业微信驳回、撤销或删除退款审批尝试。
+	AuditActionRefundAttemptClosed = "refund.attempt_close"
+	// AuditActionRefundAnomalyFlagged 表示企业微信通过后撤销，只写正交异常标记并转人工处理。
+	AuditActionRefundAnomalyFlagged = "refund.anomaly_flag"
+	// AuditActionRefundChannelCalled 表示按退款方式发起渠道原路退款调用。
+	AuditActionRefundChannelCalled = "refund.channel_call"
+	// AuditActionRefundChannelRecovered 表示恢复任务按渠道退款请求号回填原路退款结果。
+	AuditActionRefundChannelRecovered = "refund.channel_recover"
 	// AuditActionApprovalRequested 表示创建通用审批实例并请求渠道提交。
 	AuditActionApprovalRequested = "approval.request"
 	// AuditActionApprovalSubmissionSynced 表示同步审批渠道提交结果。
@@ -648,6 +660,10 @@ const (
 	AuditResourceOrder = "order"
 	// AuditResourceRefund 表示退款资源。
 	AuditResourceRefund = "refund"
+	// AuditResourceRefundAttempt 表示退款审批尝试记录资源，主键同时充当审批业务标识。
+	AuditResourceRefundAttempt = "refund_attempt"
+	// AuditResourceRefundChannelRefund 表示退款单上的渠道原路退款事实资源。
+	AuditResourceRefundChannelRefund = "refund_channel_refund"
 	// AuditResourceAccount 表示后台账号资源。
 	AuditResourceAccount = "account"
 	// AuditResourceRole 表示后台角色资源。
@@ -936,6 +952,8 @@ const (
 	AuditResourceRoleRefundPackageUsage = "refund_package_usage"
 	// AuditResourceRoleRefundNotification 表示退款完成通知的可靠 Outbox 事实。
 	AuditResourceRoleRefundNotification = "refund_notification"
+	// AuditResourceRoleRefundChannelRefund 表示退款单上的渠道原路退款事实。
+	AuditResourceRoleRefundChannelRefund = "refund_channel_refund"
 	// AuditResourceRoleCommissionRecord 表示佣金计算或入账涉及的佣金记录。
 	AuditResourceRoleCommissionRecord = "commission_record"
 	// AuditResourceRoleCommissionOrder 表示佣金关联订单。
@@ -1065,6 +1083,8 @@ const (
 	AuditActorIDRefundAssetPostProcessing = "refund_asset_post_processing"
 	// AuditActorIDRefundCommissionPostProcessing 表示退款佣金自动回扣任务。
 	AuditActorIDRefundCommissionPostProcessing = "refund_commission_post_processing"
+	// AuditActorIDRefundChannel 表示退款渠道原路退款的调用与恢复任务。
+	AuditActorIDRefundChannel = "refund_channel"
 	// AuditActorIDCommissionCalculationWorker 表示订单佣金计算任务。
 	AuditActorIDCommissionCalculationWorker = "commission_calculation_worker"
 	// AuditActorIDRetentionWorker 表示日志留存清理任务。
--- a/pkg/constants/constants.go
+++ b/pkg/constants/constants.go
@@ -91,6 +91,7 @@ const (
 	TaskTypeWeComApprovalSync     = "wecom:approval:sync"             // 企业微信审批详情异步同步
 	TaskTypeWeComApprovalRecovery = "wecom:approval:recovery"         // 企业微信审批主动恢复与轮询
 	TaskTypeAgentRechargeRecovery = "agent_recharge:payment:recovery" // 代理在线充值支付恢复与查单
+	TaskTypeRefundChannelRecovery = "refund:channel:recovery"         // 渠道原路退款结果恢复与查询
 )

 // 用户状态常量
@@ -306,7 +307,7 @@ func QueueForTaskType(taskType string) string {
 		return QueueCardObservationSeries
 	case TaskTypeWeComApprovalSync, TaskTypeWeComApprovalRecovery:
 		return QueueWeComApproval
-	case TaskTypeAgentRechargeRecovery:
+	case TaskTypeAgentRechargeRecovery, TaskTypeRefundChannelRecovery:
 		return QueueDefault
 	default:
 		return QueueDefault
--- a/pkg/constants/iot.go
+++ b/pkg/constants/iot.go
@@ -57,12 +57,12 @@ const (

 // Gateway 卡状态
 const (
-	GatewayCardStatusReady             = "准备"     // 网关卡状态：准备
-	GatewayCardStatusNormal            = "正常"     // 网关卡状态：正常
-	GatewayCardStatusStopped           = "停机"     // 网关卡状态：停机
+	GatewayCardStatusReady                 = "准备"     // 网关卡状态：准备
+	GatewayCardStatusNormal                = "正常"     // 网关卡状态：正常
+	GatewayCardStatusStopped               = "停机"     // 网关卡状态：停机
 	GatewayCardExtendPendingActivation     = "待激活"    // 网关扩展状态：待激活
 	GatewayCardExtendMachineSeparated      = "机卡分离停机" // 网关扩展状态：机卡分离停机
-	GatewayCardStartExtendMachineSeparated = "2"         // 机卡分离复机时上传给运营商的 extend 值
+	GatewayCardStartExtendMachineSeparated = "2"      // 机卡分离复机时上传给运营商的 extend 值
 	GatewayCardExtendRiskStop              = "风险停机"   // 网关扩展状态：运营商风险停机（独立卡不允许复机）
 	GatewayCardExtendCancelled             = "已销户"    // 网关扩展状态：已销户（独立卡不允许复机）
 )
@@ -409,7 +409,7 @@ func GetOrderCommissionResultName(result int) string {
 }

 // GetRefundStatusName 获取退款申请状态名称
-// 1=待审批, 2=已通过, 3=已拒绝, 4=已退回
+// 1=待审批, 2=已通过, 3=已拒绝, 4=已退回, 5=原路退款处理中, 6=原路退款失败
 func GetRefundStatusName(status int) string {
 	switch status {
 	case 1:
@@ -420,6 +420,10 @@ func GetRefundStatusName(status int) string {
 		return "已拒绝"
 	case 4:
 		return "已退回"
+	case 5:
+		return "原路退款处理中"
+	case 6:
+		return "原路退款失败"
 	default:
 		return "未知"
 	}
--- a/pkg/constants/refund.go
+++ b/pkg/constants/refund.go
@@ -0,0 +1,110 @@
+package constants
+
+const (
+	// RefundMethodOriginalRoute 表示按原支付渠道原路退款。
+	RefundMethodOriginalRoute = "original_route"
+	// RefundMethodCustomerAccount 表示退至客户提供的收款信息。
+	RefundMethodCustomerAccount = "customer_account"
+	// RefundMethodAssetWallet 表示退回原资产钱包。
+	RefundMethodAssetWallet = "asset_wallet"
+	// RefundMethodAgentWallet 表示退回原代理主钱包。
+	RefundMethodAgentWallet = "agent_wallet"
+)
+
+// RefundMethodName 返回退款方式中文名称。
+func RefundMethodName(method string) string {
+	switch method {
+	case RefundMethodOriginalRoute:
+		return "原路退款"
+	case RefundMethodCustomerAccount:
+		return "客户收款信息退款"
+	case RefundMethodAssetWallet:
+		return "退回资产钱包"
+	case RefundMethodAgentWallet:
+		return "退回代理主钱包"
+	default:
+		return "未知方式"
+	}
+}
+
+const (
+	// RefundChannelStatusNone 表示未发起渠道退款或不适用该方式。
+	RefundChannelStatusNone = 0
+	// RefundChannelStatusProcessing 表示渠道退款已提交但结果未确认。
+	RefundChannelStatusProcessing = 1
+	// RefundChannelStatusSucceeded 表示渠道明确退款成功。
+	RefundChannelStatusSucceeded = 2
+	// RefundChannelStatusFailed 表示渠道明确退款失败。
+	RefundChannelStatusFailed = 3
+)
+
+// RefundChannelStatusName 返回渠道退款状态中文名称。
+func RefundChannelStatusName(status int) string {
+	switch status {
+	case RefundChannelStatusProcessing:
+		return "处理中"
+	case RefundChannelStatusSucceeded:
+		return "已成功"
+	case RefundChannelStatusFailed:
+		return "已失败"
+	default:
+		return "未发起"
+	}
+}
+
+// 退款结构化失败分类稳定编码。
+// 分类既用于详情展示与审计，也用于后续佣金回溯判定「明确失败可回溯 / 在途不可回溯」。
+const (
+	// RefundFailureChannelRejected 表示渠道明确拒绝退款。
+	RefundFailureChannelRejected = "channel_rejected"
+	// RefundFailureCredentialInvalid 表示该商户退款必需凭证缺失或失效，渠道侧不可执行。
+	RefundFailureCredentialInvalid = "credential_invalid"
+	// RefundFailureInsufficientBalance 表示渠道账户余额不足。
+	RefundFailureInsufficientBalance = "insufficient_balance"
+	// RefundFailureTimeoutUnknown 表示调用超时或渠道结果未确认，属可恢复状态。
+	RefundFailureTimeoutUnknown = "timeout_unknown"
+	// RefundFailureApprovalRejected 表示企业微信驳回、撤销或删除。
+	RefundFailureApprovalRejected = "approval_rejected"
+	// RefundFailureRevokedAfterApproved 表示企业微信通过后撤销，属需人工处理的异常。
+	RefundFailureRevokedAfterApproved = "revoked_after_approved"
+	// RefundFailurePaymentFactInvalid 表示本地原支付单、实际收款商户、原渠道流水或可退金额校验不通过。
+	RefundFailurePaymentFactInvalid = "payment_fact_invalid"
+)
+
+// RefundFailureReasonName 返回失败分类中文名称。
+func RefundFailureReasonName(reason string) string {
+	switch reason {
+	case RefundFailureChannelRejected:
+		return "渠道明确拒绝"
+	case RefundFailureCredentialInvalid:
+		return "渠道凭证失效"
+	case RefundFailureInsufficientBalance:
+		return "渠道余额不足"
+	case RefundFailureTimeoutUnknown:
+		return "超时或结果未知"
+	case RefundFailureApprovalRejected:
+		return "企业微信驳回或关闭"
+	case RefundFailureRevokedAfterApproved:
+		return "企业微信通过后撤销"
+	case RefundFailurePaymentFactInvalid:
+		return "本地原支付事实不可用"
+	default:
+		return "无失败"
+	}
+}
+
+// RefundFailureReasonIsDefinitive 判断失败分类是否属于明确失败。
+// 明确失败表示退款已终结且可进入后续回溯判定；超时未知与企业微信通过后撤销均非明确失败，
+// 前者保持可恢复、后者转人工处理，都不得据此回溯佣金。
+func RefundFailureReasonIsDefinitive(reason string) bool {
+	switch reason {
+	case RefundFailureChannelRejected,
+		RefundFailureCredentialInvalid,
+		RefundFailureInsufficientBalance,
+		RefundFailureApprovalRejected,
+		RefundFailurePaymentFactInvalid:
+		return true
+	default:
+		return false
+	}
+}