# Vercel 배포 및 운영 가이드 (Deployment & Operations)

> **일시**: 2026-02-11
> **상태**: 배포 완료 (`insuwiki.vercel.app`)
> **목표**: InsuWiki 프로젝트의 배포 절차 및 향후 개발/운영 워크플로우 정의

---

## 1. 배포 개요 (Summary)
- **Production URL**: [https://insuwiki.vercel.app](https://insuwiki.vercel.app)
- **Frontend**: Vercel (Next.js 16)
- **Backend**: Firebase (Firestore, Functions, Auth)

---

## 2. 배포 절차 (Initial Setup - Completed)
*본 절차는 2026-02-11에 완료되었습니다.*

### 2.1. Vercel 프로젝트 설정
- **Project Name**: `insuwiki`
- **Framework Preset**: `Next.js`
- **Root Directory**: `nextapp` (필수)
- **Environment Variables**: `.env.local` 내용 복사 (단, `NEXT_PUBLIC_USE_EMULATOR=false`)
- **Server-Side Secrets**: `FIREBASE_SERVICE_ACCOUNT_KEY` (JSON string or base64) - *Required for KakaoTalk Sharing (SSR Metadata)*

### 2.2. 도메인 설정
- Vercel Settings > Domains 에서 `insuwiki.vercel.app` 설정 완료.
- Firebase Authentication > Settings > Authorized domains 에 도메인 추가 완료.

---

## 3. 개발 워크플로우 (Development Workflow)

**"개발은 로컬에서, 배포는 자동으로"**

### 3.1. 로컬 개발 (Local Development)
- **환경**: 로컬 에뮬레이터 (`localhost:3000`)
- **실행**:
  ```bash
  firebase emulators:start
  npm run dev
  ```
- **특징**: `NEXT_PUBLIC_USE_EMULATOR=true`가 적용되어 실제 데이터를 건드리지 않고 안전하게 개발 가능.

### 3.2. 운영 배포 (Production Deployment)

**방법 A: 수동 배포 (현재 사용 중)**
- **설명**: 로컬에서 Vercel CLI를 통해 직접 배포합니다. 
- **사용 이유**: 현재 Vercel 프로젝트가 Git 저장소와 자동 연동되어 있지 않거나, 로컬 환경 변수 문제 등을 우회하기 위해 사용합니다.
- **명령어 (Windows PowerShell)**:
  ```bash
  $env:CI="1"; npx vercel --prod --token vcp_6i1nycaSAGM191I5KqL5jFJwHlurRsqEWgHVISRBTDunbYaQSn2fwuIB
  ```

**방법 B: 자동 배포 (Git Integration - 권장)**
- **설명**: GitHub에 코드를 푸시하면 Vercel이 변경사항을 감지하여 자동으로 배포합니다.
- **조건**: Vercel 대시보드에서 `Settings > Git` 메뉴를 통해 GitHub 저장소(`JonghyukJeon/InsuWiki`)가 연결되어 있어야 합니다.
- **명령어**:
  ```bash
  git add .
  git commit -m "update: message"
  git push origin main
  ```

---

## 4. 트러블슈팅 (Troubleshooting)

### 4.1. 404 Not Found 에러
- **원인**: `Root Directory`가 `nextapp`으로 설정되지 않음.
- **해결**: Settings > Build and Deployment > Root Directory에서 `nextapp` 선택 후 Redeploy.

### 4.2. 로그인 실패 (Firebase Error)
- **원인**: 배포된 도메인이 Firebase 승인 목록에 없음.
- **해결**: Firebase Console > Authentication > Authorized domains에 `insuwiki.vercel.app` 추가.

---
*Generated with [Claude Code](https://claude.com/claude-code)*