5.0 KiB

Raw Blame History

봇 설정 도우미 (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/Redis에 SetupSession (진행 단계 등) 보관. (구현 편의상 customId payload에 스텝 인덱스를 담는 Stateless 방식 채택)
i18n 통합:
- 버튼 레이블 및 Embed 내용은 모두 t() 함수를 거쳐야 합니다.
- Step 1에서 언어가 변경되면, 즉시 그 언어 기준의 t()를 이용해 현재 뷰(View)를 갱신합니다.

5. 예외 처리 (Error Handling)

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