83 lines
5.0 KiB
Markdown
83 lines
5.0 KiB
Markdown
# 봇 설정 도우미 (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로 이동 (사용 안함 선택 시 Step 5로 이동).
|
||
|
||
### Step 4: 감사 로그 카테고리 설정 (Audit Categories)
|
||
|
||
- **내용**: 수신할 감사 로그의 종류(음성, 권한, 시스템 등)를 필터링합니다.
|
||
- **컴포넌트**:
|
||
- 각 카테고리(SYSTEM, VOICE, PERMISSION, INVITE, MIMIC)를 토글할 수 있는 버튼 5개.
|
||
- 활성화 상태는 **초록색(Success)**, 비활성화는 **빨간색(Danger)**으로 표시.
|
||
- **액션**: 버튼 클릭 시 DB의 `disabledCategories` 필드 업데이트 후 현재 뷰 갱신. `[다음 단계]` 버튼으로 이동.
|
||
|
||
### Step 5: 임시 음성 채널 설정 (Voice Generator)
|
||
|
||
- **내용**: 임시 음성 채널 생성 시스템의 진입점이 될 '생성기 채널'을 지정하거나 새로 생성합니다.
|
||
- **컴포넌트**:
|
||
- 기존 생성할 채널을 고르는 `ChannelSelectMenu` (ChannelType.GuildVoice).
|
||
- `[자동 생성]` 버튼: 봇이 새 음성 카테고리와 "➕ 음성 채널 생성" 채널을 자동으로 만들어 줌.
|
||
- `[건너뛰기]` 버튼.
|
||
- **액션**: 설정 시 즉각 시스템 구동. 이후 Step 6(완료 요약)으로 이동.
|
||
|
||
### Step 6: 설정 요약 (Summary)
|
||
|
||
- **내용**: 지금까지 설정된 모든 항목(내용, 감사 채널/카테고리, 음성 채널)의 최종 상태를 요약하여 보여줍니다.
|
||
- **컴포넌트**: 설정 결과 요약 Embed.
|
||
- **액션**: `[설정 마치기]` 버튼 (누르면 "설정이 완료되었습니다"로 메시지 변경 후 버튼 비활성화).
|
||
|
||
## 4. 아키텍처 (Architecture)
|
||
|
||
- **State Management (상태 관리)**:
|
||
- 마법사는 ephemeral 메시지로 띄워지며, 세션 식별은 `customId` 릴레이 방식을 권장합니다.
|
||
- 예시: `setup_action_next_2` (현재 Step 2, 다음으로 이동) 등 Stateless하게 관리하거나,
|
||
- 사용자/서버별 임시 Map 등에 `SetupSession` (진행 단계 등) 보관. (구현 편의상 `customId` payload에 스텝 인덱스를 담는 Stateless 방식 채택)
|
||
- **i18n 통합**:
|
||
- 버튼 레이블 및 Embed 내용은 모두 `t()` 함수를 거쳐야 합니다.
|
||
- Step 1에서 언어가 변경되면, 즉시 그 언어 기준의 `t()`를 이용해 현재 뷰(View)를 갱신합니다.
|
||
|
||
## 5. 예외 처리 (Error Handling)
|
||
|
||
- 설정 진행 중 타임아웃(Discord 기본 15분 경과) 시: Error Guidance 시스템을 통해 "인터랙션이 만료되었습니다, `/setup`을 다시 실행해주세요" 출력.
|
||
- 권한 부족: 생성기 `[자동 생성]` 등 채널 생성 로직에서 권한 부족 에러 발생 시 Error Guidance로 팝업 형태(ephemeral) 오류 출력.
|