M-Project/DEPLOYMENT_GUIDE_20251028.md

# 배포 가이드 - 2025.10.28 업데이트

## 📋 **변경사항 요약**

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

---

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

### **⚠️ 중요: 스키마 불일치 수정**
- `Project` 모델에서 `name` 속성이 `project_name`으로 변경됨
- 백엔드 코드에서 `project.name` → `project.project_name` 수정 필요

### **새로운 의존성**
```txt
# 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. 사전 준비**
```bash
# 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. 백엔드 배포**
```bash
# 1. Docker 컨테이너 중지
docker-compose down

# 2. 이미지 재빌드 (새로운 의존성 포함)
docker-compose build backend

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

# 4. 백엔드 로그 확인
docker-compose logs backend --tail=20
```

### **3. 프론트엔드 배포**
```bash
# 1. Nginx 재시작 (캐시 무효화)
docker-compose restart nginx

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

### **4. 배포 후 검증**
```bash
# 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 속성 오류**
```bash
# 증상: "Project object has no attribute 'name'" 오류
# 원인: 백엔드에서 project.name 사용
# 해결: 백엔드 재시작 후 확인
docker-compose restart backend
docker-compose logs backend --tail=20
```

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

#### **3. 엑셀 파일 생성 실패**
```bash
# 증상: 500 Internal Server Error
# 원인: openpyxl 모듈 누락
# 해결: 백엔드 이미지 재빌드
docker-compose build backend
docker-compose up -d backend
```

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

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

---

## 📊 **성능 모니터링**

### **모니터링 포인트**
```bash
# 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. **배포 후 보고서 기능 전체 테스트 필수**

---

## 🔄 **롤백 절차**
문제 발생 시 다음 순서로 롤백:

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

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

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

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