당신의 SaaS 잔액이 거짓말을 하는 이유: TypeScript와 PostgreSQL로 불변의 금융 원장 설계하기

만약 소프트웨어 서비스(SaaS) 플랫폼, 전자상거래 마켓플레이스 또는 핀테크 앱을 운영한다면, 데이터베이스에서 계정 잔액을 어떻게 관리하는지 면밀히 살펴보십시오. 만약 코드가 컬럼을 업데이트하는 방식—예를 들어 UPDATE accounts SET balance = balance + 100 WHERE id = 'acc_123'와 같은 방식—에 의존하고 있다면, 당신은 시한폭탄 같은 금융 위험을 안고 있는 것입니다.

표준 웹 애플리케이션에서는 CRUD(Create, Read, Update, Delete)를 통해 상태를 제자리에서 수정하는 것이 매우 자연스럽습니다. 소셜 미디어 게시물의 좋아요 수를 증가시켜야 하나요? 제자리 업데이트를 실행합니다. 남은 제품 재고를 추적해야 하나요? 정수를 변경합니다. 하지만 대규모 금융 엔지니어링에서는 이 패턴이 치명적입니다.

전통적인 제자리 업데이트가 왜 실패하는지 이해하려면, 프론트엔드 시스템의 병렬 사례를 고려해 보십시오: Document Object Model (DOM)과 Redux 또는 반응형 상태 저장소(reactive state stores)를 비교하는 것입니다. 만약 애플리케이션이 사용자가 버튼을 클릭할 때마다 메모리에 흩어져 있는 깊게 중첩된, 변경 가능한 객체들을 계속해서 수정한다면, 레이스 컨디션(race conditions)과 메모리 누수(memory leaks)를 디버깅하는 것은 불가능할 것입니다. 대신에, 프론트엔드 아키텍처는 불변 이벤트 스트림(immutable event streams)—Redux 액션, React 상태 훅(state hooks), 그리고 이벤트 소싱(Event Sourcing)—을 향해 발전했습니다. 이 방식에서는 상태가 직접 수정되는 법이 없고, 오직 불변 이벤트의 추가 전용 로그(append-only log)에 대한 순수 함수(pure function)로서 결정론적으로 파생됩니다.

복식 부기 원장(double-entry ledger)은 금융 세계의 원래이자 검증된 이벤트 소싱 구현체입니다. 이는 돈이 결코 생성되거나 파괴되지 않으며, 단지 이동할 뿐임을 규정합니다.

본 포괄적인 엔지니어링 가이드에서는 복식 부기 회계(double-entry bookkeeping)의 이론적 기초를 탐구하고, 불변성을 위한 데이터베이스 스키마 설계를 해부하며, 임의 정밀도 수학(arbitrary-precision math)을 사용한 프로덕션급 TypeScript 구현 과정을 안내하고, 분산 결제 파이프라인에서 레이스 컨디션, 아이덴티티(idempotency), 그리고 동시성 제어(concurrency control)를 극복할 것입니다.

이론적 기초: 왜 CRUD가 금융에 적합하지 않은가

금융 시스템은 기존의 상태 변경(state mutations) 방식에서 타협 없는 전환을 요구합니다. 잔액(Running balances)은 캐시된 최적화일 뿐이며, 결코 진실의 원천이 될 수 없습니다. 장부(ledger)의 특정 마이크로초 시점에서의 실제 상태는 그곳에 커밋된 모든 불변 항목(immutable entries)의 합계입니다.

1594년 루카 파치올리(Luca Pacioli)가 저술한 복식 부기(double-entry bookkeeping)에 관한 논문은 심오한 수학적 불변량(invariant)을 공식화했습니다. 즉, 모든 차변(debit)에는 같고 반대되는 대변(credit)이 있어야 한다는 것입니다. 관계형 데이터베이스에서 이 불변량을 구현하려면 금융 이동을 두 가지 별개의 개념적 개체로 분해해야 합니다:

트랜잭션(The Transaction): 비즈니스 이벤트, 타임스탬프, Idempotency Key, 의도 등을 나타내는 헤더입니다.
항목들(The Entries): 계정에 대한 다면적인 기계적 영향을 나타내는 라인 항목들입니다.

t랜잭션 헤더를 HTTP 요청 봉투로 생각해보세요. 이 봉투는 타임스탬프, 전역 고유 식별자, 중복 처리를 방지하기 위한 Idempotency Key, 상태 플래그, 설명과 같은 메타데이터를 포함합니다. 하지만 이 요청 봉투 자체에는 페이로드 값이 없습니다. 실제 페이로드는 항목들(entries)에 존재합니다.

모든 항목은 반드시 특정 계정에 속해야 하며 부호가 지정된 숫자 값(signed numeric value)을 가져야 합니다. 이는 모든 트랜잭션 전반에 걸쳐 엄격한 영(zero)-합 불변량(invariant)을 강제합니다:

$$ ext{i=1} ext{\sum n} ext{Amount}_i = 0$$

여기서 $n$은 단일 트랜잭션 식별자와 관련된 항목들의 전체 집합이며, Amount는 부호(차변의 경우 양수, 대변의 경우 음수 또는 그 반대)를 포함합니다.

만약 데이터베이스가 이 항목들의 합계가 정확한 소단위 정수까지 0이 되는 것을 강제하지 못한다면, 돈은 공기 중에서 효과적으로 인쇄되거나 조용히 소각됩니다. 관계형 데이터 모델은 이러한 불가능성을 막는 견고한 물리 법칙 역할을 해야 합니다.

계정 계층 구조, 정상 잔액, 그리고 계정 과목표(Chart of Accounts)

금융 원장(financial ledger) 내의 계정들은 평평한 구조가 되는 경우는 드뭅니다. 파일 시스템이 디렉토리를 계층적 트리로 구성하는 것과 마찬가지로, 계정표(Chart of Accounts, CoA)는 계정들을 부모-자식 관계(parent-child relationships)로 구조화합니다. 한 기업은 최상위 '자산(Assets)' 계정을 가질 수 있으며, 이는 다시 '유동 자산(Current Assets)'으로 분기되고, 이어서 '운영 현금(Operating Cash)', '가맹점 게이트웨이 매출채권(Merchant Gateway Receivables)', '소액 현금(Petty Cash)' 등으로 더 세분화됩니다.

TypeScript 기반의 금융 엔진에서 이러한 계층 구조를 모델링하려면 재귀적 타입(recursive types)과 정상 잔액(normal balances)에 대한 엄격한 분류가 필요합니다. 회계의 다섯 가지 기본 기둥—자산(Assets), 부채(Liabilities), 자본(Equity), 수익(Revenue), 비용(Expenses)—은 양수 및 음수 항목이 계정의 논리적 상태를 어떻게 변경하는지 규정합니다:

자산(Assets) & 비용(Expenses): 일반적으로 차변 잔액(debit balances)을 가집니다. 자산이나 비용을 증가시키려면, 이를 차변 처리(debit)합니다. 감소시키려면 대변 처리(credit)합니다.
부채(Liabilities), 자본(Equity), & 수익(Revenue): 일반적으로 대변 잔액(credit balances)을 가집니다. 부채, 자본 또는 수익 흐름을 증가시키려면, 이를 대변 처리(credit)합니다. 감소시키려면 차변 처리(debit)합니다.

만약 데이터베이스 계층이 이러한 분류를 존중하지 않고 임의의 산술 연산을 허용한다면, 개발자는 비용을 기록하기 위해 실수로 비용 계정에 대변 처리를 하여 재무제표가 음수 비용을 보고하는 회계적 이상(accounting anomaly)을 초래할 수 있습니다. 이는 감사 준수(audit compliance)를 무너뜨립니다. 따라서 데이터 모델은 원시 금액과 함께 의미론적 분류(semantic classifications)를 포착해야 하며, 트랜잭션 파이프라인이 디스크에 바이트를 커밋하기 전에 계정 유형을 검증하도록 보장해야 합니다.

트랜잭션 항목의 관계형 분리 (The Transaction-Entry Relational Split)

초기 단계 핀테크 엔지니어링에서 흔히 발생하는 안티 패턴(anti-pattern)은 금융 이동 내역을 단일 평면 테이블에 저장하는 것입니다. 이 테이블에서는 모든 행이 하나의 이동 내역을 나타내며, '출발 계정(source account)'과 '도착 계정(destination account)' 열을 모두 포함합니다. 이러한 평면 모델은 여러 다리 거래(multi-legged transactions)—예를 들어, 한 신용카드 청구가 세 가지 다른 가맹점 지급액에 자금을 지원하면서 플랫폼 수수료를 공제하고 세금을 부과하는 분할 결제(split payment)와 같은 경우—를 처리할 때 빠르게 무너집니다.

이 문제를 해결하기 위해 transactions 테이블과 entries 테이블 사이에 엄격한 일대다(one-to-many) 관계를 강제합니다.

transactions 테이블에는 금융 금액이 포함되어 있지 않습니다. 이 테이블은 순수하게 구조적이고 시간적인 역할을 합니다. 이 테이블은 다음과 같은 질문에 답합니다: 언제 발생했는가? 왜 발생했는가? 성공적으로 처리되었는가, 아니면 실패했는가?

entries 테이블에는 돈이 움직인 이유에 대한 비즈니스 로직이 포함되어 있지 않습니다. 이 테이블은 엄격하게 수학적인 질문에 답합니다: 어떤 계좌가 건드렸는가? 얼마나 많이? 어느 방향으로?

의도(intent)와 메커니즘(mechanics)을 분리함으로써, 우리는 무한한 확장성을 얻게 됩니다. 만약 규제 요건이 모든 거래가 세 개의 새로운 메타데이터 태그를 추적하도록 요구한다면, 우리는 transactions 테이블만 수정합니다. 만약 20개의 다른 계좌에 걸쳐 자금을 분할하는 거래를 지원해야 한다면, 우리는 거래 헤더 스키마(transaction header schema)를 전혀 건드리지 않습니다. 대신 두 개의 행을 생성하는 대신 entries 테이블에 20개의 행을 단순히 생성합니다.

동시성, 경쟁 조건 및 이중 지출 (Concurrency, Race Conditions, and Double-Spending)

대용량 결제 파이프라인에서는 여러 비동기 프로세스가 동일한 계좌를 동시에 읽고 쓰려고 시도합니다. 잔액이 100인 사용자가 모바일에서 100짜리 상품을 구매하는 동시에 ATM에서 100달러를 인출한다고 상상해 보세요.

읽기-수정-쓰기(read-modify-write) 패턴을 사용하는 순진한 시스템에서는 두 워커 스레드 모두 계좌 잔액을 100으로 읽습니다. 둘 다 100 ≥ 100임을 검증합니다. 둘 다 인출 항목을 구성합니다. 둘 다 잔액을 0으로 업데이트합니다. 사용자는 원래 100만 있던 계좌에서 200을 성공적으로 인출했습니다. 이것이 바로 고전적인 이중 지출(double-spending) 취약점이며, 암호화폐 이론에서 전통적인 법정 화폐 원장 구조로 복제된 것입니다.

경쟁 조건(race conditions)을 제거하기 위해 소프트웨어 엔지니어는 데이터베이스 격리 수준(isolation levels), 비관적 잠금(pessimistic locking), 또는 직렬화 가능한 트랜잭션 로그(serializable transaction logs)에 의존해야 합니다. 계정에 변경 가능한 balance 컬럼을 저장하지 않는 순수한 복식 부기 원장(double-entry ledger)의 경우, 공격 벡터가 바뀝니다. 잔액이 읽히지 않으면 오래된 잔액을 읽을 수 없습니다—트랜잭션 항목들의 합계를 쿼리하는 것입니다. 그러나 높은 동시성 하에서 항목들을 합산하는 것조차도 두 스레드가 비즈니스 불변 조건(예: 계좌 초과 인출 한도)을 위반하는 충돌 트랜잭션을 삽입하려고 시도할 경우 경쟁 조건을 유발합니다.

처리량(throughput)을 희생하지 않으면서 절대적인 안전성을 유지하기 위해, 고신뢰성 원장 시스템은 불변의 추가 전용 제약 조건(immutable append-only constraints)과 결합된 낙관적 동시성 제어(Optimistic Concurrency Control, OCC) 또는 계정 포인터 레코드에 대한 **비관적 행 수준 잠금(SELECT ... FOR UPDATE)**을 활용합니다.

비관적 잠금을 사용할 때, 계정에 접근하려는 모든 트랜잭션은 해당 계정의 데이터베이스 행에 독점 잠금(exclusive lock)을 획득해야 합니다. 데이터베이스 잠금은 리소스별로 순차적이기 때문에, 스레드 A가 Account X에 잠금을 걸고, 항목들을 계산한 후, 트랜잭션과 항목들을 삽입하고 커밋하며—잠금을 해제합니다. 기다리던 스레드 B는 Account X의 잠금을 획득하고, 새로 커밋된 상태를 읽은 다음, 신선한 합계에 대해 불변 조건을 평가하여 안전하게 진행하거나 실패합니다.

아이뎀포턴시(Idempotency)와 분산 복원력(Distributed Resiliency)

네트워크 분할(Network partitions), 시간 초과(timeouts), 클라이언트 재시도(client retries)는 분산 시스템에서 삶의 일부입니다. 결제 게이트웨이가 은행 네트워크에서 청구를 성공적으로 처리했을지라도, 성공 페이로드(success payload)를 담아 우리 API 서버로 돌아가는 HTTP 응답은 불안정한 라우터 때문에 손실될 수 있습니다. 클라이언트는 필연적으로 요청을 재시도할 것입니다.

절대적인 아이뎀포턴시가 없다면, 재시도는 중복 트랜잭션을 초래합니다: 사용자에게 두 번 청구되고, 원장에는 두 개의 별도 입금이 기록됩니다.

이중 분개 장부(double-entry ledger)에서의멱등성(Idempotency)은 단순히 Redis에 저장된 애플리케이션 레벨 캐시가 아닙니다. Redis 키는 삭제될 수 있고, 클러스터는 장애 조치(fail over)를 할 수 있으며, 메모리 캐시는 배포 과정에서 지워질 수 있습니다. 진정한 금융 멱등성은 트랜잭션 메타데이터에 대한 고유 제약 조건(unique constraints)을 통해 영구 저장소 계층(persistent storage layer)에 직접적으로 고정되어야 합니다.

클라이언트가 결제 파이프라인을 시작할 때, 그들은 idempotency_key—클라이언트가 생성한 UUIDv4—를 제공합니다. 이 키는 transactions 테이블의 전용 고유 인덱스 컬럼에 저장됩니다. 기존 멱등성 키와 함께 요청이 도착하면, 데이터베이스는 중복된 트랜잭션 헤더 삽입을 거부합니다. 애플리케이션은 이 데이터베이스 레벨 오류를 포착하고, 원래 트랜잭션 기록과 그 불변의 항목들(immutable entries)을 검색한 다음, 클라이언트에게 정확히 동일한 성공 응답 페이로드(response payload)를 반환합니다.

규정 준수 및 감사(Auditing) 의무로서의 불변성(Immutability)

표준 소프트웨어 엔지니어링에서 버그는 마이그레이션(migration)을 작성하거나 업데이트 쿼리를 실행하여 손상된 데이터를 수정함으로써 고쳐집니다. 금융 엔지니어링에서는 과거 장부 항목을 변경하는 것(mutating past ledger entries)은 엄격하게 불법입니다.

만약 회계사가 3개월 전에 $1,000 트랜잭션이 잘못된 비용 카테고리에 기록되었다는 것을 발견한다면, 그들은 SQL UPDATE entries SET account_id = 'correct_id' WHERE id = 'old_id'를 실행할 수 없습니다. 그렇게 하는 것은 역사적 재무제표를 변경하고, 감사 추적(audit trails)을 파괴하며, Sarbanes-Oxley (SOX), GAAP, IFRS와 같은 규제 준수 프레임워크를 위반합니다.

대신, 오류는 보상 트랜잭션(compensating transactions) (취소 트랜잭션 또는 반대 항목)을 사용하여 수정됩니다.

실수를 되돌리려면 과거를 지우는 것이 아니라, 과거를 명시적으로 부정하는 새로운 이벤트를 현재에 기록합니다. 만약 트랜잭션 A가 실수로 계정 X에서 1,000을 차변(debit) 처리했다면, 트랜잭션 B를 실행하여 계정 X에 1,000을 대변(credit) 처리하고 올바른 균형 조정 계정을 차변으로 처리합니다. 두 거래 모두 불변의 원장(ledger)에 영원히 새겨집니다. 장부를 감사하는 누구든 오류와 그 수정 과정을 투명하게 추적할 수 있습니다.

TypeScript로 원장 구축하기: 프로덕션 구현

불변하고 복식 부기(double-entry) 금융 원장이 내부적으로 어떻게 작동하는지 이해하기 위해, 강력한 TypeScript 구현을 살펴보겠습니다. 이 예제는 전체 트랜잭션 생명주기를 모델링합니다: 계정 생성, 균형 잡힌 항목으로 제로섬(zero-sum) 트랜잭션 인스턴스화, 그리고 이를 시뮬레이션된 저장소 레이어에 영구히 저장하기 전에 구조적 불변성(structural invariants)을 검증하는 과정입니다.

import { Decimal } from 'decimal.js';

enum AccountType {
...