Add PostgreSQL setup guide for data persistence

POSTGRESQL_SETUP_GUIDE.md

@@ -0,0 +1,170 @@
+# PostgreSQL 설정 가이드
+
+현재 SQLite를 사용 중이며, 컨테이너 재시작 시 데이터가 삭제될 수 있습니다. PostgreSQL로 전환하면 데이터가 영구적으로 보존됩니다.
+
+## 무료 PostgreSQL 서비스 선택
+
+### 1. Supabase (권장)
+- **URL**: https://supabase.com/
+- **무료 티어**: 500MB 데이터베이스, 자동 백업
+- **장점**: 사용하기 쉬움, 자동 백업, 대시보드 제공
+
+### 2. Neon
+- **URL**: https://neon.tech/
+- **무료 티어**: 3GB 데이터베이스, 서버리스
+- **장점**: 빠른 성능, 자동 스케일링
+
+### 3. Railway
+- **URL**: https://railway.app/
+- **무료 티어**: $5 크레딧/월
+- **장점**: 간단한 설정, 다양한 서비스 통합
+
+## Supabase 설정 방법 (예시)
+
+### 1. Supabase 프로젝트 생성
+
+1. https://supabase.com/ 접속 및 로그인
+2. "New Project" 클릭
+3. 프로젝트 정보 입력:
+   - **Name**: 원하는 프로젝트 이름
+   - **Database Password**: 강력한 비밀번호 생성 (저장해두세요!)
+   - **Region**: 가장 가까운 지역 선택
+4. "Create new project" 클릭 (약 2분 소요)
+
+### 2. 연결 정보 확인
+
+프로젝트 생성 후:
+
+1. **Settings** > **Database** 메뉴로 이동
+2. **Connection string** 섹션에서 **URI** 복사
+   - 형식: `postgresql://postgres:[YOUR-PASSWORD]@db.xxxxx.supabase.co:5432/postgres`
+   - `[YOUR-PASSWORD]`를 실제 비밀번호로 교체
+
+### 3. Hugging Face Spaces에 환경 변수 설정
+
+1. Hugging Face Spaces 페이지로 이동
+2. **Settings** 탭 클릭
+3. **Repository secrets** 섹션으로 스크롤
+4. **New secret** 클릭
+5. 다음 정보 입력:
+   - **Key**: `DATABASE_URL`
+   - **Value**: Supabase에서 복사한 연결 문자열 (비밀번호 포함)
+     ```
+     postgresql://postgres:your_password@db.xxxxx.supabase.co:5432/postgres
+     ```
+6. **Add secret** 클릭
+
+### 4. Spaces 재빌드
+
+환경 변수를 설정하면 Spaces가 자동으로 재빌드됩니다 (약 2-5분 소요).
+
+### 5. 연결 확인
+
+재빌드 완료 후:
+
+1. 브라우저에서 다음 URL 접속:
+   ```
+   https://wiizm-soyailabs.hf.space/api/admin/database/status
+   ```
+2. 응답 확인:
+   ```json
+   {
+       "connected": true,
+       "type": "PostgreSQL",  // ✅ PostgreSQL 확인
+       "version": "PostgreSQL 15.x...",
+       "config_count": 1,
+       "user_count": 1
+   }
+   ```
+
+## Neon 설정 방법 (예시)
+
+### 1. Neon 프로젝트 생성
+
+1. https://neon.tech/ 접속 및 로그인
+2. "Create a project" 클릭
+3. 프로젝트 정보 입력:
+   - **Name**: 원하는 프로젝트 이름
+   - **Region**: 가장 가까운 지역 선택
+4. "Create project" 클릭
+
+### 2. 연결 정보 확인
+
+프로젝트 생성 후:
+
+1. 프로젝트 대시보드에서 **Connection string** 복사
+   - 형식: `postgresql://user:password@ep-xxxxx.region.aws.neon.tech/neondb`
+   - 또는 **Connection Details**에서 개별 정보 확인
+
+### 3. Hugging Face Spaces에 환경 변수 설정
+
+1. Hugging Face Spaces > Settings > Repository secrets
+2. **New secret** 클릭
+3. 다음 정보 입력:
+   - **Key**: `DATABASE_URL`
+   - **Value**: Neon 연결 문자열
+4. **Add secret** 클릭
+
+### 4. Spaces 재빌드 및 확인
+
+위와 동일하게 재빌드 후 `/api/admin/database/status`로 확인
+
+## 데이터 마이그레이션 (선택사항)
+
+PostgreSQL로 전환하면 기존 SQLite 데이터는 자동으로 마이그레이션되지 않습니다. 필요시:
+
+1. **기존 데이터 백업** (SQLite):
+   ```bash
+   # 로컬에서 실행
+   sqlite3 instance/finance_analysis.db .dump > backup.sql
+   ```
+
+2. **PostgreSQL로 복원** (복잡함, 수동 작업 필요)
+
+**참고**: 대부분의 경우 새로 시작하는 것이 더 간단합니다. 사용자 계정과 설정만 다시 입력하면 됩니다.
+
+## 문제 해결
+
+### PostgreSQL 연결 실패
+
+1. **연결 문자열 확인**:
+   - 비밀번호에 특수문자가 있으면 URL 인코딩 필요
+   - 예: `@` → `%40`, `#` → `%23`
+
+2. **방화벽 확인**:
+   - Supabase/Neon은 기본적으로 모든 IP 허용
+   - 특정 IP만 허용하도록 설정했다면 Hugging Face IP 추가
+
+3. **로그 확인**:
+   - Hugging Face Spaces > Logs 탭
+   - `[데이터베이스] PostgreSQL 연결 실패: ...` 오류 메시지 확인
+
+### 여전히 SQLite 사용 중
+
+1. **환경 변수 확인**:
+   - Settings > Repository secrets에서 `DATABASE_URL` 존재 확인
+   - 값이 올바른지 확인 (비밀번호 포함)
+
+2. **재빌드 확인**:
+   - 환경 변수 변경 후 Spaces가 재빌드되었는지 확인
+   - Settings > Build logs 확인
+
+3. **코드 확인**:
+   - `app/core/config.py`에서 `DATABASE_URL` 환경 변수를 올바르게 읽는지 확인
+   - (이미 구현되어 있음)
+
+## 확인 체크리스트
+
+PostgreSQL 전환 후 다음을 확인하세요:
+
+- [ ] `/api/admin/database/status`에서 `type: "PostgreSQL"` 확인
+- [ ] `connected: true` 확인
+- [ ] Gemini API 키 저장 후 `config_count` 증가 확인
+- [ ] 컨테이너 재시작 후에도 데이터 유지 확인
+
+## 추가 정보
+
+- **Supabase 문서**: https://supabase.com/docs/guides/database
+- **Neon 문서**: https://neon.tech/docs
+- **PostgreSQL 연결 문자열 형식**: https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING
+