정정지용
프로젝트 목록
프론트엔드TypeScript

금융권 자금세탁방지(AML) KYB 인증 플랫폼 프론트엔드

법인 고객 신원확인(KYB)과 본인인증(eKYC)을 통합한 금융규제 준수 솔루션의 React 기반 웹 클라이언트

kyb-client최근 업데이트 2026년 7월 27일

개요

자금세탁방지 규제(RegTech/AML)를 준수하기 위한 법인 고객 신원확인 시스템의 프론트엔드입니다. 가입자, 심사자, 관리자 3개 역할별 라우팅과 다단계 KYB 절차(법인정보 입력 → 실소유자 구조도 작성 → 임직원 등록 → eKYC 본인인증 → 증빙 제출)를 지원합니다. useb eKYC 연동을 공식 표준 흐름(iframe + postMessage)으로 마이그레이션하여 환경 간 정합성 문제를 해결했으며, TypeScript 기반 API 레이어와 React Query를 통해 타입 안전성을 확보했습니다.

담당 역할

법인 KYB 절차 UI 구현, eKYC iframe 연동 표준화, Docker 기반 런타임 환경설정 주입 아키텍처 설계 및 배포 파이프라인 구축

아키텍처 다이어그램

레포지토리 분석 결과를 바탕으로 자동 생성된 구조도입니다.

아키텍처

KYB 시스템 전체 아키텍처

가입자/심사자/관리자 3개 역할별 라우팅, API 레이어, eKYC 연동, 상태 관리 구조를 보여주는 다이어그램

다이어그램을 그리는 중…
시퀀스

eKYC 표준 흐름 시퀀스

useb eKYC 공식 표준 흐름으로 전환한 후의 본인인증 프로세스 — iframe postMessage 기반 2단계 메시지 수신

다이어그램을 그리는 중…
배포

Docker 런타임 환경설정 주입 흐름

동일 이미지로 dev/stg/prd 배포를 지원하기 위한 런타임 config.js 주입 메커니즘

다이어그램을 그리는 중…

기술스택

각 기술을 이 프로젝트에서 어떤 용도로 썼는지 정리했습니다.

언어

  • TypeScript전체 소스코드 타입 안전성 확보 및 API 인터페이스 정의

프론트엔드

  • ReactUI 컴포넌트 라이브러리 및 라우팅 기반 SPA 구현
  • React Query서버 상태 캐싱 및 GET/POST/PUT 요청 추상화
  • Redux Toolkit글로벌 상태 관리(에러, 심사자 목록, 공지사항)
  • React Hook Form폼 상태 관리 및 유효성 검증
  • SCSS컴포넌트 스타일링 및 유틸리티 믹스인
  • styled-componentsusebeauty 커스텀 컴포넌트 라이브러리 스타일링
  • react-i18next한국어/영어 다국어 지원
  • AxiosHTTP 클라이언트 및 인터셉터 기반 인증 처리

도구

  • Vite개발 서버 및 프로덕션 빌드 도구

인프라

  • Docker환경별 런타임 config.js 주입 및 nginx 기반 멀티스테이지 빌드

테스트

  • PlaywrightE2E 테스트 자동화(로그인, 회원가입 시나리오)

핵심 포인트

  • TypeScript namespace 기반 API 타입 시스템 구축 — GET/POST/PUT 요청별 Request/Response 인터페이스 선언으로 타입 안전성 확보
  • useb eKYC 비공식 커스텀 통합(WebSocket + room_key)을 공식 표준 흐름(iframe postMessage)으로 마이그레이션하여 환경 전환 시 발생하던 결과 라우팅 실패 해소
  • Docker 엔트리포인트에서 envsubst로 런타임 환경변수를 /config.js로 주입, 동일 이미지로 dev/stg/prd 배포 지원
  • 3개 역할(가입자/심사자/관리자)별 라우팅 및 인증 가드 구현 — localStorage 토큰 기반 역할별 API 인증
  • react-d3-tree로 법인 실소유자 계층 구조(OwnerHierarchy) 시각화 및 CRUD 인터페이스 제공

문제와 해결

문제eKYC 연동에서 환경별 customer 자격증명 불일치로 fkr1 전환 시 모달이 닫히지 않는 사고 발생

해결비공식 WebSocket push 방식을 폐기하고 useb 공식 iframe + postMessage 흐름으로 전환, cross-device QR도 useb iframe이 자체 제공하도록 변경

문제Vite 빌드 산출물에 환경변수가 하드코딩되어 환경마다 별도 이미지 빌드 필요

해결public/config.js를 런타임 템플릿화하고 Docker 엔트리포인트에서 envsubst로 주입, nginx Cache-Control: no-store로 브라우저 캐싱 방지

문제API 응답 envelope이 { data: { kyc_token_param } }와 { kyc_token_param } 두 가지로 혼재

해결BE와 협의하여 { data: { ... } } 단일 구조로 표준화하고 FE 분기 로직 제거

레포지토리 정보

생성
2026년 7월 27일
최근 커밋
2026년 7월 27일
크기
15,943 KB
라이선스
없음

언어 구성

  • TypeScript81.6%
  • SCSS16.1%
  • JavaScript0.8%
  • Python0.7%
  • HTML0.4%
  • CSS0.2%
  • Shell0.1%
  • Dockerfile0.1%

이 문서는 2026년 7월 28일 에 자동 분석으로 생성되었습니다.