From 1818f0229c55a86775d97c19cad361da0a21a5f1 Mon Sep 17 00:00:00 2001
From: AutonetSellCar Deploy <autonet@grantech.kr>
Date: Thu, 1 Jan 2026 10:03:46 +0900
Subject: [PATCH] Add DEPLOYMENT.md guide for deployment and DB migration
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Document server structure and deployment flow
- Add DB schema change checklist (SQLite ALTER TABLE)
- Include common troubleshooting and rollback commands
- Reference in CLAUDE.md for new sessions

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 CLAUDE.md     |   4 ++
 DEPLOYMENT.md | 191 ++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 195 insertions(+)
 create mode 100644 DEPLOYMENT.md

diff --git a/CLAUDE.md b/CLAUDE.md
index d7d33f5..bde5b6e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2,6 +2,10 @@
 
 이 문서는 Claude Code 세션에서 반드시 읽고 참고해야 하는 중요한 정보입니다.
 
+> **배포 시 반드시 [DEPLOYMENT.md](./DEPLOYMENT.md)도 함께 확인하세요!**
+> - DB 스키마 변경 시 수동으로 ALTER TABLE 필요
+> - 배포 명령어 및 롤백 방법 안내
+
 ---
 
 ## 1. 프로젝트 구조
diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md
new file mode 100644
index 0000000..bc1f74a
--- /dev/null
+++ b/DEPLOYMENT.md
@@ -0,0 +1,191 @@
+# AutonetSellCar.com 배포 가이드
+
+## 서버 구성
+
+```
+server5 (집 Win11)
+    ↓ Remote Desktop
+server4 (회사 Win11, 개발서버)
+    ↓ SSH / Git Push
+server1 (192.168.0.201) - NPM (Nginx Proxy Manager)
+server2 (192.168.0.202) - 운영서버 (Docker)
+server3 (192.168.0.203) - grantech.kr
+```
+
+## 배포 흐름
+
+```
+[server4 개발]
+    │
+    ▼ git push staging main
+[server2 스테이징 자동 배포]
+    │
+    ▼ ssh server2 "/opt/autonet/scripts/deploy.sh promote"
+[server2 운영 배포]
+```
+
+---
+
+## 일반 배포 (코드만 변경)
+
+```bash
+# 1. 커밋
+git add -A && git commit -m "변경 내용"
+
+# 2. 스테이징 배포 (자동)
+git push staging main
+
+# 3. 운영 승격
+ssh damon@192.168.0.202 "/opt/autonet/scripts/deploy.sh promote"
+```
+
+---
+
+## DB 스키마 변경 시 (중요!)
+
+### SQLite 특성
+- SQLAlchemy 모델에 컬럼 추가해도 **DB에 자동 반영 안 됨**
+- Docker 재시작해도 DB 볼륨은 유지됨
+- **반드시 수동으로 ALTER TABLE 실행 필요!**
+
+### 새 컬럼 추가 시 체크리스트
+
+```
+□ 1. backend/app/models/*.py - 모델에 컬럼 추가
+□ 2. backend/app/schemas/*.py - 스키마에 필드 추가
+□ 3. backend/app/api/*.py - API 기본값 설정
+□ 4. git commit & push
+□ 5. 운영 배포 후 DB에 컬럼 추가 (아래 명령어)
+□ 6. 테스트
+```
+
+### DB 컬럼 추가 명령어
+
+```bash
+# 운영서버 DB에 컬럼 추가
+ssh damon@192.168.0.202 "docker exec autonet-backend python -c \"
+import sqlite3
+for db in ['/app/autonet.db', '/app/autonet_data.db']:
+    try:
+        conn = sqlite3.connect(db)
+        conn.execute('ALTER TABLE 테이블명 ADD COLUMN 컬럼명 타입 DEFAULT 기본값')
+        conn.commit()
+        print(f'{db}: OK')
+    except Exception as e:
+        print(f'{db}: {e}')
+\""
+```
+
+### 예시: cc_per_banner_view 컬럼 추가
+
+```bash
+ssh damon@192.168.0.202 "docker exec autonet-backend python -c \"
+import sqlite3
+for db in ['/app/autonet.db', '/app/autonet_data.db']:
+    try:
+        conn = sqlite3.connect(db)
+        conn.execute('ALTER TABLE system_settings ADD COLUMN cc_per_banner_view REAL DEFAULT 0.1')
+        conn.commit()
+        print(f'{db}: OK')
+    except Exception as e:
+        print(f'{db}: {e}')
+\""
+```
+
+### SQLite 타입 매핑
+
+| Python/SQLAlchemy | SQLite |
+|-------------------|--------|
+| Integer | INTEGER |
+| Float | REAL |
+| String | TEXT |
+| Boolean | INTEGER (0/1) |
+| DateTime | TEXT |
+
+---
+
+## 롤백
+
+```bash
+# 직전 버전으로 롤백
+ssh damon@192.168.0.202 "/opt/autonet/scripts/deploy.sh rollback"
+
+# 특정 버전으로 롤백
+ssh damon@192.168.0.202 "/opt/autonet/scripts/deploy.sh rollback-to 20260101_094303"
+
+# 릴리즈 목록 확인
+ssh damon@192.168.0.202 "/opt/autonet/scripts/deploy.sh status"
+```
+
+---
+
+## 서버 상태 확인
+
+```bash
+# 컨테이너 상태
+ssh damon@192.168.0.202 "docker ps"
+
+# 백엔드 로그
+ssh damon@192.168.0.202 "docker logs autonet-backend --tail 50"
+
+# 프론트엔드 로그
+ssh damon@192.168.0.202 "docker logs autonet-frontend --tail 50"
+
+# DB 테이블 확인
+ssh damon@192.168.0.202 "docker exec autonet-backend python -c \"
+import sqlite3
+conn = sqlite3.connect('/app/autonet.db')
+cursor = conn.cursor()
+cursor.execute('PRAGMA table_info(system_settings)')
+for row in cursor.fetchall():
+    print(row)
+\""
+```
+
+---
+
+## SSH 키 설정 (server4 → server1,2,3)
+
+```powershell
+# 공개키 확인
+cat ~/.ssh/id_ed25519.pub
+
+# 각 서버에 등록
+# server1,2,3 각각에서:
+nano ~/.ssh/authorized_keys
+# 공개키 붙여넣기
+```
+
+---
+
+## 자주 발생하는 문제
+
+### 1. "no such column" 에러
+- **원인**: 코드에 새 컬럼 추가했지만 DB에는 없음
+- **해결**: ALTER TABLE로 컬럼 추가 (위 참고)
+
+### 2. "Failed to save settings" 에러
+- **원인**: 보통 DB 스키마 불일치
+- **확인**: `docker logs autonet-backend --tail 30`
+- **해결**: 누락된 컬럼 추가
+
+### 3. 번역 안 됨
+- **원인**: i18n.ts에 해당 단어 번역 없음
+- **해결**: CAR_TRANSLATIONS에 번역 추가
+
+### 4. 배포 후 변경사항 안 보임
+- **프론트엔드**: 브라우저 캐시 클리어 (Ctrl+Shift+R)
+- **백엔드**: 컨테이너 재시작 확인
+
+---
+
+## 변경 이력
+
+| 날짜 | 변경 내용 | DB 변경 |
+|------|----------|---------|
+| 2026-01-01 | cc_per_banner_view 설정 추가 | system_settings.cc_per_banner_view (REAL) |
+| 2026-01-01 | 마이스터 번역 추가 | - |
+
+---
+
+**이 문서는 새 세션 시작 시 CLAUDE.md와 함께 반드시 읽어주세요!**