[Decision Log] FrontEnd Component & Page 구조 표준화 및 적용

[frydaynar]

0. 배경

• Frontend 내 컴포넌트 및 페이지 구조를 통일하여 비즈니스 로직과 UI의 분리
• Backend / DB / AI 에이전트 팀과의 데이터 연동 및 협업 시 혼선을 방지하기 위함
• 역할별(원청사 vs 협력사) 도메인 분리를 통한 개발 속도 향상 및 유지보수 용이성 확보

1. 프론트엔드 디렉토리 구조

프로젝트는 컴포넌트 기반 아키텍처(Component-Based Architecture)를 따르며, 아래와 같은 구조로 역할을 엄격히 분리하여 관리

src/
├── assets/                          # 정적 리소스 및 마스터 데이터
│   ├── data/
│   │   └── masterData.js            
│   └── logos/
│
├── components/                      # 공통 재사용 컴포넌트 (Layout / UI / Common 분리)
│   ├── Layout/
│   │   ├── HeaderNav.jsx            # 상단 헤더
│   │   └── SidebarNav.jsx           # 왼쪽 사이드바
│   │
│   ├── UI/
│   │   ├── NotificationPanel.jsx    # 알림 센터 실시간 드롭다운 패널
│   │   └── SupplyChainMap.jsx       # 공급망 맵 
│   │
│   └── Common/                      # 범용 프레젠테이션 요소
│       ├── Chip.jsx                 # 상태 표시용 Chip 컴포넌트
│       ├── Kpi.jsx                  # 대시보드용 통계 카드 컴포넌트
│       ├── Card.jsx                 # 공통 카드 레이아웃 컨테이너
│       └── Form.jsx                 # 인라인 입력 폼 구조화 유틸
│
├── homes/                           # 페이지 단위 컴포넌트 (라우팅 및 탭 단위 분리)
│   ├── App.jsx                      # 메인 레이아웃 및 userRole별 페이지 스위칭 컨트롤러
│   │
│   ├── admin/                       # [원청사 전용 화면]
│   │   ├── MainDashboard.jsx        # 1. 메인 대시보드
│   │   ├── partners/                # 2. 협력사 정보 도메인
│   │   ├── boms/                    # 3. BOM 관리 도메인 
│   │   ├── pos/                     # 4. 구매 관리 도메인
│   │   ├── materials/               # 5. 원자재 관리 도메인
│   │   ├── risks/                   # 6. 평가 도메인 (규제별 리스크)
│   │   └── inspections/             # 7. 실사 도메인 (현장 실사 및 동적 보고서)
│   │
│   └── partners/                    # [1차, 2차 & 3차 협력사 통합 공유 화면]
│         ├── CompanyInfo.jsx        # 1. 기업 정보 관리
│         ├── PartnerSubList.jsx     # 2. 하위 협력사 정보 조회 
│         └── MaterialManage.jsx     # 3. 원자재 관리
│
├── styles/                          # CSS 중앙 관리 구역
│   ├── index.css                    # 글로벌 기본 스타일 및 가상 애니메이션 테마
│   └── App.css                      # 전역 레이아웃 및 Recharts 차트 보정용 서브 스타일
│
└── main.jsx                         # 엔트리 포인트 (index.css 및 최상위 라우터 결합/렌더링) 

2. 구조 설계 원칙

• homes (페이지 영역)
  • Route 기준으로 렌더링되는 최상위 페이지 컴포넌트만 위치
  • admin(원청사)과 partners(협력사) 등 권한별로 도메인을 분리하여 관리
• components (재사용 UI)
  • UI 렌더링에 집중하며, 2회 이상 재사용되는 공통 컴포넌트만 위치
  • 역할에 따라 Layout, UI, Common으로 하위 디렉토리를 분리하여 응집도를 높임
• assets (정적 리소스)
  • 프론트엔드 테스트용 더미인 마스터 데이터(masterData.js) 및 이미지 로고 등 정적 리소스를 통합 관리
  • styles (스타일 중앙 관리)
    • 모든 CSS 파일은 styles/ 폴더에서 중앙 통합 관리

3. 개발 및 네이밍 규칙

• 네이밍 규칙
  • '파일명'은 ${PascalCase}$를 적용합니다 (예: HeaderNav.jsx, MainDashboard.jsx)
  • '함수' 및 '변수명'은 ${camelCase}$를 사용합니다
  • '폴더명'은 기본적으로 소문자를 사용하되, components 내부의 디렉토리(Layout, UI, Common)는 컴포넌트와의 일관성을 위해 예외적으로 ${PascalCase}$를 허용합니다
• Import 규칙
  • 상대 경로(../../) 사용을 지양하고, alias(@) 기반의 Import를 권장합니다
• 책임 범위
  • components는 오직 UI 렌더링에만 집중해야 하며, 비즈니스 로직은 최소화합니다
  • 향후 상태 관리나 API 연동 로직이 복잡해질 경우 hooks 및 utils 폴더를 추가하여 분리할 수 있습니다

4. 협업 원칙

• 컴포넌트를 분리하거나 새로운 공통 컴포넌트를 추가할 경우, 동일 기능의 중복 구현을 막기 위해 반드시 재사용 여부를 먼저 검토해야 합니다
• 구조 변경이 필요할 시 반드시 팀원 간 공유 후 반영해야 합니다
• 영향 범위 : FE 파트 / API 연동을 담당하는 BE 파트
• 결정일 : 2026-06-04