# 권한 감사 기능 기획서 (Permission Audit Plan)

## 체인지로그 (Changelog)
- **2026-03-27**: 최초 작성

---

## 1. 개요 (Overview)

| 항목 | 내용 |
|------|------|
| **목표** | 봇이 각 기능을 정상적으로 수행하기 위해 필요한 권한을 진단하고, 부족한 권한이 미치는 영향을 관리자에게 안내 |
| **트리거** | 슬래시 명령어 (`/audit-permissions`) |
| **대상** | 서버(Guild) 관리자 전용 |
| **응답 형태** | Ephemeral Embed |

### 설계 원칙

- **변수 최소화**: 외부 환경(카테고리 오버라이드, 역할 계층 등) 에 의한 예측 불가 실패를 사전에 탐지
- **확장 가능성**: 향후 새 기능이 추가될 때, **권한 항목 정의만 추가**하면 자동으로 진단 대상에 포함되는 플러그인 방식 채택
- **영향도 우선 안내**: 단순히 권한 목록 나열이 아닌, "이 권한 없으면 어떤 기능이 안 된다"는 영향도(Consequence) 중심으로 안내

---

## 2. 권한-기능 매핑 테이블 (Permission Mapping)

> 아래는 현재 구현된 기능 기준이며, 향후 기능 추가 시 이 테이블에 **행을 추가**하여 확장합니다.

| 기능 분류 | 범주 | 필수 권한 | 누락 시 비활성화되는 기능 |
| :--- | :---: | :--- | :--- |
| **공통 (Basic)** | 전역 | `View Channel` | 봇의 모든 채널 접근 불가 |
| | | `Send Messages` | 모든 봇 응답 발송 불가 |
| | | `Embed Links` | Embed 형태의 메시지 전송 불가 |
| **임시 음성 채널** | 전역 | `Manage Channels` | 임시 채널 생성·삭제 불가 |
| | | `Move Members` | 생성기 입장 시 임시 채널로 자동 이동 불가 |
| | | `Manage Roles` | 채널 잠금, 유저 차단 등 권한 오버라이드 불가 |
| | | `Connect` | 음성 채널 접근 불가 |
| **초대 추적** | 전역 | `Manage Guild` | 서버 초대 목록 조회 불가 → 초대자 추적 전체 중단 |
| **역할 자동 부여** | 전역 | `Manage Roles` | 초대코드 기반 역할 자동 부여 불가 |
| | **계층** | `botHighestRole > 대상 역할` | 봇 역할이 대상 역할보다 낮으면 역할 부여 실패 |
| **메시지 흉내 (Mimic)** | 채널 | `Manage Webhooks` | 유저 프로필 복제 메시지 전송 불가 |
| | | `Manage Messages` | 원본 메시지 삭제 불가 (중복 노출) |
| *(향후) 감사 채널* | 전역 | `Send Messages`, `Embed Links` | 지정된 감사 채널에 로그 기록 불가 |
| *(향후) 설정 도우미* | 전역 | `Manage Channels`, `Manage Roles` | 설정 마법사 중 채널·역할 자동 생성 단계 실패 |

---

## 3. 점검 범위 (Audit Scope)

### 3.1. 전역 권한 (Guild-level)
봇의 통합 역할에 부여된 기본 권한을 확인합니다.

### 3.2. 채널 및 카테고리 오버라이드 (Channel Override)
- 음성 채널 생성기(`VoiceGenerator`)가 속한 **카테고리**에서 봇 권한이 `Deny`로 오버라이드되어 있는지 확인
- 전역 권한이 있어도 카테고리 레벨에서 차단되어 있는 경우를 ⚠️ 경고로 표시

### 3.3. 역할 계층 구조 (Role Hierarchy) **[핵심]**
Discord의 역할 관리 제약 사항:
- 봇은 **자신보다 높은 역할**을 멤버에게 부여하거나 제거할 수 없음
- 봇은 **자신보다 높은 역할**을 가진 멤버를 이동하거나 채널에서 추방할 수 없음

**진단 방법:**
1. 봇의 최상위 역할 위치(`botHighestRole.position`) 확인
2. DB에 등록된 역할 자동 부여 대상 역할의 위치(`targetRole.position`) 확인
3. `botHighestRole.position <= targetRole.position` 이면 ❌ 실패로 표시

---

## 4. UI 설계 (Embed 구성)

```
┌─────────────────────────────────────────────────────────┐
│  🔍 Kord 권한 진단 보고서                                │
├─────────────────────────────────────────────────────────┤
│  ✅ 기본 기능 (공통)          - 모든 권한 정상           │
│  ✅ 임시 음성 채널 (전역)     - 모든 권한 정상           │
│  ⚠️ 임시 음성 채널 (카테고리) - Manage Roles 차단됨     │
│     └ 📍 #음성-채널 카테고리: 채널 잠금/차단 기능 불가  │
│  ❌ 초대 추적                 - Manage Server 권한 없음  │
│     └ 💡 초대자 추적 기능 전체 비활성화                  │
│  ❌ 역할 계층 (초대 역할 부여) - 봇 역할 위치 부족       │
│     └ 💡 봇 역할을 'Member' 역할보다 위로 올려주세요.   │
├─────────────────────────────────────────────────────────┤
│  종합: ⚠️ 일부 기능 제한 / 2건 문제 감지                │
└─────────────────────────────────────────────────────────┘
```

| 아이콘 | 의미 |
|--------|------|
| ✅ | 권한 정상 보유 |
| ⚠️ | 전역 권한은 있으나 특정 채널/카테고리에서 오버라이드로 차단됨 |
| ❌ | 전역 권한 자체가 없음 / 역할 계층 문제 |

---

## 5. 구현 설계 방향 (Technical Design)

### 확장 가능한 플러그인 방식

새 기능이 추가될 때 코드 수정 없이 **권한 정의 항목만 추가**하면 되는 구조를 채택합니다.

```typescript
// FeaturePermission 정의 단위 (예시)
interface FeaturePermission {
  featureKey: string;           // i18n 키 및 식별자
  scope: 'guild' | 'channel' | 'hierarchy';
  permissions?: PermissionFlags[];
  // hierarchy 타입인 경우 동적으로 DB에서 대상 역할 조회
}

// 배열에 항목만 추가하면 자동 진단 대상에 포함
const FEATURE_PERMISSION_MAP: FeaturePermission[] = [
  { featureKey: 'BASIC', scope: 'guild', permissions: [...] },
  { featureKey: 'VOICE', scope: 'guild', permissions: [...] },
  { featureKey: 'INVITE_ROLE', scope: 'hierarchy' },
  // ↓ 향후 기능 추가 시 여기에 삽입
];
```

### 상태 판정 기준

| 케이스 | 판정 |
|--------|------|
| 전역 권한 없음 | ❌ FAIL |
| 전역 권한 있으나 채널/카테고리 오버라이드로 차단 | ⚠️ WARNING |
| 역할 계층이 부족하여 작동 불가 | ❌ FAIL |
| 모든 권한 정상 | ✅ SUCCESS |

---

## 6. 구현 단계 (Phased Implementation)

| 단계 | 내용 |
|------|------|
| **Phase 1** | 전역 권한 체크 + Embed UI 구현 |
| **Phase 2** | 카테고리/채널 오버라이드 체크 추가 |
| **Phase 3** | 역할 계층 구조 진단 로직 추가 |

> [!NOTE]
> 이 기획서를 기준으로 `PermissionAuditService`를 재구현합니다. 이전에 작성된 임시 구현 코드는 이 기획서의 내용으로 교체됩니다.