feat(admin): 어드민 버전 관리 기능 전반 신규 구축 (도메인/API/UI/인증/배포 연동)

[1Seob]

📝 요약(Summary)

배경

내부 기획 버전 관리를 효율적으로 운영하기 위해, 관리자 페이지에서 앱 버전 및 업데이트 항목을 제어하고 관리할 수 있는 기능을 신규 구축했습니다.

• 플랫폼별 최신 버전, 세부 항목, 그리고 사용자별 dismiss(다시 보지 않기) 연동을 안정적으로 처리할 수 있도록 설계했습니다.

주요 변경사항

1. 버전 관리 도메인 신규 구축

• app_versions, app_version_items, user_app_version_dismissals 테이블 기반의 모델, 리포지토리, 서비스 레이어 구현
• 플랫폼별 최신 버전 상태(is_latest) 관리 구조 적용
• 버전별 요약 정보(summary) 및 상세 항목들(items: title, description, displayOrder)의 관리 모델 반영
• 홈 화면 조회 스펙과 연계되는 사용자별 업데이트 팝업 dismiss 상태 처리 로직 포함

2. 어드민 인증 및 접근 제어 신규 구축

• ADMIN_PAGE_PASSWORD 기반의 관리자 인증 체계 도입
• 관리자 인증 관련 API 구현
  • POST /admin/api/login
  • POST /admin/api/logout
  • GET /admin/api/auth-status
• /admin/** 경로를 보호하는 인터셉터(Interceptor) 적용
  • 미인증 상태의 API 요청: 401 Unauthorized 반환
  • 미인증 상태의 페이지 요청: 로그인 페이지로 리다이렉트

3. 어드민 버전 관리 API 구축

• 최신 버전 조회: GET /admin/api/versions/latest
• 버전 생성 (플랫폼별 기존 latest 해제 및 신규 latest 전환 로직 포함): POST /admin/api/versions
• 버전 요약(Summary) 수정: PUT /admin/api/versions/{appVersionId}/summary
• 세부 항목(Items) CRUD API 구현
  • 추가: POST /admin/api/versions/{appVersionId}/items
  • 수정: PUT /admin/api/versions/items/{appVersionItemId}
  • 삭제: DELETE /admin/api/versions/items/{appVersionItemId}

4. Thymeleaf 기반 어드민 UI 구축

• 관리자 로그인 페이지 및 버전 관리 메인 인터페이스 구현
• 버전 생성, summary 수정, 항목 추가/수정/삭제 API 프론트 연동 완료
• 실무 운영성을 고려한 UX 요소 반영
  • 모든 최종 변경 작업에 확인 팝업(Yes/No) 적용
  • 성공 및 오류 발생 시 결과 팝업 UI 통일
  • 데이터의 확정 상태와 수정 상태를 시각적으로 명확히 구분 (opacity 조절)
  • Edit(편집) / Cancel(취소) 액션 분리
  • 항목 편집 모드 진입 시 실수로 인한 삭제를 방지하기 위해 Delete 버튼 숨김 처리

5. 어드민 라우팅 구조 정리

• /admin 접근 시 /admin/tabs/app-versions 경로로 리다이렉트되도록 구조 적용
• 향후 기능 확장에 따른 탭 추가를 고려하여 폴더 및 경로 체계를 마련하되, 현재는 단일 탭(App Versions)만 깔끔하게 노출되도록 정리

6. 배포 워크플로우 연동

• GitHub Actions의 dev 및 prod 배포 워크플로우에 ADMIN_PAGE_PASSWORD 환경변수 주입 설정 추가

안정성 및 예외 처리

• 동시성 및 제약조건 최적화: 최신 버전(is_latest) 전환 과정에서 JPA flush 순서를 명시적으로 제어하여, Unique Index(유니크 인덱스) 충돌 가능성을 완화했습니다.
• 예외 시나리오 방어: 항목 등록/수정 시 displayOrder 중복 검증, 리소스 미존재 등 운영 중 발생할 수 있는 시나리오에 대한 예외 처리를 완료했습니다.
• 신규 에러코드 추가 및 매핑:
  • APP_VERSION_ALREADY_EXISTS
  • APP_VERSION_ITEM_NOT_FOUND
  • APP_VERSION_ITEM_DISPLAY_ORDER_DUPLICATED
  • ADMIN_PAGE_INVALID_PASSWORD

🔗 Related Issue

• Closes:

💬 공유사항

✅ PR Checklist

PR이 다음 요구 사항을 충족하는지 확인하세요.

• PR 제목을 커밋 메시지 컨벤션에 맞게 작성했습니다.

[coldsunn]

머지 고고!