STATUS_CHECK_2026-05-24

Task ID: VOICE_CHAT_ROOM_수다방
작성자: 덱스PM
작성일: 2026-05-24
목적: 구현계획서와 현재 코드 상태를 비교하여 실제 상태 기준 점검표를 남긴다.
범위: 문서/코드 비교만 수행, 코드 수정 없음

1. 이번 점검의 기준

이번 점검은 아래 기준으로 작성했다.

구현계획서: implementation_plan.md
API 코드: api/routers/voice_chat.py
Flutter 코드:
- flutter/mmx_player/lib/screens/voice_chat_lobby_screen.dart
- flutter/mmx_player/lib/screens/voice_chat_room_screen.dart
- flutter/mmx_player/lib/services/voice_chat_service.dart
Agora, RTC, Android는 이번 점검에서 보류 표시
점검 범위는 LOBBY_ROOM, TEXT_CHAT 중심

2. 전체 상태 한눈에 보기

항목	계획서 기대 상태	현재 코드 상태	판정
LOBBY_ROOM	방 목록, 방 생성, 비밀번호방, 입장 흐름	기본 구현 존재	부분 구현 완료
TEXT_CHAT	메시지 송수신, 시스템 메시지, room 채팅 패널	기본 구현 존재	부분 구현 완료
AUTH_TOKEN	Agora token 구조 확인 및 발급	이번 점검 범위 제외	보류
RTC_WINDOWS	Windows Agora RTC 연동	현재 미구현	보류
ACTIVE_SPEAKER	현재 화자 강조	현재 미구현	보류
ANDROID_PORT	Android 이식	현재 미구현	보류

3. SUBTASK_LOBBY_ROOM 점검

3.1 확인됨

아래 항목은 코드 기준으로 확인되었다.

방 목록 조회 API 존재
- GET /voice-chat/rooms
방 생성 API 존재
- POST /voice-chat/rooms
방 입장 API 존재
- POST /voice-chat/rooms/{roomCode}/join
방 퇴장 API 존재
- POST /voice-chat/rooms/{roomCode}/leave
Flutter 로비 화면에서 방 목록 로드 구현
Flutter 로비 화면에서 방 생성 다이얼로그 구현
비밀번호 방 입장용 비밀번호 입력 다이얼로그 구현
방 생성 직후 room 화면으로 직접 진입하는 흐름 구현
room 화면 종료 후 로비 목록 재조회 구현

3.2 확인됨, 그러나 계획 대비 부족한 점

참여 인원 수는 표시되지만, 참여자 닉네임 리스트는 room 내부에서 아직 별도 구현되지 않음
방 상태는 active/inactive 개념이 API에는 있으나, 로비 화면에서 상태 배지나 종료 사유 표시가 없음
정원 초과, 비밀번호 오류는 API 에러로 처리되지만, UI에서 사용자 친화적인 분기 문구로 세분화되어 있지는 않음
로비는 수동 새로고침 기반이며, 실시간 목록 동기화는 없음

3.3 추정

호스트가 방을 나가면 방이 종료되도록 설계되어 있으나, 종료 직후 다른 사용자 화면에서 상태 반영 UX가 충분히 정리되지 않았을 가능성이 높다.
동일 사용자가 여러 번 join 요청을 보내는 경우를 막는 별도 참여자 식별 구조는 아직 없을 가능성이 높다.
현재 구조는 단순 current_members 카운트 기반이라, 앱 비정상 종료나 네트워크 이탈 시 인원 수 정합 문제가 생길 가능성이 있다.

3.4 점검표

점검 항목	상태	구분	메모
방 목록 조회	완료	확인됨	로비 진입 시 `_loadRooms()` 호출
방 생성	완료	확인됨	title, description, password, maxMembers 지원
비밀번호 방 입장	완료	확인됨	비밀번호 입력 다이얼로그 존재
방 나가기	완료	확인됨	leave API 호출 존재
목록 자동 동기화	미흡	확인됨	수동 refresh 중심
참여자 메타데이터 정교화	미구현	확인됨	currentMembers 외 상세 참여자 구조 없음
비정상 종료 정합성	점검 필요	추정	current_members 카운트 기반 한계 가능

4. SUBTASK_TEXT_CHAT 점검

4.1 확인됨

아래 항목은 코드 기준으로 확인되었다.

메시지 조회 API 존재
- GET /voice-chat/rooms/{roomCode}/messages
메시지 전송 API 존재
- POST /voice-chat/rooms/{roomCode}/messages
메시지는 created_at asc 기준으로 조회됨
room 생성 시 시스템 메시지 기록
- [{nickname}] 님이 방을 만들었습니다.
room 입장 시 시스템 메시지 기록
- [{nickname}] 님이 입장했습니다.
room 퇴장 시 시스템 메시지 기록
- [{nickname}] 님이 퇴장했습니다.
- 방 종료 시 방이 종료되었습니다. 문구 추가
Flutter room 화면에서 시스템 메시지와 일반 메시지를 구분 렌더링
메시지 전송 후 로컬 리스트에 append 처리
메시지 전송 후 하단 스크롤 이동 시도 존재

4.2 확인됨, 그러나 계획 대비 부족한 점

실시간 push 동기화가 아니라 수동 조회 + 로컬 append 구조다.
새 메시지 자동 polling 또는 websocket 기반 반영이 없다.
메시지 중복 방지, 재전송, reconnect 복구 정책은 코드에 드러나지 않는다.
읽음 상태, 미전송 상태, 실패 재시도 UX는 없다.
system 메시지 author는 system 고정 문자열로만 보인다.

4.3 추정

여러 사용자가 동시에 메시지를 보내는 경우, 현재 로컬 append 중심 구조에서는 다른 사용자의 메시지가 자동 반영되지 않아 room 화면 간 표시 차이가 생길 가능성이 높다.
메시지 전송 직후 새로고침을 병행하면 중복 표시는 없을 수 있으나, 사용자 체감상 지연 또는 순서 혼선이 생길 가능성이 있다.
장시간 채팅 시 pagination 또는 lazy loading 없이 전체 조회 구조라 성능 이슈가 생길 가능성이 있다.

4.4 점검표

점검 항목	상태	구분	메모
메시지 조회	완료	확인됨	created_at asc 정렬
메시지 전송	완료	확인됨	room 활성 상태일 때만 가능
시스템 메시지	완료	확인됨	생성/입장/퇴장 기록 있음
일반 채팅 UI	완료	확인됨	room 화면에서 렌더링
실시간 반영	미흡	확인됨	push 없음, 수동 새로고침 필요
중복/재연결 정책	미확인	확인됨	코드상 명시 없음
대화량 증가 대응	점검 필요	추정	전체 조회 구조

5. 보류 항목 표시

이번 점검에서는 아래 항목을 보류로 둔다.

항목	상태	이유
Agora	보류	owner가 secret 관련 복귀 후 진행 예정
RTC_WINDOWS	보류	실제 RTC 연동은 아직 범위 밖
Android	보류	Windows/Agora 기준선 이후 진행
ACTIVE_SPEAKER	보류	Agora 이벤트 의존

6. 현재 판단 요약

확인됨

LOBBY_ROOM은 기본 루프가 이미 구현되어 있다.
TEXT_CHAT도 기본 루프가 이미 구현되어 있다.
현재 상태는 “문서만 있는 단계”는 아니며, 최소 동작 구조는 존재한다.

추정

현재 구현은 MVP 1차 골격 수준이며, 동기화/정합성/운영 UX는 아직 약하다.
특히 current_members 기반 단순 카운트와 수동 새로고침 구조는 후속 보강이 필요할 가능성이 높다.

7. 후속 점검 시 권장 순서

LOBBY_ROOM 정합성 점검
- 비정상 이탈
- 중복 입장
- 방 종료 반영
TEXT_CHAT 동기화 점검
- 다중 사용자 송수신
- 새로고침 시 메시지 일관성
- 장시간 채팅 시 조회 방식
그 다음 owner 복귀 후
- Agora secret / token
- RTC_WINDOWS

이 문서는 코드 수정 없이 현재 상태를 문서와 대조하여 남긴 점검 기록이다.

댓글