---
title: "AdLuck 어드민 사용 설명서"
subtitle: "키오스크 광고 플랫폼 — 광고주·운영자용"
date: "2026년 7월"
lang: ko
---

# 이 설명서에 대하여

AdLuck은 매장에 설치된 키오스크로 **광고를 내보내고, 방문객의 참여(게임·설문)를 고객 DB와 보상(카드 발급)으로 연결**하는 광고 플랫폼입니다. 이 문서는 **어드민(관리자 웹)** 에서 기기를 운영하고 광고·설문·보상을 관리하는 방법을, 실제 화면 캡처와 함께 단계별로 설명합니다.

- **어드민 접속**: <https://admin.adluck7.com>
- **공개 홈페이지**: <https://adluck7.com>
- **대상 독자**: 광고주, 매장 운영자, 최고 관리자
- **읽는 법**: 처음이라면 「시작하기」부터 순서대로, 특정 작업만 필요하면 맨 앞 목차에서 해당 장으로 바로 이동하세요.

> 💡 이 문서의 화면은 실제 어드민을 캡처한 것입니다. 계정 권한·데이터 상황에 따라 일부 항목이 다르게 보일 수 있습니다.

> **운영의 중심은 「기기 상세」입니다.** 광고·설문·보상 등 대부분의 콘텐츠 작업은 기기 관리에서 기기를 선택한 뒤, 상세 화면 상단의 7개 탭(광고 배치 · 스케줄 · 운영 · 건강 · 설문 · 보상·디스펜서 · 정보·통계)에서 이루어집니다.

---


# 시작하기 — 로그인과 화면 구성

이 챕터에서는 AdLuck 어드민에 처음 접속해 로그인하는 방법과, 로그인 후 모든 페이지에 공통으로 나타나는 화면 구조(상단바·사이드바·알림·검색)를 안내합니다. 광고주와 매장 운영자 모두 여기서부터 시작하시면 됩니다.

- 어드민 로그인 주소: **https://admin.adluck7.com**
- 공개 홈페이지 주소: **https://adluck7.com**

---

## 1. 로그인하기

관리자 계정으로 어드민에 접속하는 화면입니다. 이메일과 비밀번호를 넣어 로그인합니다.

### 1-1. 이메일·비밀번호 입력

![관리자 로그인 화면 — 이메일·비밀번호 입력](screenshots/login-signin-form.png)

로그인 카드 상단에는 **키오스크 광고 관리** 제목과 **관리자 계정으로 로그인하세요** 안내가 표시됩니다.

**화면 요소**

| 요소 | 설명 |
| --- | --- |
| **이메일** | 관리자 이메일 입력란입니다. 예시로 `admin@example.com` 형식이 안내됩니다. |
| **비밀번호** | 비밀번호 입력란입니다. `비밀번호 입력` 안내가 표시됩니다. |
| **로그인** | 제출 버튼입니다. 처리 중에는 **로그인 중...** 으로 바뀌며 잠시 비활성화됩니다. |

**작업 순서**

1. 브라우저에서 **https://admin.adluck7.com** 에 접속합니다.
2. **이메일** 에 관리자 이메일을 입력합니다.
3. **비밀번호** 를 입력합니다.
4. **로그인** 을 누릅니다.
5. 로그인에 성공하면 대시보드로 이동합니다.

> 💡 이미 로그인된 상태에서 로그인 주소로 다시 접속하면 자동으로 대시보드로 이동합니다.

> ⚠️ 로그인에 실패하면 원인에 따라 다른 안내가 나옵니다. 이메일이나 비밀번호가 틀리면 **이메일 또는 비밀번호가 올바르지 않습니다.**, 시도가 너무 잦으면 **너무 많은 시도가 있었습니다. 잠시 후 다시 시도해 주세요.** 가 표시됩니다. 관리자 권한이 없는 계정은 **이 계정에는 관리자 권한이 없습니다. 관리자에게 문의하세요.** 라고 안내되니, 이 경우 담당 관리자에게 문의하세요.

### 1-2. 민감 작업 전 보안 재인증

계정 생성이나 삭제처럼 특히 중요한 작업을 실행하면, 본인 확인을 위해 **보안 재인증** 모달이 뜹니다. **계속하려면 비밀번호를 다시 입력하세요** 안내에 따라 비밀번호를 넣고 **확인**(또는 Enter)을 누르면 작업이 계속되고, **취소** 를 누르면 중단됩니다.

---

## 2. 공통 화면 구조 살펴보기

로그인하면 모든 페이지 위에 공통으로 상단바와 좌측 메뉴가 나타납니다. 이 구조만 익혀 두면 어느 페이지에서든 원하는 곳으로 빠르게 이동할 수 있습니다.

### 2-1. 전체 구조 한눈에 보기

![공통 셸 전체 구조 — 상단 AppBar(HelloBee 로고·검색·알림·프로필)와 좌측 메뉴 Drawer](screenshots/shell-nav-overview.png)

**화면 요소**

- 상단바 왼쪽의 **HelloBee** 로고 — 누르면 공개 홈페이지로 이동합니다(`Bee` 글자가 파란색으로 강조됩니다).
- 상단바 오른쪽의 **검색  ⌘K**, 알림 종 아이콘, 계정 아바타.
- 왼쪽의 **메뉴** 그룹(사이드바)과 하단의 역할 상태칩.

> 💡 사이드바와 프로필 메뉴 항목은 계정의 역할과 권한에 따라 자동으로 숨겨집니다. 그래서 사람마다 보이는 메뉴가 다를 수 있습니다.

### 2-2. 사이드바 메뉴로 이동하기

왼쪽 **메뉴** 그룹에서 각 관리 페이지로 이동합니다. 현재 보고 있는 위치는 흰색으로 강조됩니다. 아래 표의 "필요 권한"이 없는 항목은 화면에 아예 나타나지 않습니다.

| 메뉴 | 이동 위치 | 필요 권한 |
| --- | --- | --- |
| **대시보드** | 운영 현황 요약 | analytics:read |
| **데이터 분석** | 상세 데이터 분석 | analytics:read |
| **기기 관리** | 키오스크 기기 목록·상세 | devices:read |
| **플레이리스트** | 재생 목록 관리 | devices:read |
| **계정 관리** | 사용자·권한 관리 | accounts:manage |
| **감사 로그** | 활동 기록 조회 | audit:read |

사이드바 하단에는 현재 역할 상태칩이 초록 점과 함께 표시됩니다(예: 최고 관리자면 **최고 관리자**, 기업 계정이면 **기업 계정**).

> 💡 원하는 메뉴가 보이지 않는다면 해당 권한이 없는 것입니다. 필요한 권한은 계정 관리자에게 요청하세요.

### 2-3. 프로필 메뉴 — 계정 정보·설정·로그아웃

![프로필 메뉴 — 이름/이메일/역할 칩과 계정 정보·설정·로그아웃](screenshots/shell-nav-profile-menu.png)

상단바 오른쪽의 아바타(이름 이니셜)를 누르면 프로필 메뉴가 열립니다. 상단에 내 이름·이메일·역할 칩이 표시됩니다.

**화면 요소**

- **계정 정보** — 내 계정 정보 페이지로 이동합니다.
- **설정** — 설정 페이지로 이동합니다.
- **로그아웃** — 빨간색 항목으로, 누르면 **로그아웃 하시겠습니까?** 확인 후 로그아웃됩니다.

**작업 순서**

1. 상단바 오른쪽 아바타를 누릅니다.
2. 이름·이메일·역할을 확인합니다.
3. **계정 정보**, **설정**, **로그아웃** 중 원하는 항목을 선택합니다.

### 2-4. 알림 확인하기

![알림 드롭다운 — 묶음 표시·모두 읽음·전체 알림 보기](screenshots/shell-nav-notifications.png)

상단바의 종 아이콘은 알림을 보여 줍니다. 읽지 않은 알림이 있으면 빨간 배지에 개수가 표시됩니다(10건 이상이면 **9+**).

**화면 요소**

- 드롭다운 제목 **알림**.
- **모두 읽음** — 누르면 전체를 읽음 처리하고 **모든 알림을 읽음 처리했습니다.** 안내가 뜹니다.
- 같은 대상의 반복 알림은 최신 1건과 함께 **외 N건** 으로 묶여 표시됩니다.
- **전체 알림 보기** — 전체 알림 페이지로 이동합니다.
- 알림이 없으면 **알림이 없습니다** 가 표시됩니다.

**작업 순서**

1. 상단바 종 아이콘을 누릅니다.
2. 목록에서 알림을 누르면 관련 페이지로 이동하며 자동으로 읽음 처리됩니다.
3. **모두 읽음** 으로 한 번에 정리하거나, **전체 알림 보기** 로 전체 목록을 봅니다.

**전체 알림 페이지**(종 드롭다운 아래 **전체 알림 보기** 링크로 진입)에서는 더 자세히 관리할 수 있습니다. 개별 알림을 클릭하면 전체 페이지가 아니라 관련 화면(예: 해당 기기 상세)으로 바로 이동합니다.

- **카테고리 필터**: **운영**(기기 오프라인·이상 등) / **계정·구독** 으로 나눠 봅니다.
- **읽음 상태 필터**: **안읽음** / **읽음** 으로 좁힙니다.
- **유형 칩·검색**: 알림 유형 칩과 제목·내용 검색으로 원하는 알림을 찾습니다.
- **모두 읽음**: 목록 전체를 한 번에 읽음 처리합니다.
- 알림을 클릭하면 관련 화면(예: 해당 기기 상세)으로 바로 이동합니다.

> 💡 알림은 약 30초 간격으로 자동 갱신됩니다. 새 알림이 생기면 잠시 후 배지 숫자에 반영됩니다.

### 2-5. ⌘K 명령 팔레트로 빠르게 이동

![⌘K 명령 팔레트 — 검색으로 메뉴·기기 빠른 이동](screenshots/shell-nav-command-palette.png)

명령 팔레트는 메뉴 이름이나 기기를 검색해 어디서든 바로 이동할 수 있는 검색창입니다. 상단바의 **검색  ⌘K** 를 누르거나 키보드로 열 수 있습니다.

**화면 요소**

- 입력창 안내문: **검색 또는 이동… (기기 이름·위치·일련번호)**.
- 결과는 **이동 / 설정 / 기기** 그룹으로 나뉩니다.
- 일치하는 결과가 없으면 **결과가 없습니다** 가 표시됩니다.

**작업 순서**

1. 상단바 **검색  ⌘K** 를 누르거나 키보드로 **⌘K**(맥) 또는 **Ctrl+K**(윈도우)를 누릅니다.
2. 검색창에 메뉴 이름 또는 기기 이름·위치·일련번호를 입력합니다.
3. ↑/↓ 키로 항목을 고른 뒤 Enter(또는 클릭)로 이동합니다.
4. Esc를 누르면 닫힙니다.

> 💡 기기 검색은 이름뿐 아니라 위치와 일련번호로도 찾을 수 있고, 최대 8건까지 표시됩니다. 아직 등록되지 않은 기기는 이름 뒤에 **(미등록)** 으로 표시됩니다.

> 💡 명령 팔레트에는 일부 메뉴(대시보드·데이터 분석·기기 관리·플레이리스트·계정 관리·계정 정보·설정)만 나옵니다. **감사 로그**는 왼쪽 사이드바에서 이동하세요.

### 2-6. 자동 로그아웃 안내

일정 시간 동안 아무 조작이 없으면 보안을 위해 자동으로 로그아웃됩니다. 로그아웃 1분 전에는 **세션 만료 경고** 모달이 뜨며, 본문에 **비활동으로 인해 곧 자동 로그아웃됩니다.** 라고 안내됩니다. 계속 사용하려면 **세션 연장** 을 눌러 타이머를 초기화하세요.

> 💡 자동 로그아웃 시간은 설정 페이지에서 드롭다운으로 정합니다(**사용안함 / 15분 / 30분 / 1시간 / 2시간 / 4시간 / 8시간**). **사용안함**이면 자동 로그아웃이 꺼집니다.


# 대시보드

**대시보드**는 로그인 후 가장 먼저 만나는 화면입니다. 오늘의 운영 현황을 한 페이지에 요약해 보여 주는 정보판으로, 매출과 직결되는 완료 세션·가동 기기·터치·보상 수령 같은 핵심 지표와 조치가 필요한 경보, 최근 활동을 한눈에 확인할 수 있습니다.

접속 주소는 로그인 화면 `https://admin.adluck7.com` 이며, 로그인 후 왼쪽 사이드바에서 **대시보드**를 클릭하면 이 화면으로 이동합니다.

## 화면 개요

![대시보드 전체 개요 — KPI 4종과 운영 경보, 빠른 작업](screenshots/dashboard-overview.png)

화면 맨 위에는 페이지 제목 **대시보드**와 부제 **오늘의 운영 현황을 한눈에 확인합니다.** 가 표시됩니다. 제목 오른쪽의 **데이터 분석 →** 링크를 누르면 더 자세한 통계를 보는 데이터 분석 화면으로 이동합니다.

대시보드는 위에서부터 다음 순서로 구성됩니다.

1. 상단 KPI 카드 4종
2. 운영 경보 배너
3. 빠른 작업 버튼
4. 완료 세션 추이 차트
5. 기기 현황 표
6. 최근 활동 표

> 💡 페이지를 열어 두면 60초마다 배경에서 데이터가 자동으로 새로 고쳐집니다. 정상 기기가 잠깐 오프라인으로 잘못 표시되는 일을 막아 주므로, 대시보드는 계속 띄워 두어도 됩니다.

> ⚠️ 데이터를 불러오는 동안에는 **대시보드 데이터를 불러오는 중…** 이 표시됩니다. 문제가 생기면 **데이터를 불러오는 중 오류가 발생했습니다.** 와 함께 **다시 시도** 버튼이 나타나며, 이 버튼을 누르면 다시 불러옵니다.

## 상단 KPI 카드 (핵심 지표)

화면 상단에는 오늘의 핵심 지표 4개가 카드로 나란히 표시됩니다. 일부 카드에는 흐름을 보여 주는 작은 그래프(스파크라인)가 함께 나옵니다.

| 카드 | 표시 값 | 부제 / 참고 |
| --- | --- | --- |
| **오늘 완료 세션** | 오늘 완료된 세션 수 | **최근 7일 평균 N**, 스파크라인 표시 |
| **가동 기기** | 온라인/전체(예: 3/5) | **heartbeat 2분 기준** |
| **오늘 터치** | 오늘 발생한 터치 수 | 스파크라인 표시 |
| **오늘 보상 수령** | 오늘 보상 수령 건수 | 불일치가 있으면 **디스펜서 불일치 N** |

> 💡 **가동 기기**는 기기가 약 30초마다 보내는 신호(heartbeat)를 기준으로 판정합니다. 마지막 신호가 2분 넘게 없으면 오프라인으로 셉니다.

> ⚠️ **오늘 보상 수령** 카드에 **디스펜서 불일치 N** 이 보이면, 보상 지급 기록과 실제 배출 장치의 동작이 어긋난 건이 있다는 뜻입니다. 해당 기기의 상태를 점검하세요.

## 운영 경보

KPI 카드 아래에는 지금 조치가 필요한 항목을 알려 주는 운영 경보 영역이 있습니다.

- 조치할 항목이 없으면 초록색 배너 **조치가 필요한 운영 경보가 없습니다.** 가 표시됩니다.
- 조치가 필요한 상황이 있으면 그에 해당하는 경보 배너가 나타나고, 각 배너 오른쪽에는 **보기** 버튼이 있습니다. **보기**를 누르면 경보 종류에 따라 기기 화면(`/devices`) 또는 알림 화면(`/notifications`)으로 이동합니다.

경보는 다음 조건이 충족될 때만 나타납니다.

- 오프라인 기기가 있을 때
- 오늘 디스펜서 불일치가 있을 때
- 미등록 기기가 있을 때
- 이상 감지 알림(읽지 않음)이 있을 때
- 계정·구독 주의(읽지 않은 계정 관련 알림)가 있을 때

**운영 현황을 빠르게 파악하는 방법**

1. 대시보드에 들어옵니다.
2. 상단 KPI 4종(**오늘 완료 세션 / 가동 기기 / 오늘 터치 / 오늘 보상 수령**)을 확인합니다.
3. 운영 경보 배너에서 조치가 필요한 항목이 있는지 봅니다.
4. 경보의 **보기** 버튼을 눌러 해당 화면으로 이동해 처리합니다.

> 💡 **미등록 기기** 경보의 대상은 이름이 `Kiosk-xxxxxxxx` 형태로 자동 생성된 기기입니다. 이름과 소유 기업을 설정해 주면 정상적으로 관리됩니다.

> ⚠️ 이상 감지·계정 주의 건수는 알림 벨의 최근 스트림을 바탕으로 한 근사치입니다. 정확한 내역은 알림 화면에서 확인하세요.

## 빠른 작업

자주 이동하는 화면으로 바로 가는 버튼 모음입니다.

- **기기 관리** — 기기 목록 화면으로 이동합니다.
- **데이터 분석** — 데이터 분석 화면으로 이동합니다.
- **알림** — 알림 화면으로 이동합니다.
- **계정 관리** — 계정 관리 화면으로 이동합니다.
- **보안 이벤트** — 클릭하면 인증 이벤트 모달이 열립니다.

**보안 이벤트 확인하기**

1. 빠른 작업에서 **보안 이벤트** 버튼을 누릅니다.
2. 열린 인증 이벤트 모달에서 내용을 확인합니다.
3. 모달을 닫습니다.

> ⚠️ **보안 이벤트** 버튼과 인증 이벤트 모달은 보안 조회 권한(`security:read`)이 있는 계정에서만 보입니다. 버튼이 없다면 권한이 없는 것이니, 관리자에게 문의하세요.

## 완료 세션 추이 (최근 7일)

![완료 세션 추이 (최근 7일) 라인 차트](screenshots/dashboard-trend-chart.png)

최근 7일 동안 완료된 세션의 흐름을 선 그래프로 보여 줍니다. 그래프의 시리즈 이름은 **완료 세션**입니다.

- 조회 기간은 최근 7일(오늘 기준 -6일부터 오늘까지)로 고정되어 있습니다.
- 표시할 데이터가 없으면 **조회 기간 내 데이터가 없습니다.** 라고 나타납니다.

> 💡 하루하루의 세션 흐름을 보며 늘어나는지 줄어드는지 추세를 파악할 수 있습니다. 더 긴 기간이나 세부 분석이 필요하면 **데이터 분석 →** 으로 이동하세요.

## 기기 현황

![기기 현황 표 — 기기명/위치/상태/마지막 연결](screenshots/dashboard-device-status.png)

등록된 기기의 현재 상태를 표로 보여 줍니다.

| 열 | 설명 |
| --- | --- |
| **기기명** | 기기 이름. 누르면 해당 기기 상세 화면으로 이동합니다. |
| **위치** | 기기가 설치된 위치 |
| **상태** | **온라인** 또는 **오프라인** 칩으로 표시 |
| **마지막 연결** | 마지막으로 연결된 이후 경과 시간 |

등록된 기기가 없으면 **등록된 기기가 없습니다.** 라고 표시됩니다.

**기기 상태를 점검하는 방법**

1. **기기 현황** 표에서 각 기기의 상태 칩(**온라인**/**오프라인**)을 확인합니다.
2. **마지막 연결**의 경과 시간을 확인합니다.
3. 자세히 볼 기기의 **기기명**을 눌러 기기 상세 화면으로 이동합니다.

> ⚠️ 기기 이름이 매핑되지 않은 경우 **(삭제된 기기)** 로 표기됩니다.

## 최근 활동


키오스크에서 최근 일어난 활동을 최대 10건까지 최신순으로 보여 줍니다.

| 열 | 설명 |
| --- | --- |
| **시각** | 활동이 일어난 시각 |
| **유형** | **보상 수령** 또는 **설문 응답** 칩 |
| **기기명** | 활동이 일어난 기기 |
| **상세** | 활동에 대한 부가 정보 |

최근 활동이 없으면 **최근 활동이 없습니다.** 라고 표시됩니다.

> 💡 대시보드는 오늘의 요약에 집중한 화면입니다. 기간별 비교, 세그먼트 분석 등 깊이 있는 통계는 상단 **데이터 분석 →** 링크나 빠른 작업의 **데이터 분석** 버튼을 통해 확인하세요.


# 데이터 분석

**데이터 분석** 페이지는 선택한 기간 동안 우리 광고와 키오스크가 얼마나 잘 작동했는지를 한 화면에서 확인하는 전용 분석 공간입니다. 손님이 화면을 터치하고, QR을 스캔하고, 설문을 완료하기까지의 흐름(전환 퍼널)과 일별 추이, 광고 노출 점유율, 기기별 비교, 설문 성과, 요일·시간대별 피크 시간까지 살펴볼 수 있습니다. 최근 30일 장기 추이와 주간 리포트 다운로드도 제공합니다.

- 로그인: https://admin.adluck7.com
- 사이드바에서 **데이터 분석** 을 눌러 들어갑니다.

> ⚠️ 이 페이지는 데이터 분석 권한(`analytics:read`)이 있는 계정만 보입니다. 권한이 없으면 사이드바에 메뉴가 나타나지 않거나 접근이 제한됩니다.

> 💡 페이지 상단에 "기간을 선택해 전환 퍼널, 추이, 광고/기기/설문 성과를 분석합니다." 라는 안내가 있습니다. 모든 표와 차트는 위쪽에서 고른 기간을 기준으로 함께 바뀝니다.

---

## 장기 추이 (최근 30일)

![장기 추이(최근 30일) — 완료 세션·터치 일별 선 차트](screenshots/analytics-longterm-trend.png)

페이지에 들어가면 가장 먼저 보이는 **장기 추이 (최근 30일)** 섹션입니다. 최근 30일 동안 하루하루 성과가 어떻게 흘러왔는지를 큰 흐름으로 보여줍니다.

### 화면 요소

- **완료 세션 추이 (일별)**: 손님이 설문까지 마친 완료 건수의 일별 흐름입니다.
- **터치 추이 (일별)**: 화면 터치 건수의 일별 흐름입니다.

아직 집계가 없으면 **집계 데이터가 아직 없습니다.** 카드와 함께 "장기 추이는 매일 01:10에 자동 집계됩니다. 첫 집계 이후 표시됩니다." 라는 안내가 나옵니다.

> 💡 장기 추이는 매일 새벽 01:10에 자동 집계된 데이터를 사용합니다. 실시간이 아니라 전일까지 반영된 값이라는 점을 참고하세요.

---

## 기간 분석

![데이터 분석 상단 — 기간 선택과 전환 퍼널(터치→세션→완료), 완료/터치 추이 차트](screenshots/analytics-overview-funnel.png)

**기간 분석** 은 원하는 날짜 범위를 직접 골라 그 기간의 성과를 자세히 들여다보는 핵심 영역입니다. 이 섹션에서 고른 기간이 아래의 모든 표·차트에 적용됩니다.

### 화면 요소

- **날짜 범위 선택기**: 섹션 우측에 있으며 시작일과 종료일을 고를 수 있습니다(빠른 프리셋 포함). 기본값은 오늘 기준 최근 7일(-6일 ~ 오늘)입니다.
- **전환 퍼널 (터치 → 세션 → 완료)**: 3단 막대로 손님의 여정을 보여줍니다.
  - **터치 (QR 화면 진입)** → **세션 (QR 스캔)** → **완료 (설문 제출)**
  - 단계 사이에 **↓ 스캔율 %**, **↓ 완료율 %** 가 표시됩니다.
- **완료 세션 추이**: 기간 내 완료 세션의 일별 선 차트(파랑)입니다.
- **터치 추이**: 기간 내 터치의 일별 선 차트(주황)입니다.

### 기간을 지정해 분석하는 방법

1. **기간 분석** 우측의 날짜 범위 선택기에서 시작일 ~ 종료일을 지정합니다(또는 빠른 프리셋 선택).
2. **전환 퍼널 (터치 → 세션 → 완료)** 막대에서 스캔율과 완료율을 확인합니다.
3. **완료 세션 추이** 와 **터치 추이** 선 차트로 일별 흐름을 살펴봅니다.
4. 아래의 **광고 노출 점유율**, **기기 비교**, **설문 성과**, **노출 추이** 를 이어서 검토합니다.

> 💡 기간 기본값은 최근 7일입니다. 더 넓은 기간을 보려면 날짜 범위 선택기를 조정하세요.

> ⚠️ 전환율·완료율·점유율이 100%를 넘으면 ⚠ 아이콘이 표시됩니다. 이벤트 기록 누락 등 데이터 정합성 점검이 필요하다는 신호일 수 있습니다.

> ⚠️ 선 차트는 데이터가 모두 0이면 "조회 기간 내 데이터가 없습니다." 를 표시합니다. 데이터가 없다면 기간을 더 넓혀 보세요.

---

## 요일 × 시간대 히트맵

![요일 × 시간대 히트맵 — 피크 시간대 파악(터치/완료 세션 전환)](screenshots/analytics-weekday-hour-heatmap.png)

**요일 × 시간대 히트맵** 은 선택한 기간의 이벤트를 요일과 시간(0~23시)으로 나누어 보여주는 표입니다. 색이 진할수록 건수가 많다는 뜻이라, 언제 손님이 가장 많은지(피크 시간)를 한눈에 파악할 수 있습니다.

### 화면 요소

- 좌측 첫 열 헤더는 **요일/시**, 우측과 하단에는 **합계** 가 표시됩니다.
- **터치 / 완료 세션** 세그먼트 컨트롤: 히트맵에 표시할 지표를 **터치** 또는 **완료 세션** 중에서 고릅니다.
- 데이터가 없으면 **표시할 데이터가 없습니다.** 와 함께 "조회 기간 내 해당 이벤트가 없습니다. 기간을 넓혀 보세요." 안내가 나옵니다.

### 피크 시간대 확인 방법

1. **요일 × 시간대 히트맵** 섹션으로 스크롤합니다.
2. 세그먼트 컨트롤에서 **터치** 또는 **완료 세션** 지표를 선택합니다.
3. 표에서 색이 진한 요일·시간대(피크 시간)를 확인합니다.
4. 우측과 하단의 **합계** 로 요일별·시간대별 총계를 확인합니다.

> 💡 히트맵과 추이는 모두 Asia/Seoul(한국 시간) 기준으로 요일·시간을 계산합니다.

---

## 주간 리포트 다운로드

**주간 리포트 다운로드** 카드는 선택한 기간의 일자별 요약과 점유율 상위 광고를 파일로 내보내는 기능입니다. 카드 부제에 현재 선택한 기간이 표시됩니다.

### 화면 요소

- **CSV** 버튼: 주간 리포트를 CSV 파일로 저장합니다(파일명 예: `주간리포트_시작일_종료일.csv`).
- **Excel** 버튼: 주간 리포트를 Excel(.xls) 파일로 저장합니다.

### 리포트를 내보내는 방법

1. **기간 분석** 에서 원하는 기간을 먼저 선택합니다.
2. **주간 리포트 다운로드** 카드로 이동합니다.
3. **CSV** 또는 **Excel** 버튼을 클릭합니다.
4. 다운로드된 파일에서 일자별 요약·합계·점유율 상위 광고를 확인합니다.

> 💡 다운로드 파일은 현재 화면에서 고른 기간을 그대로 반영합니다. 원하는 기간을 먼저 맞춘 뒤 내려받으세요.

---

## 광고 노출 점유율 · 설문 성과

![광고 노출 점유율·설문 성과 표](screenshots/analytics-ad-share-survey.png)

### 광고 노출 점유율

어떤 광고가 얼마나 노출되었는지를 표로 보여줍니다.

| 컬럼 | 의미 |
| --- | --- |
| 광고 | 광고 이름(클릭 시 광고 상세로 이동) |
| 노출 수 | 노출된 횟수 |
| 총 노출시간 | 누적 노출 시간 |
| 점유율 | 전체 노출시간 중 비중 |

> ⚠️ 종료 시각이 기록되지 않은 '진행 중 노출'은 점유율 집계에서 제외되며, 그 건수는 표 하단에 안내됩니다. 삭제된 광고는 **(삭제된 광고)** 로 표시되고 링크되지 않습니다.

> 💡 '점유율'은 노출시간을 기준으로 합니다. 터치는 3개 패널이 동시에 노출되어 특정 광고에 귀속되지 않으므로, 소재(광고 콘텐츠) 성과 지표가 아니라 스케줄 노출을 점검하는 용도입니다.

### 설문 성과

설문별 응답 성과를 표로 보여줍니다.

| 컬럼 | 의미 |
| --- | --- |
| 설문 | 설문 이름(클릭 시 응답 화면으로 이동) |
| 세션 수 | 설문이 시작된 세션 수 |
| 완료 수 | 설문을 끝까지 마친 수 |
| 완료율 | 완료 수 ÷ 세션 수 |
| 평균 소요시간 | 완료 세션의 시작~완료 평균 시간 |

> ⚠️ 삭제된 설문은 **(삭제된 설문)** 으로 표시되며 링크되지 않습니다.

---

## 기기 비교

![기기 비교 — 지표별 상위 막대 랭킹과 세션화율/완료율 포함 표](screenshots/analytics-device-comparison.png)

**기기 비교** 는 여러 키오스크의 성과를 지표별로 나란히 견주어 보는 섹션입니다. 상위 10대 막대 랭킹과 함께 전체 기기를 정렬해 볼 수 있는 표를 제공합니다.

### 화면 요소

- **터치 / 세션 / 완료 / 완료율 / 시간당 터치** 세그먼트 컨트롤: 막대 랭킹의 정렬 기준을 고릅니다. 막대는 상위 10대만 표시되며, 전체는 아래 표를 참고합니다.
- 비교 표 컬럼: **기기명 / 터치 / 세션 / 완료 / 세션화율 / 완료율 / 가동시간 / 가동시간당 터치**. 기기명을 클릭하면 해당 기기 상세로 이동합니다.

### 기기별로 비교하는 방법

1. **기기 비교** 섹션으로 이동합니다.
2. 지표 세그먼트(**터치 / 세션 / 완료 / 완료율 / 시간당 터치**)로 정렬 기준을 선택합니다.
3. 상위 10대 막대 랭킹을 확인합니다.
4. 하단 표에서 세션화율·완료율·가동시간당 터치 등 전체 기기를 비교합니다.
5. 기기명을 클릭해 기기 상세로 들어가 더 자세히 확인합니다.

> 💡 '세션화율'은 세션 ÷ 터치, '완료율'은 완료 ÷ 세션입니다. '가동시간당 터치'의 분모는 기간 내 기기가 온라인이었던 누적 시간입니다.

---

## 노출 추이

**노출 추이** 는 광고 노출 건수의 일별 흐름을 보여주는 선 차트(보라)입니다. 차트 캡션에 "기기가 온라인인데 노출이 0이면 광고 재생 실패 신호입니다." 라는 안내가 있습니다.

> ⚠️ 기기가 온라인 상태인데도 노출이 0으로 나온다면 광고 재생에 실패하고 있다는 신호일 수 있습니다. 해당 기기의 상태를 점검하세요.

---

## 데이터를 불러오지 못할 때

데이터 로드 중 문제가 생기면 "데이터를 불러오는 중 오류가 발생했습니다." 라는 문구와 함께 **다시 시도** 버튼이 나타납니다. **다시 시도** 를 눌러 다시 조회하세요.

> ⚠️ 장기 추이 집계 범위는 계정 역할에 따라 다릅니다. 전체 관리자는 모든 데이터를, 기업(enterprise) 계정은 자기 기업 데이터만 집계해서 봅니다.


# 기기 관리 (기기 목록)

**기기 관리** 화면은 등록된 키오스크 기기를 한 화면에서 조회·검색·필터하고, 상태·건강·소유 기업을 관리하는 목록 화면입니다. 새 기기를 등록하고, 정보를 수정·삭제하며, 여러 기기를 한꺼번에 다루는 일괄 작업(광고·설문·보상·프로파일·원격 명령)의 출발점이기도 합니다.

접속은 로그인 페이지(https://admin.adluck7.com)에서 로그인한 뒤 사이드바의 **기기 관리** 메뉴를 눌러 들어옵니다.

> ⚠️ 이 페이지는 **super_admin**·**enterprise** 역할을 가진 계정만 접근할 수 있습니다. 두 역할에 따라 보이는 항목이 조금씩 다릅니다.

## 기기 목록 살펴보기

![기기 관리 목록 전체 화면 — 상태 요약 칩, 검색, 표 컬럼(기기명/상태/건강/마지막 연결)](screenshots/devices-list-overview.png)

기기 관리 페이지에 들어오면 상단에 페이지 제목 **기기 관리** 와 부제 *등록된 키오스크 기기를 조회하고 상태·소유 기업을 관리합니다.* 가 보이고, 그 아래로 상태 요약 칩과 기기 목록 표가 나타납니다.

### 화면 요소

| 요소 | 설명 |
| --- | --- |
| **새 기기 등록** | 헤더 우측 버튼. 기기 등록 모달을 엽니다. 목록이 비어 있을 때는 화면 가운데 안내 영역에도 같은 버튼이 표시됩니다. |
| **전체 {N}대 / 온라인 {N} / 오프라인 {N}** 칩 | 상단 상태 요약 필터 칩. 누르면 전체·온라인·오프라인으로 목록이 걸러집니다. |
| **태그** 영역 | 기기 태그가 하나라도 있으면 나타나는 태그 필터 영역입니다. |
| 검색창 | placeholder `기기명·위치·일련번호·기업 검색`. 여러 항목으로 한 번에 검색합니다. |
| **상태 (온라인/오프라인/점검중)** | 표 상단의 상태 드롭다운 필터입니다. |
| 표 컬럼 | **기기명 / 일련번호 / 위치 / 소유 기업 / 상태 / 건강 / 마지막 연결** |

표에서 **기기명**을 누르면 해당 기기의 상세 페이지로 이동합니다. **소유 기업**이 지정되지 않았으면 *미할당*, 이름을 확인할 수 없으면 *이름 미확인* 으로 표시됩니다. **건강** 컬럼은 정상/주의/위험 뱃지로, **마지막 연결** 은 오프라인일 때 경과 시간으로 나타납니다.

> 💡 목록은 30초마다 백그라운드로 자동 새로고침되어 **마지막 연결** 과 온·오프라인 판정이 최신 상태로 유지됩니다(화면이 깜빡이며 다시 로딩되지 않습니다).

> 💡 검색은 기기명뿐 아니라 위치·일련번호·소유 기업명으로도 됩니다.

### 상태 칩과 경고 배너

상단 요약 칩(**전체 / 온라인 / 오프라인**)을 누르면 목록이 그 상태로 걸러집니다. 태그가 있으면 태그 칩을 눌러 추가로 좁힐 수 있고, **태그 해제** 버튼으로 선택한 태그를 모두 초기화합니다.

기기 상태에 따라 목록 위쪽에 경고 배너가 뜹니다.

- 최근 24시간 안에 이상이 감지되면 *위험 기기 {N}대 · 주의 기기 {N}대 — 최근 24시간 내 이상이 감지되었습니다. 기기 상세의 건강 이력을 확인하세요.* 배너가 표시됩니다.
- 키오스크 앱이 자동으로 만든 미등록 기기가 있으면 *미등록 기기 {N}대 — 이름·위치·소유 기업을 설정해 주세요.* 배너가 표시됩니다.

> 💡 상단 칩(온라인/오프라인)과 표의 상태 뱃지는 모두 heartbeat 기준으로 통일되어 있어 서로 일치합니다(*점검중* 상태만 수동으로 설정한 값이 유지됩니다).

> 💡 **건강** 컬럼은 최근 24시간의 이상 감지를 정상/주의/위험으로 요약합니다. 자세한 내용은 기기 상세의 **건강** 탭에서 확인하세요.

## 새 기기 등록하기

![새 기기 등록 모달 — '앱 기기 매칭' 방식과 미등록 기기 선택](screenshots/devices-list-register-modal-match.png)

**새 기기 등록** 버튼을 누르면 등록 모달이 열립니다. 모달 상단의 **등록 방식** 토글에서 **앱 기기 매칭**(기본값)과 **수동 등록** 중 하나를 고릅니다.

### 앱 기기 매칭으로 등록

키오스크 앱을 켜면 자동으로 미등록 기기(`Kiosk-xxxxxxxx`)가 만들어집니다. 이 방식은 그 기기를 골라 이름·위치를 채워 넣는 방법입니다.

1. **새 기기 등록** 을 누릅니다.
2. **등록 방식** 에서 **앱 기기 매칭** 을 선택합니다(기본값).
3. **미등록 기기 선택** 드롭다운(`기기를 선택하세요`)에서 자동 생성된 기기를 고릅니다. 선택하면 ID·일련번호·기기 정보 카드가 나타납니다.
4. **기기 이름**(필수, placeholder `예: 강남점 1번`)과 **설치 위치**(placeholder `예: 서울 강남구 역삼동`)를 입력하고 **상태** 를 선택합니다.
5. (super_admin) **소유 기업 계정** 을 지정합니다.
6. **등록** 을 누릅니다. 성공하면 토스트 *기기가 매칭되었습니다.* 가 뜹니다.

> ⚠️ 매칭할 미등록 기기가 없으면 드롭다운에 *매칭 가능한 미등록 기기가 없습니다.* 가 표시됩니다. 기기를 고르지 않으면 **등록** 버튼이 비활성 상태로 남습니다.

### 수동 등록

아직 앱이 연결되지 않은 기기를 미리 등록해 둘 때 사용합니다.

1. **새 기기 등록** → **등록 방식** 에서 **수동 등록** 을 선택합니다.
2. **기기 이름**(필수)·**설치 위치** 를 입력하고 **상태** 를 선택합니다.
3. (super_admin) **소유 기업 계정** 을 지정합니다.
4. **등록** 을 누릅니다. 토스트 *기기가 등록되었습니다.* 가 뜹니다.

> ⚠️ **소유 기업 계정** 선택 필드는 super_admin에게만 보입니다. enterprise 계정으로 등록하면 소유 기업이 본인 계정으로 자동 지정됩니다. 안내 문구: *키오스크는 여기 매핑된 기업 계정으로 로그인해야 자기 광고/설문에 접근할 수 있습니다.*

> ⚠️ 소유 기업 후보는 루트 기업 계정만 나옵니다. 위임된 하위 계정을 소유자로 지정하면 기기가 고아 상태가 되어 기업이 조회하지 못할 수 있으니 주의하세요.

### 다른 기기 설정 복사하며 등록

신규 등록 시에는 이미 운영 중인 기기의 설정을 그대로 가져올 수 있습니다.

1. 신규 등록 모달에서 기본 정보를 입력합니다.
2. **설정 복사** 영역의 **다른 기기에서 설정 복사** 를 체크합니다.
3. **복사 원본 기기** 를 선택합니다.
4. **복사할 설정 항목** 을 체크합니다(QR 화면 설정/디스펜서 설정/게임 설정/플로우 설정/퍼즐 격자 크기/태그). 원본에 없는 항목은 선택할 수 없습니다.
5. 필요하면 **이 기기 대상 보상 복제**·**광고 스케줄 복제** 를 체크합니다.
6. **등록** 을 누릅니다. 토스트 *설정 복사 완료 — 보상 N건, 광고 스케줄 N건* 이 뜹니다.

> 💡 설정 복사는 신규 등록할 때만 가능합니다. 이름·위치·일련번호·소유 기업 같은 식별 정보는 복사되지 않습니다.

## 기기 수정·삭제하기

표의 각 행 오른쪽 끝에 있는 케밥(작업 메뉴) 아이콘을 누르면 작업 메뉴가 열립니다.

### 수정 / 등록

일반 기기는 **수정**, 미등록 기기는 **등록** 라벨로 같은 모달이 열립니다.

1. 대상 행의 케밥 메뉴를 엽니다.
2. **수정**(미등록 기기는 **등록**)을 선택합니다.
3. 이름·위치·상태·(super_admin)소유 기업을 변경합니다.
4. **수정** 을 누릅니다. 토스트 *기기 정보가 수정되었습니다.* 가 뜹니다.

> 💡 미등록(`Kiosk-xxxxxxxx`) 기기는 이름·위치·소유 기업을 채우면 **미등록** 뱃지가 사라집니다. 뱃지에 마우스를 올리면 *키오스크 앱이 자동 생성한 기기입니다. 수정에서 이름·위치·소유 기업을 설정하면 뱃지가 사라집니다.* 안내가 보입니다.

### 삭제

1. 대상 행의 케밥 메뉴에서 **삭제** 를 선택합니다.
2. 확인 창의 *"{기기명}" 기기를 삭제하시겠습니까?* 에서 확인합니다.
3. 토스트 *기기가 삭제되었습니다.* 가 뜹니다.

> ⚠️ 기기를 삭제하면 선택 목록에서도 자동으로 빠집니다. 삭제된 기기가 일괄 작업에 섞여 잘못된 결과가 생기는 것을 막기 위한 동작입니다.

## 여러 기기 한꺼번에 다루기 (일괄 작업)

![기기 여러 대 선택 시 나타나는 일괄 작업 바(광고/설문/보상/프로파일/원격 명령)](screenshots/devices-list-bulk-actions-bar.png)

여러 기기를 선택하면 목록 위에 강조된 **{N}대 선택됨** 바가 나타나, 선택한 기기 전체에 한 번에 작업을 적용할 수 있습니다.

### 작업 단계

1. 각 행의 체크박스로 기기를 선택하거나, 표 헤더의 **현재 목록 전체 선택** 을 눌러 지금 걸러진 목록 전체를 선택합니다.
2. **{N}대 선택됨** 바에서 원하는 작업을 고릅니다.
3. 모달에서 세부 설정을 마친 뒤 실행합니다.
4. **선택 해제** 로 마무리합니다.

### 일괄 작업 버튼

| 버튼 | 하는 일 |
| --- | --- |
| **광고 일괄 배정** | 선택한 기기에 광고를 한 번에 배정합니다. |
| **설문 일괄 할당** | 선택한 기기에 설문을 일괄 할당합니다. |
| **보상 일괄 생성** | 선택한 기기를 대상으로 보상을 일괄 생성합니다. |
| **프로파일 적용** | 저장된 기기 프로파일을 선택 기기에 일괄 적용합니다. 적용 후 선택이 해제되고 목록이 새로고침됩니다. |
| **원격 명령** | 선택한 기기에 원격 명령을 한꺼번에 보냅니다. |
| **응답 내보내기** | **선택한 기기들의 설문 응답을 CSV로 내려받습니다.** 아래 설명 참고. |
| **선택 해제** | 지금 선택한 기기를 모두 해제합니다. |

> 💡 **설문 응답을 파일로 받고 싶다면 여기입니다.** 기기 관리에서 기기를 체크 → 상단 일괄 작업 바의 **응답 내보내기** → 기간(최근 30일 / 전체 기간 등)을 고르면, **설문별 표(wide) + 전체 통합 표(long)** 를 묶은 **ZIP** 파일이 내려받아집니다. 엑셀에서 바로 열 수 있습니다.

> ⚠️ **원격 명령** 버튼은 선택한 모든 기기에 명령 실행 권한이 있을 때만 보이며, 서버에서 최종적으로 거부될 수도 있습니다.


# 기기 상세 — 광고 배치 (자유 캔버스)

키오스크 세로 화면(9:16)에 광고·게임·QR·정적(이미지/텍스트) 요소를 자유롭게 드래그·리사이즈·회전으로 배치하고, 여러 장면(씬)으로 구성하는 화면입니다. 편집한 내용은 2초 뒤 자동으로 저장되고, 버전이 자동 기록되어 언제든 이전 상태로 되돌릴 수 있습니다.

**기기 관리**에서 기기를 선택 → 상세 화면 상단 탭에서 **광고 배치** 탭(첫 번째·기본 탭)으로 진입합니다.

> ⚠️ 저장·자동저장·실행 취소/다시 실행·요소 편집은 모두 **기기 편집(devices:write)** 권한이 있어야 동작합니다. 권한이 없으면 **저장** 버튼이 비활성화되고 캔버스는 읽기 전용(요소 클릭만 가능)입니다.

## 화면 한눈에 보기

![광고 배치 탭의 3-패널 자유 캔버스 에디터 전체 화면(좌: 버전 이력, 중앙: 9:16 캔버스, 우: 요소 패널)](screenshots/device-canvas-overview.png)

화면은 크게 세 부분으로 나뉩니다.

| 영역 | 위치 | 하는 일 |
| --- | --- | --- |
| **버전 이력** | 좌측 패널 | 저장된 버전을 최신순으로 최대 20개 표시, **복원** 제공 |
| 캔버스 | 중앙 | 9:16 검정 프레임에 요소를 배치·이동·크기 조절·회전 |
| **요소 추가** / 편집 패널 | 우측 | 요소 추가, 선택한 요소·씬·재생 설정 편집 |

상단 툴바에는 **저장**, **게임 미리보기**, **실행 취소** / **다시 실행** 버튼이 있습니다.

- **저장**: 현재 레이아웃을 수동 저장합니다. 변경이 없거나 저장 중이거나 권한이 없으면 비활성화되며, 저장 중에는 `저장 중...`으로 표시됩니다. 성공하면 `레이아웃이 저장되었습니다.` 토스트가 뜹니다.
- **실행 취소** / **다시 실행**: `Cmd/Ctrl+Z`로 실행 취소, `Shift+Cmd/Ctrl+Z`로 다시 실행합니다. 이 단축키는 **광고 배치** 탭에서만 동작합니다.
- **게임 미리보기**: 이 기기의 게임 설정으로 게임을 모달에서 시뮬레이션합니다.

> 💡 편집 후 2초간 조작이 없으면 자동으로 저장됩니다(버전 라벨 `자동`). 연속으로 드래그하는 동안에는 타이머가 리셋되어 버전이 폭증하지 않습니다.

> ⚠️ 다른 탭에서는 저장 버튼 자리에 **변경 사항은 각 항목에서 저장됩니다** 안내가 뜹니다. 통합 저장은 **광고 배치** 탭에만 있습니다.

## 요소 추가하기


캔버스 빈 곳을 클릭해 선택을 해제하면, 우측에 **요소 추가** 패널이 나타나고 `캔버스에 추가할 요소를 선택하세요.` 안내와 함께 4개 버튼이 보입니다.

| 버튼 | 캔버스에 추가되는 것 |
| --- | --- |
| **광고** | 광고 썸네일과 제목이 나오는 광고 영역 |
| **게임** | 퍼즐 게임(🎮) 영역 |
| **QR** | QR 코드 영역 |
| **정적 (이미지·텍스트)** | 고정 이미지 또는 텍스트 |

작업 순서:

1. 캔버스 빈 곳을 클릭해 선택을 해제합니다.
2. **광고** / **게임** / **QR** / **정적 (이미지·텍스트)** 중 원하는 버튼을 클릭합니다.
3. 캔버스에 생긴 상자를 드래그로 옮기고, 핸들로 크기를 조절합니다.
4. 우측 편집 패널에서 세부 설정을 지정합니다(아래 각 요소 설명 참고).

## 요소 선택과 위치·크기 조절


배치한 요소를 클릭하면 하늘색 아웃라인으로 선택됩니다.

- 드래그 = 이동, 8방향 핸들 = 크기 조절, 상단 점 = 회전, 빈 곳 클릭 = 선택 해제
- 우측 **위치 · 크기 (%)** 패널에서 X / Y / 너비 / 높이 / 회전(°) / z-index를 수치로 직접 입력할 수 있습니다.
- **맨 앞** / **맨 뒤** 버튼으로 겹친 요소의 앞뒤 순서(z-order)를 바꿉니다.
- 패널 헤더의 **닫기** 버튼으로 선택을 해제하고, 하단 **요소 삭제** 버튼으로 선택한 요소를 캔버스에서 제거합니다.

> 💡 드래그·리사이즈·회전은 제스처 단위로 한 번에 실행 취소됩니다. 잘못 옮겼다면 `Cmd/Ctrl+Z`로 바로 되돌리세요.

### 광고 요소

광고 요소를 선택하면 우측에 **광고 (다중 선택 — 순환 재생)** 목록이 나옵니다.

1. 목록에서 표시할 광고를 선택합니다. 여러 개를 고르면 순환 재생 풀이 됩니다.
2. 선택한 광고는 **해제**로 뺄 수 있습니다.
3. 각 행의 **연필(수정)** 아이콘으로 그 광고의 내용을 고칠 수 있습니다 — **이미지·영상 교체**, 제목, 노출 시간, 게임 광고의 카드 이미지·원본 이미지·배경까지 모두 바꿀 수 있습니다. 미디어를 바꾸려고 광고를 새로 만들 필요가 없습니다.
4. 각 행의 **휴지통** 아이콘은 광고 자체를 삭제합니다.
5. 새 광고가 필요하면 **새 광고 등록** 버튼으로 등록합니다.

> ⚠️ 광고 수정은 **광고 문서 자체**를 바꿉니다. **이 광고를 사용하는 다른 기기에도 함께 반영**되므로, 특정 기기에서만 다르게 쓰고 싶다면 광고를 복제해 쓰세요(수정 창 상단에도 같은 안내가 표시됩니다).

> 💡 여러 광고를 넣으면 기기의 재생 방식(플레이리스트: 랜덤 순환 / 가중치 확률)에 따라 순환 재생됩니다.

> ⚠️ **새 광고 등록** 버튼은 **광고 쓰기(ads:write)** 권한이 있는 계정만 보입니다. 또한 게임(puzzle)이 아닌 광고만 후보로 표시됩니다.

### 게임 요소

게임 요소를 선택하면 **게임 광고 (puzzle)**와 **게임 스타일 (기기 기본)** 섹션이 나옵니다.

1. **게임 광고 (puzzle)**에서 puzzle 타입 광고를 하나 선택합니다. 없으면 `puzzle 타입 광고가 없습니다.`가 표시됩니다.
2. **게임 제한시간(초, 0=무제한)**을 입력합니다(광고에 저장됩니다).
3. **게임 스타일 (기기 기본)**에서 테마 프리셋·색상·타이밍·시작 이펙트·완료 흐름·오디오 볼륨(배경음 BGM·효과음 SFX)·음원 URL 등을 조정합니다.
4. 상단 **게임 미리보기**로 결과를 확인합니다.

**게임 배경**은 다음 순서로 정해집니다.

1. 게임 광고에 **배경 이미지·영상**(광고의 미디어)이 있으면 그것이 우선합니다.
2. 없으면 게임 스타일의 **배경색**(색상 섹션의 「배경색」)이 쓰입니다.
3. 배경색도 비어 있으면 기기 기본 배경이 나옵니다.

> ⚠️ 게임 그리드가 올바르지 않으면(memory_pair는 행×열이 짝수여야 함) 저장이 막히고 오류 토스트가 뜹니다.

### QR 표시 위치 요소 · QR 화면 설정

**QR 화면 설정은 모든 씬에 공통으로 적용됩니다.** 그래서 두 곳 중 어디서 열어도 **같은 편집 화면**이 나옵니다.

- **기기 공통 → QR 화면**: 요소를 선택하지 않은 상태의 우측 패널에 있습니다. 씬에 QR 요소가 없어도 편집할 수 있습니다.
- **씬의 「QR 표시 위치」 요소 선택**: 위치·크기와 함께 같은 설정이 이어서 나옵니다.

편집 항목:

1. **배치 모드** — 비율(중앙 고정) 또는 자유 배치.
2. **문구·타이머** — 제목, 부제, 자동 닫힘 시간(초), 하단 안내 문구, 닫기 버튼 라벨(기본 `닫기`), 경고 임계(초, 기본 60)와 경고색(기본 `#FFB4B4`), **QR 스캔 후에도 유지** 옵션.
3. **카드 스타일** — 글라스/단색/없음, 배경색, 불투명도, 모서리, 카드 폭.
4. 하단 미리보기로 최종 모습을 확인합니다(자유 배치에서는 미리보기에서 QR 상자를 드래그해 미세 조정할 수 있습니다).

> 💡 **「QR 표시 위치」 요소는 QR이 뜰 자리를 잡는 기준**입니다. 손님이 터치하는 버튼이 아닙니다 — 아래 안내대로 **화면 어디를 터치해도** QR이 뜹니다. 이 요소는 기기 화면에 보이지 않습니다.

> ⚠️ **QR 크기(%)** 는 비율 모드에서만 쓰이며, 기준은 **카드 내부 폭**입니다. 실제 크기는 기기 화면 밀도에 따라 달라져 캔버스에는 미리보기를 그리지 않습니다(아래 미리보기로 확인하세요). 자유 배치에서는 캔버스의 박스 크기로 조절됩니다.

### 손님이 QR을 여는 방법

**화면 어디를 터치해도 설문 QR이 열립니다.** 광고 영역이든, 이미지·문구 같은 정적 영역이든, 빈 여백이든 상관없습니다.

예외는 **게임의 조작 부분**입니다 — 퍼즐 카드, 게임 시작/완료 안내를 누르면 게임이 반응하고 QR은 뜨지 않습니다.

QR이 열리려면 두 조건이 모두 맞아야 합니다.

- 스케줄의 **광고 터치 동작**이 「무반응」이 아닐 것
- 스케줄의 **QR(설문) 창**이 허용 시간대일 것 · 그리고 이 기기에 **노출 중인 설문**이 있을 것

### 정적 요소 (이미지·텍스트)

정적 요소는 **유형** 토글로 이미지/텍스트를 고릅니다.

- **이미지**: 이미지 URL 입력 또는 파일 업로드
- **텍스트**: 텍스트, 글자 크기, 글자 색, 굵기(보통·굵게), 정렬(왼쪽·가운데·오른쪽)
- 공통: 배경 색(비우면 투명)

> 💡 QR·게임 스타일 값을 비우면 키오스크 기본값(폴백)이 쓰입니다. 입력란 placeholder에 표시된 `기본 …` 값이 바로 그 폴백입니다.

## 여러 장면(씬) 구성


캔버스 상단의 **장면** 스트립에서 여러 화면을 만들어 번갈아 재생할 수 있습니다. 각 씬 버튼에는 씬 이름(또는 `씬 N`)과 표시 시간(`{n}s`)이 나옵니다.

우측 아이콘 버튼: **씬 추가**(+), **현재 씬 복제**, **현재 씬 앞으로**(◀), **현재 씬 뒤로**(▶), **현재 씬 삭제**(휴지통).

요소를 선택하지 않은 상태에서 우측 **씬 설정 (현재 씬)** 패널에 다음 필드가 있습니다.

| 필드 | 설명 |
| --- | --- |
| 이름 | 미설정 시 `씬 N`으로 표시 |
| 표시 시간(초) | 이 시간이 지나면 다음 씬으로 전환 |
| 가중치 | 재생 비중(placeholder `1`) |
| 영상 반복(회) | 비우면 표시 시간 기준 |

그 아래 **재생 설정 (기기 기본)**에는 **영상 전환 시간(초)** 필드가 있습니다. 영상 광고를 이 시간만큼 표시한 뒤 전환합니다.

작업 순서:

1. **씬 추가**(+) 또는 **현재 씬 복제**로 씬을 만듭니다.
2. 씬 버튼을 클릭해 편집할 씬으로 전환합니다.
3. **씬 설정 (현재 씬)**에서 이름·표시 시간·가중치·영상 반복을 조정합니다.
4. **현재 씬 앞으로** / **현재 씬 뒤로**로 순서를 바꿉니다.
5. 자동저장되거나 **저장**을 누릅니다.

> 💡 씬은 표시 시간이 지나면 다음 씬으로 전환됩니다. 단, 게임 플레이·설문 진행 중에는 전환이 보류됩니다.

> ⚠️ 씬은 최소 1개가 유지되어야 하며, 씬이 1개면 **현재 씬 삭제**가 비활성화됩니다.

## 이전 버전으로 복원


좌측 **버전 이력** 패널은 저장된 버전을 최신순으로 최대 20개 보여줍니다. 각 항목은 `v{번호} (자동/수동/복원/이관)`, 시각, `N씬 · M개 요소` 요약으로 구성됩니다. 저장된 버전이 없으면 `저장된 버전이 없습니다 / 레이아웃을 저장하면 버전이 자동으로 기록됩니다.`가 표시됩니다.

1. **버전 이력**에서 되돌릴 버전(v번호·시각)을 찾습니다.
2. 해당 항목의 **복원**을 클릭하면 캔버스가 그 버전으로 되돌아갑니다.
3. 확인 후 **저장**하면 복원 상태가 새 버전으로 기록됩니다.

> 💡 버전 이력은 최신 20개까지만 롤링 보관되고, 오래된 버전은 자동 정리됩니다. **복원** 버튼은 쓰기 권한이 있는 계정만 보입니다.

> ⚠️ 캔버스는 씬 계층(schema v3)으로 저장되며 키오스크 2.2.0 이상이 필요합니다. 구버전과는 호환되지 않으니, 현장 키오스크 앱 버전을 함께 확인하세요.


# 기기 상세 — 스케줄

기기가 **시간대·요일별로 다르게 동작**하도록 규칙을 정하는 곳입니다. 광고 화면을 터치했을 때의 동작, 그 시간에 순환할 씬, 설문 QR 진입 허용 여부를 각각 규칙으로 지정할 수 있습니다. 규칙이 없는 시간대는 키오스크 기본 동작(터치 → 설문 QR · 전 씬 순환 · QR 허용)을 그대로 따릅니다.

**기기 관리**에서 기기를 선택 → 상세 화면 상단 탭에서 **스케줄**을 눌러 진입합니다.

> ⚠️ 규칙을 편집·저장하려면 **기기 편집(devices:write)** 권한이 있는 계정이어야 합니다. 권한이 없으면 **+ 규칙 추가**·↑/↓·**삭제**·입력칸·**스케줄 저장**이 보이지 않거나 비활성 상태이며, 화면은 읽기 전용으로만 표시됩니다.

## 화면 한눈에 보기

![스케줄 탭 전체 — 타임라인 미리보기와 3개 유형 규칙 섹션](screenshots/device-schedule-overview.png)

스케줄 탭은 크게 두 부분으로 되어 있습니다.

- 위쪽: **타임라인 미리보기** — 선택한 요일의 하루 동작을 색 막대로 보여 줍니다.
- 아래쪽: 세 종류의 규칙 섹션 — **광고 터치 동작**, **씬 편성 창**, **QR(설문) 창**.

각 규칙 섹션은 서로 독립적으로 동작하므로, 필요한 종류만 규칙을 추가하면 됩니다.

## 타임라인 미리보기

![타임라인 미리보기 — 요일 버튼과 유형별 색 막대(보라/초록/주황)](screenshots/device-schedule-timeline-preview.png)

지금 설정한 규칙이 하루 동안 어떻게 적용되는지 색 막대로 미리 확인하는 곳입니다.

**화면 요소**

- **일 월 화 수 목 금 토** 원형 버튼: 미리보기로 볼 요일을 고릅니다(기본값은 오늘 요일).
- 색 막대: 유형별로 색이 다릅니다.
  - 보라 = **광고 터치 동작**
  - 초록 = **씬 편성 창**
  - 주황 = **QR(설문) 창**
- **0시 / 6시 / 12시 / 18시 / 24시**: 막대 아래 시간 눈금입니다.
- 미리보기 아래 안내: **규칙이 없는 시간대의 기본 동작 — 광고 터치: 설문 QR · 씬: 전체 순환 · QR: 허용. 같은 유형이 겹치면 목록의 위 규칙이 우선합니다.**

> 💡 요일 버튼을 바꿔 가며 요일마다 다른 규칙이 어떻게 겹치는지 확인해 보세요. **사용** 체크를 해제한 규칙은 미리보기에서 빠집니다.

## 규칙 카드 공통 요소

세 섹션 모두 규칙은 카드 형태로 추가되며, 다음 요소를 공통으로 가집니다.

| 요소 | 설명 |
| --- | --- |
| **사용** | 규칙을 켜고 끄는 체크박스. 해제하면 규칙을 지우지 않고 임시로 비활성화됩니다(카드가 흐려지고 미리보기에서 제외). |
| **시작 시각** / **끝 시각** | 규칙이 적용될 시간(HH:mm)을 지정합니다. |
| **(자정 넘김)** | 시작 시각이 끝 시각보다 크면 표시되며, 자정을 넘기는 구간으로 처리됩니다(예: 22:00~06:00). |
| **요일** | 일~토 원형 버튼으로 적용 요일을 고릅니다. 전체 해제하면 **= 매일**로 표시됩니다. |
| **↑** / **↓** | 같은 유형에서 규칙 우선순위를 올리거나 내립니다(위 규칙이 우선). |
| **삭제** | 규칙을 삭제합니다(빨간색). |

각 유형 섹션 머리의 **+ 규칙 추가** 버튼으로 새 규칙을 만들면 기본값(09:00~18:00, 사용=켬, 요일=매일)으로 추가됩니다.

> 💡 같은 유형의 규칙이 시간대에서 겹치면 목록에서 **위에 있는 규칙이 우선**합니다. ↑/↓로 순서를 조정하세요.

## 광고 터치 동작


광고 화면을 손님이 터치했을 때 무엇을 할지 시간대별로 정하는 곳입니다. 규칙이 하나도 없으면 **규칙 없음 — 광고 터치 시 항상 설문 QR이 뜹니다.** 안내가 표시됩니다.

카드에는 공통 요소 외에 **터치 동작** 셀렉트가 있습니다.

- **설문 QR 표시** — 터치하면 설문 QR을 띄웁니다.
- **게임 씬으로 전환** — 터치하면 게임 씬으로 넘어갑니다.
- **무반응** — 터치해도 아무 동작을 하지 않습니다.

**예시: 저녁 시간대에만 게임으로 전환하기**

1. **광고 터치 동작** 섹션에서 **+ 규칙 추가**를 누릅니다.
2. **시작 시각** / **끝 시각**을 지정합니다.
3. **터치 동작**에서 **게임 씬으로 전환**을 선택합니다.
4. **요일** 버튼으로 적용 요일을 고릅니다(전체 해제 = 매일).
5. **스케줄 저장**을 누르고 **스케줄이 저장되었습니다. 키오스크는 다음 콘텐츠 갱신 시 반영합니다.** 토스트를 확인합니다.

> ⚠️ **게임 씬으로 전환**을 골라도 이 기기 캔버스에 게임 씬이 없으면 실제로는 무반응이 됩니다. 이 경우 **⚠ 이 기기 캔버스에 게임 씬이 없습니다 — "게임 씬으로 전환"은 무반응이 됩니다.** 경고가 표시됩니다.

## 씬 편성 창

특정 시간대에 **일부 씬만** 순환하도록 제한하는 곳입니다. 규칙이 없으면 **규칙 없음 — 모든 씬이 항상 순환합니다.** 안내가 표시됩니다.

카드에는 공통 요소 외에 **씬** 다중 선택이 있습니다.

- 캔버스 씬 이름 칩을 눌러 그 시간대에 순환시킬 씬만 고릅니다(게임이 포함된 씬은 🎮 표시).
- 아무 씬도 고르지 않으면 제한 없이 **전 씬**이 순환합니다.
- 캔버스에 씬이 없으면 **캔버스에 씬이 없습니다 — 광고 배치 탭에서 먼저 구성하세요.** 안내만 표시됩니다.

**작업 순서**

1. **씬 편성 창** 섹션에서 **+ 규칙 추가**를 누릅니다.
2. **시작 시각** / **끝 시각**과 **요일**을 지정합니다.
3. **씬** 칩에서 순환시킬 씬만 고릅니다(선택 없음 = 전 씬).
4. **스케줄 저장**을 누릅니다.

> ⚠️ 씬을 고르려면 **광고 배치(캔버스)** 탭에 씬이 미리 구성되어 있어야 합니다.

## QR(설문) 창

시간대별로 설문 QR 진입을 허용하거나 차단하는 곳입니다. 이 규칙은 씬 편성과 **독립된 별도 객체**이므로, 씬을 제한하더라도 QR 허용/차단은 여기서 따로 설정해야 합니다. 규칙이 없으면 **규칙 없음 — 설문 QR 진입이 항상 허용됩니다.** 안내가 표시됩니다.

카드에는 공통 요소 외에 **QR 허용 여부** 셀렉트가 있습니다.

- **QR 허용** — 그 시간대에 설문 QR 진입을 허용합니다.
- **QR 차단** — 진입을 막습니다.

**예시: 야간에 설문 QR 차단하기**

1. **QR(설문) 창** 섹션에서 **+ 규칙 추가**를 누릅니다.
2. **시작 시각** 22:00 ~ **끝 시각** 06:00을 지정하고 **(자정 넘김)** 표시를 확인합니다.
3. **QR 허용 여부**에서 **QR 차단**을 선택합니다.
4. **스케줄 저장**을 누릅니다.

## 저장과 반영

규칙을 다 만들었으면 **스케줄 저장**을 눌러 전체를 저장합니다. 저장 중에는 버튼이 **저장 중...**으로 바뀝니다.

> 💡 저장한 규칙은 키오스크에 즉시가 아니라 **다음 콘텐츠 갱신 시** 반영됩니다. 토스트 **스케줄이 저장되었습니다. 키오스크는 다음 콘텐츠 갱신 시 반영합니다.** 가 곧 갱신됨을 알려 줍니다.

> 💡 규칙을 잠시 꺼 두고 싶을 때는 삭제하지 말고 **사용** 체크를 해제하세요. 언제든 다시 켤 수 있습니다.


# 기기 상세 — 운영 (원격 명령·화면 문구)

키오스크 기기 한 대의 연결 상태를 확인하고, 멀리 떨어진 기기에 원격으로 명령을 보내며, 광고 화면에 표시되는 안내 문구를 직접 편집하는 운영 허브입니다. 콘텐츠 새로고침·앱 재시작·진단·화면 캡처 같은 작업을 즉시 또는 예약으로 발신하고, 그 결과를 기록에서 추적할 수 있습니다.

진입 방법은 간단합니다. **기기 관리**에서 원하는 기기를 선택 → 상세 화면 상단 탭에서 **운영** 탭을 누르면 됩니다.

> ⚠️ 원격 명령 카드·QR 테스트·화면 캡처는 `commands:execute` 권한이 있는 계정만 사용할 수 있습니다. 권한이 없으면 카드 대신 **원격 명령 권한이 없습니다 — 이 기기에 명령을 보내려면 commands:execute 권한이 필요합니다.** 안내만 보입니다. 광고 화면 문구 편집과 설정 프로파일은 `devices:write` 권한이 있는 계정만 보입니다.

## 연결 상태 확인하기

![운영 탭 상단: 연결 상태 카드와 원격 명령 그리드](screenshots/device-operations-overview.png)

운영 탭 맨 위의 **연결 상태** 카드에서 기기가 지금 켜져 있는지, 마지막으로 서버와 통신한 시각이 언제인지 한눈에 확인합니다.

- **온라인**: 초록색 Wifi 아이콘. 기기가 정상적으로 하트비트(주기적 신호)를 보내고 있는 상태입니다.
- **오프라인**: 빨간색 WifiOff 아이콘. 기기가 꺼져 있거나 네트워크가 끊긴 상태입니다.
- **마지막 연결**: 마지막으로 통신한 시각과 경과 시간을 함께 보여줍니다. 화면을 처음 열 때는 잠시 `확인 중…`으로 표시됩니다.

> 💡 저녁이나 영업 종료 후 기기가 오프라인으로 보이는 것은 정상일 수 있습니다. 전원이 꺼진 것일 뿐 고장이 아닙니다. 실기기 확인은 매장 운영 시간대에 하는 것이 좋습니다.

## 원격 명령 보내기

기기를 직접 만지지 않고도 여러 작업을 원격으로 지시할 수 있습니다. **원격 명령** 섹션에는 다음 안내가 표시됩니다: **명령은 기기 하트비트(최대 30초) 때 전달됩니다. 즉시 실행 또는 예약을 선택할 수 있습니다.** 기기가 오프라인이면 **기기 오프라인 — 명령은 다시 연결되면 실행됩니다** 경고가 함께 뜹니다.

### 명령 카드 종류

| 명령 | 하는 일 |
| --- | --- |
| **콘텐츠 새로고침** | 기기가 최신 광고·설문 콘텐츠를 다시 내려받습니다. |
| **앱 재시작** | 키오스크 앱을 재시작합니다. 진행 중 화면이 중단됩니다. (파괴적 명령) |
| **진단 리포트** | 기기 상태·버전·네트워크 진단 리포트를 수집합니다. |
| **화면 캡처** | 현재 기기 화면을 캡처합니다. |
| **로그 수집** | 기기 로그를 수집해 링크로 제공합니다. |

### 즉시 발신하기


1. 보내려는 명령 카드(예: **콘텐츠 새로고침**)를 클릭합니다.
2. 발신 확인 모달이 열리고 **"{명령}" 명령을 보내시겠습니까?** 문구가 표시됩니다.
3. 상단 선택에서 **즉시 실행**을 그대로 둡니다.
4. **명령 보내기**를 클릭합니다.
5. 토스트 **명령을 보냈습니다. 기기가 다음 하트비트(최대 30초) 때 실행합니다. 10분 내 미수신 시 만료됩니다.** 가 뜨면 발신 완료입니다.
6. 아래 **원격 명령 기록**에서 상태가 대기 → 전달됨 → 완료로 바뀌는지 추적합니다.

### 예약 발신하기

원하는 시각에 자동으로 실행되도록 예약할 수도 있습니다.

1. 명령 카드를 클릭해 모달을 엽니다.
2. **예약** 세그먼트를 선택합니다.
3. 나타난 **예약 시각** 입력란에 실행할 시각을 넣습니다. 브라우저의 로컬 시간대 기준이며, 현재보다 이후여야 합니다.
4. **예약하기**를 클릭합니다.
5. 토스트 **명령을 예약했습니다. 예약 시각에 대기 상태로 전환되어 기기가 실행합니다.** 가 뜹니다.

> 💡 예약된 명령은 예약 시각이 되면 대기 상태로 전환되며, 시스템이 1분 주기로 확인해 활성화합니다.

> ⚠️ **앱 재시작**은 파괴적 명령입니다. 진행 중인 화면을 중단·재시작하므로 모달에 빨간 경고(**이 명령은 기기 동작을 중단·재시작합니다. 신중히 실행하세요.**)가 표시됩니다. 영업 중에는 신중히 사용하세요.

## 기기에서 QR 테스트

**원격 명령** 섹션 하단 **QR 미리보기**에서 저장된 QR 설정이 실제 기기 화면에 어떻게 보이는지 미리 확인할 수 있습니다.

1. **기기에서 QR 테스트** 버튼을 클릭합니다.
2. 토스트 **테스트 명령을 보냈습니다. 기기 화면을 확인하세요 (약 30초간 QR 표시).** 를 확인합니다.
3. 기기 화면에서 약 30초간 QR이 표시되는지 확인합니다.

> ⚠️ 이 버튼은 **저장된** 설정을 기기가 불러와 표시합니다. 광고 배치 캔버스에 아직 저장하지 않은 변경이 있으면 버튼이 비활성화되고 저장 후 테스트하라는 안내가 뜹니다. 먼저 광고 배치 탭에서 저장하세요. 기기가 오프라인일 때도 비활성화됩니다. 전송 중에는 `전송 중…`으로 표시됩니다.

## 원격 명령 기록 보기

![원격 명령 기록 — 종류/상태 필터 칩과 결과·취소](screenshots/device-operations-command-history.png)

보낸 명령의 진행 상황과 결과를 **원격 명령 기록** 섹션에서 최근 50건까지 확인합니다. 안내 문구는 다음과 같습니다: **대기 중인 명령은 10분 내 미수신 시 만료됩니다. 기기가 이미 가져간 명령은 취소해도 실행될 수 있습니다.**

- **전체 종류 / 전체 상태** 필터 칩으로 원하는 명령만 골라 볼 수 있습니다. 상태는 예약·대기·전달됨·완료·실패·만료·취소로 나뉩니다.
- **일괄 발신** 뱃지가 붙은 항목은 여러 기기에 동시에 보낸 명령입니다.
- 결과가 있는 항목은 펼쳐서 **결과 링크 열기 / 로그 열기 / 결과 데이터**로 스크린샷 이미지·진단 표·로그 링크(줄 수 포함)·JSON을 바로 확인할 수 있습니다.

### 대기·예약 명령 취소하기

아직 실행되지 않은 명령은 취소할 수 있습니다.

1. 기록에서 대기 또는 예약 상태 항목의 **취소** 버튼을 클릭합니다. (`commands:execute` 권한이 있어야 버튼이 보입니다.)
2. **명령 취소** 확인 다이얼로그에서 다시 **명령 취소**를 클릭합니다.
3. 토스트 **명령을 취소했습니다.** 가 뜹니다.

> ⚠️ 이미 기기가 가져간(전달됨) 명령은 취소해도 기기에서 실행될 수 있습니다. 취소는 아직 기기가 가져가지 않은 명령에 확실히 적용됩니다.

> 💡 명령은 보통 약 2초 안에 전달되며, 늦어도 하트비트 주기(최대 30초) 내에 도착합니다. 진단·화면 캡처·로그 수집 결과는 도착까지 최대 약 1분 걸릴 수 있으니 기록 항목을 잠시 후 다시 펼쳐 확인하세요.

## 광고 화면 문구 편집하기

![광고 화면 문구 CMS 편집 필드 4종](screenshots/device-operations-ad-messages.png)

키오스크 광고 화면에 표시되는 상태·오류 안내 문구를 직접 정할 수 있습니다. 섹션 안내는 다음과 같습니다: **키오스크 광고 화면의 상태·오류 안내 문구입니다. 비워 두면 키오스크 기본 문구가 표시됩니다.** (`devices:write` 권한이 있는 계정만 편집할 수 있습니다.)

편집 가능한 문구는 4가지입니다.

| 필드 | 언제 표시되나 |
| --- | --- |
| **화면 구성 대기** | 캔버스 레이아웃이 비어 있을 때 표시됩니다. |
| **서비스 일시 중단** | 서비스 일시 중단 오버레이에 표시됩니다. |
| **콘텐츠 표시 불가** | 콘텐츠를 렌더링할 수 없을 때 표시됩니다. |
| **영상 로드 실패** | 영상 로드에 실패했을 때 표시됩니다. |

작업 순서:

1. 각 필드에 원하는 문구를 입력합니다.
2. 비워 두면 키오스크에 내장된 기본 문구가 그대로 표시됩니다.
3. **저장**을 클릭합니다. 저장 중에는 `저장 중...`으로 표시됩니다.
4. 토스트 **광고 화면 문구가 저장되었습니다.** 가 뜨면 완료입니다.

> 💡 각 입력란의 placeholder(흐린 예시 글자)가 바로 키오스크 기본 문구입니다. 특별히 바꿀 필요가 없다면 비워 두어 기본값을 유지하세요.

## 설정 프로파일 저장·적용

이 기기의 운영 설정(게임·QR/설문·플로우·디스펜서·캔버스)을 프로파일로 저장해 두었다가 다른 기기에 그대로 적용할 수 있습니다. 식별 정보와 광고 문구는 프로파일에 담기지 않습니다. (`devices:write` 권한이 없으면 이 섹션은 아예 표시되지 않습니다.)

- **프로파일 이름**을 입력하고 **현재 설정 저장**을 누르면 지금 설정이 저장됩니다. `담길 설정: ...` 미리보기로 무엇이 담기는지 확인할 수 있습니다.
- 저장된 프로파일의 **적용** 버튼을 누르면 그 설정을 이 기기에 적용합니다.

> ⚠️ 프로파일을 적용하면 캔버스를 포함한 설정 전체가 덮어써지고 페이지가 다시 로드됩니다. 덮어쓰기 확인 후 진행하세요.


# 기기 상세 — 건강

이 챕터는 **기기 상세** 화면의 **건강** 탭을 다룹니다. **기기 관리**에서 기기를 선택한 뒤, 상세 화면 상단 탭에서 **건강**을 눌러 진입합니다.

**건강** 탭은 선택한 키오스크가 지금 잘 돌아가고 있는지를 한 화면에서 보여 줍니다. 최근 24시간 동안 키오스크가 보고한 이상(크래시·저장소·메모리·네트워크·디스펜서)과 연결 상태를 종합해 **정상 / 주의 / 위험** 등급을 매기고, 필요하면 진단·로그를 원격으로 요청하며, 이상 타임라인과 24시간 가동률·상태 이력을 확인할 수 있습니다.

> 💡 화면을 처음 열면 잠시 **`건강 정보를 불러오는 중...`**이 보일 수 있습니다. 데이터가 준비되면 자동으로 카드가 채워집니다.

---

## 기기 건강 상태 (요약 카드)

![기기 건강 상태 요약 카드 — 등급 배지와 24시간 위험/주의 알림, 연결 상태, 마지막 이상](screenshots/device-health-summary-card.png)

**건강** 탭 맨 위에 있는 **`기기 건강 상태`** 카드는 이 기기의 현재 건강을 한눈에 요약합니다. 제목 옆에 색상 점과 함께 등급 배지가 표시됩니다.

- **`정상`** (초록): 최근 24시간 동안 이상이 없고 연결도 정상인 상태입니다.
- **`주의`** (노랑): 가벼운 이상이 감지되어 지켜볼 필요가 있는 상태입니다.
- **`위험`** (빨강): 즉시 확인이 필요한 심각한 이상이 있는 상태입니다.

배지 아래 **`최근 24시간 내 키오스크가 보고한 이상(크래시·저장소·메모리·네트워크·디스펜서)과 연결 상태로 판정합니다.`** 문구가 등급 산정 기준을 안내합니다.

카드에는 다음 값이 함께 표시됩니다.

| 항목 | 의미 |
| --- | --- |
| **`위험 알림(24h)`** | 최근 24시간 동안의 위험 등급 알림 건수 (예: 0건) |
| **`주의 알림(24h)`** | 최근 24시간 동안의 주의 등급 알림 건수 |
| **`연결 상태`** | 현재 온라인/오프라인 여부 |
| **`마지막 이상`** | 가장 최근 이상 요약과 발생 시각·경과 시간 (없으면 `없음`) |

**등급 확인 순서**

1. **기기 관리**에서 기기를 선택하고 **건강** 탭으로 이동합니다.
2. **`기기 건강 상태`** 카드에서 등급 배지(**`정상`** / **`주의`** / **`위험`**)를 확인합니다.
3. **`위험 알림(24h)`** · **`주의 알림(24h)`** · **`연결 상태`** · **`마지막 이상`** 값을 차례로 확인합니다.

> ⚠️ 오프라인 판정과 화면상의 경과 시간은 상세 화면이 30초 주기로 갱신하는 하트비트를 기준으로 합니다. 방금 발생한 변화는 최대 30초 뒤에 반영될 수 있습니다.

---

## 진단·로그 수집 요청

카드 우측의 **`진단 수집`** · **`로그 수집`** 버튼으로 키오스크에 리포트를 직접 요청할 수 있습니다. 이 두 버튼은 `commands:execute` 권한이 있는 계정에만 보입니다.

- **`진단 수집`**: 키오스크가 진단 JSON을 올리도록 원격으로 요청합니다.
- **`로그 수집`**: 키오스크가 로그를 올리도록 원격으로 요청합니다.

요청을 보내는 동안 버튼 문구가 **`요청 중...`**으로 바뀌고 두 버튼 모두 잠시 비활성화됩니다.

**요청 방법**

1. **`기기 건강 상태`** 카드 우측의 **`진단 수집`**(또는 **`로그 수집`**)을 클릭합니다.
2. **`요청을 보냈습니다...`** 안내 토스트가 뜨는지 확인합니다.
3. 아래 **`진단 리포트`** 목록이 새로고침되며 키오스크가 올린 리포트를 확인합니다.

> 💡 진단·로그 수집은 원격 명령으로 전달됩니다. 기기가 온라인이면 다음 하트비트(최대 30초) 때, 오프라인이면 온라인으로 복귀했을 때 리포트를 올립니다.

> ⚠️ 권한이 없으면 버튼 대신 **`리포트를 직접 요청하려면 commands:execute 권한이 필요합니다. 조회는 가능합니다.`** 안내만 표시됩니다. 이력과 리포트 조회는 그대로 가능합니다.

> ⚠️ 관리자 정보가 아직 로딩 중일 때 요청하면 **`관리자 정보 로딩 중입니다. 잠시 후 다시 시도해 주세요.`** 토스트가 뜨고 요청이 전송되지 않습니다. 요청이 실패하면 **`리포트 요청에 실패했습니다.`** 토스트가 표시됩니다.

---

## 진단 리포트

**`진단 리포트`** 섹션에는 키오스크가 올린 진단 JSON·로그·스크린샷 목록이 표시됩니다. 안내 문구는 **`키오스크가 올린 진단 JSON·로그·스크린샷입니다. 위 진단 수집·로그 수집으로 새 리포트를 요청할 수 있습니다.`**입니다.

위의 **`진단 수집`** · **`로그 수집`**으로 새 리포트를 요청하면 이 목록이 갱신됩니다.

> 💡 위험 알림에 포함된 진단·로그 스냅샷은 **운영** 탭의 원격 명령 기록에서도 확인할 수 있습니다.

---

## 건강 이력 (타임라인)

![건강 이력 타임라인 — 위험/경고 이상과 오프라인 전환](screenshots/device-health-timeline.png)

**`건강 이력`** 카드는 자동으로 감지된 이상과 오프라인 전환을 시간순으로 보여 줍니다. 부제는 **`최근 기기 이상(크래시·저장소·네트워크·디스펜서 등)과 오프라인 전환을 시간순으로 표시합니다...`**입니다.

각 항목에는 심각도 배지가 붙습니다.

- **`위험`** / **`경고`**: 감지된 이상의 심각도 배지입니다(위험 = critical, 경고 = warning/알 수 없음).
- **`오프라인 전환`**: 기기가 오프라인으로 바뀐 이력입니다. 사유 라벨이 함께 표시될 수 있습니다.

위험 알림에 진단·로그 스냅샷 URL이 있으면 **`진단 열기`** · **`로그 열기`** 링크가 나타나며, 클릭하면 새 탭에서 열립니다(링크가 있을 때만 표시).

**이상 이력 조사**

1. **`건강 이력`** 타임라인에서 **`위험`** / **`경고`** / **`오프라인 전환`** 항목을 확인합니다.
2. 각 항목의 발생 시각·경과 시간·메시지를 확인합니다.
3. **`진단 열기`** · **`로그 열기`** 링크가 있으면 클릭해 스냅샷을 확인합니다.

이상이나 오프라인 전환이 없으면 **`이상 이력 없음`** 상태로 **`최근 기기 이상 알림이나 오프라인 전환이 없습니다.`**가 표시됩니다.

> ⚠️ 이 타임라인은 **`오프라인 전환`**만 표시하고 온라인/점검 복구는 노이즈로 제외합니다. 상태가 복구된 기록은 아래 **`상태 변경 히스토리`**에서 확인하세요.

---

## 상태 변경 히스토리

![상태 변경 히스토리 — 24시간 가동률과 상태 타임라인 막대·범례](screenshots/device-health-status-history.png)

**`상태 변경 히스토리`** 카드는 최근 24시간의 상태를 막대 타임라인과 가동률로 보여 줍니다.

- **`최근 24시간 가동률`**: 온라인 구간 비율을 퍼센트로 표시합니다(예: 98%). 우측에 **`24시간 전 → 현재`** 구간이 함께 표시됩니다.
- 막대 타임라인은 시간대별 상태를 색으로 나타내며, 범례는 **`온라인`** / **`오프라인`** / **`점검중`** / **`기록 없음`**입니다.
- 막대 아래에는 상태 변경 로그가 이어집니다.

**가동률·상태 이력 점검**

1. **`최근 24시간 가동률`** 퍼센트를 확인합니다.
2. 막대 타임라인의 색(**`온라인`** / **`오프라인`** / **`점검중`** / **`기록 없음`**)으로 시간대별 상태를 파악합니다.
3. 하단 상태 변경 로그에서 변화가 언제 일어났는지 확인합니다.

로딩 중에는 **`상태 히스토리 로딩 중...`**, 기록이 없으면 **`상태 변경 기록이 없습니다.`**가 표시됩니다. 조회에 실패하면 **`상태 히스토리를 불러오지 못했습니다. 잠시 후 다시 시도해 주세요.`** 문구가 나타납니다.

> 💡 24시간 가동률은 온라인 구간 시간을 24시간으로 나눈 값입니다. 오프라인·점검중 구간이 많을수록 값이 낮아집니다.

---

## 최근 이벤트

![최근 이벤트 — 심각도별 이벤트와 24시간 내 문제 건수 배지](screenshots/device-health-recent-events.png)

**건강** 탭 최하단의 **`최근 이벤트`** 카드는 상태 로그를 심각도(오류/경고/정보) 아이콘과 함께 최대 20건 보여 줍니다. 카드 우측에는 **`24시간 내 문제 N건`** 배지 또는 **`24시간 내 문제 없음`** 배지가 표시됩니다.

표시할 이벤트가 없으면 **`최근 이벤트가 없습니다.`**가 나타납니다.

> 💡 카드 우측 배지만 봐도 최근 24시간 안에 오류·경고가 몇 건 있었는지 빠르게 파악할 수 있습니다.


# 기기 상세 — 설문

**기기 관리**에서 기기를 선택한 뒤, 상세 화면 상단 탭에서 **설문**을 눌러 진입합니다.

이 탭에서는 해당 기기에 노출할 설문을 할당·생성·편집·활성화·응답 조회·삭제로 운영합니다. 새 설문은 드래그앤드롭 블록 빌더로 본문과 완료 페이지를 직접 디자인할 수 있습니다. 고객 만족도, NPS 추천, 방문 후기 같은 설문을 만들어 키오스크 화면에 띄우고, 모인 응답을 통계로 확인하는 것이 이 화면의 목적입니다.

> ⚠️ 설문 생성·편집·저장은 `surveys:write` 권한이 필요합니다. 권한이 없으면 **저장** 버튼이 비활성화되고 `설문 편집(surveys:write) 권한이 없습니다` 툴팁이 표시됩니다. 새 설문·응답 페이지·빌더 화면은 관리자(super_admin) 또는 위임받은 엔터프라이즈 계정만 접근할 수 있습니다.

---

## 이 기기에 할당된 설문 (목록)

![기기 상세 '설문' 탭 — 할당된 설문 목록(상태·기간·질문 수·응답 수·대상)과 행별 액션](screenshots/device-surveys-tab-list.png)

**설문** 탭을 열면 **이 기기에 할당된 설문** 제목 아래로, 이 기기에 지정되었거나 전체 기기를 대상으로 하는 설문이 표로 나열됩니다.

### 화면 요소

| 요소 | 설명 |
| --- | --- |
| **설문 할당** 버튼 | 다른 곳에서 만든 기존 설문을 이 기기에도 추가합니다. |
| **새 설문** 버튼 | 설문 빌더를 새로 시작합니다. |
| `설문 제목 검색...` | 목록에서 설문을 제목으로 검색합니다. |
| 상태 필터 | **활성** / **비활성** 으로 목록을 걸러 봅니다. |
| 목록 컬럼 | **설문 제목 · 상태 · 기간 · 질문 수 · 응답 수 · 대상** |
| 행별 액션 | **수정** · **응답** · **복제** · **활성화**/**비활성화** · **할당해제** · **삭제** |

- **기간** 열은 시작·종료 시각이 없으면 `상시`로 표시됩니다.
- **대상** 열은 `전체 기기` 또는 `지정 기기`로 표시됩니다.
- **할당해제**는 이 기기에 지정된 설문에만 나타납니다.

> 💡 **기간**이 `상시`이면 항상 노출됩니다. 특정 기간에만 띄우려면 빌더 설정 패널에서 시작/종료 시각을 지정하세요.

> ⚠️ **삭제**는 모든 기기에서 제거되며 되돌릴 수 없습니다(확인 문구: `모든 기기에서 제거되며 되돌릴 수 없습니다`).

### 기존 설문을 이 기기에 할당하기

1. **설문 할당** 버튼을 누릅니다.
2. 열린 모달에서 `설문 제목 검색...`으로 원하는 설문을 찾습니다.
3. 대상 설문의 **할당** 버튼을 누릅니다.
4. `설문이 이 기기에 할당되었습니다.` 토스트가 뜨면 완료입니다.

> 💡 추가할 수 있는 설문이 하나도 없으면 모달에 `할당 가능한 설문이 없습니다.`가 표시됩니다.

### 활성/비활성 및 할당 해제

1. 목록에서 **활성화** 또는 **비활성화**를 눌러 노출을 켜고 끕니다.
2. 이 기기에서만 빼려면 **할당해제**를 누르고 확인 다이얼로그에서 동의합니다.

> ⚠️ 어떤 설문의 마지막 지정 기기에서 **할당해제**하면 대상 기기가 비게 되어 전체 기기 노출이 될 수 있습니다. 이를 막기 위해 시스템이 해당 설문을 자동으로 함께 비활성화하며, 확인 다이얼로그에 이 경고가 표시됩니다.

---

## 새 설문 시작 — 템플릿 갤러리

![새 설문 시작 — 빈 설문/템플릿 갤러리](screenshots/device-surveys-template-gallery.png)

**새 설문**을 누르면 **새 설문 시작** 갤러리가 열립니다. 처음부터 직접 만들거나, 기본 제공 템플릿에서 시작할 수 있습니다.

### 화면 요소

- **빈 설문으로 시작** 카드: **처음부터 직접 구성**합니다.
- 템플릿 카드: **고객 만족도 조사** · **NPS 추천 조사** · **이벤트 참여 설문** · **방문 후기** · **직원·서비스 평가**. 각 카드에는 포함된 블록 수(`N개 블록`) 뱃지가 붙습니다.

### 작업 순서

1. **빈 설문으로 시작** 또는 원하는 템플릿 카드(예: **고객 만족도 조사**)를 클릭합니다.
2. 선택한 구성으로 설문 빌더가 열립니다.

> 💡 템플릿을 골라도 빌더에서 자유롭게 블록을 추가·삭제·수정할 수 있으니, 가장 비슷한 템플릿으로 시작하면 작업이 빨라집니다.

---

## 설문 빌더 (3분할 작업 공간)

![설문 빌더 3분할 — 좌측 블록 팔레트/프리셋, 중앙 캔버스, 우측 인스펙터·설정](screenshots/device-surveys-builder-workspace.png)

빌더는 세 영역으로 나뉩니다. 왼쪽에서 블록을 꺼내고, 가운데 캔버스에 배치하고, 오른쪽에서 세부 속성과 설문 설정을 편집합니다.

### 화면 요소

- **상단 탭**: **설문 본문** / **완료 페이지**. 각 탭에 블록 개수 뱃지가 표시됩니다.
- **툴바**: **미리보기** · **취소** · **저장**. **미리보기**는 현재 탭 블록을 키오스크 노출 형태로 보여주고, **저장**은 유효성 검증 후 저장합니다.
- **좌측 블록 추가 팔레트**: **콘텐츠**(제목·텍스트·이미지·영상), **질문**(질문·동의), **레이아웃**(컨테이너/그룹·버튼·여백·구분선·페이지 나눔). 카드를 캔버스로 끌어다 놓아 추가합니다.
- **좌측 프리셋 패널**: **기본 제공**(만족도 5점 척도·NPS 세트·연락처 수집·인구통계·개인정보 동의)과 **내 프리셋**. **선택 블록 저장**으로 자주 쓰는 묶음을 계정 프리셋으로 만듭니다.
- **우측 인스펙터**: 캔버스에서 블록을 선택하면 그 블록의 속성 편집 화면과 복제/삭제 버튼이 나타납니다.

### 새 설문 만들기

1. 좌측 팔레트에서 블록 카드를 캔버스로 **드래그**해 추가하고, 캔버스 안에서 끌어 순서를 재배치합니다.
2. 캔버스에서 블록을 선택하고 우측 인스펙터에서 속성을 편집합니다.
3. 우측 **설문 정보**에서 제목·기간·대상 기기를 지정합니다(다음 소절 참고).
4. **미리보기**로 키오스크 화면을 확인합니다.
5. **저장**을 누릅니다. `설문이 저장되었습니다.` 토스트가 뜨면 완료입니다.

> 💡 질문 유형은 단일 선택·복수 선택·서술형·별점·슬라이더·날짜·이미지 선택·NPS·순위·행렬(척도)·이모지 만족도를 지원합니다.

> 💡 자주 쓰는 블록 묶음은 블록을 고른 뒤 **선택 블록 저장**으로 저장하세요(이름 예시 placeholder: `예: 만족도 + 재방문 세트`). 계정 전체에서 다시 꺼내 쓸 수 있습니다.

> ⚠️ 저장하지 않고 나가면 `저장하지 않은 변경이 있습니다` 경고가 뜹니다. 작업 중에는 자주 **저장**하세요.

> ⚠️ 저장하려면 제목이 반드시 있어야 하고, 종료 시각은 시작 시각 이후여야 하며, 블록이 최소 1개 있어야 합니다. 선택지가 필요한 질문(단일/복수/이미지/순위)은 선택지가 최소 2개 있어야 합니다.

### 설문 정보와 커스텀 테마

캔버스 빈 곳을 눌러 블록 선택을 해제하면 우측에 **설문 정보** 설정 패널이 나타납니다.

- **설문 정보**: 설문 제목·설명·시작 시각·종료 시각·활성화·대상 기기. 대상 기기를 지정하지 않으면 전체 기기로 표시됩니다.
- **커스텀 테마 사용** 토글: 켜면 키오스크 설문 화면의 배경색·텍스트 색상·버튼 색상·로고 URL·글꼴 크기(12~24px)를 지정할 수 있습니다.

> ⚠️ 대상 기기를 지정하지 않으면 전체 기기에 노출됩니다. 특정 매장 전용 설문은 반드시 대상 기기를 선택하세요.

### 완료 페이지 직접 디자인

**완료 페이지** 탭은 응답을 마친 고객에게 보여줄 화면입니다.

1. 빌더 상단에서 **완료 페이지** 탭을 선택합니다.
2. **완료 페이지 직접 디자인** 토글을 켭니다(끄면 기본 완료 화면 — 설문 완료 + 리워드 안내 — 이 표시됩니다).
3. 팔레트에서 블록을 배치해 완료 화면을 꾸밉니다.
4. **저장**합니다.

> ⚠️ 완료 페이지에는 질문·동의 블록을 추가할 수 없습니다(팔레트에서도 숨겨지며, 시도하면 `완료 페이지에는 질문·동의 블록을 추가할 수 없습니다` 경고가 뜹니다).

---

## 응답 조회 및 내보내기


목록에서 설문 행의 **응답**을 누르면 모인 응답을 통계로 확인하고 파일로 내보낼 수 있습니다.

### 화면 요소

- **탭**: **통계** / **교차분석** / **상세 보기**.
- **상단 액션**: **CSV** · **Excel** · **설문 복제**. 응답이 없으면 CSV/Excel은 비활성화됩니다.
- **필터**: 날짜 범위·기기 필터·**응답값 세그먼트**(문항). **조건 추가**로 문항 값 조건을 더하고(모두 충족하는 AND 조건), **필터 초기화**로 되돌립니다.

### 작업 순서

1. 목록에서 대상 설문의 **응답**을 클릭합니다.
2. **통계** / **교차분석** / **상세 보기** 탭을 전환하며 결과를 봅니다.
3. 필요하면 날짜·기기·세그먼트 필터를 적용합니다.
4. **CSV** 또는 **Excel**로 내보냅니다.

> 💡 응답 CSV/Excel는 문구가 같은 문항이라도 고유 ID로 구분하므로, 열이 서로 덮어써지지 않고 안전하게 분리됩니다.

> 💡 **복제**(목록의 **복제** 링크 또는 응답 페이지의 **설문 복제**)는 컨테이너 안쪽 블록까지 새 ID로 다시 발급해 안전하게 사본을 만듭니다. 비슷한 설문을 새로 만들 때 편리합니다.

> ⚠️ 상세 보기의 세션 삭제는 해당 세션의 모든 응답을 되돌릴 수 없이 삭제합니다. 신중하게 사용하세요.


# 기기 상세 — 보상·디스펜서

이 화면에서는 특정 기기를 대상으로 하는 **보상**(쿠폰·포인트·기프트)을 등록·수정·삭제하고, 설문 완료 후 카드를 내보내는 **디스펜서**의 켜짐 여부와 1·2·3등 토출 확률을 조정할 수 있습니다.

**기기 관리**에서 기기를 선택한 뒤, 상세 화면 상단 탭에서 **보상·디스펜서** 탭을 눌러 진입합니다.

---

## 이 기기 대상 보상

### 보상 목록 살펴보기

![이 기기 대상 보상 목록 — 유형·확률·재고·대상·상태 컬럼](screenshots/device-dispenser-rewards-list.png)

**이 기기 대상 보상** 섹션에는 현재 기기에서 지급되는 보상이 표로 나열됩니다. 전체 기기를 대상으로 하는 보상과 이 기기만 지정한 보상이 함께 표시됩니다.

표의 컬럼은 다음과 같습니다.

| 컬럼 | 설명 |
| --- | --- |
| **보상 이름** | 보상의 이름입니다. |
| **유형** | 쿠폰·포인트·기프트 중 하나가 색상 뱃지로 표시됩니다. |
| **값** | 쿠폰 코드 또는 포인트 수 등 실제 지급되는 값입니다. |
| **당첨 확률** | 백분율로 표시됩니다(예: `10.0%`). |
| **재고** | `잔여 / 총량` 형태로 표시됩니다. |
| **대상** | `전체 기기` 또는 `지정 기기`로 표시됩니다. |
| **상태** | 활성/비활성 여부가 색상 뱃지로 표시됩니다. |

각 보상 행에는 **수정**·**삭제** 버튼이 있습니다.

> 💡 **대상** 컬럼이 `전체 기기`이면 모든 기기에서 공통으로 지급되는 보상이고, `지정 기기`이면 특정 기기에만 할당된 보상입니다.

### 새 보상 등록하기

![새 보상 등록 모달 — 유형·값·확률·대상 기기 선택](screenshots/device-dispenser-reward-form.png)

목록 우측 상단의 **새 보상** 버튼을 누르면 **새 보상 등록** 모달이 열립니다. 아직 보상이 하나도 없을 때는 목록 대신 `이 기기를 대상으로 하는 보상이 없습니다.` 안내와 함께 **첫 보상 만들기** 버튼이 표시됩니다.

모달의 입력 항목은 다음과 같습니다.

- **보상 이름** — 필수 입력입니다.
- **설명** — 선택 입력입니다.
- **보상 유형** — 쿠폰·포인트·기프트 중에서 선택합니다.
- **보상 값** — 필수 입력입니다. `쿠폰 코드 또는 포인트 수`를 입력합니다.
- **당첨 확률** — 필수 입력입니다. `0.0 ~ 1.0` 범위의 소수로 입력합니다(예: 0.1 = 10%).
- **총 수량** — 필수 입력입니다. 기본값은 100입니다.
- **활성화** — 보상을 즉시 사용할지 정하는 체크박스입니다.
- **대상 기기** — 이 보상을 지급할 기기를 체크로 선택합니다. `선택하지 않으면 모든 기기에서 이 보상을 사용할 수 있습니다.`

작업 순서:

1. **새 보상**(또는 빈 상태의 **첫 보상 만들기**)을 누릅니다.
2. **새 보상 등록** 모달에서 **보상 이름**·**설명**·**보상 유형**·**보상 값**을 입력합니다.
3. **당첨 확률**(0.0~1.0)과 **총 수량**을 입력하고 **활성화**를 체크합니다.
4. **대상 기기**에서 지급할 기기를 선택합니다(선택하지 않으면 모든 기기 대상이 됩니다).
5. **등록**을 누르면 `보상이 등록되었습니다.` 토스트가 표시됩니다.

> 💡 이 화면에서 만든 보상은 **대상 기기**에서 현재 기기를 빼더라도 자동으로 포함되어, 지금 보고 있는 기기에서는 반드시 지급됩니다.

> ⚠️ **당첨 확률**은 0.0~1.0 범위의 소수로 입력해야 하며, 목록에는 백분율로 환산되어 표시됩니다(예: 0.1 → `10.0%`).

### 보상 수정하기

보상 행의 **수정** 버튼을 누르면 **보상 수정** 모달이 열립니다. 신규 등록 모달과 동일하되, 수정 모드에서만 **잔여 수량** 필드가 추가로 표시되어 남은 재고를 직접 조정할 수 있습니다.

1. 목록에서 수정할 보상 행의 **수정**을 누릅니다.
2. 값을 변경합니다(필요 시 **잔여 수량** 조정).
3. **수정**을 누르면 `보상이 수정되었습니다.` 토스트가 표시됩니다.

> ⚠️ 신규 등록 시에는 **잔여 수량** 필드가 보이지 않으며, 잔여 수량은 총 수량과 동일하게 설정됩니다. 잔여 수량 조정은 수정 모드에서만 가능합니다.

### 보상 삭제하기

보상 행의 빨간색 **삭제** 버튼을 누르면 확인 다이얼로그가 열립니다. 전체 기기 대상이거나 여러 기기에 할당된 보상은 모든 대상 기기에서 함께 제거된다는 경고가 표시됩니다.

1. 삭제할 보상 행의 **삭제**를 누릅니다.
2. 확인 다이얼로그의 경고를 확인합니다.
3. 확인하면 `보상이 삭제되었습니다.` 토스트가 표시됩니다.

> ⚠️ 보상 삭제는 되돌릴 수 없습니다. 전체 기기 대상이거나 여러 기기에 할당된 보상을 삭제하면 모든 대상 기기에서 함께 사라집니다.

---

## 디스펜서 설정

### 디스펜서 활성화

**디스펜서 활성화** 카드의 토글로 카드 토출 기능을 켜고 끕니다. 안내문은 `비활성화 시 설문 완료 후에도 카드가 토출되지 않습니다.` 입니다.

> ⚠️ 디스펜서를 비활성화하면 이용자가 설문을 완료해도 카드가 나오지 않습니다. 운영 중인 기기라면 켜짐 상태를 유지하세요.

### 등수별 토출 확률

![등수별 토출 확률 조정 — 슬라이더·합계 100% 비율 바](screenshots/device-dispenser-config-probability.png)

**등수별 토출 확률** 카드에서 1·2·3등의 토출 확률을 조정합니다. 한 등급을 조정하면 나머지 두 등급에 자동으로 비례 분배되어 **합계는 항상 100%로 유지**됩니다(카드 상단 **합계 100%** 표시가 초록색 비율 바로 보입니다). 화면에는 각 등급이 %로 보이며, 그 비율대로 추첨됩니다.

각 등급은 슬라이더 또는 숫자 입력으로 조정하며, 물리 디스펜서 포트에 대응합니다.

| 등급 | 대응 포트 |
| --- | --- |
| **1등 /dev/ttyS1 (DC1)** | ttyS1 |
| **2등 /dev/ttyS3 (DC3)** | ttyS3 |
| **3등 /dev/ttyS4 (DC4)** | ttyS4 |

안내문은 다음과 같습니다. `한 등급의 확률을 조정하면 나머지 두 등급에 비례 분배되어 합계는 항상 100%가 유지됩니다. 한 등급을 0%로 두면 해당 등급은 추첨에서 제외됩니다.`

작업 순서:

1. **디스펜서 활성화** 토글로 카드 토출을 켭니다.
2. **등수별 토출 확률**에서 1·2·3등의 슬라이더 또는 숫자를 조정합니다(나머지 등급이 자동 비례 분배됩니다).
3. 상단 **합계 100%**가 초록색으로 유지되는지 확인합니다.
4. **저장**을 누르면 `디스펜서 확률이 저장되었습니다.` 토스트가 표시됩니다.

값을 처음 상태로 되돌리려면 **기본값으로 초기화**를 누릅니다. 기본값(활성화·1등 5%·2등 25%·3등 70%)으로 화면 값이 되돌아가며 `기본값으로 초기화되었습니다. 저장을 눌러 적용하세요.` 토스트가 표시됩니다.

> 💡 특정 등급을 0%로 두면 그 등급은 추첨에서 제외됩니다. 특정 등급 카드 재고가 소진되었을 때 유용합니다.

> ⚠️ **기본값으로 초기화**는 화면 값만 되돌립니다. 실제로 적용하려면 반드시 **저장**을 눌러야 합니다.

> 💡 합계는 자동으로 100%가 맞춰지므로 보통 신경 쓸 필요가 없습니다. 혹시라도 합계가 100%가 아니게 되면 합계 표시가 빨간색이 되고 **저장** 버튼이 비활성화되니, 값을 다시 조정해 100%로 맞추세요.


# 기기 상세 — 정보·통계

키오스크 1대의 현재 상태와 운영·통계를 한눈에 확인하는 화면입니다. **기기 관리**에서 기기를 선택해 상세 화면으로 들어간 뒤, 상단 탭에서 **정보·통계**를 열면 됩니다.

이 탭에서는 지금 화면에 무엇이 나오고 있는지, 오늘의 스케줄은 어떻게 짜여 있는지, 기기 기본 정보와 소유 기업은 무엇인지 확인할 수 있고, 기간별 노출·터치·세션 지표와 설문·토출(경품 배출) 통계, 최근 이력까지 모두 볼 수 있습니다.

## 현재 화면과 오늘 스케줄

탭을 열면 맨 위에 기기가 마지막으로 올린 **현재 화면(마지막 캡처 이미지)**과, 하루 24시간을 한 줄로 보여주는 **오늘 스케줄 타임라인**이 나옵니다.

- **현재 화면**: 기기가 마지막으로 올린 화면 캡처 이미지입니다(캡처 시각이 함께 표시됩니다). 지금 화면을 새로 보려면 **지금 캡처** 버튼을 누르세요 — 기기가 응답하면 최대 1분 안에 갱신됩니다(`commands:execute` 권한이 있는 계정만). 광고가 잘 나오는지, 화면이 멈춰 있지 않은지 점검할 때 유용합니다.
- **오늘 스케줄 타임라인**: 오늘 하루 동안 광고·씬·QR 창이 언제 뜨도록 예약돼 있는지 시간대별로 보여줍니다.

작업 순서:

1. **정보·통계** 탭을 엽니다.
2. 상단 **현재 화면**의 캡처 시각을 확인하고, 최신 화면이 필요하면 **지금 캡처**로 갱신합니다.
3. 그 아래 **오늘 스케줄 타임라인**으로 광고/씬/QR 창 배치를 확인합니다.

## 기기 정보 카드

![기기 정보 카드 — 위치·일련번호·기기 정보·IP·마지막 연결·소유 기업](screenshots/device-info-meta-card.png)

기기의 기본 정보와 소유 기업을 확인하는 카드입니다.

| 항목 | 설명 |
| --- | --- |
| **위치** | 기기 설치 위치입니다. 설정하지 않았으면 `-`로 표시됩니다. |
| **일련번호** | 기기 시리얼 번호입니다. 없으면 `-`. |
| **기기 정보** | 기기 모델 등 정보 문자열입니다. 없으면 `-`. |
| **IP 주소** | 기기의 IP 주소입니다. 없으면 `-`. |
| **마지막 연결** | 마지막으로 기기 신호가 들어온 시각과 경과 시간(예: `(3분 전)`)입니다. 오프라인이면 **빨간색**으로 표시됩니다. |
| **소유 기업** | 소유 기업 이름과 기업 코드 칩입니다. 할당되지 않았으면 **미할당**으로 표시됩니다. |

**소유 기업 ID 복사** 버튼을 누르면 그 기업의 코드가 클립보드에 복사됩니다. 성공하면 체크 아이콘이 잠깐 표시되고, 실패하면 **복사에 실패했습니다.** 안내가 뜹니다.

작업 순서:

1. 카드에서 위치·일련번호·IP 등 기본 정보를 확인합니다.
2. **마지막 연결**의 경과 시간으로 온라인/오프라인을 판단합니다(빨간색이면 오프라인).
3. 다른 화면에 기업 코드를 붙여 넣어야 하면 **소유 기업 ID 복사** 버튼을 누릅니다.

> 💡 **마지막 연결** 옆 시간이 빨간색이라도, 화면은 30초마다 신호를 다시 확인하므로 잠시 뒤 자동으로 갱신될 수 있습니다.

> ⚠️ **소유 기업 ID 복사**는 브라우저 클립보드 기능을 사용합니다. 보안 연결(https)이 아닌 환경에서는 복사가 실패할 수 있습니다.

## 기기 분석

![기기 분석 KPI와 날짜 범위 선택기(노출·터치·세션·완료·완료율·가동시간)](screenshots/device-info-analytics-kpi.png)

선택한 기간 동안 이 기기의 운영 지표를 보여주는 카드입니다. 카드 오른쪽 위 **날짜 범위 선택기**로 기간을 바꾸면 아래 모든 수치와 차트가 그 기간에 맞춰 다시 계산됩니다.

주요 지표(KPI):

| 지표 | 의미 |
| --- | --- |
| **노출** | 기간 내 광고가 화면에 표시된 횟수 |
| **터치** | 화면을 터치한 횟수 |
| **세션** | 설문이 시작된 횟수 |
| **완료** | 설문을 끝까지 마친 횟수 |
| **완료율** | 완료 ÷ 세션 비율 |
| **가동시간** | 기기가 온라인으로 켜져 있던 누적 시간 |
| **가동시간당 터치** | 온라인 1시간당 평균 터치 수 |

그 아래에는 **디스펜서 건전성** 안내가 있습니다. 보상 수령 건수와 실제 토출(경품 배출) 기록이 맞으면 "일치합니다"로, 어긋나면 몇 건이 불일치하는지와 함께 **디스펜서 하드웨어 신호를 점검하세요.** 라는 경고가 표시됩니다.

카드 하단에는 추이 차트 두 개가 있습니다. **완료 세션 추이**(파란 선)와 **터치 추이**(주황 선)로 기간 내 일별 흐름을 볼 수 있습니다.

작업 순서:

1. 카드 오른쪽 위 **날짜 범위 선택기**에서 기간을 고릅니다(기본값: 오늘 포함 최근 7일).
2. **노출·터치·세션·완료·완료율·가동시간·가동시간당 터치** 값을 확인합니다.
3. **디스펜서 건전성**에서 보상 수령과 토출 기록이 맞는지 봅니다.
4. **완료 세션 추이**·**터치 추이** 차트로 날짜별 변화를 확인합니다.

> 💡 KPI와 차트는 모두 날짜 범위 선택기의 기간에 종속됩니다. 기본값은 서울 시간 기준 오늘 포함 최근 7일입니다.

> ⚠️ 데이터를 불러오지 못하면 **분석 데이터를 불러오는 중 오류가 발생했습니다.** 문구와 **다시 시도** 버튼이 나옵니다. 버튼을 눌러 다시 조회해 보세요. 데이터가 많은 기기는 정합성 조회에 시간이 걸려 로딩이 느릴 수 있습니다.

## 설문 / 토출 통계

![설문/토출 통계 — 설문 완료 + 등급별(1등 DC1/2등 DC3/3등 DC4) 실토출·발사·시도](screenshots/device-info-dispense-stats.png)

설문 완료 건수와, 경품 등급별로 실제 몇 개가 나갔는지를 보여주는 카드입니다.

- **설문 완료**: 완료된 세션 총 건수입니다.
- **1등 (DC1)**, **2등 (DC3)**, **3등 (DC4)**: 등급별 토출 통계 칸입니다. 각 칸의 큰 숫자는 **실토출**(기기가 배출을 확인한 수)이고, 그 아래에 **발사**(배출 명령을 보낸 수)와 **시도**(전체 시도 수)가 함께 표시됩니다.

작업 순서:

1. **설문 완료** 건수로 참여 규모를 확인합니다.
2. 등급별 칸에서 큰 숫자(**실토출**)와 **발사 / 시도** 값을 비교합니다.
3. 세 값이 서로 다르면 디스펜서 신호에 문제가 없는지 살펴봅니다.

> 💡 등급과 배출구는 고정입니다: 1등 = DC1, 2등 = DC3, 3등 = DC4.

> ⚠️ 실토출·발사 수치는 화면에서 항목 수를 세어 계산한 근사치입니다. 정밀한 정산이 필요할 때는 참고용으로만 보세요.

### 최근 토출 이력

![최근 토출 이력 — 결과 뱃지(성공/ACK 없음/발사 실패)와 점검 필요 하이라이트](screenshots/device-info-dispense-history.png)

경품이 배출된 최근 기록을 시각·등급·결과와 함께 보여줍니다. 처음에는 최근 5건만 보이고, **더보기** 버튼으로 나머지를 펼칠 수 있습니다.

각 행에는 결과 뱃지가 붙습니다:

| 뱃지 | 의미 |
| --- | --- |
| **성공** | 배출이 정상적으로 확인됨(초록) |
| **ACK 없음** | 배출 명령은 보냈으나 완료 신호가 오지 않음(노랑, 점검 필요) |
| **발사 실패** | 배출 명령조차 나가지 못함(빨강, 점검 필요) |

**ACK 없음**이나 **발사 실패**인 행은 경고 색으로 강조되고 삼각형 아이콘이 붙습니다.

작업 순서:

1. 각 행의 시각·등급·결과 뱃지를 확인합니다.
2. 경고로 강조된(점검 필요) 행이 있으면 디스펜서 하드웨어(케이블·배출구)를 점검합니다.
3. 전체 기록을 보려면 **더보기** 버튼을 누릅니다.

> ⚠️ 통계나 토출 이력을 불러오지 못하면 **통계를 불러올 수 없습니다 (인덱스 빌드 중일 수 있음).** 또는 **토출 이력을 불러올 수 없습니다 (인덱스 빌드 중일 수 있음).** 문구가 뜹니다. 데이터 색인을 만드는 중일 수 있으니 잠시 뒤 다시 확인해 보세요.

## 최근 이력

카드 하단에는 최근 활동을 표로 보여주는 세 가지 이력이 있습니다.

- **최근 광고 노출**: 최근 10건으로, **광고 / 위치(메인·보조1·보조2) / 시작 / 시간(초)** 컬럼을 보여줍니다. 기록이 없으면 **노출 기록이 없습니다.** 로 표시됩니다.
- **최근 설문 참여**: 세션 단위 최근 10건으로 설문명과 시각을 보여줍니다. 없으면 **설문 참여 기록이 없습니다.**.
- **최근 보상 수령**: 최근 10건으로 보상명과 시각을 보여줍니다. 없으면 **보상 수령 기록이 없습니다.**.

> ⚠️ 원본이 삭제된 광고·설문·보상은 이력에서 **(삭제됨)**으로 표시됩니다.

> 💡 기기의 건강 상태 이력과 상태 변화 기록은 이 탭이 아니라 **건강** 탭에서 확인할 수 있습니다.


# 광고 등록·상세·게재 스케줄

키오스크 화면에 내보낼 광고를 만들고, 각 광고가 어느 기기에서 언제 나올지(게재 스케줄)를 정하는 방법을 안내합니다. 모든 작업은 https://admin.adluck7.com 에 로그인한 뒤 진행합니다.

> 💡 광고 만들기는 **기기 상세** 화면의 **광고 배치** 탭에서 시작합니다. 캔버스에서 광고를 넣을 영역(광고 영역)을 선택한 다음 **새 광고 등록**을 누르면 아래에서 설명하는 광고 등록 창이 열립니다. 광고 상세(`/ads/[id]`)와 게재 스케줄(`/ads/[id]/schedules`) 화면은 **데이터 분석 → 광고 노출 점유율** 표에서 광고명을 클릭하면 볼 수 있습니다.

## 광고 등록하기

**새 광고 등록** 창에서 광고 제목, 콘텐츠 종류, 미디어(이미지·영상·게임), 노출 시간을 한 번에 설정합니다.

> ⚠️ 현재 화면에서는 **광고 등록만** 지원합니다. 이미 만든 광고의 내용을 고치는 별도 진입(광고 수정)은 제공되지 않으니, 필요하면 광고를 새로 등록해 교체하세요. (게재 스케줄은 아래 스케줄 화면에서 수정할 수 있습니다.)

### 기본 정보와 콘텐츠 타입

| 화면 요소 | 설명 |
| --- | --- |
| **광고 제목** | 광고를 구분할 이름입니다. 최대 100자까지 입력할 수 있습니다. |
| **콘텐츠 타입** | `이미지` / `동영상` / `메모리 페어 매칭 게임` 중에서 선택합니다. |
| **활성화** | 체크하면 광고가 실제로 노출됩니다. 잠시 내리고 싶으면 체크를 해제합니다. |

일반 광고(이미지·동영상)와 게임 광고는 입력 항목이 다릅니다.

- **이미지 / 동영상 광고**: **미디어** 영역에서 파일이나 URL만 넣으면 됩니다.
- **메모리 페어 매칭 게임 광고**: **게임 설정**, **게임 카드 이미지**(또는 **원본 이미지**), **게임 배경 이미지/영상** 항목이 추가로 나타납니다.

### 미디어 넣기 (이미지·동영상)

**미디어** 영역에는 두 개의 탭이 있습니다.

| 탭 | 사용 방법 |
| --- | --- |
| **파일 업로드** | `클릭하거나 파일을 끌어다 놓으세요` 영역에 파일을 올립니다. `이미지 10MB, 동영상 100MB 이하`만 가능합니다. |
| **URL 직접 입력** | `https://example.com/media.jpg` 형식으로 이미지·영상 주소를 붙여 넣습니다. |

작업 순서

1. **콘텐츠 타입**에서 `이미지` 또는 `동영상`을 고릅니다. (파일을 올리면 종류에 맞게 자동으로 맞춰지기도 합니다.)
2. **파일 업로드** 또는 **URL 직접 입력** 탭에서 미디어를 넣습니다.
3. 아래 **노출 설정**을 확인합니다.
4. 오른쪽 아래 **등록** 버튼을 누릅니다.

> ⚠️ 동영상은 **영상 표시 시간(초)** 을 비워 두면 `미설정 (기기 기본 → 영상 길이)` 상태가 되어, 기기 기본값이나 영상 길이만큼 재생한 뒤 다음 광고로 넘어갑니다.

### 게임 광고 설정하기

**콘텐츠 타입**을 `메모리 페어 매칭 게임`으로 고르면 **게임 설정** 영역이 열립니다.

| 화면 요소 | 설명 |
| --- | --- |
| **게임 종류** | `메모리 카드 매칭`(같은 카드 두 장 찾기) 또는 `이미지 짝맞추기`(원본 사진 1장을 조각으로 나눠 맞추기). |
| **게임 프리셋** | 자주 쓰는 그리드·제한시간 조합을 버튼 한 번으로 적용합니다. **현재 설정을 프리셋으로 저장**으로 나만의 프리셋을 만들 수 있습니다. |
| **그리드 (행 × 열)** / **레이어 (조각 분할)** | 카드·조각 배치를 정합니다. `메모리 카드 매칭`은 **행 × 열**을 골라 카드 쌍(짝수)이 되게 하고, `이미지 짝맞추기`는 **레이어(조각 분할) 프리셋**을 드롭다운에서 고릅니다(3×3처럼 홀수 분할 프리셋도 있습니다). |
| **제한시간(초, 0=무제한)** | 게임 제한시간입니다. |
| **모드** | `게임+설문` 또는 `게임만+보상`. `게임+설문`에서는 **설문 사용** 체크가 나타납니다. |
| **게임 스타일 (이 광고)** | 색·글자·타이밍·소리를 이 광고에만 다르게 지정합니다. 비워 두면 기기 기본 스타일을 따릅니다. |
| **게임 미리보기 / 플레이** | 저장 전에 현재 설정으로 실제 게임을 눌러 볼 수 있습니다. |

- `메모리 카드 매칭`을 고르면 **게임 카드 이미지**에서 **카드 이미지 추가**(파일) 또는 `이미지 URL 직접 입력 (https://...)` + **URL 추가**로 카드를 넣습니다. (최대 20장)
- `이미지 짝맞추기`를 고르면 **원본 이미지**에 `https://… 원본 이미지 URL`을 넣습니다. 이 항목은 필수입니다.
- **게임 배경 이미지/영상**은 카드가 아니라 게임 화면 뒤에 깔리는 배경입니다.

> ⚠️ `이미지 짝맞추기` 게임은 **원본 이미지만** 넣으면 **등록** 버튼이 활성화되지 않을 수 있습니다. 이럴 때는 **게임 배경 이미지/영상**에도 파일이나 URL을 하나 넣으면 등록됩니다.

> ⚠️ 게임 광고의 **표시 시간**은 **제한시간 이상**으로 잡아야 게임이 중간에 끊기지 않습니다.

## 광고 상세 확인하기

특정 광고의 종류·노출 위치·총 노출수·상태를 한눈에 확인하는 화면입니다. **super_admin**(최고 관리자) 또는 **enterprise**(사업자) 권한이 있는 계정만 볼 수 있습니다.

![광고 상세 — 정보·미디어·노출 통계](screenshots/ad-detail-overview.png)

| 항목 | 설명 |
| --- | --- |
| **타입** | 이미지 또는 동영상 여부입니다. (참고: 게임 광고는 상세 화면에 별도 타입 표시가 없어 '동영상'으로 나타납니다.) |
| **위치** | 예전 방식의 광고 자리(`메인` / `보조1` / `보조2`) 표시입니다. 자유 캔버스 도입 이후 실제 배치는 **광고 배치** 탭의 영역(region)으로 정하므로, 이 값은 참고용입니다. |
| **노출 시간** | 한 번 표시될 때 화면에 머무는 시간(초)입니다. |
| **총 노출수** | 지금까지 노출된 누적 횟수입니다. |
| **상태** | 활성/비활성 여부를 뱃지로 보여줍니다. |

작업 순서

1. **데이터 분석 → 광고 노출 점유율** 표에서 광고명을 눌러 상세 화면으로 들어갑니다.
2. 미디어 미리보기와 위 항목으로 광고 내용을 확인합니다.
3. 화면 아래 **스케줄 관리 →** 링크를 눌러 게재 스케줄로 이동합니다.

> 💡 왼쪽 위 **← 뒤로** 를 누르면 직전 화면으로 돌아갑니다.

## 게재 스케줄 관리하기

이 광고를 어느 기기에서, 어떤 기간·시간·요일에 내보낼지 정하는 화면입니다. **super_admin** 또는 **enterprise** 권한이 있는 계정만 볼 수 있습니다.

![광고 게재 스케줄 — 기기별 배정과 시간대](screenshots/ad-schedules-overview.png)

| 열 | 설명 |
| --- | --- |
| **기기** | 스케줄이 적용된 기기 이름입니다. |
| **기간** | 시작 날짜 ~ 종료 날짜입니다. |
| **시간** | 하루 중 노출 시작 ~ 종료 시간입니다. |
| **요일** | 노출 요일(일·월·화·수·목·금·토)입니다. |
| **우선순위** | 숫자가 높을수록 먼저 표시됩니다. |
| **수정 / 삭제** | 각 줄의 스케줄을 고치거나 지웁니다. |

스케줄이 하나도 없으면 `등록된 스케줄이 없습니다.` 라고 표시됩니다. 위쪽 검색창(`기기명·날짜 검색`)으로 목록을 좁힐 수 있습니다.

### 스케줄 한 건 추가·수정하기

1. 오른쪽 위 **스케줄 추가** 버튼을 누르면 **스케줄 추가** 창이 열립니다.
2. **기기 선택**에서 `기기를 선택하세요` 목록에서 기기를 고릅니다.
3. **시작 날짜** / **종료 날짜**, **시작 시간** / **종료 시간**을 정합니다.
4. **요일** 버튼(일~토)을 눌러 노출할 요일을 켜고 끕니다.
5. **우선순위** 숫자를 입력합니다. (`숫자가 높을수록 우선 표시됩니다`)
6. **추가**(수정 시 **수정**)를 누릅니다.
7. 이미 있는 스케줄은 목록의 **수정**을 눌러 같은 창에서 값을 바꿉니다.

> ⚠️ **시작 날짜/시간이 종료보다 늦으면** 저장되지 않습니다. 특히 자정을 넘기는 시간대(예: 22:00 ~ 02:00)는 지원하지 않으니, 밤샘 노출은 날짜를 나눠서 등록하세요.

### 여러 기기에 한 번에 배정하기

같은 조건을 여러 기기에 동시에 넣을 때 사용합니다.

1. 오른쪽 위 **일괄 배정** 버튼을 누르면 **일괄 스케줄 배정** 창이 열립니다.
2. 왼쪽 **기기 선택** 목록에서 기기를 체크합니다. **전체 선택** / **전체 해제**로 한꺼번에 고를 수 있습니다.
3. 오른쪽에서 시작·종료 날짜, 시작·종료 시간, 요일, 우선순위를 정합니다.
4. 아래 **N개 기기에 배정** 버튼을 누릅니다.
5. 배정이 끝나면 `N개 기기에 스케줄이 배정되었습니다.` 알림이 뜹니다.

> ⚠️ 일괄 배정은 단건 등록과 달리 날짜·시간·요일을 자동으로 막아 주지 않습니다. **시작이 종료보다 늦지 않은지, 요일을 최소 하나 선택했는지**를 배정 전에 반드시 확인하세요(잘못된 값이 여러 기기에 한꺼번에 저장될 수 있습니다).

> ⚠️ 일부 기기만 실패하면 `일괄 스케줄 배정 — 성공 N건 · 실패 N건` 이라고 표시됩니다. 성공한 기기는 그대로 두고, 실패한 기기만 다시 선택해 재시도하면 됩니다.

> 💡 스케줄을 지우려면 목록에서 해당 줄의 **삭제**를 누르고 `이 스케줄을 삭제하시겠습니까?` 확인 창에서 삭제를 확정합니다. 광고가 삭제된 경우 제목 옆에 `- 삭제된 광고`가 표시되며, 이때는 **스케줄 추가**·**일괄 배정** 버튼이 비활성화됩니다.


# 플레이리스트

**플레이리스트** 화면에서는 기기별로 광고가 순환되는 방식을 정하고, 확률 방식을 쓰는 기기에서 각 광고가 뽑힐 상대적인 가중치를 관리합니다. 접속 주소는 https://admin.adluck7.com 이며, 왼쪽 메뉴에서 **플레이리스트**를 눌러 들어갑니다.

화면 맨 위에는 제목 **플레이리스트**와 함께 안내 문구 "기기별 광고 순환 방식과, 확률 모드에서 광고가 선택될 상대 가중치를 관리합니다."가 표시됩니다. 아래로는 두 개의 카드가 이어집니다.

![플레이리스트 — 기기별 재생 방식과 광고별 가중치](screenshots/playlist-overview.png)

> 💡 데이터를 불러오는 동안에는 화면 가운데에 로딩 표시가 잠시 나타났다가, 준비가 끝나면 두 카드가 함께 나타납니다.

## 기기별 재생 방식

첫 번째 카드 **기기별 재생 방식**에서는 각 기기가 광고를 어떤 순서 규칙으로 재생할지 고릅니다. 카드 설명에 적힌 대로 "랜덤 순환은 모든 광고를 골고루(무중복 셔플) 재생하고, 가중치 확률은 아래 광고별 가중치에 비례해 추첨합니다."

### 화면 요소

| 요소 | 설명 |
| --- | --- |
| **기기** | 기기 이름 |
| **위치** | 기기가 설치된 장소 |
| **재생 방식** | **랜덤 순환** / **가중치 확률** 중 하나를 고르는 토글 버튼 |

두 가지 재생 방식의 뜻은 다음과 같습니다.

| 재생 방식 | 동작 |
| --- | --- |
| **랜덤 순환** | 모든 광고를 겹치지 않게 섞어(무중복 셔플) 골고루 재생합니다. |
| **가중치 확률** | 아래 **광고별 가중치**에 비례해 광고를 추첨합니다. |

### 작업 순서

1. 방식을 바꾸려는 기기의 행을 찾습니다.
2. 오른쪽 **재생 방식** 칸에서 원하는 버튼(**랜덤 순환** 또는 **가중치 확률**)을 누릅니다.
3. 저장이 끝나면 화면 오른쪽 아래에 "○○○: 가중치 확률 모드로 변경했습니다." 또는 "○○○: 랜덤 순환 모드로 변경했습니다."라는 알림이 뜹니다.

> 💡 버튼을 누르면 곧바로 저장됩니다. 별도의 저장 버튼은 없습니다. 저장이 진행되는 동안에는 버튼이 잠시 눌리지 않아 실수로 두 번 바뀌는 것을 막아 줍니다.

> ⚠️ 이 카드는 **기기 편집 권한(devices:write)**이 있는 계정에서만 버튼을 조작할 수 있습니다. 권한이 없으면 토글 버튼이 비활성화되어 보기만 가능합니다.

> ⚠️ 등록된 기기가 없으면 표 대신 "등록된 기기가 없습니다."라는 문구가 표시됩니다.

## 광고별 가중치

두 번째 카드 **광고별 가중치**에서는 각 광고에 숫자로 가중치를 부여합니다. 카드 설명에 적힌 대로 이 값은 "가중치 확률 모드 기기에서만 적용됩니다. 비중(%)은 활성 광고 전체 기준 근사치이며, 실제 추첨은 각 기기 화면 영역에 스케줄된 광고들 안에서 이뤄집니다."

### 화면 요소

| 요소 | 설명 |
| --- | --- |
| **광고** | 광고 제목 |
| **타입** | 광고 종류 (**이미지** / **영상** / **게임**) |
| **상태** | **활성** 또는 **비활성** |
| **가중치** | 광고가 뽑힐 상대 비중을 정하는 숫자 입력칸 (1 이상) |
| **비중(근사)** | 활성 광고 전체를 기준으로 계산한 대략적인 점유 비율(%). 비활성이거나 계산할 수 없으면 **—**로 표시 |

### 작업 순서

1. 가중치를 조정할 광고의 행을 찾습니다.
2. **가중치** 칸의 숫자를 원하는 값(1 이상의 정수)으로 바꿉니다.
3. 입력칸 밖을 클릭하거나 **Enter** 키를 누르면 저장됩니다.
4. 저장이 끝나면 "○○○: 가중치를 5(으)로 저장했습니다."처럼 실제 저장된 값이 담긴 알림이 표시됩니다.

> 💡 값을 바꾼 뒤 반드시 입력칸 밖을 누르거나 **Enter**를 눌러야 저장이 반영됩니다. 숫자만 고치고 그대로 두면 저장되지 않습니다.

> 💡 가중치를 크게 줄수록 그 광고가 더 자주 뽑힙니다. 예를 들어 두 광고의 가중치가 각각 3과 1이면, 대략 3:1 비율로 재생됩니다. **비중(근사)** 칸에서 대략적인 비율을 미리 확인할 수 있습니다.

> ⚠️ 1보다 작은 값이나 숫자가 아닌 값, 빈칸을 입력하면 저장되지 않고 원래 값으로 되돌아갑니다. 가중치는 항상 1 이상의 정수로만 저장됩니다(소수를 넣으면 정수로 내려 저장됩니다).

> ⚠️ **비중(%)**은 활성 광고 전체를 기준으로 한 근사치입니다. 실제 광고 재생은 각 기기 화면 영역에 스케줄된 광고들 안에서만 이뤄지므로, 이 값과 실제 노출 비율은 다를 수 있습니다. 또한 가중치는 **가중치 확률** 모드인 기기에서만 효과가 있습니다.

> ⚠️ 이 카드에서 값을 바꾸려면 **광고 편집 권한(ads:write)**이 필요합니다. 권한이 없으면 입력칸이 비활성화되어 보기만 가능합니다.

> ⚠️ 등록된 광고가 없으면 표 대신 "등록된 광고가 없습니다."라는 문구가 표시됩니다.


# 계정 관리와 권한

**계정 관리** 화면에서는 기업 계정과 하위 계정을 트리(나무 가지) 형태로 관리하고, 각 하위 계정에 어떤 일을 할 수 있는지 권한을 위임합니다. 계정을 새로 만들거나 수정·삭제하고, 비밀번호 재설정, 강제 로그아웃, 정지/활성화(하나씩 또는 여러 개 한꺼번에)를 이곳에서 처리합니다.

이 화면은 https://admin.adluck7.com 에 로그인한 뒤 사이드바에서 **계정 관리** 를 클릭하면 열립니다.

> ⚠️ 이 화면 전체는 `accounts:manage` 권한이 있는 계정만 볼 수 있습니다. 권한이 없으면 **접근 권한이 없습니다 / 계정 관리(accounts:manage) 권한이 필요합니다.** 안내만 표시됩니다. 기업 계정도 이 권한이 있으면 접근할 수 있으나, 자기 아래 하위 계정만 보고 관리할 수 있습니다.

---

## 계정 트리 살펴보기

![계정 관리 트리 전체 화면 — 상위/하위 계정 위계와 권한 요약 칩](screenshots/accounts-tree-overview.png)

계정들이 위아래 위계(상위 계정 아래 하위 계정)로 정리되어 한눈에 보입니다.

**화면 요소**

- **새 계정 생성** — 헤더 우측(또는 계정이 하나도 없을 때 가운데)에 있는 버튼입니다. 클릭하면 새 계정을 만드는 창이 열립니다.
- **이메일·이름 검색** — 이메일이나 이름 일부를 입력하면 해당 계정만 걸러서 보여 줍니다.
- 각 계정 옆에는 권한을 요약한 칩이 표시됩니다. **전체 권한**, **권한 없음**, **커스텀 N개** 처럼 나타나며, 자식이 있으면 **자식 N**, 연결된 기기가 있으면 **기기 N대** 도 함께 보입니다.
- 자식(하위 계정)이 있는 계정은 **하위 계정 펼치기** / **하위 계정 접기** 화살표로 열고 닫을 수 있습니다.

> 💡 관리 권한이 있으면 각 계정 앞에 체크박스가 나타나 여러 계정을 한꺼번에 정지하거나 활성화할 수 있습니다. 단, 본인 계정 체크박스는 선택할 수 없습니다(**자기 계정은 일괄 작업 대상이 아닙니다**).

---

## 계정 메뉴 열기

![계정 노드 케밥 메뉴 — 하위 계정 추가·수정·비밀번호 재설정·강제 로그아웃·정지/활성화·삭제](screenshots/accounts-node-menu.png)

각 계정 오른쪽의 케밥 버튼(⋮)을 누르면 그 계정에 대해 할 수 있는 작업 메뉴가 열립니다.

**메뉴 항목**

| 항목 | 하는 일 |
| --- | --- |
| **하위 계정 추가** | 이 계정 아래에 새 하위 계정을 만듭니다. |
| **수정** | 이름·상태·권한을 변경합니다. |
| **비밀번호 재설정** | 새 비밀번호를 지정합니다. |
| **강제 로그아웃** | 현재 로그인된 모든 세션을 종료합니다(계정은 활성 유지). |
| **정지** / **활성화** | 계정을 정지하거나 다시 활성화합니다. |
| **삭제** | 계정을 삭제합니다. |

> ⚠️ 이 메뉴는 관리 권한이 있는 계정에만 표시됩니다.

---

## 새 하위 계정 만들고 권한 주기 (위저드)

새 계정은 **계정 정보 → 권한** 2단계 위저드로 만듭니다. 화면 위쪽의 원형 번호(**1** · **2**)가 현재 단계를 알려 줍니다.

### 1단계 — 계정 정보

![신규 계정 생성 위저드 1단계 '계정 정보' — 이메일·비밀번호·이름 입력](screenshots/accounts-wizard-step1-info.png)

**입력 항목**

- **이메일** (필수) — placeholder `user@example.com`. 수정 시에는 변경할 수 없습니다.
- **비밀번호** (필수, 새 계정 생성 시에만) — 최소 10자입니다.
- **이름** (필수) — placeholder `관리자 이름`.
- **역할** — 옵션은 **기업 계정** / **최고 관리자** 입니다.

**작업 순서**

1. 계정 옆 케밥에서 **하위 계정 추가** 를 누르거나, 헤더의 **새 계정 생성** 을 누릅니다.
2. **이메일**, **비밀번호**, **이름** 을 입력합니다.
3. **다음** 을 눌러 권한 단계로 넘어갑니다.

> 💡 **역할** 선택(**기업 계정** / **최고 관리자**)은 최고 관리자가 최상위 계정을 새로 만들 때만 나타납니다. 하위 계정은 항상 기업 계정으로 만들어집니다.

### 2단계 — 권한

![권한 편집기 — 권한 세트 프리셋과 도메인별 레벨(없음/조회/편집/관리) 및 적용 후 권한 미리보기](screenshots/accounts-policy-editor-levels.png)

여기서 하위 계정이 무엇을 할 수 있는지 정합니다.

**화면 요소**

- **권한 세트** — 미리 만들어진 프리셋을 카드로 고릅니다(전체 권한 / 뷰어 / 기기 운영자 / 콘텐츠 편집자 / 랜딩 디자이너 / 커스텀).
- **도메인 레벨 행** — 항목(기기·광고 등)별로 **없음** / **조회** / **편집** / **관리** 중 하나를 고릅니다.
- **원격 명령 허용 (기기 재시작·잠금 등)** — 기기 도메인을 **편집** 으로 두었을 때 나타나는 체크박스입니다.
- **리소스 범위** — **전체** 또는 **선택 항목** 을 고릅니다. **선택 항목** 을 고르면 특정 기기·광고·설문·보상만 골라 권한을 한정할 수 있습니다.
- **역할 템플릿** — 자주 쓰는 권한 조합을 저장해 재사용합니다. 드롭다운에서 **역할 적용...** 으로 불러오고, 이름을 입력해 **현재 권한을 역할로 저장** 할 수 있습니다.
- **적용 후 권한** — 최종 권한을 요약해 보여 줍니다. 수정 모드에서는 **변경 사항** 을 전→후로 비교(추가는 녹색, 제거는 빨강)해 줍니다.

**작업 순서**

1. **권한 세트** 에서 상황에 맞는 프리셋을 먼저 고릅니다.
2. 필요하면 **도메인 레벨 행** 에서 항목별 레벨을 조정합니다.
3. (선택) **리소스 범위** 를 **선택 항목** 으로 바꿔 특정 대상에만 권한을 한정합니다.
4. **적용 후 권한** 미리보기를 확인한 뒤 **생성** 을 누릅니다.

> 💡 프리셋을 먼저 고르고 세부만 손보면 훨씬 빠릅니다. 자주 쓰는 조합은 **역할 템플릿** 으로 저장해 다른 계정을 만들 때 **역할 적용** 으로 재사용하세요(단, 전체 권한은 저장할 수 없습니다).

> ⚠️ 본인의 권한을 넘어서 위임할 수는 없습니다. 초과하면 **내 권한을 초과해 위임할 수 없습니다.** 오류나 **일부 권한이 내 권한을 초과합니다. 초과 항목은 저장 시 거부됩니다.** 경고가 표시됩니다. 또한 기업 트리 계정에는 랜딩 디자이너 같은 플랫폼 전용 권한이 숨겨지며 저장 시 제거됩니다.

---

## 고급 규칙 편집 (거부·IP·시간)


IP나 시간대에 따라 접근을 막는 등, 더 세밀한 규칙이 필요할 때 사용합니다. 프리셋이 전체 권한이 아닐 때 편집기 우측의 **고급 규칙 편집** 링크로 들어갑니다(다시 돌아올 때는 **레벨 편집기로**).

**화면 요소**

- **허용** / **거부** — 규칙의 효과를 고릅니다. 거부가 허용보다 우선합니다.
- **액션 카탈로그** — 도메인별 권한을 체크하거나 **모든 권한 (\*)** 을 선택합니다.
- **리소스 범위** — 규칙을 전체에 적용할지 특정 대상에만 적용할지 정합니다.
- **조건 사용 (IP·시간)** — 허용 IP를 CIDR 형식으로(한 줄에 하나) 입력하고, 시작~종료 시각으로 **시간대 제한** 을 걸 수 있습니다(Asia/Seoul 기준).

**작업 순서**

1. **고급 규칙 편집** 을 누릅니다.
2. **규칙 추가** 를 누르고 효과를 **허용** 또는 **거부** 로 선택합니다.
3. **액션 카탈로그** 에서 권한을 체크합니다(또는 **모든 권한 (\*)**).
4. 리소스 범위를 지정합니다.
5. **조건 사용 (IP·시간)** 을 체크해 허용 CIDR과 시간대 제한을 입력합니다.

> 💡 필요 없는 규칙은 **규칙 삭제** 로 지울 수 있습니다. IP/시간대처럼 세밀한 제한은 거부(deny) 규칙과 함께 작성하면 확실합니다(거부가 허용보다 우선).

---

## 계정 수정하기 (재인증)

기존 계정의 케밥에서 **수정** 을 누르면 위저드 없이 한 화면에서 편집합니다.

**바꿀 수 있는 것**

- **이름**
- **계정 상태** — **활성** / **정지** / **유예** / **비활성**
- 권한 섹션의 정책

**작업 순서**

1. 케밥 → **수정** 을 누릅니다.
2. 이름·계정 상태를 바꾸고, 권한 섹션에서 정책을 조정합니다.
3. **변경 사항** 전→후 비교로 의도치 않은 변화가 없는지 확인합니다.
4. **수정** 을 누릅니다.
5. 보안 재인증 팝업이 뜨면 비밀번호를 입력합니다(**권한·역할 변경은 보안을 위해 재인증이 필요합니다.**).

> ⚠️ 권한·역할 변경과 삭제에는 비밀번호 재인증이 필요합니다. 재인증을 취소하면 작업이 중단됩니다. 또한 프로필/권한과 상태 변경은 별개 요청이라, **프로필·권한은 저장되었으나 계정 상태 변경에 실패했습니다** 처럼 일부만 적용될 수 있습니다.

---

## 여러 계정 한꺼번에 정지/활성화

트리에서 계정 체크박스를 하나 이상 선택하면, 위쪽에 **N개 선택됨** 일괄 작업 바가 나타납니다.

**작업 순서**

1. 대상 계정들의 체크박스를 선택합니다(본인 계정은 제외).
2. **일괄 정지**(확인 창이 뜹니다) 또는 **일괄 활성화** 를 누릅니다.
3. 결과 토스트로 성공/실패 개수를 확인합니다. 선택을 비우려면 **선택 해제** 를 누릅니다.

> ⚠️ 정지(일괄 정지 포함)는 즉시 로그인이 차단되고 열려 있던 세션도 종료됩니다. **강제 로그아웃** 은 세션만 끊고 계정은 활성 상태로 유지된다는 점이 다릅니다.

---

## 비밀번호 재설정·강제 로그아웃·삭제

- **비밀번호 재설정** — 케밥 → **비밀번호 재설정** → **새 비밀번호**(최소 10자) 입력 → **재설정**.
- **강제 로그아웃** — 케밥 → **강제 로그아웃** → 확인하면 모든 세션이 폐기됩니다.
- **삭제** — 케밥 → **삭제** → 비밀번호 재인증 → 확인.

> ⚠️ 하위 계정이 있는 계정은 삭제할 수 없습니다. **하위 계정이 있으면 먼저 정리하세요** 안내가 뜨므로, 아래 계정들을 먼저 옮기거나 삭제한 뒤 진행하세요.


# 감사 로그

감사 로그는 **누가·언제·무엇을 변경했는지** 추적하는 화면입니다. 광고·설문·보상·기기 설정의 변경과 삭제, 원격 명령 발행, 계정 관련 작업 등이 자동으로 기록되므로, 문제가 생겼을 때 원인을 되짚어 볼 수 있습니다. 접속 주소는 https://admin.adluck7.com 이며, 사이드바의 **감사 로그** 메뉴로 들어갑니다.

> 💡 이 메뉴와 화면은 **감사 로그 조회 권한(audit:read)** 이 있는 계정만 보입니다. 권한이 없으면 **권한이 없습니다** 와 함께 "감사 로그 조회 권한(audit:read)이 필요합니다. 관리자에게 문의하세요." 안내가 표시되니, 필요한 경우 계정 관리자에게 요청하세요.

## 화면 살펴보기

기록을 조회하는 필터 영역과, 조건에 맞는 결과를 보여 주는 표로 구성됩니다.

![감사 로그 — 기업·작업·기간 필터와 CSV 내보내기](screenshots/audit-log-overview.png)

화면 상단에는 제목 **감사 로그** 와 부제 "누가·언제·무엇을 변경했는지 추적합니다. 변경·삭제·원격명령·계정 작업이 기록됩니다." 가 표시되고, 우측 상단에 **CSV 내보내기** 버튼이 있습니다.

| 요소 | 설명 |
| --- | --- |
| **기업 계정** | 조회할 기업을 고르는 드롭다운입니다. 아래에 "조회할 기업을 선택하세요" 안내가 붙어 있으며, **최고 관리자 계정에만 보입니다.** 기업 계정은 자기 회사 기록만 자동으로 조회됩니다. |
| **작업** | 조회할 작업 종류를 고르는 드롭다운입니다. 비워 두면 **전체** 가 조회됩니다. (예: 광고 생성, 기기 설정 변경, 원격 명령 발행, 계정 상태 변경 등) |
| **작업자 UID** | 특정 담당자의 기록만 보고 싶을 때 그 사람의 계정 식별자(UID)를 입력하는 칸입니다. |
| **시작일** / **종료일** | 조회할 기간을 정하는 날짜 칸입니다. 한국 시간 기준으로 계산됩니다. |
| **조회** | 설정한 조건으로 기록을 불러오는 버튼입니다. |
| **CSV 내보내기** | 현재 조회된 결과를 CSV 파일로 내려받는 버튼입니다. 결과가 없거나 필터를 바꾼 직후에는 비활성화됩니다. |

### 감사 로그 조회하기

1. (최고 관리자라면) **기업 계정** 드롭다운에서 조회할 기업을 먼저 선택합니다.
2. 필요에 따라 **작업**, **작업자 UID**, **시작일**, **종료일** 을 설정합니다. 조건을 비워 두면 더 넓은 범위가 조회됩니다.
3. **조회** 버튼을 누릅니다.
4. 아래 표에 조건에 맞는 기록이 나타납니다.

> 💡 조건을 아직 한 번도 조회하지 않았다면 **조회를 실행하세요** — "필터를 설정하고 조회 버튼을 누르세요." 안내가 표시됩니다. 필터를 정한 뒤 **조회** 를 눌러 주세요.

> ⚠️ 최고 관리자가 **기업 계정** 을 고르지 않으면 **기업을 선택하세요** — "감사 로그를 조회할 기업 계정을 먼저 선택하세요." 라는 안내만 보이고, 기업을 선택할 때까지 **조회** 버튼은 눌리지 않습니다. 먼저 기업을 선택하세요.

## 결과 표 읽기

조회에 성공하면 아래와 같은 항목으로 기록이 정리되어 표시됩니다.

| 열 | 설명 |
| --- | --- |
| **시각** | 작업이 일어난 날짜와 시간입니다. |
| **작업자** | 작업을 한 사람의 이메일(또는 계정 식별자)입니다. 아래에 역할(**최고 관리자** 또는 **기업**)과 접속 IP 주소가 함께 표시됩니다. |
| **작업** | 어떤 작업이었는지 한글로 표시됩니다. (예: 광고 삭제, 기기 설정 변경, 비밀번호 재설정) |
| **대상** | 작업이 적용된 대상의 종류와 식별자(ID)입니다. |
| **변경 내용** | 값이 어떻게 바뀌었는지 "항목: 이전 값 → 이후 값" 형태로 보여 줍니다. 변경 정보가 없으면 `—`, 데이터가 너무 크면 "(데이터 큼 — 생략)" 으로 표시됩니다. |
| **결과** | 작업의 성공 여부입니다. **성공** 또는 **실패** 뱃지로 표시됩니다. |

한 번에 일부 기록만 불러오며, 아래쪽에 **더 보기** 버튼이 있으면 눌러서 다음 기록을 이어서 불러올 수 있습니다.

> 💡 조건에 맞는 기록이 하나도 없으면 **기록 없음** — "조건에 맞는 감사 로그가 없습니다." 라고 표시됩니다. 기간이나 작업 조건을 넓혀서 다시 조회해 보세요.

### 필터를 바꿨을 때 주의

필터를 바꾼 뒤 아직 다시 조회하지 않으면, 화면에 노란색 경고 배너로 "필터가 변경되었습니다. 아래 결과는 이전 조회 기준이며, "조회"를 눌러 갱신하세요." 가 나타납니다.

> ⚠️ 이 경고가 떠 있는 동안에는 표에 보이는 내용이 지금 설정한 필터와 다를 수 있고, **CSV 내보내기** 도 잠깁니다. **조회** 버튼을 다시 눌러 결과를 갱신한 뒤 확인하거나 내보내세요.

## 기록을 파일로 내려받기

현재 조회된 결과를 파일로 보관하거나 다른 곳에서 검토하고 싶을 때 사용합니다.

1. 원하는 조건으로 **조회** 를 실행해 결과가 표에 나온 것을 확인합니다.
2. 우측 상단의 **CSV 내보내기** 버튼을 누릅니다.
3. `audit-log-날짜.csv` 형식의 파일이 내려받아집니다.

내려받은 파일에는 시각, 작업자, 역할, 작업, 대상유형, 대상ID, 결과, 변경, IP 정보가 담깁니다.

> 💡 표에 보이는 기록만 파일에 담깁니다. 더 많은 기록을 함께 내보내려면 먼저 **더 보기** 로 필요한 만큼 불러온 뒤 내보내세요.

> ⚠️ 결과가 하나도 없거나 필터를 바꾼 직후에는 **CSV 내보내기** 가 비활성화됩니다. 버튼에 마우스를 올리면 "필터가 변경되었습니다. '조회'를 눌러 갱신한 뒤 내보내세요." 안내가 표시되니, **조회** 를 먼저 실행해 주세요.


# 설정과 보안

이 챕터에서는 어드민 화면을 내 취향에 맞게 조정하는 **설정** 페이지와, 비밀번호·세션을 관리하는 **보안 설정** 페이지, 그리고 내 프로필을 확인하는 **계정 정보** 페이지를 다룹니다. 어드민 웹은 https://admin.adluck7.com 으로 접속합니다.

## 설정

공통 헤더 오른쪽 위 프로필 드롭다운에서 **설정**을 누르면 설정 페이지로 이동합니다. 여기서는 테마, 목록 표시 방식, 편집 경고, 알림, 자동 로그아웃 같은 개인 환경을 조정합니다.

![설정 화면 — 테마 선택, 테이블 표시, 편집, 알림, 보안(자동 로그아웃), 초기화 카드](screenshots/settings-security-general-overview.png)

이 페이지의 가장 큰 특징은 **자동 저장**입니다. 헤더에 **변경사항은 자동으로 저장됩니다.** 라는 안내가 있고, 값을 바꿀 때마다 우측 상단에 **저장 중...** → **저장됨** 상태가 표시됩니다. 저장에 실패하면 **저장 실패** 가 나타납니다.

### 화면 요소

| 카드 | 내용 |
| --- | --- |
| **테마** | 라이트 / 다크 / 미드나잇 블루 / 고대비 4종 프리뷰 카드 |
| **테이블 표시** | **페이지당 항목 수** 드롭다운(10개 / 20개 / 50개 / 100개) |
| **편집** | **미저장 변경 이탈 경고** 스위치 |
| **알림** | **운영 알림** / **계정 알림** 스위치 |
| **보안** | **자동 로그아웃 시간** 드롭다운 |
| **설정 초기화** | **초기화** 버튼(모든 설정을 기본값으로 복원) |

> 💡 별도 저장 버튼이 없습니다. 값만 바꾸면 됩니다. 우측 상단의 **저장됨** 표시로 반영 여부를 확인하세요.

### 테마 바꾸기

![테마 선택 — 라이트/다크/미드나잇 블루/고대비 4종 프리뷰(선택 카드에 체크)](screenshots/settings-security-theme-picker.png)

**테마** 카드에서는 화면 배색을 4종 중에서 고를 수 있습니다. 각 카드는 실제 화면을 축소한 미니어처 프리뷰로 보여 줍니다.

1. **테마** 카드에서 **라이트**, **다크**, **미드나잇 블루**, **고대비** 중 원하는 프리뷰를 클릭합니다.
2. 선택하면 자동 저장됩니다.
3. 현재 선택된 테마 카드에는 체크 표시가 나타납니다.

> 💡 눈이 부시거나 어두운 환경에서 오래 작업한다면 **다크** 또는 **미드나잇 블루**, 글자 대비를 크게 보고 싶다면 **고대비**를 사용해 보세요.

> ⚠️ 현재 관리자 화면은 다크 테마로 통일되어 표시됩니다(개편 전환기). 라이트·미드나잇 블루·고대비를 골라도 관리자 화면 배색은 다크로 유지되며, 선택한 값은 계정에 저장됩니다.

### 목록·편집·알림 조정

- **테이블 표시 / 페이지당 항목 수**: 기기 목록 같은 표에서 한 페이지에 몇 줄을 보여줄지 정합니다(10개 / 20개 / 50개 / 100개).
- **편집 / 미저장 변경 이탈 경고**: 켜 두면 *저장하지 않은 변경이 있을 때 페이지를 떠나면 확인합니다.* 실수로 작업 내용을 잃지 않도록 도와줍니다.
- **알림 / 운영 알림**: 기기 오프라인·이상·시스템 오류 알림을 켜고 끕니다. 끄면 종 아이콘 배지와 목록에서 빠집니다(알림 페이지에서는 계속 확인할 수 있습니다).
- **알림 / 계정 알림**: 구독·계정 상태 변경 알림을 켜고 끕니다.

### 자동 로그아웃 시간

**보안** 카드의 **자동 로그아웃 시간** 드롭다운으로, 아무 조작 없이 방치했을 때 자동으로 로그아웃되는 시간을 정합니다.

1. **보안** 카드에서 **자동 로그아웃 시간** 드롭다운을 엽니다.
2. **사용안함 / 15분 / 30분 / 1시간 / 2시간 / 4시간 / 8시간** 중에서 선택합니다.
3. 선택 즉시 자동 저장됩니다.

> ⚠️ **사용안함**으로 두면 자리를 비워도 로그아웃되지 않습니다. 여러 사람이 쓰는 공용 PC에서는 **15분~30분**처럼 짧게 설정하는 것이 안전합니다.

### 설정 초기화

**설정 초기화** 카드의 **초기화** 버튼을 누르면 *모든 설정을 기본값으로 복원합니다.* 실수를 막기 위해 **취소** / **확인** 2단계 확인을 거칩니다.

## 보안 설정

**계정 정보** 페이지의 **보안** 카드에서 **비밀번호 변경**을 누르면 보안 설정 페이지(/settings/security)로 이동합니다. 페이지 상단의 **← 설정** 링크로 설정 페이지로 돌아갈 수 있습니다.

> ⚠️ 이 페이지는 로그인한 상태에서만 열립니다. 로그인이 풀린 경우 **로그인이 필요합니다.** 안내만 표시됩니다.

### 비밀번호 변경

![비밀번호 변경 폼 — 현재/새/새 확인 필드와 정책 안내](screenshots/settings-security-password-change.png)

**비밀번호 변경** 카드에서 로그인 비밀번호를 바꿉니다.

1. **현재 비밀번호** 에 지금 쓰는 비밀번호를 입력합니다.
2. **새 비밀번호** 에 새 비밀번호를 입력합니다. 조건은 `10자 이상, 영문 대·소문자·숫자` 입니다.
3. **새 비밀번호 확인** 에 같은 값을 한 번 더 입력합니다.
4. **비밀번호 변경** 버튼을 누릅니다. 처리 중에는 **변경 중...** 으로 바뀌고, 완료되면 **비밀번호가 변경되었습니다.** 토스트가 뜹니다.

> 💡 조건에 못 미치면 **10자 이상·영문 대소문자·숫자가 필요합니다.**, 두 번째 입력이 다르면 **새 비밀번호와 일치하지 않습니다.** 안내가 필드 아래에 표시됩니다.

### 세션 관리

**세션 관리** 카드의 **모든 기기에서 로그아웃** 버튼은 내 계정이 로그인되어 있는 모든 기기·브라우저의 세션을 한 번에 폐기합니다. 분실·도난·비밀번호 노출이 의심될 때 사용합니다.

1. **모든 기기에서 로그아웃** 버튼을 누릅니다.
2. **모든 기기에서 로그아웃하시겠습니까?** 확인 다이얼로그에서 **전체 로그아웃** 을 누릅니다.
3. 모든 세션이 폐기되고 로그인 화면으로 이동합니다.

> ⚠️ 지금 사용 중인 이 기기도 함께 로그아웃됩니다. 실행 직후 다시 로그인해야 합니다.

## 계정 정보

프로필 드롭다운의 **계정 정보**(/account)에서는 *본인 계정의 기본 정보와 보안을 관리합니다.* 세 개의 카드로 구성됩니다.

- **기본 정보**: 이메일(읽기 전용)·역할 뱃지·이름이 있습니다. 이름은 수정 후 저장할 수 있고, 성공하면 **이름이 변경되었습니다.** 토스트가 뜹니다.
- **계정 상세**: 가입일, 소속 기업, 보유 기기 수, 내 권한 요약(전체 권한 또는 커스텀 작업·도메인 목록)을 보여 줍니다.
- **보안**: **비밀번호 변경** 버튼이 있습니다. 누르면 보안 설정 페이지로 바로 이동합니다.

> 💡 비밀번호 변경은 보안 설정 페이지뿐 아니라 계정 정보 페이지의 **보안** 카드에서도 바로 시작할 수 있습니다.


---

# 문제 해결

운영 중 자주 겪는 상황과 확인 순서입니다. 대부분은 아래 표로 해결되며, 그래도 안 되면 **운영 탭 → 진단/로그 수집** 으로 데이터를 모아 기술 지원에 문의하세요.

| 증상 | 이렇게 확인하세요 |
| --- | --- |
| **화면에 광고가 안 나옴** | ① 광고 배치 탭에서 현재 씬에 광고가 배정돼 있는지, 광고가 활성 상태인지 확인 ② 기기가 온라인인지(정보·통계/건강 탭) ③ 데이터 분석의 **노출 추이** 에서 온라인인데 노출이 0이면 재생 실패 신호 |
| **설문 QR이 안 뜸** | ① 설문이 이 기기에 배정·활성 상태인지(설문 탭) ② 스케줄 탭의 **QR(설문) 창** 이 지금 시간대를 차단하고 있지 않은지 ③ 광고 터치 동작이 **무반응** 으로 설정돼 있지 않은지 |
| **보상 카드가 안 나옴** | ① 보상·디스펜서 탭에서 보상 재고가 남았는지 ② **토출 확률** 합계와 각 등수 설정 확인 ③ 정보·통계 탭의 **설문 / 토출 통계**(실토출·발사·시도 비교)와 **최근 토출 이력**(성공/ACK 없음/발사 실패)을 확인 ④ 디스펜서 카드함·케이블 물리 확인 |
| **기기가 오프라인** | ① 기기 전원과 네트워크(Wi-Fi) 연결 ② 건강 탭의 상태 변경 히스토리로 오프라인 전환 시점 확인. 저녁·야간에는 전원을 끄는 운영이 정상일 수 있습니다 |
| **변경이 반영 안 됨** | 운영 탭 → **콘텐츠 새로고침** 을 보내면 광고·스케줄·설정이 즉시 다시 로드됩니다. 별도 조치가 없으면 최대 5분 이내 자동 반영됩니다 |
| **화면이 멈추거나 이상함** | 운영 탭 → **앱 재시작** 으로 원격 재시작. 그 전에 정보·통계 탭의 **지금 캡처**(또는 운영 탭 원격 명령의 **화면 캡처**)로 현재 화면을 먼저 확인할 수 있습니다 |

---

# 부록

## A. 원격 명령 6종 (운영 탭)

| 명령 | 용도 |
| --- | --- |
| **콘텐츠 새로고침** | 광고·스케줄·화면 문구 등 변경 사항을 기기에 즉시 반영 |
| **앱 재시작** | 화면이 이상할 때 키오스크 앱을 원격으로 재시작 |
| **QR 미리보기** | 저장된 QR 화면 설정을 기기 화면에 약 30초 띄워 실제 노출을 확인 |
| **화면 캡처** | 현재 기기 화면을 원격으로 캡처해 확인 |
| **진단 리포트** | 기기 상태·버전·네트워크 진단 리포트(JSON) 수집 |
| **로그 수집** | 문제 분석용 상세 로그 수집 |

- 명령은 보통 **2초 이내** 기기에 전달되며, 네트워크가 불안정해도 최대 30초 안에 폴링으로 전달됩니다.
- 예약 발송(특정 시각)과 여러 기기 일괄 발송(기기 목록에서 여러 대 선택 → 원격 명령)을 지원합니다.

## B. 스케줄 규칙 요약 (스케줄 탭)

- 규칙 종류 3가지: **광고 터치 동작**(설문 QR 표시 / 무반응), **씬 편성 창**(특정 시간대에 지정한 씬만 순환), **QR(설문) 창**(설문 진입 허용/차단).
- 규칙이 없는 시간대는 기본 동작(화면 터치 → 설문 QR, 모든 씬 순환, QR 상시 허용)입니다.
- 「게임 씬으로 전환」 선택지는 폐지됐습니다. 게임은 씬 안의 게임 요소를 직접 터치해 시작합니다. 과거에 저장된 규칙은 `지원 종료`로 표시되며 다른 값으로 바꾸면 사라집니다.
- 같은 종류의 규칙이 겹치면 **목록에서 위에 있는 규칙이 우선**합니다. ↑↓ 버튼으로 우선순위를 바꾸세요.
- 종료 시각이 시작보다 빠르면 **자정을 넘는 규칙**(예: 22:00~02:00)이 됩니다.
- 요일 칩을 아무것도 선택하지 않으면 **매일** 적용됩니다.

## C. 반영 시점과 시간대

- **자동 반영**: 광고 배치·스케줄·화면 문구 변경은 키오스크가 최대 5분 이내 자동으로 가져갑니다.
- **즉시 반영**: 운영 탭 → **콘텐츠 새로고침** 을 보내면 바로 다시 로드됩니다.
- **시간대**: 광고·씬·QR 스케줄과 통계·집계는 **한국 시간(Asia/Seoul)** 기준입니다. 단, **원격 명령 예약**의 예약 시각은 지금 사용 중인 **브라우저의 시간대**를 따릅니다.
- **장기 추이**(데이터 분석)는 매일 새벽 자동 집계되어 전일까지 반영됩니다.

## D. 자주 쓰는 용어

| 용어 | 뜻 |
| --- | --- |
| **씬(Scene)** | 키오스크 화면의 한 장면. 여러 씬이 순환하며, 씬 안에 광고·게임·QR·정적 영역을 배치합니다 |
| **세션** | 방문객이 QR을 스캔해 설문에 참여한 한 번의 흐름(스캔→완료) |
| **터치** | 방문객이 광고 화면을 터치해 참여를 시작한 횟수 |
| **완료율 / 세션화율** | 완료율=완료÷세션, 세션화율=세션÷터치 |
| **heartbeat** | 기기가 살아 있음을 알리는 신호(약 30초마다 발신). 마지막 신호가 2분 이상 없으면 오프라인으로 봅니다 |
| **디스펜서** | 보상 카드를 물리적으로 토출하는 장치(등수별 1등/2등/3등 구성) |
| **ACK** | 기기(디스펜서)가 명령을 받아 처리했음을 알리는 응답. "ACK 없음"은 카드가 실제로 나갔는지 기기가 확인해 주지 못했다는 뜻입니다 |
| **권한 코드** | 계정이 할 수 있는 작업을 나타내는 내부 코드. `devices:read`=기기 조회, `devices:write`=기기 편집, `accounts:manage`=계정 관리, `ads:write`=광고 편집, `analytics:read`=대시보드·데이터 분석, `audit:read`=감사 로그, `commands:execute`=원격 명령 실행 |

---

*본 문서는 AdLuck 어드민 기준으로 작성되었습니다. 기능 업데이트에 따라 화면이 다소 다를 수 있습니다. 문의: 담당 관리자 또는 도입 문의 채널.*