🗓️ 프로젝트 기간

2025.12.19 ~ ing

📱 프로젝트 소개

Finders는 필름 카메라 사용자가 웹에서 현상소를 탐색하고, 예약과 결제까지 한 번에 처리할 수 있도록 돕는 서비스입니다. AI 사진 복원, 커뮤니티 피드, 필름 카메라 가이드 등 필름 라이프 전반을 아우르는 경험을 제공합니다.

⭐ 핵심 기능

Feature	Description
로그인 / 회원가입	카카오톡 기반 소셜 로그인
필카 입문 101	필름 카메라 입문자를 위한 가이드 콘텐츠
AI 사진 복원	Replicate AI 기반 사진 복원 기능
현상소 보기	위치·가격·리뷰 기반 현상소 검색
온라인 예약	날짜·옵션 선택을 통한 비대면 예약
사진 수다	사진 공유 및 커뮤니티 소통 기능
현상 관리	현상 완료 사진 관리, 배송 및 방문 수령 상태 확인

👩‍💻 Web 파트

김민석	김혜린	전병국	한현서
Web Developer	Web Developer	Web Developer	Web Developer
현상소 보기 온라인 예약 현상관리	사진수다 커뮤니티 현상관리	로그인 / 회원가입 마이페이지 현상관리	메인페이지 AI 사진 복원 현상관리

⚒️ 기술 Stack

카테고리	기술 스택	선정 이유
UI Library		컴포넌트 기반 구조로 재사용성과 유지보수성을 높이고, 생태계가 안정적인 SPA 환경을 구축하기 위해 선택
Language		정적 타입 기반 개발로 런타임 에러를 최소화하고, API 계약 안정성을 확보하기 위해 도입
Build Tool		빠른 HMR과 빌드 속도를 통해 개발 생산성을 극대화하기 위해 선택
Styling		유틸리티 기반 스타일링으로 일관된 디자인 시스템을 유지하고, SVG를 컴포넌트화하여 동적 제어를 가능하게 하기 위해 도입
Server State Management		서버 상태 캐싱, 동기화, 재요청 전략을 체계적으로 관리하여 네트워크 비용을 줄이고 UX를 개선하기 위해 사용
Global State Management		경량 전역 상태 관리로 불필요한 보일러플레이트 없이 인증/필터 상태 등을 관리하기 위해 선택
HTTP Client		인터셉터 기반 인증 처리 및 공통 에러 핸들링 구조를 구현하기 위해 사용
Routing		SPA 환경에서 선언적 라우팅 및 레이아웃 분리를 효율적으로 관리하기 위해 도입
Package Manager		디스크 공간 효율성과 의존성 충돌 방지를 위해 선택
Code Quality		코드 스타일 일관성과 PR 품질 유지를 위해 자동화된 린트/포맷팅 환경을 구축
Error Monitoring		배포 후 발생하는 런타임 에러를 실시간 추적하고 안정적인 운영 환경을 구축하기 위해 도입
Deployment / CI		자동 빌드 및 배포 파이프라인을 구축하여 항상 배포 가능한 상태를 유지하기 위해 사용
Collaboration		디자인 협업, 문서화, 이슈 관리 및 실시간 커뮤니케이션을 위해 활용

📁 폴더 구조

도메인 기준(photoLab, photoFeed, photoManage, photoRestoration 등)으로 기능을 분리하고, API / Query Hook / UI / Type / Store를 역할별로 분리해 유지보수성과 확장성을 확보했습니다.

└── 📁 src/
    ├── 🌐 apis/                 // 도메인별 API 요청 모듈 (Barrel Pattern: index.ts)
    │   ├── auth/
    │   ├── file/
    │   ├── mainPage/
    │   ├── member/
    │   ├── my/
    │   ├── photoFeed/
    │   ├── photoLab/
    │   ├── photoManage/
    │   └── photoRestoration/
    │
    ├── 🔁 hooks/                // 도메인별 Query Hook + 공통 훅 (캡슐화된 쿼리 훅 전략)
    │   ├── auth/
    │   ├── common/
    │   ├── file/
    │   ├── mainPage/
    │   ├── member/
    │   ├── my/
    │   ├── photoFeed/
    │   ├── photoLab/
    │   ├── photoManage/
    │   └── photoRestoration/
    │
    ├── 🧩 components/           // UI 컴포넌트 (공통/도메인 단위 분리)
    │   ├── common/
    │   ├── auth/
    │   ├── mainPage/
    │   ├── mypage/
    │   ├── photoFeed/
    │   ├── photoLab/
    │   ├── photoManage/
    │   └── photoRestoration/
    │
    ├── 📄 pages/                // 라우트 단위 페이지(진입점)
    │   ├── auth/
    │   ├── developmentHistory/
    │   ├── filmCameraGuide/
    │   ├── mainPage/
    │   ├── mypage/
    │   ├── photoFeed/
    │   ├── photoLab/
    │   ├── photoManage/
    │   └── photoRestoration/
    │
    ├── 🧱 layouts/              // 레이아웃 컴포넌트 (Root/Footer/MyPage 등)
    ├── 🧭 router/               // 라우팅 구성 (Router.tsx)
    ├── 🗂 store/                // 전역 상태 관리 (Zustand)
    │
    ├── 🧬 types/                // 도메인별 타입 정의 + ApiResponse<T>
    ├── 📚 constants/            // 상수/라벨/매핑 값
    ├── 🛠 utils/                // 순수 유틸 함수
    ├── ⚙️ lib/                  // 전역 설정 (axios instance, interceptors 등)
    ├── 🖼 assets/               // 폰트/아이콘/SVG/이미지 리소스
    │
    ├── 🚀 App.tsx               // 앱 엔트리 UI
    └── 🔥 main.tsx              // 앱 엔트리 포인트

📌 구조 설계 포인트

• 도메인 기준 폴더링: photoLab, photoFeed, photoManage, photoRestoration 등 서비스 기능 축을 기준으로 모듈을 분리했습니다.
• API / Hook / UI / Type 역할 분리: 한 도메인에서도 apis/, hooks/, components/, types/로 레이어를 분리해 변경 영향 범위를 줄였습니다.
• Barrel Pattern: apis/*/index.ts, hooks/*/index.ts를 활용해 외부에서는 단순한 import 경로로 사용하도록 구성했습니다.
• Interceptors / Storage 단일화: lib/setUpInterceptors.ts, utils/tokenStorage.ts 중심으로 인증/토큰 관리 로직을 집중시켜 중복과 취약점을 줄였습니다.

🤖 기술 의사결정 (워크북 외 선택 기술)

워크북 기반 학습을 넘어, 실제 서비스 수준의 안정성과 확장성을 확보하기 위해
아래 기술 및 패턴을 추가 도입했습니다.
각 항목은 선정 이유와 팀 합의 여부를 명시합니다.

1️⃣ 아키텍처 및 고도화 패턴

🔐 API 요청 동시성 제어 (Concurrency Control in Interceptors)

선정 이유
토큰 만료 시 여러 API 요청이 동시에 실패하면 리프레시 요청이 중복 발생하는 Race Condition 문제가 발생합니다.
이를 방지하기 위해 실패 요청을 Pending Queue에 저장하고, 토큰 갱신 후 대기 요청을 일괄 재시도하는 구조를 설계했습니다.

팀 합의
인증 안정성은 서비스 신뢰성과 직결된다고 판단하여, 단순 재요청 방식이 아닌 큐 기반 동시성 제어 로직을 프로젝트 표준으로 채택했습니다.

🧩 도메인 주도 서비스 계층 + Barrel Pattern

선정 이유
컴포넌트와 API 호출 로직의 강한 결합을 방지하기 위해 auth, member, photoLab 등 도메인 단위로 서비스 레이어를 분리했습니다.
또한 index.ts 기반 Barrel Pattern을 활용해 내부 구현을 은닉하고 명확한 인터페이스만 외부에 노출하도록 구성했습니다.

팀 합의
백엔드 API 명세 변경 시 수정 범위를 최소화하고 유지보수성을 높이기 위해 해당 구조를 프로젝트 기본 아키텍처로 채택했습니다.

📦 캡슐화된 쿼리 훅 (Encapsulated Query Hooks)

선정 이유
useQuery를 컴포넌트에서 직접 사용할 경우 쿼리 키 중복, 캐싱 전략 불일치, 정책 분산 문제가 발생할 수 있습니다.
이를 방지하기 위해 도메인별 커스텀 훅으로 감싸 쿼리 키 및 캐싱 전략(staleTime 등)을 일원화했습니다.

팀 합의
UI는 데이터 표현에 집중하고, 데이터 정책은 훅 계층에서 관리하는 방향으로 관심사 분리 원칙을 팀 규칙으로 합의했습니다.

🧬 제네릭 기반 API 응답 타입 설계 (ApiResponse<T>)

선정 이유
모든 API 응답 구조를 ApiResponse<T> 형태로 일반화하여 타입 추론을 강화하고, 런타임 에러 가능성을 최소화했습니다.

팀 합의
타입 안정성과 개발 생산성 향상을 위해 공통 응답 타입을 전 API에 일괄 적용하기로 합의했습니다.

🗄️ 스토리지 파사드 패턴 (Storage Facade Pattern)

선정 이유
토큰 접근 로직이 여러 파일에 분산될 경우 중복 코드 및 보안 취약점이 발생할 수 있습니다.
이를 방지하기 위해 tokenStorage 객체로 접근 로직을 단일화했습니다.

팀 합의
추후 쿠키 기반 인증 등 저장소 정책 변경에 유연하게 대응할 수 있도록 파사드 패턴 도입에 합의했습니다.

2️⃣ 개발 환경 및 인프라

⚡ Vite + PNPM

선정 이유
Vite는 빠른 HMR과 빌드 속도를 제공하며, PNPM은 디스크 공간 효율성과 의존성 충돌 방지 측면에서 장점이 있습니다.
개발 생산성과 프로젝트 확장성을 동시에 고려해 해당 조합을 선택했습니다.

팀 합의
프로젝트 초기부터 최적화된 개발 환경을 팀 표준으로 확정했습니다.

🤖 GitHub Actions + Husky

선정 이유
PR 단계에서 자동 린트 및 빌드 테스트를 수행하고, 커밋 단계에서 포맷 및 린트 오류를 사전에 차단하여 코드 품질을 유지하기 위함입니다.

팀 합의
“항상 배포 가능한 상태”를 유지하기 위해 자동화된 품질 게이트 운영에 합의했습니다.

🧭 Path Aliasing (@/)

선정 이유
상대 경로 중첩을 제거하여 가독성을 높이고, 파일 이동 시 import 경로가 깨지는 문제를 방지하기 위해 루트 기준 절대 경로를 도입했습니다.

팀 합의
프로젝트 전반에서 절대 경로 사용을 공식 규칙으로 표준화했습니다.

3️⃣ UI/UX 특화 라이브러리

🎨 SVGR

선정 이유
SVG를 React 컴포넌트로 변환하여 Props 및 Tailwind 기반 동적 스타일링이 가능하도록 구성했습니다.

팀 합의
아이콘 자산의 재사용성과 유지보수성을 높이기 위해 도입에 합의했습니다.

🧱 React Masonry CSS

선정 이유
사진 커뮤니티 피드에서 다양한 비율의 이미지를 빈틈 없이 배치하기 위해 Masonry 레이아웃을 적용했습니다.

팀 합의
커뮤니티 UX 완성도 향상을 위해 전담 레이아웃 라이브러리 사용에 합의했습니다.

🏠 React Daum Postcode

선정 이유
국내 사용자에게 익숙한 주소 검색 UX를 제공하고, 도로명 주소 입력 정확도를 높이기 위해 도입했습니다.

팀 합의
실사용자 경험 개선을 위해 도입에 합의했습니다.

🌿 브랜치 전략

• main : 운영
• develop : 개발
• 모든 작업 브랜치는 develop 기준 생성

💬 Commit 메시지

type: 메시지 (#이슈번호)

• feat / fix / refactor / style / chore / docs

🔀 Pull Request

• Base: develop
• 제목: [FEAT] 회원가입 API 연동
• Issue 연결: Closes #10
• 24시간 내 리뷰 필수
  

_{UMC 9th · Finders · Web}