Vibot
Frontend사내 문서 기반 AI 챗봇 운영 관리자 페이지
관리자가 문서·URL 데이터를 업로드·분류하고, 수집·학습 상태를 모니터링하며 챗봇 응답을 검증하는 B2B 챗봇 운영 관리자 페이지입니다. 카카오엔터프라이즈 SW 아카데미의 기업실무형 프로젝트로 진행했습니다.
기업 연계 프로젝트로 진행되어, 대외비 정책에 따라 저장소와 상세 코드는 공개하지 않습니다.
프로젝트 개요
- 목표
- 관리자가 사내 문서 기반 챗봇의 학습 데이터를 적재·분류하고 처리 상태와 답변을 검증하는 운영 화면을 구축했습니다.
- 배경
- 기업용 챗봇을 운영하려면 문서·URL 등록뿐 아니라 데이터 처리 상태, 접근 권한, 배포 후 오류를 한 흐름에서 관리해야 합니다.
- 주요 기능
- 문서 파일 업로드와 URL 등록으로 챗봇이 학습할 데이터를 관리자가 직접 적재할 수 있습니다.
- 카테고리 기반 데이터 분류와 DataTable 목록·상세 조회로 적재된 문서를 관리합니다.
- 데이터 수집·처리 상태를 확인해 학습이 어디까지 진행됐는지 추적할 수 있는 모니터링 UI를 구성했습니다.
- 쿠키 기반 인증 환경에서 CSRF에 대응하고, Sentry로 운영 중 발생하는 런타임 에러를 추적합니다.
역할·팀 구성
팀 내 역할 분담 · 7인 팀
- Frontend Lead · 본인
- 관리자 페이지 화면 설계, 데이터 관리 기능, 프론트엔드 공통 구조
- Frontend
- 관리자 화면 및 사용자 인터랙션 구현
- Backend / AI
- 인증·권한 API, 문서 수집·처리와 챗봇 응답 기능 연동
담당 역할
Frontend Lead
7인 팀에서 프론트엔드 리드로 관리자 페이지 설계와 데이터 관리 핵심 기능을 담당했습니다.
관리자 페이지 설계·구현
- 관리자 페이지 설계·구현 총괄
프론트엔드 개발 팀장으로 관리자 페이지 화면 설계와 데이터 관리 핵심 기능 구현 담당
- 데이터 관리 UI 구현
DataTable 기반 목록, 상세 모달, 파일 업로드·URL 등록 플로우 UI 구현
프론트엔드 인프라 구성
- 상태 관리 책임 분리
서버 상태는 TanStack Query, UI·권한 상태는 Zustand로 나눠 상태 관리 책임 분리
- API 통신 레이어 정리
Axios 인스턴스 구성 및 인증 쿠키 전송을 전제로 한 API 통신 레이어 정리
- Sentry 기반 에러 추적 도입
Sentry를 도입해 운영 환경의 런타임 에러 추적 기반 마련
사용 기술 & 이유 & 구현
Next.js · React · TypeScript
- 선택 이유
- 관리자 화면을 재사용 가능한 컴포넌트로 구성하고 데이터 구조를 타입으로 관리하기 위해 사용했습니다.
- 구현 내용
- 문서 목록·상세·업로드·URL 등록 및 처리 상태 모니터링 화면을 구현했습니다.
TanStack Query · Zustand
- 선택 이유
- 서버 데이터의 캐싱·동기화와 화면·권한 상태를 구분하기 위해 사용했습니다.
- 구현 내용
- API 데이터는 Query로, UI·권한 상태는 Zustand로 관리했습니다.
Axios
- 선택 이유
- 쿠키 인증과 CSRF 헤더를 여러 API에서 일관되게 처리하기 위해 사용했습니다.
- 구현 내용
- 공통 인스턴스와 요청 인터셉터에서 쿠키 전송 및 CSRF 토큰 헤더 첨부를 정리했습니다.
Sentry
- 선택 이유
- 배포 후 발생하는 관리자 화면의 런타임 에러를 추적하기 위해 도입했습니다.
- 구현 내용
- 운영 환경의 프론트엔드 오류를 수집하는 기반을 연결했습니다.
문제 해결 사례
사례 1CSRF 토큰 처리 방식의 차이로 발생한 403 오류 해결
1. 오류 분석
- 문제 현상
- 로그인 후 서버에서 CSRF 토큰을 발급받고, 쿠키의 XSRF-TOKEN 값을 요청 헤더에 담아 전송하도록 구현했습니다. 하지만 일부 POST, PUT, DELETE 요청에서 CSRF 검증에 실패하며 403 Forbidden이 반복해서 발생했습니다.
- 원인
- 일부 요청에 CSRF 헤더가 누락됐고, 인터셉터 보완 이후에도 클라이언트와 서버의 RAW 토큰·XOR 토큰 처리 흐름이 맞지 않았습니다.
- 추가 확인 사항
- 헤더 첨부만으로 해결되지 않아 Spring Security 검증 과정까지 확인했습니다.
- Swagger UI와 기존 CSRF 보호를 유지하면서 동일한 보안 설정으로 동작해야 했습니다.
2. 개선 과정
- 1.Network 요청 확인
- 2.헤더 누락 발견
- 3.Axios 인터셉터 보완
- 4.403 재현
- 5.Spring Security RAW/XOR 확인
- 6.토큰 처리 일치
- 7.보호 API 검증
요청 과정을 확인해 일부 API 호출에서 CSRF 헤더가 누락되는 문제를 발견하고, Axios 인터셉터에서 쿠키의 토큰 값을 요청마다 헤더에 넣도록 수정했습니다. 이후에도 403이 발생해 Spring Security의 CSRF 처리 과정을 확인했고, 원본 토큰과 XOR 처리 토큰의 흐름이 맞지 않아 검증에 실패하고 있음을 파악했습니다. Swagger UI와 기존 보안 설정을 유지하기 위해 우회하지 않고, 프론트엔드는 쿠키 값을 헤더에 전달하고 토큰 생성과 검증은 Spring Security의 기본 처리 방식에 맡기도록 정리했습니다.
3. Before & After 비교
| 항목 | Before | After |
|---|---|---|
| CSRF 토큰 전달 | 일부 요청에 헤더 누락 | Axios 공통 처리 |
| 원인 분석 범위 | 프론트엔드 요청 | 프론트엔드 + Spring Security |
| POST·PUT·DELETE 요청 | 반복되는 403 | 정상 API 요청 |
| 보안 정책 | CSRF 검증 적용 | CSRF 보호·Swagger 설정 유지 |
해결 결과
프론트엔드와 백엔드의 CSRF 토큰 처리 방식을 일치시켜 반복적으로 발생하던 403 오류를 해결했습니다. 또한 Swagger UI를 위해 별도의 예외를 두거나 CSRF 기능을 비활성화하지 않고도 동일한 보안 설정을 유지할 수 있도록 했습니다. 인증 오류로 API 연동과 기능 테스트가 계속 지연되던 문제도 해결해 이후 개발 일정을 원활하게 진행할 수 있었습니다.
프로젝트 성과 및 결과
- 문서 업로드·URL 등록·분류·처리 상태 확인을 연결하는 관리자 페이지 구현
- 서버 데이터와 UI·권한 상태의 관리 책임 분리
- CSRF 보호를 유지하면서 반복적인 403 오류 해결
- Sentry 기반 배포 후 런타임 에러 추적 기반 마련
프로젝트 회고
기술적 한계와 개선 방안
- 한계·아쉬운 점
- 인증·CSRF처럼 여러 요청이 공유하는 기능은 요청별 수동 확인만으로 회귀를 막기 어렵습니다.
- 개선 방향
- 로그인 → 문서 등록 → 수정·삭제와 Swagger 요청을 회귀 시나리오로 묶고 토큰 처리 방식도 API 계약에 기록할 계획입니다.
- 한계·아쉬운 점
- 에러 수집만으로는 어떤 작업에서 사용자가 막혔는지 설명하기 어려울 수 있습니다.
- 개선 방향
- 업로드·분류·응답 검증 등 작업 단계와 오류를 연결해 실패율과 복구 흐름을 함께 확인할 계획입니다.