Blueprint

가상의 독서 목록 앱 별책. 책장 선택 → 읽기 상태 필터 → 책 상세 확인. 화면 흐름·결정·질문·API 계약을 한 문서에 담는 작성 예시. 등장하는 서비스·책·인물·식별자·API·결정은 모두 이 문서를 위한 가상 내용.

Overview

Area	Purpose	Reference
책장 목록	읽을 책이 담긴 책장 선택	Shelf list
조건 설정	읽기 상태로 책 목록 좁힘	Conditions
책 목록	제목·저자·읽기 상태 비교	Book list
미결 사항	예시 설계의 남은 판단	Questions

Screen

Flow

책장을 선택하면 해당 책 목록 조회. 읽기 상태를 적용하면 같은 책장의 목록 갱신. 책 제목을 누르면 그 책의 상세 화면으로 이동.

Shelf list

왼쪽 목록. 책장 이름과 책 수. 예시 책장: 주말 읽기, 다음에 읽을 책.

Value	Display
`shelfId`	선택 식별자
`name`	책장 이름
`bookCount`	`N 권`

구현 상세 · 선택과 조회

Selection state

선택 key와 요청 path는 응답의 shelfId 사용 · D1
책장 이름을 바꿔도 같은 식별자 유지
예시 주소: /shelves/weekend?status=reading

GET /api/shelves/weekend/books?status=reading

Conditions

목록 머리의 읽기 상태 필터. 편집 중인 draft와 목록에 적용된 조건 구분. 후보는 all, planned, reading, finished. all은 query에서 상태 생략.

State	Use
Draft	편집 중인 읽기 상태
Applied	책 목록의 요청 조건
Selection	선택한 책장의 식별자

D2: 적용 버튼에서만 목록 갱신. 취소하면 draft 폐기. 편집 중의 선택으로 현재 목록이 계속 바뀌는 현상 방지.

Book list

선택한 책장의 책 목록. 제목·저자·읽기 상태 표시. 아래 책과 저자는 실제 도서 정보를 사용하지 않은 예시 데이터.

ID	Title	Author	Status
`book-101`	비 오는 골목의 지도	윤가람	`reading`
`book-102`	느린 우체국의 편지	서누리	`planned`

구현 상세 · 요청과 표시

Table contract

path: 선택한 shelfId
query: 선택 상태의 status · 전체 보기에서는 생략
제목순 표시 · 제목이 같으면 bookId순
빈 목록과 조회 오류는 별도 상태로 표시

Decisions

ID	Status	Decision	Reason
D1	Decided	이름 대신 `shelfId`로 책장 참조	이름 변경 후에도 링크 유지
D2	Decided	적용 버튼에서만 조건 반영	편집 중인 입력과 목록 구분

결정에는 식별자·상태·선택 이유. 미결 사항은 Questions에서 추적. 이 표의 상태도 가상 앱의 설계 예시. 라이브러리 구현의 진행 상태와 무관.

Questions

ID	Topic	Needs answer
Q1	초기 선택	첫 책장을 자동 선택할지
Q2	완료한 책	별도 보관함으로 옮길지, 상태만 바꿀지

답이 정해지면 같은 항목에 이유를 기록. 결정과 남은 질문을 나눠 적는 방법의 예시.

Structure

API

아래 path와 응답은 가상 계약. 실제 서버와 연결된 API가 아님.

Endpoint	Caller	Use
`GET /api/shelves`	책장 목록	책장 이름·건수 조회
`GET /api/shelves/{shelfId}/books`	책 목록	책장의 책 조회
`GET /api/books/{bookId}`	책 상세	선택한 책의 상세

구현 상세 · 응답 필드

Response fields

{
    "shelfId": "weekend",
    "books": [
        {"bookId": "book-101", "title": "비 오는 골목의 지도", "author": "윤가람", "status": "reading"}
    ]
}

Checks

선택 책장과 책 목록 요청의 path 일치
draft 편집과 적용된 조회 조건의 구분
목록의 로딩·빈 결과·오류 표시
책장 이름을 바꿔도 같은 링크 사용
결정한 내용과 미결 질문 구분

Selection state, Table contract, Response fields는 접힌 구현 상세의 직접 링크.

Writing this example

화면 흐름은 Mermaid, 값과 계약은 표·코드, 보충 설명은 Note, 구현 상세는 Details로 작성. 소스는 이 페이지의 blueprint.md. 가상 내용은 자신의 프로젝트 설명으로 교체해 사용.

현재 type: blueprint는 일반 문서와 같은 페이지 표현. 전용 정보 구조와 표현은 Roadmap의 다음 단계.