fin-normalize-kr

v1.1.0

Published

7 months ago

한국 금융 데이터(카드/계좌/사업자등록번호/금액)의 검증, 정규화, 포맷팅, 마스킹, 자동 감지를 위한 TypeScript 라이브러리

FinNormalizeKR 🇰🇷

한국 금융 데이터의 검증, 정규화, 포맷팅, 마스킹, 자동 감지를 위한 종합 TypeScript 라이브러리

🎯 해결하고자 하는 문제

한국 핀테크 개발의 공통 과제

한국의 금융 서비스를 개발할 때 개발자들이 마주하는 반복적이고 복잡한 문제들:

카드번호 처리의 복잡성
- 16자리 Visa/Mastercard, 15자리 AMEX, 다양한 한국 BC카드 포맷
- Luhn 알고리즘 검증 구현
- BIN(Bank Identification Number) 기반 카드사/은행 자동 감지
- 사용자 친화적 포맷팅 (4-4-4-4)
계좌번호 검증의 어려움
- 은행별로 다른 자릿수 (11자리~14자리)
- PREFIX 기반 은행 식별
- 개인정보 보호를 위한 마스킹 처리
사업자등록번호의 복잡한 검증
- 가중치 기반 체크썸 알고리즘 (국세청 표준)
- 표준 포맷팅 (123-45-67890)
다양한 금액 표현의 정규화
- ₩15,000, 1만원, 15000원, 1.5만원 등 다양한 입력 처리
- 천의 자리 콤마, 한국어 단위 (만, 억) 처리
텍스트에서 금융 정보 자동 추출
- 자연어 텍스트에서 카드번호, 계좌번호 등 자동 감지
- 개인정보 자동 마스킹

기존 해결 방식의 한계

// ❌ 문제: 프로젝트마다 각각 구현
function validateCard(cardNumber: string): boolean {
  // 간단한 길이 체크만... Luhn 알고리즘은 누락
  return cardNumber.replace(/\s/g, '').length === 16;
}

function formatCard(cardNumber: string): string {
  // 하드코딩된 포맷팅... AMEX는 지원 안됨
  return cardNumber.match(/.{1,4}/g)?.join('-') || '';
}

// 카드사 감지는... 각자 알아서? 🤷‍♂️

결과: 중복 구현, 버그, 유지보수 비용, 일관성 부족

✨ FinNormalizeKR의 해결책

🚀 핵심 가치 제안

완벽한 타입 안정성: 엄격한 TypeScript로 런타임 에러 방지
포괄적 검증: 국제 표준 + 한국 금융 규정 완벽 지원
자동 감지: AI 수준의 텍스트 파싱 및 금융 정보 추출
React 완전 지원: 즉시 사용 가능한 훅과 컴포넌트
제로 의존성: 외부 라이브러리 없이 가벼운 구현

💡 혁신적 기능

1. 스마트 은행 감지 시스템

import { detectBankUnified } from 'fin-normalize-kr';

// 🎯 카드번호에서 은행 자동 감지
const cardResult = detectBankUnified('4300-1234-5678-9012');
// {
//   bankCode: 'kb',
//   bankName: 'KB국민은행',
//   confidence: 'high',
//   source: 'card_bin',
//   additionalInfo: {
//     cardIssuer: 'kb',
//     cardScheme: 'visa'
//   }
// }

// 🎯 계좌번호에서 은행 자동 감지
const accountResult = detectBankUnified('123-1234-5678901');
// {
//   bankCode: 'kb',
//   bankName: 'KB국민은행',
//   confidence: 'high',
//   source: 'account_prefix'
// }

2. 통합 금융 데이터 처리

import { normalizeCard, normalizeAccount, normalizeBizNumber } from 'fin-normalize-kr';

// 🔄 카드번호 완전 처리
const cardInfo = normalizeCard('9403123456789012');
// {
//   isValid: true,
//   scheme: 'bc',
//   issuer: 'kb',
//   bankCode: 'kb',
//   bankName: 'KB국민은행',
//   formatted: '9403-1234-5678-9012',
//   masked: '9403-****-****-9012',
//   digits: '9403123456789012'
// }

// 🏦 계좌번호 스마트 처리
const accountInfo = normalizeAccount('123456789012');
// {
//   isValid: true,
//   bankCode: 'kb',
//   bankName: 'KB국민은행',
//   formatted: '123-456789-012',
//   masked: '123-******-012'
// }

3. 자연어 텍스트에서 자동 추출

import { detectFinancialData } from 'fin-normalize-kr';

const text = "제 카드번호는 4300-1234-5678-9012이고 계좌는 123-456-789012 입니다.";
const results = detectFinancialData(text);
// [
//   {
//     type: 'card',
//     value: '4300-1234-5678-9012',
//     bankInfo: { bankName: 'KB국민은행', ... },
//     position: { start: 8, end: 27 }
//   },
//   {
//     type: 'account',
//     value: '123-456-789012',
//     bankInfo: { bankName: 'KB국민은행', ... },
//     position: { start: 34, end: 48 }
//   }
// ]

📚 완벽한 React 지원

즉시 사용 가능한 컴포넌트

import { BankDetectionInput, CardNumberInput } from 'fin-normalize-kr';

function PaymentForm() {
  return (
    <div>
      {/* 🎯 자동 은행 감지 입력 */}
      <BankDetectionInput
        placeholder="계좌번호 또는 카드번호 입력"
        onBankDetected={(code, name, confidence) => {
          console.log(`${name} 감지 (신뢰도: ${confidence})`);
        }}
      />

      {/* 💳 전용 카드 입력 */}
      <CardNumberInput
        autoFormat={true}
        onBankDetect={(code, name) => {
          console.log(`발급은행: ${name}`);
        }}
      />
    </div>
  );
}

고성능 React 훅

import { useBankDetection, useCardNumber } from 'fin-normalize-kr';

function SmartPaymentInput() {
  const {
    value,
    setValue,
    bankName,
    confidence,
    isCardNumber,
    isAccountNumber
  } = useBankDetection();

  return (
    <div>
      <input
        value={value}
        onChange={(e) => setValue(e.target.value)}
        placeholder="금융정보 입력"
      />
      {bankName && (
        <p>감지된 은행: {bankName} ({confidence} 신뢰도)</p>
      )}
      {isCardNumber && <p>💳 카드번호로 감지</p>}
      {isAccountNumber && <p>🏦 계좌번호로 감지</p>}
    </div>
  );
}

🛠 설치 및 사용법

설치

# npm
npm install fin-normalize-kr

# yarn
yarn add fin-normalize-kr

# pnpm
pnpm add fin-normalize-kr

기본 사용법

// ES6 Modules
import { normalizeCard, detectBankUnified } from 'fin-normalize-kr';

// CommonJS
const { normalizeCard, detectBankUnified } = require('fin-normalize-kr');

// 즉시 사용
const result = normalizeCard('4300123456789012');
console.log(result.bankName); // 'KB국민은행'

TypeScript 지원

완벽한 타입 정의로 개발 경험 극대화:

import type {
  CardInfo,
  BankInfo,
  UnifiedBankDetectionResult
} from 'fin-normalize-kr';

// 모든 반환값이 완벽하게 타이핑됨
const cardInfo: CardInfo = normalizeCard(input);
const bankInfo: UnifiedBankDetectionResult = detectBankUnified(input);

🏗 아키텍처 및 설계 원칙

모듈화된 구조

src/
├── core/           # 핵심 비즈니스 로직
│   ├── card/       # 카드 처리 (BIN, Luhn, 포맷팅)
│   ├── account/    # 계좌 처리 (은행 패턴, 검증)
│   ├── biz/        # 사업자등록번호 처리
│   ├── amount/     # 금액 처리 (한국어 단위)
│   └── detect/     # 통합 감지 시스템
├── hooks/          # React 훅
├── components/     # React 컴포넌트
└── utils/          # 공통 유틸리티

설계 원칙

단일 책임 원칙: 각 모듈은 하나의 금융 데이터 타입에 집중
의존성 역전: 추상화에 의존, 구체적 구현에 의존하지 않음
확장성: 새로운 은행, 카드사 쉽게 추가 가능
성능 최적화: 메모이제이션, 지연 로딩 적용
타입 안정성: 모든 API가 완전히 타이핑됨

🧪 품질 보증

포괄적 테스트

단위 테스트: 각 함수별 엣지 케이스 포함 100% 커버리지
통합 테스트: 실제 사용 시나리오 기반 테스트
타입 테스트: TypeScript 컴파일 타임 검증
성능 테스트: 대용량 데이터 처리 벤치마크

npm test                 # 모든 테스트 실행
npm run test:coverage    # 커버리지 리포트
npm run test:watch       # 감시 모드

CI/CD 파이프라인

✅ 자동화된 테스트: PR 생성시 전체 테스트 스위트 실행
✅ 코드 품질 검사: ESLint, Prettier, TypeScript strict 모드
✅ 보안 스캔: 의존성 취약점 자동 스캔
✅ 자동 릴리즈: 시맨틱 버전닝 기반 자동 배포

📈 성능 및 최적화

벤치마크 결과

카드번호 검증 (10,000회):     평균 0.15ms
계좌번호 포맷팅 (10,000회):   평균 0.08ms
은행 감지 (10,000회):        평균 0.22ms
텍스트 파싱 (1,000회):       평균 1.2ms

최적화 기법

메모이제이션: 반복 계산 결과 캐싱
지연 로딩: 필요시에만 모듈 로드
트리 쉐이킹: 사용하지 않는 코드 자동 제거
번들 크기 최적화: 압축시 ~15KB

🔒 보안 및 개인정보 보호

내장된 보안 기능

자동 마스킹: 민감 정보 자동 마스킹 (****-****-****-1234)
메모리 안전: 민감 데이터 즉시 가비지 컬렉션
입력 검증: XSS, 인젝션 공격 방어
개인정보 보호: 실제 개인정보 처리하지 않음 (패턴 매칭만)

📖 API 레퍼런스

핵심 함수

`normalizeCard(input: string): CardInfo`

카드번호 완전 처리 (검증, 포맷팅, 마스킹, 은행 감지)

`normalizeAccount(input: string): AccountInfo`

계좌번호 완전 처리 (검증, 포맷팅, 마스킹, 은행 감지)

`detectBankUnified(input: string): UnifiedBankDetectionResult`

카드번호/계좌번호에서 통합 은행 감지

`detectFinancialData(text: string): DetectedInfo[]`

자연어 텍스트에서 금융 정보 자동 추출

React 훅

`useBankDetection(options?): UseBankDetectionResult`

실시간 은행 감지 훅

`useCardNumber(options?): UseCardNumberResult`

카드번호 입력 관리 훅

React 컴포넌트

`<BankDetectionInput />`

자동 은행 감지 입력 컴포넌트

`<CardNumberInput />`

카드번호 전용 입력 컴포넌트

🌟 실제 사용 사례

1. 핀테크 스타트업

// 송금 서비스의 계좌번호 검증
const { isValid, bankName } = normalizeAccount(userInput);
if (isValid) {
  showConfirmation(`${bankName}으로 송금합니다.`);
}

2. 이커머스 결제

// 카드 정보 자동 완성
const { issuer, scheme, bankName } = normalizeCard(cardNumber);
displayCardInfo(bankName, scheme); // 'KB국민은행 VISA'

3. 개인정보 자동 마스킹

// 고객 센터 채팅에서 민감 정보 자동 처리
const maskedText = detectFinancialData(message)
  .reduce((text, info) => text.replace(info.value, info.masked), message);

🤝 기여 가이드

우리는 커뮤니티의 기여를 환영합니다!

개발 환경 설정

# 레포지토리 클론
git clone https://github.com/CraftsManShip001/fin-normalize-KR.git
cd fin-normalize-KR

# 의존성 설치
npm install

# 개발 모드 실행
npm run dev

# 테스트 실행
npm test

# 빌드
npm run build

기여 방법

이슈 리포트: 버그 발견 또는 기능 제안
문서 개선: README, API 문서, 예제 개선
코드 기여: 새 기능, 버그 수정, 성능 개선
테스트 추가: 엣지 케이스, 새로운 시나리오

코드 스타일

TypeScript: 엄격한 타입 체크
ESLint: Airbnb 기반 린팅 규칙
Prettier: 자동 코드 포맷팅
Conventional Commits: 커밋 메시지 컨벤션

📋 로드맵

v2.0 (계획)

[ ] AI 기반 자연어 금융 정보 추출 향상
[ ] 새로운 금융 데이터 타입 지원 (주민번호, 외국인등록번호)
[ ] 국제 금융 데이터 지원 (미국, 일본, 중국)
[ ] React Native 전용 컴포넌트

v2.1 (계획)

[ ] 실시간 유효성 검증 API 연동
[ ] 은행 API 연동을 통한 실시간 계좌 확인
[ ] 프리미엄 기능: 대용량 배치 처리

📄 라이선스

MIT License - 자세한 내용은 LICENSE 파일을 참조하세요.

🔗 링크

GitHub: https://github.com/CraftsManShip001/fin-normalize-KR
npm: https://www.npmjs.com/package/fin-normalize-kr
이슈 트래커: https://github.com/CraftsManShip001/fin-normalize-KR/issues
문서: https://github.com/CraftsManShip001/fin-normalize-KR/wiki

Made with ❤️ for Korean FinTech

한국 핀테크 생태계의 발전을 위해 만들어진 라이브러리입니다. 여러분의 의견과 기여를 기다립니다!