diff --git a/Docs/Plans/Event_Schedule_Management_Plan.md b/Docs/Plans/Event_Schedule_Management_Plan.md new file mode 100644 index 0000000..e9da768 --- /dev/null +++ b/Docs/Plans/Event_Schedule_Management_Plan.md @@ -0,0 +1,315 @@ +# Kord - 서버 이벤트 일정 관리 기능 기획안 (Event Schedule Management) + +## 체인지로그 (Changelog) +- **2026-03-30**: 최초 기획안 작성 + +--- + +## 1. 개요 + +서버 이벤트 일정 관리 기능은 관리자 또는 운영진이 디스코드 서버 내 이벤트를 등록하고, +참여자에게 일정 정보를 공지하며, 시작 전 자동 리마인더를 보낼 수 있도록 돕는 기능입니다. + +현재 Kord가 제공하는 운영 보조 기능과 자연스럽게 연결되며, +특히 감사 로그, i18n, 설정 마법사와의 연동 가치가 높습니다. + +### 목표 + +- 서버 공용 이벤트 일정을 등록, 수정, 취소할 수 있어야 함 +- 예정된 이벤트 목록을 슬래시 커맨드로 빠르게 조회할 수 있어야 함 +- 이벤트 시작 전 지정 채널에 자동 리마인더를 보낼 수 있어야 함 +- 이벤트 생성/수정/취소 내역을 감사 로그 채널에 기록할 수 있어야 함 +- 향후 RSVP, 반복 일정, Discord Scheduled Event 연동으로 확장 가능해야 함 + +### 초기 범위 (MVP) + +- 서버 단위 공용 이벤트만 지원 +- 단발성 이벤트만 지원 +- 이벤트 생성 / 목록 조회 / 삭제 / 공지 / 리마인더 제공 +- 시간대는 우선 서버 기본 시간대 기준으로 처리 + +--- + +## 2. 주요 사용자 시나리오 + +### 시나리오 A: 운영진이 서버 이벤트를 등록 + +1. 관리자가 `/event create` 명령을 실행 +2. 제목, 시작 일시, 설명, 공지 채널, 리마인더 여부를 입력 +3. Kord가 DB에 이벤트를 저장 +4. 필요 시 지정 채널에 이벤트 공지 Embed를 게시 +5. 감사 로그 채널에 "이벤트 생성" 로그 기록 + +### 시나리오 B: 일반 사용자가 예정된 이벤트를 확인 + +1. 사용자가 `/event list` 명령을 실행 +2. Kord가 아직 시작하지 않은 이벤트를 시작 시각 순으로 정렬해 표시 +3. 사용자는 제목, 시간, 설명, 공지 채널 정보를 확인 + +### 시나리오 C: 이벤트 시작 전 자동 알림 + +1. 백그라운드 스케줄러가 예정된 이벤트를 주기적으로 확인 +2. 이벤트 시작 1시간 전 또는 10분 전에 리마인더 조건이 충족되면 +3. 지정 채널에 리마인더 Embed를 전송 +4. 중복 전송 방지를 위해 리마인더 전송 상태를 저장 + +--- + +## 3. 명령 구조 제안 + +### 3.1 `/event create` + +이벤트를 새로 등록합니다. + +입력 예시: + +- `title`: 이벤트 제목 +- `starts_at`: 시작 시각 +- `description`: 이벤트 설명 +- `channel`: 공지 채널 +- `reminder`: 리마인더 사용 여부 + +응답: + +- 성공 시 Ephemeral Embed로 생성 결과 표시 +- 필요 시 공지 채널에 이벤트 공지 Embed 전송 + +### 3.2 `/event list` + +예정된 이벤트 목록을 조회합니다. + +출력: + +- 가까운 순으로 정렬된 이벤트 목록 +- 제목 / 시작 시각 / 남은 시간 / 공지 채널 / 리마인더 여부 표시 + +### 3.3 `/event cancel` + +등록된 이벤트를 취소합니다. + +동작: + +- 이벤트 상태를 `CANCELLED`로 변경하거나 삭제 +- 이미 공지된 이벤트라면 취소 안내 메시지 전송 옵션 제공 가능 + +### 3.4 `/event announce` + +등록된 이벤트를 지정 채널에 다시 공지합니다. + +활용: + +- 공지 메시지를 다시 올리고 싶을 때 +- 최초 생성 시 자동 공지를 끈 경우 수동으로 게시할 때 + +### 3.5 `/event detail` + +특정 이벤트의 상세 정보를 조회합니다. + +출력: + +- 제목 +- 설명 +- 시작 시각 +- 생성자 +- 공지 채널 +- 리마인더 상태 + +--- + +## 4. 데이터 모델 제안 + +### `GuildEvent` + +```prisma +model GuildEvent { + id String @id @default(uuid()) + guildId String + title String + description String? + startsAt DateTime + timezone String @default("Asia/Seoul") + status EventStatus @default(SCHEDULED) + announcementChannelId String? + createdByUserId String + reminderEnabled Boolean @default(true) + remindedOneHour Boolean @default(false) + remindedTenMinutes Boolean @default(false) + announcedAt DateTime? + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + @@index([guildId, startsAt]) + @@index([guildId, status]) +} + +enum EventStatus { + SCHEDULED + CANCELLED + COMPLETED +} +``` + +### 설계 메모 + +- `status`를 두어 삭제 대신 취소/완료 상태 전환 가능 +- 리마인더 중복 전송 방지를 위해 플래그 저장 +- 시간대는 초기에는 서버 기본값 하나를 두고, 이후 서버별 설정으로 확장 + +--- + +## 5. 리마인더 처리 방식 + +### 기본 방향 + +- 별도 외부 스케줄러 없이 봇 프로세스 내부 주기 작업으로 시작 +- 예: 1분 간격으로 `SCHEDULED` 이벤트 조회 +- 현재 시각과 비교해 리마인더 조건 충족 시 공지 채널에 메시지 전송 + +### 리마인더 규칙 (초기안) + +- 시작 1시간 전 +- 시작 10분 전 + +### 중복 방지 + +- 전송 직후 `remindedOneHour`, `remindedTenMinutes` 업데이트 +- 다중 인스턴스 환경에서는 Redis lock 또는 `INSTANCE_ID` 기반 단일 실행 제어 고려 + +> [!NOTE] +> 현재 프로젝트는 글로벌 커맨드 동기화 시 Redis lock을 사용하므로, +> 이벤트 리마인더도 같은 방식으로 확장하기 좋습니다. + +--- + +## 6. UI 설계 + +### 이벤트 공지 Embed + +포함 정보: + +- 이벤트 제목 +- 시작 시각 +- 남은 시간 +- 설명 +- 공지 채널 +- 주최자 또는 생성자 + +예시 필드: + +- `시작 시각` +- `남은 시간` +- `안내 채널` +- `설명` + +### 리마인더 Embed + +용도: + +- 이벤트 시작이 가까워졌음을 강조 + +예시 문구: + +- "이 이벤트가 1시간 뒤 시작됩니다." +- "이 이벤트가 10분 뒤 시작됩니다." + +### 목록 조회 Embed + +출력 형태: + +- 이벤트 5개 또는 10개 단위 요약 +- 오래된 완료 이벤트는 제외 +- 이벤트가 없을 경우 친절한 Empty State 메시지 제공 + +--- + +## 7. 권한 및 운영 정책 + +### 실행 권한 + +- `/event create`, `/event cancel`, `/event announce` + - 관리자 또는 `Manage Guild` 권한 사용자만 허용 권장 +- `/event list`, `/event detail` + - 일반 사용자도 허용 가능 + +### 감사 로그 연동 + +아래 이벤트를 감사 로그 채널에 남깁니다. + +- 이벤트 생성 +- 이벤트 수정 +- 이벤트 취소 +- 리마인더 전송 실패 + +추천 카테고리: + +- 신규 카테고리 `EVENT` + 또는 +- 초기에는 `SYSTEM` 카테고리에 포함 + +--- + +## 8. i18n 고려사항 + +- 날짜/시간 포맷은 locale에 맞춰 표시 필요 +- 공지/리마인더/오류 문구는 모두 `t()` 기반으로 관리 +- 명령 설명에도 `setDescriptionLocalizations()` 적용 + +초기 지원 언어: + +- `en` +- `ko` + +--- + +## 9. 구현 단계 (Phased Implementation) + +| 단계 | 내용 | +|------|------| +| **Phase 1** | Prisma `GuildEvent` 모델 추가 및 마이그레이션 | +| **Phase 1** | `/event create`, `/event list`, `/event cancel` 기본 명령 구현 | +| **Phase 2** | 이벤트 공지 Embed 및 `/event announce` 구현 | +| **Phase 2** | 내부 주기 작업 기반 리마인더 전송 구현 | +| **Phase 3** | 감사 로그 연동 및 에러 처리 고도화 | +| **Phase 3** | i18n 문구 정리 및 테스트 추가 | +| **Phase 4** | RSVP 버튼, 반복 일정, 서버 기본 시간대 설정 확장 | + +--- + +## 10. 검증 계획 + +### 자동 테스트 + +- 이벤트 생성/조회/취소 서비스 로직 테스트 +- 리마인더 조건 계산 테스트 +- 이벤트 상태 전환 테스트 +- i18n 문구 조회 테스트 + +### 수동 테스트 + +1. `/event create`로 10분 뒤 이벤트 생성 +2. `/event list`에서 조회되는지 확인 +3. 지정 채널에 공지 Embed가 정상 게시되는지 확인 +4. 리마인더 시각 도달 시 중복 없이 전송되는지 확인 +5. `/event cancel` 후 더 이상 리마인더가 가지 않는지 확인 + +--- + +## 11. 후속 확장 아이디어 + +- RSVP 버튼 (`참석`, `불참`, `미정`) +- Discord Scheduled Event API 연동 +- 반복 일정 (`매주`, `매월`) +- 이벤트 참가자 역할 자동 부여 +- 이벤트 전용 임시 음성채널 자동 생성 +- 서버 기본 시간대 설정 (`/config timezone`) + +--- + +## 12. 관련 문서 + +| 문서 | 링크 | +|------|------| +| 기능 로드맵 | [`Feature_Roadmap.md`](./Feature_Roadmap.md) | +| 감사 채널 기획안 | [`Audit_Channel_Plan.md`](./Audit_Channel_Plan.md) | +| i18n 기획안 | [`i18n_Plan.md`](./i18n_Plan.md) | +| 설정 마법사 기획안 | [`Setup_Wizard_Plan.md`](./Setup_Wizard_Plan.md) | diff --git a/Docs/index.md b/Docs/index.md index cd7d4fd..baa8278 100644 --- a/Docs/index.md +++ b/Docs/index.md @@ -22,6 +22,7 @@ - [봇 상태 메시지 기획 (Bot Presence Plan)](Plans/Bot_Presence_Plan.md) - [에러 안내 기능 기획서 (Error Guidance Plan)](Plans/Error_Guidance_Plan.md) - [다국어 지원 기획서 (i18n Plan)](Plans/i18n_Plan.md) +- [서버 이벤트 일정 관리 기능 기획안 (Event Schedule Management Plan)](Plans/Event_Schedule_Management_Plan.md) ## 아키텍처 및 정책 결정 (Decisions)