---
type: knowledge
domain: architecture
status: active
last-reviewed: 2026-07-27
---

# 프론트엔드 설계

> 한 줄 정의
> 외주·SI에서 프론트엔드의 설계 결정 목록·판단 기준과, **화면정의서(구현 측)·소스·빌드 이관**으로의 납품 연결. 렌더링·상태 4분류·3상태 원칙 등 기술 원리는 [[프론트엔드 원리]]가 정본.

## 설계 대상과 납품 산출물

| 설계 대상 | 납품 산출물 | 검수에서 판정되는 것 |
|---|---|---|
| 화면 구조·라우팅·전이 | **화면정의서(구현 측)** — 정본은 UX 측 [[03_화면·상태 명세]] 승인본이고 구현 측은 그 파생. 충돌 시 UX 승인본이 이기고 변경은 CR 경유 | 화면·메뉴가 프로그램 목록과 1:1인가, 요구 ID로 추적되나 |
| 컴포넌트 경계·상태 설계 | 소스 구조 (인수인계서에 개요) | 유지보수팀이 수정 지점을 찾을 수 있는가 |
| API 소비 계약 | API정의서 합의 서명 (소비 측) | 계약과 화면 데이터가 일치하는가 |
| 빌드·배포 산출물 | **소스코드·빌드 스크립트 이관** | 발주사 환경에서 재빌드가 재현되는가 |

기획 측 입력 템플릿: [[01_화면·라우트 목록]] · [[02_컴포넌트·상태 설계]] · [[03_API 의존성 계약]] · 디자인 측 [[03_화면·상태 명세]].

## 핵심 결정 항목 — 판단 기준

| 결정 | 판단 기준 | 기록 위치 |
|---|---|---|
| 화면 구조·라우팅 | URL이 화면정의서의 화면 ID와 대응되게 — 검수가 화면 단위로 진행된다 | 화면정의서 |
| 렌더링 전략 | 페이지 성격별 혼합 ([[프론트엔드 원리]] 표). 사내 시스템(SEO 무관)은 CSR 기본 | 소스 구조 개요 |
| 상태 관리 | 서버/클라이언트/URL/폼 4분류로 저장소 분리 — 전역 스토어 승격은 근거를 ADR로 | ADR(승격 시) |
| 컴포넌트 경계 | 화면정의서의 반복 요소(목록·폼·모달)를 경계 후보로. 2회 미만 반복은 추출하지 않는다 | 소스 구조 개요 |
| API 계약 소비 규율 | 계약 밖 필드 의존 금지, 계약 변경은 백엔드 Owner 경유 ([[00_역할별 설계 지도]]) — 응답을 임의 가공해 이중 진실을 만들지 않는다 | API 의존성 계약 |
| 3상태·실패 UX | 로딩·빈 값·에러를 화면정의서 상태 열에 명시 — 검수에서 "에러 화면이 없다"는 결함이다 | 화면정의서 |
| 지원 브라우저·해상도 | **계약 확정 사항** — 발주사 표준 브라우저(구형 포함)·VDI 해상도를 착수 전 확인. 추가 지원 요청은 CR. 공통 기본값(viewport 5종·48×48 터치 타겟·7상태 최소선)은 [[04_접근성·반응형·성능 계획]]·[[03_화면·상태 명세]] — 계약이 이를 재정의할 수 있다 | 계약·화면정의서 서두 |

## 다른 역할과의 경계

- **백엔드**: API 계약의 소비자·합의자. 필요한 데이터는 역제안하고, 없는 API를 프론트에서 조합·보정으로 때우지 않는다 — 그 보정 로직이 하자보수 폭탄이 된다.
- **UX 디자인**: 디자인 측 화면·상태 명세가 입력, 구현 측 화면정의서가 출력. 디자인 없는 화면은 미결 의존으로 기록하고 임의 디자인으로 채우지 않는다.
- **보안**: 토큰 보관·세션 처리 방식은 [[05_보안 설계]] 판정 — 클라이언트 검증은 UX이고 서버 검증만이 보안이다.
- **인프라**: 정적 자산 배포 경로·CDN 여부는 [[04_인프라 설계]] 소관. 폐쇄망이면 외부 CDN·폰트·라이브러리 로드가 전부 막힌다 — 번들에 포함.

## 외주 특수 제약

- 지원 브라우저는 "요즘 기준"이 아니라 계약 문구다 — 발주사 표준 PC 환경(IE 모드·구형 크롬·VDI)을 착수 전 서면 확인.
- 화면 수·프로그램 목록이 검수 범위의 단위다. 화면 추가·분할 요청은 CR 회부 ([[SI 수주와 범위 관리]]).
- 폐쇄망 반입: npm 미러·의존성 반입 절차가 있으면 라이브러리 선택의 고정 입력이다 ([[04_인프라 설계]]).

## 안티패턴

- **성공 화면만 설계** — 3상태 누락은 AI·사람 공통의 대표 실수이자 검수 지적 1순위.
- **프론트 보정으로 계약 결함 은폐** — 백엔드 응답 오류를 화면에서 가공해 감추면 결함이 유지보수 단계에서 폭발한다.
- **서버 응답의 스토어 복제** — 이중 진실. 서버 상태는 캐시로 취급 ([[프론트엔드 원리]]).
- **문서 없는 컴포넌트 재사용 구조** — 인수인계서에 구조 개요가 없으면 발주사에겐 블랙박스 이관이다.

## 관련 문서

- [[00_설계 허브]] · [[00_역할별 설계 지도]] · [[01_백엔드 설계]] · [[04_인프라 설계]] · [[05_보안 설계]]
- [[프론트엔드 원리]] · [[프론트엔드-체크리스트]] · [[API-명세-템플릿]]
- [[외주 개발 산출물]] · [[SI 수주와 범위 관리]]