콘텐츠로 이동

ADR 0005: frontend 앱 경계와 화면 중심 구조

상태: 채택, 로컬 구현·검증 완료 (2026-09-07). 서비스 배포는 별도.

문제

Next 앱이 저장소 루트에 있어 backend와 도구·실행 경계가 비대칭이다. 화면에 조회·계산·표시 책임이 섞인 반면, 일부 비활성 편집 구현은 현재 기능처럼 남아 있어 변경 대상을 찾기 어렵다.

결정

FE 실행 단위를 frontend/로 분리한다. package.json·lockfile·Next/TS/CSS/lint 설정·src·public은 frontend가 소유한다. 별도 루트 npm 프로젝트나 workspace 도구는 추가하지 않는다. backend·운영 자동화·공통 문서는 기존 위치에 둔다.

flowchart TD
  R["저장소"] --> B["backend: API·DB"]
  R --> F["frontend: Next 앱·npm·테스트"]
  R --> D["docs / ops / .github"]
  F --> A["src/app: 경로·화면·지역 상호작용"]
  F --> M["src/features: 도메인 계약·정규화"]
  F --> U["src/components: 앱 셸·기존 UI"]
  F --> L["src/lib: 기술 유틸·서버 연결"]
  A --> M
  A --> U
  M --> L

화면은 사용자 행동과 상태를 읽는 기본 단위다. 제품은 목록·상세·비교창을 구분하고 URL/history/스크롤 복원만 독립 hook으로 둔다. 단순 조회 위임과 화면 전용 필터 상태는 소비 화면 가까이에 둔다. 도메인 응답 검증과 정규화는 UI와 분리한다. 모든 도메인에 고정된 파일 세트를 요구하지 않는다.

서버 데이터는 조회 결과, 공유 선택은 URL, 임시 상태는 화면이 소유하고 파생값은 계산한다. 제품에서는 검증된 TanStack Query 기반 부분 실패·재시도를 유지한다. 이를 이유로 전체 화면이나 provider 정책을 일괄 전환하지 않는다.

레거시 삭제는 실제 import/사용 경로와 활성 UI를 기준으로 한다. 미사용 구현과 상수로 비활성화된 편집 가지는 제거하되, 공개 URL·참조 데이터·과거 설계 자료는 검색 결과가 없다는 이유만으로 삭제하지 않는다.

선택하지 않은 안

  • 단순 이동과 전 화면 재작성을 하나의 검증 불가능한 변경으로 합치기.
  • 만능 ResourcePage, 범용 CRUD 엔진, 전역 화면 상태 store.
  • 컴포넌트 줄 수를 맞추기 위한 위임 hook과 고정 types/constants/api/query 파일 세트.
  • 백엔드 계약·계산 정책 변경, 새 DB, 실제 배포 설정 변경.

영향과 검증

개발 명령은 frontend에서 실행한다. Vercel 프로젝트 Root Directory도 frontend로 맞춰야 하며, 실제 서비스 설정 변경은 이번 로컬 구현 범위와 구분한다. 루트의 Azure workflow는 backend 전용이므로 유지한다.

위치 이동은 먼저 파일 동일성과 route 보존·빌드로 검증한다. 이후 제품 compact와 레거시 정리를 검증한다. 제품 URL·필터·최대 3개 비교·history·포커스·부분 실패, 분류 체계 읽기 동작이 회귀 기준이다.

2026-09-07 로컬 검증에서 FE lint·typecheck·제품 테스트 9개·build가 통과했다. 제품·분류 화면의 격리 브라우저 검증도 수행했지만 전 화면 E2E·실기기 접근성·성능 검증 완료를 뜻하지 않는다. 제품 parser는 잘못된 행을 누락시키지 않고 조회 오류로 표시한다. 현재 실행과 남은 검토는 frontend README를 따른다. 과거 리뷰·작업 보고서는 Git 이력에서 확인한다.

가독성 판단 기준

  • 필터 하나를 추가할 때 목록 상태·필터 UI·계산 위치를 바로 찾을 수 있는가?
  • 상세 항목 변경이 HTTP 또는 history 내부 수정까지 요구하지 않는가?
  • 실패와 빈 결과를 구분하고 실패한 영역만 재시도할 수 있는가?
  • 값의 원본이 하나이며, 단순 위임 때문에 여러 파일을 따라가지 않는가?
  • 분리한 컴포넌트·함수의 이름이 실제 책임을 설명하는가?

제품에서 확인한 구조를 전면 규칙으로 확대하기 전에 단순 가격 조회, 사전 체크의 로컬 판정, 사전 관리의 preview/apply/rollback 같은 다른 유형에서 적합성을 확인한다. 폴더 수나 줄 수 감소만으로 개선을 판정하지 않는다.