API 엔드포인트 정보

기능 메서드 엔드포인트 설명 요청 데이터 성공 응답
코인 잔액 조회 GET /coins 현재 로그인한 사용자의 코인 잔액을 조회 없음 { "result": "SUCCESS", "coins": 1000 }
코인 차감 POST /coins/deduct 사용자의 코인을 100개 차감 없음 { "result": "SUCCESS", "message": "100 코인이 차감되었습니다.", "deducted": 100, "remainingCoins": 900 }
광고 시청 충전 POST /coins/recharge/ad 광고 시청 후 500코인 충전 { "adCompleted": true } { "result": "SUCCESS", "message": "광고 시청으로 500 코인이 충전되었습니다.", "recharged": 500, "currentCoins": 1500 }
구매 충전 POST /coins/purchase 구매를 통한 코인 충전 { "amount": 1000, "paymentId": "pay_123", "paymentType": "CARD" } { "result": "SUCCESS", "message": "1000 코인이 성공적으로 충전되었습니다.", "purchased": 1000, "currentCoins": 2500 }

오류 응답 정보

오류 유형 HTTP 상태 코드 결과 코드 응답 내용
인증 필요 401 AUTH_REQUIRED { "result": "AUTH_REQUIRED", "message": "로그인이 필요합니다." }
사용자 없음 404 USER_NOT_FOUND { "result": "USER_NOT_FOUND", "message": "사용자를 찾을 수 없습니다." }
코인 부족 400 INSUFFICIENT_COINS { "result": "INSUFFICIENT_COINS", "message": "코인이 부족합니다.", "currentCoins": 50 }
잘못된 파라미터 400 INVALID_PARAMETER { "result": "INVALID_PARAMETER", "message": "유효한 충전 수량을 입력해주세요." }
광고 미완료 400 AD_NOT_COMPLETED { "result": "AD_NOT_COMPLETED", "message": "광고 시청이 완료되지 않았습니다." }
결제 검증 실패 400 PAYMENT_VERIFICATION_FAILED { "result": "PAYMENT_VERIFICATION_FAILED", "message": "결제 검증에 실패했습니다." }
업데이트 실패 500 UPDATE_FAILED { "result": "UPDATE_FAILED", "message": "코인 차감/충전에 실패했습니다." }
서버 오류 500 ERROR { "result": "ERROR", "message": "서버 오류가 발생했습니다." }

코드 구성 요소

컴포넌트 역할 구현 상태
인증 미들웨어 로그인 여부 확인 구현 완료
DB 필드 users 컬렉션의 coins 필드 구현 완료
코인 로그 코인 거래 내역 기록 주석 처리됨
결제 검증 외부 결제 API 연동 더미 함수(항상 true 반환)
결제 내역 payments 컬렉션에 기록 주석 처리됨

추가 필요 사항

구분 설명
로그 활성화 coinLogs 컬렉션을 활성화하여 모든 코인 거래 내역 추적 필요
결제 연동 실제 PG사 API와 연동하여 verifyPayment 함수 구현 필요
오류 처리 결제 성공 후 코인 충전 실패 시 복구 로직 추가 필요
환불 기능 필요 시 환불 API 추가 구현