Kord/Docs/Plans/Permission_Audit_Plan.md

권한 감사 기능 기획서 (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)

확장 가능한 플러그인 방식

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

// 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를 재구현합니다. 이전에 작성된 임시 구현 코드는 이 기획서의 내용으로 교체됩니다.