[docs] 책(Book) 도메인 PRD 역설계 (specs/003-book-domain)

[buzz0331]

Summary

운영 중인 책 도메인을 사용자 관점에서 역설계해 PRD로 정형화한 세 번째 산출물.
신규 기능 정의가 아닌 기존 구현을 "이래야 한다"로 문서화하는 작업.

Depends on #353 (Spec Kit 셋업 + 헌법 v1.0.0 비준). #353 머지 후 base를 develop으로 retarget 예정.
피드 PRD(#354)·팔로우 PRD(#355)와는 독립적으로 리뷰·머지 가능.

무엇이 추가되는가

파일	내용
specs/003-book-domain/spec.md	책 도메인 PRD (한국어, 226 줄)
specs/003-book-domain/checklists/requirements.md	사양 품질 체크리스트 (15/15 통과)

PRD 구성

• User Stories 5건 (우선순위)
  • P1: 책 검색하기 (키워드 + 페이지, 확정 시 최근 검색어 기록)
  • P1: 책 상세 정보 보기 (ISBN, 사용자 컨텍스트 포함)
  • P1: 책 저장하고 다시 찾아보기 (토글 정합성)
  • P2: 방 생성을 위한 책 선택 (SAVED / JOINING)
  • P2: 인기 검색 책과 모집중인 방 발견
• Functional Requirements 18건 — 검색·발견 / 상세 / 저장 / 다른 도메인 입력 제공 / 데이터 정리 / 외부 데이터 안정성
• Success Criteria 7건 — 기술 비종속, 사용자 관찰 가능 측정치
• Edge Cases 8건 — 잘못된 ISBN·페이지 범위·외부 일시 장애·신규 책 자동 등록·정리 안전 조건 등

핵심 결정

인기 검색 책 산정 기준 (FR-004)

신호	책 상세 조회 호출 횟수 (키워드 검색 횟수가 아님)
윈도우	전날(직전 1일)
개인화	없음 (모든 사용자 동일 결과)
갱신	일 단위 경계(자정) 이후 첫 호출부터 반영

⚠️ 화면 라벨이 "인기 검색 책"이지만 신호는 "상세 조회"라 사용자 오해 여지가 있음. 라벨 검토는 별도 백로그.

외부 도서 데이터 소스의 벤더 중립화 (FR-008, Assumptions)

현재 Naver Book API를 1차 공급원으로 사용하지만 PRD에는 명시하지 않음. "외부 도서 데이터 소스"로 추상화. 벤더 교체는 본 PRD 변경 트리거가 아님.

외부 데이터 일시 장애 시 UX (FR-018)

팔로우 PRD(#355)의 재시도 정책과 동일하게:

• 사용자에게는 자원/외부 원인을 비노출
• "잠시 후 다시 시도해주세요" 일반 안내만 반환
• 내부 식별을 위한 시스템 차원의 오류 코드·로그는 유지

데이터 정리의 안전 조건 (FR-016, FR-017)

`BookCleanUpService`가 어떤 사용자·피드·방도 더 이상 참조하지 않는 책을 정리하지만, 현재 참조 중인 책 데이터가 사라져서는 안 됨.

범위 외 (의도적)

• 방 도메인 — 책별 모집중인 방 목록의 출처. 별도 PRD에서 정의
• 피드 도메인 — 책별 피드 목록은 피드 PRD([docs] 피드(Feed) 도메인 PRD 역설계 (specs/001-feed-features) #354) 따름
• 최근 검색어 — 별도 검색 이력 도메인 PRD가 저장·만료·조회 정책 정의. 본 PRD는 "`isFinalized=true`인 검색 성공 시 기록"만 명시
• 외부 메타데이터 갱신 정책 — 외부 데이터가 갱신되었을 때 시스템이 따라가는 빈도·정책은 별도 결정 사항
• 벤더 의존(Naver API) — 추상화 계층("외부 도서 데이터 소스")으로 회피

누적 PRD 진행 상황

#	도메인	PR
001	피드(Feed)	#354
002	팔로우(Follow)	#355
003	책(Book)	본 PR

Test plan

• PRD 본문이 비즈니스 어휘로 읽히는지 (벤더·구현 디테일 누출 점검)
• 인기 검색 책 산정 기준(전날 상세 조회 호출 수)이 현재 구현과 일치하는지
• 화면 라벨 "인기 검색 책"의 오해 여지에 대한 팀 의견
• 데이터 정리의 안전 조건(FR-016, FR-017)이 현재 `BookCleanUpService` 동작과 일치하는지
• 외부 도서 데이터 소스 일시 장애 UX 정책(FR-018)이 팔로우 PRD([docs] 팔로우(Follow) 도메인 PRD 역설계 (specs/002-follow-domain) #355)와 일관된지
• 누락된 시나리오(예: 책 신고, 책 메타 수정 요청, 책별 통계 등)가 있는지 검토

[coderabbitai]

Warning

Rate limit exceeded

@buzz0331 has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 24 minutes and 58 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: c6435a49-d46c-4dc0-819a-c9a6c178259f

📥 Commits

Reviewing files that changed from the base of the PR and between 2277cb3 and c4c008b.

📒 Files selected for processing (2)

• specs/003-book-domain/checklists/requirements.md
• specs/003-book-domain/spec.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 003-book-domain

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}