Node.js와 TypeScript를 활용한 AI 기반 금융 웰니스 어시스턴트 구축

서론 (Introduction)

인사(HR)팀이나 급여(Payroll) 팀에 번거롭게 묻지 않고도 직원들이 자신의 급여 명세서, 공제 항목, 세금 절감 기회를 즉시 이해할 수 있다면 어떨까요?

이 포스트에서는 바로 그 역할을 수행하는 보안이 강화된 AI 기반 금융 웰니스 어시스턴트(financial wellness assistant)를 구축하는 과정을 안내해 드리겠습니다. 이 시스템은 구조화된 급여 데이터와 업로드된 급여 명세서 문서를 모두 분석한 다음, 문서에 근거한(document-grounded) 설명을 직원 친화적인 쉬운 언어로 제공합니다.

우리가 해결하려는 문제 (The Problem We're Solving)

급여 구성 요소, 법정 공제액, 비용 상환 및 연간 누계(year-to-date) 값이 종종 압축적이고 기술적인 형식으로 제시되기 때문에 직원들은 급여 명세서를 해석하는 데 어려움을 겪는 경우가 많습니다. 이는 급여, 인사(HR) 및 재무 팀에 반복적인 문의를 발생시킵니다.

직원들의 일반적인 질문:

"이번 달 실수령액(net salary)이 왜 더 적나요?"
"HRA(주택 임대료 보조금)를 얼마나 받았나요?"
"어떤 공제 항목이 적용되었나요?"
"세금을 어떻게 더 절약할 수 있나요?"

목표는 민감한 금융 정보에 대한 엄격한 사용자 수준의 개인정보 보호를 유지하면서, 즉각적이고 개인화되었으며 문서에 기반한 응답을 제공함으로써 운영 부하를 줄이는 것입니다.

우리가 구축한 것 (What We Built)

다음 기능을 포함한 완전한 AI 기반 금융 웰니스 어시스턴트:

보안 인증 (Secure Authentication) - 역할 기반 액세스 제어(role-based access control)가 적용된 JWT 기반 인증
급여 명세서 처리 (Payslip Processing) - PDF 또는 이미지 업로드, AI 비전(vision) 기능을 사용한 데이터 추출
AI 기반 질의응답 (AI-Powered Q&A) - 근거 있는 응답과 함께 자연어로 질문
세금 시뮬레이션 (Tax Simulation) - 추가 투자에 따른 세금 부채(tax liability)의 영향 확인
투자 체크리스트 (Investment Checklist) - 개인화된 증빙 제출 체크리스트
YTD 요약 (YTD Summary) - 연간 누계 급여 및 세금 요약
트렌드 분석 (Trend Analysis) - 월별 급여 비교
급여 상세 내역 (Salary Breakdown) - 수입 및 공제액의 상세 보기

기술 스택 (Technology Stack)

계층 (Layer)	기술 (Technology)
백엔드 (Backend)	Node.js, Express.js, TypeScript
...

시스템 아키텍처 (System Architecture)

┌─────────────────────────────────────────────────────┐
│              Frontend (HTML/CSS/JS)                 │
│              http://localhost:3000                  │
...

프로젝트 구조 (Project Structure)

financial-wellness-ai-agent/
├── src/
│   ├── config/               # 설정 파일 (Configuration files)
...

주요 기능 설명 (Key Features Explained)

1. 보안 인증 (Secure Authentication)

역할 기반 액세스 제어 (Role-based access control)를 포함한 JWT 기반 인증을 통해 직원이 자신의 데이터에만 접근할 수 있도록 보장합니다.

export const authenticate = (req, res, next) => {
  const token = req.headers.authorization?.split(' ')[1];
  if (!token) return res.status(401).json({ error: 'Unauthorized' });
...

2. AI 기반 문서 처리 (AI-Powered Document Processing)

시스템은 AI 비전 (AI vision)을 사용하여 급여 명세서 (payslip) 문서에서 구조화된 데이터를 추출합니다:

export const EXTRACT_PAYSLIP_PROMPT = `
You are a payroll data extraction assistant. Analyze the provided payslip document 
and extract the following fields in a valid JSON format.
...

3. 근거 기반 AI 응답 (Grounded AI Responses)

환각 (hallucinations) 현상을 방지하기 위해 모든 AI 응답은 사용자의 실제 급여 데이터에 근거합니다:

export const GROUNDED_QUERY_PROMPT = (userQuery, userData) => `
You are an employee-friendly financial wellness assistant.

...

4. 세금 시뮬레이션 (Tax Simulation)

시뮬레이션 기능을 갖춘 간소화된 세금 계산:

export class TaxService {
  private static readonly TAX_SLABS = [
    { limit: 250000, rate: 0 },
...

API 엔드포인트 개요 (API Endpoints Overview)

인증 (Authentication)

메서드 (Method)	엔드포인트 (Endpoint)	설명 (Description)
POST	`/api/auth/login`	사용자 로그인 (Login user)

급여 명세서 관리 (Payslip Management)

메서드 (Method)	엔드포인트 (Endpoint)	설명 (Description)
POST	`/api/payslip/upload`	급여 명세서 업로드 (Upload payslip)
...

AI 질의 (AI Queries)

메서드 (Method)	엔드포인트 (Endpoint)	설명 (Description)
POST	`/api/query/ask`	AI에게 질문하기 (Ask AI question)
POST	`/api/query/explain`	구성 요소 설명하기 (Explain component)

세금 서비스 (Tax Services)

Method	Endpoint	Description
GET	`/api/tax/summary`	세금 요약 (Tax summary)
...

데모 워크스루 (Demo Walkthrough)

1. 로그인 (Login)

POST /api/auth/login
{
  "email": "john.doe@company.com",
...

2. AI에게 질문하기 (Ask AI Question)

POST /api/query/ask
{
  "question": "How much HRA did I receive?"
...

응답 (Response):

귀하의 HRA (House Rent Allowance, 주택 임차 수당) 내역:

최근 달 (2026년 6월):
...

3. 세금 시뮬레이션 (Tax Simulation)

POST /api/tax/simulate
{
  "additionalInvestment": 50000
...

응답 (Response):

세금 절감 시뮬레이션 (Tax Savings Simulation):

추가 투자액: ₹50,000
...

설치 및 설정 (Installation and Setup)

# 저장소 클론 (Clone the repository)
git clone git@github.com:mohin-sheikh/ai-financial-assistant.git
cd ai-financial-assistant
...

데모 자격 증명 (Demo Credentials)

역할 (Role)	이메일 (Email)	비밀번호 (Password)
직원 (Employee)	john.doe@company.com	demo123
관리자 (Admin)	admin@company.com	admin123

테스트 (Testing)

# 모든 테스트 실행 (Run all tests)
npm test

...

보안 기능 (Security Features)

만료 시간이 포함된 JWT 기반 인증 (JWT-based authentication)
역할 기반 액세스 제어 (Role-based access control) (직원, 관리자, 급여 담당자)
사용자 수준의 데이터 격리 (User-level data isolation)
속도 제한 (Rate limiting) (15분당 100회 요청)
모든 사용자 작업에 대한 감사 로그 (Audit logging)
입력 값 검증 및 정화 (Input validation and sanitization)
보안 헤더를 위한 Helmet.js 사용

Postman 컬렉션 (Postman Collection)

contrib/ 디렉토리에서 전체 Postman 컬렉션을 사용할 수 있습니다:

postman_collection.json - 예제가 포함된 모든 API 엔드포인트
postman_environment.json - 테스트를 위한 환경 변수 (Environment variables)

가져오기(Import) 방법:

Postman을 엽니다.
"Import"를 클릭합니다.
contrib/에서 JSON 파일을 선택합니다.
환경(Environment)을 선택합니다.
토큰을 받기 위해 먼저 "Login - Employee"를 실행합니다.

주요 학습 내용 및 시사점 (Key Learnings and Takeaways)

1. AI 그라운딩 (AI Grounding)의 중요성

항상 AI의 응답을 실제 사용자 데이터에 기반(Grounding)시켜야 합니다. 이는 환각 (Hallucinations) 현상을 방지하고 신뢰를 구축합니다.

2. 보안 우선 (Security First)

금융 데이터는 엄격한 사용자 수준의 격리 (Isolation), JWT 인증 (Authentication), 그리고 감사 로깅 (Audit logging)을 필요로 합니다.

3. 단순한 세금 로직 (Simple Tax Logic)

프로토타입의 경우, 가정이 명확하게 문서화되어 있다면 단순화된 세금 로직을 사용하는 것도 허용됩니다.

4. 사용자 친화적인 언어 (User-Friendly Language)

기술적인 급여 관련 전문 용어를 직원이 이해하기 쉬운 단순한 설명으로 번역합니다.

5. 문서 그라운딩 (Document Grounding)

AI 비전 (AI vision) 기능을 사용하여 비정형 문서에서 구조화된 데이터를 추출합니다.

도전 과제 및 해결책 (Challenges and Solutions)

도전 과제 1: AI 환각 (Hallucinations) 방지

해결책: AI가 제공된 데이터만을 사용하도록 강제하는 엄격한 그라운딩 프롬프트 (Grounding prompts)를 사용합니다.

도전 과제 2: 문서 추출 정확도

해결책: 더 나은 추출을 위해 정규 표현식 (Regex) 폴백 (Fallback)과 AI 비전을 결합하여 사용합니다.

도전 과제 3: 사용자 데이터 격리

해결책: 데이터 소유권을 확인하는 미들웨어 (Middleware)와 함께 JWT 기반 인증을 사용합니다.

도전 과제 4: 시간 제약 (1시간)

해결책: 프로덕션 수준의 완성도보다 핵심 기능에 우선순위를 두었으며, 실제 데이터베이스 대신 모의 데이터 (Mock data)를 사용했습니다.

향후 개선 사항 (Future Enhancements)

GitHub 저장소 (GitHub Repository)

Star, Fork, 그리고 기여하기: https://github.com/mohin-sheikh/ai-financial-assistant

git clone git@github.com:mohin-sheikh/ai-financial-assistant.git
cd ai-financial-assistant
npm install
...

결론 (Conclusion)

AI 기반 금융 웰니스 어시스턴트를 구축하는 것은 신뢰성, 정확성, 그리고 개인정보 보호가 매우 중요한 내부 직원 금융 사례에서 AI가 어떻게 안전하고 실용적으로 적용될 수 있는지를 보여줍니다.

이 시스템은 민감한 금융 정보에 대해 엄격한 사용자 수준의 개인정보 보호 (privacy)를 유지하면서, 즉각적이고 개인화되었으며 문서 내용을 인지하는 (document-aware) 응답을 제공합니다. 이 프로토타입은 다음과 같은 기능을 보여줍니다:

AI 기반 문서 이해 (document understanding)
환각 (hallucinations) 없는 근거 있는 응답 (grounded responses)
사용자 친화적인 설명
안전한 데이터 처리
확장 가능한 아키텍처 (scalable architecture)

의견을 공유해 주세요

여러분의 피드백을 듣고 싶습니다! 비슷한 것을 만들어 보신 적이 있나요? 어떤 기능을 추가하고 싶으신가요?

GitHub: mohin-sheikh
LinkedIn: mohin-sheikh