1. 레벨 관리 개요

DXCMS 관리자 패널의 [레벨 관리] 메뉴는 회원이 경험치를 쌓아 올라가는 레벨 시스템의 구조 자체를 커스터마이징하는 도구입니다. 각 레벨의 필요 경험치•이름•아이콘(이모지)•색상을 직접 설정할 수 있으며, 기본값은 총 150레벨로 구성됩니다.

📌  접근 경로: 관리자 대시보드 → 레벨 관리 (또는 URL: /admin/levels)

1.1 레벨 시스템의 동작 원리

레벨은 DxPoint 클래스가 경험치(EXP) 변동 시마다 dx_level_config 테이블을 참조하여 자동으로 계산합니다. 레벨 관리 화면에서 설정한 값이 즉시 사이트 전체 레벨 시스템에 반영됩니다.
 

구분	내용
레벨 설정 저장소	dx_level_config 테이블. level/name/exp_required/icon/color/updated_at 컬럼.
테이블 자동 생성	레벨 관리 페이지 접근 시 CREATE TABLE IF NOT EXISTS로 자동 생성됩니다. 별도 마이그레이션 불필요.
초기 기본 데이터	테이블이 비어있으면 150레벨 기본 데이터(새싹~초월왕)를 자동으로 INSERT합니다.
DB 우선 적용	dx_level_config 테이블에 데이터가 있으면 DxPoint 클래스의 하드코딩 기본값을 무시하고 DB 값을 사용합니다.
레벨 캐시	레벨 설정은 요청 단위로 PHP 정적 변수에 캐시됩니다. 저장 시 DxPoint::clearLevelCache()가 자동 호출됩니다.
최대 레벨 제한	레벨 번호는 1~999까지 지원합니다. 새 레벨 추가 폼의 최대값은 9,999이나, 기존 기본값은 150레벨이 상한입니다.

1.2 화면 구성

영역	설명
페이지 헤더	현재 등록된 레벨 수와 최고 레벨 번호 표시. [기본값 초기화] 버튼.
새 레벨 추가 폼	레벨 번호·이름·필요 경험치·아이콘·색상을 입력하여 새 레벨을 추가합니다.
레벨 목록 패널	등록된 모든 레벨을 level ASC 순으로 표시. 셀을 클릭하여 인라인 편집 가능.
검색/필터 바	레벨 번호 또는 이름으로 필터링. "커스텀 이름만" 체크박스.
토스트 알림	저장 또는 삭제 후 화면 우측 하단에 보라색 토스트 메시지가 2.2초간 표시됩니다.

2. 기본 150레벨 구성

처음 레벨 관리에 접근하거나 기본값 초기화를 실행하면 아래의 150레벨 데이터가 자동으로 삽입됩니다. 레벨은 10개 세계관 구간으로 나뉩니다.

2.1 세계관 구간별 레벨 구성

구간	레벨 범위	테마	최고 필요 경험치	레벨명 예시
1구간	Lv.1~10	기초~마스터	8,000	새싹/초보/일반/활동/열정/고수/달인/전문가/명인/마스터
2구간	Lv.11~20	그랜드~창조자	210,000	그랜드/전설/영웅/신화/전설왕/불사자/신계/초월자/각성자/지존
3구간	Lv.21~30	챔피언~신	1,220,000	챔피언/정복자/패왕/천하무적/무림고수/절대자/초인/신인/반신/신
4구간	Lv.31~40	신성각성	4,010,000	태양신/달의신/별의신/바람의신/대지의신/불의신/물의신/번개의신/어둠의신/빛의신
5구간	Lv.41~60	신성·정령	22,400,000	시간의주인/공간의주인/차원의주인/…/정령왕/바람정령왕/…/자연의화신
6구간	Lv.61~80	천계·용신	65,000,000	천계입문자/천계수행자/…/천룡왕/하늘의신왕/용신각성/…/대용신/용신의신
7구간	Lv.81~100	황제	127,700,000	화염용신/빙하용신/…/절대황제(Lv.99)/고대신입문(Lv.101~)
8구간	Lv.101~120	고대신·심연	222,200,000	고대신입문/태초의관찰자/…/고대신황/심연입문자/…/심연신황
9구간	Lv.121~140	코스모스·차원	336,800,000	코스모스각성/별의지배자/…/코스모스신황/차원개척자/…/다차원신황
10구간	Lv.141~150	절대·초월	1,097,640,000	절대각성/절대수행자/…/절대신황/초월의문턱/초월왕(Lv.150)

💡  Lv.100(절대황제)과 Lv.101(고대신입문) 사이에는 기본 데이터에 Lv.100이 없습니다. 필요하면 새 레벨 추가로 Lv.100을 직접 추가하세요.

2.2 주요 레벨 경험치 기준점

레벨	레벨명	필요 경험치	레벨	레벨명	필요 경험치
Lv.1	새싹	0	Lv.50	창조자	10,100,000
Lv.10	마스터	8,000	Lv.100	절대황제	127,700,000
Lv.20	지존	210,000	Lv.120	심연신황	222,200,000
Lv.30	신	1,220,000	Lv.140	다차원신황	336,800,000
Lv.40	빛의신	4,010,000	Lv.150	초월왕	1,097,640,000

3. 새 레벨 추가

화면 상단의 [새 레벨 추가] 폼에서 기존에 없는 새 레벨을 등록합니다.

3.1 추가 폼 필드

필드	필수 여부	설명 및 유의사항
레벨 번호 (level)	필수	1~9999 사이의 정수. 이미 존재하는 레벨 번호는 추가 불가 (오류 메시지). 이미 존재하는 레벨은 목록에서 인라인 편집 사용.
레벨 이름 (name)	필수	최대 50자. 프론트엔드 레벨 배지에 표시되는 이름. 예: 신왕, 무적의전사, 빛의수호자.
필요 경험치 (exp_required)	필수	이 레벨에 도달하기 위한 누적 경험치. 0 이상의 정수. 상위 레벨일수록 높은 값을 설정하세요.
아이콘 (icon)	선택	최대 10자. 이모지 권장. 예: 🌟, 👑, 🔥, 💎. 프론트엔드 레벨 표시 시 이름 앞에 붙어 표시됩니다. 빈 값이면 아이콘 미표시.
색상 (color)	선택	HEX 색상 피커. 기본값 #7c3aed(보라). 레벨 목록의 아이콘 색상 및 프론트엔드 레벨 배지 색상에 적용됩니다.

3.2 추가 처리 로직

1. CSRF 토큰 검증
2. 레벨 번호가 1 미만이면 "레벨 번호는 1 이상이어야 합니다." 오류
3. 해당 레벨 번호가 이미 존재하면 "레벨 N은 이미 존재합니다. 목록에서 직접 편집하세요." 오류
4. 레벨 이름이 빈 값이면 "레벨 이름을 입력하세요." 오류
5. dx_level_config 테이블에 INSERT
6. DxPoint::clearLevelCache() 호출 — 레벨 캐시 초기화
7. "레벨 N (이름) 이(가) 추가되었습니다." 성공 메시지 표시

3.3 추가 절차

1. [새 레벨 추가] 패널에서 레벨 번호 입력 (기존 없는 번호)
2. 레벨 이름 입력 (예: 신왕)
3. 필요 경험치 입력 (예: 1200000000)
4. 이모지 아이콘 입력 (선택, 예: 🌟👑)
5. 색상 피커로 색상 선택
6. [레벨 추가] 보라색 버튼 클릭
7. 성공 메시지 확인 후 하단 목록에서 추가된 레벨 확인

4. 인라인 편집 — 레벨 목록에서 직접 수정

레벨 목록에서 각 레벨의 이름•경험치•아이콘•색상을 페이지 이동 없이 즉시 편집할 수 있습니다. "셀을 클릭하면 바로 편집됩니다" 안내 텍스트가 목록 헤더에 표시됩니다.

4.1 인라인 편집 방법

동작	방법 및 설명
이름 편집	목록의 이름 셀(텍스트 입력창)을 클릭하여 직접 편집. 셀에 포커스 시 보라색 테두리로 강조.
필요 경험치 편집	숫자 입력창에 클릭하여 직접 수정. 우측 정렬 모노스페이스 폰트.
아이콘 편집	아이콘 셀에 이모지를 직접 입력. 변경 후 저장 시 레벨 번호 셀의 아이콘 미리보기가 즉시 갱신됩니다.
색상 변경	컬러 피커를 클릭하여 색상 선택. 저장 시 아이콘 미리보기 색상도 즉시 반영됩니다.
[저장] 버튼 클릭	각 행의 보라색 [저장] 버튼 클릭 시 AJAX(fetch API)로 save_one 요청. 화면 이동 없이 저장. 저장 중 버튼이 비활성(...)으로 변경됩니다.
Enter 키 저장	입력 필드에서 Enter 키를 누르면 해당 행의 [저장] 버튼이 자동 클릭됩니다. 빠른 편집에 편리합니다.

4.2 저장(save_one) 처리 흐름

1. CSRF 토큰 검증 (FormData로 전송)
2. 레벨 번호가 1~999 범위 내인지 확인
3. 해당 레벨이 테이블에 존재하면 UPDATE, 없으면 INSERT (upsert 방식)
4. DxPoint::clearLevelCache() 호출
5. {"ok": true} JSON 응답 반환
6. 클라이언트에서 "Lv.N 저장됨 ✓" 토스트 알림 표시 + 아이콘/색상 미리보기 즉시 갱신

💡  인라인 저장은 AJAX 방식으로 처리되므로 페이지 새로고침 없이 즉시 반영됩니다. 실시간으로 사이트의 레벨 이름이 변경됩니다.

5. 레벨 삭제

각 레벨 행의 [삭제] 버튼을 클릭하면 확인 창이 표시되고, 확인 후 AJAX로 해당 레벨이 삭제됩니다.

5.1 삭제 규칙

규칙	내용
Lv.1 삭제 불가	레벨 1은 삭제할 수 없습니다. [삭제] 버튼 대신 "—" 텍스트가 표시됩니다. 서버에서도 level <= 1이면 {"ok":false,"msg":"레벨 1은 삭제할 수 없습니다."} 반환.
Lv.2 이상 삭제 가능	레벨 2 이상은 모두 삭제 가능. 삭제 전 "레벨 N을(를) 삭제하시겠습니까?" 확인 창이 표시됩니다.
삭제 처리	DELETE FROM dx_level_config WHERE level=N 실행. DxPoint::clearLevelCache() 호출. 삭제된 행은 테이블에서 즉시 제거됩니다.
회원 레벨 영향	삭제된 레벨에 있는 회원은 즉시 아래 레벨로 재계산되지 않습니다. 다음 경험치 변동 시 calcLevel()이 실행될 때 자동으로 재계산됩니다.

🚨  중간 레벨을 삭제하면 해당 레벨에 있는 회원들의 레벨 표시가 일시적으로 부정확해질 수 있습니다. 삭제 전 해당 레벨 구간의 회원이 없는지 포인트 관리에서 확인하세요.

6. 기본값 초기화

페이지 헤더 오른쪽의 [기본값 초기화] 버튼을 클릭하면 현재 모든 레벨 설정을 삭제하고 150레벨 기본 데이터로 되돌립니다.

6.1 초기화 처리 흐름

1. "150레벨 기본값으로 초기화하시겠습니까? 현재 설정이 모두 삭제됩니다." 확인 창
2. 확인 클릭 시 POST 요청(sub=reset) 전송
3. CSRF 토큰 검증
4. DELETE FROM dx_level_config (전체 삭제)
5. _levels_insert_defaults()로 150레벨 기본 데이터 INSERT IGNORE
6. DxPoint::clearLevelCache() 호출
7. "150레벨 기본값으로 초기화되었습니다." 성공 메시지 표시

🚨  초기화하면 커스텀으로 수정한 모든 레벨 설정이 삭제됩니다. 복구가 불가능하므로 중요한 설정은 미리 백업(DB Export)하세요.

7. 검색 및 필터

레벨 목록 패널 상단의 검색/필터 바에서 원하는 레벨을 빠르게 찾을 수 있습니다. 검색은 JavaScript로 클라이언트 측에서 즉시 처리됩니다.

7.1 검색/필터 기능

기능	동작 상세
레벨 번호 검색	검색어가 data-level 속성(레벨 번호 문자열)에 포함되어 있으면 표시. 예: "15" 검색 시 Lv.15, Lv.115, Lv.150 모두 표시.
이름 검색	검색어가 data-name 속성(레벨 이름, 소문자 변환)에 포함되어 있으면 표시. 예: "신" 검색 시 "신인", "용신황제" 등 표시.
AND 조건	검색어 필터와 커스텀 필터가 모두 충족해야 표시됩니다.
커스텀 이름만 체크박스	"LV."으로 시작하지 않는 이름을 가진 레벨만 표시합니다. 기본값 레벨명은 대부분 한글이므로 체크 시 커스텀으로 변경한 레벨만 보입니다.
실시간 처리	input 이벤트마다 즉시 필터링. 검색어 입력 즉시 해당하지 않는 행이 style.display=none으로 숨겨집니다.

💡  "커스텀 이름만" 필터는 직접 이름을 변경한 레벨을 빠르게 확인할 때 유용합니다. 단, 기본 데이터 이름(새싹, 초보 등)도 한글이므로 이 필터는 "LV."으로 시작하는 이름을 가진 경우(자동 생성된 이름)를 제외하는 방식입니다.

8. 레벨 설정 전략

사이트 성격에 맞는 레벨 시스템을 설계하는 전략을 안내합니다.

8.1 경험치 곡선 유형

곡선 유형	경험치 증가 방식	특징 및 적합 사이트
선형 증가	각 레벨마다 일정량 증가	예측 가능하고 공정. 경쟁보다 꾸준한 참여를 유도하는 커뮤니티에 적합.
지수 증가 (기본값)	레벨이 높아질수록 급격히 증가	초반은 빠른 레벨업, 후반은 도전감. DXCMS 기본 150레벨이 이 방식. 게임성이 필요한 커뮤니티에 적합.
단계적 증가	구간별로 다른 증가율 적용	특정 구간마다 의미 있는 이정표를 부여. 고급 커뮤니티·등급제 사이트에 적합.

8.2 소규모 사이트용 간단 레벨 구성 예시 (10레벨)

DXCMS 기본 150레벨 대신 10레벨 간단 구성으로 교체하려면:

1. 기본값 초기화를 실행하여 150레벨로 초기화
2. Lv.11~Lv.150을 모두 삭제
3. Lv.1~Lv.10의 이름•경험치를 아래 예시처럼 인라인 편집

레벨	레벨명	필요 경험치	아이콘	색상 예시
Lv.1	새내기	0	🌱	#4ade80
Lv.2	초보자	100	🌿	#22c55e
Lv.3	일반회원	500	⭐	#0ea5e9
Lv.5	활동회원	3,000	🌟	#f59e0b
Lv.10	명예회원	50,000	👑	#7c3aed

💡  대량 삭제가 번거로우면 DB에서 직접 DELETE FROM dx_level_config WHERE level > 10; 을 실행한 후 남은 1~10레벨을 인라인 편집하는 방법이 더 빠릅니다.

8.3 레벨별 색상 활용 가이드

레벨 색상은 프론트엔드에서 레벨 배지•아이콘 등에 사용됩니다. 사용자가 시각적으로 레벨 등급을 인식할 수 있도록 색상 계층을 설계하세요.
 

레벨 구간	권장 색상 계열	이유
초반 (Lv.1~10)	초록·하늘 계열	자연스럽고 친근한 색상. 새 회원에게 부드러운 첫인상.
중반 (Lv.11~50)	파랑·보라 계열	신뢰감과 활동성을 표현. 점진적으로 색이 깊어지도록.
고급 (Lv.51~100)	황금·주황 계열	희소성과 성취감 강조. 눈에 띄는 고급스러운 색상.
최상위 (Lv.101~)	빨강·진한 보라 계열	강렬하고 희귀한 인상. 최고 등급임을 강조.

9. 전체 사용 절차

9.1 특정 레벨 이름•색상 변경

1. 관리자 대시보드 → [레벨 관리] 메뉴 클릭
2. 검색 바에서 변경할 레벨 번호 또는 이름 검색
3. 해당 레벨 행의 이름 셀 클릭하여 새 이름 입력
4. 색상 피커로 색상 변경
5. 아이콘 셀에 이모지 수정 (선택)
6. [저장] 버튼 클릭 또는 Enter 키
7. "Lv.N 저장됨 ✓" 토스트 알림 확인

9.2 새 레벨 추가 (기존 최고 레벨 이후)

1. [새 레벨 추가] 폼에서 현재 최고 레벨보다 큰 번호 입력 (예: 기존 최고 Lv.150이면 151 입력)
2. 레벨 이름, 필요 경험치, 아이콘, 색상 입력
3. [레벨 추가] 버튼 클릭
4. 성공 메시지 확인 후 목록 맨 하단에 추가된 레벨 확인

9.3 전체 레벨 시스템 교체

1. 중요 데이터 백업: DB에서 dx_level_config 테이블 Export
2. [기본값 초기화] 버튼으로 150레벨 기본 데이터로 초기화
3. 불필요한 레벨 번호를 목록에서 [삭제] 처리
4. 남은 레벨들을 인라인 편집으로 이름•경험치•아이콘•색상 변경
5. 새 레벨이 필요하면 [새 레벨 추가] 폼으로 추가
6. 포인트 관리에서 회원 레벨이 올바르게 표시되는지 확인

10. 자주 묻는 질문 (FAQ)

Q1. 레벨 이름을 변경했는데 프론트엔드에 반영이 안 됩니다.

A. 저장 시 DxPoint::clearLevelCache()가 호출되어 요청 단위 PHP 캐시는 즉시 초기화됩니다. 시스템 전체 캐시(DxCache)가 활성화된 경우 다음 캐시 만료 시점까지 지연될 수 있습니다. DxCache가 있다면 캐시 관리 화면에서 전체 캐시를 초기화하거나 잠시 기다리세요.

Q2. 레벨 번호 순서가 연속하지 않아도 됩니까?

A. 네, 가능합니다. 예를 들어 Lv.1, Lv.5, Lv.10만 있어도 정상 동작합니다. calcLevel()은 현재 경험치가 threshold 이상인 가장 높은 레벨을 반환하므로, 중간 레벨이 없어도 올바르게 계산됩니다.

Q3. 기존 150레벨에서 특정 레벨만 삭제할 수 있나요?

A. 네. 목록에서 해당 레벨의 [삭제] 버튼을 클릭하면 됩니다. 단 Lv.1은 삭제 불가합니다. 중간 레벨 삭제 시 해당 레벨에 있는 회원의 레벨 표시가 다음 경험치 변동 시까지 일시적으로 변경될 수 있습니다.

Q4. 레벨 이름에 영어나 숫자를 사용할 수 있나요?

A. 네. 최대 50자 내에서 한글•영문•숫자•특수문자 모두 사용 가능합니다. DxSanitizer::text()로 처리되어 XSS 방지가 적용됩니다.

Q5. 경험치 필요량을 0으로 설정해도 됩니까?

A. Lv.1의 경험치는 0으로 설정해야 합니다(기본값). 다른 레벨을 0으로 설정하면 해당 레벨에 도달하기 위한 경험치가 없어, 모든 회원이 그 레벨 이상이 됩니다. 의도적인 경우가 아니라면 각 레벨의 경험치는 이전 레벨보다 크게 설정하세요.

Q6. 150레벨 외에 추가 레벨(Lv.151 이상)을 만들 수 있나요?

A. 네. [새 레벨 추가] 폼에서 151 이상의 번호를 입력하면 됩니다. 레벨 번호는 최대 999까지 지원합니다. 단, 필요 경험치가 매우 높아야 의미가 있으며, 현재 회원들이 도달할 수 있는 현실적인 수준인지 검토하세요.

Q7. 레벨 설정을 CSV나 Excel로 가져올 수 있나요?

A. 현재 관리자 UI에서는 CSV/Excel 임포트 기능을 제공하지 않습니다. 대량 레벨 설정 변경이 필요하면 DB에 직접 REPLACE INTO dx_level_config 구문을 실행하는 방법을 사용하세요.

11. 용어 정리

용어	설명
dx_level_config	레벨 설정을 저장하는 DB 테이블. level/name/exp_required/icon/color/updated_at 컬럼.
level	레벨 번호(SMALLINT UNSIGNED). 1부터 시작. 최대 999. Primary Key.
name	레벨 표시 이름(VARCHAR 50). 최대 50자. 예: 새싹, 마스터, 초월왕.
exp_required	해당 레벨 달성에 필요한 누적 경험치(INT UNSIGNED). Lv.1은 0.
icon	레벨 아이콘 이모지(VARCHAR 10). 예: 🌱, 👑, 🌟. 비어있으면 미표시.
color	레벨 색상 HEX 코드(VARCHAR 20). 예: #7c3aed. 비어있으면 #64748b(회색) 사용.
updated_at	레벨 설정 마지막 수정 시각. ON UPDATE CURRENT_TIMESTAMP 자동 갱신.
CREATE TABLE IF NOT EXISTS	레벨 관리 접근 시 테이블이 없으면 자동 생성하는 SQL 구문. 마이그레이션 없이도 동작.
INSERT IGNORE	기본값 삽입 시 이미 존재하는 레벨 번호는 건너뛰는 SQL 옵션.
save_one	인라인 편집 저장 AJAX 액션. UPSERT(UPDATE/INSERT) 방식으로 처리.
reset	기본값 초기화 액션. 전체 삭제 후 150레벨 기본 데이터 재삽입.
delete	레벨 삭제 AJAX 액션. Lv.1은 삭제 불가.
DxPoint::clearLevelCache()	레벨 관련 PHP 정적 캐시 초기화. 저장/삭제/초기화 시마다 자동 호출.
DxPoint::calcLevel($exp)	경험치로 현재 레벨 계산. getThresholds() 배열을 순회하며 최고 달성 레벨 반환.
lvSearch	레벨 번호·이름 검색 input 요소 ID. input 이벤트마다 실시간 필터링.
lvShowCustomOnly	커스텀 이름만 필터 체크박스 ID. LV.으로 시작하지 않는 이름만 표시.
토스트 알림	저장/삭제 완료 후 화면 우측 하단에 2.2초간 표시되는 보라색 팝업 메시지.
btn-save-row	각 레벨 행의 [저장] 버튼 CSS 클래스. 이벤트 위임으로 클릭 감지.
btn-del-row	각 레벨 행의 [삭제] 버튼 CSS 클래스. Lv.1에는 미표시.
Enter 키 저장	levelTbody의 keydown 이벤트로 Enter 키 감지 → 해당 행 저장 버튼 자동 클릭.