Queuing Backend

Spring Boot 4 / Java 21 기반의 실시간 DJing·음악 공유 백엔드다.

루트 구조

• src/main/java/queuing/core
  • global 공통 설정, 예외, 보안, 응답, Redis/JPA 인프라
  • room 방/큐/실시간 재생 도메인
  • user 사용자 조회/인증/프로필 도메인
  • follow 팔로우 관계 도메인
  • friend 상호 팔로우 기반 친구 목록 API
• src/main/resources
  • config 프로필별 설정
  • templates, static, scripts 런타임 리소스
• src/test/java
  • 현재 room 중심 회귀/통합 테스트
• docs
  • frontend-room-websocket-guide.md 프론트 연동 가이드
  • queue-feature-execution-plan.md 큐 저장 구조 정리 문서
  • youtube-queue-integration.md YouTube 메타데이터 연동 메모
• container
  • 로컬 MariaDB/Redis 컨테이너 리소스

핵심 구조 원칙

• room queue의 source of truth는 Redis가 아니라 RDB 다.
• Redis는 참가자 / 세션 / playback / track-end scheduling / delayed room auto-delete reservation 같은 세션성 최신 상태만 담당한다.
• room 도메인은 application / domain / infrastructure / presentation 계층으로 분리한다.

room 관련 Redis key 메모

• 참가자: room:{slug}:participants
• playback: room:{slug}:playback
• 세션 역인덱스: room:{slug}:sessions
• user/session 매핑: room:user_session:{userId}, room:session:{sessionId}
• track-end scheduling: room:track_end:zset, room:{slug}:track_end:member
• auto-delete scheduling: room:auto_delete:zset, room:{slug}:auto_delete:member

track-end cleanup 과 auto-delete cleanup 은 모두 room delete 이후 Redis runtime state 정리 단계에서 멱등하게 실행되도록 설계되어, 이미 사라진 key 를 다시 지워도 실패로 취급하지 않는다.

자주 쓰는 명령

./gradlew test
./gradlew build
./gradlew test --tests '*RoomQueueCommandServicePersistenceTest'
./gradlew test --tests '*RoomSocketServiceTest'

Spring profile configuration

The packaged configuration uses src/main/resources/application.yaml as the common entrypoint. It imports only domain index YAML files under config/core, config/security, config/api, and config/infra. Domain index files import detail YAML files from the same domain only; detail YAML files must not declare spring.config.import.

Local profile

Run local development with an explicit profile:

SPRING_PROFILES_ACTIVE=local ./gradlew bootRun

Only the local profile carries development defaults such as local MariaDB/Redis endpoints, SQL logging, and ddl-auto=update. OAuth2 and YouTube secrets are not stored in YAML; provide them through environment variables when those features are needed locally.

Dev/prod profiles

dev and prod do not import external /config/*.yaml, overrides.yaml, or secrets.yaml files. They use required environment placeholders without defaults so missing values fail fast during startup/config validation.

Required environment variables for shared dev/prod startup:

SPRING_DATASOURCE_URL
SPRING_DATASOURCE_USERNAME
SPRING_DATASOURCE_PASSWORD
SPRING_DATA_REDIS_HOST
SPRING_DATA_REDIS_PORT
GOOGLE_OAUTH2_REDIRECT_BASE_URI
GOOGLE_OAUTH2_CLIENT_ID
GOOGLE_OAUTH2_CLIENT_SECRET
YOUTUBE_API_KEY
CORS_ALLOWED_ORIGINS
REDIRECT_BASE_URL
REDIRECT_ALLOWED_ORIGINS
XSRF_COOKIE_DOMAIN
XSRF_COOKIE_SECURE
SESSION_COOKIE_DOMAIN
SESSION_COOKIE_SECURE
REMEMBER_ME_COOKIE_KEY
ROOM_KICK_IDENTITY_PEPPER
ROOM_KICK_BLOCK_TTL

prod also enforces safer JPA behavior: SQL logging is disabled and schema mutation is not allowed by configuration validation.