Curated Book Section Management

📚 큐레이션 섹션 관리 가이드 (Curated Section Management)

이 스킬은 '칼데콧 수상작'과 같이 특별한 테마의 도서 컬렉션을 서비스에 추가할 때 따르는 표준 절차입니다.

1. 기획 및 카피라이팅 (Planning & Copywriting)

타이틀 및 메시지 선정

• 규칙: 섹션의 타이틀과 서브 텍스트는 **마케팅 팀장 페르소나**의 제안을 따릅니다.
• 목표: 단순한 정보 전달을 넘어 학부모의 니즈를 자극하는 '셀링 포인트'를 포함해야 합니다.
• 예시 (칼데콧):
  • 타이틀: "칼데콧 수상작" (명확하고 권위 있는 키워드)
  • 서브 텍스트: "미국 도서관 사서들이 엄선한 최고의 그림책" (신뢰성 강조)

2. 데이터 준비 및 품질 관리 (Data Preparation)

이미지 품질 (Image Quality)

• 필수 사항: 도서 표지 이미지는 반드시 **고해상도(cover500)**를 사용해야 합니다.
• 금지 사항: 저해상도 썸네일(coversum)은 메인 UI의 퀄리티를 떨어뜨리므로 절대 사용하지 않습니다.
• 방법: 알라딘 API 등을 통해 데이터 수집 시, 이미지 URL 패턴을 cover500으로 변경하거나 해당 해상도의 이미지를 우선적으로 확보합니다.

도서 검색 및 매칭 (ISBN Search Strategy)

• 원서 기반 검색 (For Translated Works):
  • 칼데콧 수상작처럼 해외 원작이 있는 경우, 한국어 번역명으로 검색하면 정확한 ISBN을 찾기 어렵거나 절판된 구판이 검색될 수 있습니다.
  • 해결책: **원서 제목(English Title)**과 저자명을 조합하여 검색한 뒤, 국내 번역본의 ISBN을 매칭하는 방식을 사용합니다.
  • Note: 이 방식은 칼데콧이나 뉴베리 등 해외 수상작 컬렉션 구축 시 특히 유효합니다.

연령대(Age) 매핑 표준 (Elementary Age Mapping)

• 초등 연령 매핑 규격:
  • 초등학교 16학년 대상 도서들을 프론트엔드 연령별 추천 필터 탭 중 **'812세'**에 정확하게 표시하기 위해서는, DB childbook_items.age 컬럼의 값을 **'9세부터'**로 일치시켜 적재해야 합니다.
  • 기획서상의 초등 학년군(예: 초등 1-2학년, 초등 3-4학년 등)은 DB에 삽입할 때 이 규칙에 따라 일괄 '9세부터'로 표준화하여 탭 노출 오작동을 원천 예방합니다.

카테고리화 (Categorization)

• SQL 및 파이썬 기반 분류:
  • 수집된 도서 데이터는 childbook_items 테이블에 저장될 때, 분류 속성에 따라 알맞은 category 태그(예: 동화, 그림책, 과학, 사회, 전통 등)를 부여해야 합니다.
  • 알라딘 API 장르 코드를 기본 매핑하되, 정합성이 떨어지는 책은 manual_mappings 등으로 직접 보정합니다.

3. 디자인 및 UI 구현 (Design & Implementation)

UI 일관성 유지

• 기존 섹션 참조: 새로운 섹션은 기존의 '겨울방학 추천 도서', '어린이 도서 연구회' 섹션과 동일한 UI 구조를 유지해야 합니다.
• 컴포넌트 재사용: BookList, BookCard 등 이미 검증된 공통 컴포넌트를 사용하여 개발 효율성과 사용자 경험의 일관성을 확보합니다.

모바일 큐레이션 레이아웃 및 터치 스와이프 인터랙션

• 가로 스크롤 카드 레이아웃(Horizontal Scroll): 모바일(가로폭 360px)에서 화면 높이를 아끼고 여러 큐레이션을 한눈에 훑어볼 수 있도록 큐레이션 도서 목록은 기본적으로 가로 스크롤(Flex wrap 대신 overflow-x-auto, flex-nowrap)이 가능한 형태로 구현한다.
• 가로 스크롤 지연 방지: 터치 스와이프가 매끄럽게 동작하도록 CSS scroll-behavior: smooth와 -webkit-overflow-scrolling: touch 속성을 부여한다.
• 마지막 아이템 여백: 가로 스크롤 시 마지막 도서 카드가 화면 우측 끝에 너무 달라붙지 않도록, 컨테이너 끝에 적절한 padding-right(최소 16px)를 확보해 모바일 터치 사용성을 높인다.

구현 체크리스트

• Data Fetching: lib/home-api.ts 등에 해당 큐레이션을 위한 Fetch 함수 추가
• Display Logic (Quality Control): 홈 화면 섹션의 경우, 사용자 경험을 위해 최소 7권 이상의 도서가 존재할 때만 섹션을 렌더링하도록 조건부 로직 추가
• Component Update: HomePageClient.tsx에 새로운 섹션 추가
• Responsiveness: 모바일/태블릿/데스크탑 환경에서의 스크롤 및 배치 확인
• Link Routing: "더보기" 클릭 시 해당 큐레이션 필터가 적용된 목록 페이지(/books?curation=xxx)로 이동

[예시] 노출 품질 관리 로직 (Early return)

function CurationSection({ title, books, ...props }) {
  // 7권 미만인 경우 섹션 자체를 노출하지 않음 (유저 경험 보장)
  if (books.length < 7) return null;
  
  return (
    <section>
      <h2>{title}</h2>
      <BookGrid books={books} />
    </section>
  );
}

큐레이션 리스트 노출 정렬 순서 규칙

• 시각적 연속성: 유저가 메인 화면의 큐레이션 섹션에서 "더보기"를 눌러 전체 목록 페이지(/books?curation=xxx)로 전환했을 때의 연속적인 사용자 경험(UX)을 확보하기 위해 다음을 준수합니다.
• 홈 화면 노출 도서 상단 우선 고정:
  • 홈 화면에 노출되었던 7권의 추천/큐레이션 도서가 목록 페이지에서도 항상 최상단에 우선 노출되도록 처리합니다. (BookList.tsx의 shouldFetchRecommended에 큐레이션 추가)
• 기본 정렬 순서(ㄱㄴㄷ 정렬):
  • 칼데콧 등 특별 테마 큐레이션의 경우, 유저가 정렬 필터를 변경하지 않은 기본 상태일 때 청구기호 대신 **제목(title 오름차순, 즉 ㄱㄴㄷ 순)**을 기본 정렬로 설정하여 홈 노출 순서와 일치시킵니다. (supabase-client.ts, books-api-server.ts에서 각 큐레이션에 맞는 기본 정렬 값을 분기 처리)

📅 주간 큐레이션 동기화 및 셔플 정책

• 홈페이지 동기화: 홈페이지의 dynamic 큐레이션 섹션(2~4번째)은 7일 주기(목요일 기준)로 자동 갱신되며, 프론트엔드와 백엔드가 동일한 셔플 순서를 공유해야 합니다.
• LCG 난수 및 Fisher-Yates 대칭 구현:
  • 자바스크립트 오차와 시간대 편차 방지를 위해 UTC 타임스탬프 기준으로 Unix epoch 일수를 구한 후 시드(Seed)로 사용합니다.
  • 백엔드와 프론트엔드는 동일한 LCG(Linear Congruential Generator) 난수 식을 사용하며, 초기 LCG 연산에 32비트 비트 마스킹(& 0xffffffff)을 반드시 적용합니다.
  • Fisher-Yates 셔플 알고리즘을 이 시드 기반 LCG로 실행하여 두 환경에서 100% 동일한 순서의 큐레이션 테마(예: 1. 과학원리, 2. 사회성, 3. 감정조절)를 노출합니다.

4. 검증 및 배포 (Verification)

• 데이터 무결성 확인: 이미지가 깨지지 않는지, ISBN이 정확한지 SQL 조회 및 UI 확인
• 가독성 점검: 디자인 팀장 페르소나 기준에 맞춰, 타이틀과 책 정보가 서가 환경(모바일)에서도 잘 보안지 확인