판례(Case Law)로 예외 처리 설계하기 — CanonCode에서 배운 패턴

rescue InsufficientBalanceError
  render json: { error: "포인트 충전이 필요합니다" }, status: 422
end

{
  "id": "CASE-001",
  "situation": "잔액 부족 상태에서 point 타입 공고 생성 시도",
  "ruling": "422 에러 반환. 공고 생성을 롤백하고 '포인트 충전이 필요합니다' 메시지를 표시한다.",
  "rationale": "500은 서버 오류를 의미하므로 부적절. 잔액 부족은 클라이언트가 해결할 수 있는 상황이므로 422(Unprocessable Entity)가 적합하다.",
  "references": ["CL-001-2", "CONST-001"]
}

{
  "id": "CASE-001",
  "situation": "잔액 부족 상태에서 point 타입 공고 생성 시도",
  "ruling": "422 반환. 공고 생성 롤백. '포인트 충전이 필요합니다' 메시지.",
  "rationale": "클라이언트 해결 가능 → 422. 서버 오류가 아님.",
  "references": ["CL-001-2", "CONST-001"]
}

rescue InsufficientBalanceError
  render json: { error: "포인트 충전이 필요합니다" }, status: 422
end

{
  "id": "CASE-002",
  "situation": "테스팅 진행 중 테스터가 중도 포기 선언",
  "ruling": "해당 테스터의 에스크로 포인트만 개발자에게 반환. 다른 테스터의 진행에 영향 없음.",
  "rationale": "전체 프로젝트를 중단하면 다른 테스터에게 피해. 부분 반환으로 개발자 손해 최소화.",
  "references": ["ACT-003", "CL-005-3"]
}

class QaApplications::WithdrawService
  def call(application)
    ActiveRecord::Base.transaction do
      application.update!(status: :withdrawn)

      # 해당 테스터 에스크로만 반환
      escrow_amount = application.qa_post.points_per_person
      developer_wallet = application.qa_post.user.wallet.lock!
      developer_wallet.update!(
        balance: developer_wallet.balance + escrow_amount,
        escrowed: developer_wallet.escrowed - escrow_amount
      )

      WalletTransaction.create!(
        wallet: developer_wallet,
        transaction_type: :escrow_refund,
        amount: escrow_amount,
        reference: application,
        note: "테스터 중도 포기로 인한 부분 환불"
      )

      # 다른 테스터는 영향 없음 — 아무것도 하지 않음
    end
  end
end

{
  "id": "CASE-003",
  "situation": "테스터가 일일 증빙 제출 기한(23:59)을 초과",
  "ruling": "해당 일자는 미제출로 기록. 누적 3회 미제출 시 자동 탈락 경고. 5회 시 강제 탈락.",
  "rationale": "1회 초과는 실수일 수 있으므로 즉시 탈락은 가혹. 단 반복 시 프로젝트 품질 보호를 위해 단계적 제재.",
  "references": ["ACT-004", "CL-004-1"]
}

{
  "id": "CASE-004",
  "situation": "개발자가 정당한 증빙을 반복적으로 거절하여 테스터가 이의 제기",
  "ruling": "운영팀 중재 프로세스 진입. 중재 기간 동안 에스크로 동결. 운영팀 판단에 따라 강제 승인 또는 분쟁 종결.",
  "rationale": "자동화로 해결할 수 없는 주관적 분쟁. 인간 판단이 필요한 영역.",
  "references": ["CONST-003", "ACT-005"]
}

class DisputeService
  def create_dispute(application, reason)
    Dispute.create!(
      qa_application: application,
      reporter: application.user,
      reason: reason,
      status: :pending_mediation  # 운영팀 대기
    )

    # 에스크로 동결 플래그
    application.qa_post.update!(escrow_frozen: true)

    # 운영팀 알림
    AdminNotificationJob.perform_later(:dispute_created, application.id)
  end
end

{
  "id": "CASE-005",
  "situation": "모집 인원 마감 직전 복수의 지원 동시 도달",
  "ruling": "선착순 처리. optimistic locking으로 경합. 후순위 지원은 422 반환 + '모집이 마감되었습니다'",
  "rationale": "추첨이나 심사 방식은 UX가 복잡해짐. 선착순이 가장 단순하고 공정함.",
  "references": ["CL-007-1", "ACT-002"]
}

{
  "id": "CASE-006",
  "situation": "외부 결제 시스템(TossPayments) 장애로 카드 결제 실패",
  "ruling": "3회 자동 재시도(exponential backoff: 1초, 3초, 10초). 3회 실패 시 공고 생성 보류 상태로 전환. 사용자에게 '결제 시스템 일시 장애' 알림.",
  "rationale": "일시적 네트워크 장애가 대부분이므로 즉시 실패 처리는 UX 저하. 단 무한 재시도는 시스템 부하 유발.",
  "references": ["CL-001-4", "CONST-004"]
}

$ lex_cli tree -f launchcrew.lex --root CONST-001
CONST-001: 모든 금전 거래는 에스크로를 통해야 한다
├── CL-001-2: 즉시 에스크로
├── CASE-001: 잔액 부족 → 422
├── CASE-002: 중도 포기 → 부분 반환
└── CASE-006: 결제 장애 → 재시도 + 보류

# CASE-001에서 직접 파생된 테스트
RSpec.describe "CASE-001: 잔액 부족 시 공고 생성" do
  let(:user) { create(:user) }
  let!(:wallet) { create(:wallet, user: user, balance: 100) }

  it "422를 반환하고 공고가 생성되지 않는다" do
    # points_per_person(200) × recruits_count(3) = 600 > balance(100)
    post_params = { points_per_person: 200, recruits_count: 3 }

    expect {
      post "/api/qa_posts", params: post_params
    }.not_to change(QaPost, :count)

    expect(response).to have_http_status(422)
    expect(json_body["error"]).to include("포인트")
  end

  it "잔액이 변하지 않는다 (롤백)" do
    post_params = { points_per_person: 200, recruits_count: 3 }

    expect {
      post "/api/qa_posts", params: post_params
    }.not_to change { wallet.reload.balance }
  end
end