Files
lolympus-tournament-support/docs/specs/match-status-and-result-presentation.md
T

24 KiB

내전 상태와 대회·시리즈·세트 표시 명세

2026년 11월 10일 · UX/UI 결과 표시 · 후속 구현 제안

결과 표시 작업은 대회·시리즈·세트의 결과 범위를 분리하는 데 집중한다. 전적 화면의 2:0은 해당 두 팀의 시리즈에서만 표시한다. 전체 개편은 토큰과 프리미티브를 먼저 적용한다. 경매 상태와 코드 발급 대기는 감사 당시 스테이징에서 관찰한 두 사례로, 현재 운영 흐름의 수정 범위를 정하기 전에 정상 데이터로 확인한다. UI 우선 검토 · 감사 보고서

1. 현재 원인과 범위

  1. 구현 대상. 공식 대회 데이터에는 seriesId, gameSlotId, winnerTeamId가 있다. 통계용 변환에서는 해당 식별 관계가 결과 DTO로 이어지지 않는다. 전적 서비스는 팀 인덱스 쌍으로 결과를 다시 묶고, 대회 카드와 상세는 seriesResults[0], 세트 상세는 팀 인덱스 조합으로 점수를 선택한다. 정상 데이터에서도 서로 다른 두 시리즈가 같은 팀 쌍을 가지면 이 방식으로는 둘을 구별할 수 없다. 공식 계약 · 통계용 변환 · 재집계 · 세트의 팀 쌍 선택
  2. 재현 대기. 경매 시작 경로는 편성이 끝나기 전에 Match.status = 'team-built'를 저장할 수 있다. 홈과 상세의 라벨이 다른 것은 코드로 확인했다. 감사 당시 test300의 저장 상태와 경매 스냅샷이 같은 정상 전이를 나타내는지, 중단·복구·정정이 있었는지는 확인하지 못했다. 이 기록을 정상 경매의 회귀 기준으로 쓰지 않는다. 경매 시작 · 홈 상태 라벨 · 상세 상태 라벨
  3. 정상일 수 있는 대기 상태. 대진의 ready와 슬롯의 코드 할당은 별도 상태다. 팀 화면에 발급 대기가 보였다는 사실만으로 코드 발급 실패나 화면 결함을 판단할 수 없다. 스테이징 당시 할당 예정 시점, 코드 풀, 후속 처리 결과는 확인하지 못했다. 팀 진행 조회 · 코드 할당 처리

기존 Match·경매·Competition이 각각 소유하는 상태 전이와 점수 산정은 유지한다. 새 작업은 읽기 계약, 공통 표시 규칙, 상태에 맞는 기존 행동 링크, 조회 상태를 다룬다. 저장 enum, 입찰·팀빌딩·판정 명령, 대진 알고리즘, 신규 모집 정책, 알림 및 전체 디자인 토큰 교체는 별도 변경이다. 기존 Competition 도메인 명세

2. 어떤 데이터가 무엇을 결정하는가

질문 기준 데이터 화면에 주는 값
모집·팀빌딩·내전 진행 중 어디인가? Match.status와 확정 팀 근거, 해당 내전의 현재 경매 공통 내전 단계 및 홈 섹션. 예정 시각은 일정과 정렬에 사용한다.
현재 입찰 라운드는 무엇인가? 현재 경매 lifecycle의 스냅샷·소켓 업데이트 입찰 대기/진행/마감 확인/낙찰/유찰. 전송 중·재연결 중은 별도 표시한다.
대회와 시리즈의 공식 결과는 무엇인가? 같은 Competition revision의 projection·outcome 형식·공식 대회 상태·순위/우승·시리즈 점수·판정.
세트는 실제로 끝났는가? 분석을 볼 수 있는가? 해당 gameSlotId와 연결된 공식 Game, 현재 revision에 해당하는 통계 상세 공식 세트 승패와 분석 가용성을 분리한다.
코드가 지금 사용 가능한가? 기존 팀 진행 API의 해당 슬롯 할당과 만료 코드 상태 및 복사 가능 여부. 공개 내전 요약에는 코드를 담지 않는다.

표시 상태는 동작 권한이 아니다. 역할·커뮤니티·팀 권한과 제출 가능 여부는 기존 조회·명령의 검증을 사용한다. 버튼 활성화에는 UI 표시 상태에 더해 기존의 권한, 데이터 최신성, 진행 중 요청 조건을 적용한다. 공식 상태와 Match 상태가 잠시 다른 동안에는 각각 공식 결과와 내전 상태의 범위에서 보여 준다. 예를 들어 판정 반영 직후 경기 기록에는 공식 결과 확정이 보일 수 있고, 홈은 outbox가 Match.status를 갱신한 뒤 종료 기록으로 이동한다. 결과 정정에서도 같은 원칙을 적용한다. 기존 outbox

3. 공통 내전 상태 검증과 조건부 설계

정상 절차로 만든 격리 내전에서 경매 시작 → 입찰 또는 유찰 → 편성 반영을 따라간다. 같은 matchId와 경매 lifecycle에서 현재 phase·revision·편성 반영 상태를 기록한 뒤 홈과 상세의 재조회 결과를 대조한다. 코드 흐름은 대진 확정 시각, 슬롯 할당 전후, 후속 처리 결과를 확인한다. ready 상태에서 코드 할당 전 대기는 정상 시나리오로 다룬다. 관찰 결과는 다음과 같이 처리한다.

검증 결과 구현 범위
이전 스냅샷이나 오류가 있는 레코드에서만 재현 해당 데이터·복구 경로의 문제로 분리한다. 정상 화면용 새 상태 계약은 보류한다.
정상 경매에서 편성 전인데 상세가 완료를 표시 상세가 이미 조회하는 경매 데이터로 해당 라벨을 바로잡을 수 있는지 먼저 확인한다. 정상 데이터에서 홈까지 의미가 어긋나고 기존 정보로 해결할 수 없는 경우에만 아래 공통 상태 API를 검토한다.
대진 확정 뒤 예정대로 코드가 발급됨 현재 상태와 흐름을 유지한다. 반복적인 문의나 입장 혼동이 확인될 때만 문구를 개선한다.
발급 조건이 충족됐지만 할당이 누락되거나 멈춤 슬롯·코드 풀·후속 처리의 원인을 따로 조사한다. 문구 변경만으로 해결된 것으로 보지 않는다.

다음 API와 화면 규칙은 홈·상세 공통 상태가 필요하다는 결과가 나올 때 사용할 설계안이다. 홈의 날짜 분류 개선은 실제 진행 내전이 과거 목록에 묻히는 정상 사례를 확인한 뒤 범위를 결정한다.

목록과 상세를 제공하는 API에 eventProgress?: { stage: EventStage }를 추가한다. status는 기존 도메인 값 그대로 반환한다. 서버가 한 함수에서 stage를 계산하고, 웹은 한 매핑에서 문구·강조도·화면별 진입점을 선택한다. 화면별로 team-built를 직접 번역하는 코드를 교체한다.

아래 표는 위에서부터 우선 적용한다. ‘편성 확정 근거’는 정상 링크된 competitionId, 또는 유효한 teamBuiltAt과 2개 이상 저장된 팀이다. 현재 경매가 살아 있거나 반영 실패 상태임을 알고 있다면 확정 근거를 먼저 적용하지 않는다. 데이터 불일치는 team-check로 표현하고 기존 명령 검증을 유지한다.

EventStage 결정 조건 화면 기본 문구 주요 진입점
finished Match.status = finished 종료 경기 일정·결과. 공식 결과가 정정 중이면 공식 상태를 별도 안내.
in-progress Match.status = in-progress 진행 중 대진표·일정. 기존 권한으로 내 팀을 확인할 수 있으면 팀 진행.
recruiting recruiting이고 해당 내전의 현재 경매가 없음을 확인함 모집 중 내전 상세의 참가 영역. 정원·로그인·기참가 조건은 기존 참가 판단을 사용.
auction-preparing 현재 경매 startupCompleted = false 또는 waiting 경매 준비 중 경매 페이지. 시작 처리 중에는 신청·입찰 가능 여부를 추정하지 않음.
auction-active 현재 경매 presenting, bidding, sold, passed 팀빌딩 중 경매 보기. 라운드 문구는 경매 페이지에 추가 표시.
team-finalizing 현재 경매 complete이고 편성 반영이 pending/processing, 또는 실패 신호와 확정 근거가 모두 없음 팀 편성 반영 중 경매 결과 보기. 공식 대진 및 코드 CTA는 실제 준비 상태에 따름.
team-check 편성 반영 failed, 알려진 데이터 불일치, 또는 필요한 조회를 확인하지 못함 팀빌딩 상태 확인 필요 내전 상세 또는 경매 보기. 운영자에게만 오류·회복 경로를 제공.
teams-finalized 활성 경매가 없거나 종료됐고 편성 확정 근거가 있음 팀 편성 완료 대진표가 조회되면 보기. 초기화 대기면 대진 준비 중 표시.

team-built인데 경매·확정 근거가 없거나 구버전 API에 eventProgress가 없으면 팀빌딩 상태 확인 필요로 표시한다. 조회 실패는 경매 없음과 다르다. recruiting과 이미 시작된 경매가 함께 보이면 시작이 확인된 현재 lifecycle만 표시한다. 완료된 취소의 lifecycle은 조회 후보에서 제외한다. 경매 취소가 성공해 Match가 모집 상태로 돌아가면 모집 중을 표시하고 이전 경매 상태를 폐기한다. 새 경매 lifecycle과 이전 revision을 같은 타임라인에서 비교하지 않는다. 기존 경매 스냅샷 병합 · 경매 시작 복구

읽기 경로와 홈 목록

  • 목록에 표시될 ID만 대상으로 경매의 소형 상태를 배치 조회한다. Mongo에서는 현재 경매와 startupCompleted, 엔진, lifecycle, revision 및 반영 상태만 읽는다. Redis 경매는 같은 lifecycle이고 오래되지 않은 스냅샷의 phase/반영 상태를 사용할 수 있다. Redis 누락·불일치·오류의 경우 확정 근거가 있는 종료 경매만 보존하고, 확인이 필요한 활성 후보는 team-check로 내려준다. 목록 요청은 기존 전체 경매 조회나 재수화 경로를 호출하지 않는다. 사용자 ID, 현재 선수, 채팅, 입찰 금액, 코드가 공통 상태 응답에 들어가지 않는다.
  • 기존 매치 목록 API에 홈 전용 view=active|upcoming|history를 추가한다. active는 team-built/in-progress 및 scheduledAt < asOf인 recruiting, upcoming은 scheduledAt >= asOf인 recruiting, history는 finished다. 홈은 한 번의 갱신에 세 조회가 공유할 ISO asOf를 보내고, 서버는 날짜 형식을 검증한 뒤 필터·정렬·페이지를 적용한다. 기존 status 및 날짜 필터를 사용하는 호출자는 그대로 동작한다. view와 기존 상태·날짜 필터를 한 요청에 섞으면 400으로 응답한다. 날짜는 모집 내전의 목록 위치만 정하며, 예정 시각이 지났다는 이유로 참가 가능 상태를 종료로 바꾸지 않는다.
  • 홈은 진행 중인 내전과 예정된 내전, 지난 내전 기록을 따로 보여 준다. 진행·종료는 scheduledAt 최신순, 예정은 가까운 순이며 동일한 시각의 순서는 _id로 고정한다. 서버 페이지를 통째로 클라이언트에서 재정렬하지 않는다. 진행 중인 6월 내전은 날짜가 오래돼도 종료 목록에 들어가지 않는다. 각 섹션 오류는 그 섹션에서 복구할 수 있다.
  • 경매 소켓으로 같은 lifecycle의 단계가 바뀌거나 시작·종료·취소 명령이 확정되면 해당 Match detail 및 목록 query를 갱신한다. presenting/bidding/sold/passed 사이의 가격·타이머 틱마다 홈을 다시 요청할 필요는 없다. 오래 열린 홈은 전면 복귀 시 갱신한다. 외부 운영자의 상태 전이는 기존 소켓 또는 제한된 재조회로 반영하며, 기존 목록의 전체 실시간 구독을 추가하지 않는다.

경매 페이지에서는 팀빌딩 중 아래 입찰 대기, 입찰 진행 중, 낙찰, 유찰 · 다음 선수 대기를 해당 phase로 표시한다. 화면 타이머가 0초가 되면 기존 마감 가드에 맞춰 마감 · 서버 결과 확인 중을 보여 준다. 서버가 확정할 때까지 낙찰이나 유찰을 추정하지 않는다. 연결 중, 재연결 중, 입찰 확인 중은 각각 연결 및 요청 상태로 표시한다.

4. 대회·시리즈·세트 표시 규칙

단위 표시 기준 예시
대회 / 내전 제목·형식·공식 진행 상태. 더블 엘리미네이션은 공식 완료 후에만 우승팀, 라운드 로빈은 공식 순위 및 공동 1위. paired-series 대회에 종합 우승을 만들지 않는다. 멸망전 · 8팀 더블 엘리미네이션 / 공식 시리즈 6개 확정 / 결승 확정 후 우승팀 ○○
단일 시리즈 요약 대회 그래프가 실제로 시리즈 1개인 paired-series에서만 시리즈 요약을 대회 헤더 아래에 둘 수 있다. 시즌 필터 결과가 한 팀 쌍 또는 시리즈 하나라는 사실은 판단에 사용하지 않는다. 시리즈 결과 · 나물장수 2:0 원딜미아요
시리즈 라운드·시리즈 이름, 두 팀, 형식, 상태. 점수는 entries의 A/B 슬롯을 실제 팀 ID에 붙인다. 해당 세트의 블루/레드 진영이 바뀌어도 표의 팀 순서와 시리즈 점수는 유지한다. 승자조 1라운드 · 1경기 · 3전 2선승 / 나물장수 2:0 원딜미아요
세트 시리즈 안 번호인 ordinal을 화면에 사용한다. 세트 승패는 해당 공식 Game의 승자·진영으로 표시한다. displayNumber는 기존 링크 해석과 필요한 보조 표기에 사용한다. 승자조 1라운드 · 1경기 · 1세트 / 나물장수 승리 · 블루 · 28:24
레거시 기록 공식 연결을 확정할 수 없으면 개별 기록에서 확인 가능한 팀·승패·전역 경기 번호를 표시한다. 상대 조합을 시리즈 ID 또는 우승의 근거로 삼지 않는다. 과거 기록 · 7경기 / 공식 시리즈 정보 없음

세트의 기본 헤더에는 2:0도, 세트 승패를 숫자로 바꾼 1:0도 넣지 않는다. 필요하면 별도 시리즈 최종 2:0 또는 시리즈 현재 1:0을 함께 표시한다. 현재/최종은 공식 시리즈 상태가 결정한다. 동일 두 팀이 승자조와 결승에서 다시 만나면 별개의 seriesId와 세트 목록을 가진다.

표의 라운드 이름은 설명용 예시다. 화면에서는 기존 공식 대진의 라운드 이름을 공용 함수로 재사용하고 내전 상세, 전적, 팀 진행 사이에서 같은 이름을 쓴다. 라운드 이름 공용 함수

시리즈/슬롯 상태 화면 문구와 점수
inactive 일반 목록에서 숨긴다. 브래킷에서 조건을 보여 줄 때에는 리셋 결승 · 조건부 등으로 표시한다.
waiting 대진 미정 및 확인된 팀/진출 조건. 점수 없음.
ready 대진 확정, 일정이 없으면 일정 미정. 코드 할당이 있는 화면은 코드 발급 대기/사용 가능/만료를 별도로 표시한다. 점수 없음.
in-progress 진행 중. 공식 인정된 게임이 있는 경우에만 현재 1:0처럼 점수를 붙인다.
completed / played 최종 2:0, 공식 승자 표시.
completed / draw 무승부. 실제 경기로 성립한 경우에만 최종 점수 표시. 운영 판정 무승부에는 점수를 만들지 않는다.
completed / walkover, forfeit, administrative 부전승 / 기권승 / 판정승과 공식 승자. 점수 대신 결정 문구. 판정 전에 인정된 세트가 있으면 해당 기록은 펼쳐 볼 수 있다.
voided 또는 시리즈 종료 후 사용되지 않은 슬롯 무효 또는 미진행을 구별한다. 점수 및 다른 세트로 이어지는 분석 링크 없음.
공식 Game 있음 / 통계 상세 없음 세트 승패는 그대로 표시하고 상세 분석 준비 중을 붙인다. API 요청 실패는 상세 분석을 불러오지 못했습니다 · 다시 시도로 구분한다.

팀 진행에서 실제 혼동이 확인되면 대진 확정 · 코드 발급 대기처럼 대진과 코드 상태를 함께 안내하는 문구를 검토한다. used 코드는 사용 완료를 뜻하며 Riot 기록 수집 여부는 별도 데이터다. 팀 진행의 현재 코드 상태

5. 데이터 계약과 호환성

  • packages/contracts에 기존 ID 타입을 재사용해 공개 내전 상태와 공식 전적 표시 계약을 정의한다. 기존 필드에 eventProgress 및 선택적 resultPresentation을 추가하는 방식으로 이행한다. resultPresentation은 official, legacy, unavailable을 구별한다. 과거 API에 새 필드가 없는 경우 웹은 레거시라고 단정하지 않고 기록 단위에서 확인할 수 있는 결과만 보여 준다.
  • 목록의 공식 요약에는 competitionId, sourceRevision, formatType, phase, teamCount, 공식 확정 시리즈 수와 해당 형식의 공식 결과 요약을 담는다. 단일 시리즈 예외가 성립하는 경우에만 해당 요약을 포함한다. 공식 카드는 현재 페이지의 대회 ID를 한 번에 조회해 필요한 필드만 결합한다. 필터 날짜의 게임만 다시 센 수치는 조회 기간 내 기록 N세트처럼 별도로 표시한다. 필터 결과로 공식 시리즈 최종 점수나 우승이 바뀌지 않는다.
  • 대회 상세에는 공식 요약과 표시할 series, gameSlots, 인정 games의 최소 필드를 같은 revision에서 제공한다. 팀 이름과 점수는 teamId, 세트 분석은 정확한 gameId/gameSlotId를 사용한다. 통계 상세의 기존 gameNumber는 유지하되 응답에 공식 gameId, gameSlotId, seriesId, ordinal을 연결한다. 기존 통계 fragment를 연결할 때는 같은 대회·revision과 Riot 증빙 ID가 유일하게 맞는 경우만 사용한다. 레거시 증빙은 명시적인 참조가 일치할 때만 연결한다. 이름·팀 쌍·배열 위치로 연결하지 않는다.
  • 첫 배포에는 기존 통계 집계 계산을 교체할 필요가 없다. 공식 경기 표시에서 재집계된 seriesResults와 winnerTeamIndex의 소비를 끊고, 기존 통계 필드는 호환용으로 보존한다. 결과 정정으로 공식 revision이 앞서면 최신 공식 결과를 표시하고 이전 통계 상세를 새 세트 결과처럼 붙이지 않는다. 결과 응답 캐시 버전을 올리고 기존 outbox 무효화와 fragment 재구축을 재사용한다. DB 일괄 마이그레이션 없이 캐시 갱신으로 이행한다. 현행 상세 캐시 · 현행 fragment 최신성 확인
  • 기존 두 세트 URL은 유지한다. 공개 대진 /match/:id/game/:gameNumber의 기본 복귀는 /match/:id?tab=games, 커뮤니티 경로의 기본 복귀는 해당 전적 상세다. 같은 시리즈를 펼치려면 seriesId를 포함한 링크를 생성하고 해당 대회 소속인지 검증한다. 전역 번호로 정확히 일치하는 세트만 열며, 없으면 아직 기록이 없는 세트 또는 해당 세트를 찾을 수 없습니다로 안내한다. 기존 분석이 없는 공식 세트는 공식 대진 정보를 사용해 별도로 판단한다. 정확 번호 선택
  • 커뮤니티 통계의 순위·하이라이트·최근 내전은 각각 loading / success / error를 독립 처리한다. sideWinRate.confirmed?: { sampleSize, blue, red }를 추가해 승패가 확인된 세트의 수와 그 표본의 승률을 반환한다. 새 분모가 0이면 — · 표본 없음, 분모 12에서 블루 승리가 0번이면 0% · 12세트다. 기존 승률과 bluePicks/redPicks의 계산은 호환용으로 보존한다. 새 분모가 없는 구버전 응답에서는 확인된 표본 수라고 단정하지 않는다. 재조회에 실패했지만 기존 성공 데이터가 있으면 그 값과 갱신 실패를 함께 표시한다. 현행 인사이트 응답

6. 구현 순서와 완료 조건

작업 코드 접점 완료 조건
1. 공식 결과 연결 CommunityStatsService, 공식 Competition 조회, 통계 상세 DTO, 캐시 한 대회 안의 동일 팀 재대결이 각각 다른 seriesId 및 점수를 보유. 시즌 필터와 결과 정정에서도 공식 점수가 정체성을 유지. 페이지 크기에 비례하는 외부 요청 증가 없음.
2. 전적 화면 적용 CommunityInternalStatsPage, InternalMatchDetailPage, MatchGameDetailPage, 기존 CompetitionSeriesHistory 대회 헤더에서 임의 점수 제거. 시리즈 점수와 세트 승패 구별, 링크 보존과 진입 맥락별 복귀. 표본 없음과 조회 실패는 별도 상태로 표시.
병행 검증. 경매·코드 상태 HomePage, MatchDetailPage, AuctionPage, 팀 진행 표시 유틸 및 각 조회 계약 새 내전에서 편성 전후와 슬롯 할당 전후를 확인한다. 정상 절차에서 문제가 재현되는 화면만 수정 범위에 넣는다.

전적 화면은 공식 결과 계약을 사용한다. 서버 계약 변경은 응답 필드 추가로 먼저 이행하고, 웹은 필드가 없는 응답에서도 결과 범위를 과장하지 않는 기본 표시를 제공한다. 경매·코드 검증은 공식 결과 작업의 선행 조건이 아니다.

회귀 시나리오 기대 화면/동작
감사의 8팀 대회 대회 헤더에 첫 팀 쌍 0:2가 보이지 않음. 첫 세트는 나물장수의 해당 세트 승리를, 별도 시리즈 맥락은 해당 시리즈 2:0을 보여 줌. 재현 화면
2팀 고정 세트 무승부, 4/8팀 더블 엘리미네이션, 라운드 로빈 공동 1위, 같은 팀 재대결 형식에 맞는 종합 결과. 공식 승자/순위만 표시하며 동일 팀 대결을 분리.
부전승·기권승·판정승·판정 무승부·리셋 미활성 가짜 0:0 없음. 인정 세트가 있으면 올바른 세트만 열 수 있음.
슬롯 번호가 1, 2, 7로 건너뜀 / 기존 /game/7 링크 / 결과 되돌리기 보이는 시리즈 내 번호와 전역 URL 번호가 구분됨. 요청 번호와 다른 세트로 이동하지 않음. 정정 직후 이전 분석을 새 결과에 붙이지 않음.
통계 요청 일부 실패 / 0세트 / 실제 승률 0% 다른 섹션은 계속 보이며, 실패·표본 없음·실측 0을 구분.

검증은 API 상태 결정과 DTO의 회귀 테스트, 웹의 표시 결정·링크 선택 테스트, 그리고 390px와 데스크톱에서 위 사례를 확인하는 순서로 진행한다. 기존 match-public.presenter, community-stats.service, competition-series-history, match-team-progress-view, internal-match-game-selection, auction-state 테스트를 재사용하고 기존 테스트에 없는 재대결·상태 경합에만 사례를 추가한다. 구현 후 pnpm --filter web test, pnpm --filter web build와 변경한 API 모듈 테스트를 실행한다. 쓰기가 필요한 재현은 격리된 fixture에서 검증한다.