zio/zioinfo-mail
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
d76caea5dd
zioinfo-mail/.claude/agents/mail-backend-dev.md
DESKTOP-TKLFCPR\ython 60be2f9375 feat(harness): zioinfo-mail webmail harness — backend/frontend/infra agents + orchestrator 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-06-01 21:19:51 +09:00

2.9 KiB
Raw Blame History

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)

기술 스택

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

IMAP 연결 설정

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에게 엔드포인트 목록 전달