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
配置启用场景与模板控件映射；未配置时相应提交失败关闭。

internal/service/shop_commission/service.go

@@ -7,6 +7,7 @@ import (
 	"math/rand"
 	"time"
 
+	"github.com/break/junhong_cmp_fiber/internal/application/distributionwithdrawal"
 	"github.com/break/junhong_cmp_fiber/internal/infrastructure/audit"
 	"github.com/break/junhong_cmp_fiber/internal/model"
 	"github.com/break/junhong_cmp_fiber/internal/model/dto"
@@ -30,6 +31,7 @@ type Service struct {
 	agentWalletTransactionStore      *postgres.AgentWalletTransactionStore
 	db                               *gorm.DB
 	auditWriter                      *audit.Writer
+	withdrawalApprovalService        *distributionwithdrawal.WithdrawalService
 	logger                           *zap.Logger
 }
 
@@ -38,6 +40,12 @@ func (s *Service) SetAuditWriter(writer *audit.Writer) {
 	s.auditWriter = writer
 }
 
+// SetWithdrawalApprovalService 注入接入企业微信终审的提现申请用例。
+// 未注入时发起提现失败关闭，避免绕过资料资格校验与审批实例创建。
+func (s *Service) SetWithdrawalApprovalService(service *distributionwithdrawal.WithdrawalService) {
+	s.withdrawalApprovalService = service
+}
+
 // New 创建代理商资金管理服务
 func New(
 	shopStore *postgres.ShopStore,
@@ -409,7 +417,12 @@ func (s *Service) GetDailyStats(ctx context.Context, shopID uint, req *dto.Daily
 
 // CreateWithdrawalRequest 代理发起提现申请
 // POST /shops/:id/withdrawal-requests
+// 先校验提现配置与本人代理身份，再在同一事务内校验有效提现资料资格、冻结余额、
+// 写审批尝试记录并创建企业微信审批实例。任何校验失败都不创建申请、审批实例或冻结。
 func (s *Service) CreateWithdrawalRequest(ctx context.Context, shopID uint, req *dto.CreateMyWithdrawalReq) (*dto.CreateMyWithdrawalResp, error) {
+	if s.withdrawalApprovalService == nil {
+		return nil, errors.New(errors.CodeServiceUnavailable, "提现审批能力尚未配置")
+	}
 	// 提现权限比查询更严格：必须是代理账号本人操作，不允许平台人员或顶级代理替下级提现
 	userType := middleware.GetUserTypeFromContext(ctx)
 	if userType != constants.UserTypeAgent {
@@ -418,130 +431,86 @@ func (s *Service) CreateWithdrawalRequest(ctx context.Context, shopID uint, req
 	if shopID != middleware.GetShopIDFromContext(ctx) {
 		return nil, errors.New(errors.CodeForbidden, "仅可为本人店铺发起提现")
 	}
-
-	currentUserID := middleware.GetUserIDFromContext(ctx)
-	if currentUserID == 0 {
-		return nil, errors.New(errors.CodeForbidden, "无法获取用户信息")
-	}
-
-	// 获取提现配置
-	setting, err := s.commissionWithdrawalSettingStore.GetCurrent(ctx)
+	policy, err := s.currentWithdrawalPolicy(ctx)
 	if err != nil {
-		return nil, errors.New(errors.CodeInvalidParam, "暂未开放提现功能")
-	}
-
-	// 验证最低提现金额
-	if req.Amount < setting.MinWithdrawalAmount {
-		return nil, errors.New(errors.CodeInvalidParam, fmt.Sprintf("提现金额不能低于 %.2f 元", float64(setting.MinWithdrawalAmount)/100))
-	}
-
-	// 获取佣金钱包
-	wallet, err := s.agentWalletStore.GetCommissionWallet(ctx, shopID)
-	if err != nil {
-		return nil, errors.New(errors.CodeInsufficientBalance, "钱包不存在")
-	}
-
-	// 验证可用余额
-	if req.Amount > wallet.GetAvailableBalance() {
-		return nil, errors.New(errors.CodeInsufficientBalance, "可提现余额不足")
-	}
-
-	// 验证今日提现次数
-	today := time.Now().Format("2006-01-02")
-	var todayCount int64
-	s.db.WithContext(ctx).Model(&model.CommissionWithdrawalRequest{}).
-		Where("shop_id = ? AND created_at >= ? AND created_at <= ?", shopID, today+" 00:00:00", today+" 23:59:59").
-		Count(&todayCount)
-	if int(todayCount) >= setting.DailyWithdrawalLimit {
-		return nil, errors.New(errors.CodeInvalidParam, "今日提现次数已达上限")
-	}
-
-	// 计算手续费
-	fee := req.Amount * setting.FeeRate / 10000
-	actualAmount := req.Amount - fee
-	withdrawalNo := generateWithdrawalNo()
-
-	accountInfo := map[string]string{
-		"account_name":   req.AccountName,
-		"account_number": req.AccountNumber,
-	}
-	accountInfoJSON, _ := json.Marshal(accountInfo)
-
-	withdrawalRequest := &model.CommissionWithdrawalRequest{
-		WithdrawalNo:     withdrawalNo,
-		ShopID:           shopID,
-		ApplicantID:      currentUserID,
-		Amount:           req.Amount,
-		FeeRate:          setting.FeeRate,
-		Fee:              fee,
-		ActualAmount:     actualAmount,
-		WithdrawalMethod: req.WithdrawalMethod,
-		AccountInfo:      accountInfoJSON,
-		Status:           constants.WithdrawalStatusPending,
-	}
-	withdrawalRequest.Creator = currentUserID
-	withdrawalRequest.Updater = currentUserID
-
-	err = s.db.Transaction(func(tx *gorm.DB) error {
-		// 使用条件更新防并发
-		result := tx.WithContext(ctx).Model(&model.AgentWallet{}).
-			Where("id = ? AND balance - frozen_balance >= ?", wallet.ID, req.Amount).
-			Updates(map[string]interface{}{
-				"frozen_balance": gorm.Expr("frozen_balance + ?", req.Amount),
-			})
-		if result.Error != nil {
-			return errors.Wrap(errors.CodeInternalError, result.Error, "冻结余额失败")
-		}
-		if result.RowsAffected == 0 {
-			return errors.New(errors.CodeInsufficientBalance, "余额不足或并发冲突，请稍后重试")
-		}
-
-		if err := tx.WithContext(ctx).Create(withdrawalRequest).Error; err != nil {
-			return errors.Wrap(errors.CodeInternalError, err, "创建提现申请失败")
-		}
-
-		remark := fmt.Sprintf("提现冻结，单号：%s", withdrawalNo)
-		refType := constants.ReferenceTypeWithdrawal
-		transaction := &model.AgentWalletTransaction{
-			AgentWalletID:   wallet.ID,
-			ShopID:          shopID,
-			UserID:          currentUserID,
-			TransactionType: constants.AgentTransactionTypeWithdrawal,
-			Amount:          -req.Amount,
-			BalanceBefore:   wallet.Balance,
-			BalanceAfter:    wallet.Balance - req.Amount,
-			Status:          constants.TransactionStatusProcessing,
-			ReferenceType:   &refType,
-			ReferenceID:     &withdrawalRequest.ID,
-			Remark:          &remark,
-			Creator:         currentUserID,
-			ShopIDTag:       shopID,
-		}
-
-		if err := tx.WithContext(ctx).Create(transaction).Error; err != nil {
-			return errors.Wrap(errors.CodeInternalError, err, "创建钱包流水失败")
-		}
-
-		return s.appendWithdrawalRequestAudit(ctx, tx, withdrawalRequest, wallet, transaction)
-	})
-	if err != nil {
-		s.recordWithdrawalRequestFailure(ctx, withdrawalRequest, wallet, err)
 		return nil, err
 	}
+	result, err := s.withdrawalApprovalService.Create(ctx, shopID, policy, distributionwithdrawal.WithdrawalInput{
+		Amount:           req.Amount,
+		WithdrawalMethod: req.WithdrawalMethod,
+		AccountName:      req.AccountName,
+		AccountNumber:    req.AccountNumber,
+	})
+	if err != nil {
+		return nil, err
+	}
+	return withdrawalApprovalResp(result), nil
+}
 
-	return &dto.CreateMyWithdrawalResp{
-		ID:           withdrawalRequest.ID,
-		WithdrawalNo: withdrawalRequest.WithdrawalNo,
-		Amount:       withdrawalRequest.Amount,
-		FeeRate:      withdrawalRequest.FeeRate,
-		Fee:          withdrawalRequest.Fee,
-		ActualAmount: withdrawalRequest.ActualAmount,
-		Status:       withdrawalRequest.Status,
-		StatusName:   constants.GetWithdrawalStatusName(withdrawalRequest.Status),
-		CreatedAt:    withdrawalRequest.CreatedAt.Format("2006-01-02 15:04:05"),
+// ResubmitWithdrawalRequest 代理修改金额、收款信息与本次发票后重提已被驳回的提现申请
+// PUT /shops/:shop_id/withdrawal-requests/:id
+// 事务内先释放旧未结算尝试的冻结，再按新金额冻结；历史尝试与审批结果不被覆盖。
+func (s *Service) ResubmitWithdrawalRequest(ctx context.Context, shopID uint, requestID uint, req *dto.ResubmitWithdrawalReq) (*dto.CreateMyWithdrawalResp, error) {
+	if s.withdrawalApprovalService == nil {
+		return nil, errors.New(errors.CodeServiceUnavailable, "提现审批能力尚未配置")
+	}
+	userType := middleware.GetUserTypeFromContext(ctx)
+	if userType != constants.UserTypeAgent {
+		return nil, errors.New(errors.CodeForbidden, "仅代理商用户可重提提现")
+	}
+	if shopID == 0 || shopID != middleware.GetShopIDFromContext(ctx) {
+		return nil, errors.New(errors.CodeForbidden, "仅可为本人店铺重提提现")
+	}
+	// 先复核申请属于该店铺，越权与不存在返回同一结果。
+	existing, err := s.commissionWithdrawalReqStore.GetByID(ctx, requestID)
+	if err != nil || existing == nil || existing.ShopID != shopID {
+		return nil, errors.New(errors.CodeNotFound, "提现申请不存在")
+	}
+	policy, err := s.currentWithdrawalPolicy(ctx)
+	if err != nil {
+		return nil, err
+	}
+	result, err := s.withdrawalApprovalService.Resubmit(ctx, requestID, policy, distributionwithdrawal.WithdrawalInput{
+		Amount:           req.Amount,
+		WithdrawalMethod: req.WithdrawalMethod,
+		AccountName:      req.AccountName,
+		AccountNumber:    req.AccountNumber,
+		InvoiceKeys:      req.InvoiceKeys,
+	})
+	if err != nil {
+		return nil, err
+	}
+	return withdrawalApprovalResp(result), nil
+}
+
+// currentWithdrawalPolicy 读取当前提现配置为调用方策略快照，未开放提现时返回稳定错误。
+func (s *Service) currentWithdrawalPolicy(ctx context.Context) (distributionwithdrawal.WithdrawalPolicy, error) {
+	setting, err := s.commissionWithdrawalSettingStore.GetCurrent(ctx)
+	if err != nil {
+		return distributionwithdrawal.WithdrawalPolicy{}, errors.New(errors.CodeInvalidParam, "暂未开放提现功能")
+	}
+	return distributionwithdrawal.WithdrawalPolicy{
+		MinAmount:            setting.MinWithdrawalAmount,
+		FeeRate:              setting.FeeRate,
+		DailyWithdrawalLimit: setting.DailyWithdrawalLimit,
 	}, nil
 }
 
+// withdrawalApprovalResp 把提现用例结果映射为发起提现响应。
+func withdrawalApprovalResp(result *distributionwithdrawal.WithdrawalResult) *dto.CreateMyWithdrawalResp {
+	return &dto.CreateMyWithdrawalResp{
+		ID:           result.RequestID,
+		WithdrawalNo: result.WithdrawalNo,
+		Amount:       result.Amount,
+		FeeRate:      result.FeeRate,
+		Fee:          result.Fee,
+		ActualAmount: result.ActualAmount,
+		Status:       result.Status,
+		StatusName:   constants.GetWithdrawalStatusName(result.Status),
+		CreatedAt:    result.CreatedAt.Format("2006-01-02 15:04:05"),
+	}
+}
+
 // ListMainWalletTransactions 查询代理主钱包（预充值钱包）流水
 // GET /shops/:id/main-wallet/transactions
 func (s *Service) ListMainWalletTransactions(ctx context.Context, shopID uint, req *dto.MainWalletTransactionListRequest) (*dto.MainWalletTransactionListResponse, error) {