M-Project/DEPLOYMENT_GUIDE_20251026.md

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

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

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

---

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

### **새로운 마이그레이션**
- `020_add_management_completion_fields.sql`

### **추가된 컬럼들** (이미 존재할 수 있음)
```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. 사전 준비**
```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 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. 프론트엔드 배포**
```bash
# 브라우저 캐시 무효화를 위한 버전 업데이트 (필요시)
# frontend/issues-management.html의 캐시버스터 확인
```

### **4. 배포 후 검증**
```bash
# 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 에러**
```bash
# 원인: 백엔드 스키마 불일치
# 해결: 백엔드 재시작
docker-compose restart backend
```

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

#### **3. 완료 사진 업로드 실패**
```bash
# 원인: 파일 서비스 문제
# 해결: uploads 디렉토리 권한 확인
docker-compose exec backend ls -la /uploads/
```

#### **4. 마이그레이션 실패**
```bash
# 마이그레이션 상태 확인
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. 문제 발생 시 즉시 롤백 준비