Fix: 스터디룸 내 프론트엔드 요구사항 및 오류 사항 수정 (#287)

src/main/java/com/back/domain/studyroom/controller/RoomController.java

@@ -417,6 +417,31 @@ public ResponseEntity<RsData<Void>> removeRoomPassword(
                 .body(RsData.success("방 비밀번호 제거 완료", null));
     }
 
+    @PostMapping("/{roomId}/password")
+    @Operation(
+        summary = "방 비밀번호 설정",
+        description = "비밀번호가 없는 방에 비밀번호를 설정합니다. 이미 비밀번호가 있는 경우 비밀번호 변경 API(PUT)를 사용. 방장만 실행 가능합니다."
+    )
+    @ApiResponses({
+        @ApiResponse(responseCode = "200", description = "비밀번호 설정 성공"),
+        @ApiResponse(responseCode = "400", description = "이미 비밀번호가 설정되어 있음"),
+        @ApiResponse(responseCode = "403", description = "방장 권한 없음"),
+        @ApiResponse(responseCode = "404", description = "존재하지 않는 방"),
+        @ApiResponse(responseCode = "401", description = "인증 실패")
+    })
+    public ResponseEntity<RsData<Void>> setRoomPassword(
+            @Parameter(description = "방 ID", required = true) @PathVariable Long roomId,
+            @Valid @RequestBody SetRoomPasswordRequest request) {
+
+        Long currentUserId = currentUser.getUserId();
+
+        roomService.setRoomPassword(roomId, request.getNewPassword(), currentUserId);
+
+        return ResponseEntity
+                .status(HttpStatus.OK)
+                .body(RsData.success("방 비밀번호 설정 완료", null));
+    }
+
     @DeleteMapping("/{roomId}")
     @Operation(
         summary = "방 종료", 

src/main/java/com/back/domain/studyroom/controller/RoomInvitePublicController.java

@@ -36,12 +36,13 @@ public class RoomInvitePublicController {
     @SecurityRequirement(name = "Bearer Authentication")
     @Operation(
         summary = "초대 코드로 방 입장", 
-        description = "초대 코드를 사용하여 방에 입장합니다. " +
+        description = "초대 코드를 사용하여 방 입장 권한을 획득합니다. " +
                       "비밀번호가 걸린 방도 초대 코드로 입장 가능합니다. " +
+                      "실제 온라인 등록은 WebSocket 연결 시 자동으로 처리됩니다. " +
                       "비로그인 사용자는 401 응답을 받습니다 (프론트에서 로그인 페이지로 이동)."
     )
     @ApiResponses({
-        @ApiResponse(responseCode = "200", description = "입장 성공"),
+        @ApiResponse(responseCode = "200", description = "입장 권한 획득 성공 (WebSocket 연결 필요)"),
         @ApiResponse(responseCode = "400", description = "만료되었거나 유효하지 않은 코드"),
         @ApiResponse(responseCode = "404", description = "존재하지 않는 초대 코드"),
         @ApiResponse(responseCode = "401", description = "인증 필요 (비로그인)")
@@ -56,12 +57,12 @@ public ResponseEntity<RsData<JoinRoomResponse>> joinByInviteCode(
         // 초대 코드 검증 및 방 조회
         Room room = inviteService.getRoomByInviteCode(inviteCode);
 
-        // 방 입장 (비밀번호 무시)
-        RoomMember member = roomService.joinRoom(room.getId(), null, userId);
+        // 방 입장 권한 체크 (비밀번호 무시, Redis 등록 건너뜀)
+        RoomMember member = roomService.joinRoom(room.getId(), null, userId, false);
         JoinRoomResponse response = JoinRoomResponse.from(member);
 
         return ResponseEntity
                 .status(HttpStatus.OK)
-                .body(RsData.success("초대 코드로 입장 완료", response));
+                .body(RsData.success("초대 코드로 입장 권한 획득 완료. WebSocket 연결 후 실제 입장됩니다.", response));
     }
 }

src/main/java/com/back/domain/studyroom/dto/MyRoomResponse.java

@@ -14,7 +14,8 @@ public class MyRoomResponse {
     private Long roomId;
     private String title;
     private String description;
-    private Boolean isPrivate;  // 비공개 방 여부 (UI에서 🔒 아이콘 표시용)
+    private Boolean isPrivate;
+    private String thumbnailUrl;
     private int currentParticipants;
     private int maxParticipants;
     private RoomStatus status;
@@ -27,6 +28,7 @@ public static MyRoomResponse of(Room room, long currentParticipants, RoomRole my
                 .title(room.getTitle())
                 .description(room.getDescription() != null ? room.getDescription() : "")
                 .isPrivate(room.isPrivate())  // 비공개 방 여부
+                .thumbnailUrl(room.getThumbnailUrl())  // 썸네일 URL
                 .currentParticipants((int) currentParticipants)  // Redis에서 조회한 실시간 값
                 .maxParticipants(room.getMaxParticipants())
                 .status(room.getStatus())

src/main/java/com/back/domain/studyroom/dto/RoomDetailResponse.java

@@ -15,6 +15,7 @@ public class RoomDetailResponse {
     private String title;
     private String description;
     private boolean isPrivate;
+    private String thumbnailUrl;  // 썸네일 이미지 URL
     private int maxParticipants;
     private int currentParticipants;
     private RoomStatus status;
@@ -31,6 +32,7 @@ public static RoomDetailResponse of(Room room, long currentParticipants, List<Ro
                 .title(room.getTitle())
                 .description(room.getDescription() != null ? room.getDescription() : "")
                 .isPrivate(room.isPrivate())
+                .thumbnailUrl(room.getThumbnailUrl())  // 썸네일 URL
                 .maxParticipants(room.getMaxParticipants())
                 .currentParticipants((int) currentParticipants)  // Redis에서 조회한 실시간 값
                 .status(room.getStatus())

src/main/java/com/back/domain/studyroom/dto/SetRoomPasswordRequest.java

@@ -0,0 +1,20 @@
+package com.back.domain.studyroom.dto;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.Size;
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+@Getter
+@NoArgsConstructor
+@AllArgsConstructor
+@Schema(description = "방 비밀번호 설정 요청 (비밀번호가 없는 방에 비밀번호 추가)")
+public class SetRoomPasswordRequest {
+
+    @NotBlank(message = "새 비밀번호는 필수입니다.")
+    @Size(min = 4, max = 20, message = "비밀번호는 4~20자 사이여야 합니다.")
+    @Schema(description = "설정할 비밀번호", example = "1234", required = true)
+    private String newPassword;
+}

src/main/java/com/back/domain/studyroom/entity/Room.java

@@ -224,9 +224,12 @@ public void updateWebRTCSettings(boolean allowCamera, boolean allowAudio, boolea
     /**
      * 방 비밀번호 변경 메서드
      방장이 방의 비밀번호를 변경할 때
-     별도 메서드로 분리한 이유: 비밀번호는 보안상 별도로 관리되어야 하기 때문 (ai의 추천)
+     별도 메서드로 분리한 이유: 비밀번호는 보안상 별도로 관리되어야 하기 때문
      */
     public void updatePassword(String newPassword) {
         this.password = newPassword;
+
+        // 비밀번호 유무에 따라 isPrivate 자동 설정
+        this.isPrivate = (newPassword != null && !newPassword.trim().isEmpty());
     }
 }

src/main/java/com/back/domain/studyroom/repository/RoomRepositoryImpl.java

@@ -74,20 +74,23 @@ public Page<Room> findJoinablePublicRooms(Pageable pageable) {
     }
 
     /**
-     * 사용자가 참여 중인 방 조회
+     * 사용자가 참여 중인 방 조회 (MEMBER 이상만)
      * 조회 조건:
-     * - 특정 사용자가 멤버로 등록된 방 (DB에 저장된 멤버십)
-     * TODO: Redis에서 온라인 상태 확인하도록 변경
+     * - 특정 사용자가 MEMBER 이상으로 등록된 방 (VISITOR 제외)
+     * - DB에 저장된 멤버십만 조회
      * @param userId 사용자 ID
-     * @return 참여 중인 방 목록
+     * @return 참여 중인 방 목록 (VISITOR 제외)
      */
     @Override
     public List<Room> findRoomsByUserId(Long userId) {
         return queryFactory
                 .selectFrom(room)
                 .leftJoin(room.createdBy, user).fetchJoin()  // N+1 방지
                 .join(room.roomMembers, roomMember)          // 멤버 조인
-                .where(roomMember.user.id.eq(userId))
+                .where(
+                        roomMember.user.id.eq(userId),
+                        roomMember.role.ne(com.back.domain.studyroom.entity.RoomRole.VISITOR)  // VISITOR 제외
+                )
                 .fetch();
     }
 

src/main/java/com/back/domain/studyroom/service/RoomService.java

@@ -100,7 +100,7 @@ public Room createRoom(String title, String description, boolean isPrivate,
     }
 
     /**
-     * 방 입장 메서드
+     * 방 입장 메서드 (WebSocket 연결과 함께 사용)
      * 
      * 입장 검증 과정:
      * 1. 방 존재 확인 (비관적 락으로 동시성 제어)
@@ -117,17 +117,33 @@ public Room createRoom(String title, String description, boolean isPrivate,
      */
     @Transactional
     public RoomMember joinRoom(Long roomId, String password, Long userId) {
+        return joinRoom(roomId, password, userId, true);
+    }
+
+    /**
+     * 방 입장 메서드 (오버로드 - WebSocket 등록 여부 선택 가능)
+     * 
+     * @param roomId 방 ID
+     * @param password 비밀번호 (비공개 방인 경우)
+     * @param userId 사용자 ID
+     * @param registerOnline WebSocket 세션 등록 여부 (true: Redis 등록, false: 권한 체크만)
+     * @return RoomMember (메모리상 또는 DB 저장된 객체)
+     */
+    @Transactional
+    public RoomMember joinRoom(Long roomId, String password, Long userId, boolean registerOnline) {
 
         // 1. 비관적 락으로 방 조회 - 동시 입장 시 정원 초과 방지
         Room room = roomRepository.findByIdWithLock(roomId)
                 .orElseThrow(() -> new CustomException(ErrorCode.ROOM_NOT_FOUND));
 
-        // 2. Redis에서 현재 온라인 사용자 수 조회
-        long currentOnlineCount = roomParticipantService.getParticipantCount(roomId);
+        // 2. Redis에서 현재 온라인 사용자 수 조회 (WebSocket 등록하는 경우만)
+        if (registerOnline) {
+            long currentOnlineCount = roomParticipantService.getParticipantCount(roomId);
 
-        // 3. 정원 확인 (Redis 기반)
-        if (currentOnlineCount >= room.getMaxParticipants()) {
-            throw new CustomException(ErrorCode.ROOM_FULL);
+            // 3. 정원 확인 (Redis 기반)
+            if (currentOnlineCount >= room.getMaxParticipants()) {
+                throw new CustomException(ErrorCode.ROOM_FULL);
+            }
         }
 
         // 4. 방 입장 가능 여부 확인 (활성화 + 입장 가능한 상태)
@@ -140,8 +156,8 @@ public RoomMember joinRoom(Long roomId, String password, Long userId) {
             throw new CustomException(ErrorCode.ROOM_NOT_JOINABLE);
         }
 
-        // 5. 비밀번호 확인
-        if (room.needsPassword() && !room.getPassword().equals(password)) {
+        // 5. 비밀번호 확인 (초대 코드 입장 시에는 password가 null일 수 있음)
+        if (room.needsPassword() && password != null && !room.getPassword().equals(password)) {
             throw new CustomException(ErrorCode.ROOM_PASSWORD_INCORRECT);
         }
 
@@ -156,23 +172,31 @@ public RoomMember joinRoom(Long roomId, String password, Long userId) {
             // 기존 멤버 재입장: DB에 있는 역할 그대로 사용
             RoomMember member = existingMember.get();
 
-            // Redis에 온라인 등록 (아바타 포함)
-            roomParticipantService.enterRoom(userId, roomId, avatarId);
-
-            log.info("기존 멤버 재입장 - RoomId: {}, UserId: {}, Role: {}, AvatarId: {}", 
-                    roomId, userId, member.getRole(), avatarId);
+            // WebSocket 연결과 함께 입장하는 경우에만 Redis 등록
+            if (registerOnline) {
+                roomParticipantService.enterRoom(userId, roomId, avatarId);
+                log.info("기존 멤버 재입장 (Redis 등록) - RoomId: {}, UserId: {}, Role: {}, AvatarId: {}", 
+                        roomId, userId, member.getRole(), avatarId);
+            } else {
+                log.info("기존 멤버 권한 확인 (Redis 등록 건너뜀) - RoomId: {}, UserId: {}, Role: {}", 
+                        roomId, userId, member.getRole());
+            }
 
             return member;
         }
 
         // 신규 입장자: VISITOR로 입장 (DB 저장 안함!)
         RoomMember visitorMember = RoomMember.createVisitor(room, user);
 
-        // Redis에만 온라인 등록 (아바타 포함)
-        roomParticipantService.enterRoom(userId, roomId, avatarId);
-
-        log.info("신규 입장 (VISITOR) - RoomId: {}, UserId: {}, DB 저장 안함, AvatarId: {}", 
-                roomId, userId, avatarId);
+        // WebSocket 연결과 함께 입장하는 경우에만 Redis 등록
+        if (registerOnline) {
+            roomParticipantService.enterRoom(userId, roomId, avatarId);
+            log.info("신규 입장 (VISITOR, Redis 등록) - RoomId: {}, UserId: {}, AvatarId: {}", 
+                    roomId, userId, avatarId);
+        } else {
+            log.info("신규 입장 권한 확인 (Redis 등록 건너뜀) - RoomId: {}, UserId: {}", 
+                    roomId, userId);
+        }
 
         // 메모리상 객체 반환 (DB에 저장되지 않음)
         return visitorMember;
@@ -360,6 +384,35 @@ public void removeRoomPassword(Long roomId, Long userId) {
         log.info("방 비밀번호 제거 완료 - RoomId: {}, UserId: {}", roomId, userId);
     }
 
+    /**
+     * 방 비밀번호 설정 (비밀번호가 없는 방에 비밀번호 추가)
+     * - 방장만 설정 가능
+     * - 기존 비밀번호가 없는 경우에만 사용
+     * @param roomId 방 ID
+     * @param newPassword 새 비밀번호
+     * @param userId 요청자 ID (방장)
+     */
+    @Transactional
+    public void setRoomPassword(Long roomId, String newPassword, Long userId) {
+        Room room = roomRepository.findById(roomId)
+                .orElseThrow(() -> new CustomException(ErrorCode.ROOM_NOT_FOUND));
+
+        // 방장 권한 확인
+        if (!room.isOwner(userId)) {
+            throw new CustomException(ErrorCode.NOT_ROOM_HOST);
+        }
+
+        // 이미 비밀번호가 있는 경우 에러
+        if (room.getPassword() != null && !room.getPassword().isEmpty()) {
+            throw new CustomException(ErrorCode.ROOM_PASSWORD_ALREADY_EXISTS);
+        }
+
+        // 새 비밀번호 설정
+        room.updatePassword(newPassword);
+
+        log.info("방 비밀번호 설정 완료 - RoomId: {}, UserId: {}", roomId, userId);
+    }
+
     @Transactional
     public void terminateRoom(Long roomId, Long userId) {
 

src/main/java/com/back/global/exception/ErrorCode.java

@@ -39,6 +39,7 @@ public enum ErrorCode {
     CHAT_DELETE_FAILED(HttpStatus.INTERNAL_SERVER_ERROR, "ROOM_016", "채팅 삭제 중 오류가 발생했습니다."),
     ROOM_PASSWORD_MISMATCH(HttpStatus.BAD_REQUEST, "ROOM_017", "현재 비밀번호가 일치하지 않습니다."),
     NOT_ROOM_HOST(HttpStatus.FORBIDDEN, "ROOM_018", "방장 권한이 필요합니다."),
+    ROOM_PASSWORD_ALREADY_EXISTS(HttpStatus.BAD_REQUEST, "ROOM_019", "이미 비밀번호가 설정되어 있습니다. 비밀번호 변경 API를 사용하세요."),
 
     // ======================== 초대 코드 관련 ========================
     INVALID_INVITE_CODE(HttpStatus.NOT_FOUND, "INVITE_001", "유효하지 않은 초대 코드입니다."),

src/main/java/com/back/global/websocket/controller/WebSocketMessageController.java

@@ -1,7 +1,9 @@
 package com.back.global.websocket.controller;
 
+import com.back.domain.studyroom.service.AvatarService;
 import com.back.global.exception.CustomException;
 import com.back.global.security.user.CustomUserDetails;
+import com.back.global.websocket.service.RoomParticipantService;
 import com.back.global.websocket.service.WebSocketSessionManager;
 import com.back.global.websocket.util.WebSocketAuthHelper;
 import com.back.global.websocket.util.WebSocketErrorHelper;
@@ -25,9 +27,12 @@ public class WebSocketMessageController {
 
     private final WebSocketSessionManager sessionManager;
     private final WebSocketErrorHelper errorHelper;
+    private final RoomParticipantService roomParticipantService;
+    private final AvatarService avatarService;
 
     // WebSocket 방 입장 확인 메시지
-    // 클라이언트가 REST API로 입장 후 WebSocket 세션 동기화 대기를 위해 전송
+    // 클라이언트가 REST API로 입장 후 WebSocket 세션 동기화를 위해 전송
+    // 초대 코드로 입장한 경우 Redis 등록이 안 되어 있으므로 여기서 처리
     @MessageMapping("/rooms/{roomId}/join")
     public void handleWebSocketJoinRoom(@DestinationVariable Long roomId,
                                         @Payload Map<String, Object> payload,
@@ -44,8 +49,23 @@ public void handleWebSocketJoinRoom(@DestinationVariable Long roomId,
         // 활동 시간 업데이트
         sessionManager.updateLastActivity(userId);
 
-        // 실제 방 입장 로직은 REST API에서 이미 처리했으므로
-        // 여기서는 단순히 WebSocket 세션이 준비되었음을 확인하는 용도
+        // Redis에 이미 등록되어 있는지 확인
+        Long currentRoomId = roomParticipantService.getCurrentRoomId(userId);
+
+        if (currentRoomId == null || !currentRoomId.equals(roomId)) {
+            // Redis에 등록되지 않은 경우 (초대 코드 입장 등)
+            // 아바타 로드/생성
+            Long avatarId = avatarService.loadOrCreateAvatar(roomId, userId);
+
+            // Redis에 온라인 등록
+            roomParticipantService.enterRoom(userId, roomId, avatarId);
+
+            log.info("📥 [WebSocket] Redis 등록 완료 - roomId: {}, userId: {}, avatarId: {}", 
+                    roomId, userId, avatarId);
+        } else {
+            log.info("📥 [WebSocket] 이미 Redis에 등록된 사용자 - roomId: {}, userId: {}", 
+                    roomId, userId);
+        }
     }
 
     // Heartbeat 처리