Kord/Docs/Plans/Setup_Wizard_Plan.md

봇 설정 도우미 (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) 오류 출력.