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

1. 기술 스택 요약

2. 시스템 구성도

운영은 L4 → WEB(공개망) → WAS(폐쇄망) → DB 구조입니다(발주사 확정 2026-08-11). WEB·WAS 모두 동일 구성 2대씩이며 무상태(stateless)입니다. 두 WAS 가 하나의 공유 DB와 하나의 공유 파일 폴더를 바라보므로, 요청이 어느 쪽으로 가도 결과가 같습니다. WEB 의 nginx 하나가 3개 호스트(npwp-api·npwp-pg·npwp-admin)를 server_name 으로 동시에 서비스합니다(서버를 주소별로 나누지 않음).

                    [ 인터넷 / 외부 매장 서버 / 발주사 서버 ]
                                       │
                              ┌────────┴────────┐
                              │  L4 로드밸런서   │   /health 로 각 WEB 생사 확인
                              └────────┬────────┘
              ┌────────────────────────┴────────────────────────┐
              │                 공개망 (DMZ)                     │
    ┌─────────┴──────────┐                          ┌───────────┴────────┐
    │   WEB #1           │ ······· 동일 ··········· │   WEB #2           │
    │  ┌──────────────┐  │                          │  ┌──────────────┐  │
    │  │ nginx 1.27   │  │                          │  │ nginx 1.27   │  │
    │  │ server_name  │  │  주소(npwp-api·pg·admin) │  │ server_name  │  │
    │  │ 가상호스트   │  │  로 갈라 줌              │  │ 가상호스트   │  │
    │  │ + 정적 파일  │  │  관리자 화면·문서은      │  │ + 정적 파일  │  │
    │  └──────┬───────┘  │  여기서 직접 응답        │  └──────┬───────┘  │
    └─────────┼──────────┘                          └─────────┼──────────┘
              │                 폐쇄망 (외부에서 직접 접속 불가)          │
    ┌─────────┴──────────┐                          ┌─────────┴──────────┐
    │   WAS #1 (무상태)  │ ······· 동일 ··········· │   WAS #2 (무상태)  │
    │  ┌──────────────┐  │                          │  ┌──────────────┐  │
    │  │ Spring Boot  │  │                          │  │ Spring Boot  │  │
    │  │ API :8080    │  │                          │  │ API :8080    │  │
    │  │ (@Scheduled  │  │                          │  │ (@Scheduled  │  │
    │  │  워커 포함)  │  │                          │  │  워커 포함)  │  │
    │  └──────┬───────┘  │                          │  └──────┬───────┘  │
    │  ┌──────┴───────┐  │                          │         │          │
    │  │ 파일 공유폴더│◀─┼───── 마운트(WAS #2가 함께 바라봄) ──┘          │
    │  │ STORAGE_DIR  │  │                          │                    │
    │  └──────────────┘  │                          │                    │
    └─────────┬──────────┘                          └─────────┬──────────┘
              └────────────────────┬─────────────────────────┘
                          ┌────────┴────────┐
                          │  MariaDB 10.3   │   원장·지갑·거래 (1대, 공유)
                          └─────────────────┘

  ※ 파일 실물: 오브젝트 스토리지를 쓸 수 없어(발주사 확정 2026-08-11), WAS #1 의 폴더를
     WAS #2 가 함께 마운트합니다. 폴더가 연결돼 있지 않으면 서버가 아예 켜지지 않습니다.

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

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

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

· 운영(443): 하나의 서버가 위 4개 서브도메인(www/app/admin/pg)을 server_name 으로 동시 서비스, 알 수 없는 도메인(직접 IP 접근 등)은 default_server 로 404. · 테스트 서버는 같은 도메인에 앞글자 t 를 붙입니다(twww/tapp/tadmin/tpg). 설정 파일은 한 벌(nginx/templates/nginx.conf.template)이고 환경변수 NP_HOST_PREFIX(운영="" · 테스트="t")로 갈립니다. · 앱 API 가 api. 가 아니라 app. 인 이유: api.nestpay.co.kr·tapi.nestpay.co.kr 는 발주사의 기존 결제 시스템(CyrexPay)이 이미 사용 중이라 사용할 수 없습니다. · 도메인 맨 앞을 뺀 nestpay.co.kr 접속은 www 로 301 이동. · 개발(로컬): DNS 가 없어 포트(6443/8443/9443/7443)로 같은 입구에 접속. · MariaDB(3307) 와 WAS 는 인터넷에 노출하지 않습니다(폐쇄망).

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 조회 결과 시스템 지갑 7종 확인: SETTLEMENT_CLEARING · UNMATCHED · FEE_REVENUE · EXPIRED · FORFEITED · SEIZED · SEIZE_BURNED. · 회원 지갑에서 돈이 나갈 때는 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, 기록용 스냅샷)
   │                               ※ 취소 권한: 매장·관리자만(회원 불가, 2026-07-27 정책) — 기한 강제 없음
   │                            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) 하고, 예정 시각이 되면 워커가 페이솔루스 출금요청 API로 제출하며, 이후 출금통지 웹훅으로 완료(또는 거절)가 확정됩니다. 출금은 유상(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)
        · ★페이솔루스 출금요청 API 제출(PaySolusPayoutApiClient.submit, 계약 전 스텁)
          → 접수번호 bankTranRef = "PNST-{txnId}", 상태 PENDING 유지(동기 확정 안 함)

 출금통지 웹훅 ─ X-Internal-Key ─► /webhooks/bank/withdraw-notice  (완료/거절 확정)
   · SUCCESS → confirmWithdrawal → CONFIRMED + "출금 완료" 알림
   · FAIL(거절) → 신청취소 · 선차감 복원(아래 실패 복원)
   (웹훅 미도착 등 결과불명은 PENDING 으로 남아 리컨실러(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) — 휴대폰 번호·카드번호·QR 로 즉시 전달

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

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

회원이 앱에서 충전 신청을 하면 페이솔루스 입금요청 API로 신청건(deposit_requests)이 만들어지고, 그 신청에만 유효한 입금코드(NC+8자리)가 발급됩니다. 회원이 신청한 금액 그대로 그 코드를 은행 이체 입금자명에 적어 보내면, 은행/PG 입금통지가 웹훅으로 들어오고, 워커가 코드로 신청건을 찾아 신청 금액과 정확히 일치할 때만 적립하며 그 외(무신청·금액 불일치)는 미매칭 보관합니다. 페이솔루스 입금요청 API는 계약 전 스텁입니다.

· 충전 규칙: 무신청 충전 불가 · 회원당 진행 중 신청은 1건(새 신청 시 이전 PENDING 자동취소) · 신청 금액과 정확 일치할 때만 적립 · 입금통지 미도착 시 만료 워커가 PENDING→EXPIRED 처리(단 만료·취소 후 늦게 입금돼도 코드+금액이 맞으면 적립 — 환불이 어려움) · 충전(1회/1일/월)·보유 한도는 신청 시점에 검사.

 은행/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) 신청건 매칭: 입금코드 → deposit_requests(진행 중) → 회원 → 충전 대상 카드(대표 우선), 신청 금액 정확 일치 확인
        2) 충전 강제 규약: 회원이 "인증계좌(실명+1원)" 보유해야만 자동 적립
        3) 재발행 카드면 새 카드로 갈아탐(REISSUED → reissued_to)

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

12. 업무 흐름 ⑥ 포인트 압류 SeizureService · AdminSeizureService

12.1 묶기 → 반환 또는 소각

사고(도용·분쟁·수사 협조)가 나면 그 돈이 빠져나가지 못하게 묶습니다. "쓸 수 있는 금액"을 따로 계산하지 않고 돈을 실제로 옮깁니다 — 돈 쓰는 곳(결제·출금·선물·정산)마다 검사를 넣는 방식은 한 곳만 빠뜨려도 묶은 돈이 새어 나가기 때문입니다.

 seize()   지갑 → SEIZED 로 옮김. 잔액이 줄어 어디서도 쓸 수 없음
   └ 대상 DR 금액 / SEIZED CR 금액  (+회원은 만료 임박 로트부터 차감)   [seizures.status HELD]
 refund()  조사 결과 정상 → 되돌림
   └ SEIZED DR 금액 / 대상 CR 금액  (+원래 유효기간을 이어받은 새 로트 = SEIZE_RESTORE)
 burn()    사기 확정 → 소각(회원에게 돌아가지 않음)
   └ SEIZED DR 금액 / SEIZE_BURNED CR 금액   (시스템 지갑끼리라 잔액 체인 없음)

· 거래는 ADJUST 계열 — SEIZE · SEIZE_RETURN · SEIZE_BURN. · 전부 아니면 전무(부분 반환·부분 소각 없음) — 나눠 처리해야 하면 압류를 나눠서 겁니다. · 앱에는 묶인 금액만 표시하고 관리자가 적은 사유는 내부용입니다(GET /app/me/seizure·/store/seizure). · 중복 처리 방지: lockOne 으로 잠근 뒤 HELD 인 것만 끝냅니다.

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