comrelay/화상회의_화면명세.md

화상회의 화면 명세 (단계 1: 인프라 토대)

이 문서는 현재 구현된 화상회의 화면의 기능·구조·데이터 계약을 정리한 것이다. 새 UI를 직접 설계/구현할 때, 아래 "데이터 계약"과 "상태 흐름"만 그대로 연결하면 시각 디자인은 자유롭게 바꿔도 동작이 보장된다. (미디어 전송은 LiveKit SDK가 담당하고, 우리는 토큰 발급 + 화면 구성만 한다.)

---

1. 범위

• 포함(단계 1~3 구현됨)
  • 단계 1: 방 입장 → LiveKit 연결 → 카메라/마이크 발행 → 나가기, 마이크/카메라 on·off
  • 단계 2: 권한 분기 — 방 생성자=진행자(host), 이후 입장자=일반. 역할별 토큰 grant 차등
  • 단계 3: 진행자/승격된 참여자 큰 화면(stage) + 나머지 썸네일, 진행자의 화면 승격(데이터 채널 브로드캐스트), 썸네일 페이지네이션
• 제외(후속 단계): 단계 4(방 목록/예약/참여 제한 UI), 5(부하 테스트), 6(셀프호스팅 배포)
• ⚠️ 현재 화면 레이아웃은 임시(대충)이며 UI 는 새로 개편 예정. 아래 "데이터 계약"만 그대로 연결하면 동작이 유지된다.

---

2. 진입 / 라우트

항목	값
라우트	/meeting/:room? (room 파라미터는 선택)
라우트 name	meeting
인증	requiresAuth: true (로그인 필요)
페이지 컴포넌트	frontend/src/pages/relay/MeetingPage.vue
사이드바 네비	AppShell.vue 의 "화상회의" 항목 (/meeting)

• /meeting 으로 들어오면 방 이름 미입력 상태의 로비.
• /meeting/<방이름> 으로 들어오면 그 방 이름이 입력란에 채워진 로비(공유 링크 용도). 입장 버튼을 눌러야 실제 연결된다(카메라 권한 타이밍 확보).
• 입장 성공 시 주소창을 /meeting/<방이름> 으로 replace 한다(공유 가능 링크).

---

3. 화면 상태 (4가지)

상태	조건	화면
로비(미연결)	connected === false	방 이름 입력 폼
연결 중	connecting === true	입장 버튼이 "입장 중…" + 비활성
회의실(연결됨)	connected === true	컨트롤 바 + 영상 그리드
에러	joinError / errorMsg 존재	해당 영역에 빨간/주황 문구

• joinError: 입장 시도 단계의 오류(방 이름 형식 오류, 토큰 발급 실패 등) — 로비에 표시.
• errorMsg: 연결 이후 미디어 단계의 오류(카메라/마이크 권한 거부 등) — 회의실에 표시. 권한 거부여도 연결 자체는 유지된다.

---

4. 로비 화면 (현재 구성)

• 페이지 제목 화상회의 + 안내 문구(lede)
• 카드 폼:
  • 라벨 * 방 이름 (필수 표기)
  • 힌트: "영문·숫자·하이픈(-)·밑줄(_)만 사용할 수 있습니다."
  • 입력란: maxlength=64, placeholder 예: team-standup
  • 오류 문구(joinError)
  • 푸터: 입장하기 버튼(제출 시 onJoin)
• 방 이름 규칙: ^[A-Za-z0-9_-]+$, 1~64자. (백엔드 DTO와 동일하게 검증 — 한글/공백 불가)

---

5. 회의실 화면 (현재 구성)

• 상단 바(room-bar)
  • 방 이름(roomName)
  • 참여자 수(참여자 N명 = participants.length)
  • 컨트롤 버튼 3개:
    • 마이크 토글 → toggleMic() (상태 micEnabled)
    • 카메라 토글 → toggleCam() (상태 camEnabled)
    • 나가기 → onLeave() (연결 해제 후 /meeting 로 이동)
• 큰 화면(stage): featured(승격된 참여자 > 진행자 > 첫 참여자) 1명을 크게 렌더.
• 썸네일(thumbs): 나머지 참여자를 작은 타일로 렌더. 진행자에게만 각 썸네일에 "크게"(승격) 버튼 표시 → promote(identity) 호출(데이터 채널로 전원 동기화).
• 페이지네이션(pager): 썸네일이 페이지당 12명을 넘으면 이전/다음. 현재 페이지 타일만 렌더되므로 adaptiveStream 이 안 보이는 참여자의 미디어를 자동으로 구독 해제(대역폭 절약).
• 본인 식별: participants[0] 이 항상 본인. 타일 is-local 은 p.identity === participants[0].identity 로 판정.

현재 컨트롤은 이모지(🎙/📹) 버튼·상단 바 등 임시 배치다 → 새 UI에서 하단 중앙 컨트롤 바, 큰화면/썸네일 비율, 승격 버튼 위치 등 자유롭게 재구성 가능. 연결되는 함수/상태만 동일하게 쓰면 된다.

---

6. 참여자 타일 (ParticipantTile.vue)

• Props
  • participant: Participant (livekit-client) — 필수
  • isLocal?: boolean — 본인 타일 여부
• 동작
  • 카메라 트랙을 <video> 에 attach. 본인 타일은 좌우 반전(거울) + muted(에코 방지).
  • 원격 참여자의 마이크 트랙을 <audio> 에 attach(본인 오디오는 재생 안 함).
  • 영상이 없으면(카메라 off/미발행) 이름 첫 글자 이니셜 플레이스홀더 표시.
  • 하단에 마이크 상태 아이콘 + 표시 이름(본인은 (나) 접미).
• 표시 이름: participant.name || participant.identity
  • name = 토큰에 담은 사용자 이름(한글 이름), identity = 사용자 ID(UUID).
• 마이크 상태: participant.isMicrophoneEnabled
• 트랙 변경 반영: ParticipantEvent 의 TrackSubscribed/Unsubscribed/LocalTrackPublished/LocalTrackUnpublished/TrackMuted/TrackUnmuted 구독 → 재attach.

새 디자인에서 "말하는 사람 하이라이트(speaking)"가 필요하면 participant.isSpeaking + ParticipantEvent.IsSpeakingChanged 를 추가로 쓰면 된다.

---

7. 상태 흐름 (입장 → 표시 → 나가기)

[로비] 방 이름 입력 + 입장
   │  onJoin(): 형식 검증
   ▼
useMeeting().getToken(roomName)         ← 백엔드 POST /api/meetings/token
   │  { token, roomName, identity }
   ▼
useLiveKitRoom().connect(token)
   │  ├─ Room.connect(VITE_LIVEKIT_URL, token)   (시그널링/ICE)
   │  ├─ enableCameraAndMicrophone()             (카메라/마이크 발행, 실패해도 연결 유지)
   │  └─ 이벤트 구독 → participants 갱신
   ▼
[회의실] participants 그리드 표시 (본인 + 원격)
   │  toggleMic / toggleCam 로 발행 제어
   ▼
onLeave() → disconnect() → /meeting
(화면 이탈 시 onBeforeUnmount 에서도 disconnect 자동 호출)

---

8. 데이터 계약 (새 UI가 그대로 연결할 부분)

8.1 useLiveKitRoom() — frontend/src/composables/useLiveKitRoom.ts

LiveKit 방 연결/생명주기를 캡슐화. 반환 객체:

이름	타입	의미
participants	Ref<Participant[]>	본인(0번) + 원격 참여자. 배열 통째 교체로 갱신(shallowRef)
connected	Ref<boolean>	방 연결 여부(회의실 표시 기준)
connecting	Ref<boolean>	연결 진행 중
micEnabled	Ref<boolean>	본인 마이크 on/off
camEnabled	Ref<boolean>	본인 카메라 on/off
errorMsg	Ref<string | null>	연결 이후 미디어 오류 메시지
featuredIdentity	Ref<string | null>	승격되어 크게 볼 참여자 identity(없으면 진행자/첫 참여자가 기본)
connect(token)	(token: string) => Promise<void>	입장(연결 + 카메라/마이크 발행)
disconnect()	() => Promise<void>	나가기(연결 해제, 상태 초기화)
toggleMic()	() => Promise<void>	마이크 on/off
toggleCam()	() => Promise<void>	카메라 on/off
promote(identity)	(identity: string) => Promise<void>	해당 참여자를 큰 화면으로 승격(진행자만 호출, 전원 동기화)

역할 식별: useMeeting().getToken() 응답의 role('host'|'participant')로 본인 역할을 안다. 다른 참여자의 진행자 여부는 participant.metadata(JSON {"role":"host"})로 판정한다.

• 접속 URL은 import.meta.env.VITE_LIVEKIT_URL(없으면 ws://localhost:7880). 개발은 LiveKit Cloud(wss://<project>.livekit.cloud).
• Room 옵션: adaptiveStream: true, dynacast: true.

8.2 useMeeting() — frontend/src/composables/useMeeting.ts

메서드	반환	설명
getToken(roomName)	Promise<{ token, roomName, identity }>	백엔드에서 LiveKit 입장 토큰(JWT) 발급

---

9. 백엔드 (참고 — 변경 불필요)

• 엔드포인트: POST /api/meetings/token (JWT 인증 필요)
• 요청 바디: { "roomName": "team-standup" } (DTO 검증: ^[A-Za-z0-9_-]+$, 1~64자)
• 응답: { "token": "<LiveKit JWT>", "roomName": "...", "identity": "<userId>" }
• 권한(현재 단계 1): 모든 입장자에게 roomJoin + canPublish + canSubscribe + canPublishData 부여. identity=사용자 ID, name=사용자 이름. 토큰 TTL 1시간.
• 파일: backend/src/modules/meeting/{meeting.controller.ts, meeting.service.ts, dto/create-meeting-token.dto.ts}

---

10. 파일 맵

파일	역할
frontend/src/pages/relay/MeetingPage.vue	화면(로비 + 회의실) — 새로 디자인할 대상
frontend/src/components/meeting/ParticipantTile.vue	참여자 1명 영상 타일 — 새 디자인 시 함께 손봄
frontend/src/composables/useLiveKitRoom.ts	연결/참여자/컨트롤 상태 (재사용, 그대로 연결)
frontend/src/composables/useMeeting.ts	토큰 발급 API
frontend/src/router/index.ts	/meeting/:room? 라우트
frontend/src/layouts/AppShell.vue	사이드바 "화상회의" 네비

---

11. 디자인 규약 (새 화면이 사이트와 어울리게)

• rem 단위 사용 (px 금지). 단, 1px 보더/그림자는 px 유지. 앱 기준 폰트는 14px(루트), rem은 16px 기준으로 작성해도 14px 스케일로 렌더된다.
• 인라인 스타일 금지, <style scoped> 사용.
• 색상은 CSS 변수 사용(예시):
  • 강조: --accent(#4f46e5), --accent-hover, --accent-weak
  • 텍스트: --text, --text-2, --text-3
  • 경계/패널: --border, --border-strong, --panel
  • 상태색: --green/-weak/-border, --amber/-weak/-border, --red/-weak/-border
• 공용 컴포넌트 재사용 가능: BaseModal, SegmentedTabs, EmptyState, UserAvatar(아바타 플레이스홀더로 타일에 활용 가능) 등 frontend/src/components/common/ 참고.
• 버튼 높이/폼 규격은 기존 페이지(ProjectCreatePage.vue 등)의 .btn, .tinput 패턴 참고.

---

12. 동작 확인 방법

1. dev 스택 기동 후 http://localhost:5273/meeting 접속
2. 방 이름 입력 → 입장 → 카메라/마이크 권한 허용 → 본인 영상 표시
3. 두 번째 탭(또는 다른 브라우저) 에서 같은 방으로 입장 → 서로의 영상/음성 확인
4. 미디어 서버는 LiveKit Cloud 사용(.env.development 의 LIVEKIT_*). 운영 전환은 env 값 교체만으로 가능.