인증 및 회원관리(Auto & User)

기능	메서드	엔드포인트	설명
역할 설정	`GET`	`/set-role`	소셜 로그인 전 부모/자녀 여부를 세션에 저장
회원가입 페이지	`GET`	`/join`	회원가입 화면 이동
회원가입 처리	`POST`	`/api/join`	일반/소셜 회원가입 처리 및 쿠키 관리
아이디 중복 확인	`GET`	`/api/check-username`	ID 중복 여부 확인 (JSON 반환)
로그인 페이지	`GET`	`/login`, `/goLogin`	로그인 화면 이동
로그인 처리	`POST`	`/api/login`	JWT 토큰 발행 및 쿠키 설정

도서 검색 및 외부 API (Book Search)

기능	메서드	엔드포인트	설명
도서 상세 조회	`GET`	`/book/detail`	도서 ID로 상세 정보 조회
통합 검색 페이지	`GET`	`/books`	키워드 검색 결과 리스트 조회
AI 채팅용 검색	`GET`	`/api/book-search`	AI 서비스용 도서 검색 (JSON 반환)
국립중앙도서관 검색	`GET`	`/nl/search`	NL API 연동 도서 검색
NL 상세 검색	`GET`	`/nl/detail`	필드별 상세 검색 (저자, 출판사 등)
ISBN 검색	`GET`	`/nl/isbn`	ISBN 코드로 특정 도서 검색

독서 기록장 (Book Diary)

기능	메서드	엔드포인트	설명
기록 목록 조회	`GET`	`/bookdiary`	내 독서 기록 리스트 (부모는 자녀 기록 조회 가능)
기록 상세 보기	`GET`	`/bookdiary/{id}`	특정 일기 상세 내용 및 댓글 조회
기록 작성 페이지	`GET`	`/diary`	새 독서 기록 작성 화면
기록 저장	`POST`	`/diary/save`	도서 정보 및 이미지 포함 기록 저장
기록 수정 페이지	`GET`	`/bookdiary/{id}/edit`	기존 기록 수정 화면
기록 수정 처리	`POST`	`/bookdiary/{id}/edit`	제목, 내용, 이미지 수정
기록 삭제	`POST`	`/bookdiary/{id}/delete`	특정 기록 삭제 (DB + 파일)
선택 삭제	`POST`	`/bookdiary/deleteSelected`	목록에서 선택한 여러 기록 삭제
댓글 작성	`POST`	`/bookdiary/{id}/comment`	특정 기록에 댓글 추가

마이페이지 및 책장 (My Page & Shelf)

기능	메서드	엔드포인트	설명
자녀 마이페이지	`GET`	`/mypage`	본인 독서 통계 및 책장 목록 조회
부모 페이지	`GET`	`/parentpage`	연결된 자녀의 독서 현황 및 활동 요약 모니터링
관심 도서 목록	`GET`	`/favorite`	찜한 도서(북마크) 리스트 조회
책장으로 이동	`POST`	`/favorite/moveToBookcase`	찜한 도서를 내 책장(읽기 시작)으로 이동
독서 목표 수정	`POST`	`/api/user/update-goal`	월간/연간 독서 목표 권수 수정
완독 상태 변경	`POST`	`/api/bookcase/update-status`	책장에 담긴 도서 '읽는 중' ↔ '완독' 전환

권한 분리: 부모(parent)와 자녀(child)의 접근 페이지가 구분되어 있으며, 부모는 자녀의 데이터를 조회하는 로직이 포함되어 있습니다.
보안: JWT 방식을 사용하며, SecurityContextHolder를 통해 로그인한 사용자 정보를 가져옵니다.
파일 처리: 독서 기록 작성 시 이미지 업로드(MultipartFile) 및 물리적 파일 삭제 로직이 구현되어 있습니다.

🏗️ 서비스 레이어 주요 메커니즘 분석

📋 프로젝트 통합 상세 명세서

1. 독서 활동 및 기록 (Book Diary & Shelf)

기능	설명	주요 로직 (Service)
기록 생성	다이어리 작성 및 도서 정보 연동	도서 제목으로 `BookInfo` 자동 생성/연결, 이미지 업로드 처리
이미지 삭제	기록 내 이미지만 별도 삭제	서버 내 물리 파일 삭제 + DB 경로 `null` 처리
다이어리 삭제	기록 삭제 (단일/선택)	댓글 우선 삭제(`@Transactional`) → 물리 파일 삭제 → 일기 삭제
내 책장 조회	내 서재 목록 보기	검색 조건(제목/저자/완독여부)에 따른 필터링 및 다이어리 작성 여부 포함
관심 도서 이동	찜 목록 도서를 책장으로 이동	`Bookmark` 데이터 삭제 후 `MyBookcase`로 신규 저장

2. 도서 검색 및 외부 연동 (Book Search & API)

기능	설명	주요 로직 (Service)
통합 검색	DB 및 외부 API 통합 조회	로컬 DB 조회 후 결과 부족 시 NL/네이버 API 호출 및 자동 DB 저장
네이버 API	네이버 도서 검색 서비스	`RestTemplate` 사용, 유사도 점수(`calculateSimilarityScore`) 기반 최적 결과 반환
NL API	국립중앙도서관 검색 서비스	`UriComponentsBuilder`를 이용한 상세/ISBN 검색 및 이미지 URL 정제(`refineImageUrl`)
데이터 정제	HTML 태그 및 특수문자 제거	`cleanText` 메서드로 API 응답 내 불필요한 태그 제거
3. 사용자 통계 및 관리 (Stats & User)

사용자 통계 및 관리(Stats & User)

기능	설명	주요 로직 (Service)
통계 설정	마이페이지 대시보드 데이터	월간 완독 수, 전체 완독률, 목표 달성률(`goalRate`) 계산
목표 수정	월간 독서 목표 권수 변경	`UsersAddons` 테이블에 목표 권수 저장
회원 가입	일반 및 소셜 가입	자녀 계정 가입 시 부모 ID 필수 체크, 소셜 계정 연동 정보 저장
OAuth2 로그인	네이버/구글/카카오 연동	각 벤더별 응답 속성(`Attributes`)을 추출하여 공통 규격으로 변환