M-Project/DEPLOYMENT_CHECKLIST.md

🚀 배포 안전성 체크리스트

✅ DB 마이그레이션 검증 필수사항

배포 전 필수 확인사항

1. 마이그레이션 파일 존재 확인

# 로컬에서 확인
ls -la backend/migrations/013_add_inbox_workflow_system.sql

# 배포 서버에서 확인 (배포 후)
docker-compose exec backend ls -la /app/migrations/013_add_inbox_workflow_system.sql

2. DB 연결 및 권한 확인

# DB 연결 테스트
docker-compose exec db psql -U mproject -d mproject -c "SELECT version();"

# 마이그레이션 로그 테이블 존재 확인
docker-compose exec db psql -U mproject -d mproject -c "\d migration_log"

3. 마이그레이션 실행 (배포 시)

# 1단계: 파일 복사
docker cp backend/migrations/013_add_inbox_workflow_system.sql [DB_CONTAINER_NAME]:/tmp/

# 2단계: 마이그레이션 실행
docker-compose exec db psql -U mproject -d mproject -f /tmp/013_add_inbox_workflow_system.sql

# 3단계: 실행 결과 확인
docker-compose exec db psql -U mproject -d mproject -c "SELECT * FROM migration_log WHERE migration_file = '013_add_inbox_workflow_system.sql';"

4. 테이블 구조 검증

# issues 테이블 구조 확인
docker-compose exec db psql -U mproject -d mproject -c "\d issues"

# 새로운 컬럼들 존재 확인
docker-compose exec db psql -U mproject -d mproject -c "
SELECT column_name, data_type, is_nullable, column_default 
FROM information_schema.columns 
WHERE table_name = 'issues' 
AND column_name IN (
    'review_status', 'disposal_reason', 'custom_disposal_reason', 
    'disposed_at', 'reviewed_by_id', 'reviewed_at', 
    'original_data', 'modification_log'
);"

5. ENUM 타입 검증

# review_status ENUM 확인
docker-compose exec db psql -U mproject -d mproject -c "\dT+ review_status"

# disposal_reason_type ENUM 확인  
docker-compose exec db psql -U mproject -d mproject -c "\dT+ disposal_reason_type"

6. 인덱스 검증

# 새로운 인덱스들 확인
docker-compose exec db psql -U mproject -d mproject -c "
SELECT indexname, tablename, indexdef 
FROM pg_indexes 
WHERE tablename = 'issues' 
AND indexname IN (
    'idx_issues_review_status', 
    'idx_issues_reviewed_by_id', 
    'idx_issues_disposed_at'
);"

7. 제약 조건 검증

# 체크 제약 조건 확인
docker-compose exec db psql -U mproject -d mproject -c "
SELECT constraint_name, check_clause 
FROM information_schema.check_constraints 
WHERE constraint_name IN (
    'chk_disposal_reason_required', 
    'chk_custom_reason_logic'
);"

---

🔧 배포 시 실행 스크립트

자동 마이그레이션 스크립트

#!/bin/bash
# deploy_migration.sh

echo "🚀 DB 마이그레이션 시작..."

# 1. 마이그레이션 파일 존재 확인
if [ ! -f "backend/migrations/013_add_inbox_workflow_system.sql" ]; then
    echo "❌ 마이그레이션 파일이 존재하지 않습니다!"
    exit 1
fi

# 2. DB 컨테이너 상태 확인
if ! docker-compose ps db | grep -q "Up"; then
    echo "❌ DB 컨테이너가 실행되지 않았습니다!"
    exit 1
fi

# 3. 마이그레이션 파일 복사
echo "📁 마이그레이션 파일 복사 중..."
docker cp backend/migrations/013_add_inbox_workflow_system.sql $(docker-compose ps -q db):/tmp/

# 4. 마이그레이션 실행
echo "⚡ 마이그레이션 실행 중..."
docker-compose exec -T db psql -U mproject -d mproject -f /tmp/013_add_inbox_workflow_system.sql

# 5. 실행 결과 확인
echo "🔍 마이그레이션 결과 확인 중..."
MIGRATION_COUNT=$(docker-compose exec -T db psql -U mproject -d mproject -t -c "SELECT COUNT(*) FROM migration_log WHERE migration_file = '013_add_inbox_workflow_system.sql' AND status = 'SUCCESS';")

if [ "$MIGRATION_COUNT" -eq 1 ]; then
    echo "✅ 마이그레이션이 성공적으로 완료되었습니다!"
else
    echo "❌ 마이그레이션 실행에 실패했습니다!"
    exit 1
fi

# 6. 백엔드 재시작 (새로운 모델 적용)
echo "🔄 백엔드 재시작 중..."
docker-compose restart backend

echo "🎉 배포 완료!"

---

⚠️ 배포 시 주의사항

1. 백업 필수

# 배포 전 DB 백업
docker-compose exec db pg_dump -U mproject mproject > backup_$(date +%Y%m%d_%H%M%S).sql

2. 롤백 계획

# 문제 발생 시 롤백 (마이그레이션 전 백업으로 복원)
docker-compose exec -T db psql -U mproject -d mproject < backup_YYYYMMDD_HHMMSS.sql

3. 단계별 검증

• ✅ 마이그레이션 파일 존재
• ✅ DB 연결 상태
• ✅ 마이그레이션 실행
• ✅ 테이블 구조 검증
• ✅ 백엔드 재시작
• ✅ API 동작 테스트

4. 모니터링

# 배포 후 로그 모니터링
docker-compose logs -f backend
docker-compose logs -f db

---

📋 배포 완료 후 확인사항

1. API 엔드포인트 테스트

# 수신함 API 테스트 (구현 후)
curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:16080/api/inbox/

# 부적합 상태 변경 테스트
curl -X PUT -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"review_status": "in_progress"}' \
     http://localhost:16080/api/issues/1/review-status

2. 프론트엔드 페이지 접근

• ✅ 수신함 페이지 로드 확인
• ✅ 권한 시스템 동작 확인
• ✅ 데이터 표시 확인

3. 워크플로우 테스트

• ✅ 폐기 처리 테스트
• ✅ 수정 이력 저장 테스트
• ✅ 상태 변경 테스트

---

🚨 문제 발생 시 대응

일반적인 문제들

1. 마이그레이션 파일 누락

# 해결: 파일 수동 복사
scp backend/migrations/013_add_inbox_workflow_system.sql server:/path/to/project/

2. 권한 문제

# 해결: 파일 권한 조정
chmod 644 backend/migrations/013_add_inbox_workflow_system.sql

3. DB 연결 실패

# 해결: DB 컨테이너 재시작
docker-compose restart db

4. 마이그레이션 중복 실행

• 마이그레이션 파일은 중복 실행 방지 로직 포함
• migration_log 테이블로 실행 이력 추적

---

이 체크리스트를 따라하면 배포 시 DB 마이그레이션이 안전하게 적용됩니다! ✅