FinMate — 양도세 환급 통합관리 플랫폼

Fin.mate — 세무법인의 양도소득세 환급 업무를 디지털 전환하는 SaaS형 통합관리 시스템

프로젝트 개요

세무법인이 고객의 양도소득세 과오납 환급을 대행하는 전 과정을 관리하는 웹 기반 플랫폼입니다. 고객 신청 접수부터 계약, 세무 검토, 정보공개청구, 신고서 작성, 환급 처리, 종결까지 양도세 환급 업무의 전체 라이프사이클을 하나의 시스템에서 처리합니다.

고객용 모바일 신청 웹앱(TaxBack Web)과 세무법인 실무자용 관리 시스템(FinMate Web), 그리고 두 서비스를 지원하는 NestJS 모노레포 백엔드로 구성된 3개 프로젝트를 동시 개발했습니다. 국세청 홈택스(InfoTech) API, 정부24(Gov24) 연동, Kafka 메시지 큐, AWS S3 파일 관리 등 엔터프라이즈급 인프라를 갖추고 있습니다.

시스템 아키텍처

고객 신청(TaxBack Web) → 관리 시스템(FinMate Web) → API 서버(NestJS Monorepo) → 외부 기관 연동의 4계층 구조입니다.

CLIENT LAYER
📱 TaxBack Web (고객용) Next.js 15 · React 18 · Tailwind CSS 다단계 본인인증 + 신청 폼 주소 검색 (Daum Postcode)	🖥️ FinMate Web (관리자용) Next.js 15 · React 19 · Tailwind CSS 양도세 워크플로우 관리 문자 발송 · 템플릿 · 계정 관리

▼ REST API ▼

API LAYER (NestJS Monorepo)
🔌 FinMate API (Port 3002) NestJS 10 · Fastify · TypeORM 18개 기능 모듈 (application, auth, contract, report, message, notification 등) JWT 인증 · BSign 전자서명	🔌 TaxBack API (Port 3001) NestJS 10 · Fastify · TypeORM InfoTech 국세청 연동 인증서 기반 세무 신고

▼ Kafka · Redis · MySQL ▼

INFRASTRUCTURE LAYER
MySQL 8.0 세무 데이터 고객·계약 관리	Redis 6.2 세션 캐시 실시간 상태	Kafka 메시지 큐 비동기 처리	AWS S3 파일 저장 신고서 PDF

▼ 외부 연동 ▼

EXTERNAL INTEGRATION
국세청 InfoTech Z1011/Z1017 세무 신고 인증서 기반 자동 처리	정부24 (Gov24) 정보공개청구 행정 서류 자동 수집	SMS · Slack 문자 발송 자동화 Slack 알림 연동

기술 스택

영역	기술
고객용 웹	Next.js 15 · React 18 · TypeScript · Tailwind CSS · react-daum-postcode
관리자 웹	Next.js 15 · React 19 · TypeScript · Tailwind CSS
백엔드	NestJS 10 · Fastify 4 · TypeORM 0.3 · TypeScript
데이터베이스	MySQL 8.0.32 · Redis 6.2
메시지 큐	Kafka (kafkajs) · AMQP (amqplib) · NATS
클라우드/파일	AWS S3 v3 · STS · SSO-OIDC
인증/보안	JWT · Helmet · RSA/AES 암호화
문서 생성	Puppeteer 24 · xlsx · csv-writer
실시간 통신	Socket.io 4.8 · WebSocket
알림/메시지	Nodemailer · Slack Webhook
인프라	Docker Compose · Node 20 Alpine · Yarn 4.5
외부 연동	국세청 InfoTech API · 정부24 (Gov24) · BSign 전자서명

주요 화면

양도세 전체보기

양도소득세 환급 사건의 전체 목록을 한눈에 조회하는 메인 화면입니다. 사건 번호, 고객 정보, 진행 상태(검토대기·계약중·신고완료·종결 등), 납부액, 예상 환급액, 신고서 파일, 연락 이력까지 모든 정보를 데이터 테이블로 관리합니다. 상단에는 문자 발송, 수수료 공문 생성 등의 일괄 작업 버튼과 다양한 검색·필터 기능을 제공합니다.

워크플로우 단계별 화면

양도세 환급 업무를 신청 → 계약&검토 → 신고&환급 → 종결의 4단계 워크플로우로 체계화했습니다. 각 단계별로 해당 상태의 사건만 필터링하여 보여주며, 단계에 맞는 액션 버튼과 상태 배지가 자동으로 변경됩니다.

종결 세부 관리

종결된 사건도 추가 환급 대상과 취득세 검토로 세분화하여 추적합니다. 종결 태그 시스템으로 사후 관리가 필요한 사건을 놓치지 않도록 관리합니다.

메시지 템플릿 관리

고객에게 발송하는 SMS 메시지 템플릿을 카테고리별로 체계적으로 관리합니다. 환급액 안내, 홈택스 오류, 위임장 요청 등 업무 상황별 템플릿을 사전 등록하고, 일괄 또는 개별 문자 발송에 활용합니다.

계정 권한 관리

역할 기반 접근 제어(RBAC)로 총괄, 판단 세무사, 실무 세무사, 사무장, 운영 등 세무법인의 조직 구조에 맞는 권한 체계를 구현했습니다. 계정 활성/비활성 토글로 즉시 접근을 제어할 수 있습니다.

데이터 이관

기존 시스템(구 핀메이트)에서 신규 시스템으로의 데이터 마이그레이션 기능입니다. 고객 정보, 인증 일시, 납부액, PDF 파일 등 기존 데이터를 안전하게 이관하여 업무 연속성을 보장합니다.

백엔드 모듈 구조

NestJS 모노레포 아키텍처로 FinMate API와 TaxBack API를 단일 코드베이스에서 관리합니다.

모듈	기능
application	사건(Application) 등록·관리·조회
auth / user	JWT 인증, 사용자 관리, RBAC 권한 체계
customer	고객 정보 관리 (이름, 연락처, 생년월일)
contract	계약 관리, 수수료 산정, Puppeteer 계약서 PDF 생성
detail / final	세무 검토 상세, 종결 처리, 종결 태그 관리
report / total	신고서 작성, 집계 데이터, 통계 리포트
message / notification	SMS 발송, 푸시 알림, 메시지 템플릿
template	문서·메시지 템플릿 CRUD
bsign / btransfer	전자서명(BSign), 은행 이체(BTransfer) 연동
gov24	정부24 정보공개청구 자동 처리
infotech (TaxBack)	국세청 InfoTech Z1011/Z1017 세무 신고 API 연동

프로젝트 규모

항목	수치
프로젝트 수	3개 (FinMate Web, TaxBack Web, Backend Monorepo)
백엔드 API 모듈	18개 (FinMate) + 1개 (TaxBack)
총 소스 파일	약 218개
총 코드 라인	약 20,000 LOC
Docker 서비스	5개 (API, MySQL, Redis, Kafka, Zookeeper)
개발 연도	2022년