well-service

책을 쌓아 올려 ‘우물’을 만드는 독서 게이미피케이션 플랫폼 Frolog의 우물 도메인 서비스입니다.

우물(독서 목표 집합)과 우물 아이템(책)을 생성·조회·정렬·삭제하고, 활동량 상위 사용자를 주간 집계합니다.

주요 기능

• 우물 생성·수정·삭제 및 단건 조회
• 우물 이름 중복 체크
• 우물 목록 검색 및 페이지네이션
• 우물 아이템(책) 등록·수정·삭제, 순서 변경(단건/일괄), 상태 변경
• 우물 아이템 목록 검색/정렬 (created_at, order)
• 사용자별 우물 아이템 수 집계
• 우수 사용자(상위 10% 활동량) 주간 선별 스케줄러

기술 스택

• Node.js (ESM), Express 기반 @frolog/express-api-server
• ORM: Sequelize (@frolog/models)
• 공통 유틸: @frolog/common-utils (HashId 인코딩/디코딩, 로거 등)
• 외부 API 연동: @frolog/frolog-api (도서/메모/리뷰/스토어 연계)
• Lint/Format: ESLint, Prettier

실행 방법

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

디렉터리 구조

src/
  index.js              # API 서버 부트스트랩 및 라우팅
  services/             # 도메인 서비스 로직
    searchWell.js       # 우물 목록 검색
    getWell.js          # 우물 단건 조회
    postWell.js         # 우물 생성
    editWell.js         # 우물 수정
    deleteWell.js       # 우물 삭제
    searchWellItem.js   # 우물 아이템 검색/정렬
    getWellItem.js      # 우물 아이템 조회
    postWellItem.js     # 우물 아이템 생성 + 초기 보상 지급
    editWellItem.js     # 우물 아이템 수정
    deleteWellItem.js   # 우물 아이템 삭제
    deleteWellItemsByCondition.js # 조건부 일괄 삭제
    changeWellItemOrder.js / changeWellItemOrderBulk.js # 순서 변경
    changeWellItemStatus.js        # 상태 일괄 변경(읽음 등)
    getUserWellItemCount.js        # 사용자 우물 아이템 수 집계
    searchUserWell.js              # 사용자별 우물 검색 (검색/랜덤)
    setHeavyUsers.js               # 상위 활동 사용자 선별

API 엔드포인트 맵

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

• GET: GetWellNameAvailability, SearchWell, GetWell, SearchWellItem, GetWellItem, SearchUserWell, GetUserWellItemCount
• POST: ChangeWellItemStatus, ChangeWellItemOrder, ChangeWellItemOrderBulk, PostWell, PostWellItem, SetHeavyUsers
• PATCH: EditWell, EditWellItem
• DELETE: DeleteWellItemsByCondition, DeleteWell, DeleteWellItem

스케줄러

• 매주 월요일 KST 04:00 (UTC 19:00, 다음 주부터 시작) setHeavyUsers 자동 실행
• 마스터 프로세스(IS_MASTER)에서만 동작

권한/인증

• login/admin 레벨이 엔드포인트별로 지정되어 있으며, 우물/아이템 접근 시 해시된 ID를 디코딩해 소유자 검증을 수행합니다.