+```
+
+### 폼 레이아웃 예시
+
+```typescript
+// 기본 정보 폼 (4컬럼 -> 모바일 1컬럼)
+
+
견적번호
+
접수일
+
수주처
+
현장명
+
+```
+
+---
+
+## 13.3 테이블 대응
+
+### 방법 1: IntegratedListTemplateV2 모바일 카드 (권장)
+
+```typescript
+
(
+
+ )}
+/>
+```
+
+### 방법 2: 가로 스크롤
+
+```typescript
+
+```
+
+### 방법 3: 컬럼 숨김
+
+```typescript
+비고
+{item.memo}
+```
+
+---
+
+## 13.4 모달/다이얼로그
+
+```typescript
+// ✅ 모바일에서 화면 벗어나지 않게
+
+```
+
+모바일에서 모달 내 폼:
+- 필드를 1컬럼으로 쌓기
+- 하단 버튼은 `flex-col` 또는 `flex-wrap`
+
+---
+
+## 13.5 버튼/액션
+
+```typescript
+// ✅ 모바일: 아이콘만, 태블릿+: 아이콘+텍스트
+
+```
+
+버튼 그룹 래핑:
+
+```typescript
+
+
+
+
+```
+
+---
+
+## 13.6 텍스트 처리
+
+| 상황 | 클래스 |
+|------|--------|
+| 한 줄 말줄임 | `truncate` |
+| 여러 줄 말줄임 | `line-clamp-2` |
+| 줄바꿈 방지 (한글) | `break-keep` |
+| 긴 단어 강제 줄바꿈 | `break-all` |
+| 반응형 폰트 | `text-sm md:text-base` |
+
+---
+
+## 13.7 체크리스트
+
+새 페이지/컴포넌트 작성 시:
+
+| # | 항목 |
+|---|------|
+| 1 | 그리드: `grid-cols-1`에서 시작하는가? |
+| 2 | 테이블: 모바일 카드 또는 가로 스크롤 적용했는가? |
+| 3 | 모달: `max-w-[calc(100vw-2rem)]` 적용했는가? |
+| 4 | 버튼: 모바일 아이콘만/데스크탑 아이콘+텍스트 패턴인가? |
+| 5 | 긴 텍스트: `truncate` 또는 `line-clamp` 처리했는가? |
+| 6 | Galaxy Fold (344px) 너비에서 깨지지 않는가? |
+| 7 | 줌 방지: input `font-size` 16px 이상인가? |
diff --git a/sam-docs/frontend/v1/14-error-handling.md b/sam-docs/frontend/v1/14-error-handling.md
new file mode 100644
index 00000000..2a553c3a
--- /dev/null
+++ b/sam-docs/frontend/v1/14-error-handling.md
@@ -0,0 +1,192 @@
+# 14. 에러 핸들링
+
+> 대상: 프론트엔드 개발자
+> 최종 업데이트: 2026-03-20
+
+---
+
+## 목차
+
+| 번호 | 항목 |
+|------|------|
+| 14.1 | [API 에러 핸들러](#141-api-에러-핸들러) |
+| 14.2 | [에러 클래스](#142-에러-클래스) |
+| 14.3 | [컴포넌트에서 에러 처리](#143-컴포넌트에서-에러-처리) |
+| 14.4 | [Next.js 에러 파일](#144-nextjs-에러-파일) |
+| 14.5 | [에러 표시 패턴](#145-에러-표시-패턴) |
+
+---
+
+## 14.1 API 에러 핸들러
+
+`src/lib/api/error-handler.ts`에서 HTTP 상태별 처리:
+
+| 상태코드 | 처리 | 동작 |
+|---------|------|------|
+| 401 | 인증 만료 | `/login`으로 리다이렉트 |
+| 403 | 권한 없음 | ApiError throw |
+| 400 + `duplicate_id` | 품목코드 중복 | DuplicateCodeError throw |
+| 422 | Validation 에러 | 상세 필드 에러 포함 ApiError throw |
+| 기타 | 일반 에러 | ApiError throw |
+
+### 422 Validation 에러 폴백
+
+API 응답 포맷이 2가지 존재하므로 폴백 처리:
+
+```typescript
+// data.errors (Laravel 기본) || data.error.details (커스텀 포맷)
+const validationErrors = data.errors || data.error?.details;
+```
+
+이 폴백은 다음 3곳에 동일하게 적용:
+- `error-handler.ts` (Server Action 경로)
+- `client.ts` (클라이언트 API 경로)
+- `index.ts` (직접 fetch 경로)
+
+---
+
+## 14.2 에러 클래스
+
+### ApiError
+
+```typescript
+class ApiError extends Error {
+ constructor(
+ public status: number,
+ public message: string,
+ public errors?: Record // 필드별 에러 메시지
+ ) {}
+}
+```
+
+### DuplicateCodeError
+
+```typescript
+class DuplicateCodeError extends ApiError {
+ constructor(
+ public message: string,
+ public duplicateId: number,
+ public duplicateCode: string
+ ) {}
+}
+```
+
+### getErrorMessage 유틸리티
+
+```typescript
+import { getErrorMessage } from '@/lib/api/error-handler';
+
+// 에러 객체에서 사용자 친화적 메시지 추출
+const message = getErrorMessage(error);
+// ApiError: "[422] 입력값을 확인해주세요."
+// Error: error.message
+// unknown: "알 수 없는 오류가 발생했습니다"
+```
+
+---
+
+## 14.3 컴포넌트에서 에러 처리
+
+### 기본 패턴 (Server Action 호출)
+
+```typescript
+try {
+ const result = await saveItem(formData);
+ if (!result.success) {
+ toast.error(result.error || '저장 실패');
+ return;
+ }
+ toast.success('저장 완료');
+} catch (error) {
+ if (isNextRedirectError(error)) throw error; // redirect는 재throw
+ toast.error(getErrorMessage(error));
+}
+```
+
+### Validation 에러 상세 표시
+
+```typescript
+if (error instanceof ApiError && error.errors) {
+ const firstKey = Object.keys(error.errors)[0];
+ const firstError = error.errors[firstKey];
+ toast.error(`${error.message}\n${firstKey}: ${firstError[0]}`);
+}
+```
+
+### redirect 에러 구분
+
+Next.js의 `redirect()`는 내부적으로 에러를 throw하므로 catch에서 구분 필요:
+
+```typescript
+import { isNextRedirectError } from '@/lib/utils/redirect-error';
+
+catch (error) {
+ if (isNextRedirectError(error)) throw error; // 반드시 재throw
+ // 실제 에러만 처리
+}
+```
+
+---
+
+## 14.4 Next.js 에러 파일
+
+| 파일 | 용도 | 'use client' | 위치 우선순위 |
+|------|------|-------------|-------------|
+| `error.tsx` | 런타임 에러 경계 | 필수 | 특정 라우트 > 그룹 > locale > root |
+| `not-found.tsx` | 404 페이지 | 불필요 | 특정 라우트 > locale > root |
+| `global-error.tsx` | 루트 레이아웃 에러 | 필수 | root만 |
+| `loading.tsx` | 로딩 상태 (Suspense) | 불필요 | 특정 라우트 > 그룹 |
+
+### error.tsx 필수 구조
+
+```typescript
+'use client';
+
+export default function Error({
+ error,
+ reset,
+}: {
+ error: Error & { digest?: string };
+ reset: () => void;
+}) {
+ return (
+
+
오류가 발생했습니다
+
{error.message}
+
+
오류가 발생했습니다
+
+
+
+ );
+}
+```
+
+---
+
+## 14.5 에러 표시 패턴
+
+| 상황 | 방법 |
+|------|------|
+| API 호출 실패 | `toast.error(getErrorMessage(error))` |
+| 폼 검증 실패 | Zod + react-hook-form 자동 표시 |
+| 필드별 서버 에러 | `error.errors` 파싱 후 toast |
+| 치명적 에러 | `error.tsx` 에러 바운더리 |
+| 네트워크 에러 | toast + 재시도 안내 |
+
+**금지**: `alert()`, `confirm()`, `prompt()` 사용 금지 -> `toast` (sonner) 또는 `Dialog` 사용
diff --git a/sam-docs/frontend/v1/15-deployment.md b/sam-docs/frontend/v1/15-deployment.md
new file mode 100644
index 00000000..2d5ce0c0
--- /dev/null
+++ b/sam-docs/frontend/v1/15-deployment.md
@@ -0,0 +1,172 @@
+# 15. 배포 가이드 (Vercel)
+
+> 대상: 프론트엔드 개발자, DevOps
+> 최종 업데이트: 2026-03-20
+
+---
+
+## 목차
+
+| 번호 | 항목 |
+|------|------|
+| 15.1 | [배포 환경](#151-배포-환경) |
+| 15.2 | [환경 변수](#152-환경-변수) |
+| 15.3 | [빌드 설정](#153-빌드-설정) |
+| 15.4 | [Puppeteer 설정](#154-puppeteer-설정) |
+| 15.5 | [배포 체크리스트](#155-배포-체크리스트) |
+| 15.6 | [비용 관리](#156-비용-관리) |
+
+---
+
+## 15.1 배포 환경
+
+| 환경 | 브랜치 | URL | 용도 |
+|------|--------|-----|------|
+| Development | `develop` | localhost:3000 | 로컬 개발 |
+| Stage | `stage` | stage.xxx.com | QA/테스트 |
+| Production | `main` | app.xxx.com | 실서비스 |
+
+환경 구분은 `NEXT_PUBLIC_APP_ENV` 환경변수로 판별:
+
+```typescript
+const env = process.env.NEXT_PUBLIC_APP_ENV; // 'local' | 'development' | 'staging' | 'production'
+```
+
+---
+
+## 15.2 환경 변수
+
+### 필수 환경 변수
+
+| 변수 | 설명 | 예시 |
+|------|------|------|
+| `NEXT_PUBLIC_API_URL` | 백엔드 API 주소 | `https://api.xxx.com` |
+| `NEXT_PUBLIC_APP_ENV` | 실행 환경 | `production` |
+| `JWT_SECRET` | JWT 토큰 시크릿 | (보안) |
+
+### Vercel 설정 방법
+
+1. Vercel Dashboard -> Settings -> Environment Variables
+2. 환경별(Production/Preview/Development) 분리 설정
+3. 민감 정보(JWT_SECRET 등)는 Encrypted로 저장
+
+---
+
+## 15.3 빌드 설정
+
+### vercel.json
+
+```json
+{
+ "functions": {
+ "app/**/*.ts": {
+ "memory": 1024,
+ "maxDuration": 30
+ }
+ },
+ "regions": ["icn1"]
+}
+```
+
+| 설정 | 값 | 설명 |
+|------|-----|------|
+| memory | 1024MB | PDF 생성 등 무거운 작업 대응 |
+| maxDuration | 30초 | 함수 실행 타임아웃 |
+| regions | icn1 | 서울 리전 (한국 서비스) |
+
+### TypeScript strict mode
+
+Vercel 빌드 시 `tsc --noEmit`이 실행되므로 타입 에러가 있으면 배포 실패:
+
+```bash
+# 배포 전 로컬에서 확인
+npx tsc --noEmit
+```
+
+---
+
+## 15.4 Puppeteer 설정
+
+PDF 생성(견적서, 거래명세서 등)을 위한 Puppeteer 환경별 분기:
+
+```typescript
+// 로컬: 시스템 Chrome 사용
+// Vercel: puppeteer-core + @sparticuz/chromium (경량)
+
+const browser = await (isVercel
+ ? puppeteerCore.launch({
+ args: chromium.args,
+ executablePath: await chromium.executablePath(),
+ headless: chromium.headless,
+ })
+ : puppeteer.launch({ headless: true })
+);
+```
+
+### 패키지 구성
+
+```json
+{
+ "dependencies": {
+ "puppeteer-core": "^x.x.x",
+ "@sparticuz/chromium": "^x.x.x"
+ },
+ "devDependencies": {
+ "puppeteer": "^x.x.x"
+ }
+}
+```
+
+- `puppeteer`: 로컬 개발용 (devDependencies)
+- `puppeteer-core` + `@sparticuz/chromium`: Vercel 배포용 (dependencies)
+
+---
+
+## 15.5 배포 체크리스트
+
+### 배포 전
+
+| # | 항목 |
+|---|------|
+| 1 | `npx tsc --noEmit` 에러 없음 |
+| 2 | `npm run build` 성공 |
+| 3 | 환경 변수 Vercel에 설정 완료 |
+| 4 | 백엔드 CORS에 Vercel 도메인 추가 |
+| 5 | API URL이 올바른 환경을 가리키는지 확인 |
+
+### 배포 후
+
+| # | 항목 |
+|---|------|
+| 1 | 로그인 정상 동작 (쿠키/토큰) |
+| 2 | API 호출 정상 (CORS 에러 없음) |
+| 3 | PDF 생성 정상 (Puppeteer) |
+| 4 | 모바일 접속 확인 |
+
+### 백엔드 CORS 설정
+
+```php
+// Laravel: config/cors.php
+'allowed_origins' => [
+ 'https://your-app.vercel.app',
+ 'https://your-custom-domain.com',
+],
+```
+
+---
+
+## 15.6 비용 관리
+
+### 예상 비용 (50개 회사 기준)
+
+| 항목 | 월 비용 |
+|------|--------|
+| Serverless Functions | ~$15-20 |
+| Bandwidth | ~$5-8 |
+| 합계 | ~$22-28 |
+
+### 비용 절감 전략
+
+- **Edge Middleware**: 인증 체크 등 가벼운 로직을 Edge에서 처리 (Functions 비용 95% 절감 가능)
+- **정적 페이지 최적화**: ISR(Incremental Static Regeneration) 적용 가능한 페이지 식별
+- **이미지 최적화**: `next/image` 활용으로 Bandwidth 절감