1. 포인트 관리 개요

DXCMS 관리자 패널의 [포인트 관리] 메뉴는 회원의 포인트(P)와 경험치를 직접 지급하거나 차감하고, 포인트 보유 랭킹을 확인하며, 실시간 포인트 변동 로그를 모니터링하는 도구입니다. DxPoint 엔진 클래스가 포인트•경험치•레벨 시스템 전체를 담당합니다.

📌  접근 경로: 관리자 대시보드 → 포인트 관리 (또는 URL: /admin/points)

1.1 포인트 시스템 구조

DXCMS 포인트 시스템은 포인트(Point)와 경험치(EXP)가 독립적으로 운영됩니다. 포인트는 사용•차감이 가능한 재화이고, 경험치는 누적되어 레벨을 결정하는 지표입니다.
 

구분	포인트 (Point)	경험치 (EXP)
역할	사용·차감 가능한 재화. 쇼핑·구매에 활용.	레벨 달성의 누적 지표. 사용 개념 없음.
DB 컬럼	members.point	members.exp
로그 테이블	dx_point_log	dx_exp_log
차감 가능	가능 (음수 지급)	가능 (음수 지급, 최솟값 0)
레벨 영향	없음	경험치 누적으로 자동 레벨 계산

1.2 화면 구성

영역	설명
포인트/경험치 직접 지급 폼	회원 ID 입력 후 포인트·경험치 금액과 메모를 입력하여 즉시 지급 또는 차감. 음수 입력 시 차감.
포인트 보유 랭킹	활성 회원을 포인트 내림차순으로 20명씩 표시. 이름·ID 검색, 레벨·포인트·경험치·가입일 표시.
실시간 변동 로그	최근 30건의 포인트 변동 이력. 일시·회원·유형·변동량·잔액·메모 표시.

2. 포인트 및 경험치 자동 지급 규칙

DxPoint 엔진은 회원의 활동(로그인•글쓰기•댓글•좋아요 받음•가입 등)에 따라 포인트와 경험치를 자동으로 지급합니다. 아래는 기본 지급 규칙이며, 코드 수정 또는 플러그인을 통해 변경할 수 있습니다.

2.1 활동별 자동 지급량

활동 유형 (type)	포인트	경험치	발생 시점
signup	+10P	+20 EXP	회원 가입 완료 시
login	+1P	+2 EXP	로그인 성공 시 (1일 1회)
write	+5P	+10 EXP	게시글 작성 완료 시
comment	+2P	+5 EXP	댓글 작성 완료 시
like_recv	+1P	+2 EXP	작성한 게시글이 좋아요를 받았을 때
scrap_recv	+1P	-	작성한 게시글이 스크랩을 받았을 때
admin	직접 입력	직접 입력	관리자가 포인트 관리 화면에서 수동 지급/차감

💡  자동 지급 규칙(pointRules, expRules)은 core/DxPoint.php의 정적 배열로 정의됩니다. 플러그인이나 커스텀 코드에서 DxPoint::add()를 직접 호출하여 추가 규칙을 구현할 수 있습니다.

2.2 추가 유형 설명

자동 지급 규칙 외에도 시스템 내부에서 사용되는 포인트 유형이 있습니다.
 

유형값	설명
purchase	포인트 사용. 포인트로 상품·서비스를 구매했을 때 차감. 음수로 기록됩니다.
refund	포인트 환불. 구매 취소·환불 시 포인트를 다시 지급. 양수로 기록됩니다.
delete	글 삭제 차감. 게시글 삭제 시 지급했던 포인트를 회수. 음수로 기록됩니다.

3. 포인트•경험치 직접 지급 및 차감

화면 상단의 직접 지급 폼에서 관리자가 특정 회원에게 포인트나 경험치를 즉시 지급하거나 차감합니다.

3.1 입력 필드 설명

필드	필수 여부	설명
회원 로그인 ID	필수	지급할 대상 회원의 로그인 ID를 정확히 입력. status=1(활성) 회원만 대상. 없거나 비활성 회원이면 "회원을 찾을 수 없습니다." 오류.
포인트 (P)	선택	지급할 포인트 수. 양수 입력 시 포인트 지급, 음수 입력 시 포인트 차감. 0 입력 시 포인트 변경 없음.
경험치	선택	지급할 경험치 수. 양수 입력 시 경험치 지급, 음수 입력 시 차감. 0 입력 시 경험치 변경 없음.
지급 메모	선택	포인트 변동 로그에 기록될 사유. 미입력 시 "관리자 지급"으로 자동 기록.

💡  포인트와 경험치는 각각 독립적으로 지급됩니다. 포인트만 지급하려면 경험치를 0으로, 경험치만 지급하려면 포인트를 0으로 입력하세요. 둘 다 0이면 아무것도 변경되지 않습니다.

3.2 지급 처리 흐름

1. CSRF 토큰 검증
2. login_id로 members 테이블에서 회원 조회 (status=1 활성 회원만)
3. 회원 없으면 "회원을 찾을 수 없습니다." 오류 메시지
4. pointAmt != 0이면 DxPoint::add(id, "admin", pointAmt, null, null, note) 실행
5. expAmt != 0이면 DxPoint::addExp(id, "admin", expAmt, null, null, note) 실행
6. "[이름] 님에게 포인트/경험치를 지급했습니다." 성공 메시지 표시

3.3 음수 차감 시 주의사항

• 포인트 차감: DxPoint::add()는 balance = max(0, 현재포인트 + 차감금액)으로 계산합니다. 현재 포인트보다 큰 금액을 차감해도 잔액은 0이 되며 마이너스가 되지 않습니다.
• 경험치 차감: DxPoint::addExp()도 동일하게 max(0, ...)으로 처리됩니다. 차감 후 레벨이 변경될 수 있으니 주의하세요.
• 경험치 차감 시 레벨이 내려갈 수 있습니다. 의도치 않은 레벨 다운이 발생하지 않도록 차감 전 현재 경험치를 확인하세요.

⚠️  포인트/경험치 지급•차감은 즉시 적용되며 취소가 불가능합니다. 반드시 대상 회원과 금액을 정확히 확인한 후 실행하세요.

3.4 사용 예시

상황	포인트 입력	경험치 입력	메모 예시
이벤트 상품 당첨	+500	0	2026 봄 이벤트 1등 당첨 포인트
오류로 중복 지급된 포인트 회수	-100	0	4월 15일 중복 로그인 포인트 회수
VIP 회원 경험치 보너스	0	+500	VIP 전환 경험치 보너스
포인트·경험치 동시 지급	+200	+100	월간 우수 회원 보상

4. 포인트 보유 랭킹

포인트 직접 지급 폼 아래에 현재 활성(status=1) 회원의 포인트 보유량 랭킹이 표시됩니다.

4.1 랭킹 테이블 컬럼

컬럼	내용 및 설명
순위	#N 형식. 현재 페이지 내 순위. 마우스 호버 시 주황색으로 강조.
회원 정보	이름(굵은 글씨) + 로그인 ID(모노스페이스).
레벨	"Lv.N 레벨명" 형식의 하늘색 배지. DxPoint::getLevelName()으로 레벨 이름 표시. 예: Lv.3 일반.
보유 포인트	members.point 값. 천 단위 쉼표, 주황색 굵은 글씨 + "P" 단위.
경험치	members.exp 값. 천 단위 쉼표 + "경험치" 단위.
가입일	members.join_date의 YYYY.MM.DD 형식.

4.2 검색 기능

랭킹 목록 상단 오른쪽의 검색 폼에서 이름 또는 로그인 ID로 필터링할 수 있습니다.
 

검색 방식	name LIKE %검색어% OR login_id LIKE %검색어% 조건. DxSanitizer::like()로 SQL Injection 방지.
검색 유지	페이지네이션 이동 시 ?s=검색어 파라미터가 유지됩니다.
검색 초기화	검색어를 지우고 검색하면 전체 목록으로 돌아갑니다.

4.3 랭킹 정렬 기준

기본 정렬: point DESC (보유 포인트 내림차순). 검색 시에도 동일한 정렬이 적용됩니다. 페이지당 20명씩 표시되며, 총 페이지 수가 1을 초과하면 하단에 페이지 버튼이 표시됩니다.

5. 실시간 포인트 변동 로그

화면 하단의 변동 로그 테이블에 최근 30건의 포인트 변동 내역이 실시간으로 표시됩니다. point_log 테이블과 members 테이블을 LEFT JOIN하여 조회합니다.

5.1 로그 테이블 컬럼

컬럼	내용 및 설명
일시	point_log.created_at의 "MM.DD HH:MM:SS" 형식.
회원	이름 + 로그인 ID. LEFT JOIN으로 연결. 탈퇴 회원이면 ID가 비어있을 수 있습니다.
유형	DxPoint::typeName()으로 변환된 한글 유형명. 예: admin→"관리자 지급", write→"글쓰기", login→"로그인".
변동	point_log.point 값. 양수(+)면 초록색, 음수면 빨간색 표시. "+100P" 또는 "-50P" 형식.
잔액	point_log.balance 값. 변동 후 해당 회원의 포인트 잔액.
메모/사유	point_log.note. 최대 200px 너비에서 말줄임(...) 처리. 관리자 지급 시 입력한 메모가 표시됩니다.

5.2 포인트 유형명 변환표

DxPoint::typeName() 메서드는 영문 type 코드를 관리자 화면용 한글 이름으로 변환합니다.
 

type 코드	한글 표시명	색상	설명
login	로그인		로그인 성공 시 자동 지급.
write	글쓰기		게시글 작성 완료 시 자동 지급.
comment	댓글		댓글 작성 완료 시 자동 지급.
like_recv	좋아요 받음		작성 게시글이 좋아요를 받을 때.
scrap_recv	스크랩 받음		작성 게시글이 스크랩될 때.
signup	가입 축하		신규 회원가입 시 자동 지급.
admin	관리자 지급		관리자가 직접 지급·차감.
purchase	포인트 사용	빨간색(음수)	포인트 구매/사용 차감.
refund	포인트 환불	초록색(양수)	포인트 환불 지급.
delete	글 삭제 차감	빨간색(음수)	게시글 삭제 시 포인트 회수.

6. 레벨 시스템

경험치(EXP)가 누적되면 자동으로 레벨이 계산됩니다. 레벨 설정은 DB의 level_config 테이블을 우선 사용하고, 테이블이 없으면 DxPoint 클래스에 내장된 기본값으로 동작합니다.

6.1 기본 레벨 구성 (15단계)

dx_level_config 테이블이 없거나 비어있는 경우 적용되는 기본 레벨 설정입니다.
 

레벨	필요 경험치	레벨명	레벨	필요 경험치	레벨명
Lv.1	0	새싹	Lv.9	5,000	명인
Lv.2	50	초보	Lv.10	8,000	마스터
Lv.3	150	일반	Lv.11	12,000	그랜드
Lv.4	350	활동	Lv.12	18,000	전설
Lv.5	700	열정	Lv.13	26,000	영웅
Lv.6	1,200	고수	Lv.14	36,000	신화
Lv.7	2,000	달인	Lv.15	50,000	전설왕
Lv.8	3,200	전문가

6.2 레벨 자동 계산 원리

경험치가 변경될 때마다 DxPoint::calcLevel() 메서드가 자동으로 레벨을 계산하여 members.level 컬럼을 갱신합니다.
 

calcLevel($exp)	getThresholds()에서 레벨별 필요 경험치 배열을 가져와, 현재 경험치가 해당 임계값 이상인 가장 높은 레벨을 반환합니다.
자동 레벨업 감지	addExp() 호출 후 newLevel > oldLevel이면 dx_levelup 훅이 실행됩니다. 레벨업 알림·보상 등을 이 훅에서 처리할 수 있습니다.
레벨 다운	경험치 차감 시 레벨도 자동으로 재계산됩니다. 경험치가 낮아지면 레벨이 내려갈 수 있습니다.

💡  dx_levelup 훅을 사용하면 레벨업 시 축하 메시지, 추가 포인트 지급, 이메일 알림 등을 플러그인으로 구현할 수 있습니다.

6.3 커스텀 레벨 설정 (level_config 테이블)

관리자가 원하는 레벨 구성으로 변경하려면 dx_level_config 테이블을 사용합니다. 테이블이 존재하고 데이터가 있으면 기본값보다 우선 적용됩니다.
 

컬럼	설명
level	레벨 번호 (INT). 1부터 시작.
exp_required	해당 레벨이 되기 위해 필요한 누적 경험치 (INT).
name	레벨 표시 이름. 예: "새싹", "초보", "마스터".
icon	레벨 아이콘 코드 또는 이모지. 비어있으면 아이콘 미표시.
color	레벨 색상(HEX). 예: #16a34a. 비어있으면 기본 회색(#64748b) 사용.

💡  현재 DXCMS v8.1.0에서 level_config 테이블은 직접 DB를 편집하거나 별도 관리 플러그인을 사용하여 설정합니다. 향후 버전에서 관리자 UI가 제공될 예정입니다.

7. DxPoint API 레퍼런스 (개발자)

개발자가 플러그인이나 테마에서 DxPoint 클래스를 직접 사용하는 경우 참고합니다.

7.1 주요 정적 메서드

메서드 시그니처	설명 및 반환값
DxPoint::add($memberId, $type, $point, $refType, $refId, $note)	포인트 지급/차감. 잔액(int) 반환. $point 0이면 $pointRules[$type] 기본값 사용.
DxPoint::addExp($memberId, $type, $exp, $refType, $refId, $note)	경험치 지급/차감 + 레벨 자동 재계산. 새 경험치 잔액(int) 반환.
DxPoint::getPoint($memberId)	특정 회원의 현재 포인트 반환(int).
DxPoint::getLevel($memberId)	특정 회원의 현재 레벨 반환(int).
DxPoint::calcLevel($exp)	경험치값으로 레벨을 계산하여 반환(int).
DxPoint::getLevelName($level)	레벨 번호에 해당하는 이름 반환(string). 예: 3→"일반".
DxPoint::getLevelIcon($level)	level_config에서 아이콘 코드 반환. 없으면 빈 문자열.
DxPoint::getLevelColor($level)	level_config에서 색상 HEX 반환. 없으면 "#64748b".
DxPoint::getLevelProgress($exp)	현재 레벨 내 진행 퍼센트(0~100) 반환. 프로그레스바 UI에 활용.
DxPoint::getNextLevelExp($exp)	다음 레벨까지 필요한 경험치 반환(int). 최고 레벨이면 null.
DxPoint::getLogs($memberId, $limit, $offset)	특정 회원의 포인트 로그 배열 반환.
DxPoint::getExpLogs($memberId, $limit, $offset)	특정 회원의 경험치 로그 배열 반환.
DxPoint::getThresholds()	레벨별 필요 경험치 배열 반환. DB 우선, 없으면 기본값.
DxPoint::typeName($type)	영문 type 코드를 한글 표시명으로 변환하여 반환.
DxPoint::clearLevelCache()	요청 단위 레벨 설정 캐시를 초기화. level_config 변경 후 호출.

7.2 주요 훅 (Hook)

훅 이름	실행 시점 및 전달 데이터
dx_after_point	포인트 지급/차감 완료 후. 전달: {member_id, type, point, balance}. 포인트 변경 후 추가 처리에 활용.
dx_levelup	레벨업 발생 시. 전달: {member_id, old_level, new_level}. 레벨업 보상·알림 구현에 활용.

8. 전체 사용 절차

8.1 특정 회원에게 포인트 지급

1. 관리자 대시보드 → [포인트 관리] 메뉴 클릭
2. 상단 직접 지급 폼의 [회원 로그인 ID] 필드에 대상 회원 ID 입력
3. [포인트] 필드에 지급할 금액 입력 (차감이면 음수 입력)
4. [경험치] 필드에 경험치 입력 (변경 없으면 0 유지)
5. [지급 메모] 필드에 사유 입력 (선택, 미입력 시 "관리자 지급")
6. [포인트/경험치 지급 실행] 버튼 클릭
7. 성공 메시지 확인
8. 하단 [실시간 변동 로그]에서 방금 지급된 내역 확인

8.2 포인트 랭킹 확인

1. [포인트 관리] 접속
2. 중간 [포인트 보유 랭킹] 패널에서 현재 포인트 상위 회원 확인
3. 검색이 필요하면 오른쪽 검색 폼에서 이름 또는 ID 입력 후 [🔍 검색]
4. 페이지네이션으로 다음 순위 확인

9. 자주 묻는 질문 (FAQ)

Q1. 포인트를 차감했는데 잔액이 0보다 낮아지지 않습니다.

A. 정상적인 동작입니다. DxPoint::add()는 balance = max(0, 현재포인트 + 차감금액)으로 계산합니다. 포인트 잔액은 0 미만이 될 수 없습니다. 현재 포인트보다 많은 금액을 차감하면 잔액이 0이 됩니다.

Q2. 포인트 지급 후 변동 로그에 기록이 없습니다.

A. point_log 테이블이 DB에 존재해야 합니다. DxPoint::add()는 point_log 테이블의 존재 여부를 확인(SHOW TABLES LIKE)하고, 없으면 로그를 기록하지 않고 0을 반환합니다. 테이블이 없다면 DB에 수동으로 생성하거나 마이그레이션을 실행하세요.

Q3. 경험치를 지급했는데 레벨이 변경되지 않았습니다.

A. 경험치 지급 후 DxPoint::calcLevel()이 자동 실행되어 members.level을 갱신합니다. 레벨이 바뀌지 않았다면 현재 경험치가 다음 레벨 임계값에 아직 도달하지 않은 것입니다. 랭킹 목록에서 해당 회원의 레벨과 경험치를 확인하세요.

Q4. 레벨명을 변경하고 싶습니다.

A. dx_level_config 테이블을 생성하고 레벨별 name, exp_required 등을 설정하면 기본값보다 우선 적용됩니다. 현재 v8.1.0에서는 관리자 UI가 없으므로 DB를 직접 편집해야 합니다.

Q5. 포인트 자동 지급 규칙을 변경하고 싶습니다.

A. 현재 포인트 규칙($pointRules, $expRules)은 core/DxPoint.php에 하드코딩되어 있습니다. 규칙 변경은 해당 파일을 직접 수정하거나, DxPoint::add()와 DxPoint::addExp()를 0이 아닌 명시적 금액으로 호출하는 플러그인을 작성하여 기존 훅을 오버라이드하는 방식으로 구현할 수 있습니다.

Q6. 변동 로그에서 오래된 이력을 조회하려면?

A. 현재 관리자 화면에서는 최근 30건만 표시됩니다. 오래된 이력을 조회하려면 DB에서 point_log 테이블을 직접 조회하거나, 개발자가 별도 조회 페이지를 구현해야 합니다.

Q7. 회원의 포인트를 모두 0으로 초기화하려면?

A. 포인트 관리 화면에서 음수 값을 입력하면 0 이하로 내려가지 않습니다. 완전 초기화가 필요하면 DB에서 직접 UPDATE members SET point=0 WHERE id=N을 실행하고, 관련 point_log에 초기화 기록을 수동으로 INSERT하는 방법을 사용하세요.

10. 용어 정리

용어	설명
DxPoint	포인트·경험치·레벨 시스템을 담당하는 DXCMS 핵심 클래스. PHP 5.6+ 호환.
members.point	회원 현재 포인트 잔액. 음수 불가(0 최솟값).
members.exp	회원 누적 경험치. 레벨 계산 기준.
members.level	회원 현재 레벨. addExp() 호출 시 자동 재계산.
dx_point_log	포인트 변동 이력 테이블. member_id/type/point/balance/ref_type/ref_id/note/created_at 컬럼.
dx_exp_log	경험치 변동 이력 테이블. point_log와 동일한 구조.
dx_level_config	커스텀 레벨 설정 테이블. level/exp_required/name/icon/color 컬럼.
point (변동량)	point_log.point 컬럼. 양수=지급, 음수=차감.
balance (잔액)	point_log.balance 컬럼. 변동 후 포인트 잔액.
type	포인트/경험치 변동 유형 코드. login/write/comment/like_recv/scrap_recv/signup/admin/purchase/refund/delete.
ref_type / ref_id	포인트 변동의 참조 데이터. 예: ref_type="board", ref_id=123(게시글 ID).
note	포인트 변동 사유 메모. 관리자 지급 시 입력한 메모.
pointRules	DxPoint 클래스의 정적 배열. 활동 유형별 기본 포인트 지급량 정의.
expRules	DxPoint 클래스의 정적 배열. 활동 유형별 기본 경험치 지급량 정의.
defaultThresholds	level_config 테이블 없을 때 사용하는 기본 레벨-경험치 임계값 배열.
defaultNames	level_config 테이블 없을 때 사용하는 기본 레벨명 배열.
calcLevel($exp)	경험치를 받아 현재 레벨을 계산하는 메서드. thresholds 배열을 순회하며 최고 달성 레벨 반환.
getLevelProgress($exp)	현재 레벨 내 경험치 진행 퍼센트(0~100). 프로그레스바 표시에 사용.
dx_after_point	포인트 변동 후 실행되는 훅. 포인트 변경 후 추가 처리.
dx_levelup	레벨업 시 실행되는 훅. 레벨업 보상·알림 구현에 사용.
DxSanitizer::like()	LIKE 절의 특수문자(%,_,\)를 이스케이프하는 메서드. SQL Injection 방지.