ProjectsHeo Jae Won
CapTeam

CapTeam

2026 1학기 교내 캡스톤 프로젝트 대상

학생 설문 데이터를 AI 팀 추천으로 연결하고, 관리자가 결과를 검토·수정·승인한 뒤 팀 운영까지 이어갈 수 있도록 설계한 서비스

프로젝트 정보

기간
2026.03 — 2026.08
팀 구성
Frontend 1Backend 2AI 2
역할
팀장 · 기획 · UI·UX · Frontend
기술
  • React
  • React Router
  • Axios
  • CSS Modules
  • Zustand

해결하려던 사용자 문제

학생 설문만으로 팀을 나누면 역할과 기술 수준, 프로젝트 경험을 함께 반영하기 어려웠습니다. 팀이 정해진 뒤에도 공지와 일지, 기획서, 채팅이 서로 다른 곳에 흩어져 있어 진행 상황을 한눈에 확인할 수 없었습니다.

서비스 흐름

  • 학생 설문 데이터를 AI 팀 추천으로 연결
  • 관리자가 배정 이유를 확인하고 팀원을 교체·승인
  • 확정된 팀 정보와 운영 기능을 학생 화면에 연결
  • 공지, 일지, 프로젝트 기획서, 채팅을 하나의 서비스 흐름으로 구성
  1. 로그인
  2. 학생 설문
  3. AI 팀 추천
  4. 관리자 검토
  5. 팀원 교체·승인
  6. 팀 운영
  7. 공지·일지·기획서·채팅

서비스 아키텍처

CapTeam 서비스 아키텍처 다이어그램. 사용자가 React UI 를 통해 서비스를 이용하고, React UI 는 Spring Boot API 에 요청을 보낸다. Spring Boot API 는 로그인·설문·팀 생성·공지·채팅 비즈니스 로직을 맡고, MySQL 에 회원·설문·팀 데이터를 저장하며 Amazon S3 에 채팅 파일을 올린다. 또 FastAPI 로 만든 AI Analyzer 에 분석을 요청해 학생 설문 기반 역량 분석과 팀 매칭 후보를 받는다. AI Analyzer 는 외부 LLM API 를 불러 팀 추천 이유를 생성한다.
원본 크기로 보기 ↗

담당 역할과 기여 범위

서비스 구조와 화면 설계

학생과 관리자로 역할을 나누고 서비스 전체의 화면 구조를 설계했습니다.

  • 학생·관리자 역할과 주요 사용자 흐름 설계
  • 로그인, 설문, 팀 생성·관리, 공지, 일지, 프로젝트 기획서, 채팅 화면 설계
  • 로딩, 오류, 빈 상태 보완

권한·인증·API 흐름

라우트 단위로 접근 권한을 나누고 토큰 상태를 API 호출과 연결했습니다.

  • /admin, /user 라우트 분리
  • ProtectedRoute 기반 접근 제어
  • 사용자·토큰 상태와 Axios JWT 연동
  • 팀·설문·일지 상태에 따른 접근 흐름 검증

AI 팀 생성과 팀 관리

AI 팀 생성 작업의 진행 상태를 화면에서 추적하고 관리자 확정 흐름까지 이었습니다.

  • AI 작업의 jobId 저장
  • Polling으로 진행·완료·실패 상태 표시
  • 중복 생성 요청 차단
  • 배정 이유 확인, 팀원 교체, 승인 흐름 구성

실시간 채팅과 검증

STOMP·WebSocket으로 팀 채팅을 구현하고 모바일 환경까지 동작을 확인했습니다.

  • STOMP·WebSocket 기반 팀 채팅 UI
  • 메시지 송수신, 읽음 처리, unread 표시
  • 모바일 뷰포트와 E2E 시나리오 검증

Troubleshooting

01AI 팀 생성 중복 요청과 새로고침 상태 유실
상황
AI 팀 생성은 작업 ID를 반환한 뒤 서버에서 처리되는 비동기 작업이었습니다. 버튼을 다시 누르거나 새로고침하면 중복 작업이 생성되거나 진행 상태를 잃을 수 있었습니다.
과제
한 번 시작한 작업을 식별하고 재진입해도 같은 jobId 상태를 이어서 확인해야 했습니다.
처리
  • 요청 직후 jobId 저장
  • 진행 중 버튼과 재요청 잠금
  • jobId 기준 Polling으로 진행·완료·실패 반영
  • 새로고침·재진입 시 저장된 작업 복원
결과
  • 중복 팀 생성 가능성 차단
  • 관리자가 진행 상태를 잃지 않도록 안정화
02반복 API 호출과 서버 요청 증가
상황
E2E와 Network 로그에서 대시보드, 헤더, 채팅 unread, 채널 요약 요청이 화면 전환과 Polling마다 반복됐습니다. 관리자 채팅 목록에는 방마다 요약 API를 요청하는 N+1 구조도 남아 있었습니다.
과제
기능을 유지하면서 불필요한 호출과 동시 중복 요청을 줄여야 했습니다.
처리
  • 짧은 TTL 캐시와 in-flight 요청 공유
  • 백그라운드 탭에서 unread Polling 생략
  • WebSocket 이벤트 중심 갱신
  • 채널 선택 시 read 처리 중복 제거
  • N+1의 완전한 제거에는 백엔드 일괄 API가 필요하다는 한계 기록
결과
  • 반복 호출과 Edge Request 증가 완화
  • 프론트 해결 범위와 백엔드 개선 범위 구분
03E2E에서 발견한 UI·접근성 경고
상황
선생님·학생 계정 흐름과 390·412·768px 뷰포트를 점검하며 중첩 li, 중복 React key, 모바일 가로 넘침을 발견했습니다.
과제
기능 오류로 보이지 않는 경고까지 정리하고 권한·빈 상태·예외 흐름을 다시 검증해야 했습니다.
처리
  • 공지 목록을 ul → li → 링크 구조로 수정
  • 팀·순번 기반 React key 적용
  • 잘못된 로그인, 보호 라우트, 설문 완료, 일지 시간 가드, 빈 입력 검증
  • 모바일 가로 넘침과 Console 경고 재확인
결과
  • 테스트한 핵심 화면의 가로 넘침과 React 경고 제거
  • 권한·빈 상태·예외 처리를 포함한 검증 흐름 확보

AI 활용과 검증

초기 문제 정의, 서비스 흐름, 화면 설계는 직접 진행했습니다. 후반 구현과 유지보수에서는 Codex 활용 비중이 높았으며, 생성 결과를 브라우저 화면, Console, Network, 빌드, 린트, E2E, 모바일 뷰포트로 검증했습니다.

배운 점

화면 구현을 넘어 데이터 흐름과 운영 환경을 고려해야 한다

  • 반복되는 API 호출이 화면 속도만의 문제가 아니라 서버 부담으로 이어진다는 것을 배웠습니다.
  • Polling을 직접 붙여 보며 시작 조건만으로는 부족하고 중단 조건과 복원 방식까지 필요하다는 것을 경험했습니다.
  • 프론트엔드에서 해결할 범위와 백엔드 API가 바뀌어야 할 범위를 구분하는 기준이 생겼습니다.

AI 활용 개발에서는 검증 책임이 개발자에게 있다

  • 코드가 작성된 것과 실제 서비스 흐름에서 동작하는 것이 다르다는 것을 직접 겪었습니다.
  • JWT, Polling, WebSocket처럼 상태가 이어지는 기능은 데이터 흐름을 끝까지 따라가며 확인하게 됐습니다.
  • AI를 활용하더라도 요구사항 정의와 결과 검증은 개발자의 몫이라는 것을 배웠습니다.