대량환불 설계 단일진실 확립과 대량 처리 버그 잡기

오늘 오후 작업은 "흩어진 것들을 한 곳으로" 라는 맥락 하나로 꿰인다. 설계 문서가 로컬 ~/Downloads에 떠돌고 있고, 참고 경로가 제각각이고, 코드 버그는 두 곳에서 터지고, GSC 툴링은 새 사이트를 빠뜨리는 상황—이 모든 게 "단일진실이 없는 상태"에서 오는 문제였다. 그래서 이 한 시간은 자연스럽게 정비 → 단일진실 확립 → 버그 수정 순으로 흘렀다.

1단계: 문서 정비 — 단일진실을 레포 안으로

작업 초반에 가장 먼저 건드린 건 CLAUDE.md였다. 참고 문서 경로가 절대경로(~/Downloads/...)와 상대경로가 뒤섞여 있었는데, .claude/ 기준 상대경로로 전부 통일했다. 이게 별거 아닌 것 같지만, 봇이 문서를 못 찾으면 그냥 틀린 걸 출력하거나 조용히 넘어가기 때문에 나중에 추적이 안 된다.

그 다음으로 즐거운 대량환불 관련 설계 문서들을 정리했다:

규격서 원본을 레포에 넣은 이유는 간단하다. "최신 버전"이 어디 있는지 물어볼 일이 없어야 하기 때문이다. 파일 하나 찾느라 슬랙 뒤지는 시간이 사실 제일 비싸다.

2단계: 버그 수정 — 대량 처리 계열 두 건

문서 정비가 끝나니 자연스럽게 실제 버그로 넘어갔다. 공교롭게도 둘 다 "대량 처리" 계열이었다.

클라이프스 대량발송 MAX CONN ERROR

동시 처리 수가 많을 때 커넥션 풀을 소진해버리는 문제였다. 대응은 두 방향으로 했다.

• 동시 처리 수 상한선 축소
• 실패 시 재시도 로직 추가 (지수 백오프 방식)

재시도 로직을 안 넣으면 한 번 터진 건은 그냥 유실되기 때문에, 이건 선택이 아니라 필수였다.

즐거운 대량환불 미리보기 무한로딩

이쪽은 증상이 모호해서 좀 걸렸다. 미리보기를 클릭하면 로딩이 끝나지 않는 현상인데, 처음엔 API 응답 문제로 봤다. 그런데 실제 원인은 JSP 쪽 escapeHtml 함수가 선언 없이 호출되는 ReferenceError였다. 자바스크립트 에러가 조용히 프로미스 체인을 끊어버리면서 완료 콜백이 영영 안 도는 것—전형적인 무한로딩 패턴이다.

// 문제: escapeHtml 미정의 상태로 호출
const safeHtml = escapeHtml(responseText);

// 수정: 함수 정의 추가 후 호출
function escapeHtml(str) { ... }
const safeHtml = escapeHtml(responseText);

증상이 네트워크처럼 보여서 삽질했지만, 결국은 단순한 ReferenceError였다는 게 교훈이다. 브라우저 콘솔 먼저 보는 습관을 다시 새겼다.

3단계: 인프라 자동화 — GSC와 kpopdex 봇

마지막으로 공통 인프라 쪽 두 건을 처리했다.

• GSC 자동 탐지: sites.list 기반으로 GSC 속성과 사이트맵 제출 대상을 자동 탐지하도록 변경. 새 사이트가 추가될 때 하드코딩 목록을 수동으로 갱신하지 않아도 된다. NEW-SITE-ONBOARDING.md와 hedvion-CLAUDE.md도 동시에 업데이트.
• kpopdex 봇 데이터 품질: 날짜 01-01 플레이스홀더 감지, 콜라보 아티스트 오귀속, 싱글곡을 앨범으로 잘못 분류하는 케이스에 대한 가드 조건 추가.

한 시간이지만 내용이 조밀했던 건, 결국 모든 작업이 "어딘가에 떠도는 것들"을 제자리로 끌어오는 작업이었기 때문이다. 문서든 코드든 경로든, 단일진실 하나 잡는 데 드는 비용이 나중에 헤매는 비용보다 항상 싸다는 걸 오늘도 확인했다.

🛒 이 글과 어울리는 추천 상품

• 모니터 쿠팡에서 보기 →
• 외장SSD 쿠팡에서 보기 →
• 사무의자 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.