[JoonKyoLee]

📌 작업 개요

관련 이슈

• Closes refactor: 패키지 구조 정리 및 소개 페이지 DB 전환 #61

작업 배경 및 목적

도메인별로 혼재되어 있던 패키지 구조를 일관된 레이어 구조로 정리했습니다.

또한 소개 데이터가 없는 경우 어드민에서 최초 등록할 수 없었던 문제를 해결하고, 프론트엔드의 소개 페이지 하드코딩 데이터를 DB 기반으로 전환할 수 있도록 API와 운영 절차를 정리했습니다.

🛠️ 주요 변경 사항

• 도메인 패키지를 controller, service, repository, entity 기준으로 정리
• 개발 컨벤션, 코드 리뷰 기준, PR 템플릿 추가
• PUT /admin/introductions를 소개 정보 등록·수정용 upsert API로 변경
• 기존 숨김 POST /admin/introductions 제거
• 소개 정보가 없을 때 공개·어드민 조회 API가 HTTP 404를 반환하도록 수정
• 소개 요청 필수 필드 검증 및 Bean Validation 의존성 추가
• 수정 요청에서 이미지와 목록을 생략하면 기존 데이터를 유지하도록 개선
• 소개 API 응답 타입 제네릭 적용
• 소개 API 등록·수정·조회·검증 테스트 추가
• 34기 소개 데이터 입력 및 기수 전환 절차 문서화
• README에 개발 문서 링크 추가

✅ 완료 조건

• 도메인 패키지 구조를 일관된 형태로 정리
• 패키지 이동 후 기존 코드의 import 경로 수정
• 소개 데이터를 최초 등록할 수 있는 API 제공
• 소개 데이터가 없을 때 404 응답
• 소개 정보 등록 및 수정 동작 테스트
• 소개 페이지 DB 전환 및 34기 데이터 입력 절차 문서화

🧪 테스트 및 검증 결과

테스트 항목	검증 방법	결과
전체 프로젝트 테스트	./gradlew test	성공
소개 정보가 없는 경우	GET /api/introductions MockMvc 테스트	HTTP 404 확인
소개 정보 최초 등록	PUT /admin/introductions MockMvc 테스트	데이터 생성 및 HTTP 200 확인
기존 소개 정보 수정	동일 API 재호출 및 DB 조회	기존 행 수정 및 중복 생성 방지 확인
이미지 생략 시 기존 값 유지	이미지 최초 등록 후 파일 없이 수정	기존 이미지 URL 유지 확인
필수 필드 검증	필수값을 누락한 PUT 요청	HTTP 400 확인
공개 소개 정보 조회	수정 후 GET /api/introductions 호출	변경된 응답 확인

테스트 환경

• 환경: Local, H2 in-memory DB, test profile
• 테스트 도구: JUnit 5, Spring Boot Test, MockMvc, Mockito, AssertJ

테스트 증빙

BUILD SUCCESSFUL

미검증 항목

• 운영 DB에 실제 34기 소개 데이터 입력
• 운영 AWS S3에 실제 이미지 업로드
• 프론트엔드 constants 제거 및 화면 연동
• current_cardinal 운영 데이터 변경
• 연락처 영역의 DB 전환

위 항목은 배포 후 기획·PM·프론트엔드와 실제 데이터를 확정한 뒤 진행해야 합니다.

🔍 리뷰 요청 사항

• 패키지 이동만 수행한 첫 번째 커밋과 기능 변경 커밋을 분리해서 확인 부탁드립니다.
• 소개 정보가 없으면 생성하고 있으면 수정하는 PUT upsert 방식이 적절한지 확인 부탁드립니다.
• 수정 요청에서 이미지·목록을 생략하면 유지하고, 목록을 전달하면 전체 교체하는 정책을 확인 부탁드립니다.
• EntityNotFoundException을 공통 HTTP 404 응답으로 처리하는 방식이 적절한지 확인 부탁드립니다.
• Contact 엔티티는 현재 repository/service/API가 없어 이번 소개 API 전환 범위에서 제외했습니다. 소개 API에 포함할지 별도 API로 분리할지 논의가 필요합니다.

⚠️ 배포 영향 및 참고 사항

• DB 스키마/데이터 변경: 코드상 스키마 변경은 없습니다. 배포 후 34기 소개 데이터 입력 및 current_cardinal 변경이 필요합니다.
• 환경 변수/설정 변경: 없음
• API 명세 변경:
  • 숨김 POST /admin/introductions 제거
  • PUT /admin/introductions가 최초 등록과 수정을 모두 처리
  • 소개 데이터가 없는 경우 공개·어드민 GET API가 HTTP 404 반환
  • 필수 요청값 누락 시 HTTP 400 반환
• 빌드 변경: spring-boot-starter-validation 의존성이 추가되어 기존 @Valid 검증도 정상적으로 동작합니다.
• 기타 주의 사항:
  • bannerCardinal과 회원 역할 판별용 current_cardinal은 별도 값입니다.
  • 34기 전체 데이터를 입력할 때 목록을 생략하면 기존 33기 목록이 유지되므로 모든 목록을 함께 입력해야 합니다.
  • 세부 전환 절차는 docs/introduction-data-transition.md를 참고해 주세요.

☑️ PR 체크리스트

• 관련 이슈를 연결했습니다.
• 코드 및 Git 컨벤션을 준수했습니다.
• 불필요한 코드와 디버깅 로그를 제거했습니다.
• 필요한 테스트를 수행하고 결과를 기록했습니다.
• 미검증 항목 또는 알려진 문제를 기록했습니다.
• API/DB/설정 변경 시 관련 문서를 업데이트했습니다.
• 민감 정보가 코드와 로그에 포함되지 않았는지 확인했습니다.

[github-actions]

Unit Test Results

29 tests   29 ✔️  4s ⏱️
  6 suites    0 💤
  6 files      0 ❌

Results for commit 9d29af3.

♻️ This comment has been updated with latest results.