feat(代理分销提现): 落地扫码注册、提现资料资格与企微终审提现

AUG26-008。 - 迁移 000214–000217：tb_shop 全局唯一且不可修改的随机分销码（含存量回填）、 tb_agent_distribution_registration 待审批注册记录、tb_withdrawal_qualification 资料版本、 tb_commission_withdrawal_request_attempt 审批尝试记录，以及提现申请的 latest_*/异常标记列；不修改既有迁移，down 在存在本 Change 业务事实或新类型场景行时拒绝破坏性回滚。 - 公开接口 POST /api/c/v1/agent-distribution-registrations：无认证，复用既有短信验证码校验、消费与限流；无效分销码、停用上级、验证码无效或已消费统一返回「分销码不可用」且不落库，审批通过前不创建店铺、账号或钱包。 - 审批通过才在同一事务内建启用店铺、代理主账号、钱包、上级层级与业务员快照，驳回不建实体，重复回调不重复建实体，提交后清理上级下级缓存。 - 提现资料资格按不可变版本保存，替换合同或法人身份证即新增版本并同事务失效旧有效版本；超管作废原因必填；代理停用与店铺删除联动失效。 - 提现每次提交或重提新增不可变审批尝试记录并冻结金额；企业微信通过仅一次从冻结扣减、保持状态 2 并写 paid_at（不使用状态 4），驳回/cancelled/deleted 仅一次释放，通过后撤销不回滚、不重新冻结、只写正交异常标记；加锁顺序统一为申请→尝试→钱包。 - 本地人工终审对已关联审批实例的申请返回状态冲突，approval_instance_id 为空的存量申请保持既有行为，不新增任何配置开关。 - 补齐审批业务类型注册点全集：业务类型与场景字段常量、场景 DTO 两处枚举与中文描述、场景字段白名单/合法类型/中文名、数据库 CHECK、Worker 决策消费者与装配、审批审计资源映射，以及三个新审计资源与 13 个审计动作；失败/拒绝审计改为必达。 - 新增后台路由与 OpenAPI：资格提交/查询/作废、提现申请/重提/详情、店铺详情返回只读分销码。 - 归档本 Change：主 Spec 新增 agent-distribution-withdrawal 能力（5 个 Requirement）。验证（junhong_cmp_test + Redis DB 6，显式 DB_*，未重置整库）： - 迁移 up → version 217 且 dirty=false → down 3 → up 回 217，fixture 复核残留为 0。 - 受控状态机脚手架 227 项通过 / 0 项失败，覆盖 18 组场景（幂等与乱序回调、资金冻结/释放/重提、退款回扣 × 在途提现并发、负向场景拒绝审计与 14 个动作码审计真实落库）。 - gofmt 空、go build/go vet 通过、gendocs 与工作区逐字节一致、context-health 通过、 openspec validate --strict 通过、doctor healthy；自动化测试按项目决策为 N/A。运行期前置（未完成，非代码交付物）：由超管经 PUT /api/admin/wecom/scenes/{business_type} 为 agent_distribution_approval、withdrawal_qualification_approval、commission_withdrawal_approval 配置启用场景与模板控件映射；未配置时相应提交失败关闭。
2026-09-14 09:45:13 +08:00
parent 315a7de3e4
commit 575d056f54
68 changed files with 5759 additions and 309 deletions
--- a/internal/application/distributionwithdrawal/withdrawal_approval.go
+++ b/internal/application/distributionwithdrawal/withdrawal_approval.go
@@ -0,0 +1,365 @@
+package distributionwithdrawal
+
+import (
+	"context"
+	"time"
+
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	approvalapp "github.com/break/junhong_cmp_fiber/internal/application/approval"
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/pkg/auditcontext"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+)
+
+// WithdrawalApprovalHandler 将渠道无关企业微信终态应用到提现申请。
+// 通过时仅一次从冻结余额扣减并保持 WithdrawalStatusApproved=2，同时写入到账时间；
+// 驳回、撤销与删除仅一次释放本次尝试的冻结余额并记录释放时间；
+// 通过后撤销不回滚、不重新冻结、不自动重提，只写入正交异常标记与原因。
+type WithdrawalApprovalHandler struct {
+	db    *gorm.DB
+	audit AuditWriter
+}
+
+// NewWithdrawalApprovalHandler 创建佣金提现审批终态消费者。
+func NewWithdrawalApprovalHandler(db *gorm.DB, audit AuditWriter) *WithdrawalApprovalHandler {
+	return &WithdrawalApprovalHandler{db: db, audit: audit}
+}
+
+// Handle 幂等消费标准审批终态。
+// 业务标识为提现审批尝试记录主键；先锁定尝试记录并校验审批实例一致，再按条件更新推进状态。
+func (h *WithdrawalApprovalHandler) Handle(ctx context.Context, event approvalapp.TerminalDecisionEvent) error {
+	if h == nil || h.db == nil || h.audit == nil {
+		return errors.New(errors.CodeInternalError, "佣金提现审批终态能力未配置")
+	}
+	if event.BusinessType != constants.ApprovalBusinessTypeCommissionWithdrawal ||
+		event.BusinessID == 0 || event.InstanceID == 0 {
+		return errors.New(errors.CodeInvalidParam, "佣金提现审批终态参数无效")
+	}
+	ctx = auditcontext.With(ctx, auditcontext.Context{
+		CorrelationID: event.CorrelationID, ParentEventID: event.EventID,
+	})
+	return h.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		// 全库统一加锁顺序：申请行 → 尝试行 → 钱包行（钱包永远最后）。
+		// 因此先用不加锁读取得 request_id，再按序加锁，避免与退款回扣路径形成死锁环。
+		var lookup model.CommissionWithdrawalRequestAttempt
+		if err := tx.WithContext(ctx).Select("id", "request_id").
+			First(&lookup, event.BusinessID).Error; err != nil {
+			if err == gorm.ErrRecordNotFound {
+				return errors.New(errors.CodeNotFound, "提现审批尝试记录不存在")
+			}
+			return errors.Wrap(errors.CodeDatabaseError, err, "查询提现审批尝试记录失败")
+		}
+		request, err := lockWithdrawalRequest(ctx, tx, lookup.RequestID)
+		if err != nil {
+			return err
+		}
+		var attempt model.CommissionWithdrawalRequestAttempt
+		if err := tx.WithContext(ctx).Clauses(clause.Locking{Strength: "UPDATE"}).
+			First(&attempt, event.BusinessID).Error; err != nil {
+			if err == gorm.ErrRecordNotFound {
+				return errors.New(errors.CodeNotFound, "提现审批尝试记录不存在")
+			}
+			return errors.Wrap(errors.CodeDatabaseError, err, "锁定提现审批尝试记录失败")
+		}
+		if attempt.ApprovalInstanceID == nil || *attempt.ApprovalInstanceID != event.InstanceID {
+			return errors.New(errors.CodeConflict, "提现审批尝试记录关联的审批实例不一致")
+		}
+		if attempt.RequestID != request.ID {
+			return errors.New(errors.CodeConflict, "提现审批尝试记录归属已变化")
+		}
+		if request.LatestAttemptID != attempt.ID {
+			// 已被更新尝试取代的历史尝试终态不再改变申请事实。
+			return nil
+		}
+		switch event.Decision {
+		case constants.ApprovalDecisionApproved:
+			return h.applyApproved(ctx, tx, request, &attempt, event)
+		case constants.ApprovalDecisionRejected,
+			constants.ApprovalDecisionCancelled,
+			constants.ApprovalDecisionDeleted:
+			return h.applyClosed(ctx, tx, request, &attempt, event)
+		case constants.ApprovalDecisionRevokedAfterApproved:
+			return h.applyRevoked(ctx, tx, request, &attempt, event)
+		default:
+			return errors.New(errors.CodeInvalidParam, "不支持的提现申请审批终态")
+		}
+	})
+}
+
+// applyApproved 仅一次从冻结余额扣减，保持已通过状态并写入到账时间。
+// 幂等守卫为「申请仍待审核 + paid_at 为空 + 尝试未释放」的条件更新且影响行数为 1。
+func (h *WithdrawalApprovalHandler) applyApproved(
+	ctx context.Context,
+	tx *gorm.DB,
+	request *model.CommissionWithdrawalRequest,
+	attempt *model.CommissionWithdrawalRequestAttempt,
+	event approvalapp.TerminalDecisionEvent,
+) error {
+	wallet, err := lockCommissionWallet(ctx, tx, request.ShopID)
+	if err != nil {
+		return err
+	}
+	now := time.Now().UTC()
+	if attempt.ReleasedAt != nil {
+		// 已结算的尝试不再扣减，避免重复扣款。
+		return nil
+	}
+	if wallet.FrozenBalance < attempt.Amount {
+		return errors.New(errors.CodeConflict, "冻结余额不足以完成提现扣减，请人工核对")
+	}
+	// 通过即视为已到账：先以 released_at IS NULL 条件更新标记本次冻结已结算，保证重复回调不重复扣减。
+	settled, err := markAttemptReleased(ctx, tx, attempt, now)
+	if err != nil {
+		return err
+	}
+	if !settled {
+		return nil
+	}
+	// 通过时保持状态 2 并写入到账时间，禁止使用已到账状态值 4。
+	result := tx.WithContext(ctx).Model(&model.CommissionWithdrawalRequest{}).
+		Where("id = ? AND status = ? AND paid_at IS NULL", request.ID, constants.WithdrawalStatusPending).
+		Updates(map[string]any{
+			"status":       constants.WithdrawalStatusApproved,
+			"paid_at":      now,
+			"processed_at": now,
+			"updater":      0,
+		})
+	if result.Error != nil {
+		return errors.Wrap(errors.CodeDatabaseError, result.Error, "标记提现申请已通过失败")
+	}
+	if result.RowsAffected != 1 {
+		return errors.New(errors.CodeConflict, "提现申请状态已变化")
+	}
+	if err := deductFrozenBalance(ctx, tx, wallet, attempt.Amount); err != nil {
+		return err
+	}
+	transaction, err := recordWithdrawalDeductTransaction(ctx, tx, wallet, request, attempt)
+	if err != nil {
+		return err
+	}
+	attempt.ReleasedAt = &now
+	before := map[string]any{"status": constants.WithdrawalStatusPending, "paid_at": nil, "frozen_balance": wallet.FrozenBalance + attempt.Amount}
+	request.Status = constants.WithdrawalStatusApproved
+	request.PaidAt = &now
+	request.ProcessedAt = &now
+	return h.audit.WriteDistributionWithdrawal(ctx, tx, AuditChange{
+		EventID:       "commission-withdrawal:" + uintText(request.ID) + ":attempt:" + intText(attempt.AttemptNo) + ":approved",
+		ActionCode:    constants.AuditActionCommissionWithdrawalAttemptApproved,
+		Summary:       "企业微信通过佣金提现，已从冻结余额扣减并记录到账时间",
+		CorrelationID: event.CorrelationID, Withdrawal: request, Attempt: attempt,
+		Wallet: wallet, Transaction: transaction,
+		BeforeData: before, AfterData: withdrawalAuditSnapshot(request, attempt, wallet),
+	})
+}
+
+// applyClosed 处理最终驳回、撤销与删除：仅一次释放本次尝试冻结并记录释放时间。
+// 幂等守卫为「尝试已结算时间仍为空」的条件更新且影响行数为 1。
+func (h *WithdrawalApprovalHandler) applyClosed(
+	ctx context.Context,
+	tx *gorm.DB,
+	request *model.CommissionWithdrawalRequest,
+	attempt *model.CommissionWithdrawalRequestAttempt,
+	event approvalapp.TerminalDecisionEvent,
+) error {
+	if attempt.ReleasedAt != nil {
+		return nil
+	}
+	wallet, err := lockCommissionWallet(ctx, tx, request.ShopID)
+	if err != nil {
+		return err
+	}
+	now := time.Now().UTC()
+	released, err := markAttemptReleased(ctx, tx, attempt, now)
+	if err != nil {
+		return err
+	}
+	if !released {
+		return nil
+	}
+	ok, err := releaseCommissionBalance(ctx, tx, wallet.ID, attempt.Amount)
+	if err != nil {
+		return err
+	}
+	if !ok {
+		return errors.New(errors.CodeConflict, "提现冻结余额与尝试记录不一致，请人工核对")
+	}
+	reason := rejectionReason(event.Decision)
+	result := tx.WithContext(ctx).Model(&model.CommissionWithdrawalRequest{}).
+		Where("id = ? AND status = ?", request.ID, constants.WithdrawalStatusPending).
+		Updates(map[string]any{
+			"status":        constants.WithdrawalStatusRejected,
+			"processed_at":  now,
+			"reject_reason": reason,
+			"updater":       0,
+		})
+	if result.Error != nil {
+		return errors.Wrap(errors.CodeDatabaseError, result.Error, "标记提现申请已驳回失败")
+	}
+	if result.RowsAffected != 1 {
+		return errors.New(errors.CodeConflict, "提现申请状态已变化")
+	}
+	frozenBefore := wallet.FrozenBalance + attempt.Amount
+	wallet.FrozenBalance = frozenBefore - attempt.Amount
+	transaction, err := recordWithdrawalReleaseTransaction(ctx, tx, wallet, request, attempt, frozenBefore)
+	if err != nil {
+		return err
+	}
+	attempt.ReleasedAt = &now
+	before := map[string]any{"status": constants.WithdrawalStatusPending, "frozen_balance": frozenBefore}
+	request.Status = constants.WithdrawalStatusRejected
+	request.ProcessedAt = &now
+	request.RejectReason = reason
+	return h.audit.WriteDistributionWithdrawal(ctx, tx, AuditChange{
+		EventID:       "commission-withdrawal:" + uintText(request.ID) + ":attempt:" + intText(attempt.AttemptNo) + ":closed",
+		ActionCode:    constants.AuditActionCommissionWithdrawalAttemptClosed,
+		Summary:       "企业微信未通过佣金提现，已释放本次尝试冻结余额",
+		CorrelationID: event.CorrelationID, Withdrawal: request, Attempt: attempt,
+		Wallet: wallet, Transaction: transaction,
+		BeforeData: before, AfterData: withdrawalAuditSnapshot(request, attempt, wallet),
+	})
+}
+
+// applyRevoked 处理通过后撤销。
+// 已通过：不回滚已到账金额、不重新冻结、不自动重提，只写正交异常标记与原因。
+// 仍在待审核（渠道乱序投递）：按驳回同等处理，释放本次尝试冻结并转驳回状态。
+func (h *WithdrawalApprovalHandler) applyRevoked(
+	ctx context.Context,
+	tx *gorm.DB,
+	request *model.CommissionWithdrawalRequest,
+	attempt *model.CommissionWithdrawalRequestAttempt,
+	event approvalapp.TerminalDecisionEvent,
+) error {
+	if request.Status == constants.WithdrawalStatusPending {
+		return h.applyClosed(ctx, tx, request, attempt, event)
+	}
+	if request.Status != constants.WithdrawalStatusApproved {
+		// 已驳回等终态不再改变事实。
+		return nil
+	}
+	if request.AnomalyFlag == constants.WithdrawalAnomalyFlagRevokedAfterApproved {
+		return nil
+	}
+	now := time.Now().UTC()
+	reason := "企业微信通过后撤销：" + rejectionReason(event.Decision)
+	result := tx.WithContext(ctx).Model(&model.CommissionWithdrawalRequest{}).
+		Where("id = ? AND status = ? AND anomaly_flag = ?",
+			request.ID, constants.WithdrawalStatusApproved, constants.WithdrawalAnomalyFlagNone).
+		Updates(map[string]any{
+			"anomaly_flag":   constants.WithdrawalAnomalyFlagRevokedAfterApproved,
+			"anomaly_reason": reason, "updater": 0,
+		})
+	if result.Error != nil {
+		return errors.Wrap(errors.CodeDatabaseError, result.Error, "写入提现异常标记失败")
+	}
+	if result.RowsAffected != 1 {
+		return errors.New(errors.CodeConflict, "提现申请异常标记已变化")
+	}
+	before := map[string]any{
+		"status": request.Status, "anomaly_flag": constants.WithdrawalAnomalyFlagNone,
+		"paid_at": request.PaidAt, "amount": attempt.Amount,
+	}
+	request.AnomalyFlag = constants.WithdrawalAnomalyFlagRevokedAfterApproved
+	request.AnomalyReason = reason
+	request.UpdatedAt = now
+	return h.audit.WriteDistributionWithdrawal(ctx, tx, AuditChange{
+		EventID:       "commission-withdrawal:" + uintText(request.ID) + ":attempt:" + intText(attempt.AttemptNo) + ":anomaly",
+		ActionCode:    constants.AuditActionCommissionWithdrawalAnomalyFlagged,
+		Summary:       "企业微信通过后撤销，已到账金额不回滚、不重新冻结，仅写入异常标记",
+		CorrelationID: event.CorrelationID, Withdrawal: request, Attempt: attempt,
+		BeforeData: before, AfterData: withdrawalAuditSnapshot(request, attempt, nil),
+	})
+}
+
+// markAttemptReleased 以未释放条件更新写入尝试释放时间，返回是否本次完成释放。
+func markAttemptReleased(
+	ctx context.Context,
+	tx *gorm.DB,
+	attempt *model.CommissionWithdrawalRequestAttempt,
+	now time.Time,
+) (bool, error) {
+	result := tx.WithContext(ctx).Model(&model.CommissionWithdrawalRequestAttempt{}).
+		Where("id = ? AND released_at IS NULL", attempt.ID).
+		Update("released_at", now)
+	if result.Error != nil {
+		return false, errors.Wrap(errors.CodeDatabaseError, result.Error, "写入提现尝试释放时间失败")
+	}
+	return result.RowsAffected == 1, nil
+}
+
+// deductFrozenBalance 以冻结余额充足条件更新同时扣减余额与冻结余额。
+func deductFrozenBalance(ctx context.Context, tx *gorm.DB, wallet *model.AgentWallet, amount int64) error {
+	result := tx.WithContext(ctx).Model(&model.AgentWallet{}).
+		Where("id = ? AND wallet_type = ? AND frozen_balance >= ?",
+			wallet.ID, constants.AgentWalletTypeCommission, amount).
+		Updates(map[string]any{
+			"balance":        gorm.Expr("balance - ?", amount),
+			"frozen_balance": gorm.Expr("frozen_balance - ?", amount),
+			"updated_at":     time.Now(),
+		})
+	if result.Error != nil {
+		return errors.Wrap(errors.CodeDatabaseError, result.Error, "从冻结余额扣减提现金额失败")
+	}
+	if result.RowsAffected != 1 {
+		return errors.New(errors.CodeConflict, "冻结余额不足或已被并发处理")
+	}
+	wallet.Balance -= amount
+	wallet.FrozenBalance -= amount
+	return nil
+}
+
+// recordWithdrawalDeductTransaction 写入通过时的钱包流水，余额与冻结余额同时减少。
+func recordWithdrawalDeductTransaction(
+	ctx context.Context,
+	tx *gorm.DB,
+	wallet *model.AgentWallet,
+	request *model.CommissionWithdrawalRequest,
+	attempt *model.CommissionWithdrawalRequestAttempt,
+) (*model.AgentWalletTransaction, error) {
+	remark := "企业微信终审通过，提现到账，单号：" + request.WithdrawalNo
+	refType := constants.ReferenceTypeWithdrawal
+	refID := request.ID
+	transaction := &model.AgentWalletTransaction{
+		AgentWalletID: wallet.ID, ShopID: request.ShopID, UserID: request.ApplicantID,
+		TransactionType: constants.AgentTransactionTypeWithdrawal,
+		Amount:          -attempt.Amount,
+		BalanceBefore:   wallet.Balance + attempt.Amount, BalanceAfter: wallet.Balance,
+		Status:        constants.TransactionStatusSuccess,
+		ReferenceType: &refType, ReferenceID: &refID, Remark: &remark,
+		Creator: request.ApplicantID, ShopIDTag: request.ShopID,
+	}
+	if err := tx.WithContext(ctx).Create(transaction).Error; err != nil {
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "创建提现到账钱包流水失败")
+	}
+	return transaction, nil
+}
+
+// recordWithdrawalReleaseTransaction 写入驳回时的钱包流水，仅冻结余额减少。
+func recordWithdrawalReleaseTransaction(
+	ctx context.Context,
+	tx *gorm.DB,
+	wallet *model.AgentWallet,
+	request *model.CommissionWithdrawalRequest,
+	attempt *model.CommissionWithdrawalRequestAttempt,
+	frozenBefore int64,
+) (*model.AgentWalletTransaction, error) {
+	remark := "企业微信未通过，释放提现冻结，单号：" + request.WithdrawalNo
+	refType := constants.ReferenceTypeWithdrawal
+	refID := request.ID
+	transaction := &model.AgentWalletTransaction{
+		AgentWalletID: wallet.ID, ShopID: request.ShopID, UserID: request.ApplicantID,
+		TransactionType: constants.AgentTransactionTypeRefund,
+		Amount:          attempt.Amount,
+		BalanceBefore:   wallet.Balance, BalanceAfter: wallet.Balance,
+		Status:        constants.TransactionStatusSuccess,
+		ReferenceType: &refType, ReferenceID: &refID, Remark: &remark,
+		Creator: request.ApplicantID, ShopIDTag: request.ShopID,
+	}
+	if err := tx.WithContext(ctx).Create(transaction).Error; err != nil {
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "创建提现释放钱包流水失败")
+	}
+	_ = frozenBefore
+	return transaction, nil
+}