M-Project/DEPLOYMENT_GUIDE_20251028.md

배포 가이드 - 2025.10.28 업데이트

📋 변경사항 요약

🎯 주요 기능 개선

• 보고서 시스템 구현 (일일/주간/월간 보고서)
• 품질팀용 일일보고서 엑셀 내보내기 기능
• Project 모델 속성명 수정 (name → project_name)
• API URL 절대 경로 사용 개선

---

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

⚠️ 중요: 스키마 불일치 수정

• Project 모델에서 name 속성이 project_name으로 변경됨
• 백엔드 코드에서 project.name → project.project_name 수정 필요

새로운 의존성

# backend/requirements.txt에 추가됨
openpyxl==3.1.2  # 엑셀 파일 생성용

---

🔧 백엔드 변경사항

1. 스키마 업데이트

• backend/database/schemas.py
  • DailyReportRequest 클래스 추가
  • DailyReportStats 클래스 추가

2. API 엔드포인트 추가

• backend/routers/reports.py
  • POST /api/reports/daily-export 엔드포인트 추가
• backend/routers/management.py
  • GET /api/management/stats 엔드포인트 추가

3. 중요 수정사항

• backend/routers/reports.py에서 project.name → project.project_name 수정 (3곳)

---

🎨 프론트엔드 변경사항

1. 새로운 페이지 추가

• frontend/reports.html - 보고서 메인 페이지
• frontend/reports-daily.html - 일일보고서 생성 페이지
• frontend/reports-weekly.html - 주간보고서 페이지 (준비중)
• frontend/reports-monthly.html - 월간보고서 페이지 (준비중)

2. 공통 헤더 개선

• frontend/static/js/components/common-header.js
  • 보고서 서브메뉴 추가 (일일/주간/월간)

3. API URL 절대 경로 수정

• 모든 프론트엔드 파일에서 window.API_BASE_URL 사용
• 상대 경로 /api/ → 절대 경로 http://localhost:16080/api 변경

4. 캐시 무효화

• frontend/sw.js 버전 업데이트 (v1.0.0 → v1.0.1)

---

🚀 배포 절차

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 logs backend --tail=20

3. 프론트엔드 배포

# 1. Nginx 재시작 (캐시 무효화)
docker-compose restart nginx

# 2. 브라우저 캐시 강제 새로고침 안내
# 사용자들에게 Ctrl+Shift+F5 또는 Cmd+Shift+R 안내

4. 배포 후 검증

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

# 2. 새로운 API 엔드포인트 테스트
curl -X GET "http://localhost:16080/api/management/stats?project_id=1" \
  -H "Authorization: Bearer YOUR_TOKEN"

# 3. 엑셀 내보내기 테스트
curl -X POST "http://localhost:16080/api/reports/daily-export" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"project_id": 1}' \
  --output test_report.xlsx

---

✅ 기능 테스트 체크리스트

보고서 시스템 테스트

• 보고서 메인 페이지 접근 확인
• 일일보고서 페이지 로드 확인
• 프로젝트 목록 정상 표시 확인
• 프로젝트 선택 시 통계 표시 확인
• 엑셀 파일 다운로드 정상 작동 확인
• 엑셀 파일 내용 및 형식 확인

기존 기능 회귀 테스트

• 대시보드 정상 로드 확인
• 관리함 정상 작동 확인
• 수신함 정상 작동 확인
• 일일 공수 정상 작동 확인

---

🔍 트러블슈팅

일반적인 문제들

1. Project.name 속성 오류

# 증상: "Project object has no attribute 'name'" 오류
# 원인: 백엔드에서 project.name 사용
# 해결: 백엔드 재시작 후 확인
docker-compose restart backend
docker-compose logs backend --tail=20

2. 프로젝트 목록 표시 안됨

# 증상: 드롭다운에 프로젝트가 나타나지 않음
# 원인: API 경로 문제 또는 캐시 문제
# 해결: 
# 1. 브라우저 강제 새로고침 (Ctrl+Shift+F5)
# 2. 개발자 도구에서 네트워크 탭 확인
# 3. API 호출 URL이 올바른지 확인

3. 엑셀 파일 생성 실패

# 증상: 500 Internal Server Error
# 원인: openpyxl 모듈 누락
# 해결: 백엔드 이미지 재빌드
docker-compose build backend
docker-compose up -d backend

4. 공통 헤더 로드 실패

# 증상: TypeError: window.commonHeader.init is not a function
# 원인: 스크립트 로드 순서 문제
# 해결: 페이지 새로고침 또는 캐시 클리어

5. API 연결 실패 (CORS 오류)

# 증상: "Fetch API cannot load http://localhost/api/"
# 원인: API URL 설정 문제
# 해결: 
# 1. 브라우저 캐시 클리어
# 2. 서비스 워커 캐시 무효화 확인
# 3. nginx 재시작
docker-compose restart nginx

---

📊 성능 모니터링

모니터링 포인트

# 1. 백엔드 메모리 사용량 확인
docker stats m-project-backend

# 2. 데이터베이스 연결 상태 확인
docker-compose exec postgres psql -U postgres -d m_project -c "SELECT count(*) FROM pg_stat_activity;"

# 3. 엑셀 생성 성능 확인 (대용량 데이터)
time curl -X POST "http://localhost:16080/api/reports/daily-export" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"project_id": 1}' \
  --output performance_test.xlsx

---

📞 지원 연락처

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

---

⚠️ 주의사항:

1. 반드시 데이터베이스 백업 후 배포 진행
2. 백엔드 이미지 재빌드 필수 (새로운 의존성 포함)
3. 브라우저 캐시 무효화 안내 필요
4. Project.name → project_name 수정사항 확인
5. 배포 후 보고서 기능 전체 테스트 필수

---

🔄 롤백 절차

문제 발생 시 다음 순서로 롤백:

# 1. 이전 버전으로 코드 롤백
git checkout [이전_커밋_해시]

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

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

# 4. 데이터베이스 롤백 (필요시)
# 백업 파일에서 복원