316 lines
8.4 KiB
Markdown
316 lines
8.4 KiB
Markdown
# 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) |
|