# 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` 업데이트
- 다중 인스턴스 환경에서는 DB advisory lock 또는 `INSTANCE_ID` 기반 단일 실행 제어 고려

> [!NOTE]
> 글로벌 커맨드 등록 등은 애플리케이션 레벨에서 처리하며, 이벤트 리마인더도 유사한 단일 실행 패턴으로 확장할 수 있습니다.

---

## 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) |