고객사 임직원들을 위한 연말정산 모바일 앱
연말정산 전과정을 모바일로 가능하며, 국세청 연말정산 자료를 PC를 통하지 않고 모바일에서 바로 올리고, 연말정산 관련 증빙서류를 사진을 찍어 바로 등록 하는 기능 제공. 연말정산을 완료하면 즉시 예상 환급 또는 추징 금액을 확인 기능.
1. 프로젝트 개요

연말정산 모바일 앱은 한국 기업의 임직원이 모바일 환경에서 연말정산을 간편하게
수행할 수 있도록 설계된 B2B 크로스플랫폼 모바일 솔루션이다.

기존 연말정산 업무는 종이 서류 제출, PC 기반 웹 접속 등 시간과 장소에 제약이
있었으나, 본 앱을 통해 직원은 스마트폰에서 국세청 PDF 업로드부터 전자서명,
결과 조회까지 전 과정을 14단계 가이드에 따라 완료할 수 있다.

핵심 가치
(1) 접근성 - iOS와 Android 양 플랫폼을 단일 코드베이스로 지원하여
사용 환경에 관계없이 동일한 사용자 경험 제공
(2) 편의성 - 단계별 위자드 방식으로 복잡한 연말정산 절차를 직관적으로 안내
(3) 실시간성 - 푸시 알림과 챗봇 상담을 통한 즉각적인 정보 전달
(4) 보안성 - 다중 인증 방식과 세션 기반 보안으로 개인정보 보호


2. 시스템 구성

본 시스템은 모바일 클라이언트와 백엔드 API 서버로 구성되며, 모바일 앱은
네이티브 기능과 웹 기반 콘텐츠를 하이브리드로 결합한 구조이다.

(1) 모바일 클라이언트
- 인증, 문서 관리, 전자서명 등 핵심 기능은 네이티브로 구현
- 정산 상세 화면과 동적 콘텐츠는 WebView를 통해 서버 측 웹앱과 연동
- PostMessage 기반 브릿지를 통해 네이티브와 웹앱 간 양방향 통신

(2) 백엔드 API 서버
- RESTful API 방식으로 인증, 정산 데이터, 문서 관리 등 제공
- 기업별 멀티테넌시 구조로 각 고객사 독립 운영 지원
- 세션 기반 인증 토큰을 통한 API 접근 제어


3. 핵심 기술 스택

3-1. 모바일 프론트엔드

React Native - 크로스플랫폼 모바일 앱 프레임워크
React - UI 컴포넌트 라이브러리 (Concurrent 렌더링 지원)
TypeScript - 정적 타입 시스템을 통한 코드 안정성 확보
React Navigation - 스택 기반 화면 전환 및 네비게이션 관리
Redux Toolkit - 전역 상태 관리 (예측 가능한 단방향 데이터 흐름)
Axios - HTTP 클라이언트 (API 통신)
AsyncStorage - 로컬 영구 저장소 (사용자 설정, 세션 캐시)
React Native Elements - 표준화된 UI 컴포넌트 라이브러리
React Native Vector Icons - 아이콘 시스템
React Native WebView - 하이브리드 웹 콘텐츠 렌더링

3-2. 네이티브 기능 연동

React Native FS - 디바이스 파일 시스템 접근
React Native Document Picker - 문서 파일 선택 (PDF 등)
React Native Image Picker - 카메라 촬영 및 갤러리 이미지 선택
React Native Permissions - 디바이스 권한 요청 및 관리
React Native Device Info - 디바이스 식별 및 정보 수집
Sketch Canvas - 전자서명 캔버스 (터치 기반 서명 입력)
React Native Splash Screen - 앱 시작 화면 관리
React Native Exit App - 앱 종료 제어

3-3. 푸시 알림 및 메시징

Firebase Cloud Messaging (FCM) - 실시간 푸시 알림 발송 및 수신

3-4. 개발 도구 및 품질 관리

ESLint - 코드 정적 분석 및 규칙 검증
Prettier - 코드 포맷 자동화
Jest - 단위 테스트 프레임워크
Babel - JavaScript 트랜스파일러 (Module Resolver 포함)
Metro - React Native 전용 번들러


4. 핵심 기능

4-1. 인증 및 계정 관리

(1) 다중 인증 방식
- 아이디/비밀번호 기반 로그인 (회사코드 + 사번 + 비밀번호)
- SMS 문자인증 로그인 (생년월일 + 휴대폰 번호 + 인증번호)
- 자동 로그인 (사용자 선택에 따라 세션 유지)

(2) 비밀번호 찾기 (5단계 위자드)
- 1단계: 이름, 생년월일, 성별로 본인 확인
- 2단계: 일치하는 계정 목록 표시 (개인정보 마스킹 처리)
- 3단계: 인증 수단 선택 (SMS 또는 카카오톡 알림)
- 4단계: 인증번호 입력 및 검증
- 5단계: 새 비밀번호 설정 (영문+숫자+특수문자 조합 검증)

(3) 멀티 계정 지원
- 한 사용자가 여러 회사에 소속된 경우 계정 선택 팝업 제공
- 로그인 이력 관리 및 빠른 계정 전환

4-2. 메인 대시보드

(1) 정산 현황 카드
- 환급/납부 결과 표시 (시각적 상태 인디케이터)
- 월별 급여 결과 카드
- 예상 환급액 표시

(2) 퀵 메뉴
- 연말정산 시작 / 상세 보기
- 국세청 PDF 다운로드
- 정산 일정 확인
- 추가서류 제출
- FAQ 바로가기
- 연말정산 가이드

(3) 챗봇 상담 패널
- 메인 화면 하단 애니메이션 패널로 즉시 접근
- 실시간 챗봇 기반 1:1 상담

4-3. 14단계 연말정산 프로세스

연말정산의 전 과정을 14개 단계로 체계화하여 사용자를 안내한다.
각 단계는 Drawer 네비게이션으로 접근 가능하며, 진행 상태를
아이콘으로 시각화한다.

1단계 - 메인 화면 (정산 현황 개요)
2단계 - 전직장 정보 입력
3단계 - 부양가족 등록 및 관리
4단계 - 전자문서 관리 (국세청 PDF 업로드)
5단계 - 공제항목 선택
6단계 - 보험료 공제
7단계 - 의료비 공제
8단계 - 교육비 공제
9단계 - 기부금 공제
10단계 - 신용카드 사용액 공제
11단계 - 주택자금 공제
12단계 - 기타 공제
13단계 - 증빙서류 업로드
14단계 - 결과 조회 및 전자서명 제출

4-4. 전자문서 관리 (4단계)

(1) PDF 파일 업로드
- 국세청 간소화 서비스 PDF 파일 선택 및 업로드
- 업로드 상태 및 진행률 표시
- 기존 파일 삭제 및 재업로드

(2) 요건 체크리스트
- 필수 제출 서류 현황 표시
- 주택관련 세액공제 옵션 선택
- 항목별 충족 여부 시각화

4-5. 공제항목 상세 (5~12단계)

각 공제항목(보험료, 의료비, 교육비, 기부금, 신용카드, 주택자금, 기타)별로
WebView 기반 입력 화면을 제공하며, 서버 측에서 세법 규정에 맞는 계산 로직을
실시간으로 적용한다.

4-6. 증빙서류 관리 (13단계)

(1) 다중 파일 업로드
- PDF 및 이미지 파일 지원
- 카메라 촬영 즉시 업로드
- 갤러리에서 이미지 선택
- 파일 크기 제한 검증 (최대 7MB)

(2) 카테고리 분류
- 서류 유형별 카테고리 선택
- 하위 카테고리 세분화
- 카테고리별 서류 목록 관리

(3) 서류 뷰어
- 업로드된 이미지 및 PDF 미리보기
- 서류 삭제 기능

4-7. 결과 조회 및 전자서명 (14단계)

(1) 정산 결과 표시
- 환급/납부 금액 및 상세 내역
- 예상 금액 대비 확정 금액 비교
- 상태별 메시지 파싱 및 표시

(2) 전자서명
- 터치 기반 서명 캔버스
- 서명 초기화 및 재작성
- 서명 이미지 캡처 및 서버 전송

(3) 신고서 제출
- 서명 완료 후 최종 제출
- 제출 후 세션 정리 및 완료 안내

4-8. 개인정보 관리

(1) 프로필 정보 조회
- 이름, 소속 회사, 부서, 사번
- 주소, 연락처, 이메일

(2) 설정 관리
- 비밀번호 변경 (현재 비밀번호 검증 후 변경)
- 주소 검색 및 업데이트 (도로명/지번 주소 검색)
- 자동 로그인 설정
- SMS 로그인 설정
- 연말정산 알림 수신 설정
- 이메일 주소 변경

4-9. 정보 및 지원 서비스

(1) 일정 관리
- 캘린더 기반 정산 일정 표시
- 신고 기간, 추가서류 검토 기간, 최종 결과 발표일 등 마일스톤 표시

(2) FAQ
- 자주 묻는 질문 웹 콘텐츠 제공

(3) 연말정산 가이드
- 정산 종합 안내 콘텐츠

(4) 페이데이TV
- 연말정산 관련 교육 영상 콘텐츠

(5) 자주 발생하는 질문 TOP 10
- 가장 빈번한 문의사항 모아보기

4-10. 푸시 알림

(1) Firebase Cloud Messaging 연동
- 정산 일정 안내 알림
- 서류 제출 독촉 알림
- 결과 확인 알림
- 앱 내 알림 목록 관리


5. 아키텍처 설계

5-1. 전체 아키텍처

본 앱은 하이브리드 아키텍처를 채택하여, 인증 및 디바이스 연동 기능은
네이티브로 구현하고 정산 비즈니스 로직은 WebView를 통해 서버 측 웹앱과
연동하는 구조이다. 이를 통해 네이티브 성능과 웹 기반 유연성을 동시에
확보하였다.

5-2. 프론트엔드 구조

(1) Feature-based 모듈 아키텍처
- 기능 단위로 디렉토리를 분리 (인증, 메인, 정산 등)
- 각 기능 모듈은 화면, 컴포넌트, 비즈니스 로직을 독립적으로 포함
- 모듈 간 의존성 최소화로 유지보수성 극대화

(2) 컴포넌트 계층 구조
- 공통 컴포넌트: 재사용 가능한 입력, 버튼, 로딩 인디케이터 등
- 기능 컴포넌트: 각 기능 모듈 전용 UI 컴포넌트
- 화면 컴포넌트: 라우팅 대상이 되는 최상위 레이아웃

(3) 화면/로직 분리
- 화면 컴포넌트(Screen)와 비즈니스 로직 함수(ScreenFunc)를 분리
- API 호출, 데이터 가공 등은 별도 함수 모듈로 관리
- UI 레이어와 데이터 레이어의 관심사 분리

5-3. 상태 관리

(1) 전역 상태 (Redux Toolkit)
- 단방향 데이터 흐름으로 예측 가능한 상태 변화
- Slice 패턴으로 도메인별 상태 모듈화
- Redux Logger를 통한 개발 시 상태 변화 추적

(2) 앱 컨텍스트 (React Context)
- 로그인 상태, 세션 정보 등 인증 관련 전역 상태
- 정산 단계 진행 상태 관리
- UI 상태 (Drawer 열림/닫힘, 화면 전환 플래그 등)

(3) 로컬 상태
- 각 컴포넌트 내부의 폼 입력, UI 인터랙션 상태
- React Hooks(useState, useEffect)를 활용한 선언적 상태 관리

5-4. 네비게이션 설계

(1) 조건부 네비게이터 분기
- 로그인 상태에 따라 인증 네비게이터와 메인 네비게이터 자동 전환
- 인증 네비게이터: 로그인 화면, 비밀번호 찾기 화면
- 메인 네비게이터: 홈 화면, 정산 단계별 화면

(2) Drawer 네비게이션
- 14단계 정산 프로세스를 사이드 메뉴로 접근
- 단계별 아이콘 및 진행 상태 시각화
- 중첩 카테고리를 통한 공제항목 그룹화

5-5. 네이티브-웹 브릿지

(1) PostMessage 기반 양방향 통신
- 네이티브에서 웹앱으로 세션 정보, 디바이스 정보 전달
- 웹앱에서 네이티브로 로그아웃 요청, 외부 URL 열기 등 이벤트 전달
- JSON 기반 메시지 프로토콜로 구조화된 데이터 교환


6. 인증 및 보안 아키텍처

6-1. 인증 흐름

(1) ID/PW 인증
- 회사코드, 사번, 비밀번호를 서버에 전송
- 서버 측 검증 후 세션 토큰 발급
- 토큰을 로컬 저장소에 보관하여 이후 API 호출에 사용

(2) SMS 인증
- 생년월일과 휴대폰 번호로 본인 확인
- 서버에서 SMS 인증번호 발송 (3분 유효시간)
- 인증번호 검증 후 세션 토큰 발급

(3) 자동 로그인
- 사용자 동의 하에 인증 정보를 로컬에 암호화 저장
- 앱 재실행 시 저장된 정보로 자동 인증

6-2. 세션 관리

(1) 토큰 기반 API 인증
- 모든 API 요청 시 세션 토큰을 HTTP 헤더에 포함
- 서버 측 세션 만료 시 재로그인 유도

(2) 보안 처리
- 비밀번호 입력 필드 보안 키보드 적용 (SecureTextEntry)
- 비밀번호 찾기 시 계정 정보 마스킹 표시
- 비밀번호 정책 적용 (영문+숫자+특수문자 조합, 8~15자)

6-3. 권한 관리

(1) 디바이스 권한
- 카메라 접근 권한 (증빙서류 촬영)
- 저장소 접근 권한 (파일 업로드/다운로드)
- 첫 실행 시 권한 안내 팝업으로 투명한 정보 제공
- 필수 권한과 선택 권한 구분 안내

(2) 기업별 멀티테넌시
- 회사코드(alias) 기반으로 기업별 독립 데이터 접근
- 기업별 API 엔드포인트 자동 분기


7. 데이터 관리

7-1. 로컬 데이터 저장

(1) AsyncStorage 활용
- 사용자 세션 정보 캐싱
- 자동 로그인 설정 저장
- 로그인 이력 관리
- 앱 설정 값 영구 저장
- 키-값 쌍 구조의 경량 저장소

7-2. 파일 관리

(1) 문서 파일 관리
- 디바이스 파일 시스템을 통한 PDF 파일 접근
- Document Picker를 통한 파일 선택 UI
- 파일 크기 검증 (최대 7MB 제한)

(2) 이미지 파일 관리
- 카메라 촬영 이미지 즉시 업로드
- 갤러리 이미지 선택 및 업로드
- 이미지 미리보기 및 관리

(3) 서버 동기화
- 업로드된 파일은 서버 측에서 중앙 관리
- 카테고리별 분류 체계에 따라 정리
- 파일 삭제 시 서버 동기화

7-3. API 데이터 통신

(1) HTTP 클라이언트 구조
- Axios 기반 중앙 집중식 API 호출 모듈
- 공통 헤더(세션 토큰 등) 자동 주입
- 정산 API와 마스터 API를 용도별로 분리 관리

(2) 에러 핸들링
- API 응답 코드 기반 에러 분류
- 사용자 친화적 에러 메시지 표시
- 네트워크 오류 시 재시도 안내


8. 테스트 전략

(1) 단위 테스트
- Jest 프레임워크를 활용한 컴포넌트 테스트
- React Test Renderer를 통한 렌더링 검증

(2) 개발 도구
- React Native Debugger를 통한 런타임 디버깅
- Redux Logger를 통한 상태 변화 모니터링
- 코드 품질 관리 (ESLint 정적 분석, Prettier 포맷팅)


9. 배포 환경

(1) 크로스플랫폼 빌드
- Android: Gradle 기반 빌드 시스템
- iOS: Xcode 프로젝트 기반 빌드
- 단일 JavaScript 코드베이스에서 양 플랫폼 동시 빌드

(2) 번들링
- Metro 번들러를 통한 JavaScript 번들 생성
- Babel 트랜스파일링으로 최신 문법 호환성 확보
- Module Resolver를 통한 깔끔한 모듈 경로 관리

(3) 앱 배포
- Google Play Store (Android)
- Apple App Store (iOS)
- 앱 버전 체크 기능을 통한 업데이트 유도
- 플랫폼별 스토어 링크 자동 분기

(4) 환경 관리
- 환경 변수를 통한 설정 분리
- 기업별(alias) 엔드포인트 동적 설정
- Firebase 설정 파일을 통한 푸시 서비스 환경 분리


10. 기술적 우수성

10-1. 아키텍처 강점

(1) 하이브리드 아키텍처의 유연성
- 인증, 카메라, 파일 시스템 등 네이티브 기능이 필요한 영역은
네이티브로 구현하여 최적의 성능 확보
- 정산 비즈니스 로직은 웹앱으로 분리하여 앱스토어 배포 없이
서버 측에서 즉시 업데이트 가능
- 매년 변경되는 세법 규정을 신속하게 반영할 수 있는 유연한 구조

(2) Feature-based 모듈 아키텍처
- 기능 단위의 독립적 모듈 구조로 팀 병렬 개발 가능
- 모듈 간 낮은 결합도로 변경 영향 범위 최소화
- 새로운 기능 추가 시 기존 코드 수정 없이 모듈 추가만으로 확장

10-2. 개발 생산성

(1) 현대적 기술 스택
- React Native를 통한 iOS/Android 동시 개발로 개발 비용 절감
- TypeScript 도입으로 컴파일 타임 오류 검출 및 IDE 자동완성 지원
- Redux Toolkit의 Slice 패턴으로 상태 관리 보일러플레이트 최소화

(2) 코드 품질 자동화
- ESLint와 Prettier를 통한 일관된 코딩 컨벤션 유지
- Babel Module Resolver로 깔끔한 import 경로 관리
- Jest 기반 테스트 자동화 체계

10-3. 확장성

(1) 멀티테넌시 설계
- 기업별 독립적인 데이터 및 설정 관리
- 새로운 고객사 추가 시 별도 코드 수정 없이 설정만으로 온보딩
- 기업별 커스터마이징 가능한 유연한 구조

(2) 단계 확장 용이성
- 14단계 정산 프로세스가 설정 기반으로 정의되어 있어
단계 추가/수정/삭제가 용이
- WebView 기반 콘텐츠는 서버 측에서 동적으로 관리 가능

10-4. 사용자 경험

(1) 직관적 정산 워크플로우
- 14단계 가이드로 복잡한 연말정산 절차를 단순화
- Drawer 네비게이션을 통한 단계 간 자유로운 이동
- 진행 상태 시각화로 현재 위치 및 남은 단계 파악 용이

(2) 다채널 사용자 지원
- 실시간 챗봇 상담으로 즉각적인 문의 응대
- FAQ, 가이드, 교육 영상 등 다양한 자기학습 채널 제공
- 푸시 알림으로 중요 일정 및 진행 상황 안내

(3) 접근성 향상
- 보라색(#7A5AF8) 기반의 현대적 디자인 시스템
- Safe Area 대응으로 다양한 디바이스 화면 최적화
- 뒤로가기 더블 탭 종료 등 플랫폼 관례에 맞는 인터랙션

(4) 문서 관리 편의성
- 카메라 촬영 즉시 업로드로 종이 서류 디지털화
- PDF 및 이미지 파일 통합 관리
- 카테고리별 자동 분류로 서류 정리 부담 경감
- 전자서명으로 별도 인감 또는 서명 절차 생략