# 봇 설정 도우미 (Setup Wizard) 기획서

## 1. 개요

봇 설정 도우미는 관리자가 Kord 봇을 처음 서버에 추가했거나, 재설정이 필요할 때 직관적인 UI(마법사 형태)를 통해 필수 기능들을 순차적으로 설정할 수 있도록 돕는 기능입니다.

## 2. 진입점 (Trigger)

- **명령어**: `/setup`
- **실행 권한**: `Administrator` 또는 `Manage Guild` 권한 (명령어 자체의 `defaultMemberPermissions`로 제한)
- **실행 위치**: 모든 텍스트 채널 (단, 과정 중 타인의 방해나 혼선을 줄이기 위해 ephemeral(개인만 보기) 형태로 진행)

## 3. 설정 흐름 (Setup Flow)

설정은 스텝(Step) 단위로 진행되며, 각 스텝은 Embed 메시지와 하단 컴포넌트(버튼, Select Menu 등)로 구성됩니다.
사용자는 **[다음]**, **[이번 스텝 건너뛰기]**, **[설정 종료]** 버튼 등으로 흐름을 제어합니다.

### Step 0: 환영 및 소개 (Welcome)
- **내용**: Kord 봇 설정 마법사 시작을 알리고, 설정될 4가지 주요 항목들을 간략히 소개합니다.
  (1) 언어 설정, (2) 권한 점검, (3) 감사 채널 지정, (4) 임시 음성 채널 설정
- **액션**: `[시작하기]` 버튼 클릭 시 Step 1로 이동.

### Step 1: 언어 설정 (Language)

- **내용**: 서버의 기본 언어를 설정합니다. (i18n 기능 연동)
- **현재 설정 표시**: 기존에 설정된 언어 표시.
- **컴포넌트**: 지원하는 언어(Korean, English)를 선택할 수 있는 `StringSelectMenu`.
- **액션**: 
  - 선택 시 즉각적으로 DB 업데이트 및 언어 변경 적용. (이후 UI는 변경된 언어로 릴로드 됨)
  - `[다음]` / `[건너뛰기]` 버튼.

### Step 2: 권한 점검 (Permission Check)

- **내용**: 봇이 원활하게 동작하기 위해 필요한 필수 권한(서버 수준)이 부여되어 있는지 점검합니다.
- **컴포넌트**: 점검 통과 상태 (✅ 모두 정상 / ⚠️ 일부 부족). 부족한 경우 권한 부여를 안내합니다. (권한 검사 모듈 `/audit-permissions`의 축소판)
- **액션**: `[다시 검사]` / `[다음]` 버튼.

### Step 3: 감사 채널 설정 (Audit Channel)

- **내용**: 봇의 주요 이벤트와 에러 로그를 남길 시스템 통보 채널을 지정합니다.
- **컴포넌트**: 
  - 텍스트 채널을 선택하는 `ChannelSelectMenu` (ChannelType.GuildText 채널만).
  - `[사용 안함(비활성화)]` 버튼.
- **액션**: 채널 선택 시 DB 갱신 후, `[다음]` 버튼을 눌러 이동 (혹은 선택 즉시 자동 다음 이동 고려).

### Step 4: 임시 음성 채널 설정 (Voice Generator)

- **내용**: 임시 음성 채널 생성 시스템의 진입점이 될 '생성기 채널'을 지정하거나 새로 생성합니다.
- **컴포넌트**:
  - 기존 생성할 채널을 고르는 `ChannelSelectMenu` (ChannelType.GuildVoice).
  - `[자동 생성]` 버튼: 봇이 새 음성 카테고리와 "➕ 음성 채널 생성" 채널을 자동으로 만들어 줌.
  - `[건너뛰기]` 버튼.
- **액션**: 설정 시 즉각 시스템 구동. 이후 `[다음(완료)]` 클릭.

### Step 5: 설정 요약 (Summary)

- **내용**: 지금까지 설정된 모든 항목의 최종 상태를 요약하여 보여줍니다.
- **컴포넌트**: 설정 결과 요약 Embed.
- **액션**: `[설정 마치기]` 버튼 (누르면 "설정이 완료되었습니다"로 메시지 변경 후 버튼 비활성화).

## 4. 아키텍처 (Architecture)

- **State Management (상태 관리)**:
  - 마법사는 ephemeral 메시지로 띄워지며, 세션 식별은 `customId` 릴레이 방식을 권장합니다.
  - 예시: `setup_action_next_2` (현재 Step 2, 다음으로 이동) 등 Stateless하게 관리하거나,
  - 사용자/서버별 임시 Map/Redis에 `SetupSession` (진행 단계 등) 보관. (구현 편의상 `customId` payload에 스텝 인덱스를 담는 Stateless 방식 채택)
- **i18n 통합**:
  - 버튼 레이블 및 Embed 내용은 모두 `t()` 함수를 거쳐야 합니다.
  - Step 1에서 언어가 변경되면, 즉시 그 언어 기준의 `t()`를 이용해 현재 뷰(View)를 갱신합니다.

## 5. 예외 처리 (Error Handling)

- 설정 진행 중 타임아웃(Discord 기본 15분 경과) 시: Error Guidance 시스템을 통해 "인터랙션이 만료되었습니다, `/setup`을 다시 실행해주세요" 출력.
- 권한 부족: 생성기 `[자동 생성]` 등 채널 생성 로직에서 권한 부족 에러 발생 시 Error Guidance로 팝업 형태(ephemeral) 오류 출력.