Change untested code safely

1. 변경 전 현재 동작 고정 방법

가장 먼저 운영 정산을 건드리지 않는 읽기 전용 재현 모드를 추가하거나, 기존 계산 로직을 호출해 결과만 저장하는 얇은 실행 경로를 만듭니다.

저비용 순서로는 다음과 같습니다.

1. 최근 1~2개월의 실제 매출 입력을 복사해 별도 환경에서 실행합니다.
2. 파트너사별로 다음 결과를 구조화된 로그나 JSON으로 저장합니다.
   • 정산 기준일
   • 입력 매출 합계
   • 수수료·공제 금액
   • 최종 정산 금액
   • 엑셀 출력 행
   • settlements 기록 예정 값
3. 기존 운영 엑셀과 settlements 데이터를 기준으로 재현 결과를 대조합니다.
4. 대표 케이스를 특성화 테스트로 고정합니다.
   • 일반 국내 파트너
   • 매출이 없는 파트너
   • 소수점 금액
   • 수수료가 있는 파트너
   • 재실행
   • 일부 파트너 처리 실패
   • 날짜 경계가 새벽 2시와 겹치는 경우
5. 테스트가 어려운 부분은 최소한 “입력 fixture → 현재 출력 snapshot” 형태로 저장합니다.

현재 결과와 실제 DB 기록이 이미 일치하는지 먼저 확인해야 합니다. 일치하지 않는다면 신규 기능보다 먼저 원인을 밝혀야 합니다.

운영에서는 처음부터 해외 파트너를 활성화하지 않고 다음과 같이 둡니다.

• foreign_settlement_enabled = false
• 또는 해외 파트너 목록을 명시적인 allowlist로 관리
• 계산 결과는 실제 엑셀·DB에 반영하지 않고 shadow 결과로만 기록하는 모드 제공

2. 현재 코드가 하는 일과 불확실한 점

설명으로 확실히 알 수 있는 현재 흐름은 다음과 같습니다.

1. 매일 새벽 2시 크론이 batch/settlement.php를 실행합니다.
2. 파트너사별 매출을 조회합니다.
3. 정산 금액을 계산합니다.
4. 엑셀 파일을 출력합니다.
5. settlements 테이블에 결과를 기록합니다.
6. 이 결과가 실제 입금액으로 이어집니다.

다만 다음은 아직 확인되지 않은 핵심 불확실성입니다.

• 매출 금액의 기준 통화와 저장 단위가 무엇인지
• 정산 기준일의 시간대가 서버 시간인지, 한국 시간인지, 파트너사 시간인지
• “그날 환율”의 정의가 무엇인지
  • 매매기준율
  • 고시 환율
  • 특정 금융기관 환율
  • 일일 종가
  • 영업일이 아닌 날의 직전 환율
• 환율을 어디서 가져오는지와 외부 API 장애 시 동작
• 환율을 실행 시점에 조회하는지, 사전에 저장하는지
• 환율의 소수점 정밀도와 원화 반올림 규칙
• 수수료·세금·공제 전에 환산하는지, 후에 환산하는지
• settlements의 중복 방지 키와 재실행 동작
• 엑셀과 DB 중 어느 것이 입금의 기준인지
• 중간 실패 시 이미 처리된 파트너를 되돌리는지
• 기존 국내 파트너 계산에 숨은 예외 규칙이 있는지
• 크론이 동시에 두 번 실행될 가능성이 있는지

특히 환율 기준일, 반올림 위치, 재실행 방식은 금액 오류로 직결됩니다. 이 설명만으로 임의로 정하면 안 됩니다. 이 불확실성 자체가 현재 가장 큰 위험입니다.

3. 가장 작은 변경과 테스트가 있을 때의 더 나은 변경

가장 작은 변경

기존 국내 파트너 처리 흐름은 그대로 두고, 파트너별 통화만 분기합니다.

• 국내 파트너: 기존 계산 로직 그대로 실행
• 해외 파트너:
  1. 매출 원천 통화를 확인
  2. 승인된 환율 출처에서 기준일 환율을 가져옴
  3. 기존 정산 규칙의 어느 시점에 환산할지 명시
  4. 원화로 환산
  5. 정해진 정밀도와 반올림 규칙을 적용
  6. 엑셀과 settlements에 환율·원천 통화·환산 금액도 함께 기록

단, 초기 배포에서는 해외 파트너 계산 결과를 실제 정산에 사용하지 않고 shadow 결과로만 비교합니다. 충분히 검증된 뒤 allowlist로 한 파트너씩 활성화하는 방식이 안전합니다.

테스트가 충분하다면 더 나은 변경

정산 계산을 다음처럼 작은 순수 함수 단위로 분리합니다.

• 입력 매출과 수수료 → 파트너 통화 기준 정산액
• 기준일과 환율 데이터 → 원화 환산액
• 환산액 → 엑셀 행과 DB 기록 모델
• 정산 실행 → 저장 및 외부 후속 처리

그리고 각 계산에 다음 정보를 불변으로 남깁니다.

• 원천 통화 금액
• 적용 환율
• 환율 출처와 조회 시각
• 적용 기준일
• 환산 전·후 금액
• 반올림 규칙과 결과
• 계산 로직 버전

이렇게 하면 나중에 환율 제공처나 계산 규칙이 바뀌어도 과거 정산을 재현할 수 있습니다. 다만 테스트가 없는 상태에서 이 구조 분리와 기능 변경을 동시에 진행하면 위험하므로 단계적으로 해야 합니다.

4. 변경 순서

1단계: 관찰 가능성 확보

기존 코드를 바꾸되 계산 결과는 바꾸지 않습니다.

• 입력과 출력 로그 추가
• 실행 ID 추가
• 파트너별 처리 상태 기록
• dry-run 또는 shadow 실행 추가
• 중복 실행 감지와 실패 지점 기록 추가

확인할 것:

• 기존 운영 결과와 로그가 일치하는가
• 모든 파트너가 누락 없이 처리되는가
• 재실행 시 중복 기록이 생기는가
• 엑셀과 DB 결과가 일치하는가

2단계: 기존 동작을 구조만 정리

행동은 유지한 채 다음만 분리합니다.

• 환율과 무관한 기존 국내 정산 계산
• 파트너 입력 조회
• 결과 생성
• 엑셀 출력
• DB 저장

확인할 것:

• 동일 입력에 대해 변경 전후 금액이 바이트 또는 허용 오차 내에서 동일한가
• 기존 파트너별 결과 snapshot이 변하지 않는가
• 예외와 종료 코드가 기존과 동일한가

3단계: 해외 환산을 shadow 모드로 추가

해외 파트너에 대해 계산하되 실제 입금용 엑셀과 settlements에는 반영하지 않습니다.

• 승인된 환율을 조회
• 환율 조회 실패 시 해외 정산을 보류
• 계산 결과를 별도 shadow 테이블 또는 별도 파일에 기록
• 기존 국내 파트너 결과에는 영향이 없도록 함

확인할 것:

• 환율 기준일이 의도와 일치하는가
• 환율 API 응답 단위와 통화쌍이 맞는가
• 반올림 및 소수점 처리가 정확한가
• 같은 입력과 같은 환율로 재실행했을 때 같은 결과가 나오는가
• 해외 결과가 수작업 계산 및 파트너 원장과 일치하는가

4단계: 한 파트너 또는 제한된 금액으로 활성화

명시적 allowlist를 사용해 가장 낮은 위험의 해외 파트너부터 활성화합니다.

• 상한 금액 또는 상한 파트너 수 설정
• 예상 금액과 실제 생성 금액의 차이 검사
• 차이가 임계치를 넘으면 전체 해외 정산 중단
• 국내 정산은 독립적으로 계속할지 정책을 명확히 결정

확인할 것:

• 실제 엑셀과 DB 기록이 일치하는가
• 입금 파일과 정산 테이블의 합계가 일치하는가
• 담당자가 입금 전 승인할 수 있는가
• 실패 시 해당 파트너만 보류되는가

5단계: 점진적으로 확대

며칠간 결과를 확인한 뒤 allowlist를 확대합니다. 충분한 기간 동안 기존 국내 정산의 결과가 변하지 않았는지도 확인합니다.

5. 되돌릴 수 없는 부분과 별도 계획

실제 입금으로 이어지는 엑셀 또는 후속 파일

이 파일을 생성·전달하면 사실상 되돌릴 수 없습니다.

별도 계획:

• 초기에는 shadow 파일만 생성
• 실제 입금용 파일 생성 전 승인 단계 추가
• 파일명에 실행 ID와 기준일 포함
• 승인 전 자동 합계 검증
• 승인 후 파일을 불변 보관
• 이미 전달된 파일은 “삭제 후 재생성”하지 말고 정정·취소 절차를 별도로 사용

settlements 기록

이미 입금액의 기준으로 사용될 수 있으므로 단순 덮어쓰기는 위험합니다.

별도 계획:

• 기존 행을 수정하지 않음
• 정산 실행 ID와 계산 버전 추가
• 오류 시 reversal 또는 adjustment 행으로 보정
• 동일 파트너·기준일의 중복 기록 차단
• 배포 전 백업과 복구 리허설 수행

외부 환율 API 호출

외부 API는 응답값과 가용성이 통제되지 않습니다.

별도 계획:

• 승인된 제공처와 통화쌍 고정
• 응답 환율을 즉시 원본 형태로 저장
• 타임아웃·재시도 횟수 제한
• 환율이 없거나 비정상이면 정산하지 않고 보류
• 임의의 마지막 환율이나 0을 자동 사용하지 않음
• API 변경이나 장애 시 수동 환율 입력 절차 마련

이미 잘못된 금액이 생성된 경우

자동 롤백이 없으므로 배포 전에 수동 비상 절차를 정해야 합니다.

• 정산 파일 전달 전 중지 담당자와 연락망 지정
• DB 기록의 보정 방식 정의
• 파트너 입금 전 검증 마감 시각 지정
• 오차 발견 시 신규 정산을 중지하고 adjustment로 처리
• 원본 입력, 환율, 계산 결과, 파일을 모두 보존

6. 각 단계 후 확인할 것

모든 새벽 배포 후 최소한 다음을 확인합니다.

• 실행 ID와 기준일이 올바른가
• 예상 파트너 수와 실제 처리 수가 같은가
• 국내 파트너 총액이 배포 전과 같은가
• 해외 파트너별 원천 통화 금액, 환율, 원화 금액이 기록됐는가
• 엑셀 합계와 settlements 합계가 같은가
• 환율 누락·0·비정상 급등 값이 없는가
• 중복 실행이나 중복 정산이 없는가
• 실패한 파트너가 성공으로 표시되지 않았는가
• 외부 API 응답과 조회 시각이 보존됐는가
• 입금 파일이 실제로 전달되기 전에 사람이 결과를 검토했는가

핵심 원칙은 먼저 기존 국내 정산을 재현 가능하게 고정하고, 그 다음 구조만 분리하며, 해외 환산은 shadow 모드에서 검증한 뒤 제한적으로 활성화하는 것입니다. 환율 기준일·반올림·재실행·입금 파일 전달 시점이 확정되기 전에는 실제 해외 정산을 켜면 안 됩니다.