Plan the review order for a large pull request

1. 읽기 순서와 시간 예산

현재 제공된 목록만으로는 정확한 파일명과 변경 위치를 알 수 없으므로, 아래는 경로 기준의 리뷰 계획입니다. 실제 리뷰 전에는 PR diff와 각 파일명을 확인해야 합니다.

1순위 — 한 줄씩 검토: 약 70~90분

위험도가 가장 높은 순서입니다.

1. migrations/0023_add_refund_table.sql — 10분
2. src/payments/* 8개 — 30~40분
3. src/api/webhooks/* 5개 — 25~30분
4. src/components/checkout/* 중 환불 요청을 생성하거나 API를 호출하는 파일 — 5~10분

특히 다음을 확인합니다.

• 인증·권한 검사가 실제 환불 실행 직전에 있는가
• 환불 요청이 관리자 권한만으로 제한되는가
• 주문 소유자, 주문 상태, 결제 상태를 다시 서버에서 검증하는가
• 환불 금액이 클라이언트 입력을 신뢰하지 않는가
• 누적 환불액이 결제 금액을 초과하지 않는가
• 원 단위, 소수점, 반올림, 음수, 0원 처리 방식이 일관적인가
• 두 관리자가 동시에 환불할 때 초과 환불이 발생하지 않는가
• DB 트랜잭션, 행 잠금, 원자적 조건부 업데이트, 멱등성 키가 있는가
• 토스페이먼츠 요청 실패 후 재시도 시 이중 환불이 발생하지 않는가
• 웹훅 서명 검증이 raw request body 기준으로 수행되는가
• 서명 비교가 timing-safe 방식인가
• 웹훅 이벤트가 중복 수신되어도 상태가 중복 반영되지 않는가
• 웹훅만으로 환불 완료 상태를 신뢰해도 되는지, 주문·결제 식별자가 검증되는지
• 기존 KG이니시스 코드가 실제로 변경되지 않았는지뿐 아니라 공용 결제 추상화·DB 스키마·공용 미들웨어에 부작용이 없는지
• 마이그레이션의 금액 타입, 통화, nullable 여부, foreign key, unique/index, rollback 전략
• 기존 주문·결제 데이터가 새 테이블 제약조건과 호환되는지

2순위 — 주의 깊게 검토: 약 35~45분

• src/components/checkout/* 나머지 파일
• src/payments/*의 표시용·어댑터 보조 코드
• src/api/webhooks/*의 응답 포맷, 로깅, 공통 에러 처리
• 비즈니스 로직, 예외 경로, 재시도, 타임아웃, 부분 성공 처리
• 로딩 중 중복 클릭, 새로고침, 뒤로 가기, 네트워크 재시도
• 환불 요청 성공 후 UI 상태와 실제 서버 상태가 어긋나는 경우
• 관리자 화면에서 다른 주문의 환불 API를 호출할 수 있는지
• 민감한 결제 정보나 서명이 로그에 남는지
• 트랜잭션 경계와 외부 API 호출 순서

3순위 — 훑어보기: 약 15~20분

• tests/* 7개
• generated code
• 단순 포맷 변경
• 파일명 변경·이동
• 타입 선언이나 fixture 변경

테스트는 실행 결과만 보지 말고, 이번 변경의 위험을 실제로 검증하는 assertion인지 확인합니다.

4순위 — 건너뛰기

• vendored 코드
• lockfile

단, package.json은 완전히 건너뛰지 않고 3~5분 확인합니다.

• 새 결제 SDK나 웹훅 관련 패키지가 추가되었는가
• postinstall/build/test script가 바뀌었는가
• 기존 의존성 버전이 의도치 않게 바뀌었는가
• 패키지 추가가 PR 설명의 범위에 맞는가

2. 첫 번째 그룹의 파일별 확인 항목

정확한 파일명이 없으므로 현재는 각 경로의 모든 파일을 개별 검토 대상으로 잡습니다.

migrations/0023_add_refund_table.sql

• 환불 레코드와 원 결제·주문 간 관계가 명확한가
• 하나의 환불 요청을 식별할 unique key가 있는가
• 외부 토스 환불 ID 또는 멱등성 키를 저장하는가
• 금액 타입이 부동소수점이 아닌 정확한 숫자 타입인가
• 누적 환불 계산에 필요한 상태·금액·시각이 모두 저장되는가
• 동시 업데이트를 방지할 index/constraint가 있는가
• 이미 존재하는 데이터에 안전하게 적용되는가
• 마이그레이션 재실행, 배포 중 구버전·신버전 코드 공존을 견디는가
• rollback 또는 복구 계획이 있는가

src/payments/* 8개

각 파일에서 다음을 확인합니다.

• 환불 가능 금액 계산의 단일 기준이 어디에 있는가
• 결제금액 - 기존 환불액 계산이 원자적으로 수행되는가
• 기존 환불 상태와 진행 중 상태를 어떻게 구분하는가
• 동시에 두 요청이 들어올 때 어느 시점에 금액을 예약하는가
• 토스 API 호출 전후 DB 상태가 어떻게 전이되는가
• 외부 API timeout, 4xx, 5xx, 부분 응답을 어떻게 처리하는가
• 재시도 시 동일 요청으로 인식되는가
• 토스 전용 구현이 KG이니시스 코드나 공용 인터페이스에 영향을 주는가
• 결제 제공자·주문·환불 레코드의 식별자를 서로 검증하는가
• 권한 검사가 서비스 계층에도 존재하는가
• 금액을 클라이언트에서 받은 값 그대로 사용하지 않는가

src/api/webhooks/* 5개

• 서명을 검증하기 전에 body가 파싱·재직렬화되지 않는가
• 서명 키와 비교 방식이 안전한가
• 잘못된 서명에 대해 상태 변경이나 부작용이 먼저 발생하지 않는가
• 이벤트가 중복·순서 뒤바뀜·지연 수신되어도 안전한가
• 웹훅의 주문 ID, 결제 ID, 금액이 내부 데이터와 일치하는가
• 웹훅으로 환불 완료를 처리할 때 권한 우회가 생기지 않는가
• 실패 시 제공자 재전송을 고려한 HTTP 응답과 재처리가 가능한가
• 민감한 payload와 서명이 로그에 남지 않는가
• 존재하지 않는 주문·이미 종료된 환불·취소된 이벤트의 처리 방식이 명확한가

환불 요청을 호출하는 src/components/checkout/*

• 버튼이 권한 없는 사용자에게 노출되거나 호출 가능하지 않은가
• 버튼 중복 클릭을 막는가
• 현재 환불 가능 금액을 서버에서 다시 확인하는가
• 실패·진행 중·완료 상태가 구분되는가
• 사용자에게 “환불 요청 접수”와 “환불 완료”를 혼동시키지 않는가
• 브라우저에 비밀키나 관리자용 인증정보가 노출되지 않는가
• 주문 ID를 URL·DOM 상태에서 바꿔 다른 주문을 요청할 수 없는가

3. 범위 확인

PR 설명은 “토스페이먼츠 부분환불 추가”와 “체크아웃 페이지 환불 요청 버튼”입니다. 따라서 다음은 범위 내일 가능성이 높습니다.

• 토스 환불 API 어댑터
• 환불 누적 금액 및 상태 관리
• 환불 웹훅
• 환불 테이블 마이그레이션
• 해당 기능에 필요한 체크아웃 UI와 API 연결
• 관련 테스트와 최소한의 의존성 추가

다음은 범위 밖일 가능성이 있으므로 diff에서 별도 확인해야 합니다.

• KG이니시스 파일의 실제 변경
• 공용 결제 인터페이스를 넘어선 기존 결제 흐름 변경
• 체크아웃의 결제·배송·쿠폰·회원가입 동작 변경
• 환불과 무관한 UI 리디자인
• 기존 webhook 이벤트 처리 방식의 광범위한 변경
• unrelated dependency upgrade
• 빌드·lint·배포 스크립트 변경
• 데이터 정리, 기존 주문 상태 일괄 변경, 운영용 backfill
• 새 관리자 권한 체계나 인증 미들웨어 변경
• 테스트 fixture가 기존 결제 테스트의 의미를 바꾸는 변경

특히 37개 파일, 1,842줄이면 “기존 KG 연동은 건드리지 않았다”는 설명과 실제 diff가 일치하는지 먼저 확인해야 합니다. 파일 목록만으로는 공용 모듈을 통한 간접 변경 여부를 판단할 수 없으므로, 실제 diff와 import 그래프가 필요합니다.

4. 저자에게 먼저 물을 질문

1. 환불 요청 버튼은 일반 고객용인가요, 관리자용인가요? PR 설명의 “관리자 두 명”과 체크아웃 페이지가 어떻게 연결되는지 설명해 주세요.
2. 환불 요청 시점의 최종 진실은 내부 DB인가요, 토스 API인가요, 웹훅인가요?
3. 두 관리자가 동시에 같은 주문을 환불하면 어느 요청이 성공해야 하며, 두 요청 모두 토스에 전달되지 않도록 어떤 원자성 보장을 사용했나요?
4. 환불 요청 재시도와 토스 API timeout을 어떻게 멱등적으로 처리하나요?
5. 부분환불 누적 금액 계산에서 금액 단위와 반올림 규칙은 무엇인가요?
6. 웹훅 서명 검증에 사용하는 원본 body, 키, 알고리즘, 키 회전 방식은 무엇인가요?
7. 토스 웹훅이 중복되거나 순서가 뒤바뀌어 도착하면 어떻게 처리하나요?
8. 환불 가능한 주문 상태와 환불 불가능한 상태를 명시해 주세요.
9. 환불 요청이 접수됐지만 토스 응답이 유실된 경우 운영자가 어떻게 재처리하거나 확인하나요?
10. KG이니시스 코드에 영향을 주지 않는다는 보장은 어떤 테스트나 구조적 경계로 확인했나요?
11. 이번 마이그레이션은 기존 데이터에 대해 backfill이 필요한가요?
12. 환불 기능을 일반 체크아웃 사용자에게 노출하는 것이 의도된 제품 정책인가요?

5. 변경 대비 테스트가 커버하지 않을 가능성이 높은 부분

현재 테스트 파일의 내용이 없으므로 확정할 수는 없지만, 반드시 테스트 존재 여부를 확인할 영역은 다음과 같습니다.

• 기존 환불액과 새 환불액의 합이 정확히 결제액과 같은 경우
• 1원 초과 환불이 차단되는 경우
• 0원·음수·소수점·큰 금액 입력
• 동일 주문에 대한 동시 환불 요청
• 같은 멱등성 키로 반복 요청
• 외부 API timeout 후 재시도
• 외부 API 성공 후 내부 DB 저장 실패
• 내부 DB 저장 후 응답 유실
• 중복 웹훅
• 잘못된 서명과 변조된 body
• 올바른 서명이지만 다른 주문 ID·금액을 가진 웹훅
• 웹훅 순서 역전
• 권한 없는 사용자와 다른 주문 ID를 조작한 사용자
• KG이니시스 결제 흐름의 회귀
• 구버전 애플리케이션과 마이그레이션 직후 코드의 공존
• UI에서 빠른 중복 클릭과 새로고침
• “환불 요청 접수”와 “환불 완료” 상태의 차이

6. 여러 PR로 나눴어야 하는가

그렇습니다. 현재 범위는 최소 세 개의 관심사가 섞여 있습니다.

1. 데이터 모델·마이그레이션 PR

   • migrations/0023_add_refund_table.sql
   • 환불 상태와 금액을 저장하는 도메인 모델
   • 인덱스·제약조건·backfill 검토

2. 결제 도메인·토스 연동 PR

   • src/payments/*
   • 환불 금액 계산
   • 동시성·멱등성
   • 토스 API 호출과 오류 처리

3. 웹훅·UI PR

   • src/api/webhooks/*
   • 서명 검증과 이벤트 처리
   • src/components/checkout/*
   • 환불 요청 버튼과 상태 표시

가능하다면 테스트도 각 PR에 함께 넣되, 토스 sandbox 통합 테스트는 별도 통합 테스트 PR 또는 별도 커밋으로 분리하는 편이 좋습니다.

지금 분리하기 어렵다면 이번 리뷰에서는 최소한 리뷰 순서를 위 세 경계로 나누고, 각 경계 사이의 계약—환불 상태 전이, 멱등성 키, 금액 단위, 웹훅 의미—를 명시적으로 문서화해야 합니다. 다음번에는 기능 구현, 외부 결제 연동, 관리자/UI 변경을 한 PR에 함께 넣지 않는 것이 좋습니다.