---
name: env-switch
description: Safely switch between local and production environments with validation and step-by-step guidance. Use when user wants to "switch to local", "change to production", "separate environments", or "toggle between databases". Prevents accidental production data access.
allowed-tools: [Read, Grep]
---

# Environment Switcher

로컬 개발 환경과 프로덕션 환경 간 안전한 전환을 도와주는 Skill입니다.

## 🎯 자동 실행 트리거

다음 상황에서 **자동으로 실행**:
- "로컬로 전환" / "Switch to local"
- "프로덕션으로 전환" / "Switch to production"
- "환경 분리" / "Separate environments"
- "주석 처리 말고 자동으로" (지금까지 겪은 문제!)
- "로컬/프로덕션 전환이 번거로워"

## 🔍 현재 환경 분석

### 1. 현재 .env 설정 확인

```bash
# 현재 환경 확인
grep -E "^(APP_ENV|APP_NAME|DB_CONNECTION|SESSION_DRIVER|CACHE_STORE)=" .env
```

**환경 판별**:
- `APP_ENV=local` + `DB_CONNECTION=pgsql_local` → **로컬 개발 환경** ✅
- `APP_ENV=production` + `DB_CONNECTION=pgsql` → **프로덕션 환경** ⚠️
- 혼합 상태 → **잘못된 설정** ❌

## 📋 환경별 완벽한 설정

### 로컬 개발 환경 (.env)

**Git에 커밋하지 않음** (.gitignore에 포함됨)

```env
# Application
APP_NAME="YKP ERP (Local)"
APP_ENV=local
APP_DEBUG=true
APP_URL=http://127.0.0.1:8000

# Local PostgreSQL Database
DB_CONNECTION=pgsql_local
DB_HOST_LOCAL=localhost
DB_PORT_LOCAL=5432
DB_DATABASE_LOCAL=ykp_dashboard_local
DB_USERNAME_LOCAL=postgres
DB_PASSWORD_LOCAL=1234  # 본인 로컬 비밀번호

# File-based drivers (빠른 개발)
SESSION_DRIVER=file
SESSION_LIFETIME=120
CACHE_STORE=file
QUEUE_CONNECTION=sync

# Logging
LOG_CHANNEL=stack
LOG_LEVEL=debug

# Feature Flags (로컬 테스트)
FEATURE_EXCEL_INPUT=true
FEATURE_ADVANCED_REPORTS=true
FEATURE_UI_V2=false
FEATURE_SUPABASE_ENHANCED=false
```

### 프로덕션 환경 (Railway)

**Railway 환경변수 사용** (.env 파일 무시됨!)

```env
# Application
APP_NAME="YKP ERP"
APP_ENV=production
APP_DEBUG=false
APP_URL=${RAILWAY_PUBLIC_DOMAIN}

# Supabase PostgreSQL (Connection Pooler)
DB_CONNECTION=pgsql
DB_HOST=aws-1-ap-southeast-1.pooler.supabase.com
DB_PORT=5432
DB_DATABASE=postgres
DB_USERNAME=postgres.qwafwqxdcfpqqwpmphkm
DB_PASSWORD=<Railway Secrets에 저장>
DB_SSLMODE=require

# Database drivers (분산 환경)
SESSION_DRIVER=database
CACHE_STORE=database
QUEUE_CONNECTION=database

# Logging (Railway stderr)
LOG_CHANNEL=stderr
LOG_LEVEL=error

# Feature Flags (프로덕션)
FEATURE_EXCEL_INPUT=true
FEATURE_ADVANCED_REPORTS=true
FEATURE_UI_V2=false
FEATURE_SUPABASE_ENHANCED=true
```

## 🔄 전환 절차

### 시나리오 1: 프로덕션 → 로컬 전환

**사용자 요청**: "로컬 개발 환경으로 돌아가고 싶어요"

**안내 절차**:

1. **현재 상태 확인**:
   ```bash
   grep -E "^(APP_ENV|DB_CONNECTION)=" .env
   ```
   → `APP_ENV=production` 감지 시 경고!

2. **경고 메시지**:
   > 🚨 **프로덕션 설정 감지!**
   >
   > 현재 `.env` 파일이 프로덕션 설정을 사용하고 있습니다.
   > 로컬 개발용으로 전환하시겠습니까?
   >
   > ⚠️ 주의: 프로덕션은 Railway 환경변수로만 관리됩니다!

3. **로컬 설정 템플릿 제공**:
   > ✅ **로컬 개발 환경 설정**
   >
   > `.env` 파일을 다음과 같이 수정하세요:
   > ```env
   > APP_NAME="YKP ERP (Local)"
   > APP_ENV=local
   > APP_DEBUG=true
   > APP_URL=http://127.0.0.1:8000
   >
   > DB_CONNECTION=pgsql_local
   > DB_HOST_LOCAL=localhost
   > DB_DATABASE_LOCAL=ykp_dashboard_local
   > DB_USERNAME_LOCAL=postgres
   > DB_PASSWORD_LOCAL=1234
   >
   > SESSION_DRIVER=file
   > CACHE_STORE=file
   > QUEUE_CONNECTION=sync
   > ```
   >
   > 또는 `.env.example` 파일을 복사:
   > ```bash
   > cp .env.example .env
   > php artisan key:generate
   > ```

4. **후속 조치 안내**:
   ```
   📋 다음 단계:

   1. PostgreSQL 서버 시작:
      postgresql-17.6-2-windows-x64-binaries/bin/pg_ctl.exe -D postgresql-data start

   2. 캐시 클리어:
      php artisan optimize:clear

   3. 서버 재시작:
      php artisan serve

   4. 테스트 로그인:
      http://127.0.0.1:8000
      계정: admin@ykp.com / password
   ```

### 시나리오 2: 로컬 → 프로덕션 배포 준비

**사용자 요청**: "Railway에 배포하려고 하는데, 프로덕션 설정 확인해줘"

**안내 절차**:

1. **로컬 .env 상태 확인**:
   > ✅ **로컬 환경 감지**
   >
   > 현재 `.env` 파일: 로컬 개발 설정 (정상)
   > Git에 커밋되지 않음 (`.gitignore`로 보호됨)

2. **Railway 환경변수 체크리스트 제공**:
   > 📋 **Railway 배포 체크리스트**
   >
   > Railway Dashboard → Your Service → Variables에 다음 설정:
   >
   > **필수 환경변수**:
   > - [ ] `APP_NAME="YKP ERP"`
   > - [ ] `APP_ENV=production`
   > - [ ] `APP_KEY=<php artisan key:generate --show 출력>`
   > - [ ] `APP_DEBUG=false`
   > - [ ] `APP_URL=${RAILWAY_PUBLIC_DOMAIN}`
   >
   > **Supabase DB (Railway Secrets에 저장)**:
   > - [ ] `DB_CONNECTION=pgsql`
   > - [ ] `DB_HOST=aws-1-ap-southeast-1.pooler.supabase.com`
   > - [ ] `DB_PORT=5432`
   > - [ ] `DB_DATABASE=postgres`
   > - [ ] `DB_USERNAME=postgres.qwafwqxdcfpqqwpmphkm`
   > - [ ] `DB_PASSWORD=<Supabase 비밀번호>` 🔒
   > - [ ] `DB_SSLMODE=require`
   >
   > **Session/Cache/Queue**:
   > - [ ] `SESSION_DRIVER=database`
   > - [ ] `CACHE_STORE=database`
   > - [ ] `QUEUE_CONNECTION=database`
   >
   > **Logging**:
   > - [ ] `LOG_CHANNEL=stderr`
   > - [ ] `LOG_LEVEL=error`

3. **보안 경고**:
   > 🔒 **보안 주의사항**
   >
   > ❌ `.env` 파일을 Git에 커밋하지 마세요!
   > ✅ Railway 환경변수에서 관리
   > ✅ `DB_PASSWORD`는 Railway Secrets에 저장
   > ✅ Supabase 백업 생성 후 배포

## 🚨 잘못된 설정 감지

### 혼합 설정 (가장 위험!)

**증상**: `APP_ENV=local`인데 `DB_CONNECTION=pgsql` (Supabase)

**경고 메시지**:
```
🚨 위험: 환경 설정 불일치!

현재 설정:
- APP_ENV: local (로컬 개발 모드)
- DB_CONNECTION: pgsql (Supabase 프로덕션 DB!)

⚠️ 이 상태로 작업하면 프로덕션 데이터에 영향을 줄 수 있습니다!

즉시 수정:
APP_ENV=local → DB_CONNECTION=pgsql_local 사용해야 함!

.env 파일 수정:
DB_CONNECTION=pgsql_local
DB_DATABASE_LOCAL=ykp_dashboard_local

수정 후:
php artisan optimize:clear
```

## 💡 환경 분리 베스트 프랙티스

### 절대 규칙

1. **로컬 개발**:
   - ✅ `.env` 파일 사용 (Git ignored)
   - ✅ `APP_ENV=local`
   - ✅ `DB_CONNECTION=pgsql_local`
   - ✅ File-based drivers (session/cache/queue)

2. **프로덕션 (Railway)**:
   - ✅ Railway 환경변수 사용
   - ✅ `.env` 파일 무시됨
   - ✅ `APP_ENV=production`
   - ✅ `DB_CONNECTION=pgsql` (Supabase)
   - ✅ Database drivers (분산 환경)

3. **금지 사항**:
   - ❌ `.env` 파일을 Git에 커밋
   - ❌ 주석 처리로 환경 전환
   - ❌ `.env.local` 사용 (Laravel 작동 안함!)
   - ❌ 프로덕션 DB를 로컬에서 직접 연결

### 왜 `.env.local`은 안되나?

**문제 발견 과정** (지금까지 대화 기반):
```
시도 1: .env에 프로덕션 설정, .env.local에 로컬 설정
결과: ❌ Laravel이 .env.local 무시함

이유: Laravel은 APP_ENV=production일 때 .env.local을 로드하지 않음
→ 닭이 먼저냐 달걀이 먼저냐 문제!
```

**올바른 해결책**:
- 로컬: `.env` (Git ignored)
- 프로덕션: Railway 환경변수 (파일 아님!)

## 📊 전환 완료 보고서

전환 완료 후 다음 형식으로 보고:

```
✅ 환경 전환 완료

이전 환경: production (Supabase)
새 환경: local (localhost PostgreSQL)

변경된 설정:
- APP_ENV: production → local
- DB_CONNECTION: pgsql → pgsql_local
- SESSION_DRIVER: database → file
- CACHE_STORE: database → file

✅ 캐시 클리어: 완료
✅ 환경 검증: 통과

📋 다음 단계:
1. 서버 재시작: php artisan serve
2. 로그인 테스트: http://127.0.0.1:8000
3. DB 연결 확인: admin@ykp.com / password

💡 프로덕션 배포 시:
- Railway 환경변수 사용 (`.env` 파일 무시)
- CLAUDE.md "Railway Production Environment" 섹션 참조
```

## 🎓 학습 내용 요약

이 Skill을 통해 배운 핵심:

1. **Laravel 환경 파일 우선순위**:
   - `.env` > `.env.local` (단, production 모드에서는 .env.local 무시!)
   - Railway 환경변수 > `.env` 파일

2. **환경별 드라이버 전략**:
   - 로컬: File-based (빠름, 독립적)
   - 프로덕션: Database-based (분산 환경)

3. **Git 관리 전략**:
   - `.env` → Git ignored (로컬 비밀정보 포함)
   - `.env.example` → Git tracked (템플릿)
   - `.env.production.example` → Git tracked (가이드)
   - Railway 환경변수 → 플랫폼 관리

**다음에 환경 전환 필요 시**:
1. 절대 주석 처리 금지!
2. `.env` 파일 전체 교체
3. 캐시 클리어 (`php artisan optimize:clear`)
4. 서버 재시작