재무 운영 인프라
BEATOZ Treasury - Treasury Operations Platform
이체, 환전, 준비금, 정산을 관리하는 재무 운영 플랫폼입니다. 원장·준비금·이체·정산을 별도 모듈로 나누고 Kafka 기반 비동기 처리, 실패 이벤트 재처리, 정산 대조 기능을 구현했습니다.
01 / 담당 범위
기록과 자금, 이체의 진행 상태를 나눕니다.
이체·환전·준비금·정산 업무를 연결한 재무 운영 플랫폼입니다. 각 영역의 책임을 나누면서, 비동기 처리를 운영자가 확인하고 복구할 수 있도록 구성했습니다.
Beatoz 공동 dev pilot에서 Treasury API, 운영 화면과 테스트벤치, Kafka 연동, 단일 인스턴스 배포 자동화를 1인 개발했습니다. CPG와 인접 서비스는 별도의 업무 영역입니다.
02 / 책임 구조
다른 질문에는 다른 책임이 필요합니다.
동기 API 요청과 Kafka 이벤트 수신
- 원장 · Ledger
무엇을 기록했는가
회계 기록은 원장 영역의 관심사입니다. 원장에 기록됐다는 사실과 외부 이체가 완료됐다는 사실을 같은 의미로 다루지 않습니다.
- 준비금 · Reserve
어떤 자금을 쓸 수 있는가
준비금 업무를 원장·이체 모듈과 나눠 자금의 가용성을 별도의 책임으로 설명할 수 있게 했습니다.
- 이체·환전 · Transfer / FX
처리가 어디까지 진행됐는가
이체와 환전 API는 해당 업무의 진행을 다룹니다. 그 응답만으로 정산 결과를 대신하지 않고 대사 결과와 함께 봐야 합니다.
정산 대사와 모니터링으로 연결
정산 대사 스케줄러, 운영 화면, 테스트벤치로 불일치와 복구 경로를 확인하도록 했습니다. 이 그림이 특정 트랜잭션 경계나 exactly-once 처리를 보장한다는 뜻은 아닙니다.
설계에서 나눈 것들.
반복 요청을 API의 계약으로 다루기
API 경계에 멱등성 제어와 problem-details 오류 응답을 적용한 것으로 기록돼 있습니다. 반복 요청과 실패를 화면의 임시 처리에만 맡기지 않기 위한 구성입니다.
재처리를 운영자가 확인할 수 있게 하기
Kafka 컨슈머, DLQ 재처리, 정산 대사를 운영 화면·테스트벤치와 함께 구성했습니다. 복구를 보이지 않는 재시도에 그치지 않고 운영 절차로 다룹니다.
pilot의 배포 제약에 맞춰 만들기
단일 인스턴스 환경에서 PM2·Nginx·PostgreSQL 설정을 포함한 배포를 자동화했습니다. 이를 다중 리전이나 고가용성 배포 성과로 확대해 설명하지 않습니다.
03 / 예외 검토
경계에서 확인해야 할 질문.
실제 장애나 테스트 통과 결과가 아닌 검토용 시나리오입니다.
이체 요청이 다시 들어왔다면
- 처리 방식
- 프로젝트 기록에는 API 멱등성 제어와 구조화된 오류 응답이 포함돼 있습니다.
- 확인할 내용
- 원래 요청과 반복 요청, 작업 식별자, 금융 부수 효과를 함께 확인해야 합니다. 이 페이지에는 해당 거래 추적 기록이 첨부돼 있지 않습니다.
실패한 Kafka 메시지를 재처리한다면
- 처리 방식
- Kafka 컨슈머, DLQ 재처리 서비스와 모의 이벤트 생성기가 구현 범위에 포함돼 있습니다.
- 확인할 내용
- 실패한 시도와 이미 반영된 업무 상태, 재처리 결과를 함께 봐야 합니다. 메시지 소비만으로 금융 업무가 끝났다고 판단하지 않습니다.
이체 진행과 정산 기록이 어긋난다면
- 처리 방식
- 정산 대사 스케줄러와 모니터링 화면이 프로젝트 기록에 명시돼 있습니다.
- 확인할 내용
- 어떤 기록을 비교하고, 차이를 어떻게 알리며, 어떤 조치로 해결하는지 확인해야 합니다. 실제 장애 이력이 아닌 검토 질문입니다.
구현 범위
BEATOZ Treasury
Treasury API
재무 운영 백엔드
- 멱등성을 보장하는 이체·환전·준비금 API
- 일관된 오류 응답 형식
- 정산 대조 작업
Admin Web
운영 대시보드
- 준비금과 모니터링 화면
- 이체와 정산 운영
- 오픈뱅킹 연동 화면
Testbench + Mock Services
업무 흐름 검증
- 시나리오 실행 화면
- 결제·해외송금 모의 이벤트
- Kafka와 DLQ 재처리 검증
사용 기술
- TypeScript
- NestJS
- Next.js
- Prisma
- PostgreSQL
- KafkaJS
- React
- Docker
- AWS
04 / 자료와 기록
설명의 근거를 확인합니다.
기존 프로젝트 기록을 바탕으로 정리했습니다. 원본 Treasury 저장소와 거래 로그는 이 페이지의 공개 자료에 포함돼 있지 않습니다.
작성자의 기존 구현 기록을 유지했습니다. 책임 지도는 설명용이고 시나리오는 검토 질문이며, 실제 장애나 결제 테스트 통과 기록이 아닙니다. 처리량·가용성·정산 성능 수치는 추가하지 않았습니다.
기존 상세 기록 펼치기
풀어야 했던 문제
동기 API와 Kafka 이벤트가 함께 들어오는 환경에서 이체·환전·준비금·정산 상태를 일관되게 유지해야 했습니다. 중복 요청, 실패 이벤트, 운영 복구도 같은 기준으로 다뤄야 했습니다.
설계와 구현
원장·준비금·이체·정산의 책임을 모듈별로 나누고 API 경계에서 멱등성과 오류 형식을 통일했습니다. Kafka DLQ 재처리와 정산 대조 작업을 만들고, 관리자·테스트벤치 화면과 단일 인스턴스 배포 스크립트까지 구성했습니다.
개요
- 1인 개발로 진행한 재무 운영 플랫폼 모노레포입니다.
- 이체, FX, 준비금, 정산, 모니터링 흐름을 API/운영 UI/테스트벤치/배포 스크립트까지 하나의 시스템으로 구성했습니다.
- CPG 및 인접 서비스와 함께 운영되는 Beatoz 통합 dev pilot에서 재무 운영 코어 역할을 맡도록 설계했습니다.
핵심 구성
1) Treasury API
- bank, FX, ledger, reserve, transfer, monitoring, treasury consumer ingress 모듈로 분리된 NestJS API를 구성했습니다.
- Problem Details 필터와 idempotency interceptor를 적용해 API 경계에서 오류 형식과 재시도 의미를 통일했습니다.
- 정산 상태 추적을 위해 reconcile 엔드포인트와 scheduler hook을 포함했습니다.
- CPG 및 인접 컴플라이언스/운영 서비스가 연결할 수 있는 도메인 인터페이스를 포함했습니다.
2) Kafka Ingress & Replay
- billing / cross-border ingress 이벤트(transfer, reserve movement, FX execution)를 수신합니다.
- DLQ publish, replay status/recent, worker lock coordination, replay trigger를 포함한 운영 복구 흐름을 구현했습니다.
- Kafka ingress, outbox transaction, DLQ replay를 검증하는 smoke 스크립트를 구성했습니다.
3) Admin + Testbench
- monitoring, reserve, FX, transfer, settlement, operations 화면을 포함한 Next.js admin 앱을 구성했습니다.
- 시나리오 실행, 로그 확인, 이력 export를 위한 Next.js testbench 앱을 구성했습니다.
- mock billing / mock cross-border 서비스로 consumer 기반 흐름을 검증할 수 있게 했습니다.
4) 배포/운영 자동화
- Postgres, PM2, Nginx를 묶은 단일 인스턴스 AWS 배포 스크립트를 구성했습니다.
- API/Admin/Testbench 환경 파일 생성과 기본 데이터 시드를 자동화했습니다.
- 중앙 dev pilot 배포 컨트롤러와 맞는 런타임 형태로 정리했습니다.