🔧 chore: .claude 문서 업데이트 및 아키텍처, 컨벤션, 개요 파일 수정

This commit is contained in:
hyeonggil
2026-04-11 21:09:47 +09:00
parent 6485f3cb4f
commit f6597736d2
5 changed files with 160 additions and 61 deletions

View File

@@ -1,39 +1,46 @@
# 아키텍처 (Sample)
# 아키텍처
> 이 파일은 `fe-common-rules/templates/project/architecture.md` 에서 복사된 양식입니다.
> 프로젝트의 레이어 구조와 데이터 흐름을 간단히 설명해주세요.
## 레이어 구조
<프로젝트의 레이어 구조를 그림 또는 텍스트로 그려주세요>
```
┌───────────────────────────────────
pages (Nuxt) │ ← 라우팅, 데이터 페칭 진입점
├───────────────────────────────────
components │ ← 재사용 UI (도메인/공용 분리)
├───────────────────────────────────
composables (use*) │ ← 상태 + 로직 (뷰 독립)
├───────────────────────────────────
composables/api (wrapper) │ ← 서버 통신 단일 창구
├───────────────────────────────────
│ server/api │ ← Nuxt 서버 라우트
└───────────────────────────────────┘
┌───────────────────────────────┐
presentation │ ← pages / components
├───────────────────────────────┤
logic │ ← composables / hooks / stores
├───────────────────────────────┤
data access │ ← api wrapper / queries
├───────────────────────────────┤
server │ ← 서버 라우트 / BFF
───────────────────────────────
```
## 규칙
## 의존 규칙
- 레이어는 상위 레이어를 import 할 수 없습니다. (단방향 의존)
- `components` 는 비즈니스 로직을 직접 수행하지 않고, composable 에 위임합니다.
- 전역 상태는 필요한 경우에만 Pinia store 로 승격합니다.
- → 하위 **단방향 의존**만 허용
- 같은 레이어 간 순환 import 금지
- <프로젝트 고유 규칙 추가>
## 데이터 흐름
1. 사용자 이벤트 → `components` 에서 `composable` 호출
2. `composable``composables/api` 래퍼 호출
3. 래퍼 → `$fetch` 로 Nuxt `server/api` 또는 외부 API 요청
4. 응답은 타입이 보장된 상태로 composable → component 로 전달
1. <이벤트 발생부터 응답까지의 흐름을 간단히>
2. ...
3. ...
## 상태 관리 가이드
| 상태 종류 | 권장 위치 |
| -------------------- | ------------------------ |
| 컴포넌트 로컬 상태 | `ref` / `reactive` |
| 페이지 단위 공유 상태| `provide/inject` 또는 composable |
| 앱 전역 상태 | Pinia store |
| 서버 데이터 | `useAsyncData`/`useFetch`|
| 컴포넌트 로컬 상태 | <예: ref / useState> |
| 페이지 단위 공유 상태| <예: provide/inject> |
| 앱 전역 상태 | <예: Pinia / Zustand> |
| 서버 데이터 | <예: useFetch / TanStack Query> |
## 외부 의존성
- 반드시 알아야 할 외부 서비스나 내부 API 를 나열
- 장애 발생 시 fallback 정책이 있다면 함께 기술