웹POS 결제 연동 전체 스택을 형상관리에 정식 편입

결제 연동 레이어에서 자산 보존(preservation) 성격의 커밋이 올라왔다. 신규 기능 추가가 아니라, 이미 어딘가에 흩어져 있거나 유실 위기에 있던 코드를 프로젝트 안으로 정식 편입시키는 작업이었다.

왜 "자산 보존"이라는 표현을 썼나

커밋 메시지에 "백엔드 자산 보존" 이라는 단어가 들어간 건 꽤 의미심장하다. 일반적인 feat이나 fix 커밋과 다르게, 이건 이미 누군가 작성해 둔 코드가 공식 형상관리 바깥에 있었다는 뜻이다. 로컬 브랜치에만 존재하거나, 다른 프로젝트 모듈에 임시로 붙어 있거나, 혹은 Slack/메모 등 어딘가에 파편으로 떠돌고 있었을 가능성이 높다.

결제 연동 코드는 특히 이런 상황이 자주 생긴다. PG사/VAN사 API 스펙이 중간에 바뀌거나, 파일럿 개발이 끝난 뒤 정식 통합이 늦어지면서 "만들어두긴 했는데 아직 안 올라간" 상태로 수 주씩 방치되는 일이 적지 않다. 그 사이에 담당자가 바뀌거나 브랜치가 꼬이면, 그 코드는 사실상 유실된다. 그래서 나는 이런 작업을 형상관리로의 귀환이라고 부르는데, 이번 커밋이 딱 그 케이스였다.

이번에 편입된 파일들

변경된 파일을 보면 구조가 꽤 정형화되어 있다.

그리고 커밋 메시지에 sqlmap + SQL 도 포함됐다고 명시돼 있으니, MyBatis 매퍼 XML과 쿼리도 함께 들어온 것이다. 즉 이번 작업은 단순히 API 클라이언트 하나를 올린 게 아니라, 이 연동 기능이 동작하는 데 필요한 레이어 전체 스택을 한 번에 형상관리에 안착시킨 것이다.

연동 레이어 구조 (이번에 편입된 범위)

[외부 웹POS API]
      ↑↓
ZlgoonWebPosClient          ← HTTP 통신 담당
      ↑↓
ExchangeBarcode/Cancel DTO  ← 요청/응답 직렬화
      ↑↓
SqlMap XML + SQL            ← 거래 이력/상태 영속화

Client → DTO → DB 레이어까지 수직으로 다 들어왔다는 게 포인트다. 한 레이어만 있으면 나머지가 없어서 빌드/테스트가 안 되고, 결국 "살아있는 코드"가 되지 못한다. 이번에 한 번에 세트로 올린 건 그 맥락에서 올바른 판단이었다.

팀 관점에서 이런 작업이 왜 중요한가

솔직히 이런 커밋은 리뷰어 입장에서 반응이 엇갈린다. 코드 변경 자체보다 파일 수가 많고, 각 파일이 완전히 새로 추가되는 경우가 많아서 diff가 크게 보인다. 그런데 실질적인 로직 변경은 없고, 기존 코드를 "옮겨온" 것이라면 리뷰 포인트가 애매해진다.

내가 팀에서 강조하는 건 이런 케이스를 별도 커밋으로 분리하는 습관이다.

• 자산 보존(코드 이관/편입) 커밋 → 로직 무변경, 리뷰어에게 "이건 내용 변경 없음" 명시
• 이후 실제 수정/개선 커밋 → 별도로 작성

이렇게 하면 나중에 git blame이나 git log로 추적할 때 "이 코드가 언제, 왜 지금 이 자리에 왔는지"를 명확하게 알 수 있다. 이번 커밋처럼 메시지에 "자산 보존"을 명시한 것 자체가 이미 그 의도를 충분히 표현한 좋은 사례다.

네트 취소(망취소) DTO가 따로 있다는 것

ExchangeNetCancelRequest가 별도로 존재한다는 점도 눈에 띈다. 일반 취소(ExchangeCancelRequest)와 망취소가 분리된 구조인데, 이건 결제 도메인에서 꽤 중요한 분기점이다.

• 일반 취소: 거래가 정상 완료된 이후 취소 요청
• 망취소(Net Cancel): 요청은 보냈으나 응답을 못 받은 상황에서의 원상복구

두 케이스를 DTO 레벨에서 명확히 분리해 두면, 서비스 레이어에서 의도치 않게 잘못된 취소 흐름을 타는 걸 컴파일 타임에 어느 정도 막을 수 있다. 만약 하나의 DTO에 isNetCancel 같은 플래그를 넣었다면 런타임 오류나 흐름 분기 오류가 훨씬 더 많이 발생했을 것이다. 설계 측면에서 올바른 선택이라고 본다.

이번 작업 자체는 "새로운 기능을 만든" 커밋이 아니다. 그런데 이런 자산 보존 커밋이 제때 안 올라가면, 나중에 훨씬 더 큰 비용을 치른다. 코드를 다시 짜거나, 맥락 없이 파일이 갑자기 튀어나오거나, 최악의 경우 그 코드가 영원히 사라진다. 팀장 입장에서는 이런 커밋이 PR로 올라올 때 오히려 "잘했다"고 적극적으로 피드백하는 게 맞다. 눈에 잘 안 보이는 작업일수록 인정받아야 팀이 꾸준히 이런 위생 작업을 유지한다.

끝.