PonsLink의 핵심 UX 원칙은 다섯 단계다. 방(룸)은 네 번째 단계에 불과하다. 이 글은 그 다섯 단계가 API·DB·프론트 라우트에 어떻게 내려앉는지 정리한다.
1. Request Intake — 공개 데스크
방문자는 `/public-desk/:identifier`로 들어온다. API는 `GET /public-desk/:identifier`, `POST /public-desk/:identifier/requests`를 제공한다. 별칭 경로(`/public-aliases/:alias`)도 동일 패턴이다. 요청이 저장되면 방문자에게 `request-status/:token` 추적 링크가 발급된다.
여기서 중요한 판단: 계정이 없어도 요청을 남길 수 있어야 한다. 전문가는 링크 하나로 상담 목적과 맥락을 먼저 받는다.
2. Review & Approval — 검토·수락
호스트는 라운지(`/lounge/requests`)에서 요청을 본다. 액션은 수락/거절/정보 요청/일정 제안이다.
– 라운지 내부: `POST /lounge/requests/:id/{accept,decline,propose-time,request-information}`
– 토큰 기반(이메일 링크): `POST /request-actions/:token/{accept,decline,respond,propose-time,direct-call}`
상태 변화는 `GET /request-status/:token/events`로 방문자가 실시간 추적한다. AI 요약·답변 초안(`…/ai/summary`, `…/ai/reply-draft`)은 OpenRouter를 경유한다. "자동 수락"은 없다. 판단 권한은 전문가에게 남긴다.
3. Condition/Payment — 일정·결제 게이트
수락 후에도 바로 방에 들어가지 못할 수 있다. 일정 확정, 구독, 1회 결제(드롭 패스)가 게이트다.
– 구독: `POST /subscriptions/checkout`, `GET /subscriptions/me`
– 1회 결제: `POST /payments`, 공급자별 complete/capture
– 세션 접근 확인: `GET /session-access/:roomTitle`
결제 확정은 웹훅 원장으로만 이뤄진다. 프론트의 "결제 완료 화면"은 힌트일 뿐, 권한의 근거가 아니다.
4. Professional Session — 전문 세션 룸
게이트를 통과하면 `/room/:roomTitle` 또는 `/join/:roomTitle`로 들어간다. Socket.IO(`/socket.io`)로 시그널링하고, 미디어는 P2P 메시 우선·필요 시 SFU/TURN이다.
룸 API 표면:
– 채팅 `…/chat/messages`
– 파일 `…/files/uploads`, `…/file-transfers`
– 화이트보드 `…/whiteboards`
– 코워치 `…/cowatch/sessions`
– 폰캐스트 `…/ponscast/playlists`
– 미디어 트랙 mute/unpublish
– 음성/자막 `GET /speech/*`, `…/speech/transcripts`
– 번역 `POST /translation/translate`
이 기능들은 "회의 링크"가 아니라 준비된 상담 도구로 묶여 있다. 요청 맥락이 세션 안으로 들어와야 한다.
5. Auto-Archive — 자동 보관
세션 중 `POST /rooms/:id/meeting-records/start`로 기록을 시작하고, segment를 쌓은 뒤 `finalize`한다. 결과는 `/lounge/meeting-records`에 요청과 연결되어 남는다. 후속 조치는 다시 1단계 요청으로 이어질 수 있다.
실패 모드를 먼저 설계한다
– 요청만 쌓이고 응답이 없으면 → 만료 크론/`POST /lounge/requests/expire`
– 결제는 됐는데 웹훅이 늦으면 → 멱등성 키 + 이벤트 원장 + reconcile 크론
– 세션 중 재연결 → `replayStore`로 누락 시그널 복구
– 파일이 API 메모리를 뚫고 지나가면 → 금지. R2 직접 전송만 허용
라이프사이클을 제품의 척추로 두면, 기능 추가가 "또 하나의 버튼"이 아니라 "어느 단계의 상태 전이인가"로 평가된다. 다음 글은 4단계의 실시간 인프라 — 시그널링과 TURN — 를 깊게 본다.
댓글