웹 앱 아키텍처
web-craft를 먼저 읽으세요. 작업에 필요한 참조만 로드하세요. 키트와 프레임워크 어댑터는 선택한 키트와 프레임워크에 대해서만 사용합니다.
맵
| 주제 | 참조 |
|---|---|
| 서버 vs 클라이언트 컴포넌트, BFF, 환경 변수 및 비밀 경계 | references/server-client.md |
| API 계층, 오류 모델, 상태 소유권, 폼, 낙관적 UI, URL 상태 | references/data-forms.md |
| 로딩, 오류 및 Not-found 경계, 재시도, 오프라인, 스켈레톤 타이밍 | references/states.md |
| i18n: 레지스트리, 해상도, URL, 카탈로그, 포맷팅, 백엔드 헤더 | references/i18n.md |
| RTL, 논리적 속성, 방향 아이콘, 포털 | references/rtl.md |
| 인증, 권한 부여, XSS, CSRF, 쿠키, 캐시 격리, 개인 데이터 | references/auth-security.md |
| 테마: 사용자 선호도 vs 적용 테마, 시스템 변경, 깜빡임 없음 | references/theming.md |
| 공개 페이지를 위한 SEO | references/seo.md |
| GEO: AI 검색 및 어시스턴트에서의 가시성 | references/geo.md |
| Next.js App Router 어댑터 | references/fw-next.md |
| React + Vite 어댑터 | references/fw-vite.md |
| shadcn/ui 어댑터 | references/kit-shadcn.md |
| Ant Design 어댑터 | references/kit-antd.md |
| Material UI 어댑터 | references/kit-mui.md |
| node-craft(또는 모든 OpenAPI) 백엔드와 작업 | references/node-craft-contract.md |
| 공식 소스 및 검토 날짜 | references/sources.md |
모든 곳에 적용되는 규칙
- 필요에 의한 경계. 컴포넌트는 기본적으로가 아니라 상호작용, 브라우저 API 또는 클라이언트 상태가 필요할 때 클라이언트 컴포넌트가 됩니다. 대화형 섬을 작게 유지하세요. 서버 전용 코드, ORM 클라이언트 또는 비밀을 클라이언트 코드로 가져오지 마세요. 공개 환경 변수는 비밀이 아닙니다.
- 단일 API 계층. 하나의 fetch 클라이언트, 안정적인 코드와 상태로 키가 지정된 하나의 타입 오류 모델, 하나의 인증 동작. 기능은 자체 fetch 및 재시도를 구축하지 않습니다. 서버 데이터는 쿼리/캐시 계층에 있고, 전역 클라이언트 상태는 작은 스토어 또는 컨텍스트에, 폼 상태는 폼 도구에, 로컬 UI 상태는 컴포넌트에 있습니다. 모의 소스는 개발 및 테스트를 위해 구성에 의해 전환되며, 기능을 편집하여 전환하지 않습니다. 신뢰할 수 없는 응답은 런타임에 구문 분석됩니다.
- 폼. 프로젝트에 다른 도구가 없는 한 react-hook-form + Zod.
mode: 'onTouched',reValidateMode: 'onChange', 첫 번째 오류에 포커스 및 스크롤,setError를 통한 서버 필드 오류, 오류 후에도 값 유지, 이중 제출 차단. 서버는 유효성 검사의 권위자로 남습니다. - 상태에는 경계가 있습니다. 경로 수준의 로딩 및 오류 경계와 데이터가 스트리밍되는 곳에 로컬 Suspense. 하나의 실패한 위젯이 페이지를 비우지 않습니다.
- i18n은 아키텍처입니다. 실제 엔진, 로케일 레지스트리(BCP 47 태그, 방향, 카탈로그, 표시 이름), 달리 선택하지 않는 한 영어 대체, 서버에서 요청 범위의 로케일, 서버와 클라이언트에서 동일한 초기 로케일, 로케일 및 네임스페이스별로 로드된 카탈로그, 앱 로케일에서 매핑된 키트 및 날짜 로케일.
- 보안은 서버 측입니다. 백엔드에서 권한 부여. 렌더링하는 HTML을 삭제하세요. 쿠키 세션에는 CSRF 보호가 필요합니다. 개인 응답은 공유 캐시에 절대 들어가지 않습니다. 로케일 및 사용자 종속 응답은 캐시 키를 변경합니다.
- 공개 페이지는 찾을 수 있어야 합니다. 서버에서 렌더링된 로케일 올바른 메타데이터, 언어별 표준 URL, 실제 대응 항목에 대해서만 hreflang 대체, 사이트맵, 표시되는 콘텐츠와 일치하는 구조화된 데이터. GEO는 색인 가능하고 인용 가능한 콘텐츠와 명시적인 AI 크롤러 정책으로 시작합니다. 순위 또는 인용 보장은 없습니다.
- 키트는 감싸지 않고 적용됩니다. 테마와 토큰은 제품의 디자인 결정에서 비롯됩니다. 반복되는 제품 동작이나 API를 고정하기 위해서만 키트 컴포넌트를 감싸세요. 키트 자체 전환 위에 두 번째 애니메이션 시스템을 쌓지 마세요.
완료
web-craft 적용 → 완료, 추가로: 클라이언트 번들에 비밀 또는 서버 전용 모듈이 없음; 서로 다른 로케일 또는 다른 사용자를 위한 두 개의 동시 요청이 데이터를 혼합할 수 없음; 첫 번째 렌더링이 올바른 언어와 테마로 이루어짐; 주장된 모든 키트/프레임워크 조합이 실제로 확인됨.