M-Project/DEPLOYMENT_GUIDE_20251026.md

배포 가이드 - 2025.10.26 업데이트

📋 변경사항 요약

🎯 주요 기능 개선

• 관리함 완료 신청 정보 수정 기능 추가
• 진행 중/완료 대기 상태 통합 모달 구현
• 완료 사진 업로드/교체 기능
• 완료 코멘트 수정 기능

---

🗄️ 데이터베이스 변경사항

새로운 마이그레이션

• 020_add_management_completion_fields.sql

추가된 컬럼들 (이미 존재할 수 있음)

-- issues 테이블에 추가된 컬럼들
completion_photo_path VARCHAR(500)           -- 완료 사진 경로
completion_comment TEXT                      -- 완료 코멘트
completion_requested_at TIMESTAMP WITH TIME ZONE  -- 완료 신청 시간
completion_requested_by_id INTEGER REFERENCES users(id)  -- 완료 신청자

---

🔧 백엔드 변경사항

1. 스키마 업데이트

• backend/database/schemas.py
  • ManagementUpdateRequest 클래스 추가
  • completion_photo, completion_comment 필드 지원

2. API 엔드포인트 개선

• backend/routers/management.py
  • PUT /api/management/{issue_id} 엔드포인트 개선
  • Base64 이미지 처리 로직 추가
  • 날짜 필드 처리 개선

---

🎨 프론트엔드 변경사항

1. 통합 모달 구현

• frontend/issues-management.html
  • openIssueEditModal() 함수 개선
  • 완료 신청 정보 섹션 항상 표시
  • 파일 업로드 UI 개선

2. 버튼 연결 통합

• 진행 중 "완료처리" → confirmCompletion()
• 완료 대기 "최종확인" → confirmCompletion()
• 모든 버튼이 동일한 수정 가능한 모달 사용

3. 함수명 수정

• loadManagementData() → initializeManagement()

---

🚀 배포 절차

1. 사전 준비

# 1. 현재 데이터베이스 백업
docker-compose exec postgres pg_dump -U postgres -d m_project > backup_$(date +%Y%m%d_%H%M%S).sql

# 2. Git 최신 코드 pull
git pull origin master

2. 백엔드 배포

# 1. Docker 컨테이너 중지
docker-compose down

# 2. 이미지 재빌드
docker-compose build backend

# 3. 컨테이너 시작
docker-compose up -d

# 4. 마이그레이션 실행
docker-compose exec backend python -c "
import sys
sys.path.append('/app')
from database.database import get_db
import psycopg2
import os

# 마이그레이션 실행
conn = psycopg2.connect(
    host=os.getenv('DB_HOST', 'postgres'),
    database=os.getenv('DB_NAME', 'm_project'),
    user=os.getenv('DB_USER', 'postgres'),
    password=os.getenv('DB_PASSWORD', 'password')
)

with open('/app/migrations/020_add_management_completion_fields.sql', 'r', encoding='utf-8') as f:
    migration_sql = f.read()

with conn.cursor() as cursor:
    cursor.execute(migration_sql)
    conn.commit()

print('✅ 마이그레이션 완료')
conn.close()
"

3. 프론트엔드 배포

# 브라우저 캐시 무효화를 위한 버전 업데이트 (필요시)
# frontend/issues-management.html의 캐시버스터 확인

4. 배포 후 검증

# 1. 백엔드 상태 확인
docker-compose logs backend --tail=20

# 2. 데이터베이스 연결 확인
docker-compose exec postgres psql -U postgres -d m_project -c "SELECT COUNT(*) FROM migration_log WHERE migration_file = '020_add_management_completion_fields.sql';"

# 3. 새로운 컬럼 확인
docker-compose exec postgres psql -U postgres -d m_project -c "\\d issues" | grep completion

---

✅ 기능 테스트 체크리스트

관리함 페이지 테스트

• 진행 중 상태에서 "완료처리" 버튼 클릭
• 완료 대기 상태에서 "최종확인" 버튼 클릭
• 통합 모달이 열리는지 확인
• 완료 사진 업로드/교체 버튼 작동 확인
• 완료 코멘트 텍스트 영역 수정 가능 확인
• "저장" 버튼으로 수정사항 저장 확인
• "최종확인" 버튼으로 완료 처리 확인
• 422 에러 없이 정상 저장 확인

---

🔍 트러블슈팅

일반적인 문제들

1. 422 Unprocessable Entity 에러

# 원인: 백엔드 스키마 불일치
# 해결: 백엔드 재시작
docker-compose restart backend

2. ReferenceError: loadManagementData

# 원인: 함수명 변경 미적용
# 해결: 브라우저 강제 새로고침 (Ctrl+Shift+F5)

3. 완료 사진 업로드 실패

# 원인: 파일 서비스 문제
# 해결: uploads 디렉토리 권한 확인
docker-compose exec backend ls -la /uploads/

4. 마이그레이션 실패

# 마이그레이션 상태 확인
docker-compose exec postgres psql -U postgres -d m_project -c "SELECT * FROM migration_log ORDER BY started_at DESC LIMIT 5;"

# 실패한 마이그레이션 재실행
docker-compose exec postgres psql -U postgres -d m_project -c "DELETE FROM migration_log WHERE migration_file = '020_add_management_completion_fields.sql' AND status = 'failed';"

---

📞 지원 연락처

• 개발자: [개발자 연락처]
• 배포 담당자: [배포 담당자 연락처]

---

⚠️ 주의사항:

1. 반드시 데이터베이스 백업 후 배포 진행
2. 마이그레이션 실행 전 백엔드 로그 확인
3. 배포 후 기능 테스트 필수 수행
4. 문제 발생 시 즉시 롤백 준비