sam-docs/guides/production-env-sync.md

# 운영 전환 시 .env 동기화 절차

> **작성일**: 2026-02-21
> **상태**: 설계 확정
> **최종 업데이트**: 2026-02-23

---

## 1. 개요

### 1.1 목적

SAM 프로젝트는 MNG과 API가 **독립적인 `.env` 파일**을 사용하되, **공유 DB**를 통해 일부 설정을 공유한다.
테스트 → 운영 전환 시 양쪽 환경 변수를 정확히 동기화해야 서비스 장애를 방지할 수 있다.

### 1.2 핵심 원칙

- MNG과 API는 **각각 독립된 `.env`** 파일을 보유
- **모든 API 키는 `.env`에서 관리** (DB `ai_configs` 테이블 사용하지 않음)
- 바로빌 설정은 **DB 우선, `.env` 폴백** 구조
- 동기화 필수 항목과 프로젝트 전용 항목을 명확히 구분
- 각 프로젝트에 `.env.example` 파일로 필요한 키를 문서화

### 1.3 `.env.example` 파일

| 프로젝트 | 파일 | 설명 |
|---------|------|------|
| MNG | `mng/.env.example` | MNG 프로젝트 전체 환경 변수 템플릿 |
| API | `api/.env.example` | API 프로젝트 전체 환경 변수 템플릿 |

> 새 서버 설정 시 `.env.example`을 `.env`로 복사한 후 실제 값을 입력한다.

---

## 2. 설정 관리 아키텍처

### 2.1 전체 구조

```
┌──────────────────────────────────────────┐
│           공유 DB (samdb)                  │
│  barobill_configs   → 바로빌 CERTKEY      │
│  barobill_members   → 테넌트별 서버 모드   │
│  barobill_settings  → 테넌트별 연동 설정   │
└──────────────┬───────────────────────────┘
               │ (양쪽 모두 직접 읽음)
    ┌──────────┴──────────┐
    │                     │
┌───┴──────┐      ┌──────┴───┐
│ MNG .env │      │ API .env │
│ (독립)   │      │ (독립)   │
└──────────┘      └──────────┘
```

### 2.2 API 키 관리 방식 (2026-02-23 변경)

```
변경 전: DB ai_configs 테이블 → .env 폴백
변경 후: .env 전용 (ai_configs 테이블 미사용)
```

모든 외부 API 키(Gemini, Claude, Notion, GCS)는 `.env`에서 직접 관리한다.
`AiConfig` 모델의 정적 메서드(`getActiveGemini()` 등)가 `config('services.*')`를 읽어 인스턴스를 생성하므로, 기존 서비스 코드 변경 없이 동작한다.

### 2.3 설정 로드 우선순위 (바로빌)

```
1순위: DB barobill_members.server_mode  (테넌트별 모드)
  ↓
2순위: DB barobill_configs 테이블       (is_active 환경 설정)
  ↓
3순위: .env BAROBILL_TEST_MODE          (폴백)
```

---

## 3. 동기화 필수 항목

> **경고: 아래 항목은 MNG과 API 양쪽에서 동일한 값이어야 한다.**

### 3.1 공유 API 키 (양쪽 동일 값 필수)

| 환경 변수 | MNG `.env` | API `.env` | 설명 |
|-----------|-----------|-----------|------|
| `GEMINI_API_KEY` | ✅ 설정됨 | ✅ 설정됨 | Gemini AI API 키 |
| `GEMINI_MODEL` | ✅ `gemini-2.0-flash` | ✅ `gemini-2.0-flash` | Gemini 모델 |
| `GEMINI_BASE_URL` | ✅ 설정됨 | ✅ 설정됨 | Gemini API URL |
| `GEMINI_PROJECT_ID` | ✅ `codebridge-chatbot` | ✅ `codebridge-chatbot` | GCP 프로젝트 ID |
| `VERTEX_AI_PROJECT_ID` | ✅ 설정됨 | ✅ 설정됨 | Vertex AI 프로젝트 |
| `VERTEX_AI_LOCATION` | ✅ `us-central1` | ✅ `us-central1` | Vertex AI 리전 |
| `GOOGLE_STORAGE_BUCKET` | ✅ 설정됨 | ✅ 설정됨 | GCS 버킷 이름 |

### 3.2 내부 통신 키

| 환경 변수 | MNG `.env` | API `.env` | 설명 |
|-----------|-----------|-----------|------|
| `INTERNAL_EXCHANGE_SECRET` | ✅ 설정됨 | ✅ 설정됨 | HMAC 서버 간 검증 |

> **경고: 불일치 시 MNG → API HTTP 호출이 인증 실패한다.**

### 3.3 바로빌 SOAP API

| 환경 변수 | MNG `.env` | API `.env` | 설명 |
|-----------|-----------|-----------|------|
| `BAROBILL_CERT_KEY_TEST` | ⚠️ 현재 미설정 | ✅ 설정됨 | 테스트 CERTKEY |
| `BAROBILL_CERT_KEY_PROD` | ⚠️ 현재 미설정 | ✅ 설정됨 | 운영 CERTKEY |
| `BAROBILL_CORP_NUM` | ⚠️ 현재 미설정 | ✅ 설정됨 | 파트너 사업자번호 |
| `BAROBILL_TEST_MODE` | ⚠️ 현재 미설정 | `true` | 테스트/운영 전환 플래그 |

> **참고**: MNG는 **DB(`barobill_configs`)를 우선 참조**하므로 현재 정상 동작한다.

### 3.4 공유 DB 접속 정보

| 환경 변수 | 동기화 필수 | 설명 |
|-----------|-----------|------|
| `DB_HOST` | ✅ | 동일 DB 서버 |
| `DB_PORT` | ✅ | 동일 포트 |
| `DB_DATABASE` | ✅ | 동일 데이터베이스 |
| `DB_USERNAME` / `DB_PASSWORD` | ✅ | 접속 계정 |

---

## 4. 프로젝트 전용 항목 (독립 관리)

### 4.1 MNG 전용

| 환경 변수 | 설명 | 비고 |
|-----------|------|------|
| `API_BASE_URL` | API 서버 URL | 운영: `https://api.codebridge-x.com` |
| `FLOW_TESTER_API_KEY` | API 테스터 키 | API의 `api_keys` 테이블과 일치 필요 |
| `MENU_SYNC_API_KEY` | 메뉴 동기화 키 | MNG 전용 |
| `NOTION_API_KEY` | Notion API 키 | MNG에서만 사용 |
| `NOTION_VERSION` | Notion API 버전 | MNG에서만 사용 |
| `KMA_SERVICE_KEY` | 기상청 API 키 | MNG에서만 사용 |

### 4.2 API 전용

| 환경 변수 | 설명 | 비고 |
|-----------|------|------|
| `CLAUDE_API_KEY` | Claude AI API 키 | API에서만 사용 |
| `SANCTUM_*` | 토큰 만료 설정 | API 인증 전용 |
| `LOG_SLACK_WEBHOOK_URL` | Slack 로그 알림 | API 전용 |
| `CHANDJ_DB_*` | 레거시 DB 접속 | API에서만 사용 |
| `BAROBILL_*` | 바로빌 SOAP API | API 중심 (MNG는 DB 폴백) |
| `L5_SWAGGER_*` | Swagger 문서 설정 | API 전용 |

### 4.3 양쪽 독립 설정 (동일 서비스, 경로가 다름)

| 환경 변수 | 주의사항 |
|-----------|---------|
| `GOOGLE_APPLICATION_CREDENTIALS` | 컨테이너 내부 **파일 경로**가 다르므로 각자 설정 |
| `FCM_SA_PATH` | 컨테이너 내부 **파일 경로**가 다르므로 각자 설정 |

---

## 5. 운영 전환 절차

### 5.1 사전 준비 체크리스트

```
□ 바로빌 운영 CERTKEY 발급 완료
□ 바로빌 운영 서버 사업자번호 등록 완료
□ Google 서비스 어카운트 운영 경로 확인
□ Firebase 서비스 어카운트 운영 경로 확인
□ DB 백업 완료
□ .env.example 참조하여 누락 키 없는지 확인
```

### 5.2 Step 1: DB 설정 전환 (바로빌)

> **가장 중요한 단계.** MNG과 API 모두 DB를 우선 참조하므로 DB 설정 변경이 핵심이다.

**방법 A: phpMyAdmin에서 직접 수정**

```sql
-- 1. 현재 설정 확인
SELECT id, name, environment, cert_key, corp_num, base_url, is_active
FROM barobill_configs;

-- 2. 테스트 서버 비활성화
UPDATE barobill_configs
SET is_active = 0
WHERE environment = 'test';

-- 3. 운영 서버 활성화 (없으면 INSERT)
UPDATE barobill_configs
SET is_active = 1,
    cert_key = '운영_CERTKEY_값',
    corp_num = '운영_사업자번호',
    base_url = 'https://ws.baroservice.com'
WHERE environment = 'production';
```

**방법 B: tinker로 수정**

```bash
docker exec sam-api-1 php artisan tinker --execute="
use App\Models\Tenants\BarobillConfig;

// 테스트 비활성화
BarobillConfig::where('environment', 'test')->update(['is_active' => false]);

// 운영 활성화
BarobillConfig::updateOrCreate(
    ['environment' => 'production'],
    [
        'name' => '운영서버',
        'cert_key' => '운영_CERTKEY_값',
        'corp_num' => '운영_사업자번호',
        'base_url' => 'https://ws.baroservice.com',
        'is_active' => true,
    ]
);
"
```

### 5.3 Step 2: 테넌트별 서버 모드 전환

```sql
-- 모든 테넌트를 운영 모드로 전환
UPDATE barobill_members
SET server_mode = 'production'
WHERE server_mode = 'test';
```

### 5.4 Step 3: API `.env` 수정

```bash
# /home/webservice/api/.env (서버)

# 변경 전
BAROBILL_TEST_MODE=true

# 변경 후
BAROBILL_TEST_MODE=false
```

### 5.5 Step 4: MNG `.env` 수정 및 누락 항목 추가

```bash
# /home/webservice/mng/.env (서버)에 추가/수정

# ─── 바로빌 SOAP API (누락 항목 추가) ───
BAROBILL_CERT_KEY_TEST=<테스트_CERTKEY>
BAROBILL_CERT_KEY_PROD=<운영_CERTKEY>
BAROBILL_CORP_NUM=<사업자번호>
BAROBILL_TEST_MODE=false
```

### 5.6 Step 5: 캐시 클리어 및 재시작

```bash
# Docker 환경
docker exec sam-api-1 php artisan config:clear && docker exec sam-api-1 php artisan cache:clear
docker exec sam-mng-1 php artisan config:clear && docker exec sam-mng-1 php artisan cache:clear

# bare-metal 환경
cd /home/webservice/api && php artisan config:clear && php artisan cache:clear
cd /home/webservice/mng && php artisan config:clear && php artisan cache:clear
```

---

## 6. 전환 후 검증 체크리스트

### 6.1 바로빌 API 검증

```
□ MNG 세금계산서 발행 페이지 → 서버 모드 "운영" 표시 확인
□ 바로빌 잔액 조회 정상 응답 확인
□ 홈택스 매출/매입 조회 정상 확인
□ 세금계산서 테스트 발행 → 국세청 전송 확인
□ API 바로빌 엔드포인트 정상 응답 확인
```

### 6.2 외부 서비스 검증

```
□ Gemini AI 음성 어시스턴트 동작 확인 (MNG)
□ Notion 검색 AI 동작 확인 (MNG)
□ FCM 푸시 알림 전송 확인 (MNG/API)
□ Google STT/GCS 파일 업로드 확인
□ MNG → API HTTP 호출 인증 성공 확인
```

### 6.3 롤백 절차

문제 발생 시 즉시 테스트 모드로 복귀:

```bash
# 1. DB 복구
UPDATE barobill_configs SET is_active = 1 WHERE environment = 'test';
UPDATE barobill_configs SET is_active = 0 WHERE environment = 'production';
UPDATE barobill_members SET server_mode = 'test';

# 2. .env 복구
# API: BAROBILL_TEST_MODE=true
# MNG: BAROBILL_TEST_MODE=true

# 3. 캐시 클리어
docker exec sam-api-1 php artisan config:clear
docker exec sam-mng-1 php artisan config:clear
```

---

## 관련 문서

- [Docker 환경 구성](../specs/docker-setup.md)
- [시스템 아키텍처](../architecture/system-overview.md)
- [바로빌 카카오톡 연동](../features/barobill-kakaotalk/README.md)

---

**최종 업데이트**: 2026-02-23