# T1 · 세션 시간이 끝났을 때 (안내 창)

> **보는 사람**: 모두 (진행자에게만 버튼)  
> **파일**: [index.html](index.html) (화면) · [screen.js](screen.js) (이 화면 동작)

## 이 화면은

타이머가 00:00이 되면 지금 보던 화면 위에 뜨는 안내 창. 세션은 자동으로 끝나지 않고, 진행자가 "5분 더"(session.extend) 또는 "이대로 계속"을 고른다. 참가자는 안내만 본다. 이 화면은 그 창의 목업이다(실제로는 app.js가 모든 세션 화면에 띄움).

## 누르면 어떻게 되나

| 누르는 것 | 동작 | 이동 |
|---|---|---|
| 이대로 계속 진행하기 | `timeUpDismiss` | — |
| 5분 더 진행하기 | `timeUpExtend` | — |

## 프론트엔드

**이미 구현한 것**

- ✅ 타이머 00:00 → 모든 세션 화면에서 안내 창(app.js `App.timeUp`)
- ✅ 진행자: "5분 더" → session.extend → 타이머 다시 시작 · "이대로 계속" → 창만 닫힘
- ✅ 참가자: "진행자가 정하는 중" 안내 + 확인

## 백엔드가 해야 할 일 (쉽게)

- <b>자동 종료 없음</b>(2026-09-18 결정). 서버는 endsAt이 지나도 아무것도 하지 않는다. 진행자가 session.extend를 부르면 endsAt을 늘리고 timer.sync를 모두에게 보낸다.
- 무료 세션은 총 30분을 넘길 수 없다(403 PLAN_LIMIT). durationMin이 null이면 타이머가 없으니 이 창도 안 뜬다.

## 이 화면이 쓰는 API

| 언제 | API | 요약 |
|---|---|---|
| 5분 더 진행하기 | `PUT /sessions/{sessionId}/timer` | 세션 시간 연장 |

## 실시간 이벤트 (웹소켓으로 받는 것)

| 이벤트 | 받으면 |
|---|---|
| `timer.sync` | 1분마다 서버 시각 기준으로 타이머 보정 |

형식은 [docs/02-API-공통-규칙.md](../../docs/02-API-공통-규칙.md#실시간-이벤트) 참고.

## API 상세

모든 경로 앞에 `/api/v1`가 붙어요. 공통 규칙(인증·에러 형식)은 [docs/02-API-공통-규칙.md](../../docs/02-API-공통-규칙.md).

### `PUT /api/v1/sessions/{sessionId}/timer` — 세션 시간 연장

- **API id**: `session.extend` (프론트: `api.call('session.extend', …)`)
- **누가 부를 수 있나**: 세션 진행자만
- **하는 일**: 시간이 끝났을 때(또는 끝나기 전) 진행자가 5분 단위로 늘린다. 모두에게 timer.sync 이벤트로 새 endsAt을 보낸다.

**요청 본문**

```json
{
  "addMin": 5
}
```

**응답** `200`

```json
{
  "timer": {
    "endsAt": "2026-09-18T15:37:10+09:00",
    "remainingSec": 300
  }
}
```

**에러**

| code | HTTP | 언제 |
|---|---|---|
| `VALIDATION` | 400 | addMin이 1~30 밖 |
| `PLAN_LIMIT` | 403 | 무료 세션은 총 30분을 넘길 수 없음 (PRO는 제한 없음) |
| `FORBIDDEN` | 403 | 진행자가 아님 |
| `SESSION_STARTED` | 409 | 아직 시작 전이거나 이미 끝난 세션 → 시작 전 · 종료 후에는 연장 불가 |

**백엔드 메모**

- 시간이 끝나도 세션은 자동으로 끝나지 않는다(2026-09-18 결정). 프론트가 00:00이 되면 안내 창을 띄우고, 진행자가 "5분 더"(이 API) 또는 "이대로 계속"(아무 호출 없음)을 고른다.
- durationMin이 null(제한 없음)인 세션은 타이머가 없으니 이 API도 쓰지 않는다(400 VALIDATION).
- 연장 뒤 endsAt은 "지금 + addMin"이 아니라 "원래 endsAt + addMin". 여러 번 눌러도 합계가 한도를 넘으면 403 PLAN_LIMIT.