디렉토리 구조 방식

[healim01]

✍️ [리팩터링] 도메인 기반 디렉토리 구조 도입 안내

참고 이슈

• [FEAT] 상장 아카이빙 기능을 추가한다. #86

📌 배경
기존 구조는 역할별(components/, hooks/, api/ 등)로 분리되어 있어 기능 간 의존 관계 파악이 어려웠고, 서비스 확장 시 유지보수가 어려워질 가능성이 있음.

✅ 개선 방향
pages/ 하위에 기능 단위(mileage, award, scholarship 등)로 디렉토리를 나누고, 해당 기능에 필요한 컴포넌트/훅/api/type 등을 모아 관리합니다.

pages/
└── AwardArchivePage/
├── index.tsx -> 페이지
├── hooks/
├── api/
├── types/
└── components/

🔁 도메인 간 의존

• 다른 기능의 내부 훅/API를 직접 참조 ❌
• 필요한 경우 index.ts를 통해 명시적으로 export 🔄

🧭 경로 관리

• 같은 도메인 내에서는 상대 경로(../api/award)
• 외부 도메인/공통 유틸은 alias(@/utils/...)

[healim01]

05월 11일 디렉토리 구조 관련 의견

📦 [REFACTOR] 도메인 디렉토리 구조 개편

✅ 주요 변경 사항

• pages/ 하위에 도메인 단위 디렉토리(project/, mileage/)를 생성하고 기능별로 정리
• 각 페이지(ProjectListPage, ProjectDetailPage 등)를 독립 디렉토리로 분리
• 공통 컴포넌트는 기존대로 components/ 폴더에 유지
• 도메인 단위 절대경로 alias(@project, @mileage 등) 설정

---

🔍 도입 배경

기존에는 역할 기반(components/, hooks/, api/) 디렉토리 구조로 관리하고 있었으나,
기능이 확장되며 아래와 같은 문제점이 발생했습니다.

• 각 기능(도메인) 간 관심사가 뒤섞여 유지보수가 어려움

이를 해결하기 위해 도메인 단위 중심의 디렉토리 구조를 도입하였습니다.
(까지가 초반 변경 1 디스커션 본문과 동일한 내용입니다. )

이때에도 논의를 진행하면서 도메인 단위 / 도메인 페이지 단위 중 고민하였으나 이후 유지보수할 팀원들이 캡스톤1을 시작할 시점임을 고려,
페이지 단위로 구조를 나누기로 함

하지만 진행 과정 중 아래와 같은 문제 발생

• 한 도메인 내에서 사용되는 훅/타입/API 등이 여러 폴더에 분산
• 기능 확장(예: 프로젝트 상세/수정/추가 페이지 등) 시 코드 위치가 불명확
• 중복 코드 (타입) -> 타입 변경시 변경해줘야하는 코드가 늘어남 => 유지보수에 도움이 안됨

라고 판단하여 더 명확한 도메인 단위 중심의 디렉토리 구조 를 도입하기로 했습니다.

---

🗂️ 디렉토리 구조

src/
├── components/                     # 공통 컴포넌트 (Button, Spinner 등)
├── pages/
│   ├── project/
│   │   ├── ProjectListPage/
│   │   │   ├── index.tsx
│   │   ├── ProjectDetailPage/
│   │   ├── AddProjectPage/
│   │   ├── hooks/
│   │   ├──  components/
│   │   ├── api/
│   │   └── types/
│   ├── mileage/
│   │   ├── MileageListPage/
│   │   ├── hooks/
│   │   ├──  components/
│   │   ├── api/
│   │   └── types/

---

📌 개발 규칙

항목	규칙
공통 컴포넌트	components/에 유지
도메인 내부 공통 훅/API/타입	각 도메인의 hooks/, api/, types/ 폴더에 정리
경로 사용	내부는 상대경로(./), 외부 도메인이나 공통은 alias(@project/, @components/) 사용
도메인 공통 컴포넌트	pages/{도메인}/components/
특정 페이지 전용 컴포넌트	pages/{도메인}/{Page}/components/

---

예시:

• ProjectCard.tsx → 여러 페이지에서 사용 → pages/project/components/
• ProjectEmptyState.tsx → 리스트 페이지 전용 → pages/project/ProjectListPage/components/

📌 구조 설계 이유

• 페이지에만 쓰이는 UI는 페이지 폴더에 국한시켜 관리
• 여러 페이지에서 재사용되는 UI는 도메인 레벨 컴포넌트로 승격
• 이 기준을 통해 컴포넌트 재사용 여부에 따라 위치를 명확히 분리하고,
  코드 이동이나 리팩터링 시 혼동을 줄일 수 있음