bookjeok (북적)
책과 지식의 선순환 플랫폼
키워드 도서 검색, AI 도서 요약, 독서 기록 관리, 에스크로 결제 기반 중고책 거래, 실시간 채팅, 도서 리뷰, 독자 커뮤니티가 결합된 통합 도서 플랫폼.
목차
한눈에 보기
| |
|---|
| 서비스 | https://bookjeok.com |
| 구성 | Turborepo 모노레포 — 앱 3개(web / server / admin), 공용 패키지 3개(core / api-client / react-query), 운영자 도구 1개(tools/book-ingest) |
| 프론트엔드 | Next.js 15 App Router + React 19, 한국어/영어 다국어, ISR + On-Demand Revalidation |
| 백엔드 | NestJS 11 + TypeORM + PostgreSQL(pgvector, cube/earthdistance) |
| AI | Google Gemini — 도서 요약. RAG 대화형 추천(의도 분류 → pgvector 검색 → 리랭킹)은 서버에 유지하되 웹 UI 비노출 |
| 실시간 | Socket.IO 채팅·알림 게이트웨이 |
| 결제 | 토스페이먼츠 에스크로 + Delivery Tracker 배송 추적 + 스케줄러 기반 자동 확정/환불 |
| 인프라 | Vercel(web) · Azure Container Apps(server) · Supabase PostgreSQL |
시스템 아키텍처
┌─────────────────────────────┐
│ Browser / Mobile Web │
└──────────────┬──────────────┘
│
┌──────────────────────────┼──────────────────────────┐
│ HTTPS (REST) │ SSE │ WebSocket
▼ ▼ ▼
┌────────────────────────────────────────────────────────────────────────┐
│ apps/web — Next.js 15 (Vercel) │
│ App Router · RSC/ISR · next-intl(ko/en) · TanStack Query · Zustand │
│ Route Handlers: /api/upload, /api/revalidate, /rss.xml, sitemap.ts │
└───────────────────────────────┬────────────────────────────────────────┘
│
@bookjeok/react-query → api-client → core
│
▼
┌────────────────────────────────────────────────────────────────────────┐
│ apps/server — NestJS 11 (Azure Container Apps, Docker) │
│ │
│ Global Pipeline │
│ cookie-parser → helmet → compression → CORS │
│ ThrottlerGuard → LoggingInterceptor → SmartCacheInterceptor │
│ → ActivityTrackingInterceptor → CacheInvalidationInterceptor │
│ → TransformInterceptor → ClassSerializerInterceptor │
│ → ValidationPipe(whitelist) → GlobalExceptionFilter(ERROR_CODES) │
│ │
│ Domain Modules │
│ auth · user · book · review · comment · reading-log · wishlist │
│ used-book-sale · order · trade · chat · llm · search · search-keyword │
│ insights · notification · feedback · health │
│ │
│ Cross-cutting │
│ CLS Transactional · EventEmitter · @nestjs/schedule · Resend Mail │
│ SmartCache · Activity Log · Idempotency │
└───┬──────────────┬───────────────┬────────────────┬────────────────────┘
│ │ │ │
▼ ▼ ▼ ▼
┌──────────┐ ┌────────────┐ ┌──────────┐ ┌────────────────────────┐
│ Supabase │ │ Gemini │ │ Toss │ │ Naver · Kakao (OAuth) │
│ Postgres │ │ Flash / │ │ Payments │ │ Delivery Tracker │
│ pgvector │ │ embedding │ │ (Escrow) │ │ Resend │
│ earthdist│ │ │ │ │ │ Vercel Blob │
└──────────┘ └────────────┘ └──────────┘ └────────────────────────┘
┌────────────────────────────────────────────────────────────────────────┐
│ apps/admin — Next.js 15 관리자 포털 │
│ 초기 세팅만 된 미배포 앱 (통계·검수·캐시 제어 화면 뼈대) │
└────────────────────────────────────────────────────────────────────────┘
그림의 SSE 경로와 Gemini 임베딩은 RAG 대화형 추천용입니다. 추천은 2026-09-29에 웹 UI에서
내렸으므로 지금은 브라우저가 이 경로를 쓰지 않습니다(서버 엔드포인트는 유지).
Features
키워드 기반 도서 검색
자체 DB에 적재한 도서 약 6.6만 종을 제목·저자·출판사로 검색합니다. pg_trgm GIN 인덱스 기반 부분일치이며, 관련도(완전일치 → 접두일치 → 부분일치)로 버킷을 나눈 뒤 알라딘 판매지수(salesPoint)로 순서를 가립니다. 런타임에 외부 도서 API를 호출하지 않습니다(아래 「외부 서비스 연동」 참고). TanStack Query 기반 무한 스크롤로 결과를 점진적으로 탐색하며, 사용자 검색어는 정규화 후 별도로 기록되어(초성 제거·공백 정리·2글자 미만 폐기) 최근 1년 기준 인기 검색어 Top 10을 집계합니다.
RAG 기반 AI 도서 추천 (웹 UI 비노출)
2026-09-29부터 웹에 노출하지 않습니다. 검색 화면의 AI 추천 탭을 내렸고 ?mode=ai도
키워드 검색으로 보입니다. 서버 모듈·엔드포인트(/search/ai, /search/ai/stream)와 웹
컴포넌트는 되살릴 때를 위해 남겨 두었습니다. 비용과 Supabase 무료 티어 용량 때문에
books.embedding 컬럼은 유지하되 값은 비워 두었으므로, 다시 켜려면 임베딩 재생성이 먼저입니다.
아래는 구현된 설계입니다.
사용자가 "주말에 가볍게 읽을 만한 에세이 찾고 있어요" 같은 자연어를 입력하면, 도서 DB에서 의미론적 유사도를 기반으로 도서를 찾아 추천합니다.
도서 메타데이터(제목·저자·줄거리·장르)를 결합한 텍스트를 Google gemini-embedding-001 모델로 768차원 벡터로 변환하여 PostgreSQL pgvector에 저장하는 사전 임베딩 작업을 거칩니다. 검색 시점에는 사용자의 질문도 동일한 모델로 임베딩한 뒤, 코사인 유사도 기반 벡터 검색으로 후보 도서를 추출합니다.
3단계 RAG 파이프라인
- 의도 분류 (1차 LLM) — Gemini Flash에 Function Calling 도구(
search_books)를 등록하여, 사용자의 발화가 실제 도서 검색 요청인지 단순 대화인지를 판단합니다. 단순 인사나 모호한 표현에는 꼬리 질문으로 대화를 이어가고, 구체적 독서 의도가 감지될 때만 검색 쿼리를 생성합니다.
- 벡터 검색 (pgvector) — 생성된 검색 쿼리를 768차원으로 임베딩하고 L2 정규화한 뒤,
match_books RPC 함수를 호출하여 코사인 유사도 상위 후보 도서를 추출합니다. 유사도 임계값(AI_SIMILARITY_THRESHOLD, 기본 0.35) 미만은 사전 필터링하고, 후보 풀 크기는 AI_CANDIDATE_POOL_SIZE로 조정합니다.
- RAG 합성 & 리랭킹 (2차 LLM) — 후보 도서 목록과 대화 맥락을 함께 넘겨, 사용자의 독자층·장르·분위기에 실제로 부합하는 도서만 엄선합니다. 최종적으로 전체 추천 서두 메시지와 책별 개별 추천 사유(
reason)를 JSON 구조로 생성하여 반환합니다.
사용자 메시지
│
▼
┌──────────────────────────────────────────────┐
│ 1차 LLM Agent — 의도 분류 │
│ Gemini Flash + Function Calling │
│ search_books 도구 호출 여부 판단 │
└──────────────────┬───────────────────────────┘
│ searchQuery 생성
▼
┌──────────────────────────────────────────────┐
│ EmbeddingService │
│ gemini-embedding-001 → 768차원 벡터 생성 │
│ L2 정규화 │
└──────────────────┬───────────────────────────┘
│
▼
┌──────────────────────────────────────────────┐
│ pgvector 코사인 유사도 검색 │
│ match_books RPC (상위 후보 추출) │
│ 유사도 임계값 사전 필터링 + 중복 도서 제거 │
└──────────────────┬───────────────────────────┘
│
▼
┌──────────────────────────────────────────────┐
│ 2차 LLM — RAG 합성 & 리랭킹 │
│ 대화 맥락 + 후보 도서 → 최종 추천 엄선 │
│ 추천 서두 메시지 + 책별 개별 reason 생성 │
└──────────────────┬───────────────────────────┘
│
▼
SSE 스트리밍 (POST /search/ai/stream)
응답을 조각 단위로 브라우저에 즉시 전달
결과는 POST /search/ai(일괄 응답)와 POST /search/ai/stream(SSE 스트리밍) 두 가지로 제공됩니다. 웹의 커스텀 sse-chat-client가 스트림을 파싱해 챗 UI에 점진적으로 렌더링하도록 구현돼 있으나, 현재 그 챗 UI는 화면에 연결돼 있지 않습니다.
AI 도서 핵심 요약
도서 상세 페이지에서 요청하면 서버가 ISBN으로 DB의 제목·저자·소개·출판사를 읽어 Gemini에 전달하고, 단순 소개글과 차별화된 분석적 요약을 생성합니다. 요청 본문의 서지는 저장할 요약의 기준으로 쓰지 않습니다.
- summary — 책의 고유한 서사적 갈등과 핵심 사건을 담은 250~350자 완성형 문단
- keyPoints — 핵심 인사이트 3가지
- targetAudience — 이 책이 필요한 독자의 구체적 상황이나 고민
- keywords — 연관 태그 5개
생성된 요약은 ISBN 기준으로 ai_book_summaries 테이블에 캐싱하여 동일 도서에 대한 반복 API 호출을 방지합니다. 모든 AI 요청은 토큰 사용량, 응답 지연시간, 성공/실패 여부를 ai_request_logs 테이블에 별도로 기록합니다.
중고책 마켓플레이스 + 에스크로 결제
카카오 맵 API 및 지오코딩을 활용한 위치 기반 중고책 거래 플랫폼입니다. 시/도, 시/군/구 단위 필터링과 지도 기반 거래 장소 확인, PostgreSQL cube/earthdistance 확장과 GiST 인덱스를 이용한 반경·거리순 정렬을 지원합니다.
판매글은 거래 방식을 DIRECT_ONLY(직거래) / DELIVERY_ONLY(택배) / BOTH로 선택할 수 있고, 택배 거래에는 토스페이먼츠 에스크로 결제가 연결됩니다.
결제는 현재 운영에서 꺼져 있습니다. PG 심사 전이라 FEATURE_PAYMENT_ENABLED
플래그 뒤에 봉인돼 있고, orders 테이블은 0행입니다. 아래 상태 머신과 스케줄러는
구현돼 있으나 동작하지 않는 상태입니다. 직거래는 결제 없이 정상 동작합니다.
플래그를 켜기 전에 처리할 항목이
docs/book-data-migration-plan.md 9-c
「결제 활성화 전 점검 항목」에 있습니다.
판매자가 채팅방에서 구매자 선택
│
▼
AWAITING_PAYMENT ──(24h 미결제)──▶ CANCELLED
│ 구매자 결제 승인
▼
PAID ──(3일 미배송 자동 환불)──▶ CANCELLED
│ 판매자 운송장 등록
▼
SHIPPED ──(Delivery Tracker 폴링)──▶ DELIVERED
│
구매자 확정 / 2일 후 자동 확정
▼
CONFIRMED
▲
구매확정 거부 → DISPUTED ──────┘ (7일 미해결 시 자동 환불)
- 금액 위변조 방어 — 결제 승인 금액을 서버에서 판매글 가격과 대조 검증
- 동시성 제어 —
@VersionColumn 낙관적 잠금 + x-idempotency-key 멱등성 인터셉터
- 보상 트랜잭션 — 토스 승인 성공 후 DB 저장 실패 시 자동 환불
- 스케줄러 6종 — 미결제 만료, 미배송 환불, 자동 구매확정, 분쟁 만료 환불, 배송 상태 폴링(30분 주기), 만료 임박 알림(매일 자정)
- Feature Flag —
FEATURE_PAYMENT_ENABLED와 PaymentFeatureGuard로 PG 심사 전에도 결제 경로만 차단한 채 안전 배포
- 이메일 인증 게이트 —
EmailVerifiedGuard로 판매글 작성·거래 채팅·구매자 지정·결제를 인증 회원으로 제한
- 거래 후기 — 거래 완료(
TradeCompletion) 1건당 구매자·판매자가 각각 한 건씩 남기는 양방향 TradeReview, 프로필에 "거래 완료 N건 · 긍정 후기 N%" 신뢰 지표 노출
상세 설계는 docs/used-book-pay-implementation.md를 참고하세요.
실시간 채팅 & 알림
Socket.IO 게이트웨이 2종(채팅 / 알림)을 운영합니다.
- 채팅 — 판매글별 1:1 채팅방, 이미지 전송, 타이핑 인디케이터, 읽음 워터마크(참가자별
lastReadMessageId) 기반 안 읽은 개수 계산, 핸드셰이크 단계 JWT 검증(authenticateSocket)
- 거래 캐시 갱신 — 로컬 예약·취소·완료와 원격 거래 메시지가
@bookjeok/react-query의 invalidateTradeCaches를 함께 사용합니다. 거래 완료·후기 작성 자격까지 갱신해 상대방의 열린 채팅방에도 후기 진입점이 반영됩니다.
- 알림 — 리뷰 리액션·리뷰 댓글·댓글 좋아요에 더해 중고거래·직거래 13종, 문의 답변, 독서 기록 콩을 포함한 18종 알림 타입을 실시간 푸시. 소켓이 끊겼다 다시 붙으면 웹이 토스트 없이 목록·안 읽은 개수를 재조회해 끊긴 사이의 알림을 반영합니다. 도메인 서비스는
EventEmitter 이벤트만 발행하고, 리스너가 알림 생성·채팅 시스템 메시지·메일 발송을 비동기로 처리합니다.
- 알림 계약 — core의 단일
NotificationType·종류별 필수 metadata를 서버 생성 입구에서 검사하고, 웹 등록부가 18종의 문구·이동 경로·시스템 표시를 집중 관리합니다. 타입 검사와 전 종류·한영 계약 테스트로 누락을 검증하며 기존 DB enum·저장·실시간 전달 동작은 유지합니다.
- 메일 — Resend로 회원가입 이메일 인증 링크와 채팅방 개설 알림을 발송합니다(
chat.room_created 이벤트 → ChatMailListener, async: true). 사용자 문의·제보가 접수되면 운영자(FEEDBACK_NOTIFY_EMAIL)에게도 보냅니다(feedback.created → FeedbackNotifyListener). 도메인별 발송 정의와 공통 렌더링·수신 정책·전달 결과를 사용하며, 인증 재발송 실패는 503으로 전달합니다(가입·이메일 변경·이벤트 발송은 비동기 유지).
도서 리뷰 & 독서 기록
- 리뷰 — Tiptap 리치 텍스트 에디터(이미지 리사이즈·하이라이트·정렬·링크·색상 확장), 제목 기반 반응형 목차·현재 절 강조·본문 읽기 진행률, 읽기 미리보기, 별점, 태그, 공개/비공개, 리액션(공감/인사이트/응원) 집계, 조회수 인터셉터,
sanitize-html 기반 XSS 방어
- 독서 기록 — 월별/연도별 독서 캘린더, 완독 도서·한줄평·감상문 기록, 개인 독서 통계와 공개 설정. 검색 유입용 공개 소개 페이지
/reading-log(예시 달력)
- 독서 키재기 — 한 해에 읽은 책을 실제 두께로 쌓아 비교하고 그 장면을 이미지로 공유. 비교 대상은 두 가지: 쌓은 높이에 따라 다음 목표가 자동으로 올라오는 사물 사다리(각설탕부터 기린까지 13개)와, 내 키만 한 손그림 캐릭터 또는 작가 5명(카뮈·사르트르·쿤데라·울프·카프카) 캐리커처의 추정 키. 공개 프로필에서는 캐릭터 없이 쌓은 책만 보여 줌 (책 크기는 알라딘 종료 전 수확한
book_dimensions). 기록으로 사물·몸 부위·내 키를 넘으면 그 책이 쌓이는 장면을 띄우고, 넘은 사물은 한 해 단위 사물 도감에 그 책의 표지색으로 모임. 출시 후 30일간 접속 시 한 번 넘겨 보는 소개 모달로 알림(announcement), 검색 유입용 공개 소개 페이지 /reading-height
- 콩 — 공개 프로필 독서 키재기에서 남의 기록에 보내는 작은 리액션. 연필로 그린 까만 콩이 표지 위로 날아가 앉고, 누르면 팔다리를 꺼내 바둥거림. 한 기록에 한 알이며 거둬들이지 않음. 받은 수는 주인만 보고(독서기록 hero의 콩 종지, 달력·목록·하루 상세의 콩 표시), 받으면 그날 상세로 가는 알림이 옴
- 독서 라운지 —
/lounge에서 북적 책동산(공개 독서 기록 전체를 한 산으로 쌓은 높이와 다음 이정표), 다른 독자들의 실시간 독서 기록, 인기 도서, 활동 중인 독자, 같은 책을 읽는 독자를 조회
인사이트 대시보드
/insights에서 지역별 중고 거래 분포, 가격대 분포, 인기 태그 순위, 리액션 비율 등 서비스 전체의 독서·거래 데이터를 ApexCharts로 시각화합니다.
그 외
- 위시리스트 — 관심 도서 담기 및 내 위시리스트 관리
- 댓글 — 리뷰 댓글, 댓글 좋아요, 내가 쓴 댓글 모아보기
- 하단 dock — 채팅(안 읽음 배지)·기록 달력·독서 키재기·최근 본 책·음악·맨 위로를 화면 하단 한 줄에 모음. 누르면 페이지 이동 대신 패널(데스크톱 카드·모바일 바텀시트)이 열리고, 기록 달력·키재기 패널은 보기 전용으로 독서기록 페이지의 그날·그 보기로 이어짐. 모바일은 아래로 스크롤하거나 입력 중이면 숨기고, 다른 화면으로 옮기면 패널을 닫음(채팅은 유지)
- 배경음악 플레이어 — Zustand 전역 스토어 기반 뮤직 플레이어(재생목록·반복 모드). 재생 중에는 하단 dock에서 바로 엶
- 다국어(ko/en) —
next-intl 기반 [locale] 라우팅
- SEO — 공개 리뷰·판매글 전체 및 연결 도서의
sitemap.ts, robots.ts, manifest.ts, RSS 피드(/rss.xml), JSON-LD 구조화 데이터(독서 키재기 소개의 FAQ 포함), canonical/hreflang, 마켓·리뷰·라운지·독서 키재기 전용 정적 공유 카드. 로그인 뒤에 있는 독서 기록과 독서 키재기는 공개 소개 페이지 /reading-log·/reading-height로 검색에 노출(FAQ JSON-LD 포함)
- 분석·광고 — Vercel Analytics/Speed Insights, Google Analytics, Microsoft Clarity, Google AdSense
Tech Stack
Monorepo & Tooling
| 항목 | 기술 |
|---|
| 빌드 오케스트레이션 | Turborepo 2.7 (태스크 그래프 + 캐시) |
| 패키지 매니저 | pnpm 10 Workspaces (overrides로 React 19 / axios / TanStack Query 버전 단일화) |
| 언어 | TypeScript 5 (tsconfig.base.json 공유) |
| 린트·포맷 | ESLint 9 Flat Config, Prettier 3, eslint-plugin-simple-import-sort |
| 런타임 | Node.js 22.x |
Frontend — apps/web
| 항목 | 기술 |
|---|
| 프레임워크 | Next.js 15 (App Router, RSC, SSG/ISR, Route Handlers, Server Actions) · React 19 |
| 서버 상태 | TanStack Query v5 + @lukemorales/query-key-factory (쿼리 키 팩토리) |
| 클라이언트 상태 | Zustand v5 (음악 플레이어, 확인 모달, 최근 본 책 등) |
| 스타일링 | Tailwind CSS v4(@tailwindcss/postcss), tailwind-merge, class-variance-authority, tw-animate-css, @tailwindcss/typography |
| UI 컴포넌트 | Radix UI (shadcn/ui 패턴) + Lucide React |
| 애니메이션 | Framer Motion / motion, GSAP, Swiper |
| 에디터 | Tiptap 3 (StarterKit, Image + resize, Link, Highlight, TextAlign, Color, Underline, Placeholder, BubbleMenu) |
| 폼 & 검증 | React Hook Form + Zod 4 + @hookform/resolvers |
| 차트 | ApexCharts / react-apexcharts |
| 지도·주소 | react-kakao-maps-sdk, react-daum-postcode |
| 결제 | @tosspayments/tosspayments-sdk v2 |
| 실시간 | socket.io-client, 커스텀 SSE 클라이언트 |
| 다국어 | next-intl 4 (ko/en) |
| 테마 | next-themes (다크 모드) |
| 이미지 | browser-image-compression, @vercel/blob |
| 마크다운·정제 | react-markdown + remark-gfm, sanitize-html |
| 토스트·UX | sonner, react-intersection-observer |
| 계측 | @vercel/analytics, @vercel/speed-insights, GA4, Microsoft Clarity, AdSense |
| 테스트·문서 | Vitest 4 + Testing Library + jsdom, Storybook 8, @next/bundle-analyzer |
Backend — apps/server
| 항목 | 기술 |
|---|
| 프레임워크 | NestJS 11 (Express 플랫폼) |
| ORM / DB | TypeORM 0.3 · PostgreSQL(pgvector, cube, earthdistance) · pg |
| 트랜잭션 | nestjs-cls + @nestjs-cls/transactional (TypeORM 어댑터) — 선언적 CLS 트랜잭션 |
| 인증 | Passport (JWT / JWT-Refresh / Naver / Kakao), @nestjs/jwt, bcrypt |
| 실시간 | @nestjs/websockets + @nestjs/platform-socket.io, Socket.IO 4 |
| AI | @google/generative-ai (Gemini Flash, gemini-embedding-001) |
| 캐싱 | @nestjs/cache-manager + cache-manager 7 위에 자체 SmartCache 레이어 |
| 스케줄링 | @nestjs/schedule (Cron) |
| 이벤트 | @nestjs/event-emitter (도메인 이벤트 · 탈퇴 정리 · 알림 팬아웃) |
| 검증 | class-validator, class-transformer, 전역 ValidationPipe(whitelist) |
| 보안 | helmet, @nestjs/throttler, cookie-parser, CORS 오리진 화이트리스트 |
| 성능 | compression, TypeORM 커넥션 풀(max 40) |
| 외부 통신 | @nestjs/axios (토스페이먼츠, 배송 추적) |
| 메일 | Resend |
| 스토리지 | @vercel/blob |
| API 문서 | @nestjs/swagger — /api에서 OpenAPI 문서 제공 |
| 헬스체크 | @nestjs/terminus — GET /health |
| 테스트 | Jest 29 + ts-jest, Supertest |
Infrastructure
| 항목 | 기술 |
|---|
| 프론트엔드 호스팅 | Vercel (ISR + On-Demand Revalidation) |
| 백엔드 호스팅 | Azure Container Apps + Azure Container Registry (Docker) |
| 데이터베이스 | Supabase PostgreSQL |
| CI | GitHub Actions (lint → test → build), GitLab CI (Docker 이미지 빌드/푸시) |
| CD | GitHub Actions → ACR 이미지 푸시 → Container Apps 배포 |
| 로컬 개발 | Docker Compose (PostgreSQL + pgvector) |
핵심 엔지니어링 결정
1. Contract-First 모노레포
새 기능은 항상 packages/core의 인터페이스·API_PATHS·쿼리 키부터 정의하고, 서버 DTO가 그 인터페이스를 implements합니다. 프론트와 백엔드가 같은 타입 정의를 컴파일 타임에 공유하므로 API 계약이 깨지면 빌드가 실패합니다. 의존성은 core → api-client → react-query → web/admin 단방향이며, 역방향 import와 앱 간 직접 import를 금지합니다.
2. SmartCache — 프리픽스 기반 선언적 캐시 무효화
@SmartCache({ prefix, ttl, keyStrategy }) 데코레이터로 응답을 캐싱하고, @InvalidateCache(prefix)로 쓰기 시점에 해당 프리픽스의 키를 한 번에 제거합니다. SmartCacheStore가 prefix→key 집합을 인메모리로 관리해 cache-manager가 제공하지 않는 "프리픽스 단위 삭제"를 구현했습니다. keyStrategy로 ip / user / ip+user / global 스코프를 선택합니다.
3. 멱등성 인터셉터
x-idempotency-key 헤더가 있는 요청은 캐시에 processing 락을 걸어 처리 중인 중복 요청을 409로 차단하고, 완료된 요청은 최초 응답을 재생합니다. 같은 키의 동시 요청도 핸들러를 한 번만 실행합니다(단일 인스턴스 기준). 결제처럼 재시도가 곧 이중 과금이 되는 경로와 댓글·리뷰·판매글·독서기록·직거래 등록을 방어합니다.
4. 표준화된 에러 체계
ERROR_CODES에 도메인별 코드(AUTH_xxx, SALE_xxx, ORDER_xxx …)와 메시지를 등록하고 서비스는 BusinessException만 던집니다. GlobalExceptionFilter가 모든 예외를 동일한 JSON 형태로 변환하고 TransformInterceptor가 성공 응답 봉투를 통일해, 프론트는 단일 에러 핸들러로 대응합니다.
5. 이벤트 기반 회원 탈퇴 정리
탈퇴 시 user.withdrawn 이벤트 하나만 발행하면 chat · comment · feedback · llm · notification · reading-log · review · used-book-sale · user · activity 10개 리스너가 각자의 데이터를 정리합니다. 도메인 모듈 간 직접 의존 없이 정리 로직을 확장할 수 있습니다.
이벤트 이름·payload는 서버의 각 features/*/events/가 소유하고 발행자와 리스너가 같은 계약을
사용합니다. emitDomainEvent·emitDomainEventAsync·@OnDomainEvent가 필수 payload와 구독 타입을
검사하며 주문의 커밋 후 대기 이벤트도 이름별 payload를 연결합니다. 현재 26개 이름·리스너 옵션·오류
전파를 계약 테스트로 확인합니다. 탈퇴는 트랜잭션 안에서 emitAsync를 기다리고 거래 상태 이벤트는
기존 커밋 후 순서를 유지합니다. 상세는 서버 공용 문서에 있습니다.
6. 선언적 트랜잭션 (CLS)
@nestjs-cls/transactional로 QueryRunner를 서비스 시그니처에 끌고 다니지 않고 트랜잭션을 전파합니다. 채팅방 + 참가자 생성, 주문 생성 + 판매 상태 변경, 거래 완료 기록, 리뷰 본문 + 태그 + 카운터, 회원 탈퇴 정리처럼 복수 엔티티가 얽힌 작업에 적용됩니다.
7. 활동 로그 인터셉터
@TrackActivity(type)가 붙은 엔드포인트 호출을 ActivityTrackingInterceptor가 가로채 activity_logs에 비동기 적재합니다. 로그인·검색·조회·작성 등 30여 개 지점이 계측되어 있으며, 현재는 감사(audit) 로그 용도로 적재만 하고 조회하는 기능은 없습니다.
8. 거리 검색: PostGIS 대신 cube + earthdistance
전체 GIS 스택이 필요하지 않아 PostgreSQL 기본 확장인 cube/earthdistance만 활성화하고, ll_to_earth(latitude, longitude) GiST 인덱스를 모듈 부팅 시 CREATE INDEX IF NOT EXISTS로 보장합니다. 반경 필터(radius)와 거리순 정렬을 인덱스로 처리합니다.
9. 커서 페이지네이션
판매글 검색은 offset이 아닌 Base64 커서를 사용해, 목록이 실시간으로 바뀌어도 중복·누락 없이 무한 스크롤됩니다.
10. 읽음 워터마크
채팅 읽음 처리를 메시지별 read_receipts 테이블에서 참가자별 lastReadMessageId 워터마크 방식으로 전환해, 읽음 레코드가 메시지 수에 비례해 증가하던 구조를 제거했습니다. 적용 이력은 docs/manual-ddl-log.md에 있습니다.
11. ISR + On-Demand Revalidation
목록·상세 페이지를 ISR로 정적 서빙합니다. 판매글 수정·거래 상태 변경, 리뷰 수정, 회원 탈퇴처럼 상세 HTML이 바로 틀려지는 쓰기는 웹 뮤테이션이 서버 액션(shared/actions/revalidate.ts)으로 해당 경로를 즉시 비우고, 목록·집계는 시간 기반 revalidate에 맡깁니다. 시크릿 토큰 기반 웹훅(/api/revalidate)도 있으나 호출하는 관리자 포털이 미배포라 지금은 쓰이지 않습니다. 규칙은 apps/web/docs/CACHING.md에 있습니다.
12. Feature Flag 기반 안전 배포
FEATURE_PAYMENT_ENABLED / NEXT_PUBLIC_FEATURE_PAYMENT_ENABLED와 PaymentFeatureGuard로, PG 심사 완료 전에도 결제 코드를 운영에 배포한 채 진입만 차단합니다.
외부 서비스 연동
| 서비스 | 용도 | 사용 위치 |
|---|
| 네이버 / 카카오 OAuth | 소셜 로그인 | server: auth (Passport 전략) |
| 네이버 IndexNow | 공개 리뷰 변경 URL 알림 (운영 플래그 활성화 시, 색인 보장 없음) | server: review, web: /api/revalidate |
| Google Gemini | 도서 요약. RAG 추천의 의도 분류·합성·임베딩(웹 UI 비노출) | server: llm, search |
| 토스페이먼츠 | 에스크로 결제 승인·취소·웹훅 | server: order, web: order |
| Delivery Tracker | 택배 배송 상태 조회 및 30분 주기 폴링 | server: order |
| Resend | 인증 링크·채팅 개설 알림·운영자 문의 알림 메일 | server: shared/mail |
| Vercel Blob | 리뷰·판매글·프로필 이미지 업로드/삭제 | web: /api/upload, server |
| Vercel Image Optimization | 홈 메인 슬라이더의 R2 표지를 화면 크기에 맞게 변환·캐시 | web: book-slider |
| 카카오 맵 SDK | 거래 위치 지도, 지오코딩 | web: shared/components/map |
| 다음 우편번호 | 배송지 주소 입력 | web: order/address-input |
| GA4 · Microsoft Clarity · AdSense | 트래픽 분석, 행동 분석, 광고 | web: shared/components/analytics, ads |
| 카카오 책 검색 API | 신간 적재 (운영자 도구 전용, 런타임 경로 아님) | tools/book-ingest |
| 알라딘 Open API | 신간 적재 (운영자 도구 전용, 2026-10-30 종료 시 제거) | tools/book-ingest |
| Cloudflare R2 | 도서 표지 원본 저장·서빙 (cdn.bookjeok.com) | tools/book-ingest(업로드), web(표시) |
도서 데이터는 런타임에 외부 API를 쓰지 않습니다. 과거에는 네이버 도서 API와
알라딘 Open API를 연동했으나, 알라딘 종료(2026-10-30)에 대비해 2026-09-08에
공급처 체인에서 제거했습니다. 지금은 검색·상세 모두 자체 DB 단독이며, 외부
공급처를 런타임 경로에 두지 않는 것이 방침입니다. 신규 도서는 서버가 아니라
운영자가 필요할 때 로컬에서 돌리는 적재 도구(tools/book-ingest,
카카오 책 검색 API를 입구로 사용, 10/30까지는 알라딘도 선택 가능)로 확보합니다. 표지도 2026-09-09 컷오버로
Cloudflare R2(cdn.bookjeok.com)에서 나갑니다. 홈 메인 슬라이더는 Vercel 이미지
최적화를 거쳐 화면 크기에 맞는 표지를 받습니다. 경위와 남은 정리 항목은
docs/book-data-migration-plan.md에 있습니다.
Shared Packages
Monorepo packages/ 디렉토리에 도메인 모델과 통신 클라이언트를 집약하여 플랫폼 전반의 코드 재사용성을 극대화했습니다.
| Package | Role |
|---|
@bookjeok/core | 데이터 모델 인터페이스, 서버와 공유하는 enum·입력 제한·에러 코드, API 경로 상수(API_PATHS), 포맷터, 쿼리 키 팩토리 (브라우저·Node 전용 API 없음) |
@bookjeok/api-client | 빈 Axios 인스턴스(publicApiClient, privateApiClient)와 API 호출 모듈. baseURL·응답 봉투·토큰 갱신 인터셉터는 웹(shared/libs/axios.ts)이 붙임 |
@bookjeok/react-query | TanStack Query 쿼리/뮤테이션 훅과 캐시 무효화 규칙 |
Project Structure
bookjeok/
├── apps/
│ ├── web/ # Next.js 15 사용자 웹 프론트엔드
│ │ ├── src/app/ # App Router ([locale] 다국어, route handlers, sitemap/robots/rss)
│ │ ├── src/views/ # 페이지 뷰 조립 레이어
│ │ ├── src/features/ # 도메인 기능 (announcement, auth, book, book-sale, chat, comment,
│ │ │ # confirm, feedback, insights, intro, music, notification,
│ │ │ # order, reading-log, review, trade, user)
│ │ ├── src/shared/ # 공용 컴포넌트·프로바이더·훅·유틸·i18n·analytics
│ │ ├── src/layouts/ # DefaultLayout, Header, Navigation, BottomDock
│ │ ├── docs/ARCHITECTURE.md # 컴포넌트 구조 & i18n 가이드
│ │ └── docs/CACHING.md # ISR · 쿼리 캐시 구조와 재검증 규칙
│ │
│ ├── admin/ # Next.js 15 관리자 포털 (초기 세팅만 된 미배포 앱)
│ │ ├── src/app/dashboard/ # 운영 통계, 매물/리뷰 검수, ISR 캐시 제어
│ │ └── src/stores/ # 관리자 인증 상태
│ │
│ └── server/ # NestJS 11 백엔드 API
│ ├── src/app/ # 루트 모듈 (TypeORM, CLS, Throttler, Cache, Schedule)
│ ├── src/features/ # 18개 도메인 모듈
│ │ ├── auth/ user/ book/ review/ comment/ reading-log/ wishlist/
│ │ ├── used-book-sale/ order/ trade/ chat/ notification/
│ │ ├── llm/ search/ search-keyword/
│ │ └── insights/ feedback/ health/
│ └── src/shared/ # 횡단 관심사
│ ├── activity/ # 활동 로그 (데코레이터 + 인터셉터)
│ ├── cache/ # SmartCache (캐싱/무효화 데코레이터)
│ ├── exceptions/ # BusinessException, ERROR_CODES
│ ├── filters/ # GlobalExceptionFilter
│ ├── interceptors/ # Transform, Logging, Idempotency, ViewCount
│ └── mail/ # 공통 메일 렌더링·수신 정책·Resend 전달
│
├── packages/
│ ├── core/ # @bookjeok/core
│ ├── api-client/ # @bookjeok/api-client
│ └── react-query/ # @bookjeok/react-query
│
├── tools/
│ └── book-ingest/ # 신간 적재 운영자 도구 (로컬 실행, 배포 안 함)
│
├── docs/ # 운영·설계 문서
│ ├── used-book-pay-implementation.md
│ ├── book-data-migration-plan.md
│ ├── manual-ddl-log.md
│ ├── seo-audit-2026-09-19.md
│ ├── review-search-audit-2026-10-07.md
│ ├── review-search-official-guidance-2026-10-07.md
│ ├── vercel-usage-audit-2026-09-20.md
│ └── ddl/ # 운영에 적용한 DDL 원본
├── .agents/rules/ # 코드베이스 컨벤션 (개발자 & AI 에이전트 공용)
├── .github/workflows/ # CI, Azure Container Apps 배포
├── docker/postgres/init/ # 로컬 DB 초기화 스크립트 (확장 설치)
├── docker-compose.yml # 로컬 PostgreSQL + pgvector
├── turbo.json
└── pnpm-workspace.yaml
Security
- 1회용 인증 티켓 (Social Login Ticket Exchange) — 소셜 로그인 리다이렉트 시 JWT를 URL에 노출하지 않고 60초 일회용 티켓을 발급하여
POST /auth/exchange로 안전하게 교환
- JWT Silent Refresh — Axios 인터셉터를 통한 Access Token 만료 감지 및 자동 갱신
tokenVersion 기반 즉시 무효화 — 로그아웃 또는 비정상 세션 감지 시 user.tokenVersion을 증가시켜 Refresh Token을 즉시 무효화- 이메일 인증 게이트 —
EmailVerifiedGuard로 중고거래 진입 경로를 인증 회원으로 제한(사기·어뷰징 방어)
- 소켓 인증 —
shared/websocket/authenticate-socket.ts가 WebSocket 핸드셰이크 단계에서 JWT를 검증하고 탈퇴 계정을 차단. 방 참여(joinRooms)는 별도로 참여자 여부를 확인
- Rate Limiting — 전역 Throttler(60초 / 120회) 위에 로그인·회원가입·티켓 교환·AI 검색은 개별 제한 적용
- 입력 검증 — 전역
ValidationPipe({ whitelist, forbidNonWhitelisted })로 정의되지 않은 필드 차단
- XSS 방어 — 리뷰 본문은
sanitize-html로 정제 후 렌더링
- HTTP 헤더 보안 —
helmet, CORS 오리진 화이트리스트, credentials: true 쿠키 정책
- 결제 무결성 — 서버 측 금액 검증, 낙관적 잠금, 멱등성 키, 승인 후 저장 실패 시 보상 환불
- AI 사용 로깅 — 모든 AI 요청의 토큰 사용량, 지연시간, 성공/실패 기록
Testing & Quality
| 항목 | 현황 |
|---|
| 서버 단위 테스트 | Jest — 55개 spec (주문 서비스·스케줄러·토스 연동·채팅 게이트웨이·가드·도메인 이벤트 계약 등) |
| 웹 테스트 | Vitest 4 + Testing Library — 120개 테스트 파일 (결제 플로우, 주문 상세, 배송/분쟁 모달, 거래 후기 등) |
| 컴포넌트 문서 | Storybook 8 — 40개 스토리 파일 (사이드바는 src 폴더 구조를 따름) |
| 타입 안전성 | tsc --noEmit 게이트 (server / web / admin) |
| 정적 분석 | ESLint 9 Flat Config + Prettier. 패키지 의존 방향·서버 alias import·BusinessException·웹 PATHS 사용을 규칙으로 검사 (.agents/rules/04-checklist.md) |
| CI | GitHub Actions에서 pnpm turbo lint test → pnpm turbo build. lint는 수정 없이 검사만(고칠 때는 pnpm lint:fix) |
pnpm lint
pnpm test
pnpm build
Deployment
| 대상 | 방식 |
|---|
| apps/web | Vercel — ISR 정적 재검증 + /api/revalidate 온디맨드 갱신 |
| apps/server | GitHub Actions가 같은 커밋에서 서버와 의존 패키지(core)를 lint·test·build로 검증한 뒤(verify job), apps/server/Dockerfile을 모노레포 루트 컨텍스트로 빌드 → Azure Container Registry 푸시 → Azure Container Apps 배포. main/develop push 중 서버 이미지 입력(apps/server·packages/core·공용 tsconfig/tsup/turbo 설정·lockfile)이 바뀐 경우 또는 수동 트리거 |
| DB | Supabase PostgreSQL. 운영은 synchronize: false이며 마이그레이션 도구 없이 DDL을 수동 적용합니다 — 반드시 docs/manual-ddl-log.md에 기록 |
| 컨테이너 이미지 | GitLab CI에서도 web/server 이미지를 빌드해 GitLab Container Registry에 푸시 |
서버는 단일 인스턴스 전제로 캐시·멱등성 키·채팅방 생성 합치기·Socket.IO room·이벤트를 프로세스 메모리에 둡니다. replica를 늘리기 전에 서버 공용 문서의 「다중 인스턴스 전제」를 확인하세요.
서버는 Azure 환경에서 Supabase IPv6 ENETUNREACH를 피하기 위해 main.ts에서 dns.setDefaultResultOrder("ipv4first")를 강제합니다.
Getting Started
사전 요구사항
- Node.js 22.x
- pnpm 10.x
- Docker (로컬 PostgreSQL + pgvector 구동용)
# 1. 의존성 설치
pnpm install
# 2. 환경 변수 준비 (루트에 .env 생성)
cp .env.example .env
# 3. 로컬 DB 기동 (PostgreSQL + pgvector)
pnpm db:up
# 4. 공용 패키지 빌드 (의존 순서 준수)
pnpm --filter @bookjeok/core build
pnpm --filter @bookjeok/api-client build
pnpm --filter @bookjeok/react-query build
# 5. 개발 서버 실행
pnpm dev:web # 웹 + 서버 + 웹·서버가 의존하는 공용 패키지 watch (웹 http://localhost:3000)
pnpm dev:server # 서버 + core watch (http://localhost:8000)
pnpm dev # 전체 워크스페이스
# dev:web·dev:server는 turbo의 `패키지...` 필터로 의존 패키지를 함께 띄웁니다.
# web은 api-client·react-query를 소스가 아니라 dist로 소비하므로 이 watch가 있어야
# 공용 API·훅 수정이 재시작 없이 반영됩니다. 4번의 초기 빌드는 첫 실행 때 dist가
# 아직 없어 웹이 먼저 실패하는 것을 막습니다.
# 6. 부가 도구
pnpm storybook # Storybook (http://localhost:6006)
pnpm ingest serve # 신간 적재 도구 화면 (http://127.0.0.1:4700, 운영 DB 연결 — tools/book-ingest 참고)
pnpm db:logs # DB 로그
pnpm db:down # DB 중지
API 문서는 서버 기동 후 http://localhost:8000/api (Swagger UI)에서 확인합니다.
검증
pnpm --filter @bookjeok/server exec tsc --noEmit
pnpm --filter @bookjeok/web exec tsc --noEmit
pnpm --filter @bookjeok/admin exec tsc --noEmit
pnpm test
환경 변수
전체 목록과 설명은 .env.example에 있습니다. 주요 항목:
| 변수 | 필수 | 설명 |
|---|
DATABASE_URL | ✅ | PostgreSQL 연결 문자열 |
JWT_SECRET / JWT_REFRESH_SECRET | ✅ | 액세스/리프레시 토큰 서명 키 |
CLIENT_DOMAIN | ✅ | CORS 및 소셜 로그인 리다이렉트 대상 |
NAVER_CLIENT_ID / _SECRET / _CALLBACK_URL | ✅ | 네이버 소셜 로그인 (도서 검색에는 쓰지 않음) |
KAKAO_CLIENT_ID / _SECRET / _CALLBACK_URL | ✅ | 카카오 로그인 |
ALADIN_TTB_KEY | | 서버는 쓰지 않음. 적재 도구의 알라딘 공급처 전용(10/30까지) — 지우지 말 것 |
GEMINI_API_KEY | ✅ | Google Gemini |
GEMINI_MODEL_NAME | | AI 도서 추천(search, 웹 UI 비노출)의 Gemini 모델명. 기본 gemini-3.1-flash-lite, AI 요약(llm)은 상수 사용 |
AI_SIMILARITY_THRESHOLD / AI_CANDIDATE_POOL_SIZE | | RAG 벡터 검색 튜닝 (기본 0.35 / 30, 웹 UI 비노출) |
RESEND_API_KEY / RESEND_FROM_EMAIL | ✅ | 이메일 인증·알림 발송 |
FEEDBACK_NOTIFY_EMAIL | | 사용자 문의·제보 알림을 받을 운영자 메일. 비우면 DB에만 쌓임 |
BLOB_READ_WRITE_TOKEN | ✅ | Vercel Blob 이미지 업로드 |
TOSS_PAYMENTS_SECRET_KEY / _CLIENT_KEY | | 토스페이먼츠 에스크로 |
DELIVERY_TRACKER_BASE_URL | | 배송 추적 API 엔드포인트 |
FEATURE_PAYMENT_ENABLED | | 서버 측 결제 기능 플래그 |
NEXT_PUBLIC_API_URL | ✅ | 웹에서 바라볼 백엔드 주소 |
NEXT_PUBLIC_KAKAO_APP_KEY | ✅ |
문서 인덱스
앱 · 패키지
도메인 기능 문서
모든 기능 폴더에 개별 README가 있습니다.
설계 · 운영
SEO·SNS 공유 점검 결과: 2026-09-19 SEO 감사 — 주요 페이지 운영 응답, 구조화 데이터 결함, 검색 발견성과 공유 개선 사항.
도서 리뷰 검색 노출: 2026-10-07 리뷰 점검 · 공식 가이드 조사. 공개 리뷰의 검색·OG 제목에 도서명을 보충하고 RSS에 정제한 HTML 본문 전체를 제공합니다. 공개 리뷰 생성·수정·삭제 후 서버 상세 재검증과 네이버 IndexNow 알림을 구현했으며 활성화·배포 순서는 서버 리뷰 문서에 있습니다. 서버 리뷰 링크·페이지네이션은 후속 과제입니다.
Vercel 사용량 점검: 2026-09-20 비용 진단 — 운영 캐시 반복 측정, 배포별 ISR 재생성, 사이트맵·404 렌더 및 응답 크기 분석.
License
This project is licensed under the MIT License.
