Feature/hompage

CLAUDE.md

@@ -64,6 +64,7 @@ PostgreSQL+pgvector  ·  S3/MinIO
 | SSE 이벤트 스펙 | [`docs/event-stream.md`](./docs/event-stream.md) |
 | **디자인 시스템** | [`docs/design-system.md`](./docs/design-system.md) |
 | UI 패턴 (4-state, 폼, 토스트, 키보드) | [`docs/ui-patterns.md`](./docs/ui-patterns.md) |
+| **프론트엔드 타입 시스템** | [`docs/frontend-types.md`](./docs/frontend-types.md) |
 | 보안 (인증, 암호화, 개인정보) | [`docs/security.md`](./docs/security.md) |
 | 옵저버빌리티 (trace, 로그, AI 비용) | [`docs/observability.md`](./docs/observability.md) |
 | 환경 변수 카탈로그 | [`docs/environment.md`](./docs/environment.md) |

docs/README.md

@@ -32,6 +32,7 @@
 ### 디자인·프론트엔드
 - [`design-system.md`](./design-system.md) — 토큰, 컬러, 타이포그래피, 컴포넌트 인벤토리
 - [`ui-patterns.md`](./ui-patterns.md) — 반복되는 UX 패턴, 상태 처리 (loading/empty/error)
+- [`frontend-types.md`](./frontend-types.md) — TypeScript 타입 네이밍·레이어별 흐름·정의 위치
 
 ### 보안·운영
 - [`security.md`](./security.md) — 인증·인가, 토큰 암호화, 개인정보 처리

docs/coding-conventions.md

@@ -21,6 +21,16 @@
 허용: `id`, `url`, `uri`, `api`, `db`, `pg`, `mq`, `ai`, `llm`, `rag`, `stt`, `tts`, `pdf`
 비권장: `usr`, `msg`, `cfg`, `tmp` → `user`, `message`, `config`, `temp` 사용
 
+### 1.4 타입 (TypeScript)
+
+프론트엔드 TypeScript 타입 규약은 분리 문서로 관리한다 → [**`frontend-types.md`**](./frontend-types.md).
+
+요점만:
+- PascalCase + 의미 있는 접미사 (`Dto` / `Request` / `Response` / `Result` / `Model` / `Props` / `State` / `Options` / `Id`).
+- `I` / `T` Hungarian prefix 금지.
+- 타입은 사용되는 레이어에 산다. `Dto → Entity → Model → Props` 단방향.
+- 전역 `types/` 폴더 금지. 슬라이스 내부에서 시작, 3곳 이상 중복 시 `shared` 승격.
+
 ---
 
 ## 2. 함수·메서드 설계

docs/frontend-types.md

@@ -0,0 +1,124 @@
+# 프론트엔드 타입 시스템 — TypeScript
+
+> StackUp 프론트엔드의 TypeScript 타입 규약. **타입은 사용되는 레이어에 산다.** 이름의 접미사가 책임 경계를 선언한다.
+>
+> 상위 컨텍스트 — [coding-conventions.md](./coding-conventions.md) (언어 공통 규약), [`frontend/CLAUDE.md`](../frontend/CLAUDE.md) (FSD 구조)
+> 적용 범위 — [`frontend/src/`](../frontend/src/)
+
+---
+
+## 목차
+
+1. [원칙](#1-원칙)
+2. [접미사 ↔ 레이어 매트릭스](#2-접미사--레이어-매트릭스)
+3. [레이어별 타입 흐름](#3-레이어별-타입-흐름)
+4. [`type` vs `interface`](#4-type-vs-interface)
+5. [정의 위치](#5-정의-위치)
+6. [shared 승격 임계](#6-shared-승격-임계)
+7. [안티패턴](#7-안티패턴)
+
+---
+
+## 1. 원칙
+
+- **PascalCase + 의미 있는 접미사**. 접미사가 타입의 책임·레이어를 신고한다.
+- `I` / `T` Hungarian prefix 금지 — TypeScript 컴파일러가 `type` / `interface` 를 충분히 구분한다.
+- **단방향 흐름**: `Dto → Entity → Model → Props`. 역방향 import 금지.
+- **전역 `types/` 폴더 금지**. 슬라이스 내부에서 시작, 진짜 공유될 때만 끌어올린다.
+
+---
+
+## 2. 접미사 ↔ 레이어 매트릭스
+
+| 접미사 | 레이어 | 책임 | 예 |
+|---|---|---|---|
+| `XxxDto` | `shared/api/` (OpenAPI 자동 생성) | 백엔드 wire format 스냅샷. 수정 금지 | `SessionDto`, `UserDto` |
+| `XxxRequest` / `XxxPayload` | API 호출부, 이벤트 publisher | HTTP 요청 body, RabbitMQ 메시지 payload | `CreateSessionRequest`, `ResumeAnalyzedPayload` |
+| `XxxResponse` | API 호출부 | HTTP 응답 raw shape (수동 정의 시) — **함수 반환에 사용 ✗** | `LoginResponse` |
+| `Xxx` (접미사 없음) | `domain/{slice}/model/` | 비즈니스 엔터티. Dto에서 매핑됨 | `User`, `Session`, `Resume` |
+| `XxxResult` | 도메인 / 유즈케이스 함수 반환 | 비즈니스 로직 출력 (HTTP 비종속) | `AnalysisResult`, `ValidationResult` |
+| `XxxModel` | `features/*/ui/`, `widgets/*/ui/` | UI 표시 전용 가공 데이터 | `SessionListItemModel`, `ServiceCardModel` |
+| `XxxProps` | 컴포넌트 옆 | React props | `ButtonProps`, `HomeHeroProps` |
+| `XxxState` | store / state machine | **명시적** 상태 모델. 단발 `useState` shape 에 사용 ✗ | `AuthState`, `SessionMachineState` |
+| `XxxOptions` | 함수·훅 설정 | 옵셔널 인자 묶음 | `UseTypewriterOptions` |
+| `XxxId` | 어디든 | branded identifier | `type SessionId = number & { readonly __brand: 'SessionId' }` |
+
+---
+
+## 3. 레이어별 타입 흐름
+
+```
+ [Backend OpenAPI]
+        │ openapi-typescript 자동 생성
+        ▼
+ shared/api/generated.ts      ──  XxxDto
+        │ 매퍼 함수 (toUser, toSession)
+        ▼
+ domain/{slice}/model/        ──  Xxx (Entity)
+        │ feature / widget 에서 UI 가공
+        ▼
+ features|widgets/*/ui/       ──  XxxModel
+        │ props 로 주입
+        ▼
+ React Component              ──  XxxProps
+```
+
+**경계 규칙**:
+
+- `XxxDto` 는 `shared/api/` 밖으로 새지 않는다. UI · 도메인이 Dto 를 직접 import 하면 anti-corruption layer 가 무너진다.
+- `Xxx` (Entity) 는 `domain/` 이 소유. features / widgets 는 read-only 로 참조한다.
+- `XxxModel` 은 슬라이스 내부에 머문다. 다른 슬라이스로 export 하지 않는다 — UI 표시 형태가 누수되면 변경 비용이 폭증한다.
+
+---
+
+## 4. `type` vs `interface`
+
+`type` 기본값. `interface` 는 두 경우에만:
+
+1. 클래스가 `implements` 할 때 (`ErrorBoundary` 등)
+2. declaration merging 필요 시 (외부 라이브러리 augmentation)
+
+```ts
+// 좋음
+type SessionStatus = 'READY' | 'IN_PROGRESS' | 'COMPLETED';
+type CreateSessionRequest = { userId: UserId; mode: SessionMode };
+type AnalysisResult = { score: number; suggestions: string[] };
+
+// 좋음 — implements 가 필요한 케이스
+interface ErrorBoundaryProps { children: ReactNode; fallback: ReactNode }
+class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> { ... }
+```
+
+---
+
+## 5. 정의 위치
+
+| 무엇 | 어디 |
+|---|---|
+| 컴포넌트 props (단일 사용) | `{Component}.tsx` 상단, **export 안 함** |
+| 외부에서도 import 되는 props | `{Component}.types.ts` |
+| 도메인 엔터티 | `domain/{slice}/model/types.ts` |
+| 슬라이스 내 `XxxModel` | `features/{slice}/model/types.ts` 또는 `ui/` 내부 |
+| API `XxxDto` | `shared/api/generated.ts` (OpenAPI 재생성으로만 갱신) |
+
+**전역 `src/types/` 폴더는 만들지 않는다.** 슬라이스 내부에서 시작하고, 진짜 공유될 때만 끌어올린다.
+
+---
+
+## 6. shared 승격 임계
+
+타입을 `shared/` 로 올리는 시점은 **서로 다른 슬라이스 3곳 이상에서 동일한 shape 이 반복될 때**. 그 전엔 슬라이스 안에 산다.
+
+> "언젠가 쓸지도 모르니 미리 shared 로" 는 항상 잘못된 추상화로 끝난다.
+
+---
+
+## 7. 안티패턴
+
+- ❌ `XxxResponse` 를 함수 반환 타입으로 사용 — `XxxResult` 로.
+- ❌ UI 컴포넌트가 `SessionDto` 를 props 로 받음 — `SessionListItemModel` 로 매핑.
+- ❌ 로컬 `useState<{ ... }>` shape 에 `XxxState` 이름 붙이고 export.
+- ❌ `export type Props = { ... }` 같은 generic export — `{Component}Props` 로.
+- ❌ `src/types/` 또는 `src/shared/types/` 전역 폴더 (junk drawer 화).
+- ❌ `IXxx`, `TXxx` Hungarian prefix.
+- ❌ `Dto` 가 `features/` / `widgets/` / `domain/` 에서 import 되는 경우 — boundary 위반.