docs(dm): WebSocket 전환 계획을 기록한다

2026-06-18 17:03:07 +09:00
parent fa4e41589b
commit 0e03a1a14a
2 changed files with 488 additions and 122 deletions
--- a/docs/20260610_DM_채팅화면/plan-task.md
+++ b/docs/20260610_DM_채팅화면/plan-task.md
@@ -1,7 +1,7 @@
 # DM 채팅화면 구현 계획/TASK

 ## 1. 목표
-`docs/20260610_DM_채팅화면/prd.md`를 기준으로 신규 DM 채팅방 상세 화면을 v2 패키지 하위에 구현한다. 기존 AI `ChatRoomActivity`는 직접 수정하지 않고, DM 전용 Activity, ViewModel, Repository, DTO, SSE 클라이언트, 메시지 UI 모델을 최소 범위로 추가한다.
+`docs/20260610_DM_채팅화면/prd.md`를 기준으로 신규 DM 채팅방 상세 화면을 v2 패키지 하위에 구현한다. 기존 AI `ChatRoomActivity`는 직접 수정하지 않고, DM 전용 Activity, ViewModel, Repository, DTO, WebSocket 클라이언트, 메시지 UI 모델을 최소 범위로 추가한다.

 ## 2. 구현 결정 사항
 - 신규 화면은 `kr.co.vividnext.sodalive.v2.main.chat.dm` 하위에 둔다.
@@ -11,39 +11,49 @@
  - `roomId <= 0 && creatorId > 0`: `CreateOrGetRoom` 호출 후 반환된 `roomId`로 `OpenRoom`을 호출한다.
  - 둘 다 유효하지 않으면 Activity를 종료한다.
 - REST API는 기존 v2 채팅 탭과 동일하게 Retrofit + RxJava3 + `ApiResponse<T>` 패턴을 사용한다.
- SSE는 현재 저장소에 재사용 패턴이 없으므로 별도 라이브러리 추가 없이 기존 `OkHttpClient`의 `newCall()`과 streaming `ResponseBody`를 사용하는 `DmChatEventClient`를 추가한다.
- SSE 연결/해제는 Activity foreground 범위에서 처리한다.
-  - `onStart`: `OpenRoom` 완료 후 연결 가능 상태면 SSE 연결을 시작한다.
-  - `onStop`: SSE call을 cancel하고 `DisconnectRealtime` API를 비동기로 호출한다.
-  - `onDestroy`: listener 참조와 disposable을 정리한다.
- `Last-Event-ID` replay는 기대하지 않고, SSE 재연결 후 `GetMessages`로 최신 누락 가능 메시지를 동기화한다.
- 네트워크 오류로 SSE가 실패하면 화면이 foreground에 있고 채팅방이 활성 상태인 경우 서버 `reconnectTime=3000`ms 기준으로 재연결을 시도한다.
-  - 재연결 성공 후 `Last-Event-ID` replay는 기대하지 않고 `GetMessages`로 누락 가능 메시지를 보정한다.
+- Phase 1~8은 기존 SSE 기반 구현 이력으로 보존한다. WebSocket 전환은 Phase 9부터 기존 SSE 구현을 교체하는 후속 범위로 진행한다.
+- WebSocket은 `OkHttpClient.newWebSocket()` 기반 전용 `DmChatSocketClient`를 추가하고, 기존 `DmChatEventClient`/SSE parser는 WebSocket 전환 완료 후 사용하지 않는다.
+- WebSocket 연결/해제는 Activity foreground 범위와 로그아웃 흐름에서 처리한다.
+  - `onStart`: `OpenRoom` 완료 후 연결 가능 상태면 WebSocket 연결을 시작하고 `JOIN_ROOM`을 보낸다.
+  - `JOINED`: 실시간 수신 가능 상태로 판단한다.
+  - `onStop`/화면 이탈/앱 background/로그아웃: `LEAVE_ROOM` 전송 후 socket close를 수행한다.
+  - `onDestroy`/`onCleared`: listener 참조, heartbeat, reconnect 예약, socket을 정리한다.
+- WebSocket 재연결 후에는 `JOIN_ROOM`을 다시 보내고, 필요하면 `GetMessages`로 최신 누락 가능 메시지를 동기화한다.
+- 네트워크 오류로 WebSocket이 실패하면 화면이 foreground에 있고 채팅방이 활성 상태인 경우에만 재연결을 시도한다.
+  - 재연결 성공 후 `JOIN_ROOM`을 다시 보내고 `GetMessages`로 누락 가능 메시지를 보정한다.
  - 화면 이탈 또는 background 전환 시 예약된 재연결 시도는 취소한다.
 - `VOICE` 메시지는 DTO에 보존하되 이번 UI 목록에는 표시하지 않는다.
 - 전송은 낙관적 UI를 적용한다.
  - 전송 직후 local pending 메시지를 추가한다.
-  - 성공 시 서버 응답 메시지로 교체한다.
-  - 실패 시 실패 상태와 재시도 버튼을 표시한다.
- Phase 3 ViewModel 전송 정책은 단일 `isSending` guard로 한 번에 하나의 전송만 허용한다.
-  - 이번 범위에서는 “전송 중 중복 요청 방지” 요구사항을 우선 충족한다.
-  - 서로 다른 메시지의 연속 병렬 전송 허용 여부는 Phase 5 Activity/input UX 연결 시 필요하면 재검토한다.
+  - WebSocket `SEND_ACK` 수신 시 `requestId`로 pending 메시지를 찾아 서버 `messageId`, `createdAt`, 프로필 정보로 확정한다.
+  - `ERROR` 또는 timeout 시 실패 상태와 재시도 버튼을 표시한다.
+- Phase 9 이후 텍스트 전송 정책은 `requestId` 단위 pending map으로 관리한다.
+  - 서로 다른 텍스트 메시지는 각각의 `requestId`로 독립 pending 상태를 가질 수 있다.
+  - 같은 UI item 재시도는 새 `requestId`를 발급하되 기존 local item을 유지한다.
 - Phase 3 ViewModel의 pagination/reconnect 동기화 실패는 화면 종료나 Error 화면 전환 없이 기존 메시지 상태를 유지하고 내부 loading 상태만 복구한다.
  - 사용자 노출 toast/retry UI는 Phase 5 Activity 연결 시 필요하면 별도 처리한다.

 ## 3. 파일 구조
 - Create: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/chat/dm/DmChatRoomActivity.kt`
-  - DM 채팅방 화면, intent 진입, RecyclerView/input/header/lifecycle/SSE 연결 제어를 담당한다.
+  - DM 채팅방 화면, intent 진입, RecyclerView/input/header/lifecycle/WebSocket 연결 제어를 담당한다.
 - Create: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/chat/dm/DmChatRoomViewModel.kt`
-  - 방 생성/열기, pagination, 메시지 전송, SSE 이벤트 반영, disconnect 상태를 관리한다.
+  - 방 생성/열기, pagination, WebSocket 메시지 전송/수신, leave/close 상태를 관리한다.
 - Create: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/chat/dm/data/DmChatApi.kt`
  - `user-creator-chat` REST endpoint를 정의한다.
 - Create: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/chat/dm/data/DmChatModels.kt`
  - REST DTO와 서버 메시지 DTO를 정의한다.
 - Create: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/chat/dm/data/DmChatRepository.kt`
-  - API 호출 래핑, token 전달, SSE 클라이언트 위임을 담당한다.
+  - REST API 호출 래핑, token 전달, WebSocket 클라이언트 위임을 담당한다.
 - Create: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/chat/dm/data/DmChatEventClient.kt`
-  - OkHttp 기반 SSE 연결, `connected`/`message` 이벤트 파싱, cancel 처리를 담당한다.
+  - 기존 SSE 연결 구현이다. Phase 9 이후 WebSocket 전환 완료 시 신규 경로에서 사용하지 않으며 제거 또는 미사용 상태로 둔다.
+- Create: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/chat/dm/data/DmChatSocketClient.kt`
+  - OkHttp WebSocket 연결, handshake header, `JOIN_ROOM`/`LEAVE_ROOM`/`SEND_TEXT`/`PING` 송신, 수신 callback, close 처리를 담당한다.
+- Create: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/chat/dm/data/DmChatSocketModels.kt`
+  - WebSocket envelope, payload, `requestId` 기반 `SEND_ACK`, `ERROR`, `MESSAGE`, `PONG` 모델을 정의한다.
+- Create: `app/src/test/java/kr/co/vividnext/sodalive/v2/main/chat/dm/DmChatSocketClientTest.kt`
+  - WebSocket handshake header, endpoint, send/receive envelope, close 동작을 검증한다.
+- Create: `app/src/test/java/kr/co/vividnext/sodalive/v2/main/chat/dm/DmChatSocketParserTest.kt`
+  - `JOINED`, `MESSAGE`, `SEND_ACK`, `ERROR`, `PONG`, 알 수 없는 type 파싱을 검증한다.
 - Create: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/chat/dm/model/DmChatUiModels.kt`
  - UI 메시지 모델, 전송 상태, 화면 상태를 정의한다.
 - Create: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/chat/dm/model/DmChatMappers.kt`
@@ -59,9 +69,15 @@
 - Modify: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/chat/ChatMainFragment.kt`
  - DM item 클릭 시 `DmChatRoomActivity.newIntentByRoomId()`로 이동한다.
 - Modify: `app/src/main/java/kr/co/vividnext/sodalive/di/AppDI.kt`
-  - `DmChatApi`, `DmChatRepository`, `DmChatEventClient`, `DmChatRoomViewModel` DI를 추가한다.
+  - `DmChatApi`, `DmChatRepository`, `DmChatSocketClient`, `DmChatRoomViewModel` DI를 등록한다.
 - Modify: `app/src/main/AndroidManifest.xml`
  - `DmChatRoomActivity`를 등록한다.
+- Modify: `app/src/main/java/kr/co/vividnext/sodalive/fcm/SodaFirebaseMessagingService.kt`
+  - 푸시 payload의 `chat_type`, `room_id`를 `DeepLinkActivity`로 전달한다.
+- Modify: `app/src/main/java/kr/co/vividnext/sodalive/main/DeepLinkActivity.kt`
+  - `chat_type == "USER_CREATOR"`와 `room_id` 기준으로 DM 채팅방 진입 intent를 만든다.
+- Modify: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/MainV2Activity.kt`
+  - 로그인/메인 진입 후 전달된 DM 푸시 extras를 DM 채팅방 진입으로 연결한다.
 - Modify: `docs/agent-guides/build-test-style.md`
  - 신규 DM 채팅 테스트 단일 실행 예시를 추가한다.
 - Test Create: `app/src/test/java/kr/co/vividnext/sodalive/v2/main/chat/dm/DmChatMapperTest.kt`
@@ -75,9 +91,11 @@
 - OpenRoom 메시지는 오래된 순서에서 최신 순서로 표시된다.
 - 메시지 병합은 `messageId` 기준으로 중복을 제거한다.
 - 상단 스크롤 시 `hasMore=true`, `nextCursor != null`, `isLoading=false` 조건에서만 과거 메시지를 조회한다.
- 텍스트 전송은 blank 입력을 무시하고, 전송 중 중복 요청을 막는다.
- 전송 실패 메시지는 재시도 버튼을 표시하고, 재시도 성공 시 정상 메시지로 교체된다.
- 화면 stop/destroy 흐름에서 SSE cancel과 disconnect API 호출이 화면 종료를 막지 않는다.
+- 텍스트 전송은 blank 입력을 무시하고, WebSocket `SEND_TEXT`와 `requestId` pending 매칭을 사용한다.
+- 전송 실패 메시지는 `ERROR` 또는 timeout 기준으로 실패 상태와 재시도 버튼을 표시하고, 재시도 성공 시 정상 메시지로 교체된다.
+- 화면 stop/destroy/background/logout 흐름에서 `LEAVE_ROOM` 전송과 socket close가 화면 종료를 막지 않는다.
+- 제거된 `GET /api/v2/user-creator-chat/rooms/{roomId}/events`, `POST /api/v2/user-creator-chat/rooms/{roomId}/events/disconnect`, 텍스트 전송용 `POST /api/v2/user-creator-chat/rooms/{roomId}/messages/text`는 신규 텍스트 실시간 송수신 경로에서 호출하지 않는다.
+- 음성 메시지는 기존 multipart REST API 경로를 유지한다.
 - DM 화면에는 `character_type_badge`, `ll_can_badge`, `iv_more`, `notice_container`가 없다.
 - `ChatRoomActivity` 기존 동작은 변경하지 않는다.

@@ -440,8 +458,8 @@
    - 메시지 목록은 header 바로 아래에서 시작한다.
    - blank 입력은 전송되지 않는다.
    - 텍스트 전송 실패 시 실패 상태와 재시도 버튼이 표시된다.
-    - 화면 이탈 또는 앱 background 전환 시 disconnect API가 호출된다.
-    - SSE 연결 실패가 앱 crash로 이어지지 않는다.
+    - Phase 9~13 WebSocket 전환 후 화면 이탈 또는 앱 background 전환 시 `LEAVE_ROOM` 전송 후 socket close가 호출된다.
+    - Phase 9~13 WebSocket 전환 후 WebSocket 연결 실패가 앱 crash로 이어지지 않는다.

 ### Phase 8: 크리에이터 채널 DM 진입 crash 수정

@@ -497,6 +515,303 @@
    - header 상대 정보와 초기 메시지 목록이 표시된다.
    - 채팅 탭의 기존 `roomId` 기반 DM 진입은 기존처럼 동작한다.

+### Phase 9: WebSocket 계약/클라이언트 기반 추가
+
+- [ ] **Task 9.1: WebSocket envelope와 payload 모델 정의**
+  - Files:
+    - Create: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/chat/dm/data/DmChatSocketModels.kt`
+    - Create: `app/src/test/java/kr/co/vividnext/sodalive/v2/main/chat/dm/DmChatSocketParserTest.kt`
+  - 작업:
+    - WebSocket 공통 envelope는 `type`과 `payload`를 분리해 파싱할 수 있게 정의한다.
+    - Client send type은 `JOIN_ROOM`, `LEAVE_ROOM`, `SEND_TEXT`, `PING`을 지원한다.
+    - Server receive type은 `JOINED`, `MESSAGE`, `SEND_ACK`, `ERROR`, `PONG`을 지원한다.
+    - `JOIN_ROOM`/`LEAVE_ROOM` payload는 현재 `roomId`를 포함한다.
+    - `SEND_TEXT` payload는 `roomId`, `requestId`, `textMessage`를 포함한다.
+    - `SEND_ACK` payload는 `requestId`와 서버 확정 메시지(`DmChatMessageResponse`)를 포함한다.
+    - `MESSAGE` payload는 서버 메시지(`DmChatMessageResponse`)를 포함한다.
+    - `ERROR` payload는 `requestId`가 있을 수도 있고 없을 수도 있으므로 nullable로 모델링하고, message/code 필드를 보존한다.
+    - 서버의 정확한 JSON field name은 백엔드 계약과 대조해 확정하되, Android 모델은 서버 field name을 `@SerializedName`으로 보존한다.
+  - 검증:
+    - Run: `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.main.chat.dm.DmChatSocketParserTest" --max-workers=1`
+    - Expected: `JOINED`, `MESSAGE`, `SEND_ACK`, `ERROR`, `PONG`, 알 수 없는 type, 잘못된 JSON 파싱 테스트가 PASS.
+
+- [ ] **Task 9.2: OkHttp WebSocket 클라이언트 추가**
+  - Files:
+    - Create: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/chat/dm/data/DmChatSocketClient.kt`
+    - Create: `app/src/test/java/kr/co/vividnext/sodalive/v2/main/chat/dm/DmChatSocketClientTest.kt`
+  - 작업:
+    - `DmChatSocketClient`는 `OkHttpClient.newWebSocket()`으로 `${BuildConfig.BASE_URL}`의 scheme을 WebSocket scheme으로 변환해 `/ws/v2/user-creator-chat`에 연결한다.
+      - `https://`는 `wss://`, `http://`는 `ws://`로 변환한다.
+    - handshake request에 `Authorization: Bearer <accessToken>` header를 추가한다.
+    - `connect(token, listener)`는 socket 연결만 수행하고, 방 참여는 ViewModel이 `sendJoinRoom(roomId)`로 명시 호출한다.
+    - `sendJoinRoom(roomId)`, `sendLeaveRoom(roomId)`, `sendText(roomId, requestId, textMessage)`, `sendPing()`를 제공한다.
+    - `close()`는 진행 중 socket을 close하고 listener 참조를 해제한다.
+    - `onMessage`는 `DmChatSocketModels` parser로 envelope를 파싱해 listener callback으로 전달한다.
+    - 알 수 없는 type 또는 파싱 실패는 앱 crash 없이 listener failure 또는 ignored event로 처리한다.
+  - 검증:
+    - Run: `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.main.chat.dm.DmChatSocketClientTest" --max-workers=1`
+    - Expected: endpoint URL 변환, Authorization header, `JOIN_ROOM`/`LEAVE_ROOM`/`SEND_TEXT`/`PING` JSON 송신, 수신 callback, close 정리 테스트가 PASS.
+
+- [ ] **Task 9.3: Repository와 DI를 WebSocket 클라이언트 기준으로 전환**
+  - Files:
+    - Modify: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/chat/dm/data/DmChatRepository.kt`
+    - Modify: `app/src/main/java/kr/co/vividnext/sodalive/di/AppDI.kt`
+    - Modify: `app/src/test/java/kr/co/vividnext/sodalive/v2/main/chat/dm/DmChatRepositoryTest.kt`
+  - 작업:
+    - `DmChatRepository`는 `connectRealtime()`/`cancelRealtime()` seam을 WebSocket 클라이언트 위임으로 교체하거나 `connectSocket()`/`closeSocket()`처럼 의미가 분명한 이름으로 변경한다.
+    - REST `createOrGetRoom`, `openRoom`, `getMessages`는 유지한다.
+    - 텍스트 전송용 REST `sendTextMessage()`와 `disconnectRealtime()` repository method는 신규 전송/해제 경로에서 사용하지 않도록 제거하거나 deprecated 없이 삭제한다.
+    - `AppDI.kt`는 `DmChatEventClient` 대신 `DmChatSocketClient`를 등록한다.
+    - `Authorization` header 생성은 기존 `bearer(token)` helper를 재사용해 REST와 WebSocket의 bearer 문자열이 일관되도록 한다.
+  - 검증:
+    - Run: `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.main.chat.dm.DmChatRepositoryTest" --max-workers=1`
+    - Expected: REST create/open/messages는 기존처럼 동작하고, WebSocket connect/send/close 위임과 bearer header 생성 테스트가 PASS.
+
+- [ ] **Task 9.4: 제거 endpoint API 정의 삭제**
+  - Files:
+    - Modify: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/chat/dm/data/DmChatApi.kt`
+    - Modify: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/chat/dm/data/DmChatModels.kt`
+    - Modify: `app/src/test/java/kr/co/vividnext/sodalive/v2/main/chat/dm/DmChatRepositoryTest.kt`
+  - 작업:
+    - `DmChatApi.sendDmTextMessage()` endpoint 정의를 삭제한다.
+    - `DmChatApi.disconnectRealtime()` endpoint 정의를 삭제한다.
+    - `SendDmTextMessageRequest`, `SendDmChatMessageResponse` 모델은 REST 텍스트 전송 전용이면 삭제한다.
+    - 음성 메시지 multipart REST API가 현재 DM 채팅 화면에 필요하면 별도 `sendDmVoiceMessage()`로 명시하고, 텍스트 전송 경로와 섞지 않는다.
+  - 검증:
+    - Run: `rg "messages/text|events/disconnect|SendDmTextMessageRequest|SendDmChatMessageResponse|disconnectRealtime\\(" app/src/main/java/kr/co/vividnext/sodalive/v2/main/chat/dm app/src/test/java/kr/co/vividnext/sodalive/v2/main/chat/dm`
+    - Expected: WebSocket 전환 후 유지가 필요한 과거 검증 로그를 제외하고 main/test 코드의 신규 경로에서 결과 없음.
+
+### Phase 10: ViewModel WebSocket 세션/수신/전송 전환
+
+- [ ] **Task 10.1: OpenRoom 성공 후 JOIN_ROOM 흐름으로 연결 기준 변경**
+  - Files:
+    - Modify: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/chat/dm/DmChatRoomViewModel.kt`
+    - Modify: `app/src/test/java/kr/co/vividnext/sodalive/v2/main/chat/dm/DmChatRoomViewModelTest.kt`
+  - 작업:
+    - `OpenRoom` 성공 전에는 WebSocket 연결을 시작하지 않는다.
+    - `roomOpenedEventLiveData` 또는 동등한 단발 이벤트는 Activity가 WebSocket 연결 시작을 트리거하는 용도로 유지한다.
+    - 기존 SSE `connected` callback 기준 상태 갱신을 제거하고, WebSocket `JOINED` 수신 시점에만 실시간 수신 가능 상태로 판단한다.
+    - 같은 `roomId`로 이미 연결 중이면 중복 socket 연결과 중복 `JOIN_ROOM` 전송을 막는다.
+  - 검증:
+    - Run: `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.main.chat.dm.DmChatRoomViewModelTest" --max-workers=1`
+    - Expected: OpenRoom 전 미연결, OpenRoom 후 connect + `JOIN_ROOM`, `JOINED` 후 connected 상태, 중복 connect 방지 테스트가 PASS.
+
+- [ ] **Task 10.2: MESSAGE 수신 반영으로 교체**
+  - Files:
+    - Modify: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/chat/dm/DmChatRoomViewModel.kt`
+    - Modify: `app/src/test/java/kr/co/vividnext/sodalive/v2/main/chat/dm/DmChatRoomViewModelTest.kt`
+  - 작업:
+    - 기존 SSE `onMessage()` callback 연결을 WebSocket `MESSAGE` event callback으로 교체한다.
+    - `MESSAGE` payload의 `DmChatMessageResponse`를 기존 mapper로 UI item에 변환한다.
+    - 현재 채팅방 메시지는 `messageId` 기준 중복 제거 후 append/merge한다.
+    - 현재 room이 아닌 메시지가 payload로 구분 가능하면 현재 목록에 반영하지 않는다.
+    - 잘못된 payload 또는 알 수 없는 type은 앱 crash 없이 무시한다.
+  - 검증:
+    - Run: `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.main.chat.dm.DmChatRoomViewModelTest" --max-workers=1`
+    - Expected: `MESSAGE` append, 중복 `messageId` 제거, 잘못된 payload 무시 테스트가 PASS.
+
+- [ ] **Task 10.3: SEND_TEXT/requestId pending 전송으로 교체**
+  - Files:
+    - Modify: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/chat/dm/DmChatRoomViewModel.kt`
+    - Modify: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/chat/dm/model/DmChatUiModels.kt`
+    - Modify: `app/src/test/java/kr/co/vividnext/sodalive/v2/main/chat/dm/DmChatRoomViewModelTest.kt`
+  - 작업:
+    - `sendText(text)`는 trim 후 blank면 종료한다.
+    - 전송 시 `requestId`를 생성하고 local pending item에 보존한다.
+    - REST `repository.sendTextMessage()` 호출을 제거하고 WebSocket `SEND_TEXT`를 전송한다.
+    - `SEND_ACK` 수신 시 `requestId`로 pending item을 찾아 서버 `messageId`, `createdAt`, `senderNickname`, `senderProfileImageUrl` 기준으로 확정한다.
+    - `ERROR` 또는 timeout 시 해당 pending item을 `FAILED`로 전환한다.
+    - `retry(localId)`는 기존 failed item을 유지하고 새 `requestId`를 발급해 `SEND_TEXT`를 다시 전송한다.
+    - 같은 `requestId`의 `SEND_ACK`가 중복 수신되면 첫 번째 확정 결과만 반영한다.
+  - 검증:
+    - Run: `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.main.chat.dm.DmChatRoomViewModelTest" --max-workers=1`
+    - Expected: blank 무시, pending 추가, `SEND_TEXT` 송신, `SEND_ACK` requestId 매칭, `ERROR` 실패, timeout 실패, retry 새 requestId, 중복 ack 무시 테스트가 PASS.
+
+- [ ] **Task 10.4: SEND_ACK보다 MESSAGE가 먼저 도착하는 race 처리**
+  - Files:
+    - Modify: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/chat/dm/DmChatRoomViewModel.kt`
+    - Modify: `app/src/test/java/kr/co/vividnext/sodalive/v2/main/chat/dm/DmChatRoomViewModelTest.kt`
+  - 작업:
+    - pending 텍스트와 동일한 서버 메시지가 `SEND_ACK`보다 먼저 `MESSAGE`로 도착할 수 있는 케이스를 테스트로 고정한다.
+    - `MESSAGE` payload에 `requestId`가 포함되면 requestId 기준으로 pending item을 확정한다.
+    - `MESSAGE` payload에 `requestId`가 없으면 `messageId` 중복 제거를 우선 적용하고, 이후 `SEND_ACK` 도착 시 같은 `messageId`가 중복되지 않게 병합한다.
+    - timeout으로 실패 처리된 뒤 늦은 `SEND_ACK`가 도착하면 같은 local item이 아직 존재하는 경우 정상 메시지로 복구한다.
+  - 검증:
+    - Run: `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.main.chat.dm.DmChatRoomViewModelTest" --max-workers=1`
+    - Expected: MESSAGE 선도착, ACK 후도착, timeout 후 ACK 복구, 중복 `messageId` 방지 테스트가 PASS.
+
+### Phase 11: Lifecycle, reconnect, heartbeat, token 갱신 처리
+
+- [ ] **Task 11.1: LEAVE_ROOM 후 socket close로 lifecycle 해제 전환**
+  - Files:
+    - Modify: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/chat/dm/DmChatRoomActivity.kt`
+    - Modify: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/chat/dm/DmChatRoomViewModel.kt`
+    - Modify: `app/src/test/java/kr/co/vividnext/sodalive/v2/main/chat/dm/DmChatRoomActivitySourceTest.kt`
+    - Modify: `app/src/test/java/kr/co/vividnext/sodalive/v2/main/chat/dm/DmChatRoomViewModelTest.kt`
+  - 작업:
+    - `onStop`/화면 이탈 시 기존 `disconnectRealtime()` REST 호출 대신 `LEAVE_ROOM` 전송 후 socket close를 수행한다.
+    - 앱 background 진입과 로그아웃 흐름에서 같은 leave/close API를 호출할 수 있도록 ViewModel method를 분리한다.
+    - 이미 leave/close 중이면 중복 `LEAVE_ROOM` 전송과 중복 close를 만들지 않는다.
+    - close 실패 또는 네트워크 단절은 화면 종료를 막지 않는다.
+  - 검증:
+    - Run: `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.main.chat.dm.DmChatRoomActivitySourceTest" --tests "kr.co.vividnext.sodalive.v2.main.chat.dm.DmChatRoomViewModelTest" --max-workers=1`
+    - Expected: lifecycle stop에서 `LEAVE_ROOM` + close, 중복 방지, REST disconnect 미호출 테스트가 PASS.
+
+- [ ] **Task 11.2: WebSocket reconnect 정책 구현**
+  - Files:
+    - Modify: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/chat/dm/DmChatRoomViewModel.kt`
+    - Modify: `app/src/test/java/kr/co/vividnext/sodalive/v2/main/chat/dm/DmChatRoomViewModelTest.kt`
+  - 작업:
+    - 네트워크 오류 또는 비정상 close가 발생하면 현재 채팅방 화면에 남아 있는 동안에만 재연결을 예약한다.
+    - 재연결 성공 후 `JOIN_ROOM`을 다시 보낸다.
+    - `JOINED` 수신 후 필요하면 `GetMessages(cursor = null, limit = 20)`로 최신 누락 메시지를 동기화한다.
+    - 화면 이탈/background/logout 이후 예약된 reconnect는 실행하지 않는다.
+    - backoff 간격과 최대 재시도 횟수는 PRD Open Questions에 남긴 상태이므로, 구현 전 서버 권장값이 없으면 기존 3초 반복 재시도 정책을 WebSocket에도 우선 적용한다.
+  - 검증:
+    - Run: `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.main.chat.dm.DmChatRoomViewModelTest" --max-workers=1`
+    - Expected: 화면 내부 오류 재연결, 재연결 후 `JOIN_ROOM`, 최신 메시지 동기화, 화면 밖 reconnect 취소 테스트가 PASS.
+
+- [ ] **Task 11.3: PING/PONG heartbeat 구현**
+  - Files:
+    - Modify: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/chat/dm/DmChatRoomViewModel.kt`
+    - Modify: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/chat/dm/data/DmChatSocketClient.kt`
+    - Modify: `app/src/test/java/kr/co/vividnext/sodalive/v2/main/chat/dm/DmChatRoomViewModelTest.kt`
+    - Modify: `app/src/test/java/kr/co/vividnext/sodalive/v2/main/chat/dm/DmChatSocketClientTest.kt`
+  - 작업:
+    - `JOINED` 이후 heartbeat timer를 시작한다.
+    - 주기적으로 `PING`을 전송하고 `PONG` 수신 시 마지막 heartbeat 시간을 갱신한다.
+    - `PONG` timeout이면 연결 상태를 disconnected로 바꾸고 WebSocket을 close한 뒤 화면 내부 조건에서 reconnect를 예약한다.
+    - leave/close/onCleared 시 heartbeat timer를 취소한다.
+    - 서버 권장값이 없으면 heartbeat 주기와 timeout 값은 상수로 분리하고 구현 계획 검증 기록에 남긴다.
+  - 검증:
+    - Run: `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.main.chat.dm.DmChatRoomViewModelTest" --tests "kr.co.vividnext.sodalive.v2.main.chat.dm.DmChatSocketClientTest" --max-workers=1`
+    - Expected: `PING` 주기 송신, `PONG` 수신 상태 유지, timeout reconnect, leave 시 timer 취소 테스트가 PASS.
+
+- [ ] **Task 11.4: access token refresh 시 WebSocket 재연결**
+  - Files:
+    - Modify: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/chat/dm/DmChatRoomViewModel.kt`
+    - Modify: `app/src/test/java/kr/co/vividnext/sodalive/v2/main/chat/dm/DmChatRoomViewModelTest.kt`
+  - 작업:
+    - token provider가 이전 handshake token과 다른 token을 반환하면 기존 WebSocket을 close한다.
+    - 새 token으로 WebSocket handshake를 다시 수행한다.
+    - 재연결 후 현재 `roomId`로 `JOIN_ROOM`을 다시 보낸다.
+    - token 갱신 중 화면이 종료되면 reconnect를 진행하지 않는다.
+  - 검증:
+    - Run: `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.main.chat.dm.DmChatRoomViewModelTest" --max-workers=1`
+    - Expected: token 변경 감지, 기존 socket close, 새 Authorization header 연결, `JOIN_ROOM` 재전송, 화면 종료 시 중단 테스트가 PASS.
+
+### Phase 12: 푸시 진입과 제거 endpoint 회귀 검증
+
+- [ ] **Task 12.1: FCM payload에 chat_type 전달 추가**
+  - Files:
+    - Modify: `app/src/main/java/kr/co/vividnext/sodalive/fcm/SodaFirebaseMessagingService.kt`
+    - Test: `app/src/test/java/kr/co/vividnext/sodalive/fcm/SodaFirebaseMessagingServiceSourceTest.kt`
+  - 작업:
+    - `sendNotification()`에서 `messageData["chat_type"]`이 있으면 `Constants.EXTRA_DATA` bundle에 `chat_type`을 보존한다.
+    - 기존 `room_id`, `message_id`, `deep_link_value` 전달은 유지한다.
+    - deep link URL이 있는 경우에도 `chat_type`/`room_id`가 필요한지 서버 payload 정책을 확인하고, URL 우선 정책을 유지한다면 이 동작을 테스트에 명시한다.
+  - 검증:
+    - Run: `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.fcm.SodaFirebaseMessagingServiceSourceTest" --max-workers=1`
+    - Expected: `chat_type`과 `room_id`가 notification intent extras에 포함되는 source test가 PASS.
+
+- [ ] **Task 12.2: USER_CREATOR 푸시를 DM 채팅방으로 라우팅**
+  - Files:
+    - Modify: `app/src/main/java/kr/co/vividnext/sodalive/main/DeepLinkActivity.kt`
+    - Modify: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/MainV2Activity.kt`
+    - Test: `app/src/test/java/kr/co/vividnext/sodalive/main/DeepLinkActivitySourceTest.kt`
+    - Test: `app/src/test/java/kr/co/vividnext/sodalive/v2/main/MainV2ActivitySourceTest.kt`
+  - 작업:
+    - `chat_type == "USER_CREATOR"`이고 `room_id`가 Long으로 변환 가능하면 `DmChatRoomActivity.newIntentByRoomId(context, roomId)`로 이동한다.
+    - 푸시로 진입한 채팅방도 일반 진입과 동일하게 `OpenRoom` 후 WebSocket 연결/`JOIN_ROOM`을 수행한다.
+    - `room_id`가 없거나 잘못된 경우 DM 채팅방을 열지 않고 기존 fallback 흐름을 따른다.
+    - 기존 live/content/message deep link 처리는 변경하지 않는다.
+  - 검증:
+    - Run: `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.main.DeepLinkActivitySourceTest" --tests "kr.co.vividnext.sodalive.v2.main.MainV2ActivitySourceTest" --max-workers=1`
+    - Expected: USER_CREATOR push routing, invalid room fallback, 기존 deep link 유지 테스트가 PASS.
+
+- [ ] **Task 12.3: 제거 endpoint 호출 회귀 방지 테스트 추가**
+  - Files:
+    - Modify: `app/src/test/java/kr/co/vividnext/sodalive/v2/main/chat/dm/DmChatRoomViewModelTest.kt`
+    - Modify: `app/src/test/java/kr/co/vividnext/sodalive/v2/main/chat/dm/DmChatRepositoryTest.kt`
+    - Create: `app/src/test/java/kr/co/vividnext/sodalive/v2/main/chat/dm/DmChatRemovedEndpointSourceTest.kt`
+  - 작업:
+    - source test로 main DM 채팅 코드에서 아래 문자열이 남아 있지 않은지 확인한다.
+      - `/api/v2/user-creator-chat/rooms/{roomId}/events`
+      - `/api/v2/user-creator-chat/rooms/{roomId}/events/disconnect`
+      - `/api/v2/user-creator-chat/rooms/{roomId}/messages/text`
+      - `Accept: text/event-stream`
+      - `EventSource`
+    - ViewModel 테스트에서 텍스트 전송이 REST repository method를 호출하지 않고 WebSocket `SEND_TEXT`를 호출함을 검증한다.
+    - lifecycle close 테스트에서 REST disconnect method가 호출되지 않고 `LEAVE_ROOM` + close만 호출됨을 검증한다.
+  - 검증:
+    - Run: `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.main.chat.dm.DmChatRemovedEndpointSourceTest" --tests "kr.co.vividnext.sodalive.v2.main.chat.dm.DmChatRoomViewModelTest" --tests "kr.co.vividnext.sodalive.v2.main.chat.dm.DmChatRepositoryTest" --max-workers=1`
+    - Expected: 제거 endpoint 문자열 없음, 텍스트 전송 WebSocket 사용, leave/close WebSocket 사용 테스트가 PASS.
+
+- [ ] **Task 12.4: 음성 메시지 REST 유지 범위 확인**
+  - Files:
+    - Modify: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/chat/dm/data/DmChatApi.kt`
+    - Modify: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/chat/dm/data/DmChatRepository.kt`
+    - Modify: `app/src/test/java/kr/co/vividnext/sodalive/v2/main/chat/dm/DmChatRepositoryTest.kt`
+  - 작업:
+    - 현재 DM 채팅 화면에서 음성 메시지 전송 UI가 없으면 API 추가 없이 DTO의 `voiceMessageUrl` 보존만 유지한다.
+    - DM 음성 전송 UI가 이미 연결되어 있거나 서버 배포 범위에서 필요하면 `POST /api/v2/user-creator-chat/rooms/{roomId}/messages/voice` multipart API만 추가한다.
+    - 음성 전송 경로는 WebSocket `SEND_TEXT`/`SEND_ACK` pending 정책과 섞지 않는다.
+  - 검증:
+    - Run: `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.main.chat.dm.DmChatRepositoryTest" --max-workers=1`
+    - Expected: 음성 API를 추가한 경우 multipart endpoint만 검증되고, 추가하지 않은 경우 기존 DTO 보존 테스트가 PASS.
+
+### Phase 13: WebSocket 전환 최종 검증과 수동 확인
+
+- [ ] **Task 13.1: DM 채팅 WebSocket 단위 테스트 실행**
+  - Files:
+    - Check: `app/src/test/java/kr/co/vividnext/sodalive/v2/main/chat/dm/*Test.kt`
+  - Run:
+    - `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.main.chat.dm.*" --max-workers=1`
+  - Expected:
+    - DM 채팅 WebSocket 전환 관련 단위 테스트가 모두 PASS.
+
+- [ ] **Task 13.2: 푸시/딥링크 라우팅 테스트 실행**
+  - Files:
+    - Check: `app/src/test/java/kr/co/vividnext/sodalive/fcm/*Test.kt`
+    - Check: `app/src/test/java/kr/co/vividnext/sodalive/main/*Test.kt`
+    - Check: `app/src/test/java/kr/co/vividnext/sodalive/v2/main/*Test.kt`
+  - Run:
+    - `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.fcm.*" --tests "kr.co.vividnext.sodalive.main.*" --tests "kr.co.vividnext.sodalive.v2.main.*" --max-workers=1`
+  - Expected:
+    - USER_CREATOR push routing과 기존 deep link 회귀 테스트가 PASS.
+
+- [ ] **Task 13.3: 빌드/스타일/문자열 회귀 확인**
+  - Files:
+    - Check: Gradle project
+    - Check: `app/src/main/java/kr/co/vividnext/sodalive/v2/main/chat/dm`
+  - Run:
+    - `./gradlew :app:compileDebugKotlin --max-workers=1`
+    - `./gradlew :app:ktlintCheck --max-workers=1`
+    - `git diff --check`
+    - `rg "messages/text|events/disconnect|text/event-stream|EventSource" app/src/main/java/kr/co/vividnext/sodalive/v2/main/chat/dm app/src/test/java/kr/co/vividnext/sodalive/v2/main/chat/dm`
+  - Expected:
+    - Kotlin compile, ktlint, whitespace check PASS.
+    - 제거 endpoint 문자열은 삭제 검증 테스트나 과거 이력 문서를 제외한 신규 DM main/test 코드에 남지 않는다.
+
+- [ ] **Task 13.4: WebSocket 전환 수동 확인**
+  - Files:
+    - Check: `DmChatRoomActivity`
+    - Check: `SodaFirebaseMessagingService`
+    - Check: `DeepLinkActivity`
+    - Check: `MainV2Activity`
+  - 확인 항목:
+    - 채팅 탭 DM item 클릭 시 `OpenRoom` 호출 후 WebSocket `/ws/v2/user-creator-chat` 연결과 `JOIN_ROOM` 전송이 발생한다.
+    - `JOINED` 수신 전에는 실시간 수신 상태로 판단하지 않는다.
+    - 상대방 메시지 `MESSAGE` 수신 시 현재 채팅방 메시지 목록에 append된다.
+    - 텍스트 전송 시 REST `/messages/text`가 호출되지 않고 `SEND_TEXT`가 전송된다.
+    - `SEND_ACK` 수신 시 pending 메시지가 서버 `messageId`, `createdAt`, 프로필 정보로 확정된다.
+    - `ERROR` 또는 timeout 시 pending 메시지가 실패 상태와 재시도 버튼을 표시한다.
+    - 화면 이탈, 앱 background, 로그아웃 시 `LEAVE_ROOM` 전송 후 socket close가 발생하고 `/events/disconnect`는 호출되지 않는다.
+    - 네트워크 오류 후 같은 채팅방 화면에 남아 있으면 reconnect 후 `JOIN_ROOM`과 누락 메시지 동기화가 수행된다.
+    - 화면 밖에서는 reconnect가 예약/실행되지 않는다.
+    - heartbeat `PING`/`PONG` timeout 시 연결 상태가 disconnected로 전환된다.
+    - USER_CREATOR push 터치 시 `room_id` 기준 DM 채팅방에 진입하고 일반 진입과 동일하게 `OpenRoom` 후 WebSocket join을 수행한다.
+
 ## 5. 검증 기록
 - 2026-06-10: `docs/20260610_DM_채팅화면/prd.md`를 확인해 DM 채팅방 진입, UI 제거 대상, REST API, SSE 이벤트, pagination, 전송 실패/재시도, lifecycle disconnect 요구사항을 계획에 반영했다.
 - 2026-06-10: `docs/agent-guides/work-plan-docs.md`, `docs/agent-guides/build-test-style.md`, `docs/agent-guides/code-style.md`를 확인해 신규 계획 문서 위치, phase/task 체크박스 형식, 테스트 명령 작성 방식을 확인했다.
@@ -545,3 +860,5 @@
 - 2026-06-11: Phase 6.7에서 `DmChatEventClientTest`의 `getDeclaredField("okHttpClient")` reflection 검증을 제거하고, OkHttp interceptor의 `chain.readTimeoutMillis()`를 실제 SSE 요청 경로에서 관찰하는 동작 기반 검증으로 대체했다. 비동기 요청 실행을 기다리기 위해 `CountDownLatch`를 사용했고, 공유 client의 60초 read timeout은 유지되며 SSE 요청 경로에서는 0ms read timeout이 적용됨을 확인했다.
 - 2026-06-11: Phase 6.6~6.7 검증으로 `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.main.chat.dm.DmChatRoomViewModelTest" --tests "kr.co.vividnext.sodalive.v2.main.chat.dm.DmChatEventClientTest" --max-workers=1`, `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.main.chat.dm.*" --max-workers=1`, `./gradlew :app:compileDebugKotlin --max-workers=1`, `./gradlew :app:ktlintCheck --max-workers=1`, `git diff --check` PASS를 확인했다. 최초 병렬 Gradle 실행에서는 Kotlin incremental cache 동시 접근으로 timeout/daemon fallback이 발생해 순차 실행으로 재검증했다. `ktlintCheck`에서는 기존 `.editorconfig`의 `disabled_rules` deprecation warning이 출력됐지만 실패는 없었다.
 - 2026-06-11: Phase 6.6 리뷰 후속으로 `onCleared()` 테스트를 source 문자열 검증에서 런타임 동작 검증으로 보강했다. 예약된 realtime 재연결이 `onCleared()` 후 실행되지 않는지, background thread에서 예약된 `mainHandler.post { action() }` callback이 `onCleared()` 후 상태를 갱신하지 않는지 확인하도록 수정했다. Phase 6.7 테스트에는 `requestLatch.await(2, TimeUnit.SECONDS)` 반환값 assertion을 추가해 timeout 검증 의도를 명확히 했다. 이후 `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.main.chat.dm.DmChatRoomViewModelTest" --max-workers=1`, `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.main.chat.dm.DmChatRoomViewModelTest" --tests "kr.co.vividnext.sodalive.v2.main.chat.dm.DmChatEventClientTest" --max-workers=1`, `./gradlew :app:testDebugUnitTest --tests "kr.co.vividnext.sodalive.v2.main.chat.dm.*" --max-workers=1`, `./gradlew :app:ktlintCheck --max-workers=1` PASS를 확인했다.
+- 2026-06-18: `docs/20260610_DM_채팅화면/prd.md`의 WebSocket 전환 요구사항을 기준으로 `plan-task.md`를 보강했다. 기존 Phase 1~8의 SSE 구현 이력은 보존하고, Phase 9~13에 WebSocket 모델/클라이언트, Repository/DI 전환, `JOIN_ROOM`/`JOINED`, `MESSAGE`, `SEND_TEXT`/`SEND_ACK`, `LEAVE_ROOM`/close, reconnect/heartbeat/token refresh, USER_CREATOR push routing, 제거 endpoint 회귀 검증, 최종 수동 확인 작업을 추가했다.
+- 2026-06-18: 현재 코드 기준으로 `DmChatApi`의 `/messages/text`, `/events/disconnect`, `DmChatEventClient`, `DmChatRoomViewModel.sendText()` REST 전송, `disconnectRealtime()` SSE 해제 경로가 남아 있음을 확인했고, 이를 Phase 9~13에서 제거/교체할 대상으로 문서화했다. 이번 단계는 계획 문서 수정만 수행했으며 Android 구현, 빌드, 테스트는 실행하지 않았다.