법인 계좌개설 서류 판정 시스템 (Corporate Account Opening System)

본 프로젝트는 미래에셋증권 영업점 직원이 법인/단체 고객의 계좌개설 시 필요한 서류를 정확하고 일관되게 안내할 수 있도록 지원하는 사내 룰 기반 판정 시스템입니다. 직원 간 안내 편차를 줄이고, 복잡한 예외 상황(신설법인, 고위험국가, 다단계 지배구조 등)에서의 리스크를 사전에 차단하기 위해 개발되었습니다.

---

🏗 시스템 아키텍처

본 시스템은 서버리스 환경(Vercel) 배포를 위해 Next.js 풀스택(App Router + API Routes) 기반으로 구축되었습니다.

• Frontend: Next.js App Router, Tailwind CSS, React
• Backend (API): Next.js API Routes (TypeScript)
• Engine: Rule Engine (상태 무상태 구조, JSON 기반 룰셋 평가)
• Deployment: Vercel (Root Directory: frontend)

[참고] 최초 설계는 Python(FastAPI) + SQLite로 진행되었으나, Vercel 서버리스 환경 배포를 위해 백엔드 핵심 엔진을 TypeScript 및 Next.js API 라우트로 이관하였습니다. 원본 Python 코드는 backend/ 폴더에 보존되어 있습니다.

---

🎯 핵심 기능

1. 다단계 룰 엔진 (Rule Engine)

   • 하드코딩된 로직을 지양하고, DB 형태의 JSON 조건식(Conditions) 평가 기반으로 작동합니다.
   • case_classifier: 14가지 케이스 코드(C01~C14)와 태그 도출 (ex. NEW_CORP, HIGH_RISK)
   • rule_engine: 우선순위 기반으로 조건을 평가하여 필수/조건부 서류 도출 및 상태(차단/에스컬레이션) 판정
   • document_resolver: 대체 가능 서류 그룹(예: 주주명부 or 사원명부) 제공

2. 직원용 5-Step 판정 위자드 (Wizard UI)

   • 사용자 친화적인 멀티 스텝 폼을 통해 고객 정보를 입력받습니다.
   • 판정 결과 화면에서 명확한 상태 뱃지 (접수 차단 / 보완 필요 / 승인 대상 등) 와 요구 서류를 렌더링합니다.

3. 관리자 대시보드 (Admin Dashboard)

   • 45종의 마스터 서류 유형, 14종의 케이스 유형, 그리고 26개의 활성화된 룰 목록을 직관적으로 조회할 수 있습니다.

---

🛠 폴더 구조

/
├── frontend/               # Next.js 애플리케이션 (배포 기준 폴더)
│   ├── src/app/
│   │   ├── page.tsx        # 메인 랜딩 페이지
│   │   ├── determination/  # 5-Step 판정 위자드 화면
│   │   ├── admin/          # 관리자 대시보드 화면
│   │   └── api/            # Next.js 백엔드 API Routes (/api/determine 등)
│   ├── src/lib/engine/     # TypeScript로 포팅된 핵심 룰 엔진 코어
│   └── globals.css         # UI 스타일 시트 (상세 테마/CI 지정)
├── backend/                # [Legacy] Python FastAPI 원본 소스
└── corp_account.md         # 프로젝트 초기 요구사항 명세서

---

🚀 로컬 실행 방법

이 프로젝트는 frontend 폴더를 루트로 하여 구동됩니다.

# 1. frontend 디렉토리로 이동
cd frontend

# 2. 패키지 설치
npm install

# 3. 로컬 개발 서버 실행 (localhost:3000)
npm run dev

브라우저에서 http://localhost:3000 에 접속하여 5-Step 판정 로직과 사이트 렌더링을 테스트하실 수 있습니다.

---

☁️ Vercel 배포 가이드

본 프로젝트는 Vercel에 최적화되어 있습니다. 아래 설정에 유의하여 배포를 진행하세요.

1. Vercel 대시보드 접속 -> Add New Project
2. 본 GitHub Repository(corp_account_docs) Import 클릭
3. ⭐ [중요] Configure Project (설정 화면):
   • Root Directory: 반드시 frontend 로 변경 후 Save
   • Framework Preset: Next.js (자동 선택됨)
   • 별도의 Environment Variables(환경변수) 설정은 현재 버전에서 요구되지 않습니다.
4. Deploy 버튼 클릭

---

📊 구현된 판정 시나리오 전체 목록

본 시스템은 기획서에 정의된 총 14종의 기본 케이스(C01~C14) 와 주요 예외/위험 시나리오(E01~E10) 를 100% 룰 엔진 기반으로 완벽하게 판정합니다.

🏢 기본 케이스 (C01 ~ C14)

• C01 (일반 법인 내점): 국내 영리법인 대표자 본인 내점 (필수 8종 서류)
• C02 (임직원 대리): 임직원 대리 신청 (재직증명서, 대리인 신분증, 위임장 추가)
• C03 (외부 대리인): 외부 수임인 대리 신청 (대리권 소명자료, 이사회 결의서 추가)
• C04 (공동대표 단독행사): 공동대표 중 단독 대표권 행사 가능 확인 서류 요구
• C05 (공동대표 공동행사): 전원 서명/날인 및 공동권한 행사 확인 서류 요구
• C06 (비영리법인 대표자 본인): 정관 및 규약 추가 요구
• C07 (비영리법인 대리인): 정관/규약 + 대리인 서류 요구
• C08 (법인격 없는 단체): 회칙/규약 등 단체 증빙 서류 요구
• C09 (외국법인): 외국법인 설립증빙, 번역문, 공증/아포스티유 요구 및 승인 대기(APPROVAL_PENDING) 처리
• C10 (신설법인): 설립 1년 미만 등으로 사업장 임대차계약서, 현판 사진 등 실체 확인 서류 강화
• C11 (실제소유자 확인 곤란): 5단계 이상 지배구조 등 복잡한 구조 시 심사/승인 필요
• C12 (고위험 플래그): 고위험 국가, PEP 등 관련 시 강화된 AML 심사 서류 요구
• C13 (상품별 추가 서류): 파생상품(적합성보고서), 해외주식(해외약정서), CMA(CMA약관) 등 결합 판정
• C14 (비대면 사전접수): 비대면으로 임시 접수 후 대면에서 실명확인이 완료될 때까지 승인 대기

🚨 예외 및 리스크 차단 룰 (Exception Rules)

• E01 (사업자 상태 이상): 휴업/폐업/확인불가 상태 시 즉각 접수 차단 (BLOCKED)
• E02 (서류 불일치): 명판, 인감, 서류 간 정보가 다를 경우 보완 필요 (NEEDS_SUPPLEMENT)
• E03/E04 (대리권 불명확): 공동대표 권한 미확인, 위임장 누락 시 접수 차단 (BLOCKED)
• E05 (실제소유자 미확인 / 다단계 체인): 소유자 식별 불가 혹은 다단계 시 심사/승인 필요 (ESCALATION_REQUIRED)
• E06 (신설법인 실체 의심): 신설법인의 사업장 증빙이 뚜렷하지 않을 경우 자금원천 설명 추가 요구
• E09 (고위험 요소 감지): 제재 대상국, 요주의 인물(PEP) 연루 시 준법감시 승인서 필수 (ESCALATION)
• E10 (복합 파생/해외상품 리스크): 파생상품 등 투자자보호 서류(위험고지서) 누락 시 접수 불가 보장

---

디자인 시스템

미래에셋증권 CI 가이드에 맞추어 주조색(Navy #003DA5, Orange #FF6B00)을 기반으로 금융권에 적합한 프리미엄 다크 테마 UI를 채택하였습니다.