Searchweb-Dev · jin2304 · Mar 5, 2026 · Feb 27, 2026 · Feb 27, 2026 · Feb 27, 2026
diff --git a/.gitignore b/.gitignore
@@ -40,3 +40,10 @@ out/
 
 ### VS Code ###
 .vscode/
+
+### Claude AI ###
+.claude/
+CLAUDE.md
+
+### HTTP Tests ###
+*.http
diff --git a/build.gradle b/build.gradle
@@ -34,6 +34,7 @@ dependencies {
 	implementation 'org.springframework.boot:spring-boot-starter-validation'
 	implementation 'org.springframework.boot:spring-boot-starter-oauth2-client'
 	implementation 'me.paulschwarz:spring-dotenv:4.0.0'
+	implementation 'org.jsoup:jsoup:1.17.2'
 
 	compileOnly 'org.projectlombok:lombok'
 	runtimeOnly 'org.postgresql:postgresql'
@@ -50,4 +51,8 @@ tasks.named('test') {
 
 jar {
 	enabled = false
+}
+
+tasks.withType(JavaCompile) {
+	options.compilerArgs << '-parameters'
 }
diff --git a/docs/Backend/01. backend-convention.md b/docs/Backend/01. backend-convention.md
@@ -0,0 +1,47 @@
+# 백엔드 전체 컨벤션
+
+이 문서는 백엔드 전 도메인에 공통으로 적용하는 기본 컨벤션이다.
+
+## 1) 네이밍 규칙
+- Java 클래스명: `UpperCamelCase` (예: `BoardService`)
+- Java 변수/필드/메서드명: `lowerCamelCase` (예: `boardService`)
+- DB 컬럼/테이블명: `snake_case`, 기본 단수형 사용 (예약어/특수 케이스 제외)
+
+## 2) 계층 구조
+- 기본 구조는 `Controller -> Service -> DAO` 3계층으로 구성한다.
+- 도메인 간 기능 연동이 필요하면, 대상 도메인의 Service **인터페이스를 직접 사용**한다.
+
+## 3) DTO / Command 규칙
+- DTO는 **Controller 단에서만 사용**한다.
+- Controller 요청 DTO는 `inner class` 형태로 관리한다.
+- Service/DAO 계층 DTO 정책은 추후 확정 전까지 최소화한다.
+- 조회 조건이 복잡해지면 `Command` 객체를 사용한다.
+
+## 4) API 규칙
+- RESTful API 규칙을 준수한다.
+- Controller 반환은 공통 응답 포맷을 사용한다.
+  - `ResponseEntity<ApiResponse<T>>`
+- HTTP 상태코드는 의미에 맞게 사용한다. (예: 생성 `201 Created`, 조회 `200 OK`)
+
+## 5) 도메인/에러 규칙
+- 도메인 객체 생성은 `@Builder`를 사용하고, Builder로 생성한다.
+- 에러 코드는 도메인별로 커스텀 `*ErrorCode`를 작성한다.
+- 에러 코드는 짧고 명확하게 유지한다.
+
+## 6) Config 배치 규칙
+- Config는 `config` 폴더 하위에 도메인 폴더를 만든 뒤 배치한다.
+- 예시: 아이템 도메인 Config -> `config/item/ItemConfig.java`
+
+## 7) 머지 기준
+- 테스트가 있으면 테스트 통과 후 머지한다.
+- 테스트 코드가 없더라도, 서버 실행(기동) 정상 확인 후 머지한다.
+
+## 빠른 체크리스트
+- [ ] 클래스/변수 네이밍 규칙을 지켰는가?
+- [ ] 3계층 구조를 지켰는가?
+- [ ] DTO는 Controller에서만 사용했는가?
+- [ ] 필요한 경우에만 Command를 도입했는가?
+- [ ] 공통 응답 포맷(`ApiResponse`)을 사용했는가?
+- [ ] 도메인별 에러 코드를 분리했는가?
+- [ ] Config 파일을 `config/{domain}` 경로에 배치했는가?
+- [ ] 테스트 통과 또는 서버 기동 확인 후 머지 가능한 상태인가?
diff --git a/docs/Fontend/01. frontend_architecture.md b/docs/Fontend/01. frontend_architecture.md
@@ -0,0 +1,111 @@
+# SearchWeb Frontend Architecture
+
+SearchWeb 프론트엔드는 현대적인 웹 기술 스택을 활용하여 프리미엄한 사용자 경험과 높은 유지보수성을 확보하는 것을 목표로 합니다.
+
+## 🛠 Tech Stack & Rationale (기술 스택 선정 이유)
+
+| 기술 스택 | 채택 이유 | 기대 효과 |
+| :--- | :--- | :--- |
+| **Next.js 15 (App Router)** | React 19 지원 및 서버 컴포넌트(RSC) 최적화 필요 | 초기 로딩 속도 향상 및 SEO 최적화 |
+| **Zustand** | Redux 대비 매우 가벼운 보일러플레이트 및 직관적인 API | 링크/폴더/UI의 복잡한 전역 상태를 효율적으로 관리 |
+| **TanStack Query v5** | 서버 상태(Server State) 관리와 캐싱의 표준 | API 연동의 선언적 처리 및 로딩/에러 상태 관리 자동화 |
+| **Tailwind CSS v4** | 유틸리티 우선 스타일링 및 최신 CSS 기능 활용 | 디자인 시스템 구축 속도 향상 및 유지보수 용이 |
+| **shadcn/ui** | 검증된 접근성과 고난도 UI 프리미티브(Dialog, Popover 등) 제공 | 서비스의 'Premium Purple' 스타일을 빠르고 일관되게 구현 |
+| **TypeScript (Strict)** | 엄격한 타입 체크를 통한 런타임 에러 방지 | 코드 안정성 확보 및 대규모 협업 효율성 증대 |
+| **Axios** | 인터셉터 및 커스텀 인스턴스 설정의 유연함 | 백엔드 공통 응답 규격(Envelope) 처리에 최적화 |
+
+## 📁 Directory Structure (프로젝트 구조)
+
+```text
+frontend/
+├── src/
+│   ├── app/                # Next.js App Router (Pages & Layouts)
+│   │   ├── login/          # 구글 소셜 로그인 연동 페이지
+│   │   ├── my-links/       # 핵심 기능: 대시보드 메인 뷰
+│   │   └── layout.tsx      # Root Layout (Theme & Provider)
+│   ├── components/
+│   │   ├── ui/             # shadcn/ui 기반 아토믹 컴포넌트
+│   │   ├── layout/         # AppLayout, Sidebar, Header
+│   │   ├── my-links/       # 대시보드 전용 (FolderCard, RightPanel)
+│   │   ├── dialogs/        # 기능별 모달 (CreateFolder, SaveLink)
+│   │   └── providers/      # Context (QueryProvider 등)
+│   ├── lib/
+│   │   ├── store/          # Zustand 스토어 (linkStore, folderStore, uiStore)
+│   │   ├── api/            # API 클라이언트 및 엔드포인트 모듈
+│   │   ├── types/          # 공통 타입 및 인터페이스
+│   │   └── utils.ts        # 클래스 병합 유틸리티 함수
+│   └── public/             # 브랜드 에셋 및 정적 아이콘
+```
+
+## ✅ 지금까지 완료된 작업 요약
+
+### 1. 프로젝트 기반 및 환경 설계
+- **초기화**: Next.js 15 + React 19 + TypeScript Strict 모드 설정
+- **인프라**: pnpm 워크스페이스 및 배포 최적화 설정
+- **테마**: Tailwind v4를 활용한 프리미엄 보라색(#7c3aed, #a78bfa) 및 글래스모피즘 디자인 시스템 구축
+
+### 2. 핵심 로직 및 데이터 흐름
+- **상태 관리**: Zustand를 이용한 도메인 기반 전역 상태 설계
+- **데이터 페칭**: TanStack Query v5 + Axios 기반 API 연동 모듈 및 커스텀 훅(`useFolders` 등) 구현
+- **응답 규격**: 백엔드 공통 Response (code, message, data) 규정 및 인터페이스 설계
+
+### 3. 주요 UI 및 레이아웃
+- **Layout**: 고정 사이드바 및 반응형 헤더를 포함한 `AppLayout` 완성
+- **UI Components**: shadcn/ui 기반 고품질 컴포넌트 커스터마이징 추가
+- **View**: 메인 랜딩, 소셜 로그인 인터페이스, 마이링크 대시보드 조립 완료
+
+## 🚀 실제 프론트 동작 명령어 (pnpm)
+
+```bash
+# 프론트엔드 작업 경로 진입
+cd frontend
+
+# 개발 서버 실행 (Turbopack 적용)
+pnpm dev
+
+# 배포용 빌드 및 실행
+pnpm build
+pnpm start
+
+# 코드 품질 검사
+pnpm exec tsc --noEmit  # 타입 체크
+pnpm lint               # 코드 스타일 및 린트
+```
+
+## 📝 API Response Format (Sample)
+
+```json
+{
+  "code": "200",
+  "message": "success",
+  "data": { ... }
+}
+```
+
+## 🎯 향후 구현 기능 (Next Steps) - 상세 보완
+
+### 1단계: 백엔드 실데이터 통합 (Integration)
+- [ ] 현재의 Mock 데이터를 실제 서비스 API 엔드포인트 호출로 전면 교체
+- [ ] Zod 스키마를 이용한 API 응답 런타임 데이터 검증 레이어 연동
+- [ ] 실제 데이터 기반의 로딩/에러/빈 상태 UI 정밀 튜닝
+
+### 2단계: 인증 및 권한 관리 (Authentication)
+- [ ] Google OAuth 기반 로그인 성공 후 JWT 토큰 핸들링 및 세션 유지
+- [ ] `Auth Middleware` 설정을 통한 비로그인 사용자 경로 보호
+- [ ] 사용자 프로필 이미지 및 권한에 따른 UI 노출 제어
+
+### 3단계: 고급 UX 기능 고도화 (Advanced UX)
+- [ ] 폴더 이동 및 링크 순서 조정을 위한 Drag & Drop 인터랙션 구현
+- [ ] `Intersection Observer` 기반의 대용량 북마크 무한 스크롤(Infinite Scroll) 적용
+- [ ] 글로벌 명령 팔레트(Search Cmd+K)를 통한 빠른 이동 기능
+
+### 4단계: 서비스 확장 (Extended Features)
+- [ ] 최근 방문 히스토리(`/history`) 및 방문 빈도 기반 추천 기능
+- [ ] 상세 유저 설정, 알림 설정 및 다크모드 수동 전환 제어 페이지(`settings`)
+
+---
+
+## ⚠️ 주의사항
+1. **pnpm 권장**: 모든 패키지 관리는 `pnpm`을 통해 수행해야 의존성 문제가 없습니다.
+2. **반응형 설계**: `my-links` 페이지의 그리드 레이아웃(5열) 유지 시 뷰포트 크기를 고려하십시오.
+3. **스타일 일관성**: 프리미엄 보라색 그라디언트 테마의 디자인 톤앤매너를 준수해야 합니다.