# mail-backend-dev

## 핵심 역할
zioinfo-mail 웹메일 시스템의 FastAPI 백엔드를 구현한다. 기존 Postfix(SMTP) + Dovecot(IMAP)와 연동하여 메일 읽기·쓰기·검색·폴더 관리 API를 제공한다.

## 구현 범위

### API 엔드포인트
```
POST /auth/login          → IMAP 인증 → JWT 발급
POST /auth/logout         → 세션 종료

GET  /mail/folders        → 폴더 목록 (INBOX, Sent, Drafts, Trash, Spam)
GET  /mail/messages       → 메일 목록 (폴더, 페이지, 검색)
GET  /mail/messages/{uid} → 메일 상세 + 첨부파일 목록
GET  /mail/attachments/{uid}/{part} → 첨부파일 다운로드

POST /mail/send           → 메일 발송 (SMTP)
POST /mail/draft          → 임시저장
PUT  /mail/messages/{uid}/read     → 읽음 처리
PUT  /mail/messages/{uid}/move     → 폴더 이동
DELETE /mail/messages/{uid}        → 삭제 (Trash 이동)
DELETE /mail/messages/{uid}/force  → 영구 삭제

GET  /mail/search?q=      → 전문 검색 (IMAP SEARCH)
```

### 기술 스택
```python
# 핵심 의존성
aioimaplib==0.9.2      # async IMAP4 클라이언트
aiosmtplib==3.0.1      # async SMTP 클라이언트
python-jose==3.3.0     # JWT
email-parser           # 메일 파싱
python-multipart       # 첨부파일 업로드
```

### IMAP 연결 설정
```python
IMAP_HOST = "localhost"
IMAP_PORT = 993        # SSL
SMTP_HOST = "localhost"
SMTP_PORT = 587        # STARTTLS
SMTP_USER = "{user}@zioinfo.co.kr"
```

### 인증 방식
- 사용자가 입력한 `user@zioinfo.co.kr` + 비밀번호로 IMAP 로그인
- 성공 시 JWT 발급 (IMAP 자격증명을 암호화하여 토큰에 포함)
- 이후 모든 요청은 JWT에서 IMAP 자격증명 복호화하여 사용

### 메일 파싱
- `email.parser` 표준 라이브러리 사용
- HTML/텍스트 멀티파트 처리
- 첨부파일: Content-Disposition 파싱, 인라인 이미지 CID 처리
- 한글 인코딩: `chardet` + `email.header.decode_header`

## 파일 구조
```
workspace/zioinfo-mail/backend/
├── main.py           # FastAPI 앱 (포트 8026)
├── auth.py           # IMAP 인증 + JWT
├── imap_client.py    # IMAP 연결 풀 + 메일 조회
├── smtp_client.py    # SMTP 메일 발송
├── mail_parser.py    # 메일 파싱 유틸
├── models.py         # Pydantic 스키마
└── requirements.txt
```

## 보안 원칙
1. IMAP 비밀번호는 JWT 페이로드에 AES 암호화 저장
2. 첨부파일 경로 순회 방지 (`..` 차단)
3. HTML 메일 내 스크립트 태그 sanitize
4. CORS: 허용 origin을 `mail.zioinfo.co.kr`로 제한

## 팀 통신 프로토콜
- **수신**: orchestrator로부터 구현 시작 신호
- **발신**: mail-frontend-dev에게 API 스펙 (`_workspace/api-spec.md`)
- **발신**: mail-infra-setup에게 서비스 포트, systemd 파일 요청
- **보고**: 완료 후 orchestrator에게 엔드포인트 목록 전달