시스템 구성도 · 애플리케이션 아키텍처 · 주요 업무 흐름도

1. 기술 스택 요약

2. 시스템 구성도

운영은 L4 로드밸런서 뒤에 동일 서버 2대를 두는 무상태(stateless) 구조입니다. 두 대가 하나의 공유 DB와 하나의 공유 오브젝트 스토리지를 바라보므로, 요청이 어느 서버로 가도 결과가 같습니다. 각 서버 내부에서는 nginx 하나 + Spring Boot 백엔드 하나가 5개 호스트(서브도메인)를 server_name 으로 동시에 서비스합니다(서버를 서브도메인별로 나누지 않음).

                           [ 인터넷 / 외부 매장 서버 / 은행·PG 게이트웨이 ]
                                              │
                                     ┌────────┴────────┐
                                     │  L4 로드밸런서   │   /health 로 각 노드 생사 확인
                                     └────────┬────────┘
                        ┌─────────────────────┴─────────────────────┐
                        │                                            │
              ┌─────────────────────┐                    ┌─────────────────────┐
              │   서버 #1 (무상태)   │   ······ 동일 ······│   서버 #2 (무상태)   │
              │  ┌───────────────┐  │                    │  ┌───────────────┐  │
              │  │ nginx 1.27    │  │                    │  │ nginx 1.27    │  │
              │  │ (server_name  │  │                    │  │ (server_name  │  │
              │  │  가상호스트)  │  │                    │  │  가상호스트)  │  │
              │  └──────┬────────┘  │                    │  └──────┬────────┘  │
              │  ┌──────┴────────┐  │                    │  ┌──────┴────────┐  │
              │  │ Spring Boot   │  │                    │  │ Spring Boot   │  │
              │  │ API :8080     │  │                    │  │ API :8080     │  │
              │  │ (@Scheduled   │  │                    │  │ (@Scheduled   │  │
              │  │  워커 포함)   │  │                    │  │  워커 포함)   │  │
              │  └──────┬────────┘  │                    │  └──────┬────────┘  │
              └─────────┼───────────┘                    └─────────┼───────────┘
                        │            공유 인프라(사설망, 인터넷 미노출)         │
                        └──────────────┬───────────────────┬───────────────────┘
                                       │                   │
                            ┌──────────┴─────────┐  ┌──────┴──────────────────┐
                            │  MariaDB 10.3      │  │  오브젝트 스토리지       │
                            │  (nestpay, 공유)   │  │  storages.nestpay.co.kr │
                            │  · 원장·지갑·거래  │  │  (MinIO/S3 · 파일·이미지)│
                            └────────────────────┘  └─────────────────────────┘

  ※ 워커 동시성: 서버 2대가 같은 @Scheduled 를 돌려도, 각 작업은 claim_token(원자적 UPDATE) /
     FOR UPDATE / 상태 가드 쿼리로 "한 건은 한 번만" 처리되도록 DB 에서 보호합니다(중복 처리 방지).

2.1 호스트(서브도메인) 5종 — nginx server_name 분기

하나의 nginx 가 서브도메인별로 "허용 경로만" 열어 신뢰 경계를 나눕니다. 나머지 경로는 모두 404 로 막아, 관리자 API·내부 Swagger 스펙이 공개(api/pg) 호스트로 새지 않게 합니다.

· 운영(443): 하나의 서버가 위 4개 서브도메인(www/api/admin/pg)을 server_name 으로 동시 서비스, 알 수 없는 도메인(직접 IP 접근 등)은 default_server 로 404. · 개발(로컬): DNS 가 없어 포트(6443/8443/9443/7443)로 같은 입구에 접속. · MariaDB(3307)·MinIO 는 인터넷에 노출하지 않고 앱 서버에서 사설망으로만 접속.

2.2 컨테이너 구성(로컬 docker compose)

3. 애플리케이션 아키텍처

표준 계층형 구조입니다. Controller(입출력·검증) → Service(업무 판단·트랜잭션 경계) → Mapper(MyBatis XML SQL) → MariaDB. 여러 흐름이 공유하는 계산·조회는 util 패키지의 순수 함수로 뽑아 중복을 제거했습니다(수수료·로트·지급시각 등).

  ┌──────────────────────────────────────────────────────────────────────────┐
  │  Controller  (kr.nestpay.api.controller)                                    │
  │   App*(회원앱)  Store*(매장앱)  Admin*(관리자)  Pg*(외부PG)  BankWebhook    │
  │   · 요청 DTO 검증(jakarta.validation) · ApiResponse 표준 응답            │
  └───────────────────────────────┬────────────────────────────────────────────┘
                                   │  (권한·토큰은 아래 보안 필터에서 이미 판별)
  ┌───────────────────────────────┴────────────────────────────────────────────┐
  │  Service  (@Transactional 경계 = 한 업무 = 한 트랜잭션)                      │
  │   AppPayment · AppWithdraw · AppGift · AppDeposit · StoreSettle · PgPayment  │
  │   ┌──────────────── 공용 유틸(util) — 중복 제거 ────────────────┐           │
  │   │ Fees(수수료)  Lots(로트 소비)  LedgerLookups(시스템지갑·만료) │           │
  │   │ PayoutSchedules(지급시각)  PushPayloads(알림)  Masks(마스킹)  │           │
  │   │ Hashes(SHA-256)  Pagination  BankVerify  BankMaintenance      │           │
  │   └──────────────────────────────────────────────────────────────┘           │
  └───────────────────────────────┬────────────────────────────────────────────┘
  ┌───────────────────────────────┴────────────────────────────────────────────┐
  │  Mapper  (MyBatis · resources/mapper/*.xml)  — 원장/지갑/거래 단일 원장 SQL  │
  └───────────────────────────────┬────────────────────────────────────────────┘
  ┌───────────────────────────────┴────────────────────────────────────────────┐
  │  MariaDB 10.3  —  wallets · lots · transactions · ledger_entries · …         │
  └──────────────────────────────────────────────────────────────────────────────┘

  [외부 연동은 인터페이스로 격리 — 계약 전 스텁 / 계약 후 실연동 교체]
    BankVerifier   ← StubBankVerifier   (실명조회·1원인증)
    IdentityVerifier ← StubIdentityVerifier (본인인증 PASS 등)

3.1 공용 유틸(중복 제거) — 실제 함수

4. 보안 경계 — nginx → IP → HMAC → 토큰 (3중 필터)

가장 바깥은 nginx(호스트·경로 화이트리스트)이고, 그 안에서 Spring 서블릿 필터가 순서대로 검사합니다. 값싼 검사(IP)를 먼저, 비용이 큰 검사(서명·토큰)를 뒤에 둡니다. 필터 등록·URL 패턴은 SecurityFilterConfig + application.yml 에서 확인.

  요청 ─► [ nginx ]  host(server_name)+경로 화이트리스트 (그 외 404)
            │
            ├─ /admin/*  ─► ① IpWhitelistFilter (order 1)  등록 IP 만 통과(없으면 bootstrap-allow)
            │               ─► ③ AdminAuthFilter (order 3)  관리자 토큰 + 관리자별 개인 허용 IP
            │
            ├─ /pg/*     ─► ② HmacAuthFilter (order 2)  X-Client-Id/Api-Key/Timestamp/Signature
            │                   · 시각 오차 300초 · client_id APPROVED · 키 해시대조(교체유예)
            │                   · HMAC-SHA256(method\npath\nts\nbody) 시간차 없는 비교
            │                   · 서명 통과 후 그 매장의 승인 화이트IP 인지 추가 확인(V7)
            │
            ├─ /store/*  ─► ④ StoreAuthFilter (order 4)  매장 출입증(토큰)
            │
            ├─ /app/me/* ─► ⑤ UserAuthFilter (order 5)  회원 출입증(토큰)
            │               (/app 의 가입·로그인·공개콘텐츠는 무인증)
            │
            └─ /webhooks/bank/*  ─► X-Internal-Key(=INTERNAL_API_KEY) 상수시간 비교 (은행/PG 전용)

  · 진짜 사용자 IP 판별: ClientIpResolver 가 신뢰 프록시(nginx)에서 온 X-Forwarded-For 만 신뢰.
  · 내부 Swagger 스펙(app/store/admin): docsIpWhitelistFilter(order 1)로 사내 IP 에서만 열람.

5. 부팅 안전장치 · 백그라운드 워커

5.1 부팅 안전장치(fail-fast) — 개발 기본값으로 운영 오픈 차단

· 위 두 클래스가 실제 소스에 존재하는 부팅 가드입니다(config/SecretsGuard, config/StubGuard). 조건 미충족 시 IllegalStateException 으로 서버 기동을 중단합니다. 외부 연동(펌뱅킹·본인인증·은행 실명조회)은 계약 전 스텁 상태이며, 실연동 구현으로 교체해야만 운영 기동이 됩니다.

5.2 백그라운드 워커(@Scheduled) — 2대 동시 실행 안전

6. 원장(복식부기) 공통 규약

모든 자금 이동은 transactions 1건 + ledger_entries 여러 줄로 기록되는 단일 원장(single ledger) 구조입니다. 각 줄은 direction(DR 차변 / CR 대변) · amount · balance_after 를 가지며, 한 거래의 DR 합 = CR 합(균형)입니다. 수수료는 항상 별도 CR 줄로 시스템 수수료 지갑에 적립합니다.

· 운영 DB 조회 결과 시스템 지갑 6종 확인: SETTLEMENT_CLEARING · UNMATCHED · FEE_REVENUE · GIFT_ESCROW · EXPIRED · FORFEITED. · 회원 지갑에서 돈이 나갈 때는 Lots.consume 로 유상 로트를 소비하고 배분을 남겨 취소·실패 시 정확히 복원합니다.

7. 업무 흐름 ① 회원 QR 결제 AppPaymentService

QR 은 서버가 QR 번호를 AES-GCM 으로 잠근 문자열(NPQR1.+암호문)입니다. 위조 불가·매장정보 은닉. QR 종류 3가지를 하나의 결제 로직으로 처리합니다.

 회원앱                          API (AppPaymentService.pay)                    DB
   │  스캔 QR + 금액 + pinPass  ─────►
   │                            0) requirePinPass  (PIN 인증 직후 발급된 1회용 표 검증)
   │                            1) loadQr  복호화·존재·활성·만료·매장정상 검증(5.1)
   │                            2) ORDER형이면 burnOrderQr  ← QR 선(先)소각(동시 결제 차단)
   │                            3) 회원지갑·매장지갑 번호순 잠금(데드락 방지)  ─► FOR UPDATE
   │                            4) 수수료 스냅샷(Fees.calc) + 부가세 분리(TAXED)
   │                               취소가능기한(cancelable_until) 계산(3.5)
   │                            5) 로트 잠금(무상 우선) — 가용 합 < 금액이면 결제 불가
   │                            6) transactions INSERT (멱등키 = PAY:{pinSig})
   │                            7) ledger_entries 분개(아래 표)
   │                            8) Lots.consume  회원 DR 줄에 로트 배분·차감(0.4)
   │                            9) 지갑 잔액 갱신 + 양쪽 알림(outbox) + PG주문 연결
   │  ◄─ 결제완료(txnId·잔액)

· 멱등: 멱등키 PAY:{pinSig} 를 ux_txn_idem 이 막아 같은 인증표로 두 번 결제 불가. · 수수료는 매장 부담(MERCHANT_PAYMENT 정책 스냅샷). · PG 오픈 API 주문이면 pgOrderService.onQrPaid 로 주문 PAID 연결 + 매장서버 웹훅 예약(돈 이동은 위 단일 원장에만 기록).

8. 업무 흐름 ② 출금 AppWithdrawService + WithdrawWorker

출금은 신청 즉시 지갑에서 선차감(HOLD) 하고, 예정 시각이 되면 워커가 실제 이체를 실행합니다. 출금은 유상(DEPOSIT) 로트만 가능(무상 적립금 출금 불가 — 0.5). 은행 점검시간에는 신청을 막습니다(BankMaintenanceGuard).

 회원앱  ─ 계좌·금액·pinPass ─►  request()
   · bankGuard.ensureOpen()  (은행 점검시간 차단)
   · requirePinPass · 계좌 존재 · 계좌변경 24h 냉각(cooldown) 확인
   · 지갑 잠금 · 유상로트 가용합 ≥ 금액 확인
   · 수수료(USER_WITHDRAW) → 순액 = 금액 − 수수료 (순액 ≤ 0 이면 거부)
   · 예정시각 = PayoutSchedules.from(정책)
   · transactions INSERT (status HOLD, 멱등키 WDR:{pinSig})
   · 분개 + Lots.consume(유상만) + 지갑 갱신 + 알림

 WithdrawWorker.tick (60s)
   │ scanDue()  예정시각 지난 HOLD 목록(최대 100, 짧은 TX)
   └─ 건별 executeOne() [REQUIRES_NEW]
        · claimWithdrawal  HOLD→PENDING (0건이면 타 서버가 이미 집음 → skip)
        · ★펌뱅킹 이체 = 계약 전 스텁: 항상 성공, bankTranRef = "STUB-{txnId}"
        · confirmWithdrawal → CONFIRMED + "출금 완료" 알림
        (실연동 시: 결과불명은 UNKNOWN 으로 두고 리컨실러(8.4)가 정리)

 실패 시 restoreFailed() [REQUIRES_NEW] — 역분개 + 로트 승계 복원
   · failWithdrawal (상태 전이 가드)
   · 역분개(복원 입금 거래, 멱등키 WDRBACK:{txnId}):

· 실패 복원 시 restoreLots 로 원래 쓰던 로트의 유형·만료일을 그대로 승계(유효기간 손실 방지 — 8.5). · 멱등키 WDR:{pinSig} 로 이중 신청 차단.

9. 업무 흐름 ③ 선물 AppGiftService

보낼 수 있는 것은 유상 포인트뿐(무상 적립금 선물 불가 — 0.5). 발신인이 수수료 부담(USER_GIFT). 모든 실행은 pinPass 필수. 받는 사람에게는 받은 날부터 새 유효기간의 유상 로트가 생깁니다(insertReceiveLot).

9.1 직접 선물(7.2) — 전화번호/카드번호로 즉시 전달

 sendDirect()  · 수신자 조회(전화 or 카드번호 지문) · 양쪽 지갑 번호순 잠금
   · 수수료 → 순액(≤0 거부) · 유상로트 가용 확인 · transactions(GIFT_DIRECT, CONFIRMED)

9.2 링크 선물 — 생성(7.3) → 수령(7.4) → 회수/만료반환(7.5·7.6)

 createLink()  돈을 GIFT_ESCROW 로 보류, 링크 토큰은 지금 1번만 노출(DB 엔 SHA-256 지문만)
   ┌ 발신 DR 총액 / GIFT_ESCROW CR 순액 / FEE CR (+발신 로트 소비)   [status HOLD]
 claim(token)  수령자 대표 카드로 전달 (본인이 만든 링크는 수령 불가 → 회수 이용)
   └ GIFT_ESCROW DR 금액 / 수령 CR 금액 (+수령자 새 로트)
 cancelLink(7.6, 회수) / expireOne(7.5, 24h 미수령 자동, GiftExpireWorker 5분)
   └ GIFT_ESCROW DR 금액 / 발신 CR 금액 (+발신자 새 로트 = 새 유효기간)

· 멱등: 생성 시 멱등키 GIFT:{pinSig}. · 수령 가드 claimLink·회수/만료 가드로 이미 처리된 링크 중복 방지.

10. 업무 흐름 ④ 정산 StoreSettleService · AdminSettlementService

10.1 매장 정산 출금(8.1 매장판) — 매장 지갑은 로트 없음

매장이 쌓인 매장 지갑 잔액을 자기 계좌로 빼는 기능. 매장 지갑은 로트가 없어 회원 출금보다 단순합니다(잔액에서 바로 차감). 기본 정책은 즉시 정산(delay 0). 실행·복원은 회원 출금과 같은 WithdrawWorker 가 처리(같은 규약).

 매장앱 ─ 금액 + idempotencyKey ─► request()
   · 정산계좌·잔액 확인 · 수수료(MERCHANT_PAYOUT) → 순액(≤0 거부)
   · 예정시각(PayoutSchedules) · transactions(멱등키 SETTLE:{앱제공키})
   · 분개(아래) + 지갑 갱신 + 알림   → 이후 WithdrawWorker 가 이체 실행

주의 앱이 idempotencyKey 를 주면 ux_txn_idem 이 재시도 중복을 막지만, 구버전 앱이 안 주면 새 값이 생성되어 중복 차단이 되지 않습니다(코드 주석 명시).

10.2 관리자 월 마감(재계산) — 멱등

 AdminSettlementService.closeMonth(yyyymm)
   · 월 형식·미래월 검증 → 그 달 [시작, 다음달 시작) 범위로 월 정산서 통째 재계산(17.14)
   · 같은 달을 몇 번 눌러도 값이 다시 계산되어 안전(멱등 — 18장 규약) · 감사로그 기록

· 월 마감은 집계·리포트 성격이라 원장 분개를 만들지 않습니다(자금 이동 없음). 자금 이동은 10.1 정산 출금에서만 발생.

11. 업무 흐름 ⑤ 입금 충전 AppDepositService · DepositNoticeWorker

회원이 앱에서 받은 입금자 코드(NP+8자리)를 은행 이체 입금자명에 적으면, 은행/PG 통지가 웹훅으로 들어오고, 워커가 코드로 주인을 찾아 적립하거나 미매칭 보관합니다. 가상계좌 발급은 펌뱅킹/PG 계약 후 — 현재는 입금자 코드 방식(스텁).

 은행/PG ─ X-Internal-Key ─► BankWebhookController /webhooks/bank/deposit-notice
   · 내부키 상수시간 비교 · receiveNotice():
       dedupKey = SHA256(source:bankTranRef)   ← 펌뱅킹(거래식별자 있음)
                = SHA256(source:rawText)        ← SMS(원문 지문)
     INSERT 시 DuplicateKeyException(1062) → 이미 받은 통지면 조용히 멱등 처리(INSERT IGNORE 금지)

 DepositNoticeWorker.tick (10s)  claimNewNotices(FOR UPDATE, 최대 100)
   └─ 건별 processNotice() [REQUIRES_NEW]
        1) 주인 찾기: 입금자코드 → 회원 → 충전 대상 카드(대표 우선)
        2) 충전 강제 규약: 회원이 "인증계좌(실명+1원)" 보유해야만 자동 적립
        3) 재발행 카드면 새 카드로 갈아탐(REISSUED → reissued_to)

· 멱등키 DEP:{source}:{dedupKey} 로 같은 통지의 이중 적립을 차단(DuplicateKeyException → TX 롤백). · 워커는 통지별 독립 TX 라 한 건 실패가 다른 건에 영향 없음(실패 통지는 NEW 로 남아 다음 바퀴 재시도).

NestPay 산출물 · (주)페이네스트 · 작성일 2026-07-27 · 실제 코드/DB 기준 · 외부연동(펌뱅킹·본인인증·은행 실명조회)은 계약 전 스텁 상태임을 명시