Refactor/architecture

.github/workflows/CI.yaml

@@ -16,10 +16,10 @@ jobs:
       - name: Enable Corepack
         run: corepack enable
 
-      - name: Use Node.js 20.9.0
+      - name: Use Node.js 22
         uses: actions/setup-node@v4
         with:
-          node-version: "20.9.0"
+          node-version: "22"
           cache: "yarn"
           cache-dependency-path: "yarn.lock"
 
@@ -32,11 +32,6 @@ jobs:
           key: ${{ runner.os }}-nextjs-${{ hashFiles('**/yarn.lock') }}
           restore-keys: |
             ${{ runner.os }}-nextjs-
-      - name: Install system dependencies for Sharp
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y libvips-dev
-
       - name: Install dependencies
         run: yarn install --immutable
 
@@ -50,14 +45,16 @@ jobs:
         run: yarn build
         env:
           AUTH_SECRET: ${{ secrets.AUTH_SECRET }}
+          INTERNAL_API_SECRET: ${{ secrets.INTERNAL_API_SECRET }}
           GOOGLE_CLIENT_ID: ${{ secrets.GOOGLE_CLIENT_ID }}
           GOOGLE_CLIENT_SECRET: ${{ secrets.GOOGLE_CLIENT_SECRET }}
-          KAKAO_CLIENT_ID: ${{ secrets.KAKAO_CLIENT_ID }}
+          NEXT_PUBLIC_KAKAO_APP_KEY: ${{ secrets.NEXT_PUBLIC_KAKAO_APP_KEY }}
           KAKAO_CLIENT_SECRET: ${{ secrets.KAKAO_CLIENT_SECRET }}
+          KAKAO_REST_KEY: ${{ secrets.KAKAO_REST_KEY }}
           NAVER_CLIENT_ID: ${{ secrets.NAVER_CLIENT_ID }}
-          DATABASE_URL: ${{secrets.DATABASE_URL}}
-          DIRECT_URL: ${{secrets.DIRECT_URL}}
           NAVER_CLIENT_SECRET: ${{ secrets.NAVER_CLIENT_SECRET }}
+          DATABASE_URL: ${{ secrets.DATABASE_URL }}
+          DIRECT_URL: ${{ secrets.DIRECT_URL }}
           NEXT_PUBLIC_SUPABASE_URL: ${{ secrets.NEXT_PUBLIC_SUPABASE_URL }}
-          SUPABASE_SERVICE_ROLE_KEY: ${{ secrets.SUPABASE_SERVICE_ROLE_KEY }}
           NEXT_PUBLIC_SUPABASE_ANON_KEY: ${{ secrets.NEXT_PUBLIC_SUPABASE_ANON_KEY }}
+          SUPABASE_SERVICE_ROLE_KEY: ${{ secrets.SUPABASE_SERVICE_ROLE_KEY }}

README.md

@@ -1,74 +1,95 @@
-# Perscent 🌸
+# ChickChick 🌸
 
-**Perscent**는 향수 애호가들을 위한 종합 커뮤니티 플랫폼입니다. 향수 리뷰, 추천, 컬렉션 관리 및 커뮤니티 기능을 제공합니다.
+향수 정보 조회, 리뷰, 커뮤니티 기능을 제공하는 웹 애플리케이션.
+Next.js 15 App Router와 Hono를 기반으로 구현한 풀스택 프로젝트.
 
-## ✨ 주요 기능
+---
 
-### 🔍 향수 탐색 및 검색
+## 🖼 미리보기
+
+<table>
+  <tr>
+    <td><img src="public/images/docs/image.png" alt="미리보기 1" style="width:600px;height:500px;object-fit:cover;" /></td>
+    <td><img src="public/images/docs/image2.png" alt="미리보기 2" style="width:600px;height:500px;object-fit:cover;" /></td>
+  </tr>
+</table>
+
+---
+
+## ✨ 구현된 기능
+
+### 사용자
+
+- Google, Kakao 소셜 로그인 (NextAuth.js v5)
+- 사용자 프로필 및 활동 내역
+
+### 향수
 
 - 브랜드별 향수 목록 조회
 - 향수 상세 정보 (노트, 어코드, 지속성, 실라주 등)
-- 고급 필터링 및 검색 기능
+- 향수 검색 및 다중 필터링
 
-### 📝 리뷰 시스템
+### 리뷰
 
-- 향수 사용 후기 작성
-- 5점 평점 시스템
-- 지속성, 실라주, 계절감, 가격 대비 만족도 평가
-- 성별 프로필 및 사용 시간대 정보
+- 5점 평점 및 세부 평가 (지속성, 실라주, 계절감, 가격 대비 만족도)
+- 성별 및 사용 시간대 정보 포함
+- Tiptap 기반 에디터
 
-### 👥 커뮤니티
+### 커뮤니티
 
-- 자유게시판, 질문, 추천 게시판
-- 향수 관련 게시글 작성 및 댓글
-- 게시글 좋아요 및 북마크 기능
+- 게시판 (자유/질문/추천)
+- 댓글 및 좋아요
+- 이미지 업로드 (Supabase Storage)
 
-### 📚 개인 컬렉션
+### 개인 활동
 
-- 보유 향수 컬렉션 관리
-- 북마크 기능
-- 사용자 활동 기록
+- 향수/게시글 북마크
+- 개인 향수 컬렉션 관리
+- 임시저장
 
-### 🔐 소셜 로그인
-
-- Google, Naver, Kakao 로그인 지원
-- NextAuth.js 기반 인증 시스템
+---
 
 ## 🛠 기술 스택
 
-### Frontend
+**Frontend**  
+Next.js 15 (App Router) · TypeScript · Tailwind CSS · Zustand · TanStack Query · React Hook Form · Zod · Tiptap
+
+**Backend**  
+Hono · Prisma · PostgreSQL · NextAuth.js v5 · Supabase Storage
 
-- **Framework**: Next.js 15 (App Router)
-- **Language**: TypeScript
-- **Styling**: Tailwind CSS
-- **UI Components**: Custom components with Tailwind
-- **State Management**: Zustand
-- **Forms**: React Hook Form + Zod validation
-- **Rich Text Editor**: CKEditor 5
+**Infra**  
+Vercel · Yarn
 
-### Backend
+---
 
-- **API Framework**: Hono
-- **Database**: PostgreSQL
-- **ORM**: Prisma
-- **Authentication**: NextAuth.js
-- **File Storage**: Supabase
+## 🎯 주요 기술적 선택
 
-### Development Tools
+### Hono on Next.js
 
-- **Package Manager**: Yarn
-- **Linting**: ESLint
-- **Component Development**: Storybook
-- **API Documentation**: OpenAPI/Swagger
+Next.js API Routes 대신 Hono를 도입했습니다. App Router의 폴더 기반 라우팅 방식은
+엔드포인트가 늘어날수록 파일과 폴더가 분산되어 전체 API 구조를 한눈에 파악하기 어렵다는
+한계를 느꼈습니다. 캐치올 세그먼트(`/api/[[...route]]`)를 활용해 Hono로 모든 요청을
+중앙에서 라우팅하도록 구성하여 API 구조의 응집도를 높였습니다.
 
-## 📦 설치 및 실행
+### 상태 관리 분리
 
-### 필수 요구사항
+- **Zustand**: 세션 정보, UI 상태(모달, 토글 등)
+- **TanStack Query**: 서버 상태 (API 응답 캐싱 및 재검증)
 
-- Node.js 18+
+서버 상태와 클라이언트 상태의 책임을 명확히 분리하여 관리합니다.
+
+---
+
+## 📦 로컬 실행
+
+### 요구사항
+
+- Node.js 22+
 - PostgreSQL
 - Yarn
 
+### 설치
+
 ### 1. 저장소 클론
 
 ```bash
@@ -87,13 +108,10 @@ yarn install
 `.env.local` 파일을 생성하고 다음 변수들을 설정하세요:
 
 ```env
-# Database
-DATABASE_URL="postgresql://..."
-DIRECT_URL="postgresql://..."
-
-# NextAuth.js
-NEXTAUTH_SECRET="your-secret"
-NEXTAUTH_URL="http://localhost:3000"
+# Supabase
+NEXT_PUBLIC_SUPABASE_URL="your-supabase-url"
+NEXT_PUBLIC_SUPABASE_ANON_KEY="your-supabase-anon-key"
+SUPABASE_SERVICE_ROLE_KEY="your-supabase-service-role-key"
 
 # OAuth Providers
 GOOGLE_CLIENT_ID="your-google-client-id"
@@ -102,129 +120,68 @@ NAVER_CLIENT_ID="your-naver-client-id"
 NAVER_CLIENT_SECRET="your-naver-client-secret"
 KAKAO_CLIENT_ID="your-kakao-client-id"
 KAKAO_CLIENT_SECRET="your-kakao-client-secret"
-
-# Supabase
-NEXT_PUBLIC_SUPABASE_URL="your-supabase-url"
-NEXT_PUBLIC_SUPABASE_ANON_KEY="your-supabase-anon-key"
-```
-
-### 4. 데이터베이스 설정
-
-```bash
-# Prisma 스키마 생성
-npx prisma generate
-
-# 데이터베이스 마이그레이션
-npx prisma migrate deploy
-```
-
-### 5. 개발 서버 실행
-
-```bash
-yarn dev
+NEXT_PUBLIC_KAKAO_JAVASCRIPT_KEY="your-kakao-javascript-key"
+KAKAO_REST_KEY="your-kakao-rest-key"
+
+# Auth (NextAuth.js v5)
+AUTH_SECRET="your-auth-secret"
+AUTH_TRUST_HOST=true
+AUTH_URL="http://localhost:3000"
+
+# Internal
+# NextAuth가 OAuth 로그인 시 유저 동기화를 위해 내부 API(/api/v1/auth/sync)를 호출할 때
+# 외부 요청과 구분하기 위해 x-internal-secret 헤더에 실어 보내는 시크릿 키입니다.
+INTERNAL_API_SECRET="your-internal-api-secret"
 ```
 
-서버가 실행되면 [http://localhost:3000](http://localhost:3000)에서 애플리케이션을 확인할 수 있습니다.
-
-## 📝 사용 가능한 스크립트
-
-```bash
-# 개발 서버 실행
-yarn dev
-
-# 프로덕션 빌드
-yarn build
-
-# 프로덕션 서버 실행
-yarn start
+---
 
-# Storybook 실행
-yarn storybook
-
-# Prisma Zod 스키마 생성
-yarn zod
-```
-
-## 🏗 프로젝트 구조
+## 🗂 프로젝트 구조
 
 ```
 src/
-├── app/                    # Next.js App Router
-│   ├── (main)/            # 메인 페이지 그룹
-│   ├── api/               # API 라우트
-│   ├── brand/             # 브랜드 페이지
-│   ├── community/         # 커뮤니티 페이지
-│   ├── perfumes/          # 향수 상세 페이지
-│   └── user/              # 사용자 페이지
-├── components/            # 재사용 가능한 컴포넌트
-│   ├── commons/           # 공통 컴포넌트
-│   ├── domains/           # 도메인별 컴포넌트
-│   └── modal/             # 모달 컴포넌트
-├── lib/                   # 유틸리티 및 설정
-│   ├── hono/              # Hono API 설정
-│   ├── prisma/            # Prisma 클라이언트
-│   ├── queries/           # 데이터 조회 함수
-│   ├── stores/            # Zustand 스토어
-│   └── utils/             # 유틸리티 함수
-└── stories/               # Storybook 스토리
+├── app/                        # Next.js App Router
+│   ├── (main)/                # 메인 페이지
+│   ├── api/[[...route]]/      # Hono 캐치올 API 라우트
+│   ├── api/auth/              # NextAuth.js 인증 라우트
+│   ├── api-doc/               # OpenAPI 문서 페이지
+│   ├── brand/[name]/          # 브랜드 상세 페이지
+│   ├── community/             # 커뮤니티 목록
+│   ├── community/post/        # 게시글 작성·상세·수정
+│   ├── perfumes/              # 향수 목록 및 상세
+│   └── user/[id]/             # 사용자 프로필·활동·북마크·컬렉션
+├── components/                # UI 컴포넌트
+│   ├── commons/               # 공통 컴포넌트 (버튼, 카드, 탭 등)
+│   ├── domains/               # 도메인별 컴포넌트
+│   │   ├── brandDetail/
+│   │   ├── community/
+│   │   ├── main/
+│   │   ├── perfumeDetail/
+│   │   ├── perfumes/
+│   │   ├── post/
+│   │   ├── postDetail/
+│   │   └── user/
+│   └── modal/                 # 모달 컴포넌트
+├── server/                    # 서버 사이드 코드
+│   ├── hono/                  # Hono API 레이어
+│   │   ├── middleware/        # 인증 미들웨어
+│   │   ├── repositories/      # DB 접근 레이어
+│   │   ├── routes/v1/         # 핸들러 (도메인별 라우트)
+│   │   ├── schemas/           # Zod 요청/응답 스키마
+│   │   ├── services/          # 비즈니스 로직
+│   │   └── utils/             # 서버 유틸리티
+│   ├── database/              # 서버 액션 및 세션 조회
+│   ├── prisma/                # Prisma 클라이언트
+│   └── supabase/              # Supabase 클라이언트
+├── client/                    # 클라이언트 사이드 코드
+│   ├── hooks/query/           # TanStack Query 훅
+│   ├── stores/                # Zustand 스토어
+│   ├── tiptap/                # Tiptap 에디터 설정
+│   └── utils/                 # 클라이언트 유틸리티
+└── shared/                    # 서버·클라이언트 공용
+    ├── constants/             # 공통 상수
+    ├── types/                 # 공통 타입 정의
+    └── utils/                 # 공통 유틸리티
 ```
 
-## 🎨 컴포넌트 시스템
-
-프로젝트는 재사용 가능한 컴포넌트 시스템을 갖추고 있습니다:
-
-- **Commons**: 버튼, 입력, 카드 등 기본 UI 컴포넌트
-- **Domains**: 특정 도메인(향수, 커뮤니티, 사용자)에 특화된 컴포넌트
-- **Modal**: 로그인, 리뷰 등 모달 컴포넌트
-
-모든 컴포넌트는 Storybook으로 문서화되어 있으며, `yarn storybook`으로 확인할 수 있습니다.
-
-## 📊 데이터베이스 스키마
-
-주요 엔티티:
-
-- **User**: 사용자 정보
-- **Perfume**: 향수 정보
-- **Brand**: 브랜드 정보
-- **Review**: 향수 리뷰
-- **Post**: 커뮤니티 게시글
-- **Comment**: 댓글
-- **Bookmark**: 북마크 (향수/게시글)
-- **Collection**: 사용자 향수 컬렉션
-
-자세한 스키마는 `prisma/schema.prisma` 파일을 참조하세요.
-
-## 🔧 API 문서
-
-개발 모드에서 API 문서는 다음 URL에서 확인할 수 있습니다:
-
-- OpenAPI 스펙: `http://localhost:3000/api/doc`
-
-API는 다음과 같은 엔드포인트를 제공합니다:
-
-- `/api/v1/perfumes` - 향수 관련 API
-- `/api/v1/community` - 커뮤니티 API
-- `/api/v1/reviews` - 리뷰 API
-- `/api/v1/users` - 사용자 API
-- `/api/v1/search` - 검색 API
-
-## 📸 미리보기
-
-![메인 페이지](./public/images/Preview.png)
-
-## 💡 기술적 도전 포인트
-
-    • App Router 전환: 페이지 라우팅 및 서버 컴포넌트 기반 성능 개선.
-    • 상태 관리 전략: Zustand + React Query 기반 데이터 관리.
-    • 컴포넌트 문서화: Storybook으로 UI 테스트 및 관리.
-
-## 📆 개발 로드맵
-
-    •	향수 추천 알고리즘 추가
-    •	다국어 지원 (i18n)
-    •	모바일 최적화 개선
-
-## 🤝 팀 협업 & 코드 컨벤션
-
-    • GitHub Actions + PR 리뷰 프로세스.
-    • ESLint + Prettier를 통한 일관성 유지.
+---