docs: [guides] .env 동기화 문서 업데이트

- API 키 관리 방식 변경 반영 (DB → .env 전환)
- 공유 API 키 동기화 항목 추가 (Gemini, Vertex AI 등)
- .env.example 참조 안내 추가
- 누락 항목 현황 최신화

guides/production-env-sync.md

@@ -2,6 +2,7 @@
 
 > **작성일**: 2026-02-21
 > **상태**: 설계 확정
+> **최종 업데이트**: 2026-02-23
 
 ---
 
@@ -15,8 +16,19 @@ SAM 프로젝트는 MNG과 API가 **독립적인 `.env` 파일**을 사용하되
 ### 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`로 복사한 후 실제 값을 입력한다.
 
 ---
 
@@ -40,7 +52,17 @@ SAM 프로젝트는 MNG과 API가 **독립적인 `.env` 파일**을 사용하되
 └──────────┘      └──────────┘
 ```
 
-### 2.2 설정 로드 우선순위 (바로빌)
+### 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  (테넌트별 모드)
@@ -56,7 +78,27 @@ SAM 프로젝트는 MNG과 API가 **독립적인 `.env` 파일**을 사용하되
 
 > **경고: 아래 항목은 MNG과 API 양쪽에서 동일한 값이어야 한다.**
 
-### 3.1 바로빌 SOAP 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` | 설명 |
 |-----------|-----------|-----------|------|
@@ -65,17 +107,9 @@ SAM 프로젝트는 MNG과 API가 **독립적인 `.env` 파일**을 사용하되
 | `BAROBILL_CORP_NUM` | ⚠️ 현재 미설정 | ✅ 설정됨 | 파트너 사업자번호 |
 | `BAROBILL_TEST_MODE` | ⚠️ 현재 미설정 | `true` | 테스트/운영 전환 플래그 |
 
-> **참고**: MNG의 `.env`에 바로빌 항목이 누락되어 있지만, MNG는 **DB(`barobill_configs`)를 우선 참조**하므로 현재 정상 동작한다. 단, DB에 설정이 없는 경우 `.env` 폴백이 작동하지 않는다.
+> **참고**: MNG는 **DB(`barobill_configs`)를 우선 참조**하므로 현재 정상 동작한다.
 
-### 3.2 내부 통신 키
-
-| 환경 변수 | MNG `.env` | API `.env` | 설명 |
-|-----------|-----------|-----------|------|
-| `INTERNAL_EXCHANGE_SECRET` | ⚠️ 현재 미설정 | ✅ 설정됨 | HMAC 서버 간 검증 |
-
-> **경고: 불일치 시 MNG → API HTTP 호출이 인증 실패한다.**
-
-### 3.3 공유 DB 접속 정보
+### 3.4 공유 DB 접속 정보
 
 | 환경 변수 | 동기화 필수 | 설명 |
 |-----------|-----------|------|
@@ -92,10 +126,12 @@ SAM 프로젝트는 MNG과 API가 **독립적인 `.env` 파일**을 사용하되
 
 | 환경 변수 | 설명 | 비고 |
 |-----------|------|------|
-| `API_BASE_URL` | API 서버 URL | 운영: `https://api.sam.kr` |
+| `API_BASE_URL` | API 서버 URL | 운영: `https://api.codebridge-x.com` |
 | `FLOW_TESTER_API_KEY` | API 테스터 키 | API의 `api_keys` 테이블과 일치 필요 |
 | `MENU_SYNC_API_KEY` | 메뉴 동기화 키 | MNG 전용 |
-| `CHANDJ_DB_*` | 레거시 DB 접속 | MNG에서만 사용 |
+| `NOTION_API_KEY` | Notion API 키 | MNG에서만 사용 |
+| `NOTION_VERSION` | Notion API 버전 | MNG에서만 사용 |
+| `KMA_SERVICE_KEY` | 기상청 API 키 | MNG에서만 사용 |
 
 ### 4.2 API 전용
 
@@ -104,17 +140,16 @@ SAM 프로젝트는 MNG과 API가 **독립적인 `.env` 파일**을 사용하되
 | `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 양쪽 독립 설정 (동일 서비스, 각자 관리)
+### 4.3 양쪽 독립 설정 (동일 서비스, 경로가 다름)
 
-| 환경 변수 | MNG 용도 | API 용도 |
-|-----------|---------|---------|
-| `GEMINI_API_KEY` | 음성 어시스턴트, OCR | AI 리포트 생성 |
-| `VERTEX_AI_*` | 영상 생성 | 영상 생성 |
-| `GOOGLE_APPLICATION_CREDENTIALS` | STT, GCS | STT, GCS |
-| `FCM_*` | 푸시 알림 | 푸시 알림 |
-
-> **참고**: 같은 키를 사용해도 무방하지만, 서비스 어카운트 **파일 경로**가 다르므로 주의
+| 환경 변수 | 주의사항 |
+|-----------|---------|
+| `GOOGLE_APPLICATION_CREDENTIALS` | 컨테이너 내부 **파일 경로**가 다르므로 각자 설정 |
+| `FCM_SA_PATH` | 컨테이너 내부 **파일 경로**가 다르므로 각자 설정 |
 
 ---
 
@@ -128,6 +163,7 @@ SAM 프로젝트는 MNG과 API가 **독립적인 `.env` 파일**을 사용하되
 □ Google 서비스 어카운트 운영 경로 확인
 □ Firebase 서비스 어카운트 운영 경로 확인
 □ DB 백업 완료
+□ .env.example 참조하여 누락 키 없는지 확인
 ```
 
 ### 5.2 Step 1: DB 설정 전환 (바로빌)
@@ -190,7 +226,7 @@ WHERE server_mode = 'test';
 ### 5.4 Step 3: API `.env` 수정
 
 ```bash
-# /home/aweso/sam/api/.env
+# /home/webservice/api/.env (서버)
 
 # 변경 전
 BAROBILL_TEST_MODE=true
@@ -202,48 +238,25 @@ BAROBILL_TEST_MODE=false
 ### 5.5 Step 4: MNG `.env` 수정 및 누락 항목 추가
 
 ```bash
-# /home/aweso/sam/mng/.env 에 추가/수정
+# /home/webservice/mng/.env (서버)에 추가/수정
 
 # ─── 바로빌 SOAP API (누락 항목 추가) ───
 BAROBILL_CERT_KEY_TEST=<테스트_CERTKEY>
 BAROBILL_CERT_KEY_PROD=<운영_CERTKEY>
 BAROBILL_CORP_NUM=<사업자번호>
 BAROBILL_TEST_MODE=false
-
-# ─── 내부 통신 키 (누락 항목 추가) ───
-INTERNAL_EXCHANGE_SECRET=k8sJ2mN4pQ7rT9wX3yB6cF1hL5vZ0aE8
 ```
 
-### 5.6 Step 5: Google 서비스 어카운트 경로 통일
-
-| 프로젝트 | 현재 경로 (레거시) | 권장 경로 |
-|---------|-----------------|----------|
-| MNG | `/var/www/sales/apikey/` | `/var/www/mng/apikey/` |
-| API | `/var/www/mng/apikey/` | `/var/www/mng/apikey/` (유지) |
+### 5.6 Step 5: 캐시 클리어 및 재시작
 
 ```bash
-# MNG .env 수정 (레거시 경로 → 통일 경로)
-# 변경 전
-GOOGLE_APPLICATION_CREDENTIALS=/var/www/sales/apikey/google_service_account.json
+# 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
 
-# 변경 후
-GOOGLE_APPLICATION_CREDENTIALS=/var/www/mng/apikey/google_service_account.json
-```
-
-### 5.7 Step 6: 캐시 클리어 및 재시작
-
-```bash
-# API 캐시 클리어
-docker exec sam-api-1 php artisan config:clear
-docker exec sam-api-1 php artisan cache:clear
-
-# MNG 캐시 클리어
-docker exec sam-mng-1 php artisan config:clear
-docker exec sam-mng-1 php artisan cache:clear
-
-# 서버 환경에서는
-ssh sam-server "cd /home/webservice/api && php artisan config:clear && php artisan cache:clear"
-ssh sam-server "cd /home/webservice/mng && php artisan config:clear && 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
 ```
 
 ---
@@ -264,6 +277,7 @@ ssh sam-server "cd /home/webservice/mng && php artisan config:clear && php artis
 
 ```
 □ Gemini AI 음성 어시스턴트 동작 확인 (MNG)
+□ Notion 검색 AI 동작 확인 (MNG)
 □ FCM 푸시 알림 전송 확인 (MNG/API)
 □ Google STT/GCS 파일 업로드 확인
 □ MNG → API HTTP 호출 인증 성공 확인
@@ -290,22 +304,6 @@ docker exec sam-mng-1 php artisan config:clear
 
 ---
 
-## 7. MNG `.env` 현재 누락 항목 요약
-
-> **경고: 현재 MNG `.env`에 아래 항목이 누락되어 있다. DB 폴백으로 동작하지만, 안정성을 위해 추가를 권장한다.**
-
-| 환경 변수 | 상태 | 위험도 | 설명 |
-|-----------|------|--------|------|
-| `BAROBILL_CERT_KEY_TEST` | ❌ 누락 | 🟡 중요 | DB 폴백 시 빈값 |
-| `BAROBILL_CERT_KEY_PROD` | ❌ 누락 | 🟡 중요 | DB 폴백 시 빈값 |
-| `BAROBILL_CORP_NUM` | ❌ 누락 | 🟡 중요 | DB 폴백 시 빈값 |
-| `BAROBILL_TEST_MODE` | ❌ 누락 | 🟡 중요 | 기본값 `true` 사용 중 |
-| `INTERNAL_EXCHANGE_SECRET` | ❌ 누락 | 🔴 필수 | 서버 간 HMAC 검증 실패 가능 |
-| `GEMINI_API_KEY` | 빈값 | 🟡 중요 | 음성 어시스턴트 미작동 |
-| `FCM_PROJECT_ID` | 빈값 | 🟡 중요 | 푸시 알림 미작동 |
-
----
-
 ## 관련 문서
 
 - [Docker 환경 구성](../specs/docker-setup.md)
@@ -314,4 +312,4 @@ docker exec sam-mng-1 php artisan config:clear
 
 ---
 
-**최종 업데이트**: 2026-02-21
+**최종 업데이트**: 2026-02-23