MMX Beta Project Documents 계획, 근거, 댓글이 같은 기록으로 남는 작업 저장소

음성 채팅방 구현 Plan V0.1

  • Task ID: VOICE_CHAT_ROOM_수다방
  • 문서 작성자: 덱스PM
  • 문서 오너: 덱스PM
  • 작성일: 2026-05-22
  • 상태: Draft for owner review

1. 목적

공식 요구사항인 수다방 기능을 Flutter 멀티플랫폼 구조로 구현한다. 1차 목표는 Windows PC에서 다자간 음성채팅과 텍스트 채팅이 함께 동작하는 최소 성공 루프를 만드는 것이다. 이후 동일 구조를 Android로 확장한다. iOS는 베타 범위에서 제외한다.

2. 제품 범위

포함

  • 다자간 음성채팅
  • 텍스트 채팅 병행
  • 테스트 랜딩 화면
  • 닉네임 입력
  • 마이크 상태 테스트
  • 스피커 또는 이어폰 상태 테스트
  • 로비
  • 방 리스트, 참여인원수/제한인원수 표시
  • 비밀번호 방 여부 표시
  • 방 선택 후 입장
  • 방 만들기, 비밀번호 옵션
  • 수다방 내부 참여자 닉네임 리스트
  • 입장/퇴장 감지 메시지
  • 현재 말하는 화자 닉네임 강조 표시
  • Windows PC 우선
  • Android 후속 확장

제외

  • iOS 앱 구현
  • 결제, 친구초대, 푸시 알림
  • 정교한 moderation 도구
  • 대규모 방송형 음성 구조
  • 베타 외 소셜 기능 확장

3. Agora 토큰 서버 설명

Agora SDK는 앱이 음성 채널에 안전하게 접속할 수 있도록 토큰 기반 인증을 권장한다. 클라이언트 앱에 Agora 인증 비밀값을 직접 넣으면 유출 위험이 있으므로, 서버가 짧은 수명의 입장 토큰을 발급하고 Flutter 앱은 그 토큰으로 채널에 입장하는 구조가 기본이다.

현재는 사용자가 Agora 앱 발급 및 시큐리티매니저 등록을 이미 진행했을 가능성이 높다. 따라서 착수 초반에 아래를 먼저 확인한다.

  1. Agora App ID 보유 여부
  2. App Certificate 사용 여부
  3. 현재 백엔드 또는 시큐리티매니저에 토큰 발급 로직이 이미 있는지
  4. 없다면 최소 토큰 발급 엔드포인트를 별도 세부 Task로 생성할지

4. 목표 사용자 흐름

  1. 사용자는 테스트 랜딩 화면에 들어간다.
  2. 닉네임을 입력한다.
  3. 마이크 상태를 점검한다.
  4. 스피커 또는 이어폰 출력 상태를 점검한다.
  5. 로비로 진입한다.
  6. 방 리스트를 보고 공개방 또는 비밀번호방을 선택한다.
  7. 필요 시 새 방을 만들고 비밀번호를 설정한다.
  8. 수다방 내부에서 참여자 목록, 입장/퇴장 메시지, 텍스트 채팅, 음성채팅을 사용한다.
  9. 누가 말하고 있는지 닉네임 강조로 확인한다.

5. 버전별 구축 로드맵

v0.1

목표는 Windows PC에서 수다방 기본 루프를 성립시키는 것이다.

  • 닉네임 입력
  • 마이크/출력 테스트
  • 로비
  • 방 목록
  • 방 생성/입장
  • 비밀번호방
  • 텍스트 채팅
  • Agora 음성채팅
  • active speaker 표시
  • 단일 서버 중심 단순 구조

v0.2

목표는 Android 확장과 연결 안정화다.

  • Android 포팅
  • 권한 처리
  • 오디오 라우팅 보정
  • 재입장/재연결 처리 강화
  • 사용자 오류 메시지 정리
  • 연결 상태 가시성 보강

v0.3

목표는 운영 기능과 실시간 품질 보강이다.

  • 참여자 상태 및 presence 정교화
  • 텍스트 채팅 전달 품질 강화
  • 방 운영 정책 강화
  • moderation 기초 구조 검토
  • 실시간 계층 재검토, 필요 시 WebSocket 정식 도입 판단
  • 필요 시 Redis 도입 검토 시작

v0.5

목표는 베타 운영형 구조를 갖추는 것이다.

  • 다중 방 운영 안정화
  • 상태 관리 구조 표준화
  • Redis 도입 가능 구조
  • 실시간 메시징 계층 정리
  • 관리자 도구 초안
  • 모니터링/로그 체계
  • 정책/제재/기록 기능 확장

6. 최소 성공 기준

Windows 1차 성공 기준

  • Windows Flutter 앱에서 Agora 음성 채널 입장 성공
  • 3인 이상 동시 접속 가능한 다자 음성채팅 확인
  • 텍스트 채팅 동시 동작 확인
  • 로비에서 방 생성, 방 목록 조회, 방 입장 성공
  • 비밀번호 방 진입 검증 성공
  • 발화자 닉네임 강조 표시 성공

Android 2차 성공 기준

  • 동일 기능을 Android에서 재현
  • 권한 처리와 오디오 라우팅 차이 보정

7. 아키텍처 초안

앱 서버 중심의 의미

수다방에서 앱 서버 중심이란, 음성 송수신 자체는 Agora RTC가 맡되 제품 운영과 방 정책은 MMX 앱 서버가 우선 책임지는 구조를 뜻한다.

앱 서버가 우선 맡는 범위는 아래와 같다.

  • 방 목록과 방 메타데이터
  • 방 생성
  • 방 정원과 비밀번호 정책
  • 입장 허용 여부 판정
  • 텍스트 채팅과 시스템 메시지
  • 참여자 메타데이터
  • 향후 moderation, 로그, 정책 처리

이 구조를 택하면 비밀번호방, 로비 정책, 텍스트 채팅 정책, 운영 제어를 제품 요구사항에 맞게 유지하기 쉽다.

Flutter 클라이언트

  • 플랫폼: Windows 우선, Android 후속
  • 주요 화면
    • test landing
    • lobby
    • room
  • 상태관리
    • 사용자 닉네임 상태
    • 현재 방 상태
    • 참여자 리스트 상태
    • 텍스트 채팅 리스트 상태
    • Agora 연결 상태
    • 현재 발화자 상태

실시간 서버 계층

  • 방 메타데이터 관리
  • 방 목록 조회
  • 방 생성
  • 방 비밀번호 검증
  • 텍스트 채팅 메시지 relay 또는 저장
  • 입장/퇴장 이벤트 relay
  • Agora 토큰 발급

Agora 계층

  • 채널 단위 음성 세션
  • 참가자 UID 매핑
  • active speaker 이벤트 또는 audio volume indication 기반 발화자 감지

8. 화면 구성 초안

7.1 Test Landing

  • 닉네임 입력 필드
  • 마이크 테스트 버튼 또는 레벨 표시
  • 스피커/이어폰 테스트 버튼
  • 로비 진입 버튼

7.2 Lobby

  • 방 리스트
  • 인원수/제한인원수 표시
  • 비밀번호방 여부 표시
  • 새 방 만들기 버튼
  • 방 선택 후 입장

7.3 Room

  • 참여자 닉네임 리스트
  • 현재 발화자 강조
  • 입장/퇴장 시스템 메시지
  • 텍스트 채팅 패널
  • 마이크 on/off
  • 나가기

9. 세부 Task 분해

  1. 요구사항 고정 및 와이어프레임 준비
  2. Agora 계정/토큰 서버 상태 점검
  3. Flutter Windows 음성 SDK 연동
  4. 로비/방 메타데이터 API 설계
  5. 텍스트 채팅 실시간 경로 설계
  6. 수다방 Room UI 구현
  7. active speaker 표시 구현
  8. Windows 통합 검증
  9. Android 포팅 및 권한 보정
  10. 결과보고 및 베타 범위 판정

10. WBS

WBS 작업명 내용 선행조건 산출물 대상 버전
1.0 요구사항 확정 수다방 범위, 플랫폼 우선순위, 제외 범위 확정 없음 확정 요구사항 메모 v0.1
1.1 와이어프레임 정의 필요 시 사용자 스케치와 Dex 반응형 HTML 와이어프레임 작성 1.0 화면 와이어프레임 v0.1
2.0 Agora 자산 확인 App ID, Certificate, Security Manager, 토큰 서버 유무 확인 1.0 확인 결과 문서 v0.1
2.1 토큰 서버 Task 판정 기존 발급 구조 재사용 여부 또는 신규 구현 여부 결정 2.0 결정 메모 v0.1
3.0 Windows Flutter 기본 골격 test landing, lobby, room 라우팅 골격 구현 1.0 Flutter 기본 화면 v0.1
3.1 오디오 테스트 화면 닉네임 입력, 마이크/출력 테스트 화면 구현 3.0 landing 기능 v0.1
4.0 로비 서버 연동 방 목록 조회, 방 생성, 비밀번호 검증 API 연동 2.1, 3.0 lobby 기능 v0.1
4.1 텍스트 채팅 경로 메시지 송수신, 입장/퇴장 시스템 메시지 처리 4.0 room 채팅 기능 v0.1
5.0 Agora 음성 연동 채널 입장/퇴장, mute, 오디오 세션 처리 2.1, 3.0 음성 기능 v0.1
5.1 발화자 표시 active speaker 감지, 닉네임 강조/점멸 처리 5.0 speaker indicator v0.1
6.0 Windows 통합 검증 다자간 음성 + 텍스트 + 로비 전체 루프 검증 4.1, 5.1 검증 결과 v0.1
7.0 Android 확장 Android 권한 및 오디오 라우팅 보정 포함 이식 6.0 Android beta build v0.2
7.1 재연결/오류 UX 보강 재입장, 에러 노출, 연결 상태 표시 강화 6.0 안정화 반영 v0.2
8.0 운영 기능 보강 presence, moderation 기초, 채팅 품질 보강 7.1 운영 보강 문서/코드 v0.3
8.1 실시간 계층 재평가 WebSocket, Redis 필요성 재평가 8.0 기술 결정 v0.3
9.0 베타 운영형 구조 다중 방 운영, 관리자 도구, 로그/모니터링 체계 8.1 beta ops baseline v0.5
10.0 결과 정리 결과보고서, 이슈, 후속 범위 정리 각 단계 완료 후 결과 문서 전 단계

11. 기술 쟁점

  1. Windows용 Flutter + Agora 조합 안정성
  2. Android와 Windows 사이 오디오 장치 처리 차이
  3. active speaker 이벤트 신뢰도
  4. 실시간 텍스트 채팅 계층을 Agora RTM으로 할지 자체 서버 소켓으로 할지 결정 필요
  5. 방 비밀번호 검증 및 room metadata source of truth 설계 필요

12. 권장 결정 초안

현재 단계에서는 아래 방향을 우선 검토한다.

  • 음성: Agora RTC
  • 텍스트/로비/방 메타데이터: 앱 서버 주도
  • Windows 우선 완성 후 Android 이식
  • iOS는 베타 범위 제외 유지

이 구조가 좋은 이유는 로비와 방 정책, 비밀번호 검증, 시스템 메시지를 앱 서버가 통제하기 쉽기 때문이다.

13. 검증 기준

  • 3인 이상이 같은 방에 접속 가능
  • 서로 음성이 들림
  • 텍스트 채팅 메시지 순서가 유지됨
  • 입장/퇴장 메시지가 보임
  • 발화자 닉네임 강조가 동작함
  • 비밀번호 방 입장 실패/성공이 구분됨
  • Windows에서 최소 30분 연속 테스트 중 치명 끊김이 없음

14. 서브 Task 문서 목록

  1. SUBTASK_AUTH_TOKEN.md
  2. SUBTASK_LOBBY_ROOM.md
  3. SUBTASK_TEXT_CHAT.md
  4. SUBTASK_RTC_WINDOWS.md
  5. SUBTASK_ACTIVE_SPEAKER.md
  6. SUBTASK_ANDROID_PORT.md

각 문서는 현재 상위 Task의 하위 문서로 관리하며, 작업량과 복잡도가 커지면 독립 Task로 승격하는 것을 전제로 한다.

15. 즉시 다음 액션

  1. Agora 자산 보유 현황 확인
  2. 토큰 서버 재사용 가능 여부 확인
  3. Flutter 프로젝트 구조 내 Windows 대상 앱 경로 확인
  4. 와이어프레임 필요 여부 판정
  5. 세부 구현 담당을 클코/커서 작업 단위로 분배

댓글