> ## Documentation Index
> Fetch the complete documentation index at: https://playwave.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 동작 원리

> PlayWave 플랫폼의 전체 동작 흐름을 설명합니다

## 시스템 구성

PlayWave는 4개의 구성 요소가 서로 통신합니다.

<Columns cols={2}>
  <Card title="PlayWave 런처" icon="desktop">
    PC방에 설치되는 Windows 앱. HMAC 서명으로 PC방 IP를 인증하고, OTT 토큰과 함께 게임을 실행합니다.
  </Card>

  <Card title="PlayWave 서버" icon="server">
    세션 관리, 과금, 정산을 처리하는 백엔드 API. PC방 인증 서버와 연동하여 IP 검증 및 과금을 추적합니다.
  </Card>

  <Card title="게임 서버" icon="gamepad">
    PlayWave가 연동된 Roblox 게임 서버. API Key 인증으로 PlayWave 서버에 OTT 검증, 하트비트, 세션 종료를 요청합니다.
  </Card>

  <Card title="PC방 인증 서버" icon="building">
    PC방 IP 인증과 플레이 시간 과금 API를 제공하는 외부 인프라 파트너입니다.
  </Card>
</Columns>

### 연결 구조

<Steps>
  <Step title="런처 → PlayWave 서버" icon="arrow-right">
    런처가 PC 정보를 **HMAC 서명**과 함께 PlayWave 서버로 전송하여 인증 및 OTT 발급을 요청합니다.
  </Step>

  <Step title="런처 → Roblox" icon="arrow-right">
    런처가 **LaunchData에 OTT를 포함**하여 게임을 실행하고 세션을 Roblox 클라이언트로 전달합니다.
  </Step>

  <Step title="게임 서버 → PlayWave 서버" icon="arrow-right">
    게임 서버가 **API Key 인증**으로 PlayWave 서버 API를 호출하여 OTT 검증, 하트비트, 세션 종료를 처리합니다.
  </Step>

  <Step title="PlayWave 서버 → PC방 인증 서버" icon="arrow-right">
    PlayWave 서버가 외부 PC방 인증 API를 호출하여 **IP 주소 검증** 및 **과금 세션 관리**를 수행합니다.
  </Step>
</Steps>

## 전체 흐름

```mermaid theme={null}
sequenceDiagram
    participant L as 🖥️ PlayWave 런처
    participant API as 🔷 PlayWave 서버
    participant Roblox as 🎮 Roblox Client
    participant GS as 🖥️ Game Server

    Note over L, API: Phase 1 — 세션 시작 & PC방 인증
    L->>API: POST /session/start (IP + HMAC 인증)
    API->>API: 외부 IP 추출 → PC방 인증
    API-->>L: session_token + 게임 목록

    Note over L, Roblox: Phase 2 — 게임 선택 & OTT 발급
    L->>API: POST /ott (게임 선택)
    API-->>L: OTT (1회용 토큰, 1분 유효)
    L->>Roblox: 게임 실행 (LaunchData에 OTT 포함)

    Note over Roblox, GS: Phase 3 — OTT 검증 & 혜택 지급
    Roblox->>GS: 게임 접속 (LaunchData 포함)
    GS->>API: POST /session/verify (OTT + 유저 ID)
    API-->>GS: game_session_id + is_pc_cafe
    GS-->>Roblox: PC방 혜택 적용

    Note over GS, API: Phase 4 — 하트비트 (2분 간격)
    loop 매 2분
        GS->>API: PATCH /session/heartbeat (game_session_id)
        API-->>GS: OK + 누적 플레이 시간
    end

    Note over GS, API: Phase 5 — 세션 종료
    alt 정상 퇴장
        GS->>API: DELETE /session/end (game_session_id)
    else 비정상 종료
        Note over GS, API: 4분간 하트비트 없으면 자동 종료
    end
```

## 5단계 상세

### Phase 1 — 세션 시작

PC방 유저가 PlayWave 런처를 실행하면:

1. 런처가 PC의 내부 IP와 하드웨어 정보를 수집
2. HMAC 서명과 함께 PlayWave 서버에 세션 시작 요청
3. PlayWave 서버가 HTTP 요청에서 외부 IP를 추출하여 PC방 여부를 인증
4. 인증 성공 시 세션 토큰과 지원 게임 목록을 반환

### Phase 2 — OTT 발급 & 게임 실행

유저가 게임을 선택하면:

1. 런처가 PlayWave 서버에 OTT(One-Time Token) 발급 요청
2. PlayWave 서버가 UUID 형태의 OTT를 생성 (1분 유효, 1회용)
3. 런처가 OTT를 LaunchData에 포함하여 Roblox 게임 실행

### Phase 3 — OTT 검증 & 과금 시작

유저가 게임에 접속하면:

1. 게임 서버가 LaunchData에서 OTT를 추출
2. PlayWave 서버에 OTT 검증 요청 (API Key 인증)
3. PlayWave 서버가 OTT 유효성 확인 후 과금 시작
4. 게임 세션 ID를 반환하고 PC방 혜택 지급 여부 전달

### Phase 4 — 하트비트

게임 플레이 중:

1. 게임 서버가 2분 간격으로 PlayWave 서버에 하트비트 전송
2. PlayWave 서버가 과금 세션을 갱신하고 플레이 시간을 기록
3. 하트비트가 4분간 수신되지 않으면 세션 자동 종료

### Phase 5 — 세션 종료

유저가 게임을 떠나면:

1. 게임 서버가 PlayWave 서버의 세션 종료 API 호출
2. PlayWave 서버가 과금을 중지하고 최종 플레이 시간을 기록
3. 비정상 종료 시 하트비트 타임아웃으로 자동 정리

## OTT (One-Time Token)

OTT는 PlayWave 런처에서 게임 서버로 세션을 안전하게 전달하는 1회용 토큰입니다.

| 속성    | 값                   |
| ----- | ------------------- |
| 형식    | UUID v4             |
| 유효기간  | 1분 (60초)            |
| 사용 횟수 | 1회 (verify 호출 시 소비) |
| 전달 방법 | Roblox LaunchData   |

<Warning>
  OTT는 1회용입니다. verify 호출 후 재사용할 수 없으며, 1분 내에 사용하지 않으면 만료됩니다.
</Warning>