관리자 가이드
Filament 관리 패널에서 상품과 주문을 관리하는 방법입니다.
상품 관리
상품 등록
- Tenant 패널 접속 → 좌측 메뉴 커머스 > 상품 관리
- 우상단 새로 만들기 클릭
- 상품 정보 입력:
| 필드 | 필수 | 설명 |
|---|---|---|
| 상품명 | ✅ | 표시될 이름 |
| 슬러그 | ❌ | URL용 (비워두면 자동 생성) |
| 상품 설명 | ❌ | 리치 에디터 (HTML) |
| 옵션 상품 | ❌ | 색상/사이즈 등 옵션이 있는 경우 |
| 가격 | ✅ | 원 단위 (예: 29900) |
| 할인 전 가격 | ❌ | 설정하면 할인 표시 |
| SKU | ❌ | 재고관리 코드 |
| 재고 | ✅ | 수량 (0이면 품절 표시) |
| 상태 | ✅ | 임시저장/게시됨/예약/보관 |
옵션 상품 (Variant)
옵션 상품을 활성화하면 개별 옵션(색상, 사이즈 등)별로 가격과 재고를 관리합니다.
Variant는 DB에서 직접 관리하며, 향후 Filament RelationManager로 UI를 제공할 예정입니다.
주문 관리
Tenant 패널 > 커머스 > 주문 관리에서 확인합니다.
Smartro 결제수단 설정의 의미
사이트 설정의 결제창 요청 수단(CARD/BANK/VBANK)은 MSK가 Smartro 결제창에 요청하는 값입니다. 삼성페이·카카오페이·네이버페이 같은 실제 노출 수단은 Smartro 가맹점 계약과 설정이 결정합니다.
결제창 요청 목록은 승인 응답의 허용 목록이 아닙니다. 고객이 Smartro가 노출한 간편결제를 선택하면 MSK는 응답의 PayMethod와 해당 채널의 공식 ResultCode를 정확히 결합해 검증합니다. 따라서 Smartro 가맹점에서 승인된 간편결제를 MSK 설정이 임의로 차단하지 않습니다.
주문 상태
| 상태 | 설명 |
|---|---|
| 주문접수 (pending) | 고객이 주문 완료 |
| 주문확인 (confirmed) | 관리자가 확인 |
| 처리중 (processing) | 상품 준비 중 |
| 배송중 (shipped) | 택배 발송 |
| 배송완료 (delivered) | 배송 완료 |
| 취소 (cancelled) | 주문 취소 |
결제 상태
| 상태 | 설명 |
|---|---|
| 결제대기 (pending) | 결제 전 |
| 결제완료 (paid) | 결제 성공 |
| 결제실패 (failed) | 결제 오류 |
| 환불완료 (refunded) | 전액 환불 |
| 부분환불 (partial_refund) | 일부 환불 |
PG 결제 실패 운영자 알림
외부 PG의 일반 결제 실패를 사이트 운영 채널로 받으려면 다음과 같이 설정합니다.
- 사이트 설정 > 운영자 알림에서 이메일·웹훅·텔레그램·카카오 알림톡 중 필요한 채널을 등록합니다.
- 이벤트 목록의 PG 결제 실패(
operator.payment_failed)를 활성화합니다. - 이벤트를 받을 채널을 선택하고 저장합니다.
- 테스트 발송으로 채널 자격증명과 수신 상태를 확인합니다.
이 이벤트는 opt-in이므로 활성화하지 않은 사이트에는 발송되지 않습니다. 실제 결제 실패가 발생하면 거래 원장을 먼저 확정한 뒤 알림을 발행하며, 알림 전송 장애가 주문·결제 상태를 되돌리지 않습니다. 각 채널은 독립적으로 재시도합니다.
| 상황 | 발행 이벤트 | 운영 의미 |
|---|---|---|
| 외부 PG의 일반 승인 거절·통신/응답 검증 실패 | operator.payment_failed | 오류코드와 사유를 확인 하고 PG·가맹점 설정을 점검 |
| PG 승인 후 주문·금액·MID·서명·채널의 로컬 정합성 실패 | operator.payment_unreconciled | PG 확인 필요 주문에서 승인분 취소 여부를 검토 |
| 지갑 잔액 부족 또는 고객이 결제창을 닫음 | 발행하지 않음 | 운영자 장애 알림 대상이 아님 |
일반 실패 알림에는 사이트명·주문번호·게이트웨이·금액·통화·정규화한 오류코드와 사유만 포함합니다. 원본 PG 응답, TID, 서명값, 빌링 토큰은 포함하지 않습니다. 알림의 사이트명은 결제 원장에 저장된 SaaS/Tenant 범위에서 해석하므로 여러 독립사이트를 운영하는 프로젝트에서도 실패 사이트를 구분할 수 있습니다.
주문 필터
- 주문상태별: 주문접수/확인/처리중/배송중/완료/취소
- 결제상태별: 대기/완료/실패/환불
PG 확인 필요 주문 처리
PG 확인 필요 배지는 PG 승인까지 성공했지만 MSK의 주문번호·금액·MID·서명·결제채널 검증에서 로컬 반영이 거부된 주문을 뜻합니다. 이때 주문과 결제 원장은 실패 상태를 유지하지만 PG에는 승인금액이 남아 있을 수 있습니다.
이 주문은 정상 결제를 취소하는 환불 대상이 아닙니다. PG 승인분 취소는 PG에만 남은 승인분을 원상복구하는 별도 조치입니다.
- 주문의
PG 확인 필요배지와 승인 TID·금액을 확인합니다. - 주문 액션에서 PG 승인분 취소를 선택합니다.
- 표시된 주문번호·승인금액·TID가 해당 거래와 일치하는지 다시 확인합니다.
- 요구되는 step-up 인증을 완료하고 취소를 실행합니다.
- 성공하면 배지가 제거되고
commerce.pg_void감사로그가 남습니다.
취소가 실패하면 배지와 승인 스냅샷이 유지됩니다. 알림과 오류코드를 확인하고 Smartro 가맹점 설정·거래 상태를 점검한 뒤 재시도하세요. 원인을 확인하지 않은 반복 실행이나 일반 환불 액션으로의 우회는 피합니다.
패널별 관리 범위
| 패널 | Level | 범위 |
|---|---|---|
| Platform | 0 | 모든 테넌트의 상품/주문 |
| SaaS | 1 | SaaS 소속 상품/주문 |
| Tenant | 2 | 자기 테넌트만 |