v2.24 변경 기록의 이어지는 부분이다. 같은 검증 ID 

c5f768661885ec1d8a2ab918ee97531869bf6cc66dc02c421f7a7ae2d570fa15

 — 전체 코드베이스 파일별 해부 문서 추가

사람이 읽는 설명과 운영 기준을 기록한 문서이다.

  - `findAllByUser_UserIdOrderByIdDesc(userId)` (`WishlistRepository.java:15-16`) — `@EntityGraph({"popupStore","popupStore.images"})`로 직렬화 시 LazyInit 방어(open-in-view=false 환경).
  - `existsByUser_UserIdAndPopupStore_Id` / `findByUser_UserIdAndPopupStore_Id` — 중복 찜 검사 / 찜 토글·삭제용 단건 조회.
  - `findWithUserAndPopupByEndDate(targetDate)` (`WishlistRepository.java:33-35`) — `@Query` + `@EntityGraph({"popupStore","user"})`로 특정 종료일 팝업을 찜한 위시+사용자를 한 번에 fetch(메일 발송 시 LazyInit 방지). 위시 만료 cron 전용.
- **연결**: `Wishlist`+`PopupStore`+`User`+`PopupImage` 대상. 찜 서비스·마이페이지·만료알림 cron이 호출.

#### `popspot-backend/.../repository/MyCourseRepository.java` — 코스 조회
- **책임**: `JpaRepository<MyCourse, Long>`. 사용자별 코스 목록(`findAllByUserId`) 파생 쿼리 1개.
- **연결**: `MyCourse` 대상. 코스 서비스가 호출.

#### `popspot-backend/.../repository/FeedbackRepository.java` — 의견 조회 + 어드민 검수 + SLA
- **책임**: `JpaRepository<Feedback, Long>`. 본인 의견 목록 + 어드민 상태필터 검수큐 + 상태별 카운트 + SLA 카운트.
- **핵심 로직**:
  - `findAllByUserIdOrderByCreatedAtDesc(userId)` — 본인 의견 최신순.
  - `findForAdmin(status, pageable)` (`FeedbackRepository.java:17-21`) — `:status IS NULL OR f.status=:status` 패턴으로 status가 null이면 전체, 있으면 필터(동적 조건 한 줄 구현).
  - `countByStatus(status)`(대시보드 메트릭), `countOlderThan(status, cutoff)` (`FeedbackRepository.java:27-28`) — SLA 알림용 cutoff 이전 미처리 카운트.
- **연결**: `Feedback` 대상. 사용자 의견 서비스·어드민 피드백 컨트롤러·SLA 알림 cron이 호출.

#### `popspot-backend/.../repository/MusicTrackRepository.java` — 트랙 캐시 조회/랜덤/무드/실패카운터 (복잡)
- **책임**: `JpaRepository<MusicTrack, Long>`. ID 조회, 인기/랜덤/무드 매칭, cover 캐시 일괄청소, 재생 실패 카운터까지. 음악 도메인 핵심 리포.
- **핵심 로직**:

: 사람이 읽는 설명과 운영 기준을 기록한 문서이다. 변경 전에는 이 구간에 대응하는 코드가 없었다. 변경 후 코드는 

 같은 값과 기능을 사용해 처리한다.

  - `findByItunesTrackId`/`findBySpotifyTrackId` — 외부 트랙 ID로 캐시 hit 검사.
  - `findTopPlayed(pageable)` / `findAllWithMood(pageable)` (`MusicTrackRepository.java:19-39`) — youtubeVideoId 있는 곡 한정 인기/무드 조회.
  - `findRandomWithMood()` (`MusicTrackRepository.java:24-34`) — **nativeQuery** `ORDER BY RANDOM() LIMIT 1`(PostgreSQL 전용)로 무드 있는 곡 랜덤 1곡("운명의 곡 룰렛").
  - `findLikelyNonOfficialCached()` (`MusicTrackRepository.java:48-55`) — youtubeChannel에 cover/커버/remix/live 포함 OR `isOfficial=false`인 캐시 트랙 일괄 조회(어드민 cover 청소용).
  - `clearYoutubeCacheByIds(ids)` (`MusicTrackRepository.java:58-63`) — `@Modifying @Transactional`로 youtubeVideoId/Channel=NULL + isOfficial=false 일괄 비움 → 다음 재생 시 재선택.
  - `incrementPlaybackFailed(id)` (`MusicTrackRepository.java:69-74`) — `@Modifying @Transactional` 단일 SQL UPDATE로 `playbackFailedCount = COALESCE(...,0)+1`. race 무관 원자 증가.
  - `countPlaybackBlocked(threshold)` (`MusicTrackRepository.java:77-80`) — 임계값 이상 실패 트랙 수(어드민 embed 차단 통계).
- **연결**: `MusicTrack` 대상. 음악 검색/추천 서비스·어드민 캐시청소 엔드포인트·재생 실패 리포팅이 호출.
- **특이사항**: `findRandomWithMood`만 nativeQuery라 PostgreSQL `RANDOM()`에 묶임(DB 이식성 ↓). `@Modifying` 메서드 3개는 자체 `@Transactional`을 달아 호출 측 트랜잭션 없이도 동작(PopupStore의 markExpired와 대비되는 패턴).

#### `popspot-backend/.../repository/UserMusicHistoryRepository.java` — 청취 기록 조회
- **책임**: `JpaRepository<UserMusicHistory, Long>`. 사용자 최근 청취(최신순 페이징) + 동일 곡 중복 등록 방지 카운트.
- **핵심 로직**: `findByUserIdOrderByPlayedAtDesc(userId, pageable)`(패스포트 화면/추천 보충), `countByUserIdAndTrackId(userId, trackId)`(중복 등록 방지). 둘 다 파생 쿼리.
- **연결**: `UserMusicHistory` 대상. 음악 패스포트/재생 기록 서비스가 호출.

#### `popspot-backend/.../repository/SpotifyAuthRepository.java` — Spotify 토큰 조회/삭제
- **책임**: `JpaRepository<SpotifyAuth, Long>`. 사용자별 토큰 조회 + 탈퇴 시 토큰 삭제.
- **핵심 로직**: `findByUserId(userId)`(토큰 로드/갱신), `deleteByUserId(userId)` (`SpotifyAuthRepository.java:14-16`) — `@Modifying @Transactional`로 회원 탈퇴 시 즉시 삭제(PIPA + Spotify 약관 의무).
- **연결**: `SpotifyAuth` 대상. Spotify 연동/토큰 갱신 서비스·회원 탈퇴 플로우가 호출.

#### `popspot-backend/.../repository/PopupImageRepository.java` — 팝업 이미지 기본 CRUD
- **책임**: `JpaRepository<PopupImage, Long>`. 커스텀 메서드 없는 순수 CRUD(`deleteByPopupStore`는 주석 처리됨).
- **연결**: `PopupImage` 대상. 이미지 등록/관리 서비스가 기본 save/delete로 호출.
- **특이사항**: 주석 처리된 `deleteByPopupStore` 흔적만 남음 — 현재는 이미지 삭제를 다른 경로(PopupStore의 `@JoinColumn` 단방향 관리 또는 직접 delete)로 처리.

**전체 연결 관계 요약**: `PopupStore`가 도메인 허브로 `PopupImage`(소유, 단방향 @JoinColumn) · `Goods`/`Stamp`/`Wishlist`/`ChatMessage`(자식 ManyToOne)가 모여듦. `User`는 `MatePost.author`/`Wishlist.user`만 객체 FK로 연결되고, `Stamp`/`MyCourse`/`Orders`/`Feedback`/`UserMusicHistory`/`SpotifyAuth`는 `userId`를 평문 컬럼으로 느슨하게 참조(객체 관계 없음). 음악 도메인(`MusicTrack`↔`UserMusicHistory`↔`SpotifyAuth`)도 ID 평문 참조로 느슨 결합. N+1/LazyInit 방어가 리포지토리 전반의 핵심 패턴(`@EntityGraph`로 `images`까지, 채팅은 EAGER+`@JsonIgnore(Properties)`). PK 전략은 PostgreSQL 환경 때문에 SEQUENCE(PopupStore/Orders/MatePost/MateChatMessage/ChatMessage/MyCourse/Feedback)와 IDENTITY(Goods/PopupImage/Stamp/Wishlist/MusicTrack/UserMusicHistory/SpotifyAuth)가 혼재하고, User만 애플리케이션 생성 UUID String.

## B8 — 백엔드 · DTO / model / mapper / 예외 / 리소스

#### `popspot-backend/src/main/java/com/example/popspotbackend/dto/CalendarPopupDto.java` — 캘린더 위젯용 경량 팝업 DTO
- **책임**: 프론트 캘린더가 소비하는 최소 필드만 담아 `PopupStore` 엔티티 전체 직렬화의 페이로드 과대 + LAZY 로딩 위험을 차단(`CalendarPopupDto.java:7`).
- **핵심 로직**: `fromEntity(PopupStore p)` 정적 팩토리가 Lombok `@Builder`로 9개 필드만 매핑(`:21-33`). `sourceType`(MANUAL/CRAWLED)은 "자동수집" 뱃지용, `sourceUrl`은 저작권법 출처표시용으로 의도적으로 노출(`:18-19`).
- **연결**: `entity.PopupStore` 의존. 캘린더 데이터를 내려주는 서비스/컨트롤러가 이 팩토리를 호출(피호출). Lombok `@Data @Builder`.

#### `popspot-backend/src/main/java/com/example/popspotbackend/dto/CourseSaveRequestDto.java` — 코스 저장 요청 DTO
- **책임**: 사용자가 짠 코스를 저장할 때 `userId`/`courseName`/`courseData` 3필드를 받는 단순 요청 바디.
- **특이사항**: Bean Validation 애너테이션이 전혀 없다. `userId`를 클라이언트가 직접 담는 구조라 컨트롤러/서비스 단에서 토큰 주체와 일치 검증이 없으면 IDOR 소지(타 DTO는 토큰에서 userId를 채우는 패턴을 명시함 — 이 DTO는 그렇지 않음).
- **연결**: 코스 저장 컨트롤러가 `@RequestBody`로 수신. `MyCourse` 엔티티로 변환되어 저장될 것으로 보임(응답은 `MyCourseResponseDto`).

#### `popspot-backend/src/main/java/com/example/popspotbackend/dto/LoginRequestDto.java` — 로컬 로그인 요청 DTO
- **책임**: 이메일/비밀번호 로그인 입력. `@Getter @NoArgsConstructor`만 — Jackson 역직렬화용.
- **특이사항**: 검증 애너테이션 없음(로그인은 형식보다 인증 결과로 거르므로 의도된 설계로 보임). setter가 없어 Jackson은 필드 직접 주입.

#### `popspot-backend/src/main/java/com/example/popspotbackend/dto/PopupReportRequestDto.java` — 팝업 제보 요청(Mass Assignment 방어) DTO
- **책임**: 사용자 팝업 제보 시 **허용 필드만** 명시 수신. `PopupStore` 엔티티를 그대로 받으면 `id`/`status`/`viewCount` 등을 클라이언트가 임의 주입해 저장되는 취약점을 차단(`:9-11`).

- **핵심 로직**: `name`/`location`은 `@NotBlank`+`@Size`, `category`/`description`/`imageUrl`/`startDate`/`endDate`는 `@Size`만. 길이 상한으로 저장소 오염/과대 입력 방지.
- **특이사항**: 보안 핵심 DTO. 엔티티 직접 바인딩 금지 패턴의 대표 사례. 검증 실패는 `GlobalExceptionHandler`가 400으로 변환.

#### `popspot-backend/src/main/java/com/example/popspotbackend/dto/PopupTakedownRequestDto.java` — 권리자 takedown 요청 DTO
- **책임**: 자동수집된 팝업이 부정확/저작권 침해일 때 권리자가 내리기 요청하는 폼. 이용약관 §10 신고창구 데이터(`:8`).
- **핵심 로직**: `requesterEmail` `@NotBlank @Email`, `reason` `@NotBlank @Size(max=500)`.
- **연결**: takedown 컨트롤러가 수신 → `popup_store.review_status='TAKEDOWN'` + `takedown_*` 컬럼(V4) 갱신으로 이어진다. 운영자 알림은 `popspot.crawler.takedown-notify-email`(properties §18) 및 SLA cron(§20)과 연동.

#### `popspot-backend/src/main/java/com/example/popspotbackend/dto/StampRequest.java` — 스탬프 적립 요청 DTO
- **책임**: `userId`+`popupId`로 방문 스탬프 적립 요청. `@Getter @Setter`.
- **특이사항**: 검증 없음. 중복 적립은 DTO가 아니라 DB 유니크 제약(V2 `uk_stamp_user_popup`)으로 race condition까지 차단된다 — DTO와 스키마가 한 쌍으로 동작.

#### `popspot-backend/src/main/java/com/example/popspotbackend/dto/auth/OAuthAttributes.java` — OAuth2 프로바이더 속성 정규화 DTO
- **책임**: Google/Kakao/Naver의 서로 다른 사용자 응답 JSON 구조를 공통 형태(`name`/`email`/`picture`/`provider`)로 통일(`:7-12`).
- **핵심 로직**:
  - `of(registrationId, userNameAttributeName, attributes)`가 프로바이더 분기 디스패처(`:43-52`) — naver→`ofNaver`, kakao→`ofKakao`, 그 외→`ofGoogle`(기본값이 Google).
  - `ofGoogle`: 최상위 키에서 직접 추출(`:54-64`).
  - `ofKakao`: `kakao_account.profile` 중첩에서 `nickname`/`profile_image_url`, 이메일은 `kakao_account.email`(`:67-80`). 무체크 캐스트라 `@SuppressWarnings("unchecked")`.

  - `ofNaver`: `response` 래퍼 안에서 추출하고, `attributes` 자체도 `response`로 교체 저장(`:83-95`) — 이후 Spring Security가 nameAttributeKey(`id`)를 `response` 맵 기준으로 찾도록.
- **특이사항**: Kakao/Naver는 중첩 맵을 가정하고 캐스팅하므로, 프로바이더 스코프 미동의 등으로 `kakao_account`/`profile`/`response`가 누락되면 NPE/ClassCastException 가능 → 상위에서 OAuth2 예외로 처리될 것. `attributes` 키 이름(`id`/`response`)은 properties의 `user-name-attribute` 설정과 정확히 짝.
- **연결**: 커스텀 `OAuth2UserService`가 `of(...)`를 호출(피호출), `entity.User` upsert로 연결. properties §7~9의 OAuth 등록 정보에 의존.

#### `popspot-backend/src/main/java/com/example/popspotbackend/dto/CongestionDto.java` — 성수동 실시간 혼잡도+날씨 응답 DTO
- **책임**: 혼잡도 4단계(`level`: 여유/보통/약간 붐빔/붐빔)+메시지+인구 범위(min/maxPop)+날씨(temp/sky/rainChance)+12시간 예측(`forecast`)+연령대 비율(`ageRates`) 묶음(`:9-13`).
- **핵심 로직**: 순수 데이터 홀더. `forecast`는 `List<Map<String,String>>`(`{"time":"14:00","pop":"3200"}`), `ageRates`는 `Map<String,Double>`.
- **연결**: 서울 열린데이터 API(`seoul.api.key`, properties §11) + 기상 데이터를 가공하는 혼잡도 서비스가 채워 반환. `@Data @AllArgsConstructor @NoArgsConstructor`.

#### `popspot-backend/src/main/java/com/example/popspotbackend/dto/LoginResponseDto.java` — 로그인 성공 응답 DTO
- **책임**: 로그인 성공 시 `userId`/`email`/`nickname`/`role`/`token`(JWT)/`isPremium`/`megaphoneCount` 반환.
- **핵심 로직**: `isPremium`이 boolean이라 Jackson 기본 직렬화가 `premium` 키로 나가는 것을 `@JsonProperty("isPremium")`으로 강제 고정(`:11-13`, `:24-25`) — 프론트 계약 유지를 위한 함정 회피.
- **연결**: 인증 컨트롤러가 JWT 발급 후 반환. `megaphoneCount`는 V8에서 등급별 부스트로 정책이 바뀌었지만 호환 위해 잔존하는 레거시 필드.

#### `popspot-backend/src/main/java/com/example/popspotbackend/dto/MyPageDto.java` — 마이페이지 요약 응답 DTO

- **책임**: 닉네임/프리미엄 여부/만료일/부스트(메가폰)수/스탬프·좋아요·리뷰 카운트 집계 응답.
- **핵심 로직**: `LoginResponseDto`와 동일하게 `isPremium` 키를 `@JsonProperty`로 고정(`:11`, `:18`). `premiumExpiryDate`는 `LocalDateTime`(타임존은 properties `spring.jackson.time-zone=Asia/Seoul`).
- **연결**: 마이페이지 서비스가 여러 Repository 카운트를 모아 빌드. `stampCount`는 V10 `idx_stamp_user_id` 인덱스로 가속되는 `countByUserId`와 연관.

#### `popspot-backend/src/main/java/com/example/popspotbackend/dto/PlanningPlace.java` — 계획 보드 장소 카드 DTO
- **책임**: 동행 계획 보드의 장소 카드(id/name/lat/lng/category)와 투표 카운트(`likeCount`=좋아요, `fireCount`="가자!").
- **핵심 로직**: `@Builder.Default`로 두 카운트 초기값 0 보장(`:25-26`) — Builder 사용 시 누락돼도 null/미초기화 방지. 클라이언트가 STOMP로 실시간 증분 수신(`:11-12`).
- **연결**: WebSocket/STOMP 기반 실시간 계획 보드 서비스가 사용. `VoteRequest`로 들어온 투표가 이 카운트를 증분.

#### `popspot-backend/src/main/java/com/example/popspotbackend/dto/SignupRequestDto.java` — 회원가입 요청 DTO
- **책임**: 가입 입력(email/password/nickname/phoneNumber)의 형식·강도·필수 여부를 컨트롤러 진입 직후 Bean Validation으로 검증(`:10-15`).
- **핵심 로직**:
  - 비밀번호 정규식 `PASSWORD_REGEX`(`:21-22`): 영문+숫자+특수문자(`@$!%*#?&`) 각 1개 이상, 8~20자. lookahead 조합.
  - 전화번호 정규식 `PHONE_REGEX`(`:23`): `^010\d{8}$` (010 + 8자리).
  - 각 필드에 한국어 메시지 명시(`:25-38`).
- **특이사항**: 정규식은 특수문자 집합을 화이트리스트로 제한하므로 그 외 기호(예: `^`,`-`)는 거부됨. 검증 실패 → `MethodArgumentNotValidException` → `GlobalExceptionHandler` 400.
- **연결**: 회원가입 컨트롤러 `@Valid @RequestBody`. 통과 시 `entity.User` 생성. 가입 시점에 `agreed_terms_version`(V11)을 현재 버전으로 박는 흐름과 연계.

#### `popspot-backend/src/main/java/com/example/popspotbackend/dto/VoteRequest.java` — 계획 보드 투표 요청 DTO

- **책임**: 장소 카드 투표 입력(`placeId`+`voteType`). `voteType`은 "LIKE"/"FIRE"만 허용, enum 변환은 컨트롤러에서(`:7-8`).
- **특이사항**: DTO 자체엔 enum 제약이 없어 잘못된 `voteType` 거부는 컨트롤러 변환 로직 책임(거기서 `IllegalArgumentException` 시 400).
- **연결**: `PlanningPlace`의 `likeCount`/`fireCount` 증분 트리거.

#### `popspot-backend/src/main/java/com/example/popspotbackend/dto/WishlistResponseDto.java` — 찜 목록 행 응답 DTO
- **책임**: 마이페이지 찜 목록 각 행(`wishlistId`,`popupId`,`popupName`,`popupImage`,`location`,`startDate`,`endDate`).
- **연결**: 위시리스트 조회 서비스가 `Wishlist`+`PopupStore` 조인 결과를 매핑. V10 `idx_wishlist_user_id`/`idx_wishlist_popup_store`로 가속. 위시 만료 D-3 메일 cron(properties §21)도 같은 조인 경로 사용.

#### `popspot-backend/src/main/java/com/example/popspotbackend/dto/MyCourseResponseDto.java` — 내 코스 조회 응답 DTO
- **책임**: `MyCourse` 엔티티 직접 직렬화의 LAZY/내부 컬럼 노출을 API 경계에서 차단하면서 프론트 필드명 유지(`:8-12`).
- **핵심 로직**: 전 필드 `final` + `fromEntity(MyCourse)` 정적 팩토리(`:23-31`). 불변 응답 객체.
- **연결**: 코스 조회 컨트롤러가 호출(피호출), 입력은 `CourseSaveRequestDto`. v2.9-R2C "엔티티→DTO 분리" 작업 산물로 보임.

#### `popspot-backend/src/main/java/com/example/popspotbackend/dto/FeedbackCreateRequestDto.java` — 의견 보내기 작성 요청 DTO
- **책임**: 의견 작성 입력. 로그인 사용자는 `userId`를 토큰에서 채우므로 DTO에 없음, 게스트는 답신용 이메일을 선택 입력(`:8-12`).
- **핵심 로직**: `category`(BUG/FEATURE/GOOD/OTHER) `@NotBlank @Size(32)`, `title` `@NotBlank @Size(200)`, `content` `@NotBlank @Size(4000)`, `guestEmail` `@Email @Size(255)`(선택, `@NotBlank` 없음 → 비워도 통과).
- **연결**: 사용자 FeedbackController `@Valid` 수신 → `feedback` 테이블(V7). `content` 4000자 상한은 V7 `content TEXT`와 정합.

#### `popspot-backend/src/main/java/com/example/popspotbackend/dto/FeedbackReplyRequestDto.java` — 어드민 답변+상태변경 요청 DTO
- **책임**: 어드민이 의견에 답변과 상태를 동시에(또는 따로) 보내는 DTO(`:7-10`).
- **핵심 로직**: `adminReply` `@Size(4000)`만(비우면 미작성). `status` `@NotBlank @Size(32)` — PENDING/REVIEWING/RESOLVED/WONT_FIX(`:19-22`). 둘 다 빈 요청은 서비스 단에서 거부(주석 명시이나 `status`가 `@NotBlank`라 사실상 status는 필수).
- **연결**: `AdminFeedbackController`가 수신 → `feedback.status`/`admin_reply`/`replied_at`(V7) 갱신.

#### `popspot-backend/src/main/java/com/example/popspotbackend/dto/FeedbackResponseDto.java` — 의견 단건 응답 DTO
- **책임**: 사용자 본인 목록과 어드민 검수 큐가 **동일 모양**으로 공유하는 응답(`:10-14`).
- **핵심 로직**: `fromEntity(Feedback f)` 정적 팩토리로 10개 필드 전체 매핑(`:33-46`). `guestEmail`/`userId`/`adminReply`/`repliedAt` 포함.
- **특이사항**: 사용자/어드민이 같은 DTO를 쓰므로 사용자 본인 응답에도 `guestEmail` 등 전 필드가 노출됨 — 어드민 전용 필드가 생기면 분리 필요(주석에 명시). 현재는 동일 모양이라 통합.
- **연결**: 사용자/어드민 양쪽 FeedbackController가 반환. `Feedback` 엔티티(V7) 의존.

#### `popspot-backend/src/main/java/com/example/popspotbackend/dto/MateDto.java` — 동행 게시글 작성 DTO
- **책임**: 메이트(동행) 글 작성 입력(userId/title/content/targetPopup/maxPeople/useBoost).
- **핵심 로직**: `@NoArgsConstructor`는 Jackson 역직렬화용(setter 호출 전 빈 인스턴스 생성, `:9-10`). `useBoost`(`:22-26`)는 v2.12에서 옛 `useMegaphone`의 의미를 그대로 이어받은 상단 부스트 요청 플래그 — 프론트는 `useBoost` 이름으로 전송.
- **특이사항**: 검증 애너테이션 없음. `useBoost`는 등급별 월 한도 안에서만 허용되며 한도 추적은 V8 `boost_used_count`/`boost_period` + 서비스 로직 담당.
- **연결**: 메이트 컨트롤러 수신 → `mate_post` 테이블(V8/V9/V14 확장).

#### `popspot-backend/src/main/java/com/example/popspotbackend/dto/PopupSearchDto.java` — Algolia 인덱싱용 경량 DTO

POP-SPOT v2.24 (3/3) — 브랜드 리뉴얼 — P-핀 로고 + Wanted Sans 폰트 통일

Public

v2.24에 묶인 4개 커밋과 21개 파일 변경을 Git에서 전수 대조했다. 모든 변경 줄을 Before→After와 쉬운 해석으로 기록했다.

POP-SPOT v2.24 (2/3) — 브랜드 리뉴얼 — P-핀 로고 + Wanted Sans 폰트 통일

이어 읽을 기록

댓글