Your financial hole-in-Won — 외국인 근로자의 급여를 지키는 가장 정확하고 정중한 방법

🌐 웹 서비스 바로가기 · ⚙️ 백엔드 저장소 · 🐛 이슈 제보하기

1. 프로젝트 개요
2. 왜 & 어떻게 — 문제 정의와 차별점
3. 프론트엔드 & 백엔드 아키텍처
4. 기술 스택
5. 주요 기능
6. 설치 및 실행 방법
7. 사용 방법 및 데모 시나리오
8. 테스트 및 코드 품질
9. 팀원 소개
10. 기여 방법
11. 라이센스

Foreign-One은 언어 장벽과 낯선 노무·세무 체계 속에서 급여 이상을 스스로 발견하기 어려운 외국인 근로자를 위해, 근로계약서·임금명세서·실제 입금액을 자동으로 대조하고, 문제가 발견되면 고용주에게 감정적 마찰 없이 사실에 근거해 정중하게 문의할 수 있는 서면까지 자동 생성해주는 스마트 금융 권리 케어 플랫폼입니다.

한국에서 일하는 E-9, D-2 등 체류자격의 외국인 근로자는 언어 장벽과 생소한 노무·세무 구조 때문에 급여명세서와 실제 통장 입금액 사이의 차액, 미지급, 부당 공제를 제때 인지하기 어렵습니다. 문제를 인지해도 고용주와의 불필요한 감정 마찰 없이 법적·사실적 근거를 갖춘 공손한 문의 서면을 작성하는 일 자체가 큰 진입장벽입니다.

1. 결정론적 Rule Engine과 비결정론적 AI Agent의 엄격한 분리

금액 계산과 이상징후 판단을 LLM에 맡기면 환각(Hallucination)으로 실제 금융 사고가 발생할 수 있습니다. 그래서 모든 금액 차이(원 단위 계산), 계약 급여일 준수 여부, 이상징후 유형 분류는 백엔드의 Java Rule Engine이 100% 결정론적으로 계산합니다. AI Agent(OpenAI / Gemini)는 이미 계산이 끝난 팩트 데이터만 전달받아, 고용주 전달용 비즈니스 공손체 서면 작성과 근로자 모국어 번역·설명 생성에만 역할을 한정합니다.

2. 단문 방어 가드레일 시스템

LLM의 환각(Hallucination) 및 35자 미만 무성의한 단문 출력을 원천 차단하기 위해 프론트엔드·백엔드 이중 가드레일을 구축했습니다. 항상 ① 인사말 → ② 근로계약서 제4조 및 명세서 실지급액 근거 인용 → ③ 통장 실입금액과의 차액 확인 요청 → ④ 정중한 마무리, 4단계로 구성된 완성형 정중문만 출력되도록 강제합니다.

3. 데이터 파이프라인

flowchart LR
    A["📄 금융거래 / 명세서 OCR<br/>(Google Document AI)"] --> B["⚙️ PayCheck Rule Engine<br/>(100% 결정론적 계산)"]
    B --> C["🤖 AI Agent Service<br/>(4단계 가드레일 정중문 & 번역)"]
    C --> D["📊 Calendar & Dashboard<br/>(실시간 시각화 동기화)"]

    style A fill:#f8f9fa,stroke:#4a5568,stroke-width:1.5px
    style B fill:#ebf8ff,stroke:#3182ce,stroke-width:1.5px
    style C fill:#f0fff4,stroke:#38a169,stroke-width:1.5px
    style D fill:#fefcbf,stroke:#d69e2e,stroke-width:1.5px

Foreign-One은 사용자 경험(UX)과 안정적인 금융 데이터 처리의 분리를 위해 프론트엔드와 백엔드의 역할을 엄격히 분리하여 설계되었습니다.

외국인 근로자 친화적인 직관적 UX와 다국어 금융 권리 인터페이스

• 다국어 온보딩 & 사용자 플로우: i18next 기반 한국어·영어·베트남어 실시간 토글을 지원하여 언어 장벽 없이 비자/체류자격 및 근로계약 조건을 간편하게 등록
• 실시간 금융 대시보드 & 시각화: 3자 대조 분석 결과, 월별 급여 내역, 이상징후(미지급/부당공제) 카드를 직관적으로 시각화 (Recharts, Shadcn UI, Radix UI)
• 스마트 문서 OCR 사용자 보정 UI: Google Cloud Document AI 추출 결과를 시각적으로 확인하고, 오인식된 필드를 사용자가 직접 확인·수정할 수 있는 보정 인터페이스 제공
• 특화 권리 분석 화면:
  • TaxCheck: 실제 급여명세서 기반 근로소득세·4대보험 공제율 분석 및 결과 저장/조회
  • ExitCheck: E-9 근로자의 출국 만기 시 퇴직금 및 외국인전용보험(출국만기보험·귀국비용보험) 정산 시뮬레이션
• AI 서면 프리뷰 & 대조 뷰어: 백엔드에서 생성된 4단계 완성형 정중문과 모국어 번역본을 나란히 확인하고 원클릭 복사하여 고용주에게 전달할 수 있는 전용 UI
• 클라이언트 가드레일: 입력 데이터 유효성 검증 및 35자 미만 단문 발송 방지 UI 방어 로직 적용

100% 결정론적 계산 엔진과 AI Agent 파이프라인 오케스트레이션

• PayCheck Rule Engine (도메인 엔진):
  • 근로계약서 · 임금명세서 · 통장 실입금액 3자 데이터를 원 단위로 정밀 교차 검증
  • 계약 급여일 준수 여부 및 이상징후(과소지급, 지연지급, 미등록 공제 등) 유형을 100% 결정론적 룰 기반으로 자동 판정 (LLM 계산 배제)
• 동적 캘린더 이벤트 프로젝션 & Profile 영속화:
  • 금융 거래, 계약 급여일, 체류·출국 일정을 타임라인으로 동적 투영하는 이벤트 프로젝션 설계
  • 외국인 근로자의 비자/체류자격, 계약 조건, 모국어 설정을 영속화하고 전 도메인 흐름에 실시간 반영
• TaxCheck & ExitCheck 도메인 로직: 현행 근로기준법 및 외국인고용법 기준에 기반한 세무/퇴직금 계산 및 시나리오 검증
• Document AI OCR & PDFBox 파이프라인: 비정형 다국어 PDF/이미지 명세서·계약서에서 핵심 금융 필드(기본급, 수당, 공제내역, 실수령액 등) 고정밀 자동 추출
• AI Agent Service & 가드레일 (OpenAI / Gemini):
  • Rule Engine의 팩트 연산 결과와 연계된 사업주 전달용 '4단계 완성형 정중문' 프롬프트 엔지니어링 및 모국어 번역 자동 생성
  • LLM의 환각(Hallucination) 및 35자 미만 단문 출력을 원천 차단하는 백엔드 가드레일 강제
• 데이터 영속성 & 무중단 시드 인프라:
  • Spring Data JPA 및 PostgreSQL 16 (Render 배포) 기반의 안정적인 트랜잭션 관리
  • 무중단 시드 데이터 재초기화 파이프라인(POST /api/dev/reset-seed) 설계로 시연 및 운영 안정성 확보

• 3자 대조 시각화 & 금융 캘린더 — 급여일, 체류·출국 일정을 타임라인으로 표시하고 이상징후 카드로 강조
• 스마트 문서 OCR 사용자 보정 UI — Document AI가 추출한 다국어 명세서·계약서 금융 필드를 시각적으로 확인하고 직접 보정
• AI 사장님 문의문 뷰어 — 팩트 기반 4단계 완성형 정중문과 모국어 번역 대조 화면 및 원클릭 복사
• 글로벌 다국어 UI — 한국어·영어·베트남어 3개 국어 실시간 토글 및 원화 통화 단위 지원 (i18next)

• PayCheck Rule Engine — 계약서 · 명세서 · 통장 입금액 3자 데이터 원 단위 자동 교차 검증 (100% 결정론적 연산)
• 동적 캘린더 이벤트 프로젝션 — 금융 거래, 계약 급여일, 체류·출국 일정을 타임라인으로 동적 투영 및 Profile 영속화
• Document AI OCR 파이프라인 — 비정형 다국어 PDF/이미지 명세서·계약서의 핵심 금융 데이터 자동 추출
• AI Agent & 단문 방어 가드레일 — Rule Engine 연산 팩트 기반 4단계 정중문 생성 및 35자 미만 단문 출력 원천 차단
• 무중단 시드 데이터 재초기화 — 데모 시연 및 운영 안정성을 위한 실시간 시드 데이터 리셋 파이프라인 (POST /api/dev/reset-seed)

💡 온라인 체험: 로컬 환경 설정 없이 **Foreign-One 바로가기**에서 즉시 웹 서비스를 체험해 보실 수 있습니다.

• Node.js 18 이상
• JDK 21
• PostgreSQL 16 (또는 로컬 테스트용 H2)

cd backend
./gradlew bootRun

cd frontend
npm install
npm run dev

시드 데모 유저: 베트남 국적 근로자 '민수' (E-9) · 소속 사업장 '한국정밀'

8월 급여 시나리오

• 임금명세서 기재 금액: 2,380,000원
• 실제 통장 입금액: 2,300,000원
• → 시스템이 80,000원 차액을 자동 감지

자동 생성되는 4단계 정중문 예시

1. 인사말
2. 근로계약서 제4조 및 명세서 실지급액 근거 인용
3. 통장 실입금액과의 차액 확인 요청
4. 정중한 마무리

생성된 문의문은 근로자의 모국어로 함께 번역되어, 발송 전 내용을 검토할 수 있습니다.

# 백엔드 — PayCheck 로직 테스트
./gradlew test --tests "*Paycheck*"

# 프론트엔드 — 타입 검증
npx tsc --noEmit

이승빈 @Bin0917 🤖 Full-Stack / AI Agent	박시현 @foxihyun 🎨 Frontend	하태욱 @ChocoChip0519 ⚡ AI Fullstack
Core Domain 풀스택 개발 (PayCheck·Calendar·Profile) OpenAI API & Rule Engine 연계 4단계 정중문 리포트 구현 Document AI 기반 다국어 OCR 파이프라인 및 보정 UI 구축 Vercel/Render 클라우드 배포 및 무중단 시드 리셋 API 운영 i18next 활용 한·영·베 다국어 시스템 및 반응형 UI 구축	프론트엔드 개발 (Dashboard, Records, TaxCheck) 백엔드 API 연동 및 실제 급여·세금 데이터 기반 화면 구현 TaxCheck 분석 결과 저장·조회 기능 개발 Dashboard·Records·TaxCheck 간 데이터 연동 및 사용자 흐름 개선 공통 Navbar 적용	초기 온보딩 페이지 플로우 설계 및 구현 생성형 AI 챗봇 어시스턴트 프론트/백엔드 개발 ExitCheck(출국 체크) 기능 개발 및 렌더링 안정성 개선 온보딩·대시보드·기록·세금체크 다국어 지원 UI 리팩토링

1. 이 저장소를 Fork 합니다.
2. 기능 브랜치를 생성합니다. (git checkout -b feature/기능명)
3. 변경 사항을 커밋합니다. (git commit -m "feat: 기능 설명")
4. 브랜치에 Push 합니다. (git push origin feature/기능명)
5. Pull Request를 생성합니다.

이 프로젝트는 MIT License를 따릅니다.