[FrontEnd] Component & Page 구조 ver.020

[chaehun0i]

0. 배경

• Frontend 팀 내 컴포넌트 및 페이지 구조를 통일
• Backend / DB / 문서팀과의 협업 시 혼선을 방지하기 위함
• 개발 속도 향상 및 유지보수 용이성 확보

검토안

• 컴포넌트 기반 아키텍처 (Component-Based Architecture)
• Page / Component / Hooks / Utils 역할 분리 구조

---

1. 디렉토리 구조

src/
├── assets/                          # 정적 리소스 (이미지, 아이콘, 데이터)
│   ├── data/
│   │   ├── ksicClassification.json  # 산업 분류 데이터
│   │   └── onboardingData.js        # 온보딩 설정 데이터
│   ├── icons/
│   │   ├── alarm/                   # 알림 관련 아이콘
│   │   ├── base/                    # 기본 아이콘
│   │   └── hover/                   # hover 상태 아이콘
│   └── images/
│       ├── backgrounds/             # 배경 이미지
│       ├── banners/                 # 배너 이미지
│       └── logos/                   # 로고
│
├── components/                      # 공통 컴포넌트 (재사용 2회 이상)
│   ├── Layout/
│   │   ├── HeaderNav.jsx            # 상단 네비게이션
│   │   ├── SidebarNav.jsx           # 사이드바
│   │   └── LoginBackground.jsx      # 로그인 공통 배경
│   │
│   ├── UI/
│   │   ├── Alarm.jsx                # 시스템 알림 (Notification)
│   │   ├── ServiceAlert.jsx         # 사용자 피드백 알림
│   │   └── SignupInputField.jsx     # 공통 입력 컴포넌트
│   │
│   └── Common/                      # 버튼, 모달 등 범용 요소
│
├── homes/                           # 페이지 (라우팅 단위)
│   ├── App.jsx                      # 라우팅 설정
│   ├── Home.jsx                     # 앱 진입 페이지
│   │
│   ├── gates/
│   │   └── Gate.jsx
│   │
│   ├── logins/
│   │   ├── Login.jsx
│   │   ├── SignUp.jsx
│   │   ├── CompanySelect.jsx
│   │   ├── InviteSignup.jsx
│   │   └── LoginVisualPanel.jsx
│   │
│   ├── mains/
│   │   ├── Main.jsx
│   │   ├── Dashboard.jsx
│   │   ├── Manager.jsx
│   │   ├── Invite.jsx
│   │   └── Onboarding.jsx
│   │
│   └── errors/
│       └── NotFound.jsx
│
├── hooks/                           # 전역 상태 및 커스텀 훅
│   ├── AuthContext.jsx
│   └── AlarmContext.jsx
│
├── styles/                          # CSS 중앙 관리
│   ├── index.css                    # 글로벌 스타일
│   ├── App.css                      # 레이아웃 스타일
│   ├── Gate.css
│   ├── logins.css
│   ├── mains.css
│   ├── onboarding.css
│   └── (기타 CSS)
│
├── utils/
│   └── network.js                   # API 통신 설정
│
└── main.jsx                         # 엔트리 포인트

---

2. 구조 설계 원칙

1. 역할 분리

구분	역할
homes	페이지 (Route 기준)
components	재사용 UI
hooks	상태 및 로직
utils	API 및 공통 함수
assets	정적 리소스

2. 컴포넌트 기준

• 2회 이상 재사용되는 경우에만 components/로 이동
• 단, 향후 재사용 가능성이 높은 경우 예외적으로 포함 가능

3. 알림 시스템 구분 (중요)

구분	설명
Alarm	데이터 기반 알림 (ex: 초대 요청, 승인 알림)
ServiceAlert	사용자 피드백 (ex: 성공/에러 메시지)

• 두 개념은 반드시 분리하여 사용

---

3. 개발 규칙

1 네이밍 규칙

• 파일: PascalCase (예: HeaderNav.jsx)

• 함수/변수: camelCase

• 폴더: 소문자

• 단, components 내부는 컴포넌트와 일관성을 위해 PascalCase 허용

2 스타일 규칙

• 모든 CSS는 styles/ 폴더에서 관리
• 파일명은 해당 페이지/컴포넌트와 매칭

예:

Gate.css
logins.css
ServiceAlert.css

3 Import 규칙

• 상대경로 (../../) 사용 지양
• alias(@) 사용 권장

예:

import { showDefaultAlert, showConfirmAlert } from '@components/UI/ServiceAlert';

4 금지 사항

• 불필요한 컴포넌트 분리 금지
• 동일 기능 중복 구현 금지

5. 컴포넌트 책임 범위

• components는 UI 렌더링에 집중
• 비즈니스 로직은 hooks 또는 utils에서 처리

---

4. 협업 원칙

• 구조 변경 시 반드시 팀원 공유 후 반영
• 공통 컴포넌트 추가 시 재사용 여부 검토
• 네이밍 및 import 규칙 준수

---

5. 변경 사항 (1차 → 2차)

1. assets 구조 통합

• 기존: 정적 리소스 분산 관리
• 변경: assets 하위에서 data / icons / images로 통합 관리

2. components 구조 명확화

• Layout / UI / Common 기준으로 역할 분리
• 공통 컴포넌트만 포함하도록 기준 정리

3. 알림 시스템 분리

• Alarm: 데이터 기반 알림
• ServiceAlert: 사용자 피드백 알림

4. styles 중앙 관리 유지

• 모든 CSS를 styles 폴더에서 통합 관리
• 페이지 / 컴포넌트 단위로 파일 구분
• 모든 스타일 파일은 src/styles 폴더에서 중앙 관리

5. hooks 구조 명확화

• AuthContext / AlarmContext 분리
• 전역 상태 관리 역할 정의

6. import 규칙 추가

• 상대경로 사용 지양
• alias(@) 기반 import 사용 권장

7. 네이밍 규칙 보완

• 폴더는 기본 소문자 사용
• components 내부는 PascalCase 허용

영향 범위

FE / BE @choiyc05 / DB @leeej9801-max / 문서 @frankie516c

담당자

• @x2bjvhmmwg-gif
• @frydaynar
• @agii990114-ctrl
• @leeej9801-max

결정일

2026-05-05