프론트엔드 설치 가이드

1. 디렉터리 이동

cd SCH-WEB-PORTAL/frontend

2. 의존성 설치

npm install
# 또는
pnpm install

설치되는 주요 패키지:

패키지	역할
`react 19`	UI 라이브러리
`react-router-dom 7`	클라이언트 라우팅
`@tabler/icons-react`	아이콘 (`icons.tsx` 래퍼를 통해 사용)
`vite 8`	빌드 도구
`typescript 6`	타입 안전성

3. 개발 서버 실행

npm run dev

http://localhost:5173에서 개발 서버가 실행됩니다.

백엔드 서버(localhost:8000)가 실행 중이어야 로그인 및 API 호출이 동작합니다.

4. 타입 체크 / 빌드

npx tsc -b          # 타입 체크
npm run build       # tsc -b && vite build
npm run lint

dist/ 디렉터리에 정적 파일이 생성됩니다.

타입 체크는 npx tsc -b로 실행하세요. 이 프로젝트는 프로젝트 참조(tsc -b) 구성이라 tsc --noEmit으로는 실제 검사가 이뤄지지 않습니다.

API 프록시 설정

개발 중 Vite가 /api/* 요청을 백엔드로 자동 프록시합니다.

// vite.config.ts
server: {
  proxy: {
    '/api': {
      target: 'http://localhost:8000',
      changeOrigin: true,
    },
  },
},

디렉터리 구조

frontend/src/
├── App.tsx            # 라우팅 + 세션 상태 (react-router)
├── types.ts           # 전체 TypeScript 타입 + 유틸 함수
├── icons.tsx          # @tabler/icons-react 래퍼
├── useIsMobile.ts     # 모바일 뷰포트 판별 훅
├── data/
│   ├── sitemap.ts     # 사이트맵 + URL 슬러그 매핑
│   ├── mail.ts        # 웹메일 메일함 정의 (MAIL_FOLDERS)
│   └── mailApi.ts     # 웹메일 API 래퍼 + MailApiError
└── components/        # 페이지 컴포넌트 (62개)

`sitemap.ts` 구조

메뉴 구조는 frontend/src/data/sitemap.ts에서 관리됩니다.

SITEMAP — 전체 메뉴 트리 (그룹 → 섹션 → 아이템)
IMPLEMENTED_ITEMS — 현재 구현된 메뉴 항목 Set (미구현 항목은 UI에서 비활성화)
ITEM_ROUTES — 아이템 ID → 라우트 경로 매핑
SECTION_ROUTES — 섹션 ID → 라우트 경로 매핑

새 기능을 추가할 때:

SITEMAP에 메뉴 항목 추가
IMPLEMENTED_ITEMS에 항목 이름 추가
ITEM_ROUTES에 슬러그 추가
App.tsx에 lazy() import + renderMenuPage() 분기 추가
components/에 페이지 컴포넌트 생성

개별 페이지마다 <Route>를 선언하지 않습니다. /:sectionSlug/:itemSlug 한 라우트가 슬러그를 한글 메뉴명으로 되돌리고, renderMenuPage()가 컴포넌트를 고릅니다.

/mail은 사이드바까지 통째로 바뀌는 별도 셸이라 이 라우트 밖에 있고 sitemap.ts에도 없습니다.

ESLint

npm run lint

CSS는 App.css / index.css에서 직접 관리합니다 (Tailwind 미사용). any 타입은 지양하고, console.log 디버깅 코드는 커밋하지 않습니다.

프론트엔드 설치 가이드

On this page