Instruction file imported from SOULRIGHT/child-learning-center (.cursor/rules/emergency-rollback-guide.mdc). Copyright stays with the author.

🚨 Emergency Rollback Guide

⚡ 즉시 실행 - 시스템 전체 오류 시

🔴 CRITICAL: 서버가 시작되지 않는 경우

# 1. 즉시 모든 변경사항 스태시
git stash push -m "Emergency stash - $(date)"

# 2. 마지막 정상 커밋으로 롤백
git reset --hard HEAD~1

# 3. 서버 시작 테스트
python app.py

🔴 CRITICAL: 특정 페이지가 작동하지 않는 경우

# 1. 문제 파일만 롤백
git checkout HEAD -- templates/children/detail.html
git checkout HEAD -- app.py

# 2. 즉시 테스트
python -m py_compile app.py
python app.py

🛡️ 단계별 복구 절차

Step 1: 현재 상태 진단

# Python 문법 오류 확인
python -m py_compile app.py 2>&1 | head -5

# 서버 시작 가능 여부 확인
timeout 5 python app.py 2>&1 | grep -E "(ERROR|Traceback)" | head -3

Step 2: 백업 상태 확인

# 최근 백업 브랜치 확인
git branch | grep backup | tail -3

# 최근 정상 커밋 확인
git log --oneline -5

Step 3: 선택적 롤백

# 특정 파일만 롤백 (권장)
git checkout HEAD~1 -- app.py

# 또는 전체 롤백 (최후 수단)
git reset --hard HEAD~1

📁 파일별 응급 복구 방법

app.py 오류 시:

# 1. 백업에서 복구
cp app.py.backup.* app.py  # 백업이 있는 경우

# 2. 또는 Git에서 복구
git show HEAD~1:app.py > app.py

# 3. 검증
python -m py_compile app.py

템플릿 파일 오류 시:

# 1. 해당 템플릿만 롤백
git checkout HEAD -- templates/children/detail.html

# 2. 또는 백업에서 복구
cp templates/children/detail.html.backup templates/children/detail.html

# 3. 브라우저에서 테스트
curl -s http://localhost:5000/children/1 | grep "<!DOCTYPE"

JavaScript 오류 시:

# 1. static/js 파일 롤백
git checkout HEAD -- static/js/script.js

# 2. 브라우저 캐시 클리어 후 테스트
# Ctrl+F5 또는 Ctrl+Shift+R

🔍 오류 원인 신속 진단

Python 오류 패턴:

# 들여쓰기 오류
python -m py_compile app.py 2>&1 | grep -i "indent"

# Import 오류
python -m py_compile app.py 2>&1 | grep -i "import"

# 문법 오류
python -m py_compile app.py 2>&1 | grep -i "syntax"

데이터베이스 연결 오류:

# 데이터베이스 파일 존재 확인
ls -la *.db

# Flask-SQLAlchemy 테스트
python -c "
from app import app, db
with app.app_context():
    print('DB connection OK')
"

📊 복구 성공 검증 체크리스트

✅ 기본 시스템 동작:

• python -m py_compile app.py 성공
• python app.py 서버 시작 성공
• 메인 페이지 (/) 접근 가능
• 로그인 페이지 접근 가능

✅ 핵심 기능 동작:

• 대시보드 페이지 렌더링
• 아동 목록 페이지 렌더링
• 포인트 입력 페이지 렌더링
• 데이터베이스 읽기/쓰기 작동

✅ 문제 해결 확인:

• 이전에 발생했던 오류 메시지 해결
• JavaScript 콘솔 오류 없음
• 모든 버튼과 링크 정상 작동

🔄 복구 후 안전한 재작업 절차

1. 안전한 브랜치 생성:

# 복구 완료 후 새로운 작업 브랜치 생성
git checkout -b fix/step-by-step-$(date +%Y%m%d)

2. 단계별 재수정:

# 작은 단위로 수정 → 검증 → 커밋 반복
# 예: 함수 1개씩 수정
git add app.py
git commit -m "Fix: 특정 함수 들여쓰기 수정"

python -m py_compile app.py  # 검증

3. 정기적 백업:

# 중요한 단계마다 백업 생성
cp app.py app.py.backup.$(date +%Y%m%d_%H%M%S)
git tag backup-$(date +%Y%m%d-%H%M%S)

🆘 최후 수단 - 완전 초기화

심각한 손상으로 복구 불가능한 경우:

# 1. 현재 작업 완전 백업
git stash push -m "Complete backup before reset"
git tag emergency-backup-$(date +%Y%m%d-%H%M%S)

# 2. 원격 저장소의 안전한 상태로 초기화
git fetch origin
git reset --hard origin/main

# 3. 강제 클린업
git clean -fd

# 4. 의존성 재설치
pip install -r requirements.txt

# 5. 데이터베이스 재초기화 (필요시)
python -c "
from app import app, db
with app.app_context():
    db.create_all()
    print('Database reset complete')
"

📞 응급 상황 연락처

오류 발생 시 즉시 수행할 것:

1. 작업 중단 - 추가 수정 절대 금지
2. 상태 백업 - git stash 또는 파일 복사
3. 롤백 실행 - 위의 절차 따라 복구
4. 검증 완료 - 정상 작동 확인 후 작업 재개

복구 불가 시:

1. 전체 초기화 고려
2. 백업 브랜치에서 재시작
3. 이전 안정 버전으로 되돌리기

💡 예방을 위한 교훈

이번 사고에서 배운 점:

1. 대량 수정 금지 - 한 번에 여러 파일 수정하지 않기
2. 단계별 검증 - 각 수정 후 즉시 테스트
3. 백업 필수 - 위험한 작업 전 반드시 백업
4. 점진적 접근 - 작은 단위로 나누어 작업

앞으로 지켜야 할 원칙:

• Safety First - 속도보다 안전성 우선
• Test Early - 늦은 테스트는 비싼 테스트
• Backup Always - 백업 없는 수정 금지
• One Step - 한 번에 하나씩만 수정

🚨 기억하세요: 이 가이드는 응급상황에서 빠른 복구를 위한 것입니다. 복구 완료 후에는 반드시 원인 분석을 통해 재발 방지 대책을 수립하세요!