store-service

인앱 상점·아이템·지갑·포인트 관리를 담당하는 독서 게이미피케이션 플랫폼 Frolog의 스토어 도메인 서비스입니다.

상점 아이템 CRUD, 개구리 수집품 지급, 포인트 기반 구매 시스템, 사용자 지갑 관리, 아이템 소유 추적을 처리합니다.

주요 기능

• 상점 아이템 생성·수정·삭제 (관리자)
• 아이템 검색·조회 (페이지네이션, 소유 여부 포함)
• 아이템 가용성 검증 (조건, 날짜 범위, 비활성화 플래그)
• 아이템 구매 (포인트 차감, 소유권 생성)
• 관리자 아이템 지급 (무료 지급)
• 초기 개구리 아이템 지급 (도서 수 기반, 'fro', 'rogy', 'roro')
• 사용자 지갑 생성·조회
• 포인트 추가 (관리자)
• 포인트 차감 (구매 시 자동)
• 아이템 조건 검증 (event-service 연동)

기술 스택

• Node.js (ESM), Express 기반 @frolog/express-api-server
• ORM: Sequelize (@frolog/models)
• 공통 유틸: @frolog/common-utils (로거, HashId, clamp 등)
• API 계약: @frolog/frolog-api
• Lint/Format: ESLint, Prettier

실행 방법

npm install
npm run dev   # 개발 (nodemon)
npm start     # 프로덕션
npm run lint  # 코드 규칙 검사
npm run doc   # JSDoc 생성

디렉터리 구조

src/
  index.js                      # API 서버 부트스트랩 및  라우팅
  services/
    postStoreItem.js            # 아이템 생성 (관리자)
    searchStoreItem.js          # 아이템 검색 (페이지네이 션, 소유 여부)
    getStoreItem.js             # 아이템 단건 조회
    editStoreItem.js            # 아이템 수정 (관리자)
    deleteStoreItem.js          # 아이템 삭제 (관리자)
    grantStoreItem.js           # 아이템 지급 (관리자, 무 료)
    grantInitialStoreItem.js    # 초기 개구리 아이템 지급 (도서 수 기반)
    purchaseStoreItem.js        # 아이템 구매 (포인트 차감)
    postWallet.js               # 지갑 생성 (관리자)
    getWallet.js                # 지갑 조회 (포인트 잔액)
    addPointsToWallet.js        # 포인트 추가 (관리자)

API 엔드포인트 맵

src/index.js에서 @frolog/frolog-api 스펙과 서비스 로직을 매핑합니다.

• GET: SearchStoreItem (공개), GetWallet (login)
• POST: PostStoreItem (admin), GrantStoreItem (admin), GrantInitialStoreItem (login), PurchaseStoreItem (login), PostWallet (admin), AddPointsToWallet (admin)
• PATCH: EditStoreItem (admin)
• DELETE: DeleteStoreItem (admin)

스케줄러

없음. 모든 작업은 HTTP 요청 기반으로 처리됩니다.

권한/인증

• SearchStoreItem: 공개 API (인증 불필요, 소유 여부는 인증 시 포함)
• GetWallet, GrantInitialStoreItem, PurchaseStoreItem: 로 그인 필수
• GrantInitialStoreItem: 본인에게만 지급 가능 (관리자는 타인에게도 지급 가능)
• PostStoreItem, EditStoreItem, DeleteStoreItem, GrantStoreItem, PostWallet,
• AddPointsToWallet: 관리자 전용 (is_admin=true)
• HashId 인코딩: 모든 사용자 ID는 해시 형식으로 처리

상점 시스템 구조

아이템 생성 (PostStoreItem)

• item_key (고유 식별자), type (아이템 유형)
• name (표시 이름), description (설명)
• conditions (구매 조건, 이벤트 키 배열)
• price (포인트 가격)
• start/end (판매 기간, 선택적)
• disabled (비활성화 플래그)

아이템 검색 (SearchStoreItem)

• 페이지네이션 (limit: 0-100, 기본값 10)
• 인증 사용자: 소유 여부(is_owned) 및 획득 시각 포함
• 미인증 사용자: 소유 정보 null

아이템 가용성 검증

• 비활성화 체크: disabled=false
• 날짜 범위 체크: start ≤ 현재 ≤ end (선택적)
• 조건 체크: conditions 배열의 모든 이벤트 키 충족 확인 (event-service 연동)

아이템 구매 (PurchaseStoreItem)

1. 아이템 가용성 검증 (비활성화, 날짜, 조건)
2. 지갑 잔액 확인 (points ≥ price)
3. 포인트 차감 (Wallet.points -= price)
4. 소유권 생성 (OwnedItem)
5. 원자적 트랜잭션 (포인트 차감 + 소유권 생성)

아이템 지급 (GrantStoreItem)

• 관리자 전용
• 무료 지급 (포인트 차감 없음)
• OwnedItem 레코드 생성

초기 개구리 지급 (GrantInitialStoreItem)

• 특수 개구리 수집품: 'fro', 'rogy', 'roro'
• 도서 수 기반 지급 (단일 또는 일괄)
• 기존 소유 아이템 제외 (중복 방지)
• 본인에게만 지급 가능 (관리자는 타인에게도 지급 가능)

지갑 시스템

지갑 생성 (PostWallet)

• 관리자 전용
• 초기 포인트 설정
• user_id별 고유 지갑

지갑 조회 (GetWallet)

• 현재 포인트 잔액 조회
• points_spent 필드 존재 (현재 미사용)

포인트 추가 (AddPointsToWallet)

• 관리자 전용
• Wallet.points += 추가 포인트
• TODO: 포인트 거래 ID 반환 (미구현)

주요 모델

StoreItem

• item_key (PK), type, name, description
• conditions (이벤트 키 배열), price
• start, end (판매 기간), disabled

OwnedItem

• item_key (FK), owner_id (FK) - 복합 PK
• created_at (획득 시각)

Wallet

• user_id (PK), points (잔액), points_spent (총 지출)

서비스 간 연동

• Event Service: 아이템 조건 검증 (SearchEventRecord)
• SSC_TOKEN: 서비스 간 인증 토큰