리워드 API

리워드 스키마

Fields

userId

• 타입: ObjectId (User 참조)
• 필수: true
• 설명: 구매자 정보
• 참조: User 컬렉션의 _id

referrerId

• 타입: ObjectId (User 참조)
• 필수: true
• 설명: 추천인 정보
• 참조: User 컬렉션의 _id

productId

• 타입: ObjectId (Product 참조)
• 필수: true
• 설명: 구매한 상품 정보
• 참조: Product 컬렉션의 _id

domain

• 타입: ObjectId (Domain 참조)
• 필수: true
• 설명: 리워드가 발생한 도메인
• 참조: Domain 컬렉션의 _id

amount

• 타입: Number
• 필수: true
• 설명: 리워드 금액
• 최소값: 0

level

• 타입: Number
• 필수: true
• 설명: 추천 단계 (1-5)
• 제약: 도메인의 maxReferralLevel 이하

timestamps

• createdAt: 리워드 생성 시간
• updatedAt: 리워드 정보 수정 시간
• 자동생성: true

API 엔드포인트

리워드 내역 조회

GET /api/v1/rewards

요청 파라미터

• page: 페이지 번호 (기본값: 1)
• limit: 페이지당 항목 수 (기본값: 10)
• search: 검색어 (symId 기준)
• sortBy: 정렬 기준 (createdAt, amount)
• sortOrder: 정렬 순서 (ASC, DESC)
• domain: 도메인 필터

응답

{
    "items": [
        {
            "userId": {
                "symId": "buyer123",
                "nickName": "구매자",
                "referralCode": "12345"
            },
            "referrerId": {
                "symId": "referrer456",
                "nickName": "추천인"
            },
            "productId": {
                "name": "Premium Package",
                "price": 200,
                "snpQty": 100
            },
            "domain": {
                "name": "example.com",
                "title": "Example Domain"
            },
            "amount": 20,
            "level": 1,
            "createdAt": "2024-02-19T02:08:44.285Z"
        }
    ],
    "pagination": {
        "total": 100,
        "page": 1,
        "limit": 10,
        "totalPages": 10
    }
}

SymID로 리워드 내역 조회

GET /api/v1/users/rewards/by-symid?symId={symId}

요청

• symId: Symverse 계정 ID (필수)

응답

[
    {
        "userId": {
            "symId": "buyer123",
            "nickName": "구매자",
            "referralCode": "12345"
        },
        "productId": {
            "name": "Premium Package",
            "price": 200,
            "snpQty": 100
        },
        "domain": {
            "name": "example.com",
            "title": "Example Domain"
        },
        "amount": 20,
        "level": 1,
        "createdAt": "2024-02-19T02:08:44.285Z"
    }
]

리워드 처리 프로세스

1. 주문 완료 시점
2. 구매자의 추천 관계 확인
3. 도메인의 리워드 정책 확인

4. 각 단계별 추천인 식별

5. 리워드 계산

6. 상품 가격 기준 리워드 계산
7. 각 단계별 리워드 비율 적용

8. 최대 추천 단계 제한 적용

9. 리워드 지급

10. 각 추천인에게 리워드 생성
11. 리워드 내역 기록

12. 추천인 잔액 업데이트

13. 알림 처리

14. 리워드 지급 알림 생성
15. 추천인에게 알림 발송

인덱스

• { userId: 1 }: 구매자별 조회 최적화
• { referrerId: 1 }: 추천인별 조회 최적화
• { domain: 1 }: 도메인별 조회 최적화
• { createdAt: -1 }: 생성일 기준 정렬 최적화

참고사항

1. 리워드는 주문 완료 시점에 자동 생성됨
2. 리워드 금액은 상품 가격과 단계별 비율로 계산
3. 추천 단계는 도메인별 최대 단계 설정을 따름
4. 리워드 내역은 생성 후 수정/삭제 불가
5. 모든 금액은 소수점 처리하지 않음