feat: 타임라인 삭제 불가 사유 코드 추가 및 교체 기록 null 방어

[TAEW00KIM]

이슈

• feat: 경기 진행 중 타임라인 중간 삭제 허용 #694 후속 — feat: 경기 진행 중 타임라인 중간 삭제 허용 (#694) #695 로 열린 중간 삭제에서 프론트가 사유별로 분기할 방법이 없던 것과, 조회 500 가능성을 함께 보완한다

변경 내용

삭제 불가 사유 코드 추가

지금은 프론트가 삭제 불가 사유별로 분기하려면 undeletableReason 한글 문구를 문자열 비교해야 한다. 문구가 바뀌면 화면이 조용히 깨진다.

Reason enum 이름을 undeletableReasonCode 로 함께 내려보내 문구와 분기 기준을 분리했다. 기존 undeletableReason 은 그대로 두었으므로 동작 변화가 없다.

• REPLACEMENT_PLAYER_HAS_LATER_RECORDS — 교체 투입 선수의 이후 기록 존재
• PROGRESS_TIMELINE_NOT_LAST — 쿼터 시작·종료 기록의 중간 삭제
• MIDDLE_DELETE_ONLY_WHILE_PLAYING — 종료된 경기의 중간 삭제
• INCONSISTENT_PROGRESS_STATE — 경기 상태와 기록 불일치

삭제 실패 응답({message, fieldErrors})은 공통 포맷이라 건드리지 않았다. 조회 시점에 코드로 아이콘 상태를 정하고, 실패 토스트는 지금처럼 서버 message 를 그대로 쓰면 된다.

삭제 아이콘 노출 기준을 문서에 명시

기획안에는 "쿼터 시작/종료·경기 종료 = 삭제 아이콘 미노출"로 되어 있는데, 서버는 마지막 기록이면 진행 기록도 deletable: true 로 내려준다. 오입력한 경기 종료를 되돌리는 유일한 수단이라, 기록 타입만 보고 아이콘을 숨기면 기존 기능이 사라진다. api.adoc 에 이 판단 기준을 적었다.

교체 타임라인 null 방어

replaced_lineup_player_id 는 nullable 인데 getRelatedLineupPlayers 가 List.of 로 감싸고 있어, NULL 행이 하나라도 있으면 해당 경기 타임라인 조회 전체가 500 이 된다. 삭제 가능 여부 계산이 전 기록을 훑기 때문에 매니저 화면뿐 아니라 관중 화면까지 같이 죽는다.

운영·개발 DB 를 확인한 결과 현재 NULL 행은 0건(prod 교체 기록 1,114건 / dev 44건 전부 정상)이라 실제 장애는 없었다. 컬럼이 nullable 로 남아 있는 동안의 방어다.

테스트

• TimelineQueryServiceTest — 진행 중 경기와 종료된 경기 각각에서 사유 코드가 문구와 함께 내려오는지, 삭제 가능하면 null 인지 검증
• TimelineQueryControllerTest — REST Docs 필드 문서화 추가 (가능한 코드 값 4종 설명 포함)
• 전체 848건 green / ./scripts/check-api-docs.sh 통과 (엔드포인트 96개)

영향 API

• GET /games/{gameId}/timeline — 각 record 에 undeletableReasonCode 필드 추가 (삭제 가능하면 null). 기존 필드 변경 없음

프론트 참고

위치	변경	비고
타임라인 삭제 모드	삭제 아이콘 노출 여부를 기록 타입이 아니라 deletable 값으로 판단	타입으로 판단하면 오입력한 경기 종료를 되돌릴 수 없다
삭제 불가 토스트	사유별 분기가 필요하면 문구 대신 undeletableReasonCode 사용	문구만 그대로 노출한다면 기존 undeletableReason 을 써도 된다

참고

기획안에 문구가 정의되지 않은 사유가 2건 있다.

• MIDDLE_DELETE_ONLY_WHILE_PLAYING — 종료된 경기는 마지막 기록 외 전부 삭제 불가라 득점 기록도 회색이 된다
• PROGRESS_TIMELINE_NOT_LAST

현재는 서버 문구를 그대로 쓰고 있다. 확정되면 상수 한 곳만 바꾸면 되므로 알려주면 맞추겠다.