파트너 잔액 정산 감사 내부 정책 문서화

파트너 잔액 정산 감사 테이블(tb_partner_balance_audit)에 대한 내부 가이드를 작성했음. 변경된 파일은 설정/문서 2개. 딱 봐서는 작은 커밋인데, 이 작업이 없었으면 3개월 후 같은 팀 누군가가 코드 훑으면서 "이 컬럼이 왜 이렇게 설계됐지?"를 한참 파고 있을 상황이었다.

왜 지금 이 문서를 써야 했나

tb_partner_balance_audit는 파트너 정산 흐름에서 잔액 변동이 생길 때마다 기록을 쌓는 테이블이다. 구조 자체만 보면 평범한 audit log처럼 보이지만, 실제로는 수수료 계산 기준, 정산 주기 조건, 잔액 차감 순서 같은 비즈니스 결정이 테이블 설계 곳곳에 녹아 있다.

문제는 그 결정들이 코드 어딘가에 조용히 묻혀 있다는 것. SQL로 집계하는 방식이 왜 그 순서인지, 특정 상태에서 왜 집계를 건너뛰는지 - 코드만 봐서는 알 수가 없다. 작성한 본인조차 6개월 지나면 헷갈린다. 실제로 이번에 문서 작업 하면서 "아, 이게 이런 이유였지" 하고 다시 상기한 부분이 있었다.

비즈니스 규칙이 복잡할수록 코드와 주석만으로는 한계가 있다. 특히 금융/결제 도메인은 "왜 이렇게 구현했나"가 "어떻게 구현했나"만큼 중요하다. 규칙이 틀리면 숫자가 맞지 않고, 숫자가 맞지 않으면 신뢰가 무너진다. "대충 맞는 것 같다"고 넘어간 것들이 나중에 정산 오류로 돌아온다는 걸 이 도메인 작업 하면서 계속 체감 중이다.

내부 정책 문서를 쓰는 방식

이번에 작성한 가이드는 크게 세 영역으로 구성했다.

• 테이블 개요: 무엇을 기록하는 테이블인지, 어떤 이벤트에서 레코드가 생기는지
• 정책 결정 사항: 수수료 계산 기준, 상태 전환 조건, 예외 케이스 처리 방법
• 운영 규칙: 쿼리 작성 시 주의사항, 집계 시 반드시 들어가야 하는 필터 조건

"정책 결정 사항" 파트는 Why 중심으로 썼다. What은 코드에 이미 있다. 문서가 코드를 그대로 중복 설명하면, 나중에 둘 중 하나가 틀렸을 때 어느 쪽을 믿어야 하는지 더 헷갈린다. 그래서 문서에는 결정의 배경과 트레이드오프를 담으려고 했다.

예시를 넣는 게 생각보다 훨씬 효과적이다. "잔액 차감은 발생 순서 기준으로 처리한다"고 추상적으로 쓰는 것보다, 실제 케이스 하나를 들어 설명하는 게 이해가 빠르고 오해도 줄어든다. 특히 집계 쿼리처럼 잘못 쓰면 조용히 틀린 숫자를 반환하는 종류는, 안티패턴과 올바른 패턴을 대조해서 보여주는 게 주석 열 줄보다 낫다.

-- 잘못된 집계 패턴 (상태 필터 누락 - 취소/보류 건 포함됨)
SELECT SUM(amount)
FROM tb_partner_balance_audit
WHERE partner_id = ?;

-- 의도한 집계 패턴 (확정된 건만 산출)
SELECT SUM(amount)
FROM tb_partner_balance_audit
WHERE partner_id = ?
  AND status IN ('CONFIRMED', 'SETTLED')
  AND is_deleted = 0;

위처럼 "이렇게 쓰면 안 되고, 이렇게 써야 한다"를 같이 보여주면 새로 합류한 사람이 같은 실수를 반복할 가능성이 줄어든다. 코드 리뷰에서 잡아주는 것보다 문서에서 미리 알려주는 게 비용이 훨씬 싸다.

문서도 코드처럼 관리한다

이번 작업에서 설정/문서 파일 2개를 구현 커밋과 같이 묶었다. 문서를 코드와 같은 흐름에 넣는 이유가 있다. 정책이 바뀌면 코드와 문서가 동시에 바뀌어야 하는데, 별도로 관리하면 어느 순간 둘이 어긋난다. 어긋난 문서는 없는 것보다 나쁘다. 없으면 찾아보기라도 하지, 틀린 문서는 잘못된 확신을 준다.

팀 규모가 작을 때는 위키로 관리해도 어느 정도 돌아가지만, 시간이 쌓이면 "이 정책은 언제부터 적용됐지?"가 중요해진다. git blame으로 문서 변경 이력을 볼 수 있는 구조가 그때 가서 훨씬 편하다. 정책 변경에 날짜와 이유가 같이 기록되어 있으면, 이후 "왜 이렇게 바뀌었지?"라는 질문에 코드베이스 안에서 답이 나온다.

커밋 메시지도 "문서 추가"가 아니라 내용을 담으려 한다. git log --oneline으로 훑을 때 뭘 결정했는지 보여야 하기 때문이다. 나중에 bisect 하거나 특정 정책 변경 시점을 찾을 때 메시지가 의미 없으면 결국 diff를 하나씩 열어봐야 한다.

사내 서비스 특성상 기능 하나가 화면 버튼 하나 추가로 끝나는 경우는 거의 없다. SQL 집계, 상태 머신, 예외 처리, 렌더링, 권한 체크가 다 엮여 있어서 어느 하나만 빠져도 숫자가 안 맞거나 특정 케이스에서 이상하게 동작한다. 그 복잡도를 코드로만 관리하면 결국 머릿속 컨텍스트에 의존하게 되고, 그 컨텍스트는 시간이 지나면 증발한다.

문서화를 미루는 이유는 항상 비슷하다 - 지금 당장 기능 만들기가 바빠서. 근데 지금 10분 써두는 게 나중에 1시간 파는 것보다 낫다는 걸 경험으로 알기 때문에, 구현이 어느 정도 정리되면 문서 작업을 바로 같이 넣으려 한다. 작은 커밋 자주 하는 것처럼, 문서도 나중에 몰아쓰지 않고 결정이 신선할 때 짧게라도 남기는 게 습관이 됐음.