Files
frontend/docs/st/01.총평.md
T

3.0 KiB

ST 앱 총평 (Architecture Overview)

하수도 통계 관리 시스템 (ST: Statistics) 프론트엔드 앱의 전체 구조 및 기술 평가 리포트


1. 앱 개요

항목 내용
앱 이름 st (Statistics)
목적 하수도 통계 관리 시스템 - 통계 입력, 검토, 승인, 관리 기능 제공
프레임워크 Next.js 15 (App Router)
언어 TypeScript
패키지 관리 pnpm Workspace (모노레포 구조)

2. 전체 평가 요약

✅ 강점

  1. FSD(Feature-Sliced Design) 아키텍처 도입
    shared → entities → components → pages → app 레이어 계층 구조를 적용하여 관심사 분리가 명확합니다.

  2. 서버 API 프록시 패턴 (Middleware)
    Next.js Middleware를 활용해 백엔드 API 호출을 프록시 처리하므로, 클라이언트에서 직접 API 서버를 노출하지 않는 보안 구조를 갖추고 있습니다.

  3. 멀티 백엔드 분리 구조
    일반 서버 API(/server/*)와 ST 전용 서비스(st-management-service, st-input-service) 경로를 분리하여 URL 기반 라우팅으로 독립성을 확보하였습니다.

  4. 글로벌 상태 관리 일관성
    Zustand를 통한 전역 상태(사용자 정보, 메뉴, 알림, 탭)와 TanStack Query/SWR을 활용한 서버 상태 관리를 목적에 맞게 분리하였습니다.

  5. 재사용 가능한 공통 컴포넌트
    DataGrid, SearchForm, ApproveButton, RejectButton 등 업무 공통 컴포넌트를 components/module에 집중하여 중복 개발을 최소화하였습니다.

⚠️ 개선 권고 사항

  1. 데이터 페칭 라이브러리 혼용
    SWR과 TanStack Query를 동시에 사용하고 있습니다. 용도 기준이 명확하지 않으면 유지보수 시 혼란이 생길 수 있습니다. 가급적 하나의 라이브러리로 통일하거나, 사용 기준을 문서화하는 것을 권장합니다.

  2. 미구현 업무 함수
    일부 컴포넌트에서 rejectFunc, approveFunc 등의 함수가 빈 상태로 남아 있습니다. 서비스 커버리지 확인이 필요합니다.

  3. src/store 와 src/shared/store 이중 스토어 경로
    탭 관련 스토어(tab-store)가 src/store에, 그 외 공통 스토어는 src/shared/store에 나뉘어 있습니다. FSD 원칙상 src/shared/store로 통일하는 것을 권장합니다.


3. 문서 목차

문서 내용
02.디렉토리구조.md 전체 소스 폴더 구조 설명
03.기술스택.md 사용 라이브러리 및 기술 상세
04.아키텍처패턴.md FSD 아키텍처 구조 및 데이터 흐름
05.상태관리.md Zustand 전역 상태 관리 패턴
06.데이터페칭.md SWR / TanStack Query 데이터 페칭 패턴
07.용어정리.md 프로젝트 주요 용어 정의