Frontend Stack Decision

프론트엔드 스택 결정

관련 Issue: fowoco/client#1

결정 사항

항목	결정	근거
프레임워크	React 18 + Vite	백엔드(Spring)와 REST/JSON으로 분리된 SPA. HR 관리자 웹은 SEO가 필요 없음
언어	TypeScript strict mode	저장소 공통 CLAUDE.md 기준. any 타입 금지
서버 상태	React Query (TanStack Query) 설치·초기화 완료, 실사용은 커스텀 useApiQuery 훅	서버 상태와 클라이언트 상태를 명확히 구분. 실제로는 대부분 페이지가 얇은 커스텀 훅(src/hooks/useApiQuery.ts)으로 loading/success/empty/error를 관리 중 — Component-Library 참고
클라이언트 상태	Zustand	화면 전용 상태, 인증 상태(authStore) 등 경량 스토어로 관리
코드 품질	ESLint + Prettier	fowoco/knowledge와 동일한 코드 기준
테스트	Vitest + Testing Library	유닛·컴포넌트 테스트. 정확한 현재 개수는 bun run test 실행 결과 참고 (계속 늘어나는 중이라 여기 고정 숫자를 적지 않음)
스타일링	CSS Modules + 디자인 토큰(src/styles/tokens.css)	Tailwind 미도입, Figma 추출 토큰을 CSS 변수로 관리
패키지 매니저	bun	PR #299에서 npm → bun 전환. 설치 속도 개선 + husky/lint-staged 커밋 전 검사 도입 목적. vitest 기본 워커 풀(forks)이 bun 실행 시 Windows에서 타임아웃나는 문제가 있어 vite.config.ts에서 pool: 'threads'로 고정함

검토했지만 채택하지 않은 대안

• Next.js: SSR/라우팅/이미지 최적화 등 풀스택 기능은 내부 관리자 도구 특성상 불필요.
• Vue 3 + Vite: 학습곡선은 낮지만 팀 컨벤션 일관성을 위해 제외.

패키지 경계

fowoco-client는 UI 렌더링과 서버 상태 캐싱만 담당하며, DB·모델 내부 구현에는 직접 접근하지 않습니다. Worker·Task·Audit·Document·Auth 등 대부분의 데이터는 이제 fowoco-server 실 API로 연동되어 있습니다 (Screen-Catalog의 "백엔드 연동 현황" 참고). 아직 서버 계약이 없는 일부 화면만 각 페이지의 *Data.ts 파일에 데모 데이터로 남아 있고, 남은 연동 지점은 코드 내 // TODO(backend): <메서드> <경로> 주석으로 표시되어 있습니다.