/** * 경매 거부(rejection)를 클라이언트에 알릴 때 쓰는 "설명적 거부코드" 체계. * * 배경: * - 내부 Lua/서비스는 `CONFLICT`, `EXPIRED`, `TOO_LOW` 같은 짧은 코드를 쓴다. * 이 코드들은 구현 디테일이고, 그대로 클라/운영자에게 노출하면 "무엇이 왜 * 거부됐는지"를 알기 어렵다(특히 `CONFLICT`는 원인이 광범위하다). * - 그래서 ack의 `code`/`message`는 그대로 두되(진단/하위호환), 별도로 * `auctionRejectionReason`이라는 **맥락을 코드 이름에 담은 안정적 식별자**를 * 함께 내려준다. 클라는 이 reason을 사람이 읽는 문구로 매핑한다(프론트 사전). * * 명명 규칙: * - 다소 길어지더라도 "무엇이(BID/AUCTION_TRANSITION) + 왜(BECAUSE_...)"를 * 이름만으로 알 수 있게 풀어쓴다. * * resync 권장 여부: * - `AUCTION_RESYNC_RECOMMENDED_REASONS`에 속한 reason은 "클라가 본 상태가 이미 * 바뀌었다(낙관적 동시성 충돌/만료/단계 전이)"는 신호다. 이 경우 클라는 최신 * state로 rebaseline한 뒤 (구조 액션이라면) 1회 재시도하는 것이 안전하다. * - 반대로 정원 초과/포인트 부족처럼 "상태를 새로고침해도 결과가 같은" 거부는 * resync 권장 대상이 아니다(재시도해도 또 거부됨). */ export const AUCTION_REJECTION_REASON = { // === 구조 전환(낙찰/유찰/다음/입찰오픈) === /** 내가 본 revision/phase/선수가 commit 직전 이미 바뀜(낙관적 동시성 충돌, 내부 `CONFLICT`). */ AUCTION_TRANSITION_REJECTED_BECAUSE_LIVE_STATE_CHANGED_BEFORE_APPLY: 'AUCTION_TRANSITION_REJECTED_BECAUSE_LIVE_STATE_CHANGED_BEFORE_APPLY', /** 입찰 단계가 아닌데 입찰 단계 전환을 시도함(이미 sold/passed/presenting 등). */ AUCTION_TRANSITION_REJECTED_BECAUSE_AUCTION_NOT_IN_BIDDING_PHASE: 'AUCTION_TRANSITION_REJECTED_BECAUSE_AUCTION_NOT_IN_BIDDING_PHASE', /** 현재 단계에서 "다음"으로 진행할 수 없음(sold/passed/presenting이 아님 — 보통 이미 진행됨). */ AUCTION_TRANSITION_REJECTED_BECAUSE_PHASE_DOES_NOT_ALLOW_ADVANCE: 'AUCTION_TRANSITION_REJECTED_BECAUSE_PHASE_DOES_NOT_ALLOW_ADVANCE', /** 낙찰 처리할 유효한 최고 입찰이 없음(만료 처리로 이미 정리됐을 수 있음). */ AUCTION_TRANSITION_REJECTED_BECAUSE_NO_WINNING_BID_TO_MARK_SOLD: 'AUCTION_TRANSITION_REJECTED_BECAUSE_NO_WINNING_BID_TO_MARK_SOLD', /** 진행 중인 입찰이 있는 선수를 유찰 처리하려 함. */ AUCTION_TRANSITION_REJECTED_BECAUSE_ACTIVE_BID_PRESENT: 'AUCTION_TRANSITION_REJECTED_BECAUSE_ACTIVE_BID_PRESENT', /** 전환 요청 조정(예약/리스/멱등) 단계의 일시적 거부 — 최신 상태로 재시도하면 보통 해소됨. */ AUCTION_TRANSITION_REJECTED_BECAUSE_REQUEST_COORDINATION_RETRYABLE: 'AUCTION_TRANSITION_REJECTED_BECAUSE_REQUEST_COORDINATION_RETRYABLE', // === 입찰(bid) === /** 입찰 라운드가 이미 다음 선수/다음 라운드로 넘어감(내부 `STALE_BID_ROUND`). */ BID_REJECTED_BECAUSE_BID_ROUND_ALREADY_ADVANCED: 'BID_REJECTED_BECAUSE_BID_ROUND_ALREADY_ADVANCED', /** 입찰 라운드 마감 시각이 이미 지남(내부 `EXPIRED`). */ BID_REJECTED_BECAUSE_BID_ROUND_DEADLINE_PASSED: 'BID_REJECTED_BECAUSE_BID_ROUND_DEADLINE_PASSED', /** 경매가 입찰 단계가 아님(내부 `PHASE`). */ BID_REJECTED_BECAUSE_AUCTION_NOT_IN_BIDDING_PHASE: 'BID_REJECTED_BECAUSE_AUCTION_NOT_IN_BIDDING_PHASE', /** 입찰 금액이 현재 최고가보다 높지 않음(내부 `TOO_LOW`). */ BID_REJECTED_BECAUSE_AMOUNT_NOT_HIGHER_THAN_CURRENT_HIGHEST: 'BID_REJECTED_BECAUSE_AMOUNT_NOT_HIGHER_THAN_CURRENT_HIGHEST', /** 팀 정원이 이미 가득 참(내부 `FULL`). */ BID_REJECTED_BECAUSE_TEAM_ROSTER_FULL: 'BID_REJECTED_BECAUSE_TEAM_ROSTER_FULL', /** 남은 슬롯 최소 확보분을 고려하면 포인트가 부족함(내부 `INSUFFICIENT`). */ BID_REJECTED_BECAUSE_INSUFFICIENT_REMAINING_POINTS_FOR_SLOTS: 'BID_REJECTED_BECAUSE_INSUFFICIENT_REMAINING_POINTS_FOR_SLOTS', /** 알 수 없는 팀 인덱스(내부 `UNKNOWN_TEAM`). */ BID_REJECTED_BECAUSE_UNKNOWN_TEAM: 'BID_REJECTED_BECAUSE_UNKNOWN_TEAM', /** 같은 요청 id에 다른 내용이 온 멱등성 충돌(내부 `DUPLICATE_REQUEST_CONFLICT`). */ BID_REJECTED_BECAUSE_DUPLICATE_REQUEST_PAYLOAD_CONFLICT: 'BID_REJECTED_BECAUSE_DUPLICATE_REQUEST_PAYLOAD_CONFLICT', /** 짧은 시간에 너무 많은 입찰 요청(게이트웨이 rate limit). */ BID_REJECTED_BECAUSE_RATE_LIMITED: 'BID_REJECTED_BECAUSE_RATE_LIMITED', // === 공통/그 외 === /** 실시간 상태를 아직 사용할 수 없음(재접속/재조회 필요). */ AUCTION_REQUEST_REJECTED_BECAUSE_REALTIME_STATE_UNAVAILABLE: 'AUCTION_REQUEST_REJECTED_BECAUSE_REALTIME_STATE_UNAVAILABLE', /** 위 어디에도 해당하지 않는 미분류 거부(원문 message로 안내). */ AUCTION_REQUEST_REJECTED_FOR_UNRECOGNIZED_REASON: 'AUCTION_REQUEST_REJECTED_FOR_UNRECOGNIZED_REASON', } as const; export type AuctionRejectionReason = (typeof AUCTION_REJECTION_REASON)[keyof typeof AUCTION_REJECTION_REASON]; /** 내부 짧은 코드 → 설명적 reason. */ const INTERNAL_CODE_TO_REASON: Record = { CONFLICT: AUCTION_REJECTION_REASON.AUCTION_TRANSITION_REJECTED_BECAUSE_LIVE_STATE_CHANGED_BEFORE_APPLY, STALE_BID_ROUND: AUCTION_REJECTION_REASON.BID_REJECTED_BECAUSE_BID_ROUND_ALREADY_ADVANCED, EXPIRED: AUCTION_REJECTION_REASON.BID_REJECTED_BECAUSE_BID_ROUND_DEADLINE_PASSED, PHASE: AUCTION_REJECTION_REASON.BID_REJECTED_BECAUSE_AUCTION_NOT_IN_BIDDING_PHASE, TOO_LOW: AUCTION_REJECTION_REASON.BID_REJECTED_BECAUSE_AMOUNT_NOT_HIGHER_THAN_CURRENT_HIGHEST, FULL: AUCTION_REJECTION_REASON.BID_REJECTED_BECAUSE_TEAM_ROSTER_FULL, INSUFFICIENT: AUCTION_REJECTION_REASON.BID_REJECTED_BECAUSE_INSUFFICIENT_REMAINING_POINTS_FOR_SLOTS, UNKNOWN_TEAM: AUCTION_REJECTION_REASON.BID_REJECTED_BECAUSE_UNKNOWN_TEAM, DUPLICATE_REQUEST_CONFLICT: AUCTION_REJECTION_REASON.BID_REJECTED_BECAUSE_DUPLICATE_REQUEST_PAYLOAD_CONFLICT, BID_RATE_LIMITED: AUCTION_REJECTION_REASON.BID_REJECTED_BECAUSE_RATE_LIMITED, }; /** 구조화된 code 없이 message만 던지는 BadRequest(구조 전환 검증 등) → 설명적 reason. */ const MESSAGE_TO_REASON: Record = { 'Auction is not in bidding phase.': AUCTION_REJECTION_REASON.AUCTION_TRANSITION_REJECTED_BECAUSE_AUCTION_NOT_IN_BIDDING_PHASE, 'Cannot advance from current phase.': AUCTION_REJECTION_REASON.AUCTION_TRANSITION_REJECTED_BECAUSE_PHASE_DOES_NOT_ALLOW_ADVANCE, 'No bid to mark sold.': AUCTION_REJECTION_REASON.AUCTION_TRANSITION_REJECTED_BECAUSE_NO_WINNING_BID_TO_MARK_SOLD, 'Cannot pass a player with an active bid.': AUCTION_REJECTION_REASON.AUCTION_TRANSITION_REJECTED_BECAUSE_ACTIVE_BID_PRESENT, 'Auction realtime state is not available.': AUCTION_REJECTION_REASON.AUCTION_REQUEST_REJECTED_BECAUSE_REALTIME_STATE_UNAVAILABLE, }; /** * resync(최신 state로 rebaseline 후 재시도)가 권장되는 reason 집합. * "내가 본 상태가 낡았을 뿐, 다시 보면 가능할 수 있는" 거부들이다. */ export const AUCTION_RESYNC_RECOMMENDED_REASONS: ReadonlySet = new Set([ AUCTION_REJECTION_REASON.AUCTION_TRANSITION_REJECTED_BECAUSE_LIVE_STATE_CHANGED_BEFORE_APPLY, AUCTION_REJECTION_REASON.AUCTION_TRANSITION_REJECTED_BECAUSE_AUCTION_NOT_IN_BIDDING_PHASE, AUCTION_REJECTION_REASON.AUCTION_TRANSITION_REJECTED_BECAUSE_PHASE_DOES_NOT_ALLOW_ADVANCE, AUCTION_REJECTION_REASON.AUCTION_TRANSITION_REJECTED_BECAUSE_NO_WINNING_BID_TO_MARK_SOLD, AUCTION_REJECTION_REASON.AUCTION_TRANSITION_REJECTED_BECAUSE_ACTIVE_BID_PRESENT, AUCTION_REJECTION_REASON.AUCTION_TRANSITION_REJECTED_BECAUSE_REQUEST_COORDINATION_RETRYABLE, AUCTION_REJECTION_REASON.BID_REJECTED_BECAUSE_BID_ROUND_ALREADY_ADVANCED, AUCTION_REJECTION_REASON.BID_REJECTED_BECAUSE_BID_ROUND_DEADLINE_PASSED, AUCTION_REJECTION_REASON.BID_REJECTED_BECAUSE_AUCTION_NOT_IN_BIDDING_PHASE, AUCTION_REJECTION_REASON.BID_REJECTED_BECAUSE_AMOUNT_NOT_HIGHER_THAN_CURRENT_HIGHEST, AUCTION_REJECTION_REASON.AUCTION_REQUEST_REJECTED_BECAUSE_REALTIME_STATE_UNAVAILABLE, ]); /** * 내부 거부 code(짧은 코드) 또는 BadRequest message로부터 설명적 reason을 해석한다. * 둘 다 모르면 미분류 reason으로 떨어뜨린다(원문 message는 ack에 그대로 남는다). */ export function resolveAuctionRejectionReason( internalCode?: string, message?: string, ): AuctionRejectionReason { if (internalCode && INTERNAL_CODE_TO_REASON[internalCode]) { return INTERNAL_CODE_TO_REASON[internalCode]; } if (message && MESSAGE_TO_REASON[message]) { return MESSAGE_TO_REASON[message]; } // 구조 전환 경로는 code 자리에 message 문장이 들어올 수 있어 한 번 더 확인한다. if (internalCode && MESSAGE_TO_REASON[internalCode]) { return MESSAGE_TO_REASON[internalCode]; } if ( internalCode && (internalCode.startsWith('ACTION_REQUEST_') || internalCode.startsWith('INVALID_')) ) { return AUCTION_REJECTION_REASON.AUCTION_TRANSITION_REJECTED_BECAUSE_REQUEST_COORDINATION_RETRYABLE; } return AUCTION_REJECTION_REASON.AUCTION_REQUEST_REJECTED_FOR_UNRECOGNIZED_REASON; } export function isAuctionResyncRecommended( reason: AuctionRejectionReason, ): boolean { return AUCTION_RESYNC_RECOMMENDED_REASONS.has(reason); }