위시·토너먼트 등록 경로 정리와 주석 인지부채 제거

[m-a-king]

Situation

• 코드를 읽다 보니 주석이 이해를 돕는 게 아니라 방해하고 있었다. 실측해 보니 item 패키지가 주석 30퍼센트로 저장소 평균(17퍼센트)의 두 배였고, 파싱 기계 쪽은 파일에 따라 50퍼센트를 넘었다.
• 문제는 양이 아니라 종류였다. 상당수가 코드가 이미 말하는 것을 한 번 더 말하고 있었고, 그 사이에 정말 필요한 정보가 묻혀 있었다.
• 위시 등록 진입점(POST /wishlists)부터 영속화 바닥까지 한 체인을 따라가며 정리했고, 주석을 걷어내는 과정에서 구조 문제 몇 가지가 드러났다.

Task

• 주석 판정 기준을 하나로 세운다: 숙련 개발자가 이 주석 없이 놓칠 정보가 있는가.
• 주석이 변호하고 있던 구조는 주석이 아니라 구조를 고친다.
• 등록 경로(URL·이미지)를 위시와 토너먼트 양쪽에서 같은 골격으로 맞춘다.

Action

주석이 가리키던 구조 문제

발견	신호	처리
위시·토너먼트가 등록 서두를 각자 베낌	두 곳의 주석이 거의 글자 그대로 같음	ItemRegistrar 로 관문 추출
content-type 검증이 두 번 돎	"이 중복은 무해하다" 는 변호 주석	UploadFormat 이 검증 결과를 실어 나름
persist 가 저장을 약속하며 다섯 가지를 함	이름과 본문의 불일치	붙는 길·새로 세우는 길 두 갈래로 분리
persist 가 링크 없는 Item 을 분기	널이 두 이유로 뭉개져 읽기 어려움	호출자 16곳 전수 확인 후 ProductLink 를 직접 받음

등록 관문

• 링크 등록의 서두(형식·정책 판정과 몫 확보)를 ItemRegistrar 한 곳으로 모았다. 두 호출자가 이 순서를 각자 외우던 동안 자격 검사 위치가 이미 어긋나 있었다(위시는 맨 앞, 토너먼트는 세 번째). 순서를 맞췄다.
• 중복 판정은 관문 밖에 남겼다. 기준이 도메인마다 다르고(내 위시 대 이 토너먼트) 차감 앞에 와야 해서, 인자로도 밖으로도 뺄 수 없는 자리다.

한도 코드 통합

• WISH-010 과 TOURNAMENT-037 을 ITEM-006 하나로 합쳤다. 카운터가 하나인데 담는 자리마다 code 를 나눌 이유가 없고, 이 인자가 필요했던 유일한 이유가 code 가 둘이라는 것이었다.
• 문구는 몫의 주인을 드러내지 않는 쪽으로 골랐다. 토너먼트는 오너 몫에서 깎지만 응답은 참여 게스트도 받으므로, 옛 위시 문구를 그대로 쓰면 남의 사용량이 새는 자리가 된다.

탈퇴 경합 가드 제거

WishPersistenceService.persist 의 rejectIfWithdrawnForUpdate 를 걷어냈다. 검토 내용은 아래와 같다.

	이 가드가 답하는가
cascade 가 wishes 를 지운 뒤 INSERT 가 끼어드는 것	막는다
죽은 유저를 위한 파싱 실행	못 막는다(item/service 에 유저 검사 0건)
한도 차감	못 막는다(persist 앞이라 락 밖)
고아 snapshot	못 막는다(공유 자원이라 cascade 대상 아님)

• 한 구멍만 막고 "탈퇴 경합을 막는다" 로 읽히면 보장 범위를 실제보다 넓게 믿게 된다. 활성 유저 확인과 쓰기 사이의 check-then-use 경합 차단 #776 본문도 이 선택지를 "경합 자체를 없애진 못하고 창을 좁힌다" 로 적어 두고 있었다.
• 탈퇴 후 남는 wish 행은 배치 정리로 푼다(후속).
• FCM 기기 등록과 지연 이미지 등록의 같은 가드는 남긴다. 후자는 스케줄러 공용이라 예외를 던지면 롤백이 claim 을 되살려 무한 재시도가 되는, 성격이 다른 가드다.

이미지 등록 플로우

• ImagePresignService 26줄, 폴링 스케줄러 30줄, claimer 5줄이던 주석을 각각 3·7·2줄로 줄였다.
• existsOrNull 을 uploadedOrUnknown 으로 바꿔 "null 은 판단 못 함" 이라는 주석을 이름으로 옮겼다.
• UploadFormat 은 @ConsistentCopyVisibility 를 붙였다. data class 는 생성자가 private 이어도 copy() 가 공개라 검증을 우회한다.

남긴 주석의 네 부류

• 지시: @Async 로 바꾸지 말 것. 하면 재진입 가드가 async body 로 들어가 무력해지고 fixedDelay 가 fixedRate 가 된다. 코드에 존재할 수 없는 정보다.
• 부재: 등록에 못 매인 raw 를 여기서 안 지운다는 것. 없는 동작은 코드가 못 말한다.
• 착시: presign 이 로컬 계산이라 트랜잭션에 묶어도 된다는 것. 외부 호출처럼 보인다.
• 전파 속성: 삭제가 곧 claim 이고 자기 트랜잭션을 열면 안 된다는 것. 코드에 안 보인다.

Result

• 위시 등록 진입점이 다섯 줄이 됐다. 회원 확인, 링크 파싱, 중복 거절, 관문 통과, 저장.
• 토너먼트 등록도 같은 골격으로 읽힌다. 두 경로가 관문을 공유하므로 세 번째 등록 경로가 생겨도 순서를 다시 외울 필요가 없다.
• ITEM-006 은 새 code 라 클라이언트가 모른다. 현재 클라는 이 code 들로 분기하지 않고 detail 만 표시하므로(client repo 에서 WISH-010·TOURNAMENT-037 참조 0건 확인) 화면은 그대로 동작하지만, 배포 전 공유가 필요하다.
• 파싱 위치를 역직렬화로 옮기는 안을 시도했다가 되돌렸다. 그 과정에서 LINK-001 이 COMMON-INVALID-INPUT 으로 뭉개지는 것을 발견해, 현재 계약(형식·스킴·빈 값·길이 네 갈래)을 HTTP 레벨 테스트로 고정해 두었다. 다음에 같은 시도를 할 때 이 테스트가 먼저 깨진다.
• 후속으로 남은 것: 탈퇴 유저 잔여 행의 배치 정리, 폴링이 안 올라온 key 를 7분 동안 초당 한 번씩 확인하는 문제(key 당 HEAD 약 400회), 컨트롤러가 SourcePlatformResolver 를 직접 부르는 계층 위반.

---

연관 이슈

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Team

Run ID: dd29bbdd-8989-47e5-b694-f2da2d401a20

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Discord 스레드 연동용 메타데이터입니다. discord-pr-bot 워크플로가 자동 생성하며, 수정·삭제하면 PR 과 Discord 알림 연동이 끊깁니다.