8eb7d403c4
- 新增 tb_refund_post_process_attempt，每次尝试一条（步骤、触发方式、结果、错误码与信息、耗时） - 退款单增加 asset_post_status/attempts/last_error/next_at；失败按 2^(n-1) 分钟退避（最长 1 小时），10 次后转人工 - 中间失败只写应用日志，成功或转人工写一条结论审计（带总尝试次数、首次失败时间、最后错误码） - 补偿扫描跳过需人工处理与未到重试时间的退款单，Outbox 不再无限重投 - 新增 POST /refunds/:id/asset-post-processing/retry 人工重试 - 停复机指令执行前结束（已是目标状态、条件不再满足、需相反动作）写 skipped 停复机记录 - 迁移 000271 需维护者在测试库执行后再部署 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
176 lines
14 KiB
Go
176 lines
14 KiB
Go
package model
|
||
|
||
import (
|
||
"time"
|
||
|
||
"gorm.io/datatypes"
|
||
"gorm.io/gorm"
|
||
)
|
||
|
||
// RefundRequest 退款申请模型
|
||
// 记录退款申请的完整生命周期，包含退款单号、关联订单、金额、状态流转、审批信息等
|
||
// 状态流转：1(待审批) → 2(已通过)/3(已拒绝)/4(已退回)，4(已退回) → 1(待审批)
|
||
type RefundRequest struct {
|
||
gorm.Model
|
||
BaseModel `gorm:"embedded"`
|
||
|
||
// 退款单基础信息
|
||
RefundNo string `gorm:"column:refund_no;type:varchar(50);uniqueIndex:idx_refund_request_refund_no,where:deleted_at IS NULL;not null;comment:退款单号（RF+日期时间+6位随机数）" json:"refund_no"`
|
||
OrderID uint `gorm:"column:order_id;index;not null;comment:关联订单ID" json:"order_id"`
|
||
OrderNo string `gorm:"column:order_no;type:varchar(30);not null;default:'';comment:关联订单号快照" json:"order_no"`
|
||
OrderType string `gorm:"column:order_type;type:varchar(20);not null;default:'';comment:订单类型快照（single_card/device）" json:"order_type,omitempty"`
|
||
AssetIdentifier string `gorm:"column:asset_identifier;type:varchar(100);not null;default:'';comment:下单时资产标识符快照（卡为ICCID，设备优先VirtualNo、其次IMEI）" json:"asset_identifier,omitempty"`
|
||
IotCardID *uint `gorm:"column:iot_card_id;comment:下单时IoT卡ID快照" json:"iot_card_id,omitempty"`
|
||
DeviceID *uint `gorm:"column:device_id;comment:下单时设备ID快照" json:"device_id,omitempty"`
|
||
PackageUsageID *uint `gorm:"column:package_usage_id;comment:关联套餐使用记录ID（可选）" json:"package_usage_id,omitempty"`
|
||
ShopID *uint `gorm:"column:shop_id;index;comment:店铺ID（从订单获取，用于数据权限过滤）" json:"shop_id,omitempty"`
|
||
ShopName string `gorm:"column:shop_name;->" json:"shop_name,omitempty"`
|
||
|
||
// 金额信息
|
||
ActualReceivedAmount int64 `gorm:"column:actual_received_amount;type:bigint;not null;comment:实收金额（分）" json:"actual_received_amount"`
|
||
RequestedRefundAmount int64 `gorm:"column:requested_refund_amount;type:bigint;not null;comment:申请退款金额（分）" json:"requested_refund_amount"`
|
||
ApprovedRefundAmount *int64 `gorm:"column:approved_refund_amount;type:bigint;comment:审批实际退款金额（分）" json:"approved_refund_amount,omitempty"`
|
||
|
||
// 退款凭证、原因和状态
|
||
RefundVoucherKey StringJSONBArray `gorm:"column:refund_voucher_key;type:jsonb;not null;comment:退款凭证对象存储file_key列表（jsonb存储[]string）" json:"refund_voucher_key"`
|
||
RefundReason string `gorm:"column:refund_reason;type:text;comment:退款原因" json:"refund_reason"`
|
||
Status int `gorm:"column:status;type:int;not null;default:1;index;comment:状态 1-待审批 2-已通过 3-已拒绝 4-已退回" json:"status"`
|
||
|
||
// 审批信息
|
||
ApprovalInstanceID *uint `gorm:"column:approval_instance_id;comment:关联的唯一通用审批实例ID" json:"approval_instance_id,omitempty"`
|
||
ProcessorID *uint `gorm:"column:processor_id;comment:审批人ID" json:"processor_id,omitempty"`
|
||
ProcessedAt *time.Time `gorm:"column:processed_at;comment:审批时间" json:"processed_at,omitempty"`
|
||
RejectReason string `gorm:"column:reject_reason;type:text;comment:拒绝原因" json:"reject_reason,omitempty"`
|
||
Remark string `gorm:"column:remark;type:text;comment:审批备注" json:"remark,omitempty"`
|
||
|
||
// 退款方式、冻结实收与当前材料快照
|
||
Method string `gorm:"column:method;type:varchar(20);not null;default:'';comment:退款方式，空表示未接入方式的存量申请" json:"method"`
|
||
FrozenActualReceivedAmount int64 `gorm:"column:frozen_actual_received_amount;type:bigint;not null;default:0;comment:冻结的权威实收金额（分）" json:"frozen_actual_received_amount"`
|
||
CustomerAccountInfo string `gorm:"column:customer_account_info;type:text;not null;default:'';comment:客户收款信息自由文本快照" json:"customer_account_info"`
|
||
|
||
// 结算标识：来源支付事实在创建或重提时冻结，线下处理流水号由财务补录（写审计），二者语义不同。
|
||
SourcePaymentNo string `gorm:"column:source_payment_no;type:varchar(64);not null;default:'';comment:冻结的来源支付单号，线下订单为空" json:"source_payment_no"`
|
||
OriginalChannelTradeNo string `gorm:"column:original_channel_trade_no;type:varchar(100);not null;default:'';comment:冻结的原支付渠道交易流水号（列宽与 tb_payment.third_party_trade_no 一致），线下订单为空" json:"original_channel_trade_no"`
|
||
OfflineSettlementNo string `gorm:"column:offline_settlement_no;type:varchar(128);not null;default:'';comment:线下退款处理流水号或凭证编号，由授权账号补录或更正" json:"offline_settlement_no"`
|
||
OfflineSettledAt *time.Time `gorm:"column:offline_settled_at;comment:线下退款处理流水号最近登记或更正时间" json:"offline_settled_at,omitempty"`
|
||
OfflineSettledBy uint `gorm:"column:offline_settled_by;not null;default:0;comment:线下退款处理流水号最近登记或更正的操作账号ID，0-未登记" json:"offline_settled_by"`
|
||
|
||
// 审批尝试引用，仅用于列表与详情展示
|
||
LatestAttemptID uint `gorm:"column:latest_attempt_id;type:bigint;not null;default:0;comment:最新审批尝试记录ID，仅用于展示" json:"latest_attempt_id"`
|
||
LatestApprovalInstanceID uint `gorm:"column:latest_approval_instance_id;type:bigint;not null;default:0;comment:最新通用审批实例ID，仅用于展示" json:"latest_approval_instance_id"`
|
||
|
||
// 渠道原路退款结果与结构化失败分类
|
||
ChannelRefundStatus int `gorm:"column:channel_refund_status;type:smallint;not null;default:0;comment:渠道退款状态 0-未发起或不适用 1-处理中 2-明确成功 3-明确失败" json:"channel_refund_status"`
|
||
ChannelRefundNo string `gorm:"column:channel_refund_no;type:varchar(64);not null;default:'';comment:渠道退款流水号" json:"channel_refund_no"`
|
||
ChannelRefundRequestNo string `gorm:"column:channel_refund_request_no;type:varchar(64);not null;default:'';comment:渠道退款请求号快照" json:"channel_refund_request_no"`
|
||
ChannelRefundAmount int64 `gorm:"column:channel_refund_amount;type:bigint;not null;default:0;comment:渠道退款金额快照（分）" json:"channel_refund_amount"`
|
||
ChannelRefundedAt *time.Time `gorm:"column:channel_refunded_at;comment:渠道明确退款成功时间" json:"channel_refunded_at,omitempty"`
|
||
// ChannelSubmittedAt 非空表示该尝试已向渠道提交过退款请求；重投只允许查询，不得再次提交。
|
||
ChannelSubmittedAt *time.Time `gorm:"column:channel_submitted_at;comment:渠道退款请求提交认领时间" json:"channel_submitted_at,omitempty"`
|
||
FailureReason string `gorm:"column:failure_reason;type:varchar(32);not null;default:'';comment:结构化失败分类稳定编码" json:"failure_reason"`
|
||
FailureMessage string `gorm:"column:failure_message;type:varchar(500);not null;default:'';comment:失败安全摘要" json:"failure_message"`
|
||
|
||
// 正交异常标记：企业微信通过后撤销、渠道结果永久未知等情况转人工处理
|
||
AnomalyFlag int `gorm:"column:anomaly_flag;type:smallint;not null;default:0;comment:异常标记 0-无异常 1-有异常" json:"anomaly_flag"`
|
||
AnomalyReason string `gorm:"column:anomaly_reason;type:varchar(500);not null;default:'';comment:异常原因" json:"anomaly_reason"`
|
||
|
||
// 后处理标记
|
||
CommissionDeducted bool `gorm:"column:commission_deducted;not null;default:false;comment:佣金是否已回扣" json:"commission_deducted"`
|
||
AssetReset bool `gorm:"column:asset_reset;not null;default:false;comment:退款后资产处理是否完成" json:"asset_reset"`
|
||
|
||
// 资产后处理重试状态（refactor-audit-log-persistence）
|
||
AssetPostStatus int `gorm:"column:asset_post_status;type:smallint;not null;default:0;comment:资产后处理状态 0-未开始 1-待重试 2-已完成 3-需人工处理" json:"asset_post_status"`
|
||
AssetPostAttempts int `gorm:"column:asset_post_attempts;type:int;not null;default:0;comment:资产后处理已尝试次数" json:"asset_post_attempts"`
|
||
AssetPostLastError string `gorm:"column:asset_post_last_error;type:varchar(500);not null;default:'';comment:资产后处理最后一次错误摘要" json:"asset_post_last_error"`
|
||
AssetPostNextAt *time.Time `gorm:"column:asset_post_next_at;comment:资产后处理下次自动重试时间" json:"asset_post_next_at,omitempty"`
|
||
}
|
||
|
||
// TableName 指定表名
|
||
func (RefundRequest) TableName() string {
|
||
return "tb_refund_request"
|
||
}
|
||
|
||
// RefundRequestAttempt 退款审批尝试记录。
|
||
// 每次提交或重提新增一条不可变记录，冻结当次方式、金额、冻结实收、原因、客户收款信息、
|
||
// 凭证与套餐使用快照；主键同时作为通用审批业务标识，使同一退款单每次提交持有独立审批实例。
|
||
type RefundRequestAttempt struct {
|
||
ID uint `gorm:"column:id;primaryKey;autoIncrement" json:"id"`
|
||
RefundID uint `gorm:"column:refund_id;not null;index" json:"refund_id"`
|
||
AttemptNo int `gorm:"column:attempt_no;type:int;not null" json:"attempt_no"`
|
||
Method string `gorm:"column:method;type:varchar(20);not null" json:"method"`
|
||
RefundAmount int64 `gorm:"column:refund_amount;type:bigint;not null" json:"refund_amount"`
|
||
FrozenActualReceivedAmount int64 `gorm:"column:frozen_actual_received_amount;type:bigint;not null" json:"frozen_actual_received_amount"`
|
||
RefundReason string `gorm:"column:refund_reason;type:text;not null;default:''" json:"refund_reason"`
|
||
// Remark 是本次提交的申请人备注，逐次冻结；与退款主表 remark（审批备注）语义不同，不得复用。
|
||
Remark string `gorm:"column:remark;type:text;not null;default:''" json:"remark"`
|
||
CustomerAccountInfo string `gorm:"column:customer_account_info;type:text;not null;default:''" json:"customer_account_info"`
|
||
CustomerVoucherKeys StringJSONBArray `gorm:"column:customer_voucher_keys;type:jsonb;not null" json:"customer_voucher_keys"`
|
||
PackageUsageSnapshot datatypes.JSON `gorm:"column:package_usage_snapshot;type:jsonb;not null" json:"package_usage_snapshot"`
|
||
ChannelRefundRequestNo string `gorm:"column:channel_refund_request_no;type:varchar(64);not null;default:''" json:"channel_refund_request_no"`
|
||
SubmittedByAccountID uint `gorm:"column:submitted_by_account_id;not null" json:"submitted_by_account_id"`
|
||
ApprovalInstanceID *uint `gorm:"column:approval_instance_id" json:"approval_instance_id,omitempty"`
|
||
CreatedAt time.Time `gorm:"column:created_at;type:timestamptz;not null;autoCreateTime" json:"created_at"`
|
||
}
|
||
|
||
// TableName 指定审批尝试记录表名。
|
||
func (RefundRequestAttempt) TableName() string {
|
||
return "tb_refund_request_attempt"
|
||
}
|
||
|
||
// 退款状态常量
|
||
const (
|
||
RefundStatusPending = 1 // 待审批
|
||
RefundStatusApproved = 2 // 已通过（退款已完成）
|
||
RefundStatusRejected = 3 // 已拒绝
|
||
RefundStatusReturned = 4 // 已退回
|
||
|
||
// RefundStatusChannelProcessing 表示企业微信已通过、原路渠道结果尚未确认。
|
||
RefundStatusChannelProcessing = 5
|
||
// RefundStatusChannelFailed 表示原路渠道明确失败或超时可恢复失败。
|
||
RefundStatusChannelFailed = 6
|
||
// RefundStatusSubmissionFailed 表示提交企业微信审批被明确拒绝，退款单终止且钱未动；可对原单重新发起或新建退款单。
|
||
RefundStatusSubmissionFailed = 7
|
||
)
|
||
|
||
// RefundActiveStatuses 返回会阻止同一订单创建新退款申请的状态集合。
|
||
// 该集合必须与迁移中 uk_refund_request_active_order 的谓词保持一致。
|
||
func RefundActiveStatuses() []int {
|
||
return []int{RefundStatusPending, RefundStatusChannelProcessing, RefundStatusChannelFailed}
|
||
}
|
||
|
||
// RefundResubmittableStatuses 返回允许修改材料并重提的状态集合。
|
||
func RefundResubmittableStatuses() []int {
|
||
return []int{RefundStatusRejected, RefundStatusReturned, RefundStatusChannelFailed, RefundStatusSubmissionFailed}
|
||
}
|
||
|
||
// 退款资产后处理状态。
|
||
const (
|
||
RefundAssetPostNotStarted = 0 // 未开始
|
||
RefundAssetPostRetryPending = 1 // 待重试
|
||
RefundAssetPostCompleted = 2 // 已完成
|
||
RefundAssetPostManualRequired = 3 // 需人工处理
|
||
)
|
||
|
||
// RefundPostProcessAttempt 退款资产后处理逐次尝试记录，只新增不修改。
|
||
type RefundPostProcessAttempt struct {
|
||
ID uint `gorm:"column:id;primaryKey;autoIncrement" json:"id"`
|
||
RefundID uint `gorm:"column:refund_id;not null" json:"refund_id"`
|
||
RefundNo string `gorm:"column:refund_no;type:varchar(64);not null;default:''" json:"refund_no"`
|
||
Step string `gorm:"column:step;type:varchar(32);not null" json:"step"`
|
||
AssetType string `gorm:"column:asset_type;type:varchar(16);not null;default:''" json:"asset_type"`
|
||
AssetID uint `gorm:"column:asset_id;not null;default:0" json:"asset_id"`
|
||
ICCID string `gorm:"column:iccid;type:varchar(30);not null;default:''" json:"iccid"`
|
||
Attempt int `gorm:"column:attempt;not null" json:"attempt"`
|
||
Trigger string `gorm:"column:trigger;type:varchar(16);not null" json:"trigger"`
|
||
Result string `gorm:"column:result;type:varchar(16);not null" json:"result"`
|
||
ErrorCode string `gorm:"column:error_code;type:varchar(32);not null;default:''" json:"error_code"`
|
||
ErrorMessage string `gorm:"column:error_message;type:varchar(500);not null;default:''" json:"error_message"`
|
||
DurationMS int `gorm:"column:duration_ms;not null;default:0" json:"duration_ms"`
|
||
CreatedAt time.Time `gorm:"column:created_at;type:timestamptz;not null;autoCreateTime" json:"created_at"`
|
||
}
|
||
|
||
// TableName 指定退款资产后处理尝试记录表名。
|
||
func (RefundPostProcessAttempt) TableName() string {
|
||
return "tb_refund_post_process_attempt"
|
||
}
|