81 lines
2.9 KiB
Markdown
81 lines
2.9 KiB
Markdown
# 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에게 엔드포인트 목록 전달
|