정산 역분배 정책 문서 오류 정정

정산 도메인 문서를 건드리는 건 늘 조심스럽다. 코드보다 문서가 더 오래 살아남는 경우가 많고, 특히 정책 문서는 운영 팀이나 파트너 쪽에서 그걸 보고 의사결정을 내리기 때문에 오류 하나가 생각보다 멀리 퍼진다. 이번 작업은 정산 역분배 정책 문서에 잘못 기술된 내용을 정정하는 것. 역분배의 방식이 잔여 방식임에도 불구하고 다르게 서술되어 있었고, 이를 바로잡았다.

역분배와 잔여 방식, 왜 정확하게 구분해야 하는가

정산 시스템에서 분배 방식은 크게 두 갈래다. 선순위 항목부터 순서대로 할당하고 남는 금액을 처리하는 방식과, 전체 금액에서 공제 항목을 뺀 잔여분을 특정 주체에게 귀속시키는 방식. 역분배 잔여 방식은 후자에 가깝다. 공제 순서와 귀속 주체가 정해져 있고, 계산 결과의 기준이 "잔여분이 얼마냐"이기 때문에, 정책 문서에 방식이 틀리게 적혀 있으면 계산 로직을 검토하거나 재현하는 사람이 완전히 다른 전제를 갖고 시작한다.

실제로 운영 중 이슈가 터졌을 때 "정책 문서가 이렇게 되어 있으니 이렇게 동작해야 하는 거 아니냐"는 논의가 붙으면 디버깅보다 정책 해석 싸움에 시간이 더 걸린다. 그게 제일 피하고 싶은 상황이다.

이번 변경 내용

변경된 파일은 1개. 정책 문서 내에서 역분배 방식을 기술하는 항목이 잘못된 방식으로 기재되어 있었고, 잔여 방식이 올바른 정책임을 명시하는 방향으로 수정했다.

기능 코드 변경은 없다. 실제 정산 계산 로직은 이미 잔여 방식으로 구현되어 있었고, 문서만 현실을 따라가지 못하고 있었던 것. 이런 불일치가 쌓이면 나중에 "코드가 맞나, 문서가 맞나"를 판단하는 데 불필요한 비용이 든다.

커밋은 이 변경만 단독으로 담았다. 범위가 명확하고, 나중에 이 정정의 시점과 이유를 추적할 수 있어야 하기 때문에 다른 작업과 묶지 않았다.

docs(settlement): 역분배 정책 문서 오류 정정 - 잔여 방식이 정책임을 명시

Conventional Commits 형식을 쓰면 정책성 정정과 기능 변경이 나중에 로그에서 바로 구분된다.

git log --oneline --grep="docs(settlement"

이 명령 하나로 정산 도메인의 문서성 변경만 필터링해서 볼 수 있다.

정책 문서와 코드의 동기화 문제

사실 이 오류가 얼마나 됐는지 정확히 알 수 없다. 코드는 테스트가 있고 CI가 돌아서 눈에 보이는 형태로 틀리면 잡히지만, 정책 문서의 오류는 누군가 능동적으로 들여다보지 않으면 조용히 살아남는다.

이게 문서를 코드에서 생성하지 않는 이상 피하기 어려운 구조적 문제이기도 하다. 계산 로직이 변경됐을 때 문서를 함께 수정하는 흐름이 개발 프로세스에 들어가 있지 않으면, 문서는 점점 현실과 어긋난다.

지금 상황에서 가장 현실적인 건 PR 템플릿에 정책 관련 코드 변경 시 문서도 함께 확인한다는 체크리스트 항목을 넣는 것이다. 자동화보다 덜 강력하지만, 프로세스에 진입점을 만들어두면 최소한 "알면서 놓치는" 경우는 줄어든다.

다시 확인한 원칙들

로깅은 정책 적용 시점에도 남긴다. 코드 레벨에서 정책 적용 지점에 로그를 남겨두면, 나중에 특정 정산 건이 어느 방식으로 처리됐는지 트레이싱이 된다. 방식 자체가 바뀌는 경우뿐 아니라, 이번처럼 "원래부터 이랬어야 했던 것"을 정정하는 경우에도 적용 방식이 로그에 찍혀 있으면 이슈 재현이 훨씬 빠르다.

log.info("정산 역분배 방식 적용: id={}, type={}, method=residual", id, type);
// ... 처리 ...
log.info("정산 역분배 완료: id={}, result={}", id, result);

method=residual 같이 적용 방식을 명시해두면, 같은 코드가 여러 정책 모드를 지원할 때 로그만 봐도 어느 경로를 탔는지 알 수 있다.

단일 책임은 문서 구조에도 해당한다. 정책 문서 하나에 여러 분배 방식이 혼재하면 각 방식의 책임 범위가 흐려진다. 이번에 정정하면서 구조도 같이 손봤는데, 역분배 항목은 역분배끼리, 공제 규칙은 공제 규칙끼리 모이도록 정리했다. 내용이 두 배로 길어진 게 아니라 분류가 명확해진 것이다.

방어적으로 읽기. 코드를 방어적으로 작성하듯, 기존 문서도 방어적으로 읽어야 한다. "문서에 이렇게 적혀 있으니 이렇겠지"보다 "실제로 코드가 이렇게 동작하는데 문서는 맞나"를 먼저 확인하는 습관이 기술 부채를 줄인다. null 처리나 상태 검증을 외부 입력에 대해 기본값으로 의심하듯, 문서의 기술 내용도 구현과 대조해보는 것을 기본값으로 두는 게 맞다.

정산 도메인은 금액이 오가는 만큼 문서 오류 하나의 파급이 다른 도메인보다 클 수 있다. 이번 건은 기능에 영향이 없는 문서 정정이었지만, 그래서 오히려 더 조용히 오래 남아 있었을 가능성이 높다. 쌓이기 전에 발견해서 정리한 것, 그게 이번 작업의 전부다.