Fintech Engineering Handbook – Money‑Critical 시스템 구축을 위한 종합 가이드

Fintech Engineering Handbook – Money‑Critical 시스템 구축을 위한 종합 가이드

TL;DR

Fintech Engineering Handbook은 돈을 기본 데이터 모델로 하는 소프트웨어를 구축하는 데 필요한 불변·감사 가능·신뢰‑없음 패턴을 정리합니다. 여기에는 돈 표현부터 원장 설계, 외부 연동, 접근 제어, 테스트까지 모든 내용이 세 가지 핵심 원칙과 연결됩니다.

이 핸드북을 누가 사용해야 할까요?

  • 신입 핀테크 직원 – 도메인‑특화 패턴과 용어에 대한 속성 강의.
  • 경험 많은 핀테크 엔지니어 – 구체적인 문제 해결을 위한 레퍼런스이자 팀 간 공통 언어.
  • 핀테크 외 엔지니어 – 일반 웹 애플리케이션과 왜 돈 시스템이 다른지에 대한 입문서.

기여를 환영합니다; 문서는 지속적으로 진화할 예정입니다.

핵심 원칙

원칙 강제하는 내용 일반적인 메커니즘
데이터를 임의로 생성하지 않음 돈은 임의로 나타나거나 사라질 수 없습니다. 멱등성 키, 중복 제거, 복식부기, 예약.
데이터를 잃지 않음 모든 금전 이벤트는 영구 저장되고 추적 가능해야 합니다. 고정밀 타입, 최소 1회 전달, 이벤트 소싱, 불변 감사 로그.
신뢰하지 않음 외부 제공자나 내부 컴포넌트를 신뢰한다고 가정하지 않습니다. 웹훅 서명, 스키마 검증, 교차 소스 조정, 명시적 실패 처리.

돈 표현하기

정밀도 처리

  • 부동소수점 피하기 – 비결정적 반올림을 초래합니다.
  • 정수 마이너 유닛 사용 – 법정 화폐는 가장 작은 단위(예: €12.34를 1234 로 저장)로 저장합니다. 암호화폐는 토큰 소수점이 최대 18자리까지 될 수 있어 가변 폭 정수가 필요합니다.
  • 가변 정밀도 라이브러리(BigDecimal 등)는 FX나 가격 산출 같은 중간 계산에 이상적입니다.
  • 유리수는 정밀도 손실이 없지만 속도가 느리고 직렬화가 어렵습니다.

핵심 규칙: 금액은 가장 작은 단위의 정수로 저장하고, 고정밀 타입으로 계산합니다; 직렬화 시 문자열이나 정수로 저장하고 JSON 숫자로는 절대 저장하지 마세요.

반올림 전략

  1. 명시적 반올림 – 모든 나눗셈, 변환, 수수료, 정밀도 변경 시 반드시 반올림을 수행합니다.
  2. 비즈니스‑주도 방향 – 과다 지출을 방지하려면 내림, 통계적 공정성을 위해 반올림 짝수 등을 선택합니다; 선택은 세금·법적 결과에 영향을 줄 수 있습니다.
  3. 가능한 늦게 반올림 – 영구 저장하거나 사용자에게 보여줄 때까지 전체 정밀도를 유지합니다.
  4. 잔여금 처리 – 금액을 분할할 때 발생하는 반올림 잔여금을 별도 계정에 기록해 잔액 드리프트를 방지합니다.

핵심 규칙: 반올림은 절대로 돈을 만들거나 파괴해서는 안 됩니다; 잔여금은 전용 계정에 보관합니다.

통화 처리

  • 금액과 통화를 함께 Money 타입에 담습니다.
  • 서로 다른 통화 간 산술 연산을 금지하고, 변환은 명시적이고 제어된 환율을 사용합니다.
  • 시스템 경계에서 통화 코드를 검증된 목록과 대조합니다.
  • 암호화폐는 ISO 4217 코드 대신 (네트워크, 계약 주소) 로 자산을 식별합니다.

FX 환율

  • 환율은 방향성이 있습니다 – EUR/USD ≠ USD/EUR; 매도·매수 스프레드 때문에 역환율은 단순 역수로 구할 수 없습니다.
  • 타임스탬프가 중요 – 실시간 평가는 현재 시점 환율을, 세금·보고용 평가는 가치일 환율을 사용합니다.
  • 거래 환율(실제 변환에 사용)과 참조 환율(중간시장·중앙은행 등) 를 구분합니다.
  • 단일 표준 소스는 없으며, 항상 감사 가능하도록 출처 식별자를 저장합니다.

돈 기록하기: 원장

복식부기

  • 모든 항목은 동일 금액을 대변 계정에서 차변 계정으로 이동시켜 장부가 항상 균형을 이루게 합니다.
  • 잔액은 파생값이며 직접 저장되지 않습니다.
  • 계정 유형(자산, 부채, 자본, 수익, 비용)은 회계 방정식 자산 = 부채 + 자본 을 강제합니다.
  • 수정은 보상 항목을 추가하는 방식으로 수행하고, 원본 행은 불변으로 유지합니다.

시간 차원

  • 가치 시점 – 경제적 사건이 발생한 시점.
  • 입력 시점 – 시스템에 사건이 기록된 시점.
  • 정산 시점 – 실제 자금 이체가 일어난 시점(보통 T+X 형태).
  • 세 가지 타임스탬프를 모두 기록해야 복원 가능성을 유지합니다.

감사 및 감사 로그

  • 무엇을, 언제, 누가/무엇을, 왜 를 모든 변경에 대해 캡처합니다 – 잔액 업데이트뿐 아니라 설정 변경, 권한 업데이트, 규칙 평가도 포함합니다.
  • 이벤트 소싱 은 이벤트 로그를 진실의 원천으로 삼아 감사 로그를 기본으로 만듭니다.
  • 불변성 – 추가 전용 저장소, 런타임 검증, 해시 체인 등으로 무단 편집을 방지합니다.
  • 취소 vs. 수정 – 취소는 원본 항목을 무효화하고, 수정은 순 차이를 게시해 히스토리를 보존합니다.

돈 흐름 실행하기

불변 조건

  • 구성 단계(타입‑안전 생성자, DB 제약)와 런타임(assertion, 프로퍼티 기반 테스트), 사후(조정 작업) 로 핵심 속성을 보장합니다.

자금 예약

  • 외부 서비스를 호출하기 전에 자금을 예약하고, 총액과 사용 가능액(available = total – reserved)을 구분합니다.
  • 예약은 선형화되어야 하며 항상 해제하거나 정산되어야 하여 교착 상태를 방지합니다.

초과 인출 처리

  • 의도된 초과 인출(신용 상품)과 비의도적 초과 인출(외부 불일치) 을 구분합니다.
  • balance ≥ 0 을 강제 타입 제약으로 구현하지 말고, 불변 조건으로 검증하고 위반 시 명시적으로 처리합니다.

멱등성

  • 명시적 멱등성 키 를 연산 및 클라이언트에 스코프화합니다.
  • 중복 전달은 하나의 논리적 효과로 취급하고, 재시도는 하나의 결과로 수렴해야 합니다.
  • 멱등성은 시스템의 입·출 양쪽 모두에 적용합니다.

완전 복구 가능성

  • 장시간 실행 흐름을 내구성 상태 머신 으로 모델링하고, 각 단계 후 진행 상황을 영구 저장합니다.
  • 외부 드라이버는 미완료 흐름을 감지하고 재개해야 합니다.
  • 모든 단계는 멱등 해야 하며, 외부 효과는 복구 불가능하므로 전진 재시도하거나 보상 작업(사가 패턴)을 발생시킵니다.

외부 세계와의 연동

API 사용

  • 응답을 강력히 검증하고, 스키마 변경 시 크게 실패하도록 합니다.
  • 모든 호출이 실패할 수 있다는 전제 하에 재시도, 타임아웃, 지수 백오프를 구현합니다.
  • 요청·응답을 모두 영구 저장 – 감사 로그의 일부가 되며 재처리에도 활용됩니다.
  • 중요한 경로에는 제공자 이중화 를 고려하되 복잡성이 증가함을 인지합니다.

웹훅 처리

  • 순서·유효성·전달 보장을 신뢰하지 않는다.
  • 원시 페이로드 를 저장하고 서명(HMAC 또는 비대칭) 을 검증합니다.
  • 웹훅은 트리거 로만 사용하고, 제공자 API 로 권위 있는 상태를 다시 조회합니다.
  • 빠르게 2xx 응답을 반환하고 비동기 처리하며, 멱등성을 보장합니다.

신뢰성 있는 알림(Outbox / CDC)

  • 상태 변화와 함께 트랜잭션ally 이벤트를 발행(Outbox 테이블)하거나 변경 데이터 캡처(CDC) 로 커밋된 행을 스트리밍합니다.
  • 전달은 최소 1회 이며, 소비자는 안정적인 이벤트 ID 로 중복을 제거해야 합니다.

조정(Reconciliation)

  • 내부 기록과 외부 소스를 주기적으로(시간당, 일별 등) 비교합니다.
  • 제공자‑생성 ID 로 매칭하고, 없을 경우 금액+타임스탬프 등 히스토리 기반 휴리스틱을 사용합니다.
  • 불일치는 수정 항목 또는 재처리로 해결하고, 히스토리 데이터를 덮어쓰지는 않습니다.

제어와 접근

업무 분리 & 4인 눈

  • 자금 이동·오류 정정·수수료 정책 변경 등 중요한 작업은 두 번째 승인자 가 필요합니다.
  • 요청자 와 승인자 를 기록하고, 승인은 별도 행위자여야 합니다.

접근 제어

  • 최소 권한 원칙을 적용해 역할 기반 접근 제어(RBAC)를 사용합니다.
  • 모든 권한 부여·해제는 금전 이벤트와 동일한 감사 필드로 로그합니다.
  • 주기적 재인증 으로 오래된 권한을 정리합니다.

변경 이력(SDLC)

  • 소스 컨트롤 히스토리 를 코드 변경의 권위 있는 기록으로 간주합니다.
  • 필수 코드 리뷰, 보호된 브랜치, 서명 커밋을 강제합니다.
  • 배포는 누가, 언제, 어떤 버전 을 사용했는지 추적 가능해야 하며, 사고 시 책임 있는 변경으로 연결됩니다.

돈‑중요 시스템 테스트

  • 프로퍼티 기반 테스트 – 임의 입력에 대해 불변식(예: 총 차변 = 총 대변) 을 검증합니다.
  • 각 단계 후 불변식 검사 – 자동으로 장부 규칙을 검증하는 테스트 시퀀스를 실행합니다.
  • 생성형 멱등성 테스트 – 각 연산을 반복해 이중 집계가 없음을 확인합니다.
  • 크래시·재개 주입 – 단계 사이에 실패를 시뮬레이션해 복구 가능성을 검증합니다.
  • 라운드‑트립 테스트 – Money 타입을 직렬·역직렬화해 정밀도 손실이 없는지 확인합니다.
  • 골든 테스트 – 복잡한 계산(수수료, 명세서 등)을 고정값과 비교해 회귀를 탐지합니다.
  • 하위 호환성 테스트 – 현재 코드가 과거 이벤트 포맷을 읽을 수 있는지 검증합니다.
  • 프로덕션 테스트 – 실제 돈을 사용한 카나리·합성 트랜잭션을 실행하고, 나중에 되돌릴 수 있도록 태깅합니다; 절대 원장을 우회하지 않습니다.

부록

부록 A – 도메인 용어 사전

핵심 핀테크 용어(원장, IOU, 마이너 유닛, 매도·매수 스프레드, T+X 등)와 해당 핸드북 섹션에 대한 링크를 포함한 간결한 목록.

부록 B – 엔드‑투‑엔드 흐름 예시

  1. 암호화폐 출금 – 멱등성, 예약, 컴플라이언스 검사, 온체인 전송, 최종성 대기, 원장 기록, 조정을 보여줍니다.
  2. 카드 입금 – 웹훅 처리, 청산 계정, 정산 지연, 차지백 취소 과정을 설명합니다.
  3. 인앱 전환 + 캐시백 – 통화 격리, 정밀도 유지, 경계에서의 반올림, 스프레드 수익 및 프로모션 비용의 복식부기 게시를 강조합니다.

결론

Fintech Engineering Handbook은 돈을 임의로 생성하거나 잃어버리거나 신뢰할 수 없는 시스템을 구축하기 위한 자체 포함형, 원칙 기반 청사진을 제공합니다. 여기서 제시한 패턴—정밀한 표현, 불변 복식부기 원장, 명시적 불변식, 견고한 외부 연동, 엄격한 접근 제어, 포괄적 테스트—을 따름으로써 엔지니어는 감사, 규제 검토, 그리고 분산 시스템의 필연적인 장애를 견뎌낼 수 있는 신뢰성 높은 금융 제품을 제공할 수 있습니다.

Sources