본문으로 건너뛰기

프로젝트 총정리

본 문서는 프로젝트 전체를 한눈에 이해하기 위한 요약 페이지입니다.
설계 과정이 아닌 최종 결과(Outcome) 중심으로 정리했습니다.

1. 프로젝트 상태 요약​

  • 개발 기간: REGO (예: 2025.xx.xx ~ 2025.xx.xx)
  • 개인 프로젝트: REGO (예: 개인/팀 n명)
  • 프로젝트 성격: 사내 ESS 백엔드 API (근태/휴가/연차/사용자/회사)
  • 현재 운영 상태:
    • EC2에 Docker 기반으로 배포 운영 중
    • DB는 RDS(MySQL) 연결
    • Swagger UI로 기능 시연 가능

2. 핵심 개선 사항 요약 (문제 → 해결 → 결과)​

프로젝트 진행 중 실제로 겪었던 문제들과 해결 결과를 정리했습니다.

2-1. Swagger /v3/api-docs 500 장애​

문제 배포 환경에서 Swagger 문서 엔드포인트(/v3/api-docs)가 500으로 실패하여 API 문서/테스트가 불가능했습니다.

해결

  • Spring Boot 3.5.x와 springdoc 버전 호환성 문제를 확인
  • springdoc 의존성을 Boot 3.5.x 호환 버전(2.8.5)으로 고정

결과

  • /v3/api-docs, /swagger-ui/index.html 정상 동작
  • 배포 환경에서도 Swagger로 API 즉시 검증 가능

2-2. 선택 입력 필드 공백("") 저장 문제(데이터 정합성)​

문제 회원가입 시 department, position 같은 선택 입력 필드가 프론트에서 빈 문자열("")로 전달되어 DB에 불필요한 공백 데이터가 쌓였습니다.

해결

  • 가입/승인 시점에 엔티티에서 StringUtils.hasText()로 공백/빈 문자열을 null로 정규화
  • DTO는 @JsonInclude(NON_NULL)로 null 필드 미전송(명세 정리)

결과

  • 선택 필드의 데이터 정합성이 개선되어 조회/검색/표시에서 예외 케이스 감소
  • 승인/프로필 수정 등 후속 플로우도 안정적으로 동작

2-3. N+1(조회 쿼리 폭증) 징후를 빠르게 식별/완화​

문제 리스트 조회 API에서 연관 엔티티 접근이 많아지면, N+1로 인해 쿼리 수가 급증할 가능성이 있었습니다(성능 회귀 위험).

해결

  • 요청 단위 쿼리 수/시간을 헤더로 노출하는 QueryMetricsFilter를 적용하여 관측 가능하게 구성
  • 근태/휴가 리스트 조회는 Repository에 @EntityGraph를 적용해 연관 엔티티를 함께 로딩하여 N+1을 완화

결과

  • 성능 이슈를 “감”이 아니라 **숫자(쿼리 수/시간)**로 확인 가능
  • 리스트 조회에서 연관 로딩으로 인한 쿼리 증가를 사전에 억제

3. 아키텍처/운영 구성 요약​

  • 애플리케이션: Spring Boot 단일 백엔드(모놀리식) + REST API
  • 배포 흐름: Mac → GitHub → GitHub Actions → DockerHub → EC2
  • DB: MySQL (운영은 RDS 연결)
  • 정적 리소스(프로필 이미지): 파일시스템 저장 + /profile-images/**로 정적 제공

4. 프로젝트가 제공하는 가치​

  • ESS 핵심 기능 구현
    • 근태: 체크인/체크아웃, 고정/유연 근무 규칙 반영, 지각/조퇴/부족근무 판정
    • 휴가: 신청/승인/거절, 반차(0.5) 지원, 주말 제외 일수 계산, 잔여 연차 검증/차감
    • 연차: 부여/사용/복원, 입사 1년 미만 월 1일 자동 부여 Job(Feature Flag로 선택 활성화)
    • 사용자/회사: 대표/사원 가입, 승인 기반 활성화(PENDING→ACTIVE), 권한(Role) 제어
    • 대시보드: 내 프로필/근태/연차/휴가 통합 조회
  • 운영/시연 친화성
    • Swagger UI 제공(배포 환경에서도 테스트 가능)
    • demo 프로필에서 더미데이터 자동 생성(포트폴리오 시연 최적화)

5. 배포 관련 안내​

  • Swagger UI: http://http://107.21.56.220:8080/swagger-ui/index.html

  • CI/CD: main 브랜치 push 시 GitHub Actions가

    • Docker 이미지 빌드/푸시(DockerHub)
    • EC2로 docker-compose.prod.yml 업로드
    • EC2에서 pull + up -d로 무중단에 가깝게 재배포 수행

  • TEST 전용 계정

// CEO 계정
"loginId": "ceo1",
"password": "pass1234!"

// 사원 계정
"loginId": "emp1",
"password": "pass1234!"

문서 안내​

이 문서는 Overview, ERD, Architecture, CI/CD, 기술적 의사결정, 트러블슈팅 등의 개별 페이지 내용을 최종 결과 중심으로 요약한 페이지입니다.

세부 내용은 각 문서에서 확인할 수 있습니다.