다음 책장

예약 도서의 예상 이용 가능 구간을 안내하고, 기다리는 동안 지금 빌릴 수 있는 대체도서를 연결하는 도서관 데이터 서비스

2026년 07월 진행중

JavaScript Node.js Cloudflare Workers Open API Data Visualization GitHub Actions

라이브 데모 GitHub 보기

다음 책장

Project Title: 기다리는 시간을 알려주고, 기다리는 동안 읽을 책을 연결하는 도서관 서비스

예약 순번을 막연한 숫자로 남겨두지 않고 예상 이용 가능 구간과 근거로 설명하며, 기다림이 길 때는 가까운 도서관에서 바로 빌릴 수 있는 비슷한 책을 제안합니다.

공개 서비스 바로가기

프로젝트의 탄생

도서관에서 인기 도서를 예약하면 현재 대기 순번이나 반납 예정일은 확인할 수 있지만, 이용자가 가장 궁금한 “내 차례는 언제쯤 오는가?”에 답하기는 어렵습니다. 복본 수, 앞선 예약자의 수령 여부, 연장과 지연 반납, 휴관일에 따라 실제 이용 시점이 계속 달라지기 때문입니다. 기다림을 포기한 뒤 비슷한 책을 다시 찾는 과정도 이용자에게는 또 다른 부담입니다.

다음 책장은 이 문제를 예상 이용 가능 구간과 기다리는 동안 읽을 대체도서라는 두 가지 흐름으로 해결하기 위해 시작했습니다. 도서관 정보나루의 공개 데이터를 이용해 책과 소장 도서관, 대출 가능 여부, 연관 도서를 연결하고, 공개 API에 없는 예약 정보는 이용자가 해당 도서관에서 확인한 값을 직접 입력하도록 설계했습니다.

프로젝트의 중요한 원칙은 없는 데이터를 그럴듯한 수치로 만들지 않는 것입니다. 협력 도서관의 비식별 예약·반납 원자료를 확보하기 전까지는 정밀 예측이나 실제 정확도를 주장하지 않고, 재현 가능한 정책 기반 계산 결과와 데이터의 한계를 함께 보여줍니다.

Project Overview

목적:

예약 도서 이용자가 기다림의 길이와 불확실성을 이해하고, 예약 유지·다른 도서관 이용·대체도서 대출 중 자신에게 맞는 선택을 할 수 있도록 돕습니다. 사서에게는 정보나루의 실제 대출 급상승 데이터를 제공해 자관의 소장·예약 현황을 다시 확인할 후보를 찾도록 지원합니다.

핵심 구현 기능:

도서 검색과 상세정보: 제목으로 책을 검색하고 ISBN을 기준으로 판본, 저자, 출판사와 상세정보를 조회합니다.
소장 도서관과 대출 가능 여부: 선택한 ISBN을 소장한 참여 도서관을 찾고, 도서관별 소장 여부와 현재 대출 가능 상태를 확인합니다.
정책 기반 예상 대기 구간: 앞선 예약자 수, 복본 수, 대출 가능 복본, 대출 기간, 수령 기간, 반납 예정일과 휴관 요일을 입력해 중앙 예상일과 보수적 예상일을 계산합니다.
근거와 신뢰도 표시: 결과를 확정 날짜가 아닌 구간으로 제시하고, 입력 데이터의 충실도에 따라 높음·보통·낮음 신뢰도와 계산 근거를 함께 안내합니다.
대체도서 추천: 정보나루의 연관 도서 후보를 불러오고, 같은 주제나 저자이면서 지금 빌릴 수 있는 책을 우선 탐색할 수 있도록 연결합니다.
내 예약 책장: 관심 있는 책과 계산 결과를 브라우저에 저장해 다시 확인할 수 있습니다.
사서용 동향 화면: 가상의 예약자·복본·수요 압력 수치 대신 정보나루 hotTrend의 실제 전일·금일 순위와 상승폭을 보여줍니다.

User Flow

이용자가 제목이나 ISBN으로 책을 검색합니다.
책의 판본과 소장 도서관을 확인하고 이용할 도서관을 선택합니다.
정보나루 실데이터로 현재 소장·대출 가능 여부를 확인합니다.
대기 중이라면 도서관에서 확인한 예약 순번과 정책값을 계산기에 입력합니다.
예상 이용 가능 구간, 신뢰도, 달라질 수 있는 이유를 확인합니다.
기다림이 길면 연관 도서와 다른 소장 도서관을 찾아봅니다.
예약을 유지할 책과 대체도서를 내 책장에 보관합니다.

정확한 예약 상태와 대기 일정은 도서관 운영 시스템의 최신 정보가 필요하므로, 서비스는 최종 확인을 해당 도서관 홈페이지나 사서에게 연결합니다.

System Architecture

다음 책장은 별도의 프런트엔드 프레임워크 없이 HTML, CSS와 JavaScript ES Modules로 구성한 단일 페이지 애플리케이션입니다. 로컬에서는 Node.js 서버가 정적 화면과 /api/* 프록시를 함께 제공하고, 운영 환경에서는 Cloudflare Worker가 같은 역할을 수행합니다.

사용자 브라우저
  ├─ 도서 검색·도서관 선택
  ├─ 정책 기반 대기 구간 계산
  ├─ 내 책장(Local Storage)
  └─ 사서용 동향 화면
           │
           ▼
Node.js Server / Cloudflare Worker
  ├─ 요청값 검증
  ├─ 5분 메모리 캐시
  ├─ 12초 타임아웃
  └─ 서버 환경변수에서 API 키 주입
           │
           ▼
도서관 정보나루 Open API
  ├─ 도서 검색·상세
  ├─ ISBN별 소장 도서관
  ├─ 소장·대출 가능 여부
  ├─ 연관·인기 도서
  └─ 대출 급상승·이용 추이

브라우저는 정보나루 인증키를 직접 알지 못하고 서버의 /api/* 경로만 호출합니다. 인증키는 로컬의 DATA4LIBRARY_API_KEY 환경변수 또는 Cloudflare Secret으로 주입하며, 수집 기록에는 authKey=[REDACTED]만 남깁니다. 같은 요청은 5분간 캐시하고 외부 API 응답이 12초를 넘으면 명확한 오류 상태로 전환합니다.

Data Strategy

공개 데이터로 구현한 범위

도서 검색과 ISBN 기준 상세 서지정보
지역별 정보나루 참여 도서관 검색
ISBN별 소장 도서관과 대출 가능 여부
연관 도서와 도서관별 인기 도서
도서관별 장서·대출 및 이용 추이
실제 대출 급상승 도서 순위

다음 책장의 도서관 목록은 전국의 모든 도서관 명부가 아닙니다. 도서관 정보나루에 데이터를 공개하는 참여 도서관 중 검색 조건에 맞는 결과이며, 현재 기본 지역은 서울 지역코드 11, 첫 페이지 최대 30개관입니다. 특정 책을 조회할 때는 해당 ISBN을 소장한 참여 도서관만 표시합니다.

정책 기반 계산으로 분리한 범위

정보나루 공개 API는 개인별 예약 순번, 복본별 실시간 반납 예정일, 예약 취소·미수령 이력을 제공하지 않습니다. 따라서 이 값들은 사용자가 해당 도서관에서 확인해 직접 입력하며, 결과에는 도서관 정책 기준 추정이라는 한계와 사서 확인 안내를 표시합니다.

같은 제목이라도 출판사, 개정판, 판형, 종이책·전자책이 다르면 ISBN이 달라질 수 있습니다. 다음 책장은 ISBN을 중심으로 판본을 구분해 잘못된 소장 도서관 조회와 추천 결과의 중복을 줄입니다.

Tech Stack

Frontend: HTML5, CSS3, Vanilla JavaScript, JavaScript ES Modules, Local Storage
Backend: Node.js 20, 네이티브 HTTP 서버, 정보나루 API 프록시
Deployment: Cloudflare Workers, Wrangler 4
Data: 도서관 정보나루 Open API, ISBN, KDC, 대출·소장·급상승 데이터
Testing & CI/CD: Node.js Test Runner, GitHub Actions, 비밀정보 노출 검사, 재현 가능한 제출 ZIP
Design & Documentation: Figma, Notion, GitHub

Validation

정보나루 9개 기능에 대해 총 17개의 실제 요청을 저장했고, 17개 요청이 모두 성공했습니다.
서울 3개 도서관을 대상으로 소년이 온다의 소장 여부와 대출 가능 여부를 확인해 소장 3개관, 대출 가능 1개관의 실데이터를 검증했습니다.
잘못 연결된 데모 도서 4권의 ISBN을 수정해 제목과 판본이 다른 문제를 제거했습니다.
문법 검사, 단위 테스트, API 키 노출 검사로 구성된 npm run ci에서 자동 검증 16개가 통과했습니다.
공개 Cloudflare Workers 배포에서 홈 화면 HTTP 200, API live 모드, hotTrend 실데이터와 브라우저 오류 없음을 확인했습니다.
API 연결이 실패할 때 가상값으로 대체하지 않고 오류 상태와 데이터 기준 한계를 표시하도록 검증했습니다.

Trouble Shooting

공개 API에 예약 원자료가 없는 문제

초기 기획은 실제 예약열과 반납 이력으로 이용 가능일을 예측하는 것이었습니다. 그러나 공개 API로는 개인별 예약 순번과 복본별 반납·연장·취소 이력을 확보할 수 없었습니다. 합성 데이터로 정확도를 제시하면 실제 성능으로 오해할 수 있어 기각하고, MVP를 사용자 입력 정책값 기반 예상 구간 + 실데이터 대체도서 추천으로 변경했습니다. 협력 도서관의 비식별 원자료를 확보한 뒤에만 기준선 오차와 구간 포함률을 검증할 예정입니다.

브라우저에 정보나루 API 키가 노출될 수 있는 문제

정적 화면에서 정보나루를 직접 호출하면 인증키가 소스와 네트워크 요청에 노출됩니다. 브라우저는 자체 /api/*만 호출하고 Node.js 서버 또는 Cloudflare Worker가 환경변수에서 키를 주입하도록 경계를 분리했습니다. .env와 원본 데이터는 Git에서 제외하고, CI가 추적 파일의 키 패턴을 검사합니다.

검색 결과를 전체 도서관 정보로 오해하는 문제

참여 도서관, 지역, 페이지 수와 ISBN 조건에 따라 결과가 달라지므로 “검색되지 않음”을 “도서관이나 소장 자료가 없음”으로 단정할 수 없습니다. 화면에 정보나루 참여 도서관 기준임을 명시하고, 예약자 수·복본 수·반납 예정일처럼 공개 API에 없는 값은 만들어내지 않으며, 중요한 소장·대출·예약 상태는 해당 도서관에 다시 확인하도록 안내했습니다.

Project Document

Project Status

현재 상태: 진행 중

2026년 7월 25일 기준 전체 진행률은 35%입니다. 역할과 범위, 정보나루 API 수집기, 정책 기반 대기일 계산기, 이용자 화면 3종, 사서 화면 1종, 자동 검증과 Cloudflare Workers 공개 배포를 완료했습니다. 사서 화면은 가상 수치를 제거하고 정보나루의 실제 hotTrend 데이터로 전환했습니다.

다음 개발 우선순위는 아래와 같습니다.

ISBN·KDC·도서관 필드를 표준화하는 정제 파이프라인 완성
추천 후보를 실제 loanAvailable=Y 기준으로 재정렬
계산기의 휴관일·수령 기간·결측 입력 테스트 보강
이용자 5~8명과 사서 2~3명을 대상으로 문구와 흐름 검증
협력 도서관의 비식별 예약·반납 샘플 확보 가능성 확인
공모전 원고와 제출 번들을 2026년 8월 7일까지 완성

예약 원자료를 확보하지 못하면 실제 예측 정확도 검증은 제외하고, 공개 데이터로 재현 가능한 MVP와 한계를 제출합니다. 원자료를 확보하면 정책 계산기를 기준선으로 삼아 평균 절대오차와 예상 구간 포함률을 비교하는 2단계 개발로 확장합니다.

Project Term

진행 방식: 데이터 가능성 검증 → 수집·정제 → 정책 기반 계산기 → 대체도서 추천 → 클릭형 프로토타입 → 사용자·사서 검증 → 원고와 제출 QA 순서로 작게 구현하고 단계마다 완료 기준을 확인합니다.
기록 및 관리: 범위와 일정은 Notion 실행 단계, 코드와 재현 절차는 GitHub, 화면과 클릭 흐름은 Figma를 단일 기준으로 관리합니다. 보안·개인정보·사실성에 영향을 주는 결정은 RFC와 ADR로 기록합니다.

빠른 설정

빠른 이동

사이트 검색

읽기 설정

태그 바로가기

연락처

다음 책장

다음 책장

Project Title: 기다리는 시간을 알려주고, 기다리는 동안 읽을 책을 연결하는 도서관 서비스

공개 서비스 바로가기

프로젝트의 탄생

Project Overview

User Flow

System Architecture

Data Strategy

공개 데이터로 구현한 범위

정책 기반 계산으로 분리한 범위

Tech Stack

Validation

Trouble Shooting

공개 API에 예약 원자료가 없는 문제

브라우저에 정보나루 API 키가 노출될 수 있는 문제

검색 결과를 전체 도서관 정보로 오해하는 문제

Project Document

Project Status

Project Term